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

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

@@ -0,0 +1,150 @@
+// 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;
+
+export interface WorkflowMcpProbeCacheEntry {
+  serverName: string;
+  tools: readonly string[];
+  probedAt: number;
+}
+
+type WorkflowMcpProbeResult = {
+  ok: boolean;
+  tools: readonly string[];
+  serverName?: string;
+  error?: string;
+};
+
+const cacheByProject = new Map<string, WorkflowMcpProbeCacheEntry>();
+const probeInFlightByProject = new Map<string, Promise<WorkflowMcpProbeResult>>();
+let activeWorkflowMcpSdkSessions = 0;
+
+function cacheKey(projectRoot: string): string {
+  return resolveWorkflowMcpProjectRoot(projectRoot);
+}
+
+export function beginWorkflowMcpSdkSession(): void {
+  activeWorkflowMcpSdkSessions++;
+}
+
+export function endWorkflowMcpSdkSession(): void {
+  activeWorkflowMcpSdkSessions = Math.max(0, activeWorkflowMcpSdkSessions - 1);
+}
+
+export function getCachedWorkflowMcpProbe(projectRoot: string): WorkflowMcpProbeCacheEntry | null {
+  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: string,
+  serverName: string,
+  tools: readonly string[],
+): void {
+  cacheByProject.set(cacheKey(projectRoot), {
+    serverName,
+    tools: [...tools],
+    probedAt: Date.now(),
+  });
+}
+
+export function clearWorkflowMcpProbeCache(projectRoot?: string): void {
+  if (projectRoot === undefined) {
+    cacheByProject.clear();
+    probeInFlightByProject.clear();
+    activeWorkflowMcpSdkSessions = 0;
+    return;
+  }
+  const key = cacheKey(projectRoot);
+  cacheByProject.delete(key);
+  probeInFlightByProject.delete(key);
+}
+
+export function workflowMcpProbeAdvertisesSurface(tools: readonly string[]): boolean {
+  return tools.some((tool) => isWorkflowToolSurfaceName(tool));
+}
+
+export function cachedWorkflowMcpCoversRequired(
+  projectRoot: string,
+  serverName: string,
+  required: readonly string[],
+): boolean {
+  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: string,
+  options: { timeoutMs?: number } = {},
+): Promise<WorkflowMcpProbeResult> {
+  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: string,
+  options: { timeoutMs?: number } = {},
+): Promise<WorkflowMcpProbeResult> {
+  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: string): void {
+  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/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,
@@ -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,9 +460,7 @@ 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)
   openWorkflowDatabasePath(resolveGsdPathContract(mainBasePath).projectDb);
@@ -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,7 +615,11 @@ 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)
   openWorkflowDatabasePath(resolveGsdPathContract(basePath).projectDb);

package/src/resources/extensions/gsd/worktree-manager.ts

