@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

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

@@ -5,6 +5,10 @@ import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { registerDbTools } from '../bootstrap/db-tools.ts';
 import { getLegacyTelemetry, resetLegacyTelemetry } from '../legacy-telemetry.ts';
+import {
+  WORKFLOW_TOOL_ALIAS_PAIRS,
+  WORKFLOW_TOOL_CONTRACTS,
+} from '../workflow-tool-surface.ts';
 
 
 // ─── Mock PI ──────────────────────────────────────────────────────────────────
@@ -17,49 +21,38 @@ function makeMockPi() {
   } as any;
 }
 
-// ─── Rename map ───────────────────────────────────────────────────────────────
-
-const RENAME_MAP: Array<{ canonical: string; alias: string }> = [
-  { canonical: "gsd_decision_save", alias: "gsd_save_decision" },
-  { canonical: "gsd_requirement_update", alias: "gsd_update_requirement" },
-  { canonical: "gsd_requirement_save", alias: "gsd_save_requirement" },
-  { canonical: "gsd_summary_save", alias: "gsd_save_summary" },
-  { canonical: "gsd_milestone_generate_id", alias: "gsd_generate_milestone_id" },
-  { canonical: "gsd_task_complete", alias: "gsd_complete_task" },
-  { canonical: "gsd_slice_complete", alias: "gsd_complete_slice" },
-  { canonical: "gsd_plan_milestone", alias: "gsd_milestone_plan" },
-  { canonical: "gsd_plan_slice", alias: "gsd_slice_plan" },
-  { canonical: "gsd_plan_task", alias: "gsd_task_plan" },
-  { canonical: "gsd_replan_slice", alias: "gsd_slice_replan" },
-  { canonical: "gsd_reassess_roadmap", alias: "gsd_roadmap_reassess" },
-  { canonical: "gsd_complete_milestone", alias: "gsd_milestone_complete" },
-  { canonical: "gsd_validate_milestone", alias: "gsd_milestone_validate" },
-  { canonical: "gsd_task_reopen", alias: "gsd_reopen_task" },
-  { canonical: "gsd_slice_reopen", alias: "gsd_reopen_slice" },
-  { canonical: "gsd_milestone_reopen", alias: "gsd_reopen_milestone" },
-];
-
-const STANDALONE_TOOLS = [
-  "gsd_save_gate_result",
-  "gsd_skip_slice",
-  "gsd_uat_result_save",
-];
-
 // ─── Registration count ──────────────────────────────────────────────────────
 
 console.log('\n── Tool naming: registration count ──');
 
 const pi = makeMockPi();
 registerDbTools(pi);
-
+const toolByName = new Map<string, any>(pi.tools.map((tool: any) => [tool.name, tool]));
+const registeredCanonicalNames = new Set<string>(
+  WORKFLOW_TOOL_CONTRACTS
+    .map((tool) => tool.canonicalName)
+    .filter((name) => toolByName.has(name)),
+);
+const RENAME_MAP = WORKFLOW_TOOL_ALIAS_PAIRS.filter(({ canonical }) =>
+  registeredCanonicalNames.has(canonical),
+);
+const STANDALONE_TOOLS = WORKFLOW_TOOL_CONTRACTS
+  .filter((tool) => registeredCanonicalNames.has(tool.canonicalName) && tool.aliases.length === 0)
+  .map((tool) => tool.canonicalName);
+const expectedRegisteredNames = [
+  ...STANDALONE_TOOLS,
+  ...RENAME_MAP.flatMap(({ canonical, alias }) => [canonical, alias]),
+].sort();
+
+assert.equal(pi.tools.length, toolByName.size, 'Tool registration should not produce duplicate names');
 assert.deepStrictEqual(
-  pi.tools.length,
-  RENAME_MAP.length * 2 + STANDALONE_TOOLS.length,
-  'Should register canonical/alias tool pairs plus standalone DB tools',
+  [...toolByName.keys()].sort(),
+  expectedRegisteredNames,
+  'Should register only workflow surface tools and their declared aliases',
 );
 
 for (const name of STANDALONE_TOOLS) {
-  assert.ok(pi.tools.some((t: any) => t.name === name), `Standalone tool "${name}" should be registered`);
+  assert.ok(toolByName.has(name), `Standalone tool "${name}" should be registered`);
 }
 
 // ─── Both names exist for each pair ──────────────────────────────────────────
