@opengsd/gsd-pi 1.3.0 → 1.4.0

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

@@ -8,13 +8,13 @@ import { tmpdir } from 'node:os';
 
 import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getSlice, getSliceTasks, getTask, getGateResults, updateTaskStatus } from '../gsd-db.ts';
 import { handlePlanSlice } from '../tools/plan-slice.ts';
+import { handlePlanTask } from '../tools/plan-task.ts';
 import { parsePlan } from '../parsers-legacy.ts';
-import { parseTaskPlanFile } from '../files.ts';
 import { deriveState, invalidateStateCache } from '../state.ts';
 
 function makeTmpBase(): string {
   const base = mkdtempSync(join(tmpdir(), 'gsd-plan-slice-'));
-  mkdirSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
   mkdirSync(join(base, 'src', 'resources', 'extensions', 'gsd', 'tools'), { recursive: true });
   writeFileSync(join(base, 'src', 'resources', 'extensions', 'gsd', 'tools', 'plan-milestone.ts'), '// fixture\n', 'utf-8');
   writeFileSync(join(base, 'src', 'resources', 'extensions', 'gsd', 'tools', 'plan-task.ts'), '// fixture\n', 'utf-8');
@@ -91,17 +91,14 @@ test('handlePlanSlice writes slice/task planning state and renders plan artifact
     assert.deepEqual(slice?.target_repositories, ['project']);
     assert.deepEqual(tasks[0]?.target_repositories, ['project']);
 
-    const planPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'S02-PLAN.md');
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-02-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, []);
+    // Flat-phase: no per-task plan files — tasks are checkboxes inside the slice plan.
   } finally {
     cleanup(base);
   }
@@ -318,6 +315,9 @@ test('handlePlanSlice renders plan artifacts under worktree-local .gsd while usi
   const base = makeTmpBase();
   const worktree = join(base, '.gsd', 'worktrees', 'M001');
   mkdirSync(join(worktree, '.gsd'), { recursive: true });
+  // Mirror the project's phase dir into the worktree so resolveMilestonePath
+  // finds it and the renderer targets the correct flat-phase location.
+  mkdirSync(join(worktree, '.gsd', 'phases', '01-test'), { recursive: true });
   mkdirSync(join(worktree, 'src', 'resources', 'extensions', 'gsd', 'tools'), { recursive: true });
   writeFileSync(join(worktree, 'src', 'resources', 'extensions', 'gsd', 'tools', 'plan-milestone.ts'), '// fixture\n', 'utf-8');
   writeFileSync(join(worktree, 'src', 'resources', 'extensions', 'gsd', 'tools', 'plan-task.ts'), '// fixture\n', 'utf-8');
@@ -329,8 +329,8 @@ test('handlePlanSlice renders plan artifacts under worktree-local .gsd while usi
     const result = await handlePlanSlice(validParams(), worktree);
     assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
 
-    const worktreePlan = join(worktree, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'S02-PLAN.md');
-    const projectPlan = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'S02-PLAN.md');
+    const worktreePlan = join(worktree, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    const projectPlan = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
     assert.ok(existsSync(worktreePlan), 'slice plan should be rendered to worktree-local .gsd');
     assert.ok(!existsSync(projectPlan), 'slice plan should not be rendered to project .gsd');
     assert.equal(result.planPath, realpathSync(worktreePlan));
@@ -339,6 +339,36 @@ test('handlePlanSlice renders plan artifacts under worktree-local .gsd while usi
   }
 });
 
