@opengsd/gsd-pi 1.9.0-dev.e10b60d4 → 1.10.0

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

@@ -155,6 +155,19 @@ function isInsideFlatProjectionBackup(backupDir: string, src: string): boolean {
   return src === phaseBackupDir || src.startsWith(`${phaseBackupDir}/`) || src.startsWith(`${phaseBackupDir}\\`);
 }
 
+function removeFlatProjectionBackup(backupDir: string): void {
+  const phaseBackupDir = join(backupDir, "__phases");
+  if (!existsSync(phaseBackupDir)) return;
+  try {
+    removePathWithRetries(phaseBackupDir);
+  } catch (err) {
+    logWarning(
+      "migration",
+      `flat-phase migration succeeded but could not remove temporary ${LAYOUT_SEGMENTS.level1}/ backup: ${(err as Error).message}`,
+    );
+  }
+}
+
 function restoreFlatProjectionFromBackup(basePath: string, backupDir: string): void {
   const phaseBackupDir = join(backupDir, "__phases");
   if (!existsSync(phaseBackupDir)) return;
@@ -494,4 +507,5 @@ export async function migrateToFlatPhase(basePath: string): Promise<void> {
       `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${(err as Error).message}`,
     );
   }
+  removeFlatProjectionBackup(backupDir);
 }

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

@@ -67,6 +67,13 @@ export type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
 
 import { TERMINAL_STATUS_SQL } from "./db/sql-constants.js";
 import { applyStatusTransition } from "./db/writers/status.js";
+import {
+  LAYOUT_SEGMENTS,
+  derivePhaseSlug,
+  milestoneIdToPhaseNum,
+  milestoneIdUniqueSuffix,
+  phaseDirName,
+} from "./layout-policy.js";
 
 export function insertDecision(d: Omit<Decision, "seq">): void {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
@@ -206,6 +213,47 @@ export function insertArtifact(a: {
   });
 }
 