@@ -67,8 +60,8 @@ for (const name of STANDALONE_TOOLS) {
 console.log('\n── Tool naming: canonical and alias names exist ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
-  const canonicalTool = pi.tools.find((t: any) => t.name === canonical);
-  const aliasTool = pi.tools.find((t: any) => t.name === alias);
+  const canonicalTool = toolByName.get(canonical);
+  const aliasTool = toolByName.get(alias);
 
   assert.ok(canonicalTool !== undefined, `Canonical tool "${canonical}" should be registered`);
   assert.ok(aliasTool !== undefined, `Alias tool "${alias}" should be registered`);
@@ -79,8 +72,8 @@ for (const { canonical, alias } of RENAME_MAP) {
 console.log('\n── Tool naming: alias execute wrapper ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
-  const canonicalTool = pi.tools.find((t: any) => t.name === canonical);
-  const aliasTool = pi.tools.find((t: any) => t.name === alias);
+  const canonicalTool = toolByName.get(canonical);
+  const aliasTool = toolByName.get(alias);
 
   if (canonicalTool && aliasTool) {
     assert.ok(
@@ -91,8 +84,8 @@ for (const { canonical, alias } of RENAME_MAP) {
 }
 
 test("alias execute increments legacy MCP alias telemetry before delegating", async () => {
-  const canonicalTool = pi.tools.find((t: any) => t.name === "gsd_decision_save");
-  const aliasTool = pi.tools.find((t: any) => t.name === "gsd_save_decision");
+  const canonicalTool = toolByName.get("gsd_decision_save");
+  const aliasTool = toolByName.get("gsd_save_decision");
   assert.ok(canonicalTool);
   assert.ok(aliasTool);
 
@@ -120,7 +113,7 @@ test("alias execute increments legacy MCP alias telemetry before delegating", as
 console.log('\n── Tool naming: alias descriptions ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
-  const aliasTool = pi.tools.find((t: any) => t.name === alias);
+  const aliasTool = toolByName.get(alias);
 
   if (aliasTool) {
     assert.ok(
@@ -135,7 +128,7 @@ for (const { canonical, alias } of RENAME_MAP) {
 console.log('\n── Tool naming: canonical promptGuidelines use canonical name ──');
 
 for (const { canonical } of RENAME_MAP) {
-  const canonicalTool = pi.tools.find((t: any) => t.name === canonical);
+  const canonicalTool = toolByName.get(canonical);
 
   if (canonicalTool) {
     const guidelinesText = canonicalTool.promptGuidelines.join(' ');
@@ -151,7 +144,7 @@ for (const { canonical } of RENAME_MAP) {
 console.log('\n── Tool naming: alias promptGuidelines redirect to canonical ──');
 
 for (const { canonical, alias } of RENAME_MAP) {
-  const aliasTool = pi.tools.find((t: any) => t.name === alias);
+  const aliasTool = toolByName.get(alias);
 
   if (aliasTool) {
     const guidelinesText = aliasTool.promptGuidelines.join(' ');

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

@@ -0,0 +1,155 @@
+// Project/App: gsd-pi
+// File Purpose: Contract coverage for the Tool Surface Readiness gate and its recovery classification.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import { getToolSurfaceReadinessError } from "../tool-surface-readiness.ts";
+import { isToolUnavailableError } from "../auto-tool-tracking.ts";
+import { classifyError, isTransient } from "../error-classifier.ts";
+import { toMcpToolName } from "../mcp-tool-name.ts";
+import { classifyFailure } from "../recovery-classification.ts";
+
+const SERVER = "gsd-workflow";
+
+function prefixed(tool: string): string {
+  return toMcpToolName(SERVER, tool);
+}
+
+const RUN_UAT_TOOLS = [
+  "gsd_uat_exec",
+  "gsd_uat_result_save",
+  "gsd_resume",
+  "gsd_milestone_status",
+  "gsd_journal_query",
+];
+
+describe("getToolSurfaceReadinessError", () => {
+  test("returns null when no unit type or no workflow server is in play", () => {
+    const observation = { tools: [], mcpServers: [] };
+    assert.equal(
+      getToolSurfaceReadinessError({ unitType: undefined, workflowServerName: SERVER, observation }),
+      null,
+    );
+    assert.equal(
+      getToolSurfaceReadinessError({ unitType: "run-uat", workflowServerName: undefined, observation }),
+      null,
+    );
+  });
+
+  test("returns null for units with no required workflow tools", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "rewrite-docs",
+      workflowServerName: SERVER,
+      observation: { tools: [], mcpServers: [{ name: SERVER, status: "failed" }] },
+    });
+    assert.equal(error, null);
+  });
+
+  test("returns an error when the expected workflow server is absent from the init surface", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: "other-server", status: "connected" }] },
+    });
+    assert.ok(error, "expected a readiness error when the workflow server is absent");
+    assert.match(error, /workflow tool surface not ready for run-uat/);
+    assert.match(error, /absent from the init surface/);
+    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).
+    const error = getToolSurfaceReadinessError({
+      unitType: "plan-slice",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "pending" }] },
+    });
+    assert.equal(error, null);
+  });
+
+  test("returns null when all required tools are registered under the MCP prefix", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: ["read", ...RUN_UAT_TOOLS.map(prefixed)],
+        mcpServers: [{ name: SERVER, status: "connected" }],
+      },
+    });
+    assert.equal(error, null);
+  });
+
+  test("reports the failed server and the missing tools when the surface never registered", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "failed" }] },
+    });
+    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, /gsd_uat_exec/);
+  });
+
+  test("aborts on needs-auth (terminal — cannot self-heal)", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      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"/);
+  });
+
+  test("aborts on disabled (terminal — cannot self-heal)", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: { tools: ["read", "bash"], mcpServers: [{ name: SERVER, status: "disabled" }] },
+    });
+    assert.ok(error, "expected a readiness error for disabled");
+    assert.match(error, /status is "disabled"/);
+  });
+
+  test("reports partially-registered surfaces even when the server says connected", () => {
+    const error = getToolSurfaceReadinessError({
+      unitType: "run-uat",
+      workflowServerName: SERVER,
+      observation: {
+        tools: [prefixed("gsd_uat_exec")],
+        mcpServers: [{ name: SERVER, status: "connected" }],
+      },
+    });
+    assert.ok(error, "expected a readiness error");
+    assert.match(error, /connected but has not registered/);
+    assert.match(error, /gsd_uat_result_save/);
+    assert.doesNotMatch(error, /gsd_uat_exec,/);
+  });
+});
+
+describe("readiness error classification contract", () => {
+  const readinessError = getToolSurfaceReadinessError({
+    unitType: "run-uat",
+    workflowServerName: SERVER,
+    observation: { tools: [], mcpServers: [{ name: SERVER, status: "failed" }] },
+  })!;
+
+  test("auto-tool-tracking treats the readiness error as tool-unavailable", () => {
+    assert.equal(isToolUnavailableError(readinessError), true);
+  });
+
+  test("error-classifier treats the readiness error as transient", () => {
+    const cls = classifyError(`Claude Code error: ${readinessError}`);
+    assert.equal(isTransient(cls), true);
+  });
+
+  test("Recovery Classification maps the readiness error to tool-unavailable → retry", () => {
+    const recovery = classifyFailure({ error: new Error(readinessError), unitType: "run-uat", unitId: "M001" });
+    assert.equal(recovery.failureKind, "tool-unavailable");
+    assert.equal(recovery.action, "retry");
+    assert.equal(recovery.exitReason, "tool-unavailable");
+  });
+});

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

