fix(pr): refresh re-fetches the PR description under a digest guard (#85)

[kevin-agrology]

TL;DR: In a multi-round PR review, refresh updated the diff every round but never the PR description, so from round 2 the scratch described the design the PR had when it was ingested next to a diff showing what it has now. Reviewers noticed the disagreement and spent findings on it. refresh now re-fetches the description too, and refuses to overwrite one that a person edited by hand.

Closes #85.

What changed

• seed records a digest of the description body it composed, alongside the diff digest it already records, as a multi-review-pr-desc: line in the .records sidecar.
• New replace-desc <scratch> <desc-file> subcommand swaps ## PR description under that digest guard. The current body must match a recorded digest; otherwise it exits 3 with a reason and writes nothing. An identical body is a no-op (no write, no new record). The splice follows replace-diff's discipline: record before rename, temp beside the scratch, component-by-component propagation.
• refresh fetches the PR body and calls replace-desc after the diff swap. A refused swap is not fatal: it means someone edited the description on purpose, so the round proceeds on the diff. The skip is printed (PR description not refreshed for round N) and the command doc tells the primary to relay it and reconcile by hand before seeding copies.
• Every content read sits inside the head confirmation window. refresh resolves the head, fetches the diff and the body, then re-confirms the head and refuses if it moved. Confirming between the two reads left the body outside the window, so a push in that gap paired a pre-push diff with a post-push description.
• A fatal description swap no longer leaves the round retryable. cmd_replace_desc runs in a subshell inside refresh: die calls exit, so an infra failure there used to kill refresh after the diff swap and before the head record, and the same-round retry refusal keys on that record.
• Docs: the round-N PR-flavor fan-out step in commands/multi-review.md and the pr.sh line in the README.

Design note: how the description window is located

The diff window is located as a ## Diff-to-next-heading candidate matched by digest. That does not work for the description: PR bodies routinely carry column-0 ## headings of their own (hunk lines are prefixed; prose is not), so such a candidate would end at the body's first heading and never verify. The description window is instead bounded by two trusted lines: the first ## PR description heading (above it seed writes only single-line header fields, and the title is single-line on GitHub, so nothing author-written can forge one earlier) and the heading of the digest-verified diff window. The digest then decides whether what lies between is still a body a writer composed. A decoy ## PR description planted inside the body cannot move the window; a test covers that.

Assumptions and scope

• Option 1 from the issue (re-fetch on refresh with a digest guard). Option 3 (refuse the whole refresh) was rejected as too strict for prose: the round can proceed on the diff, and the skip is loud.
• A scratch seeded before this version has no description record. refresh leaves its description alone and says so; ingest --fresh re-seeds with the record. No migration code.
• The ordering and crash-safety argument for the description writer is the same as replace-diff's; no new mechanism.
• A hand reconcile of the description is one-way. The edited body matches no recorded digest and nothing re-arms the guard, so every later round skips it too and the description is only as current as the primary's last manual pass. That is the guard working as intended — it will not clobber human text — but it was undocumented, and a primary could reasonably expect a later round to pick it back up. Now stated where the reconcile is instructed. A record-desc subcommand to re-arm the guard deliberately is the obvious follow-up; it is new behaviour, not a fix, so it is not in this PR.

Verification

Tests written first and watched fail for the expected reasons, then pass. That includes the review fixes below: the confirmation-window test went red at rc=0 with the post-push description spliced beside the pre-push diff, the retryable-window test at rc=1 with the diff swapped and no head record written, and the diagnosis test under the exact mutation it pins.

• 16 assertions in multi-review-pr.test.sh, 2 in multi-review-packaging.test.sh.
• All 18 suites green under bash 5 and all 18 under /bin/bash 3.2; shellcheck clean; version check 1.32.2 → 1.32.4.
• Mutation table: 13 new entries plus the re-pointed pr/seed-desc-propagation and pr/refresh-fetches-desc, each probed with --only. All caught by a named assertion except one recorded SURVIVES-BY-DESIGN with its covered outer layer named (pr/seed-desc-cat-propagation). --verify-table matches at 371 entries.

Review

Multi-reviewed as a star review (primary claude-opus-5; secondaries codex/gpt-5.6 and claude-fable-5-1 admitted, gemini quarantined on an auth failure). Converged in one round: 5 findings, 4 agreed and fixed here, 1 disputed.

The dispute is recorded on the PR: that the guard accepting every historical digest lets a hand edit restoring a prior body be overwritten. Refuted — the guard's predicate is "is this a body the tool composed", and every recorded digest is tool output, so a match is by construction not hand-authored prose; the record-before-rename crash window requires accepting more than the newest in any case.

One agreed finding was about this repo's own mutation table rather than the shipped code: pr/desc-window-needs-diff was recorded SURVIVES-BY-DESIGN behind a cover that does not hold — nothing drove replace-desc through a failing _locate_diff, and deleting the named outer layer as well still refuses at the record check, so no assertion could ever have surfaced its loss. What the fall-through actually costs is the diagnosis: the reader is told the document lacks a ## PR description heading it plainly has. That is now pinned by an assertion and the entry is a real caught entry.

Security

Not security-relevant. The description remains untrusted author text, as before; the new window is bounded by two lines the author cannot forge, and a body that does not match a recorded digest is never written over. No new dependencies, no new network calls beyond the existing gh pr view --json body that ingest already makes.

---

🤖 Opened by an AI agent — Claude Fable 5.1 (claude-fable-5-1); review fixes and this description by Claude Opus 5 (claude-opus-5). Both run by the maintainer, who remains accountable for the contents.

[kevin-agrology]

Commented inline (4)

Multi-review

Agreed findings (4)
🟠 med — refresh can still pair a pre-push diff with a post-push description because it confirms head before fetching the body. — risk: copies can again describe a different revision than their diff
🟡 low — The SURVIVES-BY-DESIGN reason on pr/desc-window-needs-diff misstates its cover: no test drives replace-desc with an unverifiable diff, so the mutation survives because the path is never exercised, not because a covered outer layer masks it — and losing the "no heading" refusal would still not surface it, since hstart="" then yields an empty window whose digest the record check refuses anyway. — risk: a table entry whose recorded reason is false is the "reads correctly but cannot fail" shape the table exists to catch; a test that strips the diff record and asserts exit 3/untouched would make the reason true
🟡 low — Once the primary reconciles the description by hand, as the round-N step instructs, no later refresh can ever write it again: the body matches no record, there is no record-desc to re-arm the guard, and only ingest --fresh re-seeds — so every subsequent round skips and warns, and the description is only as current as the primary's last manual pass. Neither the command doc nor the PR's assumptions say this. — risk: a one-time hand edit silently turns the fix off for the rest of the review, reintroducing the #85 drift the primary now has to close by hand each round
🟡 low — cmd_replace_desc can die (mktemp, record write, splice, mv) after cmd_replace_diff has swapped the diff and before cmd_record_head writes the head record; the same-round retry refusal keys on that head record, so a re-run is accepted and record-anchors reads the NEW diff under the old keys. The text-mismatch poison then degrades those findings to the summary rather than misplacing them, but silently. This widens a window that previously held only cmd_record_head itself; I could not trigger it without an infra failure. — risk: after an infra failure mid-refresh, anchored findings quietly lose their inline placement on the retry

Disagreements (1)
🟠 med — The description guard accepts every historical digest, so a hand edit that restores a prior body is treated as unedited and overwritten. — risk: intentional primary text can be silently lost — flagged by gpt-5.6; claude-opus-5 disputes: The guard's predicate is "is this body one the tool composed", not "is it the latest"; every recorded digest is a body seed/replace-desc wrote, so a body matching one is by construction not hand-authored prose — accepting the full history implements that predicate correctly, and the record-before-rename crash window requires accepting more than the newest in any case.

Quarantine events (secondary did not review that round; its findings for that round are excluded)

• gemini · dispatch exited 41; see pr-131.md.gemini.multi-review.log · round 1

———
🤖 Posted by AI agents (claude-opus-5 + gpt-5.6 + claude-fable-5-1 + gemini (quarantined)) via multi-review star review.

[kevin-agrology]

🟠 med — refresh can still pair a pre-push diff with a post-push description because it confirms head before fetching the body. — risk: copies can again describe a different revision than their diff — 🤖 multi-review star review (gpt-5.6 + claude-opus-5)

[kevin-agrology]

🟡 low — The SURVIVES-BY-DESIGN reason on pr/desc-window-needs-diff misstates its cover: no test drives replace-desc with an unverifiable diff, so the mutation survives because the path is never exercised, not because a covered outer layer masks it — and losing the "no heading" refusal would still not surface it, since hstart="" then yields an empty window whose digest the record check refuses anyway. — risk: a table entry whose recorded reason is false is the "reads correctly but cannot fail" shape the table exists to catch; a test that strips the diff record and asserts exit 3/untouched would make the reason true — 🤖 multi-review star review (claude-fable-5-1 + claude-opus-5)

[kevin-agrology]

🟡 low — Once the primary reconciles the description by hand, as the round-N step instructs, no later refresh can ever write it again: the body matches no record, there is no record-desc to re-arm the guard, and only ingest --fresh re-seeds — so every subsequent round skips and warns, and the description is only as current as the primary's last manual pass. Neither the command doc nor the PR's assumptions say this. — risk: a one-time hand edit silently turns the fix off for the rest of the review, reintroducing the #85 drift the primary now has to close by hand each round — 🤖 multi-review star review (claude-fable-5-1 + claude-opus-5)

[kevin-agrology]

🟡 low — cmd_replace_desc can die (mktemp, record write, splice, mv) after cmd_replace_diff has swapped the diff and before cmd_record_head writes the head record; the same-round retry refusal keys on that head record, so a re-run is accepted and record-anchors reads the NEW diff under the old keys. The text-mismatch poison then degrades those findings to the summary rather than misplacing them, but silently. This widens a window that previously held only cmd_record_head itself; I could not trigger it without an infra failure. — risk: after an infra failure mid-refresh, anchored findings quietly lose their inline placement on the retry — 🤖 multi-review star review (claude-fable-5-1 + claude-opus-5)