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

package/src/resources/extensions/gsd/tests/file-lock.test.ts

@@ -114,6 +114,49 @@ test("withFileLockSync: onLocked=\"skip\" runs callback unlocked on ELOCKED", ()
   }
 });
 
+test("withFileLockSync: onLocked=\"skip\" does not sleep through retries before fallback", () => {
+  if (!hasProperLockfile() || process.platform === "win32") {
+    return;
+  }
+
+  const lockfile = require("proper-lockfile");
+  const dir = mkdtempSync(join(tmpdir(), "gsd-file-lock-test-"));
+  const filePath = join(dir, "locked.jsonl");
+  writeFileSync(filePath, "{}\n", "utf-8");
+
+  const release = lockfile.lockSync(filePath, { retries: 0, stale: 10000 });
+  const waitDescriptor = Object.getOwnPropertyDescriptor(Atomics, "wait");
+  assert.ok(waitDescriptor, "Atomics.wait descriptor should exist");
+  let sleepCalls = 0;
+
+  Object.defineProperty(Atomics, "wait", {
+    ...waitDescriptor,
+    value: () => {
+      sleepCalls++;
+      throw new Error("skip fallback must not wait before running callback");
+    },
+  });
+
+  try {
+    let called = 0;
+    const result = withFileLockSync(
+      filePath,
+      () => {
+        called++;
+        return "fallback-ok";
+      },
+      { onLocked: "skip" },
+    );
+    assert.equal(result, "fallback-ok");
+    assert.equal(called, 1, "callback should run when onLocked is skip");
+    assert.equal(sleepCalls, 0, "skip path must not block on retry sleeps");
+  } finally {
+    Object.defineProperty(Atomics, "wait", waitDescriptor);
+    release();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
 test("withFileLock: throws ELOCKED by default (no silent fallback)", async () => {
   if (!hasProperLockfile() || process.platform === "win32") {
     return;

package/src/resources/extensions/gsd/tests/flat-phase-migration.test.ts

@@ -0,0 +1,186 @@
+// Project/App: gsd-pi
+// File Purpose: Tests the one-time migration from nested to flat-phase layout.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, renameSync, rmSync, writeFileSync, existsSync, readdirSync, readFileSync, utimesSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import {
+  _setFlatPhaseMigrationFsOpsForTest,
+  migrateToFlatPhase,
+  needsFlatPhaseMigration,
+  pruneStaleFlatPhaseBackups,
+} from "../flat-phase-migration.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask, getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.ts";
+
+const tmpDirs: string[] = [];
+function makeTmp(options: { withTask?: boolean } = {}): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-mig-${randomUUID()}`));
+  // Create legacy nested structure
+  const sliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  mkdirSync(
+    options.withTask === false ? join(sliceDir, "tasks") : join(sliceDir, "tasks", "T01"),
+    { recursive: true },
+  );
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({
+    milestoneId: "M001", id: "S01", title: "Set up tooling", status: "pending",
+    risk: "low", depends: [], demo: "build runs", sequence: 1,
+  });
+  if (options.withTask !== false) {
+    insertTask({
+      milestoneId: "M001", sliceId: "S01", id: "T01", title: "Init repo",
+      status: "pending", sequence: 1,
+    });
+  }
+  tmpDirs.push(base);
+  return base;
+}
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+test("needsFlatPhaseMigration returns true when .gsd/milestones/ exists", () => {
+  const base = makeTmp();
+  assert.equal(needsFlatPhaseMigration(base), true);
+});
+
+test("needsFlatPhaseMigration returns false when no .gsd/milestones/", () => {
+  const base = mkdtempSync(join(tmpdir(), `gsd-nomig-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd", "phases"), { recursive: true });
+  tmpDirs.push(base);
+  assert.equal(needsFlatPhaseMigration(base), false);
+});
+
+test("migrateToFlatPhase moves content from milestones/ to phases/", async () => {
+  const base = makeTmp();
+  await migrateToFlatPhase(base);
+
+  assert.ok(existsSync(join(base, ".gsd", "phases")), "phases/ should exist");
+  assert.ok(!existsSync(join(base, ".gsd", "milestones")), "milestones/ should be removed");
+});
+
+test("migrateToFlatPhase ignores and removes stale phase dirs from prior aborted runs", async () => {
+  const base = makeTmp();
+  const stalePhaseDir = join(base, ".gsd", "phases", "99-stale-aborted-run");
+  mkdirSync(stalePhaseDir, { recursive: true });
+
+  await migrateToFlatPhase(base);
+
+  assert.ok(existsSync(join(base, ".gsd", "phases", "01-foundation")), "current DB phase should render");
+  assert.equal(existsSync(stalePhaseDir), false, "stale pre-existing phase dir should be removed");
+});
+
+test("migrateToFlatPhase falls back to copy-delete when legacy rename is blocked", async (t) => {
+  const base = makeTmp();
+  const milestonesPath = join(base, ".gsd", "milestones");
+  const migratingPath = join(base, ".gsd", "milestones.migrating");
+  let blockedRenameAttempts = 0;
+
+  const restoreFsOps = _setFlatPhaseMigrationFsOpsForTest({
+    renameSync(src, dst) {
+      if (src === milestonesPath && dst === migratingPath) {
+        blockedRenameAttempts++;
+        throw Object.assign(new Error("simulated busy handle"), { code: "EPERM" });
+      }
+      return renameSync(src, dst);
+    },
+  });
+  t.after(restoreFsOps);
+
+  await migrateToFlatPhase(base);
+
+  assert.equal(blockedRenameAttempts, 1, "test should exercise the rename fallback path");
+  assert.ok(existsSync(join(base, ".gsd", "phases", "01-foundation")), "flat phase should render");
+  assert.equal(existsSync(milestonesPath), false, "legacy milestones dir should be removed");
+  assert.equal(existsSync(migratingPath), false, "staging dir should be removed after success");
+});
+
+test("migrateToFlatPhase creates a backup", async () => {
+  const base = makeTmp();
+  await migrateToFlatPhase(base);
+  assert.ok(existsSync(join(base, ".gsd-backups")), "backup should exist");
+  const backups = readdirSync(join(base, ".gsd-backups")).filter(d => d.startsWith("migrate-"));
+  assert.ok(backups.length >= 1, "at least one migrate-* backup dir should exist");
+});
+
+test("migrateToFlatPhase preserves milestone/slice/task counts in DB", async () => {
+  const base = makeTmp();
+  const msBefore = getAllMilestones().length;
+  const slicesBefore = getMilestoneSlices("M001").length;
+  const tasksBefore = getSliceTasks("M001", "S01").length;
+  await migrateToFlatPhase(base);
+  assert.equal(getAllMilestones().length, msBefore);
+  assert.equal(getMilestoneSlices("M001").length, slicesBefore);
+  assert.equal(getSliceTasks("M001", "S01").length, tasksBefore);
+});
+
+test("migrateToFlatPhase is idempotent (second run is a no-op)", async () => {
+  const base = makeTmp();
+  await migrateToFlatPhase(base);
+  // Second run should not throw and should not create a second backup
+  await migrateToFlatPhase(base);
+  const backups = readdirSync(join(base, ".gsd-backups")).filter(d => d.startsWith("migrate-"));
+  assert.equal(backups.length, 1, "should only have one backup");
+});
+
+test("migrateToFlatPhase preserves slice sidecar artifacts and skips recovery placeholder PLAN", async () => {
+  const base = makeTmp({ withTask: false });
+  const legacySliceDir = join(base, ".gsd", "milestones", "M001", "slices", "S01");
+  writeFileSync(join(legacySliceDir, "S01-CONTEXT.md"), "# Final Slice Context\n\nPrior discussion.", "utf-8");
+  writeFileSync(join(legacySliceDir, "S01-RESEARCH.md"), "# Slice Research\n\nPrior research.", "utf-8");
+  writeFileSync(join(legacySliceDir, "S01-CONTINUE.md"), "# Continue\n\nCompacted marker.", "utf-8");
+  writeFileSync(
+    join(legacySliceDir, "S01-PLAN.md"),
+    "# BLOCKER - auto-mode recovery failed\n\nUnit `plan-slice` failed to produce this artifact.",
+    "utf-8",
+  );
+
+  await migrateToFlatPhase(base);
+
+  const phaseDir = join(base, ".gsd", "phases", "01-foundation");
+  assert.equal(readFileSync(join(phaseDir, "01-01-CONTEXT.md"), "utf-8"), "# Final Slice Context\n\nPrior discussion.");
+  assert.equal(readFileSync(join(phaseDir, "01-01-RESEARCH.md"), "utf-8"), "# Slice Research\n\nPrior research.");
+  assert.equal(readFileSync(join(phaseDir, "01-01-CONTINUE.md"), "utf-8"), "# Continue\n\nCompacted marker.");
+  assert.equal(
+    existsSync(join(phaseDir, "01-01-PLAN.md")),
+    false,
+    "recovery placeholder PLAN should not be promoted when no DB tasks can render a real plan",
+  );
+});
+
+test("pruneStaleFlatPhaseBackups removes migrate-* dirs older than retention window", async () => {
+  const base = makeTmp();
+  await migrateToFlatPhase(base);
+
+  const backupRoot = join(base, ".gsd-backups");
+  assert.ok(existsSync(backupRoot), "backup should exist immediately after migration");
+
+  const staleDir = join(backupRoot, "migrate-stale");
+  mkdirSync(staleDir, { recursive: true });
+  writeFileSync(join(staleDir, "marker.txt"), "old backup\n", "utf-8");
+  const staleDate = new Date(Date.now() - 31 * 24 * 60 * 60 * 1000);
+  utimesSync(staleDir, staleDate, staleDate);
+
+  const removed = pruneStaleFlatPhaseBackups(base);
+  assert.equal(removed, 1, "stale migrate-* dir should be pruned");
+  assert.equal(existsSync(staleDir), false, "stale backup dir should be gone");
+  assert.ok(existsSync(backupRoot), "fresh migration backup should remain");
+});
+
+test("pruneStaleFlatPhaseBackups is a no-op while flat-phase migration is still needed", () => {
+  const base = makeTmp();
+  const backupRoot = join(base, ".gsd-backups", "migrate-stale");
+  mkdirSync(backupRoot, { recursive: true });
+  writeFileSync(join(backupRoot, "marker.txt"), "old backup\n", "utf-8");
+  const staleDate = new Date(Date.now() - 31 * 24 * 60 * 60 * 1000);
+  utimesSync(backupRoot, staleDate, staleDate);
+
+  assert.equal(pruneStaleFlatPhaseBackups(base), 0, "must not prune while migration is pending");
+  assert.ok(existsSync(backupRoot), "backup must remain until migration completes");
+});

package/src/resources/extensions/gsd/tests/flat-phase-renderer.test.ts

@@ -0,0 +1,83 @@
+// Project/App: gsd-pi
+// File Purpose: Verifies the renderer emits flat-phase paths and tasks-as-checkboxes.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { renderPlanFromDb, renderRoadmapFromDb } from "../markdown-renderer.ts";
+import { openDatabase, closeDatabase, insertMilestone, insertSlice, insertTask } from "../gsd-db.ts";
+
+const tmpDirs: string[] = [];
+function makeTmp(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-fp-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  insertMilestone({ id: "M001", title: "Foundation", status: "active" });
+  insertSlice({
+    milestoneId: "M001", id: "S01", title: "Set up tooling", status: "pending",
+    risk: "low", depends: [], demo: "build runs", sequence: 1,
+  });
+  insertTask({
+    milestoneId: "M001", sliceId: "S01", id: "T01", title: "Init repo",
+    status: "pending", sequence: 1,
+    planning: { estimate: "30m" },
+  });
+  tmpDirs.push(base);
+  return base;
+}
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+test("renderRoadmapFromDb writes to .gsd/phases/ not .gsd/milestones/", async () => {
+  const base = makeTmp();
+  await renderRoadmapFromDb(base, "M001");
+  const phasesDir = join(base, ".gsd", "phases");
+  const milestonesDir = join(base, ".gsd", "milestones");
+  assert.ok(existsSync(phasesDir), "expected .gsd/phases/ to exist");
+  assert.ok(!existsSync(milestonesDir), "expected .gsd/milestones/ to NOT exist");
+});
+
+test("renderPlanFromDb writes NN-MM-PLAN.md inside the phase dir", async () => {
+  const base = makeTmp();
+  const result = await renderPlanFromDb(base, "M001", "S01");
+  assert.match(result.planPath, /phases[/\\]01-[^/\\]+[/\\]01-01-PLAN\.md$/);
+  assert.ok(existsSync(result.planPath), "plan file should exist on disk");
+});
+
+test("renderPlanFromDb emits <tasks> block with task checkboxes", async () => {
+  const base = makeTmp();
+  const result = await renderPlanFromDb(base, "M001", "S01");
+  const plan = readFileSync(result.planPath, "utf-8");
+  assert.match(plan, /<tasks>/);
+  assert.match(plan, /<\/tasks>/);
+  assert.match(plan, /- \[ \] \*\*T01\*\*: Init repo/);
+});
+
+test("renderPlanFromDb does NOT create a tasks/ subdir", async () => {
+  const base = makeTmp();
+  await renderPlanFromDb(base, "M001", "S01");
+  const phasesDir = join(base, ".gsd", "phases");
+  const scanForTasksDir = (dir: string): boolean => {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isDirectory()) {
+        if (e.name === "tasks") return true;
+        if (scanForTasksDir(join(dir, e.name))) return true;
+      }
+    }
+    return false;
+  };
+  assert.ok(!scanForTasksDir(phasesDir), "no tasks/ subdir should exist under phases/");
+});
+
+test("renderPlanFromDb does NOT write per-task plan files", async () => {
+  const base = makeTmp();
+  const result = await renderPlanFromDb(base, "M001", "S01");
+  // taskPlanPaths should be empty — no per-task files written
+  assert.equal(result.taskPlanPaths.length, 0);
+});

package/src/resources/extensions/gsd/tests/flat-phase-round-trip.test.ts

@@ -0,0 +1,72 @@
+// Project/App: gsd-pi
+// File Purpose: Round-trip property test for the flat-phase layout.
+// import → render → import must produce stable milestone/slice/task hierarchy.
+import test, { afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { cpSync, mkdtempSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
+
+import { openDatabase, closeDatabase, getAllMilestones, getMilestoneSlices, getSliceTasks } from "../gsd-db.ts";
+import { migrateHierarchyToDb } from "../md-importer.ts";
+import { renderAllFromDb } from "../markdown-renderer.ts";
+import { invalidateStateCache } from "../state.ts";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_ROOT = join(__dirname, "__fixtures__", "flat-phase");
+const tmpDirs: string[] = [];
+afterEach(() => {
+  closeDatabase();
+  for (const d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+function copyFixture(): string {
+  const base = mkdtempSync(join(tmpdir(), `gsd-fprt-${randomUUID()}`));
+  cpSync(FIXTURE_ROOT, base, { recursive: true });
+  tmpDirs.push(base);
+  return base;
+}
+
+test("flat-phase round-trip: import → render → import is stable", async () => {
+  const base = copyFixture();
+  openDatabase(join(base, ".gsd", "gsd.db"));
+
+  // Pass 1: import fixture markdown → DB
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+  const ms1 = getAllMilestones();
+  const slices1 = ms1.length > 0 ? getMilestoneSlices(ms1[0]!.id) : [];
+  const tasks1 = slices1.length > 0 ? getSliceTasks(ms1[0]!.id, slices1[0]!.id) : [];
+  assert.ok(ms1.length > 0, "expected at least one milestone after import");
+
+  // Render DB → flat-phase markdown
+  const result = await renderAllFromDb(base);
+  assert.deepEqual(result.errors, [], `render errors: ${JSON.stringify(result.errors)}`);
+
+  // Pass 2: re-import the rendered markdown
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+  const ms2 = getAllMilestones();
+  const slices2 = ms2.length > 0 ? getMilestoneSlices(ms2[0]!.id) : [];
+  const tasks2 = slices2.length > 0 ? getSliceTasks(ms2[0]!.id, slices2[0]!.id) : [];
+
+  assert.equal(ms2.length, ms1.length, "milestone count drifted");
+  assert.equal(slices2.length, slices1.length, "slice count drifted");
+  assert.equal(tasks2.length, tasks1.length, "task count drifted");
+});
+
+test("flat-phase layout writes to .gsd/phases/ after import", async () => {
+  const base = copyFixture();
+  openDatabase(join(base, ".gsd", "gsd.db"));
+
+  migrateHierarchyToDb(base);
+  invalidateStateCache();
+  await renderAllFromDb(base);
+
+  // Confirm flat-phase structure on disk
+  assert.ok(existsSync(join(base, ".gsd", "phases")), "phases/ should exist after render");
+  assert.ok(!existsSync(join(base, ".gsd", "milestones")), "milestones/ should NOT exist");
+});

package/src/resources/extensions/gsd/tests/flat-phase-validation-integration.test.ts

@@ -0,0 +1,120 @@
+// Project/App: gsd-pi
+// File Purpose: End-to-end integration test for the upstream issue #876
+// fix — exercises the actual verdict-resolution code paths against a real
+// on-disk flat-phase project fixture, with no LLM or smoke required.
+//
+// Counterpart to flat-phase-validation-path.test.ts (which tests the
+// path helpers in isolation). This file tests the integrated readers
+// that auto-verification, commands-verdict, and milestone-validation-verdict
+// rely on.
+
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { loadFile } from "../files.ts";
+import { resolveMilestoneValidationVerdict } from "../milestone-validation-verdict.ts";
+import { relMilestoneFile } from "../paths.ts";
+
+function makeFlatPhaseFixtureWithPassVerdict(): {
+  basePath: string;
+  cleanup: () => void;
+} {
+  const basePath = mkdtempSync(join(tmpdir(), "flat-phase-validation-int-"));
+  const phaseDir = join(basePath, ".gsd", "phases", "01-foo");
+  mkdirSync(phaseDir, { recursive: true });
+  const validationPath = join(phaseDir, "01-VALIDATION.md");
+  writeFileSync(
+    validationPath,
+    [
+      "---",
+      "verdict: pass",
+      "---",
+      "",
+      "# M001 Validation",
+      "",
+      "All slices verified, all acceptance criteria met.",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+  return {
+    basePath,
+    cleanup: () => rmSync(basePath, { recursive: true, force: true }),
+  };
+}
+
+test("flat-phase integration: auto-verification reader path loads the on-disk VALIDATION.md (#876)", async () => {
+  // Simulates the exact path construction at auto-verification.ts:264-266
+  // after the Task 2 fix: join(basePath, relMilestoneFile(basePath, mid, "VALIDATION")).
+  // This is the load-bearing reader that was permanently null-returning on
+  // flat-phase projects before the fix.
+  const { basePath, cleanup } = makeFlatPhaseFixtureWithPassVerdict();
+  try {
+    const validationFile = join(
+      basePath,
+      relMilestoneFile(basePath, "M001", "VALIDATION"),
+    );
+    const content = await loadFile(validationFile);
+    assert.ok(
+      content && content.includes("verdict: pass"),
+      "auto-verification reader path must load the flat-phase VALIDATION.md content; received: " +
+        JSON.stringify(content),
+    );
+  } finally {
+    cleanup();
+  }
+});
+
+test("flat-phase integration: resolveMilestoneValidationVerdict returns 'pass' from disk (#876)", async () => {
+  // Exercises the full verdict-resolution waterfall in
+  // resolveMilestoneValidationVerdict: DB check first (returns undefined
+  // when no DB is open), then canonical/project-root file lookups, then
+  // the last-resort path Task 4 patched. With the fix, at least one of
+  // these branches finds the flat-phase VALIDATION.md and returns "pass".
+  // Pre-fix, the last-resort branch hardcoded milestones/MID/MID-VALIDATION.md
+  // and would miss the flat-phase file.
+  const { basePath, cleanup } = makeFlatPhaseFixtureWithPassVerdict();
+  try {
+    const verdict = await resolveMilestoneValidationVerdict(basePath, "M001");
+    assert.equal(
+      verdict,
+      "pass",
+      "resolveMilestoneValidationVerdict must read the verdict from the flat-phase VALIDATION.md on disk",
+    );
+  } finally {
+    cleanup();
+  }
+});
+
+test("flat-phase integration: pre-fix legacy hardcoded path would have missed this fixture", async () => {
+  // Documents what the bug looked like: the legacy hardcoded reader path
+  // (milestones/MID/MID-VALIDATION.md) does NOT exist in a flat-phase
+  // fixture, so loadFile on it returns null. This is the failure the fix
+  // closes.
+  const { basePath, cleanup } = makeFlatPhaseFixtureWithPassVerdict();
+  try {
+    const legacyHardcoded = join(
+      basePath,
+      ".gsd",
+      "milestones",
+      "M001",
+      "M001-VALIDATION.md",
+    );
+    assert.equal(
+      existsSync(legacyHardcoded),
+      false,
+      "fixture invariant: legacy path must not exist on flat-phase",
+    );
+    const content = await loadFile(legacyHardcoded);
+    assert.equal(
+      content,
+      null,
+      "loadFile on the pre-fix legacy hardcoded path must return null on a flat-phase fixture — this is the bug shape",
+    );
+  } finally {
+    cleanup();
+  }
+});

package/src/resources/extensions/gsd/tests/flat-phase-validation-path.test.ts

@@ -0,0 +1,74 @@
+// Project/App: gsd-pi
+// File Purpose: Regression test for upstream issue #876 — flat-phase
+// validation-path readers must use layout-aware helpers, not hardcoded
+// legacy paths.
+
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { relMilestoneFile, resolveMilestoneFile } from "../paths.ts";
+
+function makeFlatPhaseFixture(): { basePath: string; cleanup: () => void } {
+  const basePath = mkdtempSync(join(tmpdir(), "flat-phase-validation-"));
+  const phaseDir = join(basePath, ".gsd", "phases", "01-foo");
+  mkdirSync(phaseDir, { recursive: true });
+  const validationPath = join(phaseDir, "01-VALIDATION.md");
+  writeFileSync(
+    validationPath,
+    [
+      "---",
+      "verdict: pass",
+      "---",
+      "",
+      "# M001 Validation",
+      "",
+      "All slices verified.",
+      "",
+    ].join("\n"),
+    "utf-8",
+  );
+  return { basePath, cleanup: () => rmSync(basePath, { recursive: true, force: true }) };
+}
+
+test("flat-phase: relMilestoneFile resolves to the layout-aware path", () => {
+  const { basePath, cleanup } = makeFlatPhaseFixture();
+  try {
+    const rel = relMilestoneFile(basePath, "M001", "VALIDATION");
+    assert.equal(rel, ".gsd/phases/01-foo/01-VALIDATION.md");
+    const abs = join(basePath, rel);
+    assert.equal(existsSync(abs), true);
+  } finally {
+    cleanup();
+  }
+});
+
+test("flat-phase: resolveMilestoneFile finds the on-disk file", () => {
+  const { basePath, cleanup } = makeFlatPhaseFixture();
+  try {
+    const abs = resolveMilestoneFile(basePath, "M001", "VALIDATION");
+    assert.ok(abs, "resolveMilestoneFile must return a path for the flat-phase fixture");
+    assert.equal(abs!.endsWith("/.gsd/phases/01-foo/01-VALIDATION.md"), true);
+    assert.equal(existsSync(abs!), true);
+  } finally {
+    cleanup();
+  }
+});
+
+test("flat-phase: the legacy hardcoded path does NOT resolve (regression for #876)", () => {
+  const { basePath, cleanup } = makeFlatPhaseFixture();
+  try {
+    // This is the path that auto-verification.ts:264-270 used to construct.
+    // It must NOT exist on a flat-phase project — that's the whole bug.
+    const legacyHardcoded = join(basePath, ".gsd", "milestones", "M001", "M001-VALIDATION.md");
+    assert.equal(
+      existsSync(legacyHardcoded),
+      false,
+      "legacy hardcoded path must not exist in flat-phase fixture — if it does, the test fixture is wrong",
+    );
+  } finally {
+    cleanup();
+  }
+});