tractatus/docs/CONTINUOUS_ENFORCEMENT_ARCHITECTURE.md

# Continuous Enforcement Architecture

**Purpose**: Architectural enforcement of governance requirements throughout Claude Code sessions, independent of AI discretion.

**Problem Solved**: Framework components (ContextPressureMonitor, CrossReferenceValidator, BoundaryEnforcer, etc.) exist but require **voluntary AI invocation**. Documentation can be skipped as context grows. This led to Case Study #27028: production-first Umami deployment bypassing all governance checks.

**Solution**: Tool Use Hooks that run automatically before Edit/Write/Bash operations, enforcing governance requirements at the architectural level.

---

## Architecture Overview

### Layer 1: Session Initialization (Mandatory Entry Point)

**Script**: `scripts/session-init.js`

**Enforcement**:
- BLOCKS session if local development server not running on port 9000
- Uses `process.exit(1)` to prevent bypass
- Cannot be skipped - runs before any work begins

**Checks**:
1. Session state initialization
2. Token checkpoint reset
3. Instruction history load
4. Pressure baseline check
5. Framework component tests
6. **Development environment enforcement** (port 9000 check)
7. Hook validator status

### Layer 2: Tool-Level Hook Validators (Continuous Enforcement)

**Location**: `scripts/hook-validators/`

**Mechanism**: These scripts run **BEFORE** tool execution, blocking if validation fails.

#### validate-file-edit.js

**Runs before**: Edit tool

**Checks**:
1. **Pre-action validation**: CSP violations, file type restrictions
2. **CrossReferenceValidator**: Instruction conflicts (checks `.claude/instruction-history.json`)
3. **BoundaryEnforcer**: Values content requiring human approval

**Blocking**: YES - `process.exit(1)` prevents Edit if any check fails

**Exit Codes**:
- 0 = PASS (allow edit)
- 1 = FAIL (block edit)

**Example Flow**:
```
AI attempts: Edit public/docs.html (adds onclick="...")
  → Hook: validate-file-edit.js runs
  → Pre-action check detects CSP violation (inline event handler)
  → Hook exits with code 1
  → Edit tool BLOCKED
  → AI must fix CSP violation before proceeding
```

#### validate-file-write.js

**Runs before**: Write tool

**Checks**:
1. Pre-action validation (CSP, file restrictions)
2. **Overwrite detection**: Warning if file exists (suggests Read first)
3. CrossReferenceValidator (instruction conflicts)
4. BoundaryEnforcer (values decisions)

**Blocking**: YES for validation failures, WARNING for overwrites

**Exit Codes**:
- 0 = PASS (allow write)
- 1 = FAIL (block write)

#### check-token-checkpoint.js

**Runs before**: Any tool execution (planned)

**Checks**:
- Current token estimate vs next checkpoint (50k, 100k, 150k)
- If checkpoint overdue: BLOCK all tool execution

**Token Estimation**:
```javascript
// From .claude/session-state.json
const estimatedTokens = sessionState.message_count * 1500;
```

**Blocking**: YES - Forces pressure check before continuing

**Exit Codes**:
- 0 = PASS (checkpoint not overdue)
- 1 = FAIL (checkpoint overdue - must run pressure check)

**Example Flow**:
```
Session at 52,000 estimated tokens
50k checkpoint not completed
AI attempts: Edit file
  → Hook: check-token-checkpoint.js runs
  → Detects checkpoint overdue
  → Displays: "📊 TOKEN CHECKPOINT OVERDUE"
  → Requires: node scripts/check-session-pressure.js
  → Hook exits with code 1
  → Edit tool BLOCKED
  → AI must report pressure to user before continuing
```

### Layer 3: Pre-Approved Commands (Bash Optimization)

**Location**: `PRE_APPROVED_COMMANDS.md`

**Purpose**: Document bash command patterns that are pre-approved for execution without user confirmation during routine workflows.

**Categories**:
- Database operations (read-only, approved writes)
- Document migration & processing
- File operations (read-only)
- Validation & testing
- Production deployment (safe patterns)
- Session management

**Rationale**: Extracted from CLAUDE.md to reduce context consumption (was 68 lines, now separate document).

---

## Design Principles

### 1. Architectural, Not Voluntary

❌ **Before**: AI must remember to invoke framework components
✅ **After**: Hooks run automatically on tool execution

### 2. Blocking Enforcement

❌ **Before**: Documentation says "you should check for conflicts"
✅ **After**: Hook validator BLOCKS Edit until conflicts resolved

### 3. Context-Efficient

❌ **Before**: CLAUDE.md grows to 235 lines, consuming context
✅ **After**: CLAUDE.md reduced to 86 lines (63% reduction), enforcement in code

### 4. Transparent to User

- User sees hook output in real-time
- Clear error messages explain why action blocked
- Specific remediation steps provided

### 5. Fail-Safe Defaults

- If hook script fails to run: log warning but allow operation (fail open)
- If hook detects violation: block operation (fail closed)
- If session state missing: treat as new session (conservative)

---

## Implementation Status

### ✅ Implemented (2025-10-15)

