refactor: replace InjectSessionInstructions with plugin-bundled rule files

Author: cowwoc

.claude/cat/issues/v2/v2.1/refactor-plugin-bundled-rules/PLAN.md

@@ -82,8 +82,9 @@ None — architectural refactor
 - Extend `RulesDiscovery.getCatRulesForAudience()` to accept a list of source directories instead of one:
   - Files: `RulesDiscovery.java`
   - New signature: `getCatRulesForAudience(List<Path> rulesDirs, ...)` or overload that merges results
-  - Discover rules from all directories, merge, then filter by audience
-  - Deduplicate if same filename appears in both sources (project-local overrides plugin-bundled)
+  - Discover rules from all directories, concatenate (plugin rules first, project-local second), then
+    filter by audience
+  - No filename-based deduplication — if the same filename exists in both sources, both are included
 
 - Update `InjectRulesToMainAgent` to read from both sources:
   - Files: `InjectRulesToMainAgent.java`
@@ -100,7 +101,7 @@ None — architectural refactor
 - Add/update tests:
   - Files: test classes for `InjectRulesToMainAgent`, `InjectRulesToSubAgent`, `RulesDiscovery`
   - Test: plugin rules directory is read and content injected
-  - Test: project rules and plugin rules are merged correctly
+  - Test: plugin rules and project rules are concatenated in order (plugin first, project second)
   - Test: audience filtering works across both sources
   - Test: missing plugin rules directory is handled gracefully
   - Test: session ID is still injected (by existing EchoSessionId, not by plugin rules)

.claude/cat/issues/v2/v2.1/refactor-plugin-bundled-rules/STATE.md

@@ -1,6 +1,8 @@
 # State
 
-- **Status:** open
-- **Progress:** 0%
+- **Status:** closed
+- **Resolution:** implemented
+- **Progress:** 100%
 - **Dependencies:** [refactor-rules-injection-classes]
 - **Blocks:** []
+- **Target Branch:** v2.1

.claude/rules/license-header.md

@@ -94,6 +94,7 @@ The following files do not require license headers:
 - `*.xml` files (configuration files, no semantic code)
 - All `SKILL.md` files in plugin skills (`first-use.md` companions are NOT exempt and require headers)
 - All `*.md` files in `plugin/agents/` (injected into subagent context as prompts; same rationale as SKILL.md)
+- All `*.md` files in `plugin/rules/` (injected verbatim into agent context on every session; license headers waste context tokens)
 - Files in `.claude/cat/` (planning artifacts, config, runtime data)
 - `LICENSE.md` itself
 - Build artifacts (`target/`, `node_modules/`, etc.)

client/src/main/java/io/github/cowwoc/cat/hooks/SessionStartHook.java

@@ -17,7 +17,6 @@
 import io.github.cowwoc.cat.hooks.session.InjectMainAgentRules;
 import io.github.cowwoc.cat.hooks.session.InjectCriticalThinking;
 import io.github.cowwoc.cat.hooks.session.InjectEnv;
-import io.github.cowwoc.cat.hooks.session.InjectSessionInstructions;
 import io.github.cowwoc.cat.hooks.session.InjectSkillListing;
 import io.github.cowwoc.cat.hooks.session.RestoreCwdAfterCompaction;
 import io.github.cowwoc.cat.hooks.session.RestoreWorktreeOnResume;
@@ -53,7 +52,6 @@ public SessionStartHook(JvmScope scope)
       new WarnUnknownTerminal(scope),
       new EchoSessionId(),
       new CheckRetrospectiveDue(scope),
-      new InjectSessionInstructions(),
       new InjectMainAgentRules(scope),
       new InjectSkillListing(scope),
       new InjectCriticalThinking(),

client/src/main/java/io/github/cowwoc/cat/hooks/session/InjectMainAgentRules.java

@@ -16,10 +16,13 @@
 import static io.github.cowwoc.requirements13.java.DefaultJavaValidators.requireThat;
 
 /**
- * Injects audience-filtered rules from {@code .claude/cat/rules/} into main agent context.
+ * Injects audience-filtered rules from plugin-bundled and project-local rule directories into main
+ * agent context.
  * <p>
- * Discovers all rule files, filters to those with {@code mainAgent: true}, applies any {@code paths}
- * restrictions, and injects matching content as additional context.
+ * Discovers all rule files from both {@code ${CLAUDE_PLUGIN_ROOT}/rules/} (plugin-bundled) and
+ * {@code ${projectDir}/.claude/cat/rules/} (project-local), concatenates them (plugin-bundled
+ * first, project-local second), filters to those with {@code mainAgent: true}, applies any
+ * {@code paths} restrictions, and injects matching content as additional context.
  */
 public final class InjectMainAgentRules implements SessionStartHandler
 {
@@ -39,6 +42,13 @@ public InjectMainAgentRules(JvmScope scope)
 
   /**
    * Discovers and injects CAT rules applicable to the main agent.
+   * <p>
+   * Reads from two sources in order (plugin-bundled first, project-local second):
+   * <ol>
+   *   <li>{@code ${CLAUDE_PLUGIN_ROOT}/rules/} — plugin-bundled rules</li>
+   *   <li>{@code ${projectDir}/.claude/cat/rules/} — project-local rules</li>
+   * </ol>
+   * Both sources are concatenated; no filename-based deduplication is performed.
    *
    * @param input the hook input
    * @return a result with the injected rules content, or empty if no rules apply
@@ -49,11 +59,12 @@ public Result handle(HookInput input)
   {
     requireThat(input, "input").isNotNull();
 
-    Path rulesDir = scope.getClaudeProjectDir().resolve(".claude/cat/rules");
+    Path pluginRulesDir = scope.getClaudePluginRoot().resolve("rules");
+    Path projectRulesDir = scope.getClaudeProjectDir().resolve(".claude/cat/rules");
     // Rules with paths: restrictions are injected dynamically by InjectPathRules (PreToolUse hook)
     // when matching files are accessed. Only non-paths rules are injected here at session start.
-    String content = RulesDiscovery.getCatRulesForAudience(rulesDir, scope.getYamlMapper(),
-      RulesDiscovery::filterForMainAgent, List.of());
+    String content = RulesDiscovery.getCatRulesForAudience(List.of(pluginRulesDir, projectRulesDir),
+      scope.getYamlMapper(), RulesDiscovery::filterForMainAgent, List.of());
     if (content.isBlank())
       return Result.empty();