@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.97ef11e3

package/src/resources/extensions/gsd/migrate/command.ts

@@ -10,198 +10,24 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
-import { existsSync, readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
 import { gsdRoot } from "../paths.js";
-import { fileURLToPath } from "node:url";
 import { showNextAction } from "../../shared/tui.js";
 import {
   notifyMigrateNeedsInteractiveMenu,
   requiresInteractiveMenu,
 } from "../command-feedback.js";
-import {
-  validatePlanningDirectory,
-  parsePlanningDirectory,
-  transformToGSD,
-  generatePreview,
-  writeGSDDirectory,
-} from "./index.js";
-
-import type { MigrationPreview, WrittenFiles } from "./writer.js";
-import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
-import { clearArtifacts, clearDecisions, clearRequirements, clearEngineHierarchy, transaction } from "../gsd-db.js";
-import { migrateFromMarkdown } from "../md-importer.js";
-import { deriveState, invalidateStateCache } from "../state.js";
-import {
-  archiveLegacyPlanningDirectory,
-  verifyMigrationProjection,
-  writeMigrationAudit,
-  type LegacyArchiveResult,
-  type MigrationAuditResult,
-  type MigrationProjectionVerification,
-} from "./audit.js";
-import {
-  assertMigrationHasSlices,
-  assertMigrationTargetAvailable,
-  prepareMigrationTarget,
-  resolveMigrationPaths,
-  restoreMigrationTarget,
-  type MigrationBackup,
-} from "./safety.js";
-
-export type MigrationImportCounts = ReturnType<typeof migrateFromMarkdown>;
-
-export interface MigrationExecutionResult {
-  backup: MigrationBackup;
-  written: WrittenFiles;
-  imported: MigrationImportCounts;
-  legacyArchive: LegacyArchiveResult;
-  verification: MigrationProjectionVerification;
-  audit: MigrationAuditResult;
-}
-
-function assertMigrationImportMatchesPreview(imported: MigrationImportCounts, preview: MigrationPreview): void {
-  const mismatches: string[] = [];
-  if (imported.decisions !== preview.decisions.total) {
-    mismatches.push(`decisions ${imported.decisions}/${preview.decisions.total}`);
-  }
-  if (imported.hierarchy.milestones !== preview.milestoneCount) {
-    mismatches.push(`milestones ${imported.hierarchy.milestones}/${preview.milestoneCount}`);
-  }
-  if (imported.hierarchy.slices !== preview.totalSlices) {
-    mismatches.push(`slices ${imported.hierarchy.slices}/${preview.totalSlices}`);
-  }
-  if (imported.hierarchy.tasks !== preview.totalTasks) {
-    mismatches.push(`tasks ${imported.hierarchy.tasks}/${preview.totalTasks}`);
-  }
-  if (imported.requirements !== preview.requirements.total) {
-    mismatches.push(`requirements ${imported.requirements}/${preview.requirements.total}`);
-  }
-  if (mismatches.length > 0) {
-    throw new Error(`migration DB import verification failed: ${mismatches.join(", ")}`);
-  }
-}
+import { executeMigrationWrite, type MigrationExecutionResult } from "./execution.js";
+import { createMigrationPlan } from "./plan.js";
+import { buildMigrationPreviewSummary, buildReviewPrompt } from "./presentation.js";
+import type { MigrationPreview } from "./writer.js";
 
-export async function importWrittenMigrationToDb(
-  basePath: string,
-  preview?: MigrationPreview,
-): Promise<MigrationImportCounts> {
-  const opened = await ensureDbOpen(basePath);
-  if (!opened) {
-    throw new Error(`failed to open or create the GSD database at ${basePath}`);
-  }
-
-  const counts = transaction(() => {
-    clearEngineHierarchy();
-    clearArtifacts();
-    clearDecisions();
-    clearRequirements();
-    const imported = migrateFromMarkdown(basePath);
-    if (preview) assertMigrationImportMatchesPreview(imported, preview);
-    return imported;
-  });
-  invalidateStateCache();
-  return counts;
-}
-
-export async function assertMigrationDbReadiness(
-  targetRoot: string,
-  preview: MigrationPreview,
-): Promise<{ phase: string; registry: number }> {
-  invalidateStateCache();
-  const state = await deriveState(targetRoot);
-  const dbUnavailable = state.blockers.some((blocker) => blocker.includes("DB unavailable"));
-  if (dbUnavailable) {
-    throw new Error(`migration DB readiness failed: ${state.blockers.join("; ")}`);
-  }
-  if (state.registry.length !== preview.milestoneCount) {
-    throw new Error(`migration DB readiness failed: registry ${state.registry.length}/${preview.milestoneCount}`);
-  }
-  return {
-    phase: state.phase,
-    registry: state.registry.length,
-  };
-}
-
-export async function executeMigrationWrite(
-  sourcePath: string,
-  targetRoot: string,
-  project: ReturnType<typeof transformToGSD>,
-  preview: MigrationPreview,
-  startedAt: string = new Date().toISOString(),
-): Promise<MigrationExecutionResult> {
-  const backup = prepareMigrationTarget(targetRoot);
-
-  try {
-    const written = await writeGSDDirectory(project, targetRoot);
-    const legacyArchive = await archiveLegacyPlanningDirectory(sourcePath, targetRoot);
-    const imported = await importWrittenMigrationToDb(targetRoot, preview);
-    const verification = await verifyMigrationProjection(targetRoot, preview);
-    verification.dbReadiness = await assertMigrationDbReadiness(targetRoot, preview);
-    const audit = await writeMigrationAudit({
-      sourcePath,
-      targetRoot,
-      backupPath: backup.backupPath,
-      preview,
-      written,
-      imported,
-      legacyArchive,
-      verification,
-      startedAt,
-      completedAt: new Date().toISOString(),
-    });
-
-    return { backup, written, imported, legacyArchive, verification, audit };
-  } catch (err) {
-    restoreMigrationTarget(backup);
-    throw err;
-  }
-}
-
-/** Format preview stats for embedding in the review prompt. */
-function formatPreviewStats(preview: MigrationPreview): string {
-  const lines = [
-    `- Decisions: ${preview.decisions.total}`,
-    `- Milestones: ${preview.milestoneCount}`,
-    `- Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
-    `- Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,
-  ];
-  if (preview.requirements.total > 0) {
-    lines.push(
-      `- Requirements: ${preview.requirements.total} (${preview.requirements.validated} validated, ${preview.requirements.active} active, ${preview.requirements.deferred} deferred, ${preview.requirements.outOfScope} out of scope)`,
-    );
-  }
-  if (preview.migrationInputs) {
-    lines.push(`- Legacy inputs: ${preview.migrationInputs.milestonePhaseDirs} milestone phase dir(s), ${preview.migrationInputs.decisions} decision file(s), ${preview.migrationInputs.seeds} seed file(s)`);
-  }
-  return lines.join("\n");
-}
-
-/** Load and interpolate the review-migration prompt template. */
-function buildReviewPrompt(
-  sourcePath: string,
-  gsdPath: string,
-  preview: MigrationPreview,
-): string {
-  const promptsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "prompts");
-  const templatePath = join(promptsDir, "review-migration.md");
-  let content = readFileSync(templatePath, "utf-8");
-
-  content = content.replaceAll("{{sourcePath}}", sourcePath);
-  content = content.replaceAll("{{gsdPath}}", gsdPath);
-  content = content.replaceAll("{{previewStats}}", formatPreviewStats(preview));
-
-  return content.trim();
-}
-
-/** Dispatch the review prompt to the agent. */
 function dispatchReview(
   pi: ExtensionAPI,
   sourcePath: string,
   gsdPath: string,
   preview: MigrationPreview,
 ): void {
-  const prompt = buildReviewPrompt(sourcePath, gsdPath, preview);
+  const prompt = buildReviewPrompt({ sourcePath, gsdPath, preview });
 
   pi.sendMessage(
     {
@@ -218,34 +44,28 @@ export async function handleMigrate(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
 ): Promise<void> {
-  // ── Resolve source path ────────────────────────────────────────────────────
-  const { sourcePath, targetRoot } = resolveMigrationPaths(args);
+  const plan = await createMigrationPlan(args);
+  const { sourcePath, targetRoot } = plan;
 
-  if (!existsSync(sourcePath)) {
+  if (plan.status === "missing-source") {
     ctx.ui.notify(
       `Directory not found: ${sourcePath}\n\n` +
-      'Migration converts a .planning/ directory (from older GSD versions) into .gsd/ format.\n' +
-      'If you are starting a new project, use /gsd:new-project instead.\n' +
-      'If migrating, ensure the path contains a .planning/ directory.',
+      "Migration converts a .planning/ directory (from older GSD versions) into .gsd/ format.\n" +
+      "If you are starting a new project, use /gsd:new-project instead.\n" +
+      "If migrating, ensure the path contains a .planning/ directory.",
       "error",
     );
     return;
   }
 
-  // ── Validate ───────────────────────────────────────────────────────────────
-  const validation = await validatePlanningDirectory(sourcePath);
-
-  const warnings = validation.issues.filter((i) => i.severity === "warning");
-  const fatals = validation.issues.filter((i) => i.severity === "fatal");
-
-  for (const w of warnings) {
-    ctx.ui.notify(`⚠ ${w.message} (${w.file})`, "warning");
+  for (const warning of plan.warnings) {
+    ctx.ui.notify(`⚠ ${warning.message} (${warning.file})`, "warning");
   }
-  for (const f of fatals) {
-    ctx.ui.notify(`✖ ${f.message} (${f.file})`, "error");
+  for (const fatal of plan.fatals) {
+    ctx.ui.notify(`✖ ${fatal.message} (${fatal.file})`, "error");
   }
 
-  if (!validation.valid) {
+  if (plan.status === "invalid") {
     ctx.ui.notify(
       "Migration blocked — fix the fatal issues above before retrying.",
       "error",
@@ -253,41 +73,15 @@ export async function handleMigrate(
     return;
   }
 
-  // ── Parse → Transform → Preview ───────────────────────────────────────────
-  const parsed = await parsePlanningDirectory(sourcePath);
-  const project = transformToGSD(parsed);
-  const preview = generatePreview(project);
-  try {
-    assertMigrationHasSlices(preview);
-    await assertMigrationTargetAvailable(targetRoot);
-  } catch (err) {
-    ctx.ui.notify((err as Error).message, "error");
+  if (plan.status === "blocked") {
+    ctx.ui.notify(plan.message, "error");
     return;
   }
 
-  // ── Build preview text ─────────────────────────────────────────────────────
-  const lines: string[] = [
-    `Decisions: ${preview.decisions.total}`,
-    `Milestones: ${preview.milestoneCount}`,
-    `Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
-    `Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,
-  ];
+  const { project, preview } = plan;
 
-  if (preview.requirements.total > 0) {
-    lines.push(
-      `Requirements: ${preview.requirements.total} (${preview.requirements.validated} validated, ${preview.requirements.active} active, ${preview.requirements.deferred} deferred, ${preview.requirements.outOfScope} out of scope)`,
-    );
-  }
-  if (preview.migrationInputs) {
-    lines.push(`Legacy inputs: ${preview.migrationInputs.milestonePhaseDirs} milestone phase dir(s), ${preview.migrationInputs.decisions} decision file(s), ${preview.migrationInputs.seeds} seed file(s)`);
-  }
-
-  const targetGsdExists = existsSync(gsdRoot(targetRoot));
-  if (targetGsdExists) {
-    lines.push("");
-    lines.push(`⚠ A .gsd directory already exists at ${gsdRoot(targetRoot)}.`);
-    lines.push("It will be backed up, deleted, and rewritten fresh before DB import.");
-  }
+  // ── Build preview text ─────────────────────────────────────────────────────
+  const lines = buildMigrationPreviewSummary(preview, targetRoot);
 
   // ── Confirmation via showNextAction ────────────────────────────────────────
   if (requiresInteractiveMenu(ctx, false)) {

package/src/resources/extensions/gsd/migrate/execution.ts

@@ -0,0 +1,136 @@
+// gsd-pi - /gsd migrate execution service.
+// File Purpose: Write migrated .gsd files, import them into the DB, verify projection/readiness, and rollback on failure.
+
+import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
+import { closeWorkflowDatabase } from "../db-workspace.js";
+import { clearArtifacts, clearDecisions, clearEngineHierarchy, clearRequirements, transaction } from "../gsd-db.js";
+import { migrateFromMarkdown } from "../md-importer.js";
+import { deriveState, invalidateStateCache } from "../state.js";
+import {
+  archiveLegacyPlanningDirectory,
+  verifyMigrationProjection,
+  writeMigrationAudit,
+  type LegacyArchiveResult,
+  type MigrationAuditResult,
+  type MigrationProjectionVerification,
+} from "./audit.js";
+import {
+  prepareMigrationTarget,
+  restoreMigrationTarget,
+  type MigrationBackup,
+} from "./safety.js";
+import { writeGSDDirectory, type MigrationPreview, type WrittenFiles } from "./writer.js";
+import type { GSDProject } from "./types.js";
+
+export type MigrationImportCounts = ReturnType<typeof migrateFromMarkdown>;
+
+export interface MigrationExecutionResult {
+  backup: MigrationBackup;
+  written: WrittenFiles;
+  imported: MigrationImportCounts;
+  legacyArchive: LegacyArchiveResult;
+  verification: MigrationProjectionVerification;
+  audit: MigrationAuditResult;
+}
+
+function assertMigrationImportMatchesPreview(imported: MigrationImportCounts, preview: MigrationPreview): void {
+  const mismatches: string[] = [];
+  if (imported.decisions !== preview.decisions.total) {
+    mismatches.push(`decisions ${imported.decisions}/${preview.decisions.total}`);
+  }
+  if (imported.hierarchy.milestones !== preview.milestoneCount) {
+    mismatches.push(`milestones ${imported.hierarchy.milestones}/${preview.milestoneCount}`);
+  }
+  if (imported.hierarchy.slices !== preview.totalSlices) {
+    mismatches.push(`slices ${imported.hierarchy.slices}/${preview.totalSlices}`);
+  }
+  if (imported.hierarchy.tasks !== preview.totalTasks) {
+    mismatches.push(`tasks ${imported.hierarchy.tasks}/${preview.totalTasks}`);
+  }
+  if (imported.requirements !== preview.requirements.total) {
+    mismatches.push(`requirements ${imported.requirements}/${preview.requirements.total}`);
+  }
+  if (mismatches.length > 0) {
+    throw new Error(`migration DB import verification failed: ${mismatches.join(", ")}`);
+  }
+}
+
+export async function importWrittenMigrationToDb(
+  basePath: string,
+  preview?: MigrationPreview,
+): Promise<MigrationImportCounts> {
+  const opened = await ensureDbOpen(basePath);
+  if (!opened) {
+    throw new Error(`failed to open or create the GSD database at ${basePath}`);
+  }
+
+  const counts = transaction(() => {
+    clearEngineHierarchy();
+    clearArtifacts();
+    clearDecisions();
+    clearRequirements();
+    const imported = migrateFromMarkdown(basePath);
+    if (preview) assertMigrationImportMatchesPreview(imported, preview);
+    return imported;
+  });
+  invalidateStateCache();
+  return counts;
+}
+
+export async function assertMigrationDbReadiness(
+  targetRoot: string,
+  preview: MigrationPreview,
+): Promise<{ phase: string; registry: number }> {
+  invalidateStateCache();
+  const state = await deriveState(targetRoot);
+  const dbUnavailable = state.blockers.some((blocker) => blocker.includes("DB unavailable"));
+  if (dbUnavailable) {
+    throw new Error(`migration DB readiness failed: ${state.blockers.join("; ")}`);
+  }
+  if (state.registry.length !== preview.milestoneCount) {
+    throw new Error(`migration DB readiness failed: registry ${state.registry.length}/${preview.milestoneCount}`);
+  }
+  return {
+    phase: state.phase,
+    registry: state.registry.length,
+  };
+}
+
+export async function executeMigrationWrite(
+  sourcePath: string,
+  targetRoot: string,
+  project: GSDProject,
+  preview: MigrationPreview,
+  startedAt: string = new Date().toISOString(),
+): Promise<MigrationExecutionResult> {
+  const backup = prepareMigrationTarget(targetRoot);
+
+  try {
+    const written = await writeGSDDirectory(project, targetRoot);
+    const legacyArchive = await archiveLegacyPlanningDirectory(sourcePath, targetRoot);
+    const imported = await importWrittenMigrationToDb(targetRoot, preview);
+    const verification = await verifyMigrationProjection(targetRoot, preview);
+    verification.dbReadiness = await assertMigrationDbReadiness(targetRoot, preview);
+    const audit = await writeMigrationAudit({
+      sourcePath,
+      targetRoot,
+      backupPath: backup.backupPath,
+      preview,
+      written,
+      imported,
+      legacyArchive,
+      verification,
+      startedAt,
+      completedAt: new Date().toISOString(),
+    });
+
+    return { backup, written, imported, legacyArchive, verification, audit };
+  } catch (error) {
+    // The import transaction may have committed and the process may hold an
+    // open handle to the target gsd.db; close before the restore replaces the
+    // file on disk, and leave closed so the next open rebinds to the restored file.
+    try { closeWorkflowDatabase(); } catch { /* best-effort: restore must proceed */ }
+    restoreMigrationTarget(backup);
+    throw error;
+  }
+}

package/src/resources/extensions/gsd/migrate/plan.ts

@@ -0,0 +1,101 @@
+// gsd-pi - /gsd migrate planning service.
+// File Purpose: Resolve, validate, parse, transform, preview, and guard a migration before UI confirmation.
+
+import { existsSync } from "node:fs";
+
+import {
+  assertMigrationHasSlices,
+  assertMigrationTargetAvailable,
+  resolveMigrationPaths,
+  type MigrationPaths,
+} from "./safety.js";
+import { parsePlanningDirectory } from "./parser.js";
+import { generatePreview } from "./preview.js";
+import { transformToGSD } from "./transformer.js";
+import { validatePlanningDirectory } from "./validator.js";
+import type { GSDProject, ValidationIssue, ValidationResult } from "./types.js";
+import type { MigrationPreview } from "./writer.js";
+
+export interface SplitValidationIssues {
+  warnings: ValidationIssue[];
+  fatals: ValidationIssue[];
+}
+
+interface MigrationPlanBase extends MigrationPaths {
+  warnings: ValidationIssue[];
+  fatals: ValidationIssue[];
+}
+
+export interface MissingMigrationSourceResult extends MigrationPaths {
+  status: "missing-source";
+}
+
+export interface InvalidMigrationPlanResult extends MigrationPlanBase {
+  status: "invalid";
+  validation: ValidationResult;
+}
+
+export interface BlockedMigrationPlanResult extends MigrationPlanBase {
+  status: "blocked";
+  validation: ValidationResult;
+  message: string;
+}
+
+export interface ReadyMigrationPlanResult extends MigrationPlanBase {
+  status: "ready";
+  validation: ValidationResult;
+  project: GSDProject;
+  preview: MigrationPreview;
+}
+
+export type MigrationPlanResult =
+  | MissingMigrationSourceResult
+  | InvalidMigrationPlanResult
+  | BlockedMigrationPlanResult
+  | ReadyMigrationPlanResult;
+
+export function splitValidationIssues(validation: ValidationResult): SplitValidationIssues {
+  return {
+    warnings: validation.issues.filter((issue) => issue.severity === "warning"),
+    fatals: validation.issues.filter((issue) => issue.severity === "fatal"),
+  };
+}
+
+export async function createMigrationPlan(args: string, cwd: string = process.cwd()): Promise<MigrationPlanResult> {
+  const paths = resolveMigrationPaths(args, cwd);
+  if (!existsSync(paths.sourcePath)) {
+    return { status: "missing-source", ...paths };
+  }
+
+  const validation = await validatePlanningDirectory(paths.sourcePath);
+  const issues = splitValidationIssues(validation);
+  if (!validation.valid) {
+    return { status: "invalid", ...paths, validation, ...issues };
+  }
+
+  const parsed = await parsePlanningDirectory(paths.sourcePath);
+  const project = transformToGSD(parsed);
+  const preview = generatePreview(project);
+
+  try {
+    assertMigrationHasSlices(preview);
+    await assertMigrationTargetAvailable(paths.targetRoot);
+  } catch (error) {
+    return {
+      status: "blocked",
+      ...paths,
+      validation,
+      ...issues,
+      message: error instanceof Error ? error.message : String(error),
+    };
+  }
+
+  return {
+    status: "ready",
+    ...paths,
+    validation,
+    ...issues,
+    project,
+    preview,
+  };
+}

package/src/resources/extensions/gsd/migrate/planning-writer.ts

@@ -186,17 +186,14 @@ export async function writePlanningDirectory(
       });
 
       if (tasks.length === 0) {
-        // Empty phase — write a single placeholder plan so the dir isn't empty.
-        const planPath = join(phaseDir, `${pad(phaseNum)}-01-PLAN.md`);
-        await saveFile(
-          planPath,
-          formatPlanningPlan(phaseNum, 1, slice.title || slice.id, []),
-        );
-        paths.push(planPath);
-        projectionWrites.push({
-          relPath: toPlanningRel(planPath),
-          entities: [`${milestone.id}/${slice.id}`],
-        });
+        // Sketch / undecomposed slice — zero tasks. Do NOT emit an ingestible
+        // *-PLAN.md here: the reverse transform maps one GSDTask per plan file
+        // (transformer.ts mapSlice), so a placeholder would materialize a
+        // phantom "Plan NN" task and flip the slice from "needs planning" to
+        // "has a planned task", causing auto-mode to skip planning (issue #1285).
+        // The phase dir is already created (mkdirSync above) and the slice is
+        // listed in ROADMAP.md, so it round-trips with tasks = [] — the correct
+        // sketch-slice shape.
       } else {
         for (let ti = 0; ti < tasks.length; ti++) {
           const task = tasks[ti]!;
@@ -223,19 +220,14 @@ export async function writePlanningDirectory(
     }
   }
 
-  // If no slices produced any phases, write a single empty phase so ROADMAP.md
-  // isn't blank and the layout is still discoverable.
+  // If no slices produced any phases, emit a single empty phase dir + ROADMAP
+  // entry so the layout stays discoverable. Do NOT write a placeholder
+  // *-PLAN.md — an ingestible plan file would round-trip into a phantom task
+  // (see the tasks.length === 0 branch above, issue #1285).
   if (roadmapEntries.length === 0) {
     const phaseDirName = `${pad(1)}-milestone`;
     const phaseDir = join(root, "phases", phaseDirName);
     mkdirSync(phaseDir, { recursive: true });
-    const planPath = join(phaseDir, `${pad(1)}-01-PLAN.md`);
-    await saveFile(planPath, formatPlanningPlan(1, 1, milestones[0]!.title || milestones[0]!.id, []));
-    paths.push(planPath);
-    projectionWrites.push({
-      relPath: toPlanningRel(planPath),
-      entities: [milestones[0]!.id],
-    });
     roadmapEntries.push({ number: 1, title: milestones[0]!.title || milestones[0]!.id, done: false });
   }
 

package/src/resources/extensions/gsd/migrate/presentation.ts

@@ -0,0 +1,83 @@
+// gsd-pi - /gsd migrate presentation helpers.
+// File Purpose: Pure formatting for migration previews and post-write review prompts.
+
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { gsdRoot } from "../paths.js";
+import type { MigrationPreview } from "./writer.js";
+
+export interface ReviewPromptInput {
+  sourcePath: string;
+  gsdPath: string;
+  preview: MigrationPreview;
+  templatePath?: string;
+}
+
+function formatRequirements(preview: MigrationPreview): string | null {
+  if (preview.requirements.total === 0) return null;
+  return `Requirements: ${preview.requirements.total} (${preview.requirements.validated} validated, ${preview.requirements.active} active, ${preview.requirements.deferred} deferred, ${preview.requirements.outOfScope} out of scope)`;
+}
+
+function formatLegacyInputs(preview: MigrationPreview): string | null {
+  if (!preview.migrationInputs) return null;
+  return `Legacy inputs: ${preview.migrationInputs.milestonePhaseDirs} milestone phase dir(s), ${preview.migrationInputs.decisions} decision file(s), ${preview.migrationInputs.seeds} seed file(s)`;
+}
+
+export function buildMigrationPreviewSummary(preview: MigrationPreview, targetRoot: string): string[] {
+  const lines: string[] = [
+    `Decisions: ${preview.decisions.total}`,
+    `Milestones: ${preview.milestoneCount}`,
+    `Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
+    `Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,
+  ];
+
+  const requirements = formatRequirements(preview);
+  if (requirements) lines.push(requirements);
+
+  const legacyInputs = formatLegacyInputs(preview);
+  if (legacyInputs) lines.push(legacyInputs);
+
+  const targetGsdPath = gsdRoot(targetRoot);
+  if (existsSync(targetGsdPath)) {
+    lines.push("");
+    lines.push(`⚠ A .gsd directory already exists at ${targetGsdPath}.`);
+    lines.push("It will be backed up, deleted, and rewritten fresh before DB import.");
+  }
+
+  return lines;
+}
+
+export function formatMigrationPreviewStats(preview: MigrationPreview): string {
+  const lines = [
+    `- Decisions: ${preview.decisions.total}`,
+    `- Milestones: ${preview.milestoneCount}`,
+    `- Slices: ${preview.totalSlices} (${preview.doneSlices} done — ${preview.sliceCompletionPct}%)`,
+    `- Tasks: ${preview.totalTasks} (${preview.doneTasks} done — ${preview.taskCompletionPct}%)`,
+  ];
+
+  const requirements = formatRequirements(preview);
+  if (requirements) lines.push(`- ${requirements}`);
+
+  const legacyInputs = formatLegacyInputs(preview);
+  if (legacyInputs) lines.push(`- ${legacyInputs}`);
+
+  return lines.join("\n");
+}
+
+function defaultReviewTemplatePath(): string {
+  const promptsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "prompts");
+  return join(promptsDir, "review-migration.md");
+}
+
+export function buildReviewPrompt(input: ReviewPromptInput): string {
+  const templatePath = input.templatePath ?? defaultReviewTemplatePath();
+  let content = readFileSync(templatePath, "utf-8");
+
+  content = content.replaceAll("{{sourcePath}}", input.sourcePath);
+  content = content.replaceAll("{{gsdPath}}", input.gsdPath);
+  content = content.replaceAll("{{previewStats}}", formatMigrationPreviewStats(input.preview));
+
+  return content.trim();
+}

package/src/resources/extensions/gsd/model-cost-table.ts

@@ -62,6 +62,8 @@ export const BUNDLED_COST_TABLE: ModelCostEntry[] = [
   // GPT-5.5 API list price, also used for live Codex OAuth routing.
   // Source: https://openai.com/api/pricing/
   { id: "gpt-5.5", inputPer1k: 0.005, outputPer1k: 0.03, updatedAt: "2026-04-23" },
+  // Mirrors gpt-5.5 list pricing until OpenAI publishes official gpt-5.6 pricing.
+  { id: "gpt-5.6", inputPer1k: 0.005, outputPer1k: 0.03, updatedAt: "2026-07-08" },
 
   // Google
   { id: "gemini-2.0-flash", inputPer1k: 0.0001, outputPer1k: 0.0004, updatedAt: "2025-03-15" },