From 7ea1d7b1402eb68a13479f8073b84819c1d59ec8 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Mon, 27 Jul 2026 13:13:09 -0500
Subject: fix(rules): stop shipping generic rules into every project

Generic rules install once at ~/.claude/rules/ and load in every session on the machine. The language bundles copied all twenty into each project as well, so work and .emacs.d loaded them twice. Project rules outrank user-level ones, which makes it worse than waste. A stale project copy overrides the fresh global rule until the next startup heals it, and that is what happened to work's interaction.md this morning for the hours between the commit and its next session.

I stopped install-lang copying them. sync-language-bundle now sweeps the copies earlier installs left, but only where the global rule exists to take over. A machine that hasn't run make install keeps the only copy it has. I swept 20 files each from work and .emacs.d, leaving their language rules and work's publishing overlay untouched.

I updated three existing tests that encoded the old contract. The generic-rule drift test is the interesting one: I made a drifted copy get swept rather than repaired, which is the stronger fix, because that copy outranked the global rule for as long as it existed.

I also gitignored the live session anchor. This repo tracks .ai/, so the anchor read as untracked for a whole session. git-worktree-gate reported rulesets sync-blocked, and every other project skipped its rulesets pull until wrap. The anchor is ephemeral and gets archived under a different name, so nothing needs it tracked.
---
 scripts/tests/sync-language-bundle.bats | 75 ++++++++++++++++++++++++++++++---
 1 file changed, 69 insertions(+), 6 deletions(-)

(limited to 'scripts/tests/sync-language-bundle.bats')

diff --git a/scripts/tests/sync-language-bundle.bats b/scripts/tests/sync-language-bundle.bats
index 1871444..0eb3ae2 100644
--- a/scripts/tests/sync-language-bundle.bats
+++ b/scripts/tests/sync-language-bundle.bats
@@ -19,7 +19,20 @@ teardown() {
   rm -rf "$PROJ"
 }
 
