@opengsd/gsd-pi 1.3.0 → 1.4.0-dev.c18009cd

package/src/resources/extensions/gsd/tests/workflow-tool-executors.test.ts

@@ -12,6 +12,8 @@ import {
   getArtifact,
   getAssessment,
   insertAssessment,
+  insertGateRow,
+  insertMilestone,
   upsertRequirement,
   getAllMilestones,
 } from "../gsd-db.ts";
@@ -20,6 +22,7 @@ import { claimMilestoneLease, getMilestoneLease } from "../db/milestone-leases.t
 import { deriveState, invalidateStateCache } from "../state.ts";
 import { autoSession } from "../auto-runtime-state.ts";
 import { normalizeRealPath } from "../paths.ts";
+import { recordUnitHarnessAbort } from "../unit-runtime.ts";
 import { markApprovalGateVerified, markDepthVerified, clearDiscussionFlowState, loadWriteGateSnapshot, setPendingGate } from "../bootstrap/write-gate.ts";
 import {
   executeCompleteMilestone,
@@ -36,6 +39,11 @@ import {
   executeValidateMilestone,
   executeUatResultSave,
 } from "../tools/workflow-tool-executors.ts";
+import {
+  initNotificationStore,
+  readNotifications,
+  _resetNotificationStore,
+} from "../notification-store.ts";
 
 function makeTmpBase(): string {
   const base = join(tmpdir(), `gsd-workflow-executors-${randomUUID()}`);
@@ -153,9 +161,9 @@ test("executeSummarySave persists artifact and returns computed path", async ()
     }, base));
 
     assert.equal(result.details.operation, "save_summary");
-    assert.equal(result.details.path, "milestones/M001/slices/S01/S01-SUMMARY.md");
+    assert.equal(result.details.path, "phases/01-m001/01-01-SUMMARY.md");
 
-    const filePath = join(base, ".gsd", "milestones", "M001", "slices", "S01", "S01-SUMMARY.md");
+    const filePath = join(base, ".gsd", "phases", "01-m001", "01-01-SUMMARY.md");
     assert.ok(existsSync(filePath), "summary artifact should be written to disk");
     assert.match(readFileSync(filePath, "utf-8"), /# Summary/);
   } finally {
@@ -180,7 +188,7 @@ test("executeSummarySave mirrors milestone artifacts into the active worktree pr
     }, worktree));
 
     assert.equal(result.details.operation, "save_summary");
-    const relPath = "milestones/M001/slices/S02/S02-RESEARCH.md";
+    const relPath = "phases/01-m001/01-02-RESEARCH.md";
     const projectPath = join(base, ".gsd", relPath);
     const worktreePath = join(worktree, ".gsd", relPath);
     assert.equal(existsSync(projectPath), true, "canonical artifact should be written");
@@ -780,22 +788,23 @@ test("executePlanSlice writes task planning state and rendered plan artifacts",
   }
 });
 
