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

package/src/resources/extensions/gsd/tests/merge-db-cycle.test.ts

@@ -15,7 +15,7 @@ import { delimiter, join } from "node:path";
 import { execFileSync } from "node:child_process";
 
 import { mergeMilestoneToMain } from "../auto-worktree.ts";
-import { closeDatabase, openDatabase } from "../gsd-db.ts";
+import { closeDatabase, insertAssessment, insertMilestone, insertSlice, openDatabase } from "../gsd-db.ts";
 import { GIT_NO_PROMPT_ENV } from "../git-constants.js";
 import { _clearGsdRootCache } from "../paths.ts";
 import { _resetServiceCache } from "../worktree.ts";
@@ -145,6 +145,15 @@ test("mergeMilestoneToMain keeps the Windows DB cycle closed through squash merg
 
     withPlatform("win32", () => {
       assert.equal(openDatabase(join(repo, ".gsd", "gsd.db")), true);
+      insertMilestone({ id: "M001", title: "Windows DB cycle", status: "complete" });
+      insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete" });
+      insertAssessment({
+        path: "milestones/M001/M001-VALIDATION.md",
+        milestoneId: "M001",
+        status: "pass",
+        scope: "milestone-validation",
+        fullContent: "verdict: pass",
+      });
       assert.equal(existsSync(join(repo, ".gsd", "gsd.db-shm")), true);
 
       process.env.PATH = `${bin}${delimiter}${originalPath}`;

package/src/resources/extensions/gsd/tests/milestone-closeout.test.ts

@@ -6,7 +6,7 @@ import assert from "node:assert/strict";
 import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
-import { openDatabase, insertMilestone, closeDatabase } from "../gsd-db.js";
+import { openDatabase, insertAssessment, insertMilestone, insertSlice, closeDatabase } from "../gsd-db.js";
 import {
   isMilestoneCloseoutSettled,
   evaluateCompleteMilestoneDispatch,
@@ -39,6 +39,14 @@ test("isMilestoneCloseoutSettled requires DB closed and summary artifact", async
   mkdirSync(join(base, ".gsd"), { recursive: true });
   openDatabase(join(base, ".gsd", "gsd.db"));
   insertMilestone({ id: "M001", title: "Done", status: "complete" });
+  insertSlice({ id: "S01", milestoneId: "M001", title: "Done Slice", status: "complete" });
+  insertAssessment({
+    path: "milestones/M001/M001-VALIDATION.md",
+    milestoneId: "M001",
+    status: "pass",
+    scope: "milestone-validation",
+    fullContent: "verdict: pass",
+  });
   const milestoneDir = join(base, ".gsd", "milestones", "M001");
   mkdirSync(milestoneDir, { recursive: true });
   writeFileSync(join(milestoneDir, "M001-SUMMARY.md"), "# Milestone Summary\n");

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

@@ -2,7 +2,12 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.ts";
+import {
+  buildRunUatResultPresentation,
+  RUN_UAT_READ_ONLY_TOOL_NAMES,
+  RUN_UAT_TOOL_PRESENTATION_PLAN_ID,
+  RUN_UAT_WORKFLOW_TOOL_NAMES,
+} from "../tool-presentation-plan.ts";
 
 const promptsDir = join(process.cwd(), "src/resources/extensions/gsd/prompts");
 const templatesDir = join(process.cwd(), "src/resources/extensions/gsd/templates");
@@ -29,7 +34,7 @@ test("run-uat prompt branches on dynamic UAT mode and supports runtime evidence"
   assert.match(prompt, /uatType:\s*"\{\{uatType\}\}"/);
   assert.match(prompt, /gsd_uat_result_save/);
   assert.match(prompt, /presentedTools/);
-  assert.match(prompt, /blockedTools/);
+  assert.match(prompt, /\{\{canonicalPresentation\}\}/);
   assert.match(prompt, /live-runtime/);
   assert.match(prompt, /browser\/runtime\/network/i);
   assert.match(prompt, /NEEDS-HUMAN/);
@@ -51,16 +56,29 @@ test("run-uat prompt gives the complete UAT result-save presentation contract",
   const prompt = readPrompt("run-uat");
   assert.match(prompt, /Call `gsd_uat_result_save` once after all checks are complete/);
   assert.doesNotMatch(prompt, /Call `gsd_summary_save` with `artifact_type: "ASSESSMENT"`/);
+  assert.match(prompt, /\{\{canonicalPresentation\}\}/);
+  assert.match(prompt, /\{\{toolPresentationPlanId\}\}/);
 
+  const presentation = buildRunUatResultPresentation();
+  assert.equal(presentation.toolPresentationPlanId, RUN_UAT_TOOL_PRESENTATION_PLAN_ID);
   for (const toolName of RUN_UAT_WORKFLOW_TOOL_NAMES) {
-    assert.ok(prompt.includes(`"${toolName}"`), `prompt should include required presented tool ${toolName}`);
+    assert.ok(presentation.presentedTools.includes(toolName), `presentation should include required tool ${toolName}`);
+  }
+  for (const toolName of RUN_UAT_READ_ONLY_TOOL_NAMES) {
+    assert.ok(presentation.presentedTools.includes(toolName), `presentation should include read-only tool ${toolName}`);
   }
 
   for (const toolName of ["gsd_exec", "gsd_summary_save", "gsd_save_gate_result"] as const) {
-    assert.ok(prompt.includes(`name: "${toolName}"`), `prompt should include blocked tool ${toolName}`);
+    assert.ok(
+      presentation.blockedTools.some((entry) => entry.name === toolName),
+      `presentation should include blocked tool ${toolName}`,
+    );
   }
 
-  assert.ok(prompt.includes("forbidden during run-uat"), "prompt should explain blocked run-uat tools");
+  assert.ok(
+    presentation.blockedTools.every((entry) => entry.reason === "forbidden during run-uat"),
+    "presentation should explain blocked run-uat tools",
+  );
 });
 
 test("workflow-start prompt defaults to autonomy instead of per-phase confirmation", () => {

package/src/resources/extensions/gsd/tests/register-hooks-depth-verification.test.ts

@@ -70,6 +70,50 @@ test("register-hooks hard-blocks destructive bash commands outside auto-mode", a
   assert.match(block?.reason ?? "", /IaC apply\/destroy/);
 });
 
+test("register-hooks keeps depth-gate reason model-facing and adds displayReason", async (t) => {
+  const dir = makeTempDir("display-reason");
+  const originalCwd = process.cwd();
+  process.chdir(dir);
+  resetWriteGateState(dir);
+
+  t.after(() => {
+    try {
+      resetWriteGateState(dir);
+    } finally {
+      process.chdir(originalCwd);
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  const handlers = new Map<string, Array<(event: any, ctx?: any) => Promise<any> | any>>();
+  const pi = {
+    on(event: string, handler: (event: any, ctx?: any) => Promise<any> | any) {
+      const existing = handlers.get(event) ?? [];
+      existing.push(handler);
+      handlers.set(event, existing);
+    },
+  } as any;
+
+  registerHooks(pi, []);
+
+  let block: any;
+  for (const handler of handlers.get("tool_call") ?? []) {
+    const result = await handler({
+      toolName: "write",
+      input: {
+        path: join(dir, ".gsd", "milestones", "M001", "M001-CONTEXT.md"),
+        content: "# M001 Context\n",
+      },
+    });
+    if (result?.block) block = result;
+  }
+
+  assert.equal(block?.block, true);
+  assert.match(block?.reason ?? "", /HARD BLOCK: Cannot write to milestone CONTEXT\.md/);
+  assert.match(block?.reason ?? "", /ask_user_questions/);
+  assert.equal(block?.displayReason, "Depth check required before writing milestone context.");
+});
+
 test("register-hooks unlocks milestone depth verification from question id without guided-flow state (#4047)", async (t) => {
   const dir = makeTempDir("manual");
   const originalCwd = process.cwd();

package/src/resources/extensions/gsd/tests/run-uat-composer.test.ts

@@ -123,6 +123,10 @@ test("#4782 phase 3: buildRunUatPrompt inlines UAT and keeps summary/project con
   // Project path is advertised on-demand; full project body is not inlined.
   assert.match(prompt, /\.gsd\/PROJECT\.md/);
   assert.ok(!prompt.includes("Run-UAT composer fixture project"), "run-uat should not inline full project context");
+
+  assert.match(prompt, /"toolPresentationPlanId": "run-uat\/default-v1"/);
+  assert.match(prompt, /"gsd_uat_result_save"/);
+  assert.match(prompt, /"read"/);
 });
 
 test("#4782 phase 3: buildRunUatPrompt omits optional slice summary when file is missing", async (t) => {

package/src/resources/extensions/gsd/tests/runtime-invariant-modules.test.ts

@@ -7,6 +7,7 @@ import assert from "node:assert/strict";
 import { classifyFailure } from "../recovery-classification.js";
 import { reconcileBeforeDispatch } from "../state-reconciliation.js";
 import { compileUnitToolContract } from "../tool-contract.js";
+import { shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
 import type { GSDState } from "../types.js";
 
 function makeState(overrides: Partial<GSDState> = {}): GSDState {
@@ -63,10 +64,35 @@ test("Tool Contract compiles known Unit prompt and tool policy", () => {
   assert.equal(result.ok, true);
   assert.equal(result.ok && result.contract.unitType, "execute-task");
   assert.deepEqual(result.ok && result.contract.requiredWorkflowTools, ["gsd_task_complete"]);
+  assert.deepEqual(result.ok && result.contract.forbiddenWorkflowTools, []);
   assert.equal(result.ok && result.contract.toolsPolicy.mode, "all");
   assert.ok(result.ok && result.contract.validationRules.includes("closeout-tool-present"));
 });
 
+test("Tool Contract records high-risk cross-phase tool boundaries without single-owning every tool", () => {
+  const completeSlice = compileUnitToolContract("complete-slice");
+  const runUat = compileUnitToolContract("run-uat");
+
+  assert.equal(completeSlice.ok, true);
+  assert.ok(
+    completeSlice.ok &&
+      completeSlice.contract.forbiddenWorkflowTools.some((tool) => tool.name === "gsd_uat_result_save"),
+    "complete-slice should explicitly forbid saving UAT Assessments",
+  );
+
+  assert.equal(runUat.ok, true);
+  assert.ok(
+    runUat.ok &&
+      runUat.contract.requiredWorkflowTools.includes("gsd_uat_result_save"),
+    "run-uat should own the UAT result-save tool",
+  );
+  assert.ok(
+    runUat.ok &&
+      runUat.contract.forbiddenWorkflowTools.some((tool) => tool.name === "gsd_exec"),
+    "run-uat should prefer typed UAT execution over generic gsd_exec",
+  );
+});
+
 test("Tool Contract fails closed for unknown Units", () => {
   const result = compileUnitToolContract("custom-step");
 
@@ -74,10 +100,20 @@ test("Tool Contract fails closed for unknown Units", () => {
   assert.equal(!result.ok && result.reason, "unknown-unit-type");
 });
 
+test("auto Unit tool scope blocks complete-slice from saving UAT Assessment", () => {
+  const result = shouldBlockAutoUnitToolCall("complete-slice", "gsd_uat_result_save");
+
+  assert.equal(result.block, true);
+  assert.match(result.reason ?? "", /Tool Contract failure/);
+  assert.match(result.reason ?? "", /Run UAT owns persisted UAT Assessment/);
+});
+
 test("Recovery Classification covers ADR-015 failure families", () => {
   const cases = [
     ["invalid tool schema enum", "tool-schema", "stop"],
+    ["Tool Contract failure: complete-slice cannot use gsd_uat_result_save", "tool-contract", "stop"],
     ["deterministic policy rejection", "deterministic-policy", "stop"],
+    ["cannot legally advance because required UAT Assessment artifact is missing", "lifecycle-progression", "stop"],
     ["stale worker lease", "stale-worker", "stop"],
     ["worktree root missing .git", "worktree-invalid", "stop"],
     ["verification drift in state snapshot", "verification-drift", "escalate"],

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-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,210 @@ 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 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 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 +1618,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 +1664,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 +1884,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/,

package/src/resources/extensions/gsd/tests/write-gate-planning-unit.test.ts

@@ -9,6 +9,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 import { join, sep } from 'node:path';
 
+import { GSD_PHASE_SCOPE_DISPLAY_REASON } from '../auto-unit-tool-scope.ts';
 import { ALLOWED_PLANNING_DISPATCH_AGENTS, shouldBlockPlanningUnit } from '../bootstrap/write-gate.ts';
 import { extractSubagentAgentClasses } from '../bootstrap/subagent-input.ts';
 import { isDeterministicPolicyError } from '../auto-tool-tracking.ts';
@@ -65,6 +66,19 @@ test('planning-unit: deterministic block reason is suitable for retry short-circ
   assert.strictEqual(isDeterministicPolicyError(r.reason!), true);
 });
 
+test('planning-unit: blocked tool-policy calls include UI-safe display reason', () => {
+  const r = shouldBlockPlanningUnit(
+    'edit',
+    'src/main.ts',
+    BASE,
+    'discuss-milestone',
+    PLANNING,
+  );
+  assert.strictEqual(r.block, true);
+  assert.match(r.reason!, /HARD BLOCK/);
+  assert.strictEqual(r.displayReason, GSD_PHASE_SCOPE_DISPLAY_REASON);
+});
+
 test('planning-unit: blocks write to user source via relative path', () => {
   const r = shouldBlockPlanningUnit('write', 'src/main.ts', BASE, 'plan-milestone', PLANNING);
   assert.strictEqual(r.block, true);
@@ -367,6 +381,7 @@ test('auto-unit scope: execute-task allows only its task completion lifecycle to
   assert.strictEqual(blocked.block, true);
   assert.match(blocked.reason!, /HARD BLOCK/);
   assert.match(blocked.reason!, /gsd_save_gate_result/);
+  assert.strictEqual(blocked.displayReason, GSD_PHASE_SCOPE_DISPLAY_REASON);
   assert.strictEqual(isDeterministicPolicyError(blocked.reason!), true);
 });
 

package/src/resources/extensions/gsd/tool-contract.ts

@@ -8,12 +8,14 @@ import {
   type ToolsPolicy,
 } from "./unit-context-manifest.js";
 import { getRequiredWorkflowToolsForAutoUnit } from "./workflow-mcp.js";
+import { getUnitToolSurfaceContract } from "./unit-tool-contracts.js";
 
 export interface UnitToolContract {
   unitType: string;
   contextMode: ContextModePolicy;
   toolsPolicy: ToolsPolicy;
   requiredWorkflowTools: readonly string[];
+  forbiddenWorkflowTools: readonly { name: string; reason: string }[];
   promptObligations: readonly string[];
   validationRules: readonly string[];
   closeoutTools: readonly string[];
@@ -30,6 +32,7 @@ export type ToolContractResult =
 
 export function compileUnitToolContract(unitType: string): ToolContractResult {
   const manifest = resolveManifest(unitType);
+  const surfaceContract = getUnitToolSurfaceContract(unitType);
   if (!manifest) {
     return {
       ok: false,
@@ -39,6 +42,8 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
   }
 
   const requiredWorkflowTools = getRequiredWorkflowToolsForAutoUnit(unitType);
+  const forbiddenWorkflowTools = Object.entries(surfaceContract?.forbiddenGsdTools ?? {})
+    .map(([name, reason]) => ({ name, reason }));
   const closeoutTools = requiredWorkflowTools.filter((tool) =>
     /^gsd_(?:task|slice|milestone|complete|validate|save|summary)/.test(tool),
   );
@@ -58,6 +63,7 @@ export function compileUnitToolContract(unitType: string): ToolContractResult {
       contextMode: manifest.contextMode,
       toolsPolicy: manifest.tools,
       requiredWorkflowTools,
+      forbiddenWorkflowTools,
       promptObligations: [
         `context-mode:${manifest.contextMode}`,
         `tools-policy:${manifest.tools.mode}`,