From 806e99e1cb9f2d464ef289e4c964da3c5cbe0caf Mon Sep 17 00:00:00 2001 From: dan-claude-bot Date: Mon, 3 Aug 2026 23:44:43 +0000 Subject: [PATCH] docs(builder): green is read from conclusion, and the checkless head is the third ruled case MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- BUILDER.md | 36 ++++++++++++++++++++++++++---------- changelog.d/260.md | 6 ++++++ changelog.d/272.md | 6 ++++++ 3 files changed, 38 insertions(+), 10 deletions(-) create mode 100644 changelog.d/260.md create mode 100644 changelog.d/272.md diff --git a/BUILDER.md b/BUILDER.md index d1ed4b4..44d3316 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -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 on `origin/main` at ``"). Silence about a red check is what is prohibited; an argued exception shifts the burden to the author. - *Green* is a ruled term (operator, 2026-07-27): a **cancelled or - stale** check is not a green head — the rollup is scoped to the current - head, so what survives there is same-head cancellation, not - supersession by a newer push — 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. The costs behind the line are asymmetric: a false green spends - a three-reviewer round; a false red spends one author session. + *Green* is a ruled term (operator, 2026-07-27), and it is read from + each check's **`conclusion`**, never its `status`: a check carrying a + terminal conclusion is green or not-green by that conclusion whatever + its `status` field still reports — the two can disagree, and on #259 a + finished job's `status` lagged its own `conclusion: success` at the + head. A check with no conclusion at all is neither class: a configured + run still in progress is not green, and waiting for it is compliance, + 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 covering every point and stating what changed and what was verified. 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 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. +obeying this section). ## The ruling ask diff --git a/changelog.d/260.md b/changelog.d/260.md new file mode 100644 index 0000000..d32662f --- /dev/null +++ b/changelog.d/260.md @@ -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). diff --git a/changelog.d/272.md b/changelog.d/272.md new file mode 100644 index 0000000..adf20be --- /dev/null +++ b/changelog.d/272.md @@ -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).