gsd-pi 2.79.0-dev.ece5fd8ba → 2.80.0-dev.b62439b9f

package/dist/resources/extensions/gsd/auto.js

@@ -31,7 +31,7 @@ import { selectAndApplyModel, resolveModelId, clearToolBaseline } from "./auto-m
 import { resetRoutingHistory, recordOutcome } from "./routing-history.js";
 import { resetHookState, runPreDispatchHooks, restoreHookState, clearPersistedHookState, } from "./post-unit-hooks.js";
 import { runGSDDoctor, rebuildState } from "./doctor.js";
-import { preDispatchHealthGate, resetProactiveHealing, setLevelChangeCallback, } from "./doctor-proactive.js";
+import { preDispatchHealthGate, recordHealthSnapshot, resetProactiveHealing, setLevelChangeCallback, } from "./doctor-proactive.js";
 import { clearSkillSnapshot } from "./skill-discovery.js";
 import { captureAvailableSkills, resetSkillTelemetry, } from "./skill-telemetry.js";
 import { getRtkSessionSavings } from "../shared/rtk-session-stats.js";
@@ -43,7 +43,7 @@ import { isAbsolute, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { atomicWriteSync } from "./atomic-write.js";
-import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, } from "./worktree.js";
+import { autoCommitCurrentBranch, captureIntegrationBranch, detectWorktreeName, getCurrentBranch, getMainBranch, setActiveMilestoneId, resolveProjectRoot, } from "./worktree.js";
 import { GitServiceImpl } from "./git-service.js";
 import { getPriorSliceCompletionBlocker } from "./dispatch-guard.js";
 import { createAutoWorktree, enterAutoWorktree, enterBranchModeForMilestone, teardownAutoWorktree, isInAutoWorktree, getAutoWorktreePath, mergeMilestoneToMain, autoWorktreeBranch, syncWorktreeStateBack, syncProjectRootToWorktree, checkResourcesStale, escapeStaleWorktree, } from "./auto-worktree.js";
@@ -82,6 +82,7 @@ import { resolveAgentEnd, resolveAgentEndCancelled, _resetPendingResolve, isSess
 import { runAutoLoopWithUok } from "./uok/kernel.js";
 import { resolveUokFlags } from "./uok/flags.js";
 import { validateDirectory } from "./validate-directory.js";
+import { createAutoOrchestrator } from "./auto/orchestrator.js";
 import { WorktreeResolver, } from "./worktree-resolver.js";
 import { reorderForCaching } from "./prompt-ordering.js";
 export { STUB_RECOVERY_THRESHOLD, NEW_SESSION_TIMEOUT_MS, } from "./auto/session.js";
@@ -904,6 +905,12 @@ export async function stopAuto(ctx, pi, reason) {
         // changes the user made between sessions (#4959 / CodeRabbit).
         if (pi)
             clearToolBaseline(pi);
+        try {
+            await s.orchestration?.stop(reason ?? "stop");
+        }
+        catch (err) {
+            debugLog("stop-orchestration-stop", { error: err instanceof Error ? err.message : String(err) });
+        }
         // Reset all session state in one call
         s.reset();
     }
@@ -953,6 +960,7 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
             activeRunDir: s.activeRunDir,
             autoStartTime: s.autoStartTime,
             milestoneLock: s.sessionMilestoneLock ?? undefined,
+            pauseReason: _errorContext?.message,
         };
         setRuntimeKv("global", "", PAUSED_SESSION_KV_KEY, pausedMeta);
     }
