post-merge-cleanup skill

Routed skill

Finish an already-merged branch. Proves the branch is contained in the fetched default, classifies leftover artifacts as unique / redundant / superseded, returns to a clean --ff-only default checkout, and deletes the merged local branch — every discard confirmed per item.

How it is used

The orchestrator routes to this skill from an owning command. It is not a direct user entry point.

What it does

The cleanup command routes here after a pull request lands. The skill separates merge proof from local tidying so no generated file, scratch note, stash, or branch is discarded merely because it looks obsolete.

Phases

Fetch the remote default branch and prove the topic commit is contained in it.
Inventory the working tree and stashes, then explain the evidence for each classification.
Ask about every possible removal separately, preserving anything declined or uncertain.
Check out the default branch, verify the checkout, and update it only by fast-forward.
Offer deletion of the merged local branch with Git’s non-forcing safety check.
Report the final checkout and every keep/remove decision.

Exits

A complete run leaves you on a clean, current default branch and may remove the merged local branch. A safe early exit leaves the checkout unchanged and names the evidence or retained item that stopped the transition. Remote branches and stashes are outside this skill’s deletion authority.

Gates

Gate	When	Effect
merge proof	phase 1 compares the topic HEAD with the fetched default ref	work stops if containment cannot be proven from current remote state
item classification	phase 2 inventories tracked changes, untracked files, and stashes	every item receives a reasoned class and any uncertainty receives the most conservative class
explicit removal	phases 3 and 5 offer local cleanup	each artifact and the local branch require their own named confirmation
safe transition	phase 4 returns to the default branch	verifies the checkout and permits only a fast-forward update

Source

Source — plugins/ca/skills/post-merge-cleanup/SKILL.md (v2.18.2)

---
name: post-merge-cleanup
description: Finish an already-merged branch. Proves the branch is contained in the fetched default, classifies leftover artifacts as unique / redundant / superseded, returns to a clean --ff-only default checkout, and deletes the merged local branch — every discard confirmed per item. Routed to by /ca:cleanup.
---

# post-merge-cleanup

The walk back from a merged PR. Routed to by `/ca:cleanup`.

The work has landed on the default branch. What is left is local: the branch you
are standing on, and whatever the run left in the tree. This skill returns you to
a clean, fast-forwarded default checkout without losing anything you have not
explicitly agreed to lose.

**It is ordinary lifecycle work and never needs `/ca:override`.** When it
cannot proceed, it names the gate that stopped it. Issue #308 recorded the
alternative: with no owner for this transition, the routing loop reached for
`/ca:chore`, then for `/ca:override` — a bypass manufactured to cover a
coverage hole.

## Pre-flight

Read this, or STOP and surface the gap — never guess the default-branch name:

- `${CLAUDE_PROJECT_DIR}/.codearbiter/CONTEXT.md` — the default-branch name.

If HEAD is already the default branch, there is no transition to make. Report the
dirty state read-only and exit; branch pruning across *other* branches belongs to
`/ca:standup`.

## Phase 1 — Prove the merge · gate: BLOCK

A branch that looks merged is not merged. Establish it against the network, not
against a stale local ref. This repo squash-merges by default, so SHA-ancestry
alone is the wrong instrument for most landings: it holds for a fast-forward or
a merge-commit landing, but a squash merge writes a new commit with no SHA
lineage back to the branch, and `--is-ancestor` will report non-zero for a
branch that landed cleanly. The gate is **content-containment**, proven by
whichever instrument fits the landing, always reported as a fact:

1. `git fetch` the remote holding the default branch. A fetch that fails STOPs —
   an unfetched comparison proves nothing.
2. Prove containment with two primary instruments plus a fallback, tried in
   order:
   1. **Ancestry** — `git merge-base --is-ancestor HEAD origin/<default>`. Holds
      for a fast-forward or merge-commit landing. If it holds, that is the
      proof: report it and move on.
   2. **Squash-merge proof via the PR record** — if ancestry fails, run
      `gh pr list --head "$(git branch --show-current)" --state merged --json number,state,headRefOid,mergeCommit`.
      A `MERGED` PR whose `headRefOid` equals local `git rev-parse HEAD` proves
      every commit on this branch rode that PR's squash into the default
      branch. Report the PR number, that `headRefOid == HEAD`, the merge
      commit (`mergeCommit.oid` in that JSON), **and** the ancestry check's
      negative result — all as facts, not as a failure. Corroborate with
      `git diff --quiet origin/<default> HEAD` when it happens to hold; a
      **non-empty** diff alongside a valid PR proof is normal (the default
      branch advanced since the merge landed) and is reported as a fact, never
      treated as a failure. The PR-record identity — `MERGED` plus
      `headRefOid == HEAD` — is the load-bearing proof; the diff is
      corroboration only when it happens to be fresh, never a requirement.
   3. **Fallback when `gh` is unavailable or no PR record exists** —
      `git diff --quiet origin/<default> HEAD` (the tree is byte-identical to
      the fetched default) is an acceptable fallback proof. Report it as such.
