@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.eed73bea

package/src/resources/extensions/gsd/tests/unit-context-composer.test.ts

@@ -8,6 +8,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import {
+  CONTEXT_MODE_GUIDANCE_BY_UNIT,
   composeContractedUnitContext,
   composeContextModeInstructions,
   composeInlinedContext,
@@ -141,9 +142,13 @@ test("Context Mode composer: nested output is compact single sentence", () => {
   assert.ok(!out.startsWith("## Context Mode"));
   assert.match(out, /^Context Mode \(verification lane\): /);
   assert.strictEqual(out.split(/\n/).length, 1);
-  assert.match(out, /`gsd_exec`/);
-  assert.match(out, /`gsd_exec_search`/);
-  assert.match(out, /`gsd_resume`/);
+  // Nested guidance is embedded into tester subagent prompts — it must instruct the tester
+  // to run verification and call gsd_save_gate_result, NOT to dispatch further subagents.
+  assert.doesNotMatch(out, /`subagent`/, "tester prompts must not be told to dispatch subagents");
+  assert.match(out, /`gsd_save_gate_result`/);
+  assert.doesNotMatch(out, /`gsd_exec`/);
+  assert.doesNotMatch(out, /`gsd_exec_search`/);
+  assert.doesNotMatch(out, /`gsd_resume`/);
   assert.ok(out.length < 240, `nested guidance should stay compact, got ${out.length} chars`);
 });
 
@@ -158,6 +163,53 @@ const laneLabelByMode: Record<string, string> = {
   triage: "triage",
 };
 
+const contextModeGuidanceOverrideExpectedTools: Record<string, readonly string[]> = {
+  "discuss-milestone": [
+    "ask_user_questions",
+    "gsd_summary_save",
+    "gsd_decision_save",
+    "gsd_requirement_save",
+    "gsd_requirement_update",
+    "gsd_plan_milestone",
+    "gsd_milestone_generate_id",
+  ],
+  "discuss-project": [
+    "ask_user_questions",
+    "gsd_summary_save",
+    "gsd_decision_save",
+    "gsd_requirement_save",
+  ],
+  "discuss-requirements": [
+    "ask_user_questions",
+    "gsd_requirement_save",
+    "gsd_summary_save",
+  ],
+  "discuss-slice": [
+    "ask_user_questions",
+    "gsd_summary_save",
+    "gsd_decision_save",
+  ],
+  "replan-slice": [
+    "gsd_replan_slice",
+    "gsd_decision_save",
+  ],
+  "reassess-roadmap": [
+    "gsd_milestone_status",
+    "gsd_reassess_roadmap",
+  ],
+  "run-uat": [
+    "gsd_uat_exec",
+    "gsd_resume",
+  ],
+  // research-project uses scout subagents that write .gsd/research/ files directly;
+  // the parent dispatches Task calls and verifies file outputs — no GSD save tools.
+  "research-project": [],
+  "gate-evaluate": [
+    "subagent",
+    "gsd_save_gate_result",
+  ],
+};
+
 test("Context Mode composer: every known eligible unit renders its configured lane and required tools", () => {
   for (const unitType of KNOWN_UNIT_TYPES) {
     const manifest = UNIT_MANIFESTS[unitType];
@@ -170,18 +222,65 @@ test("Context Mode composer: every known eligible unit renders its configured la
     assert.ok(out.startsWith("## Context Mode"), `${unitType} should render standalone Context Mode heading`);
     assert.match(out, new RegExp(`Lane: \\*\\*${laneLabelByMode[manifest.contextMode]} lane\\*\\*\\.`, "i"));
     const forbidden = getUnitToolSurfaceContract(unitType)?.forbiddenGsdTools ?? {};
-    if ("gsd_exec" in forbidden) {
-      // Units that forbid gsd_exec (run-uat) have it stripped from their
-      // Claude Code dispatch surface; guidance steering to it produces
-      // "No such tool available" loops in the dispatched agent.
-      assert.doesNotMatch(out, /`gsd_exec`/, `${unitType} forbids gsd_exec; guidance must not steer to it`);
+    const overrideExpectedTools = contextModeGuidanceOverrideExpectedTools[unitType];
+    if ("gsd_exec" in forbidden || overrideExpectedTools) {
+      // Unit overrides are the contract-specific exception to lane defaults.
+      // Steering to the lane default here can produce unavailable-tool loops.
+      assert.doesNotMatch(out, /`gsd_exec`/, `${unitType} guidance must not steer to gsd_exec`);
       assert.doesNotMatch(out, /`gsd_exec_search`/, `${unitType} guidance must not steer to gsd_exec_search`);
-      assert.match(out, /`gsd_uat_exec`/, `${unitType} guidance should steer to gsd_uat_exec instead`);
+      for (const toolName of overrideExpectedTools ?? []) {
+        assert.match(out, new RegExp(`\`${toolName}\``), `${unitType} guidance should mention ${toolName}`);
+      }
     } else {
       assert.match(out, /`gsd_exec`/, `${unitType} should mention gsd_exec`);
       assert.match(out, /`gsd_exec_search`/, `${unitType} should mention gsd_exec_search`);
     }
-    assert.match(out, /`gsd_resume`/, `${unitType} should mention gsd_resume`);
+    if (!overrideExpectedTools || overrideExpectedTools.includes("gsd_resume")) {
+      assert.match(out, /`gsd_resume`/, `${unitType} should mention gsd_resume`);
+    } else {
+      assert.doesNotMatch(out, /`gsd_resume`/, `${unitType} guidance must not steer to gsd_resume`);
+    }
+  }
+});
+
+test("Context Mode composer: discuss interview overrides stay within unit contracts", () => {
+  const discussUnits = [
+    "discuss-milestone",
+    "discuss-project",
+    "discuss-requirements",
+    "discuss-slice",
+  ];
+
+  for (const unitType of discussUnits) {
+    const guidance = CONTEXT_MODE_GUIDANCE_BY_UNIT[unitType];
+    assert.ok(guidance, `${unitType} should have a Context Mode override`);
+    assert.doesNotMatch(guidance, /`gsd_exec`/, `${unitType} guidance must not mention gsd_exec`);
+    assert.doesNotMatch(guidance, /`gsd_exec_search`/, `${unitType} guidance must not mention gsd_exec_search`);
+    assert.doesNotMatch(guidance, /`gsd_resume`/, `${unitType} guidance must not mention gsd_resume`);
+
+    const expectedTools = contextModeGuidanceOverrideExpectedTools[unitType] ?? [];
+    assert.ok(expectedTools.length > 0, `${unitType} should declare expected override tools`);
+    const contract = getUnitToolSurfaceContract(unitType);
+    assert.ok(contract, `${unitType} should have a tool contract`);
+    const contractTools = new Set([
+      ...contract.allowedGsdTools,
+      ...contract.requiredWorkflowTools,
+    ]);
+
+    for (const toolName of expectedTools) {
+      assert.match(guidance, new RegExp(`\`${toolName}\``), `${unitType} guidance should mention ${toolName}`);
+      assert.ok(contractTools.has(toolName as UnitGsdToolName), `${unitType} contract should allow ${toolName}`);
+      const scope = shouldBlockAutoUnitToolCall(unitType, toolName);
+      assert.equal(scope.block, false, `${unitType} should not hard-block ${toolName}: ${scope.reason ?? ""}`);
+    }
+
+    const out = composeContextModeInstructions(unitType, { enabled: true, renderMode: "standalone" });
+    if (out) {
+      assert.match(out, /interview lane/i);
+      assert.doesNotMatch(out, /`gsd_exec`/);
+      assert.doesNotMatch(out, /`gsd_exec_search`/);
+      assert.doesNotMatch(out, /`gsd_resume`/);
+    }
   }
 });
 
@@ -195,8 +294,67 @@ test("Context Mode composer: run-uat guidance steers to gsd_uat_exec in both ren
   assert.doesNotMatch(standalone, /`gsd_exec`/);
 });
 
-test("Context Mode composer: slice planning and research guidance tools pass unit contracts", () => {
-  const affectedUnits = ["research-slice", "plan-slice", "refine-slice"];
+test("Context Mode composer: research-project guidance steers to scout orchestration", () => {
+  for (const renderMode of ["nested", "standalone"] as const) {
+    const out = composeContextModeInstructions("research-project", { enabled: true, renderMode });
+    assert.match(out, /research lane/i);
+    assert.match(out, /scout subagents/i);
+    assert.match(out, /\.gsd\/research\//);
+    assert.match(out, /STACK\.md/);
+    assert.match(out, /PITFALLS\.md/);
+    assert.doesNotMatch(out, /`gsd_summary_save`/);
+    assert.doesNotMatch(out, /`gsd_decision_save`/);
+    assert.doesNotMatch(out, /`gsd_exec`/);
+    assert.doesNotMatch(out, /`gsd_exec_search`/);
+    assert.doesNotMatch(out, /`gsd_resume`/);
+  }
+
+  const contract = getUnitToolSurfaceContract("research-project");
+  assert.deepEqual(contract?.allowedGsdTools, []);
+  assert.deepEqual(contract?.requiredWorkflowTools, []);
+  for (const toolName of ["gsd_summary_save", "gsd_decision_save"]) {
+    const scope = shouldBlockAutoUnitToolCall("research-project", toolName);
+    assert.equal(scope.block, true, `research-project should not allow ${toolName}`);
+  }
+});
+
+test("Context Mode composer: narrow planning guidance steers only to contracted tools", () => {
+  const cases = [
+    {
+      unitType: "replan-slice",
+      expectedTools: ["gsd_replan_slice", "gsd_decision_save"],
+    },
+    {
+      unitType: "reassess-roadmap",
+      expectedTools: ["gsd_milestone_status", "gsd_reassess_roadmap"],
+    },
+  ];
+  const disallowedTools = ["gsd_exec", "gsd_exec_search", "gsd_resume"];
+
+  for (const { unitType, expectedTools } of cases) {
+    for (const renderMode of ["nested", "standalone"] as const) {
+      const out = composeContextModeInstructions(unitType, { enabled: true, renderMode });
+      assert.match(out, /planning lane/i, `${unitType} should still render planning lane guidance`);
+      for (const toolName of expectedTools) {
+        assert.ok(out.includes(`\`${toolName}\``), `${unitType} guidance should mention ${toolName}`);
+      }
+      for (const toolName of disallowedTools) {
+        assert.ok(!out.includes(`\`${toolName}\``), `${unitType} guidance must not mention ${toolName}`);
+      }
+    }
+  }
+});
+
+test("Context Mode composer: lane guidance tools pass unit contracts", () => {
+  const affectedUnits = [
+    "research-milestone",
+    "research-slice",
+    "plan-slice",
+    "refine-slice",
+    "complete-slice",
+    "validate-milestone",
+    "complete-milestone",
+  ];
   const contextModeTools: UnitGsdToolName[] = ["gsd_exec", "gsd_exec_search", "gsd_resume"];
   const readOnlyOrientationTools: UnitGsdToolName[] = ["gsd_milestone_status", ...contextModeTools];
 
@@ -207,7 +365,10 @@ test("Context Mode composer: slice planning and research guidance tools pass uni
     for (const toolName of contextModeTools) {
       assert.ok(out.includes(`\`${toolName}\``), `${unitType} guidance should mention ${toolName}`);
     }
-    for (const toolName of readOnlyOrientationTools) {
+    const expectedContractTools = unitType === "research-milestone"
+      ? contextModeTools
+      : readOnlyOrientationTools;
+    for (const toolName of expectedContractTools) {
       assert.ok(allowed.has(toolName), `${unitType} contract should allow ${toolName}`);
       const scope = shouldBlockAutoUnitToolCall(unitType, toolName);
       assert.equal(scope.block, false, `${unitType} should not hard-block ${toolName}: ${scope.reason ?? ""}`);
@@ -357,13 +518,31 @@ test("#4782 phase 2: buildReassessRoadmapPrompt emits composer-shaped context wi
   assert.ok(!prompt.includes("Slice Context (from discussion)"));
 });
 
-test("execute-task prompt surfaces contract-declared on-demand slice research", async (t) => {
+test("execute-task prompt omits on-demand slice research when the artifact is absent", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+
+  const prompt = await buildExecuteTaskPrompt("M001", "S01", "First", "T01", "Task", base);
+
+  assert.doesNotMatch(prompt, /## On-demand Context/);
+  assert.doesNotMatch(prompt, /\.gsd\/milestones\/M001\/slices\/S01\/S01-RESEARCH\.md/);
+});
+
+test("execute-task prompt surfaces on-demand slice research when the artifact exists", async (t) => {
   const base = makeFixtureBase();
   t.after(() => cleanup(base));
   invalidateAllCaches();
 
   seed(base, "M001");
   writeArtifacts(base);
+  writeFileSync(
+    join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-RESEARCH.md"),
+    "# S01 Research\n",
+  );
 
   const prompt = await buildExecuteTaskPrompt("M001", "S01", "First", "T01", "Task", base);
 

package/src/resources/extensions/gsd/tests/unmerged-milestone-guard.test.ts

@@ -127,6 +127,31 @@ test("formatUnmergedMilestoneBlockMessage includes files, branch, and dirty over
   }
 });
 
+test("findUnmergedCompletedMilestones reports dirty overlap without content fingerprints", async () => {
+  const base = makeTempRepo("gsd-unmerged-guard-");
+  try {
+    const relPath = "build/output.bin";
+    const absPath = join(base, relPath);
+    mkdirSync(dirname(absPath), { recursive: true });
+    writeFileSync(absPath, "main artifact\n");
+    git(base, "add", relPath);
+    git(base, "commit", "-m", "test: track build output fixture");
+
+    seedMilestone(base, "M012");
+    commitBranchFile(base, "milestone/M012", relPath, "milestone artifact\n");
+    writeFileSync(absPath, "dirty root artifact\n");
+
+    const [blocker] = await findUnmergedCompletedMilestones(base);
+    assert.ok(blocker);
+    assert.deepEqual(blocker.files, [relPath]);
+    assert.deepEqual(blocker.dirtyOverlap, [{ path: relPath, status: "M" }]);
+    assert.equal(Object.hasOwn(blocker.dirtyOverlap[0], "fingerprint"), false);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("isUnmergedMilestoneAllowedCommand permits inspection and explicit recovery commands", () => {
   assert.equal(isUnmergedMilestoneAllowedCommand(""), false);
   assert.equal(isUnmergedMilestoneAllowedCommand("auto"), false);

package/src/resources/extensions/gsd/tests/validation-block-guard.test.ts

@@ -3,13 +3,28 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
+import { createRequire } from "node:module";
+import { mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const _require = createRequire(import.meta.url);
 
 import {
   formatValidationBlockedMessage,
+  getValidationBlockMessageForBase,
   isValidationBlockAllowedCommand,
   isValidationBlockedState,
 } from "../validation-block-guard.ts";
+import {
+  _getAdapter,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  openDatabase,
+} from "../gsd-db.ts";
+import { invalidateStateCache } from "../state.ts";
 import type { GSDState } from "../types.ts";
+import { cleanup, makeTempDir } from "./test-utils.ts";
 
 function blockedState(): GSDState {
   return {
@@ -38,6 +53,24 @@ function blockedState(): GSDState {
   };
 }
 
+function makeBase(): string {
+  const base = makeTempDir("gsd-validation-block-");
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  return base;
+}
+
+function openRawSqliteForTest(dbPath: string): { exec(sql: string): void; close(): void } {
+  try {
+    const mod = _require("node:sqlite") as { DatabaseSync: new (path: string) => { exec(sql: string): void; close(): void } };
+    return new mod.DatabaseSync(dbPath);
+  } catch {
+    type SqliteCtor = new (path: string) => { exec(sql: string): void; close(): void };
+    const mod = _require("better-sqlite3") as SqliteCtor | { default: SqliteCtor };
+    const DatabaseCtor: SqliteCtor = typeof mod === "function" ? mod : mod.default;
+    return new DatabaseCtor(dbPath);
+  }
+}
+
 test("validation block detection only matches validation blockers", () => {
   assert.equal(isValidationBlockedState(blockedState()), true);
   assert.equal(isValidationBlockedState({
@@ -194,3 +227,49 @@ test("validation block message can guide remediation through dispatch reassess",
   assert.match(message, /\/gsd dispatch reassess/);
   assert.doesNotMatch(message, /gsd_reassess_roadmap/);
 });
+
+test("validation block guard refreshes from disk and sees external validation blocks", async () => {
+  const base = makeBase();
+  const dbPath = join(base, ".gsd", "gsd.db");
+  const validationPath = join(base, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+  try {
+    openDatabase(dbPath);
+    insertMilestone({ id: "M001", title: "Active Milestone", status: "active" });
+    insertSlice({
+      id: "S01",
+      milestoneId: "M001",
+      title: "Done Slice",
+      status: "complete",
+      risk: "low",
+      depends: [],
+    });
+    invalidateStateCache();
+
+    const adapterBefore = _getAdapter();
+    assert.ok(adapterBefore);
+
+    const externalDb = openRawSqliteForTest(dbPath);
+    try {
+      externalDb.exec(`
+        INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
+        VALUES (
+          '${validationPath.replace(/'/g, "''")}',
+          'M001', NULL, NULL, 'needs-attention', 'milestone-validation',
+          '---\nverdict: needs-attention\n---', datetime('now')
+        )
+      `);
+    } finally {
+      externalDb.close();
+    }
+
+    const message = await getValidationBlockMessageForBase(base, "next");
+
+    assert.ok(message);
+    assert.match(message, /cannot run because the active milestone is blocked by validation/);
+    assert.notEqual(_getAdapter(), adapterBefore, "guard must refresh stale database handle");
+  } finally {
+    closeDatabase();
+    invalidateStateCache();
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/verify-artifact-tightened.test.ts

@@ -292,3 +292,69 @@ test("#852: discuss-milestone fails when CONTEXT is in neither worktree nor proj
     rmSync(projectRoot, { recursive: true, force: true });
   }
 });
+
+// ---------------------------------------------------------------------------
+// #870: discuss-milestone verify-fail when the unit runs IN the worktree.
+//
+// The #852 tests above all pass `projectRoot` as the base. But the real call
+// site (auto-post-unit.ts:1726) passes `s.currentUnit.workspaceRoot ?? s.basePath`
+// — i.e. the WORKTREE path when the unit executed in a worktree. In the
+// canonical layout (`<root>/.gsd-worktrees/<MID>/`) resolveCanonicalMilestoneRoot
+// round-trips the worktree path back to itself, so `artifactBase === base` and
+// the worktree→project-root fallback (guarded by `artifactBase !== base`) is
+// skipped. CONTEXT is written to the project root, not projected into the
+// worktree, so verification finds nothing → "existsSync false" → re-dispatch
+// 3× → stuck-loop stop. These tests pin the real call site.
+// ---------------------------------------------------------------------------
+
+test("#870: discuss-milestone falls back to project root when base IS the canonical-layout worktree", () => {
+  closeDatabase();
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-canonical-wt-"));
+  try {
+    // CONTEXT lives ONLY at the project root (flat-phase layout).
+    const phaseDir = join(projectRoot, ".gsd", "phases", "15-m015");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "15-CONTEXT.md"), "# M015 context\n");
+
+    // Canonical-layout worktree: <root>/.gsd-worktrees/<MID>/. Registered
+    // with git (.git file) so resolveCanonicalMilestoneRoot treats it as the
+    // canonical milestone root — but it has NO phases/ projection.
+    const wtRoot = join(projectRoot, ".gsd-worktrees", "M015");
+    mkdirSync(join(wtRoot, ".gsd", "milestones", "M015"), { recursive: true });
+    writeFileSync(join(wtRoot, ".gsd", "milestones", "M015", "M015-META.json"), '{"branch":"milestone/M015"}');
+    writeFileSync(join(wtRoot, ".git"), "gitdir: /fake/path");
+
+    // Real call site: base = worktree path (workspaceRoot).
+    assert.equal(
+      verifyExpectedArtifact("discuss-milestone", "M015", wtRoot),
+      true,
+      "must fall back to project root when base is the canonical-layout worktree",
+    );
+  } finally {
+    closeDatabase();
+    rmSync(projectRoot, { recursive: true, force: true });
+  }
+});
+
+test("#870: discuss-milestone also falls back when base is the legacy-layout worktree", () => {
+  closeDatabase();
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-legacy-wt-"));
+  try {
+    const phaseDir = join(projectRoot, ".gsd", "phases", "15-m015");
+    mkdirSync(phaseDir, { recursive: true });
+    writeFileSync(join(phaseDir, "15-CONTEXT.md"), "# M015 context\n");
+
+    const wtRoot = join(projectRoot, ".gsd", "worktrees", "M015");
+    mkdirSync(join(wtRoot, ".gsd", "milestones", "M015"), { recursive: true });
+    writeFileSync(join(wtRoot, ".git"), "gitdir: /fake/path");
+
+    assert.equal(
+      verifyExpectedArtifact("discuss-milestone", "M015", wtRoot),
+      true,
+      "must fall back to project root when base is the legacy-layout worktree",
+    );
+  } finally {
+    closeDatabase();
+    rmSync(projectRoot, { recursive: true, force: true });
+  }
+});

package/src/resources/extensions/gsd/tests/workspace-git-preflight.test.ts

@@ -3,9 +3,10 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { delimiter, join } from "node:path";
 
+import { GIT_NO_PROMPT_ENV } from "../git-constants.js";
 import { probeGitConflictState } from "../git-conflict-state.js";
 import { ensureWorkspaceGitReadyForPath } from "../workspace-git-preflight.js";
 import { isWorkspaceGitAllowedCommand } from "../workspace-git-guard.js";
@@ -50,6 +51,38 @@ function seedProductConflict(base: string): void {
   }
 }
 
+function installCountingGitShim(binDir: string, logPath: string): void {
+  const posixShim = join(binDir, "git");
+  writeFileSync(
+    posixShim,
+    [
+      "#!/bin/sh",
+      'printf "%s\\n" "$*" >> "$GSD_GIT_LOG"',
+      'PATH="$GSD_REAL_PATH"',
+      "export PATH",
+      'exec git "$@"',
+      "",
+    ].join("\n"),
+  );
+  chmodSync(posixShim, 0o755);
+
+  writeFileSync(
+    join(binDir, "git.cmd"),
+    [
+      "@echo off",
+      'echo %*>>"%GSD_GIT_LOG%"',
+      'set "PATH=%GSD_REAL_PATH%"',
+      "git %*",
+      "",
+    ].join("\r\n"),
+  );
+}
+
+function countGitShimInvocations(logPath: string): number {
+  if (!existsSync(logPath)) return 0;
+  return readFileSync(logPath, "utf-8").split(/\r?\n/).filter(Boolean).length;
+}
+
 test("probeGitConflictState reports clean repo", () => {
   const base = makeTempRepo("gsd-ws-git-clean-");
   try {
@@ -60,6 +93,122 @@ test("probeGitConflictState reports clean repo", () => {
   }
 });
 
+test("ensureWorkspaceGitReadyForPath caches clean target probes briefly", async () => {
+  const base = makeTempRepo("gsd-ws-git-clean-cache-");
+  const binDir = makeTempDir("gsd-ws-git-shim-");
+  const logPath = join(binDir, "git.log");
+  const originalProcessPath = process.env.PATH;
+  const originalEnvPath = GIT_NO_PROMPT_ENV.PATH;
+  const originalEnvGitLog = GIT_NO_PROMPT_ENV.GSD_GIT_LOG;
+  const originalEnvRealPath = GIT_NO_PROMPT_ENV.GSD_REAL_PATH;
+
+  try {
+    installCountingGitShim(binDir, logPath);
+    const shimmedPath = `${binDir}${delimiter}${originalProcessPath ?? ""}`;
+    process.env.PATH = shimmedPath;
+    GIT_NO_PROMPT_ENV.PATH = shimmedPath;
+    GIT_NO_PROMPT_ENV.GSD_GIT_LOG = logPath;
+    GIT_NO_PROMPT_ENV.GSD_REAL_PATH = originalProcessPath ?? "";
+
+    const first = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(first.ok, true);
+    const firstCount = countGitShimInvocations(logPath);
+    assert.equal(firstCount, 3, "first clean probe should run the existing conflict checks");
+
+    const second = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(second.ok, true);
+    assert.equal(
+      countGitShimInvocations(logPath),
+      firstCount,
+      "second clean probe within the cache window must not spawn git again",
+    );
+  } finally {
+    if (originalProcessPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalProcessPath;
+    if (originalEnvPath === undefined) delete GIT_NO_PROMPT_ENV.PATH;
+    else GIT_NO_PROMPT_ENV.PATH = originalEnvPath;
+    if (originalEnvGitLog === undefined) delete GIT_NO_PROMPT_ENV.GSD_GIT_LOG;
+    else GIT_NO_PROMPT_ENV.GSD_GIT_LOG = originalEnvGitLog;
+    if (originalEnvRealPath === undefined) delete GIT_NO_PROMPT_ENV.GSD_REAL_PATH;
+    else GIT_NO_PROMPT_ENV.GSD_REAL_PATH = originalEnvRealPath;
+    cleanup(binDir);
+    cleanup(base);
+  }
+});
+
+test("ensureWorkspaceGitReadyForPath detects merge state that appears after a clean probe", async () => {
+  const base = makeTempRepo("gsd-ws-git-cache-stale-");
+  const binDir = makeTempDir("gsd-ws-git-shim2-");
+  const logPath = join(binDir, "git2.log");
+  const originalProcessPath = process.env.PATH;
+  const originalEnvPath = GIT_NO_PROMPT_ENV.PATH;
+  const originalEnvGitLog = GIT_NO_PROMPT_ENV.GSD_GIT_LOG;
+  const originalEnvRealPath = GIT_NO_PROMPT_ENV.GSD_REAL_PATH;
+
+  try {
+    installCountingGitShim(binDir, logPath);
+    const shimmedPath = `${binDir}${delimiter}${originalProcessPath ?? ""}`;
+    process.env.PATH = shimmedPath;
+    GIT_NO_PROMPT_ENV.PATH = shimmedPath;
+    GIT_NO_PROMPT_ENV.GSD_GIT_LOG = logPath;
+    GIT_NO_PROMPT_ENV.GSD_REAL_PATH = originalProcessPath ?? "";
+
+    // First call — repo is clean, cache is populated.
+    const first = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(first.ok, true);
+    const afterFirstCount = countGitShimInvocations(logPath);
+    assert.ok(afterFirstCount > 0, "first probe must have called git");
+
+    // Introduce MERGE_HEAD to simulate merge state appearing mid-TTL window.
+    writeFileSync(join(base, ".git", "MERGE_HEAD"), "0000000000000000000000000000000000000000\n");
+
+    // Second call — cache should be bypassed because merge state markers are present.
+    await ensureWorkspaceGitReadyForPath(base);
+    const afterSecondCount = countGitShimInvocations(logPath);
+    assert.ok(
+      afterSecondCount > afterFirstCount,
+      "cache must be invalidated when merge state appears, causing a fresh git probe",
+    );
+  } finally {
+    if (originalProcessPath === undefined) delete process.env.PATH;
+    else process.env.PATH = originalProcessPath;
+    if (originalEnvPath === undefined) delete GIT_NO_PROMPT_ENV.PATH;
+    else GIT_NO_PROMPT_ENV.PATH = originalEnvPath;
+    if (originalEnvGitLog === undefined) delete GIT_NO_PROMPT_ENV.GSD_GIT_LOG;
+    else GIT_NO_PROMPT_ENV.GSD_GIT_LOG = originalEnvGitLog;
+    if (originalEnvRealPath === undefined) delete GIT_NO_PROMPT_ENV.GSD_REAL_PATH;
+    else GIT_NO_PROMPT_ENV.GSD_REAL_PATH = originalEnvRealPath;
+    cleanup(binDir);
+    cleanup(base);
+  }
+});
+
+test("ensureWorkspaceGitReadyForPath detects conflicts after a non-git folder becomes a repo", async () => {
+  const base = makeTempDir("gsd-ws-git-non-repo-cache-");
+  try {
+    const first = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(first.ok, true);
+
+    git(base, "init");
+    git(base, "config", "user.email", "test@test.com");
+    git(base, "config", "user.name", "Test");
+    git(base, "config", "core.autocrlf", "false");
+    writeFileSync(join(base, "README.md"), "# init\n");
+    git(base, "add", "-A");
+    git(base, "commit", "-m", "init");
+    git(base, "branch", "-M", "main");
+    seedProductConflict(base);
+
+    const second = await ensureWorkspaceGitReadyForPath(base);
+    assert.equal(second.ok, false);
+    if (second.ok) return;
+    assert.equal(second.severity, "product-conflicts");
+    assert.ok(second.conflictedPaths.includes("app.ts"));
+  } finally {
+    cleanup(base);
+  }
+});
+
 test("ensureWorkspaceGitReadyForPath allows fresh non-git project setup folders", async () => {
   const base = makeTempDir("gsd-ws-git-non-repo-");
   try {