tractatus/docs/SESSION_MANAGEMENT_REFERENCE.md

Tractatus Session Management Reference

Purpose: Quick reference for optimal session startup and closedown procedures in Tractatus.

---

Quick Commands

Session Startup (MANDATORY)

node scripts/session-init.js

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

Blocks if: Local development server not running on port 9000 Fix: npm start in separate terminal, then re-run session-init.js

Session Closedown (User Request Only)

node scripts/session-closedown.js

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

Framework Status & Monitoring

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

# Framework audit (manual trigger)
node scripts/framework-audit-response.js --prompt "question" --type "boundary_question"

# Context pressure check
node scripts/check-session-pressure.js --tokens <current>/200000 --messages <count> --tasks <count>

Development & Deployment

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

# Deployment (unified workflow)
./scripts/deploy.sh          # Full deployment (auto-detects changes)
./scripts/deploy.sh --frontend-only
./scripts/deploy.sh --force-cache --restart
./scripts/deploy.sh --dry-run

# Remote service management
ssh -i ~/.ssh/tractatus_deploy ubuntu@vps-93a693da.vps.ovh.net "sudo systemctl status tractatus"

---

Optimal Startup Prompt (Copy-Paste)

Full version:

Initialize this Tractatus session for productive work:

1. Run session-init.js to validate framework and system state
2. If blocked by local server check:
   - Open new terminal: npm start
   - Wait for port 9000 to be active
   - Re-run: node scripts/session-init.js
3. Review handoff document if post-compaction (auto-displayed)
4. Verify all 6 framework services operational
5. Check MongoDB connection (tractatus_dev)
6. Review git status and recent commits
7. Confirm system status and readiness for work

Do NOT start working until validation completes successfully.

Shorter version:

initialize tractatus session

---

Optimal Closedown Prompt (Copy-Paste)

Full version:

Wrap up this Tractatus session with comprehensive closedown:

1. Run: node scripts/session-closedown.js
2. Script will automatically:
   - Kill all background processes
   - Clean temporary artifacts
   - Sync instructions to database
   - Analyze framework performance (6 services)
   - Categorize git changes for deployment
   - Prompt for deployment decision
   - Generate comprehensive handoff document
   - Create compaction marker for next session

3. Review generated handoff and fill in template sections:
   - SESSION ACCOMPLISHMENTS (actual work completed)
   - CRITICAL ISSUES IDENTIFIED (bugs/blockers discovered)
   - NEXT SESSION PRIORITIES (specific tasks with estimates)

4. Verify final state: handoff complete, all deliverables documented

The next session will auto-load this handoff on startup.

Shorter version:

wrap up tractatus session

---

Session Init Validation Checklist

What session-init.js Checks ✓

• Session Status: New vs. continuing session detection
• Post-Compaction Detection: Loads handoff if compaction marker exists
• Token Checkpoints: Resets to 50k, 100k, 150k milestones
• Background Processes: Detects orphaned processes from previous sessions
• Hook Approval Cache: Resets per-session approvals (inst_061)
• Instruction History: Loads active instructions from database
• Context Pressure: Initial pressure check (NORMAL expected)
• Framework Components: All 6 services status verification
• Framework Statistics: Activity counts from previous sessions
• Framework Tests: Unit tests for all 6 services (BLOCKS on failure)
• Prohibited Terms Scan: User-facing content compliance (inst_016/017/018)
• CSP Compliance: No inline styles/scripts in public files (inst_008)
• Defense-in-Depth: 5-layer credential protection audit (inst_072)
• Dependency Licenses: Apache 2.0 compatibility (inst_080)
• Local Server Enforcement: Port 9000 must be running (BLOCKS if not)
• Hook Architecture: Validates continuous enforcement system
• Database Sync: instruction-history.json → MongoDB
• Credential Vault: Optional vault server startup (port 8888)
• Calendar Reminders: Overdue and upcoming tasks

Expected Output on Success

═══════════════════════════════════════════════════════════════════
  Tractatus Framework - Session Initialization
═══════════════════════════════════════════════════════════════════

▶ 1. Checking Session Status
  ✓ New session detected - initializing framework
  Session ID: 2025-11-24-001

▶ 2. Resetting Token Checkpoints
  ✓ Token budget: 200,000
  ✓ Next checkpoint: 50,000 tokens (25%)

▶ 3. Loading Instruction History
  ✓ Active instructions: 83
    HIGH persistence: 15
    MEDIUM persistence: 28
    LOW persistence: 40

▶ 4. Running Initial Pressure Check
  ✓ Pressure Level: NORMAL
  ✓ Overall Score: 0.0%

