docs(builder): restore five rules the squeeze had compressed away

This commit is contained in:
cndgrr 2026-08-04 13:31:48 +00:00
parent 4100121c7a
commit 46aeb02078

View file

@ -90,16 +90,18 @@ triage bug, and the move is to say so on the issue, not to guess.
issue says `Part of <owner>/<repo>#N`, sets `offsite`, and comments the issue says `Part of <owner>/<repo>#N`, sets `offsite`, and comments the
draft link on that issue in the same step; triage closes that issue by draft link on that issue in the same step; triage closes that issue by
hand once its criteria are met, the builder reporting there whether the PR hand once its criteria are met, the builder reporting there whether the PR
merged or closed and clearing `offsite` in the same comment (#13, #16). merged or closed and clearing `offsite` in the same comment. The
cross-repo merge never closes the authorizing issue (#13, #16).
- **`Closes #N` does not survive a post-merge criterion.** Where the issue - **`Closes #N` does not survive a post-merge criterion.** Where the issue
body says a criterion can only be checked after the merge — a workflow body says a criterion can only be checked after the merge — a workflow
trigger proved live, a released artifact, anything whose subject does not trigger proved live, a released artifact, anything whose subject does not
exist until the change is on the base branch — the same-repo PR says exist until the change is on the base branch — the same-repo PR says `Refs
`Refs #N`; the issue goes `post-merge` at the merge, the builder walks #N`; the issue goes `post-merge` at the merge, the builder walks away, and
away, triage owns verification and closure on the evidence, and corrective triage owns verification and closure on the evidence, returning the issue
work is a fresh issue any builder claims from current `main`. The issue to `ready` or minting a fresh one where corrective work is needed —
body says so — you never judge which qualify — and absent it `Closes #N` claimable by any builder from current `main`, the original having no
is the default (#151). special standing. The issue body says so — you never judge which qualify —
and absent it `Closes #N` is the default (#151).
- On a `Refs #N` PR, never put a closing keyword (`close`, `closes`, - On a `Refs #N` PR, never put a closing keyword (`close`, `closes`,
`closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`) `closed`, `fix`, `fixes`, `fixed`, `resolve`, `resolves`, `resolved`)
immediately before `#N` anywhere in the body, including the sentence immediately before `#N` anywhere in the body, including the sentence
@ -139,6 +141,9 @@ triage bug, and the move is to say so on the issue, not to guess.
## The review round ## The review round
(In a governed repo this file is `.ceremony/BUILDER.md`: repo-specific facts
such as the panel roster live in that repo's own CONTRIBUTING.)
1. Mark ready-for-review; request **the whole panel**: the PR repo's 1. Mark ready-for-review; request **the whole panel**: the PR repo's
`panel[<your-login>]=` line if it defines one, else its `panel=` line, `panel[<your-login>]=` line if it defines one, else its `panel=` line,
minus the author (#224) — never the roster of the repo the issue is in. minus the author (#224) — never the roster of the repo the issue is in.
@ -151,39 +156,41 @@ triage bug, and the move is to say so on the issue, not to guess.
request. The one exception is a failure genuinely outside the PR — a request. The one exception is a failure genuinely outside the PR — a
runner outage, a flaky dependency, a failure already on the default runner outage, a flaky dependency, a failure already on the default
branch — and only where the request says so and names the evidence ("the branch — and only where the request says so and names the evidence ("the
same job fails identically on `origin/main` at `<sha>`"). *Green* is a same job fails identically on `origin/main` at `<sha>`"); silence about a
ruled term (operator, 2026-07-27), read in two steps. **First take the red check is what is prohibited. *Green* is a ruled term (operator,
check's word at this head**: its newest entry by start time — not 2026-07-27), read in two steps. **First take the check's word at this
completion, a cancelled run outliving its replacement's start — and never head**: its newest entry by start time — not completion, a cancelled run
a `CANCELLED` entry while the same check has a non-cancelled one there. A outliving its replacement's start — and never a `CANCELLED` entry while
check whose entries at the head are all cancelled has not reported at all the same check has a non-cancelled one there. A check whose entries at
and is not green, the gate collapsing alike (#139, #276). **Then classify the head are all cancelled has not reported at all and is not green, the
that entry by `conclusion`, never `status`**, which can disagree with it gate collapsing alike (#139, #276). **Then classify that entry by
(#259). No conclusion is not green: a configured run in progress is `conclusion`, never `status`**, which can disagree with it (#259). No
waited on, and waiting is compliance, not a stall. Cancelled or stale is conclusion is not green: a configured run in progress is waited on, and
not green, *stale* being a superseded head's check, which a head-scoped waiting is compliance, not a stall. Cancelled or stale is not green,
rollup never shows. Skipped or neutral is green, those being deliberate *stale* being a superseded head's check, which a head-scoped rollup never
"passed / not applicable" conclusions. No checks configured is green — shows. Skipped or neutral is green, those being deliberate "passed / not
the third ruled case, not an argued exception, so the request goes out at applicable" conclusions. No checks configured is green — the third ruled
once with no evidence owed; that never covers nothing-answered-yet, and case, not an argued exception, so the request goes out at once with no
the machine partitions alike, admitting the ask on `SUCCESS` and `NONE` evidence owed; that never covers nothing-answered-yet, and the machine
(#236). The costs behind the line are asymmetric: a false green spends a partitions alike, admitting the ask on `SUCCESS` and `NONE` (#236). The
costs behind the line are asymmetric: a false green spends a
three-reviewer round, a false red one author session. What the machine three-reviewer round, a false red one author session. What the machine
drops from the rollup before grading is crew's to describe. drops from the rollup before grading is crew's to describe.
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, stating what changed and what was verified. That covering every point, stating what changed and what was verified. That
reply is the written record: the engine mirrors it under the PR body's reply is the written record: the engine mirrors it under the PR body's
**Round log**, newest last, so you owe the reply and no body edit, and a **Round log**, newest last, marked with the round's head so a retry is a
round answered without one is recorded as such and never blocks handoff. no-op, so you owe the reply and no body edit; a round answered without
Then push the fixes and re-request **by head, not by verdict**. A push one is recorded as such and never blocks handoff. Then push the fixes and
makes every approval stale — an approval is of a specific tree, and the re-request **by head, not by verdict**. A push makes every approval stale
handoff predicate counts only approvals at the current head — so **every — an approval is of a specific tree, and the handoff predicate counts
panelist is re-requested, approvers included**; one left un-re-requested only approvals at the current head — so **every panelist is re-requested,
can never approve the tree you shipped (#26, #39). Only where the head approvers included**; one left un-re-requested can never approve the tree
did not move — answered with argument or evidence, nothing pushed — do you shipped (#26, #39). Only where the head did not move — answered with
you re-request just the non-approvers (#94). **The re-request carries the argument or evidence, nothing pushed — do you re-request just the
same green-check-at-head precondition**, argued exception included: a fix non-approvers (#94). **The re-request carries the same
push whose check comes up red is your next fix, not the panel's. Prefer green-check-at-head precondition**, argued exception included: a fix push
whose check comes up red is your next fix, not the panel's. Prefer
verification over argument — add the test that settles the doubt. verification over argument — add the test that settles the doubt.
3. Never dismiss a review, never merge, never mark your own work as passed. 3. Never dismiss a review, never merge, never mark your own work as passed.
A blocking point you disagree with is answered with evidence or escalated A blocking point you disagree with is answered with evidence or escalated