From 9f84ea2c7854e35ae30c0fb5fbd63f7b7115fb41 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Thu, 28 May 2026 09:11:47 -0500
Subject: feat(sync-check): canonical/mirror drift detection + pre-commit hook

scripts/sync-check.sh diffs claude-templates/.ai/{protocols.org,
workflows,scripts} against the .ai/ mirror. Exits 0 when clean, 1 with
a diff report on drift, 2 outside a rulesets-shaped repo or git
checkout. --fix mode rsyncs canonical -> mirror and re-checks, then
prompts to re-stage.

githooks/pre-commit wraps the script. Commits abort on drift so the
issue surfaces at publish time, not at the next session's startup
rsync.

Two new Makefile targets:
- make sync-check [FIX=1] runs the script (FIX=1 passes --fix
  through).
- make install-githooks sets core.hooksPath=githooks (idempotent).

scripts/tests/sync-check.bats holds 8 tests covering clean,
drift-per-path, --fix, extra-file removal, missing canonical, and
outside-git. All eight pass.

This catches the exact drift I had to fix manually during this
morning's audit pass. The mirror's open-tasks.org PROPERTIES drawer
sat below a sub-heading because the mirror commit was older than
canonical.
---
 scripts/sync-check.sh | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)
 create mode 100755 scripts/sync-check.sh

(limited to 'scripts/sync-check.sh')

diff --git a/scripts/sync-check.sh b/scripts/sync-check.sh
new file mode 100755
index 0000000..8fb9ab0
--- /dev/null
+++ b/scripts/sync-check.sh
@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+#
+# sync-check.sh — verify canonical claude-templates/.ai/ matches the .ai/ mirror.
+#
+# Usage:
+#   scripts/sync-check.sh           # exit 0 if synced, 1 if drift
+#   scripts/sync-check.sh --fix     # rsync canonical → mirror, then re-check
+#
+# Runs as a pre-commit hook (githooks/pre-commit) to catch drift before
+# commit, and as a manual check via `make sync-check`.
+#
+# The three synced paths are:
+#   claude-templates/.ai/protocols.org  ↔  .ai/protocols.org
+#   claude-templates/.ai/workflows/     ↔  .ai/workflows/
+#   claude-templates/.ai/scripts/       ↔  .ai/scripts/
+#
+# Source of truth is the canonical (claude-templates/) side. The mirror
+# exists so rulesets-as-a-project has a working copy. Drift in either
+# direction is a defect — both have to land in the same commit.
+
+set -euo pipefail
+
+if ! repo_root="$(git rev-parse --show-toplevel 2>/dev/null)" || [ -z "$repo_root" ]; then
+    echo "sync-check: not inside a git checkout" >&2
+    exit 2
+fi
+
+canonical="$repo_root/claude-templates/.ai"
+mirror="$repo_root/.ai"
+
+if [ ! -d "$canonical" ] || [ ! -d "$mirror" ]; then
+    echo "sync-check: not a rulesets-shaped repo (missing claude-templates/.ai or .ai)" >&2
+    exit 2
+fi
+
+paths=(protocols.org workflows scripts)
+
+check_drift() {
+    local drift=0
+    for relpath in "${paths[@]}"; do
+        if ! diff -rq "$canonical/$relpath" "$mirror/$relpath" >/dev/null 2>&1; then
+            echo "drift: claude-templates/.ai/$relpath ↔ .ai/$relpath" >&2
+            diff -rq "$canonical/$relpath" "$mirror/$relpath" 2>&1 | head -20 >&2
+            drift=1
+        fi
+    done
+    return "$drift"
+}
+
+if check_drift; then
+    exit 0
+fi
+
+if [ "${1:-}" = "--fix" ]; then
+    echo "" >&2
+    echo "sync-check --fix: syncing canonical → mirror..." >&2
+    rsync -a "$canonical/protocols.org" "$mirror/protocols.org"
+    rsync -a --delete "$canonical/workflows/" "$mirror/workflows/"
+    rsync -a --delete "$canonical/scripts/" "$mirror/scripts/"
+    if check_drift; then
+        echo "sync-check --fix: resolved." >&2
+        echo "Re-stage the synced files and retry the commit." >&2
+        exit 0
+    else
+        echo "sync-check --fix: drift persists after sync. Inspect manually." >&2
+        exit 1
+    fi
+fi
+
+echo "" >&2
+echo "Run 'scripts/sync-check.sh --fix' (or 'make sync-check FIX=1') to resolve." >&2
+exit 1
-- 
cgit v1.2.3