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:

// 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