@matt82198/aesop 0.1.0-beta.5 → 0.1.0

package/docs/README.md

@@ -1,44 +1,193 @@
-# Aesop Documentation Index
+# Aesop Documentation
 
-Aesop is a fable-fleet orchestration harness for Claude Code. It runs fast, cheap delivery waves: parallel Haiku agents, lower cost via Haiku-first dispatch and faster wall-clock via parallel agents.
+Aesop is a fable-fleet orchestration harness for Claude Code. It runs fast, cheap delivery waves: parallel Haiku agents, durable state, observable machinery, security gates.
 
-**New to Aesop?** Start here: [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) — a walkthrough of one wave cycle and why it's productive.
+---
+
+## Adopter Journey (Start Here)
+
+If you're new to Aesop, follow this 4-stage path:
+
+### Stage 1: Install
+**[INSTALL.md](INSTALL.md)** — Prerequisites, `npx` scaffold, what gets created
+
+- System requirements (Claude Code CLI, Git, Bash, Node.js, Python)
+- Quick-start: `npx @matt82198/aesop@beta my-fleet`
+- Manual setup for development (git clone)
+- Pre-push hook installation
+
+### Stage 2: Configure
+**[CONFIGURE.md](CONFIGURE.md)** — aesop.config.json, repos, ports, brain root
+
+- Field reference (`aesopRoot`, `braindRoot`, `repos`, `dashboardPort`, `dashboardOrigin`)
+- Example configurations (single repo, microservices, Windows paths)
+- Security notes (git-ignore config, no secrets in config)
+- Environment variables
 
-For deeper governance + operational rules, see the reference docs below.
+### Stage 3: First Wave
+**[FIRST-WAVE.md](FIRST-WAVE.md)** — Run `/power` then `/buildsystem` end-to-end
+
+- What to expect from each phase (rank → dispatch → verify → close)
+- Monitoring (dashboard, TUI, logs)
+- When agents hang (watchdog protocol, retry cap)
+- Common Q&A (wave duration, cost, cancellation, failure handling)
+
+### Stage 4: Concepts
+**[CONCEPTS.md](CONCEPTS.md)** — Dispatch model, cost, state, security, governance
+
+- The wave cycle at a glance
+- Dispatch model (Haiku-first subagents, cost model, patterns)
+- State & checkpointing (STATE.md, BUILDLOG.md, durable recovery)
+- Security gates (secret-scan, branch discipline)
+- Governance (single-writer files, heartbeat protocol)
+- Reliability core (inputs always produce outputs, pride bar)
+- Links to all deep-dive reference docs
 
 ---
 
-## Quick Start
+## System Architecture
 
-- [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) — Concrete walkthrough of one `/buildsystem` wave (rank → fan out → verify → merge → close)
+**[ARCHITECTURE.md](ARCHITECTURE.md)** — Visual flow diagram + component overview
+
+- Mermaid diagram: orchestrator → parallel fleet → merge train → checkpoint → audit → next backlog
+- Component breakdown (watchdog, monitor, dashboard, durable state)
+- Cost model and scaling characteristics
+- Security model (pre-push hook + GitHub branch protection)
+
+---
 
-## Core Governance & Rules (Reference)
+## Deep-Dive Reference Docs
 
-- [CARDINAL-RULES.md](CARDINAL-RULES.md) — Foundational operational principles (dispatch model, cost, subagent discipline, retry caps)
-- [RELIABILITY.md](RELIABILITY.md) — Reliability core: never wait, inputs always produce outputs, pride bar for completion
-- [CHECKPOINTING.md](CHECKPOINTING.md) — Durable STATE.md/BUILDLOG.md lifecycle, recovery on resume, log rotation patterns
-- [SCRIPTS-POLICY.md](SCRIPTS-POLICY.md) — Local-only execution, shared script library, task-local vs. reusable heuristics
-- [DISPATCH-MODEL.md](DISPATCH-MODEL.md) — Fable/Haiku orchestration patterns and cost calculations
-- [GOVERNANCE.md](GOVERNANCE.md) — Single-instance loops, single-writer files, heartbeat protocol, security gates
+Once you've completed the adopter journey, use these for operational reference:
 
