@opengsd/gsd-pi 1.3.0-dev.65546769 → 1.3.0-dev.738160b9

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

@@ -17,7 +17,8 @@ import {
   getSlice,
 } from "../gsd-db.ts";
 import { autoHealSketchFlags } from "../state-reconciliation/drift/sketch-flag.ts";
-import { deriveState, deriveStateFromDb } from "../state.ts";
+import { deriveState, deriveStateFromDb, invalidateStateCache } from "../state.ts";
+import { reconcileBeforeDispatch } from "../state-reconciliation.ts";
 import { resolveDispatch } from "../auto-dispatch.ts";
 import type { DispatchContext } from "../auto-dispatch.ts";
 
@@ -174,7 +175,7 @@ test("ADR-011: refining + flag flipped OFF mid-milestone → falls through to pl
   }
 });
 
-test("ADR-011: existing PLAN heals stale sketch flag via deriveStateFromDb (progressive_planning ON)", async (t) => {
+test("ADR-011: existing PLAN + stale sketch flag heals via reconcileBeforeDispatch, then dispatch routes past refining (progressive_planning ON)", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -188,11 +189,22 @@ test("ADR-011: existing PLAN heals stale sketch flag via deriveStateFromDb (prog
   );
   process.chdir(base);
 
-  // deriveStateFromDb auto-heals the stale sketch flag when PLAN.md exists,
-  // regardless of the progressive_planning preference.
+  // Derivation is pure (ADR-017): a stale sketch flag (PLAN on disk but
+  // is_sketch=1) yields 'refining' and must NOT mutate the DB. Healing is
+  // owned by reconcileBeforeDispatch, which runs before every dispatch.
+  invalidateStateCache();
+  const beforeReconcile = await deriveStateFromDb(base);
+  assert.equal(beforeReconcile.activeSlice?.id, "S02");
+  assert.equal(beforeReconcile.phase, "refining", "derive alone must not heal the stale sketch flag");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "derive must not mutate is_sketch");
+
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile clears the stale sketch flag once PLAN exists");
+
+  invalidateStateCache();
   const state = await deriveStateFromDb(base);
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "derive: flag cleared when PLAN exists");
-  assert.equal(state.phase, "planning", "derive: phase advances past refining once flag is healed");
+  assert.equal(state.phase, "planning", "re-derive advances past refining once the flag is healed");
 
   const ctx: DispatchContext = {
     basePath: base,
@@ -229,7 +241,7 @@ test("ADR-011: autoHealSketchFlags flips is_sketch=0 when PLAN file exists", asy
   assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "post-heal: flag cleared");
 });
 
-test("ADR-011: deriveStateFromDb auto-heals stale sketch flag when PLAN exists", async (t) => {
+test("ADR-011: reconcileBeforeDispatch auto-heals stale sketch flag when PLAN exists", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -244,12 +256,23 @@ test("ADR-011: deriveStateFromDb auto-heals stale sketch flag when PLAN exists",
   );
   process.chdir(base);
 
-  const state = await deriveStateFromDb(base);
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "derive should clear stale is_sketch");
-  assert.equal(state.phase, "planning", "state should advance past refining once stale flag is healed");
+  // Pure derivation reports the stale flag as 'refining' without repairing it.
+  invalidateStateCache();
+  const stale = await deriveStateFromDb(base);
+  assert.equal(stale.phase, "refining", "derive alone must not heal the stale flag");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "is_sketch unchanged before reconcile");
+
+  // Reconciliation owns the repair (ADR-017 stale-sketch-flag drift handler).
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile should clear stale is_sketch");
+
+  invalidateStateCache();
+  const healed = await deriveStateFromDb(base);
+  assert.equal(healed.phase, "planning", "state advances past refining once the stale flag is healed");
 });
 
