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