@matt82198/aesop 0.1.0 → 0.3.1

package/docs/README.md

@@ -1,6 +1,6 @@
 # Aesop Documentation
 
-Aesop is a fable-fleet orchestration harness for Claude Code. It runs fast, cheap delivery waves: parallel Haiku agents, durable state, observable machinery, security gates.
+Aesop is an autonomous developer system that crawls into any repository and orchestrates intelligent work. It ranks tasks, dispatches parallel Haiku agents, verifies merges, audits the work, and feeds the next iteration. **State persists across multiple instances via a durable SQLite event log**, so your whole team uses one coordinated system.
 
 ---
 
@@ -12,7 +12,7 @@ If you're new to Aesop, follow this 4-stage path:
 **[INSTALL.md](INSTALL.md)** — Prerequisites, `npx` scaffold, what gets created
 
 - System requirements (Claude Code CLI, Git, Bash, Node.js, Python)
-- Quick-start: `npx @matt82198/aesop@beta my-fleet`
+- Quick-start: `npx @matt82198/aesop my-fleet`
 - Manual setup for development (git clone)
 - Pre-push hook installation
 
@@ -56,6 +56,33 @@ If you're new to Aesop, follow this 4-stage path:
 
 ---
 
+## Core Concepts: /power and /buildsystem
+
+### /power — System Initialization
+The `/power` skill initializes Aesop into your 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 Claude Code session. It's idempotent—safe to run multiple times. See [skills/power/SKILL.md](../skills/power/SKILL.md) for details.
+
+### /buildsystem — One Complete Wave Cycle
+The `/buildsystem` skill runs **one complete iteration 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 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 depending on backlog size). See [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md) for a concrete walkthrough.
+
+### Team State & Multi-Instance Design
+**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 is production-ready but currently opt-in. A future release will enable multiple Aesop instances (e.g., per-team subgroups or geographic regions) to coordinate around a single source of truth—a Postgres-backed event log, with git as a diffable export. See [TEAM-STATE.md](TEAM-STATE.md) (design in progress) for the vision and current architecture decisions.
+
+---
+
 ## Deep-Dive Reference Docs
 
 Once you've completed the adopter journey, use these for operational reference:
