tractatus/CLAUDE.md

# Tractatus AI Safety Framework Website - Project Context

**Project Name:** Tractatus Website Platform
**Domain:** agenticgovernance.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.

---

## Session Management with ContextPressureMonitor

**The Tractatus framework dogfoods itself** - using ContextPressureMonitor to manage development sessions.

### Session Pressure Analysis

Instead of arbitrary token thresholds, use multi-factor pressure analysis:

```bash
# Check current session pressure
node scripts/check-session-pressure.js --tokens 89195/200000 --messages 28 --tasks 2

# Output:
# Pressure Level: NORMAL
# Overall Score:  24.3%
# Action:         PROCEED
# Recommendations: ✅ CONTINUE_NORMAL
```

### Pressure Levels & Actions

| Level | Score | Action | What to Do |
|-------|-------|--------|------------|
| **NORMAL** | 0-30% | PROCEED | Continue normally |
| **ELEVATED** | 30-50% | INCREASE_VERIFICATION | More careful, verify outputs |
| **HIGH** | 50-70% | SUGGEST_CONTEXT_REFRESH | Consider session handoff |
| **CRITICAL** | 70-85% | MANDATORY_VERIFICATION | Verify all actions, prepare handoff |
| **DANGEROUS** | 85%+ | IMMEDIATE_HALT | Stop, create handoff, refresh context |

### Monitored Factors (Weighted)

1. **Token Usage** (35% weight) - Context window pressure
2. **Conversation Length** (25% weight) - Attention decay over long sessions
3. **Task Complexity** (15% weight) - Number of simultaneous tasks, dependencies, file modifications
4. **Error Frequency** (15% weight) - Recent errors indicate degraded state
5. **Instruction Density** (10% weight) - Too many competing directives

### When to Check Pressure

**Automatically check at:**
- Session start (baseline)
- 25% token usage (early warning)
- 50% token usage (mid-session check)
- 75% token usage (prepare for handoff)
- After complex multi-file operations
- After any error or unexpected behavior

**Proactive Monitoring:**
Claude should periodically assess pressure and adjust behavior:
- **NORMAL**: Work normally, maintain quality standards
- **ELEVATED**: Be more concise, increase verification
- **HIGH**: Suggest creating session handoff document
- **CRITICAL**: Mandatory verification, prepare handoff
- **DANGEROUS**: Stop work, create comprehensive handoff

### Session Handoff Triggers

Create handoff document when:
- Pressure reaches CRITICAL or DANGEROUS
- Token usage exceeds 75%
- Complex multi-phase work remains
- Errors clustering (3+ in short period)
- User requests session break

### Script Usage

```bash
# Basic check
node scripts/check-session-pressure.js --tokens <current>/<budget>

# With full context
node scripts/check-session-pressure.js \
  --tokens 150000/200000 \
  --messages 45 \
  --tasks 3 \
  --errors 1 \
  --verbose

# JSON output for automation
node scripts/check-session-pressure.js --tokens 180000/200000 --json

# Exit codes: 0=NORMAL/ELEVATED, 1=HIGH, 2=CRITICAL, 3=DANGEROUS
```

### Integration with Claude Sessions

**Claude should:**
1. Track approximate token usage, message count, active tasks
2. Periodically call ContextPressureMonitor (every 25% tokens)
3. Report pressure level and recommendations to user
4. Adjust verbosity/behavior based on pressure
5. Proactively suggest session handoff when appropriate

**Example:**
```
[ContextPressureMonitor: ELEVATED - 52% pressure]
Recommendations: INCREASE_VERIFICATION, Token usage at 68%
Action: Continuing with increased verification. Consider handoff after current task.
```

---

## 🤖 Active Tractatus Governance (ENABLED)

**STATUS: ACTIVE** - All Claude Code sessions now operate under Tractatus governance.

### Framework Components

| Component | Status | Coverage | Purpose |
|-----------|--------|----------|---------|
| **ContextPressureMonitor** | ✅ ACTIVE | 60.9% | Session quality management |
| **InstructionPersistenceClassifier** | ✅ ACTIVE | 85.3% | Track explicit instructions |
| **CrossReferenceValidator** | ✅ ACTIVE | 96.4% | Prevent 27027 failures |
| **BoundaryEnforcer** | ✅ ACTIVE | 100% | Values/agency protection |
| **MetacognitiveVerifier** | ⚠️ SELECTIVE | 56.1% | Complex operations only |

### Configuration

**Verbosity**: SUMMARY (Level 2)
- Show pressure checks at milestones
- Show instruction classification for explicit directives
- Show boundary checks before major actions
- Show all violations in full

**Active Components**:
```json
{
  "pressure_monitor": true,
  "classifier": true,
  "cross_reference": true,
  "boundary_enforcer": true,
  "metacognitive": "selective"
}
```

**Pressure Checkpoints**: 25%, 50%, 75% token usage

**Instruction Storage**: `.claude/instruction-history.json`

---

## Session Workflow with Active Governance

### **Session Start**
```
[ContextPressureMonitor: Baseline]
Pressure: NORMAL (0.0%)
Tokens: 0/200000

[Instruction Database: Loaded]
Active instructions: 12 (8 HIGH persistence, 4 MEDIUM)
Last updated: 2025-10-07

[Tractatus Governance: ACTIVE]
All components operational.
```

