tractatus/docs/DOCUMENTATION_UPDATES_REQUIRED.md

# Documentation Updates Required for Governance Service

**Date**: 2025-11-06
**Status**: Specification for Implementation

**Copyright 2025 John Stroh**
Licensed under the Apache License, Version 2.0

---

## 1. Tractatus README.md Updates

### New Section: "Current Capabilities & Limitations"

**Location**: After "## 📚 Core Components" (line 96)

**Content to Add**:

```markdown
---

## ⚙️ Current Capabilities & Limitations

### What Tractatus CAN Do Today

✅ **Hook-Triggered Governance** (Production-Tested)
- Validates every Edit/Write/Bash operation before execution
- Blocks operations violating governance rules (31/39 rules automated)
- Runs via Claude Code's PreToolUse/PostToolUse lifecycle hooks
- Average overhead: 47ms per validation (imperceptible to developers)

✅ **Historical Pattern Learning** (Filesystem + Agent Lightning)
- Stores governance decisions in `.claude/observations/` directory
- Semantic search over past decisions (via Agent Lightning port 5001)
- Cross-session persistence (survives auto-compacts, session restarts)
- Pattern detection: "3 previous edits to this file caused rollback"

✅ **Proactive Warnings Before Tool Execution**
- Analyzes risk based on historical patterns
- Warns: "This operation previously failed under HIGH context pressure"
- Recommends: PROCEED | PROCEED_WITH_CAUTION | REVIEW_REQUIRED
- Injects context into Claude Code before governance validation runs

✅ **Six Framework Services** (See Core Components above)
- BoundaryEnforcer, CrossReferenceValidator, MetacognitiveVerifier
- ContextPressureMonitor, InstructionPersistenceClassifier
- PluralisticDeliberationOrchestrator

### What Tractatus CANNOT Do (Requires External Agent)

❌ **Continuous Awareness Between Tool Calls**
- Hooks only run when Claude Code calls Edit/Write/Bash
- No observation during AI reasoning process (between tool uses)
- Cannot detect "I'm planning a bad decision" before tool execution

❌ **Catching Reasoning Errors in Conversation**
- Hooks don't validate conversational responses (only tool calls)
- Cannot detect wrong advice, incorrect explanations, fabricated claims
- User must catch reasoning errors before they become actions

❌ **True Autonomous Agent Monitoring From Outside**
- Not a separate process watching Claude Code externally
- Cannot observe Claude Code from outside its own execution context
- Requires Claude Code to trigger hooks (not independent monitoring)

### Why External Agent Required for Full Coverage

To catch mistakes **before they become tool calls**, you need:
- External process monitoring Claude Code session logs
- Real-time analysis of conversational responses (not just actions)
- Continuous observation between AI responses (not hook-triggered)

**Tractatus provides the interface** for external agents (observations API, semantic search, governance rules).

**Partner opportunity**: Build external monitoring agent using Agent Lightning or similar framework.

---
```

**Implementation**: Insert this section after line 96 in README.md

---

## 2. Tractatus Implementer Page (implementer.html) Updates

### New Section: "Governance Service Architecture"

**Location**: Between `<div id="hooks">` and `<div id="deployment">` sections

**Anchor**: `<div id="governance-service" class="bg-white py-16">`

**Content HTML**:

