gsd-pi 2.79.0 → 2.80.0-dev.710c06e97

package/src/resources/extensions/gsd/guided-flow.ts

@@ -70,6 +70,7 @@ import {
 } from "./preparation.js";
 import { verifyExpectedArtifact } from "./auto-recovery.js";
 import { createWorkspace, scopeMilestone, type MilestoneScope } from "./workspace.js";
+import { getPendingGate, extractDepthVerificationMilestoneId } from "./bootstrap/write-gate.js";
 
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export {
@@ -410,6 +411,15 @@ export async function checkDeepProjectSetupAfterTurn(
     }
   }
 
+  // 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);
 }
 
@@ -494,6 +504,25 @@ export function checkAutoStartAfterDiscuss(): boolean {
   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
@@ -628,6 +657,24 @@ export function checkAutoStartAfterDiscuss(): boolean {
     try { unlinkSync(manifestPath); } catch (e) { logWarning("guided", `manifest unlink failed: ${(e as Error).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 });

package/src/resources/extensions/gsd/interrupted-session.ts

@@ -37,6 +37,7 @@ export interface PausedSessionMetadata {
   activeRunDir?: string | null;
   autoStartTime?: number;
   milestoneLock?: string | null;
+  pauseReason?: string;
 }
 
 export interface InterruptedSessionAssessment {

package/src/resources/extensions/gsd/legacy-telemetry.ts

@@ -0,0 +1,99 @@
+// 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";
+
+export type LegacyTelemetryCounter =
+  | "legacy.markdownFallbackUsed"
+  | "legacy.workflowEngineUsed"
+  | "legacy.uokFallbackUsed"
+  | "legacy.mcpAliasUsed"
+  | "legacy.componentFormatUsed"
+  | "legacy.providerDefaultUsed";
+
+export type LegacyTelemetrySnapshot = Record<LegacyTelemetryCounter, number>;
+
+export interface LegacyTelemetryReport {
+  ts: string;
+  counters: LegacyTelemetrySnapshot;
+}
+
+const COUNTERS: LegacyTelemetryCounter[] = [
+  "legacy.markdownFallbackUsed",
+  "legacy.workflowEngineUsed",
+  "legacy.uokFallbackUsed",
+  "legacy.mcpAliasUsed",
+  "legacy.componentFormatUsed",
+  "legacy.providerDefaultUsed",
+];
+
+const values: LegacyTelemetrySnapshot = Object.fromEntries(
+  COUNTERS.map((counter) => [counter, 0]),
+) as LegacyTelemetrySnapshot;
+
+const warnedCounters = new Set<LegacyTelemetryCounter>();
+
+const DIAGNOSTICS: Record<LegacyTelemetryCounter, string> = {
+  "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: LegacyTelemetryCounter, amount = 1): void {
+  if (!Number.isFinite(amount) || amount <= 0) return;
+  values[counter] += amount;
+  emitLegacyDiagnostic(counter);
+  persistLegacyTelemetry();
+}
+
+export function getLegacyTelemetry(): LegacyTelemetrySnapshot {
+  return { ...values };
+}
+
+export function resetLegacyTelemetry(): void {
+  for (const counter of COUNTERS) {
+    values[counter] = 0;
+  }
+  warnedCounters.clear();
+}
+
+export function listLegacyTelemetryCounters(): LegacyTelemetryCounter[] {
+  return [...COUNTERS];
+}
+
+export function getLegacyTelemetryReport(): LegacyTelemetryReport {
+  return {
+    ts: new Date().toISOString(),
+    counters: getLegacyTelemetry(),
+  };
+}
+
+export function persistLegacyTelemetrySnapshot(): void {
+  persistLegacyTelemetry();
+}
+
+function emitLegacyDiagnostic(counter: LegacyTelemetryCounter): void {
+  if (warnedCounters.has(counter)) return;
+  warnedCounters.add(counter);
+  logWarning("migration", DIAGNOSTICS[counter], { counter });
+}
+
+function persistLegacyTelemetry(): void {
+  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/src/resources/extensions/gsd/markdown-renderer.ts

@@ -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.
@@ -23,7 +25,8 @@ import {
   insertArtifact,
   getGateResults,
 } from "./gsd-db.js";
-import type { MilestoneRow, SliceRow, TaskRow, ArtifactRow } from "./gsd-db.js";
+import type { MilestoneRow, ArtifactRow } from "./db-milestone-artifact-rows.js";
+import type { SliceRow, TaskRow } from "./db-task-slice-rows.js";
 import type { GateRow } from "./types.js";
 import {
   resolveMilestoneFile,

package/src/resources/extensions/gsd/model-router.ts

@@ -1,6 +1,5 @@
-// 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 type { ComplexityTier, ClassificationResult, TaskMetadata } from "./complexity-classifier.js";
 import { tierOrdinal } from "./complexity-classifier.js";
@@ -8,6 +7,7 @@ import type { ResolvedModelConfig } from "./preferences.js";
 import { getProviderCapabilities, type ProviderCapabilities } from "@gsd/pi-ai";
 import { getToolCompatibility, getAllToolCompatibility } from "@gsd/pi-coding-agent";
 import type { ToolCompatibility } from "@gsd/pi-coding-agent";
+import { incrementLegacyTelemetry } from "./legacy-telemetry.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 
@@ -641,14 +641,18 @@ export function resolveModelForTier(
 
   // 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/src/resources/extensions/gsd/notification-widget.ts

@@ -27,9 +27,13 @@ export function buildNotificationWidgetLines(): string[] {
 }
 
 const REFRESH_INTERVAL_MS = 30_000;
+let notificationWidgetCleanup: (() => void) | undefined;
 
-export function initNotificationWidget(ctx: ExtensionContext): void {
-  if (!ctx.hasUI) return;
+export function initNotificationWidget(ctx: ExtensionContext): () => void {
+  notificationWidgetCleanup?.();
+  notificationWidgetCleanup = undefined;
+
+  if (!ctx.hasUI) return () => {};
 
   const push = () => {
     const chip = buildNotificationChip();
@@ -37,6 +41,23 @@ export function initNotificationWidget(ctx: ExtensionContext): void {
   };
   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(): void {
+  notificationWidgetCleanup?.();
+  notificationWidgetCleanup = undefined;
 }

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

@@ -188,9 +188,14 @@ export function resolveDir(parentDir: string, idPrefix: string): string | null {
     // Exact match first (current convention: bare ID)
     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 + "-")
+      e => e.isDirectory() && e.name.toLowerCase().startsWith(idLower + "-")
     );
     return prefixed ? prefixed.name : null;
   } catch {

package/src/resources/extensions/gsd/post-execution-checks.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Post-execution validation checks for completed GSD task output.
+
 /**
  * Post-Execution Checks — Validate task output after execution completes.
  *
@@ -15,7 +18,7 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, dirname, join, extname } from "node:path";
-import type { TaskRow } from "./gsd-db.ts";
+import type { TaskRow } from "./db-task-slice-rows.js";
 
 // ─── Result Types ────────────────────────────────────────────────────────────
 
@@ -144,12 +147,30 @@ export function resolveImportPath(
     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 };
     }
   }
@@ -222,6 +243,13 @@ export function checkImportResolution(
     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) {

package/src/resources/extensions/gsd/pr-evidence.ts

@@ -0,0 +1,182 @@
+// Project/App: GSD-2
+// File Purpose: Shared pull request evidence generator for GSD shipping paths.
+
+export type PrChangeType = "feat" | "fix" | "refactor" | "test" | "docs" | "chore";
+
+export interface PrEvidenceInput {
+  milestoneId: string;
+  subjectId?: string;
+  subjectKind?: "milestone" | "slice" | "workflow";
+  milestoneTitle?: string;
+  changeType?: PrChangeType;
+  linkedIssue?: string;
+  summaries?: string[];
+  blockers?: string[];
+  roadmapItems?: string[];
+  metrics?: string[];
+  testsRun?: string[];
+  why?: string;
+  how?: string;
+  rollbackNotes?: string[];
+  aiAssisted?: boolean;
+}
+
+export interface PrEvidence {
+  title: string;
+  body: string;
+}
+
+const CHANGE_TYPE_LABELS: Record<PrChangeType, string> = {
+  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: string): string {
+  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: string): string {
+  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: readonly string[] | undefined): string[] {
+  return (values ?? [])
+    .map((value) => sanitizeUserContent(value).trim())
+    .filter(Boolean);
+}
+
+function changeTypeChecklist(selected: PrChangeType): string[] {
+  return (Object.keys(CHANGE_TYPE_LABELS) as PrChangeType[]).map((type) => {
+    const checked = type === selected ? "x" : " ";
+    return `- [${checked}] \`${type}\` - ${CHANGE_TYPE_LABELS[type]}`;
+  });
+}
+
+function bulletList(values: readonly string[], fallback: string): string {
+  if (values.length === 0) return `- ${fallback}`;
+  return values.map((value) => `- ${value}`).join("\n");
+}
+
+export function buildPrEvidence(input: PrEvidenceInput): PrEvidence {
+  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: string[] = [
+    "## 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: string): string {
+  return value.slice(0, 1).toUpperCase() + value.slice(1);
+}

package/src/resources/extensions/gsd/pre-execution-checks.ts

@@ -1,3 +1,6 @@
+// Project/App: GSD-2
+// File Purpose: Pre-execution validation checks for GSD task plans.
+
 /**
  * Pre-Execution Checks — Validate task plans before execution begins.
  *
@@ -18,7 +21,7 @@ import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
-import type { TaskRow } from "./gsd-db.ts";
+import type { TaskRow } from "./db-task-slice-rows.js";
 import type { PreExecutionCheckJSON } from "./verification-evidence.ts";
 
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";

package/src/resources/extensions/gsd/preferences-types.ts

@@ -154,8 +154,26 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "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",
@@ -164,7 +182,7 @@ export const KNOWN_UNIT_TYPES = [
   "workflow-preferences", "discuss-project", "discuss-requirements",
   "research-decision", "research-project",
 ] as const;
-export type UnitType = (typeof KNOWN_UNIT_TYPES)[number];
+export type UnitLabel = (typeof KNOWN_UNIT_LABELS)[number];
 
 
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
@@ -343,7 +361,8 @@ export interface GSDPreferences {
   /**
    * Tool-output sandboxing via gsd_exec. Keeps sub-session context windows
    * clean by running scripts in a subprocess and only surfacing a short
-   * digest. See `ContextModeConfig`. Default: disabled.
+   * digest. See `ContextModeConfig`. Default: enabled unless explicitly
+   * disabled with `context_mode.enabled: false`.
    */
   context_mode?: ContextModeConfig;
   token_profile?: TokenProfile;

package/src/resources/extensions/gsd/preferences-validation.ts

@@ -14,7 +14,7 @@ import { normalizeStringArray } from "../shared/format-utils.js";
 
 import {
   KNOWN_PREFERENCE_KEYS,
-  KNOWN_UNIT_TYPES,
+  KNOWN_UNIT_LABELS,
 
   SKILL_ACTIONS,
   type WorkflowMode,
@@ -441,7 +441,7 @@ export function validatePreferences(preferences: GSDPreferences): {
   if (preferences.post_unit_hooks && Array.isArray(preferences.post_unit_hooks)) {
     const validHooks: PostUnitHookConfig[] = [];
     const seenNames = new Set<string>();
-    const knownUnitTypes = new Set<string>(KNOWN_UNIT_TYPES);
+    const knownUnitTypes = new Set<string>(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");
@@ -503,7 +503,7 @@ export function validatePreferences(preferences: GSDPreferences): {
   if (preferences.pre_dispatch_hooks && Array.isArray(preferences.pre_dispatch_hooks)) {
     const validPreHooks: PreDispatchHookConfig[] = [];
     const seenPreNames = new Set<string>();
-    const knownUnitTypes = new Set<string>(KNOWN_UNIT_TYPES);
+    const knownUnitTypes = new Set<string>(KNOWN_UNIT_LABELS);
     const validActions = new Set(["modify", "skip", "replace"]);
     for (const hook of preferences.pre_dispatch_hooks) {
       if (!hook || typeof hook !== "object") {