3. Report whichever instrument held as a fact — the default branch, the fetched
   SHA, and which of the three proofs established containment.

If none of the three hold, STOP exactly as today. Name the un-landed commits
and route to `/ca:pr`; nothing is deleted here.

> Deliberate deviation from issue #586's suggested contract: that suggestion
> required the squash-merge proof's diff to be empty. That requirement
> re-breaks this gate the moment any later PR merges to the default branch —
> the common state, not an edge case. The PR-record identity is what proves
> containment; the diff is corroboration, demoted from requirement to fact.

Gate: the remote is fetched and HEAD is proven contained in the fetched default
branch — by ancestry, by the PR-record squash proof, or by the byte-identical
fallback — or the skill has stopped.

## Phase 2 — Classify the residue · gate: BLOCK

List every dirty tracked change, every untracked file, and every stash reachable
from this branch. Classify each into exactly one of three, and say *why* for each:

- **Redundant** — byte-identical to content already on the default branch, or a
  regenerated build artifact whose generator is committed and rerunnable. Safe to
  remove because removing it loses no information.
- **Superseded** — an earlier form of something the merged PR already landed in a
  better shape. Name what supersedes it.
- **Unique** — anything else. This is the default: an artifact that cannot be
  proven redundant or superseded IS unique. Uncertainty classifies as unique, not
  as redundant.

Present the classification before touching anything. A file whose class you
cannot establish is reported as unique with the reason you could not classify it.

Gate: every dirty, untracked, and stashed artifact carries a class and a stated
reason, with unclassifiable items counted as unique.

## Phase 3 — Resolve the residue · gate: STOP

Per item, in the order Phase 2 listed them. Never batch:

- **Unique** — offer to keep it: `/ca:commit` it on this branch before the
  transition, move it aside, or leave it in place and stop the cleanup. It is
  discarded only if the user explicitly confirms *that item by name*, with the
  Phase 2 reasoning in view.
- **Redundant / superseded** — offer removal, one confirmation each, stating what
  it is and why it is safe. Declining leaves it exactly where it is.

A stash is never dropped here. Stashes are reported with `git stash show` as the
suggested next step, the same report-and-route contract `/ca:standup` holds.

If anything the user chose to keep would block the checkout, STOP and say so
rather than removing it anyway — but distinguish the two causes before naming
the artifact as the blocker:

- **The kept artifact genuinely conflicts** — its content collides with what
  checking out the default branch would need to change or remove. This is the
  user's to resolve, as today.
- **The local default ref lags the fetched one** — git refuses a checkout when
  a locally-modified tracked file differs between HEAD and the target ref, and
  a stale local `<default>` makes that difference larger than reality: content
  the kept artifact never actually touches can still collide with what a
  *current* default branch would carry. That gap is not the user's problem and
  not the kept artifact's fault. It is resolved by Phase 4's fast-forward-first
  step, not by discarding anything here. Issue #586 recorded the observed
  failure mode: a stale local `main` — 513 lines behind on
  `.codearbiter/gate-events.log` alone — made this STOP name a correctly-kept
  38-line artifact as the blocker, which invites exactly the silent discard
  this phase exists to prevent.

Gate: every item is resolved by an explicit per-item decision, and the working
tree is clean enough to check out the default branch — or the skill has stopped
with the blocker named, correctly attributed to a genuine conflict or a stale
local ref.

## Phase 4 — Transition · gate: BLOCK

Only after Phase 3 leaves the tree safe:

1. **Fast-forward the local default ref BEFORE checking it out:**
   `git fetch origin <default>:<default>`. Git refuses a non-fast-forward
   update of a ref that is not currently checked out, so the `--ff-only`
   guarantee is preserved by the instrument itself — this cannot silently
   rewrite the local default ref, only advance it or refuse. This is what
   keeps a stale local default from blocking (or worse, misattributing) the
   checkout below. This step can itself be refused for the same reason a
   checkout can be — `<default>` checked out in another worktree — in which
   case report that as the (correctly attributed) blocker, per Phase 3, and
   stop; do not treat the refusal as license to skip ahead.
