feat(code-review): fold Gate B route + partition into run-prefix (PLN-1229 Phase 2) (#174)

* feat(code-review): fold Gate B route + partition into run-prefix (PLN-1229 Phase 2)

Extend cmd_run_prefix to run the WHOLE deterministic prefix in one process,
through Gate B route + stage_17_partition + derive-spawn-spec, stopping at the
reviewer fleet.

- After stage_19_cache_check the runner invokes `route` itself (writing
  spawn.json.route), caches fast_path / max_bha_agents on the context, and on
  fast-path deletes the cached-BHA replay artifact.
- stage_17_partition is skipped entirely in fast-path (no partitions.json /
  patches_p<N>.txt); otherwise its args are augmented with
  --loc-budget 500 --max-files 25 --max-bha-agents <N>, swapping --diff-data to
  uncached_diff_data.json when a cache dir is active.
- The terminal return is now `ready_for_reviewers`, carrying fast_path,
  max_bha_agents, and cache_status_message so the orchestrator prints the
  routing + cache notices without re-reading spawn.json. A route failure
  surfaces as error with failed_stage="route".

Parity oracle: the subprocess A-side gains a subprocess `route` runner and the
same partition skip/augmentation, and both sides now run through to the reviewer
fleet — so the A/B byte-equality test covers the full prefix (incl.
partitions.json / spawn.json) across the fast-path and partitioned branches on
all seven fixtures. Adds route/partition contract tests; SCHEMA.md §7b documents
the ready_for_reviewers result and its fast_path / max_bha_agents /
cache_status_message fields.

Zero orchestrator changes (start.md untouched). Full code-review suite 1305
passed / 3 skipped; ruff + pyright clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(code-review): changelog + README for run-prefix route/partition folding (PLN-1229 Phase 2)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(code-review): resumable route-failure error + unconditional Gate B route (PLN-1229 Phase 2)

Addresses review of PR #174:
- Route-failure error was non-resumable: it set failed_stage="route" (not a
  real plan stage) and resume_stage=stage_17_partition (which would skip route
  on retry). Anchor both on stage_19_cache_check so a per-stage fallback re-runs
  cache-check → route → partition, restoring the resume_stage == failed_stage ==
  real-stage-id invariant every other error path holds. Adds a test that stubs
  route to fail and asserts the contract.
- run-prefix gated the Gate B route call on `status != "skipped"`, diverging
  from start.md's Walker Contract (route reads the diff, not the cache result,
  so it fires unconditionally after cache-check) and from the parity oracle's
  A-side, which runs route unconditionally. Removed the guard so both sides —
  and the walker contract — agree; the A/B byte-equality oracle stays green.
- SCHEMA.md §7b now states exactly which result fields (fast_path /
  max_bha_agents / cache_status_message) are present per next_action, and that
  they are omitted (not null) elsewhere, so consumers use .get().

Full code-review suite 1306 passed / 3 skipped; ruff + pyright clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: wongk

CHANGELOG.md

@@ -4,6 +4,12 @@ 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.3.0
+
+#### Changed
+- `run-prefix` now runs the **entire** deterministic review prefix in one process, folding in the Gate B model-routing (`route`) and file partitioning that previously sat outside the runner. After the cache check it computes the routing decision itself (writing `spawn.json.route`), then — unless the fast path is selected — partitions the changed files (applying the reviewer-budget caps and, when a cache directory is active, restricting partitions to the files that missed the cache). In fast-path mode partitioning is skipped entirely and the cached Bug-Hunter-A replay artifact is removed. The terminal result is now `ready_for_reviewers`, which carries the `fast_path` decision, the Bug-Hunter-A agent cap, and the cache status message so the orchestrator can print the routing and cache notices without re-reading `spawn.json`. Routing runs unconditionally after the cache check (matching the walker contract, since it reads the diff rather than the cache result), and a routing failure is surfaced as an `error` result anchored on the cache-check stage so a per-stage fallback re-runs routing rather than skipping it. Documented in `SCHEMA.md`, which now also specifies exactly which result fields are present per outcome.
+- The subprocess A/B parity oracle now walks the whole prefix through partitioning and spawn-spec derivation on both sides, so its byte-identical-artifact guarantee covers the fast-path and partitioned branches (including `partitions.json` and `spawn.json`) across all seven fixtures.
+
 ### code-review v3.2.0
 
 #### Added

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

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

plugins/code-review/README.md

@@ -231,7 +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) |
+| `run-prefix` | Runs the whole deterministic prefix (setup through Gate B route + partition + spawn-spec derivation) in one process, resolving tokens and honoring gates/`on_failure`; pauses at the hygiene-only exit or a singleton needing an agent, otherwise returns `ready_for_reviewers` with the fast-path/cache-status decision — emitting a status JSON and resuming from a given stage (PLN-1229) |
 
 ## GitHub CI Mode
 

plugins/code-review/SCHEMA.md

@@ -495,51 +495,63 @@ 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).
+`run-prefix` runs the **entire** deterministic prefix (stages 01 through Gate B
+`route` + `partition` + `derive-spawn-spec`) 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.                                 |
+| 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.                                 |
+| `fast_path`            | bool            | Gate B routing decision. Present **only** on `ready_for_reviewers`.      |
+| `max_bha_agents`       | int \| null     | Gate B Bug-Hunter-A agent cap. Present **only** on `ready_for_reviewers`.|
+| `cache_status_message` | string \| null  | `cache_result.json.status_message` to print. Present on `ready_for_reviewers` and `hygiene_exit`. |
+
+`next_action`, `resume_stage`, `singleton`, `failed_stage`, `ran_stages`, and
+`message` are present on every result. The three Gate-B fields above are
+**omitted entirely** (not set to null) on the results that don't carry them —
+`fast_path` / `max_bha_agents` appear only on `ready_for_reviewers`, and
+`cache_status_message` only on `ready_for_reviewers` / `hygiene_exit`. Read them
+with `.get()`, not direct indexing.
 
 **`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.
+| 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) | Print `cache_status_message`, present hygiene findings, stop (no verdict).    |
+| `ready_for_reviewers` | the whole deterministic prefix is done | Print `cache_status_message` + the `fast_path` notice; spawn the reviewer fleet (`stage_20`). |
+| `error`               | a stage aborted / a gate failed       | Fall back to the per-stage walk from `failed_stage`; partials are preserved.  |
+
+On `ready_for_reviewers` the runner has already run Gate B `route` (writing
+`spawn.json.route`) and — unless `fast_path` — `stage_17_partition` (with the
+`--loc-budget 500 --max-files 25 --max-bha-agents <N>` augmentation, and the
+`uncached_diff_data.json` swap when a cache dir is active). In `fast_path` mode
+partition is skipped (no `partitions.json` / `patches_p<N>.txt`) and any cached
+BHA replay artifact is deleted. The `fast_path` / `max_bha_agents` /
+`cache_status_message` fields let the orchestrator print the routing + cache
+notices without re-reading `spawn.json`.
 
 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
+`next_action` field is the contract. 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`).
+`collect-findings`). A `route` failure is surfaced as `error` with
+`failed_stage: "route"`.
 
 ---