Make the round cap productive: scope-down + follow-up, not a dead-end

[yihanzhu]

Closes #50

What

Make the ~3-round cap productive: instead of dead-ending at round-3 with needs-human, Faber first asks "can this scope down to the part the reviewer is satisfied with, with the contested remainder split into a follow-up issue?" If yes (the usual case): direct one scoped-down final change → clean review → merge the converged core, and open + log a follow-up issue for the contested remainder. needs-human is now reserved for when even the scoped-down core is contested, a genuine coder↔reviewer standoff, or a safety-rail / north-star decision.

Why

Today the cap is a dead-end (coder hits round-3, applies needs-human, stops). In practice (e.g. PRs #45/#47/#48 this cycle) the right resolution is to land the converged core and defer the contested part to a follow-up — escalating to the human only on a genuine standoff / safety / north-star call. This encodes that so the cap ships value rather than stalling.

Changes (per file)

• manager/CLAUDE.md — step 4 rewritten to the scope-down + follow-up branch (yes → scoped-down change → clean review → merge core + open/log follow-up; no → needs-human, reserved). needs-human re-entry note updated to reflect that most round-cap cases resolve in-loop.
• routines/coder-revision.md — rounds-cap step keeps "no further unsolicited changes at round-3," with an explicit exception: Faber may direct one scoped-down final change (agreed core); the remainder goes to a follow-up, not more rounds.
• templates/faber-command.md — mirrors the scope-down + follow-up behavior at the cap.
• README.md — loop diagram + "One rounds counter" design note now describe scope-down + follow-up; needs-human reserved for standoff/safety/north-star.
• reviewer/codex-review.md — in-session loop diagram reflects the productive cap resolution.

Preserved

The ~3-round cap count itself, needs-human for real escalations, the consensus front gate, auto-merge safety, manager-reviewer, and all other rails. The change is how the cap resolves, not the count — no gate logic touched.

Verification

• Structure check (CI's required-files gate) passes locally; docs/prompt-only, no scripts touched so shellcheck is unaffected.
• Re-read across all five files: cap → scope-down + follow-up is described consistently; needs-human reserved for genuine standoffs / safety / north-star; cap count unchanged.

Self-modification call-out

Prompt-doc change — does not change live behavior until synced:

• /faber (templates/faber-command.md) needs scripts/install.sh re-run to regenerate the command.
• manager/CLAUDE.md takes effect on Faber's next read.

🤖 Generated with Claude Code

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 70633b5
Reviewed-base: e5a9b05

Posted verbatim by codex-review.sh (codex exec review --base origin/main in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The new scoped-down round-cap path can instruct the coder to stop before pushing or recording the final change, which can stall the intended review-and-merge flow.

Review comment:

• [P2] Push the scoped-down fix before stopping — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.3xe8TcoJ19/routines/coder-revision.md:18-18
  When Faber invokes the new scoped-down exception at round-3, this instruction tells the coder to make the change and stop inside step 2, before the later push/label/comment steps. In this path the scoped-down core may remain only in the coder's local worktree and Faber cannot re-run Codex or merge it, so the exception should explicitly continue through pushing and reporting.

[yihanzhu]

Round-1: addressed Codex [P2].

The scoped-down round-cap exception in routines/coder-revision.md (step 2) said "make exactly that change and stop" — which stopped before the push/label/comment steps, leaving the scoped core only in the coder's local worktree. The exception now explicitly continues through the normal push/label/comment steps (4–7), so when Faber directs a scoped-down final change at the cap, the coder makes it, pushes to the branch, and posts the summary — the scoped core actually lands for re-review and merge.

Cap behavior otherwise intact: no unsolicited changes at round-3, scope-down only when Faber directs it, needs-human for genuine standoffs. Docs/prompt-only — structure check passes locally.

Commit: 2d903dc

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 2d903dc
Reviewed-base: e5a9b05

Posted verbatim by codex-review.sh (codex exec review --base origin/main in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The new scoped-down round-cap path can drive the coder into adding a non-existent round-4 label, so the workflow it introduces may fail at the cap.

Review comment:

• [P2] Keep capped scoped-down rounds on defined labels — /var/folders/rm/bkx4f4b91vqfn79vk02pcd140000gn/T/tmp.MZgl1Mo1cw/routines/coder-revision.md:18-20
  When Faber uses the new scoped-down exception at round-3, this instruction sends the coder through steps 4–7, including step 5's round-(N+1) bump. Since the setup script and docs only create round-0..3, that path will try to add an undefined round-4 label or leave PR state inconsistent, breaking the new cap workflow. Clarify that the final scoped-down change should not bump past the cap, or provision/document the extra label.

[yihanzhu]

Round-2: addressed Codex [P2].

The scoped-down round-cap exception in routines/coder-revision.md (step 2) sent the coder through steps 4–7, including step 5's round-N → round-(N+1) bump. At round-3 that would try to add a nonexistent round-4 label (only round-0..3 exist).

The exception is now explicit that the scoped-down change is terminal: make the change, push it (step 4) so the scoped core lands for re-review/merge, then SKIP step 5's bump — the PR stays at round-3, no round-4 — then post the summary (step 6) and stop (step 7).

The round-1 push+report fix is preserved (the scoped core still reaches the branch). Normal (non-cap) rounds still bump round-N → round-(N+1) via step 5, unchanged. Cap behavior, scope-down + follow-up, the cap count, and needs-human for genuine standoffs all intact. Docs/prompt-only — structure check passes locally.

Commit: 3a2a038

[yihanzhu]

Codex reviewer (cross-vendor, read-only)

Reviewed-head: 3a2a038
Reviewed-base: e5a9b05

Posted verbatim by codex-review.sh (codex exec review --base origin/main in an isolated temp worktree, sandbox forced read-only). Comments only — Codex never pushes, approves, or merges.

The changes are documentation/workflow updates, and I did not identify a discrete, actionable defect introduced by the patch.