feat(tooling): add /review_prs command to batch-review a filtered set of PRs

[scottschreckengaust]

Summary

Add a /review_prs command under .abca/commands/ that runs the existing single-PR
review_pr workflow across a filtered set of
PRs in one invocation. It orchestrates, it does not re-implement: each PR is reviewed by
the full review_pr process, so the review bar stays single-sourced.

The per-PR fan-out is delegated to a Workflow script (deterministic multi-agent
orchestration) rather than described in prose. This keeps the orchestrating (main) context
fresh: each PR's heavy work — a large diff, three nested review_pr review agents, the full
review body — runs inside a Workflow-spawned subagent, and only a small structured result per PR
(verdict + rationale + review URL) returns to the caller. The Workflow makes that isolation a
property of the control flow, not of an executor choosing to follow prose.

Prior art / sibling: review_pr (single PR) and commit are the existing .abca/commands/
entries; both are synced to .claude/ and .cursor/ stubs by scripts/sync-abca-commands.mjs
(mise run sync:abca-commands, part of drift-prevention).

Use case

Reviewers (human or agent) routinely face a queue of PRs — e.g. everything requesting their
review. Today that means invoking /review_pr N times by hand and first hand-deriving the list
(the GitHub search bar can't express "not from a fork" or "CI all-green" for PR search).
/review_prs makes the common case one step: derive the work-list, optionally gate on CI, then
fan out one full review_pr per PR concurrently — with the diffs and nested-agent transcripts
kept out of the main context so a large queue doesn't blow the caller's window.

Scope / acceptance criteria

• New source .abca/commands/review_prs.md follows the review_pr persona + staged
  structure (Principal-Architect persona, numbered stages, human-review heuristics) and
  delegates per-PR review to review_pr.md via a relative link — it does not copy
  the review process (coherence: single source of truth for the review bar).
• review_pr.md is unchanged (it remains the single-PR authority).
• Stage 1 — work-list derivation is documented with the exact default query:
  gh pr list --search "is:open is:pr draft:false -author:@me -review:approved review-requested:@me" --json number,isCrossRepository --jq '.[] | select(.isCrossRepository == false) | .number',
  plus a note that GitHub PR search has no fork qualifier (is:fork is repo-search only
  and is silently ignored), so the fork filter is client-side on isCrossRepository.
  Stage 1 (scouting the work-list) runs inline; Stage 2 (fan-out) is the Workflow step.
• Optional CI-green gate documented: keep a PR iff gh pr checks <n> exits 0 (every
  check terminal AND passed), with the explicit warning that passing --json to
  gh pr checks nullifies the exit code. The gate is opt-in (not default) and any PR it drops
  is announced with the reason — no silent truncation.
• Empty-list handling: if no PRs match, the command says so and stops — it never invokes the
  Workflow / invents PRs.
• Stage 2 — fan-out via Workflow documented (this is the change from the original
  subagent-prose scope). The command instructs the executor to invoke the Workflow tool with
  a self-contained script that:
  - takes the resolved PR list as args;
  - pre-stages shared git state once, then processes PRs concurrently (a parallel() /
  pipeline() fan-out, one agent per PR) with the cap the tool enforces;
  - has each agent run the full review_pr workflow for its PR and submit the decision
  (Approve / Comment / Request-changes) with inline suggestions;
  - returns a small structured result per PR (number, verdict, one-line rationale, review
  URL) via a schema — so diffs, nested-agent output, and review bodies stay in the
  subagent contexts and only the compact result reaches the caller (context-freshness).
  Each agent is given: PR number, worktree path, diff path, head SHA (review commit_id), and
  base branch (flag stacked PRs whose base ≠ main).
• Context-freshness rationale is stated in the command: why the fan-out is a Workflow
  (isolation is a property of the control flow, not of an executor choosing to obey prose);
  note the caveat that per-PR summaries still accrete linearly, so freshness ≠ constant.
• Governance carried forward from review_pr: the gate is an approved backing issue; a
  pr/* branch name is a de-facto-waived nit, not a blocker.
• Submission mechanism documented: GitHub MCP pull_request_review_write lacks token scope
  in this repo, so reviews are submitted via
  gh api --method POST .../pulls/<n>/reviews --input <file>.json (inline comments must anchor
  to RIGHT-side diff lines or the call 422s → move to the body).
• Stage 3 cleanup: worktrees/temp branches removed; a summary table returned
  (PR · verdict · one-line rationale · review URL), assembled from the Workflow's results.
• mise run sync:abca-commands regenerates .claude/commands/review_prs.md +
  .cursor/commands/review_prs.md; all three files committed together and
  mise run build (incl. drift-prevention) is green (no mutation).
• CONTRIBUTING.md references /review_prs alongside /review_pr, and the Starlight mirror
  (docs/src/content/docs/developer-guide/Contributing.md) is regenerated via
  mise //docs:sync so CI's "Fail build on mutation" passes.

Non-goals

• No change to the review_pr review process or verdict semantics.
• No new deploy-time infrastructure, IAM, or agent-runtime code (docs/command-only) — no ADR-002
  bootstrap impact.
• Not an automated/scheduled reviewer; /review_prs is invoked on demand.
• No change to the Workflow tool itself — the command uses it; it does not modify orchestration
  infrastructure.

Notes

• Scope revision (re-approval required): the original approved scope specified the Stage-2
  fan-out as prose subagent dispatch. This revises it to a Workflow-based fan-out so
  context-freshness is enforced by the control flow rather than left to the executor. Per ADR-003
  the issue is scope-frozen once approved, so this change requires re-approval. PR feat(tooling): add /review_prs command to batch-review a filtered set of PRs (#620) #621 (which
  implemented the prose version, green) will be updated in place to the Workflow version.
• Roadmap alignment (ADR-003): developer tooling / DX; not a current roadmap line-item, so it
  requires explicit permitted-user approved per ADR-003's "issues that do not align require
  explicit approval."
• Effort: small (one command file describing the Workflow invocation + generated stubs + one
  CONTRIBUTING reference + mirror regen).

[scottschreckengaust]

Starting implementation. Branch feat/620-review-prs-command. Per the acceptance criteria: new .abca/commands/review_prs.md delegating to review_pr.md (unchanged), regenerated .claude/.cursor stubs via sync:abca-commands, a CONTRIBUTING.md reference + Starlight mirror regen, and a green mise run build (incl. drift-prevention).

[scottschreckengaust]

Scope revision — re-approval requested (ADR-003 scope-freeze).

Per the maintainer's direction, revising the Stage 2 fan-out from prose subagent dispatch to a Workflow-based fan-out. Rationale: context-freshness for the orchestrating (main) context should be a property of the control flow — each PR's diff, nested review_pr review agents, and review body run in a Workflow-spawned subagent; only a compact per-PR result (verdict + rationale + review URL, via a schema) returns to the caller — rather than relying on an executor choosing to follow prose.

What changed in the body: the Stage-2 acceptance criterion now specifies the Workflow invocation (list as args, concurrent one-agent-per-PR fan-out, structured-result return), plus a new criterion requiring the command to state the freshness rationale (and the caveat that per-PR summaries still accrete linearly). Non-goals gain "no change to the Workflow tool itself." Everything else (Stage 1 query, CI gate, submission mechanism, sync/mirror, CONTRIBUTING) is unchanged.

Since the issue was already approved, this is a deliverable change and I've removed the approved label. Holding implementation until a permitted user re-applies it. PR #621 (prose version, currently green) will be updated in place to the Workflow version once re-approved.

[scottschreckengaust]

Re-approval confirmed. Resuming implementation on feat/620-review-prs-command — updating PR #621 in place to the Workflow-based Stage-2 fan-out.