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

package/src/resources/extensions/gsd/guided-flow.ts

@@ -864,6 +864,13 @@ export function getDiscussableFutureMilestones<T extends { id: string; status: s
   );
 }
 
+function findDiscussTargetMilestone(
+  registry: GSDState["registry"],
+  milestoneId: string,
+): GSDState["registry"][number] | undefined {
+  return registry.find((m) => m.id === milestoneId || m.id.startsWith(`${milestoneId}-`));
+}
+
 function getStructuredQuestionsAvailability(
   pi: ExtensionAPI,
   ctx: ExtensionContext | undefined,
@@ -1333,12 +1340,23 @@ export async function showDiscuss(
     if (slash > 0) {
       const mid = target.slice(0, slash);
       const sid = target.slice(slash + 1);
-      const targetMilestone = state.registry.find((m) => m.id === mid);
-      if (!targetMilestone || targetMilestone.status === "complete" || targetMilestone.status === "parked") {
-        ctx.ui.notify(`Milestone ${mid} is not discussable.`, "warning");
+      const targetMilestone = findDiscussTargetMilestone(state.registry, mid);
+      if (!targetMilestone) {
+        ctx.ui.notify(
+          `Milestone ${mid} was not found in the roadmap. Use /gsd new-milestone to add it, or /gsd status to see available milestones.`,
+          "warning",
+        );
+        return;
+      }
+      if (targetMilestone.status === "complete") {
+        ctx.ui.notify(`Milestone ${targetMilestone.id} is already complete.`, "info");
         return;
       }
-      const slices = await loadDiscussNormSlices(basePath, mid);
+      if (targetMilestone.status === "parked") {
+        ctx.ui.notify(`Milestone ${targetMilestone.id} is parked. Run /gsd unpark ${targetMilestone.id} to reactivate.`, "warning");
+        return;
+      }
+      const slices = await loadDiscussNormSlices(basePath, targetMilestone.id);
       const chosen = slices.find((s) => s.id.toUpperCase() === sid.toUpperCase());
       if (!chosen) {
         ctx.ui.notify(`Slice ${target} was not found in discussable slices.`, "warning");
@@ -1348,10 +1366,10 @@ export async function showDiscuss(
         ctx.ui.notify(`Slice ${target} is already complete; nothing to discuss.`, "info");
         return;
       }
-      const discussBasePath = resolveDiscussSliceBasePath(basePath, mid);
-      const contextFile = resolveSliceFile(discussBasePath, mid, sid, "CONTEXT");
+      const discussBasePath = resolveDiscussSliceBasePath(basePath, targetMilestone.id);
+      const contextFile = resolveSliceFile(discussBasePath, targetMilestone.id, sid, "CONTEXT");
       const sqAvail = getStructuredQuestionsAvailability(pi, ctx);
-      const prompt = await buildDiscussSlicePrompt(mid, sid, chosen.title, discussBasePath, {
+      const prompt = await buildDiscussSlicePrompt(targetMilestone.id, sid, chosen.title, discussBasePath, {
         rediscuss: !!contextFile,
         structuredQuestionsAvailable: sqAvail,
       });
@@ -1359,9 +1377,20 @@ export async function showDiscuss(
       return;
     }
 
-    const targetMilestone = state.registry.find((m) => m.id === target);
-    if (!targetMilestone || targetMilestone.status === "complete" || targetMilestone.status === "parked") {
-      ctx.ui.notify(`Milestone ${target} is not discussable.`, "warning");
+    const targetMilestone = findDiscussTargetMilestone(state.registry, target);
+    if (!targetMilestone) {
+      ctx.ui.notify(
+        `Milestone ${target} was not found in the roadmap. Use /gsd new-milestone to add it, or /gsd status to see available milestones.`,
+        "warning",
+      );
+      return;
+    }
+    if (targetMilestone.status === "complete") {
+      ctx.ui.notify(`Milestone ${targetMilestone.id} is already complete.`, "info");
+      return;
+    }
+    if (targetMilestone.status === "parked") {
+      ctx.ui.notify(`Milestone ${targetMilestone.id} is parked. Run /gsd unpark ${targetMilestone.id} to reactivate.`, "warning");
       return;
     }
     await dispatchDiscussForMilestone(ctx, pi, basePath, targetMilestone.id, targetMilestone.title, {});

package/src/resources/extensions/gsd/markdown-renderer.ts

@@ -1208,6 +1208,21 @@ export interface AssessmentData {
   completedSliceId?: string;
 }
 
+function existingLegacySliceAssessmentPath(
+  basePath: string,
+  milestoneId: string,
+  sliceId: string,
+): string | null {
+  if (!isLegacyMilestonesLayout(basePath)) return null;
+  const legacyBase = legacyMilestonesDir(basePath);
+  const milestoneDirName = resolveDir(legacyBase, milestoneId);
+  if (!milestoneDirName) return null;
+  const slicesDir = join(legacyBase, milestoneDirName, "slices");
+  const sliceDirName = resolveDir(slicesDir, sliceId);
+  if (!sliceDirName) return null;
+  return join(slicesDir, sliceDirName, `${sliceId}-ASSESSMENT.md`);
+}
+
 export async function renderReplanFromDb(
   basePath: string,
   milestoneId: string,
@@ -1258,13 +1273,14 @@ export async function renderAssessmentFromDb(
   sliceId: string,
   assessmentData: AssessmentData,
 ): Promise<{ assessmentPath: string; content: string }> {
-  const absPath = targetSliceFile(
-    basePath,
-    milestoneId,
-    sliceId,
-    "ASSESSMENT",
-    getMilestone(milestoneId)?.title,
-  );
+  const absPath = existingLegacySliceAssessmentPath(basePath, milestoneId, sliceId)
+    ?? targetSliceFile(
+      basePath,
+      milestoneId,
+      sliceId,
+      "ASSESSMENT",
+      getMilestone(milestoneId)?.title,
+    );
   mkdirSync(dirname(absPath), { recursive: true });
   const artifactPath = toArtifactPath(absPath, basePath);
 

package/src/resources/extensions/gsd/md-importer.ts

@@ -17,6 +17,8 @@ import {
   transaction,
   updateMilestoneStatus,
   updateSliceStatus,
+  getMilestoneSlices,
+  getSliceTasks,
   _getAdapter,
 } from './gsd-db.js';
 import { openWorkflowDatabasePath } from './db-workspace.js';
@@ -43,6 +45,26 @@ const VALID_MADE_BY = new Set(['human', 'agent', 'collaborative']);
 
 const IMPORT_COMPLETE_STATUSES = new Set(['complete', 'done']);
 
+/**
+ * Derive the set of milestone ids a projection entry's `entities` touch. Marker
+ * entity ids are fully-qualified DB ids (`M001`, `M001/S01`, `M001/S01/T01`), so
+ * the milestone id is always the first `/`-segment — independent of the on-disk
+ * layout (legacy `milestones/<MID>/…` vs flat `phases/NN-slug/…`). The
+ * external-edit drift repairs (#027) feed this into
+ * `migrateHierarchyToDb(..., { statusAuthoritativeMilestones })` to scope status
+ * authority to exactly the milestone(s) a drifted file projects. Empty/blank
+ * entries are dropped, so an entity-less entry yields an empty set (repair then
+ * preserves DB status everywhere — fail toward the DB, not markdown).
+ */
+export function milestoneIdsFromEntities(entities: readonly string[]): Set<string> {
+  const ids = new Set<string>();
+  for (const e of entities) {
+    const milestoneId = e.split('/')[0];
+    if (milestoneId) ids.add(milestoneId);
+  }
+  return ids;
+}
+
 /**
  * Completion timestamp for an entity imported as complete: the SUMMARY.md mtime
  * when one exists (deterministic, matches the completion drift handler), else
@@ -676,15 +698,35 @@ function findFileByPrefixAndSuffix(dir: string, idPrefix: string, suffix: string
  * Uses INSERT OR IGNORE for idempotency. Insert order: milestones → slices → tasks.
  * Ghost milestones (dirs with no CONTEXT, ROADMAP, or SUMMARY) are skipped.
  *
+ * `opts.statusAuthoritativeMilestones` narrows *status* authority. It exists for
+ * the scoped external-edit drift repair: detection knows exactly which
+ * projection file drifted, but this import walks the whole tree. Without scoping,
+ * an unrelated file that is stale from gsd-pi's own miss (a forgotten render)
+ * rides along with markdown authority it was never granted and its stale checked
+ * checkbox silently reverts a reopened slice/milestone in the DB (#027).
+ *
+ * - opts absent → full markdown authority for every milestone (initial migration,
+ *   gsd-core full import, /gsd recover rebuild). Behavior is identical to before.
+ * - opts present → for a milestone NOT in the set whose DB row *already exists*,
+ *   the existing DB status is preserved: the slice upsert is fed the current DB
+ *   status (so a stale `complete` checkbox can't overwrite a reopened `pending`),
+ *   and the complete-status backfills are skipped. Milestone rows are already
+ *   protected by INSERT OR IGNORE. Rows that do not exist yet are inserted with
+ *   the parsed status regardless of scope (new content is new content).
+ *
  * Returns count of inserted hierarchy items.
  */
-export function migrateHierarchyToDb(basePath: string): {
+export function migrateHierarchyToDb(
+  basePath: string,
+  opts?: { statusAuthoritativeMilestones?: ReadonlySet<string> },
+): {
   milestones: number;
   slices: number;
   tasks: number;
 } {
   const counts = { milestones: 0, slices: 0, tasks: 0 };
   const milestoneIds = findMilestoneIds(basePath);
+  const statusScope = opts?.statusAuthoritativeMilestones;
 
   for (const milestoneId of milestoneIds) {
     // Check for ghost milestones — skip dirs with no meaningful content
@@ -745,8 +787,30 @@ export function migrateHierarchyToDb(basePath: string): {
       }
     }
 
-    // Insert milestone (FK parent — must come first)
-    insertMilestone({
+    // #027: when a status scope is supplied, a milestone outside it keeps DB
+    // status authority for rows that already exist — only the drifted file's
+    // milestone(s) may drive status closes from checkboxes. Absent scope, every
+    // milestone is authoritative (unchanged full-import behavior).
+    const milestoneStatusAuthoritative = !statusScope || statusScope.has(milestoneId);
+    // Snapshot existing slice statuses once (only needed when preserving DB
+    // authority for this milestone) so the upsert can echo them back instead of
+    // flipping an open slice closed from a stale checkbox.
+    const existingSliceStatus = new Map<string, string>();
+    const existingTaskStatus = new Map<string, string>();
+    if (!milestoneStatusAuthoritative) {
+      for (const s of getMilestoneSlices(milestoneId)) {
+        existingSliceStatus.set(s.id, s.status);
+        for (const t of getSliceTasks(milestoneId, s.id)) {
+          existingTaskStatus.set(`${s.id}/${t.id}`, t.status);
+        }
+      }
+    }
+
+    // Insert milestone (FK parent — must come first). INSERT OR IGNORE: an
+    // existing milestone row is never overwritten, so DB status is already
+    // preserved for out-of-scope milestones. `inserted` tells us whether this
+    // row is new (parsed status applies) vs pre-existing (backfill gated below).
+    const milestoneInserted = insertMilestone({
       id: milestoneId,
       title: milestoneTitle,
       status: milestoneStatus,
@@ -760,10 +824,14 @@ export function migrateHierarchyToDb(basePath: string): {
     // insertMilestone never sets completed_at; backfill it now for milestones
     // imported as complete so the DB is internally coherent immediately after
     // import (rather than relying on a later reconciliation pass that can't even
-    // see the drift when no SUMMARY file exists).
-    if (IMPORT_COMPLETE_STATUSES.has(milestoneStatus)) {
+    // see the drift when no SUMMARY file exists). #027: skip the backfill for an
+    // out-of-scope milestone that already existed — its DB status is authoritative.
+    if (IMPORT_COMPLETE_STATUSES.has(milestoneStatus) && (milestoneStatusAuthoritative || milestoneInserted)) {
       const summaryPath = resolveMilestoneFile(basePath, milestoneId, 'SUMMARY');
-      updateMilestoneStatus(milestoneId, milestoneStatus, importCompletionTimestamp(summaryPath));
+      // #1291: preserve an existing completion timestamp so a re-import backfills
+      // only rows that lack one, never re-stamping an already-complete milestone
+      // with the current import time. Same guard as the task path below.
+      updateMilestoneStatus(milestoneId, milestoneStatus, importCompletionTimestamp(summaryPath), true);
     }
     counts.milestones++;
 
@@ -783,11 +851,22 @@ export function migrateHierarchyToDb(basePath: string): {
         plan = parsePlan(planContent);
       }
 
+      // #027: for an out-of-scope milestone, echo the existing DB status of a
+      // slice that already exists so the upsert's `ELSE excluded.status` branch
+      // becomes a no-op instead of flipping a reopened `pending` slice back to
+      // `complete` from a stale checkbox. New slices (not yet in the DB) take the
+      // parsed status regardless of scope.
+      const sliceRowExists = existingSliceStatus.has(sliceEntry.id);
+      const sliceStatusAuthoritative = milestoneStatusAuthoritative || !sliceRowExists;
+      const effectiveSliceStatus = sliceStatusAuthoritative
+        ? sliceStatus
+        : existingSliceStatus.get(sliceEntry.id)!;
+
       insertSlice({
         id: sliceEntry.id,
         milestoneId: milestoneId,
         title: sliceEntry.title,
-        status: sliceStatus,
+        status: effectiveSliceStatus,
         risk: sliceEntry.risk,
         depends: (sliceEntry.depends ?? []).map(d => d.replace(/^\[|\]$/g, '')).filter(d => /^[A-Za-z0-9][A-Za-z0-9-]*$/.test(d)),
         demo: sliceEntry.demo,
@@ -798,20 +877,30 @@ export function migrateHierarchyToDb(basePath: string): {
         },
       });
       // insertSlice never sets completed_at; backfill it for slices imported as
-      // complete (same rationale as milestones above).
-      if (IMPORT_COMPLETE_STATUSES.has(sliceStatus)) {
+      // complete (same rationale as milestones above). #027: skip when preserving
+      // an out-of-scope slice's existing DB status.
+      if (IMPORT_COMPLETE_STATUSES.has(sliceStatus) && sliceStatusAuthoritative) {
         const sliceSummary = resolveSliceFile(basePath, milestoneId, sliceEntry.id, 'SUMMARY');
+        // #1291: preserve an existing completion timestamp so a re-import backfills
+        // only slices that lack one, never re-stamping an already-complete slice
+        // with the current import time. Same guard as the task path below.
         updateSliceStatus(
           milestoneId,
           sliceEntry.id,
           sliceStatus,
           importCompletionTimestamp(sliceSummary),
+          true,
         );
       }
       counts.slices++;
 
-      // Insert tasks from parsed plan
-      if (!plan) continue;
+      // Insert tasks from parsed plan.
+      // Sketch slices carry only a stub PLAN until refined; do not seed DB
+      // tasks from a placeholder <tasks> block (would falsely flip
+      // planning -> executing before the slice is decomposed). Once the
+      // `[sketch]` badge is removed by a real plan-slice, tasks import
+      // normally on the next pass. (#1286)
+      if (!plan || sliceEntry.isSketch) continue;
 
       for (const taskEntry of plan.tasks) {
         // Per K002: use 'complete' not 'done'
@@ -880,12 +969,20 @@ export function migrateHierarchyToDb(basePath: string): {
           );
         }
 
+        // #027: same scope guard as slices — out-of-scope milestones echo existing
+        // DB task status so stale plan checkboxes cannot re-complete reopened tasks.
+        const taskRowExists = existingTaskStatus.has(`${sliceEntry.id}/${taskEntry.id}`);
+        const taskStatusAuthoritative = milestoneStatusAuthoritative || !taskRowExists;
+        const effectiveTaskStatus = taskStatusAuthoritative
+          ? taskStatus
+          : existingTaskStatus.get(`${sliceEntry.id}/${taskEntry.id}`)!;
+
         insertTask({
           id: taskEntry.id,
           sliceId: sliceEntry.id,
           milestoneId: milestoneId,
           title: taskEntry.title,
-          status: taskStatus,
+          status: effectiveTaskStatus,
           planning: {
             files: taskEntry.files ?? [],
             verify: taskEntry.verify ?? '',
@@ -935,13 +1032,19 @@ export function migrateHierarchyToDb(basePath: string): {
           // checkbox (#1222); flat-phase checkboxes are authoritative without summary.
           return summaryAttestsCompletion || (t.done && !isLegacySliceLayout);
         });
-        if (allTasksDone && hasSliceSummary) {
+        // #027: the same close guard as the backfill above — a stale slice
+        // SUMMARY under an out-of-scope milestone must not upgrade a reopened
+        // slice to complete. New slices stay authoritative.
+        if (allTasksDone && hasSliceSummary && sliceStatusAuthoritative) {
           if (_getAdapter()) {
+            // #1291: preserve an existing completion timestamp — this consistency
+            // upgrade sets a completion time only when the row lacks one.
             updateSliceStatus(
               milestoneId,
               sliceEntry.id,
               'complete',
               importCompletionTimestamp(sliceSummaryPath),
+              true,
             );
             process.stderr.write(
               `gsd-migrate: ${milestoneId}/${sliceEntry.id} all tasks + slice summary complete — upgrading slice to complete\n`,

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)) {