@opengsd/get-shit-done-redux 1.0.0

package/sdk/src/query/validate.test.ts

@@ -0,0 +1,924 @@
+/**
+ * Tests for validation query handlers — verifyKeyLinks, validateConsistency, validateHealth.
+ *
+ * Uses temp directories with fixture files to test verification logic.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, mkdir, rm, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir, homedir } from 'node:os';
+import { GSDError } from '../errors.js';
+
+import { verifyKeyLinks, validateConsistency, validateHealth, regexForKeyLinkPattern } from './validate.js';
+
+// ─── regexForKeyLinkPattern ────────────────────────────────────────────────
+
+describe('regexForKeyLinkPattern', () => {
+  it('preserves normal regex patterns used in key_links', () => {
+    const re = regexForKeyLinkPattern('import.*foo.*from.*target');
+    expect(re.test("import { foo } from './target.js';")).toBe(true);
+  });
+
+  it('falls back to literal match for nested-quantifier patterns', () => {
+    const re = regexForKeyLinkPattern('(a+)+');
+    expect(re.source).toContain('\\');
+  });
+});
+
+// ─── verifyKeyLinks ────────────────────────────────────────────────────────
+
+describe('verifyKeyLinks', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-validate-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('throws GSDError Validation when no args', async () => {
+    let caught: unknown;
+    try {
+      await verifyKeyLinks([], tmpDir);
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(GSDError);
+    expect((caught as GSDError).classification).toBe('validation');
+  });
+
+  it('returns all_verified true when pattern found in source', async () => {
+    // Create source file with an import statement
+    await writeFile(join(tmpDir, 'source.ts'), "import { foo } from './target.js';");
+    await writeFile(join(tmpDir, 'target.ts'), 'export const foo = 1;');
+
+    // Create plan with key_links
+    const planContent = `---
+phase: 01
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+
+must_haves:
+  key_links:
+    - from: source.ts
+      to: target.ts
+      via: "import foo"
+      pattern: "import.*foo.*from.*target"
+---
+
+# Plan
+`;
+    await writeFile(join(tmpDir, 'plan.md'), planContent);
+
+    const result = await verifyKeyLinks(['plan.md'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.all_verified).toBe(true);
+    expect(data.verified).toBe(1);
+    expect(data.total).toBe(1);
+    const links = data.links as Array<Record<string, unknown>>;
+    expect(links[0].detail).toBe('Pattern found in source');
+  });
+
+  it('returns verified true with "Pattern found in target" when not in source but in target', async () => {
+    await writeFile(join(tmpDir, 'source.ts'), 'const x = 1;');
+    await writeFile(join(tmpDir, 'target.ts'), "import { foo } from './other.js';");
+
+    const planContent = `---
+phase: 01
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+
+must_haves:
+  key_links:
+    - from: source.ts
+      to: target.ts
+      via: "import foo"
+      pattern: "import.*foo"
+---
+
+# Plan
+`;
+    await writeFile(join(tmpDir, 'plan.md'), planContent);
+
+    const result = await verifyKeyLinks(['plan.md'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const links = data.links as Array<Record<string, unknown>>;
+    expect(links[0].verified).toBe(true);
+    expect(links[0].detail).toBe('Pattern found in target');
+  });
+
+  it('returns verified false when pattern not found in source or target', async () => {
+    await writeFile(join(tmpDir, 'source.ts'), 'const x = 1;');
+    await writeFile(join(tmpDir, 'target.ts'), 'const y = 2;');
+
+    const planContent = `---
+phase: 01
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+
+must_haves:
+  key_links:
+    - from: source.ts
+      to: target.ts
+      via: "import foo"
+      pattern: "import.*foo"
+---
+
+# Plan
+`;
+    await writeFile(join(tmpDir, 'plan.md'), planContent);
+
+    const result = await verifyKeyLinks(['plan.md'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.all_verified).toBe(false);
+    const links = data.links as Array<Record<string, unknown>>;
+    expect(links[0].verified).toBe(false);
+  });
+
+  it('returns Source file not found when source missing', async () => {
+    await writeFile(join(tmpDir, 'target.ts'), 'export const foo = 1;');
+
+    const planContent = `---
+phase: 01
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+
+must_haves:
+  key_links:
+    - from: missing.ts
+      to: target.ts
+      via: "import"
+      pattern: "import"
+---
+
+# Plan
+`;
+    await writeFile(join(tmpDir, 'plan.md'), planContent);
+
+    const result = await verifyKeyLinks(['plan.md'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const links = data.links as Array<Record<string, unknown>>;
+    expect(links[0].detail).toBe('Source file not found');
+    expect(links[0].verified).toBe(false);
+  });
+
+  it('checks target reference in source when no pattern specified', async () => {
+    await writeFile(join(tmpDir, 'source.ts'), "import { foo } from './target.ts';");
+    await writeFile(join(tmpDir, 'target.ts'), 'export const foo = 1;');
+
+    const planContent = `---
+phase: 01
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+
+must_haves:
+  key_links:
+    - from: source.ts
+      to: target.ts
+      via: "import"
+---
+
+# Plan
+`;
+    await writeFile(join(tmpDir, 'plan.md'), planContent);
+
+    const result = await verifyKeyLinks(['plan.md'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const links = data.links as Array<Record<string, unknown>>;
+    expect(links[0].verified).toBe(true);
+    expect(links[0].detail).toBe('Target referenced in source');
+  });
+
+  it('reports invalid regex like gsd-tools.cjs (try/catch on new RegExp)', async () => {
+    await writeFile(join(tmpDir, 'source.ts'), 'const x = 1;');
+    await writeFile(join(tmpDir, 'target.ts'), 'const y = 2;');
+
+    const planContent = `---
+phase: 01
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+
+must_haves:
+  key_links:
+    - from: source.ts
+      to: target.ts
+      via: "bad regex"
+      pattern: "[invalid"
+---
+
+# Plan
+`;
+    await writeFile(join(tmpDir, 'plan.md'), planContent);
+
+    const result = await verifyKeyLinks(['plan.md'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const links = data.links as Array<Record<string, unknown>>;
+    expect(links[0].verified).toBe(false);
+    expect((links[0].detail as string)).toMatch(/Invalid regex pattern/);
+  });
+
+  it('returns error when no must_haves.key_links in plan', async () => {
+    const planContent = `---
+phase: 01
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified: []
+autonomous: true
+---
+
+# Plan
+`;
+    await writeFile(join(tmpDir, 'plan.md'), planContent);
+
+    const result = await verifyKeyLinks(['plan.md'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.error).toBe('No must_haves.key_links found in frontmatter');
+  });
+});
+
+// ─── validateConsistency ──────────────────────────────────────────────────
+
+describe('validateConsistency', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-consistency-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  /** Helper: create a .planning directory structure */
+  async function createPlanning(opts: {
+    roadmap?: string;
+    phases?: Array<{ dir: string; plans?: string[]; summaries?: string[]; planContents?: Record<string, string> }>;
+    config?: Record<string, unknown>;
+  }): Promise<void> {
+    const planning = join(tmpDir, '.planning');
+    await mkdir(planning, { recursive: true });
+
+    if (opts.roadmap !== undefined) {
+      await writeFile(join(planning, 'ROADMAP.md'), opts.roadmap);
+    }
+
+    if (opts.config) {
+      await writeFile(join(planning, 'config.json'), JSON.stringify(opts.config));
+    }
+
+    if (opts.phases) {
+      const phasesDir = join(planning, 'phases');
+      await mkdir(phasesDir, { recursive: true });
+      for (const phase of opts.phases) {
+        const phaseDir = join(phasesDir, phase.dir);
+        await mkdir(phaseDir, { recursive: true });
+        if (phase.plans) {
+          for (const plan of phase.plans) {
+            const content = phase.planContents?.[plan] ?? `---\nphase: ${phase.dir}\nplan: 01\ntype: execute\nwave: 1\ndepends_on: []\nfiles_modified: []\nautonomous: true\n---\n\n# Plan\n`;
+            await writeFile(join(phaseDir, plan), content);
+          }
+        }
+        if (phase.summaries) {
+          for (const summary of phase.summaries) {
+            await writeFile(join(phaseDir, summary), '# Summary\n');
+          }
+        }
+      }
+    }
+  }
+
+  it('returns passed true when ROADMAP phases match disk', async () => {
+    await createPlanning({
+      roadmap: '# Roadmap\n\n## Phase 1: Foundation\n\nGoal here.\n\n## Phase 2: Features\n\nMore goals.\n',
+      phases: [
+        { dir: '01-foundation', plans: ['01-01-PLAN.md'], summaries: ['01-01-SUMMARY.md'] },
+        { dir: '02-features', plans: ['02-01-PLAN.md'], summaries: ['02-01-SUMMARY.md'] },
+      ],
+      config: { phase_naming: 'sequential' },
+    });
+
+    const result = await validateConsistency([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.passed).toBe(true);
+    expect((data.errors as string[]).length).toBe(0);
+    expect((data.warnings as string[]).length).toBe(0);
+  });
+
+  it('warns when phase in ROADMAP but not on disk', async () => {
+    await createPlanning({
+      roadmap: '# Roadmap\n\n## Phase 1: Foundation\n\n## Phase 2: Features\n\n## Phase 3: Polish\n',
+      phases: [
+        { dir: '01-foundation', plans: ['01-01-PLAN.md'] },
+        { dir: '02-features', plans: ['02-01-PLAN.md'] },
+      ],
+      config: { phase_naming: 'sequential' },
+    });
+
+    const result = await validateConsistency([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as string[];
+    expect(warnings.some(w => w.includes('Phase 3') && w.includes('ROADMAP') && w.includes('no directory'))).toBe(true);
+  });
+
+  it('warns when phase on disk but not in ROADMAP', async () => {
+    await createPlanning({
+      roadmap: '# Roadmap\n\n## Phase 1: Foundation\n',
+      phases: [
+        { dir: '01-foundation', plans: ['01-01-PLAN.md'] },
+        { dir: '02-features', plans: ['02-01-PLAN.md'] },
+      ],
+      config: { phase_naming: 'sequential' },
+    });
+
+    const result = await validateConsistency([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as string[];
+    expect(warnings.some(w => w.includes('02') && w.includes('disk') && w.includes('not in ROADMAP'))).toBe(true);
+  });
+
+  it('warns on gap in sequential phase numbering', async () => {
+    await createPlanning({
+      roadmap: '# Roadmap\n\n## Phase 1: Foundation\n\n## Phase 3: Polish\n',
+      phases: [
+        { dir: '01-foundation', plans: ['01-01-PLAN.md'] },
+        { dir: '03-polish', plans: ['03-01-PLAN.md'] },
+      ],
+      config: { phase_naming: 'sequential' },
+    });
+
+    const result = await validateConsistency([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as string[];
+    expect(warnings.some(w => w.includes('Gap in phase numbering'))).toBe(true);
+  });
+
+  it('warns on plan numbering gap within phase', async () => {
+    await createPlanning({
+      roadmap: '# Roadmap\n\n## Phase 1: Foundation\n',
+      phases: [
+        { dir: '01-foundation', plans: ['01-01-PLAN.md', '01-03-PLAN.md'] },
+      ],
+      config: { phase_naming: 'sequential' },
+    });
+
+    const result = await validateConsistency([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as string[];
+    expect(warnings.some(w => w.includes('Gap in plan numbering'))).toBe(true);
+  });
+
+  it('warns on summary without matching plan', async () => {
+    await createPlanning({
+      roadmap: '# Roadmap\n\n## Phase 1: Foundation\n',
+      phases: [
+        { dir: '01-foundation', plans: ['01-01-PLAN.md'], summaries: ['01-01-SUMMARY.md', '01-02-SUMMARY.md'] },
+      ],
+      config: { phase_naming: 'sequential' },
+    });
+
+    const result = await validateConsistency([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as string[];
+    expect(warnings.some(w => w.includes('Summary') && w.includes('no matching PLAN'))).toBe(true);
+  });
+
+  it('warns when plan missing wave in frontmatter', async () => {
+    const noWavePlan = `---\nphase: 01\nplan: 01\ntype: execute\ndepends_on: []\nfiles_modified: []\nautonomous: true\n---\n\n# Plan\n`;
+    await createPlanning({
+      roadmap: '# Roadmap\n\n## Phase 1: Foundation\n',
+      phases: [
+        { dir: '01-foundation', plans: ['01-01-PLAN.md'], planContents: { '01-01-PLAN.md': noWavePlan } },
+      ],
+      config: { phase_naming: 'sequential' },
+    });
+
+    const result = await validateConsistency([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as string[];
+    expect(warnings.some(w => w.includes('wave') && w.includes('frontmatter'))).toBe(true);
+  });
+
+  it('returns passed false with error when ROADMAP.md missing', async () => {
+    await createPlanning({
+      phases: [{ dir: '01-foundation', plans: ['01-01-PLAN.md'] }],
+      config: { phase_naming: 'sequential' },
+    });
+
+    const result = await validateConsistency([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.passed).toBe(false);
+    expect((data.errors as string[])).toContain('ROADMAP.md not found');
+  });
+});
+
+// ─── validateHealth ─────────────────────────────────────────────────────────
+
+describe('validateHealth', () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), 'gsd-health-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  /** Helper: create a healthy .planning directory structure */
+  async function createHealthyPlanning(): Promise<void> {
+    const planning = join(tmpDir, '.planning');
+    await mkdir(join(planning, 'phases', '01-foundation'), { recursive: true });
+
+    await writeFile(join(planning, 'PROJECT.md'), '# Project\n\n## What This Is\n\nA project.\n\n## Core Value\n\nValue here.\n\n## Requirements\n\n- Req 1\n');
+    await writeFile(join(planning, 'ROADMAP.md'), '# Roadmap\n\n## Phase 1: Foundation\n\nGoals.\n');
+    await writeFile(join(planning, 'STATE.md'), '---\nstatus: executing\n---\n\n# State\n\n**Current Phase:** 1\n**Status:** executing\n');
+    await writeFile(join(planning, 'config.json'), JSON.stringify({
+      model_profile: 'balanced',
+      workflow: { nyquist_validation: true },
+    }, null, 2));
+
+    await writeFile(join(planning, 'phases', '01-foundation', '01-01-PLAN.md'), '---\nphase: 01\nplan: 01\ntype: execute\nwave: 1\ndepends_on: []\nfiles_modified: []\nautonomous: true\n---\n\n# Plan\n');
+    await writeFile(join(planning, 'phases', '01-foundation', '01-01-SUMMARY.md'), '# Summary\n');
+  }
+
+  it('returns healthy status when all files present', async () => {
+    await createHealthyPlanning();
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.status).toBe('healthy');
+    expect((data.errors as unknown[]).length).toBe(0);
+    expect((data.warnings as unknown[]).length).toBe(0);
+  });
+
+  it('returns broken with E001 when no .planning/ directory', async () => {
+    // tmpDir has no .planning/ — already the case
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.status).toBe('broken');
+    const errors = data.errors as Array<Record<string, unknown>>;
+    expect(errors.some(e => e.code === 'E001')).toBe(true);
+  });
+
+  it('returns error E002 when PROJECT.md missing', async () => {
+    await createHealthyPlanning();
+    const { unlink } = await import('node:fs/promises');
+    await unlink(join(tmpDir, '.planning', 'PROJECT.md'));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const errors = data.errors as Array<Record<string, unknown>>;
+    expect(errors.some(e => e.code === 'E002')).toBe(true);
+  });
+
+  it('returns error E003 when ROADMAP.md missing', async () => {
+    await createHealthyPlanning();
+    const { unlink } = await import('node:fs/promises');
+    await unlink(join(tmpDir, '.planning', 'ROADMAP.md'));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const errors = data.errors as Array<Record<string, unknown>>;
+    expect(errors.some(e => e.code === 'E003')).toBe(true);
+  });
+
+  it('returns error E004 when STATE.md missing (repairable)', async () => {
+    await createHealthyPlanning();
+    const { unlink } = await import('node:fs/promises');
+    await unlink(join(tmpDir, '.planning', 'STATE.md'));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const errors = data.errors as Array<Record<string, unknown>>;
+    const e004 = errors.find(e => e.code === 'E004');
+    expect(e004).toBeDefined();
+    expect(e004!.repairable).toBe(true);
+  });
+
+  it('returns error E005 when config.json has invalid JSON (repairable)', async () => {
+    await createHealthyPlanning();
+    await writeFile(join(tmpDir, '.planning', 'config.json'), '{invalid json!!!');
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const errors = data.errors as Array<Record<string, unknown>>;
+    const e005 = errors.find(e => e.code === 'E005');
+    expect(e005).toBeDefined();
+    expect(e005!.repairable).toBe(true);
+  });
+
+  it('returns warning W003 when config.json missing (repairable)', async () => {
+    await createHealthyPlanning();
+    const { unlink } = await import('node:fs/promises');
+    await unlink(join(tmpDir, '.planning', 'config.json'));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w003 = warnings.find(w => w.code === 'W003');
+    expect(w003).toBeDefined();
+    expect(w003!.repairable).toBe(true);
+  });
+
+  // Regression: #2633 — W002 must consult ROADMAP.md (current + shipped
+  // milestones) for valid phase numbers, not only on-disk phase dirs. After
+  // `phases clear` at the start of a new milestone, STATE.md can legitimately
+  // reference future phases (current milestone) and history phases (shipped
+  // milestones) that no longer have a corresponding disk directory.
+  it('does not emit W002 for roadmap-valid future or history phase refs (#2633)', async () => {
+    const planning = join(tmpDir, '.planning');
+    await mkdir(join(planning, 'phases', '03-alpha'), { recursive: true });
+    await mkdir(join(planning, 'phases', '04-beta'), { recursive: true });
+
+    await writeFile(join(planning, 'PROJECT.md'), '# Project\n\n## What This Is\n\nA project.\n\n## Core Value\n\nValue here.\n\n## Requirements\n\n- Req 1\n');
+    await writeFile(join(planning, 'ROADMAP.md'), [
+      '# Roadmap', '',
+      '## v1.0: Shipped ✅ SHIPPED', '',
+      '### Phase 1: Origin', '**Goal:** O', '',
+      '### Phase 2: Continuation', '**Goal:** C', '',
+      '## v1.1: Current', '',
+      '### Phase 3: Alpha', '**Goal:** A', '',
+      '### Phase 4: Beta', '**Goal:** B', '',
+      '### Phase 5: Gamma', '**Goal:** C', '',
+    ].join('\n'));
+    await writeFile(join(planning, 'STATE.md'), [
+      '---', 'milestone: v1.1', 'milestone_name: Current', 'status: executing', '---', '',
+      '# State', '',
+      '**Current Phase:** 4',
+      '**Next:** Phase 5',
+      '',
+      '## Accumulated Context',
+      '- Decision from Phase 1',
+      '- Follow-up from Phase 2',
+    ].join('\n'));
+    await writeFile(join(planning, 'config.json'), JSON.stringify({
+      model_profile: 'balanced',
+      workflow: { nyquist_validation: true },
+    }, null, 2));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w002s = warnings.filter(w => w.code === 'W002');
+    expect(w002s).toEqual([]);
+  });
+
+  // Regression: #3652 — after /gsd:complete-milestone, STATE.md body retains
+  // historical phase references across milestones while their `#### Phase N:`
+  // headings in ROADMAP.md are collapsed into <details> blocks and the phase
+  // dirs are moved to `milestones/vX.Y-phases/`. The heading-scan regex misses
+  // collapsed phases, so W002 used to fire for every archived phase mentioned
+  // in narrative prose. Cross-referencing the milestones archive suppresses it.
+  it('does not emit W002 for phase refs that live in milestones archive (#3652)', async () => {
+    const planning = join(tmpDir, '.planning');
+    await mkdir(join(planning, 'phases', '23-current'), { recursive: true });
+    await mkdir(join(planning, 'milestones', 'v1.3a-phases', '12-old-phase'), { recursive: true });
+    for (const n of ['19-alpha', '20-beta', '21-gamma', '22-delta']) {
+      await mkdir(join(planning, 'milestones', 'v1.3b-phases', n), { recursive: true });
+    }
+
+    await writeFile(join(planning, 'PROJECT.md'), '# Project\n\n## What This Is\n\nA project.\n\n## Core Value\n\nValue here.\n\n## Requirements\n\n- Req 1\n');
+    await writeFile(join(planning, 'ROADMAP.md'), [
+      '# Roadmap', '',
+      '<details><summary>v1.3a: Shipped</summary>', '',
+      '- Phase 12: archived', '',
+      '</details>', '',
+      '<details><summary>v1.3b: Shipped</summary>', '',
+      '- Phase 19, 20, 21, 22: archived', '',
+      '</details>', '',
+      '## v1.4: Current', '',
+      '### Phase 23: Current work', '**Goal:** stuff', '',
+    ].join('\n'));
+    await writeFile(join(planning, 'STATE.md'), [
+      '---', 'milestone: v1.4', 'milestone_name: Current', 'status: executing', '---', '',
+      '# State', '',
+      '**Current Phase:** 23', '',
+      '## Recent', '- Phase 19 shipped', '- Phase 20 shipped', '- Phase 21 shipped', '- Phase 22 shipped',
+      '', '## Decisions', '- Decision from Phase 12 still applies',
+      '', '## Deferred Items', '- Note from Phase 19',
+    ].join('\n'));
+    await writeFile(join(planning, 'config.json'), JSON.stringify({
+      model_profile: 'balanced',
+      workflow: { nyquist_validation: true },
+    }, null, 2));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w002s = warnings.filter(w => w.code === 'W002');
+    expect(w002s).toEqual([]);
+  });
+
+  // Regression: #3652 — project-code-prefixed archive dirs (e.g. `CK-64-...`)
+  // must also be recognised as valid phase declarations. The shared
+  // PHASE_TOKEN_FROM_DIR_RE / MILESTONE_ARCHIVE_DIR_RE constants handle the
+  // prefix; an ad-hoc /^\d+/-style regex here would miss them.
+  it('recognises project-code-prefixed archive dirs as valid for W002 (#3652)', async () => {
+    const planning = join(tmpDir, '.planning');
+    await mkdir(join(planning, 'phases', 'CK-65-current'), { recursive: true });
+    await mkdir(join(planning, 'milestones', 'v2.0-phases', 'CK-64-prior-shipped'), { recursive: true });
+
+    await writeFile(join(planning, 'PROJECT.md'), '# Project\n\n## What This Is\n\nA project.\n\n## Core Value\n\nValue here.\n\n## Requirements\n\n- Req 1\n');
+    await writeFile(join(planning, 'ROADMAP.md'), [
+      '# Roadmap', '',
+      '<details><summary>v2.0: Shipped</summary>', '',
+      // `#### Phase 64:` lives inside <details> so the heading-scan
+      // picks it up but the on-disk active phases scan does NOT. The W006
+      // archive scan must recognise `CK-64-prior-shipped` to suppress the
+      // warning — proving the shared regex is in use.
+      '#### Phase 64: Prior shipped', '',
+      '</details>', '',
+      '## v2.1: Current', '',
+      '### Phase 65: Current', '**Goal:** stuff', '',
+    ].join('\n'));
+    await writeFile(join(planning, 'STATE.md'), [
+      '---', 'milestone: v2.1', 'milestone_name: Current', 'status: executing', '---', '',
+      '# State', '',
+      '**Current Phase:** 65', '',
+      '## Recent', '- Phase 64 shipped',
+    ].join('\n'));
+    await writeFile(join(planning, 'config.json'), JSON.stringify({
+      model_profile: 'balanced',
+      workflow: { nyquist_validation: true },
+    }, null, 2));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w002s = warnings.filter(w => w.code === 'W002');
+    expect(w002s).toEqual([]);
+    // Same prefixed-archive recognition must also suppress W006 for any
+    // ROADMAP heading that points at the CK-prefixed archived phase, so the
+    // pre-existing W006 archive scan doesn't regress to the old ad-hoc regex.
+    const w006sForArchived = warnings.filter(
+      w => w.code === 'W006' && String(w.message).includes('Phase 64'),
+    );
+    expect(w006sForArchived).toEqual([]);
+  });
+
+  it('returns warning W005 for bad phase directory naming', async () => {
+    await createHealthyPlanning();
+    await mkdir(join(tmpDir, '.planning', 'phases', 'bad_name'), { recursive: true });
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    expect(warnings.some(w => w.code === 'W005')).toBe(true);
+  });
+
+  it('does not emit W005 for 999.X backlog phase directory naming (#3473)', async () => {
+    await createHealthyPlanning();
+    await mkdir(join(tmpDir, '.planning', 'phases', '999.1-backlog-sweep'), { recursive: true });
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w005ForBacklog = warnings.find(
+      w => w.code === 'W005' && String(w.message).includes('999.1-backlog-sweep'),
+    );
+    expect(w005ForBacklog).toBeUndefined();
+  });
+
+  it('does not emit W006 when roadmap phase exists in milestones archive dir (#3473)', async () => {
+    await createHealthyPlanning();
+    await writeFile(join(tmpDir, '.planning', 'ROADMAP.md'), [
+      '# Roadmap',
+      '',
+      '## v1.0: Shipped ✅ SHIPPED',
+      '',
+      '### Phase 7: Old shipped phase',
+      '',
+      '## v1.1: Current',
+      '',
+      '### Phase 1: Foundation',
+      '',
+    ].join('\n'));
+    await mkdir(join(tmpDir, '.planning', 'milestones', 'v1.0-phases', '07-old-shipped-phase'), { recursive: true });
+    await writeFile(
+      join(tmpDir, '.planning', 'milestones', 'v1.0-phases', '07-old-shipped-phase', '07-01-PLAN.md'),
+      '# Plan\n',
+    );
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w006s = warnings.filter(w => w.code === 'W006');
+    expect(w006s.some(w => String(w.message).includes('Phase 7'))).toBe(false);
+  });
+
+  it('does not emit W007 for archived milestone-only phase dirs (#3560)', async () => {
+    await createHealthyPlanning();
+    await writeFile(join(tmpDir, '.planning', 'ROADMAP.md'), [
+      '# Roadmap',
+      '',
+      '## v1.1: Current',
+      '',
+      '### Phase 21: Active',
+      '',
+    ].join('\n'));
+    await mkdir(join(tmpDir, '.planning', 'phases', '21-active'), { recursive: true });
+    await mkdir(join(tmpDir, '.planning', 'milestones', 'v1.0-phases', '02-old-shipped-phase'), { recursive: true });
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w007s = warnings.filter(w => w.code === 'W007');
+    expect(w007s.some(w => String(w.message).includes('Phase 02'))).toBe(false);
+  });
+
+  it('does not emit W006 for unchecked future phases with no directory (#3559)', async () => {
+    await createHealthyPlanning();
+    await writeFile(join(tmpDir, '.planning', 'ROADMAP.md'), [
+      '# Roadmap',
+      '',
+      '## v1.1: Current',
+      '',
+      '- [x] **Phase 21: Active**',
+      '- [ ] **Phase 22: Future planned**',
+      '',
+      '### Phase 21: Active',
+      '',
+      '### Phase 22: Future planned',
+      '',
+    ].join('\n'));
+    await mkdir(join(tmpDir, '.planning', 'phases', '21-active'), { recursive: true });
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w006s = warnings.filter(w => w.code === 'W006');
+    expect(w006s.some(w => String(w.message).includes('Phase 22'))).toBe(false);
+  });
+
+  it('does not alias 22A to 22 when suppressing W006 (#3565)', async () => {
+    await createHealthyPlanning();
+    await writeFile(join(tmpDir, '.planning', 'ROADMAP.md'), [
+      '# Roadmap',
+      '',
+      '## v1.1: Current',
+      '',
+      '- [x] **Phase 22: Started phase**',
+      '- [ ] **Phase 22A: Future variant**',
+      '',
+      '### Phase 22: Started phase',
+      '',
+      '### Phase 22A: Future variant',
+      '',
+    ].join('\n'));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    const w006s = warnings.filter(w => w.code === 'W006');
+    expect(w006s.some(w => String(w.message).includes('Phase 22 in ROADMAP.md'))).toBe(true);
+  });
+
+  it('does not emit I001 when plan file has descriptor but summary uses canonical stem (#3473)', async () => {
+    await createHealthyPlanning();
+    await mkdir(join(tmpDir, '.planning', 'phases', '68-bug-surface'), { recursive: true });
+    await writeFile(join(tmpDir, '.planning', 'phases', '68-bug-surface', '68-01-scaffolding-PLAN.md'), [
+      '---',
+      'phase: 68',
+      'plan: 01',
+      'wave: 1',
+      'depends_on: []',
+      'files_modified: []',
+      'autonomous: true',
+      '---',
+      '# Plan',
+    ].join('\n'));
+    await writeFile(join(tmpDir, '.planning', 'phases', '68-bug-surface', '68-01-SUMMARY.md'), '# Summary\n');
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const info = data.info as Array<Record<string, unknown>>;
+    const i001ForPhase = info.find(
+      i => i.code === 'I001' && String(i.message).includes('68-bug-surface/68-01-scaffolding-PLAN.md'),
+    );
+    expect(i001ForPhase).toBeUndefined();
+  });
+
+  it('returns early with E010 when CWD equals home directory', async () => {
+    const result = await validateHealth([], homedir());
+    const data = result.data as Record<string, unknown>;
+    expect(data.status).toBe('error');
+    const errors = data.errors as Array<Record<string, unknown>>;
+    expect(errors.some(e => e.code === 'E010')).toBe(true);
+  });
+
+  it('returns warning W008 when config.json missing workflow.nyquist_validation', async () => {
+    await createHealthyPlanning();
+    await writeFile(join(tmpDir, '.planning', 'config.json'), JSON.stringify({
+      model_profile: 'balanced',
+      workflow: { research: true },
+    }, null, 2));
+
+    const result = await validateHealth([], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const warnings = data.warnings as Array<Record<string, unknown>>;
+    expect(warnings.some(w => w.code === 'W008')).toBe(true);
+  });
+
+  it('derives status from errors (broken), warnings (degraded), none (healthy)', async () => {
+    // broken: no .planning/
+    const r1 = await validateHealth([], tmpDir);
+    expect((r1.data as Record<string, unknown>).status).toBe('broken');
+
+    // degraded: missing config.json (warning only, not error)
+    await createHealthyPlanning();
+    const { unlink } = await import('node:fs/promises');
+    await unlink(join(tmpDir, '.planning', 'config.json'));
+    const r2 = await validateHealth([], tmpDir);
+    expect((r2.data as Record<string, unknown>).status).toBe('degraded');
+
+    // healthy: all present
+    await writeFile(join(tmpDir, '.planning', 'config.json'), JSON.stringify({
+      model_profile: 'balanced',
+      workflow: { nyquist_validation: true },
+    }, null, 2));
+    const r3 = await validateHealth([], tmpDir);
+    expect((r3.data as Record<string, unknown>).status).toBe('healthy');
+  });
+
+  // ─── Repair tests ───────────────────────────────────────────────────────
+
+  it('--repair with missing config.json creates config.json with defaults', async () => {
+    await createHealthyPlanning();
+    const { unlink } = await import('node:fs/promises');
+    await unlink(join(tmpDir, '.planning', 'config.json'));
+
+    const result = await validateHealth(['--repair'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.repairs_performed).toBeDefined();
+    const repairs = data.repairs_performed as Array<Record<string, unknown>>;
+    expect(repairs.some(r => r.action === 'createConfig' && r.success === true)).toBe(true);
+
+    // Verify file was created
+    const config = JSON.parse(await readFile(join(tmpDir, '.planning', 'config.json'), 'utf-8'));
+    expect(config.model_profile).toBe('balanced');
+    expect(config.workflow.nyquist_validation).toBe(true);
+  });
+
+  it('--repair with missing STATE.md generates minimal STATE.md', async () => {
+    await createHealthyPlanning();
+    const { unlink } = await import('node:fs/promises');
+    await unlink(join(tmpDir, '.planning', 'STATE.md'));
+
+    const result = await validateHealth(['--repair'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const repairs = data.repairs_performed as Array<Record<string, unknown>>;
+    expect(repairs.some(r => r.action === 'regenerateState' && r.success === true)).toBe(true);
+
+    // Verify file was created
+    const stateContent = await readFile(join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    expect(stateContent).toContain('# Session State');
+    expect(stateContent).toContain('regenerated by');
+  });
+
+  it('--repair with missing nyquist key adds workflow.nyquist_validation', async () => {
+    await createHealthyPlanning();
+    await writeFile(join(tmpDir, '.planning', 'config.json'), JSON.stringify({
+      model_profile: 'balanced',
+      workflow: { research: true },
+    }, null, 2));
+
+    const result = await validateHealth(['--repair'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    const repairs = data.repairs_performed as Array<Record<string, unknown>>;
+    expect(repairs.some(r => r.action === 'addNyquistKey' && r.success === true)).toBe(true);
+
+    // Verify key was added
+    const config = JSON.parse(await readFile(join(tmpDir, '.planning', 'config.json'), 'utf-8'));
+    expect(config.workflow.nyquist_validation).toBe(true);
+  });
+});