2. Check out the default branch, then **verify the checkout actually happened**
   (`git branch --show-current`). A checkout silently fails when another worktree
   holds the branch, and every step after this one would otherwise run against
   the wrong branch.
3. Fast-forward with `--ff-only` (belt over the braces of step 1 — a no-op when
   the pre-checkout fetch already brought the local ref current). A divergence
   means the default branch moved in a way this skill will not reconcile:
   report it and stop. Never a merge commit, never a rebase, never a reset.

Gate: the local default ref was fast-forwarded before the checkout — or the
fast-forward's refusal was itself reported as a fact and the skill stopped —
HEAD is confirmed on the default branch by re-read, and the belt-and-braces
`--ff-only` pull either succeeded (typically a no-op) or was reported as a
refused divergence.

## Phase 5 — Delete the merged local branch · gate: STOP

Offer deletion of the now-merged local branch, with the Phase 1 containment
proof restated. One confirmation, naming the branch.

- `git branch -d` first, always. Never reach for `-D` on the assumption that a
  refusal means `-d` can't handle a squash merge — it often can. `git branch
  -d`'s safety check accepts a branch merged into its **upstream**, not only
  into HEAD: with an upstream still configured and equal to the tip, `-d`
  succeeds (with a warning) even for a squash merge that `--is-ancestor` alone
  would call unmerged. Do not conclude a refusal here means `-D` is required —
  check the reason first.
- **The sanctioned `-D` path.** `-d` typically refuses once the remote branch
  has been auto-deleted and pruned, because there is then no upstream left for
  `-d` to test reachability against. When that happens, `git branch -D` is
  permitted, but ONLY when both hold:
  1. Phase 1's proof, established this run, was the PR-record squash proof
     (`MERGED` and `headRefOid == HEAD`) — not a bare ancestry pass, not a
     stale or assumed proof.
  2. The confirmation restates that Phase-1 proof and explicitly names the
     branch.
  Frame this precisely: `-d`'s safety check tests SHA-reachability, and the
  squash proof has already shown that instrument is the wrong one for this
  repo's merge mode. The PR-record proof plus a named confirmation **replaces**
  the check that `-d` can no longer run — it does not bypass it. Everywhere
  else, `-D` stays forbidden exactly as before: if `-d` refuses and Phase 1's
  proof was anything other than the PR-record squash proof, report both and
  stop.
- The **remote** branch is never touched. If the user wants it gone, that is
  theirs to do or the platform's auto-delete-on-merge to do.

Declining leaves the branch in place. That is a normal outcome, not a failure.

Gate: the branch is deleted only after an explicit confirmation naming it, via
`-d`, or via `-D` restricted to the sanctioned path above with the proof
restated, with the remote untouched.

## Phase 6 — Receipt

One short summary: what landed, what was removed, what was kept, and where HEAD
is now. State declines as declines — a cleanup the user stopped halfway is a
correct outcome reported plainly, not an error.

## Hard rules

- MUST fetch and prove `HEAD` is **contained** in the fetched default branch
  before any deletion — via ancestry, via the PR-record squash proof (`MERGED`
  and `headRefOid == HEAD`), or, without `gh`, via a byte-identical tree diff.
  MUST NOT infer merge state from a `: gone]` upstream alone.
- MUST classify every artifact, and MUST treat anything not provably redundant or
  superseded as unique.
- MUST NOT discard a unique or unclassifiable artifact without an explicit
  confirmation naming that item.
- MUST confirm every removal and the branch deletion individually — no batched or
  implied yes.
- MUST fast-forward the local default ref (`git fetch origin <default>:<default>`)
  before checking it out, or report the fast-forward's own refusal (e.g.
  `<default>` checked out in another worktree) as the blocker and stop. MUST
  re-read the current branch after checkout before acting on it.
- MUST use `--ff-only`, and MUST NOT merge, rebase, or reset to reach the default
  branch.
- MUST use `git branch -d`, and MAY use `-D` ONLY when the Phase-1 squash-merge
  proof held this run and `-d` refused, with that proof restated and the branch
  named in the confirmation. Everywhere else `-D` is forbidden. MUST NOT delete a
  remote branch, force-push, or write to the default branch.
- MUST NOT drop a stash — report and route, as `/ca:standup` does.
- MUST NOT route to `/ca:override` when blocked. Name the gate instead.

View in repo