@@ -5,7 +5,6 @@ import {
   classifyUatContent,
   getDeclaredUatType,
   getUatBrowserToolSupportError,
-  hasUatBrowserToolSurface,
   isPartialEligibleUatType,
   resolveEffectiveUatType,
   shouldDispatchUatForContent,
@@ -13,6 +12,12 @@ 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", () => {
@@ -63,11 +68,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", "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", () => {
@@ -89,6 +97,16 @@ describe("uat-policy", () => {
       }),
       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-closeout.test.ts

@@ -0,0 +1,209 @@
+// gsd-pi — ADR-032 Unit Closeout module tests (Interactive Closeout adapter path).
+//
+// All git/preference/notification effects go through the injected deps seam —
+// no real repos, no notification store state.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  closeUnit,
+  isUnitCloseoutTool,
+  runInteractiveUnitCloseout,
+  type UnitCloseoutDeps,
+} from "../unit-closeout.ts";
+
+interface DepsLog {
+  commits: Array<{ unitType: string; unitId: string }>;
+  notices: Array<{ message: string; severity: string }>;
+}
+
+function makeDeps(overrides: {
+  isolation?: "none" | "worktree" | "branch";
+  branch?: string | null;
+  commitResult?: string | null | (() => string | null);
+} = {}): { deps: UnitCloseoutDeps; log: DepsLog } {
+  const log: DepsLog = { commits: [], notices: [] };
+  const deps: UnitCloseoutDeps = {
+    isolationMode: () => overrides.isolation ?? "none",
+    currentBranch: () => (overrides.branch === undefined ? "main" : overrides.branch),
+    commit: (_basePath, unitType, unitId) => {
+      log.commits.push({ unitType, unitId });
+      const result = overrides.commitResult;
+      if (typeof result === "function") return result();
+      return result === undefined ? "chore(gsd): closeout" : result;
+    },
+    notify: (message, severity) => {
+      log.notices.push({ message, severity });
+    },
+  };
+  return { deps, log };
+}
+
+const BASE = "/tmp/closeout-test-project";
+
+test("task boundary commits and stays quiet", () => {
+  const { deps, log } = makeDeps({ isolation: "worktree" });
+  const result = closeUnit(
+    { basePath: BASE, unitType: "execute-task", unitId: "M001/S01/T01", boundary: "task", outcome: "complete" },
+    deps,
+  );
+  assert.equal(result.gitVerdict, "committed");
+  assert.equal(result.notice, undefined);
+  assert.deepEqual(log.commits, [{ unitType: "execute-task", unitId: "M001/S01/T01" }]);
+  assert.equal(log.notices.length, 0);
+});
+
+test("milestone boundary under isolation none commits without a notice", () => {
+  const { deps, log } = makeDeps({ isolation: "none" });
+  const result = closeUnit(
+    { basePath: BASE, unitType: "complete-milestone", unitId: "M001", boundary: "milestone", outcome: "complete" },
+    deps,
+  );
+  assert.equal(result.gitVerdict, "committed");
+  assert.equal(log.notices.length, 0);
+});
+
+test("milestone boundary off-worktree under isolation worktree fails closed loudly", () => {
+  const { deps, log } = makeDeps({ isolation: "worktree", branch: "main" });
+  const result = closeUnit(
+    { basePath: BASE, unitType: "complete-milestone", unitId: "M001", boundary: "milestone", outcome: "complete" },
+    deps,
+  );
+  assert.equal(result.gitVerdict, "isolation-bypassed");
+  assert.equal(log.notices.length, 1);
+  assert.equal(log.notices[0].severity, "warning");
+  assert.match(log.notices[0].message, /isolation preference was not honoured/);
+  assert.match(log.notices[0].message, /git\.isolation is "worktree"/);
+  assert.match(log.notices[0].message, /committed directly on "main"/);
+});
+
+test("milestone boundary on a milestone branch defers the merge to worktree tooling", () => {
+  const { deps, log } = makeDeps({ isolation: "worktree", branch: "milestone/M001" });
+  const result = closeUnit(
+    { basePath: BASE, unitType: "complete-milestone", unitId: "M001", boundary: "milestone", outcome: "complete" },
+    deps,
+  );
+  assert.equal(result.gitVerdict, "milestone-branch");
+  assert.equal(log.notices.length, 1);
+  assert.equal(log.notices[0].severity, "info");
+  assert.match(log.notices[0].message, /worktree merge/);
+});
+
+test("clean tree records nothing-to-commit, and the bypass notice says so", () => {
+  const { deps, log } = makeDeps({ isolation: "branch", branch: "main", commitResult: null });
+  const result = closeUnit(
+    { basePath: BASE, unitType: "complete-milestone", unitId: "M001", boundary: "milestone", outcome: "complete" },
+    deps,
+  );
+  assert.equal(result.gitVerdict, "isolation-bypassed");
+  assert.equal(result.commitMessage, null);
+  assert.match(log.notices[0].message, /nothing left to commit/);
+});
+
+test("commit failure is surfaced, never thrown", () => {
+  const { deps, log } = makeDeps({
+    commitResult: () => {
+      throw new Error("index.lock exists");
+    },
+  });
+  const result = closeUnit(
+    { basePath: BASE, unitType: "complete-milestone", unitId: "M001", boundary: "milestone", outcome: "complete" },
+    deps,
+  );
+  assert.equal(result.gitVerdict, "commit-failed");
+  assert.equal(log.notices[0].severity, "error");
+  assert.match(log.notices[0].message, /index\.lock/);
+});
+
+test("re-entrancy is safe: a re-fire over an already-clean tree is nothing-to-commit", () => {
+  // No result cache — re-entrancy is absorbed by git itself. The second fire
+  // sees a clean tree (commit returns null) and records nothing-to-commit.
+  let firstFire = true;
+  const { deps, log } = makeDeps({
+    isolation: "worktree",
+    branch: "main",
+    commitResult: () => {
+      const committed = firstFire;
+      firstFire = false;
+      return committed ? "chore(gsd): closeout" : null;
+    },
+  });
+  const request = {
+    basePath: BASE,
+    unitType: "complete-milestone",
+    unitId: "M001",
+    boundary: "milestone" as const,
+    outcome: "complete" as const,
+  };
+  const first = closeUnit(request, deps);
+  const second = closeUnit(request, deps);
+  assert.equal(first.gitVerdict, "isolation-bypassed");
+  assert.equal(first.commitMessage, "chore(gsd): closeout");
+  assert.equal(second.gitVerdict, "isolation-bypassed");
+  assert.equal(second.commitMessage, null);
+  assert.match(second.notice ?? "", /nothing left to commit/);
+  assert.equal(log.commits.length, 2);
+});
+
+// ─── Interactive adapter mapping ──────────────────────────────────────────
+
+test("isUnitCloseoutTool recognizes exactly the closeout tools", () => {
+  assert.equal(isUnitCloseoutTool("gsd_complete_milestone"), true);
+  assert.equal(isUnitCloseoutTool("gsd_save_gate_result"), false);
+  assert.equal(isUnitCloseoutTool("read"), false);
+});
+
+test("interactive adapter is scoped to milestone boundaries — task/slice tools do not commit", () => {
+  const { deps, log } = makeDeps();
+  assert.equal(isUnitCloseoutTool("gsd_task_complete"), false);
+  assert.equal(isUnitCloseoutTool("gsd_slice_complete"), false);
+  assert.equal(
+    runInteractiveUnitCloseout(
+      { basePath: BASE, canonicalToolName: "gsd_task_complete", input: { milestoneId: "M001", sliceId: "S02", taskId: "T03" } },
+      deps,
+    ),
+    null,
+  );
+  assert.equal(
+    runInteractiveUnitCloseout(
+      { basePath: BASE, canonicalToolName: "gsd_slice_complete", input: { milestoneId: "M001", sliceId: "S02" } },
+      deps,
+    ),
+    null,
+  );
+  assert.equal(log.commits.length, 0);
+});
+
+test("interactive adapter maps milestone tool input to canonical unit type", () => {
+  const { deps, log } = makeDeps();
+  const result = runInteractiveUnitCloseout(
+    { basePath: BASE, canonicalToolName: "gsd_complete_milestone", input: { milestoneId: "M001" } },
+    deps,
+  );
+  assert.equal(result?.gitVerdict, "committed");
+  assert.deepEqual(log.commits, [{ unitType: "complete-milestone", unitId: "M001" }]);
+});
+
+test("interactive adapter accepts snake_case ids and milestone-only input", () => {
+  const { deps, log } = makeDeps();
+  const result = runInteractiveUnitCloseout(
+    { basePath: BASE, canonicalToolName: "gsd_complete_milestone", input: { milestone_id: "M007" } },
+    deps,
+  );
+  assert.equal(result?.gitVerdict, "committed");
+  assert.deepEqual(log.commits, [{ unitType: "complete-milestone", unitId: "M007" }]);
+});
+
+test("interactive adapter declines unidentifiable input instead of guessing", () => {
+  const { deps, log } = makeDeps();
+  assert.equal(
+    runInteractiveUnitCloseout({ basePath: BASE, canonicalToolName: "gsd_complete_milestone", input: {} }, deps),
+    null,
+  );
+  assert.equal(
+    runInteractiveUnitCloseout({ basePath: BASE, canonicalToolName: "not_a_closeout_tool", input: { milestoneId: "M001" } }, deps),
+    null,
+  );
+  assert.equal(log.commits.length, 0);
+});

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

