@delegance/claude-autopilot 5.2.2 → 6.2.2

package/CHANGELOG.md

@@ -1,4 +1,1030 @@
-# Changelog
+## Unreleased
+
+- v5.6 Phase 7 (docs reconciliation) — pending.
+
+## 6.2.2 — `claude-autopilot autopilot --json` envelope + cache version policy (2026-05-07)
+
+**Headline.** Closes out the v6.2.x track. `claude-autopilot autopilot --json` now emits exactly one machine-readable envelope on stdout — successful runs, pre-run failures, and mid-pipeline failures all produce the same shape so CI consumers can branch on `.exitCode` / `.failedPhase` / `.errorCode` directly without parsing stderr NDJSON. The cache contract gains a `MIN_SUPPORTED..MAX_SUPPORTED` schema-version window so a stale run dir from a future binary fails with a clear error instead of an opaque shape crash. The migration guide gets a new "v6.1 → v6.2: one runId across the pipeline" section.
+
+**Motivation — Codex review of the v6.2 spec (3 WARNING + 3 NOTE).** The v6.2 orchestrator spec reserved `--json` for v6.2.2; the spec for this PR (Codex 5.3-reviewed) folded back three warnings (strict equality on schemaVersion blocks rolling deploys, exactly-once envelope needs uncaughtException coverage, exit-code taxonomy ambiguous for pre-run failures) and three notes (six-phases vs four-phases migration text, `errorCode` union too loose, stdout purity test under stderr load).
+
+**What's in (the 9 deliverables from the spec's "Scope" section).**
+
+- **Outer JSON envelope** for `claude-autopilot autopilot --json`. New `AutopilotJsonEnvelope` shape (`version: '1'`, `verb: 'autopilot'`, `runId | null`, `status`, `exitCode`, `phases[]`, `totalCostUSD`, `durationMs`, `errorCode?`, `errorMessage?`, `failedAtPhase?`, `failedPhaseName?`). Pre-run failures get `runId: null` + populated `errorCode`. Mid-pipeline failures get `failedAtPhase` + `failedPhaseName`.
+- **Bounded `AutopilotErrorCode` enum.** Exact strings: `invalid_config | budget_exceeded | lock_held | corrupted_state | partial_write | needs_human | phase_failed | internal_error`. CI consumers can rely on these specific values; new codes ship as minor versions of the envelope schema. Per codex NOTE #5.
+- **Single-write latch + uncaughtException / unhandledRejection handlers.** Module-scoped boolean in `src/cli/json-envelope.ts` flips BEFORE writing so subsequent calls no-op. The orchestrator's `runAutopilotWithJsonEnvelope` installs process-level fatal handlers that consult the latch — if an envelope already shipped, they exit silently; otherwise they emit a fallback `internal_error` envelope before exiting `1`. Test seam `__testInstallProcessHandlers: false` keeps the handlers from leaking across the suite. Per codex WARNING #2.
+- **Deterministic exit-code-to-errorCode mapping** via `computeAutopilotExitCode`. `0` success / `1` `invalid_config | phase_failed | internal_error` / `2` `lock_held | corrupted_state | partial_write` / `78` `budget_exceeded | needs_human`. Per codex WARNING #3.
+- **Cache contract version policy** in `src/core/run-state/state.ts` + the replay path in `events.ts`. New exports `RUN_STATE_MIN_SUPPORTED_SCHEMA_VERSION = 1` and `RUN_STATE_MAX_SUPPORTED_SCHEMA_VERSION = RUN_STATE_SCHEMA_VERSION`. `replayState()` throws `corrupted_state` when the persisted `schema_version` falls outside the window, with a message naming both bounds for operator triage. Future minor versions can additively expand the schema while preserving forward-read compatibility (bump writer, leave reader); major bumps reset `MIN_SUPPORTED` to break with the past explicitly. Per codex WARNING #1.
+- **Migration guide section.** New "v6.1 → v6.2: one runId across the pipeline" section in `docs/v6/migration-guide.md` walks through the per-verb → orchestrator collapse, the `--json` envelope shape (success / pre-run failure / mid-pipeline failure examples), the `AutopilotErrorCode` taxonomy table, and the cache version policy. Flags the v6.2.0 vs v6.2.1 phase-set difference per codex NOTE #4 — examples assume the v6.2.1 6-phase set (`scan → spec → plan → implement → migrate → pr`).
+- **Channel discipline preserved.** The envelope is the only thing on stdout in `--json` mode (orchestrator runs with `__silent: true`). NDJSON events continue to flow to stderr unchanged via the existing v6 Phase 5 helpers.
+- **Dispatcher wiring.** `src/cli/index.ts` plumbs `--json` through to `runAutopilotWithJsonEnvelope`; pre-run validation failures (`--mode`, `--budget`) emit envelopes too so CI never sees free-text errors when `--json` is on.
+
+**Tests.** Baseline 1534 → 1548 (+14 net new):
+
+- 9 envelope tests in `tests/cli/autopilot-json-envelope.test.ts` covering the 6 spec scenarios (success, pre-run failure, mid-pipeline failure, no-ANSI on stdout, stdout purity under stderr load, single-write latch + uncaughtException) plus 1 latch sanity test and 2 exit-code/enum mapping tests.
+- 5 schema-version range tests in `tests/run-state/state.test.ts` covering the bounds export plus accept-in-range, reject-below-MIN, reject-above-MAX, and message-names-both-bounds.
+
+**Engine-off path unchanged.** The schema-version range check applies inside `replayState()` (engine-on territory). Engine-off invocations don't read run dirs and are byte-for-byte identical to v6.2.1.
+
+**Out of scope (deliberate, see spec for full list).**
+- `--json` envelope on individual wrapped verbs other than `autopilot`. They already emit per-verb envelopes via the v6 Phase 5 helper; no change needed.
+- Streaming JSON (newline-delimited progress events on stdout). v6.3 — would need a major channel-discipline change.
+- Schema migration tooling. v6.x has only one schema version; migration tooling is reserved for the v7 layout change.
+
+**Spec.** docs/specs/v6.2.2-json-envelope-and-docs.md (3 WARNING + 3 NOTE folded from the Codex 5.3 review).
+
+## 6.2.1 — Side-effect phase idempotency contracts (`migrate` + `pr`) (2026-05-07)
+
+**Headline.** Side-effecting phases now satisfy a registry-enforced two-step contract — record a deterministic "I'm starting this work" breadcrumb BEFORE the side-effect, then one reconciliation ref per durable artifact AFTER. With the contract in place, `migrate` and `pr` enter the orchestrator's `--mode=full` registry, expanding the v6.2.0 `scan → spec → plan → implement` pipeline to the full **6-phase** flow `scan → spec → plan → implement → migrate → pr` under one runId.
+
+**Motivation — Codex CRITICAL gate from v6.2.** The v6.2 orchestrator spec flagged side-effect resume as the riskiest property to certify before adding `migrate` or `pr`: a partial crash mid-dispatch could leave the engine blind to applied work, causing the resume preflight to either silently re-run side effects (data loss) or pessimistically refuse every retry (operability tax). v6.2.1 closes the gap with a uniform contract every side-effecting phase must declare AND a registry-time guard that throws if the declaration is missing.
+
+**What's in (the 7 deliverables from spec section "Scope of THIS PR").**
+
+- **New `migration-batch` ref kind** in `ExternalRefKind` (`src/core/run-state/types.ts`). Documented semantics: "deterministic id covers a planned migration batch; emitted BEFORE dispatch so a partial crash leaves a resume target." Joins `migration-version` (the post-effect reconciliation ref).
+- **`migrate` pre-effect breadcrumb.** `src/cli/migrate.ts` now emits a `migration-batch` ref BEFORE `dispatchFn(input)` — a partial crash leaves the orchestrator a resume target. The post-success `migration-version` refs stay (one per applied migration). Per the v6.2.1 spec, the batch id uses the `${env}:pre-dispatch:${Date.now()}` fallback form because no Delegance migrate skill (Supabase, Rails, Alembic, …) exposes its planned set pre-dispatch — the deterministic-id form `sha256(env+plannedMigrations)` is reserved for a follow-up that adds a planning verb to the skill protocol.
+- **Provider readback for `migration-batch`** in `src/core/run-state/provider-readback.ts`. Queries the dispatcher's ledger for the planned set + applied set, returns `merged` (all applied), `open` (some pending), `failed` (any errored), or `unknown` (fail closed on missing fetcher / throw / null). New `MigrationBatchFetcher` interface + `registerMigrationBatchFetcher` seam alongside the existing `MigrationStateFetcher`.
+- **Registry-time enforcement** in `src/core/run-state/phase-registry.ts`. New `registerPhase()` helper throws `Error: registry: side-effect phase <name> missing idempotency contract` when a `hasSideEffects: true` registration omits `preEffectRefKinds` or `postEffectRefKinds`. Applied to all six entries; the four read-only phases (scan/spec/plan/implement) omit the arrays without complaint.
+- **`buildMigratePhase` and `buildPrPhase` builders** extracted following the v6.2.0 builder pattern (scan/spec/plan/implement). Each verb's existing `runX(options)` continues to delegate to its builder — direct CLI behavior is byte-for-byte identical to v6.2.0. The full registry now has: `scan / spec / plan / implement / migrate / pr`.
+- **Resume preflight in orchestrator** (`src/cli/autopilot.ts` + new `src/core/run-state/resume-preflight.ts`). Before invoking `runPhase` on any side-effecting phase, the orchestrator collects prior `phase.success` + `phase.externalRef` events from `events.ndjson` and routes per the spec decision matrix: all post-effect refs `merged`/`live` → emit synthetic `phase.success` and skip; pre-effect breadcrumb `open` → retry (the phase body's own ledger handles dedup); otherwise → emit `replay.override` + throw `GuardrailError('needs_human')`. New error code `needs_human` joins the taxonomy in `src/core/errors.ts`.
+- **`--mode=full` extended** to 6 phases (`DEFAULT_FULL_PHASES` in `phase-registry.ts`). After v6.2.1, `claude-autopilot autopilot` runs the entire pipeline under one runId — the YC-demo win deferred from v6.2.0.
+
+**Tests.** Baseline 1509 → 1532 (+23 net new):
+
+- 9 gating tests in `tests/cli/autopilot-side-effect-resume.test.ts` covering the 6 spec scenarios (migrate partial-crash retry, migrate full-success skip, pr-open skip, pr-closed needs-human, registry rejection, run-scope budget no-double-charge) plus 3 edge cases (proceed-fresh, prior success without refs, errored-ledger needs-human).
+- 8 unit tests in `tests/run-state/provider-readback.test.ts` covering the new `migration-batch` readback (merged / open / failed / empty plan / null fetcher / throw / no fetcher / default-registry routing).
+- 2 updated tests in `tests/cli/migrate-engine-smoke.test.ts` to account for the new pre-effect breadcrumb (now `1 + N` refs per run instead of `N`).
+- 4 new test variants for the contract guard (`hasSideEffects: true` with each missing array, plus the empty-postEffect / read-only positive cases).
+
+**Engine-off path unchanged.** Existing `migrate`/`pr` invocations without `--engine` continue byte-for-byte identical. The engine-off escape hatch threads through `executeMigratePhase(input, null)` / `executePrPhase(input, null)`, where a null `ctx` makes `emitExternalRef` a no-op — same precedent as every other wrapped verb.
+
+**Out of scope (deliberate, see spec for full list).**
+- Deterministic batch id (`sha256(env + plannedMigrations)`) — requires extracting a `planMigrations()` verb from each migrate skill's protocol. v6.2.x follow-up.
+- `implement`'s `git-remote-push` ref (declared in the spec table but not yet emitted by `implement.ts`). v6.2.x follow-up.
+- Cross-run ref dedup (e.g. recognizing two pre-dispatch breadcrumbs as the same operation across runs). Not needed for orchestrator MVP.
+- Provider readback for non-Delegance migrate skills (Rails, Alembic, …). v6.2.1 ships the contract; per-skill readback is per-skill follow-up work.
+
+**Spec.** docs/specs/v6.2.1-side-effect-idempotency.md (Codex CRITICAL gate from v6.2 — folded back as the foundation for this PR).
+
+## 6.2.0 — Multi-phase orchestrator (`claude-autopilot autopilot`) (2026-05-07)
+
+**Headline.** New top-level `claude-autopilot autopilot` verb runs `scan → spec → plan → implement` under **one runId**. The pre-v6.2 chain (`scan && spec && plan && implement`) created four separate runs with no parent — the orchestrator collapses them into a single ledger so `claude-autopilot runs watch <id>` covers the whole pipeline and a `--budget=$25` cap ticks down across phases instead of resetting per verb.
+
+**What's in.**
+- **`claude-autopilot autopilot [options]`** — sequential N-phase orchestrator. Engine-on REQUIRED (rejected at pre-flight if `--no-engine` / `CLAUDE_AUTOPILOT_ENGINE=off` / `engine.enabled: false`). Lifecycle: `createRun({ phases })` → per-phase `buildPhase + runPhase` → emit `run.complete` exactly once → refresh state snapshot → release lock in `finally`. Non-interactive (a `pause` budget decision becomes hard-fail) so it works in CI without prompting.
+- **`build<Phase>Phase()` builders** extracted from `scan`, `spec`, `plan`, `implement`. Each verb's existing `runX(options)` continues to call its builder internally — direct CLI behavior is byte-for-byte identical to v6.1. Per-verb parity tests (`tests/cli/<verb>-builder-parity.test.ts`) compare stdout / stderr / `events.ndjson` between the legacy entry and the explicit builder + `runPhaseWithLifecycle` path.
+- **Phase registry** at `src/core/run-state/phase-registry.ts`. `as const` + per-entry `satisfies PhaseRegistration<I, O>` preserves per-phase I/O typing through dynamic dispatch (per codex review NOTE #5). `getPhase(name)`, `listPhaseNames()`, and `validatePhaseNames(names)` are the public surface; `--phases=<csv>` validation lives here.
+- **Run-scope budget** — `BudgetConfig.scope: 'phase' | 'run'` (default `'phase'` for back-compat). When `scope === 'run'` the orchestrator's per-phase budget gates resolve against cross-phase `phase.cost` totals so the `$25` demo narrative ticks down across the whole pipeline. `sumPhaseCost(events, '*')` cross-phase overload added. Both `BudgetCheck.scope` and `BudgetCheckEvent.scope` carry the resolution forward to observers (`runs show <id> --events`, future cost dashboards). Per codex review WARNING #2 — pulled forward into v6.2.0 (was deferred to v6.2.2 in the initial draft).
+- **Exit-code matrix** (per codex review WARNING #3) — 0 success, 78 budget_exceeded, 2 engine error (`lock_held` / `corrupted_state` / `partial_write`), 1 everything else. Phase failure wins over finalization error.
+- **CLI surface**: `--mode=full` (default — `scan → spec → plan → implement`), `--phases=<csv>` for custom lists, `--budget=<usd>` for the run-scope cap. `--mode=fix` and `--mode=review` reserved for v6.2.1+; `--json` envelope reserved for v6.2.2.
+
+**Tests.** Baseline 1492 → 1509 (+17 new):
+- 4 builder-parity tests (`scan`, `spec`, `plan`, `implement`) covering stdout / stderr / events triple-snapshot.
+- 6 run-scope budget tests in `tests/run-state/budget.test.ts` covering scope flag default, run-scope happy path, run-scope cap exceeded across phases, Layer 1 advisory in run-scope, and phase/run scope math equivalence (regression guard).
+- 7 orchestrator integration tests in `tests/cli/autopilot.test.ts` covering: 3-phase happy path, scan-failure phase 0, run-scope budget exceeded → exit 78, resume lookup `already-complete` short-circuit, `--phases=invalid,scan` → exit 1 invalid_config no run dir, `CLAUDE_AUTOPILOT_ENGINE=off` → exit 1 invalid_config, `cliEngine: false` → exit 1 invalid_config.
+
+**Out of scope (deliberate, see spec for full list).**
+- `migrate`, `pr` — gated on per-phase idempotency contracts (preflight readback + externalRef recorded BEFORE side-effect). v6.2.1.
+- `--mode=fix`, `--mode=review` — v6.2.1+.
+- `--json` envelope — v6.2.2.
+- Parallel phase execution. Sequential by design.
+- Interactive prompts inside the orchestrator. CI/scripts get deterministic exit codes; pause budget decisions hard-fail.
+
+**Spec.** docs/specs/v6.2-multi-phase-orchestrator.md (Codex-reviewed: 1 CRITICAL + 3 WARNING + 3 NOTE folded back into the spec before implementation).
+
+## 6.1.0 — Default flip: engine on by default + `--no-engine` deprecated (2026-05-07)
+
+**Headline.** The Run State Engine is now ON by default. Bare
+`claude-autopilot <verb>` invocations create a `.guardrail-cache/runs/<ulid>/`
+directory, emit typed NDJSON events on stderr, apply budget gates if
+`budgets:` is configured, and write a state snapshot — without any opt-in
+config. v6.0 shipped the engine OFF behind an explicit `engine.enabled: true`
+opt-in to give users control during a stabilization window; v6.1 closes
+that window.
+
+**Motivation — v6.0 stabilization criteria met.**
+- 10 of 10 pipeline phases wrapped through `runPhaseWithLifecycle`
+  (`scan` v6.0.1, `costs`/`fix` v6.0.2, `brainstorm`/`spec` v6.0.3,
+  `plan`/`review` v6.0.4, `validate` v6.0.5, `implement` v6.0.7,
+  `migrate` v6.0.8 — first side-effecting wrap with `migration-version`
+  externalRefs, `pr` v6.0.9 — second side-effecting wrap with `github-pr`
+  externalRefs).
+- Lifecycle helper extracted (v6.0.6) so all 10 wraps share the same
+  byte-for-byte engine-on / engine-off behavior.
+- Side-effecting wraps proven (`migrate` + `pr`) — externalRef ledger
+  + provider readback semantics exercised end-to-end.
+- Live adapter cert suite green (Vercel + Fly + Render).
+- `runs watch <id>` live cost/budget meter shipped (this release's
+  `v6.1.0-pre` entry below) — the YC-demo moment for the events stream.
+- `npm test` baseline: 1469 → 1492 (+23 net new this release; all green).
+
+**Deprecation.** `--no-engine`, `CLAUDE_AUTOPILOT_ENGINE=off|false|0|no`,
+and `engine.enabled: false` continue to work as the legacy escape hatch
+in v6.1.x. Each invocation that resolves to engine-off via one of those
+explicit opt-outs now prints a single-line stderr deprecation notice:
+
+```
+[deprecation] --no-engine / engine.enabled: false will be removed in v7. Migrate to engine-on (default).
+```
+
+The notice fires only on user-driven opt-outs (`source: 'cli' | 'env' |
+'config'`); the new (engine-on) default never trips it. **v7 removes
+the escape hatch** — `engine.enabled: false` becomes a config validation
+error and `--no-engine` / `CLAUDE_AUTOPILOT_ENGINE=off` are silently
+ignored.
+
+**Spec.** [`docs/specs/v6.1-default-flip.md`](docs/specs/v6.1-default-flip.md)
+is the canonical reference for what flipped, why, and the v7 follow-up.
+
+**Migration tips.**
+- If your CI parses stderr as free-form text and relies on the v5.x
+  shape, set `CLAUDE_AUTOPILOT_ENGINE=off` (or pass `--no-engine`)
+  to pin the legacy behavior. You'll see the deprecation notice on
+  every invocation until you remove it — that's expected.
+- If you opt out via config (`engine.enabled: false`), the same notice
+  fires on every invocation. Plan to remove that line before bumping
+  to v7.
+- Existing users on `engine.enabled: true` are no-op'd — your config
+  still wins via the same precedence rules.
+- See [`docs/v6/migration-guide.md#migrating-from-v60-to-v61`](docs/v6/migration-guide.md)
+  for the full upgrade walkthrough.
+
+**Test surface.**
+- `tests/run-state/resolve-engine.test.ts` — flipped 4 default-related
+  cases. New `v6.1 default-flip` describe block + `v6.1 deprecation
+  warning` describe block covering the predicate, the emitter, the
+  default `process.stderr` branch, and the `builtInDefault` override
+  path.
+- `tests/run-state/run-phase-with-lifecycle.test.ts` — added 4 new
+  cases pinning engine-on as the new default + the deprecation banner
+  firing on opt-out / staying silent on the new default.
+- 9 engine-smoke tests (`brainstorm`, `costs`, `implement`, `migrate`,
+  `plan`, `pr`, `review`, `spec`, `validate`) updated — the
+  "engine off (default)" cases are now "engine on (v6.1 default)";
+  the matching `cliEngine: false` cases stay as legacy-escape-hatch
+  coverage.
+
+**Files changed.**
+- `src/core/run-state/resolve-engine.ts` — new active default constant
+  `ENGINE_DEFAULT_V6_1 = true`. The deprecated `ENGINE_DEFAULT_V6_0`
+  export keeps its historical value (`false`) so out-of-tree consumers
+  who pinned that symbol get what the name promises; both constants are
+  removed in v7. New `emitEngineOffDeprecationWarning` helper +
+  `shouldWarnEngineOffDeprecation` predicate +
+  `ENGINE_OFF_DEPRECATION_MESSAGE` stable copy.
+- `src/core/run-state/run-phase-with-lifecycle.ts` — wires the
+  deprecation helper into the engine-off branch.
+- `docs/v6/migration-guide.md` — new "Migrating from v6.0 to v6.1"
+  section, updated precedence matrix, refreshed default-flip plan,
+  relabeled "What changes" table.
+- `README.md` — v6 section updated (engine on by default + v7 removal
+  timeline).
+- `package.json` — version `5.5.2` → `6.1.0`.
+
+## v6.1.0-pre — `runs watch <id>` live cost meter (2026-05-07)
+
+**The YC-demo moment.** v6.0.x hardened the events.ndjson stream across
+all 10 wrapped phases; v6.1 makes that stream visible in real time.
+`runs watch <runId>` tails events.ndjson via `fs.watchFile` (1s poll —
+inotify/FSEvents are unreliable for tiny appends across our matrix) and
+pretty-renders each event with a running cost/budget meter so a user
+running `claude-autopilot autopilot ...` in one terminal can `runs watch`
+in another and watch their $25 budget tick down while phases ship code.
+
+**Demo transcript.** Live tail of a fixture run, ANSI-stripped:
+
+```
+* run 01HZK7P3D8Q9V00000000000AB
+  phases: spec -> plan -> implement -> pr
+  budget: $0.00 / $25.00 (0%)
+[12:00:01] phase.start         spec
+[12:00:42] phase.cost          spec           +$0.07  (in: 1.2k, out: 3.4k)  total: $0.07
+[12:00:45] phase.success       spec           OK 44.2s
+[12:00:46] phase.start         plan
+[12:01:12] phase.cost          plan           +$0.21  (in: 4.1k, out: 8.2k)  total: $0.28
+[12:01:15] phase.success       plan           OK 29.0s
+[12:08:33] phase.externalRef   pr             -> github-pr#123
+[12:08:34] run.complete        status=success  totalCostUSD=$4.20  duration=8m32s
+
+done  run 01HZK7P3D8Q9V00000000000AB
+  status=success  totalCostUSD=$4.20  duration=8m33s
+```
+
+**Modes.**
+
+- `runs watch <id>` — live tail, exits on `run.complete` / Ctrl-C
+- `runs watch <id> --since <seq>` — replay forward from a specific seq
+  (resume after disconnect)
+- `runs watch <id> --no-follow` — render snapshot once and exit (CI /
+  scripting)
+- `runs watch <id> --json` — emit raw NDJSON to stdout (one event per
+  line) for piping to `jq` or external dashboards. ANSI suppressed.
+- `runs watch <id> --no-color` — force ANSI off even on a TTY
+
+**Pretty rendering.** Color thresholds on the budget bar — green <50%,
+yellow 50-90%, red >90%. Per-event coloring: cyan for phase.start, yellow
+for phase.cost, green for phase.success, red for phase.failed, magenta
+for phase.externalRef + lock.takeover + replay.override, bold-green for
+run.complete success, bold-red for run.complete failed/aborted. ANSI
+auto-strips when stdout is not a TTY (CI), when `--no-color` or `--json`
+is set, or when `NO_COLOR` env var is present.
+
+**Pure renderer.** `src/cli/runs-watch-renderer.ts` is referentially
+transparent — `renderEventLine(event, runningTotal, opts)` is the core
+primitive, exported and 100% pure. Tests run as string-equality
+assertions in <300ms.
+
+**Engine modules untouched.** This is purely a consumer of the existing
+event stream — no changes to `src/core/run-state/**`, no changes to the
+10 wrapped phase verbs, no changes to `runPhaseWithLifecycle`.
+
+**Tests.** +43 new tests:
+- `tests/cli/runs-watch-renderer.test.ts` — 29 pure-renderer cases
+  covering every event-line variant, the three budget-bar color
+  thresholds, ANSI on/off symmetry, and the final-summary block
+- `tests/cli/runs-watch.test.ts` — 14 verb-level cases covering
+  `--no-follow` snapshot, `--since` replay, `--json` mode, run-not-found
+  (exit 2), invalid-ULID, live tail picks up appended events,
+  budget rendering with/without `BudgetConfig`, plural `budgets` config
+  alias, ANSI behavior, and run-complete short-circuit on already-
+  terminated runs
+
+**CLI plumbing.** New sub-verb on the `runs` umbrella: `runs watch <id>`.
+Help block surfaces `--since`, `--no-follow`, `--json`, `--no-color`
+plus a behavior summary + exit-code key. Exit codes: 0 success / clean
+exit, 1 invalid input or stream error, 2 not_found.
+
+## v6.0.9 — wrap `pr` through `runPhaseWithLifecycle` (2026-05-06)
+
+**First side-effecting phase wrapped.** v6.0.1 → v6.0.5 wrapped read-only
+verbs (`scan`, `costs`, `fix`, `brainstorm`, `spec`, `plan`, `review`,
+`validate`); v6.0.6 extracted the lifecycle helper. v6.0.9 wraps `pr` —
+the first verb that mutates state on the platform of record (GitHub
+issue comments + PR reviews). This proves the helper's `ctx.emitExternalRef`
+plumbing for genuinely side-effecting phases without any helper-shape
+changes.
+
+**Declarations.** Match the v6 spec table exactly:
+
+- `idempotent: false` — re-running posts a NEW PR review ID each time
+  (`postReviewComments` dismisses prior + creates new). PR comment
+  posting (`postPrComment`) is marker-deduped on the body but the
+  underlying `gh` API call is still mutating.
+- `hasSideEffects: true` — posts to GitHub via the `gh` CLI inside the
+  inner `runCommand` invocation.
+- `externalRefs: github-pr` — recorded BEFORE the inner `runCommand`
+  runs so a crash mid-pipeline still leaves a breadcrumb pointing at
+  the PR. The engine path's Phase 6 resume logic can `gh pr view <id>`
+  to confirm the PR is still open before deciding whether a replay
+  is safe.
+
+**Engine-off byte-for-byte unchanged.** All `gh pr view` + `git fetch` +
+`runCommand` behavior preserved. The wrap adds two test seams
+(`__testPrMeta` to short-circuit PR metadata lookup, `__testRunCommand`
+to stub the inner pipeline) so the smoke test exercises the engine
+lifecycle without `gh` or a real review pipeline. Production callers
+must not pass these — they're documented "test only" with a comment
+mirroring scan / fix's `__testReviewEngine` precedent.
+
+**CLI plumbing.** The `pr` dispatcher arm now threads `cliEngine` from
+`parseEngineCliFlag()` and `envEngine` from
+`process.env.CLAUDE_AUTOPILOT_ENGINE`, mirroring every other wrapped
+verb. The per-verb help block (`claude-autopilot help pr`) gains
+`--engine` / `--no-engine` lines plus a side-effects note (engine-on
+records a `github-pr` externalRef; future replays gate on the spec's
+"side-effect readback" rule). `GLOBAL_FLAGS_BLOCK` adds "v6.0.9: wired
+for `pr`" to its breadcrumb list.
+
+**Smoke test.** New `tests/cli/pr-engine-smoke.test.ts`, 6 cases:
+- engine off (default): no run dir / no engine artifacts; runCommand
+  still invoked
+- engine off (`cliEngine: false`): no run dir
+- engine on (`--engine`): state.json + events.ndjson + lifecycle in
+  order (run.start → phase.start → phase.externalRef → phase.success
+  → run.complete); externalRef recorded with kind=`github-pr`,
+  id=`42`, provider=`github`; `idempotent: false, hasSideEffects: true`
+  reflected on the phase
+- env precedence (`CLAUDE_AUTOPILOT_ENGINE=on` without CLI flag)
+- CLI override (`--no-engine` beats env on)
+- runCommand returning 1 surfaces as verb exit 1 WITHOUT marking the
+  engine phase as failed (pipeline result ≠ phase failure, same
+  precedent as scan)
+
+**Why no follow-up `github-comment` externalRef yet.** A potential
+extension is to record one externalRef per posted comment / review
+(`github-comment`). That requires plumbing the post-comment URL out
+of `runCommand` (currently only logged) — deferred to a follow-up PR.
+For v6.0.9 the `github-pr` ref is sufficient for the spec's readback
+rule: a Phase 6 resume can verify the PR is still open before
+deciding whether to retry.
+
+**Files changed.** `src/cli/pr.ts` (270 insertions / 22 deletions),
+`src/cli/index.ts` (+12 lines for engine knob plumbing),
+`src/cli/help-text.ts` (+8 lines for the per-verb Options block +
+breadcrumb), `tests/cli/pr-engine-smoke.test.ts` (new, 306 lines),
+`docs/v6/wrapping-pipeline-phases.md` (status header + table row +
+deviation note), `docs/v6/migration-guide.md` ("what works today" list
+adds `pr`), `docs/specs/v6-run-state-engine.md` (reconciliation block
+appended). Total: ~600 lines added, ~25 lines removed.
+
+**Status after v6.0.9.** Nine of 10 phases wrapped. Remaining:
+`implement` (v6.0.7) and `migrate` (v6.0.8) — both side-effecting,
+both wrapped concurrently with this PR by parallel agents.
+- **Bundled UI polish skills** — ships `/ui`, `/simplify-ui`, `/ui-ux-pro-max`,
+  `/make-interfaces-feel-better` so consumers get them via `npm install` instead
+  of needing user-level skill installs. `/ui` runs the chained pass (audit →
+  simplify → align → polish); the other three are individual lenses. Auto-
+  discovered via the existing `skills/` directory in the package `files`
+  allowlist. Pairs with the design context loader
+  (`src/core/ui/design-context-loader.ts`) — both gate on the same
+  `hasFrontendFiles()` predicate so they only fire when frontend files change.
+
+## v6.0.7 — wrap `implement` through `runPhaseWithLifecycle` (2026-05-07)
+
+**Wraps the ninth pipeline phase.** Mechanical wrap following the v6.0.6
+helper recipe. Engine-off path is byte-for-byte unchanged (advisory print
+pointing at the Claude Code `claude-autopilot` skill); engine-on path
+creates a run dir + emits run.start / phase.start / phase.success /
+run.complete events. Concurrent dispatch — landed alongside v6.0.8
+(`migrate`) and v6.0.9 (`pr`).
+
+- New `src/cli/implement.ts` — `RunPhase<ImplementInput, ImplementOutput>`
+  with `idempotent: true, hasSideEffects: false`. **Documented deviation
+  from spec table:** the spec at line 159 of
+  `docs/specs/v6-run-state-engine.md` lists `implement` with
+  `idempotent: partial, hasSideEffects: yes, externalRefs: git-remote-push`.
+  That declaration assumes the verb itself writes commits and pushes them
+  to a remote. The v6.0.7 CLI verb does **not** write code, run tests,
+  commit, or push to a remote — all of that lives in the Claude Code
+  `claude-autopilot` skill (and its delegates: `subagent-driven-development`,
+  `commit-push-pr`, `using-git-worktrees`). The CLI verb is the engine-wrap
+  shell — its only side effect is writing the local
+  `.guardrail-cache/implement/<ts>-implement.md` log stub. If a future PR
+  inlines the implement loop into the CLI verb, the declarations flip to
+  match the spec table and a `ctx.emitExternalRef({ kind: 'git-remote-push',
+  id: '<commit-sha>' })` call lands after each push.
+- CLI dispatcher in `src/cli/index.ts` — wires `--engine` / `--no-engine` /
+  `--context` / `--plan` / `--output` / `--config` through the helper
+  alongside `process.env.CLAUDE_AUTOPILOT_ENGINE`. Mirrors the validate /
+  review / plan dispatcher shape.
+- Help text in `src/cli/help-text.ts` — adds `implement` to the Pipeline
+  group + per-verb Options block. Bumps `GLOBAL_FLAGS_BLOCK` to cite
+  v6.0.7 alongside v6.0.1 → v6.0.5.
+- New smoke test `tests/cli/implement-engine-smoke.test.ts` (6 cases) —
+  asserts state.json + events.ndjson lifecycle, idempotent /
+  hasSideEffects flags, env / CLI precedence, log file location.
+- Test count: 1408 → 1414 (+6). `npm test` clean. `npx tsc --noEmit`
+  clean except pre-existing fixture errors.
+
+## v6.0.8 — wrap `migrate` through `runPhaseWithLifecycle` (2026-05-06)
+
+**First side-effecting phase under the engine.** v6.0.1 → v6.0.6 wrapped
+eight read-only / advisory verbs (`scan`, `costs`, `fix`, `brainstorm`,
+`spec`, `plan`, `review`, `validate`). v6.0.8 wraps `migrate` — the
+first verb that mutates external state (database schema). Builds on the
+`runPhaseWithLifecycle` helper landed in v6.0.6 plus
+`ctx.emitExternalRef()` from inside the phase body for the
+`migration-version` ledger. No helper-shape changes needed.
+
+**Phase declarations** match the spec table at line 162 of
+`docs/specs/v6-run-state-engine.md`:
+
+```
+idempotent:     false   — dispatcher output varies by ledger state
+                          (N applied on attempt 1, 0 on attempt 2 even
+                          though both are operationally safe)
+hasSideEffects: true    — applies migrations, writes audit log,
+                          regenerates types, refreshes schema cache
+externalRefs:   migration-version, scoped `<env>:<name>` per applied
+                migration. Phase 6's resume gate will read these back
+                against the live `migration_state` to decide
+                skip-already-applied vs retry vs needs-human.
+```
+
+**Why `idempotent: false` even though the underlying Delegance migrate
+skill is ledger-guarded against double-apply:** at the *engine
+semantics* layer, `idempotent: true` means "re-running the phase against
+the same input produces equivalent output." A dispatch invocation that
+previously applied N migrations on attempt 1 and applies 0 on attempt 2
+(everything already in the ledger) DOES produce different output
+(different `appliedMigrations` list, different `status`). The spec's
+`idempotent: false` is correct.
+
+**Engine-off path is byte-for-byte identical to v6.0.7.** Same dispatch
+shape (`src/core/migrate/dispatcher.ts` unchanged), same render lines,
+same `--json` payload callback. CI / scripts that don't pass `--engine`
+are unaffected.
+
+| File | Role |
+|---|---|
+| `src/cli/migrate.ts` (new) | Engine-wrap shell calling `runMigrate(opts) → { exitCode, result }`. Defines `MigrateInput` / `MigrateOutput` (JSON-serializable), `RunPhase<MigrateInput, MigrateOutput>` with `name: 'migrate'`, `idempotent: false`, `hasSideEffects: true`. Phase body invokes the dispatcher and emits one `migration-version` externalRef per applied migration via `ctx.emitExternalRef({ kind: 'migration-version', id: '<env>:<name>' })`. Test seam: `__testDispatch` injects a fake dispatcher so smoke tests can exercise the engine-wrap path without spawning a child process or hitting a real database |
+| `src/cli/index.ts` | dispatcher case for `migrate` routes through `runMigrate` instead of inlining `runMigrateDispatch`; threads `cliEngine` + `envEngine`. Engine-off byte-for-byte unchanged — same `--json` payload callback, same render |
+| `src/cli/help-text.ts` | per-verb Options block for `migrate` documents `--engine` / `--no-engine` + `--config`; GLOBAL_FLAGS_BLOCK breadcrumb cites v6.0.8 |
+| `tests/cli/migrate-engine-smoke.test.ts` (new) | 6 cases: engine off (default — no run dir), engine on (lifecycle events, state.json shape, idempotent: false + hasSideEffects: true declaration), externalRef emission per applied migration scoped by env, skipped status (zero externalRefs), dispatcher error → exit 1 + engine still records phase.success (domain failure ≠ engine failure), CLI `--no-engine` beats env on |
+| `docs/v6/wrapping-pipeline-phases.md` | phase-status table flips `migrate` to "WRAPPED in v6.0.8"; status line at top moves to "NINE phases wrapped"; new deviation note documents the ledger-vs-engine-semantics rationale |
+| `docs/v6/migration-guide.md` | "What works today" updated — three knobs now honored by `scan`, `costs`, `fix`, `brainstorm`, `spec`, `plan`, `review`, `validate`, `migrate` |
+| `docs/specs/v6-run-state-engine.md` | new "What was actually built (v6.0.8)" reconciliation block |
+
+**Test delta:** 1408 → 1414 (+6). Typecheck clean. All 1408 existing
+tests pass unchanged — the engine-off path for `migrate` is byte-for-
+byte identical to v6.0.7 (same dispatch shape, same render).
+
+**Concurrency note.** v6.0.7 (`implement`) and v6.0.9 (`pr`) are in
+flight on parallel worktrees, both targeting shared docs (CHANGELOG,
+recipe table, migration-guide) and `src/cli/{index,help-text}.ts`. The
+rebase contract: on push rejection, fetch + rebase + resolve conflicts
+keeping all wraps' contributions, re-test, push with `--force-with-lease`.
+
+**Not done in v6.0.8 — explicit non-goals:**
+- Wrapping `implement` and `pr`. Continues across v6.0.7 / v6.0.9
+  using the same helper plus `ctx.emitExternalRef()` for
+  `git-remote-push` (implement) and `github-pr` (pr).
+- Wiring Phase 6's `migration_state` read-back. The engine PERSISTS
+  `migration-version` externalRefs in v6.0.8; consulting them on
+  resume ships in Phase 6+. Until then, retries on side-effecting
+  phases require `--force-replay`.
+- Multi-phase pipeline orchestrator (autopilot's full
+  `brainstorm → spec → plan → ... → migrate → ...` flow under one runId).
+- Flipping the v6.0 built-in default to ON. v6.1 territory.
+
+## v6.0.6 — `runPhaseWithLifecycle` helper (2026-05-06)
+
+**Tech-debt refactor, no behavior change.** v6.0.1 → v6.0.5 wrapped eight
+CLI verbs (`scan`, `costs`, `fix`, `brainstorm`, `spec`, `plan`, `review`,
+`validate`) by hand-rolling the same ~100-line lifecycle pattern in each
+file: `createRun → optional run.warning → runPhase → run.complete →
+state.json refresh → best-effort lock release in finally`. Bugbot caught
+the duplication on PR #97 (LOW severity, deferred) with the explicit
+note: "extracting from 5 of 10 examples risks getting the abstraction
+wrong; from 10 of 10 the pattern is fully evidenced." At 8 of 10, the
+pattern is sufficiently evidenced that the remaining three side-effecting
+phases (`implement`, `migrate`, `pr`) can use the same helper plus
+`ctx.emitExternalRef()` from inside their phase body — no helper-shape
+changes needed.
+
+**The helper.** New `src/core/run-state/run-phase-with-lifecycle.ts` sits
+on top of the existing `runPhase()` API (which is unchanged). Callers
+continue to define their own `RunPhase<I, O>` with per-phase
+`idempotent` / `hasSideEffects` / `run`, and pass it in alongside the
+input, the loaded config, the engine knobs, and an `runEngineOff`
+escape-hatch callback. The helper:
+
+- Resolves engine on/off via the canonical CLI > env > config > default
+  precedence
+- On engine-off: invokes `runEngineOff()` and returns its result with
+  `runId/runDir: null`
+- On engine-on: creates a run dir, optionally emits `run.warning` for
+  invalid env, runs the phase, emits `run.complete` (success or failed),
+  refreshes `state.json` from replayed events, releases the lock in
+  `finally` (idempotent), and returns `{ output, runId, runDir }`
+- On phase failure: emits `run.complete` with `status: 'failed'`, prints
+  the legacy `[<phase>] engine: phase failed — <msg>` banner to stderr
+  byte-for-byte, releases the lock, and re-throws
+
+**Migrated phases.** All eight wrapped verbs reduced. Each `runX(opts)`
+function shrinks: keep the per-phase `RunPhase<I, O>` definition + the
+engine-off path body; delete the lifecycle boilerplate; call
+`runPhaseWithLifecycle` once. Total reduction across `src/cli/`:
+
+- `scan.ts` 498 → 429 lines (-69)
+- `costs.ts` 297 → 231 lines (-66)
+- `fix.ts` 473 → 415 lines (-58)
+- `brainstorm.ts` 251 → 189 lines (-62)
+- `spec.ts` 216 → 159 lines (-57)
+- `plan.ts` 269 → 199 lines (-70)
+- `review.ts` 256 → 189 lines (-67)
+- `validate.ts` 262 → 196 lines (-66)
+- **Total: 2522 → 2007 lines (~515 lines saved)**
+
+**Engine-off path is byte-for-byte unchanged.** All eight existing
+`tests/cli/<verb>-engine-smoke.test.ts` smokes pass without modification
+(44 cases). The helper supplies an `runEngineOff` callback so the legacy
+code path stays intact even when the phase body's call shape would
+otherwise pin it.
+
+### Test count
+
+After v6.0.5 baseline: 1396 → 1408 (+12). +12 cases for the new
+`tests/run-state/run-phase-with-lifecycle.test.ts` covering: engine-off
+(default + CLI > env > config precedence); engine-on success (lifecycle
+events, state.json shape, env / config resolution, costUSD pass-through,
+costUSD-absent fallback to 0); engine-on failure (run.complete failed,
+state.json refresh, error re-thrown with original message preserved,
+lock released through finally); invalid env value falling through to
+config-resolved engine-on with `run.warning`. Existing 44 phase smokes
+unchanged. Typecheck clean. Bugbot LOW from PR #97 addressed.
+
+### Deliberately deferred
+
+- Wrapping the remaining pipeline phases (`implement`, `migrate`, `pr`).
+  Side-effecting phases need careful externalRef plumbing — they will
+  build against `runPhaseWithLifecycle` plus `ctx.emitExternalRef()`
+  from inside their phase body. Helper signature does not need to grow
+  for them; documented in the helper's header comment.
+- Multi-phase pipeline orchestrator (autopilot's full
+  `brainstorm → spec → plan → ...` flow under one runId). The single-
+  phase shape stays — multi-phase wrapping is a separate v6.x lift.
+- Flipping the v6.0 built-in default to ON. v6.1 territory.
+
+## v6.0.5 — Engine wire-up Part E (2026-05-06)
+
+**The headline.** v6.0.4 wrapped `plan` and `review`. v6.0.5 continues the
+mechanical wrap pattern from the recipe at
+[`docs/v6/wrapping-pipeline-phases.md`](docs/v6/wrapping-pipeline-phases.md)
+with one more single-shot, read-only verb:
+
+- **`validate`** — new CLI verb. Engine-wrap shell for the validate
+  pipeline phase. Writes a validate log stub under
+  `.guardrail-cache/validate/`; the actual validation work (static
+  checks, auto-fix, tests, Codex review with auto-fix, bugbot triage) is
+  owned by the Claude Code `/validate` skill. Declared `idempotent: true,
+  hasSideEffects: false` (local file write only; no provider calls, no
+  git push, no PR comment, no SARIF upload).
+
+**Documented deviation from the spec table.** The v6 spec
+([docs/specs/v6-run-state-engine.md](docs/specs/v6-run-state-engine.md),
+line 161) lists `validate` with externalRefs `sarif-artifact`. The
+v6.0.5 wrap matches the `idempotent: true, hasSideEffects: false`
+declaration but does **not** plumb a `sarif-artifact` externalRef — the
+v6.0.5 `validate` CLI verb does not emit a SARIF artifact. SARIF
+emission lives in `claude-autopilot run --format sarif --output <path>`
+(a separate verb). The SARIF reference is local-only file output (no
+remote upload), so the engine doesn't need a readback rule for it on
+resume — `idempotent: true` covers replay safety. If a future PR adds
+SARIF emission directly to this verb, the wrap can add a
+`ctx.emitExternalRef({ kind: 'sarif-artifact', ... })` call after the
+file write lands. Documented inline in `src/cli/validate.ts` and in the
+wrapping recipe's deviation note.
+
+The engine-off code path is byte-for-byte unchanged; the `validate`
+verb is brand new in v6.0.5 (validation previously lived only as a
+Claude Code skill).
+
+### Test count
+
+After v6.0.4 baseline: 1390 → 1396 (+6). +6 cases for
+`validate-engine-smoke.test.ts`, mirroring the
+`review-engine-smoke.test.ts` shape: engine off → no run dir + log
+written; engine off (cliEngine: false); engine on → state.json +
+events.ndjson with the right lifecycle (`run.start` →
+`phase.start` → `phase.success` → `run.complete`); engine on with
+explicit `--context`; env-resolved; CLI override beats env. Typecheck
+clean.
+
+### Deliberately deferred
+
+- Wrapping the remaining pipeline phases (`implement`, `migrate`,
+  `pr`). Side-effecting phases need careful externalRef plumbing per
+  the recipe's "side effects" gate; wrap them last.
+- Adding SARIF emission directly to the `validate` verb. Lives in
+  `claude-autopilot run --format sarif` (separate verb).
+- Extracting a shared `runPhaseWithLifecycle` helper across the eight
+  wrapped verbs. Separate refactor PR — out of scope for v6.0.5.
+- Flipping the v6.0 built-in default to ON. v6.1 territory.
+
+## v6.0.4 — Engine wire-up Part D (2026-05-06)
+
+**The headline.** v6.0.3 wrapped `brainstorm` and `spec`. v6.0.4 continues
+the mechanical wrap pattern from the recipe at
+[`docs/v6/wrapping-pipeline-phases.md`](docs/v6/wrapping-pipeline-phases.md)
+with two more single-shot verbs:
+
+- **`plan`** ([#98](https://github.com/axledbetter/claude-autopilot/pull/98)) —
+  new CLI verb. Engine-wrap shell for the plan pipeline phase. Writes a
+  plan markdown stub under `.guardrail-cache/plans/`; the actual
+  LLM-driven planning content is owned by the Claude Code
+  superpowers:writing-plans skill. Declared `idempotent: true,
+  hasSideEffects: false` (local file write only; no provider calls, no
+  git push, no PR comment).
+- **`review`** ([#98](https://github.com/axledbetter/claude-autopilot/pull/98)) —
+  new CLI verb. Engine-wrap shell for the review pipeline phase. Writes
+  a review log stub under `.guardrail-cache/reviews/`; the actual
+  LLM-driven review content is owned by the Claude Code review skills
+  (`/review`, `/review-2pass`, `pr-review-toolkit:review-pr`). Declared
+  `idempotent: true, hasSideEffects: false`.
+
+**Documented deviation from the spec table.** The v6 spec
+([docs/specs/v6-run-state-engine.md](docs/specs/v6-run-state-engine.md))
+lists `review` with externalRefs `review-comments`, implying PR-side
+comment posting (which would force `hasSideEffects: true`). The v6.0.4
+`review` verb does **not** post anywhere — PR-side comment posting
+lives in `claude-autopilot pr --inline-comments` /
+`--post-comments` (a separate verb). If a future PR adds platform-side
+comment posting to this verb, both declarations will need to flip and
+the readback rules will need to plumb a `review-comments` externalRef.
+Documented inline in `src/cli/review.ts`.
+
+**Backward-compat — `review` grouping prefix preserved.**
+`claude-autopilot review` (no args) still prints the alpha.2 prefix
+help banner per the V16 v4-compat test. Flat-verb invocation requires
+at least one flag, e.g. `claude-autopilot review --engine`.
+`claude-autopilot help review` continues to surface the flat-verb
+Options block via `buildCommandHelpText`.
+
+Engine-off code paths are unchanged for both verbs.
+
+### Test count
+
+After v6.0.3 baseline: 1378 → 1390 (+12). +6 cases for
+`plan-engine-smoke.test.ts`, +6 cases for `review-engine-smoke.test.ts`.
+Both mirror `costs-engine-smoke.test.ts`: engine off → no run dir;
+engine on → state.json + events.ndjson with the right lifecycle
+(`run.start` → `phase.start` → `phase.success` → `run.complete`);
+env-resolved; CLI override beats env. Typecheck clean.
+
+### Deliberately deferred
+
+- Wrapping the remaining pipeline phases (`implement`, `migrate`,
+  `validate`, `pr`). Side-effecting phases (`implement`, `migrate`,
+  `pr`) need careful externalRef plumbing per the recipe's "side
+  effects" gate; wrap them last.
+- Flipping the v6.0 built-in default to ON. v6.1 territory.
+
+## v6.0.3 — Wrap brainstorm + spec through runPhase (2026-05-05)
+
+**The headline.** v6.0.3 continues the mechanical phase-wrap pattern from
+the recipe at
+[`docs/v6/wrapping-pipeline-phases.md`](docs/v6/wrapping-pipeline-phases.md)
+with two more pipeline verbs:
+
+- **`brainstorm`** — the pipeline entry point. Implemented primarily as
+  a Claude Code skill (`/brainstorm` → `superpowers:brainstorming`); the
+  CLI verb is an advisory shim pointing the user there. The wrap declares
+  `idempotent: true, hasSideEffects: false`. Engine-off path is
+  byte-for-byte identical to v6.0.2 (the same advisory banner). Engine-on
+  path creates a run dir + emits `run.start` / `phase.start` /
+  `phase.success` / `run.complete`. `--json` envelope shape is preserved
+  for back-compat with the WS7 welcome regression guard and
+  `json-channel-discipline.test.ts`.
+- **`spec`** — same shape as brainstorm. New top-level subcommand (it
+  was previously absent from `SUBCOMMANDS`); the CLI verb is an advisory
+  shim pointing at the autopilot/brainstorm Claude Code flow. Same wrap
+  flags + same engine lifecycle.
+
+**Documented deviation from the spec table.** The
+[v6 spec table](docs/specs/v6-run-state-engine.md) declares both
+`brainstorm` and `spec` `idempotent: no` because the LLM dialogue
+produces new content each invocation. v6.0.3 declares `idempotent: true`
+because the CLI verbs themselves are static advisory prints with no LLM
+call and no externalRefs to reconcile — the engine's idempotency check
+is "safe to retry without reconciliation," not "produces byte-identical
+output." Justified inline at the top of `src/cli/brainstorm.ts` and
+`src/cli/spec.ts` plus a deviation block in the recipe. Once the CLI
+verbs grow real LLM bodies (a future v6.x lift), the declaration may
+flip and a `spec-file` externalRef will land on every successful run.
+
+Engine-off code paths are unchanged for both verbs; existing tests pass
+without modification.
+
+### Test count
+
+1367 → 1378 (+11). +5 cases for `brainstorm-engine-smoke.test.ts`, +5
+cases for `spec-engine-smoke.test.ts`, +1 case for `spec` joining
+`MIGRATED_VERBS` in `json-channel-discipline.test.ts`. Both new smoke
+files mirror `costs-engine-smoke.test.ts`: engine off → no run dir;
+engine on → state.json + events.ndjson with the right lifecycle
+(`run.start` → `phase.start` → `phase.success` → `run.complete`);
+env-resolved; CLI override beats env. Typecheck clean.
+
+### Deliberately deferred
+
+- Wrapping the six remaining pipeline phases (`plan`, `implement`,
+  `migrate`, `validate`, `pr`, `review`). One or two per release across
+  v6.0.4+. A parallel agent works `plan` + `review` for v6.0.4.
+- Promoting `brainstorm`/`spec` from advisory shims to full LLM-bearing
+  CLI verbs. The Claude Code skill remains the user-facing entry point;
+  the CLI wraps exist so the engine has a place to record run-state for
+  future multi-phase orchestration.
+
+## v6.0.2 — Engine wire-up Part B (2026-05-06)
+
+**The headline.** v6.0.1 wrapped the first pipeline phase (`scan`) through
+`runPhase`. v6.0.2 continues the mechanical wrap pattern from the recipe at
+[`docs/v6/wrapping-pipeline-phases.md`](docs/v6/wrapping-pipeline-phases.md)
+with two more single-shot verbs:
+
+- **`costs`** ([#96](https://github.com/axledbetter/claude-autopilot/pull/96)) —
+  pure read-only summary of the local cost ledger. The cleanest possible
+  wrap: `idempotent: true, hasSideEffects: false`, no provider, no LLM,
+  no file writes. CLI dispatcher passes `cliEngine` + `envEngine` through;
+  `--config` flag also wired since the engine resolver consults config.
+- **`fix`** ([#96](https://github.com/axledbetter/claude-autopilot/pull/96)) —
+  applies LLM-generated patches to local files. Declared
+  `idempotent: true` (same finding + same file content → same patch) and
+  `hasSideEffects: false` (no remote / git push / PR creation in the
+  existing flow — purely local file edits, which the recipe defines as
+  platform-side-effect-free). If/when fix grows a `--push` mode it will
+  flip to `hasSideEffects: true` with a `git-remote-push` externalRef.
+
+**Documented deviation from the recipe.** Both wraps follow the recipe
+mechanically. `fix` adds one explicit deviation: its phase body emits
+per-finding console output and reads a [y/n/q] confirmation via
+`readline`. Pure side-effect-free phase bodies are the recipe default,
+but interactive verbs are an explicit exception (same precedent as
+`scan` keeping its LLM call inside `executeScanPhase`). The summary line
++ exit-code logic still lives in `renderFixOutput` so the engine path's
+idempotency isn't coupled to the final stdout shape. See the new "Note
+on interactive verbs" section at the bottom of the wrapping recipe.
+
+Engine-off code paths are byte-for-byte unchanged for both verbs;
+existing tests pass without modification.
+
+### Test count
+
+1356 → 1367 (+11). +6 cases for `costs-engine-smoke.test.ts`, +5 cases
+for `fix-engine-smoke.test.ts`. Both mirror `scan-engine-smoke.test.ts`:
+engine off → no run dir; engine on → state.json + events.ndjson with
+the right lifecycle (`run.start` → `phase.start` → `phase.success` →
+`run.complete`); env-resolved; CLI override beats env. Typecheck clean.
+
+### Deliberately deferred
+
+- Wrapping the seven remaining pipeline phases (`brainstorm`, `plan`,
+  `implement`, `migrate`, `validate`, `pr`, `review`). One or two per
+  release across v6.0.3+.
+- Flipping the v6.0 built-in default to ON. v6.1 territory.
+
+## v6.0.1 — Engine wire-up Part A (2026-05-05)
+
+**The headline.** v6.0 shipped the engine modules but left the user-facing
+knobs un-wired. This release lights up the three knobs (`--engine` /
+`--no-engine` CLI flag, `CLAUDE_AUTOPILOT_ENGINE` env var,
+`engine.enabled` config key) with explicit precedence (CLI > env > config
+> built-in default) and wraps the **first** pipeline phase — `scan` —
+through `runPhase`. Every other pipeline phase still bypasses the engine;
+those land one or two per PR across subsequent v6.0.x releases following
+the recipe at [`docs/v6/wrapping-pipeline-phases.md`](docs/v6/wrapping-pipeline-phases.md).
+
+The engine still ships **OFF** by default in v6.0.x. The default flip to
+**ON** lands in v6.1 per [`docs/specs/v6.1-default-flip.md`](docs/specs/v6.1-default-flip.md).
+
+### What landed (PR #95)
+
+- **`resolveEngineEnabled()` precedence resolver.** Pure / no-IO function
+  in `src/core/run-state/resolve-engine.ts`. Inputs:
+  `{cliEngine?, envValue?, configEnabled?, builtInDefault?}`. Outputs:
+  `{enabled, source, reason, invalidEnvValue?}`. Accepts case-insensitive
+  env values `on/off/true/false/1/0/yes/no` (plus whitespace tolerance);
+  invalid values fall through to the next-lowest precedence layer and
+  surface the raw string in `invalidEnvValue` so the caller can emit a
+  `run.warning`. **+45 unit tests** covering every precedence layer, every
+  accepted env form, the conflict rules, and the invalid-env fallthrough.
+- **CLI flag parsing in `src/cli/index.ts`.** New `parseEngineCliFlag()`
+  helper rejects the conflict case (both `--engine` AND `--no-engine`)
+  with `invalid_config` exit 1. Wired into the `scan` case to pass
+  `cliEngine` + `envEngine` (from `process.env.CLAUDE_AUTOPILOT_ENGINE`)
+  through to `runScan`.
+- **Config schema** (`src/core/config/types.ts` + `schema.ts`). New
+  optional `engine.enabled: boolean` knob; schema rejects unknown
+  sub-keys (`additionalProperties: false`).
+- **Help text** (`src/cli/help-text.ts`). New `GLOBAL_FLAGS_BLOCK`
+  documents `--json` / `--engine` / `--no-engine` + the precedence
+  matrix + scope (scan only in v6.0.1; rest follows the recipe). Per-verb
+  `scan` Options block adds the new flags so `claude-autopilot help scan`
+  is self-contained.
+- **`scan` pilot phase wrapping** (`src/cli/scan.ts`). Refactored the
+  LLM-call-and-finding-processing portion into `executeScanPhase(input)`
+  → `ScanOutput` (pure, no console output, no exit-code logic). Defined
+  `RunPhase<ScanInput, ScanOutput>` with `name: 'scan'`,
+  `idempotent: true`, `hasSideEffects: false`. Engine-on path:
+  `createRun()` → `runPhase()` → `run.complete` event +
+  `replayState`/`writeStateSnapshot` refresh + best-effort lock release
+  in `finally`. Engine-off path: `executeScanPhase(input)` directly,
+  byte-for-byte unchanged from v6.0. Rendering extracted into
+  `renderScanOutput()` so the engine path's idempotency isn't coupled
+  to console output. Test seam (`__testReviewEngine`) lets the smoke test
+  inject a fake without an LLM key.
+- **End-to-end smoke test** (`tests/cli/scan-engine-smoke.test.ts`).
+  Drives `runScan` with the engine on against a tmp project; asserts
+  `state.status === 'success'`, single `scan` phase with the right
+  `idempotent` / `hasSideEffects` flags, monotonic seq numbers, and the
+  full lifecycle (`run.start` → `phase.start` → `phase.success` →
+  `run.complete`). Five cases including engine-off (no run dir),
+  env-resolved, CLI override, and invalid-env-fallthrough warning.
+- **Wrapping recipe doc** (`docs/v6/wrapping-pipeline-phases.md`).
+  Six-step recipe + phase-status table + idempotency decision tree +
+  worked example (scan) + a checklist subsequent v6.0.x PRs follow when
+  wrapping the remaining ten pipeline phases (`brainstorm`, `plan`,
+  `implement`, `migrate`, `validate`, `pr`, `review`, `fix`, `costs`).
+- **Migration guide** (`docs/v6/migration-guide.md`). "What works today"
+  list updated — three knobs move from "wiring pending" to "wired (limited
+  to scan)". Other phases still tracked under "wiring pending."
+- **Spec reconciliation** (`docs/specs/v6-run-state-engine.md`). New "What
+  was actually built (v6.0.1 — Part A)" block.
+
+### Test count
+
+1306 → 1356 (+50). Typecheck clean. Existing 1306 tests continue to pass
+unchanged — the engine-off code path for `scan` is byte-for-byte
+identical to v6.0.
+
+### Deliberately deferred
+
+- Wrapping of any other pipeline phase. Lands one or two per PR across
+  v6.0.2+ following the recipe.
+- Flipping the v6.0 built-in default to ON. v6.1 territory.
+- Removing `--no-engine`. v7 territory.
+
+## v6.0 — Run State Engine (2026-05-05)
+
+**The headline.** Autopilot moves from a stateless command-stream to a
+checkpointed, resumable, budget-bounded, observable pipeline. Every run gets
+a ULID and a per-project directory at `.guardrail-cache/runs/<ulid>/`.
+Every state transition appends a typed event to `events.ndjson` and updates
+`state.json` atomically. Two-layer budget enforcement (advisory `estimateCost`
+preflight + mandatory runtime guard) hard-stops runaway spend before it
+happens. Every CLI verb grows a `--json` flag with strict stdout/stderr
+channel discipline so CI consumers can drive the pipeline programmatically.
+Side-effect phase replay decisions consult persisted `externalRefs` plus a
+live provider read-back so resume is safe by construction. **v6.0 ships
+with the engine OFF by default — opt-in via `engine.enabled: true` (config
+wiring across 6.0.x point releases). Default flips to ON in v6.1.** See
+[`docs/v6/migration-guide.md`](docs/v6/migration-guide.md) for the v5.x → v6
+walkthrough and [`docs/v6/quickstart.md`](docs/v6/quickstart.md) for the
+five-minute version.
+
+### Per-phase landings
+
+- **Phase 1 — Run State Engine persistence layer ([#86](https://github.com/axledbetter/claude-autopilot/pull/86)).** `RunState` / `RunEvent` / `PhaseSnapshot` / `ExternalRef` / `WriterId` types in `src/core/run-state/types.ts`. Pure-TS 26-char Crockford Base32 ULID generator (`ulid.ts`). Per-run advisory lock via `proper-lockfile` + `.lock-meta.json` sidecar with PID + SHA-256-hashed hostname; off-host writers default to alive (fail closed) so a network-mounted lock can't be stolen. Durable append protocol for `events.ndjson` (`open(O_APPEND)` → `write` → `fsync(fd)` → `close` per event) with monotonic `seq` via `.seq` sidecar. Truncated last-line detection emits `run.recovery(reason: 'recovered-from-partial-write')` and continues; mid-file corruption throws `partial_write` immediately. Atomic snapshot writer for `state.json` (`open(.tmp)` → `fsync(fd)` → `rename` → `fsync(dirfd)`; tmpfs/SMB compatibility via swallowed EISDIR/EPERM/ENOTSUP on the dir-fsync). `recoverState` falls back to events replay when `state.json` is missing/corrupt. `createRun` / `listRuns` / `gcRuns` lifecycle helpers; symlink-safe GC. New `ErrorCode` variants: `lock_held`, `corrupted_state`, `partial_write`. **+56 tests.**
+- **Phase 2 — Phase wrapper + lifecycle ([#87](https://github.com/axledbetter/claude-autopilot/pull/87)).** `RunPhase<I, O>` interface (`idempotent` / `hasSideEffects` / `estimateCost?` / `run` / `onResume?`). `runPhase` orchestrator emits `phase.start` → `phase.success`/`failed` and gates idempotent short-circuit + side-effecting replay. Atomic per-phase snapshot writer (`writePhaseSnapshot` with path-traversal rejection on phase names). Hidden CLI verb `claude-autopilot internal log-phase-event` exposed via `cli-internal.ts` so markdown-driven skills can append events without importing the engine. Sub-phase nesting via synthetic `phaseIdx` encoding (`parentIdx * 1000 + childOrdinal`). **+27 tests.** Spec deviation: idempotent-replay short-circuit emits `run.warning(details.reason: 'idempotent-replay')` instead of a new `phase.skipped` event variant — durable log doesn't need a new shape since the snapshot is identical.
+- **Phase 3 — `runs` / `run resume` CLI ([#88](https://github.com/axledbetter/claude-autopilot/pull/88)).** Six verbs: `runs list` (newest-first, `--status` filter), `runs show <id>` (state + optional events tail), `runs gc` (default 30-day cutoff, confirmation gate), `runs delete <id>` (terminal-status guard + lock acquisition), `runs doctor` (replay vs snapshot drift; `--fix` rewrites), `run resume <id>` (**lookup-only** in v6.0 — identifies next phase + decision rationale; live execution wires in 6.1+). Every verb supports `--json` envelope output (v1 schema). New `Engine` group in `HELP_GROUPS`. Decision vocabulary (`retry` / `skip-idempotent` / `needs-human` / `already-complete`) preserved as a thin wrapper around the canonical `decideReplay` matrix introduced in Phase 6. **No changes to existing CLI verbs.**
+- **Phase 4 — Budget enforcement ([#89](https://github.com/axledbetter/claude-autopilot/pull/89)).** `BudgetConfig` (`perRunUSD`, `perPhaseUSD?`, `councilMaxRecursionDepth?`, `bgAutopilotMaxRoundsPerSelfEat?`, `conservativePhaseReserveUSD?`). `checkPhaseBudget` pure decision function with two-layer policy: (1) advisory — uses `estimateCost.high` if the phase declares one; (2) mandatory — runs regardless, enforces `actualSoFar + conservativePhaseReserveUSD <= perRunUSD` so phases without `estimateCost` still trigger budget gates. `runPhase` emits a `budget.check` event with full decision rationale (`{phase, phaseIdx, estimatedHigh, actualSoFar, reserveApplied, capRemaining, decision, reason}`) before every spawn; throws `GuardrailError(budget_exceeded)` on hard-fail. Council synthesizer recursion bounded via `councilMaxRecursionDepth` — exceeded calls return `status: 'partial'` rather than continuing. **+25-30 tests.**
+- **Phase 5 — Typed JSON events + strict `--json` channel discipline ([#90](https://github.com/axledbetter/claude-autopilot/pull/90)).** `--json` flag now lives on every Review / Pipeline / Deploy / Migrate / Diagnostics verb. Strict channel contract enforced by a dispatcher-level wrapper (`runUnderJsonMode` in `src/cli/json-envelope.ts`): exactly **one** JSON envelope on stdout per invocation; **only** NDJSON event lines on stderr (synthetic `run.warning` for legacy text via `installJsonModeChannelDiscipline` console-wrap); ANSI color codes stripped; interactive prompts hard-fail with `EXIT_NEEDS_HUMAN = 78` and the envelope's `nextActions` field carries the resume hint. Text-mode behavior unchanged. **`tests/cli/json-channel-discipline.test.ts` asserts the invariants per migrated verb.**
+- **Phase 6 — Idempotency contracts + provider read-back ([#91](https://github.com/axledbetter/claude-autopilot/pull/91)).** `decideReplay` pure decision matrix in `replay-decision.ts` maps `(priorSuccess, idempotent, hasSideEffects, refs, readbacks, forceReplay)` → `'retry' | 'skip-already-applied' | 'needs-human' | 'abort'`. Pluggable `ProviderReadback` registry in `provider-readback.ts` with built-in read-backs for `github` (via `gh` CLI), `vercel` / `fly` / `render` (via the deploy adapters), `supabase` (via `migration_state`). All read-backs **fail closed** — any throw, parse failure, or unrecognized state collapses to `existsOnPlatform=false, currentState='unknown'` so the matrix routes to `needs-human` instead of a silent skip. `runPhase` wires `decideReplay` (replaces Phase 2's hard-coded throw). New `replay.override` event variant emitted when `--force-replay` flips a refusal into a retry; `foldEvents` records overrides on `phase.meta.replayOverrides`. `PhaseSnapshot.result` field added so `skip-already-applied` returns the prior output without re-execution. CLI lookup (`runRunResume`) delegates to the same `decideReplay` so prediction matches live execution. **+55 tests.**
+- **Phase 7 — Live adapter certification suite ([#92](https://github.com/axledbetter/claude-autopilot/pull/92)).** Five live assertions × three providers (Vercel + Fly + Render): deploy success, auth failure, 404, rollback, log streaming with redaction-on-planted-secret. Env-gated via `resolveProviderEnv()` — runs report `skipped` until the operator adds the seven `*_TEST` GitHub Secrets per `docs/adapters/cert-suite.md`. Flake-control harness (`tests/adapters/live/_harness.ts`) implements per-provider 3-attempt retry budget with exp backoff (1s / 4s / 16s) on transient categories, hard-fail (no retry) on auth/404/schema-mismatch, soft-fail with 3-strike escalation on rollout/log-streaming flakes; **+42 unit tests** for the harness alone (run under regular `npm test`, no live creds required). Nightly CI workflow at `.github/workflows/adapter-cert.yml` (09:00 UTC + manual `workflow_dispatch`); uploads `events.ndjson` + `log-tail.txt` artifacts on every run. **Spec deviation:** Fly cert needs a third env var (`FLY_IMAGE_TEST`) since the Fly adapter doesn't build images per the v5.6 design.
+- **Phase 8 — Docs + migration guide ([#94](https://github.com/axledbetter/claude-autopilot/pull/94), this PR).** `docs/v6/migration-guide.md` walks v5.x users through the opt-in flow with a precedence matrix, troubleshooting recipes, the per-phase idempotency table, and the v6.0 → v6.1 default-flip plan. `docs/v6/quickstart.md` is the five-minute version. README gains a "Run State Engine (v6)" section. CHANGELOG (this entry) bundles every phase. Spec gets a Phase 8 reconciliation block + a Status column on the implementation phases table. New `docs/specs/v6.1-default-flip.md` outlines the stabilization criteria for flipping `engine.enabled` to `true` by default and removing `--no-engine`.
+- **Spec — Codex-reviewed twice ([#85](https://github.com/axledbetter/claude-autopilot/pull/85)).** Two passes through Codex 5.3 hardened the persistence protocol (durable append + atomic snapshot ordering), promoted `events.ndjson` to source-of-truth with `state.json` as a derived cache, mandated copy-not-symlink for artifacts, added the two-layer budget policy with a mandatory runtime guard, formalized the strict `--json` channel discipline, defined the external-operation ledger for replay safety (`ExternalRef` + provider read-back), pinned the precedence matrix, and added flake-control parameters for the live adapter cert suite.
+
+### Codex / council pricing — from the GPT-5.5 swap ([#93](https://github.com/axledbetter/claude-autopilot/pull/93))
+
+- **Default codex/council model bumped `gpt-5.3-codex` → `gpt-5.5`.** OpenAI
+  released GPT-5.5 (codename Spud) on 2026-04-23 — better at coding than 5.4
+  with fewer tokens, available via standard Responses/Chat Completions API
+  at `gpt-5.5` (no `-codex` suffix). Pricing **doubles** to $5/1M input +
+  $30/1M output, so the per-adapter `COST_PER_M_INPUT/OUTPUT` defaults moved
+  in lockstep — without this, every cost-ledger entry would silently halve.
+  New canonical pricing table at `src/adapters/pricing.ts` keeps the legacy
+  `gpt-5.3-codex` and `gpt-5.4` entries for back-compat with pinned
+  `CODEX_MODEL`/`council.models[].model` configs. Override via env vars
+  (`CODEX_MODEL`, `CODEX_COST_INPUT_PER_M`, `CODEX_COST_OUTPUT_PER_M`).
+
+## v5.6.0 — Fly.io + Render deploy adapters (2026-05-04)
+
+### Added
+
+- **`@delegance/claude-autopilot deploy --adapter fly`** — first-class Fly.io adapter. Image-based releases via the Machines API (image must be pre-pushed via `fly deploy --build-only --push`), polling-based status, **WebSocket log streaming**, **native rollback** with simulated fallback when the API endpoint is unavailable. `FLY_API_TOKEN` env var; auth doctor warns when missing.
+- **`@delegance/claude-autopilot deploy --adapter render`** — first-class Render adapter. REST API deploys (with optional `clearCache`), service-scoped status polling at `GET /v1/services/{serviceId}/deploys/{deployId}`, REST-polling log stream with `(timestamp, logId)` cursor dedup, **simulated rollback** by re-deploying the previous successful commit. `RENDER_API_KEY` env var; auth doctor warns when missing.
+- **`DeployAdapterCapabilities` interface** — adapters declare `streamMode: 'websocket' | 'polling' | 'none'` and `nativeRollback: boolean`. CLI prints a one-line stderr notice for polling-mode adapters under `--watch` so users understand why log lines arrive in batches.
+- **Bounded auto-rollback orchestration in `src/cli/deploy.ts`** — when health check fails after deploy and `rollbackOn: [healthCheckFailure]` is configured, the CLI fires exactly one rollback (no chains), with `runHealthCheck` capped at 5 attempts × 6s backoff (~30s window). New terminal `DeployResult.status` values: `fail_rolled_back` and `fail_rollback_failed`.
+- **HTTP-status error taxonomy** — new `not_found` `ErrorCode` joins the union; per-adapter mapping: 401/403→`auth`, 404→`not_found`, 422/400→`invalid_config`, 5xx→`transient_network` (retryable). Provider request-id headers (`Fly-Request-Id`, `x-request-id`) captured into `error.details` for support tickets.
+- **Mandatory log redaction across all adapters** — every log line surfaced into `DeployResult.output` or PR-comment bodies runs through `redactLogLines()` (defaults: `AKIA…`, `sk-…`, `eyJ…`, `ghp_`, `xoxb-`, plus user-configurable `config.persistence.redactionPatterns`). Closes a real existing security hazard in the v5.4 Vercel adapter that was emitting unredacted logs into PR comments.
+- **Shared `src/adapters/deploy/_http.ts`** — extracted `fetchWithRetry` + `safeReadBody` helpers used by Vercel, Fly, and Render adapters; one canonical retry implementation to maintain.
+
+### Fixed
+
+- **Bugbot caught + autopilot fixed 4 real bugs across the v5.6 self-eat phases.** HIGH on Phase 2 (Render service-scoped URL — `pollUntilTerminal` and `status()` were using shorthand `/v1/deploys/{id}` which doesn't exist on Render's API). MEDIUM on Phase 3 (Render cursor dedup wasn't sorting same-ms entries by id, silently dropping out-of-order siblings). LOW on Phase 4 (`printAutoRollback` hardcoded "failed 3x" but the constant is now 5). LOW on Phase 5 (`getPreviousFileContent` was being called for `.sql` files where `previousContent` is ignored, wasting a `git show` spawn per migration).
+- **Schema-alignment diff-aware Prisma parsing (PR #44, schema-alignment cleanup)** — `getPreviousFileContent` now defaults to a CI-aware base ref (`GITHUB_BASE_REF` → `origin/<base>`, then `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`, fallback `HEAD~1`) instead of always reading from `HEAD` (which gave empty diffs in CI). Dropped models now emit `drop_column` for every field of the removed model.
+- **Tombstone CLI no longer crashes with a stack trace when presets are missing (PR #82)** — schema-validator was running file IO at module load time, so every `claude-autopilot --version` call eagerly read `presets/aliases.lock.json` + `presets/schemas/migrate.schema.json`; missing presets crashed the CLI before it could format an error. Now lazy-init via memoized `getValidator()`.
+
+## v5.5.2 — Framework-agnostic /migrate (2026-04-30)
+
+### Added
+
+- **Working examples for Rails, Alembic, Django, golang-migrate, Prisma, Drizzle, dbmate, Flyway, supabase-cli, custom scripts** in `skills/migrate/SKILL.md`. The dispatcher was always framework-agnostic, but the prior doc text only described the Supabase path.
+- **Detector `defaultCommand` fills** for `prisma-push`, `drizzle-push`, `golang-migrate`, `typeorm` so `claude-autopilot init` produces a working `stack.md` on first try for these toolchains.
+
+### Fixed
+
+- **`/migrate` skill description rewritten** as a generic dispatcher description with a "when to use migrate-supabase instead" callout. Anyone running `migrate@1` in a non-Supabase repo no longer sees Supabase-specific instructions.
+
+## v5.5.1 — `openai` SDK now optional (2026-04-30)
+
+### Changed
+
+- **`openai` moved to `optionalDependencies`** alongside `@anthropic-ai/sdk`, `@google/generative-ai`, `@modelcontextprotocol/sdk`. All four LLM SDKs are now optional. `npm install --omit=optional` shed grows to **~26 MB** (was ~13 MB after v5.5.0). `scripts/autoregress.ts` migrated to `loadOpenAI()` — the last direct `import OpenAI` outside the adapter layer.
+
+### Notes
+
+- Council runner already handles missing-synth-SDK gracefully — returns `status: 'partial'` with the friendly install hint surfaced via the synthesis error field. Users with only `ANTHROPIC_API_KEY` get a partial result with model responses preserved.
+
+## v5.5.0 — Lazy-load LLM SDKs + Vercel auth doctor (2026-04-30)
+
+### Added
+
+- **`src/adapters/sdk-loader.ts`** with `loadAnthropic` / `loadOpenAI` / `loadGoogleGenerativeAI` + `isSdkInstalled` helper. Friendly `GuardrailError` on `MODULE_NOT_FOUND` points at the exact `npm install` command.
+- **Phase 6 of v5.4 spec — Vercel auth doctor.** `claude-autopilot doctor` detects `deploy.adapter: vercel` in `guardrail.config.yaml` and warns when `VERCEL_TOKEN` is missing.
+- **LLM SDK install-state surface in doctor** — shows which optional LLM SDKs are actually installed.
+
+### Changed
+
+- **`@anthropic-ai/sdk`, `@google/generative-ai`, `@modelcontextprotocol/sdk` moved to `optionalDependencies`**. Six adapters converted from top-level import to dynamic load. Users with `--omit=optional` shed ~13 MB and only need the SDK matching their API key.
+
+## v5.4.0 — Vercel first-class deploy adapter (2026-04-30)
+
+### Added
+
+- **`@delegance/claude-autopilot deploy --adapter vercel`** — first-class Vercel adapter via the v13 deployments API. Returns `dpl_xxx` IDs, polls status until terminal, populates `deployUrl` / `buildLogsUrl` / `output`. Auth via `VERCEL_TOKEN`.
+- **`--watch` SSE+NDJSON log streaming** — subscribes to `/v2/deployments/<id>/events?builds=1`, prints to stderr in real time. Reconnects once with exp backoff on disconnect.
+- **`claude-autopilot deploy rollback` + `deploy status`** — CLI subverbs over the adapter's `rollback()` / `status()` methods. `--to <id>` overrides "previous prod deploy" lookup.
+- **Auto-rollback on health-check failure** — when `rollbackOn: [healthCheckFailure]` is set in config, the CLI promotes the previous prod deploy if the post-deploy health check fails. PR comment shows both URLs (new + rolled-back-to).
+- **`<!-- claude-autopilot-deploy -->` upserting PR comment** — single comment is updated in place across deploy → log-stream → health-check → rollback, instead of spamming the PR with multiple comments.
+
+### Fixed
+
+- **Bugbot caught explicit `--config <missing>` was silently ignored on PR #63 (Phase 3)** — autopilot fixed it with a regression test in 4 minutes.
+- **Phase 4 introduced a regression in Phase 2's `--watch` test surface; caught via `npm test` before PR opened**, autopilot adapted spec interpretation (made health-check opt-in instead of falling back to deployUrl) and documented the deviation.
+
+### Notes
+
+- This release was **shipped as four self-eat PRs** (#59, #61, #63, #64) where autopilot implemented its own next phase end-to-end. Cumulative cost ~\$17.50, wall clock ~82 min, 47 new tests. See [DEMO.md](DEMO.md) for the full proof set.
+- v5.3 "deploy phase" was superseded by v5.4 — the adapter pattern subsumed the generic-command-only design from the in-flight v5.3 spec.
+
+## v5.2.2 — Demo polish
+
+### Fixed
+
+- **Cost log skips zero-token entries.** Setup-flow scans, dry-runs, and no-findings paths were polluting the log with empty rows that drowned real review entries in `claude-autopilot costs` output.
+- **`costs` shows scope.** Output now explicitly notes "per-project — scoped to `<cwd>/.guardrail-cache/costs.jsonl`" so users understand it's not a global aggregate.
+- **`pr` no longer hard-fails on missing config.** First-run on a fresh repo now auto-detects + prints a remediation line pointing at `setup`.
+
+### Added
+
+- **DEMO.md committed at repo root.** Real end-to-end pipeline run on randai-johnson (multi-file Python integration, 12 min wall clock, $2.20 spend, 5 new tests, zero manual intervention). Linkable from external docs / pitch material.
+
+## v5.2.1 — Stress-test polish
+
+### Fixed
+
+- **venv detection in tests phase.** `pytest -q` now resolves to `<project>/.venv/bin/pytest` (or `venv/`, `env/`) when present, so `claude-autopilot pr` no longer reports "tests failed" on Python repos with venv-installed pytest.
+- **`autoregress` 100% broken on global install** — the bridge resolved `SCRIPT` to `dist/scripts/autoregress.ts` under the compiled layout, but `scripts/` ships at the package root. Every invocation threw `ERR_MODULE_NOT_FOUND`. Now uses `findPackageRoot` + existence check.
+- **Council in python preset.** Python preset now ships a commented `council:` template (mirrors the generic preset). Out-of-the-box `init --preset python` no longer requires manual schema discovery.
+- **Regression-lane fixture top-level await.** CI workflow's `npx tsx -e "..."` blocks wrapped in `async () => {...}` so esbuild's CJS output accepts them. Plus expected-ledger.json updated to match v5.2.0's new version format.
+
+## v5.0.8 — Line extraction + fix gate
+
+### Fixed
+
+- **Parser extracts "line N" / "on line N" / "at line N" from prose** when not adjacent to a file ref. Previously findings shipped with file but no line, so `fix --dry-run` reported "no fixable findings" on a non-empty findings list.
+- **`fix` distinguishes actionable (file present) from fixable (file + line).** Dry-run surfaces actionable findings even when line-less, with a clear message about why the LLM-fix loop can't act on them.
+
+## v5.0.7 — File backfill + cost ledger consolidation
+
+### Fixed
+
+- **Single-file scan unconditionally backfills the file path.** The 5.0.6 fallback only triggered on `<unspecified>`, so prose-noise like `"n.r"` slipped through and broke `fix`.
+- **`pr-desc` and `council` now persist to the cost ledger.** Previously only `scan` and `run` were tracked, so `claude-autopilot costs` showed misleadingly low totals after multi-call sessions.
+- **Single-letter code extensions removed from bare-reference parser** (c/d/h/m/r/s) — they still match when backtick-wrapped, but bare matches like "n.r" no longer slip through.
+- **`appendCostLog` swallows write errors centrally.** Cost log is observability, not a contract — a read-only FS or full disk no longer crashes commands that already succeeded.
+
+## v5.0.6 — Setup YAML + branch fallback
+
+### Fixed
+
+- **`setup` no longer writes duplicate `testCommand` keys.** Several presets (go, python, python-fastapi, rails-postgres) ship with their own `testCommand:` line; `cli/setup.ts` was unconditionally appending another, producing invalid YAML that hard-failed every command after `setup` on those stacks.
+- **Single-file scan backfills file path** (initial fix; superseded by v5.0.7's unconditional version).
+- **Branch-derived PR titles default to `chore:` for unknown prefixes.** `autopilot-test/validate-weights` → `chore: validate weights` instead of `autopilot test validate weights` (which fails commitlint).
+
+## v5.0.5 — Python detect + parser hardening
+
+### Added
+
+- **`presets/python/`** — general Python config (pytest, ruff, hardcoded-secrets, common protected paths). Detector now picks it for any `pyproject.toml` or `requirements.txt` without FastAPI signals (was falling through to the JS/Generic preset).
+
+### Fixed
+
+- **Parser rejects "e.g" / "i.e" / "etc" prose as file refs.** The prior regex `\.[a-z]{1,6}` accepted any 1-6 letter suffix, so prose like "(e.g. dict, list)" was matched. Bare references now require a known code-file extension.
+- **`pr-desc` real titles.** Prompt now explicitly asks for a Title line; parser falls through to a branch-derived conventional-commit title (`fix/cost-tracker` → `fix: cost tracker`), then first summary bullet, then `chore: update` only as a last resort.
+- **`runReviewOnTestFail` default flipped to `true`.** Failed/missing test commands no longer silently kill the LLM review phase. Strict gating still available via explicit `false`.
+
+## v5.0.4 — Council Responses API
+
+### Fixed
+
+- **Council 404s on `gpt-5.3-codex` resolved.** Codex variants and o-series reasoning models are Responses-API-only — the council adapter only used `client.chat.completions`. Now branches by model name (`/codex|^o[1-9]|^gpt-5\.3-/`) to use `client.responses.create()` for those models. Fixes the multi-model differentiator for any user with only `OPENAI_API_KEY`.
+- **Generic preset ships a working council template.**
+
+## v5.0.3 — Cost tracker
+
+### Fixed
+
+- **Codex adapter computes `costUSD`** (was returning `usage` without a cost field, so every codex run logged $0).
+- **`scan` now persists to cost log** (was only `run` writing entries).
+
+## v5.0.2 — Post-install friction
+
+### Fixed
+
+- **preflight `tsx` false-positive eliminated.** Every fresh global install reported `✗ tsx available` blocker because the bundled tsx wasn't checked. Now uses `findPackageRoot(import.meta.url)`.
+- **Top-level `unhandledRejection` + `uncaughtException` handlers** format `GuardrailError` as a single-line red message instead of a Node stack trace. `CLAUDE_AUTOPILOT_DEBUG=1` re-enables stack.
+- **Tarball trimmed:** dropped `src/` + `*.map` from `files` array → 319 files / 182 kB packed (was 726 / 382 kB), -56% / -52%.
+- **Stale strings:** `@alpha` install hint → `@latest`; `npx guardrail run` blocker text → `claude-autopilot run`; init deprecation banner removed (both verbs work).
+
+## v5.0.1 — Types + tombstone
+
+### Fixed
+
+- **Ships `dist/src/index.d.ts`** for TypeScript consumers.
+- **Tombstone `@delegance/guardrail` package** publishes a forwarder pointing at the renamed package; pre-rename versions deprecated with migration message.
 
 ## v5.2.0 — Migrate skill generalization