gsd-pi 2.18.0 → 2.20.0

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

@@ -2,8 +2,11 @@ import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@gsd/pi-coding-agent";
+import { parse as parseYaml } from "yaml";
 import type { GitPreferences } from "./git-service.js";
 import type { PostUnitHookConfig, PreDispatchHookConfig, BudgetEnforcementMode, NotificationPreferences, TokenProfile, InlineLevel, PhaseSkipPreferences } from "./types.js";
+import type { DynamicRoutingConfig } from "./model-router.js";
+import { defaultRoutingConfig } from "./model-router.js";
 import { VALID_BRANCH_NAME } from "./git-service.js";
 
 const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
@@ -15,9 +18,40 @@ const GLOBAL_PREFERENCES_PATH_UPPERCASE = join(homedir(), ".gsd", "PREFERENCES.m
 const PROJECT_PREFERENCES_PATH_UPPERCASE = join(process.cwd(), ".gsd", "PREFERENCES.md");
 const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);
 
+// ─── Workflow Modes ──────────────────────────────────────────────────────────
+
+export type WorkflowMode = "solo" | "team";
+
+/** Default preference values for each workflow mode. */
+const MODE_DEFAULTS: Record<WorkflowMode, Partial<GSDPreferences>> = {
+  solo: {
+    git: {
+      auto_push: true,
+      push_branches: false,
+      pre_merge_check: false,
+      merge_strategy: "squash",
+      isolation: "worktree",
+      commit_docs: true,
+    },
+    unique_milestone_ids: false,
+  },
+  team: {
+    git: {
+      auto_push: false,
+      push_branches: true,
+      pre_merge_check: true,
+      merge_strategy: "squash",
+      isolation: "worktree",
+      commit_docs: true,
+    },
+    unique_milestone_ids: true,
+  },
+};
+
 /** All recognized top-level keys in GSDPreferences. Used to detect typos / stale config. */
 const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "version",
+  "mode",
   "always_use_skills",
   "prefer_skills",
   "avoid_skills",
@@ -25,6 +59,7 @@ const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "custom_instructions",
   "models",
   "skill_discovery",
+  "skill_staleness_days",
   "auto_supervisor",
   "uat_dispatch",
   "unique_milestone_ids",
@@ -36,8 +71,10 @@ const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "git",
   "post_unit_hooks",
   "pre_dispatch_hooks",
+  "dynamic_routing",
   "token_profile",
   "phases",
