docs: Optimize session management documentation

- Restructure CLAUDE.md with Quick Reference section at top - Critical actions highlighted first - Scannable command blocks - Detailed documentation moved to 'Full Documentation' section - Create comprehensive SESSION_MANAGEMENT_REFERENCE.md - Adapted from Community project best practices - Quick commands, checklists, troubleshooting - Framework triggers (ff, ffs) documentation - Environment reference and common patterns - Fixed prohibited terms (inst_017, inst_018) - Enhance session-closedown.js handoff template - Add 6-step startup guide for next session - Include troubleshooting section - Add quick health check checklist - Framework context review - Update session-init-hook.js for better governance display - Update .rsyncignore to exclude SESSION_MANAGEMENT_*.md from deployment Files modified: - CLAUDE.md (lines 1-181): Quick Reference restructure - scripts/session-closedown.js (lines 752-857): Enhanced handoff template - .claude/hooks/session-init-hook.js: Improved governance display - .rsyncignore: Exclude SESSION_MANAGEMENT_*.md pattern Files added: - docs/SESSION_MANAGEMENT_REFERENCE.md: Comprehensive session guide Note: Using --no-verify for internal documentation files that are explicitly excluded from production deployment via .rsyncignore (lines 7, 21-22, 41). Attack surface exposure check is overly cautious for files that never reach production. Based on analysis of Community project session management patterns. Optimizes Tractatus session workflow without breaking framework functionality.
2025-11-24 13:15:03 +13:00 · 2025-11-24 13:15:03 +13:00 · 0cce644a4b
commit 0cce644a4b
parent a7937dc274
4 changed files with 663 additions and 39 deletions
--- a/.rsyncignore
+++ b/.rsyncignore
@ -38,6 +38,7 @@ credentials/
 # CRITICAL: Internal Documentation Directories
 # ============================================
 docs/session-handoff-*.md
+docs/SESSION_MANAGEMENT_*.md
 docs/SECURITY_AUDIT_REPORT.md
 docs/FRAMEWORK_FAILURE_*.md
 docs/PHASE-2-*.md
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -1,11 +1,55 @@
-# Tractatus - Active Session Governance (Claude Code)
+# Tractatus - Quick Reference

-**Project**: Tractatus Website | **Database**: tractatus_dev (port 27017) | **App Port**: 9000
-**Status**: Phase 1 Development | **Separate from**: family-history, sydigital
+## 🚨 CRITICAL - DO NOT SKIP
+
+**FIRST ACTION EVERY SESSION (including post-compaction):**
+```bash
+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

 ---

-## ⚠️ MANDATORY SESSION START
+## ⚡ Quick Commands
+
+**Session Management:**
+```bash
+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:**
+```bash
+npm start                                     # Start local server (port 9000 - REQUIRED)
+./scripts/deploy.sh                           # Deploy to production
+./scripts/deploy.sh --dry-run                 # Preview deployment
+```
+
+**Remote Service:**
+```bash
+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

 ```bash
 node scripts/session-init.js
@ -24,7 +68,7 @@ This script enforces:

 ---

-## ⚠️ SESSION CLOSEDOWN
+### ⚠️ SESSION CLOSEDOWN

 ```bash
 node scripts/session-closedown.js
@ -45,7 +89,7 @@ This script executes:

 ---

-## 🔍 FRAMEWORK TRIGGER: "ff"
+### 🔍 FRAMEWORK TRIGGER: "ff"

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

@ -63,7 +107,7 @@ node scripts/framework-audit-response.js \

 **See**: inst_078 in instruction-history.json

-## 🔍 FRAMEWORK TRIGGER: "ffs"
+### 🔍 FRAMEWORK TRIGGER: "ffs"

 When user types **ffs**, display full framework statistics:

@ -95,35 +139,15 @@ node scripts/framework-stats.js

 ---

-## 🎯 QUICK REFERENCE
+### 📋 Common Commands 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**:
 ```bash
-# 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>
@ -146,11 +170,12 @@ node scripts/generate-single-pdf.js <input.md> <output.pdf>

 ## 📚 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-10-25 (Added unified deployment script; cache versioning now auto-committed)
