tractatus/docs/SESSION_MANAGEMENT_ARCHITECTURE.md

Session Management Architecture

Version: 2.0 Date: 2025-10-24 Status: Design Proposal

---

🎯 Executive Summary

Move session management from manual rules (inst_024_CONSOLIDATED) to executable scripts (session-init.js ✅, session-closedown.js 🔨). Scripts enforce consistency, reduce cognitive load, and enable automated framework analysis.

---

📋 Current State Analysis

What Works (session-init.js) ✅

node scripts/session-init.js

Enforcements:

• ✅ Local server running (BLOCKS if not)
• ✅ Framework component initialization
• ✅ Token checkpoint reset
• ✅ Instruction history loading
• ✅ Framework tests execution
• ✅ Database synchronization
• ✅ NEW: Framework statistics display

User Experience:

• User says: "start session" or runs init script
• Claude runs script
• Clear pass/fail output
• Framework proven operational

What's Missing (session-closedown) ❌

Current: inst_024_CONSOLIDATED (manual checklist)

(1) Kill background processes
(2) Verify instruction history
(3) Document git status
(4) Clean temporary artifacts
(5) Create handoff document
STOP ALL WORK after creating handoff

Problems:

• ❌ Manual execution (prone to skipping steps)
• ❌ No framework performance analysis
• ❌ No rule improvement suggestions
• ❌ Inconsistent handoff quality
• ❌ Compaction handling unclear

---

🏗️ Proposed Architecture

1. session-closedown.js Script

Invocation Pattern:

# User says: "process session closedown"
# Claude runs:
node scripts/session-closedown.js

Script Responsibilities:

Phase 1: Cleanup

• Kill background processes (ps aux | grep node/npm)
• Clean temporary artifacts (.memory-test/, lock files, test databases)
• Sync instruction-history.json to MongoDB (--force)
• Verify sync counts match

Phase 2: Framework Analysis (NEW 🔨)

• Collect statistics from all 6 framework services
• Analyze audit logs from this session
• Calculate metrics:
  • Enforcements per service
  • Violation patterns
  • Pressure trends
  • Classification accuracy
• Compare to baseline/previous sessions
• Generate performance report

Phase 3: Rule Intelligence (NEW 🔨)

• Identify recurring violations → suggest new rules
• Detect edge cases → suggest rule clarifications
• Find rule conflicts → suggest consolidation
• Output: SUGGESTED_RULES_<DATE>.md for human review

Phase 4: Git & State

• Capture complete git status
• Document modified files
• Check for uncommitted work
• Identify deployment state

Phase 5: Handoff Creation

• Generate SESSION_CLOSEDOWN_<DATE>.md with:
  • Session summary (tasks completed/pending)
  • Framework performance metrics
  • Suggested rule changes
  • Git status
  • Known issues
  • Startup instructions for next session

Phase 6: Compaction Prep (NEW 🔨)

• Create .claude/session-complete.marker
• Store session metadata for recovery
• STOP EXECUTION (script exits)

Exit Behavior: Script exits with code 0, Claude STOPS working

---

2. Compaction Handling Strategy

Problem: Compaction is automatic. Claude loses context. How to restart cleanly?

Solution: Marker-based Detection

When Closedown Runs:

// session-closedown.js creates:
{
  "session_completed": true,
  "closedown_timestamp": "2025-10-24T08:45:00Z",
  "next_action": "compaction_expected",
  "recovery_doc": "SESSION_CLOSEDOWN_2025-10-24.md"
}

When session-init.js Runs:

// Check for completion marker
if (sessionCompleteMarker.exists) {
  console.log('⚠️  PREVIOUS SESSION ENDED WITH CLOSEDOWN');
  console.log('📄 Recovery document:', marker.recovery_doc);
  console.log('');
  console.log('This appears to be a POST-COMPACTION restart.');
  console.log('Read recovery document for context.');

  // Delete marker (consumed)
  fs.unlinkSync(markerPath);
}

User Experience:

