docs(code-review): reframe pre-v2.1.182 fleet fallback as operator concern

Address deep-review findings on the parallel-fleet contract:

- The "Legacy fallback (Claude Code < v2.1.182)" branch was written as if the
  orchestrating agent picks between parallel and synchronous dispatch at runtime,
  but the agent cannot introspect its own CLI version from inside the prompt, so
  the fallback was an unreachable branch. Reframe it in spawn-reviewers/SKILL.md
  and start.md as an operator/environment concern (claude-code-action@v1 ships
  >= v2.1.182, so CI is always parallel; an operator on an older CLI must edit
  the skill), not a path the live agent resolves.
- Add the matching legacy-fallback note to verify-findings/SKILL.md so the
  reviewer and verifier fleets document the same degradation on older CLIs.
- Scope the CHANGELOG entry: only stage_20 removed a synchronous-GitHub branch;
  stage_23 was already background-dispatched in both modes and is now only
  documented explicitly. Drop the inflated "halving" estimate.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: wongk

CHANGELOG.md

@@ -7,7 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### code-review v3.5.0
 
 #### Changed
-- GitHub-mode reviews now dispatch the reviewer fleet (`stage_20`) and verifier fleet (`stage_23`) as parallel background tasks collected with a blocking `TaskOutput`, the same as local mode, instead of running each agent synchronously one at a time. Headless `claude -p` waits for background subagents to finish before exiting (Claude Code v2.1.182+), so a code-review CI run's fleet stages now take the wall-clock of the slowest agent rather than the sum of all agents — roughly halving shallow-tier CI review time. A synchronous one-at-a-time fallback stays documented for Claude Code older than v2.1.182, the per-agent background wait can be raised past its 10-minute default via `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`, and runs that background reviewers must allow the `TaskOutput` tool. Updates the `spawn-reviewers` and `verify-findings` skills and the `start.md` walker contract.
+- GitHub-mode reviews now dispatch the reviewer fleet (`stage_20`) as parallel background tasks collected with a blocking `TaskOutput`, the same as local mode, instead of running each reviewer synchronously one at a time. The verifier fleet (`stage_23`) already dispatched in the background in both modes; its contract is now stated explicitly as parallel with a matching fallback note so the two fleets are documented consistently. Headless `claude -p` waits for background subagents to finish before exiting (Claude Code v2.1.182+), so a code-review CI run's reviewer stage now takes the wall-clock of the slowest reviewer rather than the sum of all reviewers, cutting shallow-tier CI review time. The synchronous one-at-a-time fallback for Claude Code older than v2.1.182 is documented as an operator/environment concern (the orchestrating agent cannot detect its own CLI version at runtime, so it always takes the parallel path); the per-agent background wait can be raised past its 10-minute default via `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS`, and runs that background reviewers must allow the `TaskOutput` tool. Updates the `spawn-reviewers` and `verify-findings` skills and the `start.md` walker contract.
 
 ### code-review v3.4.1
 

plugins/code-review/commands/start.md