@@ -8,6 +8,7 @@ import { join } from "node:path";
 import { tmpdir } from "node:os";
 
 import {
+  composeContractedUnitContext,
   composeContextModeInstructions,
   composeInlinedContext,
   composeUnitContext,
@@ -15,6 +16,7 @@ import {
   type ArtifactResolver,
   type ExcerptResolver,
 } from "../unit-context-composer.ts";
+import { compileUnitContextContract } from "../tool-contract.ts";
 import type {
   ArtifactKey,
   BaseResolverContext,
@@ -22,6 +24,7 @@ import type {
   UnitContextManifest,
 } from "../unit-context-manifest.ts";
 import { KNOWN_UNIT_TYPES, UNIT_MANIFESTS } from "../unit-context-manifest.ts";
+import { getUnitToolSurfaceContract } from "../unit-tool-contracts.ts";
 import {
   buildExecuteTaskPrompt,
   buildGateEvaluatePrompt,
@@ -163,12 +166,32 @@ test("Context Mode composer: every known eligible unit renders its configured la
     }
     assert.ok(out.startsWith("## Context Mode"), `${unitType} should render standalone Context Mode heading`);
     assert.match(out, new RegExp(`Lane: \\*\\*${laneLabelByMode[manifest.contextMode]} lane\\*\\*\\.`, "i"));
-    assert.match(out, /`gsd_exec`/, `${unitType} should mention gsd_exec`);
-    assert.match(out, /`gsd_exec_search`/, `${unitType} should mention gsd_exec_search`);
+    const forbidden = getUnitToolSurfaceContract(unitType)?.forbiddenGsdTools ?? {};
+    if ("gsd_exec" in forbidden) {
+      // Units that forbid gsd_exec (run-uat) have it stripped from their
+      // Claude Code dispatch surface; guidance steering to it produces
+      // "No such tool available" loops in the dispatched agent.
+      assert.doesNotMatch(out, /`gsd_exec`/, `${unitType} forbids gsd_exec; guidance must not steer to it`);
+      assert.doesNotMatch(out, /`gsd_exec_search`/, `${unitType} guidance must not steer to gsd_exec_search`);
+      assert.match(out, /`gsd_uat_exec`/, `${unitType} guidance should steer to gsd_uat_exec instead`);
+    } else {
+      assert.match(out, /`gsd_exec`/, `${unitType} should mention gsd_exec`);
+      assert.match(out, /`gsd_exec_search`/, `${unitType} should mention gsd_exec_search`);
+    }
     assert.match(out, /`gsd_resume`/, `${unitType} should mention gsd_resume`);
   }
 });
 
