gsd-pi 2.79.0 → 2.80.0-dev.0aaa4fc17

package/src/resources/extensions/gsd/tests/journal-integration.test.ts

@@ -399,6 +399,140 @@ test("runDispatch pauses when complete-milestone summary exists on disk but the
   assert.equal(stopCalls, 0, "mismatch pause should not hard-stop the loop");
 });
 
+test("runDispatch clears stuck state after Level 1 artifact recovery", async (t) => {
+  const capture = createEventCapture();
+  let invalidateCalls = 0;
+  let stopCalls = 0;
+  const base = join(tmpdir(), `gsd-stuck-plan-${randomUUID()}`);
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  const tasksDir = join(sliceDir, "tasks");
+  mkdirSync(tasksDir, { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending" });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "First task", status: "pending" });
+  writeFileSync(join(sliceDir, "S01-PLAN.md"), "# S01\n\n## Tasks\n\n- [ ] **T01: First task** `est:1h`\n");
+  writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n");
+
+  const deps = makeMockDeps(capture, {
+    invalidateAllCaches: () => { invalidateCalls++; },
+    stopAuto: async () => { stopCalls++; },
+    resolveDispatch: async () => ({
+      action: "dispatch" as const,
+      unitType: "plan-slice",
+      unitId: "M001/S01",
+      prompt: "plan the slice",
+      matchedRule: "planning → plan-slice",
+    }),
+  });
+  const ic = makeIC(deps, {
+    s: {
+      ...makeSession(),
+      basePath: base,
+      originalBasePath: base,
+    } as any,
+  });
+  const preData: PreDispatchData = {
+    state: {
+      phase: "planning",
+      activeMilestone: { id: "M001", title: "Test", status: "active" },
+      activeSlice: { id: "S01", title: "Slice" },
+      registry: [{ id: "M001", status: "active" }],
+      blockers: [],
+    } as any,
+    mid: "M001",
+    midTitle: "Test Milestone",
+  };
+  const loopState: LoopState = {
+    recentUnits: [
+      { key: "plan-slice/M001/S01" },
+      { key: "plan-slice/M001/S01" },
+    ],
+    stuckRecoveryAttempts: 0,
+    consecutiveFinalizeTimeouts: 0,
+  };
+
+  const result = await runDispatch(ic, preData, loopState);
+
+  assert.equal(result.action, "continue");
+  assert.equal(invalidateCalls, 1, "Level 1 artifact recovery should invalidate caches");
+  assert.equal(stopCalls, 0, "Level 1 artifact recovery should not hard-stop");
+  assert.deepEqual(loopState.recentUnits, [], "Level 1 artifact recovery should clear the stuck window");
+  assert.equal(loopState.stuckRecoveryAttempts, 0, "Level 1 artifact recovery should reset the recovery counter");
+});
+
+test("runDispatch escapes Level 2 stuck stop when artifact verifies after cache invalidation", async (t) => {
+  const capture = createEventCapture();
+  let invalidateCalls = 0;
+  let stopCalls = 0;
+  const base = join(tmpdir(), `gsd-stuck-plan-l2-${randomUUID()}`);
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  const tasksDir = join(sliceDir, "tasks");
+  mkdirSync(tasksDir, { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Slice", status: "pending" });
+  insertTask({ id: "T01", milestoneId: "M001", sliceId: "S01", title: "First task", status: "pending" });
+  writeFileSync(join(sliceDir, "S01-PLAN.md"), "# S01\n\n## Tasks\n\n- [ ] **T01: First task** `est:1h`\n");
+  writeFileSync(join(tasksDir, "T01-PLAN.md"), "# T01 Plan\n");
+
+  const deps = makeMockDeps(capture, {
+    invalidateAllCaches: () => { invalidateCalls++; },
+    stopAuto: async () => { stopCalls++; },
+    resolveDispatch: async () => ({
+      action: "dispatch" as const,
+      unitType: "plan-slice",
+      unitId: "M001/S01",
+      prompt: "plan the slice",
+      matchedRule: "planning → plan-slice",
+    }),
+  });
+  const ic = makeIC(deps, {
+    s: {
+      ...makeSession(),
+      basePath: base,
+      originalBasePath: base,
+    } as any,
+  });
+  const preData: PreDispatchData = {
+    state: {
+      phase: "planning",
+      activeMilestone: { id: "M001", title: "Test", status: "active" },
+      activeSlice: { id: "S01", title: "Slice" },
+      registry: [{ id: "M001", status: "active" }],
+      blockers: [],
+    } as any,
+    mid: "M001",
+    midTitle: "Test Milestone",
+  };
+  const loopState: LoopState = {
+    recentUnits: [
+      { key: "plan-slice/M001/S01" },
+      { key: "plan-slice/M001/S01" },
+    ],
+    stuckRecoveryAttempts: 1,
+    consecutiveFinalizeTimeouts: 0,
+  };
+
+  const result = await runDispatch(ic, preData, loopState);
+
+  assert.equal(result.action, "continue");
+  assert.equal(invalidateCalls, 1, "Level 2 escape should invalidate caches before rechecking artifacts");
+  assert.equal(stopCalls, 0, "verified artifacts should escape Level 2 hard stop");
+  assert.deepEqual(loopState.recentUnits, [], "Level 2 artifact escape should clear the stuck window");
+  assert.equal(loopState.stuckRecoveryAttempts, 0, "Level 2 artifact escape should reset the recovery counter");
+});
+
 test("runUnitPhase emits unit-start and unit-end with causedBy reference", async () => {
   const capture = createEventCapture();
 

package/src/resources/extensions/gsd/tests/legacy-component-format-telemetry.test.ts

@@ -0,0 +1,62 @@
+// Project/App: GSD-2
+// File Purpose: Verifies telemetry for legacy component formats.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { loadComponentFromAgentFile, loadComponentFromDir } from "../component-loader.js";
+import { getLegacyTelemetry, resetLegacyTelemetry } from "../legacy-telemetry.js";
+
+function makeTempDir(): string {
+  return mkdtempSync(join(tmpdir(), "gsd-legacy-component-format-"));
+}
+
+test("legacy component telemetry counts successful skill and agent format loads", () => {
+  const dir = makeTempDir();
+  try {
+    resetLegacyTelemetry();
+
+    const modernDir = join(dir, "modern-skill");
+    mkdirSync(modernDir, { recursive: true });
+    writeFileSync(join(modernDir, "component.yaml"), `
+apiVersion: gsd/v1
+kind: skill
+metadata:
+  name: modern-skill
+  description: "Modern skill"
+spec:
+  prompt: SKILL.md
+`, "utf-8");
+    writeFileSync(join(modernDir, "SKILL.md"), "Modern content.", "utf-8");
+    assert.ok(loadComponentFromDir(modernDir, "user").component);
+    assert.equal(getLegacyTelemetry()["legacy.componentFormatUsed"], 0);
+
+    const legacySkillDir = join(dir, "legacy-skill");
+    mkdirSync(legacySkillDir, { recursive: true });
+    writeFileSync(join(legacySkillDir, "SKILL.md"), `---
+name: legacy-skill
+description: Legacy skill
+---
+Skill content.
+`, "utf-8");
+    assert.ok(loadComponentFromDir(legacySkillDir, "user").component);
+    assert.equal(getLegacyTelemetry()["legacy.componentFormatUsed"], 1);
+
+    const legacyAgentFile = join(dir, "legacy-agent.md");
+    writeFileSync(legacyAgentFile, `---
+name: legacy-agent
+description: Legacy agent
+tools: read, grep
+---
+Agent content.
+`, "utf-8");
+    assert.ok(loadComponentFromAgentFile(legacyAgentFile, "user").component);
+    assert.equal(getLegacyTelemetry()["legacy.componentFormatUsed"], 2);
+  } finally {
+    resetLegacyTelemetry();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/legacy-telemetry.test.ts

@@ -0,0 +1,144 @@
+// Project/App: GSD-2
+// File Purpose: Tests for telemetry counters guarding legacy compatibility cleanup.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import {
+  getLegacyTelemetryReport,
+  getLegacyTelemetry,
+  incrementLegacyTelemetry,
+  listLegacyTelemetryCounters,
+  persistLegacyTelemetrySnapshot,
+  resetLegacyTelemetry,
+} from "../legacy-telemetry.ts";
+import { closeDatabase } from "../gsd-db.ts";
+import { deriveState, invalidateStateCache } from "../state.ts";
+import { _resetLogs, peekLogs, setStderrLoggingEnabled } from "../workflow-logger.ts";
+
+test("legacy telemetry exposes every Phase 8 cleanup counter", () => {
+  resetLegacyTelemetry();
+
+  assert.deepEqual(listLegacyTelemetryCounters(), [
+    "legacy.markdownFallbackUsed",
+    "legacy.workflowEngineUsed",
+    "legacy.uokFallbackUsed",
+    "legacy.mcpAliasUsed",
+    "legacy.componentFormatUsed",
+    "legacy.providerDefaultUsed",
+  ]);
+  assert.equal(getLegacyTelemetry()["legacy.markdownFallbackUsed"], 0);
+});
+
+test("legacy telemetry increments positive finite amounts only", () => {
+  resetLegacyTelemetry();
+
+  incrementLegacyTelemetry("legacy.workflowEngineUsed");
+  incrementLegacyTelemetry("legacy.workflowEngineUsed", 2);
+  incrementLegacyTelemetry("legacy.workflowEngineUsed", 0);
+  incrementLegacyTelemetry("legacy.workflowEngineUsed", Number.NaN);
+
+  assert.equal(getLegacyTelemetry()["legacy.workflowEngineUsed"], 3);
+});
+
+test("legacy telemetry emits one actionable diagnostic per counter", () => {
+  const previousStderr = setStderrLoggingEnabled(false);
+  try {
+    resetLegacyTelemetry();
+    _resetLogs();
+
+    incrementLegacyTelemetry("legacy.mcpAliasUsed");
+    incrementLegacyTelemetry("legacy.mcpAliasUsed");
+
+    const logs = peekLogs();
+    assert.equal(logs.length, 1);
+    assert.equal(logs[0]?.component, "migration");
+    assert.equal(logs[0]?.context?.counter, "legacy.mcpAliasUsed");
+    assert.match(logs[0]?.message ?? "", /canonical gsd_\* tool name/);
+  } finally {
+    _resetLogs();
+    resetLegacyTelemetry();
+    setStderrLoggingEnabled(previousStderr);
+  }
+});
+
+test("legacy telemetry can persist an opt-in snapshot file", () => {
+  const previousStderr = setStderrLoggingEnabled(false);
+  const previousOutput = process.env.GSD_LEGACY_TELEMETRY_FILE;
+  const base = mkdtempSync(join(tmpdir(), "gsd-legacy-telemetry-file-"));
+  const outputPath = join(base, "runtime", "legacy-telemetry.json");
+  try {
+    resetLegacyTelemetry();
+    _resetLogs();
+    process.env.GSD_LEGACY_TELEMETRY_FILE = outputPath;
+
+    incrementLegacyTelemetry("legacy.providerDefaultUsed", 2);
+
+    const report = JSON.parse(readFileSync(outputPath, "utf-8")) as ReturnType<typeof getLegacyTelemetryReport>;
+    assert.equal(typeof report.ts, "string");
+    assert.equal(report.counters["legacy.providerDefaultUsed"], 2);
+    assert.equal(report.counters["legacy.markdownFallbackUsed"], 0);
+  } finally {
+    if (previousOutput === undefined) delete process.env.GSD_LEGACY_TELEMETRY_FILE;
+    else process.env.GSD_LEGACY_TELEMETRY_FILE = previousOutput;
+    _resetLogs();
+    resetLegacyTelemetry();
+    setStderrLoggingEnabled(previousStderr);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("legacy telemetry can persist a zero-use snapshot for deletion gates", () => {
+  const previousOutput = process.env.GSD_LEGACY_TELEMETRY_FILE;
+  const base = mkdtempSync(join(tmpdir(), "gsd-legacy-zero-telemetry-"));
+  const outputPath = join(base, "legacy-telemetry.json");
+  try {
+    resetLegacyTelemetry();
+    process.env.GSD_LEGACY_TELEMETRY_FILE = outputPath;
+
+    persistLegacyTelemetrySnapshot();
+
+    const report = JSON.parse(readFileSync(outputPath, "utf-8")) as ReturnType<typeof getLegacyTelemetryReport>;
+    assert.equal(typeof report.ts, "string");
+    assert.deepEqual(report.counters, {
+      "legacy.markdownFallbackUsed": 0,
+      "legacy.workflowEngineUsed": 0,
+      "legacy.uokFallbackUsed": 0,
+      "legacy.mcpAliasUsed": 0,
+      "legacy.componentFormatUsed": 0,
+      "legacy.providerDefaultUsed": 0,
+    });
+  } finally {
+    if (previousOutput === undefined) delete process.env.GSD_LEGACY_TELEMETRY_FILE;
+    else process.env.GSD_LEGACY_TELEMETRY_FILE = previousOutput;
+    resetLegacyTelemetry();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("deriveState increments markdown fallback telemetry on explicit legacy fallback", async () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-legacy-telemetry-"));
+  const originalFallback = process.env.GSD_ALLOW_MARKDOWN_DERIVE_FALLBACK;
+  try {
+    closeDatabase();
+    resetLegacyTelemetry();
+    invalidateStateCache();
+    process.env.GSD_ALLOW_MARKDOWN_DERIVE_FALLBACK = "1";
+    mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+    writeFileSync(join(base, ".gsd", "milestones", "M001", "M001-CONTEXT.md"), "# M001: Legacy\n");
+
+    const state = await deriveState(base);
+
+    assert.equal(state.activeMilestone?.id, "M001");
+    assert.equal(getLegacyTelemetry()["legacy.markdownFallbackUsed"], 1);
+  } finally {
+    invalidateStateCache();
+    resetLegacyTelemetry();
+    if (originalFallback === undefined) delete process.env.GSD_ALLOW_MARKDOWN_DERIVE_FALLBACK;
+    else process.env.GSD_ALLOW_MARKDOWN_DERIVE_FALLBACK = originalFallback;
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/memory-pressure-stuck-state.test.ts

@@ -9,16 +9,36 @@ import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { decideMemoryPressure } from "../auto/workflow-kernel.ts";
+import { measureMemoryPressure } from "../auto/workflow-memory-pressure.ts";
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const loopSource = readFileSync(join(__dirname, "..", "auto", "loop.ts"), "utf-8");
 
 describe("memory pressure monitoring (#3331)", () => {
-  test("checkMemoryPressure function exists", () => {
-    assert.match(loopSource, /function checkMemoryPressure/);
+  test("measureMemoryPressure reports pressure above threshold", () => {
+    const snapshot = measureMemoryPressure({
+      threshold: 0.5,
+      deps: {
+        memoryUsage: () => ({ heapUsed: 768 * 1024 * 1024 }),
+        heapLimitBytes: () => 1024 * 1024 * 1024,
+      },
+    });
+
+    assert.equal(snapshot.pressured, true);
+    assert.equal(snapshot.heapMB, 768);
+    assert.equal(snapshot.limitMB, 1024);
   });
 
-  test("MEMORY_PRESSURE_THRESHOLD constant is defined", () => {
-    assert.match(loopSource, /MEMORY_PRESSURE_THRESHOLD\s*=\s*0\.\d+/);
+  test("measureMemoryPressure defaults to a sub-100-percent threshold", () => {
+    const snapshot = measureMemoryPressure({
+      deps: {
+        memoryUsage: () => ({ heapUsed: 3584 * 1024 * 1024 }),
+        heapLimitBytes: () => 4096 * 1024 * 1024,
+      },
+    });
+
+    assert.equal(snapshot.pressured, true);
   });
 
   test("memory check runs every MEMORY_CHECK_INTERVAL iterations", () => {
@@ -26,8 +46,16 @@ describe("memory pressure monitoring (#3331)", () => {
   });
 
   test("memory pressure triggers graceful stopAuto", () => {
-    assert.match(loopSource, /mem\.pressured/);
-    assert.match(loopSource, /Stopping gracefully to prevent OOM/);
+    const decision = decideMemoryPressure({
+      pressured: true,
+      heapMB: 3900,
+      limitMB: 4096,
+      pct: 0.95,
+      iteration: 10,
+    });
+
+    assert.equal(decision.action, "stop");
+    assert.match(decision.stopMessage, /Stopping gracefully to prevent OOM/);
   });
 });
 
@@ -55,15 +83,11 @@ describe("stuck detection persistence (#3704)", () => {
   // unit_dispatches (recentUnits) + runtime_kv (stuckRecoveryAttempts).
   // The stuck-state-via-db.test.ts suite covers the round-trip.
 
-  test("saveStuckState called in standard dev path as well as custom engine path (#4382)", () => {
-    // Count all call-sites of saveStuckState (excluding the function definition itself).
-    // After the fix, both the custom-engine path and the standard dev path must each
-    // call saveStuckState so stuckRecoveryAttempts survives session restarts.
-    const callMatches = loopSource.match(/saveStuckState\(s,\s*loopState\)/g) ?? [];
-    assert.ok(
-      callMatches.length >= 2,
-      `saveStuckState must be called in both the custom-engine path and the standard dev path ` +
-      `(found ${callMatches.length} call(s) — standard path is missing its call, #4382)`,
-    );
+  test("completeIteration centralizes stuck-state persistence for both loop paths (#4382)", () => {
+    assert.match(loopSource, /const completeIteration = \(\): void =>/);
+    assert.match(loopSource, /completeWorkflowIteration\(/);
+    assert.match(loopSource, /saveStuckState:\s*\(\)\s*=>\s*saveStuckState\(s,\s*loopState\)/);
+    assert.match(loopSource, /completeIteration,/);
+    assert.match(loopSource, /completeIteration\(\);/);
   });
 });

package/src/resources/extensions/gsd/tests/migrate-writer-integration.test.ts

@@ -13,6 +13,9 @@ import { parseRoadmap, parsePlan } from '../parsers-legacy.ts';
 import { parseSummary } from '../files.ts';
 import { deriveState } from '../state.ts';
 import { invalidateAllCaches } from '../cache.ts';
+import { ensureDbOpen } from '../bootstrap/dynamic-tools.ts';
+import { closeDatabase, getAllMilestones } from '../gsd-db.ts';
+import { importWrittenMigrationToDb } from '../migrate/command.ts';
 import type {
   GSDProject,
   GSDMilestone,
@@ -250,6 +253,51 @@ test('Scenario 1: Incomplete project — write, parse, deriveState', async () =>
     }
 });
 
+test('Scenario 1b: written migration imports into authoritative DB state', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-writer-db-import-'));
+    try {
+      const project = buildIncompleteProject();
+      await writeGSDDirectory(project, base);
+
+      assert.equal(await ensureDbOpen(base), true, 'db import: ensureDbOpen creates authoritative DB');
+
+      invalidateAllCaches();
+      const before = await deriveState(base);
+      assert.equal(before.activeMilestone, null, 'db import: markdown-only migration is invisible before DB import');
+
+      const imported = await importWrittenMigrationToDb(base);
+      assert.deepStrictEqual(imported.hierarchy, { milestones: 1, slices: 2, tasks: 3 }, 'db import: hierarchy counts');
+
+      invalidateAllCaches();
+      const after = await deriveState(base);
+      assert.deepStrictEqual(after.phase, 'executing', 'db import: deriveState sees imported DB hierarchy');
+      assert.deepStrictEqual(after.activeMilestone?.id, 'M001', 'db import: active milestone');
+      assert.deepStrictEqual(after.activeSlice?.id, 'S02', 'db import: active slice');
+      assert.deepStrictEqual(after.activeTask?.id, 'T03', 'db import: active task');
+    } finally {
+      closeDatabase();
+      rmSync(base, { recursive: true, force: true });
+    }
+});
+
+test('Scenario 1c: DB import verification fails when preview counts do not match', async () => {
+    const base = mkdtempSync(join(tmpdir(), 'gsd-writer-db-check-'));
+    try {
+      const project = buildIncompleteProject();
+      await writeGSDDirectory(project, base);
+
+      const preview = generatePreview(project);
+      await assert.rejects(
+        () => importWrittenMigrationToDb(base, { ...preview, totalTasks: preview.totalTasks + 1 }),
+        /migration DB import verification failed: tasks 3\/4/,
+      );
+      assert.deepStrictEqual(getAllMilestones(), [], 'db import: failed verification rolls back hierarchy rewrite');
+    } finally {
+      closeDatabase();
+      rmSync(base, { recursive: true, force: true });
+    }
+});
+
   // ─── Scenario 2: Fully complete project ────────────────────────────────
 
 test('Scenario 2: Fully complete project — deriveState phase', async () => {

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

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+
+import { ensureDbOpen } from "../bootstrap/dynamic-tools.ts";
+import {
+  _getAdapter,
+  closeDatabase,
+  getAllMilestones,
+  getSliceTasks,
+} from "../gsd-db.ts";
+import {
+  autoImportMarkdownHierarchyIfDbMismatch,
+  countMarkdownHierarchy,
+} from "../migration-auto-check.ts";
+import { writeGSDDirectory } from "../migrate/writer.ts";
+import type { GSDProject } from "../migrate/types.ts";
+
+function makeBase(): string {
+  return mkdtempSync(join(tmpdir(), "gsd-migration-auto-check-"));
+}
+
+function cleanup(base: string): void {
+  closeDatabase();
+  rmSync(base, { recursive: true, force: true });
+}
+
+function projectFixture(): GSDProject {
+  return {
+    projectContent: "# Legacy Project\n",
+    decisionsContent: "",
+    requirements: [],
+    milestones: [
+      {
+        id: "M001",
+        title: "Legacy Milestone",
+        vision: "Carry forward previous work",
+        successCriteria: ["Existing task is visible"],
+        research: null,
+        boundaryMap: [],
+        slices: [
+          {
+            id: "S01",
+            title: "Legacy Slice",
+            risk: "medium",
+            depends: [],
+            done: false,
+            demo: "Legacy slice demo",
+            goal: "Legacy slice demo",
+            research: null,
+            summary: null,
+            tasks: [
+              {
+                id: "T01",
+                title: "Legacy Task",
+                description: "Task carried from markdown",
+                done: false,
+                estimate: "",
+                files: ["src/index.ts"],
+                mustHaves: [],
+                summary: null,
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+test("migration auto-check imports markdown hierarchy when DB is empty", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory(projectFixture(), base);
+    assert.deepEqual(countMarkdownHierarchy(base), { milestones: 1, slices: 1, tasks: 1 });
+
+    assert.equal(await ensureDbOpen(base), true);
+    assert.equal(getAllMilestones().length, 0, "fresh authoritative DB starts empty");
+
+    const result = await autoImportMarkdownHierarchyIfDbMismatch(base);
+    assert.equal(result.action, "imported");
+    assert.equal(result.reason, "db-empty");
+    assert.deepEqual(result.afterDb, { milestones: 1, slices: 1, tasks: 1 });
+    assert.equal(getAllMilestones().length, 1);
+    assert.equal(getSliceTasks("M001", "S01").length, 1);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("migration auto-check repairs DB hierarchy count mismatch", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory(projectFixture(), base);
+    await autoImportMarkdownHierarchyIfDbMismatch(base);
+
+    _getAdapter()!.prepare("DELETE FROM tasks WHERE milestone_id = ? AND slice_id = ? AND id = ?").run("M001", "S01", "T01");
+    assert.equal(getSliceTasks("M001", "S01").length, 0, "test fixture simulates stale DB task count");
+
+    const result = await autoImportMarkdownHierarchyIfDbMismatch(base);
+    assert.equal(result.action, "imported");
+    assert.equal(result.reason, "count-mismatch");
+    assert.deepEqual(result.beforeDb, { milestones: 1, slices: 1, tasks: 0 });
+    assert.deepEqual(result.afterDb, { milestones: 1, slices: 1, tasks: 1 });
+    assert.equal(getSliceTasks("M001", "S01").length, 1);
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("migration auto-check leaves matching DB hierarchy alone", async () => {
+  const base = makeBase();
+  try {
+    await writeGSDDirectory(projectFixture(), base);
+    await autoImportMarkdownHierarchyIfDbMismatch(base);
+
+    const result = await autoImportMarkdownHierarchyIfDbMismatch(base);
+    assert.equal(result.action, "none");
+    assert.equal(result.reason, "in-sync");
+    assert.deepEqual(result.markdown, { milestones: 1, slices: 1, tasks: 1 });
+    assert.deepEqual(result.afterDb, { milestones: 1, slices: 1, tasks: 1 });
+  } finally {
+    cleanup(base);
+  }
+});