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, 99 insertions, 0 deletions

diff --git a/.ai/scripts/flashcard-diff-ids.py b/.ai/scripts/flashcard-diff-ids.py
new file mode 100755
index 0000000..152bb70
--- /dev/null
+++ b/.ai/scripts/flashcard-diff-ids.py
@@ -0,0 +1,99 @@
+#!/usr/bin/env python3
+"""SRS-state preservation check between two versions of an org-drill deck.
+
+Extracts every :ID: from each version and reports IDs that disappeared
+or appeared. Disappeared IDs lose org-drill SRS state (review history,
+ease, intervals) and are the worst-case bug from a deck rewrite. Appeared
+IDs are usually fine (new cards added on purpose) but worth surfacing.
+
+Exits 0 when clean, 1 when any IDs disappeared or appeared.
+
+Usage:
+  flashcard-diff-ids.py <before.org> <after.org>
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+CARD_RE = re.compile(r"^\*\*\s+(.+?)\s+:drill:\s*$")
+ID_RE = re.compile(r"^\s*:ID:\s+(\S+)\s*$")
+
+
+def card_id_map(path: Path) -> dict[str, str]:
+    """Return {id -> heading} for every :drill: card in path."""
+    result: dict[str, str] = {}
+    lines = path.read_text(encoding="utf-8").splitlines()
+    i = 0
+    while i < len(lines):
+        m = CARD_RE.match(lines[i])
+        if m:
+            heading = m.group(1).strip()
+            i += 1
+            while i < len(lines):
+                line = lines[i]
+                if line.startswith("* ") or CARD_RE.match(line):
+                    break
+                mid = ID_RE.match(line)
+                if mid:
+                    result[mid.group(1)] = heading
+                    break
+                i += 1
+            continue
+        i += 1
+    return result
+
+
+def main() -> int:
+    if len(sys.argv) != 3:
+        print(f"usage: {sys.argv[0]} <before.org> <after.org>", file=sys.stderr)
+        return 2
+
+    before_path = Path(sys.argv[1]).expanduser().resolve()
+    after_path = Path(sys.argv[2]).expanduser().resolve()
+
+    for p in (before_path, after_path):
+        if not p.is_file():
+            print(f"error: {p} not found", file=sys.stderr)
+            return 2
+
+    before = card_id_map(before_path)
+    after = card_id_map(after_path)
+
+    before_ids = set(before)
+    after_ids = set(after)
+
+    preserved = before_ids & after_ids
+    disappeared = before_ids - after_ids
+    appeared = after_ids - before_ids
+
+    print(f"flashcard-diff-ids: {before_path.name} → {after_path.name}")
+    print()
+    print(f"IDs in BEFORE: {len(before_ids)}")
+    print(f"IDs in AFTER: {len(after_ids)}")
+    print(f"Preserved: {len(preserved)}")
+    print(f"Disappeared: {len(disappeared)}")
+    print(f"Appeared: {len(appeared)}")
+    print()
+
+    warnings = 0
+    if disappeared:
+        warnings += 1
+        print(f"WARN: {len(disappeared)} card IDs disappeared (SRS state lost)")
+        for cid in sorted(disappeared):
+            print(f"      - {cid} (was: {before[cid]!r})")
+    if appeared:
+        warnings += 1
+        print(f"NOTE: {len(appeared)} new card IDs appeared")
+        for cid in sorted(appeared):
+            print(f"      - {cid} (now: {after[cid]!r})")
+
+    if warnings == 0:
+        print("clean — SRS state preserved")
+        return 0
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())