-test("ADR-011: deriveState uses canonical artifact root for sketch-flag healing", async (t) => {
+test("ADR-011: deriveState stays pure across worktree/canonical-root; healing belongs to reconcile at the canonical artifact root", async (t) => {
   const originalCwd = process.cwd();
   const base = makeFixtureBase();
   t.after(() => cleanup(base, originalCwd));
@@ -265,9 +288,22 @@ test("ADR-011: deriveState uses canonical artifact root for sketch-flag healing"
   mkdirSync(worktreePath, { recursive: true });
   process.chdir(worktreePath);
 
-  const state = await deriveState(worktreePath, { projectRootForReads: base });
-  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "deriveState should heal from canonical artifact root");
-  assert.equal(state.phase, "planning", "state should advance past refining when PLAN exists at canonical root");
+  // Deriving from the worktree with reads routed to the canonical artifact
+  // root resolves DB state but never mutates it (ADR-017: derive is pure).
+  // The legacy projectRootForReads-driven heal is gone; healing now happens
+  // in reconcileBeforeDispatch, which auto runs against canonicalProjectRoot.
+  invalidateStateCache();
+  const beforeReconcile = await deriveState(worktreePath, { projectRootForReads: base });
+  assert.equal(beforeReconcile.phase, "refining", "derive alone must not heal, even via projectRootForReads");
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 1, "derive must not mutate is_sketch");
+
+  const reconcile = await reconcileBeforeDispatch(base);
+  assert.equal(reconcile.ok, true);
+  assert.equal(getSlice("M001", "S02")?.is_sketch, 0, "reconcile at the canonical root heals the stale flag");
+
+  invalidateStateCache();
+  const healed = await deriveState(worktreePath, { projectRootForReads: base });
+  assert.equal(healed.phase, "planning", "re-derive advances past refining once healed at the canonical root");
 });
 
 test("ADR-011: schema v16 is idempotent — re-opening DB preserves is_sketch and sketch_scope columns", async (t) => {

package/src/resources/extensions/gsd/tests/prompt-budget-enforcement.test.ts

@@ -72,6 +72,25 @@ function setupDependencyFixture(
   mkdirSync(targetSliceDir, { recursive: true });
 }
 
+function setupFlatPhaseSlicePlan(base: string): void {
+  const phaseDir = join(base, ".gsd", "phases", "01-flat-phase");
+  mkdirSync(phaseDir, { recursive: true });
+  writeFileSync(
+    join(phaseDir, "01-01-PLAN.md"),
+    [
+      "# S01: Flat phase slice",
+      "",
+      "## Tasks",
+      "",
+      "- [ ] **T01: Flat task** `est:15m`",
+      "",
+      "## Verification",
+      "",
+      "- Rendered prompt points at this slice plan.",
+    ].join("\n"),
+  );
+}
+
 // ─── inlineDependencySummaries truncation ─────────────────────────────────────
 
 describe("prompt-budget: inlineDependencySummaries truncation", () => {
@@ -412,6 +431,26 @@ describe("prompt-budget: execute-task template", () => {
     }
   });
 
+  it("flat-phase execute-task fallback points at the slice plan", async () => {
+    const base = createFixtureBase();
+    try {
+      setupFlatPhaseSlicePlan(base);
+
+      const prompt = await buildExecuteTaskPrompt("M001", "S01", "Slice", "T01", "Task", base, {
+        level: "minimal",
+        sessionContextWindow: 128_000,
+      });
+
+      assert.match(
+        prompt,
+        /Task plan not found at dispatch time\. Read `\.gsd\/phases\/01-flat-phase\/01-01-PLAN\.md` before executing\./,
+      );
+      assert.doesNotMatch(prompt, /\.gsd\/phases\/01-flat-phase\/tasks\/T01-PLAN\.md/);
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("verificationBudget format varies with context window size", () => {
     const budget128K = computeBudgets(128_000);
     const budget1M = computeBudgets(1_000_000);
@@ -566,6 +605,25 @@ describe("prompt-budget: execute-task builder truncation pattern", () => {
 });
 
 describe("prompt-budget: reactive-execute builder", () => {
+  it("flat-phase subagent fallback points at the slice plan", async () => {
+    const base = createFixtureBase();
+    try {
+      setupFlatPhaseSlicePlan(base);
+
+      const prompt = await buildReactiveExecutePrompt("M001", "Milestone", "S01", "Slice", ["T01"], base, undefined, {
+        sessionContextWindow: 128_000,
+      });
+
+      assert.match(
+        prompt,
+        /Task plan not found at dispatch time\. Read `\.gsd\/phases\/01-flat-phase\/01-01-PLAN\.md` before executing\./,
+      );
+      assert.doesNotMatch(prompt, /\.gsd\/phases\/01-flat-phase\/tasks\/T01-PLAN\.md/);
+    } finally {
+      cleanup(base);
+    }
+  });
+
   it("caps dependency carry-forward per ready subagent", async () => {
     const base = createFixtureBase();
     try {

package/src/resources/extensions/gsd/tests/prompt-contracts.test.ts

@@ -533,6 +533,7 @@ test("plan-milestone prompt references DB-backed planning tool and explicitly fo
   assert.match(prompt, /Do \*\*not\*\* write `?\{\{outputPath\}\}`?, `?ROADMAP\.md`?, or other planning artifacts manually/i);
   assert.match(prompt, /NEVER call `gsd_plan_milestone` with only `milestoneId` and `sliceId`/);
   assert.match(prompt, /gsd_plan_slice/);
+  assert.match(prompt, /gsd_plan_task/);
 });
 
 test("discuss prompts forbid gsd_plan_milestone slice-only tool args", () => {
@@ -548,12 +549,12 @@ test("plan-slice prompt no longer frames direct PLAN writes as the source of tru
   assert.match(prompt, /Do \*\*not\*\* rely on direct `PLAN\.md` writes as the source of truth/i);
 });
 
-test("plan-slice prompt explicitly names gsd_plan_slice as DB-backed planning tool", () => {
+test("plan-slice prompt explicitly names incremental DB-backed planning tools", () => {
   const prompt = readPrompt("plan-slice");
   assert.match(prompt, /gsd_plan_slice/);
   assert.match(prompt, /gsd_plan_task/);
-  // The prompt should describe the DB-backed tool as the canonical write path
-  assert.match(prompt, /DB-backed tool is the canonical write path/i);
+  assert.match(prompt, /Persist incrementally through DB-backed tools/i);
+  assert.match(prompt, /DB-backed tools are the canonical write path/i);
 });
 
 test("plan-slice prompt does not instruct direct file writes as a primary step", () => {
@@ -562,11 +563,12 @@ test("plan-slice prompt does not instruct direct file writes as a primary step",
   assert.doesNotMatch(prompt, /^\d+\.\s+Write `?\{\{outputPath\}\}`?\s*$/m);
 });
 
-test("plan-slice prompt clarifies gsd_plan_slice handles task persistence", () => {
+test("plan-slice prompt requires per-task incremental persistence", () => {
   const prompt = readPrompt("plan-slice");
-  // gsd_plan_slice persists tasks in its transaction — no separate gsd_plan_task calls needed
   assert.match(prompt, /gsd_plan_task/);
-  assert.match(prompt, /gsd_plan_slice` handles task persistence/i);
+  assert.match(prompt, /omit `tasks` for this metadata call/i);
+  assert.match(prompt, /call `gsd_plan_task` once per task/i);
+  assert.doesNotMatch(prompt, /do not call `gsd_plan_task`/i);
 });
 
 test("plan-slice prompt references web app UAT guidance when planning browser work", () => {

package/src/resources/extensions/gsd/tests/provider-errors.test.ts

@@ -7,7 +7,7 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { classifyError, isTransient, isTransientNetworkError } from "../error-classifier.ts";
@@ -26,6 +26,10 @@ import { _buildCancelledUnitStopReason } from "../auto/phase-helpers.ts";
 import { _classifyZeroToolProviderMessageForTest } from "../auto/unit-phase.ts";
 import { autoSession } from "../auto-runtime-state.ts";
 import { getNextFallbackModel } from "../preferences.ts";
+import { clearGuidedUnitContext, getGuidedUnitContext, setGuidedUnitContext } from "../guided-unit-context.ts";
+import { initNotificationStore, readNotifications, _resetNotificationStore } from "../notification-store.ts";
+import { installNotifyInterceptor } from "../bootstrap/notify-interceptor.ts";
+import { extractTrace } from "../session-forensics.ts";
 // Zero-import module — imported by path rather than through the package
 // barrel to avoid pulling the full AgentSession / @gsd/pi-ai dep graph into
 // this unit test (see #4837).
@@ -488,6 +492,63 @@ test("pauseAutoForProviderError falls back to indefinite pause when not rate lim
   ]);
 });
 
+test("agent_end retries when empty errorMessage has stream failure in content (#956)", async () => {
+  const originalSetTimeout = globalThis.setTimeout;
+  const notifications: Array<{ message: string; level?: string }> = [];
+  const sendMessageCalls: unknown[][] = [];
+  const timers: Array<{ fn: () => void; delay: number }> = [];
+
+  resetTransientRetryState();
+  autoSession.reset();
+  // handleAgentEnd returns at the isAutoActive() guard unless auto-mode is
+  // active. Set the minimum fields needed to reach the stopReason === "error"
+  // branch without requiring a real DB or worktree.
+  autoSession.active = true;
+  autoSession.currentUnit = { type: "execute-task", id: "M001/S01/T01", startedAt: Date.now() };
+
+  globalThis.setTimeout = ((fn: () => void, delay?: number) => {
+    timers.push({ fn, delay: delay ?? 0 });
+    return 0 as unknown as ReturnType<typeof setTimeout>;
+  }) as typeof setTimeout;
+
+  try {
+    await handleAgentEnd({
+      sendMessage: (...args: unknown[]) => {
+        sendMessageCalls.push(args);
+      },
+    } as any, {
+      messages: [{
+        role: "assistant",
+        stopReason: "error",
+        errorMessage: "",
+        content: [{ type: "text", text: "API Error: stream idle timeout - partial response received" }],
+      }],
+    } as any, {
+      model: { provider: "openai-codex", id: "gpt-5.5" },
+      ui: {
+        notify(message: string, level?: "info" | "warning" | "error" | "success") {
+          notifications.push({ message, level });
+        },
+      },
+    } as any);
+
+    assert.equal(timers.length, 1, "empty errorMessage stream failures should use the network retry path");
+    assert.equal(timers[0].delay, 3_000);
+    assert.deepEqual(notifications[0], {
+      message: "Network error on gpt-5.5: API Error: stream idle timeout - partial response received. Retry 1/2 in 3s...",
+      level: "warning",
+    });
+
+    timers[0].fn();
+    assert.equal(sendMessageCalls.length, 1);
+    assert.deepEqual(sendMessageCalls[0][1], { triggerTurn: true });
+  } finally {
+    globalThis.setTimeout = originalSetTimeout;
+    resetTransientRetryState();
+    autoSession.reset();
+  }
+});
+
 test("rate-limit agent_end walks past unavailable fallback models before pausing (#716 follow-up)", async () => {
   const originalCwd = process.cwd();
   const originalSetTimeout = globalThis.setTimeout;
@@ -648,6 +709,139 @@ test("does not suppress deleted-worktree provider errors outside terminal comple
   assert.equal(event.message.stopReason, "error");
 });
 
+test("manual guided discuss provider error records warning and activity marker (#944)", async () => {
+  const originalCwd = process.cwd();
+  const base = mkdtempSync(join(tmpdir(), "gsd-manual-discuss-error-"));
+  const notifications: Array<{ message: string; level?: string }> = [];
+  const sendMessageCalls: unknown[][] = [];
+
+  try {
+    autoSession.reset();
+    mkdirSync(join(base, ".git"), { recursive: true });
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    process.chdir(base);
+    initNotificationStore(base);
+
+    // Use base as the guided context path so gsdRoot(base) hits the fast path
+    // (.gsd exists at base directly) and doesn't need git to walk up from a
+    // subdirectory — the empty .git folder is not a real repo and git resolution
+    // from a child directory would return the wrong .gsd path.
+    setGuidedUnitContext(base, "discuss-slice");
+
+    const ctx = {
+      model: { provider: "openai-codex", id: "gpt-5.1-codex" },
+      modelRegistry: { getAvailable: () => [] },
+      ui: {
+        notify(message: string, level?: "info" | "warning" | "error" | "success") {
+          notifications.push({ message, level });
+        },
+      },
+    } as any;
+    installNotifyInterceptor(ctx);
+
+    const pi = {
+      sendMessage: (...args: unknown[]) => {
+        sendMessageCalls.push(args);
+      },
+    } as any;
+
+    await handleAgentEnd(pi, {
+      messages: [{
+        role: "assistant",
+        stopReason: "error",
+        errorMessage: "",
+        content: [{ type: "text", text: "stream idle timeout while saving summary" }],
+      }],
+    } as any, ctx);
+
+    assert.deepEqual(sendMessageCalls, [], "manual discuss terminal errors must not auto-retry or redispatch");
+    assert.equal(getGuidedUnitContext(base), null, "guided unit context must still be cleared after the turn");
+    assert.equal(notifications.length, 1);
+    assert.equal(notifications[0]?.level, "warning");
+    assert.match(notifications[0]?.message ?? "", /Manual \/gsd discuss discuss-slice ended with a provider error/);
+    assert.match(notifications[0]?.message ?? "", /openai-codex\/gpt-5\.1-codex/);
+    assert.match(notifications[0]?.message ?? "", /stream idle timeout/);
+
+    const persisted = readNotifications(base);
+    assert.equal(persisted.length, 1, "wrapped notify should persist exactly one warning notification");
+    assert.equal(persisted[0]?.severity, "warning");
+    assert.equal(persisted[0]?.source, "notify");
+
+    const activityDir = join(base, ".gsd", "activity");
+    const files = readdirSync(activityDir).filter((file) => file.endsWith(".jsonl"));
+    assert.equal(files.length, 1, "manual guided provider error should write one activity marker");
+    const entries = readFileSync(join(activityDir, files[0]!), "utf-8")
+      .split("\n")
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+    const trace = extractTrace(entries);
+    assert.equal(trace.errors.length, 1);
+    assert.match(trace.errors[0] ?? "", /discuss-slice/);
+    assert.match(trace.errors[0] ?? "", /openai-codex\/gpt-5\.1-codex/);
+    assert.match(trace.errors[0] ?? "", /stream idle timeout/);
+  } finally {
+    clearGuidedUnitContext();
+    _resetNotificationStore();
+    autoSession.reset();
+    process.chdir(originalCwd);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
+test("manual guided discuss user-cancel is not treated as a provider error (#944)", async () => {
+  const originalCwd = process.cwd();
+  const base = mkdtempSync(join(tmpdir(), "gsd-manual-discuss-cancel-"));
+  const guidedBase = join(base, "slice-work");
+  const notifications: Array<{ message: string; level?: string }> = [];
+
+  try {
+    autoSession.reset();
+    mkdirSync(join(base, ".git"), { recursive: true });
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    mkdirSync(guidedBase, { recursive: true });
+    process.chdir(base);
+    initNotificationStore(base);
+
+    setGuidedUnitContext(guidedBase, "discuss-slice");
+
+    const ctx = {
+      model: { provider: "anthropic", id: "claude-opus-4" },
+      modelRegistry: { getAvailable: () => [] },
+      ui: {
+        notify(message: string, level?: "info" | "warning" | "error" | "success") {
+          notifications.push({ message, level });
+        },
+      },
+    } as any;
+    installNotifyInterceptor(ctx);
+
+    const pi = { sendMessage: () => {} } as any;
+
+    await handleAgentEnd(pi, {
+      messages: [{
+        role: "assistant",
+        stopReason: "error",
+        errorMessage: "Request aborted by user",
+        content: [],
+      }],
+    } as any, ctx);
+
+    assert.deepEqual(notifications, [], "user-cancel stopReason=error must not emit a provider-error warning");
+    assert.equal(getGuidedUnitContext(guidedBase), null, "context must be cleared even for user-cancel");
+
+    // No activity directory should have been created
+    let activityExists = false;
+    try { readdirSync(join(base, ".gsd", "activity")); activityExists = true; } catch { /* expected */ }
+    assert.equal(activityExists, false, "user-cancel must not write an activity error marker");
+  } finally {
+    clearGuidedUnitContext();
+    _resetNotificationStore();
+    autoSession.reset();
+    process.chdir(originalCwd);
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 // ── resumeAutoAfterProviderDelay ────────────────────────────────────────────
 
 test("resumeAutoAfterProviderDelay restarts paused auto-mode from the recorded base path", async () => {

package/src/resources/extensions/gsd/tests/read-uat-gate-verdict.test.ts

@@ -0,0 +1,185 @@
+/**
+ * Behavioural regression test for the milestone-closeout UAT gate —
+ * `readUatGateVerdict`.
+ *
+ * The gate (ADR-017: DB-authoritative UAT sign-off) reads a slice's UAT
+ * verdict from its ASSESSMENT artifact via the *canonical* expected path
+ * (`resolveSliceFile` + a path-keyed `getAssessment`). When a milestone
+ * artifact-layout migration orphans the ASSESSMENT markdown from that canonical
+ * path (e.g. `phases/…` → `milestones/…`), the gate used to return `null` and
+ * block milestone closure with "missing UAT PASS verdict" — even though the
+ * verdict was correctly recorded in the `assessments` table by
+ * `gsd_uat_result_save`.
+ *
+ * The DB fallback added to `readUatGateVerdict` consults the authoritative
+ * `assessments` table by (milestoneId, sliceId, scope='run-uat') identity,
+ * independent of path. These tests pin that behaviour.
+ */
+
+import { describe, test, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+import {
+  openDatabase,
+  closeDatabase,
+  insertMilestone,
+  insertSlice,
+  insertAssessment,
+} from '../gsd-db.ts';
+import { readUatGateVerdict } from '../auto-dispatch.ts';
+
+function tempDbPath(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-uat-gate-'));
+  return path.join(dir, 'test.db');
+}
+
+function cleanupDb(dbPath: string): void {
+  closeDatabase();
+  try { fs.rmSync(path.dirname(dbPath), { recursive: true, force: true }); } catch { /* */ }
+}
+
+const MID = 'M001';
+const SLICE = 'S01';
+
+/** Canonical on-disk ASSESSMENT path produced by `resolveSliceFile`. */
+function canonicalAssessmentPath(basePath: string): string {
+  return path.join(basePath, '.gsd', 'milestones', MID, 'slices', SLICE, `${SLICE}-ASSESSMENT.md`);
+}
+
+/** An ASSESSMENT body that declares a runtime-executable UAT type and a PASS verdict. */
+const RUNTIME_PASS_BODY = [
+  '---',
+  'verdict: pass',
+  '---',
+  '',
+  '# S01 UAT Assessment',
+  '',
+  '## UAT Type',
+  '- UAT mode: runtime-executable',
+  '',
+  '## Result',
+  'All checks passed.',
+].join('\n');
+
+describe('readUatGateVerdict — DB fallback for orphaned ASSESSMENT', () => {
+  let dbPath: string;
+  let basePath: string;
+
+  beforeEach(() => {
+    dbPath = tempDbPath();
+    openDatabase(dbPath);
+    basePath = fs.mkdtempSync(path.join(os.tmpdir(), 'gsd-uat-gate-proj-'));
+    insertMilestone({ id: MID });
+    insertSlice({ id: SLICE, milestoneId: MID });
+  });
+
+  afterEach(() => {
+    cleanupDb(dbPath);
+    try { fs.rmSync(basePath, { recursive: true, force: true }); } catch { /* */ }
+  });
+
+  test('returns pass when the ASSESSMENT is keyed by a legacy/orphaned path (the bug)', async () => {
+    // Reproduces milestone 15: `gsd_uat_result_save` wrote S01's assessment row
+    // under a now-migrated path; the canonical file never existed on disk and
+    // the `assessments.path` is not what `resolveSliceFile` computes.
+    insertAssessment({
+      // Deliberately non-canonical — a legacy `phases/…` path.
+      path: `.gsd/phases/01-some-feature/01-01-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'pass',
+      scope: 'run-uat',
+      fullContent: RUNTIME_PASS_BODY,
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.ok(result, 'expected the DB fallback to resolve a verdict, got null');
+    assert.equal(result!.verdict, 'pass');
+  });
+
+  test('the DB fallback derives uatType from the assessment body when no file exists', async () => {
+    insertAssessment({
+      path: `.gsd/phases/01-some-feature/01-01-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'pass',
+      scope: 'run-uat',
+      fullContent: RUNTIME_PASS_BODY,
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.ok(result);
+    assert.equal(result!.verdict, 'pass');
+    assert.equal(result!.uatType, 'runtime-executable');
+  });
+
+  test('canonical ASSESSMENT file on disk still resolves (regression guard)', async () => {
+    // When the file is present at the canonical path, the existing path-keyed
+    // lookup must resolve it without needing the fallback.
+    const file = canonicalAssessmentPath(basePath);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, RUNTIME_PASS_BODY);
+    // Also seed the path-keyed assessments row, mirroring a normal save.
+    insertAssessment({
+      path: `.gsd/milestones/${MID}/slices/${SLICE}/${SLICE}-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'pass',
+      scope: 'run-uat',
+      fullContent: RUNTIME_PASS_BODY,
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.ok(result);
+    assert.equal(result!.verdict, 'pass');
+    assert.equal(result!.uatType, 'runtime-executable');
+  });
+
+  test('a roadmap-scoped assessment does NOT satisfy the UAT gate', async () => {
+    // `reassess-roadmap` writes roadmap-scoped assessments to the same
+    // S##-ASSESSMENT path; those must never be treated as a UAT verdict. The
+    // legacy-path fallback queries scope='run-uat', so a roadmap-only row is
+    // invisible and the gate returns null.
+    insertAssessment({
+      path: `.gsd/milestones/${MID}/slices/${SLICE}/${SLICE}-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'pass',
+      scope: 'roadmap',
+      fullContent: RUNTIME_PASS_BODY,
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.equal(result, null, 'roadmap-scoped assessments must not satisfy the UAT gate');
+  });
+
+  test('returns null when no assessment and no file exist (fallback does not hallucinate)', async () => {
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+    assert.equal(result, null);
+  });
+
+  test('surfaces a recorded non-pass verdict via the DB fallback', async () => {
+    // A failing verdict stored under a legacy path must surface (not be masked
+    // as "missing") so the gate's non-PASS branch can act on it.
+    insertAssessment({
+      path: `.gsd/phases/01-some-feature/01-01-ASSESSMENT.md`,
+      milestoneId: MID,
+      sliceId: SLICE,
+      status: 'fail',
+      scope: 'run-uat',
+      fullContent: RUNTIME_PASS_BODY.replace('verdict: pass', 'verdict: fail'),
+    });
+
+    const result = await readUatGateVerdict(basePath, MID, SLICE);
+
+    assert.ok(result);
+    assert.equal(result!.verdict, 'fail');
+  });
+});