gsd-pi 2.81.0-dev.72a81bdf3 → 2.82.0-dev.2841a1e44

package/src/resources/extensions/gsd/tests/plan-milestone-sketch-render.test.ts

@@ -0,0 +1,157 @@
+// ADR-011 #5750: ROADMAP.md renders sketch slices with a `[sketch]` badge.
+//
+// Locks in the visual distinction so an auditor scanning the rendered roadmap
+// can tell which slices are sketches awaiting refine-slice expansion vs which
+// already carry a full plan. Sits alongside `plan-milestone.test.ts` which
+// covers the full-plan render path.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, rmSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { openDatabase, closeDatabase } from "../gsd-db.ts";
+import { handlePlanMilestone, type PlanMilestoneParams } from "../tools/plan-milestone.ts";
+
+function makeTmpBase(): string {
+  const base = mkdtempSync(join(tmpdir(), "gsd-plan-sketch-render-"));
+  mkdirSync(join(base, ".gsd", "milestones", "M001"), { recursive: true });
+  openDatabase(join(base, ".gsd", "gsd.db"));
+  return base;
+}
+
+function cleanup(base: string): void {
+  try {
+    closeDatabase();
+  } catch {
+    /* noop */
+  }
+  try {
+    rmSync(base, { recursive: true, force: true });
+  } catch {
+    /* noop */
+  }
+}
+
+function planMilestoneWithSketches(): PlanMilestoneParams {
+  return {
+    milestoneId: "M001",
+    title: "Progressive Planning Demo",
+    vision: "Demonstrate sketch slices in ROADMAP rendering.",
+    successCriteria: ["S01 full, S02 sketch", "ROADMAP distinguishes them"],
+    keyRisks: [{ risk: "Visual collision", whyItMatters: "Auditors need to spot sketches." }],
+    proofStrategy: [{ riskOrUnknown: "Render correctness", retireIn: "S01", whatWillBeProven: "Roadmap shows the badge." }],
+    verificationContract: "Contract verification text",
+    verificationIntegration: "Integration verification text",
+    verificationOperational: "Operational verification text",
+    verificationUat: "UAT verification text",
+    definitionOfDone: ["Renderer emits badge", "Test asserts it"],
+    requirementCoverage: "Covers ADR-011 #5750.",
+    boundaryMapMarkdown: "| From | To | Produces | Consumes |\n|------|----|----------|----------|\n| S01 | S02 | scaffold | nothing |",
+    slices: [
+      {
+        sliceId: "S01",
+        title: "Fully planned scaffold",
+        risk: "medium" as const,
+        depends: [],
+        demo: "Scaffold is in place.",
+        goal: "Lay down the structural foundation.",
+        successCriteria: "Scaffold tests pass.",
+        proofLevel: "integration" as const,
+        integrationClosure: "Downstream slices depend on this scaffold.",
+        observabilityImpact: "No new telemetry.",
+        // No isSketch flag — defaults to full plan.
+      },
+      {
+        sliceId: "S02",
+        title: "Refinement candidate",
+        risk: "low" as const,
+        depends: ["S01"],
+        demo: "Sketched until S01 ships.",
+        goal: "Refine into a full plan after S01 lands.",
+        successCriteria: "",
+        proofLevel: "",
+        integrationClosure: "",
+        observabilityImpact: "",
+        isSketch: true,
+        sketchScope: "Pick up the scaffold from S01 and add the demo behavior. Stay inside the existing module boundaries.",
+      },
+    ],
+  };
+}
+
+test("ROADMAP renders sketch slices with [sketch] badge and full slices without", async () => {
+  const base = makeTmpBase();
+  try {
+    const params = planMilestoneWithSketches();
+    const result = await handlePlanMilestone(params, base);
+    if ("error" in result) {
+      assert.fail(`handlePlanMilestone failed: ${result.error}`);
+    }
+
+    const roadmapPath = join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md");
+    const roadmap = readFileSync(roadmapPath, "utf-8");
+
+    // S01 is a full slice — no sketch badge.
+    const s01Line = roadmap.split("\n").find((line) => line.includes("**S01:"));
+    assert.ok(s01Line, "S01 slice line must exist in roadmap");
+    assert.equal(
+      s01Line.includes("`[sketch]`"),
+      false,
+      "fully-planned S01 must NOT carry the sketch badge",
+    );
+    assert.match(s01Line, /`risk:medium`/);
+
+    // S02 is a sketch — badge required, positioned before risk.
+    const s02Line = roadmap.split("\n").find((line) => line.includes("**S02:"));
+    assert.ok(s02Line, "S02 slice line must exist in roadmap");
+    assert.ok(
+      s02Line.includes("`[sketch]`"),
+      `sketch slice S02 must carry the sketch badge, got: ${s02Line}`,
+    );
+    // Badge sits before risk so it stays visible if the line truncates.
+    const sketchIdx = s02Line.indexOf("`[sketch]`");
+    const riskIdx = s02Line.indexOf("`risk:");
+    assert.ok(
+      sketchIdx >= 0 && riskIdx >= 0 && sketchIdx < riskIdx,
+      "sketch badge must appear before the risk tag",
+    );
+  } finally {
+    cleanup(base);
+  }
+});
+
+test("ROADMAP omits sketch badge when no slices are sketches", async () => {
+  const base = makeTmpBase();
+  try {
+    const params = planMilestoneWithSketches();
+    // Strip the sketch designation from S02 so both slices are fully planned.
+    params.slices[1] = {
+      ...params.slices[1],
+      isSketch: false,
+      successCriteria: "Demo behavior works.",
+      proofLevel: "unit" as const,
+      integrationClosure: "S02 closes the demo behavior.",
+      observabilityImpact: "No new telemetry.",
+    };
+
+    const result = await handlePlanMilestone(params, base);
+    if ("error" in result) {
+      assert.fail(`handlePlanMilestone failed: ${result.error}`);
+    }
+
+    const roadmap = readFileSync(
+      join(base, ".gsd", "milestones", "M001", "M001-ROADMAP.md"),
+      "utf-8",
+    );
+
+    assert.equal(
+      roadmap.includes("`[sketch]`"),
+      false,
+      "roadmap must not carry the sketch badge when no slice is a sketch",
+    );
+  } finally {
+    cleanup(base);
+  }
+});