+  "auto_visualize",
 ]);
 
 export interface GSDSkillRule {
@@ -102,7 +139,7 @@ export interface AutoSupervisorConfig {
 }
 
 export interface RemoteQuestionsConfig {
-  channel: "slack" | "discord";
+  channel: "slack" | "discord" | "telegram";
   channel_id: string | number;
   timeout_minutes?: number;        // clamped to 1-30
   poll_interval_seconds?: number;  // clamped to 2-30
@@ -110,6 +147,7 @@ export interface RemoteQuestionsConfig {
 
 export interface GSDPreferences {
   version?: number;
+  mode?: WorkflowMode;
   always_use_skills?: string[];
   prefer_skills?: string[];
   avoid_skills?: string[];
@@ -117,6 +155,7 @@ export interface GSDPreferences {
   custom_instructions?: string[];
   models?: GSDModelConfig | GSDModelConfigV2;
   skill_discovery?: SkillDiscoveryMode;
+  skill_staleness_days?: number;  // Skills unused for N days get deprioritized (#599). 0 = disabled. Default: 60.
   auto_supervisor?: AutoSupervisorConfig;
   uat_dispatch?: boolean;
   unique_milestone_ids?: boolean;
@@ -128,8 +167,10 @@ export interface GSDPreferences {
   git?: GitPreferences;
   post_unit_hooks?: PostUnitHookConfig[];
   pre_dispatch_hooks?: PreDispatchHookConfig[];
+  dynamic_routing?: DynamicRoutingConfig;
   token_profile?: TokenProfile;
   phases?: PhaseSkipPreferences;
+  auto_visualize?: boolean;
 }
 
 export interface LoadedGSDPreferences {
@@ -163,25 +204,49 @@ export function loadProjectGSDPreferences(): LoadedGSDPreferences | null {
     ?? loadPreferencesFile(PROJECT_PREFERENCES_PATH_UPPERCASE, "project");
 }
 
+/**
+ * Apply mode defaults as the lowest-priority layer.
+ * Mode defaults fill in undefined fields; any explicit user value wins.
+ */
+export function applyModeDefaults(mode: WorkflowMode, prefs: GSDPreferences): GSDPreferences {
+  const defaults = MODE_DEFAULTS[mode];
+  if (!defaults) return prefs;
+  return mergePreferences(defaults, prefs);
+}
+
 export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
   const globalPreferences = loadGlobalGSDPreferences();
   const projectPreferences = loadProjectGSDPreferences();
 
   if (!globalPreferences && !projectPreferences) return null;
-  if (!globalPreferences) return projectPreferences;
-  if (!projectPreferences) return globalPreferences;
 
-  const mergedWarnings = [
-    ...(globalPreferences.warnings ?? []),
-    ...(projectPreferences.warnings ?? []),
-  ];
+  let result: LoadedGSDPreferences;
+  if (!globalPreferences) {
+    result = projectPreferences!;
+  } else if (!projectPreferences) {
+    result = globalPreferences;
+  } else {
+    const mergedWarnings = [
+      ...(globalPreferences.warnings ?? []),
+      ...(projectPreferences.warnings ?? []),
+    ];
+    result = {
+      path: projectPreferences.path,
+      scope: "project",
+      preferences: mergePreferences(globalPreferences.preferences, projectPreferences.preferences),
+      ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
+    };
+  }
 
-  return {
-    path: projectPreferences.path,
-    scope: "project",
-    preferences: mergePreferences(globalPreferences.preferences, projectPreferences.preferences),
-    ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
-  };
+  // Apply mode defaults as the lowest-priority layer
+  if (result.preferences.mode) {
+    result = {
+      ...result,
+      preferences: applyModeDefaults(result.preferences.mode, result.preferences),
+    };
+  }
+
+  return result;
 }
 
 // ─── Skill Reference Resolution ───────────────────────────────────────────────
@@ -419,148 +484,27 @@ function loadPreferencesFile(path: string, scope: "global" | "project"): LoadedG
 
 /** @internal Exported for testing only */
 export function parsePreferencesMarkdown(content: string): GSDPreferences | null {
-  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-  if (!match) return null;
-  return parseFrontmatterBlock(match[1]);
+  // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
+  const startMarker = content.startsWith('---\r\n') ? '---\r\n' : '---\n';
+  if (!content.startsWith(startMarker)) return null;
+  const searchStart = startMarker.length;
+  const endIdx = content.indexOf('\n---', searchStart);
+  if (endIdx === -1) return null;
+  const block = content.slice(searchStart, endIdx);
+  return parseFrontmatterBlock(block.replace(/\r/g, ''));
 }
 
 function parseFrontmatterBlock(frontmatter: string): GSDPreferences {
-  const root: Record<string, unknown> = {};
-  const stack: Array<{ indent: number; value: Record<string, unknown> }> = [{ indent: -1, value: root }];
-
-  const lines = frontmatter.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    if (!line.trim()) continue;
-
-    const indent = line.match(/^\s*/)?.[0].length ?? 0;
-    const trimmed = line.trim();
-
-    // Skip comment lines (standalone YAML comments)
-    if (trimmed.startsWith("#")) continue;
-
-    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
-      stack.pop();
-    }
-
-    const current = stack[stack.length - 1].value;
-    const keyMatch = trimmed.match(/^([A-Za-z0-9_]+):(.*)$/);
-    if (!keyMatch) continue;
-
-    const [, key, remainder] = keyMatch;
-    // Strip inline comments from the value portion
-    const valuePart = remainder.replace(/\s+#.*$/, "").trim();
-
-    if (valuePart === "") {
-      const nextLine = lines[i + 1] ?? "";
-      const nextTrimmed = nextLine.trim();
-      if (nextTrimmed.startsWith("- ")) {
-        const items: unknown[] = [];
-        let j = i + 1;
-        while (j < lines.length) {
-          const candidate = lines[j];
-          const candidateIndent = candidate.match(/^\s*/)?.[0].length ?? 0;
-          const candidateTrimmed = candidate.trim();
-          if (!candidateTrimmed) {
-            j++;
-            continue;
-          }
-          if (candidateIndent <= indent || !candidateTrimmed.startsWith("- ")) break;
-
-          const itemText = candidateTrimmed.slice(2).trim();
-          const nextCandidate = lines[j + 1] ?? "";
-          const nextCandidateIndent = nextCandidate.match(/^\s*/)?.[0].length ?? 0;
-          const nextCandidateTrimmed = nextCandidate.trim();
-
-          // Treat an array item as a structured object only when:
-          //   a) It looks like a YAML key-value pair (key starts with [A-Za-z0-9_]+:), OR
-          //   b) The next line is indented deeper (nested block under this item).
-          // Bare colons (e.g. "qwen/qwen3-coder:free") are NOT key-value pairs.
-          const looksLikeKeyValue = /^[A-Za-z0-9_]+:/.test(itemText);
-          if (looksLikeKeyValue || (nextCandidateTrimmed && nextCandidateIndent > candidateIndent)) {
-            const obj: Record<string, unknown> = {};
-            const firstMatch = itemText.match(/^([A-Za-z0-9_]+):(.*)$/);
-            if (firstMatch) {
-              obj[firstMatch[1]] = parseScalar(firstMatch[2].trim());
-            }
-            j++;
-            while (j < lines.length) {
-              const nested = lines[j];
-              const nestedIndent = nested.match(/^\s*/)?.[0].length ?? 0;
-              const nestedTrimmed = nested.trim();
-              if (!nestedTrimmed) {
-                j++;
-                continue;
-              }
-              if (nestedIndent <= candidateIndent) break;
-              const nestedMatch = nestedTrimmed.match(/^([A-Za-z0-9_]+):(.*)$/);
-              if (nestedMatch) {
-                const nestedValue = nestedMatch[2].trim();
-                if (nestedValue === "") {
-                  const nestedItems: string[] = [];
-                  j++;
-                  while (j < lines.length) {
-                    const nestedArrayLine = lines[j];
-                    const nestedArrayIndent = nestedArrayLine.match(/^\s*/)?.[0].length ?? 0;
-                    const nestedArrayTrimmed = nestedArrayLine.trim();
-                    if (!nestedArrayTrimmed) {
-                      j++;
-                      continue;
-                    }
-                    if (nestedArrayIndent <= nestedIndent || !nestedArrayTrimmed.startsWith("- ")) break;
-                    nestedItems.push(String(parseScalar(nestedArrayTrimmed.slice(2).trim())));
-                    j++;
-                  }
-                  obj[nestedMatch[1]] = nestedItems;
-                  continue;
-                }
-                obj[nestedMatch[1]] = parseScalar(nestedValue);
-              }
-              j++;
-            }
-            items.push(obj);
-            continue;
-          }
-
-          items.push(parseScalar(itemText));
-          j++;
-        }
-        current[key] = items;
-        i = j - 1;
-      } else {
-        const obj: Record<string, unknown> = {};
-        current[key] = obj;
-        stack.push({ indent, value: obj });
-      }
-      continue;
+  try {
+    const parsed = parseYaml(frontmatter);
+    if (typeof parsed !== 'object' || parsed === null) {
+      return {} as GSDPreferences;
     }
-
-    current[key] = parseScalar(valuePart);
+    return parsed as GSDPreferences;
+  } catch (e) {
+    console.error("[parseFrontmatterBlock] YAML parse error:", e);
+    return {} as GSDPreferences;
   }
-
-  return root as GSDPreferences;
-}
-
-function parseScalar(value: string): unknown {
-  // Strip inline YAML comments: " # comment" (# preceded by whitespace).
-  // Quoted strings are returned as-is (the comment is inside quotes).
-  const quoteMatch = value.match(/^(['"])(.*)(\1)$/);
-  if (quoteMatch) return quoteMatch[2];
-
-  const stripped = value.replace(/\s+#.*$/, "");
-  if (stripped === "true") return true;
-  if (stripped === "false") return false;
-  // Recognize empty array/object literals (with or without surrounding quotes)
-  const unquoted = stripped.replace(/^['\"]|['\"]$/g, "");
-  if (unquoted === "[]") return [];
-  if (unquoted === "{}") return {};
-  if (/^-?\d+$/.test(stripped)) {
-    const n = Number(stripped);
-    // Keep large integers (e.g. Discord channel IDs) as strings to avoid precision loss
-    if (Number.isSafeInteger(n)) return n;
-    return stripped;
-  }
-  return unquoted;
 }
 
 /**
@@ -572,6 +516,15 @@ export function resolveSkillDiscoveryMode(): SkillDiscoveryMode {
   return prefs?.preferences.skill_discovery ?? "suggest";
 }
 
+/**
+ * Resolve the skill staleness threshold in days.
+ * Returns 0 if disabled, default 60 if not configured.
+ */
+export function resolveSkillStalenessDays(): number {
+  const prefs = loadEffectiveGSDPreferences();
+  return prefs?.preferences.skill_staleness_days ?? 60;
+}
+
 /**
  * Resolve which model ID to use for a given auto-mode unit type.
  * Returns undefined if no model preference is set for this unit type.
@@ -674,6 +627,20 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode
   };
 }
 
+/**
+ * Resolve the dynamic routing configuration from effective preferences.
+ * Returns the merged config with defaults applied.
+ */
+export function resolveDynamicRoutingConfig(): DynamicRoutingConfig {
+  const prefs = loadEffectiveGSDPreferences();
+  const configured = prefs?.preferences.dynamic_routing;
+  if (!configured) return defaultRoutingConfig();
+  return {
+    ...defaultRoutingConfig(),
+    ...configured,
+  };
+}
+
 export function resolveAutoSupervisorConfig(): AutoSupervisorConfig {
   const prefs = loadEffectiveGSDPreferences();
   const configured = prefs?.preferences.auto_supervisor ?? {};
@@ -756,6 +723,7 @@ export function resolveInlineLevel(): InlineLevel {
 function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPreferences {
   return {
     version: override.version ?? base.version,
+    mode: override.mode ?? base.mode,
     always_use_skills: mergeStringLists(base.always_use_skills, override.always_use_skills),
     prefer_skills: mergeStringLists(base.prefer_skills, override.prefer_skills),
     avoid_skills: mergeStringLists(base.avoid_skills, override.avoid_skills),
@@ -763,6 +731,7 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     custom_instructions: mergeStringLists(base.custom_instructions, override.custom_instructions),
     models: { ...(base.models ?? {}), ...(override.models ?? {}) },
     skill_discovery: override.skill_discovery ?? base.skill_discovery,
+    skill_staleness_days: override.skill_staleness_days ?? base.skill_staleness_days,
     auto_supervisor: { ...(base.auto_supervisor ?? {}), ...(override.auto_supervisor ?? {}) },
     uat_dispatch: override.uat_dispatch ?? base.uat_dispatch,
     unique_milestone_ids: override.unique_milestone_ids ?? base.unique_milestone_ids,
@@ -780,6 +749,9 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
       : undefined,
     post_unit_hooks: mergePostUnitHooks(base.post_unit_hooks, override.post_unit_hooks),
     pre_dispatch_hooks: mergePreDispatchHooks(base.pre_dispatch_hooks, override.pre_dispatch_hooks),
+    dynamic_routing: (base.dynamic_routing || override.dynamic_routing)
+      ? { ...(base.dynamic_routing ?? {}), ...(override.dynamic_routing ?? {}) } as DynamicRoutingConfig
+      : undefined,
     token_profile: override.token_profile ?? base.token_profile,
     phases: (base.phases || override.phases)
       ? { ...(base.phases ?? {}), ...(override.phases ?? {}) }
@@ -811,6 +783,16 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Workflow Mode ──────────────────────────────────────────────────
+  if (preferences.mode !== undefined) {
+    const validModes = new Set<string>(["solo", "team"]);
+    if (typeof preferences.mode === "string" && validModes.has(preferences.mode)) {
+      validated.mode = preferences.mode as WorkflowMode;
+    } else {
+      errors.push(`invalid mode "${preferences.mode}" — must be one of: solo, team`);
+    }
+  }
+
   const validDiscoveryModes = new Set(["auto", "suggest", "off"]);
   if (preferences.skill_discovery) {
     if (validDiscoveryModes.has(preferences.skill_discovery)) {
@@ -820,6 +802,15 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  if (preferences.skill_staleness_days !== undefined) {
+    const days = Number(preferences.skill_staleness_days);
+    if (Number.isFinite(days) && days >= 0) {
+      validated.skill_staleness_days = Math.floor(days);
+    } else {
+      errors.push(`invalid skill_staleness_days: must be a non-negative number`);
+    }
+  }
+
   validated.always_use_skills = normalizeStringList(preferences.always_use_skills);
   validated.prefer_skills = normalizeStringList(preferences.prefer_skills);
   validated.avoid_skills = normalizeStringList(preferences.avoid_skills);
@@ -1100,6 +1091,56 @@ export function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Dynamic Routing ─────────────────────────────────────────────────
+  if (preferences.dynamic_routing !== undefined) {
+    if (typeof preferences.dynamic_routing === "object" && preferences.dynamic_routing !== null) {
+      const dr = preferences.dynamic_routing as unknown as Record<string, unknown>;
+      const validDr: Partial<DynamicRoutingConfig> = {};
+
+      if (dr.enabled !== undefined) {
+        if (typeof dr.enabled === "boolean") validDr.enabled = dr.enabled;
+        else errors.push("dynamic_routing.enabled must be a boolean");
+      }
+      if (dr.escalate_on_failure !== undefined) {
+        if (typeof dr.escalate_on_failure === "boolean") validDr.escalate_on_failure = dr.escalate_on_failure;
+        else errors.push("dynamic_routing.escalate_on_failure must be a boolean");
+      }
+      if (dr.budget_pressure !== undefined) {
+        if (typeof dr.budget_pressure === "boolean") validDr.budget_pressure = dr.budget_pressure;
+        else errors.push("dynamic_routing.budget_pressure must be a boolean");
+      }
+      if (dr.cross_provider !== undefined) {
+        if (typeof dr.cross_provider === "boolean") validDr.cross_provider = dr.cross_provider;
+        else errors.push("dynamic_routing.cross_provider must be a boolean");
+      }
+      if (dr.hooks !== undefined) {
+        if (typeof dr.hooks === "boolean") validDr.hooks = dr.hooks;
+        else errors.push("dynamic_routing.hooks must be a boolean");
+      }
+      if (dr.tier_models !== undefined) {
+        if (typeof dr.tier_models === "object" && dr.tier_models !== null) {
+          const tm = dr.tier_models as Record<string, unknown>;
+          const validTm: Record<string, string> = {};
+          for (const tier of ["light", "standard", "heavy"]) {
+            if (tm[tier] !== undefined) {
+              if (typeof tm[tier] === "string") validTm[tier] = tm[tier] as string;
+              else errors.push(`dynamic_routing.tier_models.${tier} must be a string`);
+            }
+          }
+          if (Object.keys(validTm).length > 0) validDr.tier_models = validTm as DynamicRoutingConfig["tier_models"];
+        } else {
+          errors.push("dynamic_routing.tier_models must be an object");
+        }
+      }
+
+      if (Object.keys(validDr).length > 0) {
+        validated.dynamic_routing = validDr as unknown as DynamicRoutingConfig;
+      }
+    } else {
+      errors.push("dynamic_routing must be an object");
+    }
+  }
+
   // ─── Git Preferences ───────────────────────────────────────────────────
   if (preferences.git && typeof preferences.git === "object") {
     const git: Record<string, unknown> = {};
@@ -1167,6 +1208,13 @@ export function validatePreferences(preferences: GSDPreferences): {
       if (typeof g.commit_docs === "boolean") git.commit_docs = g.commit_docs;
       else errors.push("git.commit_docs must be a boolean");
     }
+    if (g.worktree_post_create !== undefined) {
+      if (typeof g.worktree_post_create === "string" && g.worktree_post_create.trim()) {
+        git.worktree_post_create = g.worktree_post_create.trim();
+      } else {
+        errors.push("git.worktree_post_create must be a non-empty string (path to script)");
+      }
+    }
     // Deprecated: merge_to_main is ignored (branchless architecture).
     if (g.merge_to_main !== undefined) {
       warnings.push("git.merge_to_main is deprecated — milestone-level merge is now always used. Remove this setting.");

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

@@ -7,15 +7,17 @@
  * Templates live at prompts/ relative to this module's directory.
  * They use {{variableName}} syntax for substitution.
  *
- * Templates are cached on first read per session. This prevents a running
- * session from being invalidated when another `gsd` launch overwrites
- * ~/.gsd/agent/ 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.
+ * All templates are eagerly loaded into cache at module init via warmCache().
+ * This prevents a running session from being invalidated when another `gsd`
+ * launch overwrites ~/.gsd/agent/ with newer templates via initResources().
+ * Without eager 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 — especially for late-loading templates like complete-milestone
+ * that aren't read until the end of a long auto-mode run.
  */
 
-import { readFileSync } from "node:fs";
+import { readFileSync, readdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -23,10 +25,44 @@ const __extensionDir = dirname(fileURLToPath(import.meta.url));
 const promptsDir = join(__extensionDir, "prompts");
 const templatesDir = join(__extensionDir, "templates");
 
-// Cache templates on first read — a running session uses the template versions
-// that were on disk when it first loaded them, immune to later overwrites.
+// Cache all templates eagerly at module load — a running session uses the
+// template versions that were on disk at startup, immune to later overwrites.
 const templateCache = new Map<string, string>();
 
+/**
+ * Eagerly read all .md files from prompts/ and templates/ into cache.
+ * Called once at module init so that every template is snapshot before
+ * a concurrent initResources() can overwrite files on disk.
+ */
+function warmCache(): void {
+  try {
+    for (const file of readdirSync(promptsDir)) {
+      if (!file.endsWith(".md")) continue;
+      const name = file.slice(0, -3);
+      if (!templateCache.has(name)) {
+        templateCache.set(name, readFileSync(join(promptsDir, file), "utf-8"));
+      }
+    }
+  } catch {
+    // prompts/ may not exist in test environments — lazy loading still works
+  }
+
+  try {
+    for (const file of readdirSync(templatesDir)) {
+      if (!file.endsWith(".md")) continue;
+      const cacheKey = `tpl:${file.slice(0, -3)}`;
+      if (!templateCache.has(cacheKey)) {
+        templateCache.set(cacheKey, readFileSync(join(templatesDir, file), "utf-8"));
+      }
+    }
+  } catch {
+    // templates/ may not exist in test environments — lazy loading still works
+  }
+}
+
+// Snapshot all templates at module load time
+warmCache();
+
 /**
  * Load a prompt template and substitute variables.
  *

package/src/resources/extensions/gsd/prompts/execute-task.md

@@ -43,7 +43,7 @@ Then:
 9. If the task plan includes an Observability Impact section, verify those signals directly. Skip this step if the task plan omits the section.
 10. **If execution is running long or verification fails:**
 
-    **Context budget:** If you've used most of your context and haven't finished all steps, stop implementing and prioritize writing the task summary with clear notes on what's done and what remains. A partial summary that enables clean resumption is more valuable than one more half-finished step with no documentation. Never sacrifice summary quality for one more implementation step.
+    **Context budget:** You have approximately **{{verificationBudget}}** reserved for verification context. If you've used most of your context and haven't finished all steps, stop implementing and prioritize writing the task summary with clear notes on what's done and what remains. A partial summary that enables clean resumption is more valuable than one more half-finished step with no documentation. Never sacrifice summary quality for one more implementation step.
 
     **Debugging discipline:** If a verification check fails or implementation hits unexpected behavior:
     - Form a hypothesis first. State what you think is wrong and why, then test that specific theory. Don't shotgun-fix.
@@ -53,9 +53,9 @@ Then:
     - Know when to stop. If you've tried 3+ fixes without progress, your mental model is probably wrong. Stop. List what you know for certain. List what you've ruled out. Form fresh hypotheses from there.
     - Don't fix symptoms. Understand *why* something fails before changing code. A test that passes after a change you don't understand is luck, not a fix.
 11. **Blocker discovery:** If execution reveals that the remaining slice plan is fundamentally invalid — not just a bug or minor deviation, but a plan-invalidating finding like a wrong API, missing capability, or architectural mismatch — set `blocker_discovered: true` in the task summary frontmatter and describe the blocker clearly in the summary narrative. Do NOT set `blocker_discovered: true` for ordinary debugging, minor deviations, or issues that can be fixed within the current task or the remaining plan. This flag triggers an automatic replan of the slice.
-12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (use the **Decisions** output template from the inlined templates below if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
+12. If you made an architectural, pattern, library, or observability decision during this task that downstream work should know about, append it to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet). Not every task produces decisions — only append when a meaningful choice was made.
 13. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things.
-14. Use the **Task Summary** output template from the inlined templates below
+14. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
 15. Write `{{taskSummaryPath}}`
 16. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
 17. Do not commit manually — the system auto-commits your changes after this unit completes.
@@ -65,6 +65,4 @@ All work stays in your working directory: `{{workingDirectory}}`.
 
 **You MUST mark {{taskId}} as `[x]` in `{{planPath}}` AND write `{{taskSummaryPath}}` before finishing.**
 
-{{inlinedTemplates}}
-
 When done, say: "Task {{taskId}} complete."

package/src/resources/extensions/gsd/prompts/heal-skill.md

@@ -0,0 +1,45 @@
+## Skill Heal Analysis
+
+Analyze the just-completed unit ({{unitId}}) for skill drift.
+
+### Steps
+
+1. **Identify loaded skill**: Check which SKILL.md file was read during this unit by examining recent tool calls. If no skill was explicitly loaded (no `read` call to a SKILL.md path), write "No skill loaded — skipping heal analysis" to {{healArtifact}} and stop.
+
+2. **Read the skill**: Load the SKILL.md that was used during this unit.
+
+3. **Compare execution to skill guidance**: Review what the agent actually did vs what the skill recommended. Look for:
+   - API patterns the skill recommended that the agent did differently
+   - Error handling approaches the skill specified but the agent bypassed
+   - Conventions the skill documented that the agent ignored
+   - Outdated instructions in the skill that caused errors, retries, or workarounds
+   - Commands or tools the skill referenced that no longer exist or have changed
+
+4. **Assess drift severity**:
+   - **None**: Agent followed skill correctly → write "No drift detected" to {{healArtifact}} and stop
+   - **Minor**: Agent found a better approach but skill isn't wrong → append a note to `.gsd/KNOWLEDGE.md` and stop
+   - **Significant**: Skill has outdated or incorrect guidance → continue to step 5
+
+5. **If significant drift found**, append a heal suggestion to `.gsd/skill-review-queue.md`:
+
+```markdown
+### {{skillName}} (flagged {{date}})
+- **Unit:** {{unitId}}
+- **Issue:** {1-2 sentence description of what was wrong}
+- **Root cause:** {outdated API / incorrect pattern / missing context / etc.}
+- **Discovery method:** {how the agent discovered the skill was wrong — error message, trial and error, docs lookup, etc.}
+- **Proposed fix:**
+  - File: {relative path to the file in the skill directory}
+  - Section: {section heading or line range}
+  - Current: {quote the incorrect/outdated text}
+  - Suggested: {the corrected text}
+- **Action:** [ ] Reviewed [ ] Updated [ ] Dismissed
+```
+
+Then write a brief summary of the finding to {{healArtifact}}.
+
+**Critical rules:**
+- Do NOT modify any skill files directly. Only write to the review queue.
+- The SkillsBench research (Feb 2026) shows curated skills beat auto-generated ones by +16.2pp. Human review is what makes this valuable.
+- Keep the analysis focused — don't flag stylistic preferences, only genuine errors or outdated content.
+- If multiple issues found, write one entry per issue.

package/src/resources/extensions/gsd/prompts/plan-slice.md

@@ -26,9 +26,13 @@ Narrate your decomposition reasoning — why you're grouping work this way, what
 
 **Right-size the plan.** If the slice is simple enough to be 1 task, plan 1 task. Don't split into multiple tasks just because you can identify sub-steps. Don't fill in sections with "None" when the section doesn't apply — omit them entirely. The plan's job is to guide execution, not to fill a template.
 
+{{executorContextConstraints}}
+
 Then:
 0. If `REQUIREMENTS.md` was preloaded above, identify which Active requirements the roadmap says this slice owns or supports. These are the requirements this plan must deliver — every owned requirement needs at least one task that directly advances it, and verification must prove the requirement is met.
-1. Use the **Slice Plan** and **Task Plan** output templates from the inlined context above
+1. Read the templates:
+   - `~/.gsd/agent/extensions/gsd/templates/plan.md`
+   - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`
 2. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during planning, without overriding required plan formatting
 3. Define slice-level verification — the objective stopping condition for this slice:
    - For non-trivial slices: plan actual test files with real assertions. Name the files.