gsd-pi 2.10.12 → 2.12.0

package/dist/resources/extensions/gsd/tests/migrate-writer.test.ts

@@ -0,0 +1,398 @@
+// Migration writer format round-trip test suite
+// Tests that format functions produce output that parses back correctly
+// through parseRoadmap(), parsePlan(), parseSummary(), and parseRequirementCounts().
+// Pure in-memory tests — no filesystem needed.
+
+import {
+  formatRoadmap,
+  formatPlan,
+  formatSliceSummary,
+  formatTaskSummary,
+  formatTaskPlan,
+  formatRequirements,
+  formatProject,
+  formatDecisions,
+  formatContext,
+  formatState,
+} from '../migrate/writer.ts';
+import {
+  parseRoadmap,
+  parsePlan,
+  parseSummary,
+  parseRequirementCounts,
+} from '../files.ts';
+import type {
+  GSDMilestone,
+  GSDSlice,
+  GSDTask,
+  GSDRequirement,
+  GSDSliceSummaryData,
+  GSDTaskSummaryData,
+} from '../migrate/types.ts';
+import { createTestContext } from './test-helpers.ts';
+
+const { assertEq, assertTrue, report } = createTestContext();
+// ─── Test Data Builders ────────────────────────────────────────────────────
+
+function makeTask(overrides: Partial<GSDTask> = {}): GSDTask {
+  return {
+    id: 'T01',
+    title: 'Setup Auth',
+    description: 'Implement authentication',
+    done: false,
+    estimate: '30m',
+    files: ['src/auth.ts'],
+    mustHaves: ['JWT support'],
+    summary: null,
+    ...overrides,
+  };
+}
+
+function makeSlice(overrides: Partial<GSDSlice> = {}): GSDSlice {
+  return {
+    id: 'S01',
+    title: 'Auth System',
+    risk: 'medium' as const,
+    depends: [],
+    done: false,
+    demo: 'Login flow works end-to-end',
+    goal: 'Working authentication',
+    tasks: [makeTask()],
+    research: null,
+    summary: null,
+    ...overrides,
+  };
+}
+
+function makeMilestone(overrides: Partial<GSDMilestone> = {}): GSDMilestone {
+  return {
+    id: 'M001',
+    title: 'Core Platform',
+    vision: 'Build the core platform',
+    successCriteria: ['All tests pass', 'Deploy to staging'],
+    slices: [makeSlice()],
+    research: null,
+    boundaryMap: [],
+    ...overrides,
+  };
+}
+
+function makeSliceSummary(overrides: Partial<GSDSliceSummaryData> = {}): GSDSliceSummaryData {
+  return {
+    completedAt: '2026-03-10',
+    provides: ['auth-flow', 'jwt-tokens'],
+    keyFiles: ['src/auth.ts', 'src/middleware.ts'],
+    keyDecisions: ['Use JWT over sessions'],
+    patternsEstablished: ['Middleware pattern'],
+    duration: '2h',
+    whatHappened: 'Implemented full auth system with JWT.',
+    ...overrides,
+  };
+}
+
+function makeTaskSummary(overrides: Partial<GSDTaskSummaryData> = {}): GSDTaskSummaryData {
+  return {
+    completedAt: '2026-03-09',
+    provides: ['auth-endpoint'],
+    keyFiles: ['src/auth.ts'],
+    duration: '45m',
+    whatHappened: 'Built the auth endpoint.',
+    ...overrides,
+  };
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario A: Roadmap round-trip with 2 slices (1 done, 1 not)
+// ═══════════════════════════════════════════════════════════════════════════
+
+{
+  const milestone = makeMilestone({
+    slices: [
+      makeSlice({
+        id: 'S01',
+        title: 'Auth System',
+        risk: 'high',
+        depends: [],
+        done: true,
+        demo: 'Login flow works',
+      }),
+      makeSlice({
+        id: 'S02',
+        title: 'Dashboard',
+        risk: 'low',
+        depends: ['S01'],
+        done: false,
+        demo: 'Dashboard renders data',
+      }),
+    ],
+  });
+
+  const output = formatRoadmap(milestone);
+  const parsed = parseRoadmap(output);
+
+  assertEq(parsed.title, 'M001: Core Platform', 'roadmap: title');
+  assertEq(parsed.vision, 'Build the core platform', 'roadmap: vision');
+  assertEq(parsed.successCriteria.length, 2, 'roadmap: successCriteria count');
+  assertEq(parsed.successCriteria[0], 'All tests pass', 'roadmap: successCriteria[0]');
+  assertEq(parsed.successCriteria[1], 'Deploy to staging', 'roadmap: successCriteria[1]');
+  assertEq(parsed.slices.length, 2, 'roadmap: slices count');
+
+  assertEq(parsed.slices[0].id, 'S01', 'roadmap: S01 id');
+  assertEq(parsed.slices[0].title, 'Auth System', 'roadmap: S01 title');
+  assertEq(parsed.slices[0].done, true, 'roadmap: S01 done');
+  assertEq(parsed.slices[0].risk, 'high', 'roadmap: S01 risk');
+  assertEq(parsed.slices[0].depends.length, 0, 'roadmap: S01 depends empty');
+  assertEq(parsed.slices[0].demo, 'Login flow works', 'roadmap: S01 demo');
+
+  assertEq(parsed.slices[1].id, 'S02', 'roadmap: S02 id');
+  assertEq(parsed.slices[1].title, 'Dashboard', 'roadmap: S02 title');
+  assertEq(parsed.slices[1].done, false, 'roadmap: S02 done');
+  assertEq(parsed.slices[1].risk, 'low', 'roadmap: S02 risk');
+  assertEq(parsed.slices[1].depends, ['S01'], 'roadmap: S02 depends');
+  assertEq(parsed.slices[1].demo, 'Dashboard renders data', 'roadmap: S02 demo');
+
+  assertEq(parsed.boundaryMap.length, 0, 'roadmap: boundaryMap empty');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario B: Plan round-trip with 3 tasks (mixed done)
+// ═══════════════════════════════════════════════════════════════════════════
+
+{
+  const slice = makeSlice({
+    id: 'S01',
+    title: 'Auth System',
+    goal: 'Working authentication system',
+    demo: 'Login works with valid credentials',
+    tasks: [
+      makeTask({ id: 'T01', title: 'Setup Models', done: true, estimate: '15m', description: 'Define user model' }),
+      makeTask({ id: 'T02', title: 'Build Endpoints', done: false, estimate: '30m', description: 'REST API endpoints' }),
+      makeTask({ id: 'T03', title: 'Write Tests', done: true, estimate: '20m', description: 'Unit and integration tests' }),
+    ],
+  });
+
+  const output = formatPlan(slice);
+  const parsed = parsePlan(output);
+
+  assertEq(parsed.id, 'S01', 'plan: id');
+  assertEq(parsed.title, 'Auth System', 'plan: title');
+  assertEq(parsed.goal, 'Working authentication system', 'plan: goal');
+  assertEq(parsed.demo, 'Login works with valid credentials', 'plan: demo');
+  assertEq(parsed.tasks.length, 3, 'plan: tasks count');
+
+  assertEq(parsed.tasks[0].id, 'T01', 'plan: T01 id');
+  assertEq(parsed.tasks[0].title, 'Setup Models', 'plan: T01 title');
+  assertEq(parsed.tasks[0].done, true, 'plan: T01 done');
+  assertEq(parsed.tasks[0].estimate, '15m', 'plan: T01 estimate');
+
+  assertEq(parsed.tasks[1].id, 'T02', 'plan: T02 id');
+  assertEq(parsed.tasks[1].done, false, 'plan: T02 done');
+  assertEq(parsed.tasks[1].estimate, '30m', 'plan: T02 estimate');
+
+  assertEq(parsed.tasks[2].id, 'T03', 'plan: T03 id');
+  assertEq(parsed.tasks[2].done, true, 'plan: T03 done');
+  assertEq(parsed.tasks[2].estimate, '20m', 'plan: T03 estimate');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario C: Slice summary round-trip with full data
+// ═══════════════════════════════════════════════════════════════════════════
+
+{
+  const slice = makeSlice({
+    id: 'S01',
+    title: 'Auth System',
+    done: true,
+    summary: makeSliceSummary(),
+  });
+
+  const output = formatSliceSummary(slice, 'M001');
+  const parsed = parseSummary(output);
+
+  assertEq(parsed.frontmatter.id, 'S01', 'sliceSummary: id');
+  assertEq(parsed.frontmatter.parent, 'M001', 'sliceSummary: parent');
+  assertEq(parsed.frontmatter.milestone, 'M001', 'sliceSummary: milestone');
+  assertEq(parsed.frontmatter.provides, ['auth-flow', 'jwt-tokens'], 'sliceSummary: provides');
+  assertEq(parsed.frontmatter.requires.length, 0, 'sliceSummary: requires empty');
+  assertEq(parsed.frontmatter.affects.length, 0, 'sliceSummary: affects empty');
+  assertEq(parsed.frontmatter.key_files, ['src/auth.ts', 'src/middleware.ts'], 'sliceSummary: key_files');
+  assertEq(parsed.frontmatter.key_decisions, ['Use JWT over sessions'], 'sliceSummary: key_decisions');
+  assertEq(parsed.frontmatter.patterns_established, ['Middleware pattern'], 'sliceSummary: patterns_established');
+  assertEq(parsed.frontmatter.duration, '2h', 'sliceSummary: duration');
+  assertEq(parsed.frontmatter.completed_at, '2026-03-10', 'sliceSummary: completed_at');
+  assertEq(parsed.frontmatter.verification_result, 'passed', 'sliceSummary: verification_result');
+  assertEq(parsed.frontmatter.blocker_discovered, false, 'sliceSummary: blocker_discovered');
+  assertTrue(parsed.whatHappened.includes('Implemented full auth system'), 'sliceSummary: whatHappened content');
+  assertEq(parsed.title, 'S01: Auth System', 'sliceSummary: title');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario D: Task summary round-trip
+// ═══════════════════════════════════════════════════════════════════════════
+
+{
+  const task = makeTask({
+    id: 'T01',
+    title: 'Setup Auth',
+    done: true,
+    summary: makeTaskSummary(),
+  });
+
+  const output = formatTaskSummary(task, 'S01', 'M001');
+  const parsed = parseSummary(output);
+
+  assertEq(parsed.frontmatter.id, 'T01', 'taskSummary: id');
+  assertEq(parsed.frontmatter.parent, 'S01', 'taskSummary: parent');
+  assertEq(parsed.frontmatter.milestone, 'M001', 'taskSummary: milestone');
+  assertEq(parsed.frontmatter.provides, ['auth-endpoint'], 'taskSummary: provides');
+  assertEq(parsed.frontmatter.key_files, ['src/auth.ts'], 'taskSummary: key_files');
+  assertEq(parsed.frontmatter.duration, '45m', 'taskSummary: duration');
+  assertEq(parsed.frontmatter.completed_at, '2026-03-09', 'taskSummary: completed_at');
+  assertTrue(parsed.whatHappened.includes('Built the auth endpoint'), 'taskSummary: whatHappened content');
+  assertEq(parsed.title, 'T01: Setup Auth', 'taskSummary: title');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario E: Requirements round-trip with mixed statuses
+// ═══════════════════════════════════════════════════════════════════════════
+
+{
+  const requirements: GSDRequirement[] = [
+    { id: 'R001', title: 'Auth Required', class: 'core-capability', status: 'active', description: 'Must have auth', source: 'spec', primarySlice: 'S01' },
+    { id: 'R002', title: 'Logging', class: 'observability', status: 'active', description: 'Must log', source: 'spec', primarySlice: 'S02' },
+    { id: 'R003', title: 'OAuth Support', class: 'core-capability', status: 'validated', description: 'OAuth working', source: 'testing', primarySlice: 'S01' },
+    { id: 'R004', title: 'Dark Mode', class: 'ui', status: 'deferred', description: 'Nice to have', source: 'feedback', primarySlice: 'none' },
+    { id: 'R005', title: 'Legacy API', class: 'compat', status: 'out-of-scope', description: 'Dropped', source: 'decision', primarySlice: 'none' },
+  ];
+
+  const output = formatRequirements(requirements);
+  const counts = parseRequirementCounts(output);
+
+  assertEq(counts.active, 2, 'requirements: active count');
+  assertEq(counts.validated, 1, 'requirements: validated count');
+  assertEq(counts.deferred, 1, 'requirements: deferred count');
+  assertEq(counts.outOfScope, 1, 'requirements: outOfScope count');
+  assertEq(counts.total, 5, 'requirements: total count');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Scenario F: Edge cases
+// ═══════════════════════════════════════════════════════════════════════════
+
+// F1: Empty vision → fallback text
+{
+  const milestone = makeMilestone({ vision: '' });
+  const output = formatRoadmap(milestone);
+  const parsed = parseRoadmap(output);
+  assertEq(parsed.vision, '(migrated project)', 'edge: empty vision fallback');
+}
+
+// F2: Empty successCriteria → empty array
+{
+  const milestone = makeMilestone({ successCriteria: [] });
+  const output = formatRoadmap(milestone);
+  const parsed = parseRoadmap(output);
+  assertEq(parsed.successCriteria.length, 0, 'edge: empty successCriteria');
+}
+
+// F3: Empty tasks → empty array in parsed plan
+{
+  const slice = makeSlice({ tasks: [] });
+  const output = formatPlan(slice);
+  const parsed = parsePlan(output);
+  assertEq(parsed.tasks.length, 0, 'edge: empty tasks');
+}
+
+// F4: Null summary → empty string from formatSliceSummary
+{
+  const slice = makeSlice({ summary: null });
+  const output = formatSliceSummary(slice, 'M001');
+  assertEq(output, '', 'edge: null summary returns empty string');
+}
+
+// F5: Done=true checkbox in roadmap
+{
+  const milestone = makeMilestone({
+    slices: [makeSlice({ id: 'S01', done: true })],
+  });
+  const output = formatRoadmap(milestone);
+  const parsed = parseRoadmap(output);
+  assertEq(parsed.slices[0].done, true, 'edge: done checkbox true');
+}
+
+// F6: Done=false checkbox in roadmap
+{
+  const milestone = makeMilestone({
+    slices: [makeSlice({ id: 'S01', done: false })],
+  });
+  const output = formatRoadmap(milestone);
+  const parsed = parseRoadmap(output);
+  assertEq(parsed.slices[0].done, false, 'edge: done checkbox false');
+}
+
+// F7: Null task summary → empty string from formatTaskSummary
+{
+  const task = makeTask({ summary: null });
+  const output = formatTaskSummary(task, 'S01', 'M001');
+  assertEq(output, '', 'edge: null task summary returns empty string');
+}
+
+// F8: Empty requirements → all zeros
+{
+  const output = formatRequirements([]);
+  const counts = parseRequirementCounts(output);
+  assertEq(counts.total, 0, 'edge: empty requirements total 0');
+}
+
+// F9: formatProject with empty content → produces valid stub
+{
+  const output = formatProject('');
+  assertTrue(output.includes('# Project'), 'edge: empty project has heading');
+  assertTrue(output.length > 10, 'edge: empty project not blank');
+}
+
+// F10: formatProject with existing content → passes through
+{
+  const content = '# My Project\n\nDescription here.\n';
+  const output = formatProject(content);
+  assertEq(output, content, 'edge: project passthrough');
+}
+
+// F11: formatDecisions with empty content → produces valid stub
+{
+  const output = formatDecisions('');
+  assertTrue(output.includes('# Decisions'), 'edge: empty decisions has heading');
+}
+
+// F12: formatContext produces valid content
+{
+  const output = formatContext('M001');
+  assertTrue(output.includes('M001'), 'edge: context mentions milestone');
+}
+
+// F13: formatState produces valid content
+{
+  const milestones = [makeMilestone({
+    slices: [
+      makeSlice({ done: true }),
+      makeSlice({ id: 'S02', done: false }),
+    ],
+  })];
+  const output = formatState(milestones);
+  assertTrue(output.includes('1/2'), 'edge: state shows slice progress');
+}
+
+// F14: Task with no estimate → no est backtick in plan
+{
+  const slice = makeSlice({
+    tasks: [makeTask({ id: 'T01', title: 'Quick Fix', estimate: '' })],
+  });
+  const output = formatPlan(slice);
+  const parsed = parsePlan(output);
+  assertEq(parsed.tasks[0].id, 'T01', 'edge: task no estimate id');
+  assertEq(parsed.tasks[0].estimate, '', 'edge: task no estimate empty');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+
+report();

package/dist/resources/extensions/gsd/tests/must-have-parser.test.ts

@@ -0,0 +1,291 @@
+import { parseTaskPlanMustHaves } from '../files.ts';
+import { createTestContext } from './test-helpers.ts';
+
+const { assertEq, assertTrue, report } = createTestContext();
+// ═══════════════════════════════════════════════════════════════════════════
+// (a) Standard unchecked format: - [ ] text
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: standard unchecked ===');
+{
+  const content = `# T01: Test Task
+
+## Must-Haves
+
+- [ ] First must-have item
+- [ ] Second must-have item
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 2, 'should return 2 items');
+  assertEq(result[0].text, 'First must-have item', 'first item text');
+  assertEq(result[0].checked, false, 'first item unchecked');
+  assertEq(result[1].text, 'Second must-have item', 'second item text');
+  assertEq(result[1].checked, false, 'second item unchecked');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// (b) Checked variants: - [x] and - [X]
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: checked [x] and [X] ===');
+{
+  const content = `## Must-Haves
+
+- [x] Lowercase checked item
+- [X] Uppercase checked item
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 2, 'should return 2 items');
+  assertEq(result[0].checked, true, 'lowercase x is checked');
+  assertEq(result[0].text, 'Lowercase checked item', 'lowercase x text');
+  assertEq(result[1].checked, true, 'uppercase X is checked');
+  assertEq(result[1].text, 'Uppercase checked item', 'uppercase X text');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// (c) No-checkbox bullets: - text
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: no-checkbox bullets ===');
+{
+  const content = `## Must-Haves
+
+- Plain bullet item
+- Another plain item
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 2, 'should return 2 items');
+  assertEq(result[0].text, 'Plain bullet item', 'plain bullet text');
+  assertEq(result[0].checked, false, 'plain bullet defaults to unchecked');
+  assertEq(result[1].text, 'Another plain item', 'second plain bullet text');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// (d) Indented variants
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: indented variants ===');
+{
+  const content = `## Must-Haves
+
+  - [ ] Indented unchecked item
+  - [x] Indented checked item
+  - Plain indented item
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 3, 'should return 3 items');
+  assertEq(result[0].text, 'Indented unchecked item', 'indented unchecked text');
+  assertEq(result[0].checked, false, 'indented unchecked state');
+  assertEq(result[1].text, 'Indented checked item', 'indented checked text');
+  assertEq(result[1].checked, true, 'indented checked state');
+  assertEq(result[2].text, 'Plain indented item', 'indented plain text');
+  assertEq(result[2].checked, false, 'indented plain state');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// (e) Mixed checkbox states in one section
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: mixed states ===');
+{
+  const content = `## Must-Haves
+
+- [ ] Unchecked one
+- [x] Checked one
+- [X] Also checked
+- Plain bullet
+- [ ] Another unchecked
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 5, 'should return 5 items');
+  assertEq(result[0].checked, false, 'first is unchecked');
+  assertEq(result[1].checked, true, 'second is checked');
+  assertEq(result[2].checked, true, 'third is checked (uppercase)');
+  assertEq(result[3].checked, false, 'fourth (plain) is unchecked');
+  assertEq(result[4].checked, false, 'fifth is unchecked');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// (f) Missing Must-Haves section → empty array
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: missing section ===');
+{
+  const content = `# T01: Some Task
+
+## Description
+
+Some description here.
+
+## Verification
+
+- Run tests
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 0, 'returns empty array when section missing');
+  assertTrue(Array.isArray(result), 'result is an array');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// (g) Empty Must-Haves section → empty array
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: empty section ===');
+{
+  const content = `## Must-Haves
+
+## Verification
+
+- Run tests
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 0, 'returns empty array when section is empty');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// (h) Content with YAML frontmatter
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: YAML frontmatter ===');
+{
+  const content = `---
+estimated_steps: 5
+estimated_files: 3
+---
+
+# T01: Task with frontmatter
+
+## Must-Haves
+
+- [ ] Real must-have after frontmatter
+- [x] Checked must-have after frontmatter
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 2, 'frontmatter does not pollute results');
+  assertEq(result[0].text, 'Real must-have after frontmatter', 'first item text correct');
+  assertEq(result[0].checked, false, 'first item unchecked');
+  assertEq(result[1].text, 'Checked must-have after frontmatter', 'second item text correct');
+  assertEq(result[1].checked, true, 'second item checked');
+}
+
+// Verify frontmatter content is not misinterpreted as must-haves
+console.log('\n=== parseTaskPlanMustHaves: frontmatter-only content ===');
+{
+  const content = `---
+estimated_steps: 5
+estimated_files: 3
+---
+
+# T01: Task with only frontmatter
+
+## Description
+
+No must-haves section here.
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 0, 'frontmatter-only content returns empty array');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// (i) Real task plan format (based on S01/T01-PLAN.md structure)
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: real task plan format ===');
+{
+  const content = `---
+estimated_steps: 5
+estimated_files: 3
+---
+
+# T01: Add completing-milestone phase to deriveState with tests
+
+**Slice:** S01 — Milestone Completion Unit
+**Milestone:** M002
+
+## Description
+
+Add the \`completing-milestone\` phase to the GSD state machine.
+
+## Steps
+
+1. Add \`'completing-milestone'\` to the \`Phase\` union type in \`types.ts\`.
+2. In \`state.ts\`, modify the registry-building loop.
+
+## Must-Haves
+
+- [ ] \`Phase\` type includes \`'completing-milestone'\`
+- [ ] \`deriveState\` returns \`phase: 'completing-milestone'\` when all slices are \`[x]\` and no \`M00x-SUMMARY.md\` exists
+- [ ] \`deriveState\` returns milestone as \`'complete'\` and advances when summary exists
+- [ ] All 63+ existing \`deriveState\` tests pass without modification
+- [ ] New test fixtures cover single-milestone and multi-milestone completing-milestone scenarios
+
+## Verification
+
+- Run tests
+- All existing 63 assertions pass
+
+## Observability Impact
+
+- Signals added/changed: \`completing-milestone\` phase now visible
+- How a future agent inspects this: Run \`deriveState(basePath)\`
+- Failure state exposed: If \`deriveState\` doesn't detect the phase
+
+## Inputs
+
+- \`agent/extensions/gsd/types.ts\` — Phase type definition
+
+## Expected Output
+
+- \`agent/extensions/gsd/types.ts\` — Phase union includes \`'completing-milestone'\`
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 5, 'real plan has 5 must-haves');
+  assertTrue(result[0].text.includes('`Phase` type includes'), 'first must-have text matches');
+  assertTrue(result[1].text.includes('`deriveState` returns'), 'second must-have text matches');
+  assertEq(result[0].checked, false, 'all real must-haves are unchecked');
+  assertEq(result[4].checked, false, 'last real must-have is unchecked');
+  assertTrue(result[4].text.includes('multi-milestone'), 'last must-have references multi-milestone');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Edge cases
+// ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n=== parseTaskPlanMustHaves: empty string ===');
+{
+  const result = parseTaskPlanMustHaves('');
+  assertEq(result.length, 0, 'empty string returns empty array');
+}
+
+console.log('\n=== parseTaskPlanMustHaves: must-haves with inline code and backticks ===');
+{
+  const content = `## Must-Haves
+
+- [ ] \`functionName\` is exported from \`module.ts\`
+- [x] Returns \`Array<{ text: string }>\` with correct extraction
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 2, 'handles backtick content');
+  assertTrue(result[0].text.includes('`functionName`'), 'preserves backticks in text');
+  assertEq(result[0].checked, false, 'backtick item unchecked');
+  assertEq(result[1].checked, true, 'backtick item checked');
+}
+
+console.log('\n=== parseTaskPlanMustHaves: asterisk bullets ===');
+{
+  const content = `## Must-Haves
+
+* [ ] Asterisk unchecked
+* [x] Asterisk checked
+* Plain asterisk
+`;
+  const result = parseTaskPlanMustHaves(content);
+  assertEq(result.length, 3, 'handles asterisk bullets');
+  assertEq(result[0].checked, false, 'asterisk unchecked');
+  assertEq(result[1].checked, true, 'asterisk checked');
+  assertEq(result[2].checked, false, 'plain asterisk unchecked');
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+
+report();