-# Mirror install-lang.sh: copy the bundle's files into a synthetic project.
+# Mirror what a CURRENT install-lang.sh leaves: language rules only, no copies
+# of the generic rules (those live once at ~/.claude/rules/).
+install_bundle_current() {
+  install_bundle "$1" "$2"
+  local f
+  for f in "$REAL_REPO/claude-rules"/*.md; do
+    [ -f "$f" ] || continue
+    rm -f "$2/.claude/rules/$(basename "$f")"
+  done
+}
+
+# Mirror what an OLDER install-lang.sh left behind: language rules PLUS copies
+# of every generic rule. This is the state the sweep exists to clean up, and
+# real projects are still in it until their next startup.
 install_bundle() {
   local lang="$1" proj="$2"
   mkdir -p "$proj/.claude/rules"
@@ -67,14 +80,14 @@ install_team_overlay() {
 }
 
 @test "sync: clean elisp bundle is a quiet no-op (exit 0)" {
-  install_bundle elisp "$PROJ"
+  install_bundle_current elisp "$PROJ"
   run bash "$SCRIPT" "$PROJ"
   [ "$status" -eq 0 ]
   [ -z "$output" ]
 }
 
 @test "sync: absent CLAUDE.md is not flagged as drift (seed-only/project-owned)" {
-  install_bundle elisp "$PROJ"   # helper never seeds CLAUDE.md
+  install_bundle_current elisp "$PROJ"   # helper never seeds CLAUDE.md
   [ ! -f "$PROJ/CLAUDE.md" ]
   run bash "$SCRIPT" "$PROJ"
   [ "$status" -eq 0 ]
@@ -94,13 +107,17 @@ install_team_overlay() {
   matches_canonical ".claude/rules/elisp.md" "$REAL_REPO/languages/elisp/claude/rules/elisp.md"
 }
 
-@test "sync: drifted generic rule is auto-fixed and restored" {
+# Generic rules are no longer auto-fixed in place: they are swept, because the
+# global copy at ~/.claude/rules/ is the one that loads. A drifted project copy
+# is not repaired, it is removed — which is the stronger fix, since the drifted
+# copy outranked the global rule while it existed.
+@test "sync: a drifted generic rule copy is swept, not repaired" {
   install_bundle elisp "$PROJ"
   echo "junk" >> "$PROJ/.claude/rules/commits.md"
   run bash "$SCRIPT" "$PROJ"
   [ "$status" -eq 0 ]
-  [[ "$output" == *".claude/rules/commits.md"* ]]
-  matches_canonical ".claude/rules/commits.md" "$REAL_REPO/claude-rules/commits.md"
+  [[ "$output" == *"swept"* ]]
+  [ ! -f "$PROJ/.claude/rules/commits.md" ]
 }
 
 @test "sync: missing rule is re-copied" {
@@ -276,3 +293,49 @@ install_team_overlay() {
   [ ! -f "$PROJ/.claude/rules/commits.md" ]
   [ ! -f "$PROJ/.claude/rules/testing.md" ]
 }
+
+# --- generic-rule de-duplication -------------------------------------------
+#
+# Generic rules live at ~/.claude/rules/ (symlinked by `make install`) and load
+# in every session. Copying them into each project as well made Claude Code
+# load them twice, and project copies take priority — so a stale project copy
+# silently overrode the fresh global one. The bundle now ships only its own
+# language rules and sweeps the duplicates it previously installed.
+
+@test "sync: sweeps generic rule copies that duplicate the global set" {
+  install_bundle python "$PROJ"
+  [ -f "$PROJ/.claude/rules/commits.md" ]
+  HOME_RULES="$(mktemp -d)" ; mkdir -p "$HOME_RULES/.claude/rules"
+  cp "$REAL_REPO/claude-rules"/*.md "$HOME_RULES/.claude/rules/"
+  run env HOME="$HOME_RULES" bash "$SCRIPT" "$PROJ"
+  [ "$status" -eq 0 ]
+  [ ! -f "$PROJ/.claude/rules/commits.md" ]
+  [ ! -f "$PROJ/.claude/rules/todo-format.md" ]
+}
+
+@test "sync: keeps the language bundle's own rules while sweeping generics" {
+  install_bundle python "$PROJ"
+  HOME_RULES="$(mktemp -d)" ; mkdir -p "$HOME_RULES/.claude/rules"
+  cp "$REAL_REPO/claude-rules"/*.md "$HOME_RULES/.claude/rules/"
+  run env HOME="$HOME_RULES" bash "$SCRIPT" "$PROJ"
+  [ "$status" -eq 0 ]
+  [ -f "$PROJ/.claude/rules/python-testing.md" ]
+}
+
+@test "sync: keeps a project-owned overlay rule the bundle does not own" {
+  install_bundle python "$PROJ"
+  printf '# Publishing\n\nApplies to: `**/*`\n' > "$PROJ/.claude/rules/publishing.md"
+  HOME_RULES="$(mktemp -d)" ; mkdir -p "$HOME_RULES/.claude/rules"
+  cp "$REAL_REPO/claude-rules"/*.md "$HOME_RULES/.claude/rules/"
+  run env HOME="$HOME_RULES" bash "$SCRIPT" "$PROJ"
+  [ "$status" -eq 0 ]
+  [ -f "$PROJ/.claude/rules/publishing.md" ]
+}
+
+@test "sync: does NOT sweep when the global rule is absent (nothing takes over)" {
+  install_bundle python "$PROJ"
+  HOME_RULES="$(mktemp -d)"   # no ~/.claude/rules/ at all
+  run env HOME="$HOME_RULES" bash "$SCRIPT" "$PROJ"
+  [ "$status" -eq 0 ]
+  [ -f "$PROJ/.claude/rules/commits.md" ]
+}
-- 
cgit v1.2.3