@opengsd/gsd-pi 1.8.1 → 1.9.0-dev.5c1a3ff2

package/dist/resources/extensions/gsd/md-importer.js

@@ -5,9 +5,9 @@
 // Exports: parseDecisionsTable, parseRequirementsSections, migrateFromMarkdown
 import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';
 import { join, basename, dirname } from 'node:path';
-import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, transaction, updateMilestoneStatus, updateSliceStatus, _getAdapter, } from './gsd-db.js';
+import { upsertDecision, upsertRequirement, insertArtifact, insertMilestone, insertSlice, insertTask, transaction, updateMilestoneStatus, updateSliceStatus, getMilestoneSlices, getSliceTasks, _getAdapter, } from './gsd-db.js';
 import { openWorkflowDatabasePath } from './db-workspace.js';
-import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveTasksDir, legacyMilestonesDir, gsdRoot, resolveTaskFiles, resolveMilestonePath, } from './paths.js';
+import { resolveGsdRootFile, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveTasksDir, legacyMilestonesDir, gsdRoot, resolveTaskFiles, resolveTaskFile, resolveMilestonePath, } from './paths.js';
 import { findMilestoneIds } from './guided-flow.js';
 import { milestoneIdToPhaseNum } from './layout-policy.js';
 import { parseRoadmap, parsePlan } from './parsers-legacy.js';
