docs(review): tie verdicts to pull request heads

[coreplane-switchboard]

Proposes record 0076: every posted pull-request verdict becomes a durable, head-bound subscription that renews after substantive pushes. It now closes the cold reader's ambiguity about stale approvals and ship-owned re-review arbitration.

Why: Issue #2145 found four merges whose verdicts no longer matched the merged head. Record 0076 makes renewal bot-owned; its cold-reader receipt passed with two notes now resolved before the two-unit rollout.

Where to look

1. Decision and success criteria Defines one durable subscription, once-per-surface updates, head-bound approval, the rebase exception, repository setting and optional check.
2. Ownership and residual enforcement hole Makes the ship round the sole re-review and names the stale-approval merge still possible when dismissal and check enforcement both fail. ⚠ Wrong arbitration duplicates costly reviews; overstated enforcement hides an unsafe merge window.
3. Requested-review hard case Traces duplicate webhooks, a second push during review, stale completion, blocker repair and unchanged-rebase carry. ⚠ A duplicate run or late approval would recreate the issue's unsafe merge window.
4. Ship-owned hard case Shows a fix push racing synchronize intake while the webhook records deferral and the owning unit performs exactly one re-review. ⚠ Ambiguous ownership could wake both ship and generic review paths for one head.
5. Rollout and acceptance gates Splits bot-owned renewal from optional GitHub enforcement and keeps acceptance behind the independent cold-reader receipt.
6. Generated decision index Publishes record 0076 as proposed in the generated architecture index.

Feedback wanted: Is the ship-owned deferral rule precise enough to implement, and does the residual-hole sentence correctly bound what only a required optional check can close?

Risk: Docs only; runtime behavior is unchanged. A mistaken decision could guide duplicate review dispatch or leave stale approvals mergeable. Rollback is a revert before acceptance; status remains proposed.

Verified: After rebase, decisions, docs, hygiene, specs, changed-file Prettier and title gates passed; docs:gen changed 0 files. The independent cold-reader receipt passed.

Decisions (4)

• The bot owns renewal. Branch protection can block a merge but cannot start the missing review, update the original thread or renew approval. The durable subscription therefore owns orchestration.
• The live ship owner arbitrates. A generic webhook review would duplicate the ship unit's existing durable round. The ship round performs the re-review; synchronize intake records its deferral and dispatches only when no live ship owner exists.
• Unchanged patches carry approval. Record 0071 treats an empty range-diff as proof that the reviewed patch did not change. Re-reviewing adds cost without evidence; an unknown comparison still fails toward re-review.
• The check closes a named residual hole. Product state fails closed when GitHub refuses dismissal, but an unrequired red check cannot block merge. Requiring the projected check is the optional enforcement layer that closes that remaining stale-approval path.

Validation (7 criteria)

Criterion	Proof
Decision records remain structurally valid and record 0076 remains proposed	npm run decisions:check passed after rebase: 115 records valid, supersession links resolve and accepted records are unchanged.
Generated documentation matches its sources	npm run docs:gen completed with 0 of 12 files changed; npm run docs:check then passed for all 12 generated files.
Public documentation adds no unapproved imprint	npm run hygiene:check passed: 9 files and 37 retained hits remain within the recorded allowlist.
Spec proof references remain valid	npm run specs:check passed: 51 specs and 5,680 proof references checked.
Changed Markdown is formatted	npx prettier --check docs/decisions/0076-a-verdict-and-its-approval-belong-to-the-head-they-reviewed.md passed.
PR title satisfies changelog grammar	npm run check:pr-title -- "docs(review): tie verdicts to pull request heads" passed.
Independent cold-reader gate passed	The PR comment records PASS and the two non-blocking notes folded into this head.

For agents

Existing PR #2207 was updated in place; no new branch or pull request was created. Branch docs/record-0076-rereview-on-push was fetched and rebased onto origin/main at 9f6516d immediately before the guarded force push. Pushed head is 0dcf640. This fix changes only record 0076; the PR's generated decision-index line was already present and docs:gen reported no changes. Review the residual-hole sentence at line 51 and the ship-owned trace at lines 84–91 against the cold-reader comment.
Requested by @justinhelmer in slack:C0BRRHKFLCB

🤖 Generated with Claude Code

[justinhelmer]

Cold-reader gate: PASS

A fresh reader was given only docs/decisions/0076-a-verdict-and-its-approval-belong-to-the-head-they-reviewed.md at a8735e40, with no repository access and no session context, and asked to restate the bet, name the hardest part, and state its first objection and whether the record answers it.

