docs(builder): re-request by head, not by verdict — a push stales every approval

The round protocol told the author to re-request exactly the reviewers
who did not approve, but the handoff predicate counts an approval only
at the current head: any push while answering a round staled the
earlier approver's verdict, doctrine said not to re-request them, and
the PR could never converge — the silent-stall shape of #26/#39.
Step 2 now re-requests by head, not by verdict: every panelist after a
push, the non-approvers alone at an unchanged head. Shape 2's wording
is aligned so the two paragraphs agree.

Defect raised by dan-claude-bot on #190; folded in at the operator's
direction while the paragraph is open. Refs #189.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
claude-bot-andresmgsl 2026-07-27 19:53:59 +00:00
parent e9cf461ed3
commit 44ff7524af
2 changed files with 23 additions and 4 deletions

View file

@ -41,8 +41,10 @@ triage bug, and the move is to say so on the issue, not to guess.
its `Blocked:` line stops the remaining work; its `Blocked:` line stops the remaining work;
2. the deliverable is in a review round where every outstanding verdict 2. the deliverable is in a review round where every outstanding verdict
belongs to someone else — either the round is awaiting its first belongs to someone else — either the round is awaiting its first
verdicts, or it was answered whole and the non-approvers re-requested verdicts, or it was answered whole and the owed re-requests posted —
(the review round, steps 12). This is the *live* round; shape 4 is by head, not by verdict: every panelist after a push, the
non-approvers alone at an unchanged head (the review round, steps
12). This is the *live* round; shape 4 is
the *passed* one — they are sequential and do not overlap. A red the *passed* one — they are sequential and do not overlap. A red
check at the current head takes the deliverable **out of this check at the current head takes the deliverable **out of this
shape**: mid-round CI going red is exactly the state that reads as shape**: mid-round CI going red is exactly the state that reads as
@ -242,8 +244,21 @@ CONTRIBUTING; everything below is the shared flow.)
purpose. The costs behind the line are asymmetric: a false green spends purpose. The costs behind the line are asymmetric: a false green spends
a three-reviewer round; a false red spends one author session. a three-reviewer round; a false red spends one author session.
2. **Wait for every verdict, then answer the round whole** — one reply 2. **Wait for every verdict, then answer the round whole** — one reply
covering every point, then push the fixes, then re-request exactly the covering every point, then push the fixes, then re-request **by head,
reviewers who did not approve — **and the re-request carries the same not by verdict**: if answering the round pushed any commit, every
panelist's approval is now stale — an approval is of a specific tree,
and the handoff predicate counts only approvals at the current head —
so **every panelist is re-requested, the approvers included**; a
panelist left un-re-requested after a push can never approve the tree
you shipped, and the PR sits looking finished with a full set of
verdicts and nothing owed by anyone, the same silent-stall shape as
[#26](https://github.com/heavy-duty/ceremony/issues/26)/[#39](https://github.com/heavy-duty/ceremony/issues/39).
Only when the head did not move — the round was answered with argument
or evidence and nothing was pushed — do you re-request just the
non-approvers: a standing approval already covers this exact head, and
the engine absorbs a re-request at an unchanged head (the re-request
rule, [#94](https://github.com/heavy-duty/ceremony/issues/94); its
mechanism is crew's to describe). **The re-request carries the same
green-check-at-head precondition as the first request**, argued green-check-at-head precondition as the first request**, argued
exception included. This is where the measured cost landed: crew#40 exception included. This is where the measured cost landed: crew#40
burned two consecutive heads and four reviewer-rounds, every one burned two consecutive heads and four reviewer-rounds, every one

View file

@ -10,3 +10,7 @@
- `FLEET.md` writes the ci-red wake into the duty order between resume - `FLEET.md` writes the ci-red wake into the duty order between resume
and build, marked on paper until crew#64 merges, with the and build, marked on paper until crew#64 merges, with the
reconciliation stamp unchanged (#189). reconciliation stamp unchanged (#189).
- `BUILDER.md` re-requests by head, not by verdict: a push while
answering a round stales every approval, so every panelist is
re-requested; only an unchanged head re-requests the non-approvers
alone (#190).