tractatus/CLAUDE.md

Tractatus - Quick Reference

🚨 CRITICAL - DO NOT SKIP

FIRST ACTION EVERY SESSION (including post-compaction):

node scripts/session-init.js

BLOCKS if: Local server not running on port 9000 → Fix: npm start in new terminal

Framework Triggers: ff = framework audit | ffs = framework stats

Session End (user request only): node scripts/session-closedown.js → STOP ALL WORK after completion

---

⚡ Quick Commands

Session Management:

node scripts/session-init.js                  # Initialize (MANDATORY - blocks without port 9000)
node scripts/session-closedown.js             # End session (user request only)
node scripts/framework-stats.js --tokens=X/200000  # Framework status
node scripts/check-session-pressure.js        # Context pressure check

Development:

npm start                                     # Start local server (port 9000 - REQUIRED)
./scripts/deploy.sh                           # Deploy to production
./scripts/deploy.sh --dry-run                 # Preview deployment

Remote Service:

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"

Environment:

• 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)
• Quality: World-class, no shortcuts, no fake data
• Approval required: Architectural changes, DB schema, security, values

---

📖 Full Documentation

⚠️ 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:

# With real-time context pressure (recommended)
node scripts/framework-stats.js --tokens=<current>/<budget>

# With cached data (may be stale)
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 (real-time when --tokens provided)
• Instruction counts (by quadrant/persistence)
• Audit log counts (by service)
• Framework service status (all 6 services)

Output: Formatted report + JSON for programmatic access

Important: Use --tokens= parameter for accurate real-time pressure. Without it, displays cached session data which may show 0% pressure.

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

See: inst_082 in instruction-history.json

---

📋 Common Commands Reference

# 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

# 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

• docs/SESSION_MANAGEMENT_REFERENCE.md - Session workflow guide, checklists, troubleshooting
• 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-11-24 (Optimized session management documentation; added Quick Reference) Philosophy: If it can be enforced in code, it should not be documented here.