@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

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, getSliceTasks, 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;
 }
 
@@ -24,6 +24,26 @@ function seedParent(): void {
   insertSlice({ id: 'S02', milestoneId: 'M001', title: 'Planning slice', status: 'pending', demo: 'Rendered plans exist.' });
 }
 
+function writeParentWorkspacePreferences(base: string): void {
+  mkdirSync(join(base, 'frontend', 'src'), { recursive: true });
+  mkdirSync(join(base, 'backend', 'src'), { recursive: true });
+  writeFileSync(
+    join(base, '.gsd', 'PREFERENCES.md'),
+    [
+      '---',
+      'workspace:',
+      '  mode: parent',
+      '  repositories:',
+      '    frontend:',
+      '      path: frontend',
+      '    backend:',
+      '      path: backend',
+      '---',
+    ].join('\n'),
+    'utf-8',
+  );
+}
+
 function validParams() {
   return {
     milestoneId: 'M001',
@@ -55,7 +75,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 +85,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'));
@@ -136,6 +175,32 @@ test('handlePlanTask rejects absolute task IO paths outside the active worktree'
   }
 });
 
+test('handlePlanTask rejects parent-checkout task IO paths from an active worktree', async () => {
+  const projectRoot = mkdtempSync(join(tmpdir(), 'gsd-plan-task-project-'));
+  const worktree = join(projectRoot, '.gsd', 'worktrees', 'M001');
+  mkdirSync(join(projectRoot, '.gsd'), { recursive: true });
+  mkdirSync(join(worktree, '.gsd', 'phases', '01-test'), { recursive: true });
+  openDatabase(join(projectRoot, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const parentCheckoutPath = join(projectRoot, 'src', 'index.ts');
+    const result = await handlePlanTask({
+      ...validParams(),
+      files: [parentCheckoutPath],
+      inputs: [parentCheckoutPath],
+      expectedOutput: [parentCheckoutPath],
+    }, worktree);
+
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: files contains path outside allowed repository roots/);
+    assert.match(result.error, new RegExp(worktree.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')));
+    assert.equal(getTask('M001', 'S02', 'T02'), null, 'parent-checkout paths must not persist worktree task planning');
+  } finally {
+    cleanup(projectRoot);
+  }
+});
+
 test('handlePlanTask rejects missing parent slice', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));
@@ -157,7 +222,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 +235,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);
@@ -200,3 +289,220 @@ test('handlePlanTask reruns idempotently and refreshes parse-visible state', asy
     cleanup(base);
   }
 });
+
+test('handlePlanTask persists targetRepositories for parent-workspace tasks', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const result = await handlePlanTask({
+      ...validParams(),
+      targetRepositories: ['project'],
+    }, base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    const tasks = getSliceTasks('M001', 'S02');
+    const planned = tasks.find((t) => t.id === 'T02');
+    assert.ok(planned, 'planned task should exist');
+    assert.deepEqual(planned?.target_repositories, ['project']);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask rejects non-array targetRepositories', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const result = await handlePlanTask({
+      ...validParams(),
+      targetRepositories: 'frontend' as unknown as string[],
+    }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: targetRepositories/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask rejects empty targetRepositories', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const result = await handlePlanTask({
+      ...validParams(),
+      targetRepositories: [],
+    }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: targetRepositories must include at least one repository id when provided/);
+    assert.equal(getTask('M001', 'S02', 'T02'), null, 'invalid target repositories must not persist');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask rejects unknown target repositories', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    const result = await handlePlanTask({
+      ...validParams(),
+      targetRepositories: ['frontend'],
+    }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: unknown targetRepositories:/);
+    assert.equal(getTask('M001', 'S02', 'T02'), null, 'unknown target repositories must not persist');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask enforces path scope to declared target repositories', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    mkdirSync(join(base, 'frontend', 'src'), { recursive: true });
+    mkdirSync(join(base, 'backend', 'src'), { recursive: true });
+    writeFileSync(
+      join(base, '.gsd', 'PREFERENCES.md'),
+      [
+        '---',
+        'workspace:',
+        '  mode: parent',
+        '  repositories:',
+        '    frontend:',
+        '      path: frontend',
+        '    backend:',
+        '      path: backend',
+        '---',
+      ].join('\n'),
+      'utf-8',
+    );
+
+    const result = await handlePlanTask({
+      ...validParams(),
+      targetRepositories: ['frontend'],
+      files: [join(base, 'backend', 'src', 'server.ts')],
+      inputs: ['app.js'],
+      expectedOutput: ['app.js'],
+    }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: files contains path outside allowed repository roots/);
+    assert.equal(getTask('M001', 'S02', 'T02'), null, 'invalid scoped paths must not persist');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask inherits parent slice target repositories for path scope', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    insertSlice({
+      id: 'S02',
+      milestoneId: 'M001',
+      planning: { targetRepositories: ['frontend'] },
+    });
+    writeParentWorkspacePreferences(base);
+
+    const result = await handlePlanTask({
+      ...validParams(),
+      files: [join(base, 'backend', 'src', 'server.ts')],
+      inputs: ['app.js'],
+      expectedOutput: ['app.js'],
+    }, base);
+    assert.ok('error' in result);
+    assert.match(result.error, /validation failed: files contains path outside allowed repository roots/);
+    assert.equal(getTask('M001', 'S02', 'T02'), null, 'slice-scoped invalid paths must not persist');
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask preserves stored task target repositories when omitted replan needs them for path scope', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    writeParentWorkspacePreferences(base);
+    insertSlice({
+      id: 'S02',
+      milestoneId: 'M001',
+      planning: { targetRepositories: ['frontend'] },
+    });
+    insertTask({
+      id: 'T02',
+      sliceId: 'S02',
+      milestoneId: 'M001',
+      title: 'Parent root work',
+      status: 'pending',
+      planning: { targetRepositories: ['project'] },
+    });
+
+    const rootFile = join(base, 'root-config.json');
+    const result = await handlePlanTask({
+      ...validParams(),
+      files: [rootFile],
+      inputs: [rootFile],
+      expectedOutput: [rootFile],
+    }, base);
+
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+    assert.deepEqual(getTask('M001', 'S02', 'T02')?.target_repositories, ['project']);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handlePlanTask follows the current slice target default when omitted replan paths validate there', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedParent();
+    writeParentWorkspacePreferences(base);
+    insertSlice({
+      id: 'S02',
+      milestoneId: 'M001',
+      planning: { targetRepositories: ['frontend'] },
+    });
+    insertTask({
+      id: 'T02',
+      sliceId: 'S02',
+      milestoneId: 'M001',
+      title: 'Child repo work',
+      status: 'pending',
+      planning: { targetRepositories: ['frontend'] },
+    });
+    insertSlice({
+      id: 'S02',
+      milestoneId: 'M001',
+      planning: { targetRepositories: ['backend'] },
+    });
+
+    const backendFile = join(base, 'backend', 'src', 'server.ts');
+    const result = await handlePlanTask({
+      ...validParams(),
+      files: [backendFile],
+      inputs: [backendFile],
+      expectedOutput: [backendFile],
+    }, base);
+
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+    assert.deepEqual(getTask('M001', 'S02', 'T02')?.target_repositories, ['backend']);
+  } finally {
+    cleanup(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");
+});

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

