gsd-pi 2.43.0 → 2.44.0-dev.62b5d6c

package/src/resources/extensions/gsd/tests/plan-milestone.test.ts

@@ -1,133 +1,196 @@
-// Tests for inlinePriorMilestoneSummary — the cross-milestone context bridging helper.
-//
-// Scenarios covered:
-//   (A) M002 with M001-SUMMARY.md present → returns string containing "Prior Milestone Summary" and summary content
-//   (B) M001 (no prior milestone in dir) → returns null
-//   (C) M002 with no M001-SUMMARY.md written → returns null
-//   (D) M003 with M002 dir present but no M002-SUMMARY.md → returns null
-
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
-import { join, dirname } from 'node:path';
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { tmpdir } from 'node:os';
-import { fileURLToPath } from 'node:url';
 
-import { inlinePriorMilestoneSummary } from '../files.ts';
-import { createTestContext } from './test-helpers.ts';
+import { openDatabase, closeDatabase, getMilestone, getMilestoneSlices } from '../gsd-db.ts';
+import { handlePlanMilestone } from '../tools/plan-milestone.ts';
+import { parseRoadmap } from '../parsers-legacy.ts';
 
-// ─── Worktree-aware prompt loader ──────────────────────────────────────────
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-
-const { assertEq, assertTrue, report } = createTestContext();
-// ─── Fixture helpers ───────────────────────────────────────────────────────
-
-function createFixtureBase(): string {
-  const base = mkdtempSync(join(tmpdir(), 'gsd-plan-ms-test-'));
-  mkdirSync(join(base, '.gsd', 'milestones'), { recursive: true });
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-plan-milestone-'));
+  mkdirSync(join(base, '.gsd', 'milestones', 'M001'), { recursive: true });
   return base;
 }
 
-function writeMilestoneDir(base: string, mid: string): void {
-  mkdirSync(join(base, '.gsd', 'milestones', mid), { recursive: true });
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
 }
 
-function writeMilestoneSummary(base: string, mid: string, content: string): void {
-  const dir = join(base, '.gsd', 'milestones', mid);
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, `${mid}-SUMMARY.md`), content);
+function validParams() {
+  return {
+    milestoneId: 'M001',
+    title: 'DB-backed planning',
+    vision: 'Make planning write through the database.',
+    successCriteria: ['Planning persists', 'Roadmap renders from DB'],
+    keyRisks: [
+      { risk: 'Renderer mismatch', whyItMatters: 'Rendered roadmap may stop round-tripping.' },
+    ],
+    proofStrategy: [
+      { riskOrUnknown: 'Render correctness', retireIn: 'S01', whatWillBeProven: 'ROADMAP output matches DB state.' },
+    ],
+    verificationContract: 'Contract verification text',
+    verificationIntegration: 'Integration verification text',
+    verificationOperational: 'Operational verification text',
+    verificationUat: 'UAT verification text',
+    definitionOfDone: ['Tests pass', 'Tool reruns cleanly'],
+    requirementCoverage: 'Covers R015.',
+    boundaryMapMarkdown: '| From | To | Produces | Consumes |\n|------|----|----------|----------|\n| S01 | terminal | roadmap | nothing |',
+    slices: [
+      {
+        sliceId: 'S01',
+        title: 'Tool wiring',
+        risk: 'medium',
+        depends: [],
+        demo: 'The tool writes roadmap state.',
+        goal: 'Wire the handler.',
+        successCriteria: 'Handler persists state and renders markdown.',
+        proofLevel: 'integration',
+        integrationClosure: 'Downstream callers read rendered roadmap output.',
+        observabilityImpact: 'Tests expose render and validation failures.',
+      },
+      {
+        sliceId: 'S02',
+        title: 'Prompt migration',
+        risk: 'low',
+        depends: ['S01'],
+        demo: 'Prompts call the tool.',
+        goal: 'Migrate prompts to DB-backed path.',
+        successCriteria: 'Prompt contracts reference the new tool.',
+        proofLevel: 'integration',
+        integrationClosure: 'Prompt tests cover the new planning route.',
+        observabilityImpact: 'Prompt and rogue-write failures become explicit.',
+      },
+    ],
+  };
 }
 
