docs(builder): WIP — drop optional whys, classes as a list

BUILDER.md

@@ -14,15 +14,14 @@ triage bug, and the move is to say so on the issue, not to guess.
   release-window members.
 - **Your own red head outranks a new claim**: repair a failing check at the
   head of a PR you authored before claiming another issue, or it strands
-  mergeable and unattended (#163). Record the failing check and its failure
+  mergeable and unattended (#163). Record the check and its failure class;
-  class; rerun a clearly retryable infrastructure failure without changing
+  rerun a clearly retryable infrastructure failure unchanged; treat a branch
-  code; treat a failure belonging to the branch as an ordinary fix round,
+  failure as an ordinary fix round, worklog and all; leave visible evidence
-  worklog and all; leave visible evidence where a rerun cannot be started or
+  where a rerun cannot be started or the cause is uncertain; never rerun a
-  the cause is uncertain; never rerun a deterministic branch failure without
+  deterministic branch failure without a corrective commit; hand off once
-  a corrective commit; hand off once the check is green and current-head
+  the check is green and current-head approvals stand. Such a PR is **not
-  approvals stand. Such a PR is **not parked**, whatever the round's verdict
+  parked**, whatever the round's verdict state says. How the engine detects
-  state says. Red and green are the review round's ruled terms below; how
+  a red head is crew's to describe, not this file's.
-  the engine detects a red head is crew's to describe, not this file's.
 - **One build at a time**: at most one issue on which you are writing or
   revising a deliverable, finished or released before you start new work.
   The rule counts build work in flight, not claims — a **parked** claim,
@@ -44,18 +43,19 @@ triage bug, and the move is to say so on the issue, not to guess.
      work, the direction names what the hold waits on, and only they end it.
      A hold ends the way it started, **on the labels**: where labels and
      prose disagree, the most recent queue-label event by the hold's owner
-     governs, an operator being free to lift by label alone (#149, #151). So
+     governs, an operator being free to lift by label alone (#149, #151).
-     read the label events (`gh api /repos/{owner}/{repo}/issues/{n}/timeline`),
+     Read the label events (`gh api
-     not only the comments, before standing down *or* standing up, and where
+     /repos/{owner}/{repo}/issues/{n}/timeline`), not only the comments,
-     you act against stale prose say so in the claim, naming the events,
+     before standing down *or* standing up, and where you act against stale
-     their timestamps and their actor. Refusing to claim through the
+     prose say so in the claim, naming the events, their timestamps and
-     contradiction is no resting place: where the events do not resolve it,
+     their actor. Refusing to claim through the contradiction is no resting
-     say so on the issue and take the next `ready` issue.
+     place: where the events do not resolve it, say so on the issue and take
+     the next `ready` issue.
   Not parked: waiting on yourself, on CI (a red head is your own work; a
   pending one resolves without you), or for a good moment. An issue you have
-  simply stopped working on is abandoned — unassign and restore `ready`. The
+  simply stopped working on is abandoned — unassign and restore `ready`.
-  rule counts work because parked claims are legitimately held beside the
+  Parked claims are legitimately held beside the one active build (#15, #16,
-  one active build (#15, #16, #73).
+  #73).
 
 ## Claiming
 
@@ -71,11 +71,10 @@ triage bug, and the move is to say so on the issue, not to guess.
   name the wait (the merge) and its owner (the human).
 - **A declaration stands until the park's facts change**, so a resumption
   that finds nothing changed posts nothing (#177). One new comment is owed
-  each time the facts change — the named wait resolves or changes hands, the
+  each time they do change — the named wait resolves or changes hands, the
   parked shape changes, or the claim unparks. A parked claim with **no open
   PR** still feeds the 48-hour reclaim clock, so refresh the declaration
-  before that window closes; that refresh is the only repeat a park owes, at
+  before that window closes; that refresh is the only repeat a park owes.
-  the reclaim window's cadence.
 - **Pick up `attention` before anything else.** Post a short pickup comment
   and remove `attention`; the removal is the ack. A demand on a parked claim
   is usually its unpark, so take the slot back — unless the demand *is* the
@@ -84,13 +83,13 @@ triage bug, and the move is to say so on the issue, not to guess.
 - **A directed hold keeps its bookkeeping visible.** The PR carries
   `blocked` with a comment naming what it waits on; the issue stays
   `claimed` and carries `attention` until the builder acknowledges it.
-  Nobody unassigns the issue, and the 48-hour reclaim does not fire because
+  Nobody unassigns the issue, and the 48-hour reclaim does not fire while
   the claim has an open PR.
 - **Unparking is a claim like any other** and takes the slot: if you are
   active elsewhere, finish or release that work first and say which you did
-  on both issues. Nothing counts claims per builder and no reconciler path
+  on both issues. No machinery counts claims per builder, and none should be
-  enforces this — the discipline is the declaration, not a counter, and no
+  built expecting this section to have specified one — the discipline is the
-  such machinery should be built expecting it to have been specified here.
+  declaration, not a counter.
 - **Abandoning is fine; ghosting is not.** Say where you got to, push the
   branch if it holds anything useful, unassign, and restore `ready`.
 
@@ -133,10 +132,10 @@ triage bug, and the move is to say so on the issue, not to guess.
   the fragment, a rarer kind only where a change genuinely is one. An entry
   is at most 300 characters, so a long change ships several short entries;
   wrapping one over continuation lines never counts against it. It **ends
-  with its issue citation**: one `(` group of `#N`, `repo#N` or
+  with its issue citation** — one parenthesised group of `#N`, `repo#N` or
-  `owner/repo#N` separated by `, `, then `)`, then the final `.` and nothing
+  `owner/repo#N` references separated by `, `, then the final `.` and
-  after it — `(#262).`, or `(#236, #250).` where an entry honestly lands two
+  nothing after it: `(#262).`, or `(#236, #250).` where an entry honestly
-  — and it need not name the fragment's own issue, which the filename
+  lands two — and need not name the fragment's own issue, which the filename
   carries. The guard reds a longer entry (#167) and an uncited one (#262)
   alike. Never edit `CHANGELOG.md` for an entry: the release PR assembles
   the section from the fragments (#112), and the monotonic guard refuses
@@ -153,8 +152,7 @@ triage bug, and the move is to say so on the issue, not to guess.
 - **Scope discipline: the PR does the issue — whole, and nothing else.**
   Adjacent problems go to a **discussion**, or a comment on the relevant
   issue, where triage does its job. You do not mint issues — nobody but
-  triage does — and you do not fix drive-by findings in the same PR, because
+  triage does — and you do not fix drive-by findings in the same PR.
-  a reviewer cannot converge on a widening target.
 
 ## The review round
 
@@ -174,26 +172,26 @@ triage bug, and the move is to say so on the issue, not to guess.
    request says so explicitly and names the evidence ("the same job fails
    identically on `origin/main` at `<sha>`"); silence about a red check is
    what is prohibited.
-   *Green* is a ruled term (operator, 2026-07-27), read in two steps,
+   *Green* is a ruled term (operator, 2026-07-27), read in two steps.
-   because a head carries more rollup entries than it has checks. **First
+   **First take the check's word at this head**: its newest entry by start
-   take the check's word at this head**: its newest entry by start time,
+   time — not by completion, a cancelled run outliving its replacement's
-   never a `CANCELLED` entry while the same check has a non-cancelled one at
+   start — and never a `CANCELLED` entry while the same check has a
-   that head. Date entries by start, not completion — a cancelled run
+   non-cancelled one at that head. A check whose every entry at the head is
-   outlives its replacement's start. A check whose every entry at the head
+   cancelled has not reported at all and is not green, the gate collapsing
-   is cancelled has not reported at all and stays not-green by the classes
+   the same way (#139, #276). **Then classify that entry from its
-   below, the gate collapsing the same way (#139, #276).
+   `conclusion`, never its `status`**, which can still disagree with it
-   **Then classify that entry from its `conclusion`, never its `status`**,
+   (#259):
-   which can still disagree with it (#259). No conclusion at all is neither
+   - no conclusion at all — not green: a configured run still in progress is
-   class: a configured run still in progress is not green, and waiting on it
+     waited on, and waiting is compliance, not a stall;
-   is compliance, not a stall. **Cancelled or stale** is not green — *stale*
+   - cancelled or stale — not green, *stale* meaning a superseded head's
-   means a superseded head's check, which a head-scoped rollup never shows,
+     check, which a head-scoped rollup never shows;
-   so what survives there is same-head cancellation. **Skipped or neutral**
+   - skipped or neutral — green, those being deliberate "passed / not
-   *is* green, those being deliberate "passed / not applicable" conclusions.
+     applicable" conclusions;
-   **No checks configured** is the third ruled case, not an argued
+   - no checks configured at the head — green, the third ruled case and not
-   exception: nothing is configured, so nothing is waited for and the
+     an argued exception: the request goes out at once, no evidence owed.
-   request goes out at once, no evidence owed — which rules
+     That never covers nothing-answered-yet, and the machine partitions
-   nothing-configured, never nothing-answered-yet, and the machine
+     alike, admitting the ask on `SUCCESS` and on `NONE` (#236).
-   partitions alike, admitting the ask on `SUCCESS` and on `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*
    drops from the rollup before grading is crew's to describe.
@@ -209,12 +207,11 @@ triage bug, and the move is to say so on the issue, not to guess.
    panelist is re-requested, the approvers included**; one left
    un-re-requested can never approve the tree you shipped (#26, #39). Only
    where the head did not move — the round answered with argument or
-   evidence, nothing pushed — do you re-request just the non-approvers, a
+   evidence, nothing pushed — do you re-request just the non-approvers (#94).
-   standing approval already covering this exact head (#94). **The
+   **The re-request carries the same green-check-at-head precondition**,
-   re-request carries the same green-check-at-head precondition**, argued
+   argued exception included: a fix push whose check comes up red is your
-   exception included: a fix push whose check comes up red is your next fix,
+   next fix, not the panel's. Prefer verification over argument — where a
-   not the panel's. Prefer verification over argument — where a reviewer
+   reviewer doubts behavior, add the test that settles it.
-   doubts behavior, add the test that settles it.
 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
    in the PR; silence and force-forward are not options, and a panel
@@ -233,9 +230,8 @@ may draft a PR but only the builder undrafts it. **Where a draft suppressed
 the checks, green is proven at the flip and the request still follows it** —
 marking ready is what runs the checks the draft held back, so the order is
 flip, let the head answer, then request, which is step 1's precondition and
-not a second one. Waiting there is compliance, not a stall, and
+not a second one. Waiting there is compliance, and `blocker:unrequested`
-`blocker:unrequested` does not fire while a head's checks are pending or red
+does not fire while a head's checks are pending or red (#236).
-(#236).
 
 ## The ruling ask