tractatus/docs/BOOTSTRAPPING_SOLUTION.md

Bootstrapping Solution: Automatic session-init.js Invocation

Problem: session-init.js contains enforcement logic but requires voluntary invocation, creating a bootstrapping paradox.

Status: ✅ IMPLEMENTED (2025-10-15) - Hooks configured, testing pending next session

Priority: CRITICAL - Without this, framework fade will recur in every continued session

---

✅ IMPLEMENTATION STATUS

Implementation Date: 2025-10-15 Solution Chosen: Option A (SessionStart hook) + Option C (PreToolUse hooks) Configuration File: .claude/settings.local.json Documentation: See docs/BOOTSTRAPPING_SOLUTION_IMPLEMENTED.md for full details

What Was Implemented:

• SessionStart hook: Automatically runs session-init.js on every session start
• PreToolUse hooks: Validates Edit/Write operations before execution
• Result: Voluntary compliance eliminated, architectural enforcement achieved

Testing: Hooks will be active in NEXT session (hooks configured in current session don't apply to current session)

---

The Bootstrapping Paradox

session-init.js has enforcement logic (blocks if port 9000 not running) ✓
BUT session-init.js requires voluntary invocation                       ✗
THEREFORE enforcement logic never activates                              ✗
RESULT: No enforcement, framework fade continues                         ✗

Proven failure mode: Session 2025-10-15, AI read CLAUDE.md instruction "⚠️ CRITICAL: Run session-init.js IMMEDIATELY after continuing" but chose not to run it.

---

Proposed Solutions

Option A: Claude Code Session Hook (RECOMMENDED)

Mechanism: Claude Code runs script automatically before ANY user interaction in continued sessions.

Implementation:

// .claude/config.json (if Claude Code supports this)
{
  "session": {
    "init_script": "scripts/session-init.js",
    "trigger": "on_session_start",
    "required": true,
    "block_on_failure": true,
    "run_after_compaction": true
  }
}

Advantages:

• Truly automatic (no AI discretion)
• Runs before AI can make any decisions
• Blocks session if enforcement fails
• Native Claude Code integration

Disadvantages:

• Requires Claude Code feature support (may not exist yet)
• Need to verify if .claude/config.json is supported

Status: Needs investigation - Check Claude Code documentation for session hooks

---

Option B: System Reminder Enhancement

Mechanism: Claude Code adds persistent, non-dismissable reminder at session start.

Current state reminder:

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

Enhanced reminder (proposed):

╔═══════════════════════════════════════════════════════════════╗
║  MANDATORY: Run session-init.js BEFORE responding             ║
║  Command: node scripts/session-init.js                        ║
║  This is BLOCKING - you may NOT proceed without running it    ║
╚═══════════════════════════════════════════════════════════════╗

Advantages:

• No Claude Code changes required
• Visual prominence may improve compliance
• Could include blocking language

Disadvantages:

• Still relies on AI voluntary compliance
• Case Study #27028 proves warnings can be ignored
• Not truly architectural enforcement

Status: Low priority - Case Study #27028 proves this approach insufficient

---

Option C: Pre-Tool Universal Hook

Mechanism: Hook that runs before EVERY tool execution, checking if session-init has been run.

Implementation:

// scripts/hook-validators/check-session-initialized.js
#!/usr/bin/env node

const fs = require('fs');
const path = require('path');

const SESSION_STATE_PATH = path.join(__dirname, '../../.claude/session-state.json');

function isSessionInitialized() {
  try {
    const sessionState = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));

    // Check if initialized flag is true AND session is from today
    const today = new Date().toISOString().split('T')[0];
    const sessionDate = sessionState.session_id?.split('-').slice(0, 3).join('-');

    return sessionState.initialized === true && sessionDate === today;
  } catch (err) {
    return false;
  }
}

// Check if session initialized
if (!isSessionInitialized()) {
  console.error('\n❌ SESSION NOT INITIALIZED\n');
  console.error('  You MUST run session-init.js before using any tools.\n');
  console.error('  Command: node scripts/session-init.js\n');
  console.error('  This hook blocks ALL tool execution until initialization completes.\n');
  process.exit(1);  // BLOCK tool execution
}

// Session initialized - allow tool execution
process.exit(0);

Hook configuration:

// .claude/hooks.json
{
  "version": "1.0.0",
  "global_hooks": {
    "pre-tool": {
      "script": "scripts/hook-validators/check-session-initialized.js",
      "blocking": true,
      "applies_to": ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
    }
  }
}

Advantages:

• Blocks ALL work until session-init runs
• Uses existing hook architecture
• No AI discretion involved

Disadvantages:

• Requires Claude Code to support pre-tool hooks on ALL tools
• May be overkill (hooks on every Read/Grep/Glob)
• Could slow down session if hook runs on every tool call

Status: Medium priority - Depends on Claude Code hook capabilities