-function cleanup(base: string): void {
-  rmSync(base, { recursive: true, force: true });
-}
+test('handlePlanMilestone writes milestone and slice planning state and renders roadmap', async () => {
+  const base = makeTmpBase();
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  openDatabase(dbPath);
+
+  try {
+    const result = await handlePlanMilestone(validParams(), base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    const milestone = getMilestone('M001');
+    assert.ok(milestone, 'milestone should exist');
+    assert.equal(milestone?.vision, 'Make planning write through the database.');
+    assert.deepEqual(milestone?.success_criteria, ['Planning persists', 'Roadmap renders from DB']);
+    assert.equal(milestone?.verification_contract, 'Contract verification text');
+
+    const slices = getMilestoneSlices('M001');
+    assert.equal(slices.length, 2);
+    assert.equal(slices[0]?.id, 'S01');
+    assert.equal(slices[0]?.goal, 'Wire the handler.');
+    assert.equal(slices[1]?.depends[0], 'S01');
+
+    const roadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
+    assert.ok(existsSync(roadmapPath), 'roadmap should be rendered to disk');
+    const roadmap = readFileSync(roadmapPath, 'utf-8');
+    assert.match(roadmap, /# M001: DB-backed planning/);
+    assert.match(roadmap, /\*\*Vision:\*\* Make planning write through the database\./);
+    assert.match(roadmap, /- \[ \] \*\*S01: Tool wiring\*\* `risk:medium` `depends:\[\]`/);
+    assert.match(roadmap, /- \[ \] \*\*S02: Prompt migration\*\* `risk:low` `depends:\[S01\]`/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanMilestone rejects invalid payloads', async () => {
+  const base = makeTmpBase();
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  openDatabase(dbPath);
+
+  try {
+    const params = validParams();
+    const result = await handlePlanMilestone({ ...params, slices: [] }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: slices must be a non-empty array/);
+  } finally {
+    cleanup(base);
+  }
+});
 
-// ═══════════════════════════════════════════════════════════════════════════
-// Tests
-// ═══════════════════════════════════════════════════════════════════════════
-
-async function main(): Promise<void> {
-
-  // ─── (A) M002 with M001-SUMMARY.md present ────────────────────────────────
-  console.log('\n── (A) M002 with M001-SUMMARY.md present → string containing "Prior Milestone Summary"');
-  {
-    const base = createFixtureBase();
-    try {
-      writeMilestoneDir(base, 'M001');
-      writeMilestoneDir(base, 'M002');
-      writeMilestoneSummary(base, 'M001', '# M001 Summary\n\nKey decisions: used TypeScript throughout.\n');
-
-      const result = await inlinePriorMilestoneSummary('M002', base);
-
-      assertTrue(result !== null, '(A) result is not null when prior milestone has SUMMARY');
-      assertTrue(
-        typeof result === 'string' && result.includes('Prior Milestone Summary'),
-        '(A) result contains "Prior Milestone Summary" label',
-      );
-      assertTrue(
-        typeof result === 'string' && result.includes('Key decisions: used TypeScript throughout.'),
-        '(A) result contains the summary file content',
-      );
-    } finally {
-      cleanup(base);
-    }
+test('handlePlanMilestone surfaces render failures and does not clear parse-visible state on failure', async () => {
+  const base = makeTmpBase();
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  openDatabase(dbPath);
+
+  try {
+    const fallbackRoadmapPath = join(base, '.gsd', 'milestones', 'MISSING', 'MISSING-ROADMAP.md');
+    mkdirSync(fallbackRoadmapPath, { recursive: true });
+
+    const result = await handlePlanMilestone({ ...validParams(), milestoneId: 'MISSING' }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /render failed:/);
+
+    const existingRoadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
+    writeFileSync(existingRoadmapPath, '# M001: Cached roadmap\n\n**Vision:** old value\n\n## Slices\n\n', 'utf-8');
+    const cachedAfter = parseRoadmap(readFileSync(existingRoadmapPath, 'utf-8'));
+    assert.equal(cachedAfter.vision, 'old value');
+  } finally {
+    cleanup(base);
   }
+});
 
-  // ─── (B) M001 (no prior milestone in dir) ─────────────────────────────────
-  console.log('\n── (B) M001 — first milestone, no prior → null');
-  {
-    const base = createFixtureBase();
-    try {
-      writeMilestoneDir(base, 'M001');
+test('handlePlanMilestone clears parse-visible roadmap state after successful render', async () => {
+  const base = makeTmpBase();
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  openDatabase(dbPath);
 
-      const result = await inlinePriorMilestoneSummary('M001', base);
+  try {
+    const roadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
+    writeFileSync(roadmapPath, '# M001: Cached roadmap\n\n**Vision:** old value\n\n## Slices\n\n', 'utf-8');
 
-      assertEq(result, null, '(B) M001 with no prior milestone → null');
-    } finally {
-      cleanup(base);
-    }
-  }
+    const cachedBefore = parseRoadmap(readFileSync(roadmapPath, 'utf-8'));
+    assert.equal(cachedBefore.vision, 'old value');
 
-  // ─── (C) M002 with no M001-SUMMARY.md ────────────────────────────────────
-  console.log('\n── (C) M002 with M001 dir but no M001-SUMMARY.md → null');
-  {
-    const base = createFixtureBase();
-    try {
-      writeMilestoneDir(base, 'M001');
-      writeMilestoneDir(base, 'M002');
-      // Intentionally do NOT write M001-SUMMARY.md
-
-      const result = await inlinePriorMilestoneSummary('M002', base);
-
-      assertEq(result, null, '(C) M002 when M001 has no SUMMARY file → null');
-    } finally {
-      cleanup(base);
-    }
-  }
+    const result = await handlePlanMilestone(validParams(), base);
+    assert.ok(!('error' in result));
 
-  // ─── (D) M003 with M002 dir but no M002-SUMMARY.md ───────────────────────
-  console.log('\n── (D) M003, M002 is immediately prior but has no SUMMARY → null');
-  {
-    const base = createFixtureBase();
-    try {
-      writeMilestoneDir(base, 'M001');
-      writeMilestoneDir(base, 'M002');
-      writeMilestoneDir(base, 'M003');
-      // M001 has a summary — but M002 (the immediately prior to M003) does NOT
-      writeMilestoneSummary(base, 'M001', '# M001 Summary\n\nOld context.\n');
-      // Intentionally do NOT write M002-SUMMARY.md
-
-      const result = await inlinePriorMilestoneSummary('M003', base);
-
-      assertEq(result, null, '(D) M003 when M002 (immediately prior) has no SUMMARY → null');
-    } finally {
-      cleanup(base);
-    }
+    const parsedAfter = parseRoadmap(readFileSync(roadmapPath, 'utf-8'));
+    assert.equal(parsedAfter.vision, 'Make planning write through the database.');
+    assert.equal(parsedAfter.slices.length, 2);
+  } finally {
+    cleanup(base);
   }
+});
 
-  report();
-}
-
-main().catch((error) => {
-  console.error(error);
-  process.exit(1);
+test('handlePlanMilestone reruns idempotently and updates existing planning state', async () => {
+  const base = makeTmpBase();
+  const dbPath = join(base, '.gsd', 'gsd.db');
+  openDatabase(dbPath);
+
+  try {
+    const first = await handlePlanMilestone(validParams(), base);
+    assert.ok(!('error' in first));
+
+    const second = await handlePlanMilestone({
+      ...validParams(),
+      vision: 'Updated vision',
+      slices: [
+        {
+          ...validParams().slices[0],
+          goal: 'Updated goal',
+          observabilityImpact: 'Updated observability',
+        },
+        validParams().slices[1],
+      ],
+    }, base);
+    assert.ok(!('error' in second));
+
+    const milestone = getMilestone('M001');
+    assert.equal(milestone?.vision, 'Updated vision');
+
+    const slices = getMilestoneSlices('M001');
+    assert.equal(slices.length, 2);
+    assert.equal(slices[0]?.goal, 'Updated goal');
+    assert.equal(slices[0]?.observability_impact, 'Updated observability');
+  } finally {
+    cleanup(base);
+  }
 });

package/src/resources/extensions/gsd/tests/plan-slice-prompt.test.ts

@@ -54,6 +54,13 @@ test("plan-slice prompt: all variables substituted", () => {
   assert.ok(result.includes("S01"));
 });
 
+test("plan-slice prompt: DB-backed tool names survive template substitution", () => {
+  const result = loadPrompt("plan-slice", { ...BASE_VARS, commitInstruction: "Do not commit." });
+  assert.ok(result.includes("gsd_plan_slice"), "gsd_plan_slice should appear in rendered prompt");
+  assert.ok(result.includes("gsd_plan_task"), "gsd_plan_task should appear in rendered prompt");
+  assert.ok(result.includes("canonical write path"), "canonical write path language should survive substitution");
+});
+
 test("domain-work prompts use skillActivation placeholder", () => {
   const prompts = [
     "research-milestone",

package/src/resources/extensions/gsd/tests/plan-slice.test.ts

@@ -0,0 +1,179 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, getSlice, getSliceTasks, getTask } from '../gsd-db.ts';
+import { handlePlanSlice } from '../tools/plan-slice.ts';
+import { parsePlan } from '../parsers-legacy.ts';
+import { parseTaskPlanFile } from '../files.ts';
+
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-plan-slice-'));
+  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks'), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+function seedParentSlice(): void {
+  insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+  insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.' });
+}
+
+function validParams() {
+  return {
+    milestoneId: 'M001',
+    sliceId: 'S02',
+    goal: 'Persist slice planning through the DB.',
+    successCriteria: '- Slice plan renders from DB\n- Task plan files are regenerated',
+    proofLevel: 'integration',
+    integrationClosure: 'Planning handlers now write DB rows and render plan artifacts.',
+    observabilityImpact: '- Validation failures return structured errors\n- Cache invalidation is proven by parse-visible state updates',
+    tasks: [
+      {
+        taskId: 'T01',
+        title: 'Write slice handler',
+        description: 'Implement the slice planning handler.',
+        estimate: '45m',
+        files: ['src/resources/extensions/gsd/tools/plan-slice.ts'],
+        verify: 'node --test src/resources/extensions/gsd/tests/plan-slice.test.ts',
+        inputs: ['src/resources/extensions/gsd/tools/plan-milestone.ts'],
+        expectedOutput: ['src/resources/extensions/gsd/tools/plan-slice.ts'],
+        observabilityImpact: 'Tests exercise cache invalidation and render failure paths.',
+      },
+      {
+        taskId: 'T02',
+        title: 'Write task handler',
+        description: 'Implement the task planning handler.',
+        estimate: '30m',
+        files: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+        verify: 'node --test src/resources/extensions/gsd/tests/plan-task.test.ts',
+        inputs: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+        expectedOutput: ['src/resources/extensions/gsd/tests/plan-task.test.ts'],
+        observabilityImpact: 'Task-plan renders remain parse-compatible.',
+      },
+    ],
+  };
+}
+
+test('handlePlanSlice writes slice/task planning state and renders plan artifacts', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParentSlice();
+
+    const result = await handlePlanSlice(validParams(), base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    const slice = getSlice('M001', 'S02');
+    assert.ok(slice);
+    assert.equal(slice?.goal, 'Persist slice planning through the DB.');
+    assert.equal(slice?.proof_level, 'integration');
+
+    const tasks = getSliceTasks('M001', 'S02');
+    assert.equal(tasks.length, 2);
+    assert.equal(tasks[0]?.title, 'Write slice handler');
+    assert.equal(tasks[0]?.description, 'Implement the slice planning handler.');
+    assert.equal(tasks[1]?.estimate, '30m');
+
+    const planPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'S02-PLAN.md');
+    assert.ok(existsSync(planPath), 'slice plan should be rendered to disk');
+    const parsedPlan = parsePlan(readFileSync(planPath, 'utf-8'));
+    assert.equal(parsedPlan.goal, 'Persist slice planning through the DB.');
+    assert.equal(parsedPlan.tasks.length, 2);
+    assert.equal(parsedPlan.tasks[0]?.id, 'T01');
+
+    const taskPlanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks', 'T01-PLAN.md');
+    assert.ok(existsSync(taskPlanPath), 'task plan should be rendered to disk');
+    const taskPlan = parseTaskPlanFile(readFileSync(taskPlanPath, 'utf-8'));
+    assert.deepEqual(taskPlan.frontmatter.skills_used, []);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanSlice rejects invalid payloads', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParentSlice();
+    const result = await handlePlanSlice({ ...validParams(), tasks: [] }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: tasks must be a non-empty array/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanSlice rejects missing parent slice', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    const result = await handlePlanSlice(validParams(), base);
+    assert.ok('error' in result);
+    assert.match(result.error, /missing parent slice: M001\/S02/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanSlice surfaces render failures without changing parse-visible task-plan state for the failing task', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParentSlice();
+    const failingTaskPlanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks', 'T01-PLAN.md');
+    writeFileSync(failingTaskPlanPath, '---\nestimated_steps: 1\nestimated_files: 1\nskills_used: []\n---\n\n# T01: Cached task\n', 'utf-8');
+    rmSync(failingTaskPlanPath, { force: true });
+    mkdirSync(failingTaskPlanPath, { recursive: true });
+
+    const result = await handlePlanSlice(validParams(), base);
+    assert.ok('error' in result);
+    assert.match(result.error, /render failed:/);
+
+    assert.ok(existsSync(failingTaskPlanPath), 'failing task plan path should remain the blocking directory');
+    assert.equal(getTask('M001', 'S02', 'T01')?.description, 'Implement the slice planning handler.');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanSlice reruns idempotently and refreshes parse-visible state', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParentSlice();
+    writeFileSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'S02-PLAN.md'), '# S02: Cached\n\n**Goal:** old value\n\n## Tasks\n\n- [ ] **T01: Cached task**\n', 'utf-8');
+
+    const first = await handlePlanSlice(validParams(), base);
+    assert.ok(!('error' in first));
+
+    const second = await handlePlanSlice({
+      ...validParams(),
+      goal: 'Updated goal from rerun.',
+      tasks: [
+        { ...validParams().tasks[0], description: 'Updated slice handler description.' },
+        validParams().tasks[1],
+      ],
+    }, base);
+    assert.ok(!('error' in second));
+
+    const parsedAfter = parsePlan(readFileSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'S02-PLAN.md'), 'utf-8'));
+    assert.equal(parsedAfter.goal, 'Updated goal from rerun.');
+    const task = getTask('M001', 'S02', 'T01');
+    assert.equal(task?.description, 'Updated slice handler description.');
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/plan-task.test.ts

@@ -0,0 +1,145 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getTask } from '../gsd-db.ts';
+import { handlePlanTask } from '../tools/plan-task.ts';
+import { parseTaskPlanFile } from '../files.ts';
+
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-plan-task-'));
+  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks'), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+function seedParent(): void {
+  insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+  insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.' });
+}
+
+function validParams() {
+  return {
+    milestoneId: 'M001',
+    sliceId: 'S02',
+    taskId: 'T02',
+    title: 'Write task handler',
+    description: 'Implement the DB-backed task planning handler.',
+    estimate: '30m',
+    files: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+    verify: 'node --test src/resources/extensions/gsd/tests/plan-task.test.ts',
+    inputs: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+    expectedOutput: ['src/resources/extensions/gsd/tests/plan-task.test.ts'],
+    observabilityImpact: 'Tests exercise validation, render failure, and cache refresh behavior.',
+  };
+}
+
+test('handlePlanTask writes planning state and renders task plan', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const result = await handlePlanTask(validParams(), base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    const task = getTask('M001', 'S02', 'T02');
+    assert.ok(task);
+    assert.equal(task?.title, 'Write task handler');
+    assert.equal(task?.description, 'Implement the DB-backed task planning handler.');
+    assert.equal(task?.estimate, '30m');
+
+    const taskPlanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks', 'T02-PLAN.md');
+    assert.ok(existsSync(taskPlanPath), 'task plan should be rendered to disk');
+    const taskPlan = parseTaskPlanFile(readFileSync(taskPlanPath, 'utf-8'));
+    assert.equal(taskPlan.frontmatter.estimated_files, 1);
+    assert.deepEqual(taskPlan.frontmatter.skills_used, []);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask rejects invalid payloads', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const result = await handlePlanTask({ ...validParams(), files: [''] }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: files must contain only non-empty strings/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask rejects missing parent slice', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    const result = await handlePlanTask(validParams(), base);
+    assert.ok('error' in result);
+    assert.match(result.error, /missing parent slice: M001\/S02/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask surfaces render failures without changing parse-visible task plan state', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    insertTask({ id: 'T02', sliceId: 'S02', milestoneId: 'M001', title: 'Cached task', status: 'pending' });
+    const taskPlanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks', 'T02-PLAN.md');
+    writeFileSync(taskPlanPath, '---\nestimated_steps: 1\nestimated_files: 1\nskills_used: []\n---\n\n# T02: Cached task\n', 'utf-8');
+    rmSync(taskPlanPath, { force: true });
+    mkdirSync(taskPlanPath, { recursive: true });
+
+    const result = await handlePlanTask(validParams(), base);
+    assert.ok('error' in result);
+    assert.match(result.error, /render failed:/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask reruns idempotently and refreshes parse-visible state', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const taskPlanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks', 'T02-PLAN.md');
+    writeFileSync(taskPlanPath, '---\nestimated_steps: 1\nestimated_files: 1\nskills_used: []\n---\n\n# T02: Cached task\n', 'utf-8');
+
+    const first = await handlePlanTask(validParams(), base);
+    assert.ok(!('error' in first));
+
+    const second = await handlePlanTask({
+      ...validParams(),
+      description: 'Updated task handler description.',
+      estimate: '1h',
+    }, base);
+    assert.ok(!('error' in second));
+
+    const task = getTask('M001', 'S02', 'T02');
+    assert.equal(task?.description, 'Updated task handler description.');
+    assert.equal(task?.estimate, '1h');
+
+    const parsed = parseTaskPlanFile(readFileSync(taskPlanPath, 'utf-8'));
+    assert.equal(parsed.frontmatter.estimated_steps, 1);
+    assert.match(readFileSync(taskPlanPath, 'utf-8'), /Updated task handler description\./);
+  } finally {
+    cleanup(base);
+  }
+});