docs(todo): add --archive-done task for todo-cleanup.el

1 files changed, 11 insertions, 0 deletions

diff --git a/todo.org b/todo.org
index dfc748f..5ade938 100644
--- a/todo.org
+++ b/todo.org
@@ -1745,6 +1745,17 @@ Companion to =make doctor= (single-machine scope, checks =~/.claude/=). =audit=
 
 =doctor= currently has a clean meaning: "is this machine's =~/.claude/= consistent with rulesets?" Mixing in cross-project =.ai/= drift muddies the exit code. Keep them separate; a future =make all-checks= can wrap both.
 
+** TODO [#B] Add =--archive-done= mode to =.ai/scripts/todo-cleanup.el=
+
+Opt-in mode that moves every level-2 subtree whose TODO state is DONE or CANCELLED out of the "Open Work" section and into the "Resolved" section of the same org file, subtree intact.
+
+- *Section matching.* Key on a top-level heading containing "Open Work" and one containing "Resolved" — that pairing is the only naming consistent across projects (=Work Open Work= / =Work Resolved= here; bare =Open Work= / =Resolved= elsewhere). Require exactly one match for each; otherwise skip with a clear message, no crash.
+- *Modes.* =--check= previews and writes nothing, same as the existing hygiene pass. Idempotent. Not run by default in the wrap-up flow — archiving is consequential, so it stays opt-in: =emacs --batch -q -l todo-cleanup.el --archive-done FILE=.
+- *Edge cases.* Source or target section missing; subtree at EOF; nested DONE subtree under an open parent stays put (only level-2 entries move); nothing to move → clean no-op.
+- *Tests.* TDD with ERT — would be the project's first elisp tests. Small fixture =.org= files under =.ai/scripts/tests/fixtures/=; run via =emacs --batch -l ert -l test-todo-cleanup.el -f ert-run-tests-batch-and-exit=. Cases: one DONE level-2 moves; multiple; CANCELLED also moves; structural (no-state) headings don't move; nested DONE under an open parent stays; subtree at EOF; missing target section; nothing-to-do; idempotency.
+
+Origin: came up while scrubbing a project's todo.org on 2026-05-11 — moving a big completed PROJECT subtree (plus a few smaller ones) into the Resolved section by hand was the cue to build a reusable tool.
+
 * Rulesets Resolved
 ** DONE [#A] Add =make doctor= — verify ~/.claude/ matches repo + settings.json :feature: