gsd-remix 1.0.0

package/sdk/src/query/phase-lifecycle.test.ts

@@ -0,0 +1,1126 @@
+/**
+ * Unit tests for phase lifecycle handlers.
+ *
+ * Tests phaseAdd, phaseAddBatch, phaseInsert, phaseScaffold, replaceInCurrentMilestone,
+ * and readModifyWriteRoadmapMd.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtemp, writeFile, readFile, rm, mkdir, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { existsSync } from 'node:fs';
+
+// ─── Fixtures ─────────────────────────────────────────────────────────────
+
+const MINIMAL_ROADMAP = `# Roadmap
+
+## Current Milestone: v3.0 SDK-First Migration
+
+### Phase 9: Foundation
+
+**Goal:** Build foundation
+**Requirements**: TBD
+**Depends on:** Phase 8
+**Plans:** 3 plans
+
+Plans:
+- [x] 09-01 (Foundation setup)
+
+### Phase 10: Read-Only Queries
+
+**Goal:** Port queries.
+**Requirements**: TBD
+**Depends on:** Phase 9
+**Plans:** 3 plans
+
+Plans:
+- [x] 10-01 (Query setup)
+
+---
+*Last updated: 2026-04-08*
+`;
+
+const ROADMAP_WITH_DETAILS = `# Roadmap
+
+<details>
+<summary>v1.0 (shipped)</summary>
+
+### Phase 1: Old Phase
+
+**Goal:** Shipped already
+**Plans:** 2 plans
+
+</details>
+
+## Current Milestone: v3.0 SDK-First Migration
+
+### Phase 9: Foundation
+
+**Goal:** Build foundation
+**Requirements**: TBD
+**Plans:** 3 plans
+
+### Phase 10: Read-Only Queries
+
+**Goal:** Port queries.
+**Requirements**: TBD
+**Plans:** 3 plans
+
+---
+*Last updated: 2026-04-08*
+`;
+
+const MINIMAL_STATE = `---
+gsd_state_version: 1.0
+milestone: v3.0
+milestone_name: SDK-First Migration
+status: executing
+---
+
+# Project State
+
+## Current Position
+
+Phase: 10 (Read-Only Queries) — EXECUTING
+Plan: 2 of 3
+Status: Executing Phase 10
+
+## Session Continuity
+
+Last session: 2026-04-07T10:00:00.000Z
+Stopped at: Completed 10-02-PLAN.md
+`;
+
+/** Create a test project with .planning structure. */
+async function setupTestProject(
+  tmpDir: string,
+  opts?: { roadmap?: string; state?: string; config?: Record<string, unknown>; phases?: string[] }
+): Promise<string> {
+  const planningDir = join(tmpDir, '.planning');
+  await mkdir(planningDir, { recursive: true });
+  const phasesDir = join(planningDir, 'phases');
+  await mkdir(phasesDir, { recursive: true });
+  await writeFile(join(planningDir, 'ROADMAP.md'), opts?.roadmap || MINIMAL_ROADMAP, 'utf-8');
+  await writeFile(join(planningDir, 'STATE.md'), opts?.state || MINIMAL_STATE, 'utf-8');
+  await writeFile(
+    join(planningDir, 'config.json'),
+    JSON.stringify(opts?.config || { model_profile: 'balanced', phase_naming: 'sequential' }),
+    'utf-8'
+  );
+  // Create phase directories if requested
+  if (opts?.phases) {
+    for (const phase of opts.phases) {
+      await mkdir(join(phasesDir, phase), { recursive: true });
+      await writeFile(join(phasesDir, phase, '.gitkeep'), '', 'utf-8');
+    }
+  }
+  return tmpDir;
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────
+
+let tmpDir: string;
+
+beforeEach(async () => {
+  tmpDir = await mkdtemp(join(tmpdir(), 'gsd-lifecycle-'));
+});
+
+afterEach(async () => {
+  await rm(tmpDir, { recursive: true, force: true });
+});
+
+// ─── replaceInCurrentMilestone ──────────────────────────────────────────
+
+describe('replaceInCurrentMilestone', () => {
+  it('replaces in full content when no details blocks', async () => {
+    const { replaceInCurrentMilestone } = await import('./phase-lifecycle.js');
+    const content = '### Phase 9: Foundation\n**Plans:** 3 plans\n';
+    const result = replaceInCurrentMilestone(content, /3 plans/, '4 plans');
+    expect(result).toContain('4 plans');
+  });
+
+  it('only replaces after last </details> block', async () => {
+    const { replaceInCurrentMilestone } = await import('./phase-lifecycle.js');
+    const content = '<details>\n### Phase 1: Old\n**Plans:** 3 plans\n</details>\n\n### Phase 9: Current\n**Plans:** 3 plans\n';
+    const result = replaceInCurrentMilestone(content, /3 plans/, '4 plans');
+    // Should only replace in the current milestone section (after </details>)
+    const before = result.slice(0, result.indexOf('</details>') + '</details>'.length);
+    const after = result.slice(result.indexOf('</details>') + '</details>'.length);
+    expect(before).toContain('3 plans'); // old milestone untouched
+    expect(after).toContain('4 plans'); // current milestone updated
+  });
+});
+
+// ─── readModifyWriteRoadmapMd ───────────────────────────────────────────
+
+describe('readModifyWriteRoadmapMd', () => {
+  it('reads, modifies, and writes ROADMAP.md atomically', async () => {
+    const { readModifyWriteRoadmapMd } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+    const result = await readModifyWriteRoadmapMd(tmpDir, (content) => {
+      return content.replace('Port queries.', 'Port all queries.');
+    });
+    expect(result).toContain('Port all queries.');
+    const ondisk = await readFile(join(tmpDir, '.planning', 'ROADMAP.md'), 'utf-8');
+    expect(ondisk).toContain('Port all queries.');
+  });
+
+  it('creates and releases lockfile', async () => {
+    const { readModifyWriteRoadmapMd } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+    await readModifyWriteRoadmapMd(tmpDir, (c) => c);
+    // Lock should be released after operation
+    const lockPath = join(tmpDir, '.planning', 'ROADMAP.md.lock');
+    expect(existsSync(lockPath)).toBe(false);
+  });
+});
+
+// ─── phaseAdd ──────────────────────────────────────────────────────────
+
+describe('phaseAdd', () => {
+  it('creates directory and updates ROADMAP.md for sequential phase', async () => {
+    const { phaseAdd } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation', '10-read-only-queries'],
+    });
+
+    const result = await phaseAdd(['New Feature'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.phase_number).toBe(11);
+    expect(data.padded).toBe('11');
+    expect(data.name).toBe('New Feature');
+    expect(data.slug).toBe('new-feature');
+    expect(data.naming_mode).toBe('sequential');
+
+    // Verify directory was created
+    const dir = data.directory as string;
+    expect(dir).toContain('11-new-feature');
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    const entries = await readdir(phasesDir, { withFileTypes: true });
+    const newDir = entries.find(e => e.isDirectory() && e.name.includes('11-new-feature'));
+    expect(newDir).toBeTruthy();
+
+    // Verify .gitkeep
+    expect(existsSync(join(phasesDir, newDir!.name, '.gitkeep'))).toBe(true);
+
+    // Verify ROADMAP.md updated
+    const roadmap = await readFile(join(tmpDir, '.planning', 'ROADMAP.md'), 'utf-8');
+    expect(roadmap).toContain('### Phase 11: New Feature');
+    expect(roadmap).toContain('**Goal:** [To be planned]');
+  });
+
+  it('skips phases >= 999 when calculating next number (backlog exclusion)', async () => {
+    const { phaseAdd } = await import('./phase-lifecycle.js');
+    const roadmapWith999 = MINIMAL_ROADMAP.replace(
+      '---\n*Last updated',
+      '### Phase 999: Backlog\n\n**Goal:** Backlog items\n**Plans:** 0 plans\n\n---\n*Last updated'
+    );
+    await setupTestProject(tmpDir, { roadmap: roadmapWith999 });
+
+    const result = await phaseAdd(['After Ten'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    // Should be 11, not 1000
+    expect(data.phase_number).toBe(11);
+  });
+
+  it('throws GSDError with Validation for empty description', async () => {
+    const { phaseAdd } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+
+    await expect(phaseAdd([], tmpDir)).rejects.toThrow('description required');
+  });
+
+  it('inserts phase entry before last --- separator', async () => {
+    const { phaseAdd } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+
+    await phaseAdd(['Inserted Phase'], tmpDir);
+    const roadmap = await readFile(join(tmpDir, '.planning', 'ROADMAP.md'), 'utf-8');
+
+    // The new phase should appear before the trailing ---
+    const phaseIdx = roadmap.indexOf('### Phase 11: Inserted Phase');
+    const sepIdx = roadmap.lastIndexOf('\n---');
+    expect(phaseIdx).toBeLessThan(sepIdx);
+    expect(phaseIdx).toBeGreaterThan(0);
+  });
+});
+
+// ─── phaseAddBatch ─────────────────────────────────────────────────────
+
+describe('phaseAddBatch', () => {
+  it('adds multiple sequential phases in one pass', async () => {
+    const { phaseAddBatch } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation', '10-read-only-queries'],
+    });
+
+    const result = await phaseAddBatch(['Alpha', 'Beta'], tmpDir);
+    const data = result.data as { phases: Array<Record<string, unknown>>; count: number };
+
+    expect(data.count).toBe(2);
+    expect(data.phases[0].phase_number).toBe(11);
+    expect(data.phases[0].name).toBe('Alpha');
+    expect(data.phases[1].phase_number).toBe(12);
+    expect(data.phases[1].name).toBe('Beta');
+
+    const roadmap = await readFile(join(tmpDir, '.planning', 'ROADMAP.md'), 'utf-8');
+    expect(roadmap).toContain('### Phase 11: Alpha');
+    expect(roadmap).toContain('### Phase 12: Beta');
+
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    expect(existsSync(join(phasesDir, '11-alpha', '.gitkeep'))).toBe(true);
+    expect(existsSync(join(phasesDir, '12-beta', '.gitkeep'))).toBe(true);
+  });
+
+  it('accepts --descriptions JSON array', async () => {
+    const { phaseAddBatch } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, { phases: ['09-foundation', '10-read-only-queries'] });
+
+    const result = await phaseAddBatch(
+      ['--descriptions', JSON.stringify(['One', 'Two'])],
+      tmpDir,
+    );
+    const data = result.data as { count: number };
+    expect(data.count).toBe(2);
+  });
+
+  it('throws when no descriptions', async () => {
+    const { phaseAddBatch } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+
+    await expect(phaseAddBatch([], tmpDir)).rejects.toThrow('descriptions array required');
+  });
+});
+
+// ─── phaseInsert ────────────────────────────────────────────────────────
+
+describe('phaseInsert', () => {
+  it('creates decimal phase directory after target phase', async () => {
+    const { phaseInsert } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation', '10-read-only-queries'],
+    });
+
+    const result = await phaseInsert(['10', 'Urgent Fix'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.phase_number).toBe('10.1');
+    expect(data.after_phase).toBe('10');
+    expect(data.name).toBe('Urgent Fix');
+    expect(data.slug).toBe('urgent-fix');
+
+    // Verify directory created
+    const dir = data.directory as string;
+    expect(dir).toContain('10.1-urgent-fix');
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    const entries = await readdir(phasesDir, { withFileTypes: true });
+    const newDir = entries.find(e => e.isDirectory() && e.name.includes('10.1-urgent-fix'));
+    expect(newDir).toBeTruthy();
+  });
+
+  it('scans both directories and ROADMAP.md for existing decimals to avoid collisions', async () => {
+    const { phaseInsert } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation', '10-read-only-queries', '10.1-hotfix'],
+    });
+
+    const result = await phaseInsert(['10', 'Another Fix'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    // Should be 10.2 since 10.1 already exists on disk
+    expect(data.phase_number).toBe('10.2');
+  });
+
+  it('inserts section in ROADMAP.md after target phase', async () => {
+    const { phaseInsert } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+
+    await phaseInsert(['10', 'Urgent Fix'], tmpDir);
+    const roadmap = await readFile(join(tmpDir, '.planning', 'ROADMAP.md'), 'utf-8');
+
+    expect(roadmap).toContain('### Phase 10.1: Urgent Fix (INSERTED)');
+    // Should appear after Phase 10 section
+    const phase10Idx = roadmap.indexOf('### Phase 10:');
+    const insertedIdx = roadmap.indexOf('### Phase 10.1:');
+    expect(insertedIdx).toBeGreaterThan(phase10Idx);
+  });
+
+  it('throws GSDError for missing target phase', async () => {
+    const { phaseInsert } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+
+    await expect(phaseInsert(['99', 'Missing'], tmpDir)).rejects.toThrow('Phase 99 not found');
+  });
+
+  it('throws GSDError with Validation for missing args', async () => {
+    const { phaseInsert } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+
+    await expect(phaseInsert([], tmpDir)).rejects.toThrow('after-phase and description required');
+  });
+});
+
+// ─── phaseScaffold ──────────────────────────────────────────────────────
+
+describe('phaseScaffold', () => {
+  it('creates context template for a phase', async () => {
+    const { phaseScaffold } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation'],
+    });
+
+    const result = await phaseScaffold(['context', '9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.created).toBe(true);
+    const filePath = data.path as string;
+    expect(filePath).toContain('09-CONTEXT.md');
+
+    // Check content
+    const fullPath = join(tmpDir, '.planning', 'phases', '09-foundation', '09-CONTEXT.md');
+    expect(existsSync(fullPath)).toBe(true);
+    const content = await readFile(fullPath, 'utf-8');
+    expect(content).toContain('phase: "09"');
+    expect(content).toContain('Context');
+  });
+
+  it('creates uat template', async () => {
+    const { phaseScaffold } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation'],
+    });
+
+    const result = await phaseScaffold(['uat', '9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.created).toBe(true);
+    const fullPath = join(tmpDir, '.planning', 'phases', '09-foundation', '09-UAT.md');
+    expect(existsSync(fullPath)).toBe(true);
+    const content = await readFile(fullPath, 'utf-8');
+    expect(content).toContain('User Acceptance Testing');
+  });
+
+  it('creates verification template', async () => {
+    const { phaseScaffold } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation'],
+    });
+
+    const result = await phaseScaffold(['verification', '9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.created).toBe(true);
+    const fullPath = join(tmpDir, '.planning', 'phases', '09-foundation', '09-VERIFICATION.md');
+    expect(existsSync(fullPath)).toBe(true);
+    const content = await readFile(fullPath, 'utf-8');
+    expect(content).toContain('Verification');
+  });
+
+  it('creates phase-dir under phases/', async () => {
+    const { phaseScaffold } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir);
+
+    const result = await phaseScaffold(['phase-dir', '15', 'New Module'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.created).toBe(true);
+    const dir = data.directory as string;
+    expect(dir).toContain('15-new-module');
+  });
+
+  it('returns already_exists for existing file', async () => {
+    const { phaseScaffold } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation'],
+    });
+
+    // Create first
+    await phaseScaffold(['context', '9'], tmpDir);
+    // Second call should return already_exists
+    const result = await phaseScaffold(['context', '9'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.created).toBe(false);
+    expect(data.reason).toBe('already_exists');
+  });
+
+  it('throws GSDError for unknown type', async () => {
+    const { phaseScaffold } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation'],
+    });
+
+    await expect(phaseScaffold(['badtype', '9'], tmpDir)).rejects.toThrow('Unknown scaffold type');
+  });
+});
+
+// ─── phaseRemove ─────────────────────────────────────────────────────────
+
+const ROADMAP_FOR_REMOVE = `# Roadmap
+
+## Current Milestone: v3.0 SDK-First Migration
+
+### Phase 5: Auth
+
+**Goal:** Build authentication
+**Requirements**: TBD
+**Depends on:** Phase 4
+**Plans:** 2 plans
+
+Plans:
+- [x] 05-01 (Auth setup)
+- [x] 05-02 (Auth complete)
+
+### Phase 6: Dashboard
+
+**Goal:** Build dashboard
+**Requirements**: TBD
+**Depends on:** Phase 5
+**Plans:** 3 plans
+
+Plans:
+- [ ] 06-01 (Dashboard setup)
+
+### Phase 7: API
+
+**Goal:** Build API layer
+**Requirements**: TBD
+**Depends on:** Phase 6
+**Plans:** 2 plans
+
+Plans:
+- [ ] 07-01 (API setup)
+
+---
+*Last updated: 2026-04-08*
+`;
+
+const STATE_FOR_REMOVE = `---
+gsd_state_version: 1.0
+milestone: v3.0
+milestone_name: SDK-First Migration
+status: executing
+progress:
+  total_phases: 7
+  completed_phases: 4
+  total_plans: 15
+  completed_plans: 12
+  percent: 80
+---
+
+# Project State
+
+## Current Position
+
+Phase: 6 (Dashboard) — EXECUTING
+Plan: 1 of 3
+Status: Executing Phase 6
+
+## Session Continuity
+
+Last session: 2026-04-08T10:00:00.000Z
+Stopped at: Started
+`;
+
+describe('phaseRemove', () => {
+  it('removes integer phase directory and renumbers subsequent phases', async () => {
+    const { phaseRemove } = await import('./phase-lifecycle.js');
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_REMOVE,
+      state: STATE_FOR_REMOVE,
+      phases: ['05-auth', '06-dashboard', '07-api'],
+    });
+    // Create files inside directories to verify file renaming
+    await writeFile(join(phasesDir, '06-dashboard', '06-01-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(phasesDir, '07-api', '07-01-PLAN.md'), 'plan', 'utf-8');
+
+    const result = await phaseRemove(['6'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.removed).toBe('6');
+    expect(data.directory_deleted).toBeTruthy();
+    expect(data.roadmap_updated).toBe(true);
+    expect(data.state_updated).toBe(true);
+
+    // Phase 6 dir should be gone
+    const entries = await readdir(phasesDir, { withFileTypes: true });
+    const dirNames = entries.filter(e => e.isDirectory()).map(e => e.name);
+    expect(dirNames.find(d => d.includes('06-dashboard'))).toBeUndefined();
+
+    // Phase 7 should have been renamed to 06
+    const renamedDir = dirNames.find(d => d.includes('06-api'));
+    expect(renamedDir).toBeTruthy();
+
+    // Files inside renamed dir should also be renamed
+    const files = await readdir(join(phasesDir, renamedDir!));
+    expect(files.some(f => f.includes('06-01'))).toBe(true);
+    expect(files.some(f => f.includes('07-01'))).toBe(false);
+  });
+
+  it('removes decimal phase and renumbers sibling decimals', async () => {
+    const { phaseRemove } = await import('./phase-lifecycle.js');
+    const decimalRoadmap = ROADMAP_FOR_REMOVE.replace(
+      '### Phase 7: API',
+      '### Phase 6.1: Hotfix A\n\n**Goal:** Fix A\n**Plans:** 1 plans\n\n### Phase 6.2: Hotfix B\n\n**Goal:** Fix B\n**Plans:** 1 plans\n\n### Phase 6.3: Hotfix C\n\n**Goal:** Fix C\n**Plans:** 1 plans\n\n### Phase 7: API'
+    );
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    await setupTestProject(tmpDir, {
+      roadmap: decimalRoadmap,
+      state: STATE_FOR_REMOVE,
+      phases: ['05-auth', '06-dashboard', '06.1-hotfix-a', '06.2-hotfix-b', '06.3-hotfix-c', '07-api'],
+    });
+    // Create files with phase ID in name
+    await writeFile(join(phasesDir, '06.2-hotfix-b', '06.2-01-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(phasesDir, '06.3-hotfix-c', '06.3-01-PLAN.md'), 'plan', 'utf-8');
+
+    const result = await phaseRemove(['6.1'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.removed).toBe('6.1');
+
+    // 06.1 should be gone
+    const entries = await readdir(phasesDir, { withFileTypes: true });
+    const dirNames = entries.filter(e => e.isDirectory()).map(e => e.name);
+    expect(dirNames.find(d => d.includes('06.1-hotfix-a'))).toBeUndefined();
+
+    // 06.2 should become 06.1, 06.3 should become 06.2
+    expect(dirNames.find(d => d.includes('06.1-hotfix-b'))).toBeTruthy();
+    expect(dirNames.find(d => d.includes('06.2-hotfix-c'))).toBeTruthy();
+    expect(dirNames.find(d => d.includes('06.3'))).toBeUndefined();
+
+    // Files inside renamed dirs should be renamed
+    const dir1Files = await readdir(join(phasesDir, '06.1-hotfix-b'));
+    expect(dir1Files.some(f => f.includes('06.1-01'))).toBe(true);
+    const dir2Files = await readdir(join(phasesDir, '06.2-hotfix-c'));
+    expect(dir2Files.some(f => f.includes('06.2-01'))).toBe(true);
+  });
+
+  it('requires --force to remove phase with SUMMARY files', async () => {
+    const { phaseRemove } = await import('./phase-lifecycle.js');
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_REMOVE,
+      state: STATE_FOR_REMOVE,
+      phases: ['05-auth', '06-dashboard', '07-api'],
+    });
+    // Create a SUMMARY file to simulate executed work
+    await writeFile(join(phasesDir, '06-dashboard', '06-01-SUMMARY.md'), 'summary', 'utf-8');
+
+    await expect(phaseRemove(['6'], tmpDir)).rejects.toThrow('--force');
+  });
+
+  it('allows removal with --force even when SUMMARY files exist', async () => {
+    const { phaseRemove } = await import('./phase-lifecycle.js');
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_REMOVE,
+      state: STATE_FOR_REMOVE,
+      phases: ['05-auth', '06-dashboard', '07-api'],
+    });
+    await writeFile(join(phasesDir, '06-dashboard', '06-01-SUMMARY.md'), 'summary', 'utf-8');
+
+    const result = await phaseRemove(['6', '--force'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.removed).toBe('6');
+    expect(data.directory_deleted).toBeTruthy();
+  });
+
+  it('throws GSDError when ROADMAP.md is missing', async () => {
+    const { phaseRemove } = await import('./phase-lifecycle.js');
+    // Set up without ROADMAP.md
+    const planningDir = join(tmpDir, '.planning');
+    await mkdir(planningDir, { recursive: true });
+    const phasesDir = join(planningDir, 'phases');
+    await mkdir(phasesDir, { recursive: true });
+    await writeFile(join(planningDir, 'STATE.md'), STATE_FOR_REMOVE, 'utf-8');
+
+    await expect(phaseRemove(['6'], tmpDir)).rejects.toThrow('ROADMAP.md not found');
+  });
+
+  it('throws GSDError when phase number is missing', async () => {
+    const { phaseRemove } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_REMOVE,
+      state: STATE_FOR_REMOVE,
+    });
+
+    await expect(phaseRemove([], tmpDir)).rejects.toThrow('phase number required');
+  });
+
+  it('updates ROADMAP.md by removing phase section and renumbering', async () => {
+    const { phaseRemove } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_REMOVE,
+      state: STATE_FOR_REMOVE,
+      phases: ['05-auth', '06-dashboard', '07-api'],
+    });
+
+    await phaseRemove(['6'], tmpDir);
+
+    const roadmap = await readFile(join(tmpDir, '.planning', 'ROADMAP.md'), 'utf-8');
+    // Phase 6 section should be removed
+    expect(roadmap).not.toContain('### Phase 6: Dashboard');
+    // Phase 7 should be renumbered to 6
+    expect(roadmap).toContain('### Phase 6: API');
+    // Plan references should be renumbered
+    expect(roadmap).toContain('06-01');
+    expect(roadmap).not.toContain('07-01');
+  });
+
+  it('decrements total_phases in STATE.md frontmatter', async () => {
+    const { phaseRemove } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_REMOVE,
+      state: STATE_FOR_REMOVE,
+      phases: ['05-auth', '06-dashboard', '07-api'],
+    });
+
+    await phaseRemove(['6'], tmpDir);
+
+    const stateContent = await readFile(join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    // total_phases should be decremented from 7 to 6
+    expect(stateContent).toMatch(/total_phases:\s*6/);
+  });
+});
+
+// ─── phaseComplete ─────────────────────────────────────────────────────────
+
+const ROADMAP_FOR_COMPLETE = `# Roadmap
+
+<details>
+<summary>v1.0 (shipped)</summary>
+
+### Phase 1: Old Phase
+
+**Goal:** Shipped already
+**Plans:** 2 plans
+
+</details>
+
+## Current Milestone: v3.0 SDK-First Migration
+
+| Phase | Plans | Status | Completed |
+|-------|-------|--------|-----------|
+| 9.    | 3/3   | Complete | 2026-04-01 |
+| 10.   | 0/3   | In Progress |  |
+| 11.   | 0/2   | Not Started |  |
+
+- [x] Phase 9: Foundation (completed 2026-04-01)
+- [ ] Phase 10: Read-Only Queries
+- [ ] Phase 11: Final Phase
+
+### Phase 9: Foundation
+
+**Goal:** Build foundation
+**Requirements**: FOUND-01, FOUND-02
+**Depends on:** Phase 8
+**Plans:** 3/3 plans complete
+
+Plans:
+- [x] 09-01 (Foundation setup)
+- [x] 09-02 (Foundation core)
+- [x] 09-03 (Foundation tests)
+
+### Phase 10: Read-Only Queries
+
+**Goal:** Port queries
+**Requirements**: QUERY-01
+**Depends on:** Phase 9
+**Plans:** 3 plans
+
+Plans:
+- [x] 10-01 (Query setup)
+- [x] 10-02 (Query core)
+- [ ] 10-03 (Query tests)
+
+### Phase 11: Final Phase
+
+**Goal:** Final work
+**Requirements**: FINAL-01
+**Depends on:** Phase 10
+**Plans:** 2 plans
+
+Plans:
+- [ ] 11-01 (Final setup)
+- [ ] 11-02 (Final complete)
+
+---
+*Last updated: 2026-04-08*
+`;
+
+const STATE_FOR_COMPLETE = `---
+gsd_state_version: 1.0
+milestone: v3.0
+milestone_name: SDK-First Migration
+status: executing
+progress:
+  total_phases: 3
+  completed_phases: 1
+  total_plans: 8
+  completed_plans: 5
+  percent: 33
+---
+
+# Project State
+
+## Current Position
+
+Phase: 10 of 3 (Read-Only Queries) — EXECUTING
+Plan: 3 of 3
+Status: Executing Phase 10
+Last activity: 2026-04-08
+
+## Performance Metrics
+
+**Velocity:**
+
+- Total plans completed: 3
+- Average duration: --
+- Total execution time: 0 hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| 9 | 3 | - | - |
+
+## Session Continuity
+
+Last session: 2026-04-08T10:00:00.000Z
+Stopped at: Completed 10-03-PLAN.md
+`;
+
+const REQUIREMENTS_FOR_COMPLETE = `# Requirements
+
+## Checklist
+
+- [x] **FOUND-01** Foundation setup
+- [x] **FOUND-02** Foundation core
+- [ ] **QUERY-01** Query implementation
+- [ ] **FINAL-01** Final work
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| FOUND-01 | Phase 9 | Complete |
+| FOUND-02 | Phase 9 | Complete |
+| QUERY-01 | Phase 10 | In Progress |
+| FINAL-01 | Phase 11 | Pending |
+`;
+
+describe('phaseComplete', () => {
+  it('marks phase checkbox, updates progress table, and plan count in ROADMAP.md', async () => {
+    const { phaseComplete } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_COMPLETE,
+      state: STATE_FOR_COMPLETE,
+      phases: ['09-foundation', '10-read-only-queries', '11-final-phase'],
+    });
+    // Create PLAN and SUMMARY files for phase 10
+    const p10Dir = join(tmpDir, '.planning', 'phases', '10-read-only-queries');
+    await writeFile(join(p10Dir, '10-01-PLAN.md'), 'plan1', 'utf-8');
+    await writeFile(join(p10Dir, '10-02-PLAN.md'), 'plan2', 'utf-8');
+    await writeFile(join(p10Dir, '10-03-PLAN.md'), 'plan3', 'utf-8');
+    await writeFile(join(p10Dir, '10-01-SUMMARY.md'), 'summary1', 'utf-8');
+    await writeFile(join(p10Dir, '10-02-SUMMARY.md'), 'summary2', 'utf-8');
+    await writeFile(join(p10Dir, '10-03-SUMMARY.md'), 'summary3', 'utf-8');
+    // Create REQUIREMENTS.md
+    await writeFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), REQUIREMENTS_FOR_COMPLETE, 'utf-8');
+
+    const result = await phaseComplete(['10'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.completed_phase).toBe('10');
+    expect(data.plans_executed).toBe('3/3');
+    expect(data.is_last_phase).toBe(false);
+    expect(data.next_phase).toBeTruthy();
+    expect(data.roadmap_updated).toBe(true);
+
+    // Check ROADMAP.md updates
+    const roadmap = await readFile(join(tmpDir, '.planning', 'ROADMAP.md'), 'utf-8');
+    // Checkbox should be marked
+    expect(roadmap).toMatch(/\[x\].*Phase 10/);
+    // Progress table should show Complete
+    expect(roadmap).toMatch(/10\.?\s*\|.*3\/3.*\|.*Complete/i);
+    // Plan count in section should be updated
+    expect(roadmap).toContain('3/3 plans complete');
+    // Plan checkboxes should be [x]
+    expect(roadmap).toMatch(/\[x\] 10-01/);
+    expect(roadmap).toMatch(/\[x\] 10-02/);
+    expect(roadmap).toMatch(/\[x\] 10-03/);
+  });
+
+  it('updates REQUIREMENTS.md checkboxes and traceability table', async () => {
+    const { phaseComplete } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_COMPLETE,
+      state: STATE_FOR_COMPLETE,
+      phases: ['09-foundation', '10-read-only-queries', '11-final-phase'],
+    });
+    const p10Dir = join(tmpDir, '.planning', 'phases', '10-read-only-queries');
+    await writeFile(join(p10Dir, '10-01-PLAN.md'), 'plan1', 'utf-8');
+    await writeFile(join(p10Dir, '10-02-PLAN.md'), 'plan2', 'utf-8');
+    await writeFile(join(p10Dir, '10-03-PLAN.md'), 'plan3', 'utf-8');
+    await writeFile(join(p10Dir, '10-01-SUMMARY.md'), 'summary1', 'utf-8');
+    await writeFile(join(p10Dir, '10-02-SUMMARY.md'), 'summary2', 'utf-8');
+    await writeFile(join(p10Dir, '10-03-SUMMARY.md'), 'summary3', 'utf-8');
+    await writeFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), REQUIREMENTS_FOR_COMPLETE, 'utf-8');
+
+    await phaseComplete(['10'], tmpDir);
+
+    const req = await readFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), 'utf-8');
+    // QUERY-01 checkbox should be marked
+    expect(req).toMatch(/\[x\].*\*\*QUERY-01\*\*/);
+    // Traceability should show Complete for QUERY-01
+    expect(req).toMatch(/QUERY-01\s*\|.*\|\s*Complete\s*\|/);
+    // FINAL-01 should remain Pending
+    expect(req).toMatch(/FINAL-01\s*\|.*\|\s*Pending\s*\|/);
+  });
+
+  it('updates STATE.md fields: current phase, status, completed phases, percent', async () => {
+    const { phaseComplete } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_COMPLETE,
+      state: STATE_FOR_COMPLETE,
+      phases: ['09-foundation', '10-read-only-queries', '11-final-phase'],
+    });
+    const p10Dir = join(tmpDir, '.planning', 'phases', '10-read-only-queries');
+    await writeFile(join(p10Dir, '10-01-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p10Dir, '10-02-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p10Dir, '10-03-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p10Dir, '10-01-SUMMARY.md'), 'summary', 'utf-8');
+    await writeFile(join(p10Dir, '10-02-SUMMARY.md'), 'summary', 'utf-8');
+    await writeFile(join(p10Dir, '10-03-SUMMARY.md'), 'summary', 'utf-8');
+    await writeFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), REQUIREMENTS_FOR_COMPLETE, 'utf-8');
+
+    await phaseComplete(['10'], tmpDir);
+
+    const state = await readFile(join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    // Phase should advance to 11
+    expect(state).toMatch(/Phase:\s*11/);
+    // Status should indicate ready to plan
+    expect(state).toMatch(/Status:\s*Ready to plan/);
+    // Completed phases should be incremented from 1 to 2
+    expect(state).toMatch(/completed_phases:\s*2/);
+    // Percent should be recalculated (2/3 = 67%)
+    expect(state).toMatch(/percent:\s*67/);
+  });
+
+  it('detects next phase from filesystem, falls back to ROADMAP.md', async () => {
+    const { phaseComplete } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_COMPLETE,
+      state: STATE_FOR_COMPLETE,
+      phases: ['09-foundation', '10-read-only-queries', '11-final-phase'],
+    });
+    const p10Dir = join(tmpDir, '.planning', 'phases', '10-read-only-queries');
+    await writeFile(join(p10Dir, '10-01-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p10Dir, '10-01-SUMMARY.md'), 'summary', 'utf-8');
+    await writeFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), REQUIREMENTS_FOR_COMPLETE, 'utf-8');
+
+    const result = await phaseComplete(['10'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    // Next phase should be 11 (from filesystem)
+    expect(data.next_phase).toBe('11');
+    expect(data.is_last_phase).toBe(false);
+  });
+
+  it('sets is_last_phase when completing the final phase', async () => {
+    const { phaseComplete } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_COMPLETE,
+      state: STATE_FOR_COMPLETE,
+      phases: ['09-foundation', '10-read-only-queries', '11-final-phase'],
+    });
+    const p11Dir = join(tmpDir, '.planning', 'phases', '11-final-phase');
+    await writeFile(join(p11Dir, '11-01-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p11Dir, '11-01-SUMMARY.md'), 'summary', 'utf-8');
+    await writeFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), REQUIREMENTS_FOR_COMPLETE, 'utf-8');
+
+    const result = await phaseComplete(['11'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.is_last_phase).toBe(true);
+    expect(data.next_phase).toBeNull();
+
+    // State should show milestone complete
+    const state = await readFile(join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    expect(state).toMatch(/Status:\s*Milestone complete/);
+  });
+
+  it('collects UAT/VERIFICATION warnings without blocking', async () => {
+    const { phaseComplete } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_COMPLETE,
+      state: STATE_FOR_COMPLETE,
+      phases: ['09-foundation', '10-read-only-queries', '11-final-phase'],
+    });
+    const p10Dir = join(tmpDir, '.planning', 'phases', '10-read-only-queries');
+    await writeFile(join(p10Dir, '10-01-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p10Dir, '10-01-SUMMARY.md'), 'summary', 'utf-8');
+    // Create UAT file with pending status
+    await writeFile(join(p10Dir, '10-UAT.md'), '---\nresult: pending\n---\nPending tests', 'utf-8');
+    // Create VERIFICATION file with gaps
+    await writeFile(join(p10Dir, '10-VERIFICATION.md'), '---\nstatus: gaps_found\n---\nGaps', 'utf-8');
+    await writeFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), REQUIREMENTS_FOR_COMPLETE, 'utf-8');
+
+    const result = await phaseComplete(['10'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    // Should complete despite warnings
+    expect(data.completed_phase).toBe('10');
+    expect(data.has_warnings).toBe(true);
+    const warnings = data.warnings as string[];
+    expect(warnings.length).toBeGreaterThan(0);
+    expect(warnings.some(w => w.includes('pending'))).toBe(true);
+    expect(warnings.some(w => w.includes('gaps'))).toBe(true);
+  });
+
+  it('throws GSDError for missing phase', async () => {
+    const { phaseComplete } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_COMPLETE,
+      state: STATE_FOR_COMPLETE,
+      phases: ['09-foundation'],
+    });
+    await writeFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), REQUIREMENTS_FOR_COMPLETE, 'utf-8');
+
+    await expect(phaseComplete(['99'], tmpDir)).rejects.toThrow('Phase 99 not found');
+  });
+
+  it('updates performance metrics table in STATE.md', async () => {
+    const { phaseComplete } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      roadmap: ROADMAP_FOR_COMPLETE,
+      state: STATE_FOR_COMPLETE,
+      phases: ['09-foundation', '10-read-only-queries', '11-final-phase'],
+    });
+    const p10Dir = join(tmpDir, '.planning', 'phases', '10-read-only-queries');
+    await writeFile(join(p10Dir, '10-01-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p10Dir, '10-02-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p10Dir, '10-03-PLAN.md'), 'plan', 'utf-8');
+    await writeFile(join(p10Dir, '10-01-SUMMARY.md'), 'summary', 'utf-8');
+    await writeFile(join(p10Dir, '10-02-SUMMARY.md'), 'summary', 'utf-8');
+    await writeFile(join(p10Dir, '10-03-SUMMARY.md'), 'summary', 'utf-8');
+    await writeFile(join(tmpDir, '.planning', 'REQUIREMENTS.md'), REQUIREMENTS_FOR_COMPLETE, 'utf-8');
+
+    await phaseComplete(['10'], tmpDir);
+
+    const state = await readFile(join(tmpDir, '.planning', 'STATE.md'), 'utf-8');
+    // Total plans completed should be incremented: 3 + 3 = 6
+    expect(state).toContain('Total plans completed: 6');
+    // By Phase table should have a row for phase 10
+    expect(state).toMatch(/\|\s*10\s*\|\s*3\s*\|/);
+  });
+});
+
+// ─── phasesClear ────────────────────────────────────────────────────────────
+
+describe('phasesClear', () => {
+  it('throws GSDError without --confirm flag, showing count', async () => {
+    const { phasesClear } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation', '10-read-only-queries', '999.1-backlog'],
+    });
+
+    // Should throw with count of dirs to delete (2, not 3 since 999.1 is excluded)
+    await expect(phasesClear([], tmpDir)).rejects.toThrow(/2 phase director/);
+  });
+
+  it('deletes all dirs except 999.x with --confirm', async () => {
+    const { phasesClear } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation', '10-read-only-queries', '999.1-backlog'],
+    });
+
+    const result = await phasesClear(['--confirm'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.cleared).toBe(2);
+
+    // Verify filesystem
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    const entries = await readdir(phasesDir, { withFileTypes: true });
+    const dirNames = entries.filter(e => e.isDirectory()).map(e => e.name);
+    expect(dirNames.length).toBe(1);
+    expect(dirNames[0]).toContain('999');
+  });
+
+  it('returns 0 cleared when phases dir is empty', async () => {
+    const { phasesClear } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, { phases: [] });
+
+    const result = await phasesClear(['--confirm'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+    expect(data.cleared).toBe(0);
+  });
+});
+
+// ─── phasesArchive ──────────────────────────────────────────────────────────
+
+describe('phasesArchive', () => {
+  it('moves milestone phase dirs to milestones/{version}-phases/', async () => {
+    const { phasesArchive } = await import('./phase-lifecycle.js');
+    await setupTestProject(tmpDir, {
+      phases: ['09-foundation', '10-read-only-queries'],
+    });
+
+    const result = await phasesArchive(['v3.0'], tmpDir);
+    const data = result.data as Record<string, unknown>;
+
+    expect(data.version).toBe('v3.0');
+    expect((data.archived as number)).toBeGreaterThan(0);
+
+    // Verify archive directory exists
+    const archiveDir = join(tmpDir, '.planning', 'milestones', 'v3.0-phases');
+    expect(existsSync(archiveDir)).toBe(true);
+
+    // Verify dirs were moved
+    const archivedEntries = await readdir(archiveDir, { withFileTypes: true });
+    const archivedDirs = archivedEntries.filter(e => e.isDirectory()).map(e => e.name);
+    expect(archivedDirs.length).toBeGreaterThan(0);
+
+    // Original dirs should be gone
+    const phasesDir = join(tmpDir, '.planning', 'phases');
+    const remaining = await readdir(phasesDir, { withFileTypes: true });
+    const remainingDirs = remaining.filter(e => e.isDirectory()).map(e => e.name);
+    expect(remainingDirs.length).toBe(0);
+  });
+});
+
+// ─── Registry integration ──────────────────────────────────────────────────
+
+describe('lifecycle handlers in registry', () => {
+  it('registers all 7 lifecycle handlers with dot notation', async () => {
+    const { createRegistry } = await import('./index.js');
+    const registry = createRegistry();
+
+    const commands = [
+      'phase.add', 'phase.insert', 'phase.remove', 'phase.complete',
+      'phase.scaffold', 'phases.clear', 'phases.archive',
+    ];
+
+    for (const cmd of commands) {
+      const handler = registry.getHandler(cmd);
+      expect(handler, `${cmd} should be registered`).toBeDefined();
+    }
+  });
+
+  it('registers space-delimited aliases', async () => {
+    const { createRegistry } = await import('./index.js');
+    const registry = createRegistry();
+
+    const commands = [
+      'phase add', 'phase insert', 'phase remove', 'phase complete',
+      'phase scaffold', 'phases clear', 'phases archive',
+    ];
+
+    for (const cmd of commands) {
+      const handler = registry.getHandler(cmd);
+      expect(handler, `${cmd} should be registered`).toBeDefined();
+    }
+  });
+});