docs(review): enumerate every child of a base branch before deleting it

[lilyshen0722]

@sam's rule from the threading train (57287), in their words: "a protocol that protects the children you know about isn't a protocol."

What happened

#1109 merged at 18:50:59Z. #1120 had been retargeted to main while the parent ref still lived, and survived with its review history intact. #1128 shared that same base, had not been retargeted, and auto-closed at 18:51:05Z — six seconds later. Same protocol, opposite outcomes, and the only difference was whether someone remembered the PR existed.

The rule

Before deleting a merged parent's branch, run gh pr list --base <branch> and retarget all of them. Worth running even when you're confident, because the failure is silent from the author's side — their PR simply isn't there any more, with no notification that names the cause.

Two riders, which are why this isn't just a checklist item

• A stack's protocol does not cover siblings. Keep-branch reasoning is about children of the PR being merged. A sibling that merely shares the same base is a different relationship, the UI renders the two identically, and the sibling is the one that gets missed.
• Recovery is cheap if you catch it. The head sha stays fetchable: resurrect-ref → reopen → retarget → clean up the temp ref, review history preserved. feat(threading): explicit thread_root_id, with derivation as the fallback #1128 came back that way and merged the same evening at 0a2b69b7, green on Test & Coverage, Tier 1 real-DBs and E2E. Rebuilding is only needed if nobody notices in time.

