heavy-duty/ceremony
7
0
Fork 2
Code Issues 1 Pull requests Projects Releases 8 Packages Wiki Activity Actions

docs(builder): WIP — terse register throughout

Browse source
This commit is contained in:
cndgrr 2026-08-04 13:23:56 +00:00
parent 1b6143f4aa
commit e1c3e3e9af
1 changed files with 181 additions and 201 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

382
BUILDER.md
View file

@ -6,244 +6,225 @@ triage bug, and the move is to say so on the issue, not to guess.
## Picking ## Picking
- Pick from issues labeled **`ready`** — never `blocked`, never `claimed`, - Pick from issues labeled **`ready`** — never `blocked`, `claimed`, or an
never an `epic` (epics organize; their children are the work). Inside an `epic` (epics organize; their children are the work). Inside an epic take
epic take the earliest unblocked unclaimed child; between epics and strays the earliest unblocked unclaimed child; otherwise prefer the issue that
prefer the issue that unblocks the most other work. Where a repository unblocks the most work. Where a repo adopts version epics,
adopts version epics, [RELEASES.md](RELEASES.md) governs the choice among [RELEASES.md](RELEASES.md) governs the choice among window members.
release-window members. - **Your own red head outranks a new claim**: repair a failing check at your
- **Your own red head outranks a new claim**: repair a failing check at the PR's head before claiming another issue, or it strands mergeable and
head of a PR you authored before claiming another issue, or it strands unattended (#163). Record the check and its failure class; rerun a clearly
mergeable and unattended (#163). Record the check and its failure class; retryable infrastructure failure unchanged; treat a branch failure as an
rerun a clearly retryable infrastructure failure unchanged; treat a branch ordinary fix round, worklog and all; leave evidence where a rerun cannot
failure as an ordinary fix round, worklog and all; leave visible evidence start or the cause is unclear; never rerun a deterministic failure without
where a rerun cannot be started or the cause is uncertain; never rerun a a corrective commit; hand off once green with current-head approvals. Such
deterministic branch failure without a corrective commit; hand off once a PR is **never parked**, whatever the round's verdict state says. How the
the check is green and current-head approvals stand. Such a PR is **not engine detects a red head is crew's to describe.
parked**, whatever the round's verdict state says. How the engine detects - **One build at a time**: one issue on which you are writing or revising a
a red head is crew's to describe, not this file's. deliverable, finished or released before you start more. The rule counts
- **One build at a time**: at most one issue on which you are writing or work in flight, not claims — a **parked** claim, whose next move is
revising a deliverable, finished or released before you start new work. someone else's, does not hold the slot. Five shapes park:
The rule counts build work in flight, not claims — a **parked** claim,
whose next move belongs to someone else, does not consume the slot.
Exactly five shapes park:
1. `needs-ruling` is set, the escalation names a decider, and its 1. `needs-ruling` is set, the escalation names a decider, and its
`Blocked:` line stops the remaining work; `Blocked:` line stops the rest;
2. a **live** review round holds the deliverable, every outstanding 2. a **live** review round holds it, every outstanding verdict someone
verdict someone else's — awaiting its first verdicts, or answered whole else's — awaiting first verdicts, or answered whole with the owed
with the owed re-requests posted, by head and not by verdict (steps 1–2 re-requests posted, by head and not by verdict (steps 1–2). A red check
below). A red check at the current head takes it out of this shape: the at the head takes it out of this shape: the next move is yours;
next move is yours; 3. every remaining acceptance criterion is operator-owned, stated so by
3. every remaining acceptance criterion is operator-owned, stated as such triage on the issue;
by triage on the issue; 4. it is **handed off** — round passed, no `blocker:*` standing,
4. the deliverable is **handed off** — the round passed, no `blocker:*` `state:needs-human` set per Handoff, the merge the human's. Shapes 2
stands, `state:needs-human` is set per Handoff, and the merge is the and 4 are sequential and never overlap;
human's. Shapes 2 and 4 are sequential and never overlap;
5. the claim is **held by directive** — triage or the operator stopped the 5. the claim is **held by directive** — triage or the operator stopped the
work, the direction names what the hold waits on, and only they end it. work, named what the hold waits on, and only they end it. A hold ends
A hold ends the way it started, **on the labels**: where labels and as it started, **on the labels**: where labels and prose disagree, the
prose disagree, the most recent queue-label event by the hold's owner most recent queue-label event by the hold's owner governs, and an
governs, an operator being free to lift by label alone (#149, #151). operator may lift by label alone (#149, #151). So read the label events
Read the label events (`gh api (`gh api /repos/{owner}/{repo}/issues/{n}/timeline`), not just the
/repos/{owner}/{repo}/issues/{n}/timeline`), not only the comments, comments, before standing down *or* up; acting against stale prose, say
before standing down *or* standing up, and where you act against stale so in the claim, naming the events, their timestamps and their actor.
prose say so in the claim, naming the events, their timestamps and Refusing to claim through the contradiction is no resting place: where
their actor. Refusing to claim through the contradiction is no resting the events do not resolve it, say so and take the next `ready` issue.
place: where the events do not resolve it, say so on the issue and take Not parked: waiting on yourself, on CI (a red head is yours; a pending one
the next `ready` issue. resolves without you), or for a good moment. An issue you simply stopped
Not parked: waiting on yourself, on CI (a red head is your own work; a working on is abandoned — unassign and restore `ready`. Parked claims are
pending one resolves without you), or for a good moment. An issue you have legitimately held beside the one active build (#15, #16, #73).
simply stopped working on is abandoned — unassign and restore `ready`.
Parked claims are legitimately held beside the one active build (#15, #16,
#73).
## Claiming ## Claiming
- Assign yourself, swap `ready` → `claimed`, and comment that you are - Assign yourself, swap `ready` → `claimed`, and comment that you are
starting. The claim promises a draft PR soon: a claim with no PR and no starting. The claim promises a draft PR soon: a claim with no PR and no
activity is what the staleness sweep reclaims, unless `offsite` records activity is what the staleness sweep reclaims, unless `offsite` records
that its PR lives in another repository. that its PR lives in another repo.
- **A park is declared, never inferred.** Comment on the issue naming what - **A park is declared, never inferred.** Comment naming what the claim
the claim waits on and who owns the next move; no new label, the comment waits on and who owns the next move — no new label; the comment is the
being the activity that feeds the same reclaim clock the `needs-ruling` activity the reclaim clock reads, as for `needs-ruling` (#52) and
(#52) and `offsite` (#68) exemptions guard. Shape 4 owes no separate `offsite` (#68). Shape 4 is exempt: the handoff comment and
comment: the handoff comment plus the `state:needs-human` write already `state:needs-human` already say both.
name the wait (the merge) and its owner (the human).
- **A declaration stands until the park's facts change**, so a resumption - **A declaration stands until the park's facts change**, so a resumption
that finds nothing changed posts nothing (#177). One new comment is owed finding nothing changed posts nothing (#177). Each change owes one comment
each time they do change — the named wait resolves or changes hands, the — the wait resolves or changes hands, the shape changes, the claim
parked shape changes, or the claim unparks. A parked claim with **no open unparks. A parked claim with **no open PR** still feeds the 48-hour
PR** still feeds the 48-hour reclaim clock, so refresh the declaration reclaim clock, so refresh the declaration before that window closes; that
before that window closes; that refresh is the only repeat a park owes. is the only repeat a park owes.
- **Pick up `attention` before anything else.** Post a short pickup comment - **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 and remove the label, which is the ack. A demand on a parked claim is
is usually its unpark, so take the slot back — unless the demand *is* the usually its unpark, so take the slot back — unless the demand *is* the
park, where the pickup comment doubles as the declaration and the slot park, where the pickup comment doubles as the declaration.
stays free.
- **A directed hold keeps its bookkeeping visible.** The PR carries - **A directed hold keeps its bookkeeping visible.** The PR carries
`blocked` with a comment naming what it waits on; the issue stays `blocked` with a comment naming what it waits on; the issue stays
`claimed` and carries `attention` until the builder acknowledges it. `claimed` and carries `attention` until the builder acks. Nobody unassigns
Nobody unassigns the issue, and the 48-hour reclaim does not fire while it, and the 48-hour reclaim does not fire while the claim has an open PR.
the claim has an open PR.
- **Unparking is a claim like any other** and takes the slot: if you are - **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 active elsewhere, finish or release that work first and say which on both
on both issues. No machinery counts claims per builder, and none should be issues. No machinery counts claims per builder, and none should be built
built expecting this section to have specified one — the discipline is the expecting this section to have specified one.
declaration, not a counter.
- **Abandoning is fine; ghosting is not.** Say where you got to, push the - **Abandoning is fine; ghosting is not.** Say where you got to, push the
branch if it holds anything useful, unassign, and restore `ready`. branch if it holds anything useful, unassign, restore `ready`.
## Building ## Building
- Branch per issue; open the PR **as a draft early**, `Closes #N` in the - Branch per issue; open the PR **as a draft early**, `Closes #N` in the
body. Drafts are invisible to the reviewer panel on purpose: the draft body. Drafts are invisible to the panel on purpose: the draft phase is
phase is yours. yours.
- **`Closes #N` does not cross repos.** A PR in a different repo from its - **`Closes #N` does not cross repos.** A PR in a different repo from its
authorizing issue says `Part of <owner>/<repo>#N`, sets `offsite`, and issue says `Part of <owner>/<repo>#N`, sets `offsite`, and comments the
comments the draft PR link on that issue in the same step. Triage closes draft link on that issue in the same step. Triage closes that issue by
that issue by hand once its acceptance criteria are met, and at that hand once its criteria are met; at that handoff the builder reports
handoff the builder reports whether the PR merged or closed and clears whether the PR merged or closed and clears `offsite` (#13, #16).
`offsite` in the same comment (#13, #16).
- **`Closes #N` does not survive a post-merge criterion.** Where the issue's - **`Closes #N` does not survive a post-merge criterion.** Where the issue's
body states that a criterion can only be checked after the merge — a live body says a criterion can only be checked after the merge — a workflow
proof of a workflow trigger, a released-artifact check, anything whose trigger proved live, a released artifact, anything whose subject does not
subject does not exist until the change is on the base branch — the exist until the change is on the base branch — the same-repo PR says
same-repo PR says `Refs #N` and triage closes by hand on the evidence. The `Refs #N` and triage closes by hand on the evidence. The merge releases
merge releases the claim: the issue moves to `post-merge`, the builder the claim: the issue goes `post-merge`, the builder walks away, triage
walks away, and triage owns verification and closure, returning it to owns verification and closure, and corrective work is a fresh issue any
`ready` or minting a fresh issue for corrective work that any builder builder claims from current `main`. The issue body is what says so — you
claims from current `main`. The issue body is what says so — you never never judge which issues qualify, and absent that instruction `Closes #N`
judge which issues qualify, and absent that instruction `Closes #N` is the is the default (#151).
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
explaining why the PR does not close it: GitHub reads the body by explaining why the PR does not close it: GitHub reads the body by
adjacency, not intent, and a code span does not protect the phrase (#200, adjacency, not intent, and a code span does not protect the phrase (#200,
#218). Put the number first (`#N is closed by hand`) or omit it. #218). Put the number first (`#N is closed by hand`) or omit it.
- **The issue's acceptance criteria are your definition of done.** Reproduce - **The issue's acceptance criteria are your definition of done**: reproduce
them as a checklist in the PR body and check them honestly as you go; a them as a checklist in the PR body and check them honestly. A criterion
criterion that turns out wrong or unreachable goes back to triage to be that turns out wrong or unreachable goes back to triage to be amended,
amended, never silently shipped short. never silently shipped short.
- **Every behavior change writes one fragment**, `changelog.d/<issue>.md` - **Every behavior change writes one fragment**, `changelog.d/<issue>.md`
named for the authorizing issue (`<repo>-<issue>.md` cross-repo): the named for the authorizing issue (`<repo>-<issue>.md` cross-repo): the
exact prose to be published and nothing else — `- ` bullets, plus in a exact prose to be published and nothing else — `- ` bullets, plus in a
grouped repo the `### Added` / `### Changed` / `### Fixed` headings inside grouped repo the `### Added` / `### Changed` / `### Fixed` headings, a
the fragment, a rarer kind only where a change genuinely is one. An entry rarer kind only where a change genuinely is one. An entry is at most 300
is at most 300 characters, so a long change ships several short entries; characters, so a long change ships several short entries; wrapping one
wrapping one over continuation lines never counts against it. It **ends over continuation lines never counts against it. It **ends with its issue
with its issue citation** — one parenthesised group of `#N`, `repo#N` or citation** — a parenthesised group of `#N`, `repo#N` or `owner/repo#N`
`owner/repo#N` references separated by `, `, then the final `.` and separated by `, `, then the final `.` and nothing after: `(#262).`, or
nothing after it: `(#262).`, or `(#236, #250).` where an entry honestly `(#236, #250).` where an entry honestly lands two — and need not name the
lands two — and need not name the fragment's own issue, which the filename fragment's own issue, which the filename carries. The guard reds a longer
carries. The guard reds a longer entry (#167) and an uncited one (#262) entry (#167) and an uncited one (#262). Never edit `CHANGELOG.md` for an
alike. Never edit `CHANGELOG.md` for an entry: the release PR assembles entry: the release PR assembles the section from fragments (#112), and the
the section from the fragments (#112), and the monotonic guard refuses monotonic guard refuses anything deleting a shipped heading.
anything that deletes a shipped heading.
- Follow the repo's conventions file and match the code you touch. Tests are - Follow the repo's conventions file and match the code you touch. Tests are
not optional: the issue's test plan is the floor, not the ceiling. not optional: the issue's test plan is the floor, not the ceiling.
- **A write-capable job gets a repo-owned script, not a third-party action.** - **A write-capable job gets a repo-owned script, not a third-party action.**
Where the job's token can write (`packages: write`, `contents: write`, Where the token can write (`packages: write`, `contents: write`,
`id-token: write`, deploy secrets), default to a script in the repo that a `id-token: write`, deploy secrets), default to a script a test can drive;
test can drive; a third-party action there needs an established publisher a third-party action there needs an established publisher and a
and a full-commit-SHA pin, and read-only jobs still SHA-pin. The full rule full-commit-SHA pin, and read-only jobs still SHA-pin. The full rule and
and the red-flag profile a reviewer applies are in REVIEWER.md §What you its red-flag profile are in REVIEWER.md §What you review against, item 2
review against, item 2 (#216). (#216).
- **Scope discipline: the PR does the issue — whole, and nothing else.** - **Scope discipline: the PR does the issue — whole, and nothing else.**
Adjacent problems go to a **discussion**, or a comment on the relevant Adjacent problems go to a discussion, or a comment on the relevant issue.
issue, where triage does its job. You do not mint issues — nobody but You do not mint issues — nobody but triage does — and you do not fix
triage does — and you do not fix drive-by findings in the same PR. drive-by findings in the same PR.
## The review round ## The review round
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 in either case (#224) — never the roster of the repo the minus the author (#224) — never the roster of the repo the issue is in.
issue is in. That repo's `.github/labels.conf` governs over its That repo's `.github/labels.conf` governs over its CONTRIBUTING roster,
CONTRIBUTING roster, being what the state machine reads; where the PR being what the state machine reads; where it names no roster, ask triage
repo names no roster, ask triage on the authorizing issue rather than on the authorizing issue rather than guess. An off-panel reviewer may be
guessing. An off-panel reviewer may be requested, saying that their requested, said to be advisory and not required.
verdict is advisory and does not become required. **A review request requires a green check at the head**, whether or not
**A review request requires a green check at the head**, and that binds an engine enforces it: a red check is the author's own signal, so fix it
you whether or not any engine enforces it: a red check is the author's and push, then request. The one exception is a failure genuinely outside
own signal, so fix it and push, then request. The one exception is a the PR — a runner outage, a flaky dependency, a failure already on the
failure genuinely outside the PR — a runner outage, a flaky dependency, a default branch — and only where the request says so and names the
failure already present on the default branch — and only where the evidence ("the same job fails identically on `origin/main` at `<sha>`");
request says so explicitly and names the evidence ("the same job fails silence about a red check is what is prohibited.
identically on `origin/main` at `<sha>`"); silence about a red check is *Green* is a ruled term, read in two steps. **First take the check's word
what is prohibited. at this head**: its newest entry by start time — not completion, a
*Green* is a ruled term (operator, 2026-07-27), read in two steps. cancelled run outliving its replacement's start — and never a `CANCELLED`
**First take the check's word at this head**: its newest entry by start entry while the same check has a non-cancelled one there. A check whose
time — not by completion, a cancelled run outliving its replacement's entries at the head are all cancelled has not reported at all and is not
start — and never a `CANCELLED` entry while the same check has a green, the gate collapsing alike (#139, #276). **Then classify that entry
non-cancelled one at that head. A check whose every entry at the head is by `conclusion`, never `status`**, which can disagree with it (#259):
cancelled has not reported at all and is not green, the gate collapsing - no conclusion — not green; a configured run in progress is waited on,
the same way (#139, #276). **Then classify that entry from its and waiting is compliance, not a stall;
`conclusion`, never its `status`**, which can still disagree with it - cancelled or stale — not green (*stale* is a superseded head's check,
(#259): which a head-scoped rollup never shows);
- no conclusion at all — not green: a configured run still in progress is - skipped or neutral — green, being deliberate "passed / not applicable"
waited on, and waiting is compliance, not a stall; conclusions;
- cancelled or stale — not green, *stale* meaning a superseded head's - no checks configured — green: the third ruled case, not an argued
check, which a head-scoped rollup never shows; exception, so the request goes out at once with no evidence owed. It
- skipped or neutral — green, those being deliberate "passed / not never covers nothing-answered-yet, and the machine partitions alike,
applicable" conclusions; admitting the ask on `SUCCESS` and `NONE` (#236).
- no checks configured at the head — green, the third ruled case and not
an argued exception: the request goes out at once, no evidence owed.
That never covers nothing-answered-yet, and the machine partitions
alike, admitting the ask on `SUCCESS` and on `NONE` (#236).
The costs behind the line are asymmetric: a false green spends a 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 and stating what changed and what was verified. That covering every point, stating what changed and what was verified. That
reply is the written round record: the engine mirrors it under the PR reply is the written record: the engine mirrors it under the PR body's
body's **Round log**, newest last, so the builder owes the reply and no **Round log**, newest last, so you owe the reply and no body edit, and a
separate body edit, and a round answered without one is recorded as such round answered without one is recorded as such and never blocks handoff.
and never blocks handoff.
Then push the fixes and re-request **by head, not by verdict**. A push Then push the fixes and re-request **by head, not by verdict**. A push
makes every approval stale — an approval is of a specific tree, and the makes every approval stale — an approval is of a specific tree, and the
handoff predicate counts only approvals at the current head — so **every handoff predicate counts only approvals at the current head — so **every
panelist is re-requested, the approvers included**; one left panelist is re-requested, approvers included**; one left un-re-requested
un-re-requested can never approve the tree you shipped (#26, #39). Only can never approve the tree you shipped (#26, #39). Only where the head
where the head did not move — the round answered with argument or did not move — answered with argument or evidence, nothing pushed — do
evidence, nothing pushed — do you re-request just the non-approvers (#94). you re-request just the non-approvers (#94). **The re-request carries the
**The re-request carries the same green-check-at-head precondition**, same green-check-at-head precondition**, argued exception included: a fix
argued exception included: a fix push whose check comes up red is your push whose check comes up red is your next fix, not the panel's. Prefer
next fix, not the panel's. Prefer verification over argument — where a verification over argument — where a reviewer doubts behavior, add the
reviewer doubts behavior, add the test that settles it. 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
in the PR; silence and force-forward are not options, and a panel in the PR; silence and force-forward are not options, and a panel
deadlock is one kind of human-owned decision (#50 D11). deadlock is one kind of human-owned decision (#50 D11).
**A fix round may ride a draft**, and the draft changes nothing about who **A fix round may ride a draft**, and the draft changes nothing about who
owes what: an engine may convert a PR back to draft when a round closes, and owes what: an engine may draft a PR when a round closes, ceremony implements
ceremony implements no such conversion, but whoever meets a mid-round draft no such conversion, and whoever meets a mid-round draft reads it as a draft
reads it as a draft always read — the draft phase is yours and the panel always read — the phase is yours, the panel cannot see it — while the round
cannot see it — while the round outranks the draft, so you still owe it outranks the draft, so you owe it whole, the fixes and the reply and the
whole, the fixes and the reply and the flip ([LABELS.md](LABELS.md)'s flip ([LABELS.md](LABELS.md)'s `state:building` row, #205).
`state:building` row, #205). **Ready-for-review is the act that ends the **Ready-for-review is the act that ends the round, and it is the builder's
round, and it is the builder's alone**: the flip asserts that the round was alone**: the flip asserts the round was answered whole, the one judgement
answered whole, the one judgement its author cannot delegate, so an engine its author cannot delegate, so an engine may draft a PR but only the builder
may draft a PR but only the builder undrafts it. **Where a draft suppressed undrafts it. **Where a draft suppressed the checks, green is proven at the
the checks, green is proven at the flip and the request still follows it** — flip and the request still follows it** — marking ready runs the checks the
marking ready is what runs the checks the draft held back, so the order is draft held back, so the order is flip, let the head answer, then request,
flip, let the head answer, then request, which is step 1's precondition and which is step 1's precondition and not a second one. Waiting there is
not a second one. Waiting there is compliance, and `blocker:unrequested` compliance, and `blocker:unrequested` does not fire while a head's checks
does not fire while a head's checks are pending or red (#236). are pending or red (#236).
## The ruling ask ## The ruling ask
Set `needs-ruling` whenever a decision belongs to a human: org policy, Set `needs-ruling` whenever a decision belongs to a human: org policy,
published artifacts, secrets, prod, or any choice whose cost lands outside published artifacts, secrets, prod, or any choice whose cost lands outside
the PR. A panel deadlock is one instance, not the definition. The builder is the PR — a panel deadlock is one instance, not the definition. The builder
the accountable flag-setter on a PR and consolidates the decision into one is the accountable flag-setter on a PR and consolidates the decision into
comment rather than forwarding several reviewers' phrasings (#50 D11). one comment rather than forwarding several reviewers' phrasings (#50 D11).
Keep at most these five lines above the fold and put all other analysis Keep at most these five lines above the fold, all other analysis inside it.
inside the fold. The field labels are fixed because the ruling machinery The field labels are fixed because the ruling machinery checks for them
checks for them (#50 D12): (#50 D12):
```text ```text
🧭 needs-ruling — <the decision, one line> 🧭 needs-ruling — <the decision, one line>
@ -276,31 +257,30 @@ event**, not its `Default:` deadline or the last activity (#50 D13–D14):
it as a decision, and remains accountable; the operator can overturn it at it as a decision, and remains accountable; the operator can overturn it at
merge. merge.
A re-flag starts a fresh ladder. The ladder applies whatever `Default:` says, A re-flag starts a fresh ladder. It applies whatever `Default:` says,
including a hard block, and an active back-and-forth still climbs it — unlike including a hard block, and an active back-and-forth still climbs it —
the 7-day nudge, which resets on real activity. The machine observes both unlike the 7-day nudge, which resets on real activity. The machine observes
clocks but never sets, clears, or decides `needs-ruling`. both clocks but never sets, clears, or decides `needs-ruling`. The label
stays until agreement is *reached*, not until the maintainer replies: the
The label stays until agreement is *reached*, not until the maintainer setter records the ruling, removes the label, and returns the item to its
replies. The setter records the ruling, removes the label, and returns the flow in the same comment ([LABELS.md](LABELS.md)).
item to its flow in the same comment ([LABELS.md](LABELS.md)).
## Handoff ## Handoff
When the round passes — every panel verdict approves the **current head**, When the round passes — every panel verdict approving the **current head**,
and no `blocker:*` stands (conflicts rebased, CI green, drill recorded if no `blocker:*` standing (conflicts rebased, CI green, drill recorded if this
this is a release PR) — the engine performs these mechanical steps on the is a release PR) — the engine does these mechanical steps for the builder,
builder's behalf, in order: in order:
1. request the human's review; 1. request the human's review;
2. set `state:needs-human`; 2. set `state:needs-human`;
3. post the engine-rendered handoff comment: approvals at the current head, 3. post the engine-rendered handoff comment: approvals at the current head,
the head SHA, and a pointer to the PR body's **Round log**. the head SHA, and a pointer to the PR body's **Round log**.
The builder composes no new summary at handoff: the authored record already The builder composes no new summary: the authored record already lives in
lives in the Round log, mirrored from each whole-round reply. The label write the Round log, mirrored from each whole-round reply. The label write is
is optimistic — the reconciler validates it and takes it back if the PR is optimistic — the reconciler validates it and takes it back if the PR is not
not actually mergeable-right-now. Then stop: the PR is the human's, and the mergeable-right-now. Then stop: the PR is the human's, and the claim is
claim is parked as shape 4 (Picking, above), that handoff comment being its parked as shape 4 (Picking, above), that handoff comment being its
declaration and your build slot free. Address what comes back declaration and your slot free. Address what comes back (`state:addressing`)
(`state:addressing`) and re-hand-off the same way. and re-hand-off the same way.