feat(code-review): in-process run-prefix segment runner + subprocess A/B parity oracle (PLN-1229 Phase 1)

CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to the claude-plugins project will be documented in this fil
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Entries are listed newest-first; each plugin section is treated as released when merged to `main`.
 
+### code-review v3.2.0
+
+#### Added
+- New `run-prefix` helper subcommand: a resumable, in-process runner for the deterministic review prefix (stages `setup` through `cache-check`). It reads `run_plan.json` and walks the stages in one process — resolving each stage's placeholder tokens from prior-stage artifacts, redirecting stdout per stage, and honoring `on_failure` policies and validation gates — instead of one orchestrator turn per stage. It pauses only at genuine decision points (the hygiene-only early exit, a signal-extraction or coverage-critic singleton that needs an agent, or the route/partition boundary), emitting a status JSON that tells the orchestrator what to do next, and resumes from a given stage on re-invocation. A failed `continue_with_coverage_gap` stage emits a canonical `agent-failure` system finding so the gap is auditable. Documented as the `run-prefix` result contract in `SCHEMA.md`.
+- Subprocess A/B parity oracle for the prefix: the golden-fixture harness now walks each fixture two ways — one subprocess per stage (reproducing the current per-stage orchestrator walk) versus the new `run-prefix` runner — and asserts byte-identical normalized artifacts through `cache-check` across all seven fixtures, plus a pause-sequence check pinning the resumable segment boundaries. Contract tests cover token resolution, resumable dependency reconstruction, singleton detection, `on_failure` handling, and the runner's error/boundary returns.
+- `run-prefix` failure diagnostics are attributed per stage: each in-process stage's stderr is captured and folded into the returned status message (and, for a `continue_with_coverage_gap` stage, into the emitted `agent-failure` finding's explanation), and an unexpected stage crash logs its full traceback — so a batched-runner failure stays diagnosable without reproducing it, now that one process spans many stages.
+
 ### code-review v3.1.1
 
 #### Added

plugins/code-review/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "code-review",
   "description": "Code review plugin",
-  "version": "3.1.1",
+  "version": "3.2.0",
   "author": {
     "name": "ClosedLoop",
     "email": "support@closedloop.ai"

plugins/code-review/README.md

@@ -37,7 +37,7 @@ plugins/code-review/
     python/golden_fixture_harness.py     Golden fixture harness: replays canonical inputs through helper subcommands and diffs against expected envelopes (PLN-719 Phase 8)
     python/test_golden_fixtures.py       Pytest driver that runs every fixture under tools/python/fixtures/
     python/fixtures/<name>/              Per-fixture directory (config.yaml + inputs/ + expected/); 3 full scenarios + 6 README-stubs for future coverage
-    python/prefix_golden_harness.py      Prefix golden harness: walks the deterministic prefix (setup→spawn-spec) in-process against real git fixtures and snapshots every intermediate artifact (PLN-1229 Phase 0)
+    python/prefix_golden_harness.py      Prefix golden harness + subprocess A/B parity oracle: walks the deterministic prefix against real git fixtures — in-process for golden snapshots, and per-stage-subprocess vs `run-prefix` for byte-equal parity (PLN-1229 Phase 0/1)
     python/test_prefix_golden.py         Pytest driver for the prefix harness: determinism oracle + golden diff across the prefix_fixtures/ matrix
     python/prefix_fixtures/<name>/       Per-fixture directory (expected/ golden snapshots); 7 branch scenarios (standard, fast-path, hygiene-only, empty-diff, cache-hit, since-last-review, coverage-critic)
 ```
@@ -231,6 +231,7 @@ The helper script is a multi-subcommand Python CLI. The orchestrator invokes it
 | `finalize-result` | Consolidates validated findings + coverage state + verdict into the canonical `review_result.json` envelope; deep-merges `<cr_dir>/telemetry.json` into the canonical `telemetry` block and populates `telemetry.cache_hit_rate["bha"]` from `cache_result.json` (PLN-719 Phase 7/9) |
 | `arbitrate-budget` | Applies the canonical reviewer cap policy; emits coverage gaps for required reviewers that overflow (PLN-719) |
 | `prepare-run` | Emits a declarative `run_plan.json` describing the 30-stage pipeline (PLN-719) |
+| `run-prefix` | Runs the deterministic prefix (setup→cache-check) in one process, resolving tokens and honoring gates/`on_failure`; pauses at the hygiene-only exit, a singleton needing an agent, or the route/partition boundary, emitting a status JSON and resuming from a given stage (PLN-1229) |
 
 ## GitHub CI Mode
 

plugins/code-review/SCHEMA.md

@@ -493,6 +493,56 @@ Stages from plans 01/03/05/06 are present in `run_plan.json` but marked
 
 ---
 
+## 7b. `run-prefix` result contract (PLN-1229)
+
+`run-prefix` runs the deterministic prefix (stages 01→`cache_check`) in ONE
+process instead of one orchestrator turn per stage. It reads `run_plan.json` +
+`setup.json` from `--cr-dir`, walks from `--resume-from` (default: the first
+plan stage), and stops at the next genuine decision point — emitting a status
+JSON (to stdout, or `--output <path>`) that tells the orchestrator what to do
+next. The runner is **resumable**: after handling a pause the orchestrator
+re-invokes `run-prefix --resume-from <resume_stage>`. Because each segment is a
+fresh process, the `depends_on` `completed` set is reconstructed from artifacts
+on disk (a prior stage counts as done iff its literal `expected_outputs` exist).
+
+**Result fields:**
+
+| Field           | Type            | Meaning                                                                 |
+| --------------- | --------------- | ----------------------------------------------------------------------- |
+| `next_action`   | string (enum)   | The pause reason — authoritative (read this, not the exit code).        |
+| `resume_stage`  | string \| null  | The stage id to pass as `--resume-from` on the next invocation.         |
+| `singleton`     | string \| null  | `"extract_signals"` \| `"coverage_critic"` when `needs_singleton`.      |
+| `failed_stage`  | string \| null  | The aborting stage id when `next_action == "error"`.                    |
+| `ran_stages`    | string[]        | Stage ids executed (or `continue`-failed) this segment, in order.       |
+| `message`       | string \| null  | Short diagnostic on `error`, else null.                                 |
+
+**`next_action` values:**
+
+| Value               | Fires at                              | Orchestrator does next                                                        |
+| ------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |
+| `needs_singleton`   | `stage_11` / `stage_15` `needs_agent` | Spawn the `singleton` agent, write its output, re-invoke from `resume_stage`. |
+| `hygiene_exit`      | Gate A (`hygiene_only` after hygiene) | Present hygiene findings and stop (no verdict/footer).                        |
+| `ready_for_route`   | reaching `stage_17_partition`         | Run Gate B (`route`) + partition + the rest of the walk.                      |
+| `error`             | a stage aborted / a gate failed       | Fall back to the per-stage walk from `failed_stage`; partials are preserved.  |
+
+`ready_for_route` distinguishes its two cases by `resume_stage`: a non-null
+`resume_stage` (`stage_17_partition`) is the normal boundary — run Gate B +
+partition from there. A **null** `resume_stage` means the walk reached the end
+of the plan without a partition stage (e.g. a depth tier that filters partition
+out); there is nothing left to route, so the orchestrator skips Gate B and
+partition and proceeds directly to the reviewer fleet.
+
+The exit code is `0` for every well-formed result (including `error`) — the
+`next_action` field is the contract. Route + partition (Segment 3) fold into the
+runner in Phase 2, at which point `ready_for_route` becomes `ready_for_reviewers`
+(carrying `fast_path` + `cache_status_message`). The `on_failure` policy of each
+stage is honored exactly as the Walker Contract prescribes: `abort` → `error`;
+`continue` → proceed; `continue_with_coverage_gap` → proceed after writing an
+`agent-failure` system finding to `agent_<stage>-failed.json` (collected by
+`collect-findings`).
+
+---
+
 ## 8. Determinism tiers (PLN-719 Section 8)
 
 | Tier                       | Definition                                                              | Required reviewers may depend? |