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

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

@@ -467,6 +467,21 @@ test("complete-slice prompt keeps source fixes in execution units", () => {
   assert.doesNotMatch(prompt, /Fix failures before marking done/i);
 });
 
+test("complete-slice prompt terminates after reopen or replan handoff", () => {
+  const prompt = readPrompt("complete-slice");
+  assert.match(prompt, /exactly one terminal workflow tool/i);
+  assert.match(prompt, /A text-only stop, even one mentioning a tool, is invalid/i);
+  assert.match(prompt, /After any successful failure-handoff tool call, the unit is done/i);
+  assert.match(prompt, /`gsd_task_reopen` or `gsd_replan_slice` call is the handoff signal/i);
+  assert.match(prompt, /Never call `gsd_replan_slice` after calling `gsd_task_reopen`/i);
+  assert.match(prompt, /reopened tasks are pending/i);
+  assert.match(prompt, /Do not call `gsd_plan_slice`/i);
+  assert.match(prompt, /Do not read source code, run `gsd_exec`, invoke subagents/i);
+  assert.match(prompt, /Terminal reopen sequence/i);
+  assert.match(prompt, /Terminal replan sequence/i);
+  assert.match(prompt, /Never finish this unit with plain text only/i);
+});
+
 test("complete-slice prompt binds all file operations to workingDirectory", () => {
   const prompt = readPrompt("complete-slice");
   assert.match(prompt, /Your working directory is `\{\{workingDirectory\}\}`/);
@@ -518,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", () => {
@@ -533,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", () => {
@@ -547,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,20 +7,29 @@
 
 import test from "node:test";
 import assert from "node:assert/strict";
+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";
 import { pauseAutoForProviderError } from "../provider-error-pause.ts";
 import { resumeAutoAfterProviderDelay } from "../bootstrap/provider-error-resume.ts";
 import {
   MAX_TRANSIENT_AUTO_RESUMES,
+  handleAgentEnd,
   isTerminalDeletedWorktreeProviderError,
   resetTransientRetryState,
   shouldDeferTransientErrorToCoreRetry,
   suppressTerminalDeletedWorktreeMessageEnd,
 } from "../bootstrap/agent-end-recovery.ts";
+import { blockModelUntil, clearTemporaryModelBlocksForTest } from "../blocked-models.ts";
 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).
@@ -483,6 +492,165 @@ 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;
+  const base = mkdtempSync(join(tmpdir(), "gsd-rate-limit-agent-end-"));
+  const notifications: Array<{ message: string; level?: string }> = [];
+  const setModelCalls: string[] = [];
+  const sendMessageCalls: unknown[][] = [];
+  const timers: Array<{ delay: number }> = [];
+
+  globalThis.setTimeout = ((_fn: (...args: unknown[]) => void, delay?: number) => {
+    if ((delay ?? 0) === 0) {
+      // delay-0 is a macrotask deferral (scheduleFallbackContinuation): invoke
+      // immediately in tests so sendMessage assertions can fire synchronously.
+      _fn();
+    } else {
+      // delay>0 is a pause/backoff timer: capture without firing so the test
+      // stays synchronous and can assert no pause was scheduled.
+      timers.push({ delay: delay ?? 0 });
+    }
+    return 0 as unknown as ReturnType<typeof setTimeout>;
+  }) as typeof setTimeout;
+
+  try {
+    clearTemporaryModelBlocksForTest();
+    autoSession.reset();
+    mkdirSync(join(base, ".gsd"), { recursive: true });
+    writeFileSync(
+      join(base, ".gsd", "PREFERENCES.md"),
+      [
+        "---",
+        "models:",
+        "  execution:",
+        "    model: gpt-5.5",
+        "    provider: openai-codex",
+        "    fallbacks:",
+        "      - anthropic/claude-sonnet-4-6",
+        "      - google-gemini-cli/gemini-2.5-pro",
+        "---",
+      ].join("\n"),
+      "utf-8",
+    );
+    process.chdir(base);
+
+    autoSession.active = true;
+    autoSession.basePath = base;
+    autoSession.currentUnit = { type: "execute-task", id: "M001/S01/T01", startedAt: Date.now() };
+    autoSession.autoModeStartModel = { provider: "openai-codex", id: "gpt-5.5" };
+
+    blockModelUntil(base, "anthropic", "claude-sonnet-4-6", Date.now() + 60_000, "fallback also limited");
+
+    const availableModels = [
+      { id: "gpt-5.5", provider: "openai-codex", api: "responses" },
+      { id: "claude-sonnet-4-6", provider: "anthropic", api: "anthropic-messages" },
+      { id: "gemini-2.5-pro", provider: "google-gemini-cli", api: "google-genai" },
+    ];
+    const ctx = {
+      model: availableModels[0],
+      modelRegistry: { getAvailable: () => availableModels },
+      ui: {
+        notify(message: string, level?: "info" | "warning" | "error" | "success") {
+          notifications.push({ message, level });
+        },
+        setStatus: () => {},
+        setWidget: () => {},
+        setWorkingMessage: () => {},
+      },
+    } as any;
+    const pi = {
+      setModel: async (model: { provider: string; id: string }) => {
+        setModelCalls.push(`${model.provider}/${model.id}`);
+        return true;
+      },
+      sendMessage: (...args: unknown[]) => {
+        sendMessageCalls.push(args);
+      },
+    } as any;
+
+    await handleAgentEnd(pi, {
+      messages: [{
+        role: "assistant",
+        stopReason: "error",
+        errorMessage: "You've hit your session limit · resets 7:20 pm (Europe/Rome)",
+      }],
+    } as any, ctx);
+
+    assert.deepEqual(setModelCalls, ["google-gemini-cli/gemini-2.5-pro"]);
+    assert.equal(sendMessageCalls.length, 1, "fallback recovery must trigger a deferred continuation turn");
+    assert.deepEqual(sendMessageCalls[0][1], { triggerTurn: true }, "continuation must use plain triggerTurn — no deliverAs:steer — to start a fresh turn, not steer the dying one");
+    assert.equal(timers.length, 0, "must not schedule a delay-backoff pause timer when a fallback is available");
+    assert.ok(
+      notifications.some((n) => n.message.includes("google-gemini-cli/gemini-2.5-pro")),
+      "user-facing notification should name the fallback actually selected",
+    );
+  } finally {
+    globalThis.setTimeout = originalSetTimeout;
+    process.chdir(originalCwd);
+    clearTemporaryModelBlocksForTest();
+    autoSession.reset();
+    rmSync(base, { recursive: true, force: true });
+  }
+});
+
 test("isTerminalDeletedWorktreeProviderError matches removed auto-worktree paths only", () => {
   assert.equal(
     isTerminalDeletedWorktreeProviderError('Path "/Users/dev/.gsd/projects/abc123/worktrees/M005" does not exist'),
@@ -541,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');
+  });
+});

