diff --git a/BUILDER.md b/BUILDER.md index d8376ea..d1b4df3 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -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, diff --git a/REVIEWER.md b/REVIEWER.md index 7d8e74e..754691d 100644 --- a/REVIEWER.md +++ b/REVIEWER.md @@ -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. diff --git a/changelog.d/258.md b/changelog.d/258.md new file mode 100644 index 0000000..b03d4a0 --- /dev/null +++ b/changelog.d/258.md @@ -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).