forked from heavy-duty/ceremony
docs(builder): green check at the head gates both request points; red-head recovery in picking
The round precondition (crew#45) at step 1 and the re-request in step 2, with the argued exception and its evidence requirement; the ruled classification (cancelled/stale not green, skipped/neutral green, operator 2026-07-27); ci-red pickup precedence and crew#17's recovery path in Picking, with the explicit shape-2 carve-out so a red head never reads as parked. Refs #189 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
parent
a414f3105b
commit
203907b0ea
1 changed files with 56 additions and 3 deletions
59
BUILDER.md
59
BUILDER.md
|
|
@ -11,6 +11,27 @@ triage bug, and the move is to say so on the issue, not to guess.
|
||||||
- Respect dependency order: inside an epic, take the earliest unblocked
|
- Respect dependency order: inside an epic, take the earliest unblocked
|
||||||
unclaimed child. Between epics and strays, prefer the issue that unblocks
|
unclaimed child. Between epics and strays, prefer the issue that unblocks
|
||||||
the most other work.
|
the most other work.
|
||||||
|
- **Your own red head outranks a new claim.** A failing check at the head
|
||||||
|
of a PR you authored is picked up **before claiming another issue** —
|
||||||
|
repairing your own red PR comes ahead of new work, which is why the
|
||||||
|
engine's duty order evaluates ci-red between resume and build (crew#17:
|
||||||
|
ceremony#163 sat with full-panel approvals at its head, mergeable, and
|
||||||
|
stranded on an HTTP 429 in a job that never ran the PR's code, because no
|
||||||
|
wake covered a red head that owed no round and had no conflict). Red and
|
||||||
|
green here are the ruled terms of the review round below: a cancelled or
|
||||||
|
stale check is not a green head; a skipped or neutral one is. The
|
||||||
|
recovery path (crew#17): inspect the check at the head and record the
|
||||||
|
failing check and its failure class; rerun a clearly retryable
|
||||||
|
infrastructure failure without changing code; when the failure belongs to
|
||||||
|
the branch, return to the normal fix-round and worklog discipline; leave
|
||||||
|
visible evidence when a rerun cannot be started or the cause is
|
||||||
|
uncertain; never repeatedly rerun a deterministic branch failure without
|
||||||
|
a corrective commit; and proceed to handoff once the check is green and
|
||||||
|
current-head approvals stand. A PR of yours with a red head is **not
|
||||||
|
parked** — the next move is yours, whatever the verdict ledger says
|
||||||
|
(shape 2 below carves this out explicitly). How the engine detects a red
|
||||||
|
head — its ledger, its quiet rules, the rollup's node shapes — is crew's
|
||||||
|
to describe, not this file's.
|
||||||
- **One build at a time.** You hold at most one issue on which you are
|
- **One build at a time.** You hold at most one issue on which you are
|
||||||
writing or revising a deliverable — finish or release that work before
|
writing or revising a deliverable — finish or release that work before
|
||||||
starting new work. The rule counts build work in flight, not claims: a
|
starting new work. The rule counts build work in flight, not claims: a
|
||||||
|
|
@ -22,7 +43,12 @@ triage bug, and the move is to say so on the issue, not to guess.
|
||||||
belongs to someone else — either the round is awaiting its first
|
belongs to someone else — either the round is awaiting its first
|
||||||
verdicts, or it was answered whole and the non-approvers re-requested
|
verdicts, or it was answered whole and the non-approvers re-requested
|
||||||
(the review round, steps 1–2). This is the *live* round; shape 4 is
|
(the review round, steps 1–2). This is the *live* round; shape 4 is
|
||||||
the *passed* one — they are sequential and do not overlap;
|
the *passed* one — they are sequential and do not overlap. A red
|
||||||
|
check at the current head takes the deliverable **out of this
|
||||||
|
shape**: mid-round CI going red is exactly the state that reads as
|
||||||
|
"waiting on the panel" and is not — the next move is yours (the
|
||||||
|
red-head rule above), and reading it as parked is what strands the
|
||||||
|
PR;
|
||||||
3. every remaining acceptance criterion is operator-owned, stated as such
|
3. every remaining acceptance criterion is operator-owned, stated as such
|
||||||
by triage on the issue;
|
by triage on the issue;
|
||||||
4. the deliverable is **handed off** — the round passed, no `blocker:*`
|
4. the deliverable is **handed off** — the round passed, no `blocker:*`
|
||||||
|
|
@ -53,7 +79,8 @@ triage bug, and the move is to say so on the issue, not to guess.
|
||||||
that, or, if the events genuinely do not resolve it, say so on the
|
that, or, if the events genuinely do not resolve it, say so on the
|
||||||
issue and pick the next `ready` issue rather than idling on this one.
|
issue and pick the next `ready` issue rather than idling on this one.
|
||||||
Not parked — these are what the rule defends against: waiting on
|
Not parked — these are what the rule defends against: waiting on
|
||||||
yourself, waiting on CI, or waiting for a good moment. An issue you have
|
yourself, waiting on CI (a red head is your own work, above; a pending
|
||||||
|
one resolves without you), or waiting for a good moment. An issue you have
|
||||||
simply stopped working on is not parked either — that is abandonment,
|
simply stopped working on is not parked either — that is abandonment,
|
||||||
and its move is unchanged: unassign and restore `ready` (Claiming,
|
and its move is unchanged: unassign and restore `ready` (Claiming,
|
||||||
below).
|
below).
|
||||||
|
|
@ -194,9 +221,35 @@ CONTRIBUTING; everything below is the shared flow.)
|
||||||
does not become required. On rig#112 this distinction mattered: requesting
|
does not become required. On rig#112 this distinction mattered: requesting
|
||||||
codex and grok was correct for rig's panel even though ceremony's bench was
|
codex and grok was correct for rig's panel even though ceremony's bench was
|
||||||
larger, and the doctrine had not said which roster governed.
|
larger, and the doctrine had not said which roster governed.
|
||||||
|
**A review request requires a green check at the head.** A red check is
|
||||||
|
the author's own signal, not the panel's work: if the check is red, that
|
||||||
|
is your next task, not the panel's — fix it and push, then request. This
|
||||||
|
binds *you*, whether or not any engine enforces it. "My local suite
|
||||||
|
passed" is evidence about your machine; the check at the head is the
|
||||||
|
shared artifact the panel actually reads, and a reviewer's first act is
|
||||||
|
to read it. The one exception is a failure genuinely outside the PR — a
|
||||||
|
runner outage, a flaky dependency, a failure already present on the
|
||||||
|
default branch — and it is an exception only if the request says so
|
||||||
|
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
|
||||||
|
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.
|
||||||
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, then push the fixes, then re-request exactly the
|
covering every point, then push the fixes, then re-request exactly the
|
||||||
reviewers who did not approve. Prefer verification over argument: when a
|
reviewers who did not approve — **and the re-request carries the same
|
||||||
|
green-check-at-head precondition as the first request**, argued
|
||||||
|
exception included. This is where the measured cost landed: crew#40
|
||||||
|
burned two consecutive heads and four reviewer-rounds, every one
|
||||||
|
relaying a CI failure already visible in the job log (crew#45). A fix
|
||||||
|
push whose check comes up red is not ready to go back to the panel; it
|
||||||
|
is your next fix. Prefer verification over argument: when a
|
||||||
reviewer doubts behavior, add the test that settles it.
|
reviewer doubts behavior, add the test that settles it.
|
||||||
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
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue