@opengsd/gsd-pi 1.8.1 → 1.9.0

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

@@ -57,6 +57,19 @@ test("needsFlatPhaseMigration returns false when no .gsd/milestones/", () => {
   assert.equal(needsFlatPhaseMigration(base), false);
 });
 
+test("needsFlatPhaseMigration ignores legacy anchor runtime scaffolding", () => {
+  const base = mkdtempSync(join(tmpdir(), `gsd-anchor-nomig-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd", "phases"), { recursive: true });
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "anchors"), { recursive: true });
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "anchors", "research-slice.json"),
+    "{}",
+    "utf-8",
+  );
+  tmpDirs.push(base);
+  assert.equal(needsFlatPhaseMigration(base), false);
+});
+
 test("migrateToFlatPhase moves content from milestones/ to phases/", async () => {
   const base = makeTmp();
   await migrateToFlatPhase(base);
@@ -109,6 +122,59 @@ test("migrateToFlatPhase creates a backup", async () => {
   assert.ok(backups.length >= 1, "at least one migrate-* backup dir should exist");
 });
 
+test("migrateToFlatPhase backs up existing phases projection before clearing it", async () => {
+  const base = makeTmp();
+  const reviewPath = join(base, ".gsd", "phases", "01-foundation", "PLAN-REVIEW.md");
+  mkdirSync(join(base, ".gsd", "phases", "01-foundation"), { recursive: true });
+  writeFileSync(reviewPath, "# Plan Review\n\nHand-authored review.", "utf-8");
+
+  await migrateToFlatPhase(base);
+
+  const backupRoot = join(base, ".gsd-backups");
+  const backups = readdirSync(backupRoot).filter(d => d.startsWith("migrate-"));
+  assert.equal(backups.length, 1, "one migrate backup should exist");
+  const backedUpReview = join(backupRoot, backups[0]!, "__phases", "01-foundation", "PLAN-REVIEW.md");
+  assert.equal(
+    readFileSync(backedUpReview, "utf-8"),
+    "# Plan Review\n\nHand-authored review.",
+    "pre-existing phases/ files should have a recovery copy",
+  );
+});
+
+test("failed migration restores pre-existing phases projection from backup", async (t) => {
+  const base = makeTmp();
+  const phasesPath = join(base, ".gsd", "phases");
+  const reviewPath = join(phasesPath, "01-foundation", "PLAN-REVIEW.md");
+  mkdirSync(join(phasesPath, "01-foundation"), { recursive: true });
+  writeFileSync(reviewPath, "# Plan Review\n\nHand-authored review.", "utf-8");
+
+  let sabotagedClear = false;
+  const restoreFsOps = _setFlatPhaseMigrationFsOpsForTest({
+    rmSync(target, opts) {
+      rmSync(target, opts as never);
+      if (target === phasesPath && !sabotagedClear) {
+        sabotagedClear = true;
+        writeFileSync(phasesPath, "not a directory", "utf-8");
+      }
+    },
+  });
+  t.after(restoreFsOps);
+
+  await assert.rejects(migrateToFlatPhase(base), /flat-phase migration render failed/);
+
+  assert.equal(sabotagedClear, true, "test should force a post-clear render failure");
+  assert.equal(
+    readFileSync(reviewPath, "utf-8"),
+    "# Plan Review\n\nHand-authored review.",
+    "rollback should restore the pre-existing phases/ files",
+  );
+  const backupRoot = join(base, ".gsd-backups");
+  const leaked = existsSync(backupRoot)
+    ? readdirSync(backupRoot).filter((d) => d.startsWith("migrate-"))
+    : [];
+  assert.equal(leaked.length, 0, "rollback should still clean the backup it created");
+});
+
 test("failed migration rolls back without leaking a .gsd-backups/migrate-* dir", async (t) => {
   const base = makeTmp();
   const milestonesPath = join(base, ".gsd", "milestones");
@@ -136,6 +202,33 @@ test("failed migration rolls back without leaking a .gsd-backups/migrate-* dir",
   assert.equal(leaked.length, 0, "rollback must delete the migrate-* backup it created");
 });
 
+test("resumed migration stores phases backup in retained migrate snapshot", async () => {
+  const base = makeTmp();
+  const milestonesPath = join(base, ".gsd", "milestones");
+  const migratingPath = join(base, ".gsd", "milestones.migrating");
+  const reviewPath = join(base, ".gsd", "phases", "01-foundation", "PLAN-REVIEW.md");
+  mkdirSync(join(base, ".gsd", "phases", "01-foundation"), { recursive: true });
+  writeFileSync(reviewPath, "# Plan Review\n\nResume recovery copy.", "utf-8");
+  renameSync(milestonesPath, migratingPath);
+
+  await migrateToFlatPhase(base);
+
+  assert.equal(existsSync(migratingPath), false, "resume staging dir should be removed after success");
+  const backupRoot = join(base, ".gsd-backups");
+  const backups = readdirSync(backupRoot).filter((d) => d.startsWith("migrate-"));
+  assert.equal(backups.length, 1, "resumed migration should create one retained migrate backup");
+  assert.equal(
+    readFileSync(join(backupRoot, backups[0]!, "__phases", "01-foundation", "PLAN-REVIEW.md"), "utf-8"),
+    "# Plan Review\n\nResume recovery copy.",
+    "resume should retain the phases snapshot under .gsd-backups",
+  );
+  assert.equal(
+    existsSync(join(migratingPath, "__phases")),
+    false,
+    "resume should not store the phases snapshot inside the disposable migrating tree",
+  );
+});
+
 test("migrateToFlatPhase preserves milestone/slice/task counts in DB", async () => {
   const base = makeTmp();
   const msBefore = getAllMilestones().length;
@@ -190,6 +283,42 @@ test("migrateToFlatPhase prunes legacy milestones artifact rows after flat rende
   );
 });
 
+test("migrateToFlatPhase prunes stale flat-phase artifact rows that renderAll intentionally skips", async () => {
+  const base = makeTmp();
+  insertArtifact({
+    path: "phases/01-foundation/T01-PLAN.md",
+    artifact_type: "PLAN",
+    milestone_id: "M001",
+    slice_id: "S01",
+    task_id: "T01",
+    full_content: "# Legacy standalone task plan\n",
+  });
+  insertArtifact({
+    path: "phases/01-foundation/01-01-RESEARCH.md",
+    artifact_type: "RESEARCH",
+    milestone_id: "M001",
+    slice_id: "S01",
+    task_id: null,
+    full_content: "",
+  });
+
+  await migrateToFlatPhase(base);
+
+  const rows = _getAdapter()!
+    .prepare("SELECT path FROM artifacts ORDER BY path")
+    .all() as Array<{ path: string }>;
+  assert.equal(
+    rows.some((row) => row.path === "phases/01-foundation/T01-PLAN.md"),
+    false,
+    "standalone task PLAN rows should be pruned when the flat renderer does not recreate the file",
+  );
+  assert.equal(
+    rows.some((row) => row.path === "phases/01-foundation/01-01-RESEARCH.md"),
+    false,
+    "empty-content artifact rows should be pruned when the flat renderer skips the file",
+  );
+});
+
 test("migrateToFlatPhase is idempotent (second run is a no-op)", async () => {
   const base = makeTmp();
   await migrateToFlatPhase(base);
@@ -199,6 +328,79 @@ test("migrateToFlatPhase is idempotent (second run is a no-op)", async () => {
   assert.equal(backups.length, 1, "should only have one backup");
 });
 
+test("re-fired migration reuses the existing backup instead of leaking a new migrate-* dir (#1292)", async () => {
+  const base = makeTmp();
+  await migrateToFlatPhase(base);
+  const backupRoot = join(base, ".gsd-backups");
+  const firstBackups = readdirSync(backupRoot).filter((d) => d.startsWith("migrate-"));
+  assert.equal(firstBackups.length, 1, "first migration snapshots exactly one backup");
+
+  // Simulate the re-fire: the legacy .gsd/milestones/ layout reappears (e.g. a
+  // marker-key mismatch re-imports the whole tree). The DB rows still exist, so
+  // the migration gate proceeds again — it must not snapshot a second backup.
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01"), { recursive: true });
+  assert.equal(needsFlatPhaseMigration(base), true, "reappeared legacy layout re-triggers migration");
+
+  await migrateToFlatPhase(base);
+
+  const afterBackups = readdirSync(backupRoot).filter((d) => d.startsWith("migrate-"));
+  assert.deepEqual(afterBackups, firstBackups, "re-fire must not leak a second migrate-* backup");
+  assert.equal(existsSync(join(base, ".gsd", "milestones")), false, "legacy milestones/ removed again");
+});
+
+test("rollback after a re-fired migration preserves the reused migrate-* backup", async (t) => {
+  const base = makeTmp();
+  await migrateToFlatPhase(base);
+  const backupRoot = join(base, ".gsd-backups");
+  const firstBackups = readdirSync(backupRoot).filter((d) => d.startsWith("migrate-"));
+  assert.equal(firstBackups.length, 1, "first migration snapshots exactly one backup");
+
+  mkdirSync(join(base, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01"), { recursive: true });
+  const milestonesPath = join(base, ".gsd", "milestones");
+  const phasesPath = join(base, ".gsd", "phases");
+
+  const restoreFsOps = _setFlatPhaseMigrationFsOpsForTest({
+    rmSync(target, opts) {
+      if (target === phasesPath) {
+        throw Object.assign(new Error("simulated locked phases/"), { code: "EPERM" });
+      }
+      return rmSync(target, opts as never);
+    },
+  });
+  t.after(restoreFsOps);
+
+  await assert.rejects(migrateToFlatPhase(base), /simulated locked/);
+
+  const afterBackups = readdirSync(backupRoot).filter((d) => d.startsWith("migrate-"));
+  assert.deepEqual(afterBackups, firstBackups, "rollback must preserve the reused backup");
+  assert.ok(existsSync(milestonesPath), "legacy milestones/ should be restored on rollback");
+});
+
+test("migration ignores an empty/partial leftover backup and writes a complete one (#1292)", async () => {
+  const base = makeTmp();
+
+  // Simulate a prior first-time backup that crashed mid-cpSync: an empty
+  // migrate-<ts>/ leftover with no milestones/ content. It is the newest entry,
+  // so mtime-based selection would reuse it as the rollback copy if content were
+  // not validated — silently retaining a recovery copy missing the legacy tree.
+  const backupRoot = join(base, ".gsd-backups");
+  const emptyLeftover = join(backupRoot, "migrate-crashed");
+  mkdirSync(emptyLeftover, { recursive: true });
+
+  await migrateToFlatPhase(base);
+
+  assert.ok(existsSync(join(base, ".gsd", "phases", "01-foundation")), "flat phase should render");
+  // The empty leftover must not have been reused; a fresh, content-bearing
+  // backup that actually captured the legacy milestones/ tree must be created.
+  const contentBackups = readdirSync(backupRoot)
+    .filter((d) => d.startsWith("migrate-"))
+    .filter((d) => existsSync(join(backupRoot, d, "M001")));
+  assert.ok(
+    contentBackups.length >= 1,
+    "a complete backup containing the legacy milestones/ tree must be created, not the empty leftover",
+  );
+});
+
 test("migrateToFlatPhase preserves slice sidecar artifacts and skips recovery placeholder PLAN", async () => {
   const base = makeTmp({ withTask: false });
   const legacySliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");

package/src/resources/extensions/gsd/tests/gate-storage.test.ts

@@ -19,6 +19,11 @@ import {
   insertMilestone,
   insertSlice,
 } from "../gsd-db.ts";
+import { getDb } from "../db/engine.ts";
+
+function gateRunCount(gateId: string): number {
+  return (getDb().prepare("SELECT count(*) AS cnt FROM gate_runs WHERE gate_id = :gid").get({ ":gid": gateId }) as { cnt: number }).cnt;
+}
 
 describe("quality_gates CRUD", () => {
   let tmpDir: string;
@@ -83,6 +88,30 @@ describe("quality_gates CRUD", () => {
     assert.ok(results[0].evaluated_at);
   });
 
+  test("saveGateResult commits the verdict and the gate_runs ledger row together", () => {
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" });
+    saveGateResult({
+      milestoneId: "M001", sliceId: "S01", gateId: "Q3",
+      verdict: "pass", rationale: "OK", findings: "",
+    });
+    assert.equal(getGateResults("M001", "S01")[0].status, "complete");
+    assert.equal(gateRunCount("Q3"), 1, "exactly one ledger row must accompany the verdict");
+  });
+
+  test("saveGateResult rolls back the verdict UPDATE if the ledger INSERT fails", () => {
+    insertGateRow({ milestoneId: "M001", sliceId: "S01", gateId: "Q3", scope: "slice" });
+    // Force the insertGateRun step to throw after the UPDATE by removing the
+    // ledger table. Atomicity means the gate row must stay pending.
+    getDb().exec("DROP TABLE gate_runs");
+    assert.throws(() => saveGateResult({
+      milestoneId: "M001", sliceId: "S01", gateId: "Q3",
+      verdict: "pass", rationale: "OK", findings: "",
+    }));
+    const gate = getGateResults("M001", "S01")[0];
+    assert.equal(gate.status, "pending", "gate verdict UPDATE must roll back when the ledger INSERT fails");
+    assert.equal(gate.verdict ?? "", "", "verdict must not persist after rollback");
+  });
+
   test("saveGateResult throws when the gate row does not exist", () => {
     assert.throws(
       () => saveGateResult({

package/src/resources/extensions/gsd/tests/gsd-db.test.ts

@@ -280,6 +280,31 @@ describe('gsd-db', () => {
     }
   });
 
+  test("gsd-db: insertTask stamps completed_at for every complete-alias but not for skipped", () => {
+    openDatabase(":memory:");
+
+    try {
+      insertMilestone({ id: "M001", title: "Completion stamp", status: "active" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "active", sequence: 1 });
+      insertTask({ id: "T01", sliceId: "S01", milestoneId: "M001", title: "Closed", status: "closed", sequence: 1 });
+      insertTask({ id: "T02", sliceId: "S01", milestoneId: "M001", title: "Done", status: "done", sequence: 2 });
+      insertTask({ id: "T03", sliceId: "S01", milestoneId: "M001", title: "Skipped", status: "skipped", sequence: 3 });
+
+      assert.ok(
+        getTask("M001", "S01", "T01")?.completed_at,
+        "a task imported as 'closed' is terminal and must carry a completed_at",
+      );
+      assert.ok(getTask("M001", "S01", "T02")?.completed_at, "'done' alias must stamp completed_at");
+      assert.equal(
+        getTask("M001", "S01", "T03")?.completed_at,
+        null,
+        "a skipped task was never completed and must have null completed_at",
+      );
+    } finally {
+      closeDatabase();
+    }
+  });
+
   test('gsd-db: active_decisions view excludes superseded', () => {
     openDatabase(':memory:');
 

package/src/resources/extensions/gsd/tests/import-slice-milestone-completion-preserve.test.ts

@@ -0,0 +1,116 @@
+// Project/App: gsd-pi
+// File Purpose: Regression for #1291 — a full markdown re-import must NOT rewrite
+// the completed_at of an already-complete slice or milestone with the current
+// import time. The task path was fixed for this (#1222/#1228) via
+// preserveCompletionMetadata; the slice and milestone backfills in
+// migrateHierarchyToDb had no such guard, so every re-import re-stamped every
+// complete slice/milestone. The fix threads preserveCompletion through
+// updateSliceStatus/updateMilestoneStatus so an existing completed_at survives.
+
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import {
+  openDatabase,
+  closeDatabase,
+  getAllMilestones,
+  getMilestoneSlices,
+  updateSliceStatus,
+  updateMilestoneStatus,
+} from '../gsd-db.ts';
+import { migrateHierarchyToDb } from '../md-importer.ts';
+import { describe, test, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+
+const tmpDirs: string[] = [];
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+function createFixtureBase(): string {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-preserve-completion-'));
+  tmpDirs.push(base);
+  return base;
+}
+
+function writeFile(base: string, relativePath: string, content: string): void {
+  const full = join(base, '.gsd', relativePath);
+  mkdirSync(join(full, '..'), { recursive: true });
+  writeFileSync(full, content);
+}
+
+// All slices [x] → milestone imports complete, slices import complete.
+const ROADMAP_ALL_DONE = `# M001: Finished Milestone
+
+**Vision:** Done work.
+
+## Slices
+
+- [x] **S01: First Slice** \`risk:low\` \`depends:[]\`
+  > After this: Done.
+
+- [x] **S02: Second Slice** \`risk:medium\` \`depends:[S01]\`
+  > After this: Also done.
+`;
+
+const REAL_S01 = '2026-07-05T19:52:04.672Z';
+const REAL_S02 = '2026-07-05T20:36:51.313Z';
+const REAL_M001 = '2026-07-05T21:00:00.000Z';
+
+describe('migrateHierarchyToDb: re-import preserves existing completion timestamps (#1291)', () => {
+  test('a re-import does not rewrite already-complete slice completed_at', () => {
+    const base = createFixtureBase();
+    writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_ALL_DONE);
+
+    openDatabase(join(base, '.gsd', 'gsd.db'));
+    migrateHierarchyToDb(base);
+
+    // Simulate the durable completion timestamps the real run wrote hours apart.
+    updateSliceStatus('M001', 'S01', 'complete', REAL_S01);
+    updateSliceStatus('M001', 'S02', 'complete', REAL_S02);
+
+    // A second full re-import (the class of event that bit the reporter).
+    migrateHierarchyToDb(base);
+
+    const slices = getMilestoneSlices('M001');
+    const s01 = slices.find((s) => s.id === 'S01')!;
+    const s02 = slices.find((s) => s.id === 'S02')!;
+    assert.equal(s01.completed_at, REAL_S01, 'S01 completed_at must survive re-import unchanged');
+    assert.equal(s02.completed_at, REAL_S02, 'S02 completed_at must survive re-import unchanged');
+  });
+
+  test('a re-import does not rewrite an already-complete milestone completed_at', () => {
+    const base = createFixtureBase();
+    writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_ALL_DONE);
+
+    openDatabase(join(base, '.gsd', 'gsd.db'));
+    migrateHierarchyToDb(base);
+
+    updateMilestoneStatus('M001', 'complete', REAL_M001);
+
+    migrateHierarchyToDb(base);
+
+    const m001 = getAllMilestones().find((m) => m.id === 'M001')!;
+    assert.equal(m001.completed_at, REAL_M001, 'M001 completed_at must survive re-import unchanged');
+  });
+
+  test('an initial import of a complete slice still backfills a completed_at when the row has none', () => {
+    // The guard preserves an existing timestamp but must not suppress the
+    // legitimate first-time backfill for a slice imported as complete.
+    const base = createFixtureBase();
+    writeFile(base, 'milestones/M001/M001-ROADMAP.md', ROADMAP_ALL_DONE);
+
+    openDatabase(join(base, '.gsd', 'gsd.db'));
+    migrateHierarchyToDb(base);
+
+    const slices = getMilestoneSlices('M001');
+    for (const s of slices) {
+      assert.ok(s.completed_at, `complete slice ${s.id} should receive a backfilled completed_at on first import`);
+    }
+    const m001 = getAllMilestones().find((m) => m.id === 'M001')!;
+    assert.ok(m001.completed_at, 'complete milestone should receive a backfilled completed_at on first import');
+  });
+});

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

@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { createMigrationPlan, splitValidationIssues } from "../migrate/plan.ts";
+import type { ValidationResult } from "../migrate/types.ts";
+
+function makeBase(prefix: string): string {
+  return mkdtempSync(join(tmpdir(), prefix));
+}
+
+function write(path: string, content: string): void {
+  mkdirSync(join(path, ".."), { recursive: true });
+  writeFileSync(path, content);
+}
+
+test("splitValidationIssues separates warnings from fatals without dropping issue order", () => {
+  const validation: ValidationResult = {
+    valid: false,
+    issues: [
+      { file: "ROADMAP.md", severity: "warning", message: "missing roadmap" },
+      { file: ".planning", severity: "fatal", message: "missing directory" },
+      { file: "PROJECT.md", severity: "warning", message: "missing project" },
+    ],
+  };
+
+  assert.deepEqual(splitValidationIssues(validation), {
+    warnings: [
+      { file: "ROADMAP.md", severity: "warning", message: "missing roadmap" },
+      { file: "PROJECT.md", severity: "warning", message: "missing project" },
+    ],
+    fatals: [
+      { file: ".planning", severity: "fatal", message: "missing directory" },
+    ],
+  });
+});
+
+test("createMigrationPlan reports a missing .planning source without parsing", async () => {
+  const base = makeBase("gsd-migrate-plan-missing-");
+  try {
+    const result = await createMigrationPlan(base);
+
+    assert.equal(result.status, "missing-source");
+    assert.equal(result.sourcePath, join(base, ".planning"));
+    assert.equal(result.targetRoot, base);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("createMigrationPlan reports zero-slice migrations as blocked after validation", async () => {
+  const base = makeBase("gsd-migrate-plan-blocked-");
+  try {
+    mkdirSync(join(base, ".planning"), { recursive: true });
+    write(join(base, ".planning", "PROJECT.md"), "# Legacy Project\n");
+
+    const result = await createMigrationPlan(base);
+
+    assert.equal(result.status, "blocked");
+    assert.match(result.message, /zero slices/);
+    assert.equal(result.validation.valid, true);
+    assert.ok(result.warnings.some((issue) => issue.file === "ROADMAP.md"));
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/migrate-presentation.test.ts

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import {
+  buildMigrationPreviewSummary,
+  buildReviewPrompt,
+  formatMigrationPreviewStats,
+} from "../migrate/presentation.ts";
+import { gsdRoot } from "../paths.ts";
+import type { MigrationPreview } from "../migrate/writer.ts";
+
+function previewFixture(overrides: Partial<MigrationPreview> = {}): MigrationPreview {
+  return {
+    decisions: { total: 2 },
+    migrationInputs: {
+      milestonePhaseDirs: 3,
+      decisions: 2,
+      seeds: 1,
+    },
+    milestoneCount: 1,
+    totalSlices: 2,
+    totalTasks: 5,
+    doneSlices: 1,
+    doneTasks: 3,
+    sliceCompletionPct: 50,
+    taskCompletionPct: 60,
+    requirements: {
+      active: 1,
+      validated: 2,
+      deferred: 1,
+      outOfScope: 1,
+      total: 5,
+    },
+    ...overrides,
+  };
+}
+
+test("buildMigrationPreviewSummary includes counts, legacy inputs, and existing-target warning", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-migrate-presentation-"));
+  try {
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+
+    assert.deepEqual(buildMigrationPreviewSummary(previewFixture(), base), [
+      "Decisions: 2",
+      "Milestones: 1",
+      "Slices: 2 (1 done — 50%)",
+      "Tasks: 5 (3 done — 60%)",
+      "Requirements: 5 (2 validated, 1 active, 1 deferred, 1 out of scope)",
+      "Legacy inputs: 3 milestone phase dir(s), 2 decision file(s), 1 seed file(s)",
+      "",
+      `⚠ A .gsd directory already exists at ${gsdRoot(base)}.`,
+      "It will be backed up, deleted, and rewritten fresh before DB import.",
+    ]);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("formatMigrationPreviewStats uses bullet formatting for review prompts", () => {
+  assert.equal(
+    formatMigrationPreviewStats(previewFixture({ requirements: { active: 0, validated: 0, deferred: 0, outOfScope: 0, total: 0 } })),
+    [
+      "- Decisions: 2",
+      "- Milestones: 1",
+      "- Slices: 2 (1 done — 50%)",
+      "- Tasks: 5 (3 done — 60%)",
+      "- Legacy inputs: 3 milestone phase dir(s), 2 decision file(s), 1 seed file(s)",
+    ].join("\n"),
+  );
+});
+
+test("buildReviewPrompt interpolates source, target, and preview stats", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-migrate-prompt-"));
+  try {
+    const promptsDir = join(base, "prompts");
+    mkdirSync(promptsDir, { recursive: true });
+    writeFileSync(
+      join(promptsDir, "review-migration.md"),
+      "Source={{sourcePath}}\nTarget={{gsdPath}}\nStats:\n{{previewStats}}\n",
+    );
+
+    const prompt = buildReviewPrompt({
+      sourcePath: "/legacy/.planning",
+      gsdPath: "/project/.gsd",
+      preview: previewFixture(),
+      templatePath: join(promptsDir, "review-migration.md"),
+    });
+
+    assert.match(prompt, /Source=\/legacy\/\.planning/);
+    assert.match(prompt, /Target=\/project\/\.gsd/);
+    assert.match(prompt, /- Requirements: 5 \(2 validated, 1 active, 1 deferred, 1 out of scope\)/);
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/migrate-safety-audit.test.ts

@@ -19,7 +19,7 @@ import {
   archiveLegacyPlanningDirectory,
   verifyMigrationProjection,
 } from "../migrate/audit.ts";
-import { assertMigrationDbReadiness, executeMigrationWrite, importWrittenMigrationToDb } from "../migrate/command.ts";
+import { assertMigrationDbReadiness, executeMigrationWrite, importWrittenMigrationToDb } from "../migrate/execution.ts";
 import { writeGSDDirectory } from "../migrate/writer.ts";
 import { closeDatabase, getArtifact } from "../gsd-db.ts";
 import type { GSDProject } from "../migrate/types.ts";

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

@@ -18,6 +18,7 @@ import {
   releaseMilestoneLease,
   refreshMilestoneLease,
   getMilestoneLease,
+  forceReleaseLeasesForWorker,
 } from "../db/milestone-leases.ts";
 
 function makeBase(): string {
@@ -163,6 +164,60 @@ test("refreshMilestoneLease only succeeds with the matching fencing token", (t)
   assert.equal(refreshMilestoneLease(w1, "M001", claim.token - 1), false);
 });
 
+test("forceReleaseLeasesForWorker frees only the dead worker's leases, not a live peer's", (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "One", status: "active" });
+  insertMilestone({ id: "M002", title: "Two", status: "active" });
+
+  // Distinct project roots → distinct processes (not re-entrant peers).
+  const wA = registerAutoWorker({ projectRootRealpath: base });
+  const wB = registerAutoWorker({ projectRootRealpath: join(base, "peer") });
+  assert.equal(claimMilestoneLease(wA, "M001").ok, true);
+  assert.equal(claimMilestoneLease(wB, "M002").ok, true);
+
+  const freed = forceReleaseLeasesForWorker(wA);
+  assert.equal(freed, 1, "exactly A's one held lease is released");
+
+  assert.equal(getMilestoneLease("M001")!.status, "released", "A's M001 lease is released");
+  const m2 = getMilestoneLease("M002")!;
+  assert.equal(m2.status, "held", "B's M002 lease must stay held (no over-release)");
+  assert.equal(m2.worker_id, wB);
+});
+
+test("after force release a fresh claim on the freed milestone gets a larger fencing token", (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "One", status: "active" });
+
+  const wA = registerAutoWorker({ projectRootRealpath: base });
+  const wB = registerAutoWorker({ projectRootRealpath: join(base, "peer") });
+  const first = claimMilestoneLease(wA, "M001");
+  assert.equal(first.ok, true);
+  const releasedToken = first.ok ? first.token : 0;
+
+  assert.equal(forceReleaseLeasesForWorker(wA), 1);
+
+  const takeover = claimMilestoneLease(wB, "M001");
+  assert.equal(takeover.ok, true);
+  if (takeover.ok) {
+    assert.ok(takeover.token > releasedToken, "takeover token must exceed the released lease's token");
+  }
+  assert.equal(getMilestoneLease("M001")!.worker_id, wB);
+});
+
+test("forceReleaseLeasesForWorker returns 0 for a worker holding no leases", (t) => {
+  const base = makeBase();
+  t.after(() => cleanup(base));
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "One", status: "active" });
+
+  const wA = registerAutoWorker({ projectRootRealpath: base });
+  assert.equal(forceReleaseLeasesForWorker(wA), 0);
+});
+
 test("claimMilestoneLease rethrows foreign-key failures instead of treating them as lease contention", (t) => {
   const base = makeBase();
   t.after(() => cleanup(base));