diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 81c601b..6017a3f 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -16,5 +16,5 @@ to the issue for triage to amend, not silently unshipped. --> ## Round log - + diff --git a/BUILDER.md b/BUILDER.md index 50878ff..33babb2 100644 --- a/BUILDER.md +++ b/BUILDER.md @@ -107,12 +107,12 @@ triage bug, and the move is to say so on the issue, not to guess. ([#52](https://github.com/heavy-duty/ceremony/issues/52)) and `offsite` ([#68](https://github.com/heavy-duty/ceremony/issues/68)) exemptions already guard — a parked claim nobody can name is an abandoned one. - Shape 4 alone is exempt from the separate comment: the handoff round - summary plus the `state:needs-human` write *is* its declaration — both + Shape 4 alone is exempt from the separate comment: the factual handoff + comment plus the `state:needs-human` write *is* its declaration — both halves are already there, what the claim waits on (the merge) and who owns the next move (the human), and both are visible to any scan as a - `labeled` event with the summary beside it. No second comment is owed - on the issue. Every other shape still declares as above. + `labeled` event with the comment beside it. No second comment is owed on + the issue. Every other shape still declares as above. Declared once, the declaration **stands** until the park's facts change: a resumption that finds nothing changed posts nothing — the standing declaration is the record, and silence while parked is compliant, not @@ -244,8 +244,16 @@ CONTRIBUTING; everything below is the shared flow.) 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 - covering every point, then push the fixes, then re-request **by head, - not by verdict**: if answering the round pushed any commit, every + covering every point and stating what changed and what was verified. + That reply is the written round record: the engine mirrors it under the + PR body's **Round log**, newest last, so the builder owes the reply and + no separate body edit. At re-request time the engine takes the author's + comments posted after the newest verdict in the round and appends them + with ``; an existing marker makes a retry a + no-op. If the builder posted no reply, the engine records that the round + passed without one and never blocks handoff on the omission. Then push + the fixes, then re-request **by head, not by verdict**: if answering the + round pushed any commit, every panelist's approval is now stale — an approval is of a specific tree, and the handoff predicate counts only approvals at the current head — so **every panelist is re-requested, the approvers included**; a @@ -333,12 +341,16 @@ When the round passes — every panel verdict approves the **current head**, and no `blocker:*` stands (conflicts rebased, CI green, drill recorded if this is a release PR) — hand it to the human, in order: -1. post the round summary (what changed per round, what was verified); -2. request the human's review; -3. set `state:needs-human` yourself. +1. request the human's review; +2. set `state:needs-human` yourself; +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 label write is optimistic — the reconciler validates it, and takes it -back if the PR is not actually mergeable-right-now. Then stop: the PR is the -human's. The claim is now parked as shape 4 (Picking, above) — the handoff -you just posted is its declaration, and your build slot is free. Address -what comes back (`state:addressing`) and re-hand-off the same way. +The builder composes no new summary at handoff: the authored record already +lives in the Round log, mirrored mechanically from each whole-round reply as +specified above. The label write is optimistic — the reconciler validates +it, and takes it back if the PR is not actually mergeable-right-now. Then +stop: the PR is the human's. The claim is now parked as shape 4 (Picking, +above) — the handoff you just posted is its declaration, and your build slot +is free. Address what comes back (`state:addressing`) and re-hand-off the +same way. diff --git a/changelog.d/196.md b/changelog.d/196.md new file mode 100644 index 0000000..a230d4a --- /dev/null +++ b/changelog.d/196.md @@ -0,0 +1,5 @@ +### Changed + +- Builder doctrine makes each whole-round reply the durable Round log record + mirrored by the engine, leaving handoff as a mechanical facts-only step + instead of a newly composed summary (#196).