tractatus/CLAUDE_Tractatus_Maintenance_Guide.md

Tractatus - Claude Code Maintenance Guide

Comprehensive reference for Claude Code sessions on the Tractatus project

Last Updated: 2025-10-08 Version: 2.0.0 (Enforcement-First Architecture)

---

Table of Contents

1. Project Identity
2. Tractatus Framework Governance
3. Session Management
4. Development Conventions
5. Directory Structure
6. Phase 1 Deliverables
7. Human Approval Requirements
8. Te Tiriti & Indigenous Perspective
9. Links & References

---

Project Identity

Core Information

• 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

Core Services - Five Mandatory Components

All five MUST be active throughout every session. Framework fade = critical failure.

What is a "27027 Failure"?

Named after the port number 27027 from an October 2025 incident:

User instruction: "Check port 27027" (explicit, non-standard MongoDB port) Claude's action: Used port 27017 (standard default) Root cause: Pattern recognition bias - training data's "MongoDB = 27017" association overrode explicit instruction immediately

Key insight: This is NOT about forgetting. Claude never truly "heard" the instruction because the learned pattern was so strong it autocorrected the explicit input, like a spell-checker changing a deliberately unusual word.

Why this matters: As AI capabilities increase, training data creates stronger patterns, making this problem WORSE, not better. The framework must architecturally prevent pattern recognition from overriding explicit human instructions.

---

1. ContextPressureMonitor

Purpose: Session quality management through multi-factor pressure analysis

When to invoke:

• Session start (baseline: 0/200000 tokens)
• Every 25% tokens (50k, 100k, 150k)
• After complex multi-file operations
• After any error or unexpected behavior
• Every ~20 messages or 40k tokens

Pressure Levels:

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

Command:

node scripts/check-session-pressure.js --tokens <current>/<budget> --messages <count> --tasks <num> --errors <num>

Files updated:

• .claude/session-state.json (last_framework_activity.ContextPressureMonitor)
• .claude/token-checkpoints.json (completed checkpoints)

2. InstructionPersistenceClassifier

Purpose: Make explicit instructions override learned patterns to prevent 27027 failures (pattern recognition bias)

When to invoke:

• User gives explicit instruction
• Configuration specifications
• Architectural constraints
• Port/database requirements
• Coding standards
• Project-specific rules

Quadrant Mapping:

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"

Classification process:

1. Identify explicit instruction from user
2. Classify quadrant (STR/OPS/TAC/SYS/STO)
3. Determine persistence level (LOW/MEDIUM/HIGH/CRITICAL)
4. Assign temporal scope (SESSION/SPRINT/PROJECT/PERMANENT)
5. Set verification requirement (NONE/ADVISORY/MANDATORY)
6. Calculate explicitness score (0.0-1.0)
7. Store in .claude/instruction-history.json

Files updated:

• .claude/instruction-history.json (append new instruction)
• .claude/session-state.json (last_framework_activity.InstructionPersistenceClassifier)

3. CrossReferenceValidator

Purpose: Validate proposed actions against instruction history to prevent conflicts

When to invoke:

• Before database schema changes
• Before configuration modifications
• Before architectural decisions
• Before changing established patterns
• Before modifying system-level settings

Validation process:

1. Load .claude/instruction-history.json
2. Identify relevant instructions (by quadrant, scope, keywords)
3. Check for conflicts with proposed action
4. If HIGH/CRITICAL persistence conflicts: BLOCK action
5. Report conflicts to user with instruction details
6. Require user override for conflicting actions

Blocking criteria:

• HIGH persistence instruction + direct conflict = BLOCK
• CRITICAL persistence instruction + any conflict = BLOCK
• MANDATORY verification required + no verification = BLOCK

Files updated:

• .claude/session-state.json (last_framework_activity.CrossReferenceValidator)

4. BoundaryEnforcer

Purpose: Ensure AI never makes values decisions without human approval

When to invoke:

• Before privacy policy decisions
• Before ethical trade-off decisions
• Before user agency changes
• Before mission/values modifications
• Before governance document changes

Values boundaries (from Tractatus framework):

• Privacy vs. performance trade-offs
• User autonomy vs. safety
• Transparency vs. security
• Community vs. individual rights
• Indigenous sovereignty vs. technical expediency

Enforcement actions:

1. Detect values-sensitive decision domain
2. Report boundary violation to user
3. BLOCK automatic decision
4. Provide alternatives/research/analysis only
5. Require explicit human decision
6. Document decision in instruction history

Files updated:

• .claude/session-state.json (last_framework_activity.BoundaryEnforcer)

5. MetacognitiveVerifier

Purpose: AI self-checks reasoning before proposing complex actions

When to invoke (selective use):

• Operations with >3 file modifications
• Operations with >5 sequential steps
• Architecture changes (structural modifications)
• Security implementations
• Complex refactoring
• Multi-system integrations

Verification dimensions:

1. Alignment (0.0-1.0): Does action align with project goals?
2. Coherence (0.0-1.0): Is reasoning internally consistent?
3. Completeness (0.0-1.0): Are edge cases considered?
4. Safety (0.0-1.0): What are the risks?
5. Alternatives (0.0-1.0): Have alternatives been explored?

Overall Confidence:

• 0.90-1.0: HIGH - Proceed
• 0.75-0.89: MEDIUM - Proceed with caution
• 0.60-0.74: LOW - Reconsider approach
• <0.60: VERY LOW - Stop and rethink