```html
  <!-- Governance Service Architecture -->
  <div id="governance-service" class="bg-white py-16">
    <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
      <h2 class="text-3xl font-bold text-gray-900 mb-4">Governance Service: Learning from History</h2>

      <!-- Key Distinction Callout -->
      <div class="bg-blue-50 border-l-4 border-blue-500 rounded-r-lg p-6 mb-8">
        <h3 class="font-semibold text-gray-900 mb-2">Hook-Based Governance Service (Not Autonomous Agent)</h3>
        <div class="text-gray-700 space-y-2">
          <p><strong>What This Is:</strong> A governance service triggered by Claude Code's hook system that learns from past decisions and provides proactive warnings <em>before tool execution</em>.</p>
          <p><strong>What This Is NOT:</strong> An autonomous agent that continuously monitors Claude Code from outside. It only runs when Edit/Write/Bash tools are called.</p>
        </div>
      </div>

      <!-- Architecture Diagram -->
      <div class="bg-white rounded-xl shadow-lg p-6 sm:p-8 mb-8">
        <h3 class="text-xl font-bold text-gray-900 mb-4">Enhanced Hook Flow with Historical Learning</h3>
        <div class="bg-gray-50 rounded-lg p-4 sm:p-6 font-mono text-sm">
          <pre>
PreToolUse Hooks:
  1. proactive-advisor-hook.js (NEW)
     ├─→ SessionObserver.analyzeRisk(tool, params)
     ├─→ Query Agent Lightning: Semantic search past decisions
     ├─→ Detect patterns: "3 previous edits caused rollback"
     └─→ Inject warning if HIGH/CRITICAL risk

  2. framework-audit-hook.js (EXISTING)
     ├─→ BoundaryEnforcer (values decisions)
     ├─→ CrossReferenceValidator (pattern override)
     ├─→ MetacognitiveVerifier (confidence check)
     ├─→ ContextPressureMonitor (session quality)
     ├─→ InstructionPersistenceClassifier
     └─→ PluralisticDeliberationOrchestrator

Tool Executes (Edit/Write/Bash)

PostToolUse Hooks:
  session-observer-hook.js (NEW)
    ├─→ Record: [tool, decision, outcome, context]
    ├─→ Store in .claude/observations/
    └─→ Index via Agent Lightning for semantic search
          </pre>
        </div>
      </div>

      <!-- Three Components -->
      <h3 class="text-2xl font-bold text-gray-900 mb-4">Three New Components</h3>

      <div class="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
        <!-- SessionObserver.service.js -->
        <div class="bg-white rounded-lg border border-gray-200 p-6">
          <div class="text-3xl mb-3">🧠</div>
          <h4 class="font-bold text-gray-900 mb-2">SessionObserver.service.js</h4>
          <p class="text-sm text-gray-600 mb-3">Stores and queries historical governance decisions</p>
          <ul class="text-sm text-gray-700 space-y-1">
            <li>• Filesystem storage (.claude/observations/)</li>
            <li>• Semantic search via Agent Lightning</li>
            <li>• Risk calculation from patterns</li>
            <li>• Cross-session persistence</li>
          </ul>
        </div>

        <!-- proactive-advisor-hook.js -->
        <div class="bg-white rounded-lg border border-gray-200 p-6">
          <div class="text-3xl mb-3">⚠️</div>
          <h4 class="font-bold text-gray-900 mb-2">proactive-advisor-hook.js</h4>
          <p class="text-sm text-gray-600 mb-3">PreToolUse hook that warns before risky operations</p>
          <ul class="text-sm text-gray-700 space-y-1">
            <li>• Runs BEFORE framework-audit-hook</li>
            <li>• Queries historical patterns</li>
            <li>• Injects warnings into context</li>
            <li>• Risk levels: LOW/MEDIUM/HIGH/CRITICAL</li>
          </ul>
        </div>

        <!-- session-observer-hook.js -->
        <div class="bg-white rounded-lg border border-gray-200 p-6">
          <div class="text-3xl mb-3">📊</div>
          <h4 class="font-bold text-gray-900 mb-2">session-observer-hook.js</h4>
          <p class="text-sm text-gray-600 mb-3">PostToolUse hook that records outcomes</p>
          <ul class="text-sm text-gray-700 space-y-1">
            <li>• Records decision outcomes</li>
            <li>• Stores success/failure</li>
            <li>• Indexes via Agent Lightning</li>
            <li>• Builds historical knowledge base</li>
          </ul>
        </div>
      </div>

      <!-- Example Warning -->
      <div class="bg-white rounded-xl shadow-lg p-6 sm:p-8 mb-8">
        <h3 class="text-xl font-bold text-gray-900 mb-4">Example: Historical Pattern Warning</h3>
        <div class="bg-gray-900 text-gray-100 rounded-lg p-4 font-mono text-sm">
          <div class="text-yellow-400">⚠️ HISTORICAL PATTERN DETECTED</div>
          <div class="mt-2">
            <div class="text-gray-400">Analyzing: Edit src/server.js</div>
            <div class="text-gray-400">Context Pressure: ELEVATED</div>
            <div class="mt-2 text-white">Similar patterns found:</div>
            <div class="ml-4 mt-1">
              <div>1. Editing server.js under ELEVATED pressure caused deployment failure</div>
              <div class="text-gray-400">   (3 occurrences, last: 2025-11-05)</div>
              <div class="mt-1">2. Configuration changes at end of session required rollback</div>
              <div class="text-gray-400">   (2 occurrences, last: 2025-11-03)</div>
            </div>
            <div class="mt-3 text-yellow-400">Recommendation: PROCEED_WITH_CAUTION</div>
            <div class="text-gray-400">Consider: Create backup, test in dev environment first</div>
          </div>
        </div>
      </div>

      <!-- Capabilities & Limitations -->
      <div class="grid grid-cols-1 md:grid-cols-2 gap-6 mb-8">
        <!-- What It CAN Do -->
        <div class="bg-green-50 border-l-4 border-green-500 rounded-r-lg p-6">
          <h4 class="font-bold text-gray-900 mb-3">✅ What Governance Service CAN Do</h4>
          <ul class="space-y-2 text-sm text-gray-700">
            <li>✅ Learn from past mistakes (filesystem persistence)</li>
            <li>✅ Warn about risky patterns before execution</li>
            <li>✅ Semantic search: Find similar decisions</li>
            <li>✅ Cross-session persistence (survives compacts)</li>
            <li>✅ Hook overhead: &lt;100ms (imperceptible)</li>
          </ul>
        </div>

        <!-- What It CANNOT Do -->
        <div class="bg-red-50 border-l-4 border-red-500 rounded-r-lg p-6">
          <h4 class="font-bold text-gray-900 mb-3">❌ What It CANNOT Do (Requires External Agent)</h4>
          <ul class="space-y-2 text-sm text-gray-700">
            <li>❌ Monitor continuously between tool calls</li>
            <li>❌ Catch reasoning errors in conversation</li>
            <li>❌ Observe from outside Claude Code</li>
            <li>❌ Detect "planning" a bad decision (only execution)</li>
            <li>❌ Autonomous agent monitoring externally</li>
          </ul>
        </div>
      </div>

      <!-- Partner Opportunity Callout -->
      <div class="bg-purple-50 border-l-4 border-purple-500 rounded-r-lg p-6">
        <h4 class="font-bold text-gray-900 mb-2">🤝 Partner Opportunity: External Monitoring Agent</h4>
        <p class="text-gray-700 mb-3">
          Full coverage requires an <strong>external agent</strong> that monitors Claude Code sessions from outside, analyzing conversational responses and reasoning—not just tool executions.
        </p>
        <p class="text-gray-700 mb-3">
          This would complement Tractatus governance by catching mistakes <em>before</em> they become tool calls.
        </p>
        <p class="text-gray-700">
          <strong>Technology Stack:</strong> Agent Lightning, session log monitoring, real-time response analysis
        </p>
        <div class="mt-4">
          <a href="mailto:john.stroh.nz@pm.me?subject=External%20Agent%20Partnership"
             class="inline-flex items-center bg-purple-600 text-white px-4 py-2 rounded-lg text-sm font-semibold hover:bg-purple-700 transition min-h-[44px]">
            Contact About Partnership
          </a>
        </div>
      </div>

      <!-- Implementation Guide Link -->
      <div class="mt-8 text-center">
        <a href="/docs/GOVERNANCE_SERVICE_IMPLEMENTATION_PLAN.md"
           class="inline-flex items-center bg-blue-600 text-white px-6 py-3 rounded-lg font-semibold hover:bg-blue-700 transition">
          View Full Implementation Plan →
        </a>
      </div>

    </div>
  </div>
```

