docs(builder): green is read from conclusion, and the checkless head is the third ruled case

The ruled-term paragraph now names its field — a check carrying a
terminal conclusion is green or not-green by that conclusion whatever
its status reports — and rules the head with no checks configured:
nothing to wait for, request straight away, no argued exception owed.
The draft-round restatement comes out so the file states the rule once.

Closes #260, closes #272 via the PR.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
dan-claude-bot 2026-08-03 23:44:43 +00:00
parent c7f40bb818
commit 806e99e1cb
3 changed files with 38 additions and 10 deletions

View file

@ -252,14 +252,31 @@ CONTRIBUTING; the shared flow lives here and is not restated there.)
explicitly and names the evidence (e.g. "the same job fails identically explicitly and names the evidence (e.g. "the same job fails identically
on `origin/main` at `<sha>`"). Silence about a red check is what is on `origin/main` at `<sha>`"). Silence about a red check is what is
prohibited; an argued exception shifts the burden to the author. prohibited; an argued exception shifts the burden to the author.
*Green* is a ruled term (operator, 2026-07-27): a **cancelled or *Green* is a ruled term (operator, 2026-07-27), and it is read from
stale** check is not a green head — the rollup is scoped to the current each check's **`conclusion`**, never its `status`: a check carrying a
head, so what survives there is same-head cancellation, not terminal conclusion is green or not-green by that conclusion whatever
supersession by a newer push — while a **skipped or neutral** one *is* its `status` field still reports — the two can disagree, and on #259 a
green: those are deliberate "passed / not applicable" conclusions, and finished job's `status` lagged its own `conclusion: success` at the
reddening them would red every conditional job the fleet skips on head. A check with no conclusion at all is neither class: a configured
purpose. The costs behind the line are asymmetric: a false green spends run still in progress is not green, and waiting for it is compliance,
a three-reviewer round; a false red spends one author session. not a stall. A **cancelled or stale** check is not a green head —
*stale* means a check belonging to a superseded head, which the
head-scoped rollup does not show anyway, so what survives there is
same-head cancellation, never a same-head node whose `status` lags its
conclusion — while a **skipped or neutral** one *is* green: those are
deliberate "passed / not applicable" conclusions, and reddening them
would red every conditional job the fleet skips on purpose. And a head
with **no checks configured** is the third ruled case, not an argued
exception: nothing is configured, so there is nothing to wait for —
the precondition is satisfied and the request goes out straight away,
no evidence or explanation owed, because the argued-exception path
above exists for a check that ran and came up red. This rules
nothing-configured, never nothing-answered-yet: a pending run has an
owner, CI, and is waited on as above. The machine partitions the same
way — `blocker:unrequested` admits the ask on `SUCCESS` and on `NONE`
alike (#236) — so doctrine and gate state one rule and each points at
the other. The costs behind the line are asymmetric: a false green
spends 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 and stating what changed and what was verified. covering every point and stating what changed and what was verified.
That reply is the written round record: the engine mirrors it under the That reply is the written round record: the engine mirrors it under the
@ -330,8 +347,7 @@ 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 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 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 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 obeying this section).
for and is requested straight away, the same reading that sweep gives it.
## The ruling ask ## The ruling ask

6
changelog.d/260.md Normal file
View file

@ -0,0 +1,6 @@
### Changed
- BUILDER.md's green ruled term now names its field: greenness is read from
each check's `conclusion`, never its `status`, and *stale* means a check
of a superseded head — not a same-head node whose `status` lags its own
conclusion (#260).

6
changelog.d/272.md Normal file
View file

@ -0,0 +1,6 @@
### Changed
- BUILDER.md's step 1 now rules the checkless head: no checks configured is
nothing to wait for, and the request goes out straight away — stated once,
in the ruled-term paragraph, with the draft-round restatement removed
(#272).