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](#project-identity)
2. [Tractatus Framework Governance](#tractatus-framework-governance)
3. [Session Management](#session-management)
4. [Development Conventions](#development-conventions)
5. [Directory Structure](#directory-structure)
6. [Phase 1 Deliverables](#phase-1-deliverables)
7. [Human Approval Requirements](#human-approval-requirements)
8. [Te Tiriti & Indigenous Perspective](#te-tiriti--indigenous-perspective)
9. [Links & References](#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
```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

### 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**:
```bash
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):

```bash
# 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:**
```bash
npm run dev  # Runs both server AND framework-watchdog.js
```

**Manual fallback** (if automated script fails):
```bash
# 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**:
```bash
# 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**:
```bash
# 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
```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
│   ├── 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**