@matt82198/aesop 0.2.0 → 0.3.1

package/docs/PORTING.md

@@ -0,0 +1,166 @@
+# Porting Aesop to Your Repository
+
+Guide for adopters porting the orchestration harness to a foreign repo. Step-by-step with prerequisites, scaffold, config, and the 10 likeliest failure modes from real deployments.
+
+---
+
+## Prerequisites
+
+Ensure you have:
+- **Node.js** ≥18 (from `package.json`, `.nvmrc`: v18.20.5)
+- **Python** ≥3.10 (for daemons, health checks, secret-scan)
+- **Git** ≥2.40 (worktree + pre-push hooks)
+- **Bash** v4+ (or Git Bash on Windows)
+- **Optional**: Playwright (for UI verification testing); jq (for dashboard JSON)
+
+Check versions:
+```bash
+node --version && python3 --version && git --version && bash --version
+```
+
+### OS Notes
+- **Windows**: Use Git Bash for all shell commands; paths use `/c/Users/...` POSIX style
+- **Linux/macOS**: Standard Bash; ensure `/usr/bin/bash` or equivalent exists
+
+---
+
+## 1. Scaffold & Install
+
+### Step 1: Create your harness
+```bash
+npx @matt82198/aesop my-fleet \
+  --name "my-project" \
+  --repos "/path/to/repo1,/path/to/repo2"
+```
+
+Creates `my-fleet/` with daemons, skills, config, and UI.
+
+### Step 2: Copy skills to Claude Code home
+```bash
+cp -r my-fleet/skills/power ~/.claude/skills/power
+cp -r my-fleet/skills/buildsystem ~/.claude/skills/buildsystem
+```
+
+### Step 3: Configure & test
+Edit `my-fleet/aesop.config.json`:
+```json
+{
+  "backend": "claude",
+  "aesop_root": "/path/to/my-fleet",
+  "brain_root": "~/.claude",
+  "repos": [
+    { "path": "/path/to/repo1", "name": "my-project" }
+  ],
+  "dashboardPort": 8770
+}
+```
+
+Test dashboard backend (Ollama example):
+```json
+{
+  "backend": "openai-compatible",
+  "base_url": "http://localhost:11434/v1",
+  "model": "mistral",
+  "is_local": true
+}
+```
+
+### Step 4: Install pre-push hook
+```bash
+mkdir -p my-fleet/.git/hooks
+cp my-fleet/hooks/pre-push-policy.sh my-fleet/.git/hooks/pre-push
+chmod +x my-fleet/.git/hooks/pre-push
+```
+
+### Step 5: Verify with health check
+```bash
+cd my-fleet
+python tools/health_score.py
+```
+Expected output: All checks ✓; port 8770 available; git hooks installed.
+
+---
+
+## 2. First `/power`, First Wave
+
+Run the orchestrator once to prime the brain:
+```bash
+cd my-fleet
+/power
+```
+Expected output: State created (STATE.md, BUILDLOG.md, .watchdog-heartbeat).
+
+Run one complete wave:
+```bash
+/buildsystem --one-turn
+```
+Expected verdicts: All items "PASS" or "REVIEW"; zero code defects. Health score should report ≥85/100.
+
+---
+
+## 3. The 10 Likeliest Failure Modes
+
+Each: symptom → cause → fix.
+
+### 1. Secret-scan blocks legit push
+- **Symptom**: `git push` fails: "secret detected" but code has no real secret
+- **Cause**: Test fixtures with dummy secrets (credit card, API key patterns) are parsed as real
+- **Fix**: Assemble secrets at runtime: `"key" + "_" + "123"` not `"key_123"`; use `---` delimiters in comments. Secret-scan only scans staged files, not .git.
+
+### 2. Worktree isolation violated
+- **Symptom**: Editing feature branch X; changes also appear in primary tree
+- **Cause**: Agents not using isolated worktrees; sharing same `.git/index`
+- **Fix**: Each agent task must use `git worktree add ../wt-item-slug -b feature/item-slug origin/main`; verify with `git worktree list`
+
+### 3. Heartbeat stale/missing
+- **Symptom**: Watchdog won't start; error: "unreadable state dir" or "stale heartbeat"
+- **Cause**: `state/.watchdog-heartbeat` missing/corrupted or directory unreadable (permissions)
+- **Fix**: `rm -f state/.watchdog-heartbeat && bash daemons/run-watchdog.sh --once` (re-creates it)
+
+### 4. Port 8770 conflict
+- **Symptom**: `python ui/serve.py` fails: "Address already in use"
+- **Cause**: Old dashboard process still bound, or another service using port 8770
+- **Fix**: `lsof -i :8770 | grep -v PID | awk '{print $2}' | xargs kill -9` (Mac/Linux); Windows: `netstat -ano | grep 8770`, kill the PID. Or change `dashboardPort` in config.
+
+### 5. Git identity placeholder
+- **Symptom**: Pre-push hook fails: "user identity invalid"; commits fail
+- **Cause**: Git config has template defaults (e.g., "John Doe") instead of your name
+- **Fix**: `git config user.name "Your Name" && git config user.email "you@example.com"`
+
+### 6. CRLF line endings corrupt scripts
+- **Symptom**: Bash script fails: "command not found" at line 50 (but line 50 exists)
+- **Cause**: Editor/Windows converted LF to CRLF; bash reads `\r` as part of command
+- **Fix**: `git config core.autocrlf false` locally; convert file: `dos2unix daemons/run-watchdog.sh`
+
+### 7. Test count drift in CI
+- **Symptom**: Health-check fails: "expected 127 tests, got 128"
+- **Cause**: Added new test file but didn't update baseline in tools/health_score.py or CI config
+- **Fix**: Run `python tools/health_score.py --json` to get true count; update baseline in CI gate
+
+### 8. UTF-8 encoding on Windows
+- **Symptom**: Pre-publish gate fails with encoding error in secret_scan.py
+- **Cause**: Python opens files in system encoding (cp1252) instead of UTF-8
+- **Fix**: Aesop tools now force UTF-8 internally; ensure `PYTHONIOENCODING=utf-8` if running external Python scripts
+
+### 9. Cost ceiling never triggers
+- **Symptom**: Cost ceilings configured; spending uncapped; halt never fires
+- **Cause**: Claude Code driver returns `get_tokens_spent()=None`; coerces to 0; ledger fallback skipped
+- **Fix**: For Claude Code, cost tracking integrates live API; for non-Claude backends, ledger fallback logs at end of wave
+
+### 10. Hook TTY behavior blocks CI pushes
+- **Symptom**: `git push` fails in CI/cron: "cannot read stdin"; interactive prompt hangs
+- **Cause**: Hook tries to detect TTY when stdin is `/dev/null` (non-interactive context)
+- **Fix**: Hook now handles empty stdin (rc=2 for delete-only, skip scan + log); use `hooks/pre-push-policy.sh --test` in CI (no-op validation)
+
+---
+
+## Next Steps
+
+1. **Read [INSTALL.md](./INSTALL.md)** — Full setup and environment variables
+2. **Run [health_score.py](../tools/health_score.py)** — Continuous readiness checks
+3. **Explore the [README](../README.md)** — Demo walkthrough and proof numbers
+4. **For troubleshooting**, check [GOVERNANCE.md](./GOVERNANCE.md) or open an issue on GitHub
+
+---
+
+**License**: PolyForm Strict 1.0.0 (source-available, noncommercial). See [LICENSE](../LICENSE) for details.

