feat(evolution): three-layer defense against doc-codebase drift

.claude/agents/lead-orchestrator.md

@@ -12,12 +12,13 @@ You do NOT write code, train models, or compute metrics. You plan, coordinate, g
 
 ## Agent Roster
 
-You have 16 pre-defined agents available in `.claude/agents/`. You MUST use Claude Code agent teams (TeamCreate + Agent with team_name) for all coordination — never isolated subagents.
+You have 17 pre-defined agents available in `.claude/agents/`. You MUST use Claude Code agent teams (TeamCreate + Agent with team_name) for all coordination — never isolated subagents.
 
 **Project Delivery Team (spawn for project work):**
 
 | Agent | Model | Expertise | When to spawn |
 |-------|-------|-----------|---------------|
+| research-scout | Opus | Literature survey, SOTA, open-source code, experiment plans | Phase 0: before model design begins |
 | data-engineer | Sonnet | Data pipeline, cleaning, EDA, DataLoaders | Phase 1-2: data review and feature engineering |
 | model-builder | Opus | Architecture selection, training, iteration | Phase 3-4: model design and training |
 | oracle-qa | Sonnet | Hard metric evaluation, gating, drift detection | Phase 3-5: after every training iteration |
@@ -41,7 +42,7 @@ You have 16 pre-defined agents available in `.claude/agents/`. You MUST use Clau
 
 ## Dynamic Agent Creation
 
-If a project requires expertise not covered by the 16 pre-defined agents, you MUST create a new agent definition before spawning:
+If a project requires expertise not covered by the 17 pre-defined agents, you MUST create a new agent definition before spawning:
 
 1. **Identify the gap** — what expertise is missing? (e.g., "NLP specialist", "time-series expert", "security auditor")
 2. **Write the agent .md file** to `.claude/agents/{new-agent-name}.md` following the same format:

.claude/commands/commit.md

@@ -36,7 +36,16 @@ You are creating a git commit for the current changes following Zero Operators c
    - What scope is affected? (e.g., `orchestrator`, `memory`, `oracle`, `agents`)
    - What is the concise subject? (imperative mood, lowercase, no period)
 
-5. **Stage relevant files**. Do NOT stage:
+5. **Run documentation validation** to catch doc-codebase drift:
+   ```bash
+   ./scripts/validate-docs.sh
+   ```
+   If any checks fail, fix the inconsistencies before committing. Common cascade fixes:
+   - Agent added → update count in setup.sh, README.md, specs/agents.md, lead-orchestrator.md
+   - Command added → update count in README.md, docs/COMMANDS.md, STATE.md
+   - Version bumped → update pyproject.toml, src/zo/__init__.py, src/zo/cli.py
+
+6. **Stage relevant files**. Do NOT stage:
    - `.env` files
    - Credential files, API keys, tokens
    - Large binary files (unless intentional)
