Merge pull request #197 from codex-bot-andresmgsl/build/196-round-log-handoff

docs: make round replies the durable handoff record

.github/pull_request_template.md

@@ -16,5 +16,5 @@ to the issue for triage to amend, not silently unshipped. -->
 
 ## Round log
 
-<!-- Append each round's summary here: what changed, what was verified.
+<!-- The engine appends each whole-round reply here, newest last: what
-Rounds are answered whole — one reply covering every point. -->
+changed and what was verified. Builders write the reply, not this section. -->

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
+  Shape 4 alone is exempt from the separate comment: the factual handoff
-  summary plus the `state:needs-human` write *is* its declaration — both
+  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
+  `labeled` event with the comment beside it. No second comment is owed on
-  on the issue. Every other shape still declares as above.
+  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,
+   covering every point and stating what changed and what was verified.
-   not by verdict**: if answering the round pushed any commit, every
+   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 `<!-- round:<head-sha> -->`; 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
@@ -331,14 +339,19 @@ item to its flow in the same comment ([LABELS.md](LABELS.md)).
 
 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:
+this is a release PR) — the engine performs these mechanical steps on the
+builder's behalf, in order:
 
-1. post the round summary (what changed per round, what was verified);
+1. request the human's review;
-2. request the human's review;
+2. set `state:needs-human`;
-3. 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
+The builder composes no new summary at handoff: the authored record already
-back if the PR is not actually mergeable-right-now. Then stop: the PR is the
+lives in the Round log, mirrored mechanically from each whole-round reply as
-human's. The claim is now parked as shape 4 (Picking, above) — the handoff
+specified above. The label write is optimistic — the reconciler validates
-you just posted is its declaration, and your build slot is free. Address
+it, and takes it back if the PR is not actually mergeable-right-now. Then
-what comes back (`state:addressing`) and re-hand-off the same way.
+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.

CONTRIBUTING.md

@@ -68,9 +68,11 @@ already proven:
    feedback. ([REVIEWER.md](REVIEWER.md) for why a comment-only review stalls
    the machine.)
 5. **Handoff**: when the round passes — every panel verdict is an approval of
-   the current head and no `blocker:*` label stands — the author posts the
+   the current head and no `blocker:*` label stands — the engine requests the
-   round summary, requests the human's review, and sets `state:needs-human`.
+   human's review, sets `state:needs-human`, and posts the handoff facts
-   The label write is optimistic; the reconciler validates it within seconds.
+   (approvals at the current head, head SHA, and Round-log pointer) on the
+   author's behalf. The label write is optimistic; the reconciler validates
+   it within seconds.
 6. **A human merges.** Nothing else merges.
 
 ### Roster

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).