@matt82198/aesop 0.3.2 → 0.4.0

package/docs/MICROKERNEL.md

@@ -0,0 +1,452 @@
+# Aesop as an AI Micro-Kernel: Two Swappable Seats
+
+**Status**: HS-1 (unified two-seat config) + HS-2 (live orchestrator-seat swap)
+shipped. This doc is the conceptual centerpiece for both — what the seam
+actually is, what is proven about it today, and how to swap a seat's model
+in about a minute.
+
+---
+
+## What it is
+
+Aesop's wave loop has exactly two places where a large language model makes
+a decision:
+
+1. **The worker seat** — does the work: writes files, runs commands, reports
+   a structured result. Interface: `AgentDriver`.
+2. **The orchestrator seat** — judges the work: decides whether a
+   test-verified item is safe to ship. Interface: `OrchestratorBackend`
+   (called through `OrchestratorDriver.decide()`).
+
+Both seats are **swappable parts**, not the engine itself. The engine —
+`driver/wave_loop.py`'s `run_wave()` — never talks to a model directly; it
+calls exactly two abstract interfaces and does not care what sits behind
+either one. This is the micro-kernel idea applied to an agent harness: keep
+the kernel (the loop, the state contract, the human-facing report) tiny and
+stable, and make every model a replaceable driver plugged into a fixed seam.
+
+**Identity lives in files, not memory.** Aesop is crash-only: there is no
+in-process state that a restart loses. Recovery is by reading `STATE.md`,
+`tracker.json`, the recovery journal, and the Report JSON off disk — the same
+files a *different* model in either seat would read and write. That is what
+makes a seat swap safe: the model is not the thing being recovered, the
+files are.
+
+**What is invariant across a seat swap** — the two things a human or a
+downstream tool actually depends on:
+
+- **The Report JSON** — the wave scheduler's output contract (`phase`,
+  `wave_id`, `items_selected`/`items_shipped`, `blocked`,
+  `orchestrator_gate`, …, documented in full in `driver/wave_scheduler.py`'s
+  module docstring). Swapping either seat adds *at most* two well-known
+  optional keys (`orchestrator_review`, per-item `final_catch`) and changes
+  no existing key's shape.
+- **The state layer** — `STATE.md`, `tracker.json`, receipts, and the
+  recovery journal. Same file names, same key sets, regardless of which
+  model is deciding.
+
+What is **not** invariant, and isn't meant to be: which model made a given
+decision, and (for the orchestrator seat) whether a decision was even routed
+through an API model at all versus made by the live harness. That is exactly
+the part that's supposed to change when you swap a seat.
+
+---
+
+## The two seats
+
+### Worker seat — `AgentDriver`
+
+Selected by `seats.worker` in `aesop.config.json`. Concrete backends today:
+
+| `backend` | What it is | Notes |
+|---|---|---|
+| `claude` (default) | Claude Code CLI harness | No API key; two ops run as concrete Python, three are serviced by the harness itself |
+| `codex` | OpenAI Chat Completions | Requires a `json_schema`-capable model (`gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`; `gpt-3.5-turbo` is rejected at construction unless you pass `allow_unverified_models=True`) |
+| `openai-compatible` | Any OpenAI-compatible HTTP endpoint | Ollama, OpenRouter, Together, etc. — **requires `base_url`** |
+
+**Live wiring**: `driver/wave_scheduler.py`'s `resolve_worker_driver()` reads
+`seats.worker` from `aesop.config.json` and calls `build_driver()` on it
+(`driver/backend_config.py`). `--driver claude|codex` on the CLI overrides
+the config. No `seats` block, or a bare legacy flat `{"backend": ...}` block
+with no `seats` wrapper, keeps behavior byte-identical to a pre-0.4.0
+install: `ClaudeCodeDriver`, no key needed. (The legacy flat block still
+*parses*, and direct `build_driver()` callers still honor it — it is only
+*inert* in the scheduler's default dispatch path, so migrate it into
+`seats.worker` to actually activate it.)
+
+### Orchestrator seat — `OrchestratorBackend`
+
+Selected by `seats.orchestrator`. This is the decision seat: the thing that
+calls `OrchestratorDriver.decide()` to produce a structured verdict.
+
+| `backend` | What it is |
+|---|---|
+| `harness` (default, also accepts `"claude"`) | The **null** `HarnessOrchestratorBackend`. `decide_call()` raises on purpose — there is no Python code path that "calls" the harness. This is the honest way of saying: the live Claude Code session driving this loop IS the orchestrator seat, and no swapped backend exists. |
+| `openai-compatible` | `OpenAICompatibleOrchestratorBackend` — a real OpenAI-compatible HTTP call, same `model`/`base_url`/`api_key_env`/`is_local` shape as the worker seat, plus `timeout_s`. `base_url` is optional here (defaults to the hosted OpenAI endpoint) — unlike the worker seat, which requires it. |
+
+**Live wiring**: `driver/wave_loop.py`'s `run_wave(..., orchestrator_backend=...)`
+Phase 6 — the pre-ship gate — routes **one `final_catch` decision per
+test-verified item** through the configured backend when one is live;
+`driver/wave_scheduler.py`'s `resolve_orchestrator_backend()` is what builds
+that backend from `seats.orchestrator` and passes it through. With no
+`seats.orchestrator` block (or `backend: "harness"`/`"claude"`),
+`resolve_orchestrator_backend()` returns `None` and Phase 6 stays exactly
+what it was pre-HS-2: `adversarial_review = "deferred"`, no
+`orchestrator_review` key, no OpenAI backend constructed, no key required.
+
+Be precise about scope here, because it's easy to overstate: Phase 6's
+`final_catch` is the **only** decision point HS-2 wired to the seat. Backlog
+ranking, in-session adjudication, and PR merges are still made by the live
+harness directly — see [What's proven vs bounded](#whats-proven-vs-bounded).
+
+---
+
+## The invariant boundary
+
+The claim "the Report JSON and state layer are unchanged across a seat
+swap" is not just asserted in this doc — it's a committed, offline,
+automated proof: `tests/test_hs2_swap_proof.py`. It drives the **same task**
+through the public scheduler path twice — once with the default harness
+orchestrator seat, once with a swapped `FakeOrchestratorBackend` — both on a
+non-Claude fake worker seat, and asserts:
+
+- Identical Report JSON key sets, top-level and per-item.
+- Identical values for `slug`/`backend`/`tier`/`verified`/`testExit`.
+- Identical tracker terminal state (`in_progress`) and structure.
+- Identical journal file names and entry key sets.
+- The swapped backend demonstrably decided (`call_count == 1`).
+
+A companion **bounded live run** — `bench/results/hs2-swap-proof-2026-07-25.md`
+/ `.json` — drove one real task (fix a broken `multiply`) through `run_wave`
+twice against a live codex (gpt-4o-mini) worker seat: arm A the default
+harness orchestrator seat, arm B `seats.orchestrator` = openai-compatible
+gpt-4o-mini. Both arms dispatched, test-exit 0, `verified: True`; arm B's
+gpt-4o-mini seat returned a schema-valid `final_catch` verdict (`merge`,
+with evidence + confidence) on the first attempt. Result shape was
+invariant modulo exactly the two documented opt-in keys
+(`orchestrator_review`, `final_catch`). Total spend: 3 gpt-4o-mini calls
+(~1.1k worker tokens + one decision call), well under the run's US$2 cap.
+`git=None` — the live proof never shipped anything.
+
+That is the whole evidentiary basis for "the seam is real and the boundary
+holds": one offline proof covering the general mechanism plus one small,
+real, bounded live run. See [Bounds](#whats-proven-vs-bounded) for what that
+does and does not establish.
+
+---
+
+## How to swap a seat
+
+Everything lives in one namespaced block, `seats`, in `aesop.config.json`:
+
+```json
+{
+  "seats": {
+    "worker": { "backend": "claude" },
+    "orchestrator": { "backend": "harness" }
+  }
+}
+```
+
+That's the *default* — writing it explicitly changes nothing, and deleting
+it changes nothing either. To swap a seat, replace its block. See the
+[quickstart](#swap-a-seats-model-in-60-seconds) below for copy-paste
+examples.
+
+Fields, common to both seats' `openai-compatible` backend:
+
+| Field | Required? | Meaning |
+|---|---|---|
+| `backend` | yes | `"claude"` / `"codex"` / `"openai-compatible"` (worker); `"harness"` / `"claude"` / `"openai-compatible"` (orchestrator) |
+| `model` | required for `codex` and `openai-compatible` | Model id |
+| `base_url` | **required** for worker `openai-compatible`; optional for orchestrator (defaults to `https://api.openai.com/v1`) | The HTTP endpoint |
+| `api_key_env` | optional | Env var name holding the API key — read at **call time**, never stored in the config |
+| `is_local` | optional | See below |
+
+### SECURITY notes (read these before pointing a seat at a real endpoint)
+
+- **`api_key_env` is a heuristic allowlist, not a guarantee.** Known
+  LLM-provider names (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,
+  `OPENROUTER_API_KEY`, `TOGETHER_API_KEY`, `GROQ_API_KEY`,
+  `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`, `FIREWORKS_API_KEY`,
+  `OLLAMA_API_KEY`, `AZURE_OPENAI_API_KEY`, `GOOGLE_API_KEY`) pass
+  **silently**. A name that doesn't look like a key env var, or that
+  contains an obvious non-LLM secret fragment (`SECRET`, `TOKEN`,
+  `PASSWORD`, `PASSWD`, `CREDENTIAL`, `PRIVATE`, `ACCESS`, `SESSION`,
+  `COOKIE`, `SIGNING`), is **hard-rejected**. Any other key-shaped name
+  (a custom LLM gateway) is **allowed but prints a loud `NOTICE` to
+  stderr** naming the risk: its value *will* be sent as a Bearer token
+  to your configured `base_url`. This is deliberately best-effort — no
+  name check can prove an env var actually holds an LLM key. The NOTICE
+  is the real signal; review it whenever a non-provider name appears.
+- **`is_local: true` requires a loopback `base_url`** (`localhost`,
+  `127.0.0.1`, or `::1`) — construction rejects it otherwise. `is_local`
+  waives the API-key requirement (a dummy `local-only` Bearer is sent
+  instead), so it must be pinned to loopback: `is_local` plus a remote
+  `base_url` would ship your prompt content to an arbitrary host with no
+  key needed at all.
+- **`base_url` is SSRF-validated** (`driver/backend_config.py`'s
+  `validate_base_url`): scheme must be `http`/`https`, no embedded
+  credentials, and both IP literals *and* DNS-resolved hostnames are
+  checked against private/loopback/link-local/reserved ranges (including
+  IPv4-mapped IPv6 forms like `::ffff:169.254.169.254`, which would
+  otherwise bypass the IPv4 checks, and the `169.254.169.254` cloud
+  metadata address). **Residual, documented, not closed**: this is a
+  load/construct-time check with a bounded (5s) DNS resolution. A
+  TTL-0 DNS-rebinding attacker can pass validation and then re-point the
+  name at a private address before the actual HTTP call; closing that
+  fully requires connection-time address pinning in the transport, which
+  this does not do. An unresolvable hostname is allowed through (offline
+  config loading must not fail) and the eventual connection just fails
+  on its own.
+
+---
+
+## What's PROVEN vs BOUNDED
+
+Scrupulously, so nothing here gets over-read:
+
+### PROVEN
+
+- **Worker swap is live.** `resolve_worker_driver()` builds a real,
+  configured `AgentDriver` from `seats.worker` and the scheduler dispatches
+  through it; codex and openai-compatible backends have offline test
+  coverage (`tests/test_codex_driver_e2e.py`, `tests/test_seats_config.py`).
+- **Orchestrator swap is live** (HS-2). `run_wave`'s Phase 6 routes a real
+  `final_catch` decision through a configured `OrchestratorBackend` when one
+  is present; verdict has real effect (`block` stops the ship and
+  quarantines files; `merge` approves).
+- **Swap transparency is proven** two ways: an offline test suite
+  (`tests/test_hs2_swap_proof.py`) establishing the no-op invariant and the
+  end-to-end Report/state shape invariance, *and* one bounded live run
+  (both seats real: worker + orchestrator gpt-4o-mini) where both arms went
+  green with an invariant result shape. **Small N** — see below.
+
+### BOUNDED / NOT yet claimed
+
+- **The proofs are small-N.** The offline swap-transparency test is one
+  synthetic task on a fake backend; the live run is one real task, one
+  model (gpt-4o-mini), one repeat. This proves the *plumbing* — config to
+  seat to real API call to schema-valid verdict to recorded effect — not
+  decision **quality**, and not anything at scale.
+- **Seat decision quality is a separate, ongoing question**, studied
+  in the shadow-adjudication bench line (`bench/README.md`,
+  `tools/seated_shadow_adjudication.py`). The headline finding there —
+  **"Context at the Seam"**: decontextualized adjudication (facts only, no
+  file brain) leaves both a frontier model (gpt-5.6-sol) and a cheaper
+  model (gpt-5.5) abstaining (`undetermined`, ~80–100% of runs) on the
+  hardest synthesis-heavy corpus item (item 9, a whitelist-gate-weakening
+  false positive that requires chaining "health check is top-level only" +
+  "secret_scan.py scans recursively" into "no real coverage gap"). Giving
+  the *same* models **real seated context** (actual STATE.md/tracker.json/
+  BUILDLOG.md plus the real cited code) flips both models to the correct
+  `false_positive` verdict, **stable across repeated runs and across two
+  independently-run corpus variants** (`bench/results/SEATED-AB-2026-07-24.md`,
+  `bench/results/seated-redo-2026-07-24-gpt-5_6-sol_repeat3.md`,
+  `bench/results/seated-redo-2026-07-24--neutral-seated-sol_repeat3.md`).
+  This result is **robust in the sense that matters for this doc**: it
+  reproduced after an earlier round of this same bench line caught and fixed
+  a context-leak/seam confound (a dropped-prompt / schema-mismatch bug where
+  "seated" runs weren't actually receiving the real context they claimed
+  to) — the cited results here are the **re-verified**, post-fix runs, not
+  the confounded ones. Bound: N=3 per model, one item, two OpenAI-family
+  models, not a full-corpus or cross-lab claim.
+- **Some orchestrator decisions are not routed through the seat at all.**
+  Backlog ranking, PR merges, and in-session adjudication by the live
+  harness are made outside `run_wave`'s Phase 6 and are unaffected by HS-2.
+  The seat swap covers exactly one gate: the pre-ship `final_catch` check.
+- **`wave_loop.py`'s standalone `--manifest` CLI still hardcodes
+  `ClaudeCodeDriver`** and does not read `aesop.config.json` at all. The
+  config-driven entry point is `driver/wave_scheduler.py` — that is where
+  `seats` actually takes effect. If you invoke `wave_loop.py` directly by
+  its manifest CLI, no seat swap applies.
+- **Repair stays mechanical on both seats by design.** Swapping who
+  decides `final_catch` never changes the bounded-retry repair semantics.
+
+---
+
+## The block gate
+
+`run_wave`'s Phase 6 (`_orchestrator_final_catch` in `driver/wave_loop.py`)
+reviews every **test-verified** item — a failed item never reaches the
+seat at all — and acts on the verdict:
+
+| Verdict | Effect |
+|---|---|
+| `merge` | Approved; ships exactly as it would with the default harness seat. |
+| `block` | `verified` is flipped to `False`; the item does **not** ship; the recovery journal is rewritten so a resume can't skip-and-ship it; and the item is marked **terminal** (tracker status `blocked`, never re-selected) and visible in the Report (`Report.blocked: [{slug, reason, quarantine}]`). |
+| `escalate` / `undetermined` / `DECISION_FAILED` | Degrades to today's default behavior: ships to branch (merge stays manual downstream) with an honest per-item record. **A seat outage never fabricates a verdict and never blocks a test-proven item** — this is crash-only degradation, not silent failure. |
+
+**Quarantine on block**: a blocked item's already-written files are
+restored to their pre-build state — `git checkout --` for tracked files,
+delete for untracked ones — so refused code doesn't linger in the working
+tree for a later `git add -A` to accidentally ship. This acts on **file
+paths only**: empty strings, `.`/`..`, and directory entries are rejected
+with a per-file error record rather than acted on, specifically because a
+directory or dot pathspec would revert *other* items' uncommitted verified
+work, not just the blocked item's. An ambiguous untracked/tracked
+determination (e.g. a git index lock) never deletes — fail-safe, not
+fail-delete.
+
+**Gate visibility**: if every single decision on a wave came back
+`DECISION_FAILED`, the wave-level `orchestrator_review.gate_status` is
+`"degraded"` (not `"active"`) — a 100%-failing seat is not allowed to look
+like an approving one, even though ship semantics for already-verified
+items are unaffected.
+
+---
+
+## Honest engineering note
+
+This seam did not work correctly on the first attempt at wiring it. Early
+rounds of the shadow-adjudication bench line ran through a shim that
+dropped the prompt before it reached the model, and a schema/prompt
+mismatch meant "seated" runs weren't actually seeing the context they
+claimed to have — green test output, wrong conclusion (**green is not
+correct**). Each seat — worker and orchestrator — cleared **two rounds of
+adversarial audit** before the swap-transparency claims in this doc were
+considered solid enough to write down. The context-leak confound described
+above under [Bounds](#whats-proven-vs-bounded) is exactly this class of
+bug, caught, fixed, and re-verified before being cited here.
+
+---
+
+## Swap a seat's model in 60 seconds
+
+Every config block below was verified offline against this repo's actual
+loader — `load_backend_config()` → `build_driver()` /
+`build_orchestrator_backend()` — with no network call and no API key
+(construction is always offline-safe; keys are read at call time only).
+Copy, paste, done.
+
+### Worker seat
+
+**Ollama, local, no key:**
+
+```bash
+ollama serve            # in one terminal
+ollama pull mistral     # in another
+```
+
+```json
+{
+  "seats": {
+    "worker": {
+      "backend": "openai-compatible",
+      "base_url": "http://localhost:11434/v1",
+      "model": "mistral",
+      "is_local": true
+    }
+  }
+}
+```
+
+No env var needed — `is_local: true` sends a dummy `local-only` Bearer.
+Verification tier: 3 (heaviest — small local models get the most checking).
+
+**OpenRouter, hosted:**
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+```
+
+```json
+{
+  "seats": {
+    "worker": {
+      "backend": "openai-compatible",
+      "base_url": "https://openrouter.ai/api/v1",
+      "model": "openai/gpt-4-turbo",
+      "api_key_env": "OPENROUTER_API_KEY"
+    }
+  }
+}
+```
+
+Verification tier: 2 (hosted, ~0.92 accuracy assumption).
+
+**Codex (OpenAI Chat Completions), hosted:**
+
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+```json
+{
+  "seats": {
+    "worker": {
+      "backend": "codex",
+      "model": "gpt-4o-mini"
+    }
+  }
+}
+```
+
+`model` must support `response_format: json_schema` — `gpt-4o`,
+`gpt-4o-mini`, and `gpt-4-turbo` are the known-capable set; anything else
+(including `gpt-3.5-turbo`) is rejected at construction unless you pass
+`allow_unverified_models=True` yourself. Verification tier: 2.
+
+### Orchestrator seat
+
+**OpenAI hosted (`gpt-4o-mini`) as the decision seat:**
+
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+```json
+{
+  "seats": {
+    "orchestrator": {
+      "backend": "openai-compatible",
+      "model": "gpt-4o-mini",
+      "api_key_env": "OPENAI_API_KEY"
+    }
+  }
+}
+```
+
+Note `base_url` is omitted — the orchestrator seat defaults to
+`https://api.openai.com/v1` (the worker seat has no such default; it
+requires `base_url` explicitly).
+
+**Ollama, local, no key, as the decision seat:**
+
+```bash
+ollama serve
+ollama pull mistral
+```
+
+```json
+{
+  "seats": {
+    "orchestrator": {
+      "backend": "openai-compatible",
+      "base_url": "http://localhost:11434/v1",
+      "model": "mistral",
+      "is_local": true
+    }
+  }
+}
+```
+
+**Combine any worker + any orchestrator block** under one `seats` key —
+they're independent. Running `driver/wave_scheduler.py --execute` against a
+hosted (non-`is_local`) seat requires that seat's `api_key_env` to be set;
+`--dry-run` never needs a key, because building a driver or backend is
+always offline-safe.
+
+---
+
+## See also
+
+- [docs/INSTALL.md](INSTALL.md) — "Using Non-Claude Backends" section: setup
+  prerequisites, verification-tier table, troubleshooting.
+- `driver/CLAUDE.md` — the full technical contract for both seats.
+- `bench/README.md` — the held-out benchmark measuring *quality*, separate
+  from the plumbing this doc covers.
+- `bench/results/hs2-swap-proof-2026-07-25.md` — the bounded live
+  swap-transparency run.
+- `bench/results/SEATED-AB-2026-07-24.md` — the seated-context adjudication
+  finding.

package/docs/README.md

@@ -89,6 +89,7 @@ Once you've completed the adopter journey, use these for operational reference:
 
 ### 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)
+- **[MICROKERNEL.md](MICROKERNEL.md)** — The two swappable seats (worker + orchestrator): what's invariant across a model swap, what's proven vs. bounded, and a 60-second quickstart
 
 ### Dispatch & Cost
 - **[DISPATCH-MODEL.md](DISPATCH-MODEL.md)** — Haiku-first subagent dispatch, cost analysis, patterns (fan-out, sequential, hierarchical)
@@ -144,6 +145,9 @@ Once you've completed the adopter journey, use these for operational reference:
 **I want to understand multi-instance coordination**
 → [TEAM-STATE.md](TEAM-STATE.md)
 
+**I want to swap the worker or orchestrator model (Ollama, OpenRouter, OpenAI...)**
+→ [MICROKERNEL.md](MICROKERNEL.md)
+
 **I'm reviewing a PR that changes orchestration behavior**
 → [BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md)
 

package/docs/THE-AESOP-HYPOTHESIS.md

@@ -0,0 +1,140 @@
+# The Aesop Hypothesis: Why Crash-Recoverable Systems Outrun Distributed Ones
+
+**Expanded from the original essay:** https://medium.com/@matt82198/the-aesop-hypothesis-ai-agents-that-survive-because-theyre-designed-to-fail-de5f033369d4
+
+---
+
+## The Hypothesis
+
+**Agent behavior is source code.** Everything a fleet does — every decision, every checkpoint, every recovery path — lives in durable, human-diffable files: git history, plain-text STATE.md, append-only BUILDLOG.md, Python scripts, shell hooks. No vector embeddings, no distributed consensus, no magic. When a machine fails, you re-read from disk. When a human operator needs to audit a decision, they grep the git log or read the state file. When you need to reason about cost, you look at the dispatch rules in code.
+
+This hypothesis rests on five pillars:
+
+1. **Durable plain-text state** — git + POSIX text as the state layer, not Postgres or vector DBs.
+2. **Stateless runtimes** — agents execute one request at a time; permanent state lives on disk.
+3. **Cost-aware parallelism** — cheap Haiku subagents in parallel, not serial Opus.
+4. **Guardrails in code, not prose** — pre-push secret gates, kill-switches, cost ceilings: all executable.
+5. **Observable signals** — heartbeats, append-only logs, drift detectors, crash-recovery as the normal startup path.
+
+The bet is this: **a small, crash-recoverable system running on git and plain text outperforms a distributed one** in latency, debuggability, cost, and trust — because the simpler system fails loudly and often, learns from every failure, and never hides state in a database you can't grep.
+
+---
+
+## (1) Git + POSIX Text as the State Layer
+
+**Why not Postgres? Why not vector DBs?**
+
+Aesop's core state lives in git-committed files: `STATE.md` (intent, phase, NEXT STEPS), `BUILDLOG.md` (append-only progress snapshots), Python scripts (cost rules, dispatch logic), shell hooks (pre-push gates). This is not a limitation. It is the whole idea.
+
+**Durability.** Postgres fails when the connection pool is exhausted or the database is unreachable. Git fails when the filesystem is corrupted — a far rarer event on any modern machine. State committed to git survives machine wipes, container restarts, session loss. You clone a repository from 2026-07-18, and you know *exactly* what the system was doing on that date. No migration scripts, no schema versioning, no eventual consistency.
+
+**Human-diffable forensics.** When something goes wrong, you run `git log -p` and read the actual changes that led to the broken state. You see not just what happened, but *why* the system made each decision (because the humans who designed it wrote it in code and commit messages). A vector DB stores embeddings; a BUILDLOG.md stores human-readable decisions.
+
+**Single-box by explicit design choice.** Aesop is not "not distributed yet." Multi-instance coordination is *deliberately unscheduled*. The system runs on one machine. When team scale requires multi-instance support, the real work is not "add Postgres"; it is "redesign state to support leases and event-sourcing on SQLite." That redesign is on the roadmap, not an architectural gap. Postgres is a refactoring target *after* the single-box proves the core loop works. Premature distribution is premature optimization.
+
+**Cite:** [`docs/CHECKPOINTING.md`](./CHECKPOINTING.md) — the durable state strategy; [`docs/CARDINAL-RULES.md`](./CARDINAL-RULES.md) § 5 — handoff discipline.
+
+---
+
+## (2) Stateless Runtimes + Persistent Filesystem Brain
+
+**The architecture is simple:** agents are processes. Each agent receives a scoped task, reads the filesystem for context, makes decisions, writes results, and exits. The filesystem is the only source of truth.
+
+When an agent crashes (or hits a timeout, or the user kills it), the next agent picks up from the checkpoint files on disk. There is no agent state in memory, no distributed transaction, no graceful shutdown protocol. Dead is dead; reading from disk is the recovery protocol *and the normal startup path*.
+
+**Why this matters:** the system never invents state. An agent that hangs for 3 minutes and is forcibly killed is indistinguishable from one that exits normally — both leave state on disk, and the next reader validates what's there. No "check if this agent is still alive" logic, no heartbeat-based membership. The watchdog's job is simple: if a task hangs, kill it; the orchestrator will re-read the checkpoint and decide what to do next.
+
+**Crash recovery is not a special path.** On resume after a crash (or user interruption, or session loss), the orchestrator reads STATE.md and BUILDLOG.md from disk, verifies them against git log, and proceeds. If STATE.md is stale, it updates it. If BUILDLOG.md shows a half-completed task, it completes it or rolls back and retries. This is the same code path that runs on normal startup. No two code paths, no special-case recovery hooks, no "was I shut down cleanly?" flag.
+
+**Cite:** [`docs/CHECKPOINTING.md`](./CHECKPOINTING.md) — recovery workflow; [`docs/RELIABILITY.md`](./RELIABILITY.md) — inputs-always-produce-outputs principle.
+
+---
+
+## (3) Cost Architecture: Haiku-First, Flat Fan-Out, the Cancelled Hierarchical Design
+
+**The cost model is the heart of the system.** Subagents are *always* Haiku (1/3 the per-token cost of Opus), spawned in parallel (5–8 agents per wave). This single rule, more than any other, determines whether agent-driven work scales or burns money.
+
+**The A/B that killed hierarchical dispatch:** Earlier designs proposed a three-tier model — Fable orchestrator + Sonnet supervisors (splitting work into domains) + Haiku workers. Lab testing showed **4.3× cost increase for identical quality**. The hierarchical design was cancelled. (Cancelled architectures with published data is engineering honesty, not weakness.)
+
+Today's dispatch is flat: one Opus/Fable orchestrator on the main thread, 5–8 parallel Haiku workers per wave, no intermediate supervisors. Cost per wave: roughly $0.01–0.02 USD. Scaling to 10 waves per day still costs less than a single Opus API call.
+
+**The benchmark proves Haiku is good enough.** The held-out judgment benchmark (v3 = 28 additional tasks, building on v2 = 11 prior) tested Haiku, Sonnet, and Opus across 39 combined judgment tasks: bug-in-diff (with concurrency races and resource leaks), finding-inflation, acceptance-criteria coverage, severity calibration, root-cause-from-trace, refactor-equivalence, security issue spotting. All three models converged on identical answers for all 28 v3 tasks. Combined score: **Haiku 39/39** vs **Opus 38/39** (Opus erred on one severity call; Haiku did not). At ~1/3 the per-token cost.
+
+**Honest limits on the benchmark:** Curated (N=39), not sampled from real fleet transcripts. No frontier-reaching task found where Opus beats Haiku. The benchmark maps a floor ("Haiku is sufficient for these judgment shapes"), not the absolute frontier. Cost is token-price ratio, not wall-clock latency. These are not hidden; they are load-bearing caveats.
+
+**Cite:** [`docs/DISPATCH-MODEL.md`](./DISPATCH-MODEL.md) — cost model and patterns; [`bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md`](../bench/results/2026-07-17-judgment-v3-haiku-sonnet-opus.md) — benchmark run and interpretation.
+
+---
+
+## (4) Guardrails Enforced in Code, Not Prose
+
+**Safety rules live in executable code**, not documentation:
+
+- **Pre-push secret gate** (`tools/secret_scan.py`): scans staged files for 50+ secret patterns (AWS keys, Anthropic keys, tokens). Exits with failure on file-read errors; never silently passes.
+- **Kill-switch** (`tools/halt.py`): wired into the live dispatch path. When triggered, aborts all pending work with zero new workers spawned. Operator-triggered (manual brake), not autonomous.
+- **Cost ceiling** (`tools/cost_ceiling.py`): halts dispatch when the configured per-wave budget is exceeded. Enforces a *configured* ceiling, not live-metered spend.
+- **Pre-push branch checks**: run before every push (enforced via git hooks). No committing to main, no force-push without explicit approval.
+
+The key insight: **fail-closed by default.** A secret-scan that silently passes when the file is unreadable is worse than a crash. A kill-switch that doesn't trip is useless. A cost ceiling that is "maybe" enforced wastes tokens. Aesop inverts the default: safety rules are executable and logged; unsafe paths are explicitly rejected; a gate that fails triggers an immediate backout.
+
+**Cite:** [`docs/CARDINAL-RULES.md`](./CARDINAL-RULES.md) § 7 — security and version control; [`tools/halt.py`](../tools/halt.py), [`tools/cost_ceiling.py`](../tools/cost_ceiling.py) — implementations.
+
+---
+
+## (5) Observability: Heartbeats, Append-Only Logs, Drift Signals, and CI Sharding
+
+**Every action produces a signal.** Daemons emit heartbeats every cycle (even on error). Logs are append-only; every task appended with a timestamp. Stalled agents trigger automatic watchdog restarts (3 retries, then escalate to human).
+
+**Drift detection.** The orchestrator compares expected state (BUILDLOG.md) against reality (git log, filesystem timestamps). Drift = stale checkpoint, incomplete work, or a half-written file. On detection, the system does not guess: it re-reads from disk and either rolls forward (if work completed) or rolls back (if interrupted).
+
+**CI sharding story.** Early on, Aesop's test suite ran serially on Windows, wall-clock time ~11 minutes. A single spawn-semantics bug hit Windows harder than Linux (process group cleanup behaved differently). Rather than paper over it with retries, the team:
+1. Diagnosed the root cause (Windows process tree cleanup).
+2. Fixed it (explicit cleanup in the test harness).
+3. Added sharding (4-way split, ~3 min wall-clock with 80–180s per shard).
+4. Made Windows a required check (previously optional).
+
+The point: **observability means you see the real bottleneck**, and you fix it, not the symptom. Aesop's CI reports job timings for every shard; the orchestrator reads those and can rebalance if a shard drifts >20% off baseline.
+
+**Cite:** [`docs/CARDINAL-RULES.md`](./CARDINAL-RULES.md) § 3 — reliability core and heartbeats; [`docs/RELIABILITY.md`](./RELIABILITY.md) — inputs-always-produce-outputs, never-wait discipline.
+
+---
+
+## Proof: What Ships with the System
+
+These are not claims about what Aesop *could* do. They are receipts:
+
+- **1,088 commits, 251 merged PRs, 30 waves** (verified by anyone who clones; `tools/self_stats.py`).
+- **143,403 lines of code** across 546 files, delivered end-to-end: from feature intake to merge.
+- **Benchmark results** committed in `bench/results/` — 39 judgment tasks, all models scored by deterministic Python scoring (no LLM in the grading loop).
+- **Kill-switch proof** — `tools/halt.py` is wired into the live dispatch path and was exercised on a real wave.
+- **Cost ceiling** — implemented in `tools/cost_ceiling.py`, enforced per-wave.
+- **Windows CI sharding** — reduced wall-clock time from ~11 min to ~3 min (4-way shard); now a required check.
+- **Durable state** — STATE.md, BUILDLOG.md, and all orchestration rules are git-committed and human-readable.
+
+---
+
+## Honest Limits
+
+This is not a universal solution. The system has explicit boundaries:
+
+1. **Single-box by design.** Aesop runs on one machine. Multi-instance coordination is on the roadmap, not shipped. If you need 100-machine scale today, this is not the tool.
+2. **Small-N benchmarks.** 39 judgment tasks is directional evidence, not statistical proof. Frontier reasoning (where Opus depth might matter 3×) is not tested here.
+3. **Lab-measured multi-writer throughput.** 800 events/sec is measured in a stress test, not production. Team scale beyond one machine requires additional work (leases, event-sourcing, distributed consensus).
+4. **No third-party verification yet.** The artifacts are committed so a skeptic can reproduce — that is transparency, not independent replication.
+5. **Release candidate.** APIs, config, and dashboard contracts may still shift. Pin the exact version if you need stability.
+
+---
+
+## The Bet
+
+**Simple systems that fail loudly and often outrun complex ones that hide state in databases.**
+
+Aesop bets on:
+- **Transparency over abstraction.** Every decision is code. Every state is a file you can read and diff.
+- **Crash recovery as design principle.** If you build for recovery from scratch, you build for reliability. Distributed systems hide failures; crash-recoverable ones surface them.
+- **Small is faster than smart.** Flat fan-out (5–8 Haiku agents) beats hierarchical dispatch (4.3× cost), even at scale, because the simpler system has fewer failure modes.
+- **Cost as a first-class constraint.** The whole system is designed around $0.01–0.02 per wave. Expensive paths are rejected before they ship.
+
+The evidence is in the receipts: 1,088 commits, 251 PRs, 30 waves, zero hallucinated audits (via adversarial verification), and a benchmark that proves Haiku is good enough.
+
+**Read more:** [`docs/autonomous-swe.md`](./autonomous-swe.md) — honest account of what shipped, what didn't, and where the gaps are.