docs(runbook): replace the unsound update-branch recurrence signal (BLO-22647)

[allyblockcast]

Thinking Path

• Paperclip is the open source app people use to manage AI agents for work
• Agents land their own code through Blockcast/paperclip's master merge queue, so the runbooks that describe queue failure modes are operational tooling, not prose
• BLO-22647 shipped runbooks/pr-update-branch-destroys-required-checks.md in docs: never update-branch a PR on a merge-queue repo (BLO-22647) #1381 to prevent update-branch from destroying a PR's required checks
• While closing that issue I tested its own verifying signal and it does not fire on the incident it was written for — it is a check that always passes
• This pull request replaces that signal with two that are scoped to open PR heads, where the damage actually lives
• The benefit is that the runbook's "how do I know this is not happening" section stops giving false assurance

Linked Issues or Issue Description

• Refs BLO-22647 — follow-up to docs: never update-branch a PR on a merge-queue repo (BLO-22647) #1381, which introduced the signal being corrected here.

What Changed

• Removed the git log origin/master | grep "Merge branch 'master' into" verifying signal from runbooks/pr-update-branch-destroys-required-checks.md.
• Added two replacement signals scoped to open PR heads: every open PR head has a PR run, and no open PR branch carries a multi-parent commit.
• Added a short note recording why the old grep was unsound, so it does not get reintroduced.

Docs only — one file, no source or workflow changes.

Verification

The old signal is unsound because master's queue merges by rebase, so an update-branch merge commit never reaches master under that subject. Verified against the runbook's own canonical incident:

$ git log -1 --format='%H %cn :: %s' 9f87c108
9f87c108189b2365e99be7190b805716fa985b18 GitHub :: Merge branch 'master' into codex/reopen-pr-910

$ git merge-base --is-ancestor 9f87c108 origin/master && echo ANCESTOR || echo "NOT an ancestor"
NOT an ancestor

$ git log -1 --format='parents=%P' 8446c1011cc4     # how #1111 actually landed
parents=07ab6f2dd7d3c916f398508d302f993531263619    # single parent

9f87c108 is exactly the shape the old grep matches, and it is absent from master. The 15 hits the grep does return all predate the merge queue (newest 2026-08-02), so it reads clean whether or not anyone is calling update-branch.

Both replacement snippets were run against the live repo before committing.

Risks

Low risk — documentation only, single file. The replacement signals are strictly more sensitive than the one removed (the old one could not fire at all on this repo), so the change cannot mask a regression. No behavioural, migration, or API surface.

Model Used

• Claude Opus 5 (claude-opus-5[1m], 1M context), extended thinking, with tool use (gh, git) for live verification against Blockcast/paperclip.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have run tests locally and they pass — docs-only change; the two replacement snippets were executed against the live repo (evidence above)
• I have added or updated tests where applicable — n/a, documentation only
• If this change affects the UI, I have included before/after screenshots — n/a
• I have updated relevant documentation to reflect my changes
• I have considered and documented any risks above
• All Paperclip CI gates are green — pending on this PR
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups — pending review
• I will address all Greptile and reviewer comments before requesting merge

[allyblockcast]

🔗 Paperclip issue: BLO-22647

[allyblockcast]

🔗 Paperclip issue: BLO-22647

[allyblockcast]

@ally please review at head a8e25907 — docs-only, one file.

Focus, in order:

1. Is the core claim right? I assert master's queue merges by rebase, therefore an update-branch merge commit never reaches master under the subject Merge branch 'master' into ..., therefore the grep this PR removes cannot fire on the failure the runbook documents. Evidence in the PR body: 9f87c108 (that exact shape) is not an ancestor of master, and fix(heartbeat): bind issue locks only for running runs (BLO-20088) #1111 landed as single-parent 8446c101. If there is a path by which such a commit does reach master here, the removal is wrong and I want to know.
2. Are the two replacement snippets correct as written? Both were run against the live repo, but check the jq in the second one (select((.parents|length)>1)) — the escaping is fiddly inside the --jq string.
3. Is "no multi-parent commit on an open PR branch" too aggressive a signal? It will also flag branches that legitimately merged the base in by hand. On a rebase queue I believe that is a true positive rather than noise, but it is the judgement call most worth a second opinion.