1. Session ends → User: "process session closedown"
2. Claude runs closedown script → STOPS
3. [Auto-compaction occurs]
4. New session → User runs session-init.js
5. Init detects marker → Shows recovery doc path
6. User reads SESSION_CLOSEDOWN_*.md → has full context

---

3. Framework Performance Analysis

Data Sources:

1. Service statistics (already implemented via .getStats())
2. MongoDB audit logs (auditLogs collection)
3. Session state (.claude/session-state.json)
4. Token usage (from checkpoints)

Analysis Metrics:

Service	Metrics
BoundaryEnforcer	Enforcements, violations, blocked actions, domains
ContextPressureMonitor	Pressure levels, warnings issued, error patterns
CrossReferenceValidator	Validations, conflicts, escalations, severity
InstructionPersistenceClassifier	Classifications, quadrant distribution, persistence levels
MetacognitiveVerifier	Verifications, decisions (PROCEED/BLOCK), confidence
PluralisticDeliberationOrchestrator	Deliberations, framework tensions, consensus/disagreements

Outputs:

1. Performance Dashboard: Visual summary in closedown doc
2. Anomaly Detection: Services not logging? Unusual patterns?
3. Baseline Comparison: This session vs historical average
4. Health Score: Overall framework effectiveness (0-100%)

---

4. Rule Suggestion Engine

Pattern Detection:

// Analyze audit logs for patterns
const violations = auditLogs.filter(log => !log.allowed);

// Group by reason
const violationPatterns = groupBy(violations, v => v.violations[0]);

// If same violation occurs 3+ times across different contexts:
if (violationPatterns['technical_architectural_change'].count >= 3) {
  suggestRule({
    pattern: 'technical_architectural_change',
    occurrences: violationPatterns.count,
    suggestion: 'Consider adding inst_XXX: Require human approval for architectural changes affecting >3 files',
    evidence: violations.slice(0, 3) // Show examples
  });
}

Suggestion Categories:

1. New Rules: Recurring violations → codify into rule
2. Rule Clarifications: Edge cases hitting unclear rules
3. Rule Deprecation: Rules never violated → maybe obsolete
4. Rule Consolidation: Multiple similar rules → merge
5. Quadrant Adjustments: Misclassified instructions

Output Format (SUGGESTED_RULES_.md):

# Suggested Rule Changes - 2025-10-24

## New Rules (3)

### SR-001: Architectural Change Approval
**Pattern**: 5 violations of boundary `technical_architectural`
**Suggestion**: Add inst_XXX requiring human approval for changes affecting system architecture
**Evidence**:
- 2025-10-24 10:15: Modified database schema without approval
- 2025-10-24 11:30: Changed authentication flow without discussion
...

**Proposed Rule**:
> When proposing changes to system architecture (authentication, authorization, database schema, API contracts), MUST get explicit human approval before implementation. Document decision rationale.

**Quadrant**: STRATEGIC
**Persistence**: HIGH
**Human Decision**: [ ] Approve [ ] Reject [ ] Modify

---

## Rule Clarifications (1)
...

## Rules Never Violated (Consider Deprecation) (2)
...

---

🔄 Session Lifecycle

┌─────────────────────────────────────────────┐
│ NEW SESSION STARTS                          │
│ User runs: node scripts/session-init.js     │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│ Session-init checks:                        │
│ • Compaction marker? → Show recovery doc    │
│ • Local server running?                     │
│ • Framework tests pass?                     │
│ • Framework stats (if any)                  │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│ WORK SESSION (Claude + User)                │
│ • Framework monitors continuously           │
│ • Audit logs accumulate                     │
│ • Token checkpoints hit                     │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│ SESSION ENDING                              │
│ User says: "process session closedown"      │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│ Claude runs: session-closedown.js           │
│ • Cleanup                                   │
│ • Framework analysis                        │
│ • Rule suggestions                          │
│ • Git status                                │
│ • Create handoff doc                        │
│ • Set compaction marker                     │
│ • EXIT (stops working)                      │
└─────────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────────┐
│ [AUTOMATIC COMPACTION MAY OCCUR]            │
└─────────────────────────────────────────────┘
              ↓
         (loop back to top)

