gsd-pi 2.79.0 → 2.80.0-dev.4ea7d80e7

package/dist/resources/extensions/gsd/guided-flow.js

@@ -44,6 +44,7 @@ import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { createWorkspace, scopeMilestone } from "./workspace.js";
+import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export { MILESTONE_ID_RE, generateMilestoneSuffix, nextMilestoneId, extractMilestoneSeq, parseMilestoneId, milestoneIdSort, maxMilestoneNum, findMilestoneIds, reserveMilestoneId, claimReservedId, getReservedMilestoneIds, clearReservedMilestoneIds, } from "./milestone-ids.js";
 export { showQueue, handleQueueReorder, showQueueAdd, buildExistingMilestonesContext, } from "./guided-flow-queue.js";
@@ -295,6 +296,14 @@ export async function checkDeepProjectSetupAfterTurn(_event, ctx, basePath) {
             return false;
         }
     }
+    // R2: a depth-verification gate is still pending — the LLM emitted the
+    // confirmation question (via ask_user_questions or plain chat) but the user
+    // has not approved yet. Returning false keeps the entry in the
+    // pendingDeepProjectSetupMap so the next user message can resume.
+    const pendingGateId = getPendingGate(entry.basePath);
+    if (pendingGateId) {
+        return false;
+    }
     return dispatchNextDeepProjectSetupStage(entry);
 }
 async function dispatchNextDeepProjectSetupStage(entry) {
@@ -368,6 +377,23 @@ export function checkAutoStartAfterDiscuss() {
     const roadmapFile = existsSync(roadmapFilePath) ? roadmapFilePath : null;
     if (!contextFile && !roadmapFile)
         return false; // neither artifact yet — keep waiting
+    // Gate 1a: a depth-verification gate is still pending for THIS milestone — the
+    // LLM emitted the confirmation question (via ask_user_questions or plain chat)
+    // but the user has not answered yet. Advancing now would skip the gate and
+    // race ahead with unverified context.
+    const basePathForGate = entry.scope.workspace.projectRoot;
+    const pendingGateId = getPendingGate(basePathForGate);
+    if (pendingGateId) {
+        const pendingMilestoneId = extractDepthVerificationMilestoneId(pendingGateId);
+        // Block advancement if the gate is for THIS milestone, OR if it's a
+        // project/requirements gate (no milestone id encoded) for the deep setup flow.
+        const isProjectGate = pendingGateId === "depth_verification_project_confirm" ||
+            pendingGateId === "depth_verification_requirements_confirm" ||
+            pendingGateId === "depth_verification_research_decision_confirm";
+        if (pendingMilestoneId === milestoneId || isProjectGate) {
+            return false;
+        }
+    }
     // Gate 1b: Discriminate plan-blocked from discuss-incomplete when the DB row is queued.
     // If the DB is available and the row is still "queued" but CONTEXT.md already exists on
     // disk, the discuss phase completed but gsd_plan_milestone was hard-blocked by the
@@ -489,6 +515,20 @@ export function checkAutoStartAfterDiscuss() {
             logWarning("guided", `manifest unlink failed: ${e.message}`);
         }
     }
+    // R3b: belt-and-suspenders for silent registration failure. The discuss flow
+    // finished and STATE.md exists, but the milestone may never have landed in
+    // the DB. Without this guard, the user sees "Milestone M001 ready." and then
+    // /gsd reports "No Active Milestone".
+    if (isDbAvailable()) {
+        const milestoneRow = getMilestone(milestoneId);
+        if (!milestoneRow) {
+            ctx.ui.notify(`Milestone ${milestoneId}: discuss artifacts on disk but no DB row exists. ` +
+                `PROJECT.md may have failed to register milestones. ` +
+                `Re-save PROJECT.md with canonical "- [ ] M001: Title — One-liner" lines, ` +
+                `then re-run /gsd to recover.`, "error");
+            return false;
+        }
+    }
     pendingAutoStartMap.delete(basePath);
     ctx.ui.notify(`Milestone ${milestoneId} ready.`, "success");
     startAutoDetached(ctx, pi, basePath, false, { step });
@@ -1676,8 +1716,8 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     // standard wizard below.
     {
         const prefs = loadEffectiveGSDPreferences(basePath)?.preferences;
-        const { hasPendingDeepStage } = await import("./auto-dispatch.js");
-        if (hasPendingDeepStage(prefs, basePath)) {
+        const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
+        if (shouldRunDeepProjectSetup(state, prefs, basePath)) {
             await startDeepProjectSetupForeground(ctx, pi, basePath, stepMode);
             return;
         }

package/dist/resources/extensions/gsd/legacy-telemetry.js

@@ -0,0 +1,70 @@
+// Project/App: GSD-2
+// File Purpose: Runtime counters for telemetry-gated legacy compatibility paths.
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { logWarning } from "./workflow-logger.js";
+const COUNTERS = [
+    "legacy.markdownFallbackUsed",
+    "legacy.workflowEngineUsed",
+    "legacy.uokFallbackUsed",
+    "legacy.mcpAliasUsed",
+    "legacy.componentFormatUsed",
+    "legacy.providerDefaultUsed",
+];
+const values = Object.fromEntries(COUNTERS.map((counter) => [counter, 0]));
+const warnedCounters = new Set();
+const DIAGNOSTICS = {
+    "legacy.markdownFallbackUsed": "Deprecated markdown state fallback used; migrate projects to DB-authoritative state before removing markdown derivation.",
+    "legacy.workflowEngineUsed": "Deprecated workflow engine path used; prefer auto-milestone workflow templates before removing legacy engines.",
+    "legacy.uokFallbackUsed": "Deprecated UOK fallback path used; resolve UOK kernel blockers before removing parity fallback wrappers.",
+    "legacy.mcpAliasUsed": "Deprecated MCP alias tool used; update callers to the canonical gsd_* tool name before alias removal.",
+    "legacy.componentFormatUsed": "Deprecated component format loaded; migrate skills/agents to component.yaml before removing legacy loaders.",
+    "legacy.providerDefaultUsed": "Provider-specific default fallback used without an explicit available model; configure provider-aware model preferences before removing defaults.",
+};
+process.once("beforeExit", persistLegacyTelemetry);
+export function incrementLegacyTelemetry(counter, amount = 1) {
+    if (!Number.isFinite(amount) || amount <= 0)
+        return;
+    values[counter] += amount;
+    emitLegacyDiagnostic(counter);
+    persistLegacyTelemetry();
+}
+export function getLegacyTelemetry() {
+    return { ...values };
+}
+export function resetLegacyTelemetry() {
+    for (const counter of COUNTERS) {
+        values[counter] = 0;
+    }
+    warnedCounters.clear();
+}
+export function listLegacyTelemetryCounters() {
+    return [...COUNTERS];
+}
+export function getLegacyTelemetryReport() {
+    return {
+        ts: new Date().toISOString(),
+        counters: getLegacyTelemetry(),
+    };
+}
+export function persistLegacyTelemetrySnapshot() {
+    persistLegacyTelemetry();
+}
+function emitLegacyDiagnostic(counter) {
+    if (warnedCounters.has(counter))
+        return;
+    warnedCounters.add(counter);
+    logWarning("migration", DIAGNOSTICS[counter], { counter });
+}
+function persistLegacyTelemetry() {
+    const outputPath = process.env.GSD_LEGACY_TELEMETRY_FILE?.trim();
+    if (!outputPath)
+        return;
+    try {
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, `${JSON.stringify(getLegacyTelemetryReport(), null, 2)}\n`, "utf-8");
+    }
+    catch {
+        // Legacy cleanup telemetry must never block runtime paths.
+    }
+}

package/dist/resources/extensions/gsd/markdown-renderer.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Markdown projection renderer for GSD workflow database rows.
 // GSD Markdown Renderer — DB → Markdown file generation
 //
 // Transforms DB state into correct markdown files on disk.

package/dist/resources/extensions/gsd/model-router.js

@@ -1,9 +1,9 @@
-// GSD Extension — Dynamic Model Router
-// Maps complexity tiers to models, enforcing downgrade-only semantics.
-// The user's configured model is always the ceiling.
+// Project/App: GSD-2
+// File Purpose: Routes work to appropriate models while preserving configured ceilings.
 import { tierOrdinal } from "./complexity-classifier.js";
 import { getProviderCapabilities } from "@gsd/pi-ai";
 import { getToolCompatibility } from "@gsd/pi-coding-agent";
+import { incrementLegacyTelemetry } from "./legacy-telemetry.js";
 // ─── Known Model Tiers ───────────────────────────────────────────────────────
 // Maps known model IDs to their capability tier. Used when tier_models is not
 // explicitly configured to pick the best available model for each tier.
@@ -474,13 +474,16 @@ export function resolveModelForTier(tier, availableModelIds, routingConfigOrCros
         : crossProvider ?? routingConfig.cross_provider !== false;
     // No available models known — return canonical fallback
     if (availableModelIds.length === 0) {
+        incrementLegacyTelemetry("legacy.providerDefaultUsed");
         return canonicalModelForTier(tier);
     }
     // Cross-provider tier search
     const resolved = findModelForTier(tier, routingConfig, availableModelIds, allowCrossProvider);
-    return resolved
-        ? normalizeResolvedTierModelId(resolved, tier, routingConfig)
-        : canonicalModelForTier(tier);
+    if (resolved) {
+        return normalizeResolvedTierModelId(resolved, tier, routingConfig);
+    }
+    incrementLegacyTelemetry("legacy.providerDefaultUsed");
+    return canonicalModelForTier(tier);
 }
 // ─── Internal ────────────────────────────────────────────────────────────────
 /**

package/dist/resources/extensions/gsd/notification-widget.js

@@ -21,14 +21,32 @@ export function buildNotificationWidgetLines() {
     return chip ? [`  ${chip}`] : [];
 }
 const REFRESH_INTERVAL_MS = 30_000;
+let notificationWidgetCleanup;
 export function initNotificationWidget(ctx) {
+    notificationWidgetCleanup?.();
+    notificationWidgetCleanup = undefined;
     if (!ctx.hasUI)
-        return;
+        return () => { };
     const push = () => {
         const chip = buildNotificationChip();
         ctx.ui.setStatus(STATUS_KEY, chip.length > 0 ? chip : undefined);
     };
     push();
-    onNotificationStoreChange(push);
-    setInterval(push, REFRESH_INTERVAL_MS).unref?.();
+    const unsubscribe = onNotificationStoreChange(push);
+    const interval = setInterval(push, REFRESH_INTERVAL_MS);
+    interval.unref?.();
+    const cleanup = () => {
+        unsubscribe();
+        clearInterval(interval);
+        if (notificationWidgetCleanup === cleanup) {
+            ctx.ui.setStatus(STATUS_KEY, undefined);
+            notificationWidgetCleanup = undefined;
+        }
+    };
+    notificationWidgetCleanup = cleanup;
+    return cleanup;
+}
+export function _resetNotificationWidgetForTests() {
+    notificationWidgetCleanup?.();
+    notificationWidgetCleanup = undefined;
 }

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

@@ -177,8 +177,12 @@ export function resolveDir(parentDir, idPrefix) {
         const exact = entries.find(e => e.isDirectory() && e.name === idPrefix);
         if (exact)
             return exact.name;
+        const idLower = idPrefix.toLowerCase();
+        const exactCaseInsensitive = entries.find(e => e.isDirectory() && e.name.toLowerCase() === idLower);
+        if (exactCaseInsensitive)
+            return exactCaseInsensitive.name;
         // Prefix match for legacy descriptor dirs: M001-SOMETHING
-        const prefixed = entries.find(e => e.isDirectory() && e.name.startsWith(idPrefix + "-"));
+        const prefixed = entries.find(e => e.isDirectory() && e.name.toLowerCase().startsWith(idLower + "-"));
         return prefixed ? prefixed.name : null;
     }
     catch {

package/dist/resources/extensions/gsd/post-execution-checks.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Post-execution validation checks for completed GSD task output.
 /**
  * Post-Execution Checks — Validate task output after execution completes.
  *
@@ -96,12 +98,25 @@ export function resolveImportPath(importPath, sourceFile, basePath) {
         if (existsSync(directPath)) {
             return { exists: true, resolvedPath: directPath };
         }
-        // Only .js/.jsx/.mjs/.cjs imports legitimately fall through for the TS
-        // ESM convention (.js → .ts). Any other explicit extension (.css, .json,
-        // .svg, images, fonts, .ts, .tsx, …) must stay unresolved when the direct
-        // path is missing — otherwise a stray `./missing.css.ts` could shadow a
-        // genuinely missing `./missing.css` import.
-        if (![".js", ".jsx", ".mjs", ".cjs"].includes(explicitExt)) {
+        // Known concrete extensions that should NOT fall through to code-shadow
+        // probing when missing. This preserves the "missing.css must stay missing"
+        // guarantee while still allowing dotted module stems like ./route.server
+        // to resolve as ./route.server.ts.
+        const nonFallbackExtensions = new Set([
+            ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+            ".json", ".css", ".scss", ".sass", ".less", ".styl",
+            ".svg", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".ico", ".bmp",
+            ".woff", ".woff2", ".ttf", ".otf", ".eot",
+        ]);
+        const runtimeFallbackExtensions = new Set([".js", ".jsx", ".mjs", ".cjs"]);
+        const dottedStemFallbackExtensions = new Set([".server", ".client", ".webhook"]);
+        if (explicitExt !== "" &&
+            !runtimeFallbackExtensions.has(explicitExt) &&
+            !nonFallbackExtensions.has(explicitExt) &&
+            !dottedStemFallbackExtensions.has(explicitExt)) {
+            return { exists: false, resolvedPath: null };
+        }
+        if (nonFallbackExtensions.has(explicitExt) && !runtimeFallbackExtensions.has(explicitExt)) {
             return { exists: false, resolvedPath: null };
         }
     }
@@ -163,6 +178,12 @@ export function checkImportResolution(taskRow, _priorTasks, basePath) {
         }
         const imports = extractRelativeImports(source);
         for (const { importPath, lineNum } of imports) {
+            // React Router generated +types modules may not exist on disk during
+            // post-exec checks (generated during framework build). Don't block task
+            // completion on these imports.
+            if (/^\.{1,2}\/\+types\//.test(importPath)) {
+                continue;
+            }
             const resolution = resolveImportPath(importPath, file, basePath);
             if (!resolution.exists) {
                 results.push({

package/dist/resources/extensions/gsd/pr-evidence.js

@@ -0,0 +1,117 @@
+// Project/App: GSD-2
+// File Purpose: Shared pull request evidence generator for GSD shipping paths.
+const CHANGE_TYPE_LABELS = {
+    feat: "New feature or capability",
+    fix: "Bug fix",
+    refactor: "Code restructuring",
+    test: "Adding or updating tests",
+    docs: "Documentation only",
+    chore: "Build, CI, or tooling changes",
+};
+// Per-item cap for user-supplied content. 2 KB gives slice titles plus
+// descriptions room while still bounding malicious DoS-via-PR-body input.
+const USER_CONTENT_CAP_BYTES = 2048;
+const TRUNCATION_SUFFIX = " … [truncated]";
+// Strips HTML comments, fake commit trailers (Co-Authored-By, Signed-off-by —
+// case-insensitive on the trailer name), and caps total length. Designed to
+// be a no-op for well-formed input; golden fixtures must remain byte-stable.
+// Trailer lines are removed (not rejected) so that a single bad line in an
+// otherwise legitimate description does not block the entire PR.
+function sanitizeUserContent(s) {
+    if (!s)
+        return s;
+    // Strip HTML comments greedily across newlines.
+    let out = s.replace(/<!--[\s\S]*?-->/g, "");
+    // Drop lines that look like commit trailers we do not want forged.
+    out = out
+        .split("\n")
+        .filter((line) => !/^\s*(co-authored-by|signed-off-by)\s*:/i.test(line))
+        .join("\n");
+    if (Buffer.byteLength(out, "utf8") > USER_CONTENT_CAP_BYTES) {
+        const budget = USER_CONTENT_CAP_BYTES - Buffer.byteLength(TRUNCATION_SUFFIX, "utf8");
+        // Truncate by code units to stay safely under the byte budget for ASCII;
+        // for multibyte content we conservatively walk back until under budget.
+        let sliced = out.slice(0, Math.max(0, budget));
+        while (Buffer.byteLength(sliced, "utf8") > budget && sliced.length > 0) {
+            sliced = sliced.slice(0, -1);
+        }
+        out = sliced + TRUNCATION_SUFFIX;
+    }
+    return out;
+}
+// Strips HTML comments and fake trailers without applying the length cap.
+// Used for short fields like linkedIssue where truncation would be confusing.
+function sanitizeIssueRef(s) {
+    if (!s)
+        return s;
+    let out = s.replace(/<!--[\s\S]*?-->/g, "");
+    out = out
+        .split("\n")
+        .filter((line) => !/^\s*(co-authored-by|signed-off-by)\s*:/i.test(line))
+        .join("\n");
+    return out;
+}
+function normalizeList(values) {
+    return (values ?? [])
+        .map((value) => sanitizeUserContent(value).trim())
+        .filter(Boolean);
+}
+function changeTypeChecklist(selected) {
+    return Object.keys(CHANGE_TYPE_LABELS).map((type) => {
+        const checked = type === selected ? "x" : " ";
+        return `- [${checked}] \`${type}\` - ${CHANGE_TYPE_LABELS[type]}`;
+    });
+}
+function bulletList(values, fallback) {
+    if (values.length === 0)
+        return `- ${fallback}`;
+    return values.map((value) => `- ${value}`).join("\n");
+}
+export function buildPrEvidence(input) {
+    const subjectId = input.subjectId?.trim() || input.milestoneId;
+    const subjectKind = input.subjectKind ?? "milestone";
+    const subjectTitle = input.milestoneTitle?.trim() || subjectId;
+    const changeType = input.changeType ?? "feat";
+    const summaries = normalizeList(input.summaries);
+    const blockers = normalizeList(input.blockers);
+    const roadmapItems = normalizeList(input.roadmapItems);
+    const metrics = normalizeList(input.metrics);
+    const testsRun = normalizeList(input.testsRun);
+    const rollbackNotes = normalizeList(input.rollbackNotes);
+    // linkedIssue is sanitized but not length-capped: legitimate issue refs
+    // are short by nature, and truncating "Closes #123" would be unhelpful.
+    const linkedIssueRaw = input.linkedIssue ? sanitizeIssueRef(input.linkedIssue).trim() : "";
+    const linkedIssue = linkedIssueRaw || "Not specified. Add an issue link before marking this PR ready if CONTRIBUTING.md requires one.";
+    const why = (input.why ? sanitizeUserContent(input.why).trim() : "") || `${capitalize(subjectKind)} work is complete and ready for review.`;
+    const how = (input.how ? sanitizeUserContent(input.how).trim() : "") || "Generated from GSD evidence and local workflow artifacts.";
+    const title = `${changeType}: ${subjectTitle}`;
+    const sections = [
+        "## TL;DR",
+        "",
+        `**What:** Ship ${subjectKind} ${subjectId} - ${subjectTitle}`,
+        `**Why:** ${why}`,
+        `**How:** ${how}`,
+        "",
+        "## What",
+        "",
+        summaries.length > 0 ? summaries.join("\n\n") : `${capitalize(subjectKind)} ${subjectId} completed.`,
+    ];
+    if (blockers.length > 0) {
+        sections.push("", "## Blockers", "", blockers.map((blocker) => `- ${blocker}`).join("\n"));
+    }
+    sections.push("", "## Why", "", why, "", "## How", "", how, "", "## Linked Issue", "", linkedIssue);
+    if (roadmapItems.length > 0) {
+        sections.push("", "## Roadmap", "", roadmapItems.join("\n"));
+    }
+    if (metrics.length > 0) {
+        sections.push("", "## Metrics", "", bulletList(metrics, "No metrics recorded."));
+    }
+    sections.push("", "## Tests Run", "", bulletList(testsRun, "Not specified. Add exact verification commands before requesting review."), "", "## Change Type", "", ...changeTypeChecklist(changeType), "", "## Rollback And Compatibility", "", bulletList(rollbackNotes, "No behavior-changing rollback notes recorded."));
+    if (input.aiAssisted !== false) {
+        sections.push("", "## AI Assistance Disclosure", "", "This PR was prepared with AI assistance.");
+    }
+    return { title, body: sections.join("\n") };
+}
+function capitalize(value) {
+    return value.slice(0, 1).toUpperCase() + value.slice(1);
+}

package/dist/resources/extensions/gsd/pre-execution-checks.js

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Pre-execution validation checks for GSD task plans.
 /**
  * Pre-Execution Checks — Validate task plans before execution begins.
  *

package/dist/resources/extensions/gsd/preferences-types.js

@@ -100,8 +100,26 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "context_mode",
     "planning_depth",
 ]);
-/** Canonical list of all dispatch unit types. */
-export const KNOWN_UNIT_TYPES = [
+/**
+ * Broad union of every recognized unit-type *label* used across the codebase.
+ *
+ * This intentionally covers more than the manifest-tracked dispatch units in
+ * `unit-context-manifest.ts:KNOWN_UNIT_TYPES`. Examples that live here but not
+ * in the manifest:
+ * - `discuss-slice` — dispatched by `guided-flow.ts` rather than auto-mode;
+ *   composer falls through to default behavior via `resolveManifest()` null path.
+ * - `worktree-merge` — used as a model-routing case, prompt-template name, and
+ *   commit-message label, not as an LLM-dispatched unit.
+ *
+ * Used by `preferences-validation.ts` to validate user-provided unit-type
+ * references in preferences (model overrides, skill rules, etc.) — preferences
+ * may legitimately reference any label, including non-dispatched ones.
+ *
+ * The manifest-strict subset lives in `unit-context-manifest.ts:KNOWN_UNIT_TYPES`
+ * and is enforced 1:1 against `UNIT_MANIFESTS` by the parity test in
+ * `tests/unit-context-manifest.test.ts`.
+ */
+export const KNOWN_UNIT_LABELS = [
     "research-milestone", "plan-milestone", "research-slice", "plan-slice", "refine-slice",
     "execute-task", "reactive-execute", "gate-evaluate", "complete-slice", "replan-slice", "reassess-roadmap",
     "run-uat", "complete-milestone", "validate-milestone", "rewrite-docs",

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -7,7 +7,7 @@
  */
 import { VALID_BRANCH_NAME } from "./git-service.js";
 import { normalizeStringArray } from "../shared/format-utils.js";
-import { KNOWN_PREFERENCE_KEYS, KNOWN_UNIT_TYPES, SKILL_ACTIONS, } from "./preferences-types.js";
+import { KNOWN_PREFERENCE_KEYS, KNOWN_UNIT_LABELS, SKILL_ACTIONS, } from "./preferences-types.js";
 const VALID_TOKEN_PROFILES = new Set(["budget", "balanced", "quality", "burn-max"]);
 const VALID_UOK_TURN_ACTIONS = new Set([
     "commit",
@@ -432,7 +432,7 @@ export function validatePreferences(preferences) {
     if (preferences.post_unit_hooks && Array.isArray(preferences.post_unit_hooks)) {
         const validHooks = [];
         const seenNames = new Set();
-        const knownUnitTypes = new Set(KNOWN_UNIT_TYPES);
+        const knownUnitTypes = new Set(KNOWN_UNIT_LABELS);
         for (const hook of preferences.post_unit_hooks) {
             if (!hook || typeof hook !== "object") {
                 errors.push("post_unit_hooks entry must be an object");
@@ -493,7 +493,7 @@ export function validatePreferences(preferences) {
     if (preferences.pre_dispatch_hooks && Array.isArray(preferences.pre_dispatch_hooks)) {
         const validPreHooks = [];
         const seenPreNames = new Set();
-        const knownUnitTypes = new Set(KNOWN_UNIT_TYPES);
+        const knownUnitTypes = new Set(KNOWN_UNIT_LABELS);
         const validActions = new Set(["modify", "skip", "replace"]);
         for (const hook of preferences.pre_dispatch_hooks) {
             if (!hook || typeof hook !== "object") {

package/dist/resources/extensions/gsd/process-task-path.js

@@ -0,0 +1,61 @@
+// Project/App: GSD-2
+// File Purpose: Canonical process recommendations for routing work by task size.
+const TASK_PATHS = {
+    hotfix: {
+        taskSize: "hotfix",
+        label: "Hotfix",
+        templateId: "hotfix",
+        command: "/gsd start hotfix <description>",
+        phases: ["fix", "ship"],
+        guidance: "Use for urgent production fixes that need minimal ceremony and fast verification.",
+    },
+    bugfix: {
+        taskSize: "bugfix",
+        label: "Bugfix",
+        templateId: "bugfix",
+        command: "/gsd start bugfix <description> --issue <ref>",
+        phases: ["triage", "fix", "verify", "ship"],
+        guidance: "Use for reproducible defects where a linked issue and regression test are expected.",
+    },
+    "small-feature": {
+        taskSize: "small-feature",
+        label: "Small Feature",
+        templateId: "small-feature",
+        command: "/gsd start small-feature <description>",
+        phases: ["scope", "plan", "implement", "verify"],
+        guidance: "Use for contained feature work that does not need the full milestone machinery.",
+    },
+    "large-feature": {
+        taskSize: "large-feature",
+        label: "Large Feature",
+        templateId: "full-project",
+        command: "/gsd discuss <description>, then /gsd auto",
+        phases: ["discuss", "plan", "execute", "verify"],
+        guidance: "Use for multi-slice work that should run through the DB-backed milestone flow.",
+    },
+    "architecture-change": {
+        taskSize: "architecture-change",
+        label: "Architecture Change",
+        templateId: "refactor",
+        command: "/gsd start refactor <description>",
+        phases: ["inventory", "plan", "migrate", "verify"],
+        guidance: "Use for structural changes that require inventory, compatibility notes, and staged verification.",
+    },
+};
+export function recommendProcessPath(taskSize) {
+    return TASK_PATHS[taskSize];
+}
+export function listRecommendedProcessPaths() {
+    return [
+        TASK_PATHS.hotfix,
+        TASK_PATHS.bugfix,
+        TASK_PATHS["small-feature"],
+        TASK_PATHS["large-feature"],
+        TASK_PATHS["architecture-change"],
+    ];
+}
+export function formatRecommendedProcessPaths() {
+    return listRecommendedProcessPaths()
+        .map((path) => `  ${path.taskSize.padEnd(19)} ${path.command}`)
+        .join("\n");
+}

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

@@ -10,7 +10,7 @@
  * Templates are snapshotted shortly after module init via warmCache().
  * This keeps import/extension-registration fast while still preventing a
  * running session from being invalidated when another `gsd` launch overwrites
- * ~/.gsd/agent/ with newer templates via initResources(). Without caching, the
+ * the user-local agent tree with newer templates via initResources(). Without caching, the
  * in-memory extension code (which knows variable set A) can read a newer
  * template from disk (which expects variable set B), causing a
  * "template declares {{X}} but no value was provided" crash mid-session.
@@ -47,9 +47,9 @@ export function resolveExtensionDirFromCandidates(moduleDir, agentGsdDir, exists
  *
  * `import.meta.url` resolves to whichever copy of this module is executing.
  * On Windows (npm global install via MSYS2 / Git Bash) this can resolve to
- * the npm-global `AppData/Roaming/npm/…` path, which does NOT contain the
- * prompts/ and templates/ subtrees that initResources() copies to
- * `~/.gsd/agent/extensions/gsd/`. Detect the mismatch and fall back to
+ * the npm-global package path, which does NOT contain the prompts/ and
+ * templates/ subtrees that initResources() copies to the user-local agent
+ * extension directory. Detect the mismatch and fall back to
  * the user-local agent directory.
  */
 function resolveExtensionDir() {
@@ -62,7 +62,7 @@ const promptsDir = join(__extensionDir, "prompts");
 const templatesDir = join(__extensionDir, "templates");
 /**
  * Return the resolved templates directory path for use in prompts.
- * Avoids hardcoding `~/.gsd/agent/extensions/gsd/templates/` in templates. (#3575)
+ * Avoids hardcoding the user-local templates directory in templates. (#3575)
  */
 export function getTemplatesDir() {
     return templatesDir;
@@ -138,6 +138,10 @@ export function loadPrompt(name, vars = {}) {
         templateCache.set(name, content);
     }
     const effectiveVars = {
+        templatesDir: getTemplatesDir(),
+        planTemplatePath: join(getTemplatesDir(), "plan.md"),
+        taskPlanTemplatePath: join(getTemplatesDir(), "task-plan.md"),
+        taskSummaryTemplatePath: join(getTemplatesDir(), "task-summary.md"),
         skillActivation: "If a `GSD Skill Preferences` block is present in system context, use it and the `<available_skills>` catalog in your system prompt to decide which skills to load and follow for this unit, without relaxing required verification or artifact rules.",
         ...vars,
     };