@opengsd/gsd-pi 1.3.0 → 1.4.0

package/src/resources/extensions/gsd/error-classifier.ts

@@ -10,7 +10,7 @@
  * @see https://github.com/open-gsd/gsd-pi/issues/2577
  */
 
-import { TOOL_SURFACE_NOT_READY } from "./tool-surface-readiness.js";
+import { TOOL_SURFACE_NOT_READY, isTerminalToolSurfaceError } from "./tool-surface-readiness.js";
 
 // ── ErrorClass discriminated union ──────────────────────────────────────────
 
@@ -114,7 +114,20 @@ export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorCla
     return { kind: "tool-schema", retryAfterMs: 0 };
   }
 
+  // Terminal tool-surface failure: the workflow MCP server is in a
+  // non-self-healing status (failed / needs-auth / disabled). This is NOT
+  // transient — retrying the same model cannot repair a dead server, so it
+  // must escalate / pause rather than retrying every ~3s into the per-unit
+  // cost cap. Checked ahead of the transient readiness branch below, which
+  // shares the TOOL_SURFACE_NOT_READY prefix and would otherwise collapse the
+  // terminal case into a transient `network` retry. See #783.
+  if (isTerminalToolSurfaceError(errorMsg)) {
+    return { kind: "permanent" };
+  }
+
   // Tool-surface readiness abort — transient; retry the same model shortly.
+  // This covers the not-yet-connected variants (absent, pending, connected but
+  // not registered); terminal statuses were handled by the branch above.
   if (TOOL_SURFACE_NOT_READY_RE.test(errorMsg)) {
     return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
   }

package/src/resources/extensions/gsd/escalation.ts