@@ -48,14 +57,14 @@ You are creating a git commit for the current changes following Zero Operators c
    git add {specific files}
    ```
 
-6. **Create the commit** with the conventional format:
+7. **Create the commit** with the conventional format:
    ```
    type(scope): subject
 
    Body explaining what changed and why (if non-obvious).
    ```
 
-7. **Report** to the user:
+8. **Report** to the user:
    - The commit message used
    - Files committed
    - The commit hash

.claude/hooks/cascade-reminder.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Zero Operators — Cascade reminder hook
+# Triggered by PostToolUse on Write|Edit
+# Checks if modified file is a cascade trigger and reminds about updates.
+
+set -uo pipefail
+
+# Read stdin (Claude Code hook JSON)
+INPUT=$(cat)
+
+# Extract the file path from tool_input
+# Write tool: tool_input.file_path
+# Edit tool: tool_input.file_path
+FILE_PATH=$(echo "$INPUT" | grep -oE '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed 's/.*: *"//;s/"//')
+
+# If we couldn't extract a file path, exit silently
+if [[ -z "$FILE_PATH" ]]; then
+    exit 0
+fi
+
+# Check against cascade trigger patterns
+REMINDER=""
+
+case "$FILE_PATH" in
+    *.claude/agents/*)
+        REMINDER="Agent file modified. Cascade check: update setup.sh (EXPECTED_AGENTS + count), README.md (badge + roster), specs/agents.md (team counts), lead-orchestrator.md (agent count + roster), plans/zero-operators-build.md (counts). Run: ./scripts/validate-docs.sh"
+        ;;
+    *.claude/commands/*)
+        REMINDER="Command file modified. Cascade check: update README.md (command count), docs/COMMANDS.md (add/remove entry), memory/zo-platform/STATE.md (count). Run: ./scripts/validate-docs.sh"
+        ;;
+    */pyproject.toml)
+        REMINDER="pyproject.toml modified. If version changed, also update: src/zo/__init__.py (__version__), src/zo/cli.py (_VERSION). Run: ./scripts/validate-docs.sh"
+        ;;
+    */src/zo/__init__.py)
+        REMINDER="__init__.py modified. If version changed, also update: pyproject.toml (version), src/zo/cli.py (_VERSION). Run: ./scripts/validate-docs.sh"
+        ;;
+    */src/zo/cli.py)
+        REMINDER="cli.py modified. If version or commands changed, also update: pyproject.toml (version), src/zo/__init__.py (__version__), README.md, docs/COMMANDS.md. Run: ./scripts/validate-docs.sh"
+        ;;
+esac
+
+if [[ -n "$REMINDER" ]]; then
+    cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PostToolUse",
+    "additionalContext": "${REMINDER}"
+  }
+}
+EOF
+fi
+
+exit 0

.claude/hooks/pre-commit-validate.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# Zero Operators — Pre-commit documentation validation hook
+# Triggered by PreToolUse on Bash(git commit *)
+# Reads Claude Code hook JSON from stdin, runs validate-docs.sh,
+# blocks commit if validation fails.
+
+set -uo pipefail
+
+# Find repo root relative to this hook
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$HOOK_DIR/../.." && pwd)"
+VALIDATE_SCRIPT="$REPO_ROOT/scripts/validate-docs.sh"
+
+# If validation script doesn't exist, allow commit (graceful degradation)
+if [[ ! -x "$VALIDATE_SCRIPT" ]]; then
+    exit 0
+fi
+
+# Run validation, capture output
+VALIDATION_OUTPUT=$("$VALIDATE_SCRIPT" 2>&1)
+VALIDATION_EXIT=$?
+
+if [[ $VALIDATION_EXIT -ne 0 ]]; then
+    # Validation failed — block the commit
+    # Strip ANSI color codes for clean JSON
+    CLEAN_OUTPUT=$(echo "$VALIDATION_OUTPUT" | sed 's/\x1b\[[0-9;]*m//g')
+
+    cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "Documentation consistency check failed. Fix the issues below before committing:\n\n${CLEAN_OUTPUT//
+/\\n}"
+  }
+}
+EOF
+    exit 0
+fi
+
+# Validation passed — allow silently
+exit 0

.claude/hooks/stop-check.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Zero Operators — Stop hook (fires after each Claude turn)
+# Checks if uncommitted changes exist in cascade-trigger files
+# and reminds about running validation before session ends.
+
+set -uo pipefail
+
+# Find repo root
+HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$HOOK_DIR/../.." && pwd)"
+cd "$REPO_ROOT" || exit 0
+
+# Check for uncommitted changes in cascade-trigger paths
+TRIGGER_PATHS=(
+    ".claude/agents/"
+    ".claude/commands/"
+    "pyproject.toml"
+    "src/zo/__init__.py"
+    "src/zo/cli.py"
+)
+
+DIRTY_TRIGGERS=""
+for path in "${TRIGGER_PATHS[@]}"; do
+    if git diff --name-only HEAD -- "$path" 2>/dev/null | grep -q .; then
+        DIRTY_TRIGGERS="$DIRTY_TRIGGERS $path"
+    fi
+    if git diff --name-only -- "$path" 2>/dev/null | grep -q .; then
+        DIRTY_TRIGGERS="$DIRTY_TRIGGERS $path"
+    fi
+done
+
+# Also check for untracked agent/command files
+UNTRACKED=$(git ls-files --others --exclude-standard .claude/agents/ .claude/commands/ 2>/dev/null)
+if [[ -n "$UNTRACKED" ]]; then
+    DIRTY_TRIGGERS="$DIRTY_TRIGGERS (untracked: $UNTRACKED)"
+fi
+
+if [[ -n "$DIRTY_TRIGGERS" ]]; then
+    cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "Stop",
+    "additionalContext": "Uncommitted changes detected in cascade-trigger files:${DIRTY_TRIGGERS}. Before committing or ending the session, run: ./scripts/validate-docs.sh and update all cascade files per CLAUDE.md protocol."
+  }
+}
+EOF
+fi
+
+exit 0

.claude/settings.json

@@ -33,6 +33,46 @@
       "Bash(git push --force *)"
     ]
   },
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(git commit *)",
+            "command": ".claude/hooks/pre-commit-validate.sh",
+            "timeout": 30,
+            "statusMessage": "Validating documentation consistency..."
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/cascade-reminder.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/stop-check.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  },
   "thinking": {
     "enabled": true
   }

CLAUDE.md

@@ -71,10 +71,31 @@ Before creating ANY git commit, Claude MUST:
 1. **Update `memory/zo-platform/STATE.md`** — reflect current phase, completed items, known issues, what's next
 2. **Append to `memory/zo-platform/DECISION_LOG.md`** — every architectural decision, gate passage, or scope change made in this session
 3. **Update `memory/zo-platform/PRIORS.md`** — if any failure, error, or unexpected behaviour occurred, add a new prior with: failure description, root cause category, rules learned, verified solution
-4. **Cascade doc updates** — if the change affects the public interface:
-   - Agent added/removed → update `README.md` badge + roster, `specs/agents.md` counts
-   - Command added/removed → update `README.md`, `PRD.md`, `CLAUDE.md` operating modes
-   - Version changed → update `README.md` badges + footer
+4. **Cascade doc updates** — if the change affects the public interface, update ALL files in the cascade chain. Run `scripts/validate-docs.sh` to verify.
+
+   **Agent added/removed** (trigger: any change to `.claude/agents/`):
+   - `setup.sh` → update EXPECTED_AGENTS array AND hardcoded count
+   - `README.md` → update agents badge count AND agent roster table
+   - `specs/agents.md` → update team counts in Team Philosophy AND add/remove agent entry
+   - `.claude/agents/lead-orchestrator.md` → update agent count in "Agent Roster" section AND roster table
+   - `plans/zero-operators-build.md` → update agent count references
+   - `PRD.md` → update acceptance criteria counts
+
+   **Command added/removed** (trigger: any change to `.claude/commands/`):
+   - `README.md` → update slash command count
+   - `docs/COMMANDS.md` → add/remove command entry
+   - `memory/zo-platform/STATE.md` → update command count
+
+   **Version changed** (trigger: change to `pyproject.toml` version):
+   - `src/zo/__init__.py` → update `__version__`
+   - `src/zo/cli.py` → update `_VERSION`
+   - `README.md` → update version badge
+
+   **Model tier changed** (trigger: change to agent `model:` frontmatter):
+   - `specs/agents.md` → update "Model tier" line for that agent
+   - `README.md` → update agent roster table
+
+   A PreToolUse hook enforces this: `git commit` is blocked if `scripts/validate-docs.sh` fails.
 
 ### On Session End
 

PRD.md

@@ -243,7 +243,7 @@ The orchestrator selects the appropriate mode based on `plan.md`:
 
 ### In Scope
 
-- Autonomous project delivery team (6 launch agents defined and active)
+- Autonomous project delivery team (7 launch agents defined and active)
 - Three workflow modes (classical ML, deep learning, research) with full DL pipeline
 - Memory layer (STATE.md, DECISION_LOG.md, PRIORS.md, semantic indexing)
 - Oracle framework (hard metrics, tiered success criteria, statistical significance, validation gating)
@@ -300,7 +300,7 @@ The first project (defined in its own `plan.md`) is the validation vehicle for t
 - [ ] DECISION_LOG provides complete audit trail: every agent action, every oracle result, every human approval logged.
 - [ ] Session recovery works: interrupt mid-project, restore from STATE.md, resume with zero data loss.
 - [ ] Self-evolving mechanism triggered at least once: an error occurred, root cause was identified, a rule in PRIORS.md or a spec was updated, and the updated rule prevented recurrence.
-- [ ] All 10 project delivery agent definitions written to `.claude/agents/` (6 launch + 4 phase-in).
+- [ ] All 11 project delivery agent definitions written to `.claude/agents/` (7 launch + 4 phase-in).
 - [ ] All 6 platform build agent definitions written to `.claude/agents/`.
 - [ ] Plan.md edit during execution succeeds: replan is computed, human approves, execution resumes with new objectives integrated.
 

README.md

@@ -15,7 +15,7 @@
 <br/>
 
 [![Status](https://img.shields.io/badge/status-validated-F0C040?style=flat-square&labelColor=080808)](#status)
-[![Tests](https://img.shields.io/badge/tests-295_passing-F0C040?style=flat-square&labelColor=080808)](#status)
+[![Tests](https://img.shields.io/badge/tests-298_passing-F0C040?style=flat-square&labelColor=080808)](#status)
 [![Agents](https://img.shields.io/badge/agents-17_defined-F0C040?style=flat-square&labelColor=080808)](#agent-teams)
 [![E2E](https://img.shields.io/badge/MNIST-99%25_accuracy-F0C040?style=flat-square&labelColor=080808)](#e2e-validation)
 
@@ -306,7 +306,7 @@ Adds **Phase 0: Literature Review** (prior art survey, baseline definition). Pha
 
 ## Agent Teams
 
-**Project Delivery Team** — 10 agents that execute ML/research projects:
+**Project Delivery Team** — 11 agents that execute ML/research projects:
 
 | Agent | Model | When Active | What They Do |
 |-------|-------|-------------|-------------|
@@ -366,8 +366,8 @@ zero-operators/
 ├── memory/                     # Per-project state (STATE.md, DECISION_LOG, PRIORS)
 ├── logs/                       # JSONL audit trails
 ├── targets/                    # Delivery repo configuration
-├── tests/                      # 296 tests (unit + integration)
-├── setup.sh                    # Environment validation (11 checks)
+├── tests/                      # 298 tests (unit + integration)
+├── setup.sh                    # Environment validation (10 checks)
 └── pyproject.toml              # Python package config
 ```
 
@@ -418,7 +418,7 @@ mnist-delivery/          ← delivery repo (clean)
 | 5 | E2E validation (MNIST: 99% accuracy) | Done |
 | 1.0.1 | Interactive tmux, brand panel, smart build, Research Scout, self-evolution | Done |
 
-295 platform tests. ruff clean. 17 agents. 24 slash commands.
+298 platform tests. ruff clean. 17 agents. 24 slash commands.
 
 ---