@@ -16,6 +16,26 @@ import { logWarning } from './workflow-logger.js';
 // ─── DECISIONS.md Parser ───────────────────────────────────────────────────
 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) {
+    const ids = new Set();
+    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
@@ -539,11 +559,28 @@ function findFileByPrefixAndSuffix(dir, idPrefix, suffix) {
  * 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) {
+export function migrateHierarchyToDb(basePath, opts) {
     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
         const roadmapPath = resolveMilestoneFile(basePath, milestoneId, 'ROADMAP');
@@ -600,8 +637,29 @@ export function migrateHierarchyToDb(basePath) {
                 boundaryMapSection = nextHeading >= 0 ? afterBm.slice(0, nextHeading).trim() : afterBm.trim();
             }
         }
-        // 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();
+        const existingTaskStatus = new Map();
+        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,
@@ -615,10 +673,14 @@ export function migrateHierarchyToDb(basePath) {
         // 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++;
         // Parse roadmap for slices
@@ -635,11 +697,21 @@ export function migrateHierarchyToDb(basePath) {
                 const planContent = readFileSync(planPath, 'utf-8');
                 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,
@@ -650,10 +722,14 @@ export function migrateHierarchyToDb(basePath) {
                 },
             });
             // 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');
-                updateSliceStatus(milestoneId, sliceEntry.id, sliceStatus, importCompletionTimestamp(sliceSummary));
+                // #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.
@@ -686,8 +762,7 @@ export function migrateHierarchyToDb(basePath) {
                     legacyTasksDir = isLegacySlice
                         ? resolveTasksDir(basePath, milestoneId, sliceEntry.id)
                         : null;
-                    const summaryDir = legacyTasksDir ?? slicePath;
-                    taskSummaryFile = join(summaryDir, `${taskEntry.id}-SUMMARY.md`);
+                    taskSummaryFile = resolveTaskFile(basePath, milestoneId, sliceEntry.id, taskEntry.id, 'SUMMARY');
                 }
                 const hasTaskSummary = taskSummaryFile !== null && existsSync(taskSummaryFile);
                 // Pre-migration consistency (legacy tasks/ layout only): if a task is
@@ -707,9 +782,9 @@ export function migrateHierarchyToDb(basePath) {
                 // first execute-task. The surviving SUMMARY wins over a stale checkbox.
                 // reopen-task removes the SUMMARY, so this never re-completes an
                 // intentionally reopened task.
-                // Flat-phase summaries are phase-scoped (T01-SUMMARY.md); when a milestone
-                // has multiple slices, require the summary parent frontmatter to match so
-                // one slice's completion does not attest a sibling's same-named task.
+                // Flat-phase summaries are phase-scoped; when a milestone has multiple
+                // slices, require the summary parent frontmatter to match so one slice's
+                // completion does not attest a sibling's same-named task.
                 let summaryAttestsCompletion = hasTaskSummary;
                 if (summaryAttestsCompletion && !isLegacySlice && roadmap.slices.length > 1 && taskSummaryFile) {
                     try {
@@ -724,12 +799,19 @@ export function migrateHierarchyToDb(basePath) {
                     taskStatus = 'complete';
                     process.stderr.write(`gsd-migrate: ${milestoneId}/${sliceEntry.id}/${taskEntry.id} unchecked in plan but SUMMARY.md present — importing as complete (#1222)\n`);
                 }
+                // #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 ?? '',
@@ -779,9 +861,14 @@ export function migrateHierarchyToDb(basePath) {
                     // 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()) {
-                        updateSliceStatus(milestoneId, sliceEntry.id, 'complete', importCompletionTimestamp(sliceSummaryPath));
+                        // #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/dist/resources/extensions/gsd/migrate/command.js

@@ -8,129 +8,14 @@
  * After a successful write, offers a read-only review that audits the output
  * for gsd-pi standards compliance.
  */
-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 { 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, } from "./audit.js";
-import { assertMigrationHasSlices, assertMigrationTargetAvailable, prepareMigrationTarget, resolveMigrationPaths, restoreMigrationTarget, } from "./safety.js";
-function assertMigrationImportMatchesPreview(imported, preview) {
-    const mismatches = [];
-    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, preview) {
-    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, preview) {
-    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, targetRoot, project, preview, startedAt = new Date().toISOString()) {
-    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) {
-    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, gsdPath, preview) {
-    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. */
+import { executeMigrationWrite } from "./execution.js";
+import { createMigrationPlan } from "./plan.js";
+import { buildMigrationPreviewSummary, buildReviewPrompt } from "./presentation.js";
 function dispatchReview(pi, sourcePath, gsdPath, preview) {
-    const prompt = buildReviewPrompt(sourcePath, gsdPath, preview);
+    const prompt = buildReviewPrompt({ sourcePath, gsdPath, preview });
     pi.sendMessage({
         customType: "gsd-migrate-review",
         content: prompt,
@@ -138,60 +23,32 @@ function dispatchReview(pi, sourcePath, gsdPath, preview) {
     }, { triggerTurn: true });
 }
 export async function handleMigrate(args, ctx, pi) {
-    // ── Resolve source path ────────────────────────────────────────────────────
-    const { sourcePath, targetRoot } = resolveMigrationPaths(args);
-    if (!existsSync(sourcePath)) {
+    const plan = await createMigrationPlan(args);
+    const { sourcePath, targetRoot } = plan;
+    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.', "error");
+            "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");
         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.message, "error");
+    if (plan.status === "blocked") {
+        ctx.ui.notify(plan.message, "error");
         return;
     }
+    const { project, preview } = plan;
     // ── Build preview text ─────────────────────────────────────────────────────
-    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)`);
-    }
-    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.");
-    }
+    const lines = buildMigrationPreviewSummary(preview, targetRoot);
     // ── Confirmation via showNextAction ────────────────────────────────────────
     if (requiresInteractiveMenu(ctx, false)) {
         notifyMigrateNeedsInteractiveMenu(ctx, "migration confirmation needs an interactive menu");

package/dist/resources/extensions/gsd/migrate/execution.js

@@ -0,0 +1,98 @@
+// 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, } from "./audit.js";
+import { prepareMigrationTarget, restoreMigrationTarget, } from "./safety.js";
+import { writeGSDDirectory } from "./writer.js";
+function assertMigrationImportMatchesPreview(imported, preview) {
+    const mismatches = [];
+    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, preview) {
+    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, preview) {
+    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, targetRoot, project, preview, startedAt = new Date().toISOString()) {
+    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/dist/resources/extensions/gsd/migrate/plan.js

@@ -0,0 +1,49 @@
+// 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, } from "./safety.js";
+import { parsePlanningDirectory } from "./parser.js";
+import { generatePreview } from "./preview.js";
+import { transformToGSD } from "./transformer.js";
+import { validatePlanningDirectory } from "./validator.js";
+export function splitValidationIssues(validation) {
+    return {
+        warnings: validation.issues.filter((issue) => issue.severity === "warning"),
+        fatals: validation.issues.filter((issue) => issue.severity === "fatal"),
+    };
+}
+export async function createMigrationPlan(args, cwd = process.cwd()) {
+    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/dist/resources/extensions/gsd/migrate/planning-writer.js

@@ -143,14 +143,14 @@ export async function writePlanningDirectory(basePath, layout) {
                 done: isDone,
             });
             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++) {
@@ -174,19 +174,14 @@ export async function writePlanningDirectory(basePath, layout) {
             }
         }
     }
-    // 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 });
     }
     // Root files