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

node scripts/session-init.js

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

This script enforces:

• ✅ Local development server running on port 9000 (BLOCKS if not running)
• ✅ Framework components initialized and operational
• ✅ Token checkpoints configured (50k, 100k, 150k)
• ✅ Session state tracking active
• ✅ Instruction history loaded

If blocked: Follow on-screen instructions to start local server, then re-run.

---

⚠️ SESSION CLOSEDOWN

node scripts/session-closedown.js

Run when user requests: "wrap up", "end session", "create handoff", "process session closedown"

This script executes:

• ✅ Background process cleanup
• ✅ Instruction database sync verification
• ✅ Framework performance analysis (all 6 services)
• ✅ Audit log analysis with rule suggestions
• ✅ Git status documentation
• ✅ Comprehensive handoff document creation
• ✅ Compaction marker for next session detection

STOP ALL WORK after script completes. Script output includes next session startup instructions.

---

🔍 FRAMEWORK TRIGGER: "ff"

When user prefixes prompt with ff, invoke full framework audit:

node scripts/framework-audit-response.js \
  --prompt "user's actual question" \
  --type "boundary_question"

Purpose: Manually trigger ALL 6 framework services for conversational responses (BoundaryEnforcer, PluralisticDeliberationOrchestrator, MetacognitiveVerifier, CrossReferenceValidator, ContextPressureMonitor, InstructionPersistenceClassifier).

When: User asks questions about VALUES, trade-offs, architectural decisions, or boundary-crossing topics.

Output: Include audit IDs in response (e.g., "🔍 Framework Audit: audit_67abc123")

See: inst_078 in instruction-history.json

🔍 FRAMEWORK TRIGGER: "ffs"

When user types ffs, display full framework statistics:

node scripts/framework-stats.js

Purpose: On-demand visibility into framework operational metrics during session

Reports:

• Session state (ID, message count, status)
• Token usage & checkpoints (25%, 50%, 75%)
• Context pressure level & metrics
• Instruction counts (by quadrant/persistence)
• Audit log counts (by service)
• Framework service status (all 6 services)

Output: Formatted report + JSON for programmatic access

When: User wants to see framework health/activity at any point in session

See: inst_082 in instruction-history.json

---

🎯 QUICK REFERENCE

Database: tractatus_dev (MongoDB port 27017) App: Node.js/Express on port 9000 (systemd, NOT pm2) Stack: Vanilla JS, Tailwind CSS, MongoDB Separate from: family-history, sydigital (no shared code) Approval required: Architectural changes, DB schema, security, values Quality: World-class, no shortcuts, no fake data

Common Commands:

# Session management
node scripts/session-init.js                  # Initialize session (MANDATORY)
node scripts/session-closedown.js             # End session (user request only)
node scripts/check-session-pressure.js        # Check context pressure

# Local development
npm start                                     # Start local server (port 9000)

# Production deployment (unified workflow)
./scripts/deploy.sh                           # Full deployment (auto-detects changes, auto-commits cache)
./scripts/deploy.sh --frontend-only           # Frontend-only (public/ directory)
./scripts/deploy.sh --force-cache --restart   # Force cache update + restart service
./scripts/deploy.sh --dry-run                 # Preview without deploying

# Service management (remote)
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"

# Document workflow
npm run migrate:docs -- --source docs/markdown --force
node scripts/generate-single-pdf.js <input.md> <output.pdf>

---

🚨 FRAMEWORK ENFORCEMENT

Governance is ENFORCED architecturally, not documented:

1. session-init.js - Blocks without local server on port 9000
2. Framework components - Initialize automatically, run continuously
3. Token checkpoints - Report pressure at 50k, 100k, 150k
4. Pre-action checks - node scripts/pre-action-check.js <type> [path] "<desc>"

Framework fade = enforcement gap → fix architecturally, not in docs.

---

📚 REFERENCE DOCUMENTS

• CLAUDE_Tractatus_Maintenance_Guide.md - Full governance framework
• docs/SESSION_MANAGEMENT_ARCHITECTURE.md - Session lifecycle design
• .claude/instruction-history.json - Persistent instruction database (auto-accessed)

---

Last Updated: 2025-10-25 (Added unified deployment script; cache versioning now auto-committed) Philosophy: If it can be enforced in code, it should not be documented here.