john/tractatus
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
tractatus/CLAUDE.md
TheFlow 4445b0e8d0 feat: initialize tractatus project with complete directory structure 
- Create comprehensive project structure (29 directories)
- Add CLAUDE.md with project context and conventions
- Add package.json with dependencies and scripts
- Add .gitignore and .env.example
- Add README.md with project overview
- Configure ports: MongoDB 27017, Application 9000
- Establish Tractatus governance framework baseline
- Document Te Tiriti approach and indigenous perspective
- Set up infrastructure for Phase 1 implementation

Project Status: Development - Phase 1 Foundation Complete
Next: MongoDB instance setup and systemd service configuration
2025-10-06 23:26:26 +13:00

416 lines
14 KiB
Markdown
Raw Blame History

# Tractatus AI Safety Framework Website - Project Context
**Project Name:** Tractatus Website Platform
**Domain:** mysy.digital
**Repository:** GitHub (primary) + Codeberg/Gitea (mirrors)
**Status:** Development - Phase 1 Implementation
**Created:** 2025-10-06
**Primary Developer:** Claude Code (Anthropic Sonnet 4.5)
**Project Owner:** John Stroh
---
## ⚠️ Critical: Project Isolation
**THIS IS A SEPARATE PROJECT FROM family-history AND sydigital**
- **Separate MongoDB instance**: Port 27017, database `tractatus_dev`
- **Separate application port**: 9000
- **Separate Git repository**: Local + GitHub account
- **Separate systemd services**: mongodb-tractatus.service, tractatus.service
- **No shared code/data**: Patterns may be adapted, but no dependencies
**Sessions must maintain clear separation.** Always verify which project context you're in.
---
## Project Purpose
Build a world-class platform demonstrating the **Tractatus-Based LLM Safety Framework** through:
1. **Three Audience Paths**: Researcher, Implementer, Advocate
2. **AI-Powered Features**: Blog curation, media triage, case studies (all with human oversight)
3. **Interactive Demonstrations**: Classification, 27027 incident, boundary enforcement
4. **Dogfooding**: The website implements Tractatus to govern its own AI operations
5. **Values Alignment**: Sovereignty, Transparency, Harmlessness, Community
**Timeline:** 3-4 months for complete Phase 1 local prototype (no rush, no shortcuts, world-class quality)
---
## Technical Architecture
### Infrastructure
- **MongoDB**: Port 27017, database `tractatus_dev`
- **Application**: Node.js/Express on port 9000
- **WebSocket**: Port 9001 (if needed)
- **Data Directory**: `/home/theflow/projects/tractatus/data/mongodb`
- **Logs**: `/home/theflow/projects/tractatus/logs/`
### Technology Stack
- **Backend**: Node.js 18+, Express 4.x, MongoDB 7+
- **Frontend**: Vanilla JavaScript, Tailwind CSS (no framework dependency)
- **Authentication**: JWT for admin/moderation
- **AI Integration**: Claude API (Sonnet 4.5) - Phase 2+
- **File Storage**: GridFS for PDFs, documents
- **Testing**: Jest + Supertest
### Database Collections
```javascript
tractatus_dev.documents // Technical papers, framework docs
tractatus_dev.blog_posts // AI-curated, human-approved
tractatus_dev.media_inquiries // Press/media with AI triage
tractatus_dev.case_submissions // Community case studies
tractatus_dev.resources // External links, aligned projects
tractatus_dev.moderation_queue // Human oversight queue
tractatus_dev.users // Admin accounts
tractatus_dev.citations // Academic citation tracking
tractatus_dev.translations // Multi-language content (future)
tractatus_dev.koha_donations // Phase 3
```
---
## Tractatus Framework Governance
**This project dogfoods the Tractatus framework** - all AI actions are governed by:
### Core Services (to be implemented)
1. **InstructionPersistenceClassifier** - Classifies actions by quadrant (STR/OPS/TAC/SYS/STO)
2. **CrossReferenceValidator** - Validates AI actions against explicit instructions
3. **BoundaryEnforcer** - Ensures AI never makes values decisions without human approval
4. **ContextPressureMonitor** - Detects conditions that increase error probability
5. **MetacognitiveVerifier** - AI self-checks reasoning before proposing actions
### Quadrant Mapping for Website Functions
| Function | Quadrant | Human Oversight | Example |
|----------|----------|-----------------|---------|
| Mission/values changes | STRATEGIC | Mandatory approval | "Always prioritize privacy" |
| Blog editorial guidelines | OPERATIONAL | Quarterly review | "All posts must cite sources" |
| Publish approved post | TACTICAL | Pre-approved | Execute after human approval |
| Technical config | SYSTEM | Technical review | MongoDB ports, API keys |
| AI suggests blog topics | STOCHASTIC | Always human approval | "Write about GDPR" |
**Critical:** All AI content suggestions require human approval. No AI action crosses into values territory without explicit human decision.
---
## Governance Documents
Located in `/home/theflow/projects/tractatus/governance/` (to be created):
- **TRA-VAL-0001**: Tractatus Core Values (adapted from STR-VAL-0001)
- **TRA-GOV-0001**: Strategic Review Protocol (adapted from STR-GOV-0001)
- **TRA-GOV-0002**: Values Alignment Framework (adapted from STR-GOV-0002)
- **TRA-GOV-0003**: AI Boundary Enforcement Policy
- **TRA-GOV-0004**: Human Oversight Requirements
**Reference:** Source documents in `/home/theflow/projects/sydigital/strategic/`
---
## Te Tiriti & Indigenous Perspective
### Strategic Commitment
The framework acknowledges **Te Tiriti o Waitangi** and indigenous leadership in digital sovereignty.
### Implementation Approach
- **Respect without tokenism**: Follow documented indigenous data sovereignty principles (CARE Principles)
- **No premature engagement**: Do not approach Māori organizations until we have something valuable to offer
- **Well-documented standards**: Use published research and frameworks (Te Mana Raraunga, CARE Principles)
- **Baseline integration**: Te Tiriti forms part of strategic foundation, not dominant cultural overlay
### Content Placement
- Footer acknowledgment (subtle, respectful)
- `/about/values` page (detailed explanation)
- Resource directory (links to Māori data sovereignty organizations)
- No meetings/consultations until post-launch
---
## Development Conventions
### Code Style
- **ES6+ JavaScript**: Modern syntax, async/await patterns
- **Modular architecture**: Small, focused functions/classes
- **Explicit naming**: No abbreviations, clear intent
- **Comments**: Explain WHY, not WHAT
- **Error handling**: Comprehensive try/catch, meaningful error messages
### File Naming
- **Routes**: `src/routes/blog.routes.js`
- **Controllers**: `src/controllers/blog.controller.js`
- **Models**: `src/models/BlogPost.model.js`
- **Services**: `src/services/BlogCuration.service.js`
- **Middleware**: `src/middleware/auth.middleware.js`
- **Tests**: `tests/unit/blog.test.js`
### Git Conventions
- **Commits**: Conventional commits format
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation
- `refactor:` Code restructure
- `test:` Test additions
- `chore:` Maintenance
- **Branches**: `feature/blog-curation`, `fix/auth-token`, `docs/api-reference`
- **No commits to main**: Always use feature branches
### Environment Variables
```bash
# Application
NODE_ENV=development
PORT=9000
APP_NAME=Tractatus
# MongoDB
MONGODB_URI=mongodb://localhost:27017/tractatus_dev
MONGODB_PORT=27017
# JWT
JWT_SECRET=<generate_secure_secret>
JWT_EXPIRY=7d
# Claude API (Phase 2+)
CLAUDE_API_KEY=<anthropic_api_key>
CLAUDE_MODEL=claude-sonnet-4-5
# Admin
ADMIN_EMAIL=john.stroh.nz@pm.me
```
---
## Directory Structure
```
/home/theflow/projects/tractatus/
├── .claude/ # Claude Code project config
├── .git/ # Git repository
├── docs/ # Source markdown documents
│ ├── markdown/ # Raw markdown files (migration source)
│ └── governance/ # TRA-VAL-*, TRA-GOV-* documents
├── public/ # Frontend assets
│ ├── css/
│ │ └── tailwind.css
│ ├── js/
│ │ ├── components/ # Reusable UI components
│ │ ├── demos/ # Interactive demonstrations
│ │ └── utils/
│ ├── images/
│ └── downloads/ # Generated PDFs
├── src/ # Backend code
│ ├── server.js # Express app entry point
│ ├── routes/
│ │ ├── docs.routes.js
│ │ ├── blog.routes.js
│ │ ├── media.routes.js
│ │ ├── cases.routes.js
│ │ ├── resources.routes.js
│ │ ├── admin.routes.js
│ │ └── demo.routes.js
│ ├── controllers/
│ ├── models/
│ │ ├── Document.model.js
│ │ ├── BlogPost.model.js
│ │ ├── MediaInquiry.model.js
│ │ ├── CaseSubmission.model.js
│ │ ├── ModerationQueue.model.js
│ │ └── User.model.js
│ ├── middleware/
│ │ ├── auth.middleware.js
│ │ ├── validation.middleware.js
│ │ └── tractatus/ # Framework enforcement
│ │ ├── classifier.middleware.js
│ │ ├── validator.middleware.js
│ │ └── boundary.middleware.js
│ ├── services/
│ │ ├── ClaudeAPI.service.js
│ │ ├── InstructionClassifier.service.js
│ │ ├── CrossReferenceValidator.service.js
│ │ ├── BoundaryEnforcer.service.js
│ │ ├── ContextPressureMonitor.service.js
│ │ ├── MetacognitiveVerifier.service.js
│ │ ├── BlogCuration.service.js
│ │ ├── MediaTriage.service.js
│ │ ├── DocumentProcessor.service.js
│ │ └── ModerationQueue.service.js
│ ├── utils/
│ │ ├── db.util.js
│ │ ├── jwt.util.js
│ │ ├── markdown.util.js
│ │ └── logger.util.js
│ └── config/
│ ├── database.config.js
│ └── app.config.js
├── scripts/ # Setup & migration
│ ├── init-db.js # Create collections, indexes
│ ├── migrate-documents.js # Import markdown content
│ ├── generate-pdfs.js # PDF export
│ ├── seed-admin.js # Create admin user
│ └── start-dev.sh # Development startup
├── tests/
│ ├── unit/
│ ├── integration/
│ └── security/
├── data/ # MongoDB data directory
│ └── mongodb/
├── logs/ # Application & MongoDB logs
│ ├── app.log
│ └── mongodb.log
├── .env.example # Template environment variables
├── .gitignore
├── package.json
├── package-lock.json
├── README.md
├── CLAUDE.md # This file
└── LICENSE
```
---
## Phase 1 Deliverables (3-4 Months)
**Must-Have for Complete Prototype:**
1. ✅ **Infrastructure**
- MongoDB instance (port 27017)
- Express application (port 9000)
- Systemd services
- Directory structure
2. **Core Features**
- Document migration pipeline
- Three audience paths (Researcher/Implementer/Advocate)
- Documentation viewer with search
- About/values pages (Te Tiriti acknowledgment)
3. **Tractatus Governance Services**
- InstructionPersistenceClassifier
- CrossReferenceValidator
- BoundaryEnforcer
- ContextPressureMonitor
- MetacognitiveVerifier
4. **AI-Powered Features** (with human oversight)
- Blog curation system
- Media inquiry triage
- Case study submission portal
- Resource directory curation
5. **Interactive Demonstrations**
- Instruction classification demo
- 27027 incident visualizer
- Boundary enforcement simulator
6. **Human Oversight**
- Moderation queue dashboard
- Admin authentication
- Approval workflows
7. **Quality Assurance**
- Comprehensive testing suite
- Security audit
- Performance optimization
- Accessibility compliance (WCAG)
**Not in Phase 1:**
- Production deployment (OVHCloud)
- Domain configuration (mysy.digital)
- ProtonBridge email integration
- Koha donations (Phase 3)
- Public launch
---
## Success Criteria
**Technical Excellence:**
- Clean, maintainable code
- 80%+ test coverage
- <2s page load times
- WCAG AA accessibility
- Zero security vulnerabilities
- Complete API documentation
**Framework Demonstration:**
- All AI actions governed by Tractatus
- Human oversight for values-sensitive content
- Boundary enforcement working
- Classification system accurate
- Moderation queue functional
**Content Quality:**
- All documents migrated correctly
- Three audience paths distinct and clear
- Interactive demos working
- Blog system ready for Phase 2
- No placeholder/fake data
---
## Human Approval Required For:
**All Major Decisions:**
- Architectural changes
- Database schema modifications
- Security implementations
- Third-party integrations
- Cost-incurring services
**Content & Values:**
- Governance document adaptations (TRA-VAL-*, TRA-GOV-*)
- Te Tiriti acknowledgment wording
- About/mission pages
- Editorial guidelines
- Any values-sensitive content
**Phase Transitions:**
- Completion of Phase 1 prototype
- Decision to proceed to production deployment
- Budget approval for Claude API (Phase 2)
- Launch timing and strategy
---
## Links & References
**Source Documents:**
- `/home/theflow/projects/tractatus/Tractatus-Website-Complete-Specification-v2.0.md`
- `/home/theflow/projects/tractatus/ClaudeWeb conversation transcription.md`
- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/STO-INN-0010-tractatus-llm-architecture-safety-framework-i1.md`
- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/anthropic-submission/technical-proposal.md`
- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/anthropic-submission/appendix-a-code-examples.md`
**Governance References:**
- `/home/theflow/projects/sydigital/strategic/values-principles/STR-VAL-0001-core-values-principles-v1-0.md`
- `/home/theflow/projects/sydigital/strategic/governance/STR-GOV-0001-strategic-review-protocol-v1-0.md`
- `/home/theflow/projects/sydigital/strategic/governance/STR-GOV-0002-values-alignment-framework-v1-0.md`
**Framework Documentation:**
- `/home/theflow/projects/sydigital/strategic/frameworks/STR-FRM-0001-agentic-workflow-framework-v1-0.md`
- `/home/theflow/projects/sydigital/stochastic/innovation-exploration/STO-INN-0002-agentic-organizational-structure-whitepaper-i2.md`
---
## Session Reminders
**Always:**
- Verify you're in `/home/theflow/projects/tractatus` context
- Check MongoDB port 27017, application port 9000
- No shortcuts, no fake data, world-class quality
- Human approval for major decisions
- Update todo list as tasks progress
**Never:**
- Mix tractatus code with family-history or sydigital
- Make values decisions without human approval
- Deploy to production during Phase 1
- Rush implementation to meet arbitrary deadlines
- Use placeholder/lorem ipsum content
---
**Last Updated:** 2025-10-06
**Next Review:** After Phase 1 completion
Reference in a new issue View git blame Copy permalink