Files updated:

• .claude/session-state.json (last_framework_activity.MetacognitiveVerifier)

---

Session Management

Session Start Protocol (MANDATORY)

Automated initialization (ALWAYS run this at session start):

# ONE COMMAND - Automated framework initialization
node scripts/session-init.js

# OR using npm script:
npm run framework:init

What this does automatically:

1. ✅ Detects if new session or continued session
2. ✅ Initializes .claude/session-state.json (new session ID, timestamp)
3. ✅ Resets .claude/token-checkpoints.json (25%, 50%, 75% milestones)
4. ✅ Loads .claude/instruction-history.json (displays active instruction counts)
5. ✅ Runs baseline pressure check via ContextPressureMonitor
6. ✅ Verifies all 5 framework components operational
7. ✅ Outputs formatted report with framework status

Then start dev server:

npm run dev  # Runs both server AND framework-watchdog.js

Manual fallback (if automated script fails):

# 1. Pressure baseline
node scripts/check-session-pressure.js --tokens 0/200000 --messages 0

# 2. Load instruction database
cat .claude/instruction-history.json | grep -c '"active": true'

# 3. Report to user
echo "Framework operational. Baseline: NORMAL (0%). Instructions loaded: X active."

Continuous Monitoring (THROUGHOUT SESSION)

Every ~10 messages OR ~20k tokens:

1. Check .claude/token-checkpoints.json for overdue checkpoints
2. Review .claude/session-state.json for component staleness
3. Verify watchdog has not reported alerts

At 25%, 50%, 75% token usage:

1. STOP current work
2. Run node scripts/check-session-pressure.js
3. Update both state files
4. Report pressure level + recommendations to user
5. Resume with adjusted behavior

Before major actions:

# Run pre-action check (blocking)
node scripts/pre-action-check.js <action-type> <description>

# Action types: file-edit, database, architecture, config, security, values, complex
# Exit codes: 0=PASS, 1=FAIL, 2=ERROR

Framework Fade Detection & Recovery

Framework fade = Components not being used = CRITICAL FAILURE

Automated detection (framework-watchdog.js):

• Monitors .claude/session-state.json every 30 seconds
• Detects staleness: component not used in 20 messages OR 30k tokens
• Detects overdue checkpoints
• Outputs visible warnings to terminal

Manual detection signs:

• No pressure check in 50k+ tokens
• Explicit instruction given but not classified
• Major change without cross-reference validation
• Values decision without boundary check
• Complex operation without metacognitive verification

Recovery protocol:

# 1. STOP all work immediately
# 2. Run recovery diagnostic
node scripts/recover-framework.js

# 3. Review issues reported
# 4. Address CRITICAL and HIGH issues
# 5. Resume with increased monitoring

Session Handoff (When to create)

Create handoff document when:

• Pressure reaches CRITICAL (70-85%) or DANGEROUS (85%+)
• Token usage exceeds 75% (150k/200k)
• Complex multi-phase work remains
• Errors clustering (3+ in short period)
• User requests session break

Handoff document should include:

1. Current session state (tokens, pressure, components used)
2. Completed tasks (with verification)
3. In-progress tasks (with blockers)
4. Pending tasks (prioritized)
5. Recent instruction additions
6. Known issues / challenges
7. Framework health assessment
8. Recommendations for next session

---

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
│   ├── instruction-history.json    # Persistent instruction database
│   ├── session-state.json          # Current session framework state
│   ├── token-checkpoints.json      # Token milestone tracking
│   ├── audit/                      # Framework audit logs
│   └── sessions/                   # Session handoff documents
├── .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/
│   ├── controllers/
│   ├── models/
│   ├── middleware/
│   │   └── tractatus/             # Framework enforcement middleware
│   ├── services/
│   │   ├── InstructionClassifier.service.js
│   │   ├── CrossReferenceValidator.service.js
│   │   ├── BoundaryEnforcer.service.js
│   │   ├── ContextPressureMonitor.service.js
│   │   └── MetacognitiveVerifier.service.js
│   ├── utils/
│   └── config/
├── scripts/                        # Setup & migration
│   ├── init-db.js
│   ├── migrate-documents.js
│   ├── generate-pdfs.js
│   ├── seed-admin.js
│   ├── check-session-pressure.js  # Pressure monitoring
│   ├── framework-watchdog.js      # Background monitoring
│   ├── pre-action-check.js        # Blocking validator
│   └── recover-framework.js       # Fade recovery
├── tests/
│   ├── unit/
│   ├── integration/
│   └── security/
├── data/                           # MongoDB data directory
├── logs/                           # Application & MongoDB logs
├── CLAUDE.md                       # Session start instructions (50-60 lines)
├── CLAUDE_Tractatus_Maintenance_Guide.md  # This file
├── README.md
└── LICENSE

---

Phase 1 Deliverables

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 AA)

Not in Phase 1

• Production deployment (OVHCloud)
• Domain configuration (agenticgovernance.digital)
• ProtonBridge email integration
• Koha donations (Phase 3)
• Public launch

---

Human Approval Requirements

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

---

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

---

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

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

---

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
• Use all five framework components continuously
• Update session state after each component use
• Run pressure checks at milestones

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
• Let framework components fade from active use
• Skip pre-action checks before major changes

---

End of Maintenance Guide