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