+function canonicalPhaseDirNameForDb(milestoneId: string, title: string): string {
+  const phaseNum = milestoneIdToPhaseNum(milestoneId);
+  const slug = derivePhaseSlug(title || milestoneId);
+  const suffix = milestoneIdUniqueSuffix(milestoneId);
+  return phaseDirName(phaseNum, suffix ? `${suffix}-${slug}` : slug);
+}
+
+function reconcileMilestonePhaseArtifactPaths(milestoneId: string, title: string): void {
+  const db = getDbOrNull()!;
+  const phaseNumPrefix = String(milestoneIdToPhaseNum(milestoneId)).padStart(2, "0");
+  const canonicalDir = canonicalPhaseDirNameForDb(milestoneId, title);
+  const staleRows = db.prepare(
+    `SELECT path
+       FROM artifacts
+      WHERE milestone_id = :milestone_id
+        AND path LIKE :phase_prefix`,
+  ).all({
+    ":milestone_id": milestoneId,
+    ":phase_prefix": `${LAYOUT_SEGMENTS.level1}/${phaseNumPrefix}-%/%`,
+  }) as Array<{ path: string }>;
+
+  const updatePath = db.prepare("UPDATE artifacts SET path = :new_path WHERE path = :old_path");
+  const deletePath = db.prepare("DELETE FROM artifacts WHERE path = :path");
+  const existingPath = db.prepare("SELECT 1 AS present FROM artifacts WHERE path = :path");
+
+  for (const row of staleRows) {
+    const parts = row.path.split("/");
+    if (parts.length < 3) continue;
+    if (parts[0] !== LAYOUT_SEGMENTS.level1) continue;
+    if (parts[1] === canonicalDir) continue;
+    if (!parts[1]?.startsWith(`${phaseNumPrefix}-`)) continue;
+
+    const newPath = [LAYOUT_SEGMENTS.level1, canonicalDir, ...parts.slice(2)].join("/");
+    if (existingPath.get({ ":path": newPath })) {
+      deletePath.run({ ":path": row.path });
+      continue;
+    }
+    updatePath.run({ ":new_path": newPath, ":old_path": row.path });
+  }
+}
+
 export interface MilestonePlanningRecord {
   vision: string;
   successCriteria: string[];
@@ -287,39 +335,43 @@ export function insertMilestone(m: {
 
 export function upsertMilestonePlanning(milestoneId: string, planning: Partial<MilestonePlanningRecord> & { title?: string; status?: string; depends_on?: string[] }): void {
   if (!getDbOrNull()!) throw new GSDError(GSD_STALE_STATE, "gsd-db: No database open");
-  getDbOrNull()!.prepare(
-    `UPDATE milestones SET
-      title = COALESCE(NULLIF(:title, ''), title),
-      status = COALESCE(NULLIF(:status, ''), status),
-      depends_on = COALESCE(:depends_on, depends_on),
-      vision = COALESCE(:vision, vision),
-      success_criteria = COALESCE(:success_criteria, success_criteria),
-      key_risks = COALESCE(:key_risks, key_risks),
-      proof_strategy = COALESCE(:proof_strategy, proof_strategy),
-      verification_contract = COALESCE(:verification_contract, verification_contract),
-      verification_integration = COALESCE(:verification_integration, verification_integration),
-      verification_operational = COALESCE(:verification_operational, verification_operational),
-      verification_uat = COALESCE(:verification_uat, verification_uat),
-      definition_of_done = COALESCE(:definition_of_done, definition_of_done),
-      requirement_coverage = COALESCE(:requirement_coverage, requirement_coverage),
-      boundary_map_markdown = COALESCE(:boundary_map_markdown, boundary_map_markdown)
-     WHERE id = :id`,
-  ).run({
-    ":id": milestoneId,
-    ":title": planning.title ?? "",
-    ":status": planning.status ?? "",
-    ":depends_on": planning.depends_on ? JSON.stringify(planning.depends_on) : null,
-    ":vision": planning.vision ?? null,
-    ":success_criteria": planning.successCriteria ? JSON.stringify(planning.successCriteria) : null,
-    ":key_risks": planning.keyRisks ? JSON.stringify(planning.keyRisks) : null,
-    ":proof_strategy": planning.proofStrategy ? JSON.stringify(planning.proofStrategy) : null,
-    ":verification_contract": planning.verificationContract ?? null,
-    ":verification_integration": planning.verificationIntegration ?? null,
-    ":verification_operational": planning.verificationOperational ?? null,
-    ":verification_uat": planning.verificationUat ?? null,
-    ":definition_of_done": planning.definitionOfDone ? JSON.stringify(planning.definitionOfDone) : null,
-    ":requirement_coverage": planning.requirementCoverage ?? null,
-    ":boundary_map_markdown": planning.boundaryMapMarkdown ?? null,
+  transaction(() => {
+    getDbOrNull()!.prepare(
+      `UPDATE milestones SET
+        title = COALESCE(NULLIF(:title, ''), title),
+        status = COALESCE(NULLIF(:status, ''), status),
+        depends_on = COALESCE(:depends_on, depends_on),
+        vision = COALESCE(:vision, vision),
+        success_criteria = COALESCE(:success_criteria, success_criteria),
+        key_risks = COALESCE(:key_risks, key_risks),
+        proof_strategy = COALESCE(:proof_strategy, proof_strategy),
+        verification_contract = COALESCE(:verification_contract, verification_contract),
+        verification_integration = COALESCE(:verification_integration, verification_integration),
+        verification_operational = COALESCE(:verification_operational, verification_operational),
+        verification_uat = COALESCE(:verification_uat, verification_uat),
+        definition_of_done = COALESCE(:definition_of_done, definition_of_done),
+        requirement_coverage = COALESCE(:requirement_coverage, requirement_coverage),
+        boundary_map_markdown = COALESCE(:boundary_map_markdown, boundary_map_markdown)
+       WHERE id = :id`,
+    ).run({
+      ":id": milestoneId,
+      ":title": planning.title ?? "",
+      ":status": planning.status ?? "",
+      ":depends_on": planning.depends_on ? JSON.stringify(planning.depends_on) : null,
+      ":vision": planning.vision ?? null,
+      ":success_criteria": planning.successCriteria ? JSON.stringify(planning.successCriteria) : null,
+      ":key_risks": planning.keyRisks ? JSON.stringify(planning.keyRisks) : null,
+      ":proof_strategy": planning.proofStrategy ? JSON.stringify(planning.proofStrategy) : null,
+      ":verification_contract": planning.verificationContract ?? null,
+      ":verification_integration": planning.verificationIntegration ?? null,
+      ":verification_operational": planning.verificationOperational ?? null,
+      ":verification_uat": planning.verificationUat ?? null,
+      ":definition_of_done": planning.definitionOfDone ? JSON.stringify(planning.definitionOfDone) : null,
+      ":requirement_coverage": planning.requirementCoverage ?? null,
+      ":boundary_map_markdown": planning.boundaryMapMarkdown ?? null,
+    });
+    const finalTitle = planning.title?.trim();
+    if (finalTitle) reconcileMilestonePhaseArtifactPaths(milestoneId, finalTitle);
   });
 }
 

package/src/resources/extensions/gsd/tests/auto-loop.test.ts

@@ -41,6 +41,7 @@ import { claimMilestoneLease } from "../db/milestone-leases.js";
 import { recordDispatchClaim, markCanceled } from "../db/unit-dispatches.js";
 import { setRuntimeKv, getRuntimeKv } from "../db/runtime-kv.js";
 import { SourceObservationStore } from "../source-observations.js";
+import { autoCommitCurrentBranch } from "../worktree.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -832,6 +833,37 @@ test("runUnit returns cancelled when session creation fails", async () => {
   assert.equal(pi.calls.length, 0);
 });
 
+test("runUnit returns cancelled when command context lacks newSession", async () => {
+  _resetPendingResolve();
+
+  const ctx = {
+    ...makeMockCtx(),
+    ui: {
+      notify: () => {},
+      setStatus: () => {},
+      setWorkingMessage: () => {},
+    },
+    sessionManager: {
+      getEntries: () => [],
+    },
+    modelRegistry: {
+      getProviderAuthMode: () => undefined,
+      isProviderRequestReady: () => true,
+    },
+  } as any;
+  const pi = makeMockPi();
+  const s = makeMockSession();
+  s.cmdCtx = {} as any;
+
+  const result = await runUnit(ctx, pi, s, "task", "T01", "prompt");
+
+  assert.equal(result.status, "cancelled");
+  assert.equal(result.errorContext?.category, "session-failed");
+  assert.equal(result.errorContext?.isTransient, false);
+  assert.match(result.errorContext?.message ?? "", /missing newSession/);
+  assert.equal(pi.calls.length, 0);
+});
+
 test("runUnit: TypeError from newSession is classified as structural (isTransient: false)", async () => {
   // Regression for #572: a TypeError thrown from newSession (e.g. "something is
   // not a function") indicates a programming error, not a transient provider
@@ -1582,6 +1614,130 @@ test("autoLoop exits when s.active is set to false", async (t) => {
   );
 });
 
+test("autoLoop stops before dispatch when command context lacks newSession", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.ui.setStatus = () => {};
+  const pi = makeMockPi();
+  const s = makeLoopSession({
+    cmdCtx: {
+      getContextUsage: () => ({ percent: 10, tokens: 1000, limit: 10000 }),
+    },
+  });
+  let stopReason: string | undefined;
+  let preserveWorktree: boolean | undefined;
+  let deriveCalled = false;
+
+  try {
+    const deps = makeMockDeps({
+      stopAuto: async (_ctx, _pi, reason, options) => {
+        stopReason = reason;
+        preserveWorktree = options?.preserveWorktree;
+        s.active = false;
+      },
+      deriveState: async () => {
+        deriveCalled = true;
+        throw new Error("deriveState should not run without command session support");
+      },
+    });
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.equal(stopReason, "Auto-mode has no command context for dispatch.");
+    assert.equal(preserveWorktree, true);
+    assert.equal(deriveCalled, false);
+    assert.equal(pi.calls.length, 0);
+  } finally {
+    rmSync(s.basePath, { recursive: true, force: true });
+  }
+});
+
+test("autoLoop commits open unit work when command context lacks newSession", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.ui.setStatus = () => {};
+  const pi = makeMockPi();
+  const s = makeLoopSession({
+    cmdCtx: {
+      getContextUsage: () => ({ percent: 10, tokens: 1000, limit: 10000 }),
+    },
+    currentUnit: { type: "execute-task", id: "T01", startedAt: Date.now() },
+  });
+  const outputPath = join(s.basePath, "executor-output.txt");
+  let autoCommitArgs: { unitType: string; unitId: string } | undefined;
+  let preserveWorktree: boolean | undefined;
+
+  try {
+    const deps = makeMockDeps({
+      autoCommitUnit: async (basePath, unitType, unitId) => {
+        autoCommitArgs = { unitType, unitId };
+        return autoCommitCurrentBranch(basePath, unitType, unitId);
+      },
+      stopAuto: async (_ctx, _pi, _reason, options) => {
+        preserveWorktree = options?.preserveWorktree;
+        s.active = false;
+      },
+      deriveState: async () => {
+        throw new Error("deriveState should not run without command session support");
+      },
+    });
+
+    writeFileSync(outputPath, "open unit work before stop\n", "utf-8");
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.deepEqual(autoCommitArgs, { unitType: "execute-task", unitId: "T01" });
+    assert.equal(preserveWorktree, true);
+    const committed = execSync("git show HEAD:executor-output.txt", {
+      cwd: s.basePath,
+      encoding: "utf-8",
+    });
+    assert.equal(committed, "open unit work before stop\n");
+    assert.equal(pi.calls.length, 0);
+  } finally {
+    rmSync(s.basePath, { recursive: true, force: true });
+  }
+});
+
+test("autoLoop snapshots dirty work when unit dispatch crashes", async () => {
+  _resetPendingResolve();
+
+  const ctx = makeMockCtx();
+  ctx.ui.setStatus = () => {};
+  const pi = makeMockPi();
+  const s = makeLoopSession();
+  const outputPath = join(s.basePath, "executor-output.txt");
+  let autoCommitCalls = 0;
+
+  try {
+    const deps = makeMockDeps({
+      ensurePreconditions: () => {
+        writeFileSync(outputPath, "saved before crash\n", "utf-8");
+        throw new Error("dispatch crash after file write");
+      },
+      autoCommitUnit: async (basePath, unitType, unitId) => {
+        autoCommitCalls++;
+        const commitMsg = autoCommitCurrentBranch(basePath, unitType, unitId);
+        s.active = false;
+        return commitMsg;
+      },
+    });
+
+    await autoLoop(ctx, pi, s, deps);
+
+    assert.equal(autoCommitCalls, 1);
+    const committed = execSync("git show HEAD:executor-output.txt", {
+      cwd: s.basePath,
+      encoding: "utf-8",
+    });
+    assert.equal(committed, "saved before crash\n");
+  } finally {
+    rmSync(s.basePath, { recursive: true, force: true });
+  }
+});
+
 test("autoLoop pauses visibly when Auto Orchestration Module is not wired", async () => {
   _resetPendingResolve();
 

package/src/resources/extensions/gsd/tests/auto-start-index-lock.test.ts

@@ -4,7 +4,7 @@ import { existsSync, mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
-import { hasGitIndexLockForTest } from "../auto-start.ts";
+import { hasGitIndexLockForTest, reconcileFlatPhaseBootstrapLayout } from "../auto-start.ts";
 
 test("bootstrapAutoSession detects .git/index.lock without deleting it", (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-index-lock-"));
@@ -24,3 +24,23 @@ test("bootstrapAutoSession reports no index lock when the lock file is absent",
 
   assert.equal(hasGitIndexLockForTest(base), false);
 });
+
+test("bootstrapAutoSession removes empty legacy milestones dir in flat-phase projects", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-flat-bootstrap-clean-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+  mkdirSync(join(base, ".gsd", "phases"), { recursive: true });
+  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+
+  assert.equal(reconcileFlatPhaseBootstrapLayout(base), true);
+  assert.equal(existsSync(join(base, ".gsd", "phases")), true);
+  assert.equal(existsSync(join(base, ".gsd", "milestones")), false);
+});
+
+test("bootstrapAutoSession creates phases instead of milestones for empty GSD state", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-flat-bootstrap-init-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  assert.equal(reconcileFlatPhaseBootstrapLayout(base), true);
+  assert.equal(existsSync(join(base, ".gsd", "phases")), true);
+  assert.equal(existsSync(join(base, ".gsd", "milestones")), false);
+});

package/src/resources/extensions/gsd/tests/auto-wrapup-inflight-guard.test.ts

@@ -3,7 +3,8 @@
 
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, realpathSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 
@@ -96,6 +97,78 @@ describe("hook dispatch session workspace root", () => {
     assert.equal(dispatched, true);
     assert.deepEqual(newSessionOptions, { workspaceRoot: basePath });
   });
+
+  test("dispatchHookUnit commits in-flight work when command context lacks newSession", async (t) => {
+    const originalCwd = process.cwd();
+    const basePath = realpathSync(mkdtempSync(join(tmpdir(), "gsd-hook-nosnap-")));
+    mkdirSync(join(basePath, ".gsd"), { recursive: true });
+    execSync("git init --initial-branch=main", { cwd: basePath, stdio: "ignore" });
+    execSync("git config user.email test@test.com", { cwd: basePath, stdio: "ignore" });
+    execSync("git config user.name Test", { cwd: basePath, stdio: "ignore" });
+    execSync("git commit --allow-empty -m init", { cwd: basePath, stdio: "ignore" });
+
+    autoSession.reset();
+    autoSession.active = true;
+    autoSession.basePath = basePath;
+    autoSession.originalBasePath = basePath;
+    // Simulate an in-flight unit whose executor already wrote files, then a hook
+    // fires with a command context missing newSession.
+    autoSession.currentUnit = {
+      type: "execute-task",
+      id: "M001/S01/T01",
+      startedAt: Date.now(),
+    };
+    t.after(() => {
+      try {
+        process.chdir(originalCwd);
+      } catch {
+        // best effort cleanup after cwd-sensitive dispatch tests
+      }
+      autoSession.reset();
+      rmSync(basePath, { recursive: true, force: true });
+    });
+
+    const outputPath = join(basePath, "executor-output.txt");
+    writeFileSync(outputPath, "in-flight executor work\n", "utf-8");
+
+    // Command context intentionally lacks newSession — the guard must snapshot
+    // the dirty work before stopping instead of discarding it.
+    const ctx = {
+      ui: {
+        notify: () => {},
+        setStatus: () => {},
+        setWidget: () => {},
+      },
+      modelRegistry: {
+        getAvailable: () => [],
+      },
+      sessionManager: {
+        getSessionFile: () => join(basePath, "session.jsonl"),
+      },
+    };
+    const pi = {
+      sendMessage: () => {},
+      setModel: async () => true,
+    };
+
+    const dispatched = await dispatchHookUnit(
+      ctx as any,
+      pi as any,
+      "review",
+      "execute-task",
+      "M001/S01/T01",
+      "review the completed unit",
+      undefined,
+      basePath,
+    );
+
+    assert.equal(dispatched, false);
+    const committed = execSync("git show HEAD:executor-output.txt", {
+      cwd: basePath,
+      encoding: "utf-8",
+    });
+    assert.equal(committed, "in-flight executor work\n");
+  });
 });
 
 describe("deep setup approval questions pause immediately", () => {

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

@@ -167,6 +167,45 @@ test("checkEngineHealth keeps PLAN checkbox divergence after stale projection fl
   assert.match(readFileSync(plan.planPath, "utf-8"), /- \[ \] \*\*T01\*\*:/);
 });
 
+test("checkEngineHealth ignores stale suffixed flat-phase duplicate when bare milestone exists", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-checkbox-flat-duplicate-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  mkdirSync(gsdDir, { recursive: true });
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertMilestone({ id: "M003", title: "M003-vaz73w: New milestone M003-vaz73w", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M003", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  for (const taskId of ["T01", "T02", "T03"]) {
+    insertTask({ id: taskId, milestoneId: "M003", sliceId: "S01", title: taskId, status: "complete", sequence: Number(taskId.slice(1)) });
+  }
+
+  insertMilestone({ id: "M003-vaz73w", title: "New milestone M003-vaz73w", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M003-vaz73w", title: "Slice", status: "pending", risk: "low", depends: [], sequence: 1 });
+  for (const taskId of ["T01", "T02", "T03"]) {
+    insertTask({ id: taskId, milestoneId: "M003-vaz73w", sliceId: "S01", title: taskId, status: "complete", sequence: Number(taskId.slice(1)) });
+  }
+
+  const canonicalPlan = await renderPlanFromDb(base, "M003", "S01");
+  const staleDir = join(gsdDir, "phases", "03-vaz73w-new-milestone-m003-vaz73w");
+  mkdirSync(staleDir, { recursive: true });
+  writeFileSync(
+    join(staleDir, "03-01-PLAN.md"),
+    canonicalPlan.content.replace("- [x] **T03**:", "- [ ] **T03**:"),
+    "utf-8",
+  );
+
+  const issues: any[] = [];
+  await checkEngineHealth(base, issues, []);
+
+  assert.deepEqual(
+    issues.filter((issue) => issue.code === "checkbox_db_status_divergence").map((issue) => issue.unitId),
+    [],
+    "stale suffixed duplicate phase projection must not compete with the bare milestone projection",
+  );
+});
+
 test("checkEngineHealth reads task checkboxes from the <tasks> block, not a stray line above it", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-doctor-task-section-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));
@@ -428,6 +467,50 @@ test("checkEngineHealth repair prunes stale phases artifact rows with present mi
   assert.deepEqual(rows.map((row) => row.path), []);
 });
 
+test("checkEngineHealth repair prunes stale phases artifact rows with renamed flat-phase files", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-doctor-prune-renamed-flat-phase-artifact-"));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const gsdDir = join(base, ".gsd");
+  const stalePath = "phases/01-new-milestone-m001/01-01-PLAN.md";
+  const replacementPath = "phases/01-lokably-brand-foundation-and-welcome-pag/01-01-PLAN.md";
+  mkdirSync(join(gsdDir, "phases", "01-lokably-brand-foundation-and-welcome-pag"), { recursive: true });
+  writeFileSync(join(gsdDir, replacementPath), "# Plan\n", "utf-8");
+
+  openDatabase(join(gsdDir, "gsd.db"));
+  insertArtifact({
+    path: stalePath,
+    artifact_type: "PLAN",
+    milestone_id: "M001",
+    slice_id: "S01",
+    task_id: null,
+    full_content: "# stale plan\n",
+  });
+
+  const beforeIssues: any[] = [];
+  await checkEngineHealth(base, beforeIssues, []);
+
+  const beforeIssue = beforeIssues.find((issue) => issue.code === "artifact_file_missing" && issue.file === stalePath);
+  assert.ok(beforeIssue, "stale renamed phases row should be reported when repair is off");
+  assert.equal(beforeIssue.fixable, true, "renamed phases rows with a flat replacement should be fixable");
+
+  const repairIssues: any[] = [];
+  const fixes: string[] = [];
+  await checkEngineHealth(base, repairIssues, fixes, { repair: true });
+
+  assert.equal(
+    repairIssues.some((issue) => issue.code === "artifact_file_missing" && issue.file === stalePath),
+    false,
+    "repair should not report stale rows it pruned",
+  );
+  assert.ok(fixes.includes(`pruned stale flat-phase artifact row ${stalePath}`));
+
+  const rows = _getAdapter()!
+    .prepare("SELECT path FROM artifacts ORDER BY path")
+    .all() as Array<{ path: string }>;
+  assert.deepEqual(rows.map((row) => row.path), []);
+});
+
 test("checkEngineHealth repair keeps phases rows whose own file is still present", async (t) => {
   const base = mkdtempSync(join(tmpdir(), "gsd-doctor-keep-present-phase-artifact-"));
   t.after(() => rmSync(base, { recursive: true, force: true }));

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

@@ -122,7 +122,7 @@ 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 () => {
+test("migrateToFlatPhase removes disposable phases snapshot after successful migration", async () => {
   const base = makeTmp();
   const reviewPath = join(base, ".gsd", "phases", "01-foundation", "PLAN-REVIEW.md");
   mkdirSync(join(base, ".gsd", "phases", "01-foundation"), { recursive: true });
@@ -133,11 +133,10 @@ test("migrateToFlatPhase backs up existing phases projection before clearing it"
   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",
+    existsSync(join(backupRoot, backups[0]!, "__phases")),
+    false,
+    "temporary phases/ recovery snapshot should be removed after success",
   );
 });
 
@@ -202,7 +201,7 @@ 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 () => {
+test("resumed migration removes disposable phases snapshot after success", async () => {
   const base = makeTmp();
   const milestonesPath = join(base, ".gsd", "milestones");
   const migratingPath = join(base, ".gsd", "milestones.migrating");
@@ -218,9 +217,9 @@ test("resumed migration stores phases backup in retained migrate snapshot", asyn
   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",
+    existsSync(join(backupRoot, backups[0]!, "__phases")),
+    false,
+    "temporary phases/ recovery snapshot should be removed after resumed success",
   );
   assert.equal(
     existsSync(join(migratingPath, "__phases")),

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

@@ -46,6 +46,9 @@ import {
   tryCreateMemoriesFts,
   _isLikelyWslDrvFsPathForTest,
   _shouldAttemptVacuumRecoveryForTest,
+  insertArtifact,
+  getArtifact,
+  upsertMilestonePlanning,
 } from '../gsd-db.ts';
 import { MigrationBackupError } from '../db-migration-backup.ts';
 import { _resetLogs, peekLogs, setStderrLoggingEnabled } from '../workflow-logger.ts';
@@ -357,6 +360,35 @@ describe('gsd-db', () => {
     closeDatabase();
   });
 
+  test("gsd-db: upsertMilestonePlanning rewrites placeholder phase artifact paths to final title slug", () => {
+    openDatabase(":memory:");
+
+    const stalePath = "phases/01-new-milestone-m001/01-ROADMAP.md";
+    const finalPath = "phases/01-lokably-brand-foundation-and-welcome-pag/01-ROADMAP.md";
+    insertMilestone({ id: "M001", title: "New milestone M001", status: "active" });
+    insertArtifact({
+      path: stalePath,
+      artifact_type: "ROADMAP",
+      milestone_id: "M001",
+      slice_id: null,
+      task_id: null,
+      full_content: "# Placeholder roadmap\n",
+    });
+
+    upsertMilestonePlanning("M001", {
+      title: "Lokably brand foundation and welcome page rebuild",
+    });
+
+    assert.equal(getArtifact(stalePath), null, "placeholder-derived artifact row should be removed");
+    assert.equal(
+      getArtifact(finalPath)?.full_content,
+      "# Placeholder roadmap\n",
+      "artifact row should move to the final title-derived phase path",
+    );
+
+    closeDatabase();
+  });
+
   test('gsd-db: active_requirements view excludes superseded', () => {
     openDatabase(':memory:');