package/docs/TEAM-STATE.md

@@ -1,203 +1,35 @@
-# Team-Shared State: Architecture & Migration
+# Team-Shared State: Current & Future Architecture
 
-**Status**: Design document. Prototype complete (`state_store/` SQLite module shipped). Migration path defined. NOT YET INTEGRATED into orchestrator reader/writer paths.
+**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.
 
 ---
 
-## Problem Statement
+## Current State Model (Git-as-Checkpoint)
 
 Aesop currently stores orchestration state in **two git-tracked files**:
-- `STATE.md` — intent, decisions, phase, NEXT STEPS (single-writer orchestrator)
-- `BUILDLOG.md` — append-only progress snapshots (agents append one line per work unit)
 
-This works **for single-user/single-orchestrator** workflows but does not scale to teams:
+- **STATE.md** — Orchestrator intent, decisions, phase, and NEXT STEPS (single-writer)
+- **BUILDLOG.md** — Append-only progress snapshots (agents append one line per work unit)
 
-1. **Hot-file merge conflicts** — Multiple agents appending to the same files requires rebasing and re-coordination; a team of 3+ users editing these simultaneously causes conflicts.
-2. **No transactions/concurrency** — Git has no concept of atomic multi-file updates or per-agent locks; coordination is manual and error-prone.
-3. **No real-time status** — Readers must `git fetch` to see the latest state; no subscription/push model for live updates.
-4. **Single-writer bottleneck** — The orchestrator is the only writer to STATE.md; other workers cannot safely report their own state.
+**Why it works**: Single-instance is proven. State survives machine wipes, resync on session restart, human-diffable for review and forensics.
 