**Quick Links Update**: Add to navigation (line 134):

```html
<a href="#governance-service" class="text-purple-600 hover:text-purple-800 font-medium px-2 py-2 min-h-[44px] flex items-center">🧠 Governance Service</a>
```

---

## 3. Community Project Hooks Fix

### File: `/home/theflow/projects/community/.claude/settings.local.json`

**Current Problem**: All hooks set to `trigger: "user-prompt-submit"` instead of proper lifecycle hooks (PreToolUse/PostToolUse/UserPromptSubmit).

**Solution**: Replace with Tractatus-style configuration

**Steps**:

1. **Backup existing settings**:
   ```bash
   cp /home/theflow/projects/community/.claude/settings.local.json \
      /home/theflow/projects/community/.claude/settings.local.json.backup
   ```

2. **Create symlink to Tractatus hooks** (single source of truth):
   ```bash
   cd /home/theflow/projects/community/.claude
   rm -rf hooks/  # Remove existing hooks
   ln -s /home/theflow/projects/tractatus/.claude/hooks hooks
   ```

3. **Update settings.local.json**:
   - Copy PreToolUse/PostToolUse/UserPromptSubmit structure from `/home/theflow/projects/tractatus/.claude/settings.json`
   - Update `$CLAUDE_PROJECT_DIR` paths to work in Community context
   - Keep Community-specific project metadata (ports, etc.)