+test('handlePlanSlice does not regenerate unrelated completed-task summaries during planning', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Finished slice', status: 'complete', demo: 'Existing work.' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.' });
+    insertTask({
+      id: 'T99',
+      sliceId: 'S01',
+      milestoneId: 'M001',
+      title: 'Already complete',
+      status: 'complete',
+      fullSummaryMd: '# T99 Summary\n\nAlready done.\n',
+    });
+
+    const unrelatedSummaryPath = join(base, '.gsd', 'phases', '01-test', 'T99-SUMMARY.md');
+    assert.equal(existsSync(unrelatedSummaryPath), false, 'fixture should start without unrelated summary projection');
+
+    const result = await handlePlanSlice(validParams(), base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    assert.equal(existsSync(unrelatedSummaryPath), false, 'plan-slice should not flush all milestone summaries');
+    assert.ok(existsSync(join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md')), 'current slice plan still renders');
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('handlePlanSlice preserves completed task closeout state when replanning the same task', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));
@@ -435,9 +465,10 @@ test('handlePlanSlice preserves sketch flag when render fails before artifacts e
     insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
     insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
 
-    const sliceDir = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02');
-    rmSync(sliceDir, { recursive: true, force: true });
-    writeFileSync(sliceDir, 'not a directory', 'utf-8');
+    // Block the rendered plan path by creating a directory where the file would go.
+    // The renderer resolves M001/S02 → phases/01-test/01-02-PLAN.md; creating that
+    // path as a directory causes EISDIR on write → render fails → sketch flag preserved.
+    mkdirSync(join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md'), { recursive: true });
 
     const result = await handlePlanSlice(validParams(), base);
     assert.ok('error' in result);
@@ -470,7 +501,7 @@ test('handlePlanSlice leaves omitted enrichment fields empty instead of renderin
     assert.equal(slice?.integration_closure, '');
     assert.equal(slice?.observability_impact, '');
 
-    const planPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'S02-PLAN.md');
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
     const content = readFileSync(planPath, 'utf-8');
     assert.doesNotMatch(content, /Not provided/i);
     assert.doesNotMatch(content, /^## Proof Level$/m);
@@ -481,15 +512,113 @@ test('handlePlanSlice leaves omitted enrichment fields empty instead of renderin
   }
 });
 
-test('handlePlanSlice rejects invalid payloads', async () => {
+test('handlePlanSlice accepts metadata-only payloads without deleting existing tasks', 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/);
+    const first = await handlePlanSlice(validParams(), base);
+    assert.ok(!('error' in first), `unexpected error: ${'error' in first ? first.error : ''}`);
+    assert.equal(getSliceTasks('M001', 'S02').length, 2);
+
+    const second = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Persist updated slice metadata before incremental tasks.',
+      successCriteria: '- Metadata renders before task planning',
+      proofLevel: 'unit',
+      integrationClosure: 'Task details follow through gsd_plan_task.',
+      observabilityImpact: 'Progress survives between tool calls.',
+    }, base);
+    assert.ok(!('error' in second), `unexpected error: ${'error' in second ? second.error : ''}`);
+    assert.equal(getSlice('M001', 'S02')?.goal, 'Persist updated slice metadata before incremental tasks.');
+    assert.deepEqual(getSliceTasks('M001', 'S02').map((task) => task.id), ['T01', 'T02']);
+
+    const third = await handlePlanSlice({ ...validParams(), tasks: [] }, base);
+    assert.ok(!('error' in third), `unexpected error: ${'error' in third ? third.error : ''}`);
+    assert.deepEqual(getSliceTasks('M001', 'S02').map((task) => task.id), ['T01', 'T02']);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanSlice metadata-only on a fresh sketch slice keeps is_sketch set and renders no PLAN.md (#1027)', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
+
+    // The incremental flow's first call carries metadata only (no tasks). It
+    // must NOT error (renderPlanFromDb throws on a task-less slice), and it must
+    // NOT clear the sketch flag — clearing it without a PLAN.md would leave the
+    // slice out of refining with no plan artifact, breaking sketch/plan signaling.
+    const result = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Persist slice metadata before any tasks exist.',
+    }, base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+    assert.equal(getSlice('M001', 'S02')?.goal, 'Persist slice metadata before any tasks exist.');
+    assert.equal(getSliceTasks('M001', 'S02').length, 0);
+    assert.equal(getSlice('M001', 'S02')?.is_sketch, 1, 'sketch flag must stay set until a task-bearing plan renders');
+
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.ok(!existsSync(planPath), 'no PLAN.md should be rendered until the first task is planned');
+
+    invalidateStateCache();
+    const after = await deriveState(base);
+    assert.equal(after.phase, 'refining', 'a task-less sketch slice stays in refining');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask materializes the slice PLAN.md and clears the sketch flag on the incremental path (#1027)', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
+
+    const sliceResult = await handlePlanSlice({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      goal: 'Incrementally planned slice.',
+      successCriteria: '- The slice plan is built up one task at a time',
+    }, base);
+    assert.ok(!('error' in sliceResult), `unexpected error: ${'error' in sliceResult ? sliceResult.error : ''}`);
+
+    const taskResult = await handlePlanTask({
+      milestoneId: 'M001',
+      sliceId: 'S02',
+      taskId: 'T01',
+      title: 'First incremental task',
+      description: 'Implement the first task added through gsd_plan_task.',
+      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-milestone.ts'],
+      expectedOutput: ['src/resources/extensions/gsd/tools/plan-task.ts'],
+    }, base);
+    assert.ok(!('error' in taskResult), `unexpected error: ${'error' in taskResult ? taskResult.error : ''}`);
+
+    // The first incremental task materializes the canonical slice PLAN.md with
+    // the task present, and clears the sketch flag now that a plan exists.
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.ok(existsSync(planPath), 'slice PLAN.md should exist after the first task is planned');
+    const parsedPlan = parsePlan(readFileSync(planPath, 'utf-8'));
+    assert.equal(parsedPlan.goal, 'Incrementally planned slice.');
+    assert.equal(parsedPlan.tasks.length, 1);
+    assert.equal(parsedPlan.tasks[0]?.id, 'T01');
+    assert.equal(getSlice('M001', 'S02')?.is_sketch, 0, 'sketch flag must clear once the first task renders a plan');
+
+    invalidateStateCache();
+    const after = await deriveState(base);
+    assert.notEqual(after.phase, 'refining', 'a planned slice leaves refining');
   } finally {
     cleanup(base);
   }
@@ -644,8 +773,9 @@ test('handlePlanSlice surfaces render failures without changing parse-visible ta
 
   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');
+    // Flat-phase: per-task plan files don't exist; simulate a write failure on the slice plan
+    const failingTaskPlanPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    writeFileSync(failingTaskPlanPath, '---\nestimated_steps: 1\nestimated_files: 1\nskills_used: []\n---\n\n# Cached plan\n', 'utf-8');
     rmSync(failingTaskPlanPath, { force: true });
     mkdirSync(failingTaskPlanPath, { recursive: true });
 
@@ -683,7 +813,7 @@ test('handlePlanSlice reruns idempotently and refreshes parse-visible state', as
 
   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');
+    writeFileSync(join(base, '.gsd', 'phases', '01-test', '01-02-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));
@@ -698,7 +828,7 @@ test('handlePlanSlice reruns idempotently and refreshes parse-visible state', as
     }, base);
     assert.ok(!('error' in second));
 
-    const parsedAfter = parsePlan(readFileSync(join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'S02-PLAN.md'), 'utf-8'));
+    const parsedAfter = parsePlan(readFileSync(join(base, '.gsd', 'phases', '01-test', '01-02-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.');
@@ -724,8 +854,10 @@ test('handlePlanSlice removes omitted pending tasks when replanning a smaller ta
 
     const first = await handlePlanSlice(fourTaskPlan, base);
     assert.ok(!('error' in first), `unexpected error: ${'error' in first ? first.error : ''}`);
-    const staleTaskPlanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks', 'T04-PLAN.md');
-    assert.ok(existsSync(staleTaskPlanPath), 'initial plan should render T04');
+    // In flat-phase mode tasks are checkboxes in the slice plan; no per-task plan files.
+    const slicePlanPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.ok(existsSync(slicePlanPath), 'initial plan should exist');
+    assert.match(readFileSync(slicePlanPath, 'utf-8'), /T04/, 'initial plan should contain T04');
 
     const second = await handlePlanSlice({
       ...validParams(),
@@ -735,7 +867,7 @@ test('handlePlanSlice removes omitted pending tasks when replanning a smaller ta
 
     assert.deepEqual(getSliceTasks('M001', 'S02').map((task) => task.id), ['T01', 'T02', 'T03']);
     assert.equal(getGateResults('M001', 'S02', 'task').some((gate) => gate.task_id === 'T04'), false);
-    assert.equal(existsSync(staleTaskPlanPath), false, 'omitted task plan artifact should be removed');
+    assert.doesNotMatch(readFileSync(slicePlanPath, 'utf-8'), /T04/, 'omitted T04 should be removed from plan');
   } finally {
     cleanup(base);
   }
@@ -758,8 +890,10 @@ test('handlePlanSlice rejects omitted completed tasks without changing slice or
 
     const first = await handlePlanSlice(fourTaskPlan, base);
     assert.ok(!('error' in first), `unexpected error: ${'error' in first ? first.error : ''}`);
-    const staleTaskPlanPath = join(base, '.gsd', 'milestones', 'M001', 'slices', 'S02', 'tasks', 'T04-PLAN.md');
-    assert.ok(existsSync(staleTaskPlanPath), 'initial plan should render T04');
+    // In flat-phase mode tasks are checkboxes in the slice plan; no per-task plan files.
+    const slicePlanPathR = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.ok(existsSync(slicePlanPathR), 'initial plan should exist');
+    assert.match(readFileSync(slicePlanPathR, 'utf-8'), /T04/, 'initial plan should contain T04');
 
     updateTaskStatus('M001', 'S02', 'T04', 'complete', '2026-05-12T00:00:00.000Z');
     const tasksBefore = getSliceTasks('M001', 'S02');
@@ -775,7 +909,7 @@ test('handlePlanSlice rejects omitted completed tasks without changing slice or
     assert.equal(getSlice('M001', 'S02')?.goal, 'Persist slice planning through the DB.');
     assert.deepEqual(getSliceTasks('M001', 'S02'), tasksBefore);
     assert.deepEqual(getGateResults('M001', 'S02', 'task'), gatesBefore);
-    assert.ok(existsSync(staleTaskPlanPath), 'completed task plan artifact should remain after rejected replan');
+    assert.match(readFileSync(slicePlanPathR, 'utf-8'), /T04/, 'completed task T04 should remain in plan after rejected replan');
   } finally {
     cleanup(base);
   }

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

@@ -4,13 +4,13 @@ import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync, writeFileSync
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getTask } from '../gsd-db.ts';
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getSlice, getTask, getGateResults } 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 });
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
   return base;
 }
 
@@ -55,7 +55,7 @@ test('handlePlanTask writes planning state and renders task plan', async () => {
     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');
+    const taskPlanPath = join(base, '.gsd', 'phases', '01-test', '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);
@@ -65,6 +65,25 @@ test('handlePlanTask writes planning state and renders task plan', async () => {
   }
 });
 
+test('handlePlanTask seeds execute-task gate rows for incremental planning', 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 gateIds = getGateResults('M001', 'S02', 'task')
+      .filter((gate) => gate.task_id === 'T02')
+      .map((gate) => gate.gate_id)
+      .sort();
+    assert.deepEqual(gateIds, ['Q5', 'Q6', 'Q7']);
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('handlePlanTask rejects invalid payloads', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));
@@ -157,7 +176,7 @@ test('handlePlanTask surfaces render failures without changing parse-visible tas
   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');
+    const taskPlanPath = join(base, '.gsd', 'phases', '01-test', '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 });
@@ -170,13 +189,37 @@ test('handlePlanTask surfaces render failures without changing parse-visible tas
   }
 });
 
+test('handlePlanTask keeps the sketch flag set when the flat-phase slice plan sync fails (#1083)', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M001', title: 'Milestone', status: 'active' });
+    insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.', isSketch: true });
+
+    // The per-task render writes T02-PLAN.md and succeeds, but the flat-phase
+    // slice re-render (the canonical PLAN.md that embeds task checkboxes) targets
+    // phases/01-test/01-02-PLAN.md. Pre-creating that path as a directory forces
+    // EISDIR on the slice sync, so the canonical slice plan never reflects the
+    // task. The sketch flag must therefore stay set — the slice keeps refining —
+    // instead of leaving the slice out of refining over a stale plan.
+    mkdirSync(join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md'), { recursive: true });
+
+    const result = await handlePlanTask(validParams(), base);
+    assert.equal(getSlice('M001', 'S02')?.is_sketch, 1, 'sketch flag must stay set when the canonical slice plan could not sync');
+    assert.ok(getTask('M001', 'S02', 'T02'), 'the task itself is still persisted so the slice can re-sync on retry');
+  } 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');
+    const taskPlanPath = join(base, '.gsd', 'phases', '01-test', '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);

package/src/resources/extensions/gsd/tests/planning-crossval.test.ts

@@ -90,6 +90,8 @@ console.log('\n=== planning-crossval Test 1: ROADMAP round-trip parity ===');
 
     // Render ROADMAP.md from DB
     const rendered = await renderRoadmapFromDb(base, 'M001');
+    // Milestone has planned slices — skipped variant is unreachable here.
+    if ('skipped' in rendered) throw new Error('unexpected: milestone has planned slices');
     const content = readFileSync(rendered.roadmapPath, 'utf-8');
 
     // Parse back
@@ -279,6 +281,8 @@ console.log('\n=== planning-crossval Test 3: Sequence ordering parity ===');
 
     // Render ROADMAP from DB — should produce slices in sequence order
     const rendered = await renderRoadmapFromDb(base, 'M001');
+    // Milestone has planned slices — skipped variant is unreachable here.
+    if ('skipped' in rendered) throw new Error('unexpected: milestone has planned slices');
     const content = readFileSync(rendered.roadmapPath, 'utf-8');
 
     // Parse back
@@ -312,6 +316,7 @@ console.log('\n=== planning-crossval Test 4: ROADMAP worktree projection path ==
   const base = createFixtureBase();
   const worktreeBase = join(base, '.gsd', 'worktrees', 'M001');
   const worktreeGsd = join(worktreeBase, '.gsd');
+  // Both base and worktree use the legacy milestones/ layout (no phases/ dir).
   const projectRoadmapPath = join(base, '.gsd', 'milestones', 'M001', 'M001-ROADMAP.md');
   const worktreeRoadmapPath = join(worktreeGsd, 'milestones', 'M001', 'M001-ROADMAP.md');
   const dbPath = join(base, '.gsd', 'gsd.db');
@@ -320,6 +325,10 @@ console.log('\n=== planning-crossval Test 4: ROADMAP worktree projection path ==
   try {
     scaffoldDirs(base, 'M001', []);
     mkdirSync(join(worktreeGsd, 'milestones', 'M001'), { recursive: true });
+    // Add a content file so the worktree M001 dir passes dirIsContentBearingLegacyMilestone.
+    // Without this, an empty dir is treated as a metadata-only dir (post-#852 guard) and
+    // resolveMilestonePath returns null, causing the renderer to write to a flat-phase path.
+    writeFileSync(join(worktreeGsd, 'milestones', 'M001', 'M001-CONTEXT.md'), '# M001\n');
     writeFileSync(projectRoadmapPath, '# stale project roadmap\n');
 
     insertMilestone({
@@ -340,6 +349,8 @@ console.log('\n=== planning-crossval Test 4: ROADMAP worktree projection path ==
     });
 
     const rendered = await renderRoadmapFromDb(worktreeBase, 'M001');
+    // Milestone has a planned slice — skipped variant is unreachable here.
+    if ('skipped' in rendered) throw new Error('unexpected: milestone has planned slices');
 
     assertEq(rendered.roadmapPath, worktreeRoadmapPath, 'T4: roadmap path uses worktree projection');
     assertTrue(existsSync(worktreeRoadmapPath), 'T4: worktree roadmap exists');
@@ -359,6 +370,7 @@ console.log('\n=== planning-crossval Test 5: ROADMAP existing projection file pa
   const base = createFixtureBase();
   const worktreeBase = join(base, '.gsd', 'worktrees', 'M001');
   const worktreeGsd = join(worktreeBase, '.gsd');
+  // Legacy milestones/ layout: roadmap filename is M001-ROADMAP.md (not NN-ROADMAP.md).
   const worktreeRoadmapPath = join(worktreeGsd, 'milestones', 'M001', 'M001-ROADMAP.md');
   const dbPath = join(base, '.gsd', 'gsd.db');
   const originalCwd = process.cwd();
@@ -377,6 +389,8 @@ console.log('\n=== planning-crossval Test 5: ROADMAP existing projection file pa
     });
 
     const rendered = await renderRoadmapFromDb(worktreeBase, 'M001');
+    // Milestone has a non-empty vision — skipped variant is unreachable here.
+    if ('skipped' in rendered) throw new Error('unexpected: milestone has non-empty vision');
 
     assertEq(rendered.roadmapPath, worktreeRoadmapPath, 'T5: existing roadmap path remains absolute');
     assertTrue(existsSync(worktreeRoadmapPath), 'T5: worktree roadmap still exists');
@@ -397,6 +411,7 @@ console.log('\n=== planning-crossval Test 6: ROADMAP descriptor projection dir =
   const worktreeBase = join(base, '.gsd', 'worktrees', 'M001');
   const worktreeGsd = join(worktreeBase, '.gsd');
   const descriptorMilestoneDir = join(worktreeGsd, 'milestones', 'M001-DESCRIPTOR');
+  // Legacy milestones/ layout: roadmap filename is M001-ROADMAP.md (not NN-ROADMAP.md).
   const descriptorRoadmapPath = join(descriptorMilestoneDir, 'M001-ROADMAP.md');
   const bareMilestoneDir = join(worktreeGsd, 'milestones', 'M001');
   const dbPath = join(base, '.gsd', 'gsd.db');
@@ -414,6 +429,8 @@ console.log('\n=== planning-crossval Test 6: ROADMAP descriptor projection dir =
     });
 
     const rendered = await renderRoadmapFromDb(worktreeBase, 'M001');
+    // Milestone has a non-empty vision — skipped variant is unreachable here.
+    if ('skipped' in rendered) throw new Error('unexpected: milestone has non-empty vision');
 
     assertEq(rendered.roadmapPath, descriptorRoadmapPath, 'T6: roadmap path uses descriptor milestone dir');
     assertTrue(existsSync(descriptorRoadmapPath), 'T6: descriptor roadmap exists');
@@ -455,6 +472,8 @@ console.log('\n=== planning-crossval Test 7: renderer recovers bracket-wrapped d
       .run('["[S01]"]', 'S02', 'M001');
 
     const rendered = await renderRoadmapFromDb(base, 'M001');
+    // Milestone has planned slices — skipped variant is unreachable here.
+    if ('skipped' in rendered) throw new Error('unexpected: milestone has planned slices');
     const content = readFileSync(rendered.roadmapPath, 'utf-8');
     const parsed = parseRoadmapSlices(content);
 

package/src/resources/extensions/gsd/tests/planning-layout-detect.test.ts

@@ -0,0 +1,84 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for .planning/ layout classification.
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { detectPlanningLayout } from "../migrate/layout-detect.ts";
+import type { PlanningProject } from "../migrate/types.ts";
+
+function emptyProject(over: Partial<PlanningProject> = {}): PlanningProject {
+  return {
+    path: "", project: null, roadmap: null, requirements: [], state: null,
+    config: null, phases: {}, quickTasks: [], milestones: [], research: [],
+    decisions: [], seeds: [], validation: { valid: true, issues: [] },
+    ...over,
+  } as PlanningProject;
+}
+
+test("detectPlanningLayout returns legacy-milestone-dir when milestones/ has phases", () => {
+  const p = emptyProject({
+    milestones: [{
+      id: "v1.0",
+      requirements: null,
+      roadmap: null,
+      phases: { "01-foo": {} as never },
+      extraFiles: [],
+    }],
+  });
+  assert.equal(detectPlanningLayout(p), "legacy-milestone-dir");
+});
+
+test("detectPlanningLayout returns multi-milestone when roadmap.milestones non-empty", () => {
+  const p = emptyProject({
+    roadmap: {
+      raw: "",
+      milestones: [{ id: "v1", title: "V1", collapsed: false, phases: [] }],
+      phases: [],
+    },
+  });
+  assert.equal(detectPlanningLayout(p), "multi-milestone");
+});
+
+test("detectPlanningLayout returns flat-phases when roadmap.phases non-empty and no milestone dirs", () => {
+  const p = emptyProject({
+    roadmap: {
+      raw: "",
+      milestones: [],
+      phases: [{ number: 1, title: "Foo", done: false, raw: "" }],
+    },
+  });
+  assert.equal(detectPlanningLayout(p), "flat-phases");
+});
+
+test("detectPlanningLayout returns null when nothing recognizable", () => {
+  assert.equal(detectPlanningLayout(emptyProject()), null);
+});
+
+test("priority: legacy-milestone-dir wins over multi-milestone", () => {
+  const p = emptyProject({
+    milestones: [{
+      id: "v1.0",
+      requirements: null,
+      roadmap: null,
+      phases: { "01-foo": {} as never },
+      extraFiles: [],
+    }],
+    roadmap: {
+      raw: "",
+      milestones: [{ id: "v1", title: "V1", collapsed: false, phases: [] }],
+      phases: [],
+    },
+  });
+  assert.equal(detectPlanningLayout(p), "legacy-milestone-dir");
+});
+
+test("priority: multi-milestone wins over flat-phases when both roadmap arrays non-empty", () => {
+  const p = emptyProject({
+    roadmap: {
+      raw: "",
+      milestones: [{ id: "v1", title: "V1", collapsed: false, phases: [] }],
+      phases: [{ number: 1, title: "Foo", done: false, raw: "" }],
+    },
+  });
+  assert.equal(detectPlanningLayout(p), "multi-milestone");
+});