@matt82198/aesop 0.1.0 → 0.3.1

package/CHANGELOG.md

@@ -5,7 +5,122 @@ 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).
 
-## [Unreleased]
+## [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.
+
+### Added
+- **AgentDriver Phase 1-3 shipping** (wave-32+): Complete multi-model driver abstraction with three production drivers — Claude Code reference adapter, OpenAI-compatible backend (Ollama, OpenRouter, etc.), and Phase 3 wave bridge enabling any backend to drive coding tasks end-to-end with verified-honest verification tiers.
+- **Multi-instance identity & coordination** (wave-32): Instance ID tagging (hostname:pid:nonce) and lease-by-append claims enable multi-writer coordination without collisions (fail-closed). Foundation for team-scale Aesop.
+- **Honest verification-tier wiring** (wave-32): Weaker backends automatically trigger higher verification (tier 2→tier 4) — no code changes required; orchestrator transparently adapts rigor based on driver capabilities.
+- **OpenAI-compatible backend configuration** (wave-32): `aesop.config.json` backend section configures model, base_url, and API key for local Ollama or OpenRouter inference.
+- **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.
+
+### Fixed
+- **Authorization header cross-origin stripping** (PR #221): Blocks Authorization headers on cross-origin redirects to prevent credential leakage; security hardening for urllib transport.
+- **Secret-scan fail-closed on read errors** (PR #226): `secret_scan.py` now fails CLOSED when unable to read files or git data, blocking pushes instead of silently passing; P1 security.
+- **Driver subsystem in npm package** (PR #220): Multi-model AgentDriver backend abstraction now ships in the npm package, enabling production use of alternative backends.
+- **CI/publish Node version parity** (PR #225): Unified Node.js version across CI and npm publish workflows for reproducible builds.
+- **Adversarial-review safety fixes** (wave-32): Multiple orchestration loop hardening fixes identified and validated by external review (agent-grading-agent risks eliminated).
+
+### Security & Hardening (Post-Release Fixes)
+
+Critical hardening round integrated after 0.2.0 release-artifact preparation (fe6bb04, 2026-07-21):
+
+**AI & Prompt Security:**
+- **Codex prompt-injection hardening** (fix/codex-prompt-injection): JSON-wrapped framing prevents prompt injection in orchestration context; multi-layer escaping for task/dispatch boundaries (P1 AI-security).
+- **Codex frame integrity** (fix/codex-frame-integrity): SHA-256 digest + retry nudge for frame integrity verification across API boundaries; prevents frame corruption from in-flight mutations.
+- **Codex path containment** (fix/codex-driver-path-containment): Cross-platform path normalization (Windows: `resolve()` + `commonpath()`, Unix: realpath) blocks directory traversal in task file operations (P2 security).
+- **Codex escape-accounting** (fix/codex-prompt-injection): Measure `max_owned_bytes` post-escape to detect prompt-injection breakout payloads (P1 AI-security).
+
+**System & Daemon Hardening:**
+- **Daemon fail-closed on lock errors** (fix/daemons-lock-portability): Pre-push and coordination daemons now fail CLOSED on file-write errors, lock-acquisition timeout, or heartbeat stalls; prevents silently-skipped enforcements. CONDUCTOR_ROOT portability (Windows/Unix path handling).
+
+**Data & Audit Security:**
+- **Audit log JSON escaping** (fix/audit-log-repo-escape): Escape `repo_name` and payload fields in audit-log JSON emits to prevent injection attacks on durable audit trail (P1 security).
+- **Audit-tail verdict fix** (fix/audit-tail-verdict): Correct column index in wave_audit_tail.py verdict parsing and add validation whitelist to prevent misclassified wave outcomes.
+
+**Transcript & Observability Hardening:**
+- **Redaction-proof transcript digest** (verify_ui_trio.py): Single-source redaction patterns (`transcript_digest.py`) ensure sensitive data (API keys, internal tokens, paths) are consistently masked across all observability exports — dashboard, audit, and external integrations.
+
+**Pre-Push & CI Hardening:**
+- **Pre-push delete-refspec hardening** (fix/prepush-delete-refspecs): Enforce branch-protection policy on force-delete and fast-forward-only mutations; prevent refspec conflicts from stalling the merge train.
+- **Empty-stdin handling** (fix/prepush-delete-refspecs): Guard pre-push hook against stalled CI merge-wait (empty stdin → timeout → fail-closed block).
+- **Cost-ceiling fail-closed** (fix/cost_ceiling): Per-wave spend ceiling now enforced at dispatch time; fails CLOSED on file/git read errors. **Caveat:** Enforced at every dispatch gate on ALL backends: drivers reporting live token spend are metered directly; drivers that cannot observe per-instance spend (the Claude Code reference driver, by honest contract) return None and the ceiling reads the outcomes ledger itself with proper period windowing.
+
+### Documentation
+- **Multi-model configuration guide** (wave-32): docs/INSTALL.md now includes "Using Non-Claude Backends" section with Ollama example, verification-tier table, and troubleshooting.
+- **Driver domain map complete** (wave-32): driver/CLAUDE.md now lists all Files (openai_compatible_driver.py, backend_config.py) with descriptions for one-file-per-domain rule.
+- **State_store coordination modules** (wave-32): state_store/CLAUDE.md Module Layout now includes coordination.py and identity.py.
+
+## [0.1.1] - 2026-07-17
+
+Patch release with first-hour adopter fixes, orchestration performance improvements, and observability enhancements. Targets users deploying 0.1.0 to production and the fleet during active wave execution.
+
+### Adopter / First-hour Fixes
+- **Git init + --no-git scaffold flag** (wave-rc6): New `--no-git` scaffolder option for adopters integrating into existing repos without re-initializing version control.
+- **Port conflict detection** (wave-rc6): CLI and doctor now detect and report port-binding conflicts before dashboard startup; helpful error messages with conflict resolution steps.
+- **Next-steps ordering** (wave-rc5): Orchestration template ordering fixed so next-steps appear after state blocks, improving readability for first runs.
+- **Aesop doctor subcommand** (wave-rc4): New preflight check validates configuration, hooks, state store health, and port availability before wave startup.
+- **Executable bits in tarball** (wave-rc4): Vendored dispatch template + scripts now ship with correct execution bits set (CLI was inventing a standalone validator; real one now included).
+
+### Orchestration / Performance
+- **Wave-dispatch template latency** (wave-rc5): Targeted performance repairs — self-check parallelization, postBuild hooks, multi-testCmd batching for faster feedback cycles.
+- **Wave preflight validator** (wave-rc5): New structural validation before dispatch prevents malformed config from blocking the build.
+- **CI merge-wait fail-closed** (wave-rc3): `ci_merge_wait` timeout now blocks dispatch (fail-closed) instead of silently passing; prevents merging while CI is still running.
+
+### Observability / Instrumentation
+- **OUTCOMES-LEDGER producer** (wave-rc5): Append-wave ledger tracks per-wave execution outcomes (dispatch time, wave duration, merge timing) for fleet analytics.
+- **CI workflow linter** (wave-rc5): New `tools/ci_workflow_lint.py` statically validates GitHub Actions YAML (npm-ci lockfile presence, every package.json test script is invoked, file references resolve) — catches the green-means-never-ran class.
+- **Failure drilldown** (wave-rc3): Enhanced error reporting in dashboard drill-down view — inspect failure reasons, cost metrics, and agent transcript timestamps per-incident.
+- **Cost-economics dashboard** (wave-rc4): Wave-level cost analytics with model breakdown, per-day bar chart (pure SVG), verdict scorecard (success/failure/hung rates), pricing estimates from config.
+- **MCP cost tools** (wave-rc3): New read-only MCP cost-ledger and cost-ceiling tools expose spend tracking for external Claude integrations.
+- **Transcript digest + claudemd_lint** (wave-rc6-obs): New tools/artifact for post-wave transcript summarization and CLAUDE.md scope linting (3-line max per section, enforcement on drift).
+
+### Security & Reliability
+- **Gitignore-respecting secret scan** (wave-rc5): `secret_scan.py` now respects `.gitignore` patterns; skips ephemeral runtime files (state/, .env files, node_modules traces) to reduce false positives and scan time.
+- **Aesop fleet CLI** (wave-rc3): New `aesop fleet` subcommand suite for production fleet inspection (list agents, query costs, export telemetry).
+
+### Documentation & Portability
+- **ANY-REPO portability** (wave-rc4): Aesop now scaffolds into any existing Node/Python repo; setup guides, CONTRIBUTING.md, GitHub issue templates (SECURITY.md, CODE_OF_CONDUCT) included.
+- **Domain CLAUDE.md minification** (wave-rc6): All domain-specific documentation scoped to one file per Haiku task; root CLAUDE.md now a pure map for faster load and maintenance.
+- **CONTRIBUTING guide** (wave-rc6): Contributor workflow, test running, release process, branching discipline documented with examples.
+
+### Tests
+- **Full gate green** (all waves): npm run test:py && test:node + all shell suites + secret-scan pass without signature warnings.
 
 ## [0.1.0] - 2026-07-17
 
@@ -251,7 +366,7 @@ package ships slim and reproducible from a clean clone.
 
 ## Initial Release
 
-This is the first public release of Aesop, a clean-room open-source implementation of the fable-fleet orchestration harness. The codebase includes:
+This is the first public release of Aesop, a clean-room source-available implementation of the fable-fleet orchestration harness. The codebase includes:
 
 - The complete orchestration engine with watchdog and monitor
 - Web dashboard for fleet observability

package/README.md

@@ -3,7 +3,7 @@
 </p>
 
 <p align="center">
-  <em>Fable-Fleet Orchestration Harness</em>
+  <em>Autonomous Developer for Any Repository</em>
 </p>
 
 <p align="center">
@@ -12,115 +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 orchestration harness for Claude Code that builds itself. It runs a `/buildsystem` wave cycle—ranking a backlog, fanning out parallel Haiku agents (1/3 the cost of Sonnet, 1/5 the cost of Opus), watchdogging them, verifying merges, then feeding the next wave via audit + ideation + fleet-ops monitoring. **This repo's own PRs are built by Aesop's own loop.** Dogfooding, not doctrine.
+## What It Does
 
-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-rc1).
+**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.
 
-What you get: **cost-optimized multi-agent dispatch** (Haiku-first subagents, lean orchestrator), **durable state** (git-committed checkpoints survive wipes), **observable machinery** (every agent run logged, every cost tracked), **live dashboard** (real-time fleet health at http://localhost:8770), and **security gates** (secret-scan blocks pushes, CI validates each merge).
+## Feature Demo
 
-## Milestone: it shipped itself (0.1.0-rc.1)
-
-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).
-
-## Why Aesop?
-
-Multi-agent AI fleets hit a wall: 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, and **git-committed state** (STATE.md, BUILDLOG.md) survives machine wipes with zero data loss. See the wave cycle below: ranked backlog → parallel worktree-isolated fleet → merge train → checkpoint → audit feeds next wave.
-
-```
-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)
+**One-turn wave** — Run a complete build cycle (tests, build, docs, review, merge, audit) end-to-end:
+```bash
+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.
 
-(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.
-- **Self-diagnosing npm publish** — OIDC token generation and publish reliability verified on each release; workflow surfaces diagnostics inline.
-
-## Get Started (3 steps, 5 min)
+**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.
 
-**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 -->
 
@@ -130,147 +82,36 @@ Aesop is built entirely by its own `/buildsystem` wave cycle—running parallel
 
 | Metric | Value |
 | --- | --- |
-| Merged PRs | 170 <!-- metrics-verified: self_stats.py (git log) --> |
-| Total Commits | 556 <!-- metrics-verified: self_stats.py (git log) --> |
-| Project Age | 5 days <!-- metrics-verified: self_stats.py (git log) --> |
+| Merged PRs | 223 <!-- metrics-verified: self_stats.py (git log) --> |
+| Total Commits | 880 <!-- metrics-verified: self_stats.py (git log) --> |
+| Project Age | 10 days <!-- metrics-verified: self_stats.py (git log) --> |
 | Waves | 30 <!-- metrics-verified: self_stats.py (git log) --> |
-| Insertions + Deletions | 96,065 <!-- metrics-verified: self_stats.py (git log) --> |
-| Files Tracked | 336 <!-- metrics-verified: self_stats.py (git log) --> |
+| Insertions + Deletions | 161,064 <!-- metrics-verified: self_stats.py (git log) --> |
+| Files Tracked | 500 <!-- metrics-verified: self_stats.py (git log) --> |
 | Distinct Co-authors | 9 <!-- metrics-verified: self_stats.py (git log) --> |
 
 <!-- STATS:END -->
 
 
-## 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
+## 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
 
@@ -295,4 +136,4 @@ Copyright 2026 Matt Culliton.
 
 ---
 
-**Aesop**: Fable-fleet orchestration, built by Aesop itself. May your orchestrator be wise and your subagents swift.
+**Aesop**: Autonomous developer for any repository, built by Aesop itself. May your orchestrator be wise and your subagents swift.