feat: add CLAUDE.md compliance as plan-checker Dimension 10

Add CLAUDE.md enforcement across the three core agents:
- gsd-plan-checker: new Dimension 10 verifies plans respect project
  conventions, forbidden patterns, and required tools from CLAUDE.md
- gsd-phase-researcher: outputs Project Constraints section from
  CLAUDE.md so planner can verify compliance
- gsd-executor: treats CLAUDE.md directives as hard constraints,
  with precedence over plan instructions

Includes 4 regression tests validating the new dimension and
enforcement directives across all three agents.

Closes #1260

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

agents/gsd-executor.md

@@ -35,6 +35,8 @@ Before executing, discover project context:
 5. Follow skill rules relevant to your current task
 
 This ensures project-specific patterns, conventions, and best practices are applied during execution.
+
+**CLAUDE.md enforcement:** If `./CLAUDE.md` exists, treat its directives as hard constraints during execution. Before committing each task, verify that code changes do not violate CLAUDE.md rules (forbidden patterns, required conventions, mandated tools). If a task action would contradict a CLAUDE.md directive, apply the CLAUDE.md rule — it takes precedence over plan instructions. Document any CLAUDE.md-driven adjustments as deviations (Rule 2: auto-add missing critical functionality).
 </project_context>
 
 <execution_flow>

agents/gsd-phase-researcher.md

@@ -40,6 +40,8 @@ Before researching, discover project context:
 5. Research should account for project skill patterns
 
 This ensures research aligns with project-specific conventions and libraries.
+
+**CLAUDE.md enforcement:** If `./CLAUDE.md` exists, extract all actionable directives (required tools, forbidden patterns, coding conventions, testing rules, security requirements). Include a `## Project Constraints (from CLAUDE.md)` section in RESEARCH.md listing these directives so the planner can verify compliance. Treat CLAUDE.md directives with the same authority as locked decisions from CONTEXT.md — research should not recommend approaches that contradict them.
 </project_context>
 
 <upstream_input>

agents/gsd-plan-checker.md

@@ -391,6 +391,50 @@ If FAIL: return to planner with specific fixes. Same revision loop as other dime
 
 **Severity:** WARNING for potential conflicts. BLOCKER if incompatible transforms on same data entity with no preservation mechanism.
 
+## Dimension 10: CLAUDE.md Compliance
+
+**Question:** Do plans respect project-specific conventions, constraints, and requirements from CLAUDE.md?
+
+**Process:**
+1. Read `./CLAUDE.md` in the working directory (already loaded in `<project_context>`)
+2. Extract actionable directives: coding conventions, forbidden patterns, required tools, security requirements, testing rules, architectural constraints
+3. For each directive, check if any plan task contradicts or ignores it
+4. Flag plans that introduce patterns CLAUDE.md explicitly forbids
+5. Flag plans that skip steps CLAUDE.md explicitly requires (e.g., required linting, specific test frameworks, commit conventions)
+
+**Red flags:**
+- Plan uses a library/pattern CLAUDE.md explicitly forbids
+- Plan skips a required step (e.g., CLAUDE.md says "always run X before Y" but plan omits X)
+- Plan introduces code style that contradicts CLAUDE.md conventions
+- Plan creates files in locations that violate CLAUDE.md's architectural constraints
+- Plan ignores security requirements documented in CLAUDE.md
+
+**Skip condition:** If no `./CLAUDE.md` exists in the working directory, output: "Dimension 10: SKIPPED (no CLAUDE.md found)" and move on.
+
+**Example — forbidden pattern:**
+```yaml
+issue:
+  dimension: claude_md_compliance
+  severity: blocker
+  description: "Plan uses Jest for testing but CLAUDE.md requires Vitest"
+  plan: "01"
+  task: 1
+  claude_md_rule: "Testing: Always use Vitest, never Jest"
+  plan_action: "Install Jest and create test suite..."
+  fix_hint: "Replace Jest with Vitest per project CLAUDE.md"
+```
+
+**Example — skipped required step:**
+```yaml
+issue:
+  dimension: claude_md_compliance
+  severity: warning
+  description: "Plan does not include lint step required by CLAUDE.md"
+  plan: "02"
+  claude_md_rule: "All tasks must run eslint before committing"
+  fix_hint: "Add eslint verification step to each task's <verify> block"
+```
+
 </verification_dimensions>
 
 <verification_process>
@@ -722,6 +766,7 @@ Plan verification complete when:
   - [ ] Deferred ideas not included in plans
 - [ ] Overall status determined (passed | issues_found)
 - [ ] Cross-plan data contracts checked (no conflicting transforms on shared data)
+- [ ] CLAUDE.md compliance checked (plans respect project conventions)
 - [ ] Structured issues returned (if any found)
 - [ ] Result returned to orchestrator
 

tests/agent-frontmatter.test.cjs

@@ -182,6 +182,57 @@ describe('AGENT: required frontmatter fields', () => {
   }
 });
 
+// ─── CLAUDE.md Compliance ───────────────────────────────────────────────────
+
+describe('CLAUDEMD: CLAUDE.md compliance enforcement', () => {
+  test('gsd-plan-checker has Dimension 10: CLAUDE.md Compliance', () => {
+    const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-plan-checker.md'), 'utf-8');
+    assert.ok(
+      content.includes('Dimension 10: CLAUDE.md Compliance'),
+      'gsd-plan-checker must have Dimension 10 for CLAUDE.md compliance checking'
+    );
+    assert.ok(
+      content.includes('claude_md_compliance'),
+      'gsd-plan-checker must use claude_md_compliance as dimension identifier'
+    );
+  });
+
+  test('gsd-phase-researcher has CLAUDE.md enforcement directive', () => {
+    const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-phase-researcher.md'), 'utf-8');
+    assert.ok(
+      content.includes('CLAUDE.md enforcement'),
+      'gsd-phase-researcher must enforce CLAUDE.md directives during research'
+    );
+    assert.ok(
+      content.includes('Project Constraints (from CLAUDE.md)'),
+      'gsd-phase-researcher must output a Project Constraints section from CLAUDE.md'
+    );
+  });
+
+  test('gsd-executor has CLAUDE.md enforcement directive', () => {
+    const content = fs.readFileSync(path.join(AGENTS_DIR, 'gsd-executor.md'), 'utf-8');
+    assert.ok(
+      content.includes('CLAUDE.md enforcement'),
+      'gsd-executor must enforce CLAUDE.md directives during execution'
+    );
+    assert.ok(
+      content.includes('CLAUDE.md rule — it takes precedence over plan instructions'),
+      'gsd-executor must specify CLAUDE.md precedence over plan instructions'
+    );
+  });
+
+  test('all three agents read CLAUDE.md in project_context', () => {
+    const agents = ['gsd-plan-checker', 'gsd-phase-researcher', 'gsd-executor'];
+    for (const agent of agents) {
+      const content = fs.readFileSync(path.join(AGENTS_DIR, agent + '.md'), 'utf-8');
+      assert.ok(
+        content.includes('Read `./CLAUDE.md`'),
+        `${agent} must read ./CLAUDE.md in project_context section`
+      );
+    }
+  });
+});
+
 // ─── Discussion Log ──────────────────────────────────────────────────────────
 
 describe('DISCUSS: discussion log generation', () => {