fix(v0.9.11): retire rule copying — hook injection is the sole rule mechanism

Closes the stale-rules gap: init-copied rules in .claude/rules/ never updated
on plugin upgrade and (since v0.9.9) duplicated/contradicted hook-injected
rules while bypassing maturity gating.

- /add:init Phase 2.5: no longer copies rules; detects + offers removal of
  leftovers from older inits (adoption-mode flow likewise stops copying)
- load-rules.sh: per-session warning for stale ADD copies (plain + add-
  prefixed; user-authored rules ignored) — +2 loader tests
- migration hop 0.9.10→0.9.11 with new remove_stale_rule_copies action
  (confirm-once, backup-before-delete, defined in version-migration.md)

Reported-by: Tomasz Dmitruk <@tdmitruk>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: MountainUnicorn

.add/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://github.com/MountainUnicorn/add/config.schema.json",
-  "version": "0.9.10",
+  "version": "0.9.11",
   "project": {
     "name": "ADD",
     "description": "Agent Driven Development \u2014 Claude Code plugin implementing an AI-native SDLC methodology",

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to ADD are documented here. Format loosely follows [Keep a C
 
 For commit-level detail see `git log`.
 
+## [0.9.11] — 2026-07-16
+
+Closes the stale-rules gap reported by Tomasz Dmitruk ([@tdmitruk](https://github.com/tdmitruk)): `/add:init` used to copy 10 ADD rules into the consumer project's `.claude/rules/`, where they auto-loaded forever at the version they were copied — never updated by plugin upgrades, and (since v0.9.9) duplicating and eventually contradicting the fresh rules the SessionStart hook injects. Copies also bypassed maturity gating entirely.
+
+### Changed
+
+- **Rule copying is retired.** The SessionStart hook (`load-rules.sh`) is the sole rule-distribution mechanism — always current with the installed plugin, maturity-gated, zero drift. `/add:init` Phase 2.5 no longer writes to `.claude/rules/`; it now only detects leftovers from older inits and offers a batched removal. The adoption-mode "Handling Existing Rules" flow likewise stops copying — user-authored rules are analyzed for overlap but never replaced by file copies.
+
+### Added
+
+- **Stale-copy warning** — `load-rules.sh` flags files in `.claude/rules/` matching plugin rule names (incl. `add-` prefixed) every session until they're removed, so the conflict is visible instead of silent (+2 loader tests).
+- **Migration hop 0.9.10 → 0.9.11** with a new `remove_stale_rule_copies` action (defined in `version-migration.md`): lists matches, requires one explicit user confirmation, backs up before deleting, never touches user-authored rules.
+
 ## [0.9.10] — 2026-07-12
 
 Dedup + hygiene release closing the three-release token-audit arc (v0.9.8 correctness → v0.9.9 token architecture → v0.9.10 slimming). The five heaviest skills lose ~35–45% of their lines to extraction; security patterns lose their false-positive noise; the hooks and CI lose their soft spots.

CONTRIBUTORS.md

@@ -12,7 +12,7 @@ Thank you to everyone who helps make ADD better.
 - **Caleb Dunn** ([@finish06](https://github.com/finish06)) — `/add:docs` skill with archetype-aware discovery. Generates architecture diagrams, API docs, and README drift detection for any project type (web APIs, libraries, CLIs, data pipelines, monorepos). Validated against Home Assistant core and personal projects. (v0.6.0)
 - **Piotr Pawluk** ([@piotrpawluk](https://github.com/piotrpawluk)) — `/add:roadmap`, `/add:milestone`, and `/add:promote` skills. Fills the milestone/maturity workflow gap: interactive roadmap horizon management, tactical milestone operations (list/switch/split/rescope), and evidence-based maturity promotion with 14-category gap analysis. (v0.6.0)
 - **David Giambarresi** ([@dgiambarresi](https://github.com/dgiambarresi)) — `/add:ux` skill: a design sign-off gate before implementation. Iterates on wireframes with the human and blocks UI feature implementation at Alpha+ without an approved UX artifact. Prevents the most expensive class of rework: building the right thing wrong. (v0.6.0)
-- **Tomasz** ([@tdmitruk](https://github.com/tdmitruk)) — README plugin update instructions (v0.7.3); learnings optimization with hook-driven pre-filtering and `/add:learnings` skill (v0.8.0). Context-window reduction via pre-filtered active views and archival system — 62-82% token savings as learnings accumulate.
+- **Tomasz** ([@tdmitruk](https://github.com/tdmitruk)) — README plugin update instructions (v0.7.3); learnings optimization with hook-driven pre-filtering and `/add:learnings` skill (v0.8.0). Context-window reduction via pre-filtered active views and archival system — 62-82% token savings as learnings accumulate. Reported the stale-rules gap — init-copied rules in `.claude/rules/` never updated on plugin upgrade and conflicted with hook-injected rules — fixed in v0.9.11 (rule copying retired).
 
 ## How to Contribute
 

README.md

@@ -13,7 +13,7 @@
   <br>
   <br>
   <a href="https://github.com/MountainUnicorn/add/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
-  <a href="#"><img src="https://img.shields.io/badge/version-0.9.10-brightgreen.svg" alt="Version"></a>
+  <a href="#"><img src="https://img.shields.io/badge/version-0.9.11-brightgreen.svg" alt="Version"></a>
   <a href="#"><img src="https://img.shields.io/badge/Claude_Code-plugin-blueviolet.svg" alt="Claude Code Plugin"></a>
 </p>
 

core/VERSION

@@ -1 +1 @@
-0.9.10
+0.9.11

core/rules/version-migration.md

@@ -29,6 +29,7 @@ On **every session start**, before any other work:
    - `restructure` — ensure markdown has required sections
    - `rename_fields` — move JSON fields to new keys
    - `remove_fields` — delete deprecated JSON fields
+   - `remove_stale_rule_copies` — find files in `.claude/rules/` whose basename matches a plugin rule in `${CLAUDE_PLUGIN_ROOT}/rules/` (also `add-` prefixed variants; user-authored files never match). List the matches and ask the user ONCE for confirmation; on yes, back each up per step 2, then delete. NEVER delete without explicit confirmation.
 
 4. **Update version** in config after all steps succeed. On partial failure, stay at last successful hop.
 

core/skills/init/SKILL.md

@@ -214,25 +214,26 @@ Then ask the 3 process questions from Section 3 (autonomy, quality mode, team si
 
 ### Handling Existing Rules
 
-For each ADD rule, check for equivalent coverage in `.claude/rules/`:
+ADD's rules are NOT copied into the project — they are injected each session by the plugin's SessionStart hook (`load-rules.sh`), maturity-gated, and update automatically with the plugin. `/add:init` never writes to `.claude/rules/`.
 
-- **If equivalent rule exists:** Ask the user:
+For each existing rule in the project's `.claude/rules/`, check for overlap with ADD's rule set:
+
+- **If an existing project rule covers similar ground as an ADD rule:** Ask the user:
   ```
   You have an existing rule: {existing_rule.md}
-  This covers similar ground as ADD's {add_rule}.
+  This covers similar ground as ADD's {add_rule} (injected automatically each session).
 
   Options:
-    a) Keep your existing rule, skip ADD's version
-    b) Use ADD's version (newer, aligned with ADD system)
-    c) Merge — I'll combine the best of both
+    a) Keep your rule as-is — it takes precedence where they conflict
+    b) Trim your rule to only the parts ADD doesn't cover
+    c) Remove your rule — rely on ADD's injected version
   ```
 
-- **If no overlap:** Add the ADD rule to `.claude/rules/` with a clean name (no `add-` prefix needed if there's no conflict).
-
-- **Naming convention:** If there's potential confusion with existing rules, ADD rules get an `add-` prefix:
-  - `add-human-collaboration.md`
-  - `add-learning-checkpoints.md`
-  - `add-quality-gates.md`
+- **If a stale ADD rule copy exists** (same name as a plugin rule, or `add-` prefixed — left behind by an ADD version before v0.9.11 that copied rules): recommend removal, since the hook now injects the current version and the copy will drift:
+  ```
+  .claude/rules/{name}.md matches an ADD plugin rule. ADD now injects rules
+  at session start — this copy is redundant and will go stale. Remove it?
+  ```
 
 ### Handling Existing Skills
 
@@ -485,60 +486,21 @@ tests/screenshots/errors/
 # tests/screenshots/{feature}/
 ```
 
-## Phase 2.5: Install ADD Methodology Rules
-
-Plugins cannot distribute rules directly. This phase copies ADD's rules into the consumer project's `.claude/rules/` directory so they take effect.
-
-### Step 2.5.1: Create Rules Directory
-
-```bash
-mkdir -p .claude/rules
-```
-
-### Step 2.5.2: Copy ADD Rules
+## Phase 2.5: Verify Rule Loading (no copying)
 
-For each of the 10 ADD rule files, read from the plugin and write to the consumer project:
-
-```
-Rule files to install:
-  1. spec-driven.md
-  2. tdd-enforcement.md
-  3. human-collaboration.md
-  4. agent-coordination.md
-  5. source-control.md
-  6. environment-awareness.md
-  7. quality-gates.md
-  8. learning.md
-  9. project-structure.md
-  10. maturity-lifecycle.md
-```
-
-For each rule file:
-
-1. Read `${CLAUDE_PLUGIN_ROOT}/rules/{name}.md`
-2. Check if `.claude/rules/{name}.md` already exists in the consumer project
-
-**If no conflict (file does not exist):**
-- Write the rule to `.claude/rules/{name}.md`
-- Track as "installed"
-
-**If conflict (file already exists):**
-- Use AskUserQuestion with 3 options:
-  ```
-  You already have a rule at .claude/rules/{name}.md.
-  ADD also provides a rule with this name.
-  ```
-  - "Keep existing — skip ADD's version"
-  - "Use ADD's version — overwrite mine"
-  - "Install ADD's version with `add-` prefix (as .claude/rules/add-{name}.md)"
-- Track the user's choice for each conflict
+ADD rules are NOT copied into the project. The plugin's SessionStart hook (`load-rules.sh`) injects the active rule set every session, gated by the project's maturity level — rules stay current with the plugin and never drift. (Versions before v0.9.11 copied 10 rules into `.claude/rules/`; that mechanism is retired because copies went stale and, after v0.9.9, duplicated the hook injection.)
 
-### Step 2.5.3: Track Results
+This phase only checks for leftovers:
 
-Maintain a results summary for Phase 5:
-- **Installed:** rules written without conflict
-- **Skipped:** rules the user chose to keep their existing version
-- **Prefixed:** rules installed with `add-` prefix to avoid conflict
+1. If `.claude/rules/` exists, list its files and compare basenames against `${CLAUDE_PLUGIN_ROOT}/rules/` (also match `add-` prefixed variants).
+2. For each match — a stale ADD copy from an older init — ask the user once (batch, not per-file):
+   ```
+   Found {N} ADD rule copies in .claude/rules/ from an earlier ADD version:
+   {list}
+   ADD now injects current rules at session start, so these are redundant
+   and will go stale. Remove them? (user-authored rules are untouched)
+   ```
+3. Track for the Phase 5 summary: **Removed** / **Kept** (user declined).
 
 ## Phase 3: Generate Configuration Files
 

core/templates/init-output-examples.md

@@ -72,7 +72,7 @@ WHAT ADD WOULD ADD (non-destructive):
 
 WHAT ADD WOULD PRESERVE (untouched):
   ✓ Your existing CLAUDE.md (ADD sections appended if you want them)
-  ✓ Your existing rules in .claude/rules/ (ADD rules added alongside)
+  ✓ Your existing rules in .claude/rules/ (untouched — ADD rules inject at session start)
   ✓ Your existing skills (ADD skills fill gaps only)
   ✓ Your existing specs and plans (preserved as-is)
   ✓ Your CI/CD pipelines and Docker configuration
@@ -95,7 +95,7 @@ NEWLY CREATED:
 
 ENHANCED:
   ✓ CLAUDE.md — ADD methodology section appended
-  ✓ .claude/rules/ — {N} new ADD rules added (your existing rules unchanged)
+  ✓ ADD rules — injected each session by the plugin (nothing copied; your .claude/rules/ unchanged)
   ✓ .claude/skills/ — {N} new ADD skills added (your existing skills unchanged)
 
 PRESERVED EXACTLY AS-IS:
@@ -142,11 +142,10 @@ PROJECT STRUCTURE:
 
 RULES INSTALLED:
   {for each installed rule:}
-  ✓ .claude/rules/{name}.md   — installed
+  ✓ ADD rules — injected at session start (maturity-gated, auto-updating)
   {for each skipped rule:}
-  ○ .claude/rules/{name}.md   — skipped (kept existing)
+  ○ stale ADD copies removed from .claude/rules/: {list or none}
   {for each prefixed rule:}
-  ✓ .claude/rules/add-{name}.md — installed with prefix
 
 CROSS-PROJECT:
   ✓ ~/.claude/add/profile.md          — your preferences (if created)

core/templates/migrations.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0.0",
-  "plugin_version": "0.9.10",
+  "plugin_version": "0.9.11",
   "migrations": [
     {
       "from": "0.1.0",
@@ -278,6 +278,20 @@
       "to": "0.9.10",
       "steps": [],
       "description": "v0.9.10 \u2014 dedup + hygiene release closing the token-audit arc. Heaviest skills slimmed ~35-45% (init 1093\u2192638, deploy 874\u2192557, verify 761\u2192432, cycle 659\u2192462, docs 582\u2192352 lines) via extraction to templates/ (init-interview, init-output-examples, commit-message, deploy-reference, cycle-plan, verify-report) and references/ (skill-epilogue, secrets-gate, docs-archetypes). Skill version literals normalized to {{VERSION}} (compile substitutes; can't drift). Injection patterns de-noised (ignore-previous noun now required, and a false negative on the canonical injection phrase was closed; base64 blob info@120+; system-heading anchored); audit-log redaction unified with the secret-patterns catalog; PASSWORD_KV case-insensitive; .secretsignore negations warn loudly. CHANGELOG reminder hook moved to PreToolUse (fires BEFORE push); post-write auto-fix now opt-in via hooks.autofix (default false \u2014 linters advise, don't rewrite). CI: marketplace-validate fails loudly instead of skipping green; new hooks-json + load-rules + compile suites in the guardrails matrix. Optional new consumer config key: hooks.autofix. Consumers using the stock .secretsignore template: negation lines were removed (they never worked)."
+    },
+    {
+      "from": "0.9.10",
+      "to": "0.9.11",
+      "steps": [
+        {
+          "file": ".claude/rules/",
+          "action": "remove_stale_rule_copies",
+          "params": {
+            "reason": "ADD versions before v0.9.11 copied rules into .claude/rules/ at init. Those copies auto-load stale content alongside (and eventually contradicting) the fresh rules the SessionStart hook injects since v0.9.9, and they bypass maturity gating. The injected rules are canonical."
+          }
+        }
+      ],
+      "description": "v0.9.11 \u2014 retire rule copying (closes the stale-rules gap reported by @tdmitruk). /add:init no longer writes ADD rules into .claude/rules/ (Phase 2.5 now only detects and offers to remove leftovers); load-rules.sh warns each session while stale copies remain; this migration hop offers a one-time confirmed cleanup. User-authored rules are never touched."
     }
   ]
 }

dist/codex/.agents/skills/add-agents-md/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: add-agents-md
-description: "[ADD v0.9.10] Generate or sync a portable AGENTS.md from ADD project state — writes, checks drift, or merges with hand-curated content"
+description: "[ADD v0.9.11] Generate or sync a portable AGENTS.md from ADD project state — writes, checks drift, or merges with hand-curated content"
 argument-hint: "[--write|--check|--merge|--import] [--dry-run]"
 ---
 
-# ADD AGENTS.md Skill v0.9.10
+# ADD AGENTS.md Skill v0.9.11
 
 Generate a portable [`AGENTS.md`](https://agents.md) at project root from the project's `.add/` state. `AGENTS.md` is the cross-tool open standard for project-level agent instructions — any agent (Claude Code, Cursor, Codex CLI, Windsurf, Amp, Devin, Copilot) will read it on session start. Publishing one lets mixed-toolchain teams respect the same invariants without installing ADD.