gsd-pi 2.80.0-dev.96f4d89d5 → 2.80.0-dev.b2a374d5b

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

@@ -6,6 +6,7 @@
  * flow to show when entering a project directory.
  */
 
+import { execFileSync } from "node:child_process";
 import { existsSync, openSync, readSync, closeSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, parse as parsePath } from "node:path";
 import { homedir } from "node:os";
@@ -72,6 +73,22 @@ export interface ProjectSignals {
   verificationCommands: string[];
 }
 
+export type ProjectClassificationKind =
+  | "invalid-repo"
+  | "greenfield"
+  | "untyped-existing"
+  | "typed-existing";
+
+export interface ProjectClassification {
+  kind: ProjectClassificationKind;
+  signals: ProjectSignals;
+  trackedFiles: string[];
+  untrackedFiles: string[];
+  contentFiles: string[];
+  markers: string[];
+  reason: string;
+}
+
 // ─── Project File Markers ───────────────────────────────────────────────────────
 
 export const PROJECT_FILES = [
@@ -243,6 +260,7 @@ const TEST_MARKERS = [
 const RECURSIVE_SCAN_IGNORED_DIRS = new Set([
   ".git",
   ".gsd",
+  ".bg-shell",
   ".planning",
   ".plans",
   ".claude",
@@ -267,6 +285,8 @@ const RECURSIVE_SCAN_IGNORED_DIRS = new Set([
   "out",
 ]) as ReadonlySet<string>;
 
+const PROJECT_CONTENT_EXCLUDE_DIRS = RECURSIVE_SCAN_IGNORED_DIRS;
+
 /** Project file markers safe to detect recursively via suffix matching. */
 const ROOT_ONLY_PROJECT_FILES = new Set<string>([
   ".github/workflows",
@@ -536,6 +556,114 @@ export function detectProjectSignals(basePath: string): ProjectSignals {
   };
 }
 
+function normalizeGitPath(file: string): string {
+  return file.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+function isProjectContentFile(file: string): boolean {
+  const normalized = normalizeGitPath(file);
+  if (!normalized || normalized.endsWith("/")) return false;
+  if (normalized === ".gitignore" || normalized === ".gitattributes") return false;
+  const parts = normalized.split("/");
+  if (parts.some((part) => PROJECT_CONTENT_EXCLUDE_DIRS.has(part))) return false;
+  if (normalized.endsWith(".DS_Store")) return false;
+  return true;
+}
+
+function runGitLines(basePath: string, args: string[]): string[] {
+  try {
+    const output = execFileSync("git", args, {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "ignore"],
+      encoding: "utf-8",
+    }).trim();
+    return output ? output.split("\n").map((line) => line.trim()).filter(Boolean) : [];
+  } catch {
+    return [];
+  }
+}
+
+function listTrackedProjectFiles(basePath: string): string[] {
+  return runGitLines(basePath, ["ls-files"])
+    .map(normalizeGitPath)
+    .filter(isProjectContentFile);
+}
+
+function listUntrackedProjectFiles(basePath: string): string[] {
+  return runGitLines(basePath, ["ls-files", "--others", "--exclude-standard"])
+    .map(normalizeGitPath)
+    .filter(isProjectContentFile);
+}
+
+function hasKnownProjectMarkers(basePath: string, signals: ProjectSignals): boolean {
+  if (signals.detectedFiles.length > 0) return true;
+  if (signals.xcodePlatforms.length > 0) return true;
+  return false;
+}
+
+/**
+ * Classify repo presence separately from ecosystem/tooling markers.
+ *
+ * Known project files identify tooling. Git-tracked/non-ignored content
+ * identifies whether this is an existing project at all. This keeps small
+ * static or documentation repos from being mislabeled as greenfield.
+ */
+export function classifyProject(basePath: string): ProjectClassification {
+  const signals = detectProjectSignals(basePath);
+  const markers = [...signals.detectedFiles];
+
+  if (!signals.isGitRepo) {
+    return {
+      kind: "invalid-repo",
+      signals,
+      trackedFiles: [],
+      untrackedFiles: [],
+      contentFiles: [],
+      markers,
+      reason: "missing .git",
+    };
+  }
+
+  const trackedFiles = listTrackedProjectFiles(basePath);
+  const untrackedFiles = listUntrackedProjectFiles(basePath);
+  const contentFiles = [...new Set([...trackedFiles, ...untrackedFiles])];
+  const hasMarkers = hasKnownProjectMarkers(basePath, signals);
+
+  if (hasMarkers) {
+    return {
+      kind: "typed-existing",
+      signals,
+      trackedFiles,
+      untrackedFiles,
+      contentFiles,
+      markers,
+      reason: markers.length > 0 ? `detected markers: ${markers.join(", ")}` : "detected project structure",
+    };
+  }
+
+  if (contentFiles.length > 0) {
+    return {
+      kind: "untyped-existing",
+      signals,
+      trackedFiles,
+      untrackedFiles,
+      contentFiles,
+      markers,
+      reason: "project content exists but no recognized tooling markers were found",
+    };
+  }
+
+  return {
+    kind: "greenfield",
+    signals,
+    trackedFiles,
+    untrackedFiles,
+    contentFiles,
+    markers,
+    reason: "no tracked or non-ignored project content",
+  };
+}
+
 // ─── Xcode Platform Detection ───────────────────────────────────────────────────
 
 /** Known SDKROOT values → canonical platform names. */

package/src/resources/extensions/gsd/gsd-db.ts

@@ -77,6 +77,7 @@ import {
   applyMigrationV21StructuredMemories,
   applyMigrationV22QualityGateRepair,
   applyMigrationV23MilestoneQueue,
+  applyMigrationV26MilestoneCommitAttributions,
 } from "./db-migration-steps.js";
 import { isMemoriesFtsAvailableSchema, tryCreateMemoriesFtsSchema } from "./db-memory-fts-schema.js";
 import { createDbOpenState, type DbOpenPhase } from "./db-open-state.js";
@@ -105,7 +106,7 @@ const providerLoader = createSqliteProviderLoader({
   writeStderr: (message: string) => process.stderr.write(message),
 });
 
-export const SCHEMA_VERSION = 25;
+export const SCHEMA_VERSION = 26;
 
 function initSchema(db: DbAdapter, fileBacked: boolean): void {
   if (fileBacked) db.exec("PRAGMA journal_mode=WAL");
@@ -329,6 +330,11 @@ function migrateSchema(db: DbAdapter): void {
       recordSchemaVersion(db, 25);
     }
 
+    if (currentVersion < 26) {
+      applyMigrationV26MilestoneCommitAttributions(db);
+      recordSchemaVersion(db, 26);
+    }
+
     db.exec("COMMIT");
   } catch (err) {
     db.exec("ROLLBACK");
@@ -1349,6 +1355,45 @@ export function getSliceTasks(milestoneId: string, sliceId: string): TaskRow[] {
   return rows.map(rowToTask);
 }
 
+export function getCompletedMilestoneTaskFileHints(milestoneId: string): string[] {
+  if (!currentDb) return [];
+  const rows = currentDb.prepare(
+    `SELECT files, key_files
+     FROM tasks
+     WHERE milestone_id = :mid AND status IN ('complete', 'done')`,
+  ).all({ ":mid": milestoneId }) as Array<Record<string, unknown>>;
+
+  const hints = new Set<string>();
+  for (const row of rows) {
+    for (const raw of [row["files"], row["key_files"]]) {
+      for (const file of parseStringArrayColumn(raw)) {
+        const normalized = normalizeRepoPath(file);
+        if (normalized) hints.add(normalized);
+      }
+    }
+  }
+  return [...hints];
+}
+
+function parseStringArrayColumn(raw: unknown): string[] {
+  if (Array.isArray(raw)) return raw.filter((entry): entry is string => typeof entry === "string");
+  if (typeof raw !== "string") return [];
+  const trimmed = raw.trim();
+  if (!trimmed) return [];
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) return parsed.filter((entry): entry is string => typeof entry === "string");
+    if (typeof parsed === "string") return [parsed];
+  } catch {
+    return trimmed.split(",");
+  }
+  return [];
+}
+
+function normalizeRepoPath(file: string): string {
+  return file.trim().replace(/\\/g, "/").replace(/^\.\/+/, "");
+}
+
 // ─── ADR-011 Phase 2 escalation helpers ──────────────────────────────────
 
 /** Set pause-on-escalation state on a completed task. Mutually exclusive with awaiting_review. */
@@ -2073,6 +2118,9 @@ export function deleteMilestone(milestoneId: string): void {
     currentDb!.prepare(
       `DELETE FROM artifacts WHERE milestone_id = :mid`,
     ).run({ ":mid": milestoneId });
+    currentDb!.prepare(
+      `DELETE FROM milestone_commit_attributions WHERE milestone_id = :mid`,
+    ).run({ ":mid": milestoneId });
     currentDb!.prepare(
       `DELETE FROM milestone_leases WHERE milestone_id = :mid`,
     ).run({ ":mid": milestoneId });
@@ -2391,6 +2439,75 @@ export function upsertTurnGitTransaction(entry: {
   });
 }
 
+export function getMilestoneCommitAttributionShas(milestoneId: string): string[] {
+  if (!currentDb) return [];
+  const rows = currentDb.prepare(
+    `SELECT commit_sha
+     FROM milestone_commit_attributions
+     WHERE milestone_id = :mid
+     ORDER BY created_at, commit_sha`,
+  ).all({ ":mid": milestoneId }) as Array<Record<string, unknown>>;
+  return rows
+    .map((row) => typeof row["commit_sha"] === "string" ? row["commit_sha"] : "")
+    .filter(Boolean);
+}
+
+export function recordMilestoneCommitAttribution(entry: {
+  commitSha: string;
+  milestoneId: string;
+  sliceId?: string;
+  taskId?: string;
+  source: "recorded" | "backfill";
+  confidence: number;
+  files: string[];
+  createdAt: string;
+}): void {
+  if (!currentDb) return;
+  transaction(() => {
+    currentDb!.prepare(
+      `INSERT OR REPLACE INTO milestone_commit_attributions (
+        commit_sha, milestone_id, slice_id, task_id, source, confidence, files_json, created_at
+      ) VALUES (
+        :commit_sha, :milestone_id, :slice_id, :task_id, :source, :confidence, :files_json, :created_at
+      )`,
+    ).run({
+      ":commit_sha": entry.commitSha,
+      ":milestone_id": entry.milestoneId,
+      ":slice_id": entry.sliceId ?? null,
+      ":task_id": entry.taskId ?? null,
+      ":source": entry.source,
+      ":confidence": entry.confidence,
+      ":files_json": JSON.stringify(entry.files),
+      ":created_at": entry.createdAt,
+    });
+
+    currentDb!.prepare(
+      `INSERT OR IGNORE INTO audit_events (
+        event_id, trace_id, turn_id, caused_by, category, type, ts, payload_json
+      ) VALUES (
+        :event_id, :trace_id, :turn_id, :caused_by, :category, :type, :ts, :payload_json
+      )`,
+    ).run({
+      ":event_id": `milestone-commit-attribution:${entry.milestoneId}:${entry.commitSha}`,
+      ":trace_id": "milestone-commit-attribution",
+      ":turn_id": null,
+      ":caused_by": null,
+      ":category": "git",
+      ":type": "milestone-commit-attribution-recorded",
+      ":ts": entry.createdAt,
+      ":payload_json": JSON.stringify({
+        commitSha: entry.commitSha,
+        milestoneId: entry.milestoneId,
+        sliceId: entry.sliceId ?? null,
+        taskId: entry.taskId ?? null,
+        source: entry.source,
+        confidence: entry.confidence,
+        files: entry.files,
+      }),
+    });
+  });
+}
+
 export function insertAuditEvent(entry: {
   eventId: string;
   traceId: string;
@@ -2494,6 +2611,7 @@ export function clearEngineHierarchy(): void {
     currentDb!.exec("DELETE FROM slice_dependencies");
     currentDb!.exec("DELETE FROM assessments");
     currentDb!.exec("DELETE FROM replan_history");
+    currentDb!.exec("DELETE FROM milestone_commit_attributions");
     currentDb!.exec("DELETE FROM tasks");
     currentDb!.exec("DELETE FROM slices");
     currentDb!.exec("DELETE FROM milestone_leases");

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

@@ -30,7 +30,7 @@ import {
   formatInterruptedSessionRunningMessage,
   formatInterruptedSessionSummary,
 } from "./interrupted-session.js";
-import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
+import { listUnitRuntimeRecords, clearUnitRuntimeRecord, isInFlightRuntimePhase } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
 import { gsdHome } from "./gsd-home.js";
 import {
@@ -118,6 +118,22 @@ export function resolveExpectedArtifactPathForScope(
   return resolveExpectedArtifactPath(unitType, unitId, scope.workspace.projectRoot);
 }
 
+async function runQuickTaskChoice(ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {
+  if (!ctx.hasUI) {
+    ctx.ui.notify("Run /gsd quick <task> for small bounded work, or /gsd do <task> for natural-language routing.", "info");
+    return;
+  }
+
+  const task = (await ctx.ui.input("Quick task", "Describe the small task to run with /gsd quick"))?.trim();
+  if (!task) {
+    ctx.ui.notify("Quick task cancelled.", "info");
+    return;
+  }
+
+  const { handleQuick } = await import("./quick.js");
+  await handleQuick(task, ctx, pi);
+}
+
 /**
  * Scope-based overload of isGhostMilestone.
  * Binds basePath and milestoneId from the scope, ensuring path resolution
@@ -1786,8 +1802,8 @@ function selfHealRuntimeRecords(basePath: string, ctx: ExtensionContext): { clea
         cleared++;
         continue;
       }
-      // Clear records stuck in dispatched or timeout phase (process died mid-unit)
-      if (phase === "dispatched" || phase === "timeout") {
+      // Clear records stuck in an in-flight phase (process died mid-unit).
+      if (isInFlightRuntimePhase(phase)) {
         clearUnitRuntimeRecord(basePath, unitType, unitId);
         cleared++;
       }
@@ -2042,6 +2058,23 @@ export async function showSmartEntry(
     }
   }
 
+  if (interrupted.classification !== "recoverable") {
+    try {
+      const { autoImportMarkdownHierarchyIfDbMismatch } = await import("./migration-auto-check.js");
+      const result = await autoImportMarkdownHierarchyIfDbMismatch(basePath);
+      if (result.action === "imported") {
+        ctx.ui.notify(
+          `Recovered migrated planning state into gsd.db (${result.reason}): ${result.afterDb.milestones} milestone(s), ${result.afterDb.slices} slice(s), ${result.afterDb.tasks} task(s).`,
+          "info",
+        );
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      ctx.ui.notify(`GSD could not auto-import existing planning state into gsd.db: ${message}`, "warning");
+      logWarning("guided", `planning state auto-import failed: ${message}`, { file: "guided-flow.ts" });
+    }
+  }
+
   // Always derive from the project root — the assessment may have derived
   // state from a worktree path that was cleaned up in the stale branch above.
   const state = await deriveState(basePath);
@@ -2064,8 +2097,8 @@ export async function showSmartEntry(
   // standard wizard below.
   {
     const prefs = loadEffectiveGSDPreferences(basePath)?.preferences;
-    const { hasPendingDeepStage } = await import("./auto-dispatch.js");
-    if (hasPendingDeepStage(prefs, basePath)) {
+    const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
+    if (shouldRunDeepProjectSetup(state, prefs, basePath)) {
       await startDeepProjectSetupForeground(ctx, pi, basePath, stepMode);
       return;
     }
@@ -2134,17 +2167,24 @@ export async function showSmartEntry(
         title: "GSD — Get Shit Done",
         summary: ["No active milestone."],
         actions: [
+          {
+            id: "quick_task",
+            label: "Quick task",
+            description: "For small bounded work, run /gsd quick <task> or /gsd do <task>.",
+            recommended: true,
+          },
           {
             id: "new_milestone",
             label: "Create next milestone",
-            description: "Define what to build next.",
-            recommended: true,
+            description: "Define a larger body of work with planning artifacts.",
           },
         ],
         notYetMessage: "Run /gsd when ready.",
       });
 
-      if (choice === "new_milestone") {
+      if (choice === "quick_task") {
+        await runQuickTaskChoice(ctx, pi);
+      } else if (choice === "new_milestone") {
         setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId: nextId, step: stepMode });
         await dispatchWorkflow(pi, await prepareAndBuildDiscussPrompt(ctx, pi, nextId,
           `New milestone ${nextId}.`,
@@ -2181,11 +2221,16 @@ export async function showSmartEntry(
       title: `GSD — ${milestoneId}: ${milestoneTitle}`,
       summary: ["All milestones complete."],
       actions: [
+        {
+          id: "quick_task",
+          label: "Quick task",
+          description: "Do a small bounded task without opening a milestone.",
+          recommended: true,
+        },
         {
           id: "new_milestone",
           label: "Start new milestone",
           description: "Define and plan the next milestone.",
-          recommended: true,
         },
         {
           id: "status",
@@ -2196,7 +2241,9 @@ export async function showSmartEntry(
       notYetMessage: "Run /gsd when ready.",
     });
 
-    if (choice === "new_milestone") {
+    if (choice === "quick_task") {
+      await runQuickTaskChoice(ctx, pi);
+    } else if (choice === "new_milestone") {
       const milestoneIds = findMilestoneIds(basePath);
       const uniqueMilestoneIds = !!loadEffectiveGSDPreferences()?.preferences?.unique_milestone_ids;
       const nextId = nextMilestoneIdReserved(milestoneIds, uniqueMilestoneIds, basePath);
@@ -2300,13 +2347,18 @@ export async function showSmartEntry(
       const hasContext = !!(contextFile && await loadFile(contextFile));
 
       const actions = [
+        {
+          id: "quick_task",
+          label: "Quick task instead",
+          description: "Use this when the work is small and should not become a milestone.",
+          recommended: true,
+        },
         {
           id: "plan",
           label: "Create roadmap",
           description: hasContext
             ? "Context captured. Decompose into slices with a boundary map."
             : "Decompose the milestone into slices with a boundary map.",
-          recommended: true,
         },
         ...(!hasContext ? [{
           id: "discuss",
@@ -2332,7 +2384,9 @@ export async function showSmartEntry(
         notYetMessage: "Run /gsd when ready.",
       });
 
-      if (choice === "plan") {
+      if (choice === "quick_task") {
+        await runQuickTaskChoice(ctx, pi);
+      } else if (choice === "plan") {
         setPendingAutoStart(basePath, { ctx, pi, basePath, milestoneId, step: stepMode });
         await dispatchWorkflow(
           pi,

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

@@ -25,6 +25,50 @@ import {
 
 import type { MigrationPreview } from "./writer.js";
 import { homedir } from "node:os";
+import { ensureDbOpen } from "../bootstrap/dynamic-tools.js";
+import { clearEngineHierarchy, transaction } from "../gsd-db.js";
+import { migrateFromMarkdown } from "../md-importer.js";
+import { invalidateStateCache } from "../state.js";
+
+export type MigrationImportCounts = ReturnType<typeof migrateFromMarkdown>;
+
+function assertMigrationImportMatchesPreview(imported: MigrationImportCounts, preview: MigrationPreview): void {
+  const mismatches: string[] = [];
+  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();
+    const imported = migrateFromMarkdown(basePath);
+    if (preview) assertMigrationImportMatchesPreview(imported, preview);
+    return imported;
+  });
+  invalidateStateCache();
+  return counts;
+}
 
 /** Format preview stats for embedding in the review prompt. */
 function formatPreviewStats(preview: MigrationPreview): string {
@@ -182,9 +226,10 @@ export async function handleMigrate(
 
   const result = await writeGSDDirectory(project, process.cwd());
   const gsdPath = gsdRoot(process.cwd());
+  const imported = await importWrittenMigrationToDb(process.cwd(), preview);
 
   ctx.ui.notify(
-    `✓ Migration complete — ${result.paths.length} file(s) written to .gsd/`,
+    `✓ Migration complete — ${result.paths.length} file(s) written to .gsd/ and ${imported.hierarchy.milestones}M/${imported.hierarchy.slices}S/${imported.hierarchy.tasks}T imported to the database`,
     "info",
   );
 
@@ -193,6 +238,7 @@ export async function handleMigrate(
     title: "Migration written",
     summary: [
       `${result.paths.length} files written to .gsd/`,
+      `${imported.hierarchy.milestones} milestone(s), ${imported.hierarchy.slices} slice(s), and ${imported.hierarchy.tasks} task(s) imported to gsd.db`,
       "",
       "The agent can now review the migrated output against GSD-2 standards —",
       "checking structure, content quality, deriveState() round-trip, and",

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -0,0 +1,129 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+
+import { ensureDbOpen } from "./bootstrap/dynamic-tools.js";
+import {
+  clearEngineHierarchy,
+  getAllMilestones,
+  getMilestoneSlices,
+  getSliceTasks,
+  isDbAvailable,
+  transaction,
+} from "./gsd-db.js";
+import { migrateHierarchyToDb } from "./md-importer.js";
+import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
+import {
+  milestonesDir,
+  resolveMilestoneFile,
+  resolveSliceFile,
+} from "./paths.js";
+import { invalidateStateCache } from "./state.js";
+
+export interface HierarchyCounts {
+  milestones: number;
+  slices: number;
+  tasks: number;
+}
+
+export interface MigrationAutoCheckResult {
+  action: "none" | "imported";
+  reason: "no-markdown" | "in-sync" | "db-empty" | "count-mismatch";
+  markdown: HierarchyCounts;
+  beforeDb: HierarchyCounts;
+  afterDb: HierarchyCounts;
+}
+
+function zeroCounts(): HierarchyCounts {
+  return { milestones: 0, slices: 0, tasks: 0 };
+}
+
+function sameCounts(a: HierarchyCounts, b: HierarchyCounts): boolean {
+  return a.milestones === b.milestones && a.slices === b.slices && a.tasks === b.tasks;
+}
+
+export function countMarkdownHierarchy(basePath: string): HierarchyCounts {
+  const root = milestonesDir(basePath);
+  if (!existsSync(root)) return zeroCounts();
+
+  const counts = zeroCounts();
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !/^M\d+/.test(entry.name)) continue;
+    counts.milestones++;
+
+    const roadmapPath = resolveMilestoneFile(basePath, entry.name, "ROADMAP");
+    if (!roadmapPath || !existsSync(roadmapPath)) continue;
+
+    const roadmap = parseRoadmap(readFileSync(roadmapPath, "utf-8"));
+    counts.slices += roadmap.slices.length;
+
+    for (const slice of roadmap.slices) {
+      const planPath = resolveSliceFile(basePath, entry.name, slice.id, "PLAN");
+      if (!planPath || !existsSync(planPath)) continue;
+      const plan = parsePlan(readFileSync(planPath, "utf-8"));
+      counts.tasks += plan.tasks.length;
+    }
+  }
+
+  return counts;
+}
+
+export function countDbHierarchy(): HierarchyCounts {
+  if (!isDbAvailable()) return zeroCounts();
+  const counts = zeroCounts();
+  const milestones = getAllMilestones();
+  counts.milestones = milestones.length;
+
+  for (const milestone of milestones) {
+    const slices = getMilestoneSlices(milestone.id);
+    counts.slices += slices.length;
+    for (const slice of slices) {
+      counts.tasks += getSliceTasks(milestone.id, slice.id).length;
+    }
+  }
+
+  return counts;
+}
+
+export async function autoImportMarkdownHierarchyIfDbMismatch(
+  basePath: string,
+): Promise<MigrationAutoCheckResult> {
+  const markdown = countMarkdownHierarchy(basePath);
+  if (sameCounts(markdown, zeroCounts())) {
+    return {
+      action: "none",
+      reason: "no-markdown",
+      markdown,
+      beforeDb: zeroCounts(),
+      afterDb: zeroCounts(),
+    };
+  }
+
+  const opened = await ensureDbOpen(basePath);
+  if (!opened || !isDbAvailable()) {
+    throw new Error(`failed to open or create the GSD database at ${basePath}`);
+  }
+
+  const beforeDb = countDbHierarchy();
+  if (sameCounts(markdown, beforeDb)) {
+    return { action: "none", reason: "in-sync", markdown, beforeDb, afterDb: beforeDb };
+  }
+
+  const reason = sameCounts(beforeDb, zeroCounts()) ? "db-empty" : "count-mismatch";
+  const imported = transaction(() => {
+    clearEngineHierarchy();
+    return migrateHierarchyToDb(basePath);
+  });
+  invalidateStateCache();
+
+  const afterDb = {
+    milestones: imported.milestones,
+    slices: imported.slices,
+    tasks: imported.tasks,
+  };
+  if (!sameCounts(markdown, afterDb)) {
+    throw new Error(
+      `migration auto-import verification failed: markdown ${markdown.milestones}M/${markdown.slices}S/${markdown.tasks}T, db ${afterDb.milestones}M/${afterDb.slices}S/${afterDb.tasks}T`,
+    );
+  }
+
+  return { action: "imported", reason, markdown, beforeDb, afterDb };
+}