@@ -409,7 +409,7 @@ When the walker reaches `stage_20_spawn_reviewers`, invoke the `code-review:spaw
 
 The skill is invoked for both `MODE=local` and `MODE=github` with the **same** parallel Task scheduling: spawn every standard-flow reviewer as a background task and collect them all with blocking `TaskOutput`, so `stage_20` wall-clock is the slowest reviewer rather than the sum. The verifier fleet (`stage_23`) and the PLN-725 single-agent dispatch (`stage_11` / `stage_15`) are **not** in this skill; they are owned by the `code-review:verify-findings` and `code-review:singleton-dispatch` skills respectively.
 
-GitHub headless mode carries one walker-level guard: the turn stays alive only while a pending synchronous tool call is outstanding, so the blocking `TaskOutput` collection is what keeps `claude -p` running until reviewers finish (headless awaits background subagents on Claude Code v2.1.182+). The walker must not proceed to `stage_21_collect_findings`, emit a final summary, mark the review complete, or end the assistant turn while any reviewer remains outstanding. Watcher files, sleep loops, polling loops, and "I'll continue when notified" turns are forbidden — they end the turn with no pending call and the process exits before the tail stages run. On Claude Code < v2.1.182, background subagents are not awaited; use the skill's legacy synchronous fallback there.
+GitHub headless mode carries one walker-level guard: the turn stays alive only while a pending synchronous tool call is outstanding, so the blocking `TaskOutput` collection is what keeps `claude -p` running until reviewers finish (headless awaits background subagents on Claude Code v2.1.182+). The walker must not proceed to `stage_21_collect_findings`, emit a final summary, mark the review complete, or end the assistant turn while any reviewer remains outstanding. Watcher files, sleep loops, polling loops, and "I'll continue when notified" turns are forbidden — they end the turn with no pending call and the process exits before the tail stages run. On Claude Code < v2.1.182 background subagents are not awaited — but the agent cannot self-detect its CLI version, so this is an operator/environment concern, not a runtime branch: `claude-code-action@v1` ships ≥ v2.1.182 (always parallel), and an operator forced onto an older CLI must switch the skill to its legacy synchronous fallback.
 
 Decomposition rationale: ~470 lines of reviewer-fleet dispatch content was extracted as a skill so the orchestration spine stays lean and the content no longer loads into orchestrator context during the deterministic prefix (stages 0-19) or on hygiene-only / full-cache-hit runs that never reach `stage_20`.
 

plugins/code-review/skills/spawn-reviewers/SKILL.md

@@ -329,7 +329,7 @@ When GRAPH_PROJECT is empty, grep imports instead.
 
 > **Headless requirement (GitHub mode).** GitHub reviews run under headless `claude -p`, which **waits for background subagents to complete before exiting** (their output is part of the final result) as of **Claude Code v2.1.182+** — the version `anthropics/claude-code-action@v1` ships. A blocking `TaskOutput` is a pending synchronous tool call, so the assistant turn never "ends" with an outstanding reviewer and the run does not die. The per-agent wait is capped at **10 minutes** by default; when reviewers can run long, raise it with the `CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS` env var (or set `0` for no cap) so a slow reviewer is not orphaned, and add `TaskOutput` to the run's `--allowedTools`.
 >
-> **Legacy fallback (Claude Code < v2.1.182 only).** On older CLIs headless does not await background subagents, so a backgrounded reviewer dies when the turn ends. There — and only there — dispatch standard-flow reviewers synchronously one at a time (`run_in_background: false`, wait for each `DONE findings=N file=...` before spawning the next) so no reviewer is ever left outstanding. This is the pre-v2.1.182 behavior; it is correct but serial (wall-clock = sum of reviewers).
+> **Legacy fallback (Claude Code < v2.1.182 only) — an operator concern, NOT a runtime branch the agent picks.** The orchestrating agent **cannot introspect its own CLI version from inside the prompt**, so it has no decision procedure to choose between the two paths at runtime — it always follows the parallel primary above. This fallback is therefore an environment/operator decision, not a branch the live agent resolves. `anthropics/claude-code-action@v1` ships ≥ v2.1.182, so standard GitHub CI is always on the parallel path and no action is needed. An operator who must run an older CLI — where headless does not await background subagents, so a backgrounded reviewer dies when the turn ends — must edit this skill to dispatch standard-flow reviewers synchronously one at a time (`run_in_background: false`, wait for each `DONE findings=N file=...` before spawning the next) so no reviewer is ever left outstanding. That pre-v2.1.182 path is correct but serial (wall-clock = sum of reviewers).
 
 **Agents write findings to files — NOT to their response.** Each agent writes its findings JSON to `<CR_DIR>/agent_{AGENT_ID}.json` and returns only a one-line status (`DONE findings=N file=...`). `TaskOutput` responses are ~50 tokens each instead of 2-5K tokens, so you can collect ALL agents at once without context overflow.
 

plugins/code-review/skills/verify-findings/SKILL.md

@@ -32,6 +32,8 @@ This stage runs when the walker reaches `stage_23`. It implements PLN-722's find
 
 **Dispatch the whole verifier fleet as parallel background tasks in both `MODE=local` and `MODE=github`** — spawn all `to_verify[]` entries with `run_in_background: true` (in one message or a few), then collect them with blocking `TaskOutput` (below). Do NOT dispatch verifiers one-at-a-time; headless `claude -p` awaits background subagents on Claude Code v2.1.182+, so the fleet runs concurrently in CI too (`stage_23` wall-clock is the slowest verifier, not the sum).
 
+> **Legacy fallback (Claude Code < v2.1.182 only) — an operator concern, NOT a runtime branch the agent picks.** Same as the reviewer fleet (see `spawn-reviewers/SKILL.md`): the orchestrating agent cannot introspect its own CLI version, so it always takes the parallel path above, and `anthropics/claude-code-action@v1` ships ≥ v2.1.182. An operator forced onto an older CLI — where headless does not await background subagents, so a backgrounded verifier dies when the turn ends — must edit this skill to dispatch verifiers synchronously one at a time so no verifier is left outstanding. This mirrors the reviewer fleet so both stages degrade the same way on older CLIs.
+
 For each entry in `verify_manifest.json.to_verify[]`:
 
 1. Spawn one background `Task` with `subagent_type: "code-review:code-review-worker"`. The agent's tool allowlist (`Read`, `Write`, `Grep`, `Glob`) is identical to the Reviewer Fleet's — no permission changes needed.