feat(make): add catchup-machine target for cross-machine .ai/ sync

scripts/catchup-machine.sh runs the four steps that bring a machine in sync with rulesets canonical: git pull, make install (symlink refresh), make audit APPLY=1 (rsync .ai/ across all projects), and make doctor (verify). Idempotent, safe to re-run any time.

Built for the post-fold ratio migration but applies generally: after a fresh rulesets clone on a new machine, or whenever the canonical source has advanced since last sync.

Handles dirty working trees by skipping the pull and surfacing a warning; user commits or stashes before re-running.

3 files changed, 61 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index 5474c67..9b41bc3 100644
--- a/Makefile
+++ b/Makefile
@@ -413,6 +413,9 @@ install-ai: ## Bootstrap .ai/ in a fresh project ([PROJECT=<path>] [TRACK=1 | GI
 		$(if $(GITIGNORE),--gitignore) \
 		$(PROJECT)
 
+catchup-machine: ## Pull rulesets, refresh install, sync .ai/ across projects, verify doctor
+	@bash scripts/catchup-machine.sh
+
 test: ## Run the .ai/scripts/ test suites (pytest + ERT)
 	@cd .ai/scripts/tests && python3 -m pytest
 	@set -e; for f in .ai/scripts/tests/test-*.el; do \
diff --git a/scripts/catchup-machine.sh b/scripts/catchup-machine.sh
new file mode 100755
index 0000000..e64a871
--- /dev/null
+++ b/scripts/catchup-machine.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# catchup-machine.sh — bring this machine's rulesets state and all .ai/-using
+# projects in sync with the canonical rulesets repo. Idempotent; safe to re-run.
+#
+# Steps:
+#   1. git pull --ff-only on ~/code/rulesets
+#   2. make install (refresh ~/.claude/ symlinks for any new skills/commands/rules)
+#   3. make audit APPLY=1 (rsync .ai/ template content into every project)
+#   4. make doctor (verify install)
+#
+# Use case: after a fresh clone of rulesets on a new machine, or after the
+# canonical source has advanced and the local machine needs to catch up.
+#
+# Projects with uncommitted .ai/ changes are skipped by step 3 — surface them
+# at the end so the user can commit/stash and re-run.
+
+set -euo pipefail
+
+REPO="$HOME/code/rulesets"
+if [ ! -d "$REPO" ]; then
+  echo "ERROR: $REPO not found — clone rulesets first" >&2
+  exit 1
+fi
+cd "$REPO"
+
+echo "=== Step 1/4: Pull rulesets ==="
+if git diff --quiet --ignore-submodules HEAD -- 2>/dev/null; then
+  git pull --ff-only origin main
+else
+  echo "WARN: working tree is dirty — skipping pull. Commit or stash first to update."
+fi
+
+echo
+echo "=== Step 2/4: make install (refresh symlinks) ==="
+make install
+
+echo
+echo "=== Step 3/4: make audit APPLY=1 (sync .ai/ across projects) ==="
+# Don't bail on non-zero exit — audit returns 1 when any project was skipped or
+# applied. Both are expected outcomes here.
+set +e
+make audit APPLY=1 NO_DOCTOR=1
+audit_exit=$?
+set -e
+
+echo
+echo "=== Step 4/4: make doctor (verify install) ==="
+make doctor
+
+echo
+echo "Done."
+if [ "$audit_exit" -ne 0 ]; then
+  echo
+  echo "Note: audit step exited non-zero, which is expected if any project was"
+  echo "skipped (uncommitted .ai/) or applied (drift fixed). Re-read the audit"
+  echo "output above to see what landed."
+fi
diff --git a/todo.org b/todo.org
index 1ca5b2f..7f2c3a2 100644
--- a/todo.org
+++ b/todo.org
@@ -1917,7 +1917,7 @@ Test against the current state of this machine before pushing changes to ratio.
 - =make doctor= still passes 36/0/0 after all the work.
 - =make test= (pytest + ERT) passes.
 
-*** TODO [#A] Migrate projects on ratio (second machine)
+*** DOING [#A] Migrate projects on ratio (second machine)
 
 After local fold + audit + install-ai are working, propagate to ratio.