@@ -10,7 +10,7 @@ import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import type { EscalationArtifact, EscalationOption } from "./types.js";
-import { resolveSlicePath } from "./paths.js";
+import { legacyMilestonesDir, resolveSlicePath, resolveTasksDir } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import {
   getTask,
@@ -35,9 +35,14 @@ import { logWarning } from "./workflow-logger.js";
 export function escalationArtifactPath(
   basePath: string, milestoneId: string, sliceId: string, taskId: string,
 ): string | null {
-  const sDir = resolveSlicePath(basePath, milestoneId, sliceId);
-  if (!sDir) return null;
-  return join(sDir, "tasks", `${taskId}-ESCALATION.json`);
+  const tDir = resolveTasksDir(basePath, milestoneId, sliceId);
+  if (tDir) return join(tDir, `${taskId}-ESCALATION.json`);
+  // Flat-phase: tasks live in plan files; escalation artifacts sit in the phase dir.
+  // Legacy without tasks/: return null so writeEscalationArtifact throws (run doctor).
+  if (existsSync(legacyMilestonesDir(basePath))) return null;
+  const phaseDir = resolveSlicePath(basePath, milestoneId, sliceId);
+  if (!phaseDir) return null;
+  return join(phaseDir, `${taskId}-ESCALATION.json`);
 }
 
 // ─── Artifact I/O ─────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/exec-sandbox.ts

@@ -12,7 +12,7 @@ import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { resolve } from "node:path";
-import { killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
+import { getShellConfig, killProcessTree, SIGKILL_GRACE_MS, HARD_DEADLINE_MS } from "@gsd/pi-coding-agent";
 
 export interface ExecSandboxRequest {
   /** Interpreter to use. */
@@ -48,6 +48,8 @@ export interface ExecSandboxOptions {
   now?: () => Date;
   /** Optional override for id generation (tests). */
   generateId?: () => string;
+  /** Optional request cancellation signal. Aborting kills the child process tree. */
+  signal?: AbortSignal;
   /**
    * Grace period (ms) between SIGTERM and SIGKILL on timeout.
    * Defaults to SIGKILL_GRACE_MS. Exposed as a test seam.
@@ -67,6 +69,8 @@ export interface ExecSandboxResult {
   exit_code: number | null;
   signal: NodeJS.Signals | null;
   timed_out: boolean;
+  /** True when an external AbortSignal terminated the child process tree. */
+  aborted?: boolean;
   /**
    * True when the result came from the hard-deadline force-resolve (a non-closing
    * D-state child that never emitted 'close') rather than an observed process exit.
@@ -134,7 +138,12 @@ function clampTimeout(request: ExecSandboxRequest, opts: ExecSandboxOptions): nu
 function resolveCommand(runtime: ExecSandboxRequest["runtime"]): { cmd: string; args: string[] } {
   switch (runtime) {
     case "bash":
-      return { cmd: "bash", args: ["-c"] };
+      try {
+        const { shell, args } = getShellConfig();
+        return { cmd: shell, args };
+      } catch {
+        return { cmd: "bash", args: ["-c"] };
+      }
     case "node":
       return { cmd: process.execPath, args: ["-e"] };
     case "python":
@@ -260,11 +269,23 @@ export function runExecSandbox(
     const effectiveForceResolveDelay = opts.force_resolve_delay_ms ?? (effectiveGraceMs + HARD_DEADLINE_MS);
 
     let timedOut = false;
+    let aborted = false;
     let settled = false;
+    let killInitiated = false;
+    let timer: NodeJS.Timeout | undefined;
     let forceResolveTimer: NodeJS.Timeout | undefined;
+    let abortListener: (() => void) | undefined;
 
-    const timer = setTimeout(() => {
-      timedOut = true;
+    const removeAbortListener = () => {
+      if (opts.signal && abortListener) {
+        opts.signal.removeEventListener("abort", abortListener);
+        abortListener = undefined;
+      }
+    };
+
+    const initiateKill = () => {
+      if (killInitiated) return;
+      killInitiated = true;
       // killProcessTree handles both platforms and kills the whole tree: on Unix
       // it signals the process group (SIGTERM -> grace -> SIGKILL); on Windows it
       // force-kills the tree via taskkill /F /T. Using child.kill("SIGTERM") here
@@ -281,14 +302,14 @@ export function runExecSandbox(
         finalize(null, "SIGKILL", true);
       }, effectiveForceResolveDelay);
       forceResolveTimer.unref?.();
-    }, timeoutMs);
-    timer.unref?.();
+    };
 
     const finalize = (exitCode: number | null, signal: NodeJS.Signals | null, forceResolved = false) => {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
       clearTimeout(forceResolveTimer);
+      removeAbortListener();
       const duration = Date.now() - started;
       const stdoutBuf = Buffer.concat(stdoutChunks);
       const stderrBuf = Buffer.concat(stderrChunks);
@@ -301,11 +322,13 @@ export function runExecSandbox(
       const digest =
         digestBody.length > 0
           ? digestBody
-          : timedOut
-            ? "[no stdout — timed out]"
-            : stderrBuf.length > 0
-              ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
-              : "[no output]";
+          : aborted
+            ? "[no stdout — aborted]"
+            : timedOut
+              ? "[no stdout — timed out]"
+              : stderrBuf.length > 0
+                ? `[no stdout — tail of stderr]\n${tail(stderrBuf, opts.digest_chars)}`
+                : "[no output]";
 
       const result: ExecSandboxResult = {
         id,
@@ -313,6 +336,7 @@ export function runExecSandbox(
         exit_code: exitCode,
         signal,
         timed_out: timedOut,
+        aborted,
         force_resolved: forceResolved,
         duration_ms: duration,
         stdout_bytes: stdoutBytes,
@@ -328,6 +352,26 @@ export function runExecSandbox(
       resolveP(result);
     };
 
+    timer = setTimeout(() => {
+      timedOut = true;
+      initiateKill();
+    }, timeoutMs);
+    timer.unref?.();
+
+    if (opts.signal) {
+      abortListener = () => {
+        if (settled || timedOut) return;
+        aborted = true;
+        clearTimeout(timer);
+        initiateKill();
+      };
+      if (opts.signal.aborted) {
+        abortListener();
+      } else {
+        opts.signal.addEventListener("abort", abortListener, { once: true });
+      }
+    }
+
     child.on("error", (err) => {
       const message = err instanceof Error ? err.message : String(err);
       const line = `child error: ${message}\n`;
@@ -364,6 +408,7 @@ function writeMeta(
     exit_code: result.exit_code,
     signal: result.signal,
     timed_out: result.timed_out,
+    aborted: result.aborted === true,
     force_resolved: result.force_resolved,
     duration_ms: result.duration_ms,
     stdout_bytes: result.stdout_bytes,

package/src/resources/extensions/gsd/export-html.ts

@@ -874,9 +874,10 @@ function buildChangelogSection(data: VisualizerData): string {
 
 function buildKnowledgeSection(data: VisualizerData): string {
   const k = data.knowledge;
-  if (!k.exists) return section('knowledge', 'Knowledge', '<p class="empty">No KNOWLEDGE.md found.</p>');
+  const memories = data.memories;
+  if (!k.exists && memories.entries.length === 0) return section('knowledge', 'Knowledge', '<p class="empty">No KNOWLEDGE.md found.</p>');
   const total = k.rules.length + k.patterns.length + k.lessons.length;
-  if (total === 0) return section('knowledge', 'Knowledge', '<p class="empty">KNOWLEDGE.md exists but no entries parsed.</p>');
+  if (total === 0 && memories.entries.length === 0) return section('knowledge', 'Knowledge', '<p class="empty">KNOWLEDGE.md exists but no entries parsed.</p>');
 
   const rulesHtml = k.rules.length > 0 ? `
     <h3>Rules <span class="count">${k.rules.length}</span></h3>
@@ -899,7 +900,14 @@ function buildKnowledgeSection(data: VisualizerData): string {
       <tbody>${k.lessons.map(l => `<tr><td class="mono">${esc(l.id)}</td><td>${esc(l.content)}</td></tr>`).join('')}</tbody>
     </table>` : '';
 
-  return section('knowledge', `Knowledge <span class="count">${total}</span>`, `${rulesHtml}${patternsHtml}${lessonsHtml}`);
+  const memoriesHtml = memories.entries.length > 0 ? `
+    <h3>Memories <span class="count">${memories.entries.length}/${memories.totalCount}</span></h3>
+    <table class="tbl">
+      <thead><tr><th>ID</th><th>Category</th><th>Scope</th><th>Memory</th></tr></thead>
+      <tbody>${memories.entries.map(m => `<tr><td class="mono">${esc(m.id)}</td><td>${esc(m.category)}</td><td>${esc(m.scope)}</td><td>${esc(m.content)}</td></tr>`).join('')}</tbody>
+    </table>` : '';
+
+  return section('knowledge', `Knowledge <span class="count">${total + memories.totalCount}</span>`, `${rulesHtml}${patternsHtml}${lessonsHtml}${memoriesHtml}`);
 }
 
 // ─── Section: Captures ────────────────────────────────────────────────────────
@@ -1005,4 +1013,3 @@ function hRow(label: string, value: string, status?: 'ok' | 'caution' | 'warn'):
 
 function shortModel(m: string) { return m.replace(/^claude-/, '').replace(/^anthropic\//, ''); }
 function truncStr(s: string, n: number) { return s.length > n ? s.slice(0, n - 1) + '\u2026' : s; }
-

package/src/resources/extensions/gsd/export.ts

@@ -13,6 +13,84 @@ import type { UnitMetrics } from "./metrics.js";
 import { gsdRoot } from "./paths.js";
 import { formatDuration, fileLink } from "../shared/format-utils.js";
 import { getErrorMessage } from "./error-utils.js";
+import { isDbAvailable } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
+import { getActiveMemories, getActiveMemoriesRanked } from "./memory-store.js";
+import type { MemoryInfo } from "./visualizer-data.js";
+
+const EXPORT_MEMORY_LIMIT = 20;
+const EXPORT_MEMORY_CONTENT_LIMIT = 2000;
+
+interface ExportVisualizerData {
+  totals: any;
+  byPhase: any[];
+  bySlice: any[];
+  byModel: any[];
+  units: any[];
+  criticalPath?: any;
+  remainingSliceCount?: number;
+  memories?: MemoryInfo;
+}
+
+function ensureExportDb(basePath: string): void {
+  if (isDbAvailable()) return;
+  openExistingWorkflowDatabase(basePath);
+}
+
+function loadExportMemories(basePath: string, visualizerData?: ExportVisualizerData): MemoryInfo {
+  if (visualizerData?.memories) return limitMemoryInfo(visualizerData.memories);
+  ensureExportDb(basePath);
+  try {
+    const allActive = getActiveMemories();
+    const ranked = getActiveMemoriesRanked(EXPORT_MEMORY_LIMIT);
+    return {
+      totalCount: allActive.length,
+      entries: ranked.map((memory) => ({
+        id: memory.id,
+        category: memory.category,
+        content: limitMemoryContent(memory.content),
+        confidence: memory.confidence,
+        hitCount: memory.hit_count,
+        scope: memory.scope,
+        tags: memory.tags,
+        updatedAt: memory.updated_at,
+      })),
+    };
+  } catch {
+    return { entries: [], totalCount: 0 };
+  }
+}
+
+function limitMemoryInfo(memories: MemoryInfo): MemoryInfo {
+  return {
+    totalCount: memories.totalCount,
+    entries: memories.entries.map((memory) => ({
+      ...memory,
+      content: limitMemoryContent(memory.content),
+    })),
+  };
+}
+
+function limitMemoryContent(content: string): string {
+  if (content.length <= EXPORT_MEMORY_CONTENT_LIMIT) return content;
+  return `${content.slice(0, EXPORT_MEMORY_CONTENT_LIMIT).trimEnd()}...`;
+}
+
+function formatMemoryLines(memories: MemoryInfo): string[] {
+  if (memories.entries.length === 0) return [];
+  return [
+    `## Memories`,
+    ``,
+    `Active memories: ${memories.totalCount}`,
+    ``,
+    ...memories.entries.map((memory) => {
+      const scope = memory.scope ? `, scope ${memory.scope}` : "";
+      const tags = memory.tags.length > 0 ? `, tags ${memory.tags.join(", ")}` : "";
+      return `- **${memory.id}** (${memory.category}, confidence ${Math.round(memory.confidence * 100)}%, hits ${memory.hitCount}${scope}${tags}): ${memory.content}`;
+    }),
+    ``,
+  ];
+}
 
 /**
  * Open a file in the user's default browser.
@@ -37,7 +115,7 @@ export function openInBrowser(filePath: string): void {
 export function writeExportFile(
   basePath: string,
   format: "markdown" | "json",
-  visualizerData?: { totals: any; byPhase: any[]; bySlice: any[]; byModel: any[]; units: any[]; criticalPath?: any; remainingSliceCount?: number },
+  visualizerData?: ExportVisualizerData,
 ): string | null {
   const ledger = getLedger();
   let units: UnitMetrics[];
@@ -58,6 +136,7 @@ export function writeExportFile(
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
 
   if (format === "json") {
+    const memories = loadExportMemories(basePath, visualizerData);
     const report = {
       exportedAt: new Date().toISOString(),
       project: projectName,
@@ -65,6 +144,7 @@ export function writeExportFile(
       byPhase: visualizerData?.byPhase ?? aggregateByPhase(units),
       bySlice: visualizerData?.bySlice ?? aggregateBySlice(units),
       byModel: visualizerData?.byModel ?? aggregateByModel(units),
+      memories,
       units,
     };
     const outPath = join(exportDir, `export-${timestamp}.json`);
@@ -75,6 +155,8 @@ export function writeExportFile(
     const phases = visualizerData?.byPhase ?? aggregateByPhase(units);
     const slices = visualizerData?.bySlice ?? aggregateBySlice(units);
 
+    const memories = loadExportMemories(basePath, visualizerData);
+
     const md = [
       `# GSD Session Report — ${projectName}`,
       ``,
@@ -101,6 +183,7 @@ export function writeExportFile(
         `| ${s.sliceId} | ${s.units} | ${formatCost(s.cost)} | ${formatTokenCount(s.tokens.total)} | ${formatDuration(s.duration)} |`,
       ),
       ``,
+      ...formatMemoryLines(memories),
     ].join("\n");
 
     const outPath = join(exportDir, `export-${timestamp}.md`);
@@ -258,6 +341,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
   const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
 
   if (format === "json") {
+    const memories = loadExportMemories(basePath);
     const report = {
       exportedAt: new Date().toISOString(),
       project: projectName,
@@ -265,6 +349,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
       byPhase: aggregateByPhase(units),
       bySlice: aggregateBySlice(units),
       byModel: aggregateByModel(units),
+      memories,
       units,
     };
     const outPath = join(exportDir, `export-${timestamp}.json`);
@@ -274,6 +359,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
     const totals = getProjectTotals(units);
     const phases = aggregateByPhase(units);
     const slices = aggregateBySlice(units);
+    const memories = loadExportMemories(basePath);
 
     const md = [
       `# GSD Session Report — ${projectName}`,
@@ -301,6 +387,7 @@ export async function handleExport(args: string, ctx: ExtensionCommandContext, b
         `| ${s.sliceId} | ${s.units} | ${formatCost(s.cost)} | ${formatTokenCount(s.tokens.total)} | ${formatDuration(s.duration)} |`,
       ),
       ``,
+      ...formatMemoryLines(memories),
       `## Unit History`,
       ``,
       `| Type | ID | Model | Cost | Tokens | Duration |`,

package/src/resources/extensions/gsd/file-lock.ts

@@ -56,9 +56,9 @@ export function withFileLockSync<T>(
 ): T {
   if (!existsSync(filePath)) return fn();
 
-  const retries = opts.retries ?? DEFAULT_RETRIES;
   const stale = opts.stale ?? DEFAULT_STALE_MS;
   const onLocked: OnLocked = opts.onLocked ?? "fail";
+  const retries = onLocked === "skip" ? 0 : (opts.retries ?? DEFAULT_RETRIES);
 
   try {
     const release = acquireLockSyncWithRetry(filePath, retries, stale);

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

@@ -0,0 +1,249 @@
+// Project/App: gsd-pi
+// File Purpose: One-time migration from legacy nested .gsd/milestones/ to
+// flat-phase .gsd/phases/. Runs on startup when the legacy structure is detected.
+
+import { cpSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { renderAllFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
+import { getAllMilestones, getMilestoneSlices } from "./gsd-db.js";
+import { migrateFromMarkdown } from "./md-importer.js";
+import { countDbHierarchy } from "./migration-auto-check.js";
+import { logWarning } from "./workflow-logger.js";
+import { LAYOUT_SEGMENTS } from "./layout-policy.js";
+import { canonicalPhaseDirName, milestonesDir, resolveMilestonePath } from "./paths.js";
+
+const LEGACY_MIGRATING_SEGMENT = "milestones.migrating";
+
+function legacyMigratingPath(basePath: string): string {
+  return join(basePath, ".gsd", LEGACY_MIGRATING_SEGMENT);
+}
+
+function hasLegacyMilestoneSubdirs(dirPath: string): boolean {
+  if (!existsSync(dirPath)) return false;
+  try {
+    return readdirSync(dirPath).some(e => statSync(join(dirPath, e)).isDirectory());
+  } catch {
+    return false;
+  }
+}
+
+function rollbackPartialMigration(
+  basePath: string,
+  backupDir: string,
+  migratingPath?: string,
+): void {
+  // Remove the partially-written phases/ dir.
+  rmSync(join(basePath, ".gsd", LAYOUT_SEGMENTS.level1), { recursive: true, force: true });
+  // Restore milestones/ — prefer renaming the preserved migrating copy back.
+  const milestonesPath = join(basePath, ".gsd", "milestones");
+  try {
+    if (migratingPath && existsSync(migratingPath) && !existsSync(milestonesPath)) {
+      renameSync(migratingPath, milestonesPath);
+      return;
+    }
+    if (existsSync(backupDir)) {
+      cpSync(backupDir, milestonesPath, { recursive: true });
+    }
+    if (migratingPath && existsSync(migratingPath)) {
+      rmSync(migratingPath, { recursive: true, force: true });
+    }
+  } catch (restoreErr) {
+    logWarning(
+      "migration",
+      `rollback: could not restore milestones/: ${(restoreErr as Error).message}`,
+    );
+    // Non-fatal: backup still exists at backupDir for manual recovery.
+  }
+}
+
+/**
+ * Detect whether the project uses the legacy nested layout.
+ * True when .gsd/milestones/ exists AND contains at least one milestone
+ * subdirectory. An empty milestones/ dir (created by old bootstrap code
+ * before it was fixed) is not a real legacy layout and must not trigger
+ * a migration that would thrash the reconciler.
+ */
+export function needsFlatPhaseMigration(basePath: string): boolean {
+  if (hasLegacyMilestoneSubdirs(join(basePath, ".gsd", "milestones"))) return true;
+  // Resume an interrupted migration where the legacy tree was renamed aside.
+  return hasLegacyMilestoneSubdirs(legacyMigratingPath(basePath));
+}
+
+/** Retention window before flat-phase migration backups are auto-pruned. */
+export const FLAT_PHASE_BACKUP_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+
+/**
+ * Remove stale flat-phase migration backups after the retention window.
+ * Only runs when migration is complete (.gsd/phases/ exists, legacy layout gone).
+ * Returns the number of migrate-* directories removed.
+ */
+export function pruneStaleFlatPhaseBackups(basePath: string): number {
+  if (needsFlatPhaseMigration(basePath)) return 0;
+
+  const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+  if (!existsSync(phasesPath)) return 0;
+
+  const backupRoot = join(basePath, ".gsd-backups");
+  if (!existsSync(backupRoot)) return 0;
+
+  const now = Date.now();
+  let removed = 0;
+  for (const entry of readdirSync(backupRoot)) {
+    if (!entry.startsWith("migrate-")) continue;
+    const dirPath = join(backupRoot, entry);
+    try {
+      const st = statSync(dirPath);
+      if (!st.isDirectory()) continue;
+      if (now - st.mtimeMs < FLAT_PHASE_BACKUP_RETENTION_MS) continue;
+      rmSync(dirPath, { recursive: true, force: true });
+      removed++;
+    } catch {
+      // Non-fatal: leave backup for manual recovery.
+    }
+  }
+
+  try {
+    if (readdirSync(backupRoot).length === 0) {
+      rmSync(backupRoot, { recursive: true, force: true });
+    }
+  } catch {
+    // Non-fatal.
+  }
+
+  return removed;
+}
+
+/**
+ * Migrate from legacy nested .gsd/milestones/ to flat-phase .gsd/phases/.
+ *
+ * Steps:
+ * 1. Backup .gsd/milestones/ to .gsd-backups/migrate-<ts>/
+ * 2. Rename .gsd/milestones/ aside so path resolvers target phases/
+ * 3. Render flat-phase from the DB (which already has the data)
+ * 4. Verify counts match
+ * 5. Remove the renamed legacy tree
+ *
+ * Idempotent: if .gsd/milestones/ doesn't exist, returns immediately.
+ */
+export async function migrateToFlatPhase(basePath: string): Promise<void> {
+  if (!needsFlatPhaseMigration(basePath)) return;
+
+  const milestonesPath = join(basePath, ".gsd", "milestones");
+  const migratingPath = legacyMigratingPath(basePath);
+  const phasesPath = join(basePath, ".gsd", LAYOUT_SEGMENTS.level1);
+  const resumingInterrupted =
+    !hasLegacyMilestoneSubdirs(milestonesPath) && hasLegacyMilestoneSubdirs(migratingPath);
+
+  // 1. Reconcile DB from legacy markdown before backup/removal so on-disk-only
+  // content is imported even when milestone rows already exist in SQLite.
+  // Check BEFORE creating the backup — avoids accumulating .gsd-backups/ entries
+  // on every session start when milestones/ exists but the DB has no rows.
+  migrateFromMarkdown(basePath);
+  const milestonesBefore = getAllMilestones().length;
+  if (milestonesBefore === 0) {
+    logWarning(
+      "migration",
+      "flat-phase migration skipped: legacy milestones/ exists but DB has no milestone rows — will retry when DB is populated",
+    );
+    return;
+  }
+
+  let backupDir = migratingPath;
+  if (!resumingInterrupted) {
+    // 2. Backup (only reached when the DB has rows and migration will proceed)
+    const ts = Date.now();
+    backupDir = join(basePath, ".gsd-backups", `migrate-${ts}`);
+    try {
+      mkdirSync(join(basePath, ".gsd-backups"), { recursive: true });
+      cpSync(milestonesPath, backupDir, { recursive: true });
+    } catch (err) {
+      logWarning("migration", `flat-phase migration backup failed: ${(err as Error).message}`);
+      throw err;
+    }
+
+    // 3. Rename legacy tree aside before rendering so path resolvers target
+    // phases/ instead of writing back into the nested milestones/ layout.
+    // Keep the full tree on disk until render+verify succeed (unlike rmSync).
+    try {
+      renameSync(milestonesPath, migratingPath);
+    } catch (err) {
+      logWarning("migration", `failed to rename legacy milestones/ before render: ${(err as Error).message}`);
+      throw err;
+    }
+  } else {
+    // Interrupted run: clear any partial phases/ projection before retrying.
+    rmSync(phasesPath, { recursive: true, force: true });
+  }
+
+  // 4. Render flat-phase from DB
+  let renderResult: { rendered: number; skipped: number; errors: string[] };
+  try {
+    renderResult = await renderAllFromDb(basePath);
+    // Slice-less milestones still need a phase directory for flat-phase layout.
+    for (const milestone of getAllMilestones()) {
+      if (getMilestoneSlices(milestone.id).length > 0) continue;
+      const roadmapResult = await renderRoadmapFromDb(basePath, milestone.id);
+      if ("skipped" in roadmapResult) {
+        const phaseDir = resolveMilestonePath(basePath, milestone.id) ??
+          join(milestonesDir(basePath), canonicalPhaseDirName(milestone.id, milestone.title));
+        mkdirSync(phaseDir, { recursive: true });
+        continue;
+      }
+      renderResult.rendered++;
+    }
+  } catch (err) {
+    logWarning("migration", `flat-phase render failed: ${(err as Error).message}`);
+    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    throw err;
+  }
+
+  // 5. Verify render succeeded and flat-phase projection was written
+  if (renderResult.errors.length > 0) {
+    logWarning(
+      "migration",
+      `flat-phase render had ${renderResult.errors.length} error(s): ${renderResult.errors.join("; ")}`,
+    );
+    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    throw new Error(
+      `flat-phase migration render failed: ${renderResult.errors.slice(0, 3).join("; ")}`,
+    );
+  }
+
+  const db = countDbHierarchy();
+  let renderedDirCount = 0;
+  try {
+    // /^\d+-/ matches any numeric prefix (01-, 10-, 100-) so M100+ milestones
+    // whose dirs start with "100-slug" are counted correctly.
+    renderedDirCount = readdirSync(phasesPath, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && /^\d+-/.test(entry.name)).length;
+  } catch {
+    // phases/ doesn't exist or is unreadable — same as zero dirs
+  }
+  if (db.milestones > 0 && renderedDirCount !== db.milestones) {
+    logWarning(
+      "migration",
+      `phases/ dir count mismatch: expected ${db.milestones}, found ${renderedDirCount}`,
+    );
+    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    throw new Error("flat-phase migration verification failed: phases dir milestone count mismatch");
+  }
+  if (db.slices > 0 && renderResult.rendered === 0) {
+    logWarning(
+      "migration",
+      "flat-phase migration verification failed: render produced no artifacts for populated DB",
+    );
+    rollbackPartialMigration(basePath, backupDir, migratingPath);
+    throw new Error("flat-phase migration verification failed: no artifacts rendered");
+  }
+
+  // 6. Verified — remove the renamed legacy tree (backup already on disk).
+  try {
+    rmSync(migratingPath, { recursive: true, force: true });
+  } catch (err) {
+    logWarning(
+      "migration",
+      `flat-phase migration succeeded but could not remove ${LEGACY_MIGRATING_SEGMENT}: ${(err as Error).message}`,
+    );
+  }
+}