▶ 5. Framework Components
  ✓ ContextPressureMonitor: ACTIVE
  ✓ InstructionPersistenceClassifier: READY
  ✓ CrossReferenceValidator: READY
  ✓ BoundaryEnforcer: READY
  ✓ MetacognitiveVerifier: READY (selective mode)
  ✓ PluralisticDeliberationOrchestrator: READY

▶ 6. Running Framework Tests
  ✓ All framework tests passed (36/36 tests)

▶ 9. Development Environment Enforcement
  ✓ Local development server running on port 9000
  ✓ Development environment ready

═══════════════════════════════════════════════════════════════════
  Framework Initialization Complete
═══════════════════════════════════════════════════════════════════

---

Session Closedown Validation Checklist

What session-closedown.js Does ✓

Phase 1: Comprehensive Cleanup

• Kill tracked background processes (inst_023)
• Kill untracked node/npm/jest processes (except dev server)
• Clean temporary artifacts (.memory-test, test-*.js files)
• Sync instruction-history.json to MongoDB

Phase 2: Framework Performance Analysis

• Display context pressure gauge (visual)
• Report all 6 framework service statistics
• Query audit log database for activity breakdown
• Calculate health score (0-100)

Phase 3: Git Change Categorization

• Categorize changes (framework, features, config, scripts, hooks, temp)
• Identify deployment-ready vs. excluded files
• Display recent commits (5 most recent)

Phase 4: Interactive Deployment

• Prompt for production deployment (yes/no/auto)
• Run deploy-full-project-SAFE.sh if approved
• Capture deployment output and status

Phase 5: Handoff Document Creation

• Generate SESSION_CLOSEDOWN_YYYY-MM-DD.md
• Include framework analysis, git changes, deployment results
• Include template sections for manual completion
• Scope adjustment summary (inst_052)
• Hook approval summary (inst_061)

Phase 6: Compaction Marker

• Create .claude/session-complete.marker
• Reference handoff document for next session
• Signal post-compaction restart expected

---

Session Handoff Document Structure

Every session closedown generates a comprehensive handoff with:

1. Mandatory Startup Procedure

• Commands to run (node scripts/session-init.js)
• What the script validates
• Reference to CLAUDE.md requirements

2. Session Accomplishments (⚠️ MANUAL FILL REQUIRED)

• Major deliverables created
• Strategic decisions made
• Research & analysis completed

3. Critical Issues Identified (⚠️ MANUAL FILL REQUIRED)

• P0: Blockers (must fix before major work)
• P1: High value (should fix soon)
• P2: Nice-to-have (can defer)

4. Next Session Priorities (⚠️ MANUAL FILL REQUIRED)

• Critical path tasks (ordered by priority)
• Secondary tasks (if time permits)
• Decision points (when to proceed vs. pivot)

5. Framework Performance

• Context pressure gauge (visual)
• Statistics by service (6 services)
• Audit log counts
• Health score

6. Git Changes & Deployment

• Deployment-ready changes (categorized)
• Deployment status (deployed/skipped/failed)
• Excluded files (temp, docs)
• Recent commits

7. Cleanup Summary

• Background processes killed
• Temporary files cleaned
• Instruction sync status

8. Session Activity Tracking

• Scope adjustments (inst_052)
• Hook approvals (inst_061)

9. Next Session Startup Guide

• Step-by-step initialization
• System validation checklist
• Quick reference (ports, credentials)

---

Framework Triggers & Commands

"ff" - Framework Audit (Manual Trigger)

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 When: User asks questions about VALUES, trade-offs, architectural decisions Output: Include audit IDs in response (e.g., "🔍 Framework Audit: audit_67abc123") See: inst_078 in instruction-history.json

"ffs" - Framework Statistics

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

Important: Use --tokens= parameter for accurate real-time pressure

---

Common Patterns

Pattern 1: Fresh Session Start

Startup: Run session-init.js → verify green checkmarks → start work Closedown: Generate handoff → fill template sections → commit all

Pattern 2: Post-Compaction Restart

Startup: Run session-init.js → handoff auto-loaded → review priorities → continue Closedown: Standard closedown (compaction marker already consumed)

Pattern 3: Framework Test Failure (BLOCKS)

Problem: session-init.js exits with test failures Fix:

1. Review test output for specific failures
2. Run npm test -- --testPathPattern="tests/unit" for details
3. Fix framework service bugs
4. Re-run session-init.js

Pattern 4: Local Server Not Running (BLOCKS)

Problem: session-init.js blocks at "Development Environment Enforcement" Fix:

1. Open new terminal
2. cd /home/theflow/projects/tractatus
3. npm start
4. Wait for "Server running on port 9000"
5. Re-run node scripts/session-init.js

Pattern 5: High Context Pressure

Symptom: ffs shows ELEVATED or HIGH pressure Action: Consider session closedown if approaching critical levels Checkpoints: Pressure reported automatically at 50k, 100k, 150k tokens

