@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

package/src/resources/extensions/gsd/tests/doctor-providers.test.ts

@@ -338,6 +338,7 @@ test("runProviderChecks detects custom provider keys from models.json", () => {
     join(repo, ".gsd", "PREFERENCES.md"),
     [
       "---",
+      "token_profile: burn-max",
       "models:",
       "  execution:",
       "    model: custom-model",
@@ -514,6 +515,7 @@ test("runProviderChecks uses provider-qualified anthropic-vertex model IDs", ()
     join(repo, ".gsd", "PREFERENCES.md"),
     [
       "---",
+      "token_profile: burn-max",
       "models:",
       "  execution: anthropic-vertex/claude-sonnet-4-6",
       "---",
@@ -605,6 +607,7 @@ test("runProviderChecks reports ok for Google via google-gemini-cli auth.json (#
 
   withEnv({
     HOME: tmpHome,
+    PATH: tmpHome,
     GEMINI_API_KEY: undefined,
     GOOGLE_API_KEY: undefined,
   }, () => {
@@ -904,17 +907,16 @@ test("runProviderChecks detects claude.exe in PATH on Windows (#4548)", { skip:
   });
 });
 
-test("PROVIDER_ROUTES includes google-gemini-cli as route for google (#2922)", async () => {
+test("PROVIDER_ROUTES includes google-antigravity and google-gemini-cli as routes for google (#2922)", async () => {
   const { readFileSync: readFS } = await import("node:fs");
   const { dirname: dirn, join: joinPath } = await import("node:path");
   const { fileURLToPath: fileUrl } = await import("node:url");
   const __dir = dirn(fileUrl(import.meta.url));
   const src = readFS(joinPath(__dir, "..", "doctor-providers.ts"), "utf-8");
 
-  // PROVIDER_ROUTES must map google -> [..., "google-gemini-cli"]
   assert.ok(
-    src.includes('"google-gemini-cli"'),
-    'PROVIDER_ROUTES must include "google-gemini-cli" as a route (#2922)',
+    src.includes('google: ["google-antigravity", "google-gemini-cli"]'),
+    'PROVIDER_ROUTES must prefer "google-antigravity" over "google-gemini-cli" for google (#2922)',
   );
 });
 

package/src/resources/extensions/gsd/tests/ensure-preconditions-guard-4996.test.ts

@@ -14,12 +14,13 @@ import {
   closeDatabase,
   insertMilestone,
 } from "../gsd-db.ts";
+import { canonicalPhaseDirName } from "../paths.ts";
 
 import type { GSDState } from "../types.ts";
 
 function makeBase(prefix = "gsd-precond-"): string {
   const base = mkdtempSync(join(tmpdir(), prefix));
-  mkdirSync(join(base, ".gsd", "milestones"), { recursive: true });
+  mkdirSync(join(base, ".gsd", "phases"), { recursive: true });
   return base;
 }
 
@@ -50,7 +51,8 @@ describe("ensurePreconditions phantom-dir guard (#4996)", () => {
 
     ensurePreconditions("execute-task", "M003/S01", base, state);
 
-    const milestoneDir = join(base, ".gsd", "milestones", "M003");
+    // Flat-phase: phantom guard must not create any phase dir for an unrecognised milestone.
+    const milestoneDir = join(base, ".gsd", "phases", canonicalPhaseDirName("M003"));
     assert.ok(!existsSync(milestoneDir), "M003 dir must not be created for phantom slice dispatch");
   });
 
@@ -63,22 +65,26 @@ describe("ensurePreconditions phantom-dir guard (#4996)", () => {
 
     ensurePreconditions("execute-task", "M003/S01", base, state);
 
-    const milestoneDir = join(base, ".gsd", "milestones", "M003");
-    assert.ok(existsSync(milestoneDir), "M003 dir must be created when DB row exists");
+    // Flat-phase: dir is created under phases/ using the canonical phase dir name.
+    const milestoneDir = join(base, ".gsd", "phases", canonicalPhaseDirName("M003"));
+    assert.ok(existsSync(milestoneDir), "M003 phase dir must be created when DB row exists");
   });
 
-  it("(c) slice unit ID for existing milestone dir with CONTEXT.md content file uses normal scaffolding", () => {
+  it("(c) slice unit ID for existing milestone dir with CONTEXT.md content file does not clobber it", () => {
     base = makeBase();
     const mid = "M003";
-    const milestoneDir = join(base, ".gsd", "milestones", mid);
+    // Use canonicalPhaseDirName so the dir is found by resolveMilestonePath.
+    const milestoneDir = join(base, ".gsd", "phases", canonicalPhaseDirName(mid));
     mkdirSync(milestoneDir, { recursive: true });
     writeFileSync(join(milestoneDir, `${mid}-CONTEXT.md`), "# Context\n");
     const state = makeMinimalState();
 
     ensurePreconditions("execute-task", "M003/S01", base, state);
 
-    const slicesDir = join(milestoneDir, "slices");
-    assert.ok(existsSync(slicesDir), "existing milestone dir should allow slice scaffolding");
+    // Flat-phase: ensurePreconditions returns early when the phase dir already exists.
+    // Tasks are checkboxes in plan files — no slices/ subdir is created.
+    assert.ok(existsSync(milestoneDir), "existing milestone dir must survive ensurePreconditions");
+    assert.ok(!existsSync(join(milestoneDir, "slices")), "flat-phase must not scaffold slices/ subdir");
   });
 
   it("(d) milestone-only unit ID (no slice) still creates dir even with no DB row", () => {
@@ -87,7 +93,8 @@ describe("ensurePreconditions phantom-dir guard (#4996)", () => {
 
     ensurePreconditions("discuss-milestone", "M003", base, state);
 
-    const milestoneDir = join(base, ".gsd", "milestones", "M003");
-    assert.ok(existsSync(milestoneDir), "M003 dir must be created for milestone-only dispatch");
+    // Flat-phase: dir is created under phases/ using the canonical phase dir name.
+    const milestoneDir = join(base, ".gsd", "phases", canonicalPhaseDirName("M003"));
+    assert.ok(existsSync(milestoneDir), "M003 phase dir must be created for milestone-only dispatch");
   });
 });

package/src/resources/extensions/gsd/tests/evidence-cross-ref.test.ts

@@ -86,6 +86,101 @@ test("stale verification evidence batches are ignored when a newer completion ba
   assert.deepEqual(mismatches, []);
 });
 
+test("WSL bash-spawn failure is not flagged as a falsified passing verification", () => {
+  // Issue #814: on Windows, `gsd_exec runtime=bash` resolves to a WSL with no
+  // /bin/bash. The bash-runtime verification call exits 1 with a spawn-failure
+  // banner (the command never ran); the LLM re-ran via a node runtime (exit 0)
+  // that findMatches does not capture. The infra failure must not block.
+  const command = "npx playwright test e2e/m039-s05-comparison-legibility.spec.ts";
+  const mismatches = crossReferenceEvidence(
+    [{ command, exitCode: 0, verdict: "passed" }],
+    [
+      {
+        kind: "bash",
+        toolCallId: "call-1",
+        command: `${command} --reporter=line 2>&1 | tail -40`,
+        exitCode: 1,
+        outputSnippet:
+          "<3>WSL (12 - Relay) ERROR: CreateProcessCommon:800: execvpe(/bin/bash) failed: No such file or directory",
+        timestamp: 1,
+      },
+    ] as EvidenceEntry[],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "warning");
+  assert.match(mismatches[0].reason, /inconclusive/);
+});
+
+test("missing tool failure (command not found: eslint) is a real error, not an infra spawn failure", () => {
+  // Regression for overly-broad spawn signature: `command not found: eslint`
+  // is a genuine verification failure (eslint not installed), not a missing
+  // shell interpreter. It must produce a blocking error, not a warning.
+  const command = "eslint src/";
+  const mismatches = crossReferenceEvidence(
+    [{ command, exitCode: 0, verdict: "passed" }],
+    [
+      {
+        kind: "bash",
+        toolCallId: "call-1",
+        command,
+        exitCode: 1,
+        outputSnippet: "zsh: command not found: eslint",
+        timestamp: Date.now(),
+      },
+    ] as EvidenceEntry[],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "error");
+  assert.match(mismatches[0].reason, /Claimed exitCode=0/);
+});
+
+test("missing tool failure (command not found: node) is a real error, not an infra spawn failure", () => {
+  // node is not a shell interpreter; its absence is a genuine env problem,
+  // not a shell-spawn infra failure.
+  const command = "node --test tests/verify.test.js";
+  const mismatches = crossReferenceEvidence(
+    [{ command, exitCode: 0, verdict: "passed" }],
+    [
+      {
+        kind: "bash",
+        toolCallId: "call-1",
+        command,
+        exitCode: 127,
+        outputSnippet: "bash: command not found: node",
+        timestamp: Date.now(),
+      },
+    ] as EvidenceEntry[],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "error");
+  assert.match(mismatches[0].reason, /Claimed exitCode=0/);
+});
+
+test("missing shell interpreter (command not found: bash) is treated as an infra spawn failure", () => {
+  // bash itself missing is the shell-spawn infra case; must remain a warning.
+  const command = "npm test";
+  const mismatches = crossReferenceEvidence(
+    [{ command, exitCode: 0, verdict: "passed" }],
+    [
+      {
+        kind: "bash",
+        toolCallId: "call-1",
+        command,
+        exitCode: 1,
+        outputSnippet: "command not found: bash",
+        timestamp: Date.now(),
+      },
+    ] as EvidenceEntry[],
+  );
+
+  assert.equal(mismatches.length, 1);
+  assert.equal(mismatches[0].severity, "warning");
+  assert.match(mismatches[0].reason, /inconclusive/);
+});
+
 test("missing recorded bash evidence remains a warning", () => {
   const mismatches = crossReferenceEvidence(
     [{ command: "npm test", exitCode: 0, verdict: "passed" }],

package/src/resources/extensions/gsd/tests/export-html-enhancements.test.ts

@@ -108,6 +108,7 @@ function mockData(overrides: Partial<VisualizerData> = {}): VisualizerData {
     changelog: { entries: [] },
     sliceVerifications: [],
     knowledge: { rules: [], patterns: [], lessons: [], exists: false },
+    memories: { entries: [], totalCount: 0 },
     captures: { entries: [], pendingCount: 0, totalCount: 0 },
     health: {
       budgetCeiling: undefined,
@@ -149,6 +150,30 @@ test("report uses the shared GSD HTML shell", () => {
   assert.ok(html.includes('<main>'), "should render content inside shared shell main");
 });
 
+test("knowledge section renders active memories", () => {
+  const html = generateHtmlReport(mockData({
+    memories: {
+      totalCount: 1,
+      entries: [
+        {
+          id: "MEM001",
+          category: "gotcha",
+          content: "Memory rows must be visible in exported visualizer reports",
+          confidence: 0.9,
+          hitCount: 2,
+          scope: "project",
+          tags: ["visualizer"],
+          updatedAt: "2026-06-21T12:00:00.000Z",
+        },
+      ],
+    },
+  }), mockOpts());
+
+  assert.ok(html.includes("Memories"), "should render memories heading");
+  assert.ok(html.includes("MEM001"), "should render memory ID");
+  assert.ok(html.includes("Memory rows must be visible"), "should render memory content");
+});
+
 test("Feature 1: executive summary includes budget context when set", () => {
   const data = mockData({ health: { ...mockData().health, budgetCeiling: 10.00 } });
   const html = generateHtmlReport(data, mockOpts());

package/src/resources/extensions/gsd/tests/export-memory.test.ts

@@ -0,0 +1,179 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { writeExportFile } from "../export.ts";
+import { closeDatabase, openDatabase } from "../gsd-db.ts";
+import { createMemory } from "../memory-store.ts";
+
+function mockTokens() {
+  return { input: 10, output: 5, cacheRead: 0, cacheWrite: 0, total: 15 };
+}
+
+test("writeExportFile includes active memories in markdown exports", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-export-memory-"));
+  try {
+    const largeContent = "Exported reports should include memory rows. " + "A".repeat(2500);
+    const filePath = writeExportFile(base, "markdown", {
+      totals: {
+        units: 1,
+        tokens: mockTokens(),
+        cost: 0.01,
+        duration: 1000,
+        toolCalls: 1,
+        assistantMessages: 1,
+        userMessages: 1,
+      },
+      byPhase: [
+        { phase: "execution", units: 1, tokens: mockTokens(), cost: 0.01, duration: 1000 },
+      ],
+      bySlice: [
+        { sliceId: "M001/S01", units: 1, tokens: mockTokens(), cost: 0.01, duration: 1000 },
+      ],
+      byModel: [],
+      units: [
+        {
+          type: "execute-task",
+          id: "M001/S01/T01",
+          model: "claude-sonnet",
+          startedAt: 0,
+          finishedAt: 1000,
+          tokens: mockTokens(),
+          cost: 0.01,
+          toolCalls: 1,
+          assistantMessages: 1,
+          userMessages: 1,
+        },
+      ],
+      memories: {
+        totalCount: 1,
+        entries: [
+          {
+            id: "MEM001",
+            category: "gotcha",
+            content: largeContent,
+            confidence: 0.9,
+            hitCount: 2,
+            scope: "M001/S01",
+            tags: ["export", "memory"],
+            updatedAt: "2026-06-21T00:00:00.000Z",
+          },
+        ],
+      },
+    });
+
+    assert.ok(filePath);
+    const markdown = readFileSync(filePath, "utf-8");
+    assert.match(markdown, /## Memories/);
+    assert.match(markdown, /Active memories: 1/);
+    assert.match(markdown, /MEM001/);
+    assert.match(markdown, /Exported reports should include memory rows/);
+    assert.doesNotMatch(markdown, new RegExp(`A{${2500}}`));
+  } finally {
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("writeExportFile reads project DB memories when no visualizer payload is supplied", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-export-memory-db-"));
+  try {
+    const gsdDir = join(base, ".gsd");
+    mkdirSync(gsdDir, { recursive: true });
+    writeFileSync(
+      join(gsdDir, "metrics.json"),
+      JSON.stringify({
+        version: 1,
+        projectStartedAt: Date.now(),
+        units: [
+          {
+            type: "execute-task",
+            id: "M001/S01/T01",
+            model: "claude-sonnet",
+            startedAt: 0,
+            finishedAt: 1000,
+            tokens: mockTokens(),
+            cost: 0.01,
+            toolCalls: 1,
+            assistantMessages: 1,
+            userMessages: 1,
+          },
+        ],
+      }),
+    );
+
+    openDatabase(join(gsdDir, "gsd.db"));
+    createMemory({
+      category: "pattern",
+      content: "Shared markdown export reads memories from the project DB",
+      confidence: 0.86,
+      tags: ["export"],
+    });
+    closeDatabase();
+
+    const filePath = writeExportFile(base, "markdown");
+
+    assert.ok(filePath);
+    const markdown = readFileSync(filePath, "utf-8");
+    assert.match(markdown, /## Memories/);
+    assert.match(markdown, /MEM001/);
+    assert.match(markdown, /Shared markdown export reads memories from the project DB/);
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("writeExportFile includes bounded memories in json exports", () => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-export-memory-json-"));
+  try {
+    const gsdDir = join(base, ".gsd");
+    mkdirSync(gsdDir, { recursive: true });
+    writeFileSync(
+      join(gsdDir, "metrics.json"),
+      JSON.stringify({
+        version: 1,
+        projectStartedAt: Date.now(),
+        units: [
+          {
+            type: "execute-task",
+            id: "M001/S01/T01",
+            model: "claude-sonnet",
+            startedAt: 0,
+            finishedAt: 1000,
+            tokens: mockTokens(),
+            cost: 0.01,
+            toolCalls: 1,
+            assistantMessages: 1,
+            userMessages: 1,
+          },
+        ],
+      }),
+    );
+
+    openDatabase(join(gsdDir, "gsd.db"));
+    const largeContent = "JSON export should carry memory rows. " + "B".repeat(2500);
+    createMemory({
+      category: "pattern",
+      content: largeContent,
+      confidence: 0.86,
+      tags: ["export"],
+    });
+    closeDatabase();
+
+    const filePath = writeExportFile(base, "json");
+
+    assert.ok(filePath);
+    const report = JSON.parse(readFileSync(filePath, "utf-8"));
+    assert.equal(report.memories.totalCount, 1);
+    assert.equal(report.memories.entries[0].id, "MEM001");
+    assert.match(report.memories.entries[0].content, /JSON export should carry memory rows/);
+    assert.ok(report.memories.entries[0].content.length < largeContent.length);
+    assert.ok(report.memories.entries[0].content.length <= 2003);
+    assert.ok(report.memories.entries[0].content.endsWith("..."));
+  } finally {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/extension-bootstrap-isolation.test.ts

@@ -195,4 +195,57 @@ describe("registerGsdExtension defensive registration", () => {
     assert.ok(!registeredTools.includes("gsd_plan_slice"));
     drainLogs();
   });
+
+  // ── #852 follow-up: assertCriticalGsdWorkflowToolsRegistered tolerates pre-bind ──
+  //
+  // During extension loading, getAllTools() is a throwing stub
+  // ("Extension runtime not initialized"). The assertion used to call it
+  // synchronously and throw, propagating to index.ts's catch and firing
+  // "Extension setup partially failed" — leaving the tool surface incomplete
+  // under Claude Code CLI. It must tolerate the pre-bind throw.
+
+  test("registerGsdExtension does not throw when getAllTools is the pre-bind stub", () => {
+    const registeredTools: string[] = [];
+    const pi = {
+      registerCommand: () => {},
+      registerTool: (tool: { name: string }) => { registeredTools.push(tool.name); },
+      registerHook: () => {},
+      registerShortcut: () => {},
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+      // Simulate the pre-bind throwing stub (loader.ts:182).
+      getAllTools: () => {
+        throw new Error("Extension runtime not initialized. Action methods cannot be called during extension loading.");
+      },
+    };
+
+    // Must not throw — the old code let this propagate as "Extension setup partially failed".
+    assert.doesNotThrow(() => registerGsdExtension(pi as any));
+    // Critical tools should still have been registered (registerTool is valid during load).
+    assert.ok(registeredTools.includes("gsd_plan_milestone"));
+    assert.ok(registeredTools.includes("gsd_plan_slice"));
+    drainLogs();
+  });
+
+  test("registerGsdExtension still throws when getAllTools works and critical tools are missing (post-bind)", () => {
+    // The assertion must still fire when getAllTools returns a real value but
+    // a critical tool is missing — just not during the pre-bind window.
+    const registeredTools: string[] = [];
+    const pi = {
+      registerCommand: () => {},
+      registerTool: (tool: { name: string }) => {
+        if (tool.name === "gsd_plan_slice") throw new Error("simulated failure");
+        registeredTools.push(tool.name);
+      },
+      registerHook: () => {},
+      registerShortcut: () => {},
+      events: { on: () => {}, off: () => {}, emit: () => {} },
+      getAllTools: () => registeredTools.map((name) => ({ name })),
+    };
+
+    assert.throws(
+      () => registerGsdExtension(pi as any),
+      /Critical GSD workflow tool registration failed/,
+    );
+    drainLogs();
+  });
 });

package/src/resources/extensions/gsd/tests/external-markdown-edit.test.ts

@@ -0,0 +1,137 @@
+// Project/App: gsd-pi
+// File Purpose: Unit tests for the external-markdown-edit drift handler.
+import test, { afterEach } 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 { randomUUID } from "node:crypto";
+
+import { externalMarkdownEditHandler } from "../state-reconciliation/drift/external-markdown-edit.ts";
+import { writeCompatMarker, computeProjectionSha } from "../compat/compat-marker.ts";
+import type { DriftContext } from "../state-reconciliation/types.ts";
+import type { GSDState } from "../types.ts";
+
+const tmpDirs: string[] = [];
+
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-extedit-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+
+const stubState = { phase: "idle" } as unknown as GSDState;
+
+function ctx(base: string): DriftContext {
+  return { basePath: base, state: stubState };
+}
+
+afterEach(() => {
+  for (const dir of tmpDirs) {
+    try { rmSync(dir, { recursive: true, force: true }); } catch { /* */ }
+  }
+  tmpDirs.length = 0;
+});
+
+test("detect returns no drift when file sha matches marker", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  mkdirSync(join(base, ".gsd", "m1"), { recursive: true });
+  writeFileSync(join(base, ".gsd", rel), "# Roadmap\n\n- [x] S1 done\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: { [rel]: { sha: computeProjectionSha("# Roadmap\n\n- [x] S1 done\n"), entities: ["m1"] } },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+});
+
+test("detect returns drift when file content differs from marker", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  mkdirSync(join(base, ".gsd", "m1"), { recursive: true });
+  writeFileSync(join(base, ".gsd", rel), "# Roadmap\n\n- [ ] S1 NOT done\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: { [rel]: { sha: "stale000000000000", entities: ["m1"] } },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 1);
+  assert.equal(drift[0].kind, "external-markdown-edit");
+  assert.equal(drift[0].projectionPath, rel);
+  assert.deepEqual(drift[0].entities, ["m1"]);
+});
+
+test("detect treats missing marker as drift on every tracked projection file", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  mkdirSync(join(base, ".gsd", "m1"), { recursive: true });
+  writeFileSync(join(base, ".gsd", rel), "# Roadmap\n", "utf-8");
+  // No writeCompatMarker call → marker missing → EMPTY_MARKER
+
+  // Without a marker we have no projections to compare, so detect should be a
+  // no-op (the reconcile pipeline's other handlers cover the "import everything"
+  // case via the existing /gsd recover flow). This is by design: this handler
+  // only fires when we HAVE a baseline to compare.
+  const drift = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+});
+
+test("detect ignores files missing from disk (other handlers cover that)", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  writeCompatMarker(base, {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: { [rel]: { sha: "abc123", entities: ["m1"] } },
+    piVersion: "1.4.0",
+  });
+  // No file written.
+
+  const drift = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+});
+
+test("repair is idempotent: running twice produces no further drift on second detect", async () => {
+  const base = makeTmpBase();
+  const rel = "m1/roadmap.md";
+  mkdirSync(join(base, ".gsd", "m1"), { recursive: true });
+  const content = "# Roadmap\n\n- [x] S1 done\n";
+  writeFileSync(join(base, ".gsd", rel), content, "utf-8");
+  writeCompatMarker(base, {
+    schema: 1,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: { [rel]: { sha: "stale000000000000", entities: ["m1"] } },
+    piVersion: "1.4.0",
+  });
+
+  const drift1 = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift1.length, 1);
+  // repair may call migrateHierarchyToDb which requires a DB; we only assert
+  // that detect after repair produces no further drift on THIS handler. Wrap
+  // in try/catch so a no-DB environment doesn't fail the idempotency check —
+  // the marker refresh is the load-bearing part of the assertion.
+  try {
+    await externalMarkdownEditHandler.repair(drift1[0], ctx(base));
+  } catch {
+    // migrateHierarchyToDb may throw without an open DB; that's fine for this
+    // unit test — the marker refresh below the import call still runs if the
+    // import succeeds. If it throws, we skip the second-detect assertion.
+    return;
+  }
+
+  // After repair, marker should reflect the file's actual sha → no drift.
+  const drift2 = await externalMarkdownEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift2.length, 0);
+});