@opengsd/gsd-pi 1.2.0-dev.5457a158 → 1.2.0-dev.6ccd27b3

package/src/resources/extensions/gsd/tests/tool-surface-readiness.test.ts

@@ -4,7 +4,8 @@
 import { describe, test } from "node:test";
 import assert from "node:assert/strict";
 
-import { getToolSurfaceReadinessError } from "../tool-surface-readiness.ts";
+import { getToolSurfaceReadinessError, awaitWorkflowMcpToolRegistration } from "../tool-surface-readiness.ts";
+import { clearWorkflowMcpProbeCache, recordWorkflowMcpProbe } from "../workflow-mcp-readiness-cache.ts";
 import { isToolUnavailableError } from "../auto-tool-tracking.ts";
 import { classifyError, isTransient } from "../error-classifier.ts";
 import { toMcpToolName } from "../mcp-tool-name.ts";
@@ -58,18 +59,82 @@ describe("getToolSurfaceReadinessError", () => {
     assert.match(error, /gsd_uat_exec/);
   });
 
-  test("passes a still-connecting (pending) server through instead of aborting", () => {
-    // The SDK reports still-connecting servers as "pending" at init — the
-    // common healthy session. A genuine miss after pass-through is caught
-    // in-session ("No such tool available" → tool-unavailable → retry).
+  test("still blocks pending init when required tools are absent from the live surface", () => {
     const error = getToolSurfaceReadinessError({
-      unitType: "plan-slice",
+      unitType: "run-uat",
       workflowServerName: SERVER,
       observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "pending" }] },
     });
+    assert.ok(error);
+    assert.match(error!, /status is "pending"/);
+    assert.match(error!, /gsd_uat_exec/);
+  });
+
+  test("accepts pending server status when the live init surface already contains every required tool", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: [
+          prefixed("gsd_uat_exec"),
+          prefixed("gsd_uat_result_save"),
+          prefixed("gsd_resume"),
+          prefixed("gsd_milestone_status"),
+          prefixed("gsd_journal_query"),
+        ],
+        mcpServers: [{ name: SERVER, status: "pending" }],
+      },
+    });
     assert.equal(error, null);
   });
 
+  test("does not accept a pending live init surface just because a probe cache covers required tools", () => {
+    clearWorkflowMcpProbeCache();
+    const projectRoot = "/tmp/project-discuss-probe";
+    recordWorkflowMcpProbe(projectRoot, SERVER, [
+      "ask_user_questions",
+      "gsd_summary_save",
+      "gsd_requirement_save",
+      "gsd_requirement_update",
+      "gsd_plan_milestone",
+      "gsd_milestone_generate_id",
+    ]);
+
+    const error = getToolSurfaceReadinessError({
+      unitType: "discuss-milestone",
+      workflowServerName: SERVER,
+      projectRoot,
+      observation: {
+        tools: [],
+        mcpServers: [{ name: SERVER, status: "pending" }],
+      },
+    });
+
+    assert.ok(error, "expected live init tools to be authoritative over direct probe cache");
+    assert.match(error, /status is "pending"/);
+    assert.match(error, /ask_user_questions/);
+  });
+
+  test("pending server status reports only required tools missing from the live init surface", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: [
+          prefixed("gsd_uat_result_save"),
+          prefixed("gsd_resume"),
+          prefixed("gsd_milestone_status"),
+          prefixed("gsd_journal_query"),
+        ],
+        mcpServers: [{ name: SERVER, status: "pending" }],
+      },
+    });
+    assert.ok(error, "expected a readiness error while gsd_uat_exec is still absent");
+    assert.match(error, /status is "pending"/);
+    assert.match(error, /gsd_uat_exec/);
+    assert.doesNotMatch(error, /gsd_uat_result_save/);
+  });
+
   test("returns null when all required tools are registered under the MCP prefix", () => {
     const error = getToolSurfaceReadinessError({
       unitType: "run-uat",
@@ -82,7 +147,7 @@ describe("getToolSurfaceReadinessError", () => {
     assert.equal(error, null);
   });
 
-  test("reports the failed server and the missing tools when the surface never registered", () => {
+  test("reports the failed server as terminal", () => {
     const error = getToolSurfaceReadinessError({
       unitType: "run-uat",
       workflowServerName: SERVER,
@@ -90,7 +155,20 @@ describe("getToolSurfaceReadinessError", () => {
     });
     assert.ok(error, "expected a readiness error");
     assert.match(error, /workflow tool surface not ready for run-uat/);
-    assert.match(error, /status is "failed"/);
+    assert.match(error, /terminal/);
+  });
+
+  test("reports terminal status even when required tools are already on the init surface", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: RUN_UAT_TOOLS.map(prefixed),
+        mcpServers: [{ name: SERVER, status: "failed" }],
+      },
+    });
+    assert.ok(error, "expected a readiness error despite tools on the surface");
+    assert.match(error, /terminal/);
     assert.match(error, /gsd_uat_exec/);
   });
 
@@ -101,7 +179,7 @@ describe("getToolSurfaceReadinessError", () => {
       observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "needs-auth" }] },
     });
     assert.ok(error, "expected a readiness error for needs-auth");
-    assert.match(error, /status is "needs-auth"/);
+    assert.match(error, /terminal/);
   });
 
   test("aborts on disabled (terminal — cannot self-heal)", () => {
@@ -111,7 +189,7 @@ describe("getToolSurfaceReadinessError", () => {
       observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "disabled" }] },
     });
     assert.ok(error, "expected a readiness error for disabled");
