@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.8e6112e9

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

@@ -1,8 +1,19 @@
 import { execSync } from "node:child_process";
 import { existsSync, realpathSync } from "node:fs";
-import { dirname, resolve, sep } from "node:path";
+import { basename, dirname, resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { getRequiredWorkflowToolsForUnit } from "./unit-tool-contracts.js";
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import {
+  supportsStructuredQuestions,
+  usesWorkflowMcpTransport,
+} from "./question-transport.js";
+import {
+  WORKFLOW_TOOL_SURFACE_NAMES,
+  isWorkflowToolSurfaceName,
+} from "./workflow-tool-surface.js";
+
+export { supportsStructuredQuestions, usesWorkflowMcpTransport };
 
 type WorkflowExecutorsModule = typeof import("./tools/workflow-tool-executors.js");
 
@@ -42,73 +53,9 @@ export function resolveWorkflowMcpProjectRoot(sessionCwd: string): string {
   return resolved;
 }
 
-const MCP_WORKFLOW_TOOL_SURFACE = new Set([
-  "gsd_cancel",
-  "gsd_captures",
-  "ask_user_questions",
-  "gsd_capture_thought",
-  "gsd_doctor",
-  "gsd_execute",
-  "gsd_memory_query",
-  "gsd_memory_graph",
-  "gsd_decision_save",
-  "gsd_exec",
-  "gsd_exec_search",
-  "gsd_graph",
-  "gsd_history",
-  "gsd_knowledge",
-  "gsd_progress",
-  "gsd_query",
-  "gsd_resume",
-  "gsd_result",
-  "gsd_resolve_blocker",
-  "gsd_roadmap",
-  "gsd_status",
-  "gsd_complete_milestone",
-  "gsd_complete_task",
-  "gsd_complete_slice",
-  "gsd_generate_milestone_id",
-  "gsd_journal_query",
-  "gsd_milestone_complete",
-  "gsd_milestone_generate_id",
-  "gsd_milestone_reopen",
-  "gsd_checkpoint_db",
-  "gsd_milestone_plan",
-  "gsd_milestone_status",
-  "gsd_milestone_validate",
-  "gsd_plan_task",
-  "gsd_plan_milestone",
-  "gsd_plan_slice",
-  "gsd_replan_slice",
-  "gsd_reassess_roadmap",
-  "gsd_reopen_milestone",
-  "gsd_reopen_slice",
-  "gsd_reopen_task",
-  "gsd_requirement_save",
-  "gsd_requirement_update",
-  "gsd_roadmap_reassess",
-  "gsd_save_decision",
-  "gsd_save_gate_result",
-  "gsd_save_requirement",
-  "gsd_save_summary",
-  "gsd_skip_slice",
-  "gsd_slice_plan",
-  "gsd_slice_replan",
-  "gsd_slice_complete",
-  "gsd_slice_reopen",
-  "gsd_summary_save",
-  "gsd_task_plan",
-  "gsd_task_complete",
-  "gsd_task_reopen",
-  "gsd_update_requirement",
-  "gsd_uat_exec",
-  "gsd_uat_result_save",
-  "gsd_validate_milestone",
-]);
-
 /** Workflow MCP tools are validated by transport compatibility, not pi tool-compat profiles. */
 export function isWorkflowMcpSurfaceTool(toolName: string): boolean {
-  return MCP_WORKFLOW_TOOL_SURFACE.has(toolName);
+  return isWorkflowToolSurfaceName(toolName);
 }
 
 function parseLookupOutput(output: Buffer | string): string {
@@ -276,8 +223,12 @@ function getBundledWorkflowWriteGateModulePath(): string | null {
 
 function getResolveTsHookPath(): string | null {
   const repoRoot = findGsdPiRepoRoot(dirname(fileURLToPath(import.meta.url)));
+  const sourceRepoRoot = repoRoot && basename(repoRoot) === "dist-test" ? dirname(repoRoot) : repoRoot;
   return firstExistingPath([
-    ...(repoRoot
+    ...(sourceRepoRoot
+      ? [resolve(sourceRepoRoot, "src", "resources", "extensions", "gsd", "tests", "resolve-ts.mjs")]
+      : []),
+    ...(repoRoot && repoRoot !== sourceRepoRoot
       ? [resolve(repoRoot, "src", "resources", "extensions", "gsd", "tests", "resolve-ts.mjs")]
       : []),
     resolve(fileURLToPath(new URL("./tests/resolve-ts.mjs", import.meta.url))),
@@ -421,52 +372,13 @@ export function getRequiredWorkflowToolsForAutoUnit(unitType: string): string[]
   return getRequiredWorkflowToolsForUnit(unitType);
 }
 
-export function usesWorkflowMcpTransport(
-  authMode: WorkflowCapabilityOptions["authMode"],
-  baseUrl: string | undefined,
-): boolean {
-  return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
-}
-
-function hasAskUserQuestionsTool(activeTools: string[]): boolean {
-  return activeTools.some((toolName) => {
-    if (toolName === "ask_user_questions") return true;
-    if (!toolName.startsWith("mcp__")) return false;
-    const toolSeparator = toolName.indexOf("__", "mcp__".length);
-    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === "ask_user_questions";
-  });
-}
-
 function hasRequiredTool(requiredTool: string, activeTools: string[]): boolean {
   return activeTools.some((toolName) => {
     if (toolName === requiredTool) return true;
-    if (!toolName.startsWith("mcp__")) return false;
-    const toolSeparator = toolName.indexOf("__", "mcp__".length);
-    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === requiredTool;
+    return mcpToolMatchesBaseName(toolName, requiredTool);
   });
 }
 
-function workflowMcpStructuredQuestionsOptIn(env: NodeJS.ProcessEnv = process.env): boolean {
-  const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
-  return value === "1" || value === "true";
-}
-
-export function supportsStructuredQuestions(
-  activeTools: string[],
-  options: Pick<WorkflowCapabilityOptions, "authMode" | "baseUrl" | "env"> = {},
-): boolean {
-  if (!hasAskUserQuestionsTool(activeTools)) return false;
-  if (usesWorkflowMcpTransport(options.authMode, options.baseUrl)) {
-    // Claude Code local workflow-MCP exposes ask_user_questions, but form
-    // elicitation can return an immediate cancel outside GSD's chat turn. Keep
-    // checkpoints in plain chat unless a caller deliberately opts into testing
-    // that transport.
-    return workflowMcpStructuredQuestionsOptIn(options.env);
-  }
-
-  return true;
-}
-
 export function getWorkflowTransportSupportError(
   provider: string | undefined,
   requiredTools: string[],
@@ -488,13 +400,13 @@ export function getWorkflowTransportSupportError(
 
   const uniqueRequired = [...new Set(requiredTools)];
   const missing = (options.activeTools && options.activeTools.length > 0)
-    ? uniqueRequired.filter((tool) => !hasRequiredTool(tool, options.activeTools!))
-    : uniqueRequired.filter((tool) => !MCP_WORKFLOW_TOOL_SURFACE.has(tool));
+    ? uniqueRequired.filter((tool) => !isWorkflowToolSurfaceName(tool) && !hasRequiredTool(tool, options.activeTools!))
+    : uniqueRequired.filter((tool) => !isWorkflowToolSurfaceName(tool));
   if (missing.length === 0) return null;
 
   if (options.activeTools && options.activeTools.length > 0) {
     return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the active runtime toolset currently exposes only ${options.activeTools.slice().sort().join(", ")}.`;
   }
 
-  return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the workflow MCP transport currently exposes only ${Array.from(MCP_WORKFLOW_TOOL_SURFACE).sort().join(", ")}.`;
+  return `Provider ${providerLabel} cannot run ${surface}${unitLabel}: this unit requires ${missing.join(", ")}, but the workflow MCP transport currently exposes only ${[...WORKFLOW_TOOL_SURFACE_NAMES].sort().join(", ")}.`;
 }

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

@@ -3,6 +3,16 @@ import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
 import type { WorkflowEvent } from "./workflow-events.js";
+import {
+  normalizeWorkflowEventCommand,
+  workflowEventEntityKey,
+} from "./workflow-event-vocabulary.js";
+import {
+  readWorktreeEventLogPath,
+  workflowEventLogPath,
+  writeWorkflowEventLog,
+  writeWorktreeEventLog,
+} from "./workflow-event-ledger.js";
 import {
   transaction,
   updateTaskStatus,
@@ -13,11 +23,11 @@ import {
   getMilestoneSlices,
   insertVerificationEvidence,
   upsertDecision,
-  openDatabase,
   setTaskBlockerDiscovered,
   insertOrIgnoreSlice,
   insertOrIgnoreTask,
 } from "./gsd-db.js";
+import { openWorkflowDatabasePath } from "./db-workspace.js";
 import { isClosedStatus } from "./status-guards.js";
 import { invalidateStateCache } from "./state.js";
 import { clearPathCache, resolveGsdPathContract } from "./paths.js";
@@ -82,14 +92,11 @@ function replayEvents(events: WorkflowEvent[]): void {
   transaction(() => {
   for (const event of events) {
     const p = event.params;
-    // Normalize cmd format: completion tools write hyphens ("complete-task"),
-    // legacy logs use underscores ("complete_task"). Accept both formats.
-    // Type guard: malformed event lines with non-string cmd are skipped.
-    if (typeof event.cmd !== "string") {
+    const cmd = normalizeWorkflowEventCommand(event.cmd);
+    if (!cmd) {
       logWarning("reconcile", `Event with non-string cmd skipped: ${JSON.stringify(event.cmd)}`);
       continue;
     }
-    const cmd = event.cmd.replace(/-/g, "_");
     switch (cmd) {
       case "complete_task": {
         const milestoneId = p["milestoneId"] as string;
@@ -235,48 +242,7 @@ function replayEvents(events: WorkflowEvent[]): void {
 export function extractEntityKey(
   event: WorkflowEvent,
 ): { type: string; id: string } | null {
-  const p = event.params;
-  // Normalize cmd format: accept both hyphens and underscores
-  if (typeof event.cmd !== "string") return null;
-  const cmd = event.cmd.replace(/-/g, "_");
-
-  switch (cmd) {
-    case "complete_task":
-    case "start_task":
-    case "skip_task":
-    case "report_blocker":
-    case "record_verification":
-    case "plan_task":
-      return typeof p["taskId"] === "string"
-        ? { type: "task", id: p["taskId"] }
-        : null;
-
-    case "complete_slice":
-    case "replan_slice":
-      return typeof p["sliceId"] === "string"
-        ? { type: "slice", id: p["sliceId"] }
-        : null;
-
-    case "plan_slice":
-      return typeof p["sliceId"] === "string"
-        ? { type: "slice_plan", id: p["sliceId"] }
-        : null;
-
-    case "complete_milestone":
-    case "plan_milestone":
-      return typeof p["milestoneId"] === "string"
-        ? { type: "milestone", id: p["milestoneId"] }
-        : null;
-
-    case "save_decision":
-      if (typeof p["scope"] === "string" && typeof p["decision"] === "string") {
-        return { type: "decision", id: `${p["scope"]}:${p["decision"]}` };
-      }
-      return null;
-
-    default:
-      return null;
-  }
+  return workflowEventEntityKey(event);
 }
 
 // ─── detectConflicts ──────────────────────────────────────────────────────────
@@ -360,13 +326,6 @@ function rewriteDivergedEventsForEntity(
   return rewritten;
 }
 
-function writeEventLog(basePath: string, events: WorkflowEvent[]): void {
-  const dir = join(basePath, ".gsd");
-  mkdirSync(dir, { recursive: true });
-  const content = events.map((e) => JSON.stringify(e)).join("\n") + (events.length > 0 ? "\n" : "");
-  atomicWriteSync(join(dir, "event-log.jsonl"), content);
-}
-
 // ─── writeConflictsFile ───────────────────────────────────────────────────────
 
 /**
@@ -450,12 +409,18 @@ function _reconcileWorktreeLogsInner(
   worktreeBasePath: string,
 ): ReconcileResult {
   // Step 1: Read both logs
-  const mainLogPath = join(mainBasePath, ".gsd", "event-log.jsonl");
-  const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+  const mainLogPath = workflowEventLogPath(mainBasePath);
+  const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
 
   const mainEvents = readEvents(mainLogPath);
   const wtEvents = readEvents(wtLogPath);
 
+  // Canonical worktree appends are already durable in the project ledger.
+  // Empty/missing worktree shards are legacy-only absence, not divergence.
+  if (wtEvents.length === 0) {
+    return { autoMerged: 0, conflicts: [] };
+  }
+
   // Step 2: Find fork point
   const forkPoint = findForkPoint(mainEvents, wtEvents);
 
@@ -495,12 +460,10 @@ function _reconcileWorktreeLogsInner(
 
   const baseEvents = mainEvents.slice(0, forkPoint + 1);
   const mergedLog = baseEvents.concat(merged);
-  const logContent = mergedLog.map((e) => JSON.stringify(e)).join("\n") + (mergedLog.length > 0 ? "\n" : "");
-  mkdirSync(join(mainBasePath, ".gsd"), { recursive: true });
-  atomicWriteSync(join(mainBasePath, ".gsd", "event-log.jsonl"), logContent);
+  writeWorkflowEventLog(mainBasePath, mergedLog);
 
   // Step 8: Replay into DB (wrapped in a transaction by replayEvents)
-  openDatabase(resolveGsdPathContract(mainBasePath).projectDb);
+  openWorkflowDatabasePath(resolveGsdPathContract(mainBasePath).projectDb);
   replayEvents(merged);
 
   // Step 9: Write manifest
@@ -636,8 +599,8 @@ export function resolveConflict(
   const conflict = conflicts[idx]!;
   const eventsToReplay = pick === "main" ? conflict.mainSideEvents : conflict.worktreeSideEvents;
 
-  const mainLogPath = join(basePath, ".gsd", "event-log.jsonl");
-  const wtLogPath = join(worktreeBasePath, ".gsd", "event-log.jsonl");
+  const mainLogPath = workflowEventLogPath(basePath);
+  const wtLogPath = readWorktreeEventLogPath(worktreeBasePath);
   const mainEvents = readEvents(mainLogPath);
   const wtEvents = readEvents(wtLogPath);
   const forkPoint = findForkPoint(mainEvents, wtEvents);
@@ -652,10 +615,14 @@ export function resolveConflict(
 
   const targetBasePath = pick === "main" ? worktreeBasePath : basePath;
   const targetBaseEvents = pick === "main" ? wtBaseEvents : mainBaseEvents;
-  writeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  if (pick === "main") {
+    writeWorktreeEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  } else {
+    writeWorkflowEventLog(targetBasePath, targetBaseEvents.concat(rewrittenTargetEvents));
+  }
 
   // Replay resolved events through the DB (updates DB state)
-  openDatabase(resolveGsdPathContract(basePath).projectDb);
+  openWorkflowDatabasePath(resolveGsdPathContract(basePath).projectDb);
   replayEvents(eventsToReplay);
   invalidateStateCache();
   clearPathCache();

package/src/resources/extensions/gsd/workflow-tool-surface.ts

@@ -0,0 +1,76 @@
+// Project/App: gsd-pi
+// File Purpose: Adapts shared workflow tool contracts into the extension runtime surface.
+
+import {
+  CANONICAL_WORKFLOW_TOOL_NAMES as CONTRACT_CANONICAL_WORKFLOW_TOOL_NAMES,
+  WORKFLOW_TOOL_ALIAS_NAMES as CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES,
+  WORKFLOW_TOOL_CONTRACTS as CONTRACT_WORKFLOW_TOOL_CONTRACTS,
+  WORKFLOW_TOOL_NAMES as CONTRACT_WORKFLOW_TOOL_NAMES,
+} from "@opengsd/contracts";
+import { stripMcpToolPrefix } from "./mcp-tool-name.js";
+
+export interface WorkflowToolAliasPair {
+  canonical: string;
+  alias: string;
+}
+
+export const WORKFLOW_TOOL_CONTRACTS = CONTRACT_WORKFLOW_TOOL_CONTRACTS;
+
+export const CANONICAL_WORKFLOW_TOOL_NAMES = CONTRACT_CANONICAL_WORKFLOW_TOOL_NAMES;
+export const WORKFLOW_TOOL_ALIAS_NAMES = CONTRACT_WORKFLOW_TOOL_ALIAS_NAMES;
+export const DB_WORKFLOW_TOOL_NAMES = CONTRACT_WORKFLOW_TOOL_NAMES;
+
+export const WORKFLOW_TOOL_ALIAS_PAIRS: readonly WorkflowToolAliasPair[] =
+  WORKFLOW_TOOL_CONTRACTS.flatMap((tool) =>
+    tool.aliases.map((alias) => ({ canonical: tool.canonicalName, alias })),
+  );
+
+export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL: Readonly<Record<string, string>> =
+  Object.fromEntries(WORKFLOW_TOOL_ALIAS_PAIRS.map(({ alias, canonical }) => [alias, canonical]));
+
+export const WORKFLOW_MCP_ADAPTER_TOOL_NAMES = [
+  "gsd_cancel",
+  "gsd_captures",
+  "ask_user_questions",
+  "gsd_doctor",
+  "gsd_execute",
+  "gsd_graph",
+  "gsd_history",
+  "gsd_knowledge",
+  "gsd_progress",
+  "gsd_query",
+  "gsd_result",
+  "gsd_resolve_blocker",
+  "gsd_roadmap",
+  "gsd_status",
+] as const;
+
+/** Session-orchestration tools exposed by the workflow MCP adapter alongside the contract tools. */
+export type WorkflowMcpAdapterToolName = (typeof WORKFLOW_MCP_ADAPTER_TOOL_NAMES)[number];
+
+export const WORKFLOW_TOOL_SURFACE_NAMES = [
+  ...WORKFLOW_MCP_ADAPTER_TOOL_NAMES,
+  ...DB_WORKFLOW_TOOL_NAMES,
+] as readonly string[];
+
+const WORKFLOW_TOOL_SURFACE_NAME_SET = new Set(WORKFLOW_TOOL_SURFACE_NAMES);
+
+export { stripMcpToolPrefix } from "./mcp-tool-name.js";
+
+export function canonicalWorkflowSurfaceToolName(toolName: string): string {
+  const baseName = stripMcpToolPrefix(toolName);
+  return WORKFLOW_TOOL_ALIAS_TO_CANONICAL[baseName] ?? baseName;
+}
+
+export function isWorkflowSurfaceAliasTool(toolName: string): boolean {
+  const baseName = stripMcpToolPrefix(toolName);
+  return WORKFLOW_TOOL_ALIAS_TO_CANONICAL[baseName] !== undefined;
+}
+
+export function isWorkflowToolSurfaceName(toolName: string): boolean {
+  return WORKFLOW_TOOL_SURFACE_NAME_SET.has(stripMcpToolPrefix(toolName));
+}
+
+export function aliasesForWorkflowTool(canonicalName: string): readonly string[] {
+  return WORKFLOW_TOOL_CONTRACTS.find((tool) => tool.canonicalName === canonicalName)?.aliases ?? [];
+}

package/src/resources/extensions/gsd/workspace-git-guard.ts

@@ -14,6 +14,7 @@ export function isWorkspaceGitAllowedCommand(trimmed: string): boolean {
 
   const [name, subcommand] = command.split(/\s+/, 2);
   if (name === "doctor") return true;
+  if (name === "forensics") return true;
   if (name === "closeout" || command.startsWith("closeout")) return true;
   if (name === "dispatch") {
     return subcommand === "complete" || subcommand === "complete-milestone";