The bet, restated. Switchboard, not branch protection, owns keeping a verdict current after the head it reviewed moves: every posted verdict leaves one durable per-pull-request subscription, a substantive head move invalidates the verdict and the bot-minted approval, claims the transition once, starts exactly one replacement review, posts one head-moved update and one verdict update, and re-mints approval only on an LGTM at the new head, while an unchanged-patch rebase carries the decision forward under record 0071. Second half: a repository-scoped, default-on setting plus an optional check that is a read-only projection of that subscription, which branch protection may require but which never starts or owns the re-review.

Hardest part, as the record presents it. Difficulty map item 1, one owner across requested reviews and ship units: a ship unit already knows its pull request while a directly requested review ends with only a run record, so the subscription index must be establishable from either path without one pull_request.synchronize event waking two handlers.

First objection, and where it is answered. Unit one makes a verdict stale but stops no merge; if the approval withdrawal is refused, GitHub keeps counting the stale approval. The record concedes the failure ("Failure to clear the GitHub artifact leaves the product state stale") and places enforcement in unit two's optional check, and its acceptance criterion is scoped to state rather than to merges. The reader judged that answered but only by cross-referencing three sections.

Two notes carried into a fix round (neither blocks acceptance):

1. Say plainly, in one sentence, that with the dismissal refused and the optional check not required, the motivating failure is still reachable — today that reading only emerges from three sections read together.
2. Decide the ship-versus-webhook arbitration. Criterion 1 says a ship unit reuses its existing ownership rather than creating a second watcher, and the difficulty map forbids two handlers dispatching two reviews, but the record never says which side acts when ship pushes its own fix commit. The single hard-case trace covers a directly requested review only, leaving the most expensive path untraced.

[coreplane-switchboard]

Changes requested: The proposal does not enforce stale-approval safety on GitHub and gives conflicting rules for push coalescing.

Warning

Changes requested · head a8735e4 · 2 findings: 1 major, 1 minor

Severity	Finding	Where
major	F1 The optional check cannot fail closed when approval withdrawal fails	docs/decisions/0076-a-verdict-and-its-approval-belong-to-the-head-they-reviewed.md:87
minor	F2 The hard-case trace contradicts the one-active-review coalescing rule	docs/decisions/0076-a-verdict-and-its-approval-belong-to-the-head-they-reviewed.md:77

Full review

F1: If GitHub refuses to withdraw the stale approval, the proposal only marks product state and an optional check red. GitHub can still count the old approval and merge the changed patch—the exact failure this record is meant to prevent. Require an enforced current-head gate or another mechanism that guarantees stale approvals cannot satisfy merge policy.

F2: The trace creates rC while rB is still active, but line 92 promises coalescing to the newest head with one active automatic review per pull request. Under a push burst, the trace’s design starts one costly run per head. Specify whether the active run is superseded before dispatching the newest run or whether new heads wait and coalesce, then align the trace, invariant, and acceptance test.

[coreplane-switchboard]

Changes requested: The proposal contradicts itself on whether successive pushes may create concurrent automatic reviews.

Warning

Changes requested · head ec7c836 · 1 finding: 1 minor

Severity	Finding	Where
minor	F1 Choose one concurrency policy for successive pushes	docs/decisions/0076-a-verdict-and-its-approval-belong-to-the-head-they-reviewed.md:77

Full review

F1 — Minor, high confidence. The hard-case trace creates rC while rB is still reviewing, allowing two automatic reviews for one pull request. This conflicts with line 101’s promise to coalesce successive pushes and permit only one active automatic review per pull request. Define one policy: supersede or defer the obsolete run before starting the newest, or remove the single-active-run guarantee and explicitly bound concurrent obsolete reviews.

[justinhelmer]

Re-review requested at b6f6680 — the self-contradiction is resolved: the record now states one concurrency policy and the hard-case trace demonstrates it, so a head move while an automatic review is in flight supersedes that review rather than running a second one beside it, and the requester still sees one head-moved update and one verdict update across a burst of pushes. Status stays proposed; acceptance is a person's separate step.

[coreplane-switchboard]

LGTM: The proposal now defines a coherent head-bound re-review lifecycle, including supersedes, ship ownership, and the residual stale-approval risk.

Note

Approved · head b6f6680 · no findings

Full review

No findings; the proposal coherently binds verdicts and approvals to reviewed heads, coalesces push bursts into one final-head review, defers ship-owned transitions correctly, and preserves unchanged-patch carry while documenting the optional check’s residual safety role.

[github-actions]

Auto-approved: coreplane-switchboard[bot] reviewed this PR and posted an LGTM verdict (see its review). This repository opted in through its REVIEW_BOT_LOGIN and REVIEW_BOT_ID variables.