---

🎯 Implementation Phases

Phase 1: Core Script (Week 1)

• Create scripts/session-closedown.js
• Implement cleanup (processes, temp files)
• Implement git status capture
• Implement handoff document generation
• Add compaction marker creation
• Update session-init.js to check marker

Phase 2: Framework Analysis (Week 1)

• Collect service statistics
• Query audit logs for session
• Calculate performance metrics
• Generate performance report section
• Add to handoff document

Phase 3: Rule Intelligence (Week 2)

• Implement violation pattern detection
• Build rule suggestion engine
• Generate SUGGESTED_RULES_*.md
• Create human review workflow
• Test with real session data

Phase 4: Documentation & Integration (Week 2)

• Update CLAUDE.md with new procedure
• Deprecate inst_024_CONSOLIDATED
• Create user guide for session management
• Add examples to documentation
• Train Claude on new workflow

---

💡 User Experience Improvements

Before (Manual)

User: "Create session handoff"
Claude: <manually follows inst_024 checklist>
        <creates inconsistent handoff>
        <sometimes forgets steps>
        <no framework analysis>
        <may continue working after handoff>

After (Automated)

User: "process session closedown"
Claude: <runs script>
        <script outputs:>

═══════════════════════════════════════════
  Session Closedown - 2025-10-24
═══════════════════════════════════════════

✓ Background processes killed (2 found)
✓ Temporary files cleaned
✓ Instructions synced to database
✓ Framework analysis complete

Framework Performance:
  • BoundaryEnforcer: 47 enforcements, 3 violations
  • ContextPressureMonitor: 23 analyses, peak: ELEVATED
  • ... (all 6 services)

  Health Score: 92/100 (Excellent)

Rule Suggestions: 2 new rules proposed
  → See: SUGGESTED_RULES_2025-10-24.md

Git Status:
  • Modified: 5 files
  • Branch: feature/audit-dashboard
  • Ready to commit: YES

Handoff Created:
  → SESSION_CLOSEDOWN_2025-10-24.md

Next Session Startup:
  → node scripts/session-init.js

Session closedown complete. Stopping work.
═══════════════════════════════════════════

<Claude stops>

---

🔐 Benefits

Consistency

• ✅ Every closedown follows same procedure
• ✅ No missed steps
• ✅ Reproducible results

Intelligence

• ✅ Framework learns from sessions
• ✅ Rule improvements suggested automatically
• ✅ Patterns detected and surfaced

Automation

• ✅ Reduces manual work
• ✅ Faster closedown process
• ✅ Lower cognitive load

Visibility

• ✅ Framework performance measured
• ✅ Session quality tracked over time
• ✅ Data-driven improvements

---

🚧 Open Questions

1. Rule Suggestion Threshold: How many violations before suggesting a rule? (Proposal: 3+)

2. Historical Comparison: Store session metrics for trending? Where? (Proposal: MongoDB collection)

3. Auto-commit: Should closedown offer to commit work automatically? (Proposal: Offer but require approval)

4. Emergency Closedown: Handle sudden session end (timeout, crash)? (Proposal: Periodic auto-save)

5. Multi-day Sessions: How to handle sessions spanning multiple days? (Proposal: Daily mini-closedowns)

---

📝 Recommendation

PROCEED with implementation in phases:

1. Immediate (this session): Create basic session-closedown.js with cleanup + handoff
2. Next session: Add framework analysis
3. Following session: Add rule suggestion engine
4. Ongoing: Refine based on usage

Deprecate: inst_024_CONSOLIDATED (replace with script invocation instruction)

New Instruction (inst_077):

When user requests session closedown (or says "wrap up", "end session", "create handoff"), execute: node scripts/session-closedown.js. Script will handle cleanup, analysis, and handoff creation. STOP ALL WORK after script completes. Do NOT continue working or respond beyond acknowledging completion.

---

Next Action: Create session-closedown.js with Phase 1 features?