-## The Five Pillars
+### Wave Cycle & Orchestration
+- **[HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md)** — Concrete walkthrough of one complete `/buildsystem` wave cycle (rank → fan-out → verify → merge → close)
+
+### Dispatch & Cost
+- **[DISPATCH-MODEL.md](DISPATCH-MODEL.md)** — Haiku-first subagent dispatch, cost analysis, patterns (fan-out, sequential, hierarchical)
+
+### State Management & Recovery
+- **[CHECKPOINTING.md](CHECKPOINTING.md)** — STATE.md and BUILDLOG.md lifecycle, recovery on resume, log rotation patterns
+
+### Foundational Principles
+- **[CARDINAL-RULES.md](CARDINAL-RULES.md)** — 10 foundational principles (dispatch model, cost, subagent discipline, TDD, reliability, orchestrator isolation, orchestrator focus, durable handoff, control files, security & version control)
+
+### Operational Governance
+- **[GOVERNANCE.md](GOVERNANCE.md)** — Single-instance loops, single-writer files, heartbeat protocol, inbox pattern, AUTO/PROPOSE action tiers
+
+### Reliability Guarantees
+- **[RELIABILITY.md](RELIABILITY.md)** — Reliability core (inputs always produce outputs, no silent waits, pride bar for completion), failure scenarios, recovery patterns
+
+### Security & Hooks
+- **[HOOK-INSTALL.md](HOOK-INSTALL.md)** — Install and customize `hooks/pre-push-policy.sh` (branch discipline, secret-scan enforcement at push time)
+
+### Team Onboarding
+- **[MEMORY-TEMPLATE.md](MEMORY-TEMPLATE.md)** — Canonical format for team memory and facts (to be stored in `~/.claude/MEMORY.md`)
+
+### Behavioral Review Checklist
+- **[BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md)** — Checklist for reviewing PRs that modify rules, policies, or orchestration behavior
+
+### Operational Guides
+- **[FORENSICS.md](FORENSICS.md)** — Reconstruct agent failures using `tools/agent-forensics.sh`; make agent behavior git-debuggable
+- **[RESTORE.md](RESTORE.md)** — Reconstitute Aesop & fleet on a new machine from git + watchdog backups
+- **[PUBLISHING.md](PUBLISHING.md)** — Release Aesop to npm using GitHub Actions with OIDC trusted publishing
+- **[av-resilience.md](av-resilience.md)** — Antivirus and behavioral-engine resilience patterns for reliable agent execution
+
+### Lessons & Case Studies
+- **[autonomous-swe.md](autonomous-swe.md)** — The 0.1.0-rc.1 milestone told honestly: what "autonomous SWE" means here (a fleet running the wave loop under a human who owns the outward gates), the committed evidence behind each claim (held-out benchmark, verified audit, proven kill-switch, reproducible package), and the limits the project owns
+- **[case-study-portfolio.md](case-study-portfolio.md)** — How Aesop built its own portfolio site; full audit trail and cost breakdown
+- **[SCRIPTS-POLICY.md](SCRIPTS-POLICY.md)** — Local-only execution, shared script library (`~/scripts`), task-local vs. reusable heuristics
+
+---
 
-### 1. Onboarding Templates
-- [MEMORY-TEMPLATE.md](MEMORY-TEMPLATE.md) — Canonical index format and structure for team memory & facts
+## Quick Index by Use Case
 
-### 2. Policy Hooks
-- [HOOK-INSTALL.md](HOOK-INSTALL.md) — Install and customize `hooks/pre-push-policy.sh` (branch/secret enforcement at push time)
+**I'm setting up Aesop for the first time**
+→ [INSTALL.md](INSTALL.md) → [CONFIGURE.md](CONFIGURE.md) → [FIRST-WAVE.md](FIRST-WAVE.md)
 