----
-
-## Current Truth: Git-as-State (Single-Instance)
-
-### Data model
-
-State lives as **human-readable JSON** in two git-tracked files:
-
-```
-orchestrator (Fable/Opus) ←→ STATE.md (single-writer, locked decisions + phase + NEXT STEPS)
-                          ←→ BUILDLOG.md (append-only, agents append one line per work unit)
-                          
-↓ (read-only consumers)
-
-dashboards, monitoring, forensics
-```
-
-**Invariants**:
-- Only the orchestrator writes to STATE.md (enforced by discipline, not by code)
-- BUILDLOG.md is append-only; orchestrator never rewrites earlier entries
-- All state is human-diffable (intentional — enables review, forensics, inheritance)
-- Durability via git: push after each update, recover from `git log` on session restart
-- Git is the **source of truth** for current state
-
-### Limitations for team scale
-
-- **No concurrent writers** — Two orchestrators or agents trying to write simultaneously causes merge conflicts
-- **No transactions** — A phase update + next-steps change is two separate commits, not atomic
-- **High latency** — State changes require `git push`; observability is on a push-frequency, not real-time
-- **No locking** — State can be read/modified while orchestrator is deciding; no optimistic concurrency
-- **No history/events** — Only final state (current file contents) is stored; intermediate states are lost
+**Limitation**: Does not scale to teams—no concurrent writers, no transactions, high latency (requires `git push`).
 
 ---
 
-## Target: SQLite WAL as Live Substrate, Git as Export
-
-### Proposed data model
+## Future: SQLite Event Log + Git Export
 
-```
-orchestrator/agents write events ─→ SQLite WAL event log (LIVE substrate, fast, transactional)
-                                 ↓
-                            state_store/ EventStore
-                            (append() atomic across processes/threads)
-                                 ↓
-                            [snapshots for O(n) tail-replay]
-                                 ↓
-                            projections/StateAPI (project tracker state)
-                                 ↓
-export_tracker() ─────────→ STATE.md / BUILDLOG.md (git-tracked EXPORT, human-diffable, immutable)
-                                 ↓
-                            [dashboards, monitoring, forensics read git export]
-```
-
-### Key design principles
-
-1. **Event sourcing**: State is a fold of immutable events, not mutable files. Each write is a single `append(stream, event_type, payload, actor)` call — atomic, ordered, versionable.
-
-2. **Append-only**: No deletes or mutations. History is preserved forever. Replayability + auditing for free.
-
-3. **Per-stream versioning**: Each "stream" (e.g., `"tracker"`, `"orchestrator_status"`) has its own 1-based, gapless version. Enables deterministic snapshots and tail-replay (see `state_store/store.py` line 81–92 and `state_store/projections.py` line 117–127).
-
-4. **Concurrency-safe writes**: SQLite WAL mode + `BEGIN IMMEDIATE` transactions guarantee that two writers on the same file never collide or duplicate a version (see `state_store/store.py` line 30–94). Tested in `tests/test_state_store.py::EventStoreTest::test_concurrent_appends_have_no_dupes_or_gaps`.
-
-5. **Snapshots for O(n) tail-replay**: Instead of replaying all events on every read, save materialized state snapshots at key versions; future replays fold only newer events (see `state_store/store.py` line 130–196 and `state_store/projections.py` line 84–114).
-
-6. **Git as export, not source**: The SQLite store is the system-of-record. `export_tracker(api, out_path)` renders the current projection back to human-readable JSON for git durability and review (see `state_store/export.py`). Git is now **read-only for state** (except for manual edits, which become new events on next `ingest_tracker_json`).
-
-7. **Projection-based readers**: Callers do not query the raw event log; instead, they call `api.project(view)` to get the current state as a dict. New projections (e.g., `project_orchestrator_status`) can be registered in `state_store/api.py` without changing the event store (see line 12–35).
-
----
+**Vision**: Event-sourced SQLite WAL becomes the system-of-record. Git exports are rendered from current projections for durability and review.
 
-## Architecture: The Three Layers
+**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
 
-### 1. Event Store (SQLite WAL)
+**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).
 
