tractatus/CLAUDE.md

Tractatus - Active Session Governance (Claude Code)

Project: Tractatus Website | Database: tractatus_dev (port 27017) | App Port: 9000 Status: Phase 1 Development | Separate from: family-history, sydigital

---

⚠️ MANDATORY SESSION START PROTOCOL

IMMEDIATELY upon session start, run ONE command:

node scripts/session-init.js

⚠️ CRITICAL: Also run this IMMEDIATELY after continuing from a compacted conversation!

This automated script will:

1. ✅ Detect new session vs. continued session
2. ✅ Initialize session state and reset token checkpoints
3. ✅ Load instruction history (shows active HIGH/MEDIUM/LOW counts)
4. ✅ Run baseline pressure check (ContextPressureMonitor)
5. ✅ Verify all 5 framework components operational
6. ✅ Report framework status to user

Manual fallback (if script fails):

• node scripts/check-session-pressure.js --tokens 0/200000 --messages 0
• Read .claude/instruction-history.json for active instructions

---

🔒 FIVE MANDATORY FRAMEWORK COMPONENTS (ALWAYS ACTIVE)

These MUST be used continuously throughout EVERY session. No exceptions.

1. ContextPressureMonitor (Every 25% tokens = 50k)

• When: Session start, 50k, 100k, 150k tokens, complex operations, errors
• Command: node scripts/check-session-pressure.js --tokens <current>/<budget> --messages <count>
• Update: .claude/session-state.json and .claude/token-checkpoints.json

2. InstructionPersistenceClassifier (All explicit directives)

• When: User gives explicit instruction (ports, configs, requirements, constraints)
• Action: Classify quadrant (STR/OPS/TAC/SYS/STO), persistence level, temporal scope
• Store: Append to .claude/instruction-history.json

3. CrossReferenceValidator (Before major changes)

• When: Database changes, config modifications, file edits, architecture decisions
• Action: Check .claude/instruction-history.json for conflicts
• Block: If conflicts with HIGH persistence instructions

4. BoundaryEnforcer (Before values decisions)

• When: Privacy decisions, ethical trade-offs, user agency, mission changes
• Action: Verify decision doesn't cross into values territory
• Block: All values decisions require human approval

5. MetacognitiveVerifier (Complex operations only)

• When: Operations with >3 files, >5 steps, architecture changes, security implementations
• Action: Verify alignment, coherence, completeness, safety, alternatives
• Report: Confidence score + alternatives before proceeding

---

🚨 FRAMEWORK FADE DETECTION & RECOVERY

Framework fade = Components not being used. This is CRITICAL FAILURE.

Signs of fade:

• No pressure check in 50k tokens
• No instruction classification when directive given
• No boundary check before values decision
• No validator check before major change

Immediate action when fade detected:

1. STOP all work
2. Run: node scripts/recover-framework.js
3. Report to user: Framework lapsed, recovery initiated
4. Resume: Only after recovery complete

Automated monitoring: npm run dev now runs framework-watchdog.js in background

---

📋 PRE-ACTION CHECK (Required before major actions)

Before ANY of these, run: node scripts/pre-action-check.js <action-type> [file-path] <description>

Action types: file-edit, database, architecture, config, security, values, complex

File path (optional): When editing HTML/JS files, include file path for automated CSP validation

• Example: node scripts/pre-action-check.js file-edit public/docs.html "Update navigation"

Exit codes:

• 0 = PASS (proceed)
• 1 = FAIL (blocked, address issues)
• 2 = ERROR (system failure)

🔒 Automated CSP Validation (inst_008 enforcement):

• Automatically validates HTML/JS files for Content Security Policy violations
• Detects: inline event handlers (onclick=), inline styles (style=""), inline scripts, javascript: URLs
• Blocks action if violations found - prevents CSP violations from reaching production
• This automated check catches violations that manual review might miss

---

📚 DETAILED REFERENCE DOCUMENTS

• CLAUDE_Tractatus_Maintenance_Guide.md: Full governance framework, conventions, directory structure
• docs/claude-code-framework-enforcement.md: Complete technical documentation
• .claude/instruction-history.json: Persistent instruction database
• .claude/session-state.json: Current session framework activity
• .claude/token-checkpoints.json: Token milestone tracking

---

🎯 QUICK REFERENCE

MongoDB: Port 27017, database tractatus_dev Application: Node.js/Express, port 9000 Tech Stack: Vanilla JS, Tailwind CSS, MongoDB, Express No shared code: Separate from family-history and sydigital Human approval required: Architectural changes, DB schema, security, values content Quality standard: World-class, no shortcuts, no fake data

Process Management: systemd (NOT pm2)

Production: tractatus.service (systemd service on vps-93a693da.vps.ovh.net) Development: Run via npm start (local development) or tractatus-dev.service (systemd)

Key Commands:

# Production status/control
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "sudo systemctl status tractatus"
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "sudo systemctl restart tractatus"
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "sudo journalctl -u tractatus -f"

# Install/update systemd services
./scripts/install-systemd.sh prod  # Production
./scripts/install-systemd.sh dev   # Development (requires sudo password)

Service Files: systemd/tractatus-prod.service, systemd/tractatus-dev.service Security: NoNewPrivileges, PrivateTmp, ProtectSystem=strict, 2G memory limit Auto-start: Enabled on boot via systemctl enable

---

Last Updated: 2025-10-09 (Migrated from pm2 to systemd, added automated CSP validation) For full details: See CLAUDE_Tractatus_Maintenance_Guide.md