@opengsd/gsd-pi 1.8.1 → 1.9.0

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,14 +877,19 @@ 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++;
@@ -885,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 ?? '',
@@ -940,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)) {

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;
+  }
+}