4. **Verify hooks are executable**:
   ```bash
   ls -la /home/theflow/projects/tractatus/.claude/hooks/*.js
   # Should all be -rwxr-xr-x (755)
   ```

5. **Test activation**:
   - Restart Claude Code session in Community project
   - Try dummy Edit operation
   - Verify hook output appears in console

---

## 4. Implementation Checklist

### Documentation

- [x] Create `GOVERNANCE_SERVICE_IMPLEMENTATION_PLAN.md`
- [x] Create `ANTHROPIC_CONSTITUTIONAL_AI_PRESENTATION.md`
- [ ] Update `README.md` with Capabilities & Limitations section
- [ ] Update `public/implementer.html` with Governance Service section

### Code

- [ ] Create `/home/theflow/projects/tractatus/src/services/SessionObserver.service.js`
- [ ] Create `/home/theflow/projects/tractatus/.claude/hooks/proactive-advisor-hook.js`
- [ ] Create `/home/theflow/projects/tractatus/.claude/hooks/session-observer-hook.js`
- [ ] Update `/home/theflow/projects/tractatus/.claude/settings.json` with new hooks

### Community Project

- [ ] Fix `/home/theflow/projects/community/.claude/settings.local.json`
- [ ] Create symlink: `community/.claude/hooks → tractatus/.claude/hooks`
- [ ] Test hooks activation in Community project session
- [ ] Verify governance blocks work (test with policy violation)

### Testing

- [ ] Unit tests for SessionObserver.service.js
- [ ] Integration tests for hook flow
- [ ] Performance tests (< 100ms overhead target)
- [ ] Cross-session persistence tests

---

## 5. Priority Order

**Immediate** (Complete this session):
1. ✅ Implementation plan document
2. ✅ Anthropic presentation document
3. Update README.md (add capabilities section)
4. Community hooks fix (enable governance for future sessions)

**Next Session**:
5. Update implementer.html (add new section)
6. Create SessionObserver.service.js
7. Create proactive-advisor-hook.js
8. Create session-observer-hook.js

**Week 2**:
9. Test in Tractatus project
10. Deploy to Community project
11. Deploy to Family project
12. Write tests

---

**Status**: 2/5 immediate tasks complete, 3 remaining
**Next**: Update README.md, fix Community hooks, then update implementer.html