@@ -656,7 +656,12 @@ export function removeWorktree(
   const resolvedPathSafe = isInsideWorktreesDir(basePath, resolvedWtPath);
 
   // If we're inside the worktree, move out first — git can't remove an in-use directory
-  const cwd = process.cwd();
+  let cwd: string;
+  try {
+    cwd = process.cwd();
+  } catch {
+    cwd = basePath;
+  }
   const resolvedCwd = existsSync(cwd) ? realpathSync(cwd) : cwd;
   if (resolvedCwd === resolvedWtPath || resolvedCwd.startsWith(resolvedWtPath + sep)) {
     process.chdir(basePath);

package/src/resources/extensions/gsd/worktree-safety.ts

@@ -218,52 +218,54 @@ export function createWorktreeSafetyModule(
       }
 
       let registered: readonly RegisteredWorktree[] | undefined;
-      try {
-        registered = deps.listRegisteredWorktrees?.(projectRoot);
-      } catch (error) {
-        return failure(
-          "worktree-git-probe-failed",
-          `Unable to list registered worktrees for project root ${projectRoot}.`,
-          "Recover or recreate the milestone worktree before dispatching the source-writing Unit.",
-          { projectRoot, error: errorMessage(error) },
-        );
-      }
-      if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
-        const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
-        let attemptedPrune = false;
+      if (isolationMode === "worktree") {
+        try {
+          registered = deps.listRegisteredWorktrees?.(projectRoot);
+        } catch (error) {
+          return failure(
+            "worktree-git-probe-failed",
+            `Unable to list registered worktrees for project root ${projectRoot}.`,
+            "Recover or recreate the milestone worktree before dispatching the source-writing Unit.",
+            { projectRoot, error: errorMessage(error) },
+          );
+        }
+        if (registered && !registered.some((worktree) => samePath(worktree.path, unitRoot))) {
+          const wasPreviouslyTracked = unregisteredRecoveryFailed.has(unitRoot);
+          let attemptedPrune = false;
 
-        if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
-          attemptedPrune = true;
-          try {
-            deps.pruneRegisteredWorktrees(projectRoot);
-            const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
-            if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
-              unregisteredRecoveryFailed.delete(unitRoot);
-              registered = rechecked;
-            } else {
+          if (!wasPreviouslyTracked && deps.pruneRegisteredWorktrees) {
+            attemptedPrune = true;
+            try {
+              deps.pruneRegisteredWorktrees(projectRoot);
+              const rechecked = deps.listRegisteredWorktrees?.(projectRoot);
+              if (rechecked?.some((worktree) => samePath(worktree.path, unitRoot))) {
+                unregisteredRecoveryFailed.delete(unitRoot);
+                registered = rechecked;
+              } else {
+                unregisteredRecoveryFailed.add(unitRoot);
+              }
+            } catch (error) {
               unregisteredRecoveryFailed.add(unitRoot);
+              return failure(
+                "worktree-git-probe-failed",
+                `Unable to recover unregistered worktree root ${unitRoot}.`,
+                "Run 'git worktree prune', then recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
+                { projectRoot, unitRoot, error: errorMessage(error) },
+              );
             }
-          } catch (error) {
-            unregisteredRecoveryFailed.add(unitRoot);
+          }
+
+          if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
             return failure(
-              "worktree-git-probe-failed",
-              `Unable to recover unregistered worktree root ${unitRoot}.`,
-              "Run 'git worktree prune', then recreate the milestone worktree before dispatching the source-writing Unit.",
-              { projectRoot, unitRoot, error: errorMessage(error) },
+              "worktree-unregistered",
+              `Worktree root ${unitRoot} is not registered with git worktree list.`,
+              attemptedPrune || wasPreviouslyTracked
+                ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
+                : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
+              { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) },
             );
           }
         }
-
-        if (!registered?.some((worktree) => samePath(worktree.path, unitRoot))) {
-          return failure(
-            "worktree-unregistered",
-            `Worktree root ${unitRoot} is not registered with git worktree list.`,
-            attemptedPrune || wasPreviouslyTracked
-              ? "Worktree recovery was attempted but the root is still unregistered. Recreate or re-register the milestone worktree before dispatching the source-writing Unit."
-              : "Run 'git worktree prune'. If still unregistered, recreate or re-register the milestone worktree before dispatching the source-writing Unit.",
-            { unitRoot, attemptedPrune, trackedAsFailed: unregisteredRecoveryFailed.has(unitRoot) },
-          );
-        }
       }
 
       if (input.emptyWorktreeWithProjectContent) {

package/src/resources/extensions/gsd/worktree.ts

@@ -224,7 +224,13 @@ export function resolveGitHeadPath(dir: string): string | null {
  */
 export function nudgeGitBranchCache(previousCwd: string): void {
   const now = new Date();
-  for (const dir of [previousCwd, process.cwd()]) {
+  let currentCwd: string | null = null;
+  try {
+    currentCwd = process.cwd();
+  } catch {
+    currentCwd = null;
+  }
+  for (const dir of [previousCwd, currentCwd].filter((dir): dir is string => Boolean(dir))) {
     try {
       const headPath = resolveGitHeadPath(dir);
       if (headPath) utimesSync(headPath, now, now);

package/src/resources/extensions/mcp-client/manager.ts

@@ -105,6 +105,9 @@ const CHILD_ENV_ALLOWLIST = new Set([
 
 const MCP_STDERR_MAX_BYTES = 4096;
 
+/** Short-lived stdio probes must not register/kill production MCP PIDs (see probe-mode.ts). */
+export const GSD_MCP_PROBE_ENV = "GSD_MCP_PROBE";
+
 let cachedStatus: ManagedMcpStatus | null = null;
 let cachedStatusKey = "";
 
@@ -385,7 +388,10 @@ export async function testMcpServerConnection(
 			transport = new StdioClientTransport({
 				command: config.command ?? "",
 				args: config.args,
-				env: buildMcpChildEnv(config.env),
+				env: {
+					...buildMcpChildEnv(config.env),
+					[GSD_MCP_PROBE_ENV]: "1",
+				},
 				cwd: config.cwd,
 				stderr: "pipe",
 			});

package/src/resources/skills/create-skill/SKILL.md

@@ -174,6 +174,9 @@ description: ...          # What it does AND when to use it (third person)
 ---
 ```
 
+Frontmatter must parse as YAML. Quote description values containing `:` or use
+a folded block (`description: >`) for longer trigger descriptions.
+
 Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*`
 </yaml_requirements>
 

package/src/resources/skills/create-skill/references/skill-structure.md

@@ -109,6 +109,7 @@ description: What it does and when to use it (third person, specific triggers)
 - No XML tags
 - Third person (never first or second person)
 - Include what it does AND when to use it
+- Must parse as YAML; quote values containing `:` or use `description: >`
 
 **Critical rule**: Always write in third person.
 - ✅ "Processes Excel files and generates reports"

package/dist/resources/skills/gsd-browser/SKILL.md

@@ -1,41 +0,0 @@
----
-name: gsd-browser
-description: "Use gsd-browser for browser automation and UAT: navigating local apps, inspecting pages, clicking or filling controls, taking screenshots, asserting UI behavior, collecting console/network diagnostics, visual diffing, and creating evidence bundles. Prefer this over legacy Playwright browser tooling when both are available."
-allowed-tools: Bash(gsd-browser:*), Bash(gsd-browser *)
----
-
-# gsd-browser
-
-Use `gsd-browser` as the default browser surface for automated UAT and real UI verification.
-
-## MCP First
-
-When MCP tools are available, prefer the `gsd-browser` server:
-
-- Discovery: `browser_snapshot_refs`, `browser_find`, `browser_get_accessibility_tree`
-- Actions: `browser_act`, `browser_batch`, `browser_click_ref`, `browser_fill_ref`
-- Verification: `browser_assert`, `browser_screenshot`, `browser_visual_diff`
-- Diagnostics: `browser_get_console_logs`, `browser_get_network_logs`, `browser_debug_bundle`
-
-If the host namespaces MCP tools, use names like `mcp__gsd-browser__browser_snapshot_refs`.
-
-## CLI Fallback
-
-The daemon starts automatically on first browser command.
-
-```bash
-gsd-browser navigate http://localhost:3000
-gsd-browser snapshot
-gsd-browser click-ref @v1:e1
-gsd-browser wait-for --condition network_idle
-gsd-browser assert --checks '[{"kind":"url_contains","text":"dashboard"}]'
-gsd-browser screenshot --output /tmp/gsd-browser-uat.png --format png
-```
-
-After any navigation, submit, or dynamic DOM change, take a fresh snapshot before using refs again. Refs are versioned, such as `@v1:e1` and `@v2:e3`, and old refs can become stale.
-
-Use `--json` when parsing output programmatically. Use named sessions for parallel or project-specific work:
-
-```bash
-gsd-browser --session gsd-pi navigate http://localhost:3000
-```

package/src/resources/skills/gsd-browser/SKILL.md

@@ -1,41 +0,0 @@
----
-name: gsd-browser
-description: "Use gsd-browser for browser automation and UAT: navigating local apps, inspecting pages, clicking or filling controls, taking screenshots, asserting UI behavior, collecting console/network diagnostics, visual diffing, and creating evidence bundles. Prefer this over legacy Playwright browser tooling when both are available."
-allowed-tools: Bash(gsd-browser:*), Bash(gsd-browser *)
----
-
-# gsd-browser
-
-Use `gsd-browser` as the default browser surface for automated UAT and real UI verification.
-
-## MCP First
-
-When MCP tools are available, prefer the `gsd-browser` server:
-
-- Discovery: `browser_snapshot_refs`, `browser_find`, `browser_get_accessibility_tree`
-- Actions: `browser_act`, `browser_batch`, `browser_click_ref`, `browser_fill_ref`
-- Verification: `browser_assert`, `browser_screenshot`, `browser_visual_diff`
-- Diagnostics: `browser_get_console_logs`, `browser_get_network_logs`, `browser_debug_bundle`
-
-If the host namespaces MCP tools, use names like `mcp__gsd-browser__browser_snapshot_refs`.
-
-## CLI Fallback
-
-The daemon starts automatically on first browser command.
-
-```bash
-gsd-browser navigate http://localhost:3000
-gsd-browser snapshot
-gsd-browser click-ref @v1:e1
-gsd-browser wait-for --condition network_idle
-gsd-browser assert --checks '[{"kind":"url_contains","text":"dashboard"}]'
-gsd-browser screenshot --output /tmp/gsd-browser-uat.png --format png
-```
-
-After any navigation, submit, or dynamic DOM change, take a fresh snapshot before using refs again. Refs are versioned, such as `@v1:e1` and `@v2:e3`, and old refs can become stale.
-
-Use `--json` when parsing output programmatically. Use named sessions for parallel or project-specific work:
-
-```bash
-gsd-browser --session gsd-pi navigate http://localhost:3000
-```