package/src/resources/extensions/gsd/tests/post-exec-retry-bypass.test.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Tests for post-execution retry bypass and verification gate failure handling.
 /**
  * post-exec-retry-bypass.test.ts — Tests for post-execution blocking failure retry bypass.
  *
@@ -9,7 +11,7 @@
 import { describe, test, mock, beforeEach, afterEach } from "node:test";
 import assert from "node:assert/strict";
 import { tmpdir } from "node:os";
-import { mkdirSync, writeFileSync, rmSync, existsSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 
 import { runPostUnitVerification, type VerificationContext } from "../auto-verification.ts";
@@ -71,6 +73,7 @@ function setupTestEnvironment(): void {
   mkdirSync(milestonesDir, { recursive: true });
 
   process.chdir(tempDir);
+  invalidateAllCaches();
   _clearGsdRootCache();
 
   dbPath = join(gsdDir, "gsd.db");
@@ -140,6 +143,34 @@ function createBasicTask(): void {
   });
 }
 
+function createTaskWithoutVerify(): void {
+  insertMilestone({ id: "M001" });
+  insertSlice({
+    id: "S01",
+    milestoneId: "M001",
+    title: "Test Slice",
+    risk: "low",
+  });
+
+  insertTask({
+    id: "T01",
+    sliceId: "S01",
+    milestoneId: "M001",
+    title: "Task without host verification",
+    status: "pending",
+    planning: {
+      description: "Task intentionally missing runnable verification",
+      estimate: "1h",
+      files: [],
+      verify: "",
+      inputs: [],
+      expectedOutput: [],
+      observabilityImpact: "",
+    },
+    sequence: 0,
+  });
+}
+
 function createPostExecFailureTask(): void {
   insertMilestone({ id: "M001" });
   insertSlice({
@@ -327,6 +358,53 @@ describe("Post-execution blocking failure retry bypass", () => {
     assert.equal(row?.outcome, "fail");
     assert.equal(row?.failure_class, "artifact");
   });
+
+  test("execute-task with no host-owned verification pauses fail-closed", async () => {
+    createTaskWithoutVerify();
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const pauseAutoMock = mock.fn(async () => {});
+    const s = makeMockSession(tempDir, { type: "execute-task", id: "M001/S01/T01" });
+
+    const result = await runPostUnitVerification({ s, ctx, pi }, pauseAutoMock);
+
+    assert.equal(result, "pause");
+    assert.equal(pauseAutoMock.mock.callCount(), 1);
+    assert.equal(s.pendingVerificationRetry, null);
+
+    const evidencePath = join(tempDir, ".gsd", "milestones", "M001", "slices", "S01", "tasks", "T01-VERIFY.json");
+    const evidence = JSON.parse(readFileSync(evidencePath, "utf-8"));
+    assert.equal(evidence.passed, false);
+    assert.equal(evidence.discoverySource, "none");
+    assert.ok(!("retryAttempt" in evidence), "no-host-checks evidence must not include retryAttempt");
+    assert.ok(!("maxRetries" in evidence), "no-host-checks evidence must not include maxRetries");
+  });
+
+  test("auto-discovered package.json verification failure retries instead of continuing", async () => {
+    createTaskWithoutVerify();
+    writeFileSync(
+      join(tempDir, "package.json"),
+      JSON.stringify({ scripts: { test: "exit 1" } }),
+      "utf-8",
+    );
+    writePreferences({
+      verification_auto_fix: true,
+      verification_max_retries: 2,
+    });
+
+    const ctx = makeMockCtx();
+    const pi = makeMockPi();
+    const pauseAutoMock = mock.fn(async () => {});
+    const s = makeMockSession(tempDir, { type: "execute-task", id: "M001/S01/T01" });
+
+    const result = await runPostUnitVerification({ s, ctx, pi }, pauseAutoMock);
+
+    assert.equal(result, "retry");
+    assert.equal(pauseAutoMock.mock.callCount(), 0);
+    assert.equal(s.pendingVerificationRetry?.unitId, "M001/S01/T01");
+    assert.match(s.pendingVerificationRetry?.failureContext ?? "", /npm run test/);
+  });
 });
 
 describe("Post-execution retry behavior", () => {

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

@@ -55,6 +55,14 @@ test("system prompt hard rules forbid fabricating user responses", () => {
   assert.match(prompt, /ask_user_questions.*only valid structured user input/i);
 });
 
+test("system prompt requires reading before edit or overwrite", () => {
+  const prompt = readPrompt("system");
+  assert.match(prompt, /Read before edit or overwrite/i);
+  assert.match(prompt, /Before any write that creates or replaces a file/i);
+  assert.match(prompt, /confirm whether the path exists; if it does, `read` it first/i);
+  assert.match(prompt, /For truly new files, confirm the path does not already exist/i);
+});
+
 test("discuss prompt allows implementation questions when they materially matter", () => {
   const prompt = readPrompt("discuss");
   assert.match(prompt, /Lead with experience, but ask implementation when it materially matters/i);

package/src/resources/extensions/gsd/tests/provider-switch-observer.test.ts

@@ -0,0 +1,252 @@
+// GSD-2 — ADR-005 Phase 3b: ProviderSwitchObserver Tests
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import { setProviderSwitchObserver, type ProviderSwitchReport } from "@gsd/pi-ai";
+
+import { autoSession } from "../auto-runtime-state.ts";
+import {
+  initNotificationStore,
+  readNotifications,
+  _resetNotificationStore,
+} from "../notification-store.ts";
+import {
+  _resetProviderSwitchStats,
+  getProviderSwitchStats,
+  installProviderSwitchObserver,
+  uninstallProviderSwitchObserver,
+} from "../provider-switch-observer.ts";
+
+function makeReport(overrides: Partial<ProviderSwitchReport> = {}): ProviderSwitchReport {
+  return {
+    fromApi: "anthropic-messages",
+    toApi: "openai-responses",
+    thinkingBlocksDropped: 0,
+    thinkingBlocksDowngraded: 0,
+    toolCallIdsRemapped: 0,
+    syntheticToolResultsInserted: 0,
+    thoughtSignaturesDropped: 0,
+    ...overrides,
+  };
+}
+
+function withTempBasePath(): { basePath: string; cleanup: () => void } {
+  const basePath = mkdtempSync(join(tmpdir(), "gsd-provider-switch-"));
+  return {
+    basePath,
+    cleanup: () => rmSync(basePath, { recursive: true, force: true }),
+  };
+}
+
+test.beforeEach(() => {
+  _resetProviderSwitchStats();
+  _resetNotificationStore();
+  autoSession.currentTraceId = null;
+  autoSession.basePath = "";
+});
+
+test.afterEach(() => {
+  uninstallProviderSwitchObserver();
+  _resetNotificationStore();
+  autoSession.currentTraceId = null;
+  autoSession.basePath = "";
+});
+
+test("installProviderSwitchObserver wires the pi-ai observer hook", () => {
+  installProviderSwitchObserver();
+  // Indirect: a second install is a no-op. We verify by checking the counter
+  // increments exactly once when we fire a single report directly into pi-ai's
+  // observer slot.
+  installProviderSwitchObserver();
+
+  // Drive the pi-ai observer directly. The install above pointed it at our
+  // handler; firing here exercises the same code path as a real transform.
+  // We can't reach the installed handler reference from here, so we re-install
+  // a sentinel and confirm setProviderSwitchObserver accepts undefined.
+  setProviderSwitchObserver(undefined);
+  assert.ok(true); // install/uninstall did not throw
+});
+
+test("non-empty report increments the in-memory counter", () => {
+  installProviderSwitchObserver();
+
+  // Reach into the installed handler via setProviderSwitchObserver re-binding.
+  // We snapshot the handler by re-installing, capturing nothing — instead we
+  // use the public API: drive a report through the observer hook directly by
+  // calling setProviderSwitchObserver with a wrapper that proxies into the
+  // installed handler. This is awkward without a separate seam, so we test
+  // the recordReport path end-to-end by firing through pi-ai's transform helper
+  // pattern in a sibling test below. Here we exercise install idempotency only.
+
+  // Fire by setting our own observer that forwards to the module API isn't
+  // possible without exporting handleReport. Instead, verify install state
+  // doesn't crash; the real fire path is covered by the integration test
+  // below that exercises transformMessagesWithReport.
+  assert.deepEqual(getProviderSwitchStats().totalSwitches, 0);
+});
+
+test("end-to-end: transformMessagesWithReport fires the observer and updates stats + notifications", async () => {
+  const { transformMessagesWithReport } = await import("@gsd/pi-ai");
+
+  const { basePath, cleanup } = withTempBasePath();
+  try {
+    initNotificationStore(basePath);
+    installProviderSwitchObserver();
+
+    // Construct a cross-API transform that will drop a redacted thinking block.
+    const targetModel = {
+      id: "gpt-5",
+      name: "GPT-5",
+      api: "openai-responses",
+      provider: "openai",
+      baseUrl: "",
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 128000,
+      maxTokens: 8192,
+    } as Parameters<typeof transformMessagesWithReport>[1];
+
+    const messages = [
+      {
+        role: "assistant" as const,
+        content: [
+          { type: "thinking" as const, thinking: "", redacted: true },
+          { type: "text" as const, text: "hi" },
+        ],
+        api: "anthropic-messages",
+        provider: "anthropic",
+        model: "claude-sonnet-4-6",
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason: "stop" as const,
+        timestamp: Date.now(),
+      },
+    ];
+
+    transformMessagesWithReport(messages as Parameters<typeof transformMessagesWithReport>[0], targetModel, undefined, "anthropic-messages");
+
+    const stats = getProviderSwitchStats();
+    assert.equal(stats.totalSwitches, 1, "non-empty report should bump the counter");
+    assert.ok(stats.totals.thinkingBlocksDropped >= 1, "thinking block drop should be tallied");
+    assert.ok(stats.lastReport, "last report should be retained");
+    assert.equal(stats.lastReport?.fromApi, "anthropic-messages");
+    assert.equal(stats.lastReport?.toApi, "openai-responses");
+
+    // Notification persistence — the observer is interactive (no traceId), so
+    // the byTrace key falls back to "interactive".
+    assert.ok("interactive" in stats.byTrace, "interactive trace bucket should exist");
+    assert.equal(stats.byTrace.interactive?.switches, 1);
+
+    const notifications = readNotifications(basePath);
+    const switchNotifs = notifications.filter((n) => n.message.includes("Provider switch"));
+    assert.ok(switchNotifs.length >= 1, "a provider-switch notification should be persisted");
+    assert.equal(switchNotifs[0]?.severity, "warning");
+  } finally {
+    cleanup();
+  }
+});
+
+test("end-to-end: audit event is emitted when an auto trace is active", async () => {
+  const { transformMessagesWithReport } = await import("@gsd/pi-ai");
+
+  const { basePath, cleanup } = withTempBasePath();
+  try {
+    initNotificationStore(basePath);
+    installProviderSwitchObserver();
+    autoSession.basePath = basePath;
+    autoSession.currentTraceId = "trace-provider-switch-1";
+
+    const targetModel = {
+      id: "gpt-5",
+      name: "GPT-5",
+      api: "openai-responses",
+      provider: "openai",
+      baseUrl: "",
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 128000,
+      maxTokens: 8192,
+    } as Parameters<typeof transformMessagesWithReport>[1];
+
+    const messages = [
+      {
+        role: "assistant" as const,
+        content: [
+          { type: "thinking" as const, thinking: "", redacted: true },
+          { type: "text" as const, text: "hi" },
+        ],
+        api: "anthropic-messages",
+        provider: "anthropic",
+        model: "claude-sonnet-4-6",
+        usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        stopReason: "stop" as const,
+        timestamp: Date.now(),
+      },
+    ];
+
+    transformMessagesWithReport(messages as Parameters<typeof transformMessagesWithReport>[0], targetModel, undefined, "anthropic-messages");
+
+    const auditLogPath = join(basePath, ".gsd", "audit", "events.jsonl");
+    assert.ok(existsSync(auditLogPath), "audit events file should be created");
+    const auditLines = readFileSync(auditLogPath, "utf-8")
+      .trim()
+      .split("\n")
+      .map((line) => JSON.parse(line) as { category: string; type: string; traceId: string; payload: Record<string, unknown> });
+    const switchEvent = auditLines.find((e) => e.category === "model-policy" && e.type === "provider-switch");
+    assert.ok(switchEvent, "a model-policy/provider-switch audit event should be present");
+    assert.equal(switchEvent?.traceId, "trace-provider-switch-1");
+    assert.equal(switchEvent?.payload.fromApi, "anthropic-messages");
+    assert.equal(switchEvent?.payload.toApi, "openai-responses");
+
+    const stats = getProviderSwitchStats();
+    assert.ok("trace-provider-switch-1" in stats.byTrace, "trace-keyed bucket should be populated");
+    assert.equal(stats.byTrace["trace-provider-switch-1"]?.switches, 1);
+  } finally {
+    cleanup();
+  }
+});
+
+test("empty report does not bump counter or emit a notification", async () => {
+  const { transformMessagesWithReport } = await import("@gsd/pi-ai");
+
+  const { basePath, cleanup } = withTempBasePath();
+  try {
+    initNotificationStore(basePath);
+    installProviderSwitchObserver();
+
+    // Same-API transform → no transformations → empty report.
+    const sameApiModel = {
+      id: "claude-sonnet-4-6",
+      name: "Claude Sonnet 4.6",
+      api: "anthropic-messages",
+      provider: "anthropic",
+      baseUrl: "",
+      reasoning: false,
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 200000,
+      maxTokens: 8192,
+    } as Parameters<typeof transformMessagesWithReport>[1];
+
+    transformMessagesWithReport(
+      [
+        {
+          role: "user" as const,
+          content: "plain text — no transforms triggered",
+        },
+      ] as Parameters<typeof transformMessagesWithReport>[0],
+      sameApiModel,
+      undefined,
+      "anthropic-messages",
+    );
+
+    assert.equal(getProviderSwitchStats().totalSwitches, 0);
+    assert.equal(readNotifications(basePath).length, 0);
+  } finally {
+    cleanup();
+  }
+});

package/src/resources/extensions/gsd/tests/session-start-footer.test.ts

@@ -1,9 +1,11 @@
+// Project/App: GSD-2
+// File Purpose: Verifies GSD session hook widget and footer lifecycle behavior.
+
 /**
- * session-start-footer.test.ts
- *
  * Verifies that register-hooks.ts suppresses the gsd-health widget (not the
- * built-in footer) when isAutoActive() is true, and that setFooter is never
- * called by the extension in either session_start or session_switch.
+ * built-in footer) when isAutoActive() is true, clears stale completion widgets
+ * on inactive session switches, and that setFooter is never called by the
+ * extension in either session_start or session_switch.
  *
  * Testing strategy:
  *   1. Source-code regression guards: structural checks on register-hooks.ts.
@@ -139,6 +141,16 @@ test("session_switch toggles gsd-health from runtime auto state without touching
   widgetCalls.length = 0;
   autoSession.active = false;
   await sessionSwitch!({ reason: "resume" }, ctx);
+  assert.deepEqual(
+    widgetCalls
+      .filter((call) => call.key === "gsd-progress" || call.key === "gsd-outcome")
+      .map((call) => [call.key, call.value]),
+    [
+      ["gsd-progress", undefined],
+      ["gsd-outcome", undefined],
+    ],
+    "session_switch should clear stale GSD completion widgets when auto is inactive",
+  );
   const healthWidgetValues = widgetCalls
     .filter((call) => call.key === "gsd-health")
     .map((call) => call.value);

package/src/resources/extensions/gsd/tests/state-corruption-2945.test.ts

@@ -271,6 +271,11 @@ describe("#2945 Bug 3: mergeAndExit must teardown worktree after successful merg
     // a real git fixture and verify the worktree directory is removed
     // from disk after the merge.
     const tmpBase = realpathSync(mkdtempSync(join(tmpdir(), "gsd-2945-bug3-")));
+    // ADR-016 phase 3 (#5693): Lifecycle.restoreToProjectRoot now chdirs to
+    // s.originalBasePath. Save cwd before the test so we can restore it
+    // before rmSync removes tmpBase — otherwise the next test in this file
+    // inherits a deleted cwd and process.cwd() throws ENOENT (uv_cwd).
+    const prevCwd = process.cwd();
     try {
       const git = (args: string[]): void => {
         execFileSync("git", args, { cwd: tmpBase, stdio: "pipe" });
@@ -325,6 +330,7 @@ describe("#2945 Bug 3: mergeAndExit must teardown worktree after successful merg
         `teardownAutoWorktree must be called after successful merge — worktree directory at ${wt} should be removed`,
       );
     } finally {
+      try { process.chdir(prevCwd); } catch { /* noop */ }
       try { rmSync(tmpBase, { recursive: true, force: true }); } catch { /* noop */ }
     }
   });

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