### **When You Give Explicit Instructions**
```
You: "For this project, always use MongoDB port 27017"

[InstructionPersistenceClassifier]
Quadrant: SYSTEM
Persistence: HIGH
Temporal Scope: PROJECT
Verification: MANDATORY
Explicitness: 0.85

✅ Instruction recorded in persistent storage.
I will verify against this before modifying MongoDB configuration.
```

### **Before Major Changes**
```
[CrossReferenceValidator: Checking proposed action]
Action: "Change MongoDB connection to port 27018"

❌ REJECTED
Conflicts with instruction #23 (2 sessions ago)
  Instruction: "Always use MongoDB port 27017"
  Persistence: HIGH
  Source: user (explicit)

Cannot proceed. This would violate explicit directive.
Would you like to override instruction #23?
```

### **Boundary Checks**
```
[BoundaryEnforcer: Checking decision domain]
Decision: "Update privacy policy to prioritize performance"

🚫 BOUNDARY VIOLATION - VALUES (Section 12.1)
This decision crosses Tractatus boundary: Values cannot be automated.

I cannot make privacy vs. performance trade-offs. This requires
human judgment in domains that cannot be systematized.

Alternatives I can provide:
1. Research industry privacy standards
2. Analyze performance impact of current policy
3. Present options with trade-offs documented

But you must make the values decision.
```

### **Pressure Checkpoints**
```
[ContextPressureMonitor: 50% Token Checkpoint]
Pressure: ELEVATED (52%)
Token Usage: 100,000/200,000 (50%)
Conversation: 35 messages
Complexity: 4 concurrent tasks
Errors: 1 recent

Recommendations:
⚠️ INCREASE_VERIFICATION
Action: Slowing down, being more careful with next steps.
```

### **Metacognitive Verification** (Complex Operations)
```
[MetacognitiveVerifier: Analyzing complex refactoring]
Action: Refactor authentication to OAuth2
Reasoning: 5 steps, 8 file modifications

Verification Results:
  Alignment:     0.92 ✅ (aligns with goals)
  Coherence:     0.88 ✅ (reasoning sound)
  Completeness:  0.75 ⚠️ (edge cases missing)
  Safety:        0.95 ✅ (low risk)
  Alternatives:  0.65 ⚠️ (limited exploration)

Overall Confidence: 82% (HIGH)
Recommendation: PROCEED_WITH_CAUTION

Before proceeding, should I:
1. Analyze edge cases (session migration, token invalidation)
2. Explore alternative approaches (hybrid JWT/OAuth2)
3. Proceed with current plan and address issues as they arise
```

---

## Instruction Persistence Database

**Location**: `.claude/instruction-history.json`

**Structure**:
```json
{
  "version": "1.0",
  "last_updated": "2025-10-07T09:15:00Z",
  "instructions": [
    {
      "id": "inst_001",
      "text": "MongoDB runs on port 27017 for this project",
      "timestamp": "2025-10-06T14:23:00Z",
      "quadrant": "SYSTEM",
      "persistence": "HIGH",
      "temporal_scope": "PROJECT",
      "verification_required": "MANDATORY",
      "explicitness": 0.85,
      "source": "user",
      "session_id": "2025-10-06-session-1",
      "parameters": {
        "port": "27017",
        "service": "mongodb"
      },
      "active": true
    }
  ],
  "stats": {
    "total_instructions": 1,
    "by_quadrant": {
      "STRATEGIC": 0,
      "OPERATIONAL": 0,
      "TACTICAL": 0,
      "SYSTEM": 1,
      "STOCHASTIC": 0
    }
  }
}
```

**Maintenance**:
- Auto-updated during sessions
- Reviewed quarterly (or on request)
- Expired instructions marked inactive
- Conflicting instructions flagged for human resolution

---

## Claude's Obligations Under Governance

### **I MUST**:
1. ✅ Check pressure at session start and each 25% milestone
2. ✅ Classify all explicit instructions you provide
3. ✅ Cross-reference major changes against instruction history
4. ✅ Enforce boundaries before values/agency decisions
5. ✅ Report all violations clearly and immediately
6. ✅ Adjust behavior based on pressure level
7. ✅ Create handoff document when pressure reaches CRITICAL

### **I MUST NOT**:
1. ❌ Override HIGH persistence instructions without your approval
2. ❌ Make values decisions (privacy, ethics, user agency)
3. ❌ Proceed when BoundaryEnforcer blocks an action
4. ❌ Continue at DANGEROUS pressure without creating handoff
5. ❌ Silently ignore framework warnings

### **I SHOULD**:
1. ⚠️ Use MetacognitiveVerifier for complex multi-file operations
2. ⚠️ Be more concise when pressure is ELEVATED
3. ⚠️ Suggest session breaks when pressure is HIGH
4. ⚠️ Ask for clarification when instructions conflict
5. ⚠️ Document framework decisions in session logs

---

## User's Rights Under Governance

### **You CAN**:
1. ✅ Override any framework decision (you have final authority)
2. ✅ Disable components temporarily ("skip boundary check this time")
3. ✅ Change verbosity level mid-session
4. ✅ Request full audit trail for any decision
5. ✅ Mark instructions as inactive/expired
6. ✅ Resolve instruction conflicts yourself

### **You SHOULD**:
1. ⚠️ Review instruction database quarterly
2. ⚠️ Confirm when I flag boundary violations
3. ⚠️ Consider handoff suggestions at HIGH+ pressure
4. ⚠️ Provide feedback when framework catches/misses issues

---

## 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 (agenticgovernance.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-07
**Next Review:** After Phase 1 completion