@matt82198/aesop 0.1.0-beta.3 → 0.1.0-beta.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@matt82198/aesop",
-  "version": "0.1.0-beta.3",
-  "description": "Multi-agent orchestration for AI coding agents, designed to survive failure — a plain-file brain, git as the only durable layer, cheap subagent fleets, and guardrails enforced in code.",
+  "version": "0.1.0-beta.4",
+  "description": "Multi-agent orchestration for AI coding agents, designed to survive failure \u00e2\u20ac\u201d a plain-file brain, git as the only durable layer, cheap subagent fleets, and guardrails enforced in code.",
   "bin": {
     "aesop": "bin/cli.js"
   },
@@ -14,7 +14,10 @@
     "tools/",
     "ui/",
     "docs/",
+    "hooks/",
+    "skills/",
     "aesop.config.example.json",
+    "CLAUDE-TEMPLATE.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -45,5 +48,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {}
+  "scripts": {
+    "test": "node --test --test-force-exit --test-timeout=60000 tests/**/*.test.mjs",
+    "test:node": "node --test --test-force-exit --test-timeout=60000 tests/**/*.test.mjs",
+    "test:sh": "bash tests/test_pre_push_policy.sh && bash tests/test-run-watchdog.sh && bash tests/backup-fleet.test.sh && bash tests/test_reconstitute.sh && bash tests/test_reconstitute_fixes.sh && bash tests/test_agent_forensics.sh && bash hooks/pre-push-policy.sh --test && bash tools/reconstitute.sh --test",
+    "test:py": "python -m unittest discover -s tests",
+    "test:all": "npm run test:node && npm run test:sh && npm run test:py"
+  }
 }

package/skills/CLAUDE.md