@@ -992,6 +1000,12 @@ export async function pauseAuto(ctx, _pi, _errorContext) {
     // Unblock pending unitPromise so autoLoop exits cleanly (#1799)
     resolveAgentEnd({ messages: [] });
     _resetPendingResolve();
+    try {
+        await s.orchestration?.stop("pause");
+    }
+    catch (err) {
+        debugLog("pause-orchestration-stop", { error: err instanceof Error ? err.message : String(err) });
+    }
     s.active = false;
     s.paused = true;
     deactivateGSD();
@@ -1041,6 +1055,132 @@ function buildResolverDeps() {
 function buildResolver() {
     return new WorktreeResolver(s, buildResolverDeps());
 }
+/**
+ * Thin entry glue for the new Auto Orchestration module.
+ *
+ * This intentionally wires only dispatch + error notification today, with
+ * no behavior changes to the existing auto loop. It provides a concrete seam
+ * the next refactor steps can adopt incrementally.
+ */
+export function createWiredAutoOrchestrationModule(ctx, _pi, dispatchBasePath, runtimeBasePath = resolveProjectRoot(dispatchBasePath)) {
+    const flowId = `auto-orchestrator-${Date.now()}`;
+    let seq = 0;
+    const deps = {
+        dispatch: {
+            async decideNextUnit() {
+                const state = await deriveState(dispatchBasePath);
+                const active = state.activeMilestone;
+                if (!active)
+                    return null;
+                const prefs = loadEffectiveGSDPreferences(dispatchBasePath)?.preferences;
+                const action = await resolveDispatch({
+                    basePath: dispatchBasePath,
+                    mid: active.id,
+                    midTitle: active.title,
+                    state,
+                    prefs,
+                });
+                if (action.action !== "dispatch")
+                    return null;
+                return {
+                    unitType: action.unitType,
+                    unitId: action.unitId,
+                    reason: action.matchedRule ?? "dispatch",
+                    preconditions: [],
+                };
+            },
+        },
+        recovery: {
+            async classifyAndRecover(input) {
+                const reason = input.error instanceof Error ? input.error.message : String(input.error ?? "unknown auto error");
+                return { action: "escalate", reason };
+            },
+        },
+        worktree: {
+            async prepareForUnit() { },
+            async syncAfterUnit() { },
+            async cleanupOnStop() { },
+        },
+        health: {
+            async preAdvanceGate() {
+                const gate = await preDispatchHealthGate(dispatchBasePath);
+                return {
+                    allow: gate.proceed,
+                    reason: gate.reason,
+                };
+            },
+            async postAdvanceRecord(result) {
+                if (result.kind === "error") {
+                    recordHealthSnapshot(1, 0, 0, [{
+                            code: "orchestration-error",
+                            message: result.reason ?? "orchestration error",
+                            severity: "error",
+                            unitId: "orchestration",
+                        }], [], "orchestration");
+                }
+                else if (result.kind === "blocked") {
+                    recordHealthSnapshot(0, 1, 0, [{
+                            code: "orchestration-blocked",
+                            message: result.reason ?? "orchestration blocked",
+                            severity: "warning",
+                            unitId: "orchestration",
+                        }], [], "orchestration");
+                }
+            },
+        },
+        runtime: {
+            async ensureLockOwnership() {
+                const status = getSessionLockStatus(runtimeBasePath);
+                if (!status.valid || status.failureReason === "pid-mismatch") {
+                    throw new Error("session lock held by another process");
+                }
+            },
+            async journalTransition(event) {
+                const eventType = event.name === "start"
+                    ? "iteration-start"
+                    : event.name === "resume"
+                        ? "iteration-start"
+                        : event.name === "advance"
+                            ? "dispatch-match"
+                            : event.name === "advance-blocked"
+                                ? "guard-block"
+                                : event.name === "advance-stopped"
+                                    ? "dispatch-stop"
+                                    : event.name === "advance-error"
+                                        ? "iteration-end"
+                                        : event.name === "advance-paused" || event.name === "advance-retry"
+                                            ? "guard-block"
+                                            : event.name === "stop"
+                                                ? "terminal"
+                                                : "iteration-end";
+                _emitJournalEvent(runtimeBasePath, {
+                    ts: new Date().toISOString(),
+                    flowId,
+                    seq: ++seq,
+                    eventType,
+                    data: {
+                        source: "auto-orchestrator",
+                        name: event.name,
+                        reason: event.reason,
+                        unitType: event.unitType,
+                        unitId: event.unitId,
+                    },
+                });
+            },
+        },
+        notifications: {
+            async notifyLifecycle(event) {
+                if (event.name === "error") {
+                    ctx.ui.notify(event.detail ?? "auto orchestration error", "error");
+                }
+            },
+        },
+    };
+    return createAutoOrchestrator(deps);
+}
+function ensureOrchestrationModule(ctx, pi, basePath) {
+    s.orchestration = createWiredAutoOrchestrationModule(ctx, pi, basePath, lockBase());
+}
 /**
  * Build the LoopDeps object from auto.ts private scope.
  * This bundles all private functions that autoLoop needs without exporting them.
@@ -1398,6 +1538,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             // s.basePath may have been updated to a worktree path by enterMilestone.
             rebuildScope(s.basePath, s.currentMilestoneId);
         }
+        ensureOrchestrationModule(ctx, pi, s.basePath || base);
         registerSigtermHandler(lockBase());
         ctx.ui.setStatus("gsd-auto", s.stepMode ? "next" : "auto");
         ctx.ui.setWidget("gsd-health", undefined);
@@ -1406,15 +1547,15 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         // Re-sync managed resources on resume so long-lived auto sessions pick up
         // bundled extension updates before resume-time verification/state logic runs.
         // GSD_PKG_ROOT is set by loader.ts and points to the gsd-pi package root.
-        // The relative import ("../../../resource-loader.js") only works from the source
+        // The relative import ("../../../resource-runtime/resource-loader.js") only works from the source
         // tree; deployed extensions live at ~/.gsd/agent/extensions/gsd/ where the
         // relative path resolves to ~/.gsd/agent/resource-loader.js which doesn't exist.
         // Using GSD_PKG_ROOT constructs a correct absolute path in both contexts (#3949).
         const agentDir = process.env.GSD_CODING_AGENT_DIR || join(gsdHome(), "agent");
         const pkgRoot = process.env.GSD_PKG_ROOT;
         const resourceLoaderPath = pkgRoot
-            ? pathToFileURL(join(pkgRoot, "dist", "resource-loader.js")).href
-            : new URL("../../../resource-loader.js", import.meta.url).href;
+            ? pathToFileURL(join(pkgRoot, "dist", "resource-runtime", "resource-loader.js")).href
+            : new URL("../../../resource-runtime/resource-loader.js", import.meta.url).href;
         const { initResources } = await import(resourceLoaderPath);
         initResources(agentDir);
         // Open the project DB before rebuild/derive so resume uses DB-backed
@@ -1457,6 +1598,12 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
             clearPausedSession("paused-session DB cleanup failed (resume activation)");
         }
         pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: s.stepMode ? "Step-mode resumed." : "Auto-mode resumed.", level: "progress" });
+        try {
+            await s.orchestration?.resume();
+        }
+        catch (err) {
+            debugLog("resume-orchestration-resume", { error: err instanceof Error ? err.message : String(err) });
+        }
         startAutoCommandPolling(s.basePath);
         await runAutoLoopWithUok({
             ctx,
@@ -1482,6 +1629,7 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
     // Build scope after bootstrap has populated s.basePath / s.originalBasePath /
     // s.currentMilestoneId (including worktree setup inside bootstrapAutoSession).
     rebuildScope(s.basePath, s.currentMilestoneId);
+    ensureOrchestrationModule(ctx, pi, s.basePath || base);
     captureProjectRootEnv(s.originalBasePath || s.basePath);
     registerAutoWorkerForSession(s);
     try {
@@ -1492,6 +1640,12 @@ export async function startAuto(ctx, pi, base, verboseMode, options) {
         logWarning("engine", `cmux sync failed: ${err instanceof Error ? err.message : String(err)}`, { file: "auto.ts" });
     }
     pi.events.emit(CMUX_CHANNELS.LOG, { preferences: loadEffectiveGSDPreferences(s.basePath || undefined)?.preferences, message: requestedStepMode ? "Step-mode started." : "Auto-mode started.", level: "progress" });
+    try {
+        await s.orchestration?.start({ basePath: s.basePath, trigger: "auto-loop" });
+    }
+    catch (err) {
+        debugLog("start-orchestration-start", { error: err instanceof Error ? err.message : String(err) });
+    }
     startAutoCommandPolling(s.basePath);
     // Dispatch the first unit
     await runAutoLoopWithUok({
@@ -1576,6 +1730,9 @@ export async function dispatchHookUnit(ctx, pi, hookName, triggerUnitType, trigg
         s.pendingQuickTasks = [];
     }
     s.basePath = targetBasePath;
+    if (!s.orchestration) {
+        ensureOrchestrationModule(ctx, pi, s.basePath);
+    }
     const hookUnitType = `hook/${hookName}`;
     const hookStartedAt = Date.now();
     s.currentUnit = {

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -39,6 +39,14 @@ function resolveAgentEndBasePath() {
         return undefined;
     }
 }
+export function _buildAbortedPauseContext(lastMsg) {
+    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, pi, ctx, errorDetail, isRateLimit) {
     retryState.consecutiveTransientCount += 1;
     const baseRetryAfterMs = "retryAfterMs" in cls ? cls.retryAfterMs : 15_000;
@@ -134,7 +142,7 @@ export async function handleAgentEnd(pi, event, ctx) {
             }
             return;
         }
-        await pauseAuto(ctx, pi);
+        await pauseAuto(ctx, pi, _buildAbortedPauseContext(lastMsg));
         return;
     }
     if (lastMsg && "stopReason" in lastMsg && lastMsg.stopReason === "error") {

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -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 { Text } from "@gsd/pi-tui";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
@@ -5,6 +7,7 @@ import { ensureDbOpen } from "./dynamic-tools.js";
 import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./write-gate.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
+import { incrementLegacyTelemetry } from "../legacy-telemetry.js";
 async function loadWorkflowExecutors() {
     return import("../tools/workflow-tool-executors.js");
 }
@@ -14,11 +17,18 @@ async function loadWorkflowExecutors() {
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- toolDef shape matches ToolDefinition but typing it fully requires generics
 function registerAlias(pi, toolDef, aliasName, canonicalName) {
+    const execute = typeof toolDef.execute === "function"
+        ? async (...args) => {
+            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,
     });
 }
 function requirementRootWriteGuard(operation) {

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -16,6 +16,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";
 // Skip the welcome screen on the very first session_start — cli.ts already
@@ -51,6 +52,14 @@ async function applyDisabledModelProviderPolicy(ctx) {
         // Non-fatal: keep default provider visibility if preferences cannot be loaded.
     }
 }
+export function resolveNotificationStoreBasePath(cwd = process.cwd()) {
+    return resolveWorktreeProjectRoot(cwd);
+}
+function initSessionNotifications(ctx) {
+    initNotificationStore(resolveNotificationStoreBasePath());
+    installNotifyInterceptor(ctx);
+    initNotificationWidget(ctx);
+}
 async function writeContextModeCompactionSnapshot(basePath) {
     try {
         const { loadEffectiveGSDPreferences } = await import("../preferences.js");
@@ -81,9 +90,7 @@ async function writeContextModeCompactionSnapshot(basePath) {
 }
 export function registerHooks(pi, ecosystemHandlers) {
     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);
@@ -135,8 +142,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
     });
     pi.on("session_switch", async (_event, ctx) => {
-        initNotificationStore(process.cwd());
-        installNotifyInterceptor(ctx);
+        initSessionNotifications(ctx);
         resetWriteGateState(process.cwd());
         resetToolCallLoopGuard();
         await resetAskUserQuestionsTurnCache();

package/dist/resources/extensions/gsd/commands-ship.js

@@ -1,9 +1,5 @@
-/**
- * GSD Command — /gsd ship
- *
- * Creates a PR from milestone artifacts: generates title + body from
- * roadmap, slice summaries, and metrics, then opens via `gh pr create`.
- */
+// Project/App: GSD-2
+// File Purpose: Ship command for creating pull requests from GSD milestone evidence.
 import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { readFile } from "node:fs/promises";
@@ -14,6 +10,7 @@ import { nativeGetCurrentBranch, nativeDetectMainBranch } from "./native-git-bri
 import { formatDuration } from "../shared/format-utils.js";
 import { parseEvalReviewFrontmatter } from "./eval-review-schema.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { buildPrEvidence } from "./pr-evidence.js";
 function git(basePath, args) {
     return execFileSync("git", args, { cwd: basePath, encoding: "utf-8" }).trim();
 }
@@ -114,66 +111,46 @@ export async function checkSliceEvalReview(basePath, milestoneId, sliceId) {
     };
 }
 function generatePRContent(basePath, milestoneId, milestoneTitle) {
-    const title = `feat: ${milestoneTitle || milestoneId}`;
-    const sections = [];
-    // 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
     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 = [];
     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 = [];
     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(args, ctx, _pi) {
     const basePath = currentDirectoryRoot();

package/dist/resources/extensions/gsd/commands-workflow-templates.js

@@ -1,12 +1,8 @@
-/**
- * GSD Workflow Template Commands — /gsd start, /gsd templates
- *
- * Handles the `/gsd start [template] [description]` and `/gsd templates` commands.
- * Resolves templates by name or auto-detection, then dispatches the workflow prompt.
- */
+// Project/App: GSD-2
+// File Purpose: Workflow template commands for starting, listing, and dispatching workflows.
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import { resolveByName, autoDetect, listTemplates, getTemplateInfo, loadWorkflowTemplate, loadRegistry, } from "./workflow-templates.js";
+import { resolveByName, autoDetect, listTemplates, getTemplateInfo, loadWorkflowTemplate, loadRegistry, isLegacyWorkflowMode, } from "./workflow-templates.js";
 import { loadPrompt } from "./prompt-loader.js";
 import { gsdRoot } from "./paths.js";
 import { createGitService, runGit } from "./git-service.js";
@@ -14,6 +10,8 @@ import { isAutoActive, isAutoPaused } from "./auto.js";
 import { getErrorMessage } from "./error-utils.js";
 import { resolvePlugin } from "./workflow-plugins.js";
 import { currentDirectoryRoot } from "./commands/context.js";
+import { formatRecommendedProcessPaths } from "./process-task-path.js";
+import { incrementLegacyTelemetry } from "./legacy-telemetry.js";
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 /**
  * Generate a URL-friendly slug from text.
@@ -244,6 +242,9 @@ export async function handleStart(args, ctx, pi) {
                 "  /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" +
@@ -364,6 +365,9 @@ export async function handleStart(args, ctx, pi) {
         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,
         templateName: template.name,
@@ -491,6 +495,7 @@ export function dispatchMarkdownPhasePlugin(plugin, description, ctx, pi) {
         infoLines.push(`Artifacts: ${artifactDir}`);
     infoLines.push(`Branch: ${actualBranch}`);
     ctx.ui.notify(infoLines.join("\n"), "info");
+    incrementLegacyTelemetry("legacy.workflowEngineUsed");
     const prompt = loadPrompt("workflow-start", {
         templateId,
         templateName: plugin.meta.displayName,

package/dist/resources/extensions/gsd/component-loader.js

@@ -1,18 +1,10 @@
-/**
- * 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 { validateComponentName, validateComponentDescription, computeComponentId, } from './component-types.js';
 const SUPPORTED_COMPONENT_KINDS = ['skill', 'agent'];
 const SUPPORTED_API_VERSIONS = ['gsd/v1'];
@@ -183,6 +175,7 @@ function loadFromLegacySkill(filePath, dir, source) {
         format: 'skill-md',
         enabled: true,
     };
+    incrementLegacyTelemetry('legacy.componentFormatUsed');
     return { component, diagnostics };
 }
 function loadFromLegacyAgent(filePath, source) {
@@ -235,6 +228,7 @@ function loadFromLegacyAgent(filePath, source) {
         format: 'agent-md',
         enabled: true,
     };
+    incrementLegacyTelemetry('legacy.componentFormatUsed');
     return { component, diagnostics };
 }
 // ============================================================================

package/dist/resources/extensions/gsd/custom-workflow-engine.js

@@ -13,13 +13,29 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
-import { readGraph, writeGraph, getNextPendingStep, markStepActive, markStepComplete, expandIteration, } from "./graph.js";
+import { readGraph, writeGraph, getNextPendingStep, markStepActive, markStepComplete, expandIteration, isTerminalStepStatus, } from "./graph.js";
 import { injectContext } from "./context-injector.js";
 import { readFrozenDefinition } from "./definition-io.js";
 import { parseUnitId } from "./unit-id.js";
 import { withFileLock } from "./file-lock.js";
 // Re-export for downstream consumers
 export { readFrozenDefinition } from "./definition-io.js";
+function formatBlockedWorkflowReason(graph) {
+    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 {
     engineId = "custom";
     runDir;
@@ -78,6 +94,14 @@ export class CustomWorkflowEngine {
             }
             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/dist/resources/extensions/gsd/db-adapter.js

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