feat(skills): add branch-supersede-check

[MCamner]

git diff main...branch is the wrong instrument for the question "does this branch still matter", and it fails silently.

The three-dot form compares against the merge base — the point where the branch forked. It lists everything the branch did since then, whether or not trunk has since acquired the same content by another route: a squash merge, a cherry-pick, someone doing the work again in a different PR. A branch whose work landed months ago produces exactly the same shape of output as one holding something unique. Same file count, same additions, same confident +325 insertions.

Four branches in one day looked unmerged and were not. What settled each was a per-file comparison against trunk as it is now.

What the script does

Labels every file the branch touched:

IDENTICAL       docs/ARCHITECTURE.md
BASE-AHEAD      docs/POSTING_FLOW.md  (main has 6 line(s) the branch lacks)
DIVERGED        .github/workflows/static-site-checks.yml  (+4/-9)
ONLY-ON-BRANCH  skills/command-template-library/SKILL.md

identical 7 · base-ahead 2 · branch-ahead 0 · diverged 2 · only-on-branch 0  (of 11)

It prints the three-dot file count alongside, so the two measurements can be compared in one output.

Building it changed what it says

The first version gave a binary verdict. Run against all four real branches, it answered "has unique content" every time — technically true, and misleading every time, since all four were right to delete.

The classification was correct; the verdict was overconfident. So it now:

• looks up a merged PR for the branch head — squash merging leaves neither ancestry nor identical files, so a squash-merged branch can look entirely unique. Verified: merged PR for this head: #176 merged 2026-08-08 → VERDICT: superseded.
• grades rather than rules — review, leaning superseded — 9 of 11 file(s) are identical to main or behind it.
• states its limit — every non-superseded verdict ends with "This tool compares text, not worth. A DIVERGED file often means the branch is simply older."

SKILL.md carries three real cases where "unique content" was true and deleting was still right, so the next reader calibrates against reality rather than the label.

Placement

skills/ here rather than staying loose in ~/.agents/skills, so it gets version history, shell lint, and the discoverability check added in #182. .claude/skills/branch-supersede-check symlinks to it, and ~/.agents/skills/branch-supersede-check now points at this copy too — one source of truth reachable by both agent tools.

Read-only: never checks out, merges, resets or deletes. The single network call is the PR lookup, skippable with --no-pr.

Verification

shellcheck -S warning — clean
./scripts/check-skills.sh — OK
mq-skills audit — macos-scripts: 8 skill(s), 8 indexed, 8 discoverable
[PASS] Shell lint passed at warning severity (198 files)
[PASS] All selftest checks passed.

Behaviour reproduced against the two real branches it was built from: a squash-merged one classified superseded, and a 7-of-11-identical one classified review, leaning superseded. Error paths checked too — unknown ref exits 2, no argument prints usage.

🤖 Generated with Claude Code

[MCamner]

P1 fixed — and it was worse than the report

Reproduced first. An orphan branch holding a file main has never seen:

=== lonely (91e463c) vs main (ce7573b) ===
  three-dot diff (main...lonely) touches 0 file(s)
  identical 0 · base-ahead 0 · branch-ahead 0 · diverged 0 · only-on-branch 0  (of 0)

VERDICT: superseded — nothing here is missing from main.
EXIT=0

So the tool recommended deleting a branch that shares not one commit with trunk
and carries work trunk does not have. Exactly the class this repo spent the
Pulse series eliminating: comparison failed + empty output ≠ superseded.

Two guards, both added:

• a missing merge base is a lookup error (exit 2), before any report is printed
• the three-dot diff is taken once with its status checked, instead of run
  twice into /dev/null — the count and the loop could not disagree, and any
  other diff failure stops the run rather than emptying it

They are redundant by design: either alone closes the hole. The test proves the
hole is closed, not which line closes it — removing both restores the bug and
step 1 fails.

P2 fixed

gh pr list --state merged --head "$name", filtered by GitHub. gh 2.97.0
supports -H/--head, verified. This also removes the jq expression built by
interpolating a branch name.

One thing the report did not raise, found while testing it: a failed lookup
was indistinguishable from no merged PR exists. That matters more here than
elsewhere — the merged-PR lookup is the evidence a squash merge destroys, so
its absence is what pushes a verdict toward "unique". A failed lookup now says
so and the verdict does not silently lean on it.

Test

tests/branch-supersede-smoke.sh — the script had none, and no row in
tests/manifest.tsv, so it was entirely ungated. Six steps: unrelated
histories, content landed by another route, genuinely unique content, unknown
ref, the lookup shape, the failed lookup.

Verified failable against three planted defects (guards removed, --limit 200
restored, gh failure swallowed) — each caught, tree restored.

Full suite: 85 active tests, shell lint at warning severity over 216 files,
markdownlint clean. Ran the tool for real against
backup/local-main-stray-commit — ONLY-ON-BRANCH hub, verdict review, exit 1.

main merged in; the branch was three PRs behind. Ready for the second review.