chore(ai): wrap fold-claude-templates + audit/install-ai + ratio migration

1 files changed, 179 insertions, 0 deletions

diff --git a/.ai/sessions/2026-05-15-18-19-consolidate-ai-template-infra.org b/.ai/sessions/2026-05-15-18-19-consolidate-ai-template-infra.org
new file mode 100644
index 0000000..0baac74
--- /dev/null
+++ b/.ai/sessions/2026-05-15-18-19-consolidate-ai-template-infra.org
@@ -0,0 +1,179 @@
+#+TITLE: Session Context — consolidate .ai/ template infrastructure epic
+#+AUTHOR: Craig Jennings & Claude
+#+DATE: 2026-05-15
+
+* Summary
+
+** Active Goal
+
+Started as a reconcile + cross-project =.ai/= sweep. Surfaced a canonical-source rule violation (the date-coverage scan landed in rulesets without going through claude-templates first; the startup rsync was about to silently revert it). Fix that, sweep 21 projects, then escalate into the full /Consolidate =.ai/= template infrastructure/ epic: fold claude-templates into rulesets via =git subtree=, build =make audit= + =make install-ai= + =make catchup-machine= targets, encode follow-up filing rules into =/start-work=, migrate ratio over ssh, and delete both machines' standalone claude-templates checkouts.
+
+** Decisions
+
+- *Keep the date-coverage scan in wrap-up.* It was added to rulesets in =372fb76= without landing in claude-templates first. Fix by adding the subsection to claude-templates (canonical), re-rsync into rulesets, commit consolidated delta.
+- *Subtree merge with =--squash=*. Cleaner =git log= than full 84-commit history merge; standalone history persists on =cjennings.net:git/claude-templates.git=. Reversible if you want unsquashed.
+- *Bin/ai launcher install folds into rulesets =Makefile=.* Existing user symlinks at =~/.local/bin/ai= pointing at the old path get auto-relinked to the new canonical (=~/code/rulesets/claude-templates/bin/ai=).
+- *=make audit= uses =diff -rq= for content comparison*, not =rsync --itemize-changes= (which counts attribute-only drift as changes). Skips canonical source, the in-repo prefix, and the legacy standalone path.
+- *Default audit mode is report-only*; =APPLY=1= rsyncs drift; =FORCE=1= overrides the dirty-skip safety; =NO_DOCTOR=1= skips the doctor sub-invoke. Exit 1 if anything non-ok.
+- *=make install-ai= refuses on existing =.ai/=*; points the user at =make audit APPLY=1=. =TRACK=1= adds =.gitkeep= files; =GITIGNORE=1= appends =.ai/= to project =.gitignore=.
+- *Follow-ups discovered during an epic file as level-2 siblings of the parent*, not as descendants of any child. Stays visible after parent closure. Saved as project memory + encoded into =start-work.md= Phase 4 step 5 for cross-project effect.
+- *Force-apply ratio's 14 dirty tracked projects.* The "uncommitted" =.ai/= content was accumulated template-sync drift (one project showed +615 lines on =daily-prep.org= and 5 deleted workflow files), not project-specific work. Clobbering with current canonical IS the desired state.
+- *Delete the standalone =~/projects/claude-templates/= on both machines.* History persists in the subtree under =rulesets/claude-templates/= and at =cjennings.net:git/claude-templates.git=.
+
+** Data Collected / Findings
+
+- claude-templates was 4 commits ahead of rulesets' last sync (=bb2ab6f=, =6ac1f79=, =06cf882=, =039e2e8=).
+- =make doctor= caught a drifted symlink: =todo-format.md= was in the Makefile install list but never linked in =~/.claude/rules/=. Doctor went from 35/0/1 → 36/0/0 after =make install=.
+- All 21 non-rulesets =.ai/= projects on velox were clean before the morning sweep. After sweep: 7 gitignored converged silently; 14 tracked got uncommitted working-tree deltas.
+- =git subtree add --squash= produces two commits — a "Squashed 'claude-templates/' content from commit X" commit and a "Merge commit Y as 'claude-templates'" commit. Content under the prefix is byte-identical to the source.
+- Phase A.0 of startup needed structural changes for the fold: it now refreshes /rulesets/ (the parent repo), not /claude-templates/ (the source dir). Inside rulesets sessions the pull is redundant-but-harmless. Outside rulesets sessions it's the only mechanism that pulls template updates.
+- =make audit= run #1 surfaced false positives at 86 items/project (attribute-only drift via =rsync --itemize-changes=). Switching to =diff -rq= dropped the count to 3 items/project — the actual content drift (today's path-ref updates).
+- Ratio had wider per-project drift than velox: =clipper= showed 5 deleted workflow files + 615-line =daily-prep.org= addition, =jr-estate= 564-line drift. Accumulated template-sync gap from many sessions of partial syncs. Force-applying converged everything in one operation.
+- Memory dir at =~/.claude/projects/-home-cjennings-code-rulesets/memory/= didn't exist on velox (despite session notes referencing it). Created on first memory save this session.
+
+** Files Modified
+
+claude-templates (pushed to =origin/main=):
+- =f116888 docs(wrap-it-up): add date-coverage scan for undated [#A]/[#B] tasks= — restored the subsection that rulesets had added but claude-templates missed.
+
+rulesets (pushed to =origin/main=, in order):
+- =ee721ee chore(ai): sync scripts and workflows from claude-templates= — pulled in the 4 upstream claude-templates commits.
+- =2b471da docs(todo): start consolidate .ai/ template infra epic= — parent task at =todo.org:1774= with 5 children, marked DOING.
+- =69c5e4a + c1d4e3c= — =git subtree add --squash= of claude-templates content under =claude-templates/= prefix.
+- =3a4af17 docs(ai): point template references at in-repo claude-templates/= — path swap across protocols.org, startup.org, cross-agent-comms.org (canonical + in-project copies).
+- =2d645fc chore(make): fold bin/ai launcher install into rulesets= — new install/uninstall/list logic for =~/.local/bin/ai=. Includes "relink" case for users with stale symlinks.
+- =cd35f66 docs(todo): file Makefile redundancy as fold-epic sibling= — first follow-up filed as level-2 sibling of the parent epic.
+- =e0f6002 docs(todo): file start-work follow-up filing rule task= — captured Craig's meta-observation about /start-work needing explicit placement guidance.
+- =94782ee feat(make): add audit target for cross-project .ai/ drift detection= — =scripts/audit.sh= + Makefile target.
+- =d364cf2 feat(make): add install-ai target for bootstrapping .ai/ in fresh projects= — =scripts/install-ai.sh= + Makefile target.
+- =2eab96f docs(todo): close fold-epic test plan, file edge-case follow-up= — child 4 DONE + new sibling for untested edges (=--force= on dirty, missing =.ai/=, fzf-pick).
+- =9bef4ca feat(make): add catchup-machine target for cross-machine .ai/ sync= — =scripts/catchup-machine.sh= for ratio migration and any future machine.
+- =3e895de docs(todo): mark fold-epic children 1-3 done= — status flips.
+- =cea44a9 docs(start-work): encode follow-up filing placement rules= — siblings-for-epics rule now in =.claude/commands/start-work.md= Phase 4 step 5.
+- =b7d5ba9 docs(todo): close consolidate .ai/ template infra epic; ratio migrated= — parent + child 5 DONE.
+
+System-side (no commit):
+- =~/.claude/rules/todo-format.md= → new symlink created by =make install=.
+- =~/.local/bin/ai= → relinked from old standalone path to new in-repo canonical (both machines).
+- =~/projects/claude-templates/= deleted on velox AND ratio.
+- Project memory =feedback_followups_as_siblings.md= + MEMORY.md index created at =~/.claude/projects/-home-cjennings-code-rulesets/memory/=.
+
+Ratio machine state (via ssh):
+- =~/code/rulesets= pulled to current main.
+- 23 projects audited: 22 ok + 1 applied (=danneel= had 20 items drift).
+- =~/projects/claude-templates/= deleted.
+- =make doctor= 36/0/0.
+
+** Next Steps
+
+- =[#C]= sibling open: consolidate =rulesets/claude-templates/Makefile= (still has standalone install/uninstall/list/test-scripts targets that overlap with =rulesets/Makefile=).
+- =[#C]= sibling open: build a test harness for =make audit= + =make install-ai= edge cases (=--force= on dirty, missing =.ai/=, install-ai fzf-pick form).
+- Carryover still open from prior sessions: =DOING [#A]= memory-sync investigation (pending VERIFY on stow approach — adjacent to today's work, may want coordination), =[#A]= =/update-skills= skill, =[#A]= =create-documentation= skill, =[#A]= 2026-05-04 audit review pass.
+- =/lint-org= TODO at =todo.org:1292= is stale — the work shipped last session but the entry isn't marked DONE. Should be moved to Rulesets Resolved at next cleanup.
+
+* Session Log
+
+** Startup (15:13 CDT)
+
+Clean startup — previous session wrapped cleanly (no =session-context.org=), inbox empty, no cross-agent messages, no reminders, no pending decisions. Surfaced one drift: =todo.org:1292= still shows the =/lint-org= TODO as =TODO= even though the work shipped last session. Read the 5 most recent session Summaries. Offered top open A items.
+
+** Reconcile + canonical-source fix
+
+Craig asked to reconcile rulesets and make sure all =.ai/= packages have a current updated version. rulesets =0/0= against =origin/main= but Phase A startup rsync had brought in template-sync deltas — 3 modified files, 6 untracked new files. Mapped each to specific upstream commits. The =wrap-it-up.org= =-33= delta stood out: no claude-templates commit had ever touched the date-coverage scan, meaning rulesets =372fb76= added it without going through claude-templates first. Craig picked "keep the scan" (option 1).
+
+Executed the canonical-source fix: claude-templates =f116888 docs(wrap-it-up): add date-coverage scan= committed and pushed; re-rsync into rulesets dropped =wrap-it-up.org= out of the diff; consolidated rulesets =ee721ee chore(ai): sync scripts and workflows from claude-templates= committed and pushed.
+
+** 21-project sweep
+
+Surveyed 21 non-rulesets =.ai/=-using projects on disk. All clean before sweep. Ran =protocols.org=, =workflows/=, =scripts/= rsync into each. Post-sweep: 7 gitignored converged silently; 14 tracked got uncommitted working-tree deltas. Craig picked "leave as-is" (option 1) — each project commits at its own next wrap-up rather than a 14-repo commit cascade.
+
+** Install drift discovery
+
+Craig asked whether new skills and commands would be updated/symlinked. Inventoried: =~/.claude/commands= is a directory-level symlink (children auto-pick-up). Skills are individual symlinks. Ran =make doctor= → 35 ok, 0 warn, *1 fail*: =rule todo-format.md: not installed=. =make install= created the missing symlink. Doctor re-ran 36/0/0.
+
+** Architecture clarification
+
+Craig mentioned he thought we'd do =make install= against each =.ai/= project. Clarified: =make install= is machine-wide (single symlink set into =~/.claude/=). Per-project layer is the =.ai/= rsync, which is already done. He acknowledged the correction.
+
+** make audit design pass
+
+Conversation pivoted to "build =make audit= for next time." Walked through:
+- Clean-project verification path (5 checks per project, all silent).
+- =--apply= mode for fixing drift (vs report-only default).
+- Install-ai is a separate target — operating on projects without =.ai/= is a distinct concern from audit.
+- The =[#B]= fold and audit TODOs from 2026-05-09 already had partial designs; Craig wanted both built now along with new install-ai + test plan + ratio migration as children of a single epic.
+
+Created parent task =** TODO [#A] Consolidate .ai/ template infrastructure= at =todo.org:1774= with five level-3 children. Demoted the existing [#B] tasks to children, promoted to [#A]. Build order encoded in parent prose: fold first (others depend on the path), then audit + install-ai in parallel, then test, then ratio.
+
+** Epic Phase 0 + 1 + 2
+
+/start-work on the parent task. Pre-flight reconcile clean. Existence check confirmed all three problem-statements still hold: two-repo split exists, canonical-source rule violation exists today, ratio not migrated. Justify gate covered all 9 dimensions; estimated L (4-6 hours). Craig picked option 1 (push through all 5 children today).
+
+** Child 1: Fold claude-templates into rulesets
+
+Approach gate 2: subtree-merge with =--squash= for clean log; 3 path-reference files to update; bin/ai install needs folding into rulesets =Makefile=; commit decomposition planned for 3 commits.
+
+Implemented:
+- =git subtree add --prefix=claude-templates --squash ~/projects/claude-templates main= — landed cleanly, byte-identical content vs source.
+- 3 path-reference files updated (canonical + in-project copies, 6 files total). Phase A.0 of startup.org reworked: it now refreshes rulesets, not claude-templates.
+- bin/ai install folded into rulesets =Makefile= with auto-relink for existing stale symlinks. Verified by running =make install= — relinked Craig's =~/.local/bin/ai= from old to new path.
+
+Phase 5 verification: rsync from new path produces zero diff; Phase A.0 ran cleanly from inside =~/projects/homelab/= (outside-rulesets simulation); doctor 36/0/0; tests 341 green (296 pytest + 22 lint-org ERT + 23 todo-cleanup ERT). Surface follow-up: =claude-templates/Makefile= now partially redundant with rulesets =Makefile=.
+
+Gate 3 → push (5 commits including subtree merge pair).
+
+** Sibling task pattern emerges
+
+After surfacing the Makefile redundancy follow-up, Craig instructed that all follow-ups from this epic file as siblings of the parent (not as descendants of any child). Reason: siblings stay visible after parent closure; descendants get orphaned when their parent subtree archives. Saved as project memory at =~/.claude/projects/-home-cjennings-code-rulesets/memory/feedback_followups_as_siblings.md= for future sessions.
+
+Filed first sibling: =[#C] Consolidate claude-templates/Makefile after fold=.
+
+** Mid-flight: start-work follow-up rules
+
+Craig asked whether filing follow-ups should be part of /start-work itself. Phase 4 step 5 already says "file a ticket or todo.org entry" as a disposition, but doesn't specify /where/ to file. Filed =[#B] Encode follow-up filing rules into /start-work= as a top-level task. (Implemented this later in the session — see below.)
+
+** Child 2: Build =make audit=
+
+Wrote =scripts/audit.sh= matching =doctor.sh= conventions. First implementation used =rsync --dry-run --itemize-changes= for drift detection but counted 86 items/project — attribute-only drift (mtime, permissions). Switched to =diff -rq= for content comparison; drift count dropped to 3 items/project (the actual path-ref changes).
+
+Project discovery via =find -maxdepth 3 -type d -name .ai= under =~/code=, =~/projects=, =~/.emacs.d=. Skip list: rulesets root, in-repo canonical (=rulesets/claude-templates=), and legacy standalone (=~/projects/claude-templates=) during transition.
+
+Per-project flow: dir-exists check, git-tracked-vs-gitignored detection, dirty check (skip on dirty unless =--force=), drift count via three =diff -rq= calls, optional rsync apply, convergence verify, working-tree state report. Flags: =--apply=, =--force=, =--no-doctor=. Output mirrors doctor: per-project ok/drift/applied/skipped/FAIL with summary tally.
+
+Makefile target uses Make variables (=APPLY=1=, =FORCE=1=, =NO_DOCTOR=1=) rather than passing CLI flags through =$(MAKECMDGOALS)= (cleaner; doesn't need a catchall =%:= rule).
+
+Phase 5: tested in 3 modes (report-only, =APPLY=1=, idempotent re-run). Skipped destructive tests (=--force= on real dirty project, missing =.ai/= dir) — filed as sibling follow-up for a future test harness.
+
+Gate 3 → push.
+
+** Child 3: Build =make install-ai=
+
+Wrote =scripts/install-ai.sh=. Refuses if =PROJECT/.ai/= already exists (points to =make audit APPLY=1= for sync). Creates =.ai/= structure, rsyncs canonical content (=protocols.org=, =workflows/=, =scripts/=, =someday-maybe.org=), templates =notes.org= with project-name + date placeholder substitution.
+
+Tracking modes: =--track= adds =.gitkeep= files inside otherwise-empty =sessions/= / =references/= / =retrospectives/=; =--gitignore= appends =.ai/= to project =.gitignore=. Prompts interactively if neither flag set.
+
+Fzf-pick fallback when no =PROJECT= arg: walks =~/code/*= and =~/projects/*=, filters to git checkouts without existing =.ai/=.
+
+Phase 5: tested fresh install (=TRACK=1=, =GITIGNORE=1=), refusal-on-existing, placeholder substitution, =.gitkeep= creation. fzf-pick form not exercised (interactive) — covered by the same sibling test-harness follow-up.
+
+Gate 3 → push.
+
+** Child 4: Test plan
+
+Ran the validation battery: =make doctor= 36/0/0; pytest 296+1 skipped; lint-org ERT 22/22; audit clean (7 ok + 14 dirty-skip as expected); install-ai fresh + refusal both verified. Three destructive edge cases (=--force= on dirty, missing =.ai/=, install-ai fzf) deferred to the sibling test-harness task. Child 4 marked DONE.
+
+** Mid-flight again: implement start-work follow-up rule
+
+Came back to the earlier =[#B]= task. Edited =.claude/commands/start-work.md= Phase 4 step 5's "Disposition for each candidate": new "Where to file in todo.org" subsection spelling out siblings-for-epics and new-top-level-for-standalone. Marked the task DONE.
+
+** Child 5: Migrate ratio (the destructive convergence)
+
+Force-applied audit on velox first to converge the 14 dirty projects. All 21 velox projects now reference new canonical path. Deleted velox =~/projects/claude-templates/= entirely; verified ai launcher (symlink already relinked by earlier =make install=) still works.
+
+Then ratio via ssh. Pulled rulesets on ratio (15 commits behind), ran =bash scripts/catchup-machine.sh=. Ratio's 9 gitignored converged silently. 14 tracked skipped due to dirty =.ai/=. Spot-checked one (=clipper= showed 5 deleted workflow files + 615-line =daily-prep.org= addition — accumulated template-sync drift across many sessions); spot-checked three more (homelab 151 lines, work 87, jr-estate 564) — all template drift, no project-specific work. Force-applied on ratio: 22 ok + 1 applied (=danneel= had 20 items). All 23 ratio projects converged. Deleted ratio =~/projects/claude-templates/= via ssh. Verified ratio doctor 36/0/0.
+
+Marked child 5 DONE and parent epic DONE. Committed and pushed =b7d5ba9=.
+
+** Wrap-up
+
+Craig validated the audit design: "some of those projects haven't been updated in a while. this is why I wanted to create the audit Makefile target and run it across those projects." Picked option 1 (wrap up).