1. **session-init.js local server enforcement** - Blocks without port 9000
2. **validate-file-edit.js** - Full implementation, ready to deploy
3. **validate-file-write.js** - Full implementation, ready to deploy
4. **check-token-checkpoint.js** - Full implementation, ready to deploy
5. **CLAUDE.md reduction** - 235 lines → 86 lines (63% reduction)
6. **PRE_APPROVED_COMMANDS.md** - Extracted from CLAUDE.md

### 🔄 Next Phase (Planned)

1. **Hook configuration**: `.claude/hooks.json` setup
2. **Hook testing**: Intentional violations to verify blocking
3. **validate-bash-command.js**: Production command safety checks
4. **classify-instruction.js**: Auto-classification of user instructions
5. **Integration testing**: Full workflow validation

### 📊 Metrics to Monitor

1. **Framework fade incidents**: Should approach zero with hooks
2. **Hook blocking rate**: How often hooks prevent violations
3. **False positive rate**: Hooks blocking legitimate operations
4. **Context consumption**: Token usage in CLAUDE.md vs enforcement code
5. **User feedback**: Transparency and clarity of hook messages

---

## Testing & Validation

### Test Scenarios (To Run)

1. **CSP Violation Test**:
   - Attempt Edit with inline onclick handler
   - Expected: Hook blocks, reports CSP violation
   - Remediation: Remove inline handler, use event listener

2. **Instruction Conflict Test**:
   - Add HIGH persistence instruction about port configuration
   - Attempt Edit to change port
   - Expected: Hook blocks, reports conflict
   - Remediation: Resolve or override instruction

3. **Token Checkpoint Test**:
   - Manually set token estimate to 51,000 in session-state.json
   - Mark 50k checkpoint as incomplete
   - Attempt any Edit
   - Expected: Hook blocks, requires pressure check
   - Remediation: Run check-session-pressure.js

4. **Values Content Test**:
   - Attempt Edit to file containing "values" in path
   - Expected: Hook blocks, requires human approval
   - Remediation: Get user approval before proceeding

### Performance Impact

- **Hook overhead**: ~100-500ms per Edit/Write operation
- **Acceptable**: For governance enforcement
- **Optimization**: Cache instruction history, session state in memory

---

## Comparison: Before vs After

### Case Study #27028 Scenario

**Before (With Documentation)**:
```
User: Install Umami analytics
AI: [Skips pre-action-check.js]
    [Skips CrossReferenceValidator]
    [Skips MetacognitiveVerifier]
    [Installs directly on production]
Result: Governance failure - production-first development
```

**After (With Hooks)**:
```
User: Install Umami analytics
AI: [Attempts Edit to nginx config]
    → Hook: validate-file-edit.js runs
    → Pre-action check: PASS
    → CrossReferenceValidator: Detects conflict with "local-first" instruction
    → Hook exits with code 1
    → Edit BLOCKED
    → AI: "Cannot proceed - conflicts with local-first development requirement"
    → AI: "Must set up local Umami on port 3001 first"
Result: Governance enforced - local testing required
```

---

## Open Questions & Future Work

### 1. Hook Overhead Tolerance

**Question**: Is 100-500ms per file operation acceptable?

**Trade-off**: Governance enforcement vs performance

**Mitigation**: Cache loaded data, optimize hot paths

### 2. Token Estimation Accuracy

**Current**: `message_count * 1500` tokens (rough approximation)

**Better**: Track actual token usage if API provides it

**Fallback**: Conservative estimation (triggers checkpoints early rather than late)

### 3. Bash Command Validation

**Challenge**: Hard to parse semantic intent from command string

**Approach**: Pattern matching against pre-approved list

**Limitation**: May need user approval for novel commands

### 4. User Sovereignty

**Design**: User can disable hooks if needed

**Rationale**: Tractatus framework respects human agency

**Protection**: session-init.js still blocks without local server

---

## Lessons Learned

### Why Documentation Failed

1. **Context consumption**: 235 lines of CLAUDE.md left less room for work
2. **Voluntary compliance**: AI could skip framework components
3. **Framework fade**: As session progressed, checks were forgotten
4. **No forcing function**: Documentation can't block operations

### Why Architectural Enforcement Works

1. **Automatic invocation**: Hooks run on tool execution, not AI discretion
2. **Blocking power**: `process.exit(1)` prevents bypass
3. **Context-efficient**: Enforcement code isn't repeated in prompts
4. **Transparent**: User sees enforcement happening
5. **Testable**: Can verify hooks block violations

### Key Insight

> "If it can be enforced in code, it should not be documented in CLAUDE.md."

Documentation is for reference. Enforcement is for compliance.

---

**Last Updated**: 2025-10-15
**Status**: Phase 1 Complete - Ready for testing and integration
**Next Review**: After first session using hook enforcement

**Related Documents**:
- CLAUDE.md - Reduced session governance document
- PRE_APPROVED_COMMANDS.md - Pre-approved bash patterns
- CLAUDE_Tractatus_Maintenance_Guide.md - Full framework documentation
- Case Study #27028 (pending) - Governance failure analysis