@matt82198/aesop 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to Aesop are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2026-07-22 - Waves 28-31
+
+### Added
+- **Non-Claude core proof (release gate 1)**: a Codex-backed worker (gpt-4o-mini via AgentDriver) built, verified, and shipped a full wave increment end to end (PR #325); JSON-schema-capable model gate with `allow_unverified_models` escape.
+- **Wave scheduler + gate-1 kit** (wave-28): dispatch prioritization plus the proof harness used for the multi-model gate.
+- **WriteAPI seam + OCC** (wave-29): mutation-gate write layer with optimistic concurrency control for state updates.
+- **Cost window unification + analytics panel** (wave-30): unified cost-tracking window with dashboard burn-rate and per-model spend views.
+- **Parallel local test battery** (`tools/test_battery.py`): runs the 4-harness union (python/node/shell/ui) concurrently with per-harness logs and enforced timeouts; ~5.4 min vs ~10 min serial, now the standard local gate.
+- **Frontier external-benchmark slice** (wave-31): spend-capped external grading slice for the held-out benchmark.
+- **Stall recovery + preflight backlog flags** (wave-31): recovery heuristics and preflight validation that rejects malformed backlog items before dispatch.
+
+### Fixed
+- **Windows CI green and release-blocking**: `eod_sweep` repo-list split on `:` ate drive letters (silent vacuous SAFE) — now `os.pathsep` with fail-closed missing-repo findings; `stall_check` path containment resolves 8.3 short paths on both sides; per-harness timeout now kills the process tree.
+- **Refinement-loop convergence (release gate 2)**: 4 full audit rounds, ~30 verified defects fixed, ~10 findings refuted on adversarial verification, final round clean.
+- **Test-fixture git-identity isolation**: the pre-push hook self-test wrote `git config user.name` unscoped on every shell-suite run — now scoped inside its fixture; added a writes-only identity-hygiene scanner, self-guarding fixtures, and a README canary in the regression lens.
+
+### Security
+- `secret_scan`: narrow reviewed exemption (`ALLOWED-REDACTION-SOURCE`) for the redaction-regex source fixture — single pattern, single file, always reported, never silent.
+- Pre-push gate runs **main's** scanner so a branch cannot weaken its own gate.
+
 ## [0.2.0] - 2026-07-21
 
 Minor release shipping multi-model orchestration portability and adaptive verification safety.
@@ -17,6 +37,14 @@ Minor release shipping multi-model orchestration portability and adaptive verifi
 - **Cost-ceiling enforcement** (wave-32): Per-wave spend ceiling enforced at dispatch time; blocks work if budget exceeded.
 - **Transcript-sampled benchmark Phase 1** (wave-32): Infrastructure to extract coding tasks from real Claude Code session transcripts, enabling dynamic benchmark growth beyond hand-written examples.
 - **Backend config & role resolution** (wave-32): `backend_config.py` for per-deployment model mappings (worker/setup/verify roles) without orchestrator changes.
+- **Accuracy harness Phase 1** (wave-27): Offline + live benchmark infrastructure; live run measured gpt-4o-mini 32/32 composite on 2026-07-22 (`bench/results/accuracy-live-2026-07-22.json`).
+- **Cost projection tool** (wave-27): Burn-rate tracking with 70/90-percentile alerting for proactive spend monitoring.
+- **StateAPI read facade** (wave-27): ReadAPI layer delegates to existing parsers (tracker snapshot, orchestrator status, heartbeat via `tools/common`, ledger via `tools/fleet_ledger`); read-only, no logic fork.
+- **Cross-repo portability Phase 1** (wave-27): Per-repo aesop.config.json and initialization enables multi-repo orchestration with unified state backend.
+- **aesop reproduce subcommand** (wave-27): Re-run completed wave items end-to-end from transcript (debugging, verification, metrics).
+- **PORTING guide** (wave-27): Comprehensive docs/PORTING.md for adopters integrating Aesop into existing codebases.
+- **Windows CI job** (wave-27): Non-required but validated GitHub Actions workflow for Windows build parity.
+- **Transcript-sampled benchmark N=150** (wave-27): Expanded dynamic benchmark sourced from real Claude Code transcripts; N=150 curated task extracts.
 
 ### Changed
 - **Verification policy transparent** (wave-32): Verification tiers now driven by `AgentDriver.probe_capabilities()` — config-free, capability-driven safety.

package/README.md

@@ -12,159 +12,67 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Strict%201.0.0-orange.svg" alt="License: PolyForm Strict 1.0.0 (source-available)"></a>
 </p>
 
-**Aesop** is a source-available autonomous developer that crawls into any repository and orchestrates intelligent work—**ranking tasks, dispatching parallel Haiku agents, verifying merges, auditing the work, and feeding the next iteration.**
+## What It Does
 
-What makes Aesop different: **durable state persists across multiple instances**, so your whole team uses one coordinated system. The state layer (`state_store/`) runs append-only events in SQLite (concurrent, transactional), rendered to git for checkpoints and hand-offs. Pair with [/power](#use-with-claude-code) (system init) and [/buildsystem](#core-concepts-and-operations) (the wave loop), and Aesop runs your delivery cycle—on any repository, any codebase shape, indefinitely. **This repo's own PRs are built by Aesop's own loop.** Dogfooding, not doctrine.
+**Aesop** is a source-available orchestration harness that runs multi-agent workflows on any repository. It ranks backlog, dispatches parallel Haiku workers (scoped to disjoint file ownership), verifies merges with adversarial safety, and feeds learnings into the next wave. Durable state (SQLite + git-rendered checkpoints) survives machine wipes and enables team coordination. This repo's own 223 PRs across 880 commits were delivered by Aesop's own `/buildsystem` wave loop—a supervised loop under a human operator who sets goals and owns outward gates (npm publish, releases, history rewrites). The stack is portable: swappable backends (Claude Code reference, OpenAI-compatible Ollama/OpenRouter, Codex bridge), with auto-tuned verification safety calibrated per backend.
 
-As of **0.1.0**, that loop has carried the project to an installable, tested, audited, and benchmarked stable release—the fleet running the wave loop on its own, under a human who sets goals and owns the outward gates. The claims below are backed by committed artifacts you can check, not adjectives. See [Milestone: it shipped itself](#milestone-it-shipped-itself-010).
-
-**Cost-optimized multi-agent dispatch** (Haiku-first subagents, lean orchestrator) · **Durable state** (SQLite events + git exports, survives wipes) · **Observable machinery** (every agent run logged, every cost tracked) · **Live dashboard** (real-time fleet health at http://localhost:8770) · **Security gates** (secret-scan blocks pushes, CI validates each merge).
-
-## Milestone: it shipped itself (0.1.0)
-
-Aesop reached its first release candidate by running its own wave loop—**audit → parallel build → verify → merge-train**—across the backlog that produced it. This is the version where the load-bearing claims stopped being illustrations and became measurements. The word "autonomous" has a precise, deliberately narrow meaning here.
-
-**What "autonomous" means here (and what it doesn't).** The *fleet* autonomously runs the wave loop: it ranks work, dispatches parallel Haiku workers on file-disjoint domains, verifies merges, and feeds the next wave from a closing audit. A *human* sets the goals and owns every outward gate—npm publish, tagged releases, and history rewrites all stay human-approved. It is a supervised loop, not an unsupervised agent, and not AGI. The true model-dispatch core runs inside the Claude Code harness, which lives outside this repo; what ships here is the harness around it—orchestration, guardrails, dashboard, and tooling.
-
-The differentiator is not "an AI wrote code." It's that the credibility and safety claims come with receipts:
-
-| Claim | Evidence (committed, checkable) | Honest caveat |
-| --- | --- | --- |
-| **Haiku is good enough for fleet judgment** | Across 39 held-out judgment tasks, Haiku scored **39/39** vs Opus **38/39** at ~1/3 the per-token cost — measured by a plain-Python scorer with no model in the grading loop. See [`bench/results/`](./bench/results/). | Curated set, **not** sampled from real fleet transcripts (N=39). The benchmark found *no* task where Opus beats Haiku — so it proves sufficiency for these shapes, not parity at the reasoning frontier. |
-| **Audits don't hallucinate findings** | A full release audit was run with adversarial verification of every finding: **0 hallucinated issues**, closing the prior all-Haiku severity-inflation risk. | An internal audit, not a third-party one. |
-| **Kill-switch actually stops the fleet** | The fleet-wide halt is wired into the live dispatch path and proven end-to-end — one signal **aborted a real wave with zero workers spawned**. See [`tools/halt.py`](./tools/halt.py). | Operator-triggered; it is a manual brake, not an autonomous safety monitor. |
-| **A cost ceiling brakes runaway spend** | Dispatch halts when a per-wave budget is exceeded. See [`tools/cost_ceiling.py`](./tools/cost_ceiling.py). | A brake on a *configured* ceiling, **not yet tied to live token spend**. |
-| **The package installs and reproduces** | A **~409 kB** npm tarball (measured via `npm pack`) builds and validates from a fresh clone in CI. See [docs/reproduce.md](./docs/reproduce.md). | UI browser-proofs (Playwright) and real-model runs need local setup / API keys; they don't run in the offline reproduce job. |
-
-**Nobody outside this project has reproduced these results yet.** The evidence is committed so a skeptical reader can check it — that transparency is the point, not a substitute for independent replication. For the full, unhedged account of what is and isn't proven, read [docs/autonomous-swe.md](./docs/autonomous-swe.md) and the ["Honest limits" section of the release notes](./RELEASE-NOTES.md#honest-limits).
-
-## Core Concepts and Operations
-
-### What /power Does
-
-`/power` initializes Aesop into a fresh repository. It:
-- Loads your orchestrator brain (cardinal rules, domain map, team memory, system state)
-- Verifies the system is healthy (filesystem, git, API keys, watchdog)
-- Outputs a health brief and next-step recommendations
-
-Run `/power` at the start of each session when using Claude Code. It's idempotent—safe to run multiple times. Setup once:
+## Feature Demo
 
+**One-turn wave** — Run a complete build cycle (tests, build, docs, review, merge, audit) end-to-end:
 ```bash
-cp -r skills/power/ ~/.claude/skills/power/
+python driver/wave_loop.py --manifest wave.json --one-turn
 ```
+Ranks backlog, dispatches parallel Haiku workers, runs tests, audits the output. Produces a JSON report of all agent runs and their verdicts.
 
-Then in Claude Code, type `/power` to initialize.
-
-### What /buildsystem Does
-
-`/buildsystem` runs **one complete wave cycle** of the autonomous delivery loop. It:
-1. **Ranks** the backlog (priority, dependencies, team affinity)
-2. **Dispatches** parallel Haiku agents on file-disjoint domains (tests, build, docs, UI, review, etc.)
-3. **Verifies** each merge (CI, security scans, audit spot-checks)
-4. **Checkpoints** (STATE.md + BUILDLOG.md committed to git, survive wipes)
-5. **Audits** fleet health and feeds next backlog (monitor signals, signal collectors, findings)
-
-This is **not** a one-off fix or a single pass—it's the repeatable loop that runs your delivery cycle indefinitely, with each wave learning from the prior audit. You can run `/buildsystem` once per wave (typically 30 min–2 hours per wave depending on backlog size and scope).
-
-See [docs/HOW-THE-LOOP-WORKS.md](./docs/HOW-THE-LOOP-WORKS.md) for a concrete walkthrough of one complete cycle.
-
-### Team State & Multi-Instance Vision
-
-**Current Status (0.1.0)**: Single-instance proven. A team uses Aesop by designating one operator who runs the wave loop. State is durably checkpointed in git (STATE.md, BUILDLOG.md, tracker.json exports).
-
-**In Design**: Multi-instance coordination via the state_store substrate. The event-sourced SQLite layer (`state_store/`) is production-ready but currently opt-in. A future release will enable multiple Aesop instances (e.g., per-team subgroups, geographic regions, or specialized fleets) to coordinate around a single source of truth—a Postgres-backed event log, with git as a diffable export. See [docs/TEAM-STATE.md](./docs/TEAM-STATE.md) (design in progress) for the vision and current architecture decisions.
-
-## Why Aesop?
-
-Multi-agent AI fleets hit two walls: all-Opus orchestrators cost $10k+ per wave, and machine crashes lose state—losing work and context on restart. Aesop solves both:
-
-- **Haiku-first dispatch** cuts costs to ~1/3 of Opus (Haiku subagents, Opus orchestrator).
-- **Durable state** (SQLite event log + git-rendered exports) survives machine wipes with zero data loss and enables team/multi-instance coordination.
-- **Portable orchestration** works on any repository; no custom agents per repo needed.
-
-```
-ranked backlog
-     ↓
-parallel haiku fleet (worktree-isolated)
-  [test] [build] [docs] [ui] [review] ...
-     ↓
-integration-branch merge train
-     ↓
-checkpoint (STATE.md + BUILDLOG.md)
-     ↓
-audit + fleet-ops monitoring
-     ↓
-(feeds next wave's backlog)
+**Multi-model drivers** — Choose your backend (Claude Code, Ollama, OpenRouter) with one config line:
+```json
+{ "backend": "openai-compatible", "model": "mistral-small", "base_url": "http://localhost:1234/v1" }
 ```
+Verification tiers auto-adapt to backend capability—weaker models get stronger safety checking without code changes.
 
-(See [assets/wave-cycle-diagram.txt](./assets/wave-cycle-diagram.txt) for the cycle reference.)
-
-## What You Get
-
-- **Parallel Haiku fleets** — Cheap, scoped subagents dispatch in parallel; orchestrator stays lean on main thread.
-- **Durable state** — STATE.md + BUILDLOG.md checkpoints survive machine wipes; re-sync on resume, zero data loss.
-- **Observable & auditable** — Every agent run logged, every cost tracked, every security event triaged.
-- **Self-healing watchdog** — Runs every 150s: backs up work, scans for secrets, detects drift, restores on reboot.
-- **Live web dashboard** — Real-time fleet health, security alerts, work-item kanban at `http://localhost:8770`.
-- **Secret-scan gates** — Pre-push hook blocks leaks; audit trail logged. Pair with GitHub branch protection for enforcement.
-- **Read-only MCP Fleet Server** — Expose fleet status, active agents, work items, and cost metrics to Claude Code (fleet_status, fleet_agents, fleet_tracker, fleet_cost tools). See [mcp/CLAUDE.md](./mcp/CLAUDE.md) for setup.
-- **Multi-model portability** — AgentDriver abstraction decouples the wave loop from Claude Code; drivers for Claude Code, OpenAI-compatible backends (Ollama, OpenRouter), and Codex. Honest verification tiers: weaker backends get more checking. See [driver/README.md](./driver/README.md).
-- **Self-diagnosing npm publish** — OIDC token generation and publish reliability verified on each release; workflow surfaces diagnostics inline.
-- **Verification & quality tooling** — mutation_test.py for test-quality assessment, defect_escape.py for first-try-green telemetry, held-out benchmark for robustness, and adversarial review to break and harden the orchestration loop.
-
-## Get Started (3 steps, 5 min)
-
-**Note:** Aesop's first stable release is `0.1.0`, published to npm under the `latest` tag — a plain `npx @matt82198/aesop` or `npm install @matt82198/aesop` pulls it. Earlier prereleases remain available under the `@rc` and `@beta` tags.
+**Wave templates** — Bootstrap a new fleet with a preset architecture:
+```bash
+python tools/wave_templates.py saas --project-name my-api --base-dir /workspace
+```
+Generates a manifest for typical 3-tier (API, frontend, ops) or data pipelines.
 
-### Quickest path: npx scaffold
+**Live dashboard** — Real-time view of fleet health, security alerts, work-item kanban, cost analytics:
+```bash
+npx @matt82198/aesop dash
+```
+Opens http://localhost:8770. Four views: Overview (agents, events), Work (kanban), Activity (reasoning tail), Cost (spend/tokens).
 
+**Health score** — Readiness assessment: env, git, Python, Node, ports, config, hooks:
 ```bash
-npx @matt82198/aesop my-fleet \
-  --name "my-api" \
-  --repos "/path/to/repo1,/path/to/repo2"
-cd my-fleet
+python tools/health_score.py
+```
+Outputs a scorecard of system readiness; --json for parsing.
 
-# Start the daemon
-bash daemons/run-watchdog.sh --once
+**Self-healing daemon** — Runs every 150s: backs up work, scans secrets, detects drift:
+```bash
+npx @matt82198/aesop watch
+```
+Pre-push hook blocks leaks. Heartbeat signals liveness; monitor auto-detects stalls and restarts the fleet.
 
-# Launch dashboard on localhost:8770
-python ui/serve.py
+**Hardened gate stack** — Fail-closed secret-scan, adversarial review (default-on):
+```bash
+python tools/secret_scan.py --staged   # Blocks push if leak detected
 ```
+Exits with failure on file-read errors (not silently passing). CI validates every merge.
 
-Pre-push hook auto-installed. See [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) for branch protection pairing.
+## Proof Numbers
 
-**State Store**: Aesop uses an event-sourced SQLite WAL backing store (`state_store/`) for durable state persistence. The `tracker.json` file is automatically re-rendered as an export for git-friendly checkpointing. Mutations follow a dual-path model: append new events via the StateAPI, then rendered exports for external consumption.
+Aesop builds itself. These numbers are live from git, verified by anyone who clones.
 
-### Or: git clone for hacking
+## Get Started
 
 ```bash
-git clone https://github.com/matt82198/aesop ~/aesop
-cd ~/aesop
-cp aesop.config.example.json aesop.config.json
-# Edit paths and repos
-
-export AESOP_ROOT=$HOME/aesop
-bash $AESOP_ROOT/daemons/run-watchdog.sh --once
-python ui/serve.py
+npx @matt82198/aesop my-fleet --name "api" --repos "/path/to/repo"
 ```
+→ Copy `skills/` into `~/.claude/skills` to enable the `/power` and `/buildsystem` commands.
+→ See [docs/INSTALL.md](./docs/INSTALL.md) for setup and first `/power` → `/buildsystem` cycle.
+→ See [docs/DEMO.md](./docs/DEMO.md) for a complete walkthrough of one wave.
 
-## How It Works
-
-```
-daemons/run-watchdog.sh         Every 150s: backs up work, scans secrets, detects drift
-  ↓
-orchestrator (via Claude Code)  Reads backlog, dispatches Haiku subagents in parallel
-  ↓
-parallel Haiku fleet            Tiny, scoped domains (tests, build, review, docs, etc.)
-  ↓
-watchdog backs up & gates        Heartbeat, secret-scan, push to backup branch; merging is orchestrator/human-driven
-  ↓
-monitor/collect-signals.mjs     Audits orchestration health, feeds next wave's backlog
-  ↓
-STATE.md + BUILDLOG.md          Git-committed, survives machine wipes
-```
-
-See [docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md) for cost analysis and parallel patterns.
 
 <!-- STATS:START -->
 
@@ -191,137 +99,19 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 
 
-## Recommended Agents
-
-Aesop pairs well with the open-source catalog of ~130 community-authored specialized agent definitions (TDD orchestrators, security reviewers, performance engineers, etc.). For optimal results, install agents from the upstream source and pair them with Aesop's cost-optimized Haiku dispatch. This is optional; Aesop works standalone with general-purpose Claude Code agents.
-
-## Use with Claude Code
-
-If you're using **Claude Code**, invoke `/power` at the start of each session. It loads your orchestrator brain (cardinal rules, domain map, team memory, system state) and outputs a health brief. Setup once:
-
-```bash
-# Copy the /power skill and optional /healthcheck skill
-cp -r skills/power/ ~/.claude/skills/power/
-cp -r skills/healthcheck/ ~/.claude/skills/healthcheck/
-```
-
-Then in Claude Code, type `/power` or `/buildsystem` to start a wave cycle. Use `/healthcheck` to audit fleet machinery health before running waves. See [skills/power/SKILL.md](./skills/power/SKILL.md) and [skills/healthcheck/SKILL.md](./skills/healthcheck/SKILL.md) for details.
-
-## Core Principles
-
-1. **Haiku-first dispatch** — Subagents always cheap; orchestrator stays lean on main thread.
-2. **Durable state** — STATE.md + BUILDLOG.md survive wipes; re-sync on resume.
-3. **Observable** — Every agent run logged, every cost tracked, every security event triaged.
-4. **TDD-first** — Fail tests before implementation; one Haiku per scoped domain.
-5. **Never wait** — Dispatch work in parallel; connect with heartbeats, not polling.
-6. **Push discipline** — feature/* branches only; secret-scan gates every push.
-
-Read [docs/CARDINAL-RULES.md](./docs/CARDINAL-RULES.md) for the full text.
-
-## Requirements
-
-- Claude Code CLI (v0.1+)
-- Git (v2.40+)
-- Bash (v4+) or Git Bash on Windows
-- Node.js (v18+) for dashboard and monitor
-- Python (v3.10+) for log rotation and secret-scan
-- jq (optional) for TUI dashboard
-
-## Scaling Cheaply
-
-The **dispatch model** fans work across parallel Haiku subagents (each 1/3 the cost of Opus). The orchestrator stays lean on the main thread, coordinating via durable STATE.md. Result: ~25% the cost of an all-Opus fleet.
-
-**Action tiers**: AUTO (immediate, logged) for read-only checks and appends; PROPOSE (staged in `monitor/PROPOSALS.md`) for changes requiring approval. See [docs/GOVERNANCE.md](./docs/GOVERNANCE.md).
-
-## Security
-
-The pre-push hook (`hooks/pre-push-policy.sh`) enforces branch discipline and secret scanning locally. It is bypassable (use `--no-verify` to skip), so **pair it with GitHub branch protection** for real enforcement:
-
-```
-Settings > Branches > main
-  ✓ Require pull request reviews
-  ✓ Require status checks to pass
-  ✓ Dismiss stale PR approvals
-  ✓ Restrict pushes to (Admins only)
-```
-
-**Host-header validation** in the dashboard UI handler prevents HTTP header injection attacks; all requests are validated against the configured origin. Private brain (`~/.claude`) is never committed to this repo. Keep `aesop.config.json` git-ignored. Implement `tools/secret_scan.py` with your security rules. See [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) for setup.
-
-## Dashboard (Wave-14 Rewrite)
-
-The dashboard is a **React 18 + Vite + TypeScript** single-page app with four hash-routed views:
-
-### Viewing the Dashboard
-```bash
-python ui/serve.py
-```
-Opens `http://localhost:8770` — live fleet health, security alerts, work-item kanban, cost analytics.
-
-### Architecture
-- **Backend**: Python stdlib HTTP server (`ui/handler.py`) serves the built React app + JSON/SSE APIs (`/api/state`, `/api/cost`, `/events`).
-- **Frontend**: `ui/web/` (React app) is built to `dist/` (committed to git) and served as static files by the Python server.
-- **CSRF protection**: Token injected into `dist/index.html` via sentinel substitution; mutations gated by `/submit` and `/api/tracker` endpoints.
-
-### Development
-```bash
-cd ui/web
-npm install
-npm run dev        # Vite dev server with API proxy to http://localhost:8770
-npm run build      # Build to dist/ (commit the dist/)
-```
-
-The dev server proxies `/data`, `/api`, `/events`, `/agent`, `/submit` to the Python backend on :8770, so the frontend can develop against live APIs.
-
-### Views
-- **Overview**: Fleet agents, security alerts, recent events.
-- **Work** (`#/work`): Tracker kanban (4 lanes: proposed/ranked/in-progress/done), audit backlog progress.
-- **Activity** (`#/activity`): Agent timeline, main-thread message tail (live reasoning).
-- **Cost** (`#/cost`): Per-model spend/tokens, per-day bar chart, verdict scorecard (success/failure rates).
-
-## Extending Aesop
-
-**Custom signal collectors**: Edit `monitor/collect-signals.mjs` to add domain-specific health checks.
-
-**Custom watchdog hooks**: Edit `daemons/backup-fleet.sh` to run linters, integrate with your CI, or customize secret-scan logic.
-
-**Dashboard components**: Add React components in `ui/web/src/components/` or new views in `ui/web/src/views/`. Rebuild and commit `dist/`.
-
-## Troubleshooting
-
-| Issue | Check |
-|-------|-------|
-| Watchdog doesn't start | `state/FLEET-BACKUP.log` for errors; verify `AESOP_ROOT` is set |
-| Dashboard shows "unavailable" | Install Node.js v18+; check `dash-extra.mjs` is in sync |
-| Secret-scan blocks push | Add suppression to `tools/secret_scan.py`; no auto-bypass (by design) |
-| Monitor doesn't start | Verify Node.js on PATH; check `monitor/BRIEF.md` for logs |
-
-## Documentation
-
-**Adopter journey** (start here):
-- [docs/INSTALL.md](./docs/INSTALL.md) — Install Aesop and verify setup
-- [docs/CONFIGURE.md](./docs/CONFIGURE.md) — Configure repos, ports, and brain root
-- [docs/FIRST-WAVE.md](./docs/FIRST-WAVE.md) — Run your first `/power` → `/buildsystem` cycle
-- [docs/CONCEPTS.md](./docs/CONCEPTS.md) — Key concepts (dispatch, state, security, governance) with links to deep dives
-- [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) — System architecture diagram and components
+## Why Haiku-First Works
 
-**Operational reference**:
-- [docs/HOW-THE-LOOP-WORKS.md](./docs/HOW-THE-LOOP-WORKS.md) — Concrete walkthrough of one wave cycle
-- [docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md) — Cost analysis, dispatch patterns, scaling
-- [docs/CHECKPOINTING.md](./docs/CHECKPOINTING.md) — STATE.md + BUILDLOG.md lifecycle, recovery on wipe
-- [docs/CARDINAL-RULES.md](./docs/CARDINAL-RULES.md) — 10 foundational principles
-- [docs/GOVERNANCE.md](./docs/GOVERNANCE.md) — Single-writer files, heartbeat protocol, AUTO/PROPOSE tiers
-- [docs/RELIABILITY.md](./docs/RELIABILITY.md) — Reliability guarantees, pride bar, inputs-always-outputs
-- [docs/HOOK-INSTALL.md](./docs/HOOK-INSTALL.md) — Secret-scan and branch protection setup
+The benchmark proves it: across 39 judgment tasks (code review, severity calibration, root-cause analysis, refactor equivalence, security spots), Haiku scored **39/39** vs Opus **38/39** at ~1/3 the per-token cost. See [`bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md`](./bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md). Honest caveat: curated set (N=39), not real-transcript sampled; the benchmark found no task where Opus beats Haiku, proving sufficiency for this workload, not parity at the reasoning frontier.
 
-**For specific tasks**:
-- [docs/FORENSICS.md](./docs/FORENSICS.md) — Debug agent failures (git-bisectable)
-- [docs/RESTORE.md](./docs/RESTORE.md) — Reconstitute Aesop on a new machine
-- [docs/PUBLISHING.md](./docs/PUBLISHING.md) — Release Aesop to npm
-- [docs/autonomous-swe.md](./docs/autonomous-swe.md) — The 0.1.0-rc.1 milestone told honestly: what "autonomous SWE" means here, the evidence behind each claim, and the limits the project owns
-- [docs/case-study-portfolio.md](./docs/case-study-portfolio.md) — How Aesop built its own portfolio site; full audit trail and cost breakdown
-- [docs/TEAM-STATE.md](./docs/TEAM-STATE.md) — Multi-instance and team coordination via state_store (design in progress)
+## Learn More
 
-See [CHANGELOG.md](./CHANGELOG.md) and [RELEASE-NOTES.md](./RELEASE-NOTES.md) for release notes.
+- **[docs/INSTALL.md](./docs/INSTALL.md)** — Setup and first wave  
+- **[docs/PORTING.md](./docs/PORTING.md)** — Adopter's guide: port Aesop to your repo (prerequisites, scaffold, 10 failure modes)  
+- **[docs/HOW-THE-LOOP-WORKS.md](./docs/HOW-THE-LOOP-WORKS.md)** — Concrete walkthrough of a wave cycle  
+- **[docs/DISPATCH-MODEL.md](./docs/DISPATCH-MODEL.md)** — Cost analysis and scaling  
+- **[docs/CARDINAL-RULES.md](./docs/CARDINAL-RULES.md)** — 10 foundational principles  
+- **[docs/autonomous-swe.md](./docs/autonomous-swe.md)** — What "autonomous" means (and doesn't), evidence for all claims, honest limits  
+- **[RELEASE-NOTES.md](./RELEASE-NOTES.md)** — Version 0.3.0: non-Claude core proof (Codex wave), refinement-loop convergence, Windows-green CI
 
 ## Contributing
 

package/bin/cli.js

@@ -11,8 +11,8 @@ const helpFlag = args.includes('--help') || args.includes('-h');
 const forceFlag = args.includes('--force');
 const yesFlag = args.includes('--yes');
 
-// Check for runtime subcommands (doctor, watch, dash, status, fleet, health-score)
-const runtimeCommands = ['doctor', 'watch', 'dash', 'status', 'fleet', 'health-score'];
+// Check for runtime subcommands (doctor, watch, dash, status, fleet, health-score, reproduce)
+const runtimeCommands = ['doctor', 'watch', 'dash', 'status', 'fleet', 'health-score', 'reproduce'];
 const isRuntimeCommand = runtimeCommands.includes(args[0]);
 
 if (isRuntimeCommand) {
@@ -22,7 +22,8 @@ if (isRuntimeCommand) {
     'dash': '../tools/dash.js',
     'status': '../tools/status.js',
     'fleet': '../tools/fleet.js',
-    'health-score': '../tools/health-score.js'
+    'health-score': '../tools/health-score.js',
+    'reproduce': '../tools/reproduce.js'
   };
   // Load and run the appropriate runtime module
   // These modules run async code that sets process.exitCode and will cause Node to exit
@@ -154,6 +155,7 @@ Usage:
   npx @matt82198/aesop dash
   npx @matt82198/aesop status
   npx @matt82198/aesop fleet
+  npx @matt82198/aesop reproduce
 
 Commands:
   doctor                  Preflight readiness check (Node.js, Python, git, config, dirs, hook, port)
@@ -161,6 +163,7 @@ Commands:
   dash                    Launch the web dashboard (spawns python3 ui/serve.py or python fallback)
   status                  One-shot fleet status snapshot (heartbeats, dashboard port, git branch)
   fleet                   One-shot fleet snapshot (agents, heartbeats, tracker lanes, orchestrator status)
+  reproduce               Offline verification suite (repo: full test suite; installed: self-checks)
   wizard                  Interactive onboarding (prompts for project name, repos, port)
 
 Arguments:
@@ -181,6 +184,7 @@ Examples:
   npx @matt82198/aesop dash                                 # Launch web dashboard (default localhost:8770)
   npx @matt82198/aesop status                               # Show fleet status (heartbeats, port, git)
   npx @matt82198/aesop fleet                                # Show fleet snapshot (JSON agents, heartbeats, tracker, orchestrator)
+  npx @matt82198/aesop reproduce                            # Run offline verification suite (full repo tests or installed checks)
   npx @matt82198/aesop                                      # Creates ./aesop-fleet/ with template
   npx @matt82198/aesop my-fleet                             # Creates ./my-fleet/ with template
   npx @matt82198/aesop wizard                               # Interactive onboarding (60-second setup)

package/docs/HOOK-INSTALL.md

@@ -1,82 +1,41 @@
-# Git Pre-Push Hook Installation Guide
+# Git Pre-Push Hook Setup
 
-**Ship a hook, not a memo.** The pre-push policy hook is **auto-installed during scaffold** (see below). This guide explains customization, verification, and org-wide distribution.
-
-## Security Model: Local Convenience Defense Only
-
-**IMPORTANT**: The pre-push hook is a **local-machine convenience defense** — it is **NOT cryptographic protection**. Any developer can bypass it with `git push --no-verify` or by editing/deleting `.git/hooks/pre-push`. The audit log (`SECURITY-AUDIT.log`) is stored locally and can also be edited by a user with file system access.
-
-**Real enforcement requires server-side branch protection.** See GitHub Configuration below.
+**TL;DR**: The hook is **auto-installed during scaffold**. Real enforcement requires server-side GitHub branch protection.
 
 ## What the Hook Does
 
-`hooks/pre-push-policy.sh` enforces two checks at git push time:
+`hooks/pre-push-policy.sh` enforces:
+1. **Branch Policy** — No direct pushes to `main`/`master` (feature branches only)
+2. **Secret Scan** — `tools/secret_scan.py --staged` blocks credentials
 
-1. **Branch Policy**: Blocks direct pushes to `main` or `master` branches (feature branches only).
-2. **Secret Scan**: Runs `tools/secret_scan.py --staged` to detect credentials before they reach the remote.
+## Security Model
 
-Both blocks append a JSON audit record to `state/SECURITY-AUDIT.log` with timestamp, repo, reason, and user — creating a reviewable trail of policy enforcement.
+**IMPORTANT**: Local hook is a **convenience defense only**—NOT cryptographic protection. Bypass with `git push --no-verify`.
 
-## Auto-Installation During Scaffold
+**Real enforcement**: Pair with GitHub branch protection (server-side). See below.
 
-**Default Behavior:** When you scaffold a new aesop fleet with `npx @matt82198/aesop [target-dir]`, the CLI automatically installs the pre-push hook into `.git/hooks/pre-push`.
+## Auto-Installation
 
-- **On Unix/macOS/Git Bash**: Creates a symlink so hook updates are automatic
-- **On Windows**: Copies the hook directly (symlinks don't work reliably on all NTFS setups)
-- **Idempotent**: Re-running scaffold doesn't clobber a user-customized hook
-- **Preserve Existing**: If you have a different pre-push hook, scaffold warns and preserves it
-- **Force Replace**: Use `npx @matt82198/aesop [target-dir] --force` to replace any existing hook
-
-**Example:**
+Scaffold auto-installs the hook (symlink on Unix, copy on Windows):
 
 ```bash
-# Initial scaffold (creates and installs hook automatically)
-npx @matt82198/aesop my-fleet
-
-# Later: re-scaffold the same directory (preserves customizations)
 npx @matt82198/aesop my-fleet
-
-# Force replace (even if hook was customized)
-npx @matt82198/aesop my-fleet --force
 ```
 
-## Manual Installation
-
-If you're installing into an existing repo (not scaffolded), or you need to manually add the hook:
-
-### Option 1: Symlink (Linux / macOS / Git Bash on Windows)
-
-The cleanest method — hook stays in sync with repo updates:
-
+Manual install:
 ```bash
+# Option 1: Symlink (Unix/macOS/Git Bash)
 ln -s ../../hooks/pre-push-policy.sh .git/hooks/pre-push
-chmod +x .git/hooks/pre-push
-```
-
-### Option 2: Copy (Windows, or to break sync)
-
-Copy the hook directly into `.git/hooks/`:
-
-```powershell
-Copy-Item hooks\pre-push-policy.sh .git\hooks\pre-push
-```
 
-On Windows PowerShell, mark it executable if your git respects file mode:
-
-```bash
-git config core.filemode false
+# Option 2: Copy (Windows)
+cp hooks/pre-push-policy.sh .git/hooks/pre-push
 ```
 
-## Testing
-
-Before committing to org-wide deployment, verify the hook works:
-
+Test:
 ```bash
 bash hooks/pre-push-policy.sh --test
 ```
 
-Expected output: **PASS** for all three checks (branch policy, feature branch allowance, audit log format).
-
 ## GitHub Configuration (Server-Side Enforcement)
 
 To pair this local hook with real enforcement, enable branch protection on GitHub:

package/docs/INSTALL.md

@@ -285,9 +285,10 @@ To bypass during testing: `git push --no-verify` (not recommended for production
 
 ## Next Steps
 
-1. **Read [CONFIGURE.md](CONFIGURE.md)** — Customize repos, ports, and brain root
-2. **Run [FIRST-WAVE.md](FIRST-WAVE.md)** — Test a full `/power` → `/buildsystem` cycle
-3. **Understand [CONCEPTS.md](CONCEPTS.md)** — Learn the dispatch model and state model
+1. **Read [PORTING.md](PORTING.md)** — Step-by-step guide for adopting Aesop on a foreign repo (10 common failure modes)
+2. **Read [CONFIGURE.md](CONFIGURE.md)** — Customize repos, ports, and brain root
+3. **Run [FIRST-WAVE.md](FIRST-WAVE.md)** — Test a full `/power` → `/buildsystem` cycle
+4. **Understand [CONCEPTS.md](CONCEPTS.md)** — Learn the dispatch model and state model
 4. **Explore the dashboard** — `python3 ui/serve.py` then open http://localhost:8770
 
 For troubleshooting, see the [Aesop README](../README.md#troubleshooting) or [GOVERNANCE.md](GOVERNANCE.md) for operational policies.