docs(builder): a fix round may ride a draft

BUILDER.md's review round assumed ready-throughout, so a builder or
reviewer meeting a mid-round draft found behaviour the doctrine never
described. Three points, doctrine not mechanism: the draft phase stays
the builder's through a fix round, ready-for-review is the builder's own
act and no engine's, and where the draft suppressed CI green is proven
at the flip with the request following it — step 1's rule at a stated
moment, not a second rule.

REVIEWER.md gains the reading that keeps a reviewer from misfiling it:
a draft carrying state:addressing is a fix round in progress.

Refs #258
This commit is contained in:
cndgrr 2026-08-03 21:49:11 +00:00
parent 3c96406081
commit 6634a517bc
3 changed files with 46 additions and 0 deletions

View file

@ -297,6 +297,40 @@ CONTRIBUTING; the shared flow lives here and is not restated there.)
is one kind of human-owned decision; use the ruling ask below
([#50 D11](https://github.com/heavy-duty/ceremony/issues/50)).
**A fix round may ride a draft.** An engine may convert a PR back to draft
when a round closes, and crew#139's does: the 15-minute cadence makes a
builder's fix-round pushes *saves* rather than proposals, and 41 of 106
commits across crew's last 25 PRs — 39% — were fired at CI as if they were
proposals. Ceremony implements no such conversion and this passage specifies
none; it is written down because a builder or a reviewer who meets a mid-round
draft has to find a state the doctrine describes. What it means is what a
draft already meant during the build, extended and not changed: the draft
phase is yours, the panel cannot see it, and the checkpoint discipline
(Building, above) runs through the round unaltered. Whose ball it is does not
change either — the round outranks the draft flag, which is what
[LABELS.md](LABELS.md)'s `state:building` row already says in the machine's
voice: a draft carrying a standing non-approving verdict is a fix round and
reads `state:addressing` (#205).
**Ready-for-review is the act that ends the round, and it is the builder's
alone.** No engine marks a PR ready. The flip asserts that the round was
answered whole, and that assertion is the one judgement about a round its
author cannot delegate to a machine: an engine may draft a PR, and crew#139's
does, but only the builder undrafts it.
**Where a draft suppressed the checks, green is proven at the flip and the
request still follows it.** Step 1's precondition is the whole rule and this
adds no second one — it says only *when* the head answers: marking ready is
what runs the checks the draft held back, so the order is flip, let the head
answer, then request, and the argued exception stays the only way past a red
one. Waiting there is compliance, not a stall, and the machine reads it that
way too: `blocker:unrequested` does not fire while a head's checks are pending
or red, because the one blocker that demands an act has to know when the act
is permitted (#236 — crew#318 carried it at ~12:44Z on 2026-08-03 while its
head's run was still in progress, which is the label flagging a builder for
obeying this section). A head with no checks configured has nothing to wait
for and is requested straight away, the same reading that sweep gives it.
## The ruling ask
Set `needs-ruling` whenever a decision belongs to a human: org policy,

View file

@ -141,6 +141,11 @@ saw Y" outranks one that says "this looks like it might".
- The builder answers rounds whole and re-requests you; until re-requested,
the ball is not yours (`state:addressing` is the builder working — pile-on
reviews mid-address just churn the target).
- A **draft carrying `state:addressing` is a fix round in progress**, not
abandonment: an engine may convert a PR back to draft at round close so the
builder's checkpoint pushes stop firing CI, and the flip back to ready is
the builder's own act announcing the round is answered
([BUILDER.md](BUILDER.md#the-review-round)).
- Convergence = every panel verdict approves the current head, no
`blocker:*` standing. Then the builder hands off (`state:needs-human`) and
the panel's job is done.

7
changelog.d/258.md Normal file
View file

@ -0,0 +1,7 @@
### Added
- BUILDER.md now describes a fix round that rides a draft: the draft phase
stays the builder's, ready-for-review is the builder's own act, and where a
draft suppressed the checks green is proven at the flip (#258).
- REVIEWER.md now reads a draft carrying `state:addressing` as a fix round in
progress rather than abandonment (#258).