gsd-pi 2.80.0-dev.8b3a59f5c → 2.80.0-dev.b2a374d5b

package/src/resources/extensions/gsd/crash-recovery.ts

@@ -38,6 +38,7 @@ import { _getAdapter, isDbAvailable } from "./gsd-db.js";
 import { gsdRoot, normalizeRealPath } from "./paths.js";
 import { atomicWriteSync } from "./atomic-write.js";
 import { effectiveLockFile } from "./session-lock.js";
+import { isInFlightRuntimePhase, listUnitRuntimeRecords, type AutoUnitRuntimeRecord } from "./unit-runtime.js";
 
 export interface LockData {
   pid: number;
@@ -103,10 +104,40 @@ function getLatestDispatchForWorker(workerId: string):
   return row ?? null;
 }
 
-function workerToLockData(worker: AutoWorkerRow): LockData {
+function latestInFlightRuntimeRecord(basePath: string): AutoUnitRuntimeRecord | null {
+  const records = listUnitRuntimeRecords(basePath).filter((record) =>
+    isInFlightRuntimePhase(record.phase),
+  );
+  if (records.length === 0) return null;
+  return records.sort((a, b) => {
+    const bTime = b.updatedAt || b.startedAt || 0;
+    const aTime = a.updatedAt || a.startedAt || 0;
+    return bTime - aTime;
+  })[0] ?? null;
+}
+
+function runtimeRecordToLockData(worker: AutoWorkerRow, record: AutoUnitRuntimeRecord, sessionFile?: string): LockData {
+  const startedAt = Number.isFinite(record.startedAt)
+    ? new Date(record.startedAt).toISOString()
+    : worker.started_at;
+  return {
+    pid: worker.pid,
+    startedAt: worker.started_at,
+    unitType: record.unitType,
+    unitId: record.unitId,
+    unitStartedAt: startedAt,
+    sessionFile,
+  };
+}
+
+function workerToLockData(basePath: string, worker: AutoWorkerRow): LockData {
   const dispatch = getLatestDispatchForWorker(worker.worker_id);
   const sessionFile =
     getRuntimeKv<string>("worker", worker.worker_id, SESSION_FILE_KV_KEY) ?? undefined;
+  if (!dispatch) {
+    const runtimeRecord = latestInFlightRuntimeRecord(basePath);
+    if (runtimeRecord) return runtimeRecordToLockData(worker, runtimeRecord, sessionFile);
+  }
   return {
     pid: worker.pid,
     startedAt: worker.started_at,
@@ -204,7 +235,7 @@ export function readCrashLock(basePath: string): LockData | null {
     try {
       const projectRoot = normalizeRealPath(basePath);
       const stale = findStaleWorkerForProject(projectRoot);
-      if (stale) return workerToLockData(stale);
+      if (stale) return workerToLockData(basePath, stale);
     } catch {
       // Fall through to the legacy lock-file compatibility path.
     }
@@ -260,25 +291,48 @@ export function formatCrashInfo(lock: LockData): string {
  */
 export function emitCrashRecoveredUnitEnd(basePath: string, lock: LockData): void {
   if (!lock.unitType || !lock.unitId || lock.unitType === "starting") return;
+  emitOpenUnitEndForUnit(basePath, lock.unitType, lock.unitId, "crash-recovered");
+}
 
+export function emitOpenUnitEndForUnit(
+  basePath: string,
+  unitType: string,
+  unitId: string,
+  status: string,
+  errorContext?: { message: string; category: string; stopReason?: string; isTransient?: boolean; retryAfterMs?: number },
+): boolean {
   try {
     const all = queryJournal(basePath);
 
     const starts = all.filter(
-      (e) => e.eventType === "unit-start" && e.data?.unitId === lock.unitId,
+      (e) =>
+        e.eventType === "unit-start" &&
+        e.data?.unitType === unitType &&
+        e.data?.unitId === unitId,
     );
-    if (starts.length === 0) return;
+    if (starts.length === 0) return false;
 
-    const lastStart = starts[starts.length - 1];
+    const lastStart = [...starts].reverse().find((start) => {
+      return !all.some(
+        (e) =>
+          e.eventType === "unit-end" &&
+          e.data?.unitType === unitType &&
+          e.data?.unitId === unitId &&
+          e.causedBy?.flowId === start.flowId &&
+          e.causedBy?.seq === start.seq,
+      );
+    });
+    if (!lastStart) return false;
 
     const alreadyClosed = all.some(
       (e) =>
         e.eventType === "unit-end" &&
-        e.data?.unitId === lock.unitId &&
+        e.data?.unitType === unitType &&
+        e.data?.unitId === unitId &&
         e.causedBy?.flowId === lastStart.flowId &&
         e.causedBy?.seq === lastStart.seq,
     );
-    if (alreadyClosed) return;
+    if (alreadyClosed) return false;
 
     const maxSeq = all
       .filter((e) => e.flowId === lastStart.flowId)
@@ -290,15 +344,18 @@ export function emitCrashRecoveredUnitEnd(basePath: string, lock: LockData): voi
       seq: maxSeq + 1,
       eventType: "unit-end",
       data: {
-        unitType: lock.unitType,
-        unitId: lock.unitId,
-        status: "crash-recovered",
+        unitType,
+        unitId,
+        status,
         artifactVerified: false,
+        ...(errorContext ? { errorContext } : {}),
       },
       causedBy: { flowId: lastStart.flowId, seq: lastStart.seq },
     });
+    return true;
   } catch {
     // Never throw from crash recovery path.
+    return false;
   }
 }
 

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

package/src/resources/extensions/gsd/planning-path-scope.ts

@@ -0,0 +1,35 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { normalizePlannedFileReference } from "./files.js";
+
+export interface PlanningPathScopeField {
+  field: string;
+  values: string[];
+}
+
+function isInsideBase(basePath: string, candidate: string): boolean {
+  const base = resolve(basePath);
+  const abs = resolve(candidate);
+  const rel = relative(base, abs);
+  return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * Planning IO fields are execution contracts. Absolute paths are only safe when
+ * they stay inside the active working directory; in worktree mode, an absolute
+ * path to the original checkout makes executors edit the wrong tree.
+ */
+export function validatePlanningPathScope(
+  basePath: string,
+  fields: PlanningPathScopeField[],
+): string | null {
+  for (const { field, values } of fields) {
+    for (const raw of values) {
+      const candidate = normalizePlannedFileReference(raw);
+      if (!isAbsolute(candidate)) continue;
+      if (isInsideBase(basePath, candidate)) continue;
+      return `${field} contains absolute path outside working directory: ${candidate}. Use a path relative to ${basePath}.`;
+    }
+  }
+
+  return null;
+}