feat: add rename-ai-artifact tool and rename the drill-deck family to flashcard

Renaming an .ai artifact by hand is the kind of mechanical job that gets done incompletely: the canonical copy moves but the mirror doesn't, a reference in the INDEX is missed, a trigger phrase points at the old name. I'd also assumed a rename was costly because references scatter, when the index update is trivial and the drift check already guards it. So I built the discipline into a script instead of re-deriving it each time.

scripts/rename-ai-artifact.sh takes old and new basenames, moves the file in both the canonical and mirror trees, and rewrites every reference repo-wide on a token boundary so renaming "foo" can't corrupt "foobar" or "foo-bar". It rewrites the underscore module-name variant too (a hyphenated script imported as foo_bar via importlib), leaves the archived session records under sessions/ alone because they're history, and runs workflow-integrity + sync-check at the end to prove no drift. rename-artifact.org documents it and indexes the triggers.

Then I used the tool to do the rename that prompted it: the org-drill deck workflow and its helpers are now flashcard-named, since "flashcard" is the word you'd actually search for. The renamed set is flashcard-review.org plus flashcard-stats.py, flashcard-sync, flashcard-to-anki.py, and flashcard-diff-ids.py, with their tests, every reference, and the INDEX entry updated. The deck is still an org-drill deck under the hood, so the ":drill:" tag handling and the "drill deck" trigger phrases stay. I added "review/update the flashcards" alongside them.

Tests: 9 bats for the rename tool (including the prefix-collision and history-preservation edges), and the renamed script suites all pass under make test.

1 files changed, 44 insertions, 0 deletions

diff --git a/.ai/workflows/rename-artifact.org b/.ai/workflows/rename-artifact.org
new file mode 100644
index 0000000..7b9f15b
--- /dev/null
+++ b/.ai/workflows/rename-artifact.org
@@ -0,0 +1,44 @@
+#+TITLE: Rename an .ai Artifact
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-05-31
+
+* Summary
+
+Rename a workflow or a script that lives in the =.ai/= tree, without leaving the canonical copy, the mirror copy, the INDEX, or any reference behind. The work is mechanical and easy to do incompletely by hand — a missed reference or a forgotten mirror copy is the classic failure. The =rename-ai-artifact.sh= script does it the same way every time, so reach for the script rather than renaming files by hand.
+
+Quick contract — what it does:
+- Moves the artifact in both =claude-templates/.ai/= (canonical) and =.ai/= (mirror), in lockstep.
+- Rewrites every reference to the artifact's stem, repo-wide, on a token boundary so renaming =foo= can't corrupt =foobar= or =foo-bar=.
+- Rewrites the underscore module-name variant too — a hyphenated script imported as =foo_bar= via importlib, not just the =foo-bar.py= path.
+- Leaves =sessions/= (both trees) untouched — archived session records are history.
+- Runs =workflow-integrity.py= and =sync-check.sh= afterward to prove no drift.
+
+* Execution
+
+Run once per file. For a family (a workflow plus its helper scripts), run it once per artifact; order doesn't matter because reference matching is token-bounded.
+
+#+begin_example
+scripts/rename-ai-artifact.sh OLD-BASENAME NEW-BASENAME
+
+# examples
+scripts/rename-ai-artifact.sh old-workflow.org new-workflow.org
+scripts/rename-ai-artifact.sh old-helper.py    new-helper.py
+#+end_example
+
+After the last file in a family is renamed, review =git status= and the diff, then commit through the normal publish flow.
+
+* Reference
+
+** When to use
+
+Any time an =.ai/= workflow or script changes name. Also the right tool when only the *concept* is being renamed and you want every trigger phrase, =file:= link, and prose mention updated to match.
+
+** What it will not do
+
+- It won't touch =sessions/= records (history stays accurate to when it was written).
+- It won't rename across directories — the artifact keeps its home directory; only the basename changes.
+- It renames one artifact per call and refuses if the source is missing or the target name already exists.
+
+** If a verify step reports drift
+
+The script still completes the rename, then warns. Read the =workflow-integrity= / =sync-check= output, fix by hand (usually a stale INDEX row the stem rewrite didn't reach because the row used different wording), and re-run the checks before committing.