package/src/resources/extensions/gsd/tests/ready-phrase-no-files-4573.test.ts

@@ -58,7 +58,14 @@ function mkPi(cap: MockCapture, opts: { sendThrows?: boolean } = {}): any {
 
 function mkBase(): string {
   const base = mkdtempSync(join(tmpdir(), "gsd-4573-"));
-  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  const mDir = join(base, ".gsd", "milestones", "M001");
+  mkdirSync(mDir, { recursive: true });
+  // Seed one content file so the dir is recognised as a content-bearing legacy
+  // milestone by dirIsContentBearingLegacyMilestone. Tests that check for
+  // "no CONTEXT/ROADMAP yet" still work because RESEARCH is not checked by
+  // maybeHandleReadyPhraseWithoutFiles; the stale-cache tests then verify that
+  // a file written to the same dir is NOT found until clearPathCache runs.
+  writeFileSync(join(mDir, "M001-RESEARCH.md"), "# M001 research\n");
   return base;
 }
 
@@ -181,32 +188,32 @@ describe("#4573 maybeHandleReadyPhraseWithoutFiles", () => {
 
   test("stale path cache from a prior listing → fresh writes are detected (regression)", () => {
     // Repro the live binary failure where:
-    //   1. paths.ts cached dir listings were populated when M001/ was empty
-    //      (or the milestone dir didn't yet exist).
+    //   1. paths.ts cached dir listings were populated before M001-CONTEXT.md
+    //      and M001-ROADMAP.md existed (the dir had only M001-RESEARCH.md).
     //   2. The LLM then wrote M001-CONTEXT.md and M001-ROADMAP.md via the
     //      standard Write tool — which has no awareness of paths.ts caches.
     //   3. maybeHandleReadyPhraseWithoutFiles called resolveMilestoneFile,
-    //      which read the stale cache and reported the artifacts missing,
+    //      which read the stale dirListCache and reported the artifacts missing,
     //      firing a false rejection nudge until MAX_READY_REJECTS aborted
     //      the auto-start with `LLM signaled "ready" 3 times without
     //      writing files`.
     //
     // The fix busts the path cache at the top of the validator before
     // re-resolving. This test fails pre-fix (handled === true) because the
-    // cache returns the empty listing it captured in step (a).
+    // dirListCache still holds the stale per-file listing for M001/ from
+    // step (a), so resolveFile cannot see the newly written CONTEXT/ROADMAP.
     const base = mkBase();
     try {
       const mDir = join(base, ".gsd", "milestones", "M001");
 
-      // (a) Prime the cache with a listing that DOES NOT include M001's
-      //     CONTEXT/ROADMAP files. mkBase() has already created the M001
-      //     directory but nothing inside it yet — so this readdir caches an
-      //     empty entry list keyed by the M001 dir path.
+      // (a) Prime the dirListCache for M001/ with only M001-RESEARCH.md.
+      //     mkBase() already created M001-RESEARCH.md; this first resolver
+      //     call caches that listing so CONTEXT/ROADMAP are unknown to it.
       clearPathCache();
       assert.equal(
         resolveMilestoneFile(base, "M001", "CONTEXT"),
         null,
-        "precondition: resolver must report missing before files are written",
+        "precondition: resolver must report CONTEXT missing before files are written",
       );
 
       // (b) Write the artifacts directly to disk (simulates the LLM Write
@@ -215,12 +222,14 @@ describe("#4573 maybeHandleReadyPhraseWithoutFiles", () => {
       writeFileSync(join(mDir, "M001-CONTEXT.md"), "# ctx");
       writeFileSync(join(mDir, "M001-ROADMAP.md"), "# roadmap");
 
-      // (c) Sanity: the cache is still stale. Without the fix, the
-      //     validator would still see the empty cached listing.
+      // (c) Sanity: the dirListCache for M001/ is still stale (only
+      //     M001-RESEARCH.md). dirIsContentBearingLegacyMilestone reads fresh
+      //     so resolveMilestonePath finds the dir, but resolveFile still
+      //     misses CONTEXT because cachedReaddir(M001/) is not yet cleared.
       assert.equal(
         resolveMilestoneFile(base, "M001", "CONTEXT"),
         null,
-        "stale cache still reports missing pre-clearPathCache",
+        "stale dirListCache still reports CONTEXT missing pre-clearPathCache",
       );
 
       // (d) Run the validator. With the fix it busts the cache before