@@ -108,12 +135,15 @@ Once you've completed the adopter journey, use these for operational reference:
 **I want to understand the cost model**
 → [DISPATCH-MODEL.md](DISPATCH-MODEL.md) or [HOW-THE-LOOP-WORKS.md](HOW-THE-LOOP-WORKS.md#why-its-fast--cheap)
 
-**I want to know what's actually proven vs. claimed (the rc.1 milestone)**
+**I want to know what's actually proven vs. claimed (the 0.1.0 milestone)**
 → [autonomous-swe.md](autonomous-swe.md)
 
 **I need to understand how state survives a crash**
 → [CHECKPOINTING.md](CHECKPOINTING.md)
 
+**I want to understand multi-instance coordination**
+→ [TEAM-STATE.md](TEAM-STATE.md)
+
 **I'm reviewing a PR that changes orchestration behavior**
 → [BEHAVIORAL-PR-REVIEW.md](BEHAVIORAL-PR-REVIEW.md)
 

package/docs/TEAM-STATE.md

@@ -0,0 +1,372 @@
+# Team-Shared State: Current & Future Architecture
+
+**Status (0.1.0)**: Single-instance with durable git checkpointing. Event-sourced SQLite module (`state_store/`) is production-ready but not yet integrated into orchestrator reader/writer paths.
+
+---
+
+## Current State Model (Git-as-Checkpoint)
+
+Aesop currently stores orchestration state in **two git-tracked files**:
+
+- **STATE.md** — Orchestrator intent, decisions, phase, and NEXT STEPS (single-writer)
+- **BUILDLOG.md** — Append-only progress snapshots (agents append one line per work unit)
+
+**Why it works**: Single-instance is proven. State survives machine wipes, resync on session restart, human-diffable for review and forensics.
+
+**Limitation**: Does not scale to teams—no concurrent writers, no transactions, high latency (requires `git push`).
+
+---
+
+## Future: SQLite Event Log + Git Export
+
+**Vision**: Event-sourced SQLite WAL becomes the system-of-record. Git exports are rendered from current projections for durability and review.
+
+**In the repo now**:
+- `state_store/store.py` — EventStore with atomic `append()`, concurrency-safe writes
+- `state_store/projections.py` — Fold events into tracker state
+- `state_store/api.py` — Facade for backend swaps (SQLite today, Postgres later)
+- `tests/test_state_store.py` — Concurrent-write proofs, projection tests
+
+**Next steps**: Wire the orchestrator and agent writers to use `StateAPI` instead of git direct writes. This unblocks team-scale coordination without breaking single-instance durability (git exports remain).
+
+For implementation details, see `state_store/` source code and inline documentation.
+            status["phase"] = ev["payload"]["phase"]
+        elif ev["type"] == "decision_locked":
+            key = ev["payload"]["key"]
+            status["decisions"][key] = ev["payload"]["value"]
+        elif ev["type"] == "next_steps_updated":
+            status["next_steps"] = ev["payload"]["steps"]
+        elif ev["type"] == "audit_findings_recorded":
+            status["latest_audit"] = ev["payload"]
+    return status
+```
+
+**Readers** (same-turn):
+- Dashboard queries `api.project("orchestrator_status")` → sees latest phase, decisions, next steps live (no git fetch).
+- Monitor daemon queries `api.project("orchestrator_status")` → sees what the orchestrator decided last turn; compares against local observations.
+- Agents query `api.project("orchestrator_status")` → see their assignment (brief payload in next_steps).
+
+---
+
+## Migration Path: Which Readers/Writers Move First
+
+### Phase 1: Add orchestrator_status Stream (EARLY CUTOVER)
+
+**What moves**: Orchestrator WRITES phase + next steps to `orchestrator_status` events instead of `STATE.md`. Readers stay on git (BUILDLOG.md + STATE.md fetches).
+
+**Why first**: Orchestrator is single-writer; no merge conflicts to worry about. Proof that the event store works under real orchestrator load.
+
+**Changes**:
+1. Add `orchestrator_status` projector to `state_store/projections.py` (new file or extend existing).
+2. Orchestrator calls `api.append("orchestrator_status", "phase_changed", {...}, actor="orchestrator")` instead of git commits.
+3. Export job (`export_orchestrator_status()`) renders to a new `STATE.md` periodically (e.g., per-phase boundary) for git durability.
+4. Readers still read git; no behavior change yet.
+
+**Concurrency model**: Single orchestrator writer, many readers (dashboards, agents). No conflicts.
+
+**Git-authoritative?**: NO. `STATE.md` becomes a rendered snapshot, not source-of-truth. On recovery, orchestrator reads latest `STATE.md` but reconciles with `orchestrator_status` events to fill any gaps.
+
+### Phase 2: Dual-Read Tracker (MIDDLE CUTOVER)
+
+**What moves**: Tracker CRUD (item creation, updates, archives) writes to the event log. Readers read from either git or the live event log (both running simultaneously).
+
+**Why here**: Tracker is the most-read state; dual-read lets us test the event store under high read load while keeping git as a safety net.
+
+**Changes**:
+1. Add dual-read logic to tracker consumers: try `api.project("tracker")` first; fall back to git if the event store is unavailable.
+2. Tracker CRUD emitters (`create_item()`, `update_item()`, `archive_item()`) append events instead of mutating git.
+3. Keep the export job running: `export_tracker(api, state/tracker.json)` renders live projections back to git.
+4. Tests compare git and event-store projections; must match exactly (see tests line 165–179).
+
+**Concurrency model**: Multiple writers (agents creating/updating items), many readers. SQLite WAL + `BEGIN IMMEDIATE` handles concurrency safely.
+
+**Git-authoritative?**: NO. Event store is source-of-truth. Git is an export. Reconciliation required on recovery.
+
+### Phase 3: Flip Readers (CUTOVER COMPLETE)
+
+**What moves**: All readers flip to the event store; git becomes purely an audit trail.
+
+**Changes**:
+1. Remove dual-read fallback; all tracker reads go through `api.project("tracker")`.
+2. Remove git-read paths from dashboards, forensics, monitoring.
+3. Keep export jobs running for durability + review.
+
+**Concurrency model**: No change; SQLite WAL already supports N readers + 1 writer per connection.
+
+**Git-authoritative?**: NO. Event store is source-of-truth.
+
+---
+
+## Locking & Concurrency Model
+
+### Write path (multiple writers allowed)
+
+1. Caller: `api.append("tracker", "item_created", {"id": "x", ...}, actor="agent-1")`
+2. `StateAPI` delegates to `EventStore.append()`.
+3. `EventStore.append()` opens a new connection, sets `busy_timeout=5000` (wait up to 5 seconds if locked).
+4. Executes `BEGIN IMMEDIATE` (acquires write lock up front).
+5. Reads max version for the stream (e.g., currently 42).
+6. Inserts the new event with version 43.
+7. Commits (releases lock).
+8. Returns version 43.
+
+**Guarantee**: No two writers see the same max version. Two concurrent writers always get consecutive versions (43, 44) with no dupes or gaps.
+
+**Tested**: `tests/test_state_store.py::EventStoreTest::test_concurrent_appends_have_no_dupes_or_gaps` — two threads, 50 appends each, verified versions 1–100 are consecutive.
+
+### Read path (many readers in parallel)
+
+1. Caller: `api.project("tracker")`
+2. `StateAPI` gets all events: `store.read("tracker")`
+3. `EventStore.read()` opens a connection, sets `busy_timeout=5000`.
+4. Queries all events for the stream (ascending by version). In WAL mode, readers see a consistent snapshot (MVCC).
+5. Returns list of dicts.
+6. `project_tracker()` folds events into a projection (in-process, no DB access).
+
+**Guarantee**: Readers never block writers (WAL mode). Readers see a consistent snapshot at the moment they start the read. Dirty reads are impossible; serialization is guaranteed by SQLite's MVCC.
+
+### Snapshot coordination
+
+1. `project_tracker_with_snapshot()` reads the latest snapshot (one extra query).
+2. Folds only events after the snapshot version.
+3. If the snapshot is corrupt, falls back to full replay (graceful degradation).
+
+**Snapshot updates are asynchronous**: A background job can call `api._store.save_snapshot(stream="tracker", event_version=100, projection=...)` without blocking readers. The snapshot is just an optimization.
+
+---
+
+## What Stays Git-Authoritative (and Why)
+
+### 1. Durable Checkpoint History
+
+Git history (commit log, diffs, tags) remains **definitive for auditing and recovery**:
+
+- Each time an export job runs, it writes a new commit to git.
+- The commit hash anchors a specific version of all state streams.
+- On session restart, `git log --oneline` shows when state changed, who changed it, and why.
+- `git show <commit>` lets you see exactly what was decided at that moment.
+
+**Why not move to SQLite?** SQLite has no built-in diff/review/approval workflow. Code review, pull requests, and merge discipline are git patterns. For team scale, retaining git as the audit log preserves these workflows.
+
+### 2. Durability & Offline Safety
+
+SQLite stores state **in the working tree**, which may get wiped, corrupted, or lost.
+
+Git stores state **on remote servers** (GitHub, GitLab, etc.), which have redundancy, backups, and audit logs built in.
+
+**Recommendation**: Always run `export_tracker()` and `export_orchestrator_status()` jobs after each major state change. Push the exports to git. If the SQLite store is corrupted, `ingest_tracker_json(git_version)` reconstitutes it.
+
+### 3. Team Sync & Cross-Machine Continuity
+
+When a developer or orchestrator switches machines or sessions:
+
+1. Clone/pull the repo (gets the latest git state).
+2. Reconstitute the event store: `ingest_tracker_json(api, state/tracker.json)` (tests line 165–179).
+3. Continue from there.
+
+**Why this works**: The ingest path is idempotent (see `state_store/ingest.py` line 14–41). Running it twice on the same events is a no-op (second run has no items to ingest, since they're already in the event log).
+
+### 4. Configuration & Secrets
+
+Aesop configuration (aesop.config.json, credentials, API keys) **does NOT go in state streams**. These remain git-ignored and managed separately.
+
+Event payloads must not include secrets (enforced at the append call site, not in the store).
+
+---
+
+## Multi-Writer Concurrency: Measured (2026-07-18)
+
+**Multi-writer safety is now verified under production load.** A concurrent-writer stress test (4 writer processes, 5s duration, WAL mode + `busy_timeout=5000` + `BEGIN IMMEDIATE`) appended 800 events across the tracker stream with zero dupes, zero gaps, zero "database is locked" failures. Measured throughput: ~704 events/sec. All projections converged (consistent state). This moves multi-writer support from "design" to "validated."
+
+---
+
+## Not Yet Built
+
+### 1. **Orchestrator Reader/Writer Integration**
+
+Currently, the orchestrator only writes to git (STATE.md). To move to the event store:
+
+- Orchestrator `phase_changed` → write to stream `"orchestrator_status"` instead of STATE.md
+- Orchestrator `next_steps_updated` → append event instead of git commit
+- Orchestrator recovery: read `api.project("orchestrator_status")` to bootstrap phase + next steps
+
+**Effort**: ~1 sprint. Touch: `skills/power/*, monitor/` event loop, orchestrator dispatch template.
+
+### 2. **Dashboard Real-Time Subscription**
+
+Currently, dashboards query the git export (STATE.md, tracker.json). For real-time updates:
+
+- Add `subscribe(stream: str, callback)` to StateAPI
+- Implement with SQLite's FTS/updates or a simple file-watch on the .db-wal file
+- Dashboard websocket sends live updates to browsers
+
+**Effort**: ~1 sprint. Touch: `ui/`, `state_store/api.py`.
+
+### 3. **Team-Shared Database Setup**
+
+The current design assumes a **local SQLite file** (filesystem-shared at best). For a true team:
+
+- Backend swap: `StateAPI` points to Postgres instead of SQLite (seamless; only `api.py` changes).
+- Setup: Postgres server, connection pooling, schema migration job.
+- Tuning: Query optimization for high read/write load.
+
+**Effort**: ~2 sprints. Mostly infrastructure/testing; application code is abstracted.
+
+### 4. **Reconciliation & Conflict Resolution**
+
+If two teams merge their state stores (e.g., two subagent fleets run independently, then reconcile):
+
+- **Event deduplication**: No duplicate event ids; version numbers are per-stream (don't collide between stores).
+- **Metadata tagging**: Each event carries an `actor` and `ts` (timestamp); reconciliation can detect/log conflicts.
+- **Projection idempotence**: Refolding events is deterministic; the projection will converge to the same state.
+
+**Current support**: `actor` field in every event. Reconciliation logic is **not yet implemented** (would live in `state_store/reconcile.py` or a separate tool).
+
+**Effort**: ~1–2 sprints, depending on conflict resolution strategy (append-only, last-write-wins, domain-specific merge).
+
+### 5. **Model-Dispatch Correlation**
+
+The orchestrator needs to correlate which Haiku agent was given which backlog item and track per-item cost/success.
+
+**Current event schema**: `orchestrator_status` events can carry item assignments, but **no current mechanism to append per-item traces** (which agent, which LLM, cost, tokens, result).
+
+**Needed**:
+- New stream: `"agent_traces"` with events like `agent_dispatched`, `agent_completed`, `agent_failed`.
+- Agent brief template includes event-append credentials (stream + actor).
+- Aggregation job correlates agent traces + cost logs + PR outcomes.
+
+**Effort**: ~1–2 sprints. Touch: `dispatch template`, `monitor/`, cost logger.
+
+---
+
+## Guarantees & Semantics
+
+### Atomicity
+
+Each `append()` call is atomic: either the event is inserted (and you get a version back) or it fails (exception). No partial writes.
+
+Example:
+```python
+version = api.append("tracker", "item_created", {"id": "x", "title": "Y"}, actor="agent-1")
+# version is now 43 (for stream "tracker")
+# event is durable; will survive process restart
+```
+
+### Consistency
+
+The event log is append-only; once an event is inserted, it never changes. The projection is deterministic: folding the same events always yields the same result.
+
+Example:
+```python
+events_1 = api.get("tracker")  # [v1, v2, v3]
+proj_1 = project_tracker(events_1)
+
+# Later:
+events_2 = api.get("tracker")  # [v1, v2, v3, v4, v5]
+proj_2 = project_tracker(events_2)
+
+# proj_2 differs from proj_1 only by v4+v5's changes (if any)
+```
+
+### Isolation
+
+Readers see a consistent snapshot (SQLite MVCC). No dirty reads. Concurrent writes are serialized by `BEGIN IMMEDIATE`.
+
+Example:
+```python
+# Thread 1: reader
+snapshot_1 = api.get("tracker")  # sees [v1..v50]
+
+# Thread 2: writer (concurrent)
+v51 = api.append(...)  # inserts v51
+
+# Thread 1: reader (still sees [v1..v50], consistent snapshot)
+snapshot_1  # unchanged; snapshot_1 is immutable
+```
+
+### Durability
+
+Events are flushed to disk (SQLite journal + WAL file). On process restart, all events from the last committed transaction are recovered.
+
+Example:
+```python
+version = api.append("tracker", "item_created", {...})  # returns 43, durable
+# If process crashes here, event v43 is still there on next start
+```
+
+### Idempotence (Export Fidelity)
+
+The `ingest_tracker_json()` + `project_tracker()` + `export_tracker()` round-trip preserves item fidelity: ingesting a tracker.json and exporting the projection reproduces the same items.
+
+Tested in `tests/test_state_store.py::ApiAndExportTest::test_ingest_project_export_round_trips_real_tracker`:
+
+```python
+original = json.loads("state/tracker.json")
+api.ingest_tracker_json("state/tracker.json")
+projected = api.project("tracker")
+assert projected["items"] == original["items"]  # exact match
+```
+
+---
+
+## File Organization
+
+**Event store layer** (new):
+- `state_store/store.py` — SQLite WAL append-only event log.
+- `state_store/projections.py` — Fold events into tracker state.
+- `state_store/api.py` — StateAPI facade (append/get/project).
+- `state_store/export.py` — Render projections to git-tracked JSON.
+- `state_store/ingest.py` — Backfill events from existing JSON.
+- `state_store/__init__.py` — Public exports.
+
+**Tests** (new):
+- `tests/test_state_store.py` — EventStore + projection + round-trip tests.
+- `tests/test_state_store_snapshots.py` — Snapshot save/load fidelity.
+- `tests/test_state_store_hardening.py` — Concurrency, corruption recovery.
+- `tests/test_api_state.py` — StateAPI facade tests.
+
+**Git exports** (existing, to be extended):
+- `state/tracker.json` — Current tracker state (now an export, not source-of-truth).
+- `STATE.md` — (Will become an export; currently single-writer orchestrator file.)
+- `BUILDLOG.md` — (Will be merged into event streams; currently append-only progress log.)
+
+---
+
+## Deployment Checklist (for future waves)
+
+- [ ] **Wave N+1**: Add `orchestrator_status` stream to `state_store/projections.py`.
+- [ ] Orchestrator transition: phase/next-steps writes to event store (no git commits).
+- [ ] Export job: periodically render `orchestrator_status` → `STATE.md` for git durability.
+- [ ] Dashboard: read `api.project("orchestrator_status")` + git for fallback.
+- [ ] Tests: verify orchestrator recovery from event stream (not git) works.
+
+- [ ] **Wave N+2**: Tracker dual-read.
+- [ ] Tracker CRUD: write events instead of git.
+- [ ] Add dual-read logic: try event store, fall back to git.
+- [ ] Export job: `export_tracker()` keeps `state/tracker.json` in sync.
+- [ ] Tests: compare git + event-store projections; they must match.
+
+- [ ] **Wave N+3**: Flip readers.
+- [ ] Remove dual-read fallback.
+- [ ] All reads go through `api.project()`.
+- [ ] Git becomes audit trail only.
+
+- [ ] **Wave N+4**: Postgres backend (optional, depends on team scale).
+- [ ] Postgres schema + migration job.
+- [ ] Backend swap in `StateAPI.__init__()`.
+- [ ] Load testing + performance tuning.
+
+---
+
+## References & Code Citations
+
+All design claims are grounded in actual implementation:
+
+- **Concurrency safety**: `state_store/store.py` lines 30–94 (BEGIN IMMEDIATE + busy_timeout).
+- **Snapshot replay**: `state_store/projections.py` lines 84–114 (project_tracker_with_snapshot).
+- **Tracker projection**: `state_store/projections.py` lines 25–81 (event folding logic).
+- **Round-trip fidelity**: `tests/test_state_store.py` lines 165–179 (ingest + project + export test).
+- **Concurrent append test**: `tests/test_state_store.py` lines 90–108 (two threads, no dupes).
+- **API facade**: `state_store/api.py` lines 15–35 (StateAPI.project seam for backend swaps).
+
+See `state_store/CLAUDE.md` for domain-specific setup and next steps.

package/docs/reproduce.md

@@ -1,6 +1,21 @@
 # Reproducing Aesop
 
-This document explains how to reproduce the project's claims from a clean checkout.
+This document explains how to reproduce the project's claims from a clean checkout or installed package.
+
+## Quick Start: One-Command Verification
+
+Run the verification suite with automatic context detection:
+
+```bash
+aesop reproduce
+```
+
+This command automatically detects your context (repository checkout or installed package) and runs the appropriate test suite:
+
+- **Repository checkout**: Runs the full test suite (Node syntax, shell syntax, Node tests, Python tests, benchmark, browser proofs)
+- **Installed package**: Runs shipped self-checks (preflight checks, health score, secret-scan selftest, packaging assertions)
+
+Output includes per-step timing and a clear pass/fail summary. Exit code 0 = all checks passed.
 
 ## Overview
 
@@ -55,20 +70,35 @@ Both can be reproduced entirely offline, without API keys or external dependenci
    python tools/bench_runner.py --runner mock
    ```
 
-## What the `.github/workflows/reproduce.yml` Job Does
+## CI Equivalence: aesop reproduce vs. GitHub Actions
 
-The `reproduce` workflow in GitHub Actions automates the above steps:
+The `aesop reproduce` command mirrors `.github/workflows/reproduce.yml` for local execution.
+
+### GitHub Actions Workflow (`reproduce.yml`)
+
+The `reproduce` workflow in GitHub Actions automates testing:
 
 1. **Fresh checkout**: Uses a clean clone (no state reuse from other CI jobs)
 2. **Syntax checks**: Validates all Node.js (.mjs) and shell scripts (.sh)
 3. **Node.js tests**: Runs the full test suite with `npm run test:node`
 4. **Python tests**: Runs the full test suite with `python -m unittest discover`
 5. **Benchmark scorer**: Proves the offline mock benchmark reproduces (no external API calls)
+6. **Browser proofs**: Validates UI components with Playwright
 
 The workflow is triggered:
 - **Manually**: Via GitHub Actions "Run workflow" button (workflow_dispatch)
 - **Weekly**: Every Sunday at 2:00 AM UTC (schedule)
 
+### Local Reproduction
+
+To run the same tests locally from a clean clone:
+
+```bash
+aesop reproduce
+```
+
+This produces the same verification steps and provides immediate feedback before pushing.
+
 ## What Is and Isn't Reproduced
 
 ### Reproduced (offline, no API keys needed)

package/driver/CLAUDE.md

@@ -0,0 +1,150 @@
+# driver/ — AgentDriver backend-portability seam
+
+**What**: the domain contract letting aesop's wave loop run on non-Claude backends
+(Codex, open models); the loop dispatches only through the `AgentDriver` interface.
+**Phases 1-3 shipped** (interface + reference adapter; Codex Chat Completions; wave bridge).
+
+## Files
+
+- **agent_driver.py** — the `AgentDriver` ABC + capability/request/result
+  dataclasses. The contract. stdlib-only, no provider SDKs.
+- **claude_code_driver.py** — reference adapter (Claude Code parity). Thin +
+  documented: two ops are concrete Python, three are serviced by the harness.
+- **codex_driver.py** — Phase 2 IMPLEMENTATION: OpenAI Chat Completions HTTP
+  backend. Fully wired: dispatch_worker (file injection, JSON validation with
+  retry, full-file replacement), run_command (subprocess), worker_status
+  (in-memory registry), get_tokens_spent (aggregate usage). Transport injectable
+  for offline testing.
+- **openai_transport.py** — stdlib urllib transport for OpenAI Chat Completions
+  endpoint. Injectable seam so tests feed canned responses (FakeTransport) with
+  no API key or network.
+- **openai_compatible_driver.py** — OpenAI-compatible backend (Ollama, OpenRouter, etc.).
+- **verification_policy.py** — Maps verification tier -> orchestrator tuning (validate_all_json,
+  spot_check_frac, repair_cap, require_adversarial_review).
+- **wave_loop.py** — the wave ENGINE: preflight ownership guard, parallel build,
+  bounded repair, adversarial review, per-repo batched git ship, recovery journal.
+- **wave_bridge.py** — Phase 3: bridges AgentDriver backends to wave manifest items.
+  build_manifest_item() enriches with verificationTier + model; dispatch_item() routes
+  by capability and decides green ONLY from test exit code (not model's say-so).
+- **backend_config.py** — Per-deployment model resolution (role → model id, API key/base URL).
+- **README.md** — the abstraction, the phased roadmap, the verification thesis.
+- **../tests/test_agent_driver.py** — the contract's test suite.
+- **../tests/test_codex_driver_e2e.py** — Phase 2 end-to-end offline tests
+  (FakeTransport, red-to-green verification, retry logic, ownership enforcement)
+  + gated live test (AESOP_CODEX_LIVE env var).
+- **../tests/test_wave_bridge.py** — Phase 3 offline e2e (honest green: exit 0 only).
+  no network). Tests: manifest building, routing, fail-safe, ownership enforcement,
+  headline test (red stub + FakeTransport fix + test pass -> ok=True).
+
+## The five operations (what the wave loop needs from ANY backend)
+
+1. `probe_capabilities() -> DriverCapabilities` — honest self-report (parallel?
+   filesystem? shell? structured output? worktree? cost tracking? accuracy? →
+   recommended verification tier). Read once; everything keys off it.
+2. `dispatch_worker(request) -> WorkerResult` — spawn ONE isolated worker over a
+   prompt + owned_files + workdir; the worker may read/write files, run a shell
+   command, and return a **structured** result (extent reported by the probe).
+3. `worker_status(worker_id) -> WorkerStatus` — liveness / stall detection for
+   the watchdog.
+4. `run_command(command, cwd, shell) -> CommandResult` — ORCHESTRATOR-side
+   command execution (tests, git, verification). Distinct from a worker shell.
+5. `resolve_model(role) -> str` — map an abstract role (`worker`/`setup`/
+   `verify`) to a concrete backend model id.
+
+Optional (non-abstract): `get_tokens_spent()`.
+
+## Invariants
+
+- The wave loop calls **only** `AgentDriver` methods — never `agent()`,
+  `parallel()`, Read/Write/Bash tools, or `budget.spent()` directly. That is
+  the seam.
+- `probe_capabilities()` must be **honest**. Defaults are conservative (no
+  native abilities, accuracy 0.0, tier 4) — optimism is opt-in, never default.
+- **Weaker workers → higher verification tier.** Lower `tool_use_accuracy`
+  raises `recommended_verification_tier`. Cheaper/weaker backends RAISE the
+  orchestrator's burden; they do not lower it.
+- Unknown roles in `resolve_model()` fall back to the worker model — a mis-typed
+  role can never silently escalate cost.
+- stdlib-only (`abc`, `dataclasses`, `typing`, `subprocess`), ASCII-only,
+  Windows + Linux safe. Concrete adapters own any provider SDK, not this layer.
+
+## Per-backend capability matrix (as encoded)
+
+| Capability            | claude-code  | codex (Phase 2)       |
+|-----------------------|:------------:|:---------------------:|
+| parallel_dispatch     | yes          | no (ext loop)         |
+| worker filesystem     | yes          | no (orch injects)      |
+| worker shell          | yes          | no (orch runs)         |
+| structured_output     | yes (~perfect)| yes (JSON schema)      |
+| worktree_isolation    | yes          | no (temp-dir)         |
+| native_cost_tracking  | yes          | yes (usage metadata)   |
+| tool_use_accuracy     | ~0.99        | ~0.92                 |
+| verification_tier     | 1            | 2                     |
+
+## Phase 2 Codex Implementation Details
+
+Codex driver (Tier 2): injects file contents into prompt, calls OpenAI Chat Completions via injectable transport, validates JSON with bounded retry, enforces ownership. CRITICAL: Green = exit 0 only. Verification policy: tier 2 -> {validate_all_json:True, spot_check_frac:0.50, repair_cap:2, require_adversarial_review:True}. **P1 Security**: Default model map uses gpt-4o-mini (worker, supports json_schema); init-time guard rejects models lacking json_schema support unless `allow_unverified_models=True` (P1 gate: prevent gpt-3.5-turbo silent failures).
+
+## Phase 3 Bridge Implementation Details
+
+Connects AgentDriver backends to wave-flat-dispatch manifest items; verification
+tier is driven by backend capability, not config.
+
+**build_manifest_item(driver, item) -> dict**: enriches a backlog item with model
+(driver.resolve_model), verificationTier (probe), and the four policy knobs from
+verification_policy(caps) — RESOLVED ONCE, carried as literal manifest fields so the
+template cannot recompute/drift; tier-1/Claude path stays byte-identical (repairCap=1,
+requireAdversarialReview=false, spotCheckFrac=0.10, validateAllJson=false).
+
+**dispatch_item(driver, item) -> dict**:
+- Routes by worker_filesystem_access: True→{route:'harness'}; False→orchestrator-managed
+  (dispatch_worker + run_command test). Returns {route, ok, testExit, filesWritten, verified, ...}.
+- HONESTY: Green (ok=True) ONLY on test exit 0; never from model's done:true. No testCmd
+  → unverified (ok=False, verified=False, reason='no_test_command'): "no test" ≠ "verified."
+- Fail-safe: exception → ok=False, verified=False. Ownership at driver level.
+
+**Tests**: prove a non-Claude backend (Codex + FakeTransport) takes a RED unittest
+stub, applies a fix, runs the test, and returns ok=True ONLY because the test passed
+(exit 0). All offline, no API key, no network.
+
+## Wave Scheduler (WS3a Pilot) + GATE-1 Handoff Kit
+
+**wave_scheduler.py** — single-cycle backlog orchestration: intake up to N file-disjoint todo items from tracker.json (empty/missing ownsFiles REJECTED; paths normalized posix+casefold-on-Windows before overlap checks; required fields pre-validated) -> manifest via build_manifest_item (model + verificationTier from driver.probe) -> HALT + cost-ceiling gates (fail-CLOSED: module import failure or check exception = abort with honest Report, phase=gate_unavailable) -> run_wave (recovery journal + git ship) -> STOP before merge; Report JSON with per-item observability (GATE-1). After ship, selected items atomically marked in_progress in tracker (temp+os.replace; dry-run never mutates) so a second run cannot double-dispatch.
+
+**CLI** (GATE-1): `python driver/wave_scheduler.py --tracker <path> --max-items N --dry-run|--execute --driver claude|codex` (default: claude). For codex+execute, requires OPENAI_API_KEY env var; dry-run works without it.
+
+**Tests** (35+): disjoint/normalization/rejection, gate fail-closed, dry-run, GATE-1 per-item/driver/ceiling/codex tests; module-tmpdir hygiene; all TestCase.
+
+**Invariants**: stdlib-only, ASCII, Windows+Linux safe (list-form subprocess); manifest items carry resolved policy knobs from verification_policy (no recompute drift); merge stays manual in the pilot.
+
+### REPORT-CONTRACT (GATE-1 Orchestrator Handoff)
+
+The scheduler emits a Report JSON consumed by the orchestrator to decide merge eligibility:
+```
+{
+  "phase": "dispatch"|"intake"|"halt"|"ceiling"|"gate_unavailable"|"manifest",
+  "wave_id": "<uuid>",
+  "items_selected": ["id1", "id2"],  // IDs selected for this wave
+  "items_shipped": [
+    { "slug": "feat/x", "backend": "claude-code|codex", "tier": 1|2|3|4, "verified": true|false (false = NOT PROVEN, not necessarily failed; tier null = no build record), "testExit": 0|1|null },
+    ...
+  ],
+  "merged": false, "tracker_update_attempted": true|absent, "tracker_unmapped_slugs": [..]|absent (LOUD -> success false),  // pilot always false (manual merge)
+  "success": true|false,
+  "timestamp": "<ISO8601>",
+  "branch": "<branch_name>",  // optional; set when ship succeeds
+  "sha": "<git_sha>",  // optional; set when ship succeeds
+  "halt_reason": "...",  // optional; set if halted
+  "ceiling_reason": "...",  // optional; ceiling exceeded before dispatch (abort-before-dispatch only)
+  "error": "..."  // optional; unexpected error
+}
+```
+Ceiling semantics: checked BEFORE run_wave dispatch (phase=ceiling, ceiling_reason populated). Mid-wave ceiling trips are run_wave's responsibility. items_shipped[] carries per-item observability: slug, backend (driver name), tier (verificationTier), verified (from test exit 0), testExit (test command exit code or null if not run).
+
+## Status
+
+- **Phase 1**: shipped. Interface + Claude reference adapter + contract tests.
+- **Phase 2**: shipped. Codex OpenAI Chat Completions implementation. Offline tests GREEN.
+- **Phase 3**: shipped. Wave bridge: driver → manifest, orchestrator-side dispatch.
+  Proves non-Claude backends drive items end-to-end with honest green (test exit 0 only).
+- **Wave Scheduler (WS3a) + GATE-1**: shipped. Single-cycle orchestration: intake → manifest → dispatch → report (manual merge). Per-item observability, driver injection (--driver claude|codex), ceiling semantics documented.