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

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

@@ -0,0 +1,199 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for the external-planning-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 { externalPlanningEditHandler } from "../state-reconciliation/drift/external-planning-edit.ts";
+import { reconcileBeforeDispatch } from "../state-reconciliation.ts";
+import { writeCompatMarker, readCompatMarker } 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-pedit-${randomUUID()}`));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  mkdirSync(join(base, ".planning"), { 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 d of tmpDirs) { try { rmSync(d, { recursive: true, force: true }); } catch { /* */ } }
+  tmpDirs.length = 0;
+});
+
+test("detect returns no drift when planning inactive and dir is empty", async () => {
+  const base = makeTmpBase();
+  // .planning/ exists (created by makeTmpBase) but has no ROADMAP.md → no
+  // layout signal → detectPlanningLayout returns null → stays inactive.
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+
+  const { readCompatMarker } = await import("../compat/compat-marker.ts");
+  const marker = readCompatMarker(base);
+  assert.equal(marker.planning?.active, false, "should not activate without a recognisable layout");
+});
+
+test("detect does NOT write the marker when planning inactive (dry-run invariant)", async () => {
+  // Regression test for COMMENT:3449147735: detect() must be read-only because
+  // it is called in both dry-run and non-dry-run contexts. Activation is owned
+  // by capturePlanningCompatIfNeeded (called from reconcileBeforeDispatch when
+  // !dryRun), not by the detect function itself.
+  const base = makeTmpBase();
+  writeFileSync(
+    join(base, ".planning", "ROADMAP.md"),
+    "# Roadmap\n\n## Phases\n\n- [ ] 01 — Foundation\n",
+    "utf-8",
+  );
+  // No compat marker written → planning.active = false by default.
+
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+
+  // Marker must NOT have been written by detect().
+  const { readCompatMarker } = await import("../compat/compat-marker.ts");
+  const marker = readCompatMarker(base);
+  assert.equal(marker.planning?.active, false, "detect() must not activate the marker");
+});
+
+test("detect returns drift when planning projection sha mismatches", async () => {
+  const base = makeTmpBase();
+  const rel = "ROADMAP.md";
+  writeFileSync(join(base, ".planning", rel), "# edited by gsd-core\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: { [rel]: { sha: "stale000000000000", entities: ["M001"] } },
+      passthrough: {},
+    },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 1);
+  assert.equal(drift[0]!.kind, "external-planning-edit");
+  assert.equal(drift[0]!.projectionPath, rel);
+  assert.equal(drift[0]!.passthrough, false);
+});
+
+test("detect flags passthrough files separately with passthrough=true", async () => {
+  const base = makeTmpBase();
+  const rel = "codebase/STACK.md";
+  mkdirSync(join(base, ".planning", "codebase"), { recursive: true });
+  writeFileSync(join(base, ".planning", rel), "# new stack content\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: {},
+      passthrough: { [rel]: { sha: "old0000000000000", entities: [] } },
+    },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 1);
+  assert.equal(drift[0]!.passthrough, true);
+});
+
+test("detect returns no drift when sha matches", async () => {
+  const base = makeTmpBase();
+  const rel = "ROADMAP.md";
+  const content = "# unchanged\n";
+  writeFileSync(join(base, ".planning", rel), content, "utf-8");
+  const { computeProjectionSha } = await import("../compat/compat-marker.ts");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: { [rel]: { sha: computeProjectionSha(content), entities: ["M001"] } },
+      passthrough: {},
+    },
+    piVersion: "1.4.0",
+  });
+
+  const drift = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift.length, 0);
+});
+
+test("repair refreshes passthrough marker sha (idempotent on second detect)", async () => {
+  const base = makeTmpBase();
+  const rel = "codebase/STACK.md";
+  mkdirSync(join(base, ".planning", "codebase"), { recursive: true });
+  writeFileSync(join(base, ".planning", rel), "# new stack content\n", "utf-8");
+  writeCompatMarker(base, {
+    schema: 2,
+    lastWriter: "gsd-pi",
+    lastProjectedAt: "2026-06-21T00:00:00.000Z",
+    projections: {},
+    planning: {
+      active: true,
+      layout: "flat-phases",
+      projections: {},
+      passthrough: { [rel]: { sha: "old0000000000000", entities: [] } },
+    },
+    piVersion: "1.4.0",
+  });
+
+  const drift1 = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift1.length, 1);
+  await externalPlanningEditHandler.repair(drift1[0]!, ctx(base));
+
+  const drift2 = await externalPlanningEditHandler.detect(stubState, ctx(base));
+  assert.equal(drift2.length, 0);
+});
+
+test("reconcileBeforeDispatch dryRun=true does not write compat marker (planning)", async () => {
+  // Regression test for COMMENT:3449147735: /gsd sync --dry-run claimed to be
+  // read-only but capturePlanningCompatIfNeeded wrote the marker. The guard
+  // added in reconcileBeforeDispatch must prevent any marker mutations.
+  const base = makeTmpBase();
+  writeFileSync(
+    join(base, ".planning", "ROADMAP.md"),
+    "# Roadmap\n\n## Phases\n\n- [ ] 01 — Foundation\n",
+    "utf-8",
+  );
+  // Capture the marker state before the dry-run reconcile.
+  const markerBefore = readCompatMarker(base);
+
+  await reconcileBeforeDispatch(base, {
+    dryRun: true,
+    registry: [], // empty: no handlers, no repairs
+    invalidateStateCache: () => {},
+    deriveState: async () => stubState as unknown as import("../types.ts").GSDState,
+  });
+
+  // Marker must be identical to before: no planning activation, no SHA seeding.
+  const markerAfter = readCompatMarker(base);
+  assert.equal(
+    markerAfter.planning?.active,
+    markerBefore.planning?.active,
+    "dryRun reconcile must not activate planning",
+  );
+  assert.deepEqual(
+    markerAfter.planning?.projections,
+    markerBefore.planning?.projections,
+    "dryRun reconcile must not write planning projections",
+  );
+});

package/src/resources/extensions/gsd/tests/fallback-continuation.test.ts

@@ -0,0 +1,36 @@
+// gsd-pi + src/resources/extensions/gsd/tests/fallback-continuation.test.ts - Regression test for #804 fallback continuation dispatch.
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { scheduleFallbackContinuation } from "../bootstrap/fallback-continuation.ts";
+
+/**
+ * #804: After switching to a fallback model in the agent_end recovery path, the
+ * continuation must be dispatched on a *fresh* turn — not as a steering message
+ * against the turn that just errored out (which `isStreaming` is still true for
+ * until finishRun() clears it). The fix defers the send to a macrotask and uses
+ * a plain `triggerTurn` with no `deliverAs: "steer"`.
+ */
+test("scheduleFallbackContinuation defers a plain triggerTurn dispatch (no steer)", async () => {
+  const calls: Array<{ message: unknown; options: unknown }> = [];
+  const pi = {
+    sendMessage: (message: unknown, options: unknown) => {
+      calls.push({ message, options });
+    },
+  } as any;
+
+  scheduleFallbackContinuation(pi);
+
+  // Synchronous within the awaited agent_end listener: nothing sent yet so the
+  // dispatch cannot be misrouted into the still-streaming dying turn.
+  assert.equal(calls.length, 0);
+
+  // After the macrotask (finishRun() has cleared isStreaming by now).
+  await new Promise((r) => setTimeout(r, 0));
+
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0].options, { triggerTurn: true });
+  assert.equal((calls[0].options as { deliverAs?: unknown }).deliverAs, undefined);
+});

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,114 @@
+// 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, rmSync, writeFileSync, existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { randomUUID } from "node:crypto";
+
+import { migrateToFlatPhase, needsFlatPhaseMigration } 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 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",
+  );
+});

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();
+  }
+});