-test("executePlanSlice marks validation failures with isError", async () => {
+test("executePlanSlice accepts metadata-only incremental planning payloads", async () => {
   const base = makeTmpBase();
   try {
     openTestDb(base);
+    await inProjectDir(base, () => executePlanMilestone(validMilestonePlan(), base));
 
     const result = await inProjectDir(base, () => executePlanSlice({
       milestoneId: "M001",
       sliceId: "S01",
-      goal: "Trigger validation failure for empty tasks.",
+      goal: "Persist slice metadata before tasks.",
       tasks: [],
     }, base));
 
-    assert.equal(result.isError, true);
     assert.equal(result.details.operation, "plan_slice");
-    assert.match(String(result.details.error), /validation failed: tasks must be a non-empty array/);
-    assert.match(result.content[0].text, /Error planning slice:/);
+    assert.equal(result.details.sliceId, "S01");
+    assert.equal(result.isError, undefined);
+    assert.match(result.content[0].text, /Planned slice S01/);
   } finally {
     closeDatabase();
     cleanup(base);
@@ -889,7 +898,7 @@ test("executeUatResultSave accepts gsd_uat_exec evidence written in a milestone
     assert.equal(attempt.browserToolsPresented, false);
     assert.deepEqual(attempt.modePolicy?.requiredAnyModes, ["runtime"]);
     const assessment = readFileSync(
-      join(base, ".gsd", "milestones", "M001", "slices", "S02", "S02-ASSESSMENT.md"),
+      join(base, ".gsd", "phases", "01-m001", "01-02-ASSESSMENT.md"),
       "utf-8",
     );
     assert.match(assessment, /runId: uat:M001:S02:attempt-1/);
@@ -897,7 +906,7 @@ test("executeUatResultSave accepts gsd_uat_exec evidence written in a milestone
     assert.match(assessment, /Runtime path C:\\\\tmp\\\|uat evidence/);
     assert.match(assessment, /backslash \\\\ and pipe \\\|/);
 
-    const artifactPath = "milestones/M001/slices/S02/S02-ASSESSMENT.md";
+    const artifactPath = "phases/01-m001/01-02-ASSESSMENT.md";
     const assessmentPath = `.gsd/${artifactPath}`;
     assert.equal(getArtifact(artifactPath)?.artifact_type, "ASSESSMENT");
     assert.equal(getAssessment(assessmentPath)?.scope, "run-uat");
@@ -908,6 +917,104 @@ test("executeUatResultSave accepts gsd_uat_exec evidence written in a milestone
   }
 });
 
+test("executeUatResultSave leaves UAT pending after a harness-aborted turn", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "harness-aborted-uat-evidence";
+  const startedAt = Date.now();
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S04", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S04",
+          checkId: "UAT-01",
+          intent: "uat-runtime-check",
+        },
+      }),
+      "utf-8",
+    );
+    _getAdapter()!.prepare(
+      `INSERT INTO quality_gates (milestone_id, slice_id, gate_id, scope, task_id, status)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+    ).run("M001", "S04", "UAT", "slice", "", "pending");
+    autoSession.reset();
+    autoSession.active = true;
+    autoSession.basePath = base;
+    autoSession.currentUnit = { type: "run-uat", id: "M001/S04", startedAt, workspaceRoot: worktree };
+    recordUnitHarnessAbort(base, "run-uat", "M001/S04", startedAt, {
+      kind: "tool-loop-guard",
+      reason: "Tool loop detected (repeated tool): browser_click called 7 times this turn.",
+      toolName: "browser_click",
+      count: 7,
+    });
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S04",
+      uatType: "runtime-executable",
+      verdict: "FAIL",
+      checks: [{
+        id: "UAT-01",
+        description: "Runtime behavior could not be fully evaluated before harness abort",
+        mode: "runtime",
+        result: "FAIL",
+        evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+        notes: "Partial failure should be retried because the harness aborted the turn.",
+      }],
+      presentation: {
+        surface: "mcp",
+        presentedTools: [
+          "gsd_uat_exec",
+          "gsd_uat_result_save",
+          "gsd_resume",
+          "gsd_milestone_status",
+          "gsd_journal_query",
+        ],
+        blockedTools: [
+          { name: "gsd_exec", reason: "forbidden during run-uat" },
+          { name: "gsd_summary_save", reason: "forbidden during run-uat" },
+          { name: "gsd_save_gate_result", reason: "forbidden during run-uat" },
+        ],
+      },
+      notes: "Partial UAT result after harness abort.",
+    }, worktree));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.operation, "save_uat_result");
+    assert.equal(result.details.error, "harness_aborted_needs_retry");
+    assert.equal(result.details.retryable, true);
+    assert.equal(result.details.harnessAbortKind, "tool-loop-guard");
+    assert.equal(
+      existsSync(join(base, ".gsd", "uat", "M001", "S04", "attempt-1.json")),
+      false,
+      "harness-aborted UAT should not persist an attempt artifact",
+    );
+    assert.equal(
+      existsSync(join(base, ".gsd", "phases", "01-m001", "01-04-ASSESSMENT.md")),
+      false,
+      "harness-aborted UAT should not write an ASSESSMENT verdict",
+    );
+    const row = _getAdapter()!.prepare(
+      "SELECT status, verdict FROM quality_gates WHERE milestone_id = ? AND slice_id = ? AND gate_id = ?",
+    ).get("M001", "S04", "UAT") as Record<string, unknown>;
+    assert.equal(row.status, "pending");
+    assert.equal(row.verdict, "");
+  } finally {
+    autoSession.reset();
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeUatResultSave supplies canonical presentation and normalizes verdict casing", async () => {
   const base = makeTmpBase();
   const worktree = join(base, ".gsd", "worktrees", "M001");
@@ -1098,13 +1205,14 @@ test("executeUatResultSave merges canonical plan ID and read-only tools when pre
   }
 });
 
-test("executeUatResultSave surfaces the worktree validation path for NEEDS-HUMAN checks", async () => {
+test("executeUatResultSave surfaces the worktree validation path and notification for NEEDS-HUMAN checks", async () => {
   const base = makeTmpBase();
   const worktree = join(base, ".gsd", "worktrees", "M001");
   const worktreeExecDir = join(worktree, ".gsd", "exec");
   const evidenceId = "uat-human-validation-evidence";
   try {
     openTestDb(base);
+    initNotificationStore(base);
     seedMilestone("M001", "Milestone One");
     seedSlice("M001", "S07", "complete");
     mkdirSync(worktreeExecDir, { recursive: true });
@@ -1158,13 +1266,23 @@ test("executeUatResultSave surfaces the worktree validation path for NEEDS-HUMAN
     assert.ok(returnedText.includes(worktree), "tool return should include the worktree path");
 
     const assessment = readFileSync(
-      join(base, ".gsd", "milestones", "M001", "slices", "S07", "S07-ASSESSMENT.md"),
+      join(base, ".gsd", "phases", "01-m001", "01-07-ASSESSMENT.md"),
       "utf-8",
     );
     assert.match(assessment, /## Manual Validation/);
     assert.ok(assessment.includes(worktree), "assessment should include the worktree checkout path");
     assert.match(assessment, /git worktree/);
+
+    const notifications = readNotifications(base, { kind: "uat-needs-human", scope: "M001/S07" });
+    assert.equal(notifications.length, 1);
+    assert.equal(notifications[0].severity, "warning");
+    assert.equal(notifications[0].source, "notify");
+    assert.equal(
+      notifications[0].message,
+      "UAT for M001/S07 has NEEDS-HUMAN checks awaiting human validation",
+    );
   } finally {
+    _resetNotificationStore();
     closeDatabase();
     cleanup(base);
   }
@@ -1217,7 +1335,7 @@ test("executeUatResultSave omits manual-validation guidance when no human checks
     assert.equal(returnedText.includes("Manual validation needed"), false);
 
     const assessment = readFileSync(
-      join(base, ".gsd", "milestones", "M001", "slices", "S08", "S08-ASSESSMENT.md"),
+      join(base, ".gsd", "phases", "01-m001", "01-08-ASSESSMENT.md"),
       "utf-8",
     );
     assert.equal(assessment.includes("## Manual Validation"), false);
@@ -1746,7 +1864,8 @@ test("executeSaveGateResult validates inputs and persists verdicts", async () =>
     assert.equal(row?.status, "complete");
     assert.equal(row?.verdict, "pass");
     assert.equal(row?.rationale, "Looks good.");
-    const planPath = join(base, ".gsd", "milestones", "M005", "slices", "S05", "S05-PLAN.md");
+    // Flat-phase: M005 title "Milestone Five" → phases/05-milestone-five/05-05-PLAN.md
+    const planPath = join(base, ".gsd", "phases", "05-milestone-five", "05-05-PLAN.md");
     assert.match(readFileSync(planPath, "utf-8"), /No issues found\./);
   } finally {
     closeDatabase();
@@ -1754,6 +1873,97 @@ test("executeSaveGateResult validates inputs and persists verdicts", async () =>
   }
 });
 
+test("executeSaveGateResult leaves quality gates pending after a retryable tool error", async () => {
+  const base = makeTmpBase();
+  const startedAt = Date.now();
+  try {
+    openTestDb(base);
+    seedMilestone("M005", "Milestone Five");
+    seedSlice("M005", "S05", "pending");
+    insertGateRow({ milestoneId: "M005", sliceId: "S05", gateId: "Q3", scope: "slice" });
+    autoSession.reset();
+    autoSession.active = true;
+    autoSession.basePath = base;
+    autoSession.currentUnit = { type: "plan-slice", id: "M005/S05", startedAt };
+    recordUnitHarnessAbort(base, "plan-slice", "M005/S05", startedAt, {
+      kind: "tool-error",
+      reason: "Input validation error: selector is required",
+      toolName: "browser_click",
+    });
+
+    const result = await inProjectDir(base, () => executeSaveGateResult({
+      milestoneId: "M005",
+      sliceId: "S05",
+      gateId: "Q3",
+      verdict: "flag",
+      rationale: "Partial gate failure after harness abort.",
+      findings: "This should not be persisted as a product-quality finding.",
+    }, base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.operation, "save_gate_result");
+    assert.equal(result.details.error, "harness_aborted_needs_retry");
+    assert.equal(result.details.retryable, true);
+    assert.equal(result.details.harnessAbortKind, "tool-error");
+    const row = _getAdapter()!.prepare(
+      "SELECT status, verdict, rationale, findings FROM quality_gates WHERE milestone_id = ? AND slice_id = ? AND gate_id = ? AND task_id = ''",
+    ).get("M005", "S05", "Q3") as Record<string, unknown>;
+    assert.equal(row.status, "pending");
+    assert.equal(row.verdict, "");
+    assert.equal(row.rationale, "");
+    assert.equal(row.findings, "");
+  } finally {
+    autoSession.reset();
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeSaveGateResult leaves quality gates pending after a turn abort", async () => {
+  const base = makeTmpBase();
+  const startedAt = Date.now();
+  try {
+    openTestDb(base);
+    seedMilestone("M005", "Milestone Five");
+    seedSlice("M005", "S05", "pending");
+    insertGateRow({ milestoneId: "M005", sliceId: "S05", gateId: "Q3", scope: "slice" });
+    autoSession.reset();
+    autoSession.active = true;
+    autoSession.basePath = base;
+    autoSession.currentUnit = { type: "plan-slice", id: "M005/S05", startedAt };
+    recordUnitHarnessAbort(base, "plan-slice", "M005/S05", startedAt, {
+      kind: "turn-abort",
+      reason: "Agent turn aborted before the gate evaluation completed. origin=timeout stopReason=aborted",
+    });
+
+    const result = await inProjectDir(base, () => executeSaveGateResult({
+      milestoneId: "M005",
+      sliceId: "S05",
+      gateId: "Q3",
+      verdict: "flag",
+      rationale: "Partial gate failure after a turn abort.",
+      findings: "This should not be persisted as a product-quality finding.",
+    }, base));
+
+    assert.equal(result.isError, true);
+    assert.equal(result.details.operation, "save_gate_result");
+    assert.equal(result.details.error, "harness_aborted_needs_retry");
+    assert.equal(result.details.retryable, true);
+    assert.equal(result.details.harnessAbortKind, "turn-abort");
+    const row = _getAdapter()!.prepare(
+      "SELECT status, verdict, rationale, findings FROM quality_gates WHERE milestone_id = ? AND slice_id = ? AND gate_id = ? AND task_id = ''",
+    ).get("M005", "S05", "Q3") as Record<string, unknown>;
+    assert.equal(row.status, "pending");
+    assert.equal(row.verdict, "");
+    assert.equal(row.rationale, "");
+    assert.equal(row.findings, "");
+  } finally {
+    autoSession.reset();
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeSaveGateResult fails when no canonical gate row is updated", async () => {
   const base = makeTmpBase();
   try {
@@ -2047,6 +2257,60 @@ test("executeSummarySave registers PROJECT milestone sequence for the next run",
   }
 });
 
+test("executeSummarySave reconciles bare PROJECT milestone IDs onto existing unique-ID rows (no phantom row) (#807)", async () => {
+  const base = makeTmpBase();
+  try {
+    openTestDb(base);
+
+    // Planner already minted a unique-ID milestone for sequence 1.
+    insertMilestone({ id: "M001-b1nole", title: "Foundation", status: "active" });
+
+    // A faithfully-authored PROJECT.md uses the template's bare sequence IDs.
+    const result = await inProjectDir(base, () => executeSummarySave({
+      artifact_type: "PROJECT",
+      content: [
+        "# Project",
+        "",
+        "## What This Is",
+        "",
+        "Deep project setup output.",
+        "",
+        "## Project Shape",
+        "",
+        "**Complexity:** complex",
+        "**Why:** It spans multiple delivery steps.",
+        "",
+        "## Capability Contract",
+        "",
+        "See .gsd/REQUIREMENTS.md.",
+        "",
+        "## Milestone Sequence",
+        "",
+        "- [ ] M001: Foundation - Establish the first runnable slice.",
+        "- [ ] M002: Polish - Follow-up experience work.",
+        "",
+      ].join("\n"),
+    }, base));
+
+    assert.equal(result.isError, undefined);
+    // Bare M001 maps onto the planner's canonical row; M002 is genuinely new.
+    assert.deepEqual(result.details.registeredMilestones, ["M001-b1nole", "M002"]);
+
+    const milestones = getAllMilestones();
+    // No phantom bare "M001" row — the unique-ID row is preserved and not demoted.
+    assert.deepEqual(
+      milestones.map((m) => [m.id, m.title, m.status]).sort(),
+      [
+        ["M001-b1nole", "Foundation", "active"],
+        ["M002", "Polish", "queued"],
+      ].sort(),
+    );
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeSummarySave hard-fails when milestone registration throws so silent No-Active-Milestone is impossible", async () => {
   const base = makeTmpBase();
   try {

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 {

package/src/resources/extensions/gsd/tests/workspace.test.ts

@@ -8,6 +8,7 @@ import {
   rmSync,
   realpathSync,
   symlinkSync,
+  writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -118,17 +119,17 @@ describe("scopeMilestone path methods", () => {
     rmSync(projectDir, { recursive: true, force: true });
   });
 
-  test("produces correct paths for a known milestone ID", () => {
+  test("produces flat-phase paths for a known milestone ID", () => {
     const ws = createWorkspace(projectDir);
     const scope = scopeMilestone(ws, MID);
     const gsd = ws.contract.projectGsd;
 
     assert.equal(scope.milestoneId, MID);
-    assert.equal(scope.contextFile(), join(gsd, "milestones", MID, `${MID}-CONTEXT.md`));
-    assert.equal(scope.roadmapFile(), join(gsd, "milestones", MID, `${MID}-ROADMAP.md`));
+    assert.equal(scope.contextFile(), join(gsd, "phases", "01-m001", "01-CONTEXT.md"));
+    assert.equal(scope.roadmapFile(), join(gsd, "phases", "01-m001", "01-ROADMAP.md"));
     assert.equal(scope.stateFile(), join(gsd, "STATE.md"));
     assert.equal(scope.dbPath(), ws.contract.projectDb);
-    assert.equal(scope.milestoneDir(), join(gsd, "milestones", MID));
+    assert.equal(scope.milestoneDir(), join(gsd, "phases", "01-m001"));
     assert.equal(scope.metaJson(), join(gsd, `${MID}-META.json`));
   });
 
@@ -144,6 +145,19 @@ describe("scopeMilestone path methods", () => {
     assert.equal(scope1.milestoneDir(), scope2.milestoneDir());
     assert.equal(scope1.metaJson(), scope2.metaJson());
   });
+
+  test("uses legacy milestone paths when legacy content exists", () => {
+    const legacyDir = join(projectDir, ".gsd", "milestones", MID);
+    mkdirSync(legacyDir, { recursive: true });
+    writeFileSync(join(legacyDir, `${MID}-CONTEXT.md`), "# Legacy context\n");
+
+    const ws = createWorkspace(projectDir);
+    const scope = scopeMilestone(ws, MID);
+
+    assert.equal(scope.contextFile(), join(legacyDir, `${MID}-CONTEXT.md`));
+    assert.equal(scope.roadmapFile(), join(legacyDir, `${MID}-ROADMAP.md`));
+    assert.equal(scope.milestoneDir(), legacyDir);
+  });
 });
 
 describe("createWorkspace: contract.projectGsd is realpath-canonicalized when basePath is a symlink", () => {