fix(code-review): attribute run-prefix stage-failure diagnostics per stage

Addresses review of PR #173 (all MEDIUM, non-blocking):
- Capture each in-process stage's stderr and fold its tail into the returned
  status message, so a failing stage's own diagnostic is attributed to that
  stage now that one process spans many stages (was: bare process stderr with
  no stage attribution). Written back to the real stderr so live visibility is
  unchanged.
- Thread that diagnostic into _emit_prefix_stage_failure_finding: the
  continue_with_coverage_gap agent-failure finding now carries the actual
  rc/exception/stderr in its explanation instead of a generic string.
- Log the full traceback on an unexpected stage crash (the broad except no
  longer discards it), so a Phase-1 crash is diagnosable without reproduction.
- SCHEMA.md §7b: document that ready_for_route with resume_stage=null means the
  walk completed with no partition stage (skip Gate B), distinct from the
  normal partition boundary.

The docstring subparser-count finding was already correct (46). Adds a
regression test asserting the stderr diagnostic reaches the finding explanation.
Full code-review suite 1300 passed / 3 skipped; ruff + pyright clean.

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

Author: wongk

CHANGELOG.md

@@ -9,6 +9,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.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
 

plugins/code-review/SCHEMA.md

@@ -525,6 +525,13 @@ on disk (a prior stage counts as done iff its literal `expected_outputs` exist).
 | `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`

plugins/code-review/tools/python/code_review_helpers.py

@@ -26,6 +26,7 @@
 import stat
 import subprocess
 import sys
+import traceback
 import uuid
 from collections.abc import Generator
 from dataclasses import dataclass, field
@@ -10566,14 +10567,27 @@ def _rp_dispatch(func: Any, ns: argparse.Namespace, stdout_path: Path | None) ->
     return int(rc or 0)
 
 
