From 6634a517bc744b1b9fccbaaba1b169ba9ab1073c Mon Sep 17 00:00:00 2001 From: cndgrr <59120057+cndgrr@users.noreply.github.com> Date: Mon, 3 Aug 2026 21:49:11 +0000 Subject: [PATCH 1/5] docs(builder): a fix round may ride a draft MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- BUILDER.md | 34 ++++++++++++++++++++++++++++++++++ REVIEWER.md | 5 +++++ changelog.d/258.md | 7 +++++++ 3 files changed, 46 insertions(+) create mode 100644 changelog.d/258.md 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). From dbbdbdb6ddae40573e665e199d168416f2175aec Mon Sep 17 00:00:00 2001 From: cndgrr <59120057+cndgrr@users.noreply.github.com> Date: Mon, 3 Aug 2026 21:51:25 +0000 Subject: [PATCH 2/5] docs(builder): cite what this file carries, not what crew's engine does MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first paragraph referred to a 15-minute cadence and a checkpoint discipline, neither of which BUILDER.md states — the cadence is crew's engine rule and the pointer sent a reader to a section that says nothing about it. Attribute the measurement to crew#139 and point at what Building actually says. The LABELS.md sentence stops restating the state:building row's condition and points at it instead: one rule in two voices, per #258's test plan. Refs #258 --- BUILDER.md | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/BUILDER.md b/BUILDER.md index d1b4df3..59ca1a7 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -298,19 +298,18 @@ CONTRIBUTING; the shared flow lives here and is not restated there.) ([#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). +when a round closes, and crew#139's does — an engine whose own rules make a +builder's mid-round pushes *saves* rather than proposals fires CI at every one +of them otherwise, 41 of 106 commits across crew's last 25 PRs by that +issue's measurement. 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 while you were building, extended and not changed: +the draft phase is yours and the panel cannot see it (Building, above). Whose +ball it is does not change either — the round outranks the draft, so you still +owe it whole, the fixes and the reply and the flip. The label axis says the +same thing in the machine's voice rather than in this one, and +[LABELS.md](LABELS.md)'s `state:building` row is where to read it (#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 From 7948b99acfee28238eaf2ea1b895101b7ed2c7a2 Mon Sep 17 00:00:00 2001 From: cndgrr <59120057+cndgrr@users.noreply.github.com> Date: Mon, 3 Aug 2026 21:51:48 +0000 Subject: [PATCH 3/5] docs(builder): unknot the opening sentence Refs #258 --- BUILDER.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/BUILDER.md b/BUILDER.md index 59ca1a7..639cb48 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -298,10 +298,9 @@ CONTRIBUTING; the shared flow lives here and is not restated there.) ([#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 — an engine whose own rules make a -builder's mid-round pushes *saves* rather than proposals fires CI at every one -of them otherwise, 41 of 106 commits across crew's last 25 PRs by that -issue's measurement. Ceremony implements no such conversion and this passage +when a round closes, and crew#139's does: where an engine's own rules make a +builder's mid-round pushes *saves* rather than proposals, every save fires CI +— 41 of 106 commits across crew's last 25 PRs, by that issue's measurement. 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 while you were building, extended and not changed: From 3367cae4d4745e99dde7e5989ebf3b79fce5c294 Mon Sep 17 00:00:00 2001 From: cndgrr <59120057+cndgrr@users.noreply.github.com> Date: Mon, 3 Aug 2026 21:52:44 +0000 Subject: [PATCH 4/5] =?UTF-8?q?docs(reviewer):=20one=20vocabulary=20across?= =?UTF-8?q?=20the=20two=20files=20=E2=80=94=20mid-round=20saves?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs #258 --- REVIEWER.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/REVIEWER.md b/REVIEWER.md index 754691d..17e8b77 100644 --- a/REVIEWER.md +++ b/REVIEWER.md @@ -143,8 +143,8 @@ saw Y" outranks one that says "this looks like it might". 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's mid-round saves 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 From 349fb4d964c732a764b1707ccc392ddf51d2397f Mon Sep 17 00:00:00 2001 From: cndgrr <59120057+cndgrr@users.noreply.github.com> Date: Mon, 3 Aug 2026 22:27:42 +0000 Subject: [PATCH 5/5] docs(builder): crew#139 is an open proposal, and the CI cost is what it would end MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both occurrences said crew's engine already converts a PR back to draft at round close; crew#139 is OPEN, blocked and unassigned, so the passage was describing an unshipped mechanism as live (codex, kimi). The same sentence also read as if the conversion caused the CI spend — it is the status quo the conversion would end, so the counterfactual is now explicit. Rewrapped the paragraph at 80 columns; 7948b99 had left one line at 133. --- BUILDER.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/BUILDER.md b/BUILDER.md index 639cb48..d1ed4b4 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -298,23 +298,27 @@ CONTRIBUTING; the shared flow lives here and is not restated there.) ([#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: where an engine's own rules make a -builder's mid-round pushes *saves* rather than proposals, every save fires CI -— 41 of 106 commits across crew's last 25 PRs, by that issue's measurement. 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 while you were building, extended and not changed: -the draft phase is yours and the panel cannot see it (Building, above). Whose -ball it is does not change either — the round outranks the draft, so you still -owe it whole, the fixes and the reply and the flip. The label axis says the -same thing in the machine's voice rather than in this one, and -[LABELS.md](LABELS.md)'s `state:building` row is where to read it (#205). +when a round closes; crew#139 proposes exactly that, and is still an open +proposal. What it names is the status quo without it: where an engine's own +rules make a builder's mid-round pushes *saves* rather than proposals, every +one of those saves fires CI while the PR sits ready — 41 of 106 commits +across crew's last 25 PRs, by that issue's measurement — and converting back +to draft is what would stop them. 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 while you were +building, extended and not changed: the draft phase is yours and the panel +cannot see it (Building, above). Whose ball it is does not change either — +the round outranks the draft, so you still owe it whole, the fixes and the +reply and the flip. The label axis says the same thing in the machine's +voice rather than in this one, and [LABELS.md](LABELS.md)'s `state:building` +row is where to read it (#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. +author cannot delegate to a machine: an engine may draft a PR, which is what +crew#139 proposes engines do, 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