docs(workflows): add clean-todo workflow

clean-todo is the manual entry point for tidying todo.org: it runs the hygiene pass, then --archive-done (relocate completed level-2 subtrees into "Resolved"), then summarizes what changed and leaves the diff uncommitted for review. The wrap-up flow already does both passes at session end; clean-todo runs them on demand. It's listed in INDEX.org under the usual trigger phrases.

2 files changed, 60 insertions, 0 deletions

diff --git a/.ai/workflows/INDEX.org b/.ai/workflows/INDEX.org
index 3750e91..7349d74 100644
--- a/.ai/workflows/INDEX.org
+++ b/.ai/workflows/INDEX.org
@@ -31,6 +31,8 @@ This index must list every =.org= file in =.ai/workflows/= except this one. Star
   - Standup-only triggers: "what's my standup report", "let's do the daily standup report", "give me the standup brief"
 - =journal-entry.org= — capture a daily journal entry.
   - Triggers: "let's do a journal entry", "create a journal entry"
+- =clean-todo.org= — tidy =todo.org=: hygiene pass + =--archive-done=, then summarize. Wrap-up does this automatically; this is the manual entry point.
+  - Triggers: "clean up todo.org", "clean-todo", "tidy the todo file", "archive the done items in todo.org", "run the todo cleanup"
 
 ** Calendar
 
diff --git a/.ai/workflows/clean-todo.org b/.ai/workflows/clean-todo.org
new file mode 100644
index 0000000..dd33056
--- /dev/null
+++ b/.ai/workflows/clean-todo.org
@@ -0,0 +1,58 @@
+#+TITLE: Clean-Todo Workflow
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-05-11
+
+* Overview
+
+On-demand cleanup of the project's =todo.org=: run the hygiene pass, then archive completed work, then report what changed. The wrap-up workflow already does both passes at session end; this workflow is the manual entry point — invoke it any time the todo file needs a tidy, without waiting for a wrap-up.
+
+* When to Use This Workflow
+
+When Craig says:
+- "clean up todo.org" / "clean-todo" / "tidy the todo file"
+- "archive the done items in todo.org"
+- "run the todo cleanup"
+
+Requires a =todo.org= at the project root. If there isn't one, say so and stop.
+
+* The Workflow
+
+** Step 1: Hygiene pass
+
+#+begin_src bash
+emacs --batch -q -l .ai/scripts/todo-cleanup.el todo.org
+#+end_src
+
+Deletes bogus =- State "X" from "X" [date]= log lines (state didn't actually change — these wedge between the heading and =DEADLINE:=/=SCHEDULED:= and break agenda parsing) and reports "orphan planning lines" (a body =DEADLINE:=/=SCHEDULED:= that =org-entry-get= can't read because it's out of canonical position — not auto-rewritten; surface for manual fix). Fast and idempotent. Capture the output.
+
+To preview without writing, run =--check= first: =emacs --batch -q -l .ai/scripts/todo-cleanup.el --check todo.org=.
+
+** Step 2: Archive completed work
+
+#+begin_src bash
+emacs --batch -q -l .ai/scripts/todo-cleanup.el --archive-done todo.org
+#+end_src
+
+Moves every level-2 subtree whose TODO state is DONE or CANCELLED out of the "Open Work" section into the "Resolved" section, subtree intact. The two sections are matched by a unique level-1 heading containing "Open Work" (case-insensitive) and one containing "Resolved" — if either is missing or ambiguous, the file is skipped with a message, no crash. Only direct level-2 children move; a DONE entry nested under an open parent stays put. Idempotent. Capture the output.
+
+To preview the moves without writing: =emacs --batch -q -l .ai/scripts/todo-cleanup.el --archive-done --check todo.org=.
+
+** Step 3: Summarize
+
+Report to Craig from the two captured outputs:
+- Hygiene: how many bogus state-log lines were deleted; any orphan-planning warnings (file:line + heading), or "none".
+- Archive: how many subtrees moved and which (heading + line), or "nothing to move" / the skip reason if a section was missing or ambiguous.
+- If the file changed, note that =todo.org= now has an uncommitted edit — review =git diff -- todo.org= and commit it (in this repo's commit style) if it looks right. If nothing changed, say so and stop.
+
+Don't auto-commit. The summary is the review point; Craig decides whether the diff goes in.
+
+* Principles
+
+- *Both passes apply, not just preview.* The workflow is invoked because cleanup is wanted. Use the =--check= variants only when Craig asks for a dry run.
+- *Two passes, two invocations.* =--archive-done= is its own mode and does not run the hygiene pass; run both.
+- *Never auto-commit todo.org.* Surface the diff and let Craig commit it. The cleanup is a working-tree change, fully reversible until committed.
+- *Trust the script.* It's fast and idempotent; if there's nothing to do, it reports zero and exits clean. No pre-checks.
+
+* Living Document
+
+Update this workflow if =todo-cleanup.el= grows new modes or the section-matching rules change.