+test("Context Mode composer: run-uat guidance steers to gsd_uat_exec in both render modes", () => {
+  const nested = composeContextModeInstructions("run-uat", { enabled: true, renderMode: "nested" });
+  assert.match(nested, /^Context Mode \(verification lane\): /);
+  assert.match(nested, /`gsd_uat_exec`/);
+  assert.doesNotMatch(nested, /`gsd_exec`/);
+  const standalone = composeContextModeInstructions("run-uat", { enabled: true, renderMode: "standalone" });
+  assert.match(standalone, /`gsd_uat_exec`/);
+  assert.doesNotMatch(standalone, /`gsd_exec`/);
+});
+
 test("Context Mode composer: workflow-preferences and research-decision render no Context Mode block", () => {
   assert.strictEqual(
     composeContextModeInstructions("workflow-preferences", { enabled: true, renderMode: "standalone" }),
@@ -268,6 +291,21 @@ test("#4782 phase 2: buildReassessRoadmapPrompt emits composer-shaped context wi
   assert.ok(!prompt.includes("Slice Context (from discussion)"));
 });
 
+test("execute-task prompt surfaces contract-declared on-demand slice research", async (t) => {
+  const base = makeFixtureBase();
+  t.after(() => cleanup(base));
+  invalidateAllCaches();
+
+  seed(base, "M001");
+  writeArtifacts(base);
+
+  const prompt = await buildExecuteTaskPrompt("M001", "S01", "First", "T01", "Task", base);
+
+  assert.match(prompt, /## On-demand Context/);
+  assert.match(prompt, /\.gsd\/milestones\/M001\/slices\/S01\/S01-RESEARCH\.md/);
+  assert.match(prompt, /Read it only if the inlined task plan, slice plan excerpt, and carry-forward context do not explain/);
+});
+
 test("Context Mode resume injection: eligible prompts include one bounded snapshot block above inlined context", async (t) => {
   const base = makeFixtureBase();
   t.after(() => cleanup(base));
@@ -370,6 +408,36 @@ test("#4924 v2 composer: returns empty sections for unknown unit type", async ()
   assert.deepEqual(out, { prepend: "", inline: "" });
 });
 
+test("Unit Context Contract composer exposes keyed blocks and on-demand artifacts", async () => {
+  const result = compileUnitContextContract("execute-task");
+  assert.equal(result.ok, true);
+  if (!result.ok) return;
+
+  const calls: ArtifactKey[] = [];
+  const out = await composeContractedUnitContext(result.contract, {
+    base: { ...fakeBase, unitType: "stale-unit", taskId: "T01" },
+    resolveArtifact: async (key) => {
+      calls.push(key);
+      return `BODY:${key}`;
+    },
+  });
+
+  assert.deepEqual(calls, [
+    "task-plan",
+    "slice-plan",
+    "prior-task-summaries",
+    "templates",
+  ]);
+  assert.deepEqual(out.blocks.map((block) => [block.key, block.mode]), [
+    ["task-plan", "inline"],
+    ["slice-plan", "inline"],
+    ["prior-task-summaries", "inline"],
+    ["templates", "inline"],
+  ]);
+  assert.deepEqual(out.onDemand, ["slice-research"]);
+  assert.match(out.inline, /BODY:task-plan\n\n---\n\nBODY:slice-plan/);
+});
+
 test("#4924 v2 composer: omitting resolveArtifact skips inline keys without erroring", async () => {
   const out = await composeUnitContext("reassess-roadmap", { base: fakeBase });
   assert.strictEqual(out.inline, "");