@opengsd/gsd-pi 1.1.1-dev.9bb7453 → 1.1.1-dev.9f86580

package/src/resources/extensions/gsd/tests/token-tool-gating.test.ts

@@ -101,7 +101,7 @@ test("buildMinimalAutoGsdToolSet keeps unit-specific completion tools without al
   assert.ok(!result.includes("gsd_complete_slice"));
 });
 
-test("buildMinimalAutoGsdToolSet scopes run-uat to UAT-specific tools", () => {
+test("buildMinimalAutoGsdToolSet scopes run-uat to UAT-specific and read-only tools", () => {
   const active = ["ask_user_questions", "bash", "read", "edit", "write", "gsd_summary_save"];
   const registered = [
     ...active,
@@ -123,11 +123,11 @@ test("buildMinimalAutoGsdToolSet scopes run-uat to UAT-specific tools", () => {
   assert.ok(result.includes("gsd_resume"));
   assert.ok(result.includes("gsd_milestone_status"));
   assert.ok(result.includes("gsd_journal_query"));
+  assert.ok(result.includes("read"));
   assert.ok(result.includes("browser_navigate"), "run-uat needs browser_navigate");
   assert.ok(result.includes("browser_click"), "run-uat needs browser_click");
   assert.ok(!result.includes("ToolSearch"));
   assert.ok(!result.includes("bash"));
-  assert.ok(!result.includes("read"));
   assert.ok(!result.includes("edit"));
   assert.ok(!result.includes("write"));
   assert.ok(!result.includes("gsd_exec"));
@@ -230,9 +230,9 @@ test("buildMinimalAutoGsdToolSet preserves compatible browser add-ons for run-ua
   assert.ok(result.includes("gsd_uat_exec"));
   assert.ok(result.includes("gsd_uat_result_save"));
   assert.ok(result.includes("subagent"));
+  assert.ok(result.includes("read"));
   assert.ok(!result.includes("ToolSearch"));
   assert.ok(!result.includes("bash"));
-  assert.ok(!result.includes("read"));
   assert.ok(!result.includes("edit"));
   assert.ok(!result.includes("write"));
   assert.ok(!result.includes("gsd_exec"));
@@ -281,12 +281,12 @@ test("buildMinimalAutoGsdToolSet honors provider-compatible registered tools for
 
   assert.ok(result.includes("gsd_uat_exec"));
   assert.ok(result.includes("gsd_uat_result_save"));
+  assert.ok(result.includes("read"));
   assert.ok(result.includes("browser_navigate"));
   assert.ok(result.includes("browser_click"));
   assert.ok(!result.includes("browser_screenshot"), "provider-filtered screenshot tool must stay filtered");
   assert.ok(!result.includes("ToolSearch"));
   assert.ok(!result.includes("bash"));
-  assert.ok(!result.includes("read"));
   assert.ok(!result.includes("gsd_exec"));
   assert.ok(!result.includes("gsd_summary_save"));
   assert.ok(!result.includes("gsd_save_gate_result"));

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

@@ -48,12 +48,52 @@ test("auto execute-task requires canonical task completion tool", () => {
   assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), ["gsd_task_complete"]);
 });
 
+test("plan-slice requires planning and roadmap reassessment tools", () => {
+  const expected = ["gsd_plan_slice", "gsd_reassess_roadmap"];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("plan-slice"), expected);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("plan-slice"), expected);
+});
+
+test("plan-milestone requires status, roadmap, and single-slice planning tools", () => {
+  const expected = ["gsd_milestone_status", "gsd_plan_milestone", "gsd_plan_slice"];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("plan-milestone"), expected);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("plan-milestone"), expected);
+});
+
+test("refine-slice requires canonical slice planning tool", () => {
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("refine-slice"), ["gsd_plan_slice"]);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("refine-slice"), ["gsd_plan_slice"]);
+});
+
 test("complete-slice requires closeout and execution handoff tools", () => {
-  const expected = ["gsd_slice_complete", "gsd_task_reopen", "gsd_replan_slice"];
+  const expected = [
+    "gsd_slice_complete",
+    "gsd_task_reopen",
+    "gsd_replan_slice",
+    "gsd_requirement_update",
+    "gsd_summary_save",
+  ];
   assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("complete-slice"), expected);
   assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("complete-slice"), expected);
 });
 
