ai-git-cleanup

ai-git-cleanup — remove finished local work in one pass

Say a cleanup phrase and the pass runs itself. It deletes only work that is finished — worktrees whose branch is merged into the local main, those merged branches, and the branches a squash-merged pull request left behind (their content provably already in origin/main) — and it never asks a question and never takes a name. Anything unfinished, unprovable, or detached is left exactly where it is. Run the steps in order, from the primary checkout, and report what each one did.

The pass

1. Remove the dead worktrees. The loop walks the session worktrees only — the primary checkout is never a candidate, since git worktree remove <repo> refuses it as a main working tree (and the pass leaves the tree you are standing in alone). For each worktree, read two facts before touching it: whether its HEAD is on a branch (git -C "<path>" symbolic-ref -q HEAD) and what uncommitted content it holds, ignored files included (git -C "<path>" status --porcelain --ignored --untracked-files=normal — the option is required: a status.showUntrackedFiles=no in the repository or the global config makes the bare command print nothing at all, so the read must force the listing itself; normal keeps a wholly ignored directory collapsed to one !! dir/ line, so the report stays bounded and matches the list's dir/ entries literally). Remove it with git worktree remove -- "<path>" only when the HEAD check names a branch that is already merged into the local main, the status read printed no warning, and every status entry is either absent or an ignored path on the regenerable list below. Otherwise skip it and report it kept with the reason:
   • No branch (detached HEAD). git worktree remove exits 0 on a clean detached worktree and the commits it holds become unreachable from every ref, so the pass never removes one: report it kept as "detached, no branch to prove".
   • Uncommitted content that is not regenerable. Tracked and untracked content always keeps the worktree, and so does any ignored path outside the list below — the removal is never forced, and git destroys ignored content silently (a .env, ignored screenshots). Report it kept and say what the status listed.
   • Unreadable status. git status exits 0 while warning on stderr when it cannot read a subdirectory or a path, so a read that warned is not a clean worktree: keep it and report the warning. The doubt is resolved by keeping, never by removing what the read did not see.
   • Ignored content that is all regenerable. Two groups, and nothing else: the paths this framework rebuilds — node_modules/, dist/, coverage/, .stryker-tmp/, reports/, .ai-engineering/receipts/, .ai-engineering/cache/, .ai-engineering/workflow/playwright/ — plus the system and editor noise this repository already ignores in .gitignore: *.bun-build, .claude/reviews/, and *.DS_Store (macOS writes a .DS_Store into every directory a Finder window or an app touches, so a merged worktree whose only ignored content is one must still be removed). They are build, runtime, and machine output, never data, so they do not keep a worktree: remove it and name every ignored path dropped. The ceiling is that list — it is exactly what this framework regenerates and what the repository ignores as noise, so anything else ignored is treated as data and keeps the worktree. A match is anchored to the worktree root, never a substring or a bare name: the printed path must be the entry itself, or sit inside a listed directory, so a listed directory is taken whole (dist/ covers dist/out.js, and node_modules/ covers everything under it). A lookalike is not the entry: packages/x/dist/out.js is not dist/, and reports-archive/ is not reports/. The two *-prefixed entries are the exception to the whole-path rule — they are suffix patterns matched against the path's last component at any depth, so *.DS_Store matches sub/.DS_Store and *.bun-build matches app.bun-build. The read collapses a wholly ignored directory to one !! dir/ line, so the report names the directories it drops; the ceiling is that a listed directory goes whole — a hand-written file inside dist/ is dropped with it, unlisted, and only the paths git prints are ever seen. Never force a removal.
2. Prune the stale ones. Run git worktree prune to drop registrations whose directory is already gone. It removes no live worktree.
3. Delete the merged branches (needs git ≥ 2.56.0). Run git branch --delete-merged refs/heads/main — it deletes only branches whose upstream is the local main and that are fully merged into it, and never the branch checked out here. The option exists only from git 2.56.0: on any older git it fails with an unknown option error, and that is not a pass failure — steps 1 and 2 have already run — so report it and continue to step 4 for every merged branch.
4. Fall back for a merged branch without that upstream. List the candidates with git branch --merged main, then drop the current branch and any branch checked out in another worktree (the lines decorated * or +) and read each remaining name without its decoration. Delete each with git branch -d -- "<branch>". The name goes in as one quoted argument that is data, never re-typed into a shell line: a branch name may legally carry metacharacters ($(…), ;, |, spaces), and an unquoted interpolation executes them. -- ends the options, so a name like -r cannot be read as a flag. A refusal is a keep, and it is never retried: -d tests the branch against its own upstream, so a branch merged into main whose upstream points elsewhere (a lagging origin/main, a refs/heads/behind) is refused — report that branch kept and name the upstream mismatch as the reason.