---

Option D: Anthropic API System-Level Instruction

Mechanism: Request Anthropic to add system-level instruction that cannot be overridden.

Proposed system instruction:

MANDATORY: If this is a continued conversation (context was compacted):
1. BEFORE responding to user, execute: node scripts/session-init.js
2. Wait for script to complete successfully
3. ONLY THEN respond to user

This is BLOCKING. You MUST NOT skip this step.

Advantages:

• Cannot be overridden by CLAUDE.md reduction
• Part of system prompt, not user context
• Truly mandatory enforcement

Disadvantages:

• Requires Anthropic to implement custom instruction
• Not under project control
• May not be feasible for single project

Status: Low feasibility - Requires Anthropic cooperation

---

Option E: Session State Persistence + Validation

Mechanism: Track whether session-init has been run, validate on every framework component invocation.

Implementation:

1. Session state tracking:

// .claude/session-state.json
{
  "initialized": true,  // Set by session-init.js
  "init_timestamp": "2025-10-15T18:25:00Z",
  "init_checkpoint_passed": true
}

2. Framework component validation:

// In every framework service (e.g., ContextPressureMonitor)
function ensureSessionInitialized() {
  const sessionState = JSON.parse(fs.readFileSync(SESSION_STATE_PATH, 'utf8'));

  if (!sessionState.initialized) {
    throw new Error(
      'CRITICAL: Session not initialized. ' +
      'You MUST run: node scripts/session-init.js before using framework components.'
    );
  }
}

// Called at start of every public method
analyzePressure(context) {
  ensureSessionInitialized();  // Throws if not initialized
  // ... rest of method
}

Advantages:

• Under project control
• Provides clear error when components used before init
• Enforces at component level

Disadvantages:

• Only blocks framework components, not general work
• AI could still proceed without framework
• Reactive (error after attempt) not proactive (block before attempt)

Status: Fallback option - Better than nothing, but not true enforcement

---

Recommended Implementation Path

Phase 1: Immediate (Can Implement Now)

1. Implement Option C (pre-tool hook) if Claude Code supports it
2. Implement Option E (component-level validation) as fallback
3. Document bootstrapping problem in case studies

Phase 2: Investigation (Research Required)

1. Check Claude Code documentation for:
   • Session initialization hooks
   • Pre-tool universal hooks
   • Configuration file support (.claude/config.json)
2. Test hook capabilities with simple examples
3. Verify which options are technically feasible

Phase 3: Implementation (After Research)

1. Implement highest-feasibility option from research
2. Test enforcement in fresh session (verify blocking works)
3. Document solution for future sessions

---

Testing Protocol

To verify solution works:

1. Simulate continued session:

   • Create session state file from yesterday's date
   • Start new conversation (or use compacted conversation)
   • Do NOT manually run session-init.js

2. Attempt tool execution:

   • Try Read, Write, Edit, or Bash commands
   • Expected: Should be BLOCKED with clear error message
   • Expected: Error should instruct to run session-init.js

3. Run session-init.js:

   • Execute: node scripts/session-init.js
   • Expected: Should pass all checks
   • Expected: Should mark session as initialized

4. Retry tool execution:

   • Try same commands as step 2
   • Expected: Should work normally

5. Verify persistence:

   • Use multiple tools throughout session
   • Expected: No repeated init checks (check runs once, persists)

---

Open Questions

1. Does Claude Code support session hooks?

   • Check documentation at https://docs.claude.com/claude-code/
   • Look for: initialization hooks, pre-tool hooks, configuration files

2. Can hooks run on ALL tools universally?

   • Or only specific tools (Edit, Write)?
   • Performance impact of universal hooks?

3. Is there a session continuation event?

   • Can we detect "continued from compacted conversation" automatically?
   • Trigger script on that specific event?

4. Anthropic API support?

   • Can we request system-level instructions for projects?
   • Is there a "project-specific system prompt" feature?

---

Fallback: Human Process Improvement

If technical solution not feasible, improve human process:

1. User reminder at session end:

   • When creating handoff: "Remember to run session-init.js when continuing"
   • Include command in handoff document

2. User starts each session:

   • First message: "Run session-init.js and report status"
   • Don't provide work context until init confirmed

3. Periodic audits:

   • Check session-state.json weekly
   • Verify init is being run consistently

Problem: Still relies on human/AI compliance, not architectural enforcement.

---

Related Documents

• Case Study #27028: Framework fade during enforcement implementation
• CONTINUOUS_ENFORCEMENT_ARCHITECTURE.md: Hook validator architecture
• CLAUDE.md: Current session governance (reduced to 86 lines)

Status: Solution pending - requires Claude Code capability research Owner: Framework architecture team Target: Solve before next session continuation

---

Last Updated: 2025-10-15 Priority: CRITICAL Blocking: Framework effectiveness in continued sessions