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

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:

# 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

# 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:

{
  "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:

{
  "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

# 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