-def _emit_prefix_stage_failure_finding(cr_dir: Path, stage_id: str) -> None:
+def _emit_prefix_stage_failure_finding(
+    cr_dir: Path, stage_id: str, diagnostic: str | None = None,
+) -> None:
     """Write ``agent_<stage>-failed.json`` with a canonical agent-failure finding.
 
     Mirrors start.md Walker Contract step 5 (``continue_with_coverage_gap``): a
     prefix stage that failed to run must surface as an operator-visible,
     collectable finding — ``collect-findings`` globs ``agent_*.json`` — rather
-    than vanish silently. Fail-open on write error (telemetry is observational).
-    """
+    than vanish silently. ``diagnostic`` is the caller's captured failure detail
+    (rc / exception / the stage's own stderr tail); it is folded into the
+    finding's explanation so the gap is debuggable without reproducing the
+    failure. Fail-open on write error (telemetry is observational).
+    """
+    explanation = (
+        f"The deterministic prefix stage {stage_id!r} exited non-zero or "
+        "produced no output. Its on_failure policy is "
+        "continue_with_coverage_gap, so the pipeline proceeds but the gap is "
+        "recorded here for auditability."
+    )
+    if diagnostic:
+        explanation += f" Diagnostic: {diagnostic}"
     finding = {
         "reviewer": "foundation",
         "source": "foundation",
@@ -10584,12 +10598,7 @@ def _emit_prefix_stage_failure_finding(cr_dir: Path, stage_id: str) -> None:
         "file": None,
         "line": None,
         "issue": f"Prefix stage {stage_id} failed; continuing with coverage gap.",
-        "explanation": (
-            f"The deterministic prefix stage {stage_id!r} exited non-zero or "
-            "produced no output. Its on_failure policy is "
-            "continue_with_coverage_gap, so the pipeline proceeds but the gap is "
-            "recorded here for auditability."
-        ),
+        "explanation": explanation,
         "recommendation": (
             "Re-run the review once the underlying issue is resolved. Common "
             "causes: malformed diff input, a git error, or a taxonomy mismatch "
@@ -10650,28 +10659,45 @@ def _execute_stage_inprocess(
     on_failure = stage.get("on_failure", "abort")
     rc = 1
     message: str | None = None
+    # Capture the stage's stderr so a failing stage's own diagnostic (the
+    # cmd_* handlers report via ``print(..., file=sys.stderr)``) can be attributed
+    # to THIS stage in the batched model — one process now runs many stages, so
+    # bare process stderr no longer maps to an orchestrator turn. It is written
+    # back to the real stderr below, so live visibility is unchanged.
+    err_buf = io.StringIO()
     try:
-        resolved = _rp_resolve_args(stage.get("args", []) or [], ctx)
-        ns = parser.parse_args([stage["subcommand"], *resolved])
-        stdout_target = stage.get("stdout")
-        rc = _rp_dispatch(
-            ns.func, ns, Path(stdout_target) if stdout_target else None,
-        )
+        with contextlib.redirect_stderr(err_buf):
+            resolved = _rp_resolve_args(stage.get("args", []) or [], ctx)
+            ns = parser.parse_args([stage["subcommand"], *resolved])
+            stdout_target = stage.get("stdout")
+            rc = _rp_dispatch(
+                ns.func, ns, Path(stdout_target) if stdout_target else None,
+            )
     except SystemExit as exc:  # argparse rejected the resolved args
         message = f"argparse rejected args for {stage_id}: {exc}"
         rc = 1
     except Exception as exc:  # noqa: BLE001 — a crash is a stage failure; on_failure decides
         message = f"{type(exc).__name__} in {stage_id}: {exc}"
         rc = 1
+        # Preserve the full traceback on the real stderr — the short ``message``
+        # alone can't be debugged without reproducing the crash.
+        traceback.print_exc()
+
+    stage_stderr = err_buf.getvalue()
+    if stage_stderr:
+        sys.stderr.write(stage_stderr)
 
     outputs_ok = message is None and _rp_outputs_present(stage)
     if rc != 0 or not outputs_ok:
         if message is None:
             message = f"stage {stage_id} failed (rc={rc}, outputs_ok={outputs_ok})"
+        stderr_tail = stage_stderr.strip().splitlines()
+        if stderr_tail:
+            message = f"{message}; stderr: {stderr_tail[-1][:300]}"
         if on_failure == "abort":
             return "failed_abort", message
         if on_failure == "continue_with_coverage_gap":
-            _emit_prefix_stage_failure_finding(ctx.cr_dir, stage_id)
+            _emit_prefix_stage_failure_finding(ctx.cr_dir, stage_id, message)
         return "failed_continue", message
 
     _rp_apply_post_stage_overrides(stage_id, ctx)

plugins/code-review/tools/python/test_code_review_helpers.py

@@ -22608,6 +22608,32 @@ def test_continue_with_coverage_gap_emits_agent_failure_finding(
         assert marker == "agent-failure"
         assert payload["findings"][0]["finding_scope"] == "system"
 
+    def test_coverage_gap_finding_threads_stage_stderr_diagnostic(
+        self, tmp_path: Path,
+    ) -> None:
+        from code_review_helpers import _execute_stage_inprocess
+
+        out = tmp_path / "o.json"
+
+        def _fail_with_stderr(_ns: argparse.Namespace) -> int:
+            print("Error: taxonomy mismatch after edit", file=sys.stderr)
+            return 1
+
+        parser = _fake_stage_parser(_fail_with_stderr)
+        status, message = _execute_stage_inprocess(
+            self._stage(out, id="stage_14_resolve_coverage",
+                        on_failure="continue_with_coverage_gap"),
+            _rp_ctx(tmp_path), parser, set(),
+        )
+        assert status == "failed_continue"
+        # The stage's own stderr is attributed to the stage in the message ...
+        assert "taxonomy mismatch after edit" in (message or "")
+        # ... and folded into the emitted finding's explanation (not discarded).
+        payload = json.loads(
+            (tmp_path / "agent_stage_14_resolve_coverage-failed.json").read_text(),
+        )
+        assert "taxonomy mismatch after edit" in payload["findings"][0]["explanation"]
+
     def test_skip_when_disabled(self, tmp_path: Path) -> None:
         from code_review_helpers import _execute_stage_inprocess