@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/dist/resources/extensions/gsd/workflow-events.js

@@ -1,8 +1,8 @@
-import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { readFileSync, existsSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
 import { withFileLockSync } from "./file-lock.js";
+import { appendWorkflowEvent, workflowEventArchivePath, workflowEventLogPath, } from "./workflow-event-ledger.js";
 import { logWarning } from "./workflow-logger.js";
 // ─── Session ID ───────────────────────────────────────────────────────────
 /**
@@ -20,19 +20,7 @@ export function getSessionId() {
  * Creates .gsd directory if needed.
  */
 export function appendEvent(basePath, event) {
-    const hash = createHash("sha256")
-        .update(JSON.stringify({ cmd: event.cmd, params: event.params }))
-        .digest("hex")
-        .slice(0, 16);
-    const fullEvent = {
-        v: 2,
-        ...event,
-        hash,
-        session_id: ENGINE_SESSION_ID,
-    };
-    const dir = join(basePath, ".gsd");
-    mkdirSync(dir, { recursive: true });
-    appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+    appendWorkflowEvent(basePath, event, ENGINE_SESSION_ID);
 }
 // ─── readEvents ──────────────────────────────────────────────────────────
 /**
@@ -87,8 +75,8 @@ export function findForkPoint(logA, logB) {
  * @returns { archived: number } — count of events moved to archive
  */
 export function compactMilestoneEvents(basePath, milestoneId) {
-    const logPath = join(basePath, ".gsd", "event-log.jsonl");
-    const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+    const logPath = workflowEventLogPath(basePath);
+    const archivePath = workflowEventArchivePath(basePath, milestoneId);
     return withFileLockSync(logPath, () => {
         const allEvents = readEvents(logPath);
         // Single-pass partition to halve the work (per reviewer agent)

package/dist/resources/extensions/gsd/workflow-logger.js

@@ -42,6 +42,10 @@ export function setStderrLoggingEnabled(enabled) {
     _stderrEnabled = enabled;
     return previous;
 }
+/** Whether GSD extension diagnostics may write directly to process.stderr. */
+export function isGsdExtensionStderrEnabled() {
+    return _stderrEnabled;
+}
 // ─── Public API ─────────────────────────────────────────────────────────
 /**
  * Record a warning. Warnings are persisted to notifications and buffered for

package/dist/resources/extensions/gsd/workflow-mcp-auto-prep.js

@@ -1,4 +1,5 @@
 import { ensureProjectWorkflowMcpConfig, } from "./mcp-project-config.js";
+import { warmWorkflowMcpProbeInBackground } from "./workflow-mcp-readiness-cache.js";
 import { usesWorkflowMcpTransport } from "./workflow-mcp.js";
 function withModelOverride(ctx, modelOverride) {
     if (!modelOverride)
@@ -46,6 +47,7 @@ export function prepareWorkflowMcpForProject(ctx, projectRoot, modelOverride) {
         if (result.status !== "unchanged") {
             prepCtx.ui?.notify?.(`GSD MCP Server Prepared at ${result.configPath}`, "info");
         }
+        warmWorkflowMcpProbeInBackground(projectRoot);
         return result;
     }
     catch (err) {

package/dist/resources/extensions/gsd/workflow-mcp-readiness-cache.js

@@ -0,0 +1,105 @@
+// Project/App: gsd-pi
+// File Purpose: Share recent workflow MCP probe results across guided-flow and Claude Code SDK preflight.
+import { testMcpServerConnection } from "../mcp-client/manager.js";
+import { mcpToolMatchesBaseName } from "./mcp-tool-name.js";
+import { detectWorkflowMcpLaunchConfig, resolveWorkflowMcpProjectRoot, } from "./workflow-mcp.js";
+import { isWorkflowToolSurfaceName } from "./workflow-tool-surface.js";
+/** Reuse a recent successful probe instead of spawning another stdio server. */
+export const WORKFLOW_MCP_PROBE_CACHE_TTL_MS = 120_000;
+/** Per-probe connect + tools/list budget (server typically ready in ~1–2s). */
+export const WORKFLOW_MCP_PROBE_TIMEOUT_MS = 5_000;
+const cacheByProject = new Map();
+const probeInFlightByProject = new Map();
+let activeWorkflowMcpSdkSessions = 0;
+function cacheKey(projectRoot) {
+    return resolveWorkflowMcpProjectRoot(projectRoot);
+}
+export function beginWorkflowMcpSdkSession() {
+    activeWorkflowMcpSdkSessions++;
+}
+export function endWorkflowMcpSdkSession() {
+    activeWorkflowMcpSdkSessions = Math.max(0, activeWorkflowMcpSdkSessions - 1);
+}
+export function getCachedWorkflowMcpProbe(projectRoot) {
+    const entry = cacheByProject.get(cacheKey(projectRoot));
+    if (!entry)
+        return null;
+    if (Date.now() - entry.probedAt > WORKFLOW_MCP_PROBE_CACHE_TTL_MS) {
+        cacheByProject.delete(cacheKey(projectRoot));
+        return null;
+    }
+    return entry;
+}
+export function recordWorkflowMcpProbe(projectRoot, serverName, tools) {
+    cacheByProject.set(cacheKey(projectRoot), {
+        serverName,
+        tools: [...tools],
+        probedAt: Date.now(),
+    });
+}
+export function clearWorkflowMcpProbeCache(projectRoot) {
+    if (projectRoot === undefined) {
+        cacheByProject.clear();
+        probeInFlightByProject.clear();
+        activeWorkflowMcpSdkSessions = 0;
+        return;
+    }
+    const key = cacheKey(projectRoot);
+    cacheByProject.delete(key);
+    probeInFlightByProject.delete(key);
+}
+export function workflowMcpProbeAdvertisesSurface(tools) {
+    return tools.some((tool) => isWorkflowToolSurfaceName(tool));
+}
+export function cachedWorkflowMcpCoversRequired(projectRoot, serverName, required) {
+    const entry = getCachedWorkflowMcpProbe(projectRoot);
+    if (!entry || entry.serverName !== serverName)
+        return false;
+    return required.every((tool) => entry.tools.some((name) => name === tool || mcpToolMatchesBaseName(name, tool)));
+}
+async function runProbeAndCacheWorkflowMcp(projectRoot, options = {}) {
+    const root = cacheKey(projectRoot);
+    const launch = detectWorkflowMcpLaunchConfig(root);
+    const serverName = launch?.name ?? "gsd-workflow";
+    const cached = getCachedWorkflowMcpProbe(projectRoot);
+    if (cached && workflowMcpProbeAdvertisesSurface(cached.tools)) {
+        return { ok: true, tools: cached.tools, serverName: cached.serverName };
+    }
+    const result = await testMcpServerConnection(serverName, {
+        projectDir: root,
+        timeoutMs: options.timeoutMs ?? WORKFLOW_MCP_PROBE_TIMEOUT_MS,
+    });
+    if (result.ok && workflowMcpProbeAdvertisesSurface(result.tools)) {
+        recordWorkflowMcpProbe(projectRoot, serverName, result.tools);
+    }
+    return {
+        ok: result.ok,
+        tools: result.tools,
+        serverName,
+        error: result.error,
+    };
+}
+export async function probeAndCacheWorkflowMcp(projectRoot, options = {}) {
+    const key = cacheKey(projectRoot);
+    const inFlight = probeInFlightByProject.get(key);
+    if (inFlight)
+        return inFlight;
+    const promise = runProbeAndCacheWorkflowMcp(projectRoot, options).finally(() => {
+        probeInFlightByProject.delete(key);
+    });
+    probeInFlightByProject.set(key, promise);
+    return promise;
+}
+/** Fire-and-forget probe so /gsd dispatch often hits a warm cache. */
+export function warmWorkflowMcpProbeInBackground(projectRoot) {
+    if (activeWorkflowMcpSdkSessions > 0)
+        return;
+    const key = cacheKey(projectRoot);
+    if (getCachedWorkflowMcpProbe(projectRoot))
+        return;
+    if (probeInFlightByProject.has(key))
+        return;
+    void probeAndCacheWorkflowMcp(projectRoot).catch(() => {
+        // Background warm is best-effort.
+    });
+}

package/dist/resources/extensions/gsd/workflow-mcp.js

@@ -1,8 +1,12 @@
 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 };
 /** Session cwd may be a milestone worktree; MCP config and server discovery use the project root. */
 export function resolveWorkflowMcpProjectRoot(sessionCwd) {
     let resolved;
@@ -19,72 +23,9 @@ export function resolveWorkflowMcpProjectRoot(sessionCwd) {
     }
     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) {
-    return MCP_WORKFLOW_TOOL_SURFACE.has(toolName);
+    return isWorkflowToolSurfaceName(toolName);
 }
 function parseLookupOutput(output) {
     return output
@@ -113,6 +54,7 @@ function lookupCommand(command, platform = process.platform) {
         return null;
     }
 }
+const gsdPiRepoRootCache = new Map();
 function findGsdPiRepoRoot(startPath) {
     let current;
     try {
@@ -121,15 +63,22 @@ function findGsdPiRepoRoot(startPath) {
     catch {
         current = resolve(startPath);
     }
+    const cacheKey = current;
+    if (gsdPiRepoRootCache.has(cacheKey)) {
+        return gsdPiRepoRootCache.get(cacheKey) ?? null;
+    }
     while (true) {
         const distCli = resolve(current, "packages", "mcp-server", "dist", "cli.js");
-        if (existsSync(distCli))
+        if (existsSync(distCli)) {
+            gsdPiRepoRootCache.set(cacheKey, current);
             return current;
+        }
         const parent = dirname(current);
         if (parent === current)
             break;
         current = parent;
     }
+    gsdPiRepoRootCache.set(cacheKey, null);
     return null;
 }
 function findWorkflowCliFromAncestorPath(startPath) {
@@ -239,8 +188,12 @@ function getBundledWorkflowWriteGateModulePath() {
 }
 function getResolveTsHookPath() {
     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))),
@@ -355,45 +308,13 @@ export function getRequiredWorkflowToolsForGuidedUnit(unitType) {
 export function getRequiredWorkflowToolsForAutoUnit(unitType) {
     return getRequiredWorkflowToolsForUnit(unitType);
 }
-export function usesWorkflowMcpTransport(authMode, baseUrl) {
-    return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
-}
-function hasAskUserQuestionsTool(activeTools) {
-    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, activeTools) {
     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 = process.env) {
-    const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
-    return value === "1" || value === "true";
-}
-export function supportsStructuredQuestions(activeTools, options = {}) {
-    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, requiredTools, options = {}) {
     if (!provider || requiredTools.length === 0)
         return null;
@@ -410,12 +331,12 @@ export function getWorkflowTransportSupportError(provider, requiredTools, option
     }
     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/dist/resources/extensions/gsd/workflow-projections.js

@@ -13,7 +13,7 @@ import { isClosedStatus } from "./status-guards.js";
 import { deriveState } from "./state.js";
 import { renderPlanFromDb, renderRoadmapFromDb } from "./markdown-renderer.js";
 import { readManifest } from "./workflow-manifest.js";
-import { gsdRoot } from "./paths.js";
+import { gsdRoot, resolveSliceFile, resolveMilestonePath, resolveSlicePath, gsdProjectionRoot } from "./paths.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────
 /**
  * Strip a leading ID prefix (e.g. "M001: " or "S04: ") from a title
@@ -276,7 +276,24 @@ export function renderSummaryProjection(basePath, milestoneId, sliceId, taskId)
         return;
     const evidenceRows = getVerificationEvidence(milestoneId, sliceId, taskId);
     const content = renderSummaryContent(taskRow, sliceId, milestoneId, evidenceRows);
-    const dir = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, "tasks");
+    // Layout-aware: avoid creating a milestones/ directory as a side effect for
+    // flat-phase projects. If milestonesDir() sees a freshly-created milestones/
+    // dir it treats the project as legacy, breaking all subsequent path resolution.
+    const slicePath = resolveSlicePath(basePath, milestoneId, sliceId);
+    const phaseDir = resolveMilestonePath(basePath, milestoneId);
+    let dir;
+    if (slicePath && phaseDir && slicePath !== phaseDir) {
+        // Legacy layout: slice has its own slices/SID/ subdir → tasks/ subdir
+        dir = join(slicePath, "tasks");
+    }
+    else if (phaseDir) {
+        // Flat-phase: task summaries go in the phase dir (no tasks/ subdir needed)
+        dir = phaseDir;
+    }
+    else {
+        // Fallback: legacy hardcoded path (milestone dir not on disk yet)
+        dir = join(gsdProjectionRoot(basePath), "milestones", milestoneId, "slices", sliceId, "tasks");
+    }
     mkdirSync(dir, { recursive: true });
     atomicWriteSync(join(dir, `${taskId}-SUMMARY.md`), content);
 }
@@ -447,7 +464,9 @@ export async function regenerateIfMissing(basePath, milestoneId, sliceId, fileTy
     let filePath;
     switch (fileType) {
         case "PLAN":
-            filePath = join(basePath, ".gsd", "milestones", milestoneId, "slices", sliceId, `${sliceId}-PLAN.md`);
+            // Use resolveSliceFile so both flat-phase and legacy layouts are detected.
+            // Falls back to "" (non-existent) when the file hasn't been rendered yet.
+            filePath = resolveSliceFile(basePath, milestoneId, sliceId, "PLAN") ?? "";
             break;
         case "ROADMAP":
             filePath = join(basePath, ".gsd", "milestones", milestoneId, `${milestoneId}-ROADMAP.md`);
@@ -497,7 +516,9 @@ export async function regenerateIfMissing(basePath, milestoneId, sliceId, fileTy
         switch (fileType) {
             case "PLAN":
                 await renderPlanFromDb(basePath, milestoneId, sliceId);
-                return existsSync(filePath);
+                // Re-resolve after render: the rendered file may be at a different path
+                // from the pre-check (flat-phase vs legacy). resolveSliceFile finds it.
+                return !!(resolveSliceFile(basePath, milestoneId, sliceId, "PLAN"));
             case "ROADMAP":
                 await renderRoadmapFromDb(basePath, milestoneId);
                 return existsSync(filePath);

package/dist/resources/extensions/gsd/workflow-reconcile.js

@@ -2,7 +2,10 @@ import { join } from "node:path";
 import { mkdirSync, existsSync, readFileSync, unlinkSync } from "node:fs";
 import { logWarning, logError } from "./workflow-logger.js";
 import { readEvents, findForkPoint, getSessionId } from "./workflow-events.js";
-import { transaction, updateTaskStatus, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, openDatabase, setTaskBlockerDiscovered, insertOrIgnoreSlice, insertOrIgnoreTask, } from "./gsd-db.js";
+import { normalizeWorkflowEventCommand, workflowEventEntityKey, } from "./workflow-event-vocabulary.js";
+import { readWorktreeEventLogPath, workflowEventLogPath, writeWorkflowEventLog, writeWorktreeEventLog, } from "./workflow-event-ledger.js";
+import { transaction, updateTaskStatus, updateSliceStatus, updateMilestoneStatus, getSliceTasks, insertMilestone, getMilestoneSlices, insertVerificationEvidence, upsertDecision, 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";
@@ -47,14 +50,11 @@ function replayEvents(events) {
     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"];
@@ -198,43 +198,7 @@ function replayEvents(events) {
  * (e.g. unknown or future cmds).
  */
 export function extractEntityKey(event) {
-    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 ──────────────────────────────────────────────────────────
 /**
@@ -301,12 +265,6 @@ function rewriteDivergedEventsForEntity(divergedEvents, entityType, entityId, re
     }
     return rewritten;
 }
-function writeEventLog(basePath, events) {
-    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 ───────────────────────────────────────────────────────
 /**
  * Write a human-readable CONFLICTS.md to basePath/.gsd/CONFLICTS.md.
@@ -374,10 +332,15 @@ export function reconcileWorktreeLogs(mainBasePath, worktreeBasePath) {
 }
 function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     // 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);
     // Step 3: Slice diverged sets
@@ -411,11 +374,9 @@ function _reconcileWorktreeLogsInner(mainBasePath, worktreeBasePath) {
     }
     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
     try {
@@ -532,8 +493,8 @@ pick) {
         throw new Error(`No conflict found for entity ${entityKey}`);
     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);
@@ -546,9 +507,14 @@ pick) {
         : rewriteDivergedEventsForEntity(mainDiverged, entityType, entityId, eventsToReplay);
     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/dist/resources/extensions/gsd/workflow-tool-surface.js

@@ -0,0 +1,46 @@
+// 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 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 = WORKFLOW_TOOL_CONTRACTS.flatMap((tool) => tool.aliases.map((alias) => ({ canonical: tool.canonicalName, alias })));
+export const WORKFLOW_TOOL_ALIAS_TO_CANONICAL = 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",
+];
+export const WORKFLOW_TOOL_SURFACE_NAMES = [
+    ...WORKFLOW_MCP_ADAPTER_TOOL_NAMES,
+    ...DB_WORKFLOW_TOOL_NAMES,
+];
+const WORKFLOW_TOOL_SURFACE_NAME_SET = new Set(WORKFLOW_TOOL_SURFACE_NAMES);
+export { stripMcpToolPrefix } from "./mcp-tool-name.js";
+export function canonicalWorkflowSurfaceToolName(toolName) {
+    const baseName = stripMcpToolPrefix(toolName);
+    return WORKFLOW_TOOL_ALIAS_TO_CANONICAL[baseName] ?? baseName;
+}
+export function isWorkflowSurfaceAliasTool(toolName) {
+    const baseName = stripMcpToolPrefix(toolName);
+    return WORKFLOW_TOOL_ALIAS_TO_CANONICAL[baseName] !== undefined;
+}
+export function isWorkflowToolSurfaceName(toolName) {
+    return WORKFLOW_TOOL_SURFACE_NAME_SET.has(stripMcpToolPrefix(toolName));
+}
+export function aliasesForWorkflowTool(canonicalName) {
+    return WORKFLOW_TOOL_CONTRACTS.find((tool) => tool.canonicalName === canonicalName)?.aliases ?? [];
+}

package/dist/resources/extensions/gsd/workspace-git-guard.js

@@ -12,6 +12,8 @@ export function isWorkspaceGitAllowedCommand(trimmed) {
     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") {