@opengsd/gsd-pi 1.2.0-dev.fb12b103 → 1.2.0-dev.fbdca60b

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

@@ -0,0 +1,119 @@
+// Project/App: gsd-pi
+// File Purpose: Tests for shared workflow MCP probe cache.
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  cachedWorkflowMcpCoversRequired,
+  clearWorkflowMcpProbeCache,
+  getCachedWorkflowMcpProbe,
+  probeAndCacheWorkflowMcp,
+  recordWorkflowMcpProbe,
+  beginWorkflowMcpSdkSession,
+  endWorkflowMcpSdkSession,
+  warmWorkflowMcpProbeInBackground,
+} from "../workflow-mcp-readiness-cache.ts";
+
+describe("workflow-mcp-readiness-cache", () => {
+  test("returns cached probe without reconnecting", async () => {
+    clearWorkflowMcpProbeCache();
+    const projectRoot = "/tmp/gsd-cache-project";
+    recordWorkflowMcpProbe(projectRoot, "gsd-workflow", ["gsd_status", "gsd_plan_slice"]);
+
+    const result = await probeAndCacheWorkflowMcp(projectRoot, { timeoutMs: 1000 });
+    assert.equal(result.ok, true);
+    assert.deepEqual(result.tools, ["gsd_status", "gsd_plan_slice"]);
+    assert.equal(result.serverName, "gsd-workflow");
+  });
+
+  test("cachedWorkflowMcpCoversRequired matches required workflow tools", () => {
+    clearWorkflowMcpProbeCache();
+    const projectRoot = "/tmp/gsd-cache-required";
+    recordWorkflowMcpProbe(projectRoot, "gsd-workflow", ["gsd_plan_slice", "gsd_milestone_status"]);
+
+    assert.equal(
+      cachedWorkflowMcpCoversRequired(projectRoot, "gsd-workflow", ["gsd_plan_slice"]),
+      true,
+    );
+    assert.equal(
+      cachedWorkflowMcpCoversRequired(projectRoot, "gsd-workflow", ["gsd_uat_exec"]),
+      false,
+    );
+    assert.equal(getCachedWorkflowMcpProbe(projectRoot)?.serverName, "gsd-workflow");
+  });
+
+  test("warmWorkflowMcpProbeInBackground is suppressed during active SDK sessions", async () => {
+    clearWorkflowMcpProbeCache();
+    beginWorkflowMcpSdkSession();
+    try {
+      const projectRoot = "/tmp/gsd-sdk-session-guard";
+      warmWorkflowMcpProbeInBackground(projectRoot);
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      assert.equal(getCachedWorkflowMcpProbe(projectRoot), null);
+    } finally {
+      endWorkflowMcpSdkSession();
+    }
+  });
+
+  test("warmWorkflowMcpProbeInBackground uses project root without double cache-keying", async () => {
+    clearWorkflowMcpProbeCache();
+    const projectRoot = "/tmp/gsd-warm-cache-key";
+    recordWorkflowMcpProbe(projectRoot, "gsd-workflow", ["gsd_status", "gsd_plan_slice"]);
+    warmWorkflowMcpProbeInBackground(projectRoot);
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.equal(getCachedWorkflowMcpProbe(projectRoot)?.serverName, "gsd-workflow");
+  });
+
+  test("probeAndCacheWorkflowMcp reads project .mcp.json when no env launch config exists", async () => {
+    clearWorkflowMcpProbeCache();
+    const previousGsdHome = process.env.GSD_HOME;
+    const projectRoot = mkdtempSync(join(tmpdir(), "gsd-mcp-cache-project-"));
+    const gsdHomeDir = mkdtempSync(join(tmpdir(), "gsd-mcp-cache-home-"));
+    try {
+      process.env.GSD_HOME = gsdHomeDir;
+      mkdirSync(join(projectRoot, ".gsd"), { recursive: true });
+
+      const require = createRequire(import.meta.url);
+      const mcpModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/mcp.js")).href;
+      const stdioModuleUrl = pathToFileURL(require.resolve("@modelcontextprotocol/sdk/server/stdio.js")).href;
+      const serverPath = join(projectRoot, "fake-workflow-mcp-server.mjs");
+      writeFileSync(
+        serverPath,
+        [
+          `const { McpServer } = await import(${JSON.stringify(mcpModuleUrl)});`,
+          `const { StdioServerTransport } = await import(${JSON.stringify(stdioModuleUrl)});`,
+          'const server = new McpServer({ name: "fake", version: "1.0.0" }, { capabilities: { tools: {} } });',
+          'server.tool("ask_user_questions", "Ask questions", {}, async () => ({ content: [{ type: "text", text: "ok" }] }));',
+          'await server.connect(new StdioServerTransport());',
+        ].join("\n"),
+        "utf-8",
+      );
+      writeFileSync(
+        join(projectRoot, ".mcp.json"),
+        JSON.stringify({ mcpServers: { "gsd-workflow": { command: process.execPath, args: [serverPath] } } }),
+        "utf-8",
+      );
+
+      const result = await probeAndCacheWorkflowMcp(projectRoot, { timeoutMs: 5_000 });
+
+      assert.equal(result.ok, true);
+      assert.equal(result.serverName, "gsd-workflow");
+      assert.deepEqual(result.tools, ["ask_user_questions"]);
+      assert.deepEqual(getCachedWorkflowMcpProbe(projectRoot)?.tools, ["ask_user_questions"]);
+    } finally {
+      if (previousGsdHome === undefined) {
+        delete process.env.GSD_HOME;
+      } else {
+        process.env.GSD_HOME = previousGsdHome;
+      }
+      rmSync(projectRoot, { recursive: true, force: true });
+      rmSync(gsdHomeDir, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -22,6 +22,7 @@ import {
   usesWorkflowMcpTransport,
 } from "../workflow-mcp.ts";
 import { DB_WORKFLOW_TOOL_NAMES } from "../workflow-tool-surface.ts";
+import { UNIT_TOOL_CONTRACTS } from "../unit-tool-contracts.ts";
 
 const MCP_STDIO_TIMEOUT_MS = 90_000;
 
@@ -43,11 +44,25 @@ test("resolveWorkflowMcpProjectRoot maps milestone worktree cwd to project root"
 });
 
 test("guided execute-task requires canonical task completion tool", () => {
-  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("execute-task"), ["gsd_task_complete"]);
+  const expected = [
+    "gsd_task_complete",
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_capture_thought",
+  ];
+  assert.deepEqual(getRequiredWorkflowToolsForGuidedUnit("execute-task"), expected);
 });
 
 test("auto execute-task requires canonical task completion tool", () => {
-  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), ["gsd_task_complete"]);
+  const expected = [
+    "gsd_task_complete",
+    "gsd_exec",
+    "gsd_exec_search",
+    "gsd_resume",
+    "gsd_capture_thought",
+  ];
+  assert.deepEqual(getRequiredWorkflowToolsForAutoUnit("execute-task"), expected);
 });
 
 test("plan-slice requires planning and roadmap reassessment tools", () => {
@@ -69,6 +84,8 @@ test("refine-slice requires canonical slice planning tool", () => {
 
 test("complete-slice requires closeout and execution handoff tools", () => {
   const expected = [
+    "gsd_exec",
+    "gsd_capture_thought",
     "gsd_slice_complete",
     "gsd_task_reopen",
     "gsd_replan_slice",
@@ -526,6 +543,52 @@ test("workflow MCP launch config reaches mutation tools over stdio", async () =>
   }
 });
 
+test("workflow MCP stdio surface exposes every unit's required workflow tool", async () => {
+  const projectRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-all-unit-tools-"));
+  const isolatedGsdHome = mkdtempSync(join(tmpdir(), "gsd-workflow-all-unit-home-"));
+  mkdirSync(join(projectRoot, ".gsd"), { recursive: true });
+
+  const launch = detectWorkflowMcpLaunchConfig(projectRoot, {});
+  assert.ok(launch, "expected a workflow MCP launch config");
+
+  const client = new Client({ name: "workflow-mcp-contract-test", version: "1.0.0" });
+  const transport = new StdioClientTransport({
+    command: launch.command,
+    args: launch.args,
+    env: {
+      ...process.env,
+      ...launch.env,
+      GSD_HOME: isolatedGsdHome,
+      DISCORD_BOT_TOKEN: "",
+      SLACK_BOT_TOKEN: "",
+      TELEGRAM_BOT_TOKEN: "",
+    } as Record<string, string>,
+    cwd: launch.cwd,
+    stderr: "pipe",
+  });
+
+  try {
+    await client.connect(transport, { timeout: MCP_STDIO_TIMEOUT_MS });
+    const listed = await client.listTools(undefined, { timeout: MCP_STDIO_TIMEOUT_MS });
+    const exposedTools = new Set((listed.tools ?? []).map((tool) => tool.name));
+
+    for (const [unitType, contract] of Object.entries(UNIT_TOOL_CONTRACTS)) {
+      for (const toolName of contract.requiredWorkflowTools) {
+        if (!toolName.startsWith("gsd_") && toolName !== "ask_user_questions") continue;
+        assert.ok(
+          exposedTools.has(toolName),
+          `${unitType} requires ${toolName}, but workflow MCP exposed ${JSON.stringify([...exposedTools].sort())}`,
+        );
+      }
+    }
+  } finally {
+    await client.close().catch(() => undefined);
+    await transport.close().catch(() => undefined);
+    rmSync(projectRoot, { recursive: true, force: true });
+    rmSync(isolatedGsdHome, { recursive: true, force: true });
+  }
+});
+
 test("workflow MCP ask_user_questions uses stdio elicitation round-trip", async () => {
   const projectRoot = mkdtempSync(join(tmpdir(), "gsd-workflow-elicit-"));
   mkdirSync(join(projectRoot, ".gsd"), { recursive: true });

package/src/resources/extensions/gsd/tests/workflow-phase-contract-matrix.test.ts

@@ -0,0 +1,332 @@
+// Project/App: gsd-pi
+// File Purpose: Cross-walk matrix — every unit phase, workflow tool contract, transport
+// registration, availability gate, and forbidden-tool boundary.
+
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { WORKFLOW_TOOL_CONTRACTS } from "@opengsd/contracts";
+import { registerDbTools } from "../bootstrap/db-tools.ts";
+import { registerExecTools } from "../bootstrap/exec-tools.ts";
+import { registerJournalTools } from "../bootstrap/journal-tools.ts";
+import { registerMemoryTools } from "../bootstrap/memory-tools.ts";
+import { registerQueryTools } from "../bootstrap/query-tools.ts";
+import {
+  buildMinimalAutoGsdToolSet,
+  MINIMAL_AUTO_BASE_TOOL_NAMES,
+  MINIMAL_GSD_TOOL_NAMES,
+} from "../bootstrap/register-hooks.ts";
+import { shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.ts";
+import { canonicalWorkflowToolName } from "../engine-hook-contract.ts";
+import { resolveToolPresentationPlan } from "../tool-presentation-plan.ts";
+import { getToolSurfaceReadinessError } from "../tool-surface-readiness.ts";
+import {
+  compileUnitContextContract,
+  compileUnitToolContract,
+  getUnitWorkflowDispatchReadinessError,
+} from "../tool-contract.ts";
+import {
+  getRequiredWorkflowToolsForUnit,
+  getUnitToolSurfaceContract,
+  UNIT_TOOL_CONTRACTS,
+} from "../unit-tool-contracts.ts";
+import { UNIT_MANIFESTS } from "../unit-context-manifest.ts";
+import { UNIT_REGISTRY, type UnitTypeOrVariant } from "../unit-registry.ts";
+import {
+  isWorkflowToolSurfaceName,
+  WORKFLOW_MCP_ADAPTER_TOOL_NAMES,
+  WORKFLOW_TOOL_SURFACE_NAMES,
+} from "../workflow-tool-surface.ts";
+
+const WORKFLOW_SERVER = "gsd-workflow";
+
+const MCP_TRANSPORT = {
+  provider: "claude-code-cli",
+  projectRoot: "/tmp/gsd-matrix-project",
+  env: { GSD_WORKFLOW_MCP_COMMAND: "node" } as NodeJS.ProcessEnv,
+  surface: "contract-matrix",
+  authMode: "externalCli" as const,
+  baseUrl: "local://claude-code",
+};
+
+/** Native Pi registers some contract names under legacy aliases. */
+const NATIVE_TOOL_EQUIVALENTS: Readonly<Record<string, readonly string[]>> = {
+  gsd_capture_thought: ["capture_thought", "gsd_capture_thought"],
+  gsd_memory_query: ["memory_query", "gsd_memory_query"],
+  gsd_memory_graph: ["gsd_graph", "gsd_memory_graph"],
+};
+
+const REGISTERED_SURFACE_TOOL_NAMES = [
+  ...new Set([
+    ...MINIMAL_AUTO_BASE_TOOL_NAMES,
+    ...MINIMAL_GSD_TOOL_NAMES,
+    ...Object.values(UNIT_TOOL_CONTRACTS).flatMap((contract) => contract.allowedGsdTools),
+    ...WORKFLOW_TOOL_SURFACE_NAMES,
+  ]),
+];
+
+function makeMockPi() {
+  const tools: Array<{ name: string }> = [];
+  return {
+    registerTool(tool: { name: string }) {
+      tools.push(tool);
+    },
+    tools,
+  } as const;
+}
+
+function collectNativeRegisteredToolNames(): Set<string> {
+  const pi = makeMockPi();
+  registerDbTools(pi as never);
+  registerExecTools(pi as never);
+  registerQueryTools(pi as never);
+  registerJournalTools(pi as never);
+  registerMemoryTools(pi as never);
+  return new Set(pi.tools.map((tool) => tool.name));
+}
+
+function workflowToolsForUnit(unitType: string): string[] {
+  return getRequiredWorkflowToolsForUnit(unitType).filter(
+    (tool) => tool.startsWith("gsd_") || tool === "ask_user_questions",
+  );
+}
+
+function mockConnectedObservation(requiredTools: readonly string[]) {
+  return {
+    tools: requiredTools.map((tool) => `mcp__${WORKFLOW_SERVER}__${tool}`),
+    mcpServers: [{ name: WORKFLOW_SERVER, status: "connected" }],
+  };
+}
+
+function assertNativeToolRegistered(
+  registered: Set<string>,
+  contractName: string,
+  label: string,
+): void {
+  const candidates = [contractName, ...(NATIVE_TOOL_EQUIVALENTS[contractName] ?? [])];
+  assert.ok(
+    candidates.some((name) => registered.has(name)),
+    `${label}: native transport missing ${contractName} (candidates: ${candidates.join(", ")})`,
+  );
+}
+
+function unitHasManifest(unitType: string): boolean {
+  return unitType in UNIT_MANIFESTS;
+}
+
+function unitTypesWithContracts(): Array<[UnitTypeOrVariant, (typeof UNIT_REGISTRY)[UnitTypeOrVariant]]> {
+  return Object.entries(UNIT_REGISTRY).filter(
+    (entry): entry is [UnitTypeOrVariant, (typeof UNIT_REGISTRY)[UnitTypeOrVariant]] =>
+      entry[1].toolContract !== null,
+  );
+}
+
+// ─── Unit phase × contract integrity ───────────────────────────────────────
+
+test("every manifest-backed unit with a tool contract compiles Tool Contract and Context Contract", () => {
+  for (const [unitType] of unitTypesWithContracts()) {
+    if (!unitHasManifest(unitType)) continue;
+    const toolResult = compileUnitToolContract(unitType);
+    assert.equal(toolResult.ok, true, `${unitType} must compile Tool Contract`);
+
+    const contextResult = compileUnitContextContract(unitType);
+    assert.equal(contextResult.ok, true, `${unitType} must compile Context Contract`);
+  }
+});
+
+for (const [unitType, descriptor] of unitTypesWithContracts()) {
+  test(`${unitType}: required workflow tools are declared, on-surface, and allowed`, () => {
+    const contract = descriptor.toolContract!;
+    const allowed = new Set(contract.allowedGsdTools.map((tool) => String(tool)));
+
+    for (const required of contract.requiredWorkflowTools) {
+      const name = String(required);
+      if (name === "subagent") {
+        assert.ok(allowed.has("subagent"), `${unitType}: subagent required but not allowed`);
+        continue;
+      }
+      assert.ok(
+        allowed.has(name) || name === "ask_user_questions",
+        `${unitType}: required ${name} must be allowed or be ask_user_questions`,
+      );
+      if (name.startsWith("gsd_")) {
+        assert.ok(
+          isWorkflowToolSurfaceName(name),
+          `${unitType}: required ${name} must be on WORKFLOW_TOOL_SURFACE_NAMES`,
+        );
+      } else if (name === "ask_user_questions") {
+        assert.ok(
+          (WORKFLOW_MCP_ADAPTER_TOOL_NAMES as readonly string[]).includes(name),
+          `${unitType}: ask_user_questions must be on the MCP adapter surface`,
+        );
+      }
+    }
+  });
+}
+
+for (const [unitType, descriptor] of unitTypesWithContracts()) {
+  const requiredTools = workflowToolsForUnit(unitType);
+  if (requiredTools.length === 0) continue;
+
+  test(`${unitType}: static dispatch gate passes when workflow MCP is configured`, () => {
+    const error = getUnitWorkflowDispatchReadinessError({
+      ...MCP_TRANSPORT,
+      unitType,
+      activeTools: REGISTERED_SURFACE_TOOL_NAMES,
+    });
+    assert.equal(error, null, `${unitType} static gate: ${error ?? "ok"}`);
+  });
+
+  test(`${unitType}: runtime tool-surface readiness passes when MCP tools are connected`, () => {
+    const error = getToolSurfaceReadinessError({
+      unitType,
+      workflowServerName: WORKFLOW_SERVER,
+      observation: mockConnectedObservation(requiredTools),
+    });
+    assert.equal(error, null, `${unitType} runtime readiness: ${error ?? "ok"}`);
+  });
+
+  test(`${unitType}: runtime readiness fails when a required workflow tool is missing`, () => {
+    if (requiredTools.length === 0) return;
+    const missing = requiredTools[0];
+    const partial = requiredTools.filter((tool) => tool !== missing);
+    const error = getToolSurfaceReadinessError({
+      unitType,
+      workflowServerName: WORKFLOW_SERVER,
+      observation: mockConnectedObservation(partial),
+    });
+    assert.ok(error, `${unitType} should fail readiness when ${missing} is absent`);
+    assert.match(error!, new RegExp(missing.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+  });
+
+  test(`${unitType}: native auto scoping exposes every required workflow tool`, () => {
+    const scoped = buildMinimalAutoGsdToolSet(
+      REGISTERED_SURFACE_TOOL_NAMES,
+      unitType,
+      REGISTERED_SURFACE_TOOL_NAMES,
+    );
+    for (const required of contractRequiredNames(unitType)) {
+      const canonical = canonicalWorkflowToolName(required);
+      const nativeCandidates = NATIVE_TOOL_EQUIVALENTS[canonical] ?? [canonical];
+      assert.ok(
+        scoped.some((tool) => nativeCandidates.includes(tool) || tool === canonical),
+        `${unitType}: scoped tools missing ${required}; got ${scoped.join(", ")}`,
+      );
+    }
+  });
+
+  test(`${unitType}: MCP presentation plan exposes every required workflow tool`, () => {
+    const requested = [
+      ...new Set([
+        ...(descriptor.toolContract?.allowedGsdTools ?? []),
+        ...requiredTools,
+      ]),
+    ].filter((tool) => String(tool).startsWith("gsd_") || tool === "ask_user_questions");
+    const plan = resolveToolPresentationPlan({
+      phase: unitType,
+      surface: "claude-code-sdk",
+      workflowMcpServerName: WORKFLOW_SERVER,
+      requestedToolNames: requested.map(String),
+      availableToolNames: REGISTERED_SURFACE_TOOL_NAMES,
+    });
+    for (const required of requiredTools) {
+      const presented = `mcp__${WORKFLOW_SERVER}__${required}`;
+      assert.ok(
+        plan.presentedToolNames.includes(presented),
+        `${unitType}: presentation plan missing ${presented}; got ${plan.presentedToolNames.join(", ")}`,
+      );
+    }
+  });
+}
+
+function contractRequiredNames(unitType: string): string[] {
+  return getRequiredWorkflowToolsForUnit(unitType).filter((tool) => tool !== "ask_user_questions");
+}
+
+for (const [unitType, descriptor] of unitTypesWithContracts()) {
+  const contract = descriptor.toolContract;
+  if (!contract || !("forbiddenGsdTools" in contract) || !contract.forbiddenGsdTools) continue;
+  const forbidden = Object.entries(contract.forbiddenGsdTools);
+
+  for (const [toolName, reason] of forbidden) {
+    test(`${unitType}: forbids ${toolName} — ${reason}`, () => {
+      const block = shouldBlockAutoUnitToolCall(unitType, toolName);
+      assert.equal(block.block, true, `${unitType} must block ${toolName}`);
+      assert.ok(block.reason, `${unitType} block reason for ${toolName}`);
+    });
+  }
+}
+
+// ─── Workflow tool contract × transports ───────────────────────────────────
+
+test("every canonical workflow contract tool is on the compiled MCP surface list", () => {
+  for (const contract of WORKFLOW_TOOL_CONTRACTS) {
+    assert.ok(
+      isWorkflowToolSurfaceName(contract.canonicalName),
+      `${contract.canonicalName} missing from WORKFLOW_TOOL_SURFACE_NAMES`,
+    );
+    for (const alias of contract.aliases) {
+      assert.ok(
+        isWorkflowToolSurfaceName(alias),
+        `alias ${alias} for ${contract.canonicalName} missing from surface`,
+      );
+    }
+  }
+});
+
+test("every unit-required workflow tool resolves to a registered contract canonical name", () => {
+  const canonicalNames = new Set<string>(WORKFLOW_TOOL_CONTRACTS.map((tool) => tool.canonicalName));
+  const adapterNames = new Set(WORKFLOW_MCP_ADAPTER_TOOL_NAMES as readonly string[]);
+
+  for (const [unitType] of unitTypesWithContracts()) {
+    for (const required of getRequiredWorkflowToolsForUnit(unitType)) {
+      const name = String(required);
+      if (name === "ask_user_questions") {
+        assert.ok(adapterNames.has(name), `${unitType}: ${name} must be adapter-registered`);
+        continue;
+      }
+      if (name === "subagent") continue;
+      const canonical = canonicalWorkflowToolName(name);
+      assert.ok(
+        canonicalNames.has(canonical),
+        `${unitType}: required ${name} canonicalizes to unknown contract ${canonical}`,
+      );
+    }
+  }
+});
+
+test("native bootstrap registers every contract canonical tool (or documented equivalent)", () => {
+  const registered = collectNativeRegisteredToolNames();
+  for (const contract of WORKFLOW_TOOL_CONTRACTS) {
+    assertNativeToolRegistered(registered, contract.canonicalName, "native bootstrap");
+  }
+});
+
+test("every write-policy workflow contract declares schema and audit metadata", () => {
+  for (const contract of WORKFLOW_TOOL_CONTRACTS) {
+    assert.match(contract.schemaId, /^workflow\./, `${contract.canonicalName} schemaId`);
+    assert.match(contract.auditEvent, /^workflow\./, `${contract.canonicalName} auditEvent`);
+    assert.ok(contract.executorId.length > 0, `${contract.canonicalName} executorId`);
+    if (contract.writePolicy === "write") {
+      assert.notEqual(
+        contract.executorId,
+        "executeMilestoneStatus",
+        `${contract.canonicalName} write tool must not use read executor`,
+      );
+    }
+  }
+});
+
+test("registry tool contracts stay aligned with UNIT_TOOL_CONTRACTS view", () => {
+  for (const [unitType, descriptor] of Object.entries(UNIT_REGISTRY)) {
+    if (!descriptor.toolContract) {
+      assert.equal(getUnitToolSurfaceContract(unitType), undefined);
+      continue;
+    }
+    assert.deepEqual(
+      getUnitToolSurfaceContract(unitType),
+      descriptor.toolContract,
+      `${unitType} derived contract drift`,
+    );
+  }
+});

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

@@ -89,3 +89,23 @@ test("resolveConflict(pick=main) rewrites the worktree log durably", () => {
   const second = reconcileWorktreeLogs(main, worktree);
   assert.equal(second.conflicts.length, 0, "reconcile should stay clean after choosing main");
 });
+
+test("reconcileWorktreeLogs treats canonical worktree project-ledger appends as already durable", () => {
+  const root = mkdtempSync(join(tmpdir(), "workflow-reconcile-canonical-"));
+  const main = join(root, "main");
+  const worktree = join(main, ".gsd-worktrees", "M001");
+  mkdirSync(worktree, { recursive: true });
+  tmpDirs.push(root);
+
+  appendEvent(worktree, {
+    cmd: "complete-task",
+    params: { milestoneId: "M001", sliceId: "S01", taskId: "T01" },
+    ts: "2026-01-01T00:00:00.000Z",
+    actor: "agent",
+  });
+
+  const result = reconcileWorktreeLogs(main, worktree);
+
+  assert.equal(result.autoMerged, 0, "project-ledger append should not replay the root log");
+  assert.equal(result.conflicts.length, 0, "missing worktree shard is not a conflict");
+});

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

@@ -7,6 +7,9 @@
 
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 import {
   loadRegistry,
   resolveByName,
@@ -16,6 +19,11 @@ import {
   getTemplateInfo,
   loadWorkflowTemplate,
 } from '../workflow-templates.ts';
+import {
+  findInProgressWorkflows,
+  isWorkflowStateComplete,
+  type WorkflowState,
+} from '../commands-workflow-templates.ts';
 
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -196,3 +204,87 @@ console.log('\n── Load Workflow Template ──');
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
+
+console.log('\n── Workflow Resume State ──');
+
+{
+  const started: WorkflowState = {
+    template: 'bugfix',
+    templateName: 'Bug Fix',
+    description: 'fix resume drift',
+    branch: 'gsd/bugfix/fix-resume-drift',
+    phases: [
+      { name: 'triage', index: 0, status: 'completed' },
+      { name: 'fix', index: 1, status: 'active' },
+      { name: 'verify', index: 2, status: 'pending' },
+    ],
+    currentPhase: 1,
+    startedAt: '2026-06-15T00:00:00.000Z',
+    updatedAt: '2026-06-15T00:01:00.000Z',
+    artifactDir: 'workflows/bugfixes/260615-1-fix-resume-drift',
+  };
+
+  assert.equal(isWorkflowStateComplete(started), false, 'active phase should be resumable');
+  assert.equal(
+    isWorkflowStateComplete({
+      ...started,
+      phases: started.phases.map((phase) => ({ ...phase, status: 'completed' })),
+      currentPhase: 2,
+      updatedAt: '2026-06-15T00:02:00.000Z',
+    }),
+    true,
+    'all completed phases should be treated as complete even when completedAt is absent',
+  );
+  assert.equal(
+    isWorkflowStateComplete({ ...started, completedAt: '2026-06-15T00:03:00.000Z' }),
+    true,
+    'completedAt should mark the workflow complete',
+  );
+}
+
+test('findInProgressWorkflows ignores completed phase-only STATE files', (t) => {
+  const base = mkdtempSync(join(tmpdir(), 'gsd-workflow-resume-'));
+  t.after(() => rmSync(base, { recursive: true, force: true }));
+
+  const workflowsRoot = join(base, '.gsd', 'workflows', 'bugfixes');
+  mkdirSync(join(workflowsRoot, '260615-1-complete'), { recursive: true });
+  mkdirSync(join(workflowsRoot, '260615-2-active'), { recursive: true });
+
+  const common = {
+    template: 'bugfix',
+    templateName: 'Bug Fix',
+    description: 'fix resume drift',
+    branch: 'gsd/bugfix/fix-resume-drift',
+    startedAt: '2026-06-15T00:00:00.000Z',
+    artifactDir: 'workflows/bugfixes/260615-1-complete',
+  };
+
+  writeFileSync(join(workflowsRoot, '260615-1-complete', 'STATE.json'), JSON.stringify({
+    ...common,
+    phases: [
+      { name: 'triage', index: 0, status: 'completed' },
+      { name: 'fix', index: 1, status: 'completed' },
+      { name: 'verify', index: 2, status: 'completed' },
+    ],
+    currentPhase: 2,
+    updatedAt: '2026-06-15T00:02:00.000Z',
+  }), 'utf-8');
+
+  writeFileSync(join(workflowsRoot, '260615-2-active', 'STATE.json'), JSON.stringify({
+    ...common,
+    artifactDir: 'workflows/bugfixes/260615-2-active',
+    phases: [
+      { name: 'triage', index: 0, status: 'completed' },
+      { name: 'fix', index: 1, status: 'active' },
+      { name: 'verify', index: 2, status: 'pending' },
+    ],
+    currentPhase: 1,
+    updatedAt: '2026-06-15T00:03:00.000Z',
+  }), 'utf-8');
+
+  const inProgress = findInProgressWorkflows(base);
+  assert.equal(inProgress.length, 1);
+  assert.equal(inProgress[0]?.artifactDir, 'workflows/bugfixes/260615-2-active');
+});
+
+// ═══════════════════════════════════════════════════════════════════════════