-    assert.match(error, /status is "disabled"/);
+    assert.match(error, /terminal/);
   });
 
   test("reports partially-registered surfaces even when the server says connected", () => {
@@ -128,6 +206,102 @@ describe("getToolSurfaceReadinessError", () => {
     assert.match(error, /gsd_uat_result_save/);
     assert.doesNotMatch(error, /gsd_uat_exec,/);
   });
+
+  test("reports the screenshot case: result save registered but UAT exec missing", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: [
+          prefixed("gsd_uat_result_save"),
+          prefixed("gsd_resume"),
+          prefixed("gsd_milestone_status"),
+          prefixed("gsd_journal_query"),
+        ],
+        mcpServers: [{ name: SERVER, status: "connected" }],
+      },
+    });
+    assert.ok(error, "expected a readiness error when gsd_uat_exec is absent");
+    assert.match(error, /connected but has not registered/);
+    assert.match(error, /gsd_uat_exec/);
+    assert.doesNotMatch(error, /gsd_uat_result_save/);
+  });
+});
+
+describe("awaitWorkflowMcpToolRegistration", () => {
+  test("does not skip live probe when cache already covers required tools", async () => {
+    clearWorkflowMcpProbeCache();
+    const { recordWorkflowMcpProbe } = await import("../workflow-mcp-readiness-cache.ts");
+    recordWorkflowMcpProbe("/tmp/project-cache-hit", SERVER, RUN_UAT_TOOLS);
+
+    let probeCalls = 0;
+    const error = await awaitWorkflowMcpToolRegistration({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      projectRoot: "/tmp/project-cache-hit",
+      timeoutMs: 1,
+      pollMs: 1,
+      probe: async () => {
+        probeCalls += 1;
+        return { ok: true, tools: RUN_UAT_TOOLS };
+      },
+    });
+    assert.equal(error, null);
+    assert.ok(probeCalls > 0, "preflight must probe the live MCP server even when cache is warm");
+  });
+
+  test("resolves when probe reports required tools", async () => {
+    clearWorkflowMcpProbeCache();
+    const error = await awaitWorkflowMcpToolRegistration({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      projectRoot: "/tmp/project",
+      timeoutMs: 1_000,
+      pollMs: 1,
+      probe: async () => ({
+        ok: true,
+        tools: RUN_UAT_TOOLS,
+      }),
+    });
+    assert.equal(error, null);
+  });
+
+  test("times out when required tools never register", async () => {
+    clearWorkflowMcpProbeCache();
+    const error = await awaitWorkflowMcpToolRegistration({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      projectRoot: "/tmp/project",
+      timeoutMs: 5,
+      pollMs: 1,
+      probe: async () => ({ ok: true, tools: ["gsd_uat_result_save"] }),
+    });
+    assert.ok(error);
+    assert.match(error!, /did not register required tools before session start/);
+  });
+
+  test("aborts while waiting for workflow MCP tools", async () => {
+    clearWorkflowMcpProbeCache();
+    const controller = new AbortController();
+    let probeCount = 0;
+    const wait = awaitWorkflowMcpToolRegistration({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      projectRoot: "/tmp/project-abort",
+      timeoutMs: 10_000,
+      pollMs: 10_000,
+      signal: controller.signal,
+      probe: async () => {
+        probeCount += 1;
+        return { ok: true, tools: ["gsd_uat_result_save"] };
+      },
+    });
+
+    controller.abort();
+
+    await assert.rejects(wait, /AbortError/);
+    assert.equal(probeCount, 1);
+  });
 });
 
 describe("readiness error classification contract", () => {

package/src/resources/extensions/gsd/tests/tool-unavailable-retry.test.ts

@@ -0,0 +1,33 @@
+/**
+ * Regression test for MCP tool-availability race.
+ *
+ * When the MCP workflow server is still connecting, tool calls fail with
+ * "No such tool available". The bounded retry counter on AutoSession
+ * (toolUnavailableRetries) prevents infinite re-dispatch loops by capping
+ * retries at 3 with escalating delay, then pausing auto-mode.
+ */
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { AutoSession } from "../auto/session.ts";
+
+describe("toolUnavailableRetries on AutoSession", () => {
+  test("defaults to 0", () => {
+    const s = new AutoSession();
+    assert.equal(s.toolUnavailableRetries, 0);
+  });
+
+  test("is cleared on reset()", () => {
+    const s = new AutoSession();
+    s.toolUnavailableRetries = 2;
+    s.reset();
+    assert.equal(s.toolUnavailableRetries, 0);
+  });
+
+  test("accumulates across assignments (simulates retry increments)", () => {
+    const s = new AutoSession();
+    s.toolUnavailableRetries = 1;
+    s.toolUnavailableRetries = 2;
+    s.toolUnavailableRetries = 3;
+    assert.equal(s.toolUnavailableRetries, 3);
+  });
+});

package/src/resources/extensions/gsd/tests/transport-gate-double-complete.test.ts

@@ -0,0 +1,139 @@
+// gsd-pi — Regression tests for the centralized transport gate and
+// milestone double-complete guard (auto-dispatch.ts + phases.ts).
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { resolveDispatch } from "../auto-dispatch.ts";
+import { openDatabase, closeDatabase, insertMilestone, getMilestone } from "../gsd-db.ts";
+import { isClosedStatus } from "../status-guards.ts";
+import { getWorkflowTransportSupportError } from "../workflow-mcp.ts";
+
+// ── transport gate: getWorkflowTransportSupportError blocks missing tools ────
+
+test("getWorkflowTransportSupportError blocks when required non-surface tools are missing", () => {
+  const err = getWorkflowTransportSupportError(
+    "claude-code",
+    ["custom_non_surface_tool"],
+    {
+      projectRoot: process.cwd(),
+      surface: "auto-mode",
+      unitType: "execute-task",
+      authMode: "externalCli",
+      baseUrl: "local://claude-code",
+      activeTools: ["some_other_tool"],
+    },
+  );
+  assert.ok(err, "should return an error when required non-surface tools are missing from activeTools");
+  assert.match(err, /cannot run/i);
+});
+
+test("getWorkflowTransportSupportError passes for non-MCP transport", () => {
+  const err = getWorkflowTransportSupportError(
+    "claude-code",
+    ["custom_non_surface_tool"],
+    {
+      projectRoot: process.cwd(),
+      surface: "auto-mode",
+      unitType: "execute-task",
+      authMode: "apiKey",
+      baseUrl: "https://api.anthropic.com",
+      activeTools: [],
+    },
+  );
+  assert.equal(err, null, "non-MCP transport should not be blocked");
+});
+
+test("resolveDispatch allows dispatch when MCP tools are available", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-transport-pass-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  insertMilestone({ id: "M001", title: "Test", status: "active" });
+
+  const action = await resolveDispatch({
+    basePath: base,
+    mid: "M001",
+    midTitle: "Test",
+    state: {
+      phase: "executing",
+      activeMilestone: { id: "M001", title: "Test", status: "active" },
+      activeSlice: { id: "S01", title: "Slice" },
+      activeTask: { id: "M001/S01/T01", title: "Task", status: "pending" },
+      registry: [],
+      blockers: [],
+    } as any,
+    prefs: undefined,
+    // No transport gate deps → no MCP check → dispatch should go through
+  });
+
+  assert.equal(action.action, "dispatch");
+});
+
+// ── double-complete guard: isClosedStatus prevents duplicate closeout ────────
+
+test("isClosedStatus detects complete milestone status", () => {
+  assert.equal(isClosedStatus("complete"), true);
+  assert.equal(isClosedStatus("done"), true);
+  assert.equal(isClosedStatus("skipped"), true);
+  assert.equal(isClosedStatus("closed"), true);
+  assert.equal(isClosedStatus("active"), false);
+  assert.equal(isClosedStatus("pending"), false);
+  assert.equal(isClosedStatus(""), false);
+});
+
+test("getMilestone + isClosedStatus guards against double-complete dispatch", (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-double-complete-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  insertMilestone({ id: "M001", title: "Test", status: "complete" });
+
+  // resolveDispatch itself checks for closed milestones at the top
+  // (before any dispatch rule fires), which is the same guard used
+  // by the phases.ts double-complete check.
+  const milestone = getMilestone("M001");
+  assert.ok(milestone, "milestone should exist in DB");
+  assert.equal(isClosedStatus(milestone.status), true, "closed milestone must be detected");
+});
+
+test("resolveDispatch stops on closed milestone before dispatching", async (t) => {
+  const base = mkdtempSync(join(tmpdir(), "gsd-closed-milestone-"));
+  mkdirSync(join(base, ".gsd"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  t.after(() => {
+    closeDatabase();
+    rmSync(base, { recursive: true, force: true });
+  });
+
+  insertMilestone({ id: "M001", title: "Test", status: "complete" });
+
+  const action = await resolveDispatch({
+    basePath: base,
+    mid: "M001",
+    midTitle: "Test",
+    state: {
+      phase: "complete",
+      activeMilestone: { id: "M001", title: "Test", status: "complete" },
+      activeSlice: null,
+      activeTask: null,
+      registry: [],
+      blockers: [],
+    } as any,
+    prefs: undefined,
+  });
+
+  assert.equal(action.action, "stop");
+  assert.match(action.reason ?? "", /closed/i);
+});

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

@@ -3,9 +3,9 @@ import assert from "node:assert/strict";
 
 import {
   classifyUatContent,
+  classifyUatContentForRun,
   getDeclaredUatType,
   getUatBrowserToolSupportError,
-  hasUatBrowserToolSurface,
   isPartialEligibleUatType,
   resolveEffectiveUatType,
   shouldDispatchUatForContent,
@@ -13,12 +13,104 @@ import {
   uatTypeIncludesBrowser,
   validateUatModePolicy,
 } from "../uat-policy.ts";
+import {
+  assertBrowserAutomationContractAvailable,
+  assertBrowserAutomationContractMissing,
+  assertBrowserBackedUatCanDispatch,
+  BROWSER_AUTOMATION_CONTRACT_TOOLS,
+} from "./browser-automation-contract-fixture.ts";
 
 describe("uat-policy", () => {
   it("defaults missing UAT mode to artifact-driven", () => {
     assert.equal(getDeclaredUatType("# UAT\n\nCheck generated files."), "artifact-driven");
   });
 
+  it("parses a bare keyword under ## UAT Type (M006/S01 agent format drift)", () => {
+    const content = [
+      "# S01 UAT",
+      "",
+      "## UAT Type",
+      "browser-executable",
+      "",
+      "## Preconditions",
+      "- Run `node tests/browser/search-uat.mjs` (it starts its own server on an ephemeral port; do not start serve-static separately).",
+    ].join("\n");
+    assert.equal(getDeclaredUatType(content), "browser-executable");
+    assert.equal(shouldEscalateArtifactUatToBrowser(content), false);
+  });
+
+  it("promotes browser-executable UAT when slice context names test:uat but UAT only documents test:server (M007/S01)", () => {
+    const uatFile = [
+      "# S01 UAT",
+      "",
+      "## UAT Type",
+      "- UAT mode: browser-executable",
+      "",
+      "## Preconditions",
+      "- Start the dev/local verification server with `npm run test:server`.",
+      "- Open the app at the localhost URL printed by the server.",
+    ].join("\n");
+    const sliceContext = [
+      "Fresh slice-level verification ran via `gsd_exec` with `npm run test:uat` and passed.",
+      "The run produced PASS with browser diagnostics consoleErrors=0.",
+    ].join("\n");
+
+    assert.equal(classifyUatContentForRun(uatFile, sliceContext).effectiveType, "runtime-executable");
+    assert.equal(classifyUatContentForRun(uatFile).effectiveType, "browser-executable");
+  });
+
+  it("promotes browser-executable UAT to runtime-executable when a self-contained harness is named (M006/S01)", () => {
+    const content = [
+      "# S01 UAT",
+      "",
+      "## UAT Type",
+      "- UAT mode: browser-executable",
+      "",
+      "## Preconditions",
+      "- Start the local app server with `npm run start`.",
+      "- Open the app at `http://127.0.0.1:4173`.",
+      "",
+      "## Evidence",
+      "- Fresh closeout verification command: `node --check app.js && node --check tests/browser/search-uat.mjs && npm run test:uat`",
+    ].join("\n");
+
+    assert.equal(resolveEffectiveUatType(content), "runtime-executable");
+    assert.deepEqual(classifyUatContent(content), {
+      declaredType: "browser-executable",
+      modeDeclared: true,
+      effectiveType: "runtime-executable",
+      browserRequired: false,
+      shouldDispatchByDefault: true,
+    });
+  });
+
+  it("parses a UAT mode line case-insensitively with bold markers", () => {
+    const content = [
+      "## UAT Type",
+      "- **UAT Mode:** Runtime-Executable (npx playwright test)",
+    ].join("\n");
+    assert.equal(getDeclaredUatType(content), "runtime-executable");
+  });
+
+  it("does not parse prose in the section as a mode declaration", () => {
+    const content = [
+      "## UAT Type",
+      "- Why this mode is sufficient: static checks cover the schema.",
+    ].join("\n");
+    assert.equal(getDeclaredUatType(content), "artifact-driven");
+  });
+
+  it("treats an explicit UAT mode line with an unrecognised value as undeclared", () => {
+    const content = [
+      "## UAT Type",
+      "- UAT mode: manual-spot-check",
+      "- browser-executable would also work",
+    ].join("\n");
+    // The explicit declaration wins (and fails to parse) — the stray keyword
+    // bullet below it must not be promoted to the declared mode.
+    assert.equal(getDeclaredUatType(content), "artifact-driven");
+  });
+
   it("escalates artifact-driven UAT to browser-executable when the spec requires browser work", () => {
     const content = [
       "## UAT Type",
@@ -33,6 +125,7 @@ describe("uat-policy", () => {
     assert.equal(shouldDispatchUatForContent(content, undefined), true);
     assert.deepEqual(classifyUatContent(content), {
       declaredType: "artifact-driven",
+      modeDeclared: true,
       effectiveType: "browser-executable",
       browserRequired: true,
       shouldDispatchByDefault: true,
@@ -63,14 +156,14 @@ describe("uat-policy", () => {
     }
   });
 
-  it("detects direct and MCP-shaped browser tool surfaces", () => {
-    assert.equal(hasUatBrowserToolSurface(["read", "browser_navigate"]), true);
-    assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-browser__browser_navigate"]), true);
-    assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-browser__*"]), true);
-    assert.equal(hasUatBrowserToolSurface(["read", "mcp__browser-uat__*"]), true);
-    assert.equal(hasUatBrowserToolSurface(["read", "mcp__gsd-workflow__*"]), false);
-    assert.equal(hasUatBrowserToolSurface(["read", "gsd_uat_exec"]), false);
-    assert.equal(hasUatBrowserToolSurface(undefined), false);
+  it("detects Browser Automation Contract capability across adapters", () => {
+    assertBrowserAutomationContractAvailable(BROWSER_AUTOMATION_CONTRACT_TOOLS.piProvider);
+    assertBrowserAutomationContractAvailable(BROWSER_AUTOMATION_CONTRACT_TOOLS.externalMcpClient);
+    assertBrowserAutomationContractAvailable(BROWSER_AUTOMATION_CONTRACT_TOOLS.externalMcpWildcard);
+    assertBrowserAutomationContractAvailable(BROWSER_AUTOMATION_CONTRACT_TOOLS.otherBrowserMcp);
+    assertBrowserAutomationContractMissing(BROWSER_AUTOMATION_CONTRACT_TOOLS.workflowOnly);
+    assertBrowserAutomationContractMissing(BROWSER_AUTOMATION_CONTRACT_TOOLS.withoutBrowser);
+    assertBrowserAutomationContractMissing(undefined);
   });
 
   it("reports missing browser tools only for browser-backed UAT with a known tool snapshot", () => {
@@ -92,26 +185,16 @@ describe("uat-policy", () => {
       }),
       null,
     );
-    assert.equal(
-      getUatBrowserToolSupportError({
-        uatType: "human-experience",
-        activeTools: ["read", "gsd_uat_exec"],
-        registeredTools: ["browser_navigate"],
-        milestoneId: "M001",
-        sliceId: "S01",
-      }),
-      null,
-    );
-    assert.equal(
-      getUatBrowserToolSupportError({
-        uatType: "human-experience",
-        activeTools: ["read", "gsd_uat_exec"],
-        registeredTools: ["mcp__gsd-browser__*"],
-        milestoneId: "M001",
-        sliceId: "S01",
-      }),
-      null,
-    );
+    assertBrowserBackedUatCanDispatch({
+      uatType: "human-experience",
+      activeTools: BROWSER_AUTOMATION_CONTRACT_TOOLS.withoutBrowser,
+      registeredTools: BROWSER_AUTOMATION_CONTRACT_TOOLS.piProvider,
+    });
+    assertBrowserBackedUatCanDispatch({
+      uatType: "human-experience",
+      activeTools: BROWSER_AUTOMATION_CONTRACT_TOOLS.withoutBrowser,
+      registeredTools: BROWSER_AUTOMATION_CONTRACT_TOOLS.externalMcpWildcard,
+    });
 
     const error = getUatBrowserToolSupportError({
       uatType: "browser-executable",

package/src/resources/extensions/gsd/tests/unit-context-composer.test.ts

@@ -11,6 +11,7 @@ import {
   composeContractedUnitContext,
   composeContextModeInstructions,
   composeInlinedContext,
+  composeToolSurfaceInstructions,
   composeUnitContext,
   manifestBudgetChars,
   type ArtifactResolver,
@@ -203,6 +204,49 @@ test("Context Mode composer: workflow-preferences and research-decision render n
   );
 });
 
+test("Tool Surface composer: run-uat forbids gsd_exec and Bash", () => {
+  const out = composeToolSurfaceInstructions("run-uat", { renderMode: "standalone" });
+  assert.match(out, /^## Tool Surface/);
+  assert.match(out, /Do not call `gsd_exec`/);
+  assert.match(out, /`Bash`/);
+  assert.match(out, /`gsd_uat_exec`/);
+  assert.match(out, /`gsd_save_gate_result`/);
+  assert.match(out, /`gsd_summary_save`/);
+});
+
+test("Tool Surface composer: complete-slice steers verification to gsd_exec", () => {
+  const out = composeToolSurfaceInstructions("complete-slice", { renderMode: "standalone" });
+  assert.match(out, /`gsd_exec`/);
+  assert.match(out, /not direct `bash`/);
+  assert.match(out, /`gsd_uat_result_save`/);
+});
+
+test("Tool Surface composer: planning units restrict writes to .gsd", () => {
+  const out = composeToolSurfaceInstructions("discuss-milestone", { renderMode: "standalone" });
+  assert.match(out, /restricted to `\.gsd\/\*\*`/);
+  assert.match(out, /`ask_user_questions`/);
+});
+
+test("Tool Surface composer: planning-dispatch lists allowed subagents", () => {
+  const out = composeToolSurfaceInstructions("plan-slice", { renderMode: "standalone" });
+  assert.match(out, /\*\*scout\*\*/);
+  assert.match(out, /\*\*planner\*\*/);
+});
+
+test("Tool Surface composer: execute-task warns against slice/milestone closeout tools", () => {
+  const out = composeToolSurfaceInstructions("execute-task", { renderMode: "nested" });
+  assert.match(out, /^Tool surface: /);
+  assert.match(out, /`gsd_task_complete`/);
+  assert.match(out, /Do not call `gsd_slice_complete`/);
+});
+
+test("Tool Surface composer: unknown unit renders empty block", () => {
+  assert.strictEqual(
+    composeToolSurfaceInstructions("never-dispatched", { renderMode: "standalone" }),
+    "",
+  );
+});
+
 // ─── Integration: migrated buildReassessRoadmapPrompt ─────────────────────
 
 function makeFixtureBase(): string {