Stacked PR order

When feat/B depends on feat/A, base PR B on branch A. Three things go wrong, in this order of likelihood.

1. Retarget downstream PRs to main BEFORE merging the parent

gh pr merge A --delete-branch closes any PR whose base was branch A. Deleting a head branch closes the PRs pointed at it, and that is not reversible by re-merging.

gh pr edit B --base main     # first
gh pr merge A --admin --squash --delete-branch   # then

Recovery if you forget: push the parent SHA back to re-create the branch, gh pr reopen B, gh pr edit B --base main.

Before deleting any remote branch, check for an open PR pointed at it.

1a. A stacked child gets no real CI until it targets main

ci.yml runs on pull_request: branches: [main], as do docs-lint, go-toolchain, version-fallback, ci-docs and the PR-time agent attribution check. A PR based on another feature branch gets only the workflows without that filter — in practice review-gate; test, lint, apidiff and govulncheck never run on it. A green check list on a stacked PR is therefore not evidence about its Go code.

• Say so in the PR body, and lean on the full local presubmit sweep until it is retargeted.
• After gh pr edit <child> --base main, wait for the real CI run to conclude (gh run list --branch <b>) before merging the child — the same check as for --admin merges below.

2. Rebase the downstream onto new main after each parent lands

git rebase --onto origin/main <old-parent-sha>

The --onto form is the point: the parent landed as a squash, so its commits are not ancestors of main and a plain rebase replays them on top of their own squashed copy. You get conflicts against your own change.

git push --force-with-lease on your own branch is normal here. A preceding git fetch disarms it — it compares against the remote-tracking ref the fetch just updated, so it will happily overwrite someone else's push. Use the explicit form: --force-with-lease=<ref>:<sha>.

3. The CHANGELOG duplication

A base-update on a branch stacked on a release-promotion PR duplicates the version heading with no conflict. See the changelog-bullet skill — it is the same hazard and the check is git diff <base>...HEAD -- CHANGELOG.md.

Reading merge state

"No checks reported" means the PR is DIRTY, not that CI is broken. GitHub cannot compute a merge commit for a conflicting PR, so pull_request workflows never queue at all.

gh pr view <N> --json mergeStateStatus

CLEAN with zero failed checks is not enough on a PR that touches Go. ci-docs.yml's no-op jobs reuse the required check names, so confirm that the real CI run concluded success (gh run list --branch <b>) before an --admin merge (#1271).

Straight after a push it is just registration lag — wait 30s before concluding anything. main moves faster than a full CI cycle, so a green PR can flip back to BEHIND before you look; do not chase it with repeated rebases.

Proving a branch is already in main before deleting it

Squash-merging means a merged branch is not an ancestor of main, so git branch -d refuses it and merge-base --is-ancestor says "unmerged". Cheapest first:

1. gh pr view N --json headRefOid,mergeCommit — if the branch tip still equals headRefOid and the merge commit is an ancestor of main, the whole branch was inside the merged diff.
2. Subject match + git cherry, which can only ever corroborate.
3. For a still-unmatched commit, a two-dot diff scoped to exactly the files that commit touched. Both unscoped forms are wrong: plain two-dot is drowned by everything main gained since, and three-dot (merge-base..branch) reports what the branch added, which is true whether or not main later took it.

Merging

gh pr merge <N> --admin --squash --delete-branch is the maintainer path for the rebase-then-merge cascade. Never merge unverified CI — confirm mergeStateStatus: CLEAN and zero failed checks first. --admin is not a way to skip review on a contributor PR.

If --delete-branch fails with "'main' is already used by worktree", the merge still succeeded — only the local checkout step failed. Verify with gh pr view <N> --json state and delete the branch with git push origin --delete <branch>.