gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.710c06e97

package/src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts

@@ -1,3 +1,5 @@
+// GSD-2 + src/resources/extensions/gsd/bootstrap/agent-end-recovery.ts - Handles provider and agent-end recovery for GSD auto-mode.
+
 import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
 
 import { logWarning } from "../workflow-logger.js";
@@ -12,7 +14,7 @@ import { clearPathCache } from "../paths.js";
 import { getAutoDashboardData, getAutoModeStartModel, isAutoActive, pauseAuto, setCurrentDispatchedModelId } from "../auto.js";
 import { getNextFallbackModel, resolveModelWithFallbacksForUnit } from "../preferences.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
-import { isSessionSwitchInFlight, resolveAgentEnd } from "../auto/resolve.js";
+import { isSessionSwitchInFlight, resolveAgentEnd, resolveAgentEndCancelled } from "../auto/resolve.js";
 import { resolveModelId } from "../auto-model-selection.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
@@ -56,6 +58,24 @@ function resolveAgentEndBasePath(): string | undefined {
   }
 }
 
+export function _buildAbortedPauseContext(lastMsg: { errorMessage?: unknown }): {
+  message: string;
+  category: "aborted";
+  isTransient: true;
+} {
+  const hasErrorMessage = Object.prototype.hasOwnProperty.call(lastMsg, "errorMessage") && !!lastMsg.errorMessage;
+  return {
+    message: hasErrorMessage ? String(lastMsg.errorMessage) : "Operation aborted",
+    category: "aborted",
+    isTransient: true,
+  };
+}
+
+export function isUserInitiatedAbortMessage(message: string | undefined | null): boolean {
+  if (!message) return false;
+  return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -159,7 +179,7 @@ export async function handleAgentEnd(
       return;
     }
 
-    await pauseAuto(ctx, pi);
+    await pauseAuto(ctx, pi, _buildAbortedPauseContext(lastMsg as { errorMessage?: unknown }));
     return;
   }
   if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {
@@ -167,6 +187,14 @@ export async function handleAgentEnd(
     // is in the assistant message text content. Fall back to content when
     // errorMessage looks uninformative.
     const rawErrorMsg = ("errorMessage" in lastMsg && lastMsg.errorMessage) ? String(lastMsg.errorMessage) : "";
+    if (isUserInitiatedAbortMessage(rawErrorMsg)) {
+      resolveAgentEndCancelled({
+        message: rawErrorMsg,
+        category: "aborted",
+        isTransient: false,
+      });
+      return;
+    }
     const isUseless = !rawErrorMsg || /^(success|ok|true|error|unknown)$/i.test(rawErrorMsg.trim());
     // #3588: When errorMessage is uninformative, extract the real error from
     // the assistant message text content for display purposes only.

package/src/resources/extensions/gsd/bootstrap/db-tools.ts

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Registers DB-backed GSD workflow tools and compatibility aliases.
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";
 import { Text } from "@gsd/pi-tui";
@@ -8,6 +10,7 @@ import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
 import { getErrorMessage } from "../error-utils.js";
+import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 
 async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow-tool-executors.js")> {
   return import("../tools/workflow-tool-executors.js");
@@ -19,11 +22,19 @@ async function loadWorkflowExecutors(): Promise<typeof import("../tools/workflow
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but typing it fully requires generics
 function registerAlias(pi: ExtensionAPI, toolDef: any, aliasName: string, canonicalName: string): void {
+  const execute = typeof toolDef.execute === "function"
+    ? async (...args: any[]) => {
+        incrementLegacyTelemetry("legacy.mcpAliasUsed");
+        return toolDef.execute(...args);
+      }
+    : toolDef.execute;
+
   pi.registerTool({
     ...toolDef,
     name: aliasName,
     description: toolDef.description + ` (alias for ${canonicalName} — prefer the canonical name)`,
     promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
+    execute,
   });
 }
 

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -7,7 +7,7 @@ import type { GSDEcosystemBeforeAgentStartHandler } from "../ecosystem/gsd-exten
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, shouldBlockWorktreeWrite, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -22,6 +22,7 @@ import { logWarning as safetyLogWarning } from "../workflow-logger.js";
 import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
+import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 
@@ -64,6 +65,16 @@ async function applyDisabledModelProviderPolicy(ctx: ExtensionContext): Promise<
   }
 }
 
+export function resolveNotificationStoreBasePath(cwd: string = process.cwd()): string {
+  return resolveWorktreeProjectRoot(cwd);
+}
+
+function initSessionNotifications(ctx: ExtensionContext): void {
+  initNotificationStore(resolveNotificationStoreBasePath());
+  installNotifyInterceptor(ctx);
+  initNotificationWidget(ctx);
+}
+
 async function writeContextModeCompactionSnapshot(basePath: string): Promise<void> {
   try {
     const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -101,9 +112,7 @@ export function registerHooks(
   ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
 ): void {
   pi.on("session_start", async (_event, ctx) => {
-    initNotificationStore(process.cwd());
-    installNotifyInterceptor(ctx);
-    initNotificationWidget(ctx);
+    initSessionNotifications(ctx);
     if (!isAutoActive()) {
       const { initHealthWidget } = await import("../health-widget.js");
       initHealthWidget(ctx);
@@ -156,8 +165,7 @@ export function registerHooks(
   });
 
   pi.on("session_switch", async (_event, ctx) => {
-    initNotificationStore(process.cwd());
-    installNotifyInterceptor(ctx);
+    initSessionNotifications(ctx);
     resetWriteGateState(process.cwd());
     resetToolCallLoopGuard();
     await resetAskUserQuestionsTurnCache();
@@ -474,6 +482,22 @@ export function registerHooks(
       }
     }
 
+    // ── Worktree-isolation write gate (#5199) ────────────────────────────
+    // Block planning-write tools from landing code at the project root when
+    // git.isolation=worktree but auto-mode hasn't created the milestone
+    // worktree yet. Without this, writes silently orphan outside git history.
+    if (isToolCallEventType("write", event) || isToolCallEventType("edit", event)) {
+      const wtBasePath = resolveWorktreeProjectRoot(dash.basePath ?? discussionBasePath);
+      const wtGuard = shouldBlockWorktreeWrite(
+        event.toolName,
+        event.input.path,
+        wtBasePath,
+        isAutoActive(),
+        dash.currentUnit?.type,
+      );
+      if (wtGuard.block) return wtGuard;
+    }
+
     // ── Single-writer engine: block direct writes to STATE.md ──────────
     // Covers write, edit, and bash tools to prevent bypass vectors.
     if (isToolCallEventType("write", event)) {

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -1,10 +1,12 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 
 import { minimatch } from "minimatch";
 
+import { getIsolationMode } from "../preferences.js";
 import type { ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
+import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 
 /**
  * Regex matching milestone CONTEXT.md file names in both legacy M001
@@ -882,3 +884,135 @@ export function shouldBlockPlanningUnit(
   // avoids breaking gsd_* MCP tools or future safe additions.
   return { block: false };
 }
+
+// ─── Worktree isolation write gate (#5199) ────────────────────────────────
+//
+// When `git.isolation: worktree` is configured, the per-unit commit pipeline
+// only runs inside the auto-mode loop (`auto-post-unit.ts`). If the LLM
+// authors code at the project root before auto-mode is started, those writes
+// land in the working tree but never reach a commit — they're silently
+// orphaned outside git history. This guard blocks those writes at the
+// tool_call seam so the agent receives a clear error instead.
+
+const WORKTREE_GATE_BOOTSTRAP_UNITS = new Set([
+  "discuss-milestone",
+  "plan-milestone",
+  "init",
+]);
+
+function realpathOrResolve(p: string): string {
+  const abs = resolve(p);
+  try {
+    return realpathSync(abs);
+  } catch {
+    // Path doesn't exist (yet) — realpath the deepest existing ancestor so
+    // platforms where /tmp -> /private/tmp don't break containment checks.
+    let dir = abs;
+    const tail: string[] = [];
+    while (dir && dir !== resolve(dir, "..")) {
+      try {
+        const real = realpathSync(dir);
+        return tail.length ? join(real, ...tail.reverse()) : real;
+      } catch {
+        const idx = dir.lastIndexOf(sep);
+        if (idx <= 0) break;
+        tail.push(dir.slice(idx + 1));
+        dir = dir.slice(0, idx) || sep;
+      }
+    }
+    return abs;
+  }
+}
+
+function isPathContained(target: string, container: string): boolean {
+  if (target === container) return true;
+  return target.startsWith(container.endsWith(sep) ? container : container + sep);
+}
+
+/**
+ * Block planning-write tool calls that would land code at the project root
+ * while `git.isolation: worktree` is in effect and auto-mode hasn't created
+ * (or flipped cwd into) the milestone worktree.
+ *
+ * Pure / unit-testable. Callers in `register-hooks.ts` supply the resolved
+ * project root and current auto liveness; this function does no I/O beyond
+ * realpath resolution.
+ *
+ * Allow rules (in order):
+ *   1. Tool isn't a planning-write (write/edit/multi_edit/notebook_edit).
+ *   2. `GSD_DISABLE_WORKTREE_WRITE_GUARD=1` self-hosting bypass.
+ *   3. Isolation mode is not "worktree".
+ *   4. Active unit is a bootstrap unit (discuss-milestone/plan-milestone/init).
+ *   5. Target is inside `<projectRoot>/.gsd/worktrees/` (a real worktree).
+ *   6. Target is inside `<projectRoot>/.gsd/` and isn't masquerading as a
+ *      worktrees sibling (rejects the `.gsd/worktrees-extra/…` prefix trick).
+ *   7. Auto is live AND `effectiveBasePath` is itself a `.gsd/worktrees/…` path.
+ *
+ * Otherwise: block with a message that points the agent at `/gsd` to start
+ * auto-mode.
+ */
+export function shouldBlockWorktreeWrite(
+  toolName: string,
+  targetPath: string,
+  effectiveBasePath: string,
+  isAutoLive: boolean,
+  currentUnitType?: string | null,
+): { block: boolean; reason?: string } {
+  const tool = canonicalToolName(toolName);
+  if (!PLANNING_WRITE_TOOLS.has(tool)) return { block: false };
+  if (process.env.GSD_DISABLE_WORKTREE_WRITE_GUARD === "1") return { block: false };
+  if (getIsolationMode(effectiveBasePath) !== "worktree") return { block: false };
+  if (currentUnitType && WORKTREE_GATE_BOOTSTRAP_UNITS.has(currentUnitType)) return { block: false };
+
+  if (!targetPath) {
+    return {
+      block: true,
+      reason: [
+        `HARD BLOCK: ${tool} called with empty path while \`git.isolation: worktree\` is configured`,
+        `and auto-mode is not active. Refusing to allow writes that cannot be located.`,
+      ].join(" "),
+    };
+  }
+
+  // Resolve the target relative to the project root, then realpath to defeat
+  // symlink-based escapes and prefix tricks (e.g. .gsd/worktrees-extra/).
+  const projectRoot = resolveWorktreeProjectRoot(effectiveBasePath);
+  const absTarget = isAbsolute(targetPath) ? targetPath : resolve(projectRoot, targetPath);
+  const realTarget = realpathOrResolve(absTarget);
+  const realRoot = realpathOrResolve(projectRoot);
+  const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));
+  const realWorktreesDir = realpathOrResolve(join(projectRoot, ".gsd", "worktrees"));
+
+  // Allow writes inside the legitimate worktrees subtree.
+  if (isPathContained(realTarget, realWorktreesDir)) return { block: false };
+
+  // Allow writes to .gsd/ planning artifacts, but reject siblings whose name
+  // starts with "worktrees" (the worktrees-extra prefix trick — case 4).
+  if (isPathContained(realTarget, realGsd)) {
+    const rel = relative(realGsd, realTarget);
+    const firstSeg = rel.split(/[\/\\]/)[0] ?? "";
+    if (!firstSeg.startsWith("worktrees")) return { block: false };
+    // fall through: looks like worktrees<something> sibling — block
+  }
+
+  // Auto is live and the caller is operating inside a worktree path —
+  // host tool's write happens in worktree context; let it through.
+  if (isAutoLive && isGsdWorktreePath(effectiveBasePath)) return { block: false };
+
+  // Block. Provide enough context that the agent can self-correct.
+  const displayTarget = isPathContained(realTarget, realRoot)
+    ? relative(realRoot, realTarget) || "."
+    : realTarget;
+  return {
+    block: true,
+    reason: [
+      `HARD BLOCK: Worktree isolation is configured (\`git.isolation: worktree\`) but auto-mode is`,
+      `not running and the target "${displayTarget}" is not inside \`.gsd/worktrees/<MID>/\`.`,
+      `Code edits at the project root would be lost — only the auto-mode commit pipeline`,
+      `(auto-post-unit) commits work, and it never runs outside the loop.`,
+      `Required action: start auto-mode with \`/gsd\` so the milestone worktree is created,`,
+      `then write inside it. To disable this guard for self-hosting development, set`,
+      `GSD_DISABLE_WORKTREE_WRITE_GUARD=1.`,
+    ].join(" "),
+  };
+}

package/src/resources/extensions/gsd/commands-ship.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Ship command for creating pull requests from GSD milestone evidence.
+
 /**
  * GSD Command — /gsd ship
  *
@@ -18,6 +21,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter, type Verdict } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { buildPrEvidence } from "./pr-evidence.js";
 
 function git(basePath: string, args: readonly string[]): string {
   return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
@@ -32,11 +36,6 @@ function isValidRefName(name: string): boolean {
   }
 }
 
-interface PRContent {
-  title: string;
-  body: string;
-}
-
 function listSliceIds(basePath: string, milestoneId: string): string[] {
   // Slices live at <milestoneDir>/slices/<sliceId>/ with canonical S\d+ IDs.
   // Use resolveSlicePath with a probe to find the real slices directory root.
@@ -148,74 +147,48 @@ export async function checkSliceEvalReview(
   };
 }
 
-function generatePRContent(basePath: string, milestoneId: string, milestoneTitle: string): PRContent {
-  const title = `feat: ${milestoneTitle || milestoneId}`;
-
-  const sections: string[] = [];
-
-  // TL;DR
-  sections.push("## TL;DR\n");
-  sections.push(`**What:** Ship milestone ${milestoneId} — ${milestoneTitle || "(untitled)"}`);
-  sections.push(`**Why:** Milestone work complete, ready for review.`);
-  sections.push(`**How:** See slice summaries below.\n`);
-
-  // What — slice summaries
+function generatePRContent(basePath: string, milestoneId: string, milestoneTitle: string) {
   const summaries = collectSliceSummaries(basePath, milestoneId);
-  if (summaries.length > 0) {
-    sections.push("## What\n");
-    sections.push(summaries.join("\n\n"));
-    sections.push("");
-  }
-
-  // Roadmap status
+  const roadmapItems: string[] = [];
   const roadmapPath = resolveMilestoneFile(basePath, milestoneId, "ROADMAP");
   if (roadmapPath && existsSync(roadmapPath)) {
     try {
       const roadmap = readFileSync(roadmapPath, "utf-8");
       const checkboxLines = roadmap.split("\n").filter((l) => /^\s*-\s*\[[ x]\]/.test(l));
-      if (checkboxLines.length > 0) {
-        sections.push("## Roadmap\n");
-        sections.push(checkboxLines.join("\n"));
-        sections.push("");
-      }
+      roadmapItems.push(...checkboxLines);
     } catch {
       // non-fatal
     }
   }
 
-  // Metrics
+  const metrics: string[] = [];
   const ledger = getLedger();
   const units = ledger?.units ?? loadLedgerFromDisk(basePath)?.units ?? [];
   if (units.length > 0) {
     const totals = getProjectTotals(units);
     const byModel = aggregateByModel(units);
-    sections.push("## Metrics\n");
-    sections.push(`- **Units executed:** ${units.length}`);
-    sections.push(`- **Total cost:** ${formatCost(totals.cost)}`);
-    sections.push(`- **Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
+    metrics.push(`**Units executed:** ${units.length}`);
+    metrics.push(`**Total cost:** ${formatCost(totals.cost)}`);
+    metrics.push(`**Tokens:** ${formatTokenCount(totals.tokens.input)} input / ${formatTokenCount(totals.tokens.output)} output`);
     if (totals.duration > 0) {
-      sections.push(`- **Duration:** ${formatDuration(totals.duration)}`);
+      metrics.push(`**Duration:** ${formatDuration(totals.duration)}`);
     }
     if (byModel.length > 0) {
-      sections.push(`- **Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
+      metrics.push(`**Models:** ${byModel.map((m) => `${m.model} (${m.units} units)`).join(", ")}`);
     }
-    sections.push("");
   }
 
-  // Change type checklist
-  sections.push("## Change type\n");
-  sections.push("- [x] `feat` — New feature or capability");
-  sections.push("- [ ] `fix` — Bug fix");
-  sections.push("- [ ] `refactor` — Code restructuring");
-  sections.push("- [ ] `test` — Adding or updating tests");
-  sections.push("- [ ] `docs` — Documentation only");
-  sections.push("- [ ] `chore` — Build, CI, or tooling changes\n");
-
-  // AI disclosure
-  sections.push("---\n");
-  sections.push("*This PR was prepared with AI assistance (GSD auto-mode).*");
-
-  return { title, body: sections.join("\n") };
+  return buildPrEvidence({
+    milestoneId,
+    milestoneTitle,
+    changeType: "feat",
+    summaries,
+    roadmapItems,
+    metrics,
+    testsRun: ["Run `npm run verify:pr` before marking this PR ready."],
+    rollbackNotes: ["Revert the merge commit or close the PR before merge if review finds a regression."],
+    how: "Generated from GSD milestone slice summaries, roadmap status, and local metrics.",
+  });
 }
 
 export async function handleShip(

package/src/resources/extensions/gsd/commands-workflow-templates.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Workflow template commands for starting, listing, and dispatching workflows.
+
 /**
  * GSD Workflow Template Commands — /gsd start, /gsd templates
  *
@@ -15,6 +18,7 @@ import {
   getTemplateInfo,
   loadWorkflowTemplate,
   loadRegistry,
+  isLegacyWorkflowMode,
   type TemplateMatch,
 } from "./workflow-templates.js";
 import { loadPrompt } from "./prompt-loader.js";
@@ -24,6 +28,8 @@ import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin, type WorkflowPlugin } from "./workflow-plugins.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { formatRecommendedProcessPaths } from "./process-task-path.js";
+import { incrementLegacyTelemetry } from "./legacy-telemetry.js";
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
@@ -328,6 +334,9 @@ export async function handleStart(
         "  /gsd start bugfix fix login button not responding\n" +
         "  /gsd start spike evaluate auth libraries\n" +
         "  /gsd start hotfix critical: API returns 500\n\n" +
+        "Recommended task paths:\n" +
+        formatRecommendedProcessPaths() +
+        "\n\n" +
         "Flags:\n" +
         "  --dry-run       Preview what would happen without executing\n" +
         "  --issue <ref>   Link to a GitHub issue\n\n" +
@@ -484,6 +493,9 @@ export async function handleStart(
   if (artifactDir) infoLines.push(`Artifacts: ${artifactDir}`);
   infoLines.push(`Branch: ${actualBranch}`);
   ctx.ui.notify(infoLines.join("\n"), "info");
+  if (isLegacyWorkflowMode(template.mode)) {
+    incrementLegacyTelemetry("legacy.workflowEngineUsed");
+  }
 
   const prompt = loadPrompt("workflow-start", {
     templateId,
@@ -649,6 +661,7 @@ export function dispatchMarkdownPhasePlugin(
   if (artifactDir) infoLines.push(`Artifacts: ${artifactDir}`);
   infoLines.push(`Branch: ${actualBranch}`);
   ctx.ui.notify(infoLines.join("\n"), "info");
+  incrementLegacyTelemetry("legacy.workflowEngineUsed");
 
   const prompt = loadPrompt("workflow-start", {
     templateId,

package/src/resources/extensions/gsd/component-loader.ts

@@ -1,19 +1,11 @@
-/**
- * Component Loader
- *
- * Multi-format loader that handles:
- * 1. New format: component.yaml + SKILL.md/AGENT.md
- * 2. Legacy skill format: SKILL.md with YAML frontmatter
- * 3. Legacy agent format: .md with YAML frontmatter (name, description, tools, model)
- *
- * Auto-detects format by checking for component.yaml first, then falling back
- * to legacy formats based on file naming conventions.
- */
+// Project/App: GSD-2
+// File Purpose: Loads modern component.yaml definitions and legacy skill/agent formats.
 
 import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, dirname, join } from 'node:path';
 import { parse as parseYaml } from 'yaml';
 import { parseFrontmatter } from '@gsd/pi-coding-agent';
+import { incrementLegacyTelemetry } from './legacy-telemetry.js';
 import type {
 	Component,
 	ComponentApiVersion,
@@ -270,6 +262,7 @@ function loadFromLegacySkill(
 		enabled: true,
 	};
 
+	incrementLegacyTelemetry('legacy.componentFormatUsed');
 	return { component, diagnostics };
 }
 
@@ -345,6 +338,7 @@ function loadFromLegacyAgent(
 		enabled: true,
 	};
 
+	incrementLegacyTelemetry('legacy.componentFormatUsed');
 	return { component, diagnostics };
 }
 

package/src/resources/extensions/gsd/custom-workflow-engine.ts

@@ -29,6 +29,7 @@ import {
   markStepActive,
   markStepComplete,
   expandIteration,
+  isTerminalStepStatus,
   type WorkflowGraph,
 } from "./graph.js";
 import { injectContext } from "./context-injector.js";
@@ -40,6 +41,24 @@ import { withFileLock } from "./file-lock.js";
 // Re-export for downstream consumers
 export { readFrozenDefinition } from "./definition-io.js";
 
+function formatBlockedWorkflowReason(graph: WorkflowGraph): string {
+  const statusById = new Map(graph.steps.map((step) => [step.id, step.status]));
+  const blockedSteps = graph.steps
+    .filter((step) => step.status === "pending")
+    .map((step) => {
+      const blockers = step.dependsOn
+        .filter((depId) => !isTerminalStepStatus(statusById.get(depId)))
+        .map((depId) => `${depId} (${statusById.get(depId) ?? "missing"})`);
+      return blockers.length > 0
+        ? `${step.id} waiting on ${blockers.join(", ")}`
+        : `${step.id} has no runnable dependency path`;
+    });
+
+  return blockedSteps.length > 0
+    ? `Workflow blocked: no pending steps are ready. Blocked steps: ${blockedSteps.join("; ")}`
+    : "Workflow blocked: no pending steps are ready.";
+}
+
 export class CustomWorkflowEngine implements WorkflowEngine {
   readonly engineId = "custom";
   private readonly runDir: string;
@@ -110,6 +129,16 @@ export class CustomWorkflowEngine implements WorkflowEngine {
       let next = getNextPendingStep(graph);
 
       if (!next) {
+        const allDone = graph.steps.every(
+          (step) => step.status === "complete" || step.status === "expanded",
+        );
+        if (!allDone) {
+          return {
+            action: "stop",
+            reason: formatBlockedWorkflowReason(graph),
+            level: "error",
+          };
+        }
         return {
           action: "stop",
           reason: "All steps complete",

package/src/resources/extensions/gsd/db-adapter.ts

@@ -0,0 +1,75 @@
+// Project/App: GSD-2
+// File Purpose: Normalized SQLite adapter wrapper used by the GSD database facade.
+
+export interface DbStatement {
+  run(...params: unknown[]): unknown;
+  get(...params: unknown[]): Record<string, unknown> | undefined;
+  all(...params: unknown[]): Record<string, unknown>[];
+}
+
+export interface DbAdapter {
+  exec(sql: string): void;
+  prepare(sql: string): DbStatement;
+  close(): void;
+}
+
+export function normalizeDbRow(row: unknown): Record<string, unknown> | undefined {
+  if (row == null) return undefined;
+  if (Object.getPrototypeOf(row) === null) {
+    return { ...(row as Record<string, unknown>) };
+  }
+  return row as Record<string, unknown>;
+}
+
+export function normalizeDbRows(rows: unknown[]): Record<string, unknown>[] {
+  return rows.map((row) => normalizeDbRow(row)!);
+}
+
+export function createDbAdapter(rawDb: unknown): DbAdapter {
+  const db = rawDb as {
+    exec(sql: string): void;
+    prepare(sql: string): {
+      run(...args: unknown[]): unknown;
+      get(...args: unknown[]): unknown;
+      all(...args: unknown[]): unknown[];
+    };
+    close(): void;
+  };
+
+  const stmtCache = new Map<string, DbStatement>();
+
+  function wrapStmt(raw: {
+    run(...args: unknown[]): unknown;
+    get(...args: unknown[]): unknown;
+    all(...args: unknown[]): unknown[];
+  }): DbStatement {
+    return {
+      run(...params: unknown[]): unknown {
+        return raw.run(...params);
+      },
+      get(...params: unknown[]): Record<string, unknown> | undefined {
+        return normalizeDbRow(raw.get(...params));
+      },
+      all(...params: unknown[]): Record<string, unknown>[] {
+        return normalizeDbRows(raw.all(...params));
+      },
+    };
+  }
+
+  return {
+    exec(sql: string): void {
+      db.exec(sql);
+    },
+    prepare(sql: string): DbStatement {
+      let cached = stmtCache.get(sql);
+      if (cached) return cached;
+      cached = wrapStmt(db.prepare(sql));
+      stmtCache.set(sql, cached);
+      return cached;
+    },
+    close(): void {
+      stmtCache.clear();
+      db.close();
+    },
+  };
+}