gsd-pi 2.79.0 → 2.80.0-dev.b62439b9f

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

@@ -56,6 +56,19 @@ 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,
+  };
+}
+
 async function pauseTransientWithBackoff(
   cls: ErrorClass,
   pi: ExtensionAPI,
@@ -159,7 +172,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") {

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/exec-tools.ts

@@ -1,7 +1,7 @@
 // GSD2 — Exec (context-mode) tool registration.
 //
-// Exposes the `gsd_exec` tool over MCP. Opt-in: disabled unless
-// `context_mode.enabled: true` is set in preferences.
+// Exposes the Context Mode runtime tools in-process. Default-on; opt out with
+// `context_mode.enabled: false` in preferences.
 
 import { Type } from "@sinclair/typebox";
 import type { ExtensionAPI } from "@gsd/pi-coding-agent";

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

@@ -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,14 +65,54 @@ 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");
+    const { isContextModeEnabled } = await import("../preferences-types.js");
+    const prefs = loadEffectiveGSDPreferences(basePath);
+    if (!isContextModeEnabled(prefs?.preferences)) return;
+
+    const { writeCompactionSnapshot } = await import("../compaction-snapshot.js");
+    const { ensureDbOpen } = await import("./dynamic-tools.js");
+    await ensureDbOpen(basePath);
+
+    let activeContext: string | null = null;
+    try {
+      const state = await deriveGsdState(basePath);
+      if (state.activeMilestone && state.activeSlice && state.activeTask) {
+        activeContext =
+          `Active: ${state.activeMilestone.id} / ${state.activeSlice.id} / ${state.activeTask.id}` +
+          (state.activeTask.title ? ` - ${state.activeTask.title}` : "");
+      }
+    } catch {
+      /* non-fatal */
+    }
+
+    writeCompactionSnapshot(basePath, { activeContext });
+  } catch (err) {
+    safetyLogWarning(
+      "context-mode",
+      `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+}
+
 export function registerHooks(
   pi: ExtensionAPI,
   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);
@@ -124,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();
@@ -156,7 +196,7 @@ export function registerHooks(
     await getEcosystemReadyPromise();
 
     const beforeAgentBasePath = process.cwd();
-    const pendingApprovalGate = getPendingGate();
+    const pendingApprovalGate = getPendingGate(beforeAgentBasePath);
     if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
       markApprovalGateVerified(pendingApprovalGate, beforeAgentBasePath);
       const milestoneId = extractDepthVerificationMilestoneId(pendingApprovalGate);
@@ -229,15 +269,19 @@ export function registerHooks(
   });
 
   pi.on("session_before_compact", async () => {
+    const basePath = process.cwd();
+    // Context Mode is default-on. Write the resumable snapshot before any
+    // active-auto cancel return so auto sessions still leave re-entry context.
+    await writeContextModeCompactionSnapshot(basePath);
+
     // Only cancel compaction while auto-mode is actively running.
     // Paused auto-mode should allow compaction — the user may be doing
     // interactive work (#3165).
     if (isAutoActive()) {
       return { cancel: true };
     }
-    const basePath = process.cwd();
     const { ensureDbOpen } = await import("./dynamic-tools.js");
-    await ensureDbOpen();
+    await ensureDbOpen(basePath);
     const state = await deriveGsdState(basePath);
     if (!state.activeMilestone || !state.activeSlice) return;
     // Write checkpoint for ALL phases, not just "executing" — discuss, research,
@@ -282,42 +326,6 @@ export function registerHooks(
     }));
   });
 
-  // Context-mode snapshot: write .gsd/last-snapshot.md before compaction so
-  // agents can call gsd_resume (or Read the file) to re-orient. Opt-in via
-  // preferences.context_mode.enabled. Runs after the auto-cancel handler
-  // above — if that one returned cancel:true, pi still fires us but the
-  // compaction won't actually happen; the snapshot is still useful then,
-  // since auto may pause and resume later.
-  pi.on("session_before_compact", async () => {
-    try {
-      const { loadEffectiveGSDPreferences } = await import("../preferences.js");
-      const { isContextModeEnabled } = await import("../preferences-types.js");
-      const prefs = loadEffectiveGSDPreferences();
-      if (!isContextModeEnabled(prefs?.preferences)) return;
-      const { writeCompactionSnapshot } = await import("../compaction-snapshot.js");
-      const { ensureDbOpen } = await import("./dynamic-tools.js");
-      await ensureDbOpen();
-      const basePath = process.cwd();
-      let activeContext: string | null = null;
-      try {
-        const state = await deriveGsdState(basePath);
-        if (state.activeMilestone && state.activeSlice && state.activeTask) {
-          activeContext =
-            `Active: ${state.activeMilestone.id} / ${state.activeSlice.id} / ${state.activeTask.id}` +
-            (state.activeTask.title ? ` — ${state.activeTask.title}` : "");
-        }
-      } catch {
-        /* non-fatal */
-      }
-      writeCompactionSnapshot(basePath, { activeContext });
-    } catch (err) {
-      safetyLogWarning(
-        "context-mode",
-        `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-  });
-
   pi.on("message_update", async (event, ctx: ExtensionContext) => {
     if (approvalQuestionAbortInFlight) return;
 
@@ -401,20 +409,22 @@ export function registerHooks(
     // ── Discussion gate enforcement: block tool calls while gate is pending ──
     // If ask_user_questions was called with a gate ID but hasn't been confirmed,
     // block all non-read-only tool calls to prevent the model from skipping gates.
-    if (getPendingGate()) {
+    if (getPendingGate(discussionBasePath)) {
       const milestoneId = await getDiscussionMilestoneIdFor(discussionBasePath);
       if (isToolCallEventType("bash", event)) {
         const bashGuard = shouldBlockPendingGateBash(
           event.input.command,
           milestoneId,
-          isQueuePhaseActive(),
+          isQueuePhaseActive(discussionBasePath),
+          discussionBasePath,
         );
         if (bashGuard.block) return bashGuard;
       } else {
         const gateGuard = shouldBlockPendingGate(
           toolName,
           milestoneId,
-          isQueuePhaseActive(),
+          isQueuePhaseActive(discussionBasePath),
+          discussionBasePath,
         );
         if (gateGuard.block) return gateGuard;
       }
@@ -424,7 +434,7 @@ export function registerHooks(
     // When /gsd queue is active, the agent should only create milestones,
     // not execute work. Block write/edit to non-.gsd/ paths and bash commands
     // that would modify files.
-    if (isQueuePhaseActive()) {
+    if (isQueuePhaseActive(discussionBasePath)) {
       let queueInput = "";
       if (isToolCallEventType("write", event)) {
         queueInput = event.input.path;
@@ -498,7 +508,8 @@ export function registerHooks(
       event.toolName,
       event.input.path,
       await getDiscussionMilestoneIdFor(discussionBasePath),
-      isQueuePhaseActive(),
+      isQueuePhaseActive(discussionBasePath),
+      discussionBasePath,
     );
     if (result.block) return result;
   });
@@ -558,7 +569,7 @@ export function registerHooks(
     if (toolName !== "ask_user_questions") return;
     const basePath = process.cwd();
     const milestoneId = await getDiscussionMilestoneIdFor(basePath);
-    const queueActive = isQueuePhaseActive();
+    const queueActive = isQueuePhaseActive(basePath);
 
     const details = event.details as any;
 
@@ -568,7 +579,7 @@ export function registerHooks(
     // If the user responded at all (even "needs adjustment"), clear the pending gate
     // because the user engaged — the prompt handles the re-ask-after-adjustment flow.
     const questions: any[] = (event.input as any)?.questions ?? [];
-    const currentPendingGate = getPendingGate();
+    const currentPendingGate = getPendingGate(basePath);
     if (currentPendingGate) {
       if (details?.cancelled || !details?.response) {
         // Gate stays pending. Direct the agent to the most reliable recovery

package/src/resources/extensions/gsd/bootstrap/tests/write-gate-shouldblock-basepath.test.ts

@@ -0,0 +1,97 @@
+// GSD-2 write-gate bootstrap — regression tests for basePath threading on
+// shouldBlockContextWrite / shouldBlockPendingGate (R1).
+//
+// The underlying bug: readers defaulted to process.cwd() and so missed the
+// per-basePath state Map entry written by markDepthVerified(..., baseDirA)
+// when cwd had drifted to baseDirB. With basePath threaded explicitly to
+// the readers, the depth-gate sees the verified state regardless of cwd.
+
+import { test, describe, before, after } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  markDepthVerified,
+  setPendingGate,
+  shouldBlockContextWrite,
+  shouldBlockPendingGate,
+  clearDiscussionFlowState,
+} from "../write-gate.js";
+
+function makeTempDir(): string {
+  return mkdtempSync(join(tmpdir(), "wg-shouldblock-basepath-"));
+}
+
+let originalCwd: string;
+before(() => {
+  originalCwd = process.cwd();
+});
+after(() => {
+  if (process.cwd() !== originalCwd) {
+    process.chdir(originalCwd);
+  }
+});
+
+describe("write-gate shouldBlock readers respect explicit basePath", () => {
+  let baseDirA: string;
+  let baseDirB: string;
+  let prevPersist: string | undefined;
+
+  before(() => {
+    baseDirA = makeTempDir();
+    baseDirB = makeTempDir();
+    prevPersist = process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    process.env.GSD_PERSIST_WRITE_GATE_STATE = "1";
+  });
+
+  after(() => {
+    process.chdir(originalCwd);
+    if (prevPersist === undefined) {
+      delete process.env.GSD_PERSIST_WRITE_GATE_STATE;
+    } else {
+      process.env.GSD_PERSIST_WRITE_GATE_STATE = prevPersist;
+    }
+    rmSync(baseDirA, { recursive: true, force: true });
+    rmSync(baseDirB, { recursive: true, force: true });
+  });
+
+  test("shouldBlockContextWrite with explicit basePath sees verified state after cwd drift", () => {
+    clearDiscussionFlowState(baseDirA);
+    clearDiscussionFlowState(baseDirB);
+
+    markDepthVerified("M001", baseDirA);
+    process.chdir(baseDirB);
+
+    const contextPath = join(baseDirA, ".gsd", "milestones", "M001", "M001-CONTEXT.md");
+    const result = shouldBlockContextWrite("write", contextPath, "M001", undefined, baseDirA);
+
+    assert.equal(result.block, false, "explicit basePath should resolve to baseDirA's verified state");
+  });
+
+  test("shouldBlockContextWrite without basePath defaults to cwd and misses verified state (bug repro)", () => {
+    clearDiscussionFlowState(baseDirA);
+    clearDiscussionFlowState(baseDirB);
+
+    markDepthVerified("M001", baseDirA);
+    process.chdir(baseDirB);
+
+    const contextPath = join(baseDirA, ".gsd", "milestones", "M001", "M001-CONTEXT.md");
+    const result = shouldBlockContextWrite("write", contextPath, "M001");
+
+    assert.equal(result.block, true, "default-to-cwd path resolves to baseDirB and misses baseDirA state");
+  });
+
+  test("shouldBlockPendingGate with explicit basePath sees pending gate after cwd drift", () => {
+    clearDiscussionFlowState(baseDirA);
+    clearDiscussionFlowState(baseDirB);
+
+    setPendingGate("depth_verification_M001_confirm", baseDirA);
+    process.chdir(baseDirB);
+
+    const result = shouldBlockPendingGate("write", "M001", false, baseDirA);
+
+    assert.equal(result.block, true, "explicit basePath should resolve to baseDirA's pending gate state");
+  });
+});

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

@@ -351,8 +351,9 @@ export function shouldBlockPendingGate(
   toolName: string,
   milestoneId: string | null,
   queuePhaseActive?: boolean,
+  basePath: string = process.cwd(),
 ): { block: boolean; reason?: string } {
-  return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive);
+  return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(basePath), toolName, milestoneId, queuePhaseActive);
 }
 
 export function shouldBlockPendingGateInSnapshot(
@@ -386,8 +387,9 @@ export function shouldBlockPendingGateBash(
   command: string,
   milestoneId: string | null,
   queuePhaseActive?: boolean,
+  basePath: string = process.cwd(),
 ): { block: boolean; reason?: string } {
-  return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive);
+  return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(basePath), command, milestoneId, queuePhaseActive);
 }
 
 export function shouldBlockPendingGateBashInSnapshot(
@@ -444,6 +446,7 @@ export function shouldBlockContextWrite(
   inputPath: string,
   milestoneId: string | null,
   _queuePhaseActive?: boolean,
+  basePath: string = process.cwd(),
 ): { block: boolean; reason?: string } {
   if (toolName !== "write") return { block: false };
   if (!MILESTONE_CONTEXT_RE.test(inputPath)) return { block: false };
@@ -460,7 +463,7 @@ export function shouldBlockContextWrite(
     };
   }
 
-  if (isMilestoneDepthVerified(targetMilestoneId)) return { block: false };
+  if (isMilestoneDepthVerified(targetMilestoneId, basePath)) return { block: false };
 
   return {
     block: true,
@@ -483,8 +486,9 @@ export function shouldBlockContextArtifactSave(
   artifactType: string,
   milestoneId: string | null,
   sliceId?: string | null,
+  basePath: string = process.cwd(),
 ): { block: boolean; reason?: string } {
-  return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(), artifactType, milestoneId, sliceId);
+  return shouldBlockContextArtifactSaveInSnapshot(currentWriteGateSnapshot(basePath), artifactType, milestoneId, sliceId);
 }
 
 export function shouldBlockContextArtifactSaveInSnapshot(

package/src/resources/extensions/gsd/commands/context.ts

@@ -65,7 +65,7 @@ export function currentDirectoryRoot(): string {
     try {
       cwd = process.cwd();
     } catch {
-      cwd = process.env.HOME ?? "/";
+      cwd = homedir();
     }
   }
   const result = validateDirectory(cwd);

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 };
 }