Cross-referenced to AX entry 41 (a conflicting PR's checks describe a tree that will never exist) and its addendum in #1171 (a stacked PR runs no static analysis until its base is main) — three faces of the same thing, that a PR's rendered state is about a relationship rather than about the code.

Docs-only.

🤖 Generated with Claude Code

[lilyshen0722]

Verified the recovery rider empirically rather than by reasoning, since a checklist that promises recovery is worth only as much as the promise. Measured at ae7ce331, 06:57Z, against the exact PR the entry was written about:

• feat/threading-explicit-root (#1128's head branch) is gone from origin — git ls-remote --heads origin feat/threading-explicit-root returns 0 refs.
• git fetch origin refs/pull/1128/head:refs/tmp/probe still resolves d5b8ef92, matching the PR's recorded headRefOid exactly, and the commit is readable (test(threading): the service-tier arity assertion...).

So "recovery is cheap if caught, since the head stays fetchable" holds, on a real deleted branch, not in principle.

One addition worth making before this merges

The rider is true but the obvious command doesn't demonstrate it. A default clone's fetch refspec does not include pull refs, so a bare git fetch will not surface the head and a reader following this entry can reasonably conclude it's gone.

This workspace happens to have the extra line:

+refs/heads/main:refs/remotes/origin/main
+refs/heads/*:refs/remotes/origin/*
+refs/pull/*/head:refs/remotes/origin/pr/*     <- not present in a default clone

That third line was added here on 2026-08-04; a fresh agent workspace won't have it. My probe worked regardless because it names the source ref explicitly, which is the point: the explicit refspec form is config-independent, and it's the one the entry should print.

Suggested: give the entry the literal recovery command rather than the property.

git fetch origin refs/pull/<N>/head:refs/heads/<restored-branch>

That works in any clone, deleted branch or not. "The head stays fetchable" is accurate and, for someone in a default clone who has just typed git fetch and seen nothing, indistinguishable from wrong.

Nothing here blocks — the entry is correct as written and the enumeration rule is the load-bearing half. This is one line of hardening on the half a reader will reach for while something is already broken.

[lilyshen0722]

Gating the 4-deep checklist stack (#1209 → #1219 → #1172 → #1237). The numbering claim holds; the branch topology does not.

Contiguity: confirmed. At #1237's tip the file has 21 numbered rules, 21 distinct, min 1, max 21 — exactly 1..21, no gaps, no duplicates. Each PR adds exactly one rule against its own base: #1209→18, #1219→19, #1172→20, #1237→21. The rule-18 collision I flagged earlier is resolved; #1172 is rule 20 now.

#1172 is not actually stacked on the base it declares.

base: docs/checklist-rule-19-fail-noisy @ 76578d95   (#1219's head)
head: 074e5689
git merge-base --is-ancestor 76578d95 074e5689  →  false
merge-base is 947b7966

GitHub agrees: mergeStateStatus: DIRTY, mergeable: CONFLICTING. It reproduces locally — git merge-tree gives a both-changed marker on docs/development/review-checklist.md. The PR was retargeted onto #1219's branch but never rebased onto it.

The consequence is a silent content revert, not just a conflict. Rule 19's text at the stack tip is the superseded version:

• docs(review): rule 19 — which way does this guard fail, and who hears it #1219 head (current): "status: 'failed' on AgentEvent has three readers in the whole tree — routes/admin/agentEvents.ts (twice) and scripts/seat-output.ts … failedRetentionHours, default 168h"
• docs(review): rule 21 — a priority claim needs a margin bigger than compose time #1237 tip (stale): "the only reader … in any route or controller is routes/admin/agentEvents.ts (:75, :92) … past failedThreshold (:717)"

Rules 17 and 18 are byte-identical across the stack; only 19 diverges (3,785 vs 3,834 chars). So merging bottom-up lands the corrected rule 19 via #1219, and then #1172/#1237 can revert it if the conflict is resolved "take ours".

That revert would be self-undermining: the corrected text exists because the scoped count ("only reader in any route or controller") was true-but-one-careless-quotation from false, which is the thing rule 19 is about. The stale version is the claim its own successor warns against.

Suggested: rebase #1172 onto 76578d95 and #1237 onto the result, so contiguity is a git fact rather than a coincidence of trees. Worth noting the recursion — #1172 is rule 20, "enumerate every open PR whose base is that branch," and the stack broke one link above it in exactly that shape.

Not verified: I did not check the other stacked branches for the same retarget-without-rebase pattern beyond these four, and I have not confirmed how the conflict would actually resolve — "take ours" is the failure mode I'm flagging, not an observed outcome.

[lilyshen0722]

Re-measured at 12:36:00Z, ~13 minutes after the restack was reported as landed. It is not on the remote.

#1209  CLEAN/MERGEABLE     base=main                              head=17d7580a
#1219  UNSTABLE/MERGEABLE  base=docs/checklist-rule-18-source-...  head=76578d95
#1172  DIRTY/CONFLICTING   base=docs/checklist-rule-19-fail-noisy head=074e5689
#1237  CLEAN/MERGEABLE     base=docs/enumerate-children-...       head=03f90e8c

#1172 head is unchanged from my earlier read (074e5689, no force-push), and git merge-base --is-ancestor 76578d95 074e5689 is still false. git ls-remote shows only four matching branches — there is no restacked branch pushed under another name, so this isn't me reading the wrong ref.

The commit graph shows precisely where the two diverge:

947b7966  docs(review): make rule 19's audience example checkable   ← shared merge-base
├─ #1219: 19d41910  three readers, unqualified — receipt expires at 168h
│         76578d95  rule 19 cites the scar, in the first person
└─ #1172: 074e5689  rule 20 — enumerate every child of a base branch

So #1172 branched from #1219 before the two rule-19 correction commits and never picked them up. That is the whole mechanism behind the stale rule-19 text at the stack tip I flagged above — not a mysterious conflict, just two commits missing.

Most likely reading: the rebase was done locally and not pushed. Nothing here contradicts it having been done — only that the remote doesn't have it.

Still needed: rebase #1172 onto 76578d95 and push, then #1237 onto the result. Two commits (19d41910, 76578d95) are what #1172 must gain for the rule-19 divergence to close.

Not verified: I can't see anyone's local state, so I'm reporting the remote only. If the push landed after 12:36:00Z this comment is stale — the ancestry check is the one command that settles it either way.

[lilyshen0722]

Gate — sprint-review, re-gating at 64ac1c84 (previous gate bound to ae7ce331). Base is docs/checklist-rule-19-fail-noisy, not main — 2 lines against its parent, 19 against main.

PASS on content. Rule 20's incident record is accurate to the second. I pulled the timeline rather than trusting the narrative, because merged_at/closed_at on a reopened PR show only the final close and cannot confirm an earlier auto-close:

#1109  merged            2026-08-22T18:50:59Z
#1128  closed            2026-08-22T18:51:05Z   ← six seconds later ✓
#1128  reopened          2026-08-22T18:55:00Z
#1128  base_ref_changed  2026-08-22T18:55:09Z
#1128  merged            2026-08-22T21:05:30Z   → 0a2b69b7 ✓

Every number in the citation lands, including the merge commit. The reopen-then-retarget recovery is visible as two adjacent events, exactly as described.

The refspec caveat is real and worth having kept. This workspace resolves refs/pull/* only because someone added it:

+refs/heads/main:refs/remotes/origin/main
+refs/heads/*:refs/remotes/origin/*
+refs/pull/*/head:refs/remotes/origin/pr/*     ← not default

A default clone has the first two. So "the head stays fetchable" really would read as false to someone in a fresh checkout running a bare git fetch, which is the one moment anyone opens this rule. Naming the explicit refspec is what makes the line usable under stress.

---

This PR is an instance of the hazard it documents

The stack is three deep and every link is a PR base:

#1209  base=main                                head=docs/checklist-rule-18-source-assertions   OPEN
#1219  base=docs/checklist-rule-18-…            head=docs/checklist-rule-19-fail-noisy          OPEN
#1172  base=docs/checklist-rule-19-fail-noisy   head=docs/enumerate-children-before-deleting…   OPEN

When #1219 merges and its branch is deleted, #1172 auto-closes — the precise failure this rule exists to prevent, with this rule inside it. I ran the rule's own command against its own base:

$ gh pr list --base docs/checklist-rule-19-fail-noisy --state open
#1172  docs(review): enumerate every child of a base branch before deleting it

One child, and it is this PR. So the mitigation is concrete: land bottom-up (#1209 → #1219 → #1172), and retarget each survivor while its parent ref is still alive. Retarget #1172 to main before #1219's branch is deleted, not after. Rule 20's own rider — a stack's protocol does not cover siblings — is the reason to run the command anyway rather than rely on remembering this comment.

The stacked base also costs you eight checks

gh pr checks on the two ends of the stack:

	#1172 (stacked base)	#1209 (base=main)
checks	4	11

Missing on #1172: Analyze (actions), Analyze (javascript-typescript), Analyze (python), CodeQL, Source changed ⇒ version bumped, Stale-base merge guard, Release Branch Guard. Four green ticks read as a passing PR and are a quarter of the gate.

That is not a new finding — rule 20's own closing sentence points at it ("a stacked PR runs no static analysis at all until its base is main") — but it is worth stating that the condition is live on this PR right now, and that it resolves the moment the retarget above happens. The retarget is therefore doing two jobs, and both of them argue for doing it early rather than at merge time.

---

No changes requested to the text. Retarget to main once #1219 lands, confirm the check count goes to 11, then press.