-### 3. Behavioral PRs
-- [BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md) — Checklist for reviewing PRs that modify rules, policies, or orchestration behavior
+**I want to understand the cost model**
+→ [DISPATCH-MODEL.md](DISPATCH-MODEL.md) or [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md#why-its-fast--cheap)
 
-### 4. Forensics (Git-Bisectable Agent Debugging)
-- [FORENSICS.md](FORENSICS.md) — Reconstruct agent failures using `tools/agent-forensics.sh`; make agent behavior git-debuggable
+**I want to know what's actually proven vs. claimed (the rc.1 milestone)**
+→ [autonomous-swe.md](autonomous-swe.md)
 
-### 5. Restore (Cross-Machine Reconstitution)
-- [RESTORE.md](RESTORE.md) — Reconstitute Aesop & fleet on a new machine from git + watchdog backups after a wipe
+**I need to understand how state survives a crash**
+→ [CHECKPOINTING.md](CHECKPOINTING.md)
+
+**I'm reviewing a PR that changes orchestration behavior**
+→ [BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md)
+
+**An agent failed and I need to debug it**
+→ [FORENSICS.md](FORENSICS.md)
+
+**I need to set up Aesop on a new machine after a wipe**
+→ [RESTORE.md](RESTORE.md)
+
+**I want to release a new version of Aesop**
+→ [PUBLISHING.md](PUBLISHING.md)
+
+**I'm experiencing reliability issues**
+→ [RELIABILITY.md](RELIABILITY.md) or [GOVERNANCE.md](GOVERNANCE.md)
+
+---
+
+## Architecture Diagram (Quick Reference)
+
+```
+Ranked Backlog
+     ↓
+Orchestrator (main thread)
+     ↓
+Parallel Haiku Fleet (worktrees)
+  [test] [build] [docs] [ui] ...
+     ↓
+Watchdog (heartbeat + respawn)
+     ↓
+Integration Merge Train
+     ↓
+Checkpoint (STATE.md + BUILDLOG.md)
+     ↓
+Closing Audit (findings)
+     ↓
+Monitor + Dashboard (signals)
+     ↓
+Next Backlog (feedback loop)
+```
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for the full diagram and component breakdown.
+
+---
+
+## Quick Answers
+
+**Q: How do I start a wave?**
+A: Type `/power` to prime your orchestrator brain, then `/buildsystem` to start a wave cycle. See [FIRST-WAVE.md](FIRST-WAVE.md).
+
+**Q: How much does a wave cost?**
+A: ~$0.03–$0.05 USD (1 Opus orchestrator + 5–8 Haiku agents). See [DISPATCH-MODEL.md](DISPATCH-MODEL.md).
+
+**Q: What if an agent hangs?**
+A: The watchdog detects it (>200s idle), respawns automatically (up to 3 retries), then surfaces to you if still stuck. See [CARDINAL-RULES.md](CARDINAL-RULES.md).
+
+**Q: How do I add my repos?**
+A: Edit `aesop.config.json` and add paths to `repos` array. See [CONFIGURE.md](CONFIGURE.md).
+
+**Q: Do agents work in the primary tree?**
+A: No. Each agent works in its own sibling worktree (via `git worktree add`). See [ARCHITECTURE.md](ARCHITECTURE.md).
+
+**Q: How do I set up secret-scan?**
+A: The pre-push hook is auto-installed. Customize `tools/secret_scan.py` with your rules. See [HOOK-INSTALL.md](HOOK-INSTALL.md).
+
+---
+
+## Contributing
+
+Aesop is **source-available** under the PolyForm Strict License 1.0.0, which doesn't permit modification or redistribution — so outside code patches can't be merged as contributions. **Issues, bug reports, and discussion are warmly welcome**, and are the best way to help. The repo develops itself via its own `/buildsystem` loop; code changes are made by the maintainer at their discretion, or by prior arrangement.
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for details and [CARDINAL-RULES.md](CARDINAL-RULES.md) for core principles.
+
+---
 
-## Operational Guides
+## License
 
-- [PUBLISHING.md](PUBLISHING.md) — Release Aesop to npm using GitHub Actions with OIDC trusted publishing
-- [av-resilience.md](av-resilience.md) — Antivirus & behavioral-engine resilience patterns for reliable agent execution
+**Source-available** under the [PolyForm Strict License 1.0.0](../LICENSE). Use is permitted for a permitted purpose; **modification and redistribution are not**. See [`LICENSE`](../LICENSE) for full terms.

package/docs/autonomous-swe.md

@@ -0,0 +1,149 @@
+# It shipped itself: the 0.1.0-rc.1 milestone, told honestly
+
+Aesop reached its first release candidate — `0.1.0-rc.1` — by running its own
+`/buildsystem` wave loop across the backlog that produced it: rank work, fan out
+parallel Haiku workers on file-disjoint domains, watchdog them, verify merges,
+close with an audit that seeds the next wave. This document is the honest account
+of what that milestone is and is not. Aesop's entire premise is candor, so the
+caveats here are load-bearing, not fine print.
+
+## What "autonomous SWE" means here
+
+It means something specific and narrow:
+
+> The **fleet** autonomously runs the wave loop — audit → parallel build → verify →
+> merge-train — under a **human** who sets the goals and owns the outward gates.
+
+Concretely:
+
+- **The fleet drives the loop.** Ranking, dispatch, worktree isolation, verification,
+  and the merge train run without a human hand-writing the code in each domain.
+- **A human owns the outward gates.** npm publishes, tagged releases, and git history
+  rewrites are all human-approved. The fleet proposes; a person disposes at the
+  repo boundary.
+- **The dispatch core is out-of-repo.** The actual model calls happen inside the
+  Claude Code harness, which is *not* part of this repository. What Aesop ships is
+  the machinery *around* that core — orchestration rules, guardrails, durable state,
+  the dashboard, and tooling.
+
+What it is **not**: it is not an unsupervised agent, not a hosted control plane, and
+not AGI. Calling it "autonomous SWE" is accurate only with those boundaries stated.
+Drop them and the phrase becomes hype.
+
+## The evidence, and the honest limit on each
+
+The milestone's real differentiator is not that an AI wrote code — plenty of tools do
+that. It is that the credibility and safety claims ship with **committed artifacts a
+skeptical reader can check**, each paired with the limit the project already owns.
+
+### 1. Haiku is good enough for the judgment work a fleet does
+
+The harness's whole cost model depends on cheap Haiku workers being adequate for
+subagent judgment, not just extraction. That was long asserted from the fleet grading
+its own output — agents vouching for agents, recorded in a private memory file. Not
+evidence an outsider can check.
+
+`bench/` plus `tools/bench_runner.py` replace that with a **held-out benchmark scored
+by plain Python string/regex matching — no model, no agent in the grading loop**.
+Across a combined **39 judgment tasks** (spanning bug-in-diff, finding-inflation,
+acceptance-criteria coverage, severity calibration, root-cause-from-trace,
+refactor-equivalence, and security-spotting):
+
+| Model  | Score | Cost (per-token) |
+| ------ | ----- | ---------------- |
+| Haiku  | **39/39 (100%)** | ~1/3 of Opus |
+| Sonnet | 39/39 (100%) | — |
+| Opus   | 38/39 (97%)  | baseline |
+
+On the single task any model missed — a severity call — it was *Opus* that erred, not
+Haiku. Full dated runs: [`bench/results/`](../bench/results/).
+
+**Honest limits (the project's own words):**
+
+- **Curated, not sampled.** The tasks were constructed by reasoning about fleet work,
+  not drawn from real fleet transcripts. Selection bias remains.
+- **N=39 is bigger, not statistically large.** Treat this as directional evidence for
+  this workload, not a universal law.
+- **It measures a floor, not the frontier.** The benchmark found *no* task where Opus
+  beats Haiku. So the defensible claim is bounded: *Haiku is sufficient for the
+  judgment shapes measured here*, **not** *Haiku equals Opus at the reasoning
+  frontier*. If tasks exist where Opus's depth is worth 3×, this set hasn't captured
+  them.
+- **Cost is the token-price ratio**, not measured wall-clock latency.
+
+### 2. Audits stop hallucinating findings
+
+An earlier wave (wave-24) exposed a real failure mode: an all-Haiku audit reported
+four P0 issues, **zero of which were real**. The release audit for this RC was run
+with **adversarial verification of every finding** and closed with **0 hallucinated
+issues**.
+
+**Honest limit:** it is an internal audit. No third party has re-run it.
+
+### 3. The kill-switch actually aborts a wave
+
+A halt control is only worth the claim if it's proven. The fleet-wide kill-switch
+([`tools/halt.py`](../tools/halt.py)) is wired into the **live dispatch path** and was
+exercised end-to-end: a single signal **aborted a real wave with zero workers
+spawned**.
+
+**Honest limit:** it is operator-triggered — a manual brake a human pulls, not an
+autonomous safety monitor that trips on its own.
+
+### 4. A cost ceiling brakes runaway spend
+
+A per-wave spend ceiling ([`tools/cost_ceiling.py`](../tools/cost_ceiling.py)) halts
+dispatch when the configured budget is exceeded.
+
+**Honest limit:** it brakes against a **configured** ceiling; it is **not yet tied to
+live token spend**. It's a guardrail you set, not a live meter.
+
+### 5. The package installs and reproduces from a clean clone
+
+The npm tarball is a **~409 kB** package (measured via `npm pack`) that **builds and
+validates from a fresh clone in CI** — the `reproduce` workflow proves the tarball is
+self-contained. The dashboard views shipped this RC (Wave PR Board, Agent Inspector)
+were **browser-proven** with Playwright. Steps to reproduce offline:
+[docs/reproduce.md](./reproduce.md).
+
+**Honest limit:** the offline reproduce job runs the test suites and the benchmark
+*scorer*; it does **not** run real-model benchmark calls or the Playwright browser
+proofs, which need local setup and (for the models) API keys.
+
+## The limits the project owns, in one place
+
+None of these are hidden, because hiding them would betray the one thing the project is
+actually selling — candor:
+
+1. **The benchmark is curated (N=39), not transcript-sampled.** Directional, not
+   definitive; it maps a floor, not the frontier.
+2. **The real dispatch core is out-of-repo.** It runs in the Claude Code harness. This
+   package is the harness around it, not a turnkey autonomous runtime.
+3. **No third party has reproduced any of it yet.** The artifacts are committed so a
+   skeptic can — that is transparency, not a substitute for independent replication.
+4. **The cost ceiling is a brake, not a live meter.** It enforces a configured budget,
+   not measured spend.
+5. **It is local-first.** State lives in git and local files; there is no hosted
+   control plane. Team scale beyond one machine is on the roadmap, not shipped.
+6. **It is a release candidate.** APIs, config, and dashboard contracts may still shift
+   before 0.1.0. Pin the exact version if you need stability.
+
+## Where to check the receipts
+
+- [`bench/results/`](../bench/results/) — dated benchmark runs (v1 extraction, v2 & v3
+  judgment), each with its own honest interpretation and limits.
+- [`bench/README.md`](../bench/README.md) — why the benchmark exists and how the scoring
+  removes agents from the grading loop.
+- [`tools/halt.py`](../tools/halt.py), [`tools/cost_ceiling.py`](../tools/cost_ceiling.py)
+  — the kill-switch and cost-ceiling implementations.
+- [docs/reproduce.md](./reproduce.md) — reproduce the tests and benchmark scorer from a
+  clean clone.
+- [RELEASE-NOTES.md](../RELEASE-NOTES.md#honest-limits) — release-level "Honest limits".
+- [CHANGELOG.md](../CHANGELOG.md) — the full `0.1.0-rc.1` entry.
+
+---
+
+The one-line version: **the fleet built, tested, audited, and benchmarked its way to a
+shippable release candidate, and every claim about that comes with a committed artifact
+and a stated limit.** That combination — self-built *and* honest about the seams — is
+the milestone.

package/docs/reproduce.md

@@ -0,0 +1,121 @@
+# Reproducing Aesop
+
+This document explains how to reproduce the project's claims from a clean checkout.
+
+## Overview
+
+The Aesop project includes:
+1. **Full test suites** (Node.js + Python) that verify core functionality
+2. **An offline benchmark scorer** that proves the benchmark scoring logic works correctly
+
+Both can be reproduced entirely offline, without API keys or external dependencies, from any clean clone of the repository.
+
+## Reproducing from a Clean Clone
+
+### Prerequisites
+
+- **Node.js**: 18 or later
+- **Python**: 3.12 or later
+- **Git**: any recent version
+
+### Steps
+
+1. Clone the repository (no special flags needed):
+   ```bash
+   git clone https://github.com/matt82198/aesop.git
+   cd aesop
+   ```
+
+2. Verify Node.js and Python are installed:
+   ```bash
+   node --version
+   python --version
+   ```
+
+3. Install Node.js dependencies:
+   ```bash
+   npm ci
+   ```
+
+4. Run the full test suite (Python + Node.js):
+   ```bash
+   # Run Node.js tests
+   npm run test:node
+   
+   # Run Python tests
+   python -m unittest discover -s tests
+   ```
+
+5. Run the benchmark scorer offline:
+   ```bash
+   # Run the benchmark unit tests (syntax, ground truth format, etc.)
+   python -m unittest tests.test_bench_runner -v
+   
+   # Run the offline mock benchmark
+   python tools/bench_runner.py --runner mock
+   ```
+
+## What the `.github/workflows/reproduce.yml` Job Does
+
+The `reproduce` workflow in GitHub Actions automates the above steps:
+
+1. **Fresh checkout**: Uses a clean clone (no state reuse from other CI jobs)
+2. **Syntax checks**: Validates all Node.js (.mjs) and shell scripts (.sh)
+3. **Node.js tests**: Runs the full test suite with `npm run test:node`
+4. **Python tests**: Runs the full test suite with `python -m unittest discover`
+5. **Benchmark scorer**: Proves the offline mock benchmark reproduces (no external API calls)
+
+The workflow is triggered:
+- **Manually**: Via GitHub Actions "Run workflow" button (workflow_dispatch)
+- **Weekly**: Every Sunday at 2:00 AM UTC (schedule)
+
+## What Is and Isn't Reproduced
+
+### Reproduced (offline, no API keys needed)
+
+- ✓ All committed test suites (correctness, integration, governance)
+- ✓ The benchmark **scorer logic** (matching, scoring, reporting)
+- ✓ The benchmark **mock runner** (deterministic offline accuracy score)
+- ✓ The committed benchmark files (`bench/tasks.jsonl`, `bench/ground_truth.jsonl`)
+
+### Not Reproduced (requires external APIs)
+
+- ✗ A real multi-model benchmark (calling Claude API, OpenAI, etc.)
+- ✗ The dashboard browser tests (Playwright, requires UI setup)
+- ✗ Performance/timing benchmarks
+- ✗ The full CI job's additional linting and drift checks
+
+The benchmark mock runner always returns the same accuracy score because it uses a hardcoded heuristic (plain string/regex matching), not a real model. This is intentional — the tests prove the *scorer* works correctly, not that any model achieves a specific accuracy.
+
+## Interpreting Results
+
+### Success
+
+```
+YAML is valid
+All Node.js tests pass
+All Python tests pass
+Benchmark reproduction successful
+```
+
+### Failure
+
+If any step fails, the workflow exits with a non-zero exit code and prints the failure details. Common issues:
+
+1. **Node.js test failure**: Check `tests/*.test.mjs` for the specific failing test.
+2. **Python test failure**: Check the error message; most often a missing test fixture or a test isolation bug.
+3. **Benchmark reproduction failure**: Run `python tools/bench_runner.py --runner mock` manually to see the exact error.
+
+## For Project Maintainers
+
+When you add new features or tests:
+
+1. Ensure all tests pass locally: `npm run test:all` (or individually per suite)
+2. The `reproduce` workflow will catch any regressions automatically
+3. If reproduction fails, it indicates the committed test fixtures or scorer are inconsistent
+
+## References
+
+- Test discovery: `python -m unittest discover --help`
+- Benchmark scorer: `python tools/bench_runner.py --help`
+- GitHub Actions workflow syntax: https://docs.github.com/en/actions

package/hooks/CLAUDE.md

@@ -30,6 +30,34 @@ Runs on `git push` via `.git/hooks/pre-push` symlink or copy.
 - See `docs/HOOK-INSTALL.md` for symlink (Linux/macOS/Git Bash) and copy (Windows) methods
 - Test with `bash hooks/pre-push-policy.sh --test` before org distribution
 
+## Hook: pre-commit-waveguard.sh
+
+Prevents accidental commits to the PRIMARY aesop tree during a wave cycle. Runs on `git commit` via `.git/hooks/pre-commit`.
+
+**Purpose**: During orchestrated waves, the orchestrator sets a marker file (`state/.wave-in-flight`) in the PRIMARY tree only. Sibling worktrees do not inherit this marker (separate working trees), so fleet agents commit freely in worktrees while stray commits to the primary tree are rejected.
+
+**Mechanism**:
+1. **Marker Contract**: Orchestrator writes `state/.wave-in-flight` in the PRIMARY tree before dispatching wave work. The marker is git-ignored, so sibling worktrees checked out during the wave do NOT carry it.
+2. **Pre-Commit Check**: Hook resolves the marker relative to the CURRENT working tree via `git rev-parse --show-toplevel` (NOT a hardcoded `$HOME/aesop` — that resolved to the primary tree from every worktree and blocked the whole fleet mid-wave, the wave-24 incident). Primary tree (has marker during a wave) → exit 1 (reject); sibling worktree (no marker) → exit 0 (allow).
+3. **Override**: User or orchestrator may delete `state/.wave-in-flight` to manually allow commits to primary tree.
+
+**Exit Contract**:
+- Exit 0: Marker absent, commit allowed (normal operation)
+- Exit 1: Marker present, commit blocked with clear error message
+
+**Error Message**:
+```
+Error: Wave in flight. Commit from a sibling worktree, or clear <marker_path> to override.
+```
+
+**Installation**:
+- Run `bash hooks/install-waveguard.sh` to idempotently install into `.git/hooks/pre-commit`.
+- If a pre-commit hook already exists, installer backs it up (`.git/hooks/pre-commit.waveguard-backup`) and wraps both (waveguard first, then existing hook if present).
+
+**Idempotency**:
+- Installer checks if hook already calls waveguard; skips if already installed.
+- Safe to re-run multiple times.
+
 ## Hook: hooks/claude/force-model-policy.mjs
 
 Claude Code hook enforcing subagent Haiku dispatch (cost optimization).

package/hooks/install-waveguard.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+main() {
+  local repo_root
+  repo_root=$(git rev-parse --show-toplevel 2>/dev/null)
+  if [ -z "$repo_root" ]; then
+    printf 'Error: Not in a git repository\n' >&2
+    return 1
+  fi
+
+  local hooks_dir="$repo_root/.git/hooks"
+  local waveguard_src="$repo_root/hooks/pre-commit-waveguard.sh"
+  local pre_commit_dest="$hooks_dir/pre-commit"
+  local pre_commit_orig="$hooks_dir/pre-commit.waveguard-backup"
+
+  if [ ! -f "$waveguard_src" ]; then
+    printf 'Error: Source hook not found at %s\n' "$waveguard_src" >&2
+    return 1
+  fi
+
+  mkdir -p "$hooks_dir"
+
+  if [ -f "$pre_commit_dest" ]; then
+    if grep -q 'pre-commit-waveguard' "$pre_commit_dest" 2>/dev/null; then
+      printf 'Info: pre-commit hook already has waveguard; skipping.\n'
+      return 0
+    fi
+
+    cp "$pre_commit_dest" "$pre_commit_orig"
+    printf 'Info: Existing pre-commit hook backed up to %s\n' "$pre_commit_orig"
+  fi
+
+  cat > "$pre_commit_dest" <<'HOOK_WRAPPER'
+#!/usr/bin/env bash
+set -uo pipefail
+
+repo_root=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+if [ -z "$repo_root" ]; then
+  exit 1
+fi
+
+waveguard_hook="$repo_root/hooks/pre-commit-waveguard.sh"
+if [ -f "$waveguard_hook" ]; then
+  bash "$waveguard_hook"
+  waveguard_exit=$?
+  if [ $waveguard_exit -ne 0 ]; then
+    exit $waveguard_exit
+  fi
+fi
+
+backup_hook="$repo_root/.git/hooks/pre-commit.waveguard-backup"
+if [ -f "$backup_hook" ] && [ -x "$backup_hook" ]; then
+  bash "$backup_hook"
+  exit $?
+fi
+
+exit 0
+HOOK_WRAPPER
+
+  chmod +x "$pre_commit_dest"
+  printf 'Info: Installed waveguard pre-commit hook to %s\n' "$pre_commit_dest"
+  return 0
+}
+
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  main "$@"
+fi

package/hooks/pre-commit-waveguard.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -uo pipefail
+
+main() {
+  # Resolve the marker relative to the CURRENT working tree, NOT a hardcoded primary path.
+  # This is load-bearing: the marker (state/.wave-in-flight) is git-ignored, so a sibling
+  # worktree checked out during a wave does NOT carry it — only the PRIMARY tree (where the
+  # orchestrator sets it) does. Checking the current tree's own toplevel means primary-tree
+  # commits are blocked during a wave while legitimate worktree-agent commits pass. A prior
+  # version hardcoded ${AESOP_ROOT:-$HOME/aesop}, which resolved to the primary tree from every
+  # worktree and thus blocked the entire fleet mid-wave (wave-24 incident). Do not reintroduce.
+  local toplevel
+  toplevel=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+  local marker_file="$toplevel/state/.wave-in-flight"
+
+  if [ -f "$marker_file" ]; then
+    printf 'Error: Wave in flight in this tree (%s). Commit from a sibling worktree, or clear the marker to override.\n' "$marker_file" >&2
+    exit 1
+  fi
+
+  exit 0
+}
+
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  main "$@"
+fi