---

Anti-Patterns to Avoid

❌ Don't: Skip session-init.js at session start ✅ Do: Always run, even if "just checking something quickly"

❌ Don't: Continue working after closedown completes ✅ Do: STOP ALL WORK - handoff signals intent for fresh session

❌ Don't: Leave template sections unfilled in handoff ✅ Do: Document actual accomplishments, issues, priorities

❌ Don't: Bypass local server enforcement ✅ Do: Start server, test locally before production deployment

❌ Don't: Ignore framework test failures ✅ Do: Fix immediately - framework integrity is critical

❌ Don't: Skip framework triggers (ff, ffs) for values questions ✅ Do: Use ff for boundary-crossing decisions

❌ Don't: Deploy without reviewing git changes ✅ Do: Review categorization, exclude temp files

---

Time Investment & ROI

Without proper session management:

• Startup: 10-15 minutes (context rebuilding, troubleshooting)
• Closedown: 3-5 minutes (minimal documentation)
• Framework fade: High risk without validation
• Total: 13-20 minutes + context loss

With optimal session management:

• Startup: 3-5 minutes (automated validation, handoff loaded)
• Closedown: 5-10 minutes (automated analysis + manual template fill)
• Framework integrity: Verified via unit tests
• Total: 8-15 minutes, zero context loss, full governance

Net savings: 5+ minutes per session + improved compliance tracking Quality improvement: Framework enforcement, audit trail, deployment safety

---

Environment Reference

Ports

• 9000: Local development server (MANDATORY for session work)
• 27017: MongoDB (tractatus_dev database)
• 8888: Credential vault server (optional)
• Production: vps-93a693da.vps.ovh.net

Databases

• Local Dev: mongodb://localhost:27017/tractatus_dev
• Production: (same server, different deployment)

Key Files

• Session State: .claude/session-state.json
• Token Checkpoints: .claude/token-checkpoints.json
• Instruction History: .claude/instruction-history.json
• Handoffs: SESSION_CLOSEDOWN_YYYY-MM-DD.md (project root)
• Compaction Marker: .claude/session-complete.marker

Framework Services (All 6 Required)

1. ContextPressureMonitor: Session start, checkpoints, complex ops
2. InstructionPersistenceClassifier: Explicit instructions given
3. CrossReferenceValidator: Schema changes, config mods, architecture
4. BoundaryEnforcer: Privacy, ethics, values-sensitive decisions
5. MetacognitiveVerifier: 3+ file mods or 5+ sequential steps
6. PluralisticDeliberationOrchestrator: Values conflicts flagged

---

Troubleshooting

"Local server not running" Block

Symptom: session-init.js exits at section 9 with error Cause: Port 9000 not active Fix:

# Terminal 1: Start server
npm start

# Terminal 2: Wait for "Server running on port 9000", then:
node scripts/session-init.js

Framework Tests Failing

Symptom: session-init.js exits at section 6 Cause: Unit tests failing for framework services Fix:

# Run tests with details
npm test -- --testPathPattern="tests/unit"

# Fix reported failures in src/services/*.service.js
# Re-run session-init.js

Handoff Not Auto-Loading

Symptom: Post-compaction restart doesn't show handoff Cause: .claude/session-complete.marker missing or malformed Fix: Manually read latest SESSION_CLOSEDOWN_*.md file

MongoDB Connection Failed

Symptom: "MongoDB not running" warnings in session-init Cause: mongod service not started Fix:

sudo systemctl start mongod
node scripts/session-init.js

Orphaned Background Processes

Symptom: Multiple node/npm processes running after session Cause: Previous session didn't run closedown Fix:

node scripts/track-background-process.js cleanup
# Or manual: ps aux | grep node, then kill <pid>

---

Integration with CLAUDE.md

CLAUDE.md is the primary reference - always check it first.

This document provides:

• Quick command lookup
• Detailed checklists
• Troubleshooting guides
• Session workflow patterns

Use both: CLAUDE.md for "what", SESSION_MANAGEMENT_REFERENCE.md for "how"

---

File Locations

• This Reference: docs/SESSION_MANAGEMENT_REFERENCE.md
• Project Instructions: CLAUDE.md (project root)
• Session Scripts: scripts/session-init.js, scripts/session-closedown.js
• Framework Scripts: scripts/framework-*.js, scripts/check-*.js
• Handoff Documents: SESSION_CLOSEDOWN_*.md (project root)
• Instruction Database: .claude/instruction-history.json

---

Last Updated: 2025-11-24 Adapted From: Community project SESSION_MANAGEMENT_REFERENCE.md Status: In active use for Tractatus governance framework Philosophy: If it can be enforced in code, it should not be documented here.