-**File**: `state_store/store.py`
-
-**Class**: `EventStore(db_path)`
-
-**Public API**:
-- `append(stream: str, event_type: str, payload: dict, actor: str = "system") -> int` — Append one event, return its per-stream version. Atomic: multiple writers see no dupes or gaps (tests line 90–108).
-- `read(stream: str) -> list` — All events in a stream, ascending by version. Returns list of dicts with `{"id", "ts", "actor", "stream", "type", "payload", "version"}`.
-- `read_all() -> list` — All events across all streams, ascending by global id.
-- `save_snapshot(stream: str, event_version: int, projection: dict) -> None` — Persist a materialized projection at a specific version (line 130–153).
-- `read_snapshot(stream: str) -> tuple | None` — Read the most recent snapshot; returns `(event_version, projection_dict, checksum)` or None (line 155–197).
-
-**Concurrency model**:
-- Multiple writers: `BEGIN IMMEDIATE` locks the write lock up front, so read-max-version-then-insert is atomic (line 80).
-- Multiple readers: SQLite WAL mode allows readers to run concurrently with writers on separate .db-wal shadow files (no blocking).
-- Process/thread-safe: each `append()` call opens its own connection; `busy_timeout=5000` (5 seconds) waits if the DB is locked (line 32–94).
-- Tested with two threads, each with its own EventStore instance, appending 100 events concurrently with no dupes (tests line 90–108).
-
-### 2. Projections (Fold Events into State)
-
-**File**: `state_store/projections.py`
-
-**Functions**:
-- `_fold_events(events, order=None, items=None) -> (order, items)` — Fold events into an accumulated state tuple. Mutates order + items in place. Helper used by both full and snapshot-aware projections (line 25–71).
-
-- `project_tracker(events: list) -> dict` — Original full-replay projection: fold all events → `{"version": 1, "items": [items in first-seen order]}`. Defines tracker event schema:
-  - `item_created` (payload = full item dict): establishes item, kept in first-seen order
-  - `item_updated` (payload = `{"id": ..., ...partial fields}`): merges partial fields onto existing item
-  - `item_archived` (payload = `{"id": ...}`): sets `status` to `"archived"`, optionally merges `completed_at`
-  - Unknown event types: ignored (line 74–81).
-
-- `project_tracker_with_snapshot(store, stream: str, events: list) -> dict` — Snapshot-aware projection: load latest snapshot; fold only tail events (after snapshot version) for O(n) tail-replay. Falls back to full replay if snapshot is missing or corrupt (line 84–114).
-
-- `save_snapshot(store, stream: str, event_version: int, projection: dict) -> None` — Wrapper over `store.save_snapshot()` (line 117–126).
-
-**Event schema for tracker**:
-```json
-{
-  "type": "item_created",
-  "payload": {"id": "abc", "title": "...", "lane": "proposed", "status": "todo", ...}
-}
-{
-  "type": "item_updated",
-  "payload": {"id": "abc", "lane": "in-progress"}
-}
-{
-  "type": "item_archived",
-  "payload": {"id": "abc", "completed_at": "2026-07-17T...Z"}
-}
-```
-
-Tolerance: unknown ids on update/archive are ignored (no error); unknown event types are skipped (line 62–70).
-
-### 3. Facade API (Single Seam for Backend Swaps)
-
-**File**: `state_store/api.py`
-
-**Class**: `StateAPI(db_path)`
-
-**Public API**:
-- `append(stream: str, event_type: str, payload: dict, actor: str = "system") -> int` — Append event, return version.
-- `get(stream: str) -> list` — Read all events in a stream.
-- `project(view: str) -> dict` — Fold the named stream through its projector into current state. Raises `ValueError` if projector not registered (line 15–35).
-
-**Backend swaps**: The backend (SQLite now, Postgres later) is abstracted here. Callers **never** touch `EventStore` directly; they use `StateAPI` only. On cutover to Postgres, only `api.py` changes; call sites stay the same.
-
----
-
-## New State Streams (Beyond Tracker)
-
-The tracker stream is the first proof of concept. The event log supports **arbitrary streams**; new streams are registered by adding a projector to `_PROJECTORS` in `state_store/api.py` (line 12).
-
-### Proposed: `orchestrator_status` stream
-
-**Purpose**: Record orchestrator phase, NEXT STEPS, decisions, and audit results in real-time without git writes.
-
-**Events**:
-```json
-{
-  "type": "phase_changed",
-  "payload": {"phase": "wave-rc.3", "reason": "stable release shipped"}
-}
-{
-  "type": "next_steps_updated",
-  "payload": {"steps": ["reconcile state_store SI", "add orchestrator_status stream", ...]}
-}
-{
-  "type": "decision_locked",
-  "payload": {"key": "model_dispatch_core", "value": "out-of-repo (structural)", "justification": "..."}
-}
-{
-  "type": "audit_findings_recorded",
-  "payload": {"level": "wave-rc.2", "findings_count": 3, "summary": "..."}
-}
-```
-
-**Projection** (pseudo-code):
-```python
-def project_orchestrator_status(events):
-    status = {
-        "phase": None,
-        "decisions": {},
-        "next_steps": [],
-        "latest_audit": None,
-    }
-    for ev in events:
-        if ev["type"] == "phase_changed":
+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"]

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

@@ -1,11 +1,8 @@
 # driver/ — AgentDriver backend-portability seam
 
-**What**: The one-file domain contract that lets aesop's wave loop run on
-backends other than Claude Code (Codex, open models). The wave loop dispatches
-through the `AgentDriver` interface and nothing else; each backend is a subclass.
-
-Grounded in a multi-model portability design spike.
-**Phase 1 (interface + reference adapter, shipped)** + **Phase 2 (Codex OpenAI Chat Completions, shipped)** + **Phase 3 (wave-manifest bridge, shipped)**.
+**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
 
@@ -24,6 +21,8 @@ Grounded in a multi-model portability design spike.
 - **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).
@@ -33,8 +32,7 @@ Grounded in a multi-model portability design spike.
 - **../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 end-to-end offline tests proving
-  non-Claude backend drives a real RED stub to verified-GREEN offline (no API key,
+- **../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).
 
@@ -85,47 +83,18 @@ Optional (non-abstract): `get_tokens_spent()`.
 
 ## Phase 2 Codex Implementation Details
 
-The Codex driver proves a non-Claude backend can take a real coding task
-end-to-end through the AgentDriver and produce orchestrator-verified results,
-entirely offline (no API key, no network in CI).
-
-**dispatch_worker**: Orchestrator-managed worker (Tier 2):
-- Injects owned-file contents into the prompt (worker has no filesystem access).
-- Calls OpenAI Chat Completions API via injectable transport (default=urllib).
-- Requests strict JSON schema output (full-file replacements).
-- Validates ALL JSON with bounded in-turn retry (<=2 attempts).
-- Enforces ownership: rejects out-of-scope paths wholesale.
-- Pre-dispatch max_owned_bytes guard: fails safe on oversized files (no
-  truncation).
-- Writes full-file replacements to disk; never applies diffs.
-- Records usage.total_tokens for cost tracking.
-- CRITICAL: Green is NOT decided by the model's done:true; it is decided by
-  the orchestrator running run_command and getting exit 0 (center verification).
-
-**Transport seam**: The injectable transport callable keeps CI offline. Tests
-pass FakeTransport with canned responses; production code reads OPENAI_API_KEY
-from environment and uses default_openai_transport (stdlib urllib, hard timeout).
-
-**Verification policy**: verification_policy(caps) maps tier 2 -> {
-validate_all_json: True, spot_check_frac: 0.50, repair_cap: 2,
-require_adversarial_review: True }. Feeds the wave's integration verifier.
+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
 
-The wave bridge connects AgentDriver backends to wave-flat-dispatch manifest
-items, making verification tier driven by backend capability, not config.
-
-**build_manifest_item(driver, item) -> dict**:
-- Takes a backlog item {slug, ownsFiles, prompt, testCmd, workDir, ...} + driver.
-- Returns manifest-item dict enriched with: model (from driver.resolve_model('worker')),
-  verificationTier (from driver.probe_capabilities().recommended_verification_tier),
-  AND all four resolved policy knobs (repairCap, requireAdversarialReview, spotCheckFrac,
-  validateAllJson from verification_policy(caps)).
-- Preserves all input fields; adds model, tier, and all four policy fields.
-- The policy is RESOLVED ONCE in Python and carried as literal manifest fields, so
-  the template cannot recompute/drift. Tier-1/Claude path with no verificationTier
-  maintains byte-identical behavior (tier-1 defaults: repairCap=1, requireAdversarialReview=false,
-  spotCheckFrac=0.10, validateAllJson=false).
+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
@@ -138,11 +107,44 @@ items, making verification tier driven by backend capability, not config.
 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).
-- **Next**: Refactor wave-flat-dispatch onto the driver (Phase 1 handoff).
-- **Future**: Open-model adapter (Tier-4 backend).
+- **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.