@@ -0,0 +1,107 @@
+// Project/App: gsd-pi
+// File Purpose: Schema-2 compat marker tests — the `planning` field.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import {
+  readCompatMarker,
+  writeCompatMarker,
+  EMPTY_MARKER,
+  COMPAT_MARKER_SCHEMA,
+} from "../compat/compat-marker.ts";
+
+const tmpDirs: string[] = [];
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-pm-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+afterEach(() => {
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+test("schema version is 2", () => {
+  assert.equal(COMPAT_MARKER_SCHEMA, 2);
+});
+
+test("EMPTY_MARKER has planning inactive with empty maps", () => {
+  assert.deepEqual(EMPTY_MARKER.planning, {
+    active: false,
+    layout: null,
+    projections: {},
+    passthrough: {},
+  });
+});
+
+test("writeCompatMarker then readCompatMarker round-trips planning field", () => {
+  const base = makeTmpBase();
+  const marker = {
+    schema: 2,
+    lastWriter: "gsd-pi" as const,
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases" as const,
+      projections: {
+        "ROADMAP.md": { sha: "abc", entities: ["M001"] },
+      },
+      passthrough: {
+        "codebase/STACK.md": { sha: "def", entities: [] },
+      },
+    },
+    piVersion: "1.4.0",
+  };
+  writeCompatMarker(base, marker);
+  const read = readCompatMarker(base);
+  assert.deepEqual(read.planning, marker.planning);
+});
+
+test("readCompatMarker promotes a schema-1 marker by defaulting planning inactive", () => {
+  const base = makeTmpBase();
+  // Hand-write a schema-1 marker (no planning field).
+  const v1 = {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-01T00:00:00.000Z",
+    projections: { "x.md": { sha: "1", entities: [] } },
+    piVersion: "1.3.0",
+  };
+  writeFileSync(join(base, ".gsd", ".compat.json"), JSON.stringify(v1), "utf-8");
+
+  const read = readCompatMarker(base);
+  // Promotion: planning defaults inactive. (raw schema value preserved on read;
+  // promotion is at read-time, a rewrite would emit schema 2.)
+  assert.deepEqual(read.planning, { active: false, layout: null, projections: {}, passthrough: {} });
+});
+
+test("emptyMarker returns independent planning objects (no shared reference)", () => {
+  // Mutating one empty-marker read must not pollute another.
+  const base1 = makeTmpBase();
+  const base2 = makeTmpBase();
+  const m1 = readCompatMarker(base1);
+  m1.planning!.projections["x"] = { sha: "1", entities: [] };
+  const m2 = readCompatMarker(base2);
+  assert.equal(m2.planning!.projections["x"], undefined);
+});
+
+test("readCompatMarker quarantines a marker with invalid planning field", () => {
+  const base = makeTmpBase();
+  const bad = {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: { active: "not-a-boolean" }, // invalid
+    piVersion: "1.4.0",
+  };
+  writeFileSync(join(base, ".gsd", ".compat.json"), JSON.stringify(bad), "utf-8");
+  const read = readCompatMarker(base);
+  assert.deepEqual(read.planning, { active: false, layout: null, projections: {}, passthrough: {} });
+});