Cleanup

Tidy up after shipped work — remove .minerva/worktrees/NNN-slug/ directories whose branches have been merged into the default branch, and prune the corresponding local branches. Idempotent: safe to run on a clean tree (reports zero items removed).

Usage

• minerva:cleanup — sweep all merged worktrees + branches in the current repo
• minerva:cleanup 005-add-payments — clean up only the named work unit (slug or path)
• minerva:cleanup --dry-run — list what would be removed without removing anything

Target resolution

Same pattern used by minerva:work, minerva:replan, minerva:promote, minerva:review, minerva:ship. Keep all six blocks in sync if you edit one. For minerva:cleanup specifically, the default mode (no argument) is "all merged worktrees" rather than a single target — but resolution rules apply when an argument is passed.

1. Explicit argument (slug or path) → operate on just that work unit. Check both .minerva/work/<NNN-slug>/ and .minerva/worktrees/<NNN-slug>/. Required: the corresponding branch must be merged into default (see Merge detection).
2. No argument → scan all .minerva/worktrees/NNN-*/ directories and check each branch's merge state.
3. Non-git repo → report "not a git repo, nothing to clean up" and stop.

Pre-flight checks

Bail with a clear message on any failure:

1. Git repo. git rev-parse --is-inside-work-tree returns true.
2. gh CLI available (optional but preferred). Falls back to local-only merge detection if gh is missing or unauthenticated.
3. Not currently inside a worktree being cleaned. If invoked from inside .minerva/worktrees/NNN-slug/, that worktree cannot be removed while it's the current working tree. Report and ask the user to cd out (back to the main repo root) and re-run. Cleanup always operates from the parent repo — its job is to remove worktrees, so it must never be running inside one. (No lifecycle skill makes a worktree its working directory: the others address worktrees by .minerva/worktrees/NNN-slug/-prefixed paths, while cleanup removes them outright.)

Default-branch detection

Resolve once at the start:

1. git symbolic-ref refs/remotes/origin/HEAD → parse refs/remotes/origin/<name>.
2. Fall back to main, then master.

Use the resolved value for all merge checks.

Merge detection per worktree

For each .minerva/worktrees/NNN-slug/ candidate, determine if its branch (NNN-slug by convention) has been merged into the default branch:

1. Branch exists? git rev-parse --verify NNN-slug — if the branch is already gone (was deleted upstream and locally), the worktree is orphaned and can be removed.
2. Merged via PR (preferred) — gh pr list --head NNN-slug --state merged --json number,mergedAt --limit 1. If a merged PR exists, the work is shipped.
3. Merged locally — git branch --merged <default> | grep -q "^[* ] NNN-slug$". Catches the case where the branch was merged locally or where gh isn't available.
4. Neither — branch is not merged. Skip. Do not remove an unmerged worktree (the user's in-progress work would be lost).

Report each candidate's state. For --dry-run, stop here.

Confirmation gate

Before removing anything, present the list:

Will remove:
  .minerva/worktrees/005-add-payments/   (branch 005-add-payments, merged via PR #42 on 2026-05-12)
  .minerva/worktrees/006-add-ship-skill/ (branch 006-add-ship-skill, merged via PR #45 on 2026-05-15)
Will skip:
  .minerva/worktrees/007-add-cleanup/    (branch 007-add-cleanup, NOT merged — unmerged work, leaving alone)

Ask:

"Remove these worktrees and prune the matching local branches? [y/N]"

Default is no — destructive operations require explicit yes. The user can also batch ("yes, all" / "just the first two" / "skip 006").

Skip this gate when --dry-run is set (nothing destructive happens) or when the user invokes with an explicit single-unit argument and says --yes (e.g. minerva:cleanup 005-add-payments --yes).

Removal

For each confirmed worktree:

1. git worktree remove .minerva/worktrees/<NNN-slug> — if this fails because the worktree has uncommitted changes, surface the error and skip (do not force-remove without explicit user direction; uncommitted changes in a "merged" worktree are a red flag worth surfacing).
2. git branch -d <NNN-slug> — uses -d (safe delete), not -D (force). If -d refuses because git thinks the branch isn't merged (rare after PR merge — usually a squash-merge artifact), fall back to git branch -D <NNN-slug> only if the merged-PR check in step 2 of Merge detection passed. Squash-merges leave a different commit hash on default, so local git branch -d is conservative and needs an override.
3. git worktree prune — cleans up any stale worktree metadata.

After all removals: git worktree list to show the final state.

Final report

Worktrees removed:     N (<list>)
Branches pruned:       N (<list>)
Skipped (unmerged):    N (<list with branch names>)
Skipped (uncommitted): N (<list — needs manual review>)
Remaining worktrees:   N (<list>)

If any worktrees were skipped due to uncommitted changes, recommend the user inspect each (cd .minerva/worktrees/<slug>; git status) and decide whether the changes are valuable.

Idempotency

Cleanup is stateless. Re-running on a fresh tree finds zero candidates and reports zero removed. Running mid-CI for a branch with an auto-merge pending will correctly skip that worktree (PR is OPEN, not MERGED).

If a user manually removed a worktree directory without running git worktree remove, the next minerva:cleanup call will see stale worktree metadata; git worktree prune at the end of the run handles this.

Out of scope

• Removing the work-unit's .minerva/work/NNN-slug/ directory from main. The docs already moved into the worktree at minerva:work time and were merged into main via the PR; the canonical record lives at .minerva/work/NNN-slug/ post-merge. cleanup only removes the worktree, not the merged docs.
• Removing knowledge files. .minerva/knowledge/ entries are permanent by design.
• Force-removing unmerged work. Always requires explicit user override; cleanup is conservative by default.
• Pruning remote branches. GitHub usually auto-deletes the source branch after merge if the repo is configured for it. Local prune handles the local side; remote prune is git fetch --prune and not part of this skill.