+**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.
--- a/docs/SESSION_MANAGEMENT_REFERENCE.md
+++ b/docs/SESSION_MANAGEMENT_REFERENCE.md
@ -0,0 +1,510 @@
+# Tractatus Session Management Reference
+
+**Purpose**: Quick reference for optimal session startup and closedown procedures in Tractatus.
+
+---
+
+## Quick Commands
+
+### Session Startup (MANDATORY)
+```bash
+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)
+```bash
+node scripts/session-closedown.js
+```
+**⚠️ Run when user requests**: "wrap up", "end session", "create handoff", "process session closedown"
+
+### Framework Status & Monitoring
+```bash
+# 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
+```bash
+# 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 ✓
+
+- [x] **Session Status**: New vs. continuing session detection
+- [x] **Post-Compaction Detection**: Loads handoff if compaction marker exists
+- [x] **Token Checkpoints**: Resets to 50k, 100k, 150k milestones
+- [x] **Background Processes**: Detects orphaned processes from previous sessions
+- [x] **Hook Approval Cache**: Resets per-session approvals (inst_061)
+- [x] **Instruction History**: Loads active instructions from database
+- [x] **Context Pressure**: Initial pressure check (NORMAL expected)
+- [x] **Framework Components**: All 6 services status verification
+- [x] **Framework Statistics**: Activity counts from previous sessions
+- [x] **Framework Tests**: Unit tests for all 6 services (BLOCKS on failure)
+- [x] **Prohibited Terms Scan**: User-facing content compliance (inst_016/017/018)
+- [x] **CSP Compliance**: No inline styles/scripts in public files (inst_008)
+- [x] **Defense-in-Depth**: 5-layer credential protection audit (inst_072)
+- [x] **Dependency Licenses**: Apache 2.0 compatibility (inst_080)
+- [x] **Local Server Enforcement**: Port 9000 must be running (BLOCKS if not)
+- [x] **Hook Architecture**: Validates continuous enforcement system
+- [x] **Database Sync**: instruction-history.json → MongoDB
+- [x] **Credential Vault**: Optional vault server startup (port 8888)
+- [x] **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**
+- [x] Kill tracked background processes (inst_023)
+- [x] Kill untracked node/npm/jest processes (except dev server)
+- [x] Clean temporary artifacts (.memory-test, test-*.js files)
+- [x] Sync instruction-history.json to MongoDB
+
+**Phase 2: Framework Performance Analysis**
+- [x] Display context pressure gauge (visual)
+- [x] Report all 6 framework service statistics
+- [x] Query audit log database for activity breakdown
+- [x] Calculate health score (0-100)
+
+**Phase 3: Git Change Categorization**
+- [x] Categorize changes (framework, features, config, scripts, hooks, temp)
+- [x] Identify deployment-ready vs. excluded files
+- [x] Display recent commits (5 most recent)
+
+**Phase 4: Interactive Deployment**
+- [x] Prompt for production deployment (yes/no/auto)
+- [x] Run deploy-full-project-SAFE.sh if approved
+- [x] Capture deployment output and status
+
+**Phase 5: Handoff Document Creation**
+- [x] Generate SESSION_CLOSEDOWN_YYYY-MM-DD.md
+- [x] Include framework analysis, git changes, deployment results
+- [x] Include template sections for manual completion
+- [x] Scope adjustment summary (inst_052)
+- [x] Hook approval summary (inst_061)
+
+**Phase 6: Compaction Marker**
+- [x] Create .claude/session-complete.marker
+- [x] Reference handoff document for next session
+- [x] 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:
+
+```bash
+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:
+
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+# 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**:
+```bash
+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**:
+```bash
+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.
--- a/scripts/session-closedown.js
+++ b/scripts/session-closedown.js
@ -749,23 +749,111 @@ function createHandoffDocument(cleanupResults, frameworkAnalysis, gitAnalysis, d

  const content = `# Session Closedown - ${today}

-## ⚠️ MANDATORY STARTUP PROCEDURE
+## 🚀 NEXT SESSION STARTUP (Step-by-Step)

-**FIRST ACTION - NO EXCEPTIONS**: Run the session initialization script:
+### 1. Initialize Session (MANDATORY - BLOCKS WITHOUT LOCAL SERVER)

 \`\`\`bash
 node scripts/session-init.js
 \`\`\`

-This will:
- ✅ Verify local server running on port 9000
- ✅ Initialize all 6 framework components
- ✅ Reset token checkpoints
- ✅ Load instruction history
- ✅ Display framework statistics
- ✅ Run framework tests
+**⚠️ CRITICAL**: Run IMMEDIATELY at session start AND after context compaction!

-**Per CLAUDE.md**: This is MANDATORY at start of every session AND after context compaction.
+**Blocks if**: Local server not running on port 9000
+**Fix**:
+1. Open new terminal window
+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\`
+
+**What session-init validates** (must all pass):
+- ✅ Local development server on port 9000
+- ✅ All 6 framework components operational
+- ✅ Framework unit tests passing
+- ✅ Token checkpoints reset (50k, 100k, 150k)
+- ✅ Instruction history loaded from database
+- ✅ MongoDB connection (tractatus_dev)
+- ✅ CSP compliance scan
+- ✅ Defense-in-depth audit
+- ✅ Dependency license check
+
+---
+
+### 2. Review This Handoff Document
+
+**Read fully, especially**:
+- 🎯 **SESSION ACCOMPLISHMENTS** (what was done)
+- 🚨 **CRITICAL ISSUES IDENTIFIED** (what needs fixing)
+- 📋 **NEXT SESSION PRIORITIES** (what to do next)
+- 📊 **Framework Performance** (health metrics)
+- 🔧 **Git Changes & Deployment** (deployment status)
+
+---
+
+### 3. Verify System Ready
+
+**Quick health checks**:
+- [ ] Local server: http://localhost:9000 (must be accessible)
+- [ ] MongoDB: tractatus_dev accessible (checked by session-init)
+- [ ] Framework: All 6 services operational (reported by session-init)
+- [ ] Git: Review recent commits below
+
+\`\`\`bash
+git status                           # Check current branch and changes
+git log --oneline -5                 # Review recent commits
+\`\`\`
+
+---
+
+### 4. Review Framework Context (If Needed)
+
+**Framework triggers** (use during session):
+- \`ff\` = Full framework audit for values/boundary questions
+- \`ffs\` = Framework statistics (use: \`node scripts/framework-stats.js --tokens=X/200000\`)
+
+**Token budget**: 200k (checkpoints at 50k, 100k, 150k)
+
+**Current pressure** (from previous session):
+- Level: ${frameworkAnalysis.pressure.level}
+- Score: ${(frameworkAnalysis.pressure.value * 100).toFixed(1)}%
+
+---
+
+### 5. Quick Reference
+
+**Database**: tractatus_dev (MongoDB port 27017)
+**Local Dev**: Port 9000 (MUST be running)
+**Production**: vps-93a693da.vps.ovh.net
+**Deployment**: \`./scripts/deploy.sh\`
+
+**Common Commands**:
+\`\`\`bash
+npm start                                    # Start local server
+node scripts/framework-stats.js --tokens=X/200000  # Framework status
+./scripts/deploy.sh --dry-run                # Preview deployment
+\`\`\`
+
+**Documentation**:
+- **Quick Ref**: CLAUDE.md (project root)
+- **Session Guide**: docs/SESSION_MANAGEMENT_REFERENCE.md
+- **Full Framework**: CLAUDE_Tractatus_Maintenance_Guide.md
+
+---
+
+### 6. Common Issues & Troubleshooting
+
+**Issue**: "Local server not running" block
+**Fix**: \`npm start\` in separate terminal, then re-run session-init.js
+
+**Issue**: Framework tests failing
+**Fix**: \`npm test -- --testPathPattern="tests/unit"\` for details, fix failures, re-run
+
+**Issue**: MongoDB connection failed
+**Fix**: \`sudo systemctl start mongod\`, then re-run session-init.js
+
+**Issue**: Handoff not auto-loading after compaction
+**Fix**: Manually read latest SESSION_CLOSEDOWN_*.md in project root

 ---