@opengsd/gsd-pi 1.7.0 → 1.8.1-dev.897b3c90

package/src/resources/extensions/gsd/tests/parallel-monitor-overlay.test.ts

@@ -108,6 +108,65 @@ describe("parallel-monitor-overlay", () => {
     }
   });
 
+  it("merged worker query renders slice progress and completions across multiple slices", async () => {
+    // Regression guard for the single-open merge: queryWorkerProgress now
+    // returns { slices, completions } from ONE connection per worker per tick.
+    // A worker spanning two slices, each with a completed task, must still
+    // surface every slice's progress AND both completions (previously two
+    // separate DB opens produced these).
+    const base = mkdtempSync(join(tmpdir(), "gsd-parallel-overlay-multi-"));
+
+    try {
+      mkdirSync(join(base, ".gsd", "parallel"), { recursive: true });
+      assert.equal(openDatabase(join(base, ".gsd", "gsd.db")), true);
+      insertMilestone({ id: "M001", title: "Multi-slice Fixture" });
+      insertSlice({ milestoneId: "M001", id: "S01", title: "First", status: "pending", sequence: 1 });
+      insertSlice({ milestoneId: "M001", id: "S02", title: "Second", status: "pending", sequence: 2 });
+      insertTask({ milestoneId: "M001", sliceId: "S01", id: "T01", status: "complete", oneLiner: "alpha done", sequence: 1 });
+      insertTask({ milestoneId: "M001", sliceId: "S01", id: "T02", status: "pending", sequence: 2 });
+      insertTask({ milestoneId: "M001", sliceId: "S02", id: "T01", status: "complete", oneLiner: "beta done", sequence: 1 });
+      insertTask({ milestoneId: "M001", sliceId: "S02", id: "T02", status: "pending", sequence: 2 });
+      closeDatabase();
+
+      writeFileSync(
+        join(base, ".gsd", "parallel", "M001.status.json"),
+        JSON.stringify({
+          milestoneId: "M001",
+          pid: process.pid,
+          state: "running",
+          cost: 0,
+          lastHeartbeat: Date.now(),
+          startedAt: Date.now() - 30_000,
+          worktreePath: join(base, ".gsd-worktrees", "M001"),
+        }),
+        "utf-8",
+      );
+
+      const mod = await import("../parallel-monitor-overlay.js");
+      const mockTui = { requestRender: () => {} };
+      const mockTheme = {
+        fg: (_color: string, text: string) => text,
+        bold: (text: string) => text,
+      };
+      const overlay = new mod.ParallelMonitorOverlay(mockTui, mockTheme as any, () => {}, base);
+
+      try {
+        const joined = overlay.render(120).join("\n");
+        // Both slices' progress must come from the single merged query.
+        assert.match(joined, /S01:1\/2/, "S01 progress should render from the merged query");
+        assert.match(joined, /S02:1\/2/, "S02 progress should render from the merged query");
+        // Completions for tasks in both slices ride along on the same DB open.
+        assert.match(joined, /S01\/T01: alpha done/, "S01 completion should render");
+        assert.match(joined, /S02\/T01: beta done/, "S02 completion should render");
+      } finally {
+        overlay.dispose();
+      }
+    } finally {
+      try { closeDatabase(); } catch { /* already closed */ }
+      rmSync(base, { recursive: true, force: true });
+    }
+  });
+
   it("progressBar generates correct width", async () => {
     // Dynamic import to test the module loads cleanly
     const mod = await import("../parallel-monitor-overlay.js");

package/src/resources/extensions/gsd/tests/parsers-legacy-importers.test.ts

@@ -47,6 +47,9 @@ const ALLOWED_IMPORTERS = new Set([
   "gsd/migration-auto-check.ts",
   // drift detection: compares markdown projection against DB by design
   "gsd/state-reconciliation/drift/roadmap.ts",
+  // drift detection: reads PLAN.md tasks to distinguish a real plan from a
+  // stub before clearing a stale is_sketch flag (#1287)
+  "gsd/state-reconciliation/drift/sketch-flag.ts",
   // stale-render detection + render verification helpers over rendered output
   "gsd/markdown-renderer.ts",
   // pre-migration fallback: deriveState must work before the DB exists
@@ -58,6 +61,7 @@ const ALLOWED_IMPORTERS = new Set([
   "gsd/artifact-verification.ts",
   // diagnostics-only surfaces: report on projections, make no dispatch decisions
   "gsd/doctor.ts",
+  "gsd/doctor-state-checks.ts",
   // diagnostics-only: compares PLAN.md task checkboxes against DB status
   "gsd/doctor-engine-checks.ts",
   // display/telemetry-only surfaces

package/src/resources/extensions/gsd/tests/phase-anchor.test.ts

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { mkdtempSync, mkdirSync, rmSync, existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -9,11 +9,11 @@ import type { PhaseAnchor } from "../phase-anchor.js";
 
 function makeTempBase(): string {
   const tmp = mkdtempSync(join(tmpdir(), "gsd-anchor-test-"));
-  mkdirSync(join(tmp, ".gsd", "milestones", "M001", "anchors"), { recursive: true });
+  mkdirSync(join(tmp, ".gsd"), { recursive: true });
   return tmp;
 }
 
-test("writePhaseAnchor creates anchor file in correct location", () => {
+test("writePhaseAnchor creates anchor file under runtime state", () => {
   const base = makeTempBase();
   try {
     const anchor: PhaseAnchor = {
@@ -26,7 +26,35 @@ test("writePhaseAnchor creates anchor file in correct location", () => {
       nextSteps: ["Plan the implementation slices"],
     };
     writePhaseAnchor(base, "M001", anchor);
-    assert.ok(existsSync(join(base, ".gsd", "milestones", "M001", "anchors", "discuss.json")));
+    assert.ok(existsSync(join(base, ".gsd", "runtime", "anchors", "M001", "discuss.json")));
+    assert.equal(existsSync(join(base, ".gsd", "milestones", "M001", "anchors", "discuss.json")), false);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("readPhaseAnchor falls back to legacy anchor location", () => {
+  const base = makeTempBase();
+  try {
+    const legacyDir = join(base, ".gsd", "milestones", "M001", "anchors");
+    mkdirSync(legacyDir, { recursive: true });
+    writeFileSync(
+      join(legacyDir, "research-slice.json"),
+      JSON.stringify({
+        phase: "research-slice",
+        milestoneId: "M001",
+        generatedAt: "2026-07-07T00:00:00.000Z",
+        intent: "Keep reading old anchors during upgrade.",
+        decisions: [],
+        blockers: [],
+        nextSteps: [],
+      }),
+      "utf-8",
+    );
+
+    const read = readPhaseAnchor(base, "M001", "research-slice");
+    assert.ok(read);
+    assert.equal(read.intent, "Keep reading old anchors during upgrade.");
   } finally {
     rmSync(base, { recursive: true, force: true });
   }

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

@@ -6,7 +6,7 @@ import { tmpdir } from 'node:os';
 
 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';
+import { parsePlan } from '../parsers-legacy.ts';
 
 function makeTmpBase(): string {
   const base = mkdtempSync(join(tmpdir(), 'gsd-plan-task-'));
@@ -60,7 +60,7 @@ function validParams() {
   };
 }
 
-test('handlePlanTask writes planning state and renders task plan', async () => {
+test('handlePlanTask writes planning state and renders the flat-phase slice plan', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));
 
@@ -75,11 +75,13 @@ 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', '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);
-    assert.deepEqual(taskPlan.frontmatter.skills_used, []);
+    const slicePlanPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    assert.equal(result.taskPlanPath, slicePlanPath);
+    assert.ok(existsSync(slicePlanPath), 'slice plan should be rendered to disk');
+    assert.equal(existsSync(join(base, '.gsd', 'phases', '01-test', 'T02-PLAN.md')), false);
+    const slicePlan = parsePlan(readFileSync(slicePlanPath, 'utf-8'));
+    assert.equal(slicePlan.tasks[0]?.id, 'T02');
+    assert.equal(slicePlan.tasks[0]?.files?.[0], 'src/resources/extensions/gsd/tools/plan-task.ts');
   } finally {
     cleanup(base);
   }
@@ -215,17 +217,17 @@ test('handlePlanTask rejects missing parent slice', async () => {
   }
 });
 
-test('handlePlanTask surfaces render failures without changing parse-visible task plan state', async () => {
+test('handlePlanTask surfaces render failures without changing parse-visible slice 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', '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 });
+    const slicePlanPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    writeFileSync(slicePlanPath, '# S02: Cached slice\n\n<tasks>\n- [ ] **T02**: Cached task\n</tasks>\n', 'utf-8');
+    rmSync(slicePlanPath, { force: true });
+    mkdirSync(slicePlanPath, { recursive: true });
 
     const result = await handlePlanTask(validParams(), base);
     assert.ok('error' in result);
@@ -243,15 +245,16 @@ test('handlePlanTask keeps the sketch flag set when the flat-phase slice plan sy
     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.
+    // The flat-phase slice render targets phases/01-test/01-02-PLAN.md.
+    // Pre-creating that path as a directory forces EISDIR, 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.ok('error' in result);
+    assert.match(result.error, /render failed:/);
     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 {
@@ -265,8 +268,8 @@ test('handlePlanTask reruns idempotently and refreshes parse-visible state', asy
 
   try {
     seedParent();
-    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 slicePlanPath = join(base, '.gsd', 'phases', '01-test', '01-02-PLAN.md');
+    writeFileSync(slicePlanPath, '# S02: Cached slice\n\n<tasks>\n- [ ] **T02**: Cached task\n</tasks>\n', 'utf-8');
 
     const first = await handlePlanTask(validParams(), base);
     assert.ok(!('error' in first));
@@ -282,9 +285,9 @@ test('handlePlanTask reruns idempotently and refreshes parse-visible state', asy
     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\./);
+    const parsed = parsePlan(readFileSync(slicePlanPath, 'utf-8'));
+    assert.equal(parsed.tasks[0]?.id, 'T02');
+    assert.match(readFileSync(slicePlanPath, 'utf-8'), /Updated task handler description\./);
   } finally {
     cleanup(base);
   }

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

@@ -8,7 +8,7 @@ import { tmpdir } from "node:os";
 import { randomUUID } from "node:crypto";
 
 import { writePlanningDirectory } from "../migrate/planning-writer.ts";
-import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, updateTaskStatus } from "../gsd-db.ts";
 
 const tmpDirs: string[] = [];
 function makeTmp(): string {
@@ -65,6 +65,23 @@ test("writePlanningDirectory emits phase plan file with XML structure", async ()
   assert.match(plan, /<tasks>/);
 });
 
+test("writePlanningDirectory renders completed task checkboxes as [x] (#1276)", async () => {
+  const base = makeTmp();
+  updateTaskStatus("M001", "S01", "T01", "complete");
+  await writePlanningDirectory(base, "flat-phases");
+
+  const phaseDir = readdirSync(join(base, ".planning", "phases"), { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)[0]!;
+  const planFile = readdirSync(join(base, ".planning", "phases", phaseDir))
+    .filter((f) => f.endsWith("PLAN.md"))[0]!;
+  const plan = readFileSync(join(base, ".planning", "phases", phaseDir, planFile), "utf-8");
+  assert.match(plan, /- \[x\] \*\*T01\*\*/, "completed task should project as [x], not [ ]");
+
+  const roadmap = readFileSync(join(base, ".planning", "ROADMAP.md"), "utf-8");
+  assert.match(roadmap, /- \[x\] 01 —/, "phase with all tasks complete should be [x] in ROADMAP");
+});
+
 test("writePlanningDirectory is idempotent: writing twice produces stable content", async () => {
   const base = makeTmp();
   await writePlanningDirectory(base, "flat-phases");
@@ -75,6 +92,35 @@ test("writePlanningDirectory is idempotent: writing twice produces stable conten
   assert.equal(roadmap2, roadmap1);
 });
 
+test("writePlanningDirectory does not emit an ingestible PLAN.md for a task-less (sketch) slice", async () => {
+  // Regression for #1285: a milestone-level sketch slice has zero DB tasks.
+  // The projection must not write a placeholder NN-01-PLAN.md — the reverse
+  // transform maps one task per plan file, so a placeholder would materialize
+  // a phantom "Plan NN" task and make auto-mode skip planning.
+  const base = makeTmp();
+  insertSlice({
+    milestoneId: "M001", id: "S02", title: "Sketch slice", status: "pending",
+    risk: "medium", depends: ["S01"], demo: "designed", sequence: 2,
+  });
+  // S02 intentionally has no tasks.
+
+  await writePlanningDirectory(base, "flat-phases");
+
+  const phaseDirs = readdirSync(join(base, ".planning", "phases"), { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name);
+  const sketchDir = phaseDirs.find((d) => /^02-/.test(d));
+  assert.ok(sketchDir, `expected a 02- phase dir for the sketch slice, got ${JSON.stringify(phaseDirs)}`);
+
+  const planFiles = readdirSync(join(base, ".planning", "phases", sketchDir!))
+    .filter((f) => f.endsWith("PLAN.md"));
+  assert.equal(planFiles.length, 0, `sketch slice should have no PLAN.md, got ${JSON.stringify(planFiles)}`);
+
+  // The slice remains discoverable via ROADMAP.md.
+  const roadmap = readFileSync(join(base, ".planning", "ROADMAP.md"), "utf-8");
+  assert.match(roadmap, /Sketch slice/);
+});
+
 test("writePlanningDirectory throws for unsupported layouts", async () => {
   const base = makeTmp();
   await assert.rejects(() => writePlanningDirectory(base, "multi-milestone"), /not yet supported/);

package/src/resources/extensions/gsd/tests/post-execution-checks.test.ts

@@ -496,6 +496,28 @@ describe("checkImportResolution", () => {
     }
   });
 
+  test("ignores generated Convex _generated imports", () => {
+    tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`);
+    mkdirSync(tempDir, { recursive: true });
+    mkdirSync(join(tempDir, "convex"), { recursive: true });
+    writeFileSync(
+      join(tempDir, "convex", "stagedLibraryEdits.ts"),
+      "import type { DataModel } from './_generated/dataModel';\nexport const model = {} as DataModel;"
+    );
+
+    try {
+      const task = createTask({
+        id: "T01",
+        key_files: ["convex/stagedLibraryEdits.ts"],
+      });
+
+      const results = checkImportResolution(task, [], tempDir);
+      assert.deepEqual(results, []);
+    } finally {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
   test("fails when import doesn't resolve", () => {
     tempDir = join(tmpdir(), `post-exec-test-${Date.now()}`);
     mkdirSync(tempDir, { recursive: true });

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

@@ -76,6 +76,21 @@ function writeS01Artifacts(base: string): void {
   writeFileSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md"), "# S01 Summary\n");
 }
 
+// A *real* decomposed PLAN (>= 1 genuine task). #1287: the stale-sketch-flag
+// detector requires a real plan — not a bare stub — before clearing is_sketch.
+function realPlanContent(sliceId: string): string {
+  return [
+    `# ${sliceId}: Feature`,
+    "",
+    "**Goal:** Ship the feature",
+    "",
+    "## Tasks",
+    "",
+    "- [ ] **T01: Build the feature** `est:1h`",
+    "",
+  ].join("\n");
+}
+
 function cleanup(base: string, originalCwd: string): void {
   try { closeDatabase(); } catch { /* noop */ }
   process.chdir(originalCwd);
@@ -185,7 +200,7 @@ test("ADR-011: existing PLAN + stale sketch flag heals via reconcileBeforeDispat
   writePreferences(base, "phases:\n  progressive_planning: true");
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   process.chdir(base);
 
@@ -252,7 +267,7 @@ test("ADR-011: reconcileBeforeDispatch auto-heals stale sketch flag when PLAN ex
   // Simulate plan-slice completion where PLAN exists but is_sketch was not flipped.
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   process.chdir(base);
 
@@ -282,7 +297,7 @@ test("ADR-011: deriveState stays pure across worktree/canonical-root; healing be
   writePreferences(base, "phases:\n  skip_research: false");
   writeFileSync(
     join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-PLAN.md"),
-    "# S02 Plan\n",
+    realPlanContent("S02"),
   );
   const worktreePath = join(base, "worker");
   mkdirSync(worktreePath, { recursive: true });

package/src/resources/extensions/gsd/tests/reassess-handler.test.ts

@@ -210,6 +210,56 @@ test('handleReassessRoadmap succeeds when modifying only pending slices', async
   }
 });
 
+test('handleReassessRoadmap writes legacy-layout reassessment to S##-ASSESSMENT.md', async () => {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-reassess-legacy-'));
+  mkdirSync(join(base, '.gsd', 'milestones', 'M005-3qxqd7', 'slices', 'S04'), { recursive: true });
+  mkdirSync(join(base, '.gsd', 'phases', '05-3qxqd7-legacy-milestone'), { recursive: true });
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    insertMilestone({ id: 'M005-3qxqd7', title: 'Legacy Milestone', status: 'active' });
+    insertSlice({
+      id: 'S04',
+      milestoneId: 'M005-3qxqd7',
+      title: 'Legacy Slice Four',
+      status: 'complete',
+      demo: 'Demo four.',
+    });
+
+    const result = await handleReassessRoadmap({
+      milestoneId: 'M005-3qxqd7',
+      completedSliceId: 'S04',
+      verdict: 'confirmed',
+      assessment: 'S04 completed successfully. Roadmap remains valid.',
+      sliceChanges: {
+        modified: [],
+        added: [],
+        removed: [],
+      },
+    }, base);
+
+    if ('error' in result) {
+      assert.fail(`unexpected error: ${result.error}`);
+    }
+
+    const correctPath = join(base, '.gsd', 'milestones', 'M005-3qxqd7', 'slices', 'S04', 'S04-ASSESSMENT.md');
+    const wrongFlatNameInLegacyDir = join(base, '.gsd', 'milestones', 'M005-3qxqd7', 'slices', 'S04', '05-04-ASSESSMENT.md');
+    const wrongFlatPhasePath = join(base, '.gsd', 'phases', '05-3qxqd7-legacy-milestone', '05-04-ASSESSMENT.md');
+    assert.match(
+      result.assessmentPath.replace(/\\/g, '/'),
+      /\/\.gsd\/milestones\/M005-3qxqd7\/slices\/S04\/S04-ASSESSMENT\.md$/,
+    );
+    assert.ok(existsSync(correctPath), 'legacy ASSESSMENT should use S## filename inside slices/S##/');
+    assert.equal(existsSync(wrongFlatNameInLegacyDir), false, 'legacy slice dir must not receive flat-phase assessment filename');
+    assert.equal(existsSync(wrongFlatPhasePath), false, 'legacy reassessment must not be diverted to a coexisting flat-phase dir');
+
+    const assessment = getAssessment('.gsd/milestones/M005-3qxqd7/slices/S04/S04-ASSESSMENT.md');
+    assert.ok(assessment, 'assessment row should use the legacy-layout path');
+  } finally {
+    cleanup(base);
+  }
+});
+
 test('handleReassessRoadmap cache invalidation: getMilestoneSlices reflects mutations', async () => {
   const base = makeTmpBase();
   openDatabase(join(base, '.gsd', 'gsd.db'));

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

@@ -0,0 +1,103 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertTask,
+  upsertTaskPlanning,
+  getTask,
+  getReplanHistory,
+} from '../gsd-db.ts';
+import { handleReplanTask } from '../tools/replan-task.ts';
+
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-replan-task-'));
+  mkdirSync(join(base, '.gsd', 'phases', '01-test'), { recursive: true });
+  return base;
+}
+
+function cleanup(base: string): void {
+  try { closeDatabase(); } catch { /* noop */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* noop */ }
+}
+
+function seedTask(status = 'pending'): void {
+  insertMilestone({ id: 'M001', title: 'Test Milestone', status: 'active' });
+  insertSlice({ id: 'S01', milestoneId: 'M001', title: 'Test Slice', status: 'active', demo: 'Demo.' });
+  insertTask({ id: 'T01', sliceId: 'S01', milestoneId: 'M001', title: 'Original Task', status });
+  upsertTaskPlanning('M001', 'S01', 'T01', {
+    description: 'Original task description.',
+    estimate: '30m',
+    files: ['src/original.ts'],
+    verify: 'node --test original.test.ts',
+    inputs: ['src/original.ts'],
+    expectedOutput: ['src/original.ts'],
+  });
+}
+
+function validReplanTaskParams() {
+  return {
+    milestoneId: 'M001',
+    sliceId: 'S01',
+    taskId: 'T01',
+    title: 'Replanned Task',
+    description: 'Updated task description with blocking rework scope.',
+    estimate: '45m',
+    files: ['src/replanned.ts'],
+    verify: 'node --test replanned.test.ts',
+    inputs: ['src/original.ts'],
+    expectedOutput: ['src/replanned.ts'],
+    reworkBriefRef: 'RB-001',
+  };
+}
+
+test('handleReplanTask updates one pending task plan and records a task-scoped replan history entry', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedTask('pending');
+
+    const result = await handleReplanTask(validReplanTaskParams(), base);
+    assert.ok(!('error' in result), `unexpected error: ${'error' in result ? result.error : ''}`);
+
+    const task = getTask('M001', 'S01', 'T01');
+    assert.ok(task, 'task should still exist');
+    assert.equal(task.title, 'Replanned Task');
+    assert.equal(task.description, 'Updated task description with blocking rework scope.');
+    assert.equal(task.verify, 'node --test replanned.test.ts');
+    assert.deepEqual(task.files, ['src/replanned.ts']);
+
+    const history = getReplanHistory('M001', 'S01');
+    assert.ok(history.some((row) => row['task_id'] === 'T01' && String(row['summary']).includes('RB-001')));
+
+    const planPath = join(base, '.gsd', 'phases', '01-test', '01-01-PLAN.md');
+    assert.ok(existsSync(planPath), 'slice plan projection should be rendered');
+    const planContent = readFileSync(planPath, 'utf-8');
+    assert.match(planContent, /Replanned Task/);
+    assert.match(planContent, /node --test replanned\.test\.ts/);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test('handleReplanTask rejects completed tasks', async () => {
+  const base = makeTmpBase();
+  openDatabase(join(base, '.gsd', 'gsd.db'));
+
+  try {
+    seedTask('complete');
+
+    const result = await handleReplanTask(validReplanTaskParams(), base);
+    assert.ok('error' in result);
+    assert.match(result.error, /cannot replan completed task T01/i);
+  } finally {
+    cleanup(base);
+  }
+});