git-merge-hazards

# Git Merge Hazards Read before merging a PR, merging a stacked PR chain, auditing whether a branch really landed, or merging over red CI. The body below is the verbatim text of the promoted `~/.claude/rules/pr-merge-hazards.md` rule. Three notes that are *not* part of that body: - Two gates below — §1's merged-ness authority order and the whole of §4 — are also reproduced verbatim in the `pr-merge-hazards.md` stub, because they are read *while* the decision is being made. Edit both copies together. - §1 overlaps `git-plugin:deadbranch` Step 1.5 ("Reclassify squash-merged branches"), which carries the same three signals scoped to branch cleanup. - §2 and §3 describe **ad-hoc** chains — PRs whose base is another PR's branch. A stack **registered with GitHub** (`gh stack`) retargets its upper PRs itself on merge, so the auto-close hazard and the manual retarget/rebase ordering do not apply there. See `git-plugin:git-stacked-prs`. - The two encoded recipes cited in §1 and §2 below are the author's own (a `just -g` recipe in `laurigates/dotfiles`, and a sweep script in `laurigates/claude-plugins`), not commands a plugin consumer already has. Read the authority ladder in §1 as the instruction; the recipe is a convenience, and its REVIEW bucket measured ~90% false positives (#2268). Four traps in GitHub's merge machinery, one law: "PR merged" says nothing about *content* — and a red check is not proof of failure. Each: the trap, the 5-second check, the fix. Sibling: `~/.claude/rules/git-hazards.md` (local git). ## 1. `--merged` misses squash-merged branches A squash-merge collapses a branch into one fresh-SHA commit on `main`, so the branch's own commits are never ancestors — `git branch --merged` (and any ancestry check) reports it **unmerged**. "Files identical to main" also fails once `main` drifts the same files. - **Check**, in order of authority: - `gh pr list --state all --head <branch> --json state` → a MERGED PR is **authoritative**. Reach for this first; the git-side checks below are all one-way. - `git cherry main <branch>` → marks a commit `-` when a patch-equivalent commit is already upstream, `+` when it is not. Survives squash **and** cherry-pick, and does not care that `main` drifted. - `git merge-tree --write-tree main <branch>` equals `git rev-parse main^{tree}` → contained. **A match proves containment; a non-match proves nothing.** - **Not immune to drift** (corrected 2026-07): once `main` moves on over the same files, merging an already-merged branch back would re-introduce its older versions, so the trees differ and merge-tree reports **not contained** for work that fully landed. Observed reporting three merged branches as unmerged. Same trap as "files identical to main". Use the PR state or `git cherry` to decide; keep merge-tree only as a positive-containment shortcut. - **Fix**: use the encoded recipe rather than re-deriving: `just -g branch-audit` (in `private_dot_config/just/git.just`) prints MERGED vs REVIEW + a paste-ready delete. - A non-match is "review", **not** proof of unmerged — don't force the count to zero. ## 2. Merging a stacked base auto-CLOSES the child PR When PR B is based on PR A's branch, merging A and deleting its branch auto-closes B (GitHub does **not** retarget it), and a closed PR whose base branch is gone **cannot be reopened**. - **Fix — order matters**: retarget the child **first**, while the base PR is open: 1. `gh pr edit <child> --base main` 2. `gh pr merge <base> --squash --delete-branch` 3. `git rebase --onto origin/main <old-base-tip> <child-branch>` (drops the already-squashed base commits) + `git push --force-with-lease` 4. merge the child. - **If already auto-closed**: the head branch survives — rebase as above, `gh pr create` fresh, comment "Superseded by #new" on the closed one. - **Nothing tells you this happened.** The auto-close is silent: no failed check, no notification, and the PR list just looks one shorter. claude-plugins #2049 sat stranded for a day; a sweep then found 26 dead branches, two carrying work that had **never had a PR opened at all** (so no event ever fired for them either). A scheduled sweep is the only thing that finds this class — an event handler on `pull_request: closed` is too late by construction (the base ref is already deleted, so the reopen window is gone) and is blind to never-PR'd branches. `claude-plugins scripts/check-stranded-work.sh` is the encoded audit; it takes `--repo`, so one run sweeps the portfolio. - **Telling an accident from a decision**: a closed-unmerged PR whose base ref **404s** was auto-closed; one whose base ref is still **alive** was closed by a human (duplicate/superseded). That single check is the discriminator — 11 of those 26 branches were deliberate closes and must not be resurrected. ## 3. Stacked-chain merges: push by SHA, never `HEAD:` — and expect auto-close races Working down a stacked-PR chain (retarget child → merge base → rebase child → force-push → merge, per #2) has several traps of its own (observed 2026-07, claude-plugins #1979→#1987): - **`HEAD:` in a push refspec is a race in a shared checkout.** HEAD is process-global repo state; a coworker session can move it *between two of your Bash calls*. Observed: rebase left HEAD at the child's new tip; by the next call HEAD was `main`'s tip, so `git push --force-with-lease origin HEAD:<child-branch>` overwrote the branch with main. Resolve the tip to an **explicit SHA in the same command that creates it** and push `git push --force-with-lease origin <sha>:refs/heads/<branch>`. - **Brace that variable — `"$sha:<branch>"` is a zsh word-modifier expansion.** Stock zsh (reproduces under `zsh -f`) eats the character after the colon as a history modifier whenever it happens to be one, silently rewriting the refspec the bullet above just told you to use: | Written | zsh actually sends | | |---|---|---| | `"$sha:refs/heads/x"` | `<sha>efs/heads/x` | `:r` | | `"$sha:feat/x"` | `at/x` | `:f`+`:e` | | `"$sha:chore/x"` | `<sha>hore/x` | `:c` | | `"$sha:test/x"` / `release/` / `ci/` / `hotfix/` / `refactor/` | mangled | `:t :r :c :h :r` | | `"$sha:style/x"` | **hard error** `bad substitution` | `:s` | | `"$sha:fix/x"` / `docs/` / `perf/` / `build/` / `main` | correct | not modifiers | Half the conventional-commit prefixes break and half don't, which is why it reads as a baffling one-off instead of a rule. Always `git push --force-with-lease origin "${sha}:refs/heads/<branch>"`. Observed 2026-08 pushing `feat/justfile-pr-triage`: `src refspec <sha>efs/heads/… does not match any` — the error names a ref you never typed, so it looks like a stale SHA rather than a quoting bug. - **Spell the destination `refs/heads/<branch>`, always.** A `<sha>:<branch>` refspec works only when `<branch>` **already exists on the remote**: git has a bare commit object on the left, so there is no ref namespace to infer the destination from, and it refuses rather than guessing — `error: The destination you provided is not a full refname (i.e., starting with "refs/")`. git wraps that message right after `(i.e.,`, so triage by grepping the `not a full refname` fragment, not the whole sentence. The full refname is accepted whether or not the branch exists, so there is no branch state to reason about. It compounds with the brace rule immediately above rather than replacing it: `"$sha:refs/heads/x"` is the `:r` word-modifier row in that table — unbraced, zsh silently sends `<sha>efs/heads/x`. - **An empty-diff force-push auto-closes the PR — and a closed PR whose *head* moved after closing cannot be reopened.** Sibling of #2's base-branch-deleted variant. GitHub saw the branch == main, closed the PR, and refused `gh pr reopen` because the head ref had moved since closing. - **A single mergeability read after a force-push is a race.** GitHub recomputes `mergeable` asynchronously; `gh pr merge` right after a push fails with "not mergeable" on a perfectly clean PR. Poll `gh pr view <n> --json mergeable` until it leaves `UNKNOWN`. - **Waiting for CI races check *registration*, not just completion.** A loop on "zero pending checks" can exit **immediately** after a push/`update-branch`: zero pending is trivially true before the jobs are registered. Observed 2026-07: `state=CLEAN` on a **single** check while three CI jobs had not yet appeared — merging there merges untested. Gate on **both** nothing-pending **and** `--jq 'length'` ≥ the expected check count. Same root cause as the mergeability race above: an async field read once, too early. - **Check** before every force-push: `git log --oneline origin/main..<sha>` — expect *exactly* the child's commits, nothing more, never empty. - **Recovery** when auto-closed: the rebased commits survive in local objects (`git reflog`) — `git push --force-with-lease origin "${sha}:refs/heads/<branch>"`, open a fresh PR from the branch, comment "Superseded by #new" on the closed one. The full refname matters most here: the branch may not exist on the remote yet, and the short form cannot create it. ## 4. A red PR may still be mergeable — `UNSTABLE` is not `BLOCKED` `mergeStateStatus` separates **required** failing checks (`BLOCKED` — merge refused) from merely-present ones (`UNSTABLE` — plain `gh pr merge` works), so `--admin` on an `UNSTABLE` PR takes a privilege you didn't need. Read it first. Merging over red needs **two** checks: `--json files` (config/docs can't break a compile) **and** the same check already failing on `main`. Either alone is a guess — and a stale-green `main` lies, so check `createdAt` (2026-07: a "green" run was 21 days old; main hadn't compiled for three weeks). ## 5. A **negated** closing keyword still closes the issue GitHub matches `close|fixes|resolves|…` + an issue reference without parsing the sentence around it, so the natural way to *disclaim* closure closes the issue. Markdown emphasis between verb and number doesn't break the match either: ``` Does **not** close #162 → GitHub reads `close #162`, and closes it ``` - **Check**: `gh issue view <n> --json closedByPullRequestsReferences` names the closer; a `closedAt` one second after a merge is automation, not a decision. - **Fix**: never let a closing verb precede an issue number you don't mean to close — `Related: #162`, `Unblocks #162`, or `#162 stays open — it needs …`. - **Recovery**: `gh issue reopen` works (nothing was deleted, unlike #2), then comment so the next reader doesn't re-derive it. ### It is not only negation — plain past tense in a follow-ups section does it The rule above reads as "watch out for the word *not*". The trap is wider: **any** closing verb adjacent to a reference matches, including one merely *describing* what already happened, and including a reference wrapped in a **markdown link**. > Observed 2026-08-16 (comfyui-nodes fleet). A PR body's follow-ups section > asked for an issue to be re-opened, describing it as one this bug had > **closed** on a false premise. GitHub matched the closing verb against the > bracketed cross-repo link that followed it and closed the issue on merge — a > line whose entire purpose was to request a re-open. The author had cited this > very rule earlier in the same session. Three amplifiers: - **A bracketed cross-repo link still matches.** A closing verb followed by a markdown-linked `owner/repo#N` is a match, and a naive audit regex like `keyword\s+[\w./-]*#\d+` misses it on the `[` — then reports the body clean. - **A shared fleet body multiplies it.** The same text went into 13 sweep PRs, so 13 merges each targeted the same issue. - **The actor is *you*, not a bot** — the timeline reads `closed by <you>` seconds after the merge. Don't rule out a closing keyword because no bot appears. ### And not only assertion — a keyword you are *quoting* still fires The two forms above are sentences that *mean* something about an issue. The third means nothing about it at all: the keyword appears inside an **example, a fixture, or a regex you are documenting**. GitHub does not care that the line is inside backticks, a code fence, or a sentence whose subject is the audit itself. > Observed 2026-08-17 (FVH `infrastructure` #2213). A PR body's verification > section reported that a closing-keyword scan returned zero hits, and quoted > its two control fixtures inline as evidence. The scan it was reporting on had > genuinely passed — on the *ADR file*. Run against the PR body, the same regex > matched the body's own worked examples, which would have closed an unrelated > issue on merge. Caught only because the scan was re-run against the artefact > about to be published, rather than the one it was describing. Two things generalise: - **Scan the artefact you are about to publish, not the one you were auditing.** A PR body, an issue comment, and a rules file each need their own pass; a clean result on one says nothing about the others. - **Do not reproduce the fixture in prose that ships.** Describe it — "control- tested against a bare reference and a bracketed cross-repo link, both found" — and keep the literal strings in the throwaway file. Documenting the trap is the one context where you are *guaranteed* to type the trap. **Audit the body before merging, with a control.** Scan every PR you are about to merge for a closing verb adjacent to an issue reference, allowing an optional `[` and an optional `owner/repo` between them, and prove the scan works by confirming it finds a reference you *know* is there. A negative from an unvalidated regex is worth nothing — the first audit run in the case above reported the fleet clean. The damage is a **false status report**: 2026-08-05, a PR body written to disclaim closure closed loractl #162 at merge, and the session reported it open for two turns afterward. Like #2, GitHub does this silently — only re-reading issue state from the API catches it.