@@ -7,6 +7,7 @@ import {
   ARTIFACT_KEYS,
   KNOWN_UNIT_TYPES,
   UNIT_MANIFESTS,
+  resolveSubagentPermissionContract,
   resolveManifest,
   type ArtifactKey,
   type ContextModePolicy,
@@ -244,9 +245,11 @@ test('#4934: only execute-task and reactive-execute may use tools.mode "all" (fu
 test('planning-dispatch mode is reserved for slice-level decomposition and completion units', () => {
   const allowedDispatchUnits = new Set([
     "plan-slice",
+    "research-slice",
     "refine-slice",
     "complete-slice",
     "complete-milestone",
+    "gate-evaluate",
     // Deep planning mode: research-project orchestrates 4 parallel research
     // subagents (stack/features/architecture/pitfalls). Subagent dispatch is
     // the unit's core mechanism — without it, the unit cannot do its job.
@@ -265,6 +268,24 @@ test('planning-dispatch mode is reserved for slice-level decomposition and compl
   }
 });
 
+test('Unit Tool Contract exposes subagent dispatch permissions', () => {
+  assert.deepEqual(resolveSubagentPermissionContract("plan-slice"), {
+    allowed: true,
+    allowedSubagents: ["scout", "planner"],
+    toolsMode: "planning-dispatch",
+  });
+  assert.deepEqual(resolveSubagentPermissionContract("gate-evaluate"), {
+    allowed: true,
+    allowedSubagents: ["reviewer", "security", "tester"],
+    toolsMode: "planning-dispatch",
+  });
+  assert.deepEqual(resolveSubagentPermissionContract("discuss-milestone"), {
+    allowed: false,
+    allowedSubagents: [],
+    toolsMode: "planning",
+  });
+});
+
 test('planning-dispatch manifests declare non-empty allowedSubagents lists', () => {
   for (const [unitType, manifest] of Object.entries(UNIT_MANIFESTS)) {
     if (manifest.tools.mode !== "planning-dispatch") continue;