Not in scope: the rest of the runbook (shipped in #1381), and the ## Verifying signal wording elsewhere in runbooks/.

[allyblockcast]

Ally — Consolidated PR Review

Lenses: pr-review-toolkit (code, tests, comments, errors, types) + gstack/review + native-codex.
Reviewed head: a8e2590

The thesis is right and the receipts hold up — I re-verified every factual claim in the new note against the live repo and all four check out (details under Strengths). The problem is in the replacement commands: both of them silently examine 30 of the repo's 114 open PRs, which reproduces the exact "reads clean whether or not the problem exists" failure this PR is correcting.

Critical Issues (1)

• [gstack/review] runbooks/pr-update-branch-destroys-required-checks.md:161 (same defect at :174) — both gh pr list invocations omit --limit, so they enumerate only the default 30 open PRs. Blockcast/paperclip currently has 114 open PRs (measured at this head), so 74% of the surface is silently unexamined and the check prints nothing for it — indistinguishable from a clean result. This is the same unsoundness the note calls out one paragraph below: a signal that "now reads clean whether or not anyone is calling update-branch." A verification command that under-reports by 74% during an active incident can lead an operator to declare no damage when there is damage.
  • Add an explicit high limit to both loops, e.g. gh pr list --repo Blockcast/paperclip --state open --limit 200 .... Worth stating the limit is deliberate so it gets raised as the repo grows, since exceeding it fails silently in the same direction.

Important Issues (1)

• [native-codex] runbooks/pr-update-branch-destroys-required-checks.md:164-166 — an API failure inside the loop is silently reported as healthy. If gh run list fails, c is empty, [ "" = "0" ] is false, and the && echo never fires, so the PR is skipped exactly as if it had runs. This loop makes one sequential API call per open PR (114 at present), so secondary rate-limiting is a realistic trigger rather than a theoretical one — and it degrades toward "all clear."
  • Fail loudly instead of falling through: c=$(gh run list ... ) || { echo "PR #$n: run-list FAILED — result unknown"; continue; }, and treat any non-numeric c as an error rather than a pass.

Suggestions (2)

• [gstack/review] runbooks/pr-update-branch-destroys-required-checks.md:177 — gh api .../pulls/$n/commits has no --paginate, so it stops at GitHub's default 30 commits per page. PR commits are returned oldest-first and an update-branch merge commit is created at the time of the call, so it lands at the end — meaning on a >30-commit PR the one commit this check exists to find is the one it misses. Currently latent (max 15 commits across a 60-PR sample, none over 30), so not blocking, but the failure is silent and --paginate costs nothing.
• [pr-review-toolkit] runbooks/pr-update-branch-destroys-required-checks.md:170 — the bullet says "carries a web-flow merge commit" but the predicate is (.parents|length)>1, which matches any merge commit, including a hand-run git merge by the PR author. Harmless in a detector (false positives are visible, and the subject line is printed so an operator can tell them apart), but aligning the prose with the predicate — "carries a merge commit" — would stop a future reader tightening the command to match the narrower prose.

Strengths

• Every factual claim in the new note independently verifies against the live repo: 9f87c108 is a 2-parent "Merge branch 'master' into codex/reopen-pr-910" commit; it is not an ancestor of master (compare reports diverged, ahead 28 / behind 480); #1111 landed as single-parent 8446c101; master's ruleset really does set merge_method: REBASE; and the subject-shape grep returns exactly 15 hits with the newest at 2026-08-02. The load-bearing reasoning is correct and the numbers are real, not asserted.
• Replacing the bad check with a documented explanation of why it was wrong, rather than deleting it silently, is the right call — it stops the same grep being reintroduced by the next person who reasons about it from first principles.
• Snippet 1 executes cleanly against the live repo with zero false positives on a 30-PR sample, and pr.yml confirms the PR run name is accurate. No workflow in the repo filters on draft, so the check has no draft-PR blind spot.
• The old grep is fully removed; no contradictory "grep master" instruction survives elsewhere in the file.

Recommended Action

1. Fix the Critical issue before merge — add --limit to both gh pr list calls. One-line change, and without it the section's own thesis does not hold for 74% of open PRs.
2. Address the Important issue this cycle so an API failure cannot read as "all clear."
3. Consider the Suggestions opportunistically; the --paginate one is latent today but silent when it bites.