@@ -0,0 +1,3 @@
+# skills/ — Orchestration and priming skills
+
+- **power/** — /power skill: prime the filesystem brain (load rules, dispatch model, memory, state) and report system health — see power/SKILL.md

package/skills/power/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: power
+description: Prime the "filesystem brain" — load all operating rules, behaviors, the multi-agent dispatch model, memory, and the current project's semantics from disk. Report a compact primed brief with system health and next steps.
+version: 1.0.0
+---
+
+# Power — prime the filesystem brain
+
+Everything that governs how I should behave lives on disk. This skill reads it, internalizes it,
+and reports a compact "primed" summary — **without inflating context** (code is read via subagents
+that return briefs, not dumped raw).
+
+The principle: **all rules can be abstracted to consistent agent behavior.** Rules are files;
+reading them = becoming the agent the files describe.
+
+**Scope: this is a priming skill for aesop orchestration itself** — rules, dispatch model, memory,
+machinery health. Running it does NOT imply any particular project is being worked on. Project
+state loads only when the session is actually resuming that project (step 3); deferred projects
+are rolled up to counts, never item-by-item — and their repos/daemons are left untouched.
+
+## Procedure (run in order)
+
+### 1. Load global rules + dispatch model
+Read these directly (they are small and authoritative):
+- `~/.claude/CLAUDE.md` — the **cardinal rules** (autonomous continuation, dispatch model, 
+  durable checkpointing, build env). These override defaults.
+- Any project-local `CLAUDE.md` in the current working directory and its parents.
+
+Then run the **brain integrity check**: `~/.claude` should be a git repo (if you version it). 
+Check `git -C ~/.claude status --porcelain` and ahead/behind vs origin:
+- Deliberate uncommitted rule/hook/skill/memory changes → commit + push now (gated by 
+  `python <project-root>/tools/secret_scan.py --staged`);
+- **Unexpected** modifications or deletions → report as alert — stop, diff against remote, restore 
+  before continuing (core defense: don't let tooling shadow your rules).
+
+Also check for unactioned entries in `~/.claude/PROPOSALS.md` or similar and surface a 
+one-line summary of each in the primed report.
+
+Internalize the **dispatch model** and apply it for the rest of the session. Document
+the dispatch model's key invariants locally (in your private repo's `CLAUDE.md`, 
+if you version `~/.claude`), for example:
+- **Subagents model** (Haiku vs specialists vs orchestrator tier)
+- **Parallelism defaults** (e.g., fan out 6–8 Haikus per domain)
+- **TDD-first discipline** and checkpointing (STATE.md, BUILDLOG.md)
+- **Observable machinery**: every action logged, every cost tracked
+
+### 2. Load memory
+- Read `~/.claude/memory/MEMORY.md` (the index, or use your configured path).
+- For any memory entry whose one-line hook is relevant to the current task/project, 
+  read that memory file.
+- Treat recalled memories as background context that reflects when they were written — 
+  **verify any file/flag/path they name still exists before relying on it.**
+
+### 3. Load the active project's state
+If working inside (or resuming) a known project, read its durable checkpoint first:
+- Look for a `STATE.md` and `BUILDLOG.md` in the project root or a handoff folder.
+- `STATE.md` is the source of truth for intent, locked decisions, contracts, and **NEXT STEPS**.
+- Re-sync from disk (git log, file state) — never trust stale assumptions.
+
+### 4. Codebase semantics — already-primed vs first-time init
+**First check whether this codebase has been primed before**: does it already carry its scoped
+`.md` layer (a project-root `CLAUDE.md`, domain `CLAUDE.md` units, a `STATE.md`)?
+
+- **Already primed** (has `CLAUDE.md`s and optionally `STATE.md`): do NOT re-investigate the code. 
+  The `.md` layer IS the persisted semantic memory — the project `CLAUDE.md`s are sufficient; 
+  the codebase is simply **ready to work**. Only re-scan a specific domain if its `CLAUDE.md` 
+  is contradicted by on-disk reality (then fix the `.md`, which is the bug).
+- **First time / not primed** (no scoped `.md`s found): run **init-prime** — fan out Haiku 
+  subagents to read the whole codebase (briefs only, never raw dumps) and **autonomously write 
+  the scoped `.md` layer it needs**:
+  - a project-root `CLAUDE.md`: purpose, build/run commands + toolchain, top gotchas
+  - smallest self-contained **domain `CLAUDE.md` units** (minimal, never lossy) — module layout, 
+    key contracts, domain logic, non-obvious invariants
+  - a `STATE.md` checkpoint seed if the work warrants it
+  
+  Commit + push the new `.md`s (secret-scan gated). Every future `/power` on that codebase 
+  then takes the already-primed fast path.
+
+### 5. Report "primed" (compact)
+Output a short brief, not a wall of text:
+
+- **Drain the UI inbox first** (if configured in `aesop.config.json`): run 
+  `python <project-root>/tools/inbox_drain.py pending`. If items exist, surface each under 
+  a **"QUEUED FROM DASHBOARD"** heading as `[ISO-ts] text` one-liners. Mark them processed 
+  (`python <project-root>/tools/inbox_drain.py mark-all`) after actioning.
+- **Health line first**: run `python <project-root>/tools/power_selftest.py` and lead with its 
+  `POWER-SELFTEST:` line (hooks, brain push state, heartbeats, decisions, scanner state).
+  Bullet anything non-OK.
+- **Open decisions**: surface each ACTIVE line of any decisions/proposals file and any 
+  unactioned inbox entries as one-liners (rolled-up counts for deferred items, never item-by-item).
+- **Rules loaded**: dispatch model + any project-specific overrides in one or two lines.
+- **Project**: name, purpose, status, repo, key paths.
+- **Semantics**: the domain model + main flow in a few bullets.
+- **Gotchas**: the verified ones that change how I act.
+- **Next steps**: from `STATE.md`, ready to execute (autonomously, per the dispatch model).
+
+### 6. Project app launch (if applicable)
+After reporting primed, bring the active project's runnable app up in the BACKGROUND if it has one.
+Make it **idempotent**: if the port is already serving a healthy instance, skip the start and 
+just report the URL.
+
+**Pattern** (project adopters fill in their own):
+- Define a `run` skill or script in your project (or use an existing `start`/`run` command).
+- Detect if the service is already healthy (e.g., `curl -s -o /dev/null -w '%{http_code}' http://localhost:PORT/`).
+- If healthy (200), skip startup and just report the URL.
+- If not healthy, start the service in the background via Bash with `run_in_background: true`.
+- Poll readiness WITHOUT blocking sleep: use curl retries or a cheap probe loop.
+- Report the URL + background task ID so it can be stopped on request.
+
+**DO NOT** hardcode personal app paths (e.g., Spring Boot repos, IDEs, personal tools). 
+Instead, document in your project's `CLAUDE.md` how to launch the app, and reference that 
+in your local version of this skill or a project-specific override.
+
+### 6b. Machinery health — orchestration monitor (optional)
+If your project uses an orchestration monitor, spin up a **background Haiku agent** that:
+1. Collects health signals (cheap, deterministic)
+2. Reads only that brief and acts per a charter — AUTO-applies safe refinements and stages 
+   rule/behavior changes to a `PROPOSALS.md` for review
+3. Self-paces via ScheduleWakeup and beats a heartbeat
+
+Skip if `.monitor-heartbeat` is already <300s old. Announce its task id so it can be paused/stopped.
+
+### 7. Standing dev loops (optional; only when actively developing)
+If the session is doing active development (writing/changing code — not just answering questions),
+keep these background loops running continuously. They are the "tail": cheap, persistent, 
+append-only, and never inflate the main context.
+
+**Patterns** (project adopters fill in their own):
+
+1. **Build/status + backup watchdog** (background bash loop) — appends timestamped git/test/build
+   snapshots. For example, if your project has a `daemons/` folder with a `run-watchdog.sh`, 
+   launch that via Bash with `run_in_background: true` and let it beat a heartbeat so you know 
+   it is live. Stop with TaskStop when development pauses.
+
+2. **Memory keeper** (Haiku, background) — as new decisions, contracts, or gotchas emerge, 
+   updates the relevant memory files compactly (one fact per memory; never bloat). Re-invoke 
+   via SendMessage to keep context.
+
+3. **Continuous QA loop** — after each feature reaches a checkpoint: **Haiku reviews → 
+   Haiku bugfixes → Haiku lint/format**, looping until the build is green and review is clean, 
+   with **Opus orchestrator final-catch** before merge. TDD-first: failing tests before code.
+
+4. **Tail-drift alignment** (Haiku, background) — periodically checks in-flight agents' output 
+   against their domain `CLAUDE.md` contract, and realigns anything drifting.
+
+5. **Hung-Haiku watchdog** (orchestrator's main thread, NOT a subagent) — keep watching every 
+   spawned Haiku for stalls. On hang: TaskStop it and relaunch from checkpoint or respawn.
+
+Launch any that aren't already running; **stop them with TaskStop when development pauses**.
+
+Mechanism: use background `Agent` (run_in_background) for keeper/drift loops, `Monitor` for 
+the watchdog, and self-pace longer cycles with `/loop` skill or `ScheduleWakeup`. 
+Always announce which loops were started (and their task IDs) so they can be paused/stopped.
+
+## Notes
+- If no project context exists yet, steps 1–2 still apply; skip 3–4 and say so.
+- Steps 1–5 always run on `/power`; **step 6 (launch app) runs only if the active project has one**;
+  **step 6b (monitor) runs only if configured**; step 7 (dev loops) runs only during active development.
+- Prefer subagents for anything large; the goal is a *brain*, not a *dump*.
+- After priming, proceed under the dispatch model (continue approved work autonomously; stop only 
+  for genuine decisions or unauthorized outward/destructive actions).

package/tools/CLAUDE.md

@@ -0,0 +1,191 @@
+# tools/ — Build utilities
+
+Local-only Python (stdlib only, no external deps), bash (POSIX, CRLF-safe). Never print secrets — report by pattern name/location only.
+
+## FILES
+
+**Locking & atomicity**:
+- `lock.mjs` — Fail-closed atomic lock acquisition (exponential backoff + stale-lock detection) for PROPOSALS.md and related single-writer operations
+
+**Secret scanning & compliance**:
+- `secret_scan.py` — Pre-push secret/credential detection gate; scans staged, history, or paths by regex + filename patterns
+- `scanner_selftest.py` — Regression harness for secret_scan.py; validates TP/FP vectors and self-scan cleanliness
+- `prepublish_scan.py` — Pre-publish gate running full git history + staged-changes scans; exit 0 only if CLEAR-TO-PUBLISH
+
+**Browser-level verification (CI gates)**:
+- `verify_dash.py` — Browser proof for realtime SSE dashboard; validates console errors, backlog rendering, live SSE updates (use `--allow-skip` in browserless environments)
+- `verify_submit_encoding.py` — Browser proof for /submit UTF-8 inbox bootstrap; validates encoding on Windows and real CSRF flow (use `--allow-skip` in browserless environments)
+
+**CI/merge operations**:
+- `ci_merge_wait.py` — CI-gated merge helper; polls gh pr view until checks conclude (SUCCESS/FAILURE), then merges ONLY if SUCCESS (structurally unreachable otherwise)
+
+**Orchestration infrastructure**:
+- `proposals.mjs` — Proposal lifecycle manager (list/accept/reject); uses fail-closed locking for atomic state updates
+- `power_selftest.py` — Health check harness for /power bootstrap; validates hooks, brain, heartbeats, decisions, and scanner
+- `buildlog.py` — Uniform BUILDLOG.md appender; ensures consistent timestamp + message + git HEAD ref formatting
+- `ensure_state.py` — Scaffold STATE.md and BUILDLOG.md templates in state directory if missing
+- `fleet_ledger.py` — Append-only ledger of agent runs, resource use, and verdicts; supports harvest (scan tasks) and rotate (archive)
+- `heartbeat.py` — Single-instance loop liveness registry; write beats to state/.heartbeats/<name>, check staleness across fleet
+- `stall_check.py` — Automated silent-hang detector; scans agent transcript mtimes to identify stalled agents, feeds watchdog monitoring
+- `inbox_drain.py` — Drain UI inbox submissions; tracks processed dashboard work items (queue while no session running)
+- `orchestrator_status.py` — Atomic writer for state/orchestrator-status.json (set/clear activity+phase); feeds the dashboard status panel
+
+**Repository operations**:
+- `reconstitute.sh` — Clone or fetch repos from config (tab/space-delimited); validates clone targets against fleet-root (physical paths, security)
+- `eod_sweep.py` — End-of-day safety check; scans repos for dirty trees, unpushed commits, untracked files; optional auto-push
+
+**Utilities**:
+- `agent-forensics.sh` — Incident forensics / behavior reconstruction; read-only git plumbing to snapshot or diff behavior-controlling files
+- `launch_tui.py` — Spawn bash TUI script in detached terminal; finds terminal (Git Bash → Windows Terminal), idempotent via pidfile
+- `rotate_logs.py` — Log rotation utility; archives oldest lines when file exceeds size/line thresholds; ensures no data loss
+
+## secret_scan.py — Pre-push secret/credential detection gate
+
+Scans staged/history/paths for secrets by regex pattern and credential filenames; blocks pushes on findings.
+
+- `secret_scan.py --staged [--repo PATH]` — scan git staged files
+- `secret_scan.py --history [--repo PATH]` — scan all git history blobs
+- `secret_scan.py PATH [PATH...]` — scan files/dirs directly (recurse)
+
+Exit: 0=clean, 1=findings, 2=usage error. Output masks secrets as `xxxx...`.
+
+**Pragma escape** (pattern findings only; credential filenames always fatal):
+```
+# secretscan: allow-pattern-docs
+```
+Mark file's first 10 lines to report rule-based findings as ALLOWED-DOC (non-fatal). Use only for deliberate pattern documentation.
+
+## agent-forensics.sh — Incident forensics / behavior reconstruction
+
+Read-only git plumbing; reconstructs agent behavior snapshot or diffs behavior-controlling files.
+
+- `bash tools/agent-forensics.sh <commit>` — print commit header, rules snapshot, CLAUDE.md, STATE.md, last 30 lines of BUILDLOG.md
+- `bash tools/agent-forensics.sh --diff <commitA> <commitB>` — diff CLAUDE.md, STATE.md, docs/, monitor/CHARTER.md, hooks/ between commits
+
+Exit: 0=success, 1=error (never raw git traces). Requires: git, head, tail, wc, grep.
+
+## launch_tui.py — Spawn bash TUI script in detached terminal
+
+Finds terminal (prefer Git Bash → Windows Terminal wt.exe), spawns script detached, idempotent via pidfile.
+
+- `python launch_tui.py --script <path> [--title <title>] [--pidfile <path>]`
+
+Exit: 0=success, 1=error. Output: exactly one line (`spawned (pid N)` or `already running (pid N)` or ERROR).
+
+## power_selftest.py — Health check harness for /power bootstrap
+
+Validates hooks (settings.json), brain (git status), heartbeats (state/ beat files), decisions/inbox counts, and secret scanner.
+
+- `python power_selftest.py` — run all checks and print summary line + bullets for non-OK items
+
+Configuration via `aesop.config.json` or env vars: `BRAIN_ROOT`, `AESOP_STATE_ROOT`, `SCRIPTS_ROOT`.
+Gracefully degrades when targets don't exist (reports `n/a` instead of crashing).
+
+Exit: 0=OK/DEGRADED, 1=FAIL. Output: `POWER-SELFTEST: OK|DEGRADED|FAIL — <checks>` + optional bullets.
+
+## inbox_drain.py — Drain UI inbox submissions
+
+Tracks processed dashboard submissions (work items queued while no session was running).
+
+- `python inbox_drain.py pending` — list unprocessed inbox items
+- `python inbox_drain.py mark <ISO-ts>` — mark one item processed
+- `python inbox_drain.py mark-all` — mark all pending items processed
+
+Configuration via `aesop.config.json` or env vars: `AESOP_INBOX_PATH`, `AESOP_INBOX_SEEN_PATH`, `AESOP_STATE_ROOT`.
+Gracefully handles missing inbox/seen files (no crash).
+
+Exit: 0 always. Output: `pending` lists items one per line; `mark`/`mark-all` prints summary to stderr.
+
+## heartbeat.py — Single-instance loop liveness registry
+
+Fleet-wide heartbeat tracking for monitoring loop freshness. Write heartbeat "beat" to registry, check all beats for staleness.
+
+- `heartbeat.py beat <name> [status] [--state-dir DIR] [--brain]` — write epoch to state/.heartbeats/<name> (or ~/.claude/.heartbeats with --brain)
+- `heartbeat.py check [--max-age SEC] [--state-dir DIR]` — check all beats, exit 0 if all alive
+
+## stall_check.py — Automated silent-hang detector for agent transcripts
+
+Scans agent transcript files (agent-*.jsonl) by mtime to detect stalled/silent-hanging agents.
+
+- `stall_check.py [--transcripts-root DIR] [--threshold-seconds SEC] [--json] [--exit-nonzero-on-stall]`
+
+Options:
+- `--transcripts-root DIR` — Root directory to scan; defaults to AESOP_TRANSCRIPTS_ROOT env var or ~/.claude/projects
+- `--threshold-seconds SEC` — Max age (seconds) for a "fresh" transcript (default: 600); transcripts older are flagged as stalled
+- `--json` — Output as JSON list of {agent_id, age_seconds, stalled, last_mtime} instead of human table
+- `--exit-nonzero-on-stall` — Exit 1 if any agent is stalled (for CI/monitor integration); default always exits 0
+
+Exit: 0 always (or 1 if --exit-nonzero-on-stall + stalls found). Output: human table or JSON; reports "no transcripts found" gracefully.
+
+## buildlog.py — Uniform BUILDLOG entry appender
+
+Ensures consistent BUILDLOG.md formatting across orchestrated work: timestamp + message + optional git HEAD ref.
+
+- `buildlog.py "<message>" [--state-dir DIR] [--head] [--repo-path PATH]` — append entry to state/BUILDLOG.md
+
+## ensure_state.py — Scaffold checkpointing directories
+
+Creates STATE.md and BUILDLOG.md templates in state directory if missing.
+
+- `ensure_state.py --state-dir DIR` — scaffold templates
+
+## fleet_ledger.py — Outcome audit trail for dispatched agents
+
+Append-only ledger of agent runs, resource use, and verdicts. Supports harvest (scan temp tasks) and rotate (archive old lines).
+
+- `fleet_ledger.py append <ts> <agent_type> <model> <dur_sec> <tokens_in> <tokens_out> [verdict]`
+- `fleet_ledger.py harvest` — scan session tasks and append missing outcomes
+- `fleet_ledger.py rotate` — archive old lines when ledger exceeds ~200 lines
+
+## scanner_selftest.py — Regression harness for secret_scan.py
+
+Validates scanner against TP/FP test vectors. Ensures self-scan is clean (no pragma reliance).
+
+- `python scanner_selftest.py [--temp-dir DIR]` — run full test suite, exit 0 only if all pass
+
+## prepublish_scan.py — Pre-publish gate (history + staged)
+
+Runs full git history and staged-changes scans before public release. Both must pass.
+
+- `prepublish_scan.py [--repo PATH]` — scan full history + staged changes, exit 0 only if CLEAR-TO-PUBLISH
+
+## eod_sweep.py — End-of-day repository safety check
+
+Scans listed repos for: dirty working tree, unpushed commits, untracked files. Optional auto-push on safe repos.
+
+- `eod_sweep.py [--repos PATHS] [--readonly-repos PATHS] [--fix-push]` — check repo health, optionally push
+
+## orchestrator_status.py — Atomic orchestrator status updates (wave-8+)
+
+Manages orchestrator heartbeat and activity tracking for SSE status section and wave-9+ multi-orchestrator coordination.
+
+- `python orchestrator_status.py set --activity "dispatching wave-8" --phase audit [--id main --role orchestrator]` — atomically write status
+- `python orchestrator_status.py clear` — remove status file
+
+Writes `state/orchestrator-status.json` atomically (temp+replace). Forward-compatible with bare-object → list normalization in serve.py. Exit: 0=success, 1=error.
+
+## ci_merge_wait.py — CI-gated merge helper
+
+Polls gh pr view until all status checks conclude (SUCCESS/FAILURE), then merges ONLY if all checks pass. The `gh pr merge` call is STRUCTURALLY UNREACHABLE unless CI status is SUCCESS — this prevents merge-on-CI-failure edge cases (e.g., wave-7 PR #80).
+
+- `python ci_merge_wait.py <PR-number> [--timeout SECONDS] [--poll SECONDS] [--merge-method merge|squash|rebase]`
+
+Exit codes:
+- 0 = PR merged successfully
+- 2 = CI checks failed (do NOT merge, prints which check failed)
+- 3 = Timeout waiting for CI to conclude
+- 4 = PR not mergeable or has merge conflicts
+
+Requires: `gh` CLI available on PATH. Gracefully exits with error if gh is missing.
+
+Implementation note: This is the reusable form of the orchestrator's merge-gating discipline (buildsystem Phase 1). Core invariant: the merge call is STRUCTURALLY UNREACHABLE on any status other than SUCCESS.
+
+## Invariants
+
+- **Dependency-light**: Python tools must work on base Python 3 (no pip installs).
+- **CRLF-safe shell**: no line continuations in .sh scripts; Git Bash + Linux compatible.
+- **Never print secrets**: mask as pattern name + masked value only.
+- **Config-driven paths**: heartbeat/ledger/logs use AESOP_STATE_ROOT env var (default ./state) or CLI args; no hardcoded personal paths.
+- **Fragment-assembled secrets in tests**: scanner_selftest.py concatenates dummy secrets at runtime so pattern text never appears contiguously (self-scan invariant).
+- **verify_*.py are mandatory CI gates**: verify_dash.py and verify_submit_encoding.py are required pre-push gates; use `--allow-skip` only in truly browserless environments (CI must run both).
+- **lock.mjs is the ONLY lock implementation**: never reimplement locking in proposals.mjs or elsewhere; all proposals/state updates must use fail-closed lock.mjs with exponential backoff + stale-lock breaking.

package/tools/agent-forensics.sh

@@ -0,0 +1,186 @@
+#!/usr/bin/env bash
+# agent-forensics.sh — incident forensics tool
+# Reconstruct agent behavior as of a commit using git plumbing.
+# Usage:
+#   bash tools/agent-forensics.sh <commit>
+#   bash tools/agent-forensics.sh --diff <commitA> <commitB>
+#
+# Prints:
+#   - Commit header (hash, date, subject)
+#   - Rules snapshot (docs/CARDINAL-RULES.md)
+#   - CLAUDE.md (if present)
+#   - STATE.md (if present)
+#   - Last 30 lines of BUILDLOG.md (if tracked)
+#   - For --diff: behavior changes between two commits
+#
+# Exit codes: 0 on success, 1 on error (never raw git stack traces).
+# Requires: git, head, tail, wc, grep
+# CRLF-safe: no line continuations, Git Bash + Linux compatible.
+
+set -e
+
+show_error() {
+  printf 'Error: %s\n' "$1" >&2
+  exit 1
+}
+
+show_usage() {
+  cat <<'EOF'
+Usage:
+  bash tools/agent-forensics.sh <commit>              Forensics at <commit>
+  bash tools/agent-forensics.sh --diff <commitA> <commitB>   Behavior diff
+EOF
+  exit 1
+}
+
+# --- Commit header (hash, date, subject) ---
+print_commit_header() {
+  local commit="$1"
+
+  # Verify commit exists
+  if ! git cat-file -t "$commit" >/dev/null 2>&1; then
+    show_error "unknown commit: $commit"
+  fi
+
+  local hash
+  local date
+  local subject
+
+  hash=$(git rev-parse "$commit" 2>/dev/null || show_error "commit parse failed: $commit")
+  date=$(git log -1 --format=%ai "$commit" 2>/dev/null || show_error "failed to read commit date")
+  subject=$(git log -1 --format=%s "$commit" 2>/dev/null || show_error "failed to read commit subject")
+
+  printf '# Forensics @ %s\n\n' "$hash"
+  printf 'Commit:  %s\n' "$hash"
+  printf 'Date:    %s\n' "$date"
+  printf 'Subject: %s\n\n' "$subject"
+}
+
+# --- Print first ~40 lines of docs/CARDINAL-RULES.md ---
+print_rules() {
+  local commit="$1"
+
+  printf '## Rules (docs/CARDINAL-RULES.md)\n\n'
+
+  if ! git cat-file -e "$commit:docs/CARDINAL-RULES.md" 2>/dev/null; then
+    printf '(file not present at this commit)\n\n'
+    return
+  fi
+
+  git show "$commit:docs/CARDINAL-RULES.md" 2>/dev/null | head -40
+
+  # Check if file was truncated
+  local total_lines
+  total_lines=$(git show "$commit:docs/CARDINAL-RULES.md" 2>/dev/null | wc -l)
+  if [ "$total_lines" -gt 40 ]; then
+    printf '\n[... %d more lines; see git show %s:docs/CARDINAL-RULES.md]\n' "$((total_lines - 40))" "$commit"
+  fi
+  printf '\n\n'
+}
+
+# --- Print CLAUDE.md if present ---
+print_claude_md() {
+  local commit="$1"
+
+  printf '## CLAUDE.md\n\n'
+
+  if ! git cat-file -e "$commit:CLAUDE.md" 2>/dev/null; then
+    printf '(not present at this commit)\n\n'
+    return
+  fi
+
+  git show "$commit:CLAUDE.md" 2>/dev/null
+  printf '\n\n'
+}
+
+# --- Print STATE.md if present ---
+print_state_md() {
+  local commit="$1"
+
+  printf '## STATE.md\n\n'
+
+  if ! git cat-file -e "$commit:STATE.md" 2>/dev/null; then
+    printf '(not present at this commit)\n\n'
+    return
+  fi
+
+  git show "$commit:STATE.md" 2>/dev/null
+  printf '\n\n'
+}
+
+# --- Print last 30 lines of BUILDLOG.md ---
+print_buildlog() {
+  local commit="$1"
+
+  printf '## BUILDLOG.md (last 30 lines)\n\n'
+
+  if ! git cat-file -e "$commit:BUILDLOG.md" 2>/dev/null; then
+    printf '(not tracked at this commit)\n\n'
+    return
+  fi
+
+  git show "$commit:BUILDLOG.md" 2>/dev/null | tail -30
+  printf '\n\n'
+}
+
+# --- Diff behavior between two commits ---
+diff_behavior() {
+  local commitA="$1"
+  local commitB="$2"
+
+  # Verify both commits exist
+  if ! git cat-file -t "$commitA" >/dev/null 2>&1; then
+    show_error "unknown commit: $commitA"
+  fi
+  if ! git cat-file -t "$commitB" >/dev/null 2>&1; then
+    show_error "unknown commit: $commitB"
+  fi
+
+  printf '# Behavior Diff\n\n'
+  printf '%s -> %s\n\n' "$(git rev-parse "$commitA")" "$(git rev-parse "$commitB")"
+
+  # Files that affect behavior: rules, CLAUDE.md, STATE.md, hooks, monitor/CHARTER.md
+  local behavior_files
+  behavior_files="CLAUDE.md STATE.md docs/CARDINAL-RULES.md docs/DISPATCH-MODEL.md docs/GOVERNANCE.md hooks/ monitor/CHARTER.md"
+
+  printf '## Changes in behavior-controlling files\n\n'
+
+  local has_changes=0
+  for file in $behavior_files; do
+    if git diff "$commitA" "$commitB" --name-only -- "$file" 2>/dev/null | grep -q .; then
+      has_changes=1
+      printf '### %s\n\n' "$file"
+      git diff "$commitA" "$commitB" -- "$file" 2>/dev/null | head -100
+      printf '\n'
+    fi
+  done
+
+  if [ "$has_changes" -eq 0 ]; then
+    printf '(no changes in behavior-controlling files)\n\n'
+  fi
+}
+
+# --- Main dispatch ---
+case "${1:-}" in
+  --diff)
+    if [ $# -lt 3 ]; then
+      show_error "--diff requires two commits: --diff <commitA> <commitB>"
+    fi
+    diff_behavior "$2" "$3"
+    ;;
+  --help|-h)
+    show_usage
+    ;;
+  '')
+    show_usage
+    ;;
+  *)
+    print_commit_header "$1"
+    print_rules "$1"
+    print_claude_md "$1"
+    print_state_md "$1"
+    print_buildlog "$1"
+    ;;
+esac
+
+exit 0