hq/00-META/process/09-cleanup.md

Playbook 09 — Cleanup

Trigger. The operator asks for a cleanup, or the forge and the working copies have gathered what nobody uses: merged branches, stale pull requests, worktrees and folders of finished work.

Who runs it. A session on the operator's word, with the operator deciding every deletion. Agents read and propose; a deletion is the operator's act or is done on the operator's word for the list it was shown.

The aim

Remove what is provably done, and nothing else. A cleanup that deletes one piece of unfinished work costs more than every stale branch it removed. So every item is shown with its evidence, and anything not provably safe is reported and left.

Steps

1. Take stock, reading only. One agent on the smaller model reads, changing nothing:
   • the forge: every repository, every branch as git refs (the branch list tool misses some, issue 949), every open pull request with its head, title and last update;
   • each working copy on the machine: its worktrees, local branches, stashes, and the folders beside the clones, with size and newest file. It writes one report with each item, its class and its evidence, and a list of the tools it lacked.
2. Classify each item, by evidence, never by name or age alone:
   • Safe — a forge branch whose tip is contained in its repository's default branch, with no open pull request, not protected and not a long-lived branch the mesh treats as a trunk; a worktree that is clean, whose branch is contained in the remote default branch, untouched for two hours and not in another session's working folder; a local branch contained in the remote default branch.
   • Likely safe, not proven — a branch whose every commit is patch-equal to one on the default branch (the forge lands some commits under new hashes): listed, deleted only on the operator's word for it.
   • Kept — unmerged commits, a dirty worktree, a stash, an open pull request, a protected or trunk-like branch, a repository of another owner, another session's worktree.
   • Unknown — a folder or file outside git: described, never opened where a secret may be, left. Stale open pull requests (no update for three days) are reported with their author's issue, never closed.
3. Ask the operator with the counts per class and the report's place. One question: delete the safe items as listed? The likely-safe and unknown items are separate questions, item by item when few.
4. Delete only the approved list, each with the command that refuses an unsafe case (a worktree removal that refuses a dirty one, a branch deletion that refuses an unmerged one). A refusal is reported, never forced.
5. Report: what was cleaned, what was kept and why, what was unknown, what the operator kept, and the missing tools, each opened as an issue (issue-tracker.open) or added to an existing one.

How it is checked

• The report names, for every deleted item, the evidence it was safe (contained, clean, no pull request).
• Nothing classed Kept or Unknown is deleted without the operator's word for that item.
• A cleanup's missing tools are issues, not notes in a session.