+test("complete-milestone requires status, requirement, project refresh, and closeout tools", () => {
+  const expected = [
+    "gsd_milestone_status",
+    "gsd_requirement_update",
+    "gsd_summary_save",
+    "gsd_complete_milestone",
+  ];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("complete-milestone"), expected);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("complete-milestone"), expected);
+});
+
+test("reactive-execute requires task completion and failed-task summary tools", () => {
+  const expected = ["gsd_task_complete", "gsd_summary_save"];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("reactive-execute"), expected);
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("reactive-execute"), expected);
+});
+
 test("workflow MCP capability surface includes native legacy gsd aliases", () => {
   const err = getWorkflowTransportSupportError(
     "claude-code",
@@ -679,7 +719,7 @@ test("transport compatibility ignores API-backed providers", () => {
 test("transport compatibility now allows plan-slice over workflow MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
-    ["gsd_plan_slice"],
+    getRequiredWorkflowToolsForAutoUnit("plan-slice"),
     {
       projectRoot: "/tmp/project",
       env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
@@ -696,7 +736,7 @@ test("transport compatibility now allows plan-slice over workflow MCP surface",
 test("transport compatibility now allows complete-slice over workflow MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
-    ["gsd_complete_slice"],
+    getRequiredWorkflowToolsForAutoUnit("complete-slice"),
     {
       projectRoot: "/tmp/project",
       env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
@@ -747,7 +787,7 @@ test("transport compatibility now allows gate-evaluate over workflow MCP surface
 test("transport compatibility now allows validate-milestone over workflow MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
-    ["gsd_milestone_status", "gsd_validate_milestone"],
+    getRequiredWorkflowToolsForAutoUnit("validate-milestone"),
     {
       projectRoot: "/tmp/project",
       env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
@@ -764,7 +804,7 @@ test("transport compatibility now allows validate-milestone over workflow MCP su
 test("transport compatibility now allows complete-milestone over workflow MCP surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
-    ["gsd_milestone_status", "gsd_complete_milestone"],
+    getRequiredWorkflowToolsForAutoUnit("complete-milestone"),
     {
       projectRoot: "/tmp/project",
       env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
@@ -795,7 +835,7 @@ test("transport compatibility now allows replan-slice over workflow MCP surface"
   assert.equal(error, null);
 });
 
-test("transport compatibility accepts workflow MCP tools absent from parent active tool surface", () => {
+test("transport compatibility rejects MCP tools not connected in active tool surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
     ["gsd_summary_save"],
@@ -810,10 +850,10 @@ test("transport compatibility accepts workflow MCP tools absent from parent acti
     },
   );
 
-  assert.equal(error, null);
+  assert.match(error ?? "", /requires gsd_summary_save/);
 });
 
-test("transport compatibility still checks non-MCP tools against parent active tool surface", () => {
+test("transport compatibility checks all required tools against active tool surface", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",
     ["gsd_summary_save", "secure_env_collect"],
@@ -828,8 +868,9 @@ test("transport compatibility still checks non-MCP tools against parent active t
     },
   );
 
-  assert.match(error ?? "", /requires secure_env_collect/);
-  assert.doesNotMatch(error ?? "", /gsd_summary_save/);
+  assert.match(error ?? "", /requires.*(?:gsd_summary_save|secure_env_collect)/);
+  assert.match(error ?? "", /gsd_summary_save/);
+  assert.match(error ?? "", /secure_env_collect/);
 });
 
 test("transport compatibility still blocks units whose MCP tools are not exposed", () => {
@@ -850,6 +891,32 @@ test("transport compatibility still blocks units whose MCP tools are not exposed
   assert.match(error ?? "", /currently exposes only/);
 });
 
+test("discuss-milestone guided flow does not abort when all required tools are on MCP surface (regression #469)", () => {
+  // Guided flow starts the workflow MCP server as part of dispatch, so the
+  // parent session active-tool list is not authoritative for MCP tools.
+  const discussMilestoneTools = [
+    "gsd_summary_save",
+    "gsd_requirement_save",
+    "gsd_requirement_update",
+    "gsd_plan_milestone",
+    "gsd_milestone_generate_id",
+  ];
+  const error = getWorkflowTransportSupportError(
+    "claude-code",
+    discussMilestoneTools,
+    {
+      projectRoot: "/tmp/project",
+      env: { GSD_WORKFLOW_MCP_COMMAND: "node" },
+      surface: "guided flow",
+      unitType: "discuss-milestone",
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+    },
+  );
+
+  assert.equal(error, null);
+});
+
 test("transport compatibility accepts MCP-namespaced runtime tools", () => {
   const error = getWorkflowTransportSupportError(
     "claude-code",

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

@@ -75,6 +75,11 @@ test("closeout executors reject phase escalation from the wrong active auto unit
     const milestone = await executeCompleteMilestone({} as Parameters<typeof executeCompleteMilestone>[0], "/tmp/project");
     assert.equal(milestone.isError, true);
     assert.match(String(milestone.details.error), /complete_milestone may only run from complete-milestone/);
+
+    const uat = await executeUatResultSave({} as Parameters<typeof executeUatResultSave>[0], "/tmp/project");
+    assert.equal(uat.isError, true);
+    assert.match(String(uat.details.error), /save_uat_result may only run from run-uat/);
+    assert.match(String(uat.details.error), /Tool Contract failure/);
   } finally {
     autoSession.reset();
   }
@@ -643,6 +648,398 @@ test("executeUatResultSave accepts gsd_uat_exec evidence written in a milestone
   }
 });
 
+test("executeUatResultSave supplies canonical presentation and normalizes verdict casing", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-lowercase-verdict";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S03", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S03",
+          checkId: "UAT-01",
+          intent: "uat-artifact-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S03",
+      uatType: "artifact-driven",
+      verdict: "pass",
+      checks: [{
+        id: "UAT-01",
+        description: "Static artifact contract passes",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+        notes: "Artifact check passed.",
+      }],
+      notes: "UAT passed with canonical presentation supplied by the executor.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.verdict, "PASS");
+
+    const attempt = JSON.parse(readFileSync(
+      join(base, ".gsd", "uat", "M001", "S03", "attempt-1.json"),
+      "utf-8",
+    )) as { presentation?: { toolPresentationPlanId?: string; presentedTools?: string[] } };
+    assert.equal(attempt.presentation?.toolPresentationPlanId, "run-uat/default-v1");
+    assert.ok(attempt.presentation?.presentedTools?.includes("gsd_uat_result_save"));
+    assert.ok(attempt.presentation?.presentedTools?.includes("read"));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave supplies direct browser tools for browser-executable UAT", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-direct-browser-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S06", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S06",
+          checkId: "UAT-01",
+          intent: "uat-browser-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S06",
+      uatType: "browser-executable",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Browser flow used browser tools",
+        mode: "browser",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+        notes: "Browser check passed.",
+      }],
+      notes: "UAT passed with browser evidence.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    const attempt = JSON.parse(readFileSync(
+      join(base, ".gsd", "uat", "M001", "S06", "attempt-1.json"),
+      "utf-8",
+    )) as { presentation?: { presentedTools?: string[] } };
+
+    assert.ok(attempt.presentation?.presentedTools?.includes("browser_navigate"));
+    assert.ok(attempt.presentation?.presentedTools?.includes("browser_assert"));
+    assert.equal(
+      attempt.presentation?.presentedTools?.some((toolName) => toolName.startsWith("mcp__gsd-browser__")),
+      false,
+    );
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave merges canonical plan ID and read-only tools when presentation lacks plan ID", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-no-plan-id-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S05", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S05",
+          checkId: "UAT-01",
+          intent: "uat-artifact-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S05",
+      uatType: "artifact-driven",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Presentation plan ID absent from provider call",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+        notes: "Canonical merge should apply even when toolPresentationPlanId is absent.",
+      }],
+      presentation: {
+        surface: "mcp",
+        presentedTools: [
+          "gsd_uat_exec",
+          "gsd_uat_result_save",
+          "gsd_resume",
+          "gsd_milestone_status",
+          "gsd_journal_query",
+        ],
+        blockedTools: [
+          { name: "gsd_exec", reason: "forbidden during run-uat" },
+          { name: "gsd_summary_save", reason: "forbidden during run-uat" },
+          { name: "gsd_save_gate_result", reason: "forbidden during run-uat" },
+        ],
+      },
+      notes: "Provider omitted toolPresentationPlanId; executor must canonicalize.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.verdict, "PASS");
+
+    const attempt = JSON.parse(readFileSync(
+      join(base, ".gsd", "uat", "M001", "S05", "attempt-1.json"),
+      "utf-8",
+    )) as { presentation?: { toolPresentationPlanId?: string; presentedTools?: string[] } };
+    assert.equal(attempt.presentation?.toolPresentationPlanId, "run-uat/default-v1");
+    assert.ok(attempt.presentation?.presentedTools?.includes("read"), "read-only tool must be merged in");
+    assert.ok(attempt.presentation?.presentedTools?.includes("gsd_uat_result_save"));
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave surfaces the worktree validation path for NEEDS-HUMAN checks", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-human-validation-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S07", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S07",
+          checkId: "UAT-01",
+          intent: "uat-runtime-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S07",
+      uatType: "human-experience",
+      verdict: "PASS",
+      checks: [
+        {
+          id: "UAT-01",
+          description: "Service boots and renders the dashboard",
+          mode: "runtime",
+          result: "PASS",
+          evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+          notes: "Boot check passed.",
+        },
+        {
+          id: "UAT-02",
+          description: "Dashboard layout feels balanced",
+          mode: "human-follow-up",
+          result: "NEEDS-HUMAN",
+          nonAutomatable: true,
+          notes: "Open the app and eyeball the spacing.",
+        },
+      ],
+      notes: "Automatable checks passed; layout taste needs a human.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.verdict, "PASS");
+    // The reviewer needs the buried worktree checkout path, not just the file.
+    assert.equal(result.details.manualValidationPath, worktree);
+    const returnedText = (result.content[0] as { text: string }).text;
+    assert.match(returnedText, /Manual validation needed/);
+    assert.ok(returnedText.includes(worktree), "tool return should include the worktree path");
+
+    const assessment = readFileSync(
+      join(base, ".gsd", "milestones", "M001", "slices", "S07", "S07-ASSESSMENT.md"),
+      "utf-8",
+    );
+    assert.match(assessment, /## Manual Validation/);
+    assert.ok(assessment.includes(worktree), "assessment should include the worktree checkout path");
+    assert.match(assessment, /git worktree/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave omits manual-validation guidance when no human checks remain", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "uat-no-human-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S08", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: {
+          kind: "uat_exec",
+          milestoneId: "M001",
+          sliceId: "S08",
+          checkId: "UAT-01",
+          intent: "uat-artifact-check",
+        },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S08",
+      uatType: "artifact-driven",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Config file exists",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: evidenceId }],
+        notes: "Artifact present.",
+      }],
+      notes: "Fully automated pass.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, undefined);
+    assert.equal(result.details.manualValidationPath, undefined);
+    const returnedText = (result.content[0] as { text: string }).text;
+    assert.equal(returnedText.includes("Manual validation needed"), false);
+
+    const assessment = readFileSync(
+      join(base, ".gsd", "milestones", "M001", "slices", "S08", "S08-ASSESSMENT.md"),
+      "utf-8",
+    );
+    assert.equal(assessment.includes("## Manual Validation"), false);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave rejects saved UAT without fresh UAT-owned evidence", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  const worktreeExecDir = join(worktree, ".gsd", "exec");
+  const evidenceId = "generic-exec-evidence";
+  try {
+    openTestDb(base);
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S04", "complete");
+    mkdirSync(worktreeExecDir, { recursive: true });
+    writeFileSync(
+      join(worktreeExecDir, `${evidenceId}.meta.json`),
+      JSON.stringify({
+        id: evidenceId,
+        metadata: { kind: "exec" },
+      }),
+      "utf-8",
+    );
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S04",
+      uatType: "artifact-driven",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Static artifact contract passes",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_exec", ref: evidenceId }],
+        notes: "Generic evidence should not satisfy fresh UAT evidence.",
+      }],
+      notes: "UAT should not pass without fresh UAT-owned evidence.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, true);
+    assert.match(String(result.content[0]?.text), /fresh gsd_uat_exec evidence/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
+test("executeUatResultSave rejects an unrecognized uatType", async () => {
+  const base = makeTmpBase();
+  const worktree = join(base, ".gsd", "worktrees", "M001");
+  try {
+    openTestDb(base);
+    mkdirSync(worktree, { recursive: true });
+    seedMilestone("M001", "Milestone One");
+    seedSlice("M001", "S06", "complete");
+
+    const result = await inProjectDir(worktree, () => executeUatResultSave({
+      milestoneId: "M001",
+      sliceId: "S06",
+      uatType: "hallucinated-mode",
+      verdict: "PASS",
+      checks: [{
+        id: "UAT-01",
+        description: "Static artifact contract passes",
+        mode: "artifact",
+        result: "PASS",
+        evidence: [{ kind: "gsd_uat_exec", ref: "some-ref" }],
+      }],
+      notes: "Should fail before evidence validation.",
+    } as unknown as Parameters<typeof executeUatResultSave>[0], worktree));
+
+    assert.equal(result.isError, true);
+    assert.match(String(result.content[0]?.text), /uatType must be one of/);
+  } finally {
+    closeDatabase();
+    cleanup(base);
+  }
+});
+
 test("executeUatResultSave rejects artifact-driven PASS with human follow-up checks", async () => {
   const base = makeTmpBase();
   const worktree = join(base, ".gsd", "worktrees", "M001");
@@ -1409,6 +1806,10 @@ test("executeSummarySave blocks final root artifacts while approval gate is pend
 
     assert.equal(result.isError, true);
     assert.equal(result.details.error, "root_artifact_write_blocked");
+    assert.equal(
+      result.details.displayReason,
+      "Approval confirmation required before saving final project setup artifacts.",
+    );
     assert.match(result.content[0].text, /has not been confirmed/);
     assert.equal(existsSync(join(base, ".gsd", "REQUIREMENTS.md")), false);
 
@@ -1451,6 +1852,10 @@ test("executeSummarySave requires verified root approval in deep mode", async ()
 
     assert.equal(blocked.isError, true);
     assert.equal(blocked.details.error, "root_artifact_write_blocked");
+    assert.equal(
+      blocked.details.displayReason,
+      "Approval confirmation required before saving final project setup artifacts.",
+    );
     assert.match(blocked.content[0].text, /fail-closed/);
     assert.equal(existsSync(join(base, ".gsd", "PROJECT.md")), false);
 
@@ -1667,6 +2072,10 @@ test("executeSummarySave CONTEXT HARD BLOCK clears after write-gate state file i
       content: "# Context\n\ncontent",
     }, base));
     assert.equal(blocked.isError, true, "should be blocked without depth verification");
+    assert.equal(
+      blocked.details.displayReason,
+      "Depth check required before writing milestone context.",
+    );
     assert.match(
       blocked.content[0].text,
       /HARD BLOCK/,