Playbook 09 and the hq-cleanup skill: a cleanup reads first, deletes only what the operator approves, and reports what it kept (the operator, 2026-10-16)

2026-10-16 20:01:13 +02:00
parent b29008ad36
commit 222fbe95f4
4 changed files with 90 additions and 1 deletions
@@ -58,6 +58,7 @@ the expensive half.
 | [06](06-writing-a-module.md) | Writing a module | Something that runs today must run on the mesh |
 | [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: prepared context, local development, one review, one check, one delivery |
 | [08](08-small-fixes.md) | Small fixes | One issue in one repository, about an hour of work: one review, one push, one delivery |
+| [09](09-cleanup.md) | Cleanup | Merged branches, stale pull requests, finished worktrees and folders: read first, delete only what the operator approves, report the rest |

 ## The cycle is checked

@@ -0,0 +1,46 @@
+# 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.