docs(worktrees): triage a PR that won't merge, and how to resolve safely

[wshallwshall]

Written from what actually cost time today across several parallel sessions. Docs-only, one file, +45/−0.

Why

Four mergeStateStatus values all read as "can't merge" and three need different fixes:

state	fix
BEHIND	rebase + --force-with-lease — mechanical
DIRTY	resolve hunks by hand — not a rebase
BLOCKED	usually wait
UNKNOWN	re-query; not a state to act on

BLOCKED is the trap. Right after a push every required check is pending and the PR reads BLOCKED — indistinguishable from genuinely failing. The rule added here is to count failures in statusCheckRollup first: zero failures + pending checks means wait, not investigate.

Also records something not visible in the UI: armed auto-merge does not update a BEHIND branch in this repo. Landing PR A puts PR B behind, and B then sits armed and stalled until somebody rebases it, while the UI still shows auto-merge enabled. Observed repeatedly today — every stacked pair needed a manual rebase after the first landed.

The half with teeth

docs/BACKLOG.md and CHANGELOG.md are single large append-target files, so they conflict most — and --ours / --theirs both produce a file that passes every check while silently dropping someone's work. No gate catches it, because the result is well-formed.

The worked example is real, from today: two PRs each added a ### Changed block under [Unreleased]. The union was correct; --ours would have dropped two already-published breaking-change notices, --theirs would have dropped the incoming one. Both would have merged green.

Closes with a find-and-replace warning contributed by the session that hit that conflict: re-verify a sweep after resolving, not just after the original edit — conflict fixup is exactly when a sweep gets re-run carelessly. Renumbering 252 → 316 across CHANGELOG.md turns cp1252 into cp1316, in a file nobody re-reads. Scope replacements to anchored forms (BACKLOG #252, ## 252.), never the bare number.

Verification

ledger_check.py     → no blocks
scan_forbidden.py   → clean

No code, no ledger number, no behaviour change. Does not touch docs/BACKLOG.md — deliberately, since another session is mid-resolution in that file.

🤖 Generated with Claude Code