# 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