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) ✅
```bash
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**:
```bash
# 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:
```javascript
// 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:
```javascript
// 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**:

```javascript
// 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_<DATE>.md):
```markdown
# 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?