gsd-pi 2.17.0 → 2.19.0

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

@@ -0,0 +1,256 @@
+// GSD Extension — Dynamic Model Router
+// Maps complexity tiers to models, enforcing downgrade-only semantics.
+// The user's configured model is always the ceiling.
+
+import type { ComplexityTier, ClassificationResult } from "./complexity-classifier.js";
+import { tierOrdinal } from "./complexity-classifier.js";
+import type { ResolvedModelConfig } from "./preferences.js";
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface DynamicRoutingConfig {
+  enabled?: boolean;
+  tier_models?: {
+    light?: string;
+    standard?: string;
+    heavy?: string;
+  };
+  escalate_on_failure?: boolean;   // default: true
+  budget_pressure?: boolean;       // default: true
+  cross_provider?: boolean;        // default: true
+  hooks?: boolean;                 // default: true
+}
+
+export interface RoutingDecision {
+  /** The model ID to use (may be downgraded from configured) */
+  modelId: string;
+  /** Fallback chain: [selected_model, ...configured_fallbacks, configured_primary] */
+  fallbacks: string[];
+  /** The complexity tier that drove this decision */
+  tier: ComplexityTier;
+  /** True if the model was downgraded from the configured primary */
+  wasDowngraded: boolean;
+  /** Human-readable reason for this decision */
+  reason: string;
+}
+
+// ─── 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.
+
+const MODEL_CAPABILITY_TIER: Record<string, ComplexityTier> = {
+  // Light-tier models (cheapest)
+  "claude-haiku-4-5": "light",
+  "claude-3-5-haiku-latest": "light",
+  "claude-3-haiku-20240307": "light",
+  "gpt-4o-mini": "light",
+  "gemini-2.0-flash": "light",
+  "gemini-flash-2.0": "light",
+
+  // Standard-tier models
+  "claude-sonnet-4-6": "standard",
+  "claude-sonnet-4-5-20250514": "standard",
+  "claude-3-5-sonnet-latest": "standard",
+  "gpt-4o": "standard",
+  "gemini-2.5-pro": "standard",
+  "deepseek-chat": "standard",
+
+  // Heavy-tier models (most capable)
+  "claude-opus-4-6": "heavy",
+  "claude-3-opus-latest": "heavy",
+  "gpt-4-turbo": "heavy",
+  "o1": "heavy",
+  "o3": "heavy",
+};
+
+// ─── Cost Table (per 1K input tokens, approximate USD) ───────────────────────
+// Used for cross-provider cost comparison when multiple providers offer
+// the same capability tier.
+
+const MODEL_COST_PER_1K_INPUT: Record<string, number> = {
+  "claude-haiku-4-5": 0.0008,
+  "claude-3-5-haiku-latest": 0.0008,
+  "claude-sonnet-4-6": 0.003,
+  "claude-sonnet-4-5-20250514": 0.003,
+  "claude-opus-4-6": 0.015,
+  "gpt-4o-mini": 0.00015,
+  "gpt-4o": 0.0025,
+  "gemini-2.0-flash": 0.0001,
+  "gemini-2.5-pro": 0.00125,
+  "deepseek-chat": 0.00014,
+};
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the model to use for a given complexity tier.
+ *
+ * Downgrade-only: the returned model is always equal to or cheaper than
+ * the user's configured primary model. Never upgrades beyond configuration.
+ *
+ * @param classification  The complexity classification result
+ * @param phaseConfig     The user's configured model for this phase (ceiling)
+ * @param routingConfig   Dynamic routing configuration
+ * @param availableModelIds  List of available model IDs (from registry)
+ */
+export function resolveModelForComplexity(
+  classification: ClassificationResult,
+  phaseConfig: ResolvedModelConfig | undefined,
+  routingConfig: DynamicRoutingConfig,
+  availableModelIds: string[],
+): RoutingDecision {
+  // If no phase config or routing disabled, pass through
+  if (!phaseConfig || !routingConfig.enabled) {
+    return {
+      modelId: phaseConfig?.primary ?? "",
+      fallbacks: phaseConfig?.fallbacks ?? [],
+      tier: classification.tier,
+      wasDowngraded: false,
+      reason: "dynamic routing disabled or no phase config",
+    };
+  }
+
+  const configuredPrimary = phaseConfig.primary;
+  const configuredTier = getModelTier(configuredPrimary);
+  const requestedTier = classification.tier;
+
+  // Downgrade-only: if requested tier >= configured tier, no change
+  if (tierOrdinal(requestedTier) >= tierOrdinal(configuredTier)) {
+    return {
+      modelId: configuredPrimary,
+      fallbacks: phaseConfig.fallbacks,
+      tier: requestedTier,
+      wasDowngraded: false,
+      reason: `tier ${requestedTier} >= configured ${configuredTier}`,
+    };
+  }
+
+  // Find the best model for the requested tier
+  const targetModelId = findModelForTier(
+    requestedTier,
+    routingConfig,
+    availableModelIds,
+    routingConfig.cross_provider !== false,
+  );
+
+  if (!targetModelId) {
+    // No suitable model found — use configured primary
+    return {
+      modelId: configuredPrimary,
+      fallbacks: phaseConfig.fallbacks,
+      tier: requestedTier,
+      wasDowngraded: false,
+      reason: `no ${requestedTier}-tier model available`,
+    };
+  }
+
+  // Build fallback chain: [downgraded_model, ...configured_fallbacks, configured_primary]
+  const fallbacks = [
+    ...phaseConfig.fallbacks.filter(f => f !== targetModelId),
+    configuredPrimary,
+  ].filter(f => f !== targetModelId);
+
+  return {
+    modelId: targetModelId,
+    fallbacks,
+    tier: requestedTier,
+    wasDowngraded: true,
+    reason: classification.reason,
+  };
+}
+
+/**
+ * Escalate to the next tier after a failure.
+ * Returns the new tier, or null if already at heavy (max).
+ */
+export function escalateTier(currentTier: ComplexityTier): ComplexityTier | null {
+  switch (currentTier) {
+    case "light": return "standard";
+    case "standard": return "heavy";
+    case "heavy": return null;
+  }
+}
+
+/**
+ * Get the default routing config (all features enabled).
+ */
+export function defaultRoutingConfig(): DynamicRoutingConfig {
+  return {
+    enabled: false,
+    escalate_on_failure: true,
+    budget_pressure: true,
+    cross_provider: true,
+    hooks: true,
+  };
+}
+
+// ─── Internal ────────────────────────────────────────────────────────────────
+
+function getModelTier(modelId: string): ComplexityTier {
+  // Strip provider prefix if present
+  const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
+
+  // Check exact match first
+  if (MODEL_CAPABILITY_TIER[bareId]) return MODEL_CAPABILITY_TIER[bareId];
+
+  // Check if any known model ID is a prefix/suffix match
+  for (const [knownId, tier] of Object.entries(MODEL_CAPABILITY_TIER)) {
+    if (bareId.includes(knownId) || knownId.includes(bareId)) return tier;
+  }
+
+  // Unknown models are assumed heavy (safest assumption)
+  return "heavy";
+}
+
+function findModelForTier(
+  tier: ComplexityTier,
+  config: DynamicRoutingConfig,
+  availableModelIds: string[],
+  crossProvider: boolean,
+): string | null {
+  // 1. Check explicit tier_models config
+  const explicitModel = config.tier_models?.[tier];
+  if (explicitModel && availableModelIds.includes(explicitModel)) {
+    return explicitModel;
+  }
+  // Also check with provider prefix stripped
+  if (explicitModel) {
+    const match = availableModelIds.find(id => {
+      const bareAvail = id.includes("/") ? id.split("/").pop()! : id;
+      const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel;
+      return bareAvail === bareExplicit;
+    });
+    if (match) return match;
+  }
+
+  // 2. Auto-detect: find the cheapest available model in the requested tier
+  const candidates = availableModelIds
+    .filter(id => {
+      const modelTier = getModelTier(id);
+      return modelTier === tier;
+    })
+    .sort((a, b) => {
+      if (!crossProvider) return 0;
+      const costA = getModelCost(a);
+      const costB = getModelCost(b);
+      return costA - costB;
+    });
+
+  return candidates[0] ?? null;
+}
+
+function getModelCost(modelId: string): number {
+  const bareId = modelId.includes("/") ? modelId.split("/").pop()! : modelId;
+
+  if (MODEL_COST_PER_1K_INPUT[bareId] !== undefined) {
+    return MODEL_COST_PER_1K_INPUT[bareId];
+  }
+
+  // Check partial matches
+  for (const [knownId, cost] of Object.entries(MODEL_COST_PER_1K_INPUT)) {
+    if (bareId.includes(knownId) || knownId.includes(bareId)) return cost;
+  }
+
+  // Unknown cost — assume expensive to avoid routing to unknown cheap models
+  return 999;
+}

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

@@ -15,6 +15,9 @@ import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js"
 
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 
+/** Max entries before eviction. Prevents unbounded growth in long sessions (#611). */
+const DIR_CACHE_MAX = 200;
+
 const dirEntryCache = new Map<string, Dirent[]>();
 const dirListCache = new Map<string, string[]>();
 
@@ -85,6 +88,7 @@ function cachedReaddirWithTypes(dirPath: string): Dirent[] {
           d.isSocket = () => false;
           return d;
         });
+        if (dirEntryCache.size >= DIR_CACHE_MAX) dirEntryCache.clear();
         dirEntryCache.set(dirPath, dirents);
         return dirents;
       }
@@ -92,6 +96,7 @@ function cachedReaddirWithTypes(dirPath: string): Dirent[] {
   }
 
   const entries = readdirSync(dirPath, { withFileTypes: true });
+  if (dirEntryCache.size >= DIR_CACHE_MAX) dirEntryCache.clear();
   dirEntryCache.set(dirPath, entries);
   return entries;
 }
@@ -107,6 +112,7 @@ function cachedReaddir(dirPath: string): string[] {
       const treeEntries = nativeTreeCache.get(key);
       if (treeEntries) {
         const names = treeEntries.map(e => e.name);
+        if (dirListCache.size >= DIR_CACHE_MAX) dirListCache.clear();
         dirListCache.set(dirPath, names);
         return names;
       }
@@ -114,6 +120,7 @@ function cachedReaddir(dirPath: string): string[] {
   }
 
   const entries = readdirSync(dirPath);
+  if (dirListCache.size >= DIR_CACHE_MAX) dirListCache.clear();
   dirListCache.set(dirPath, entries);
   return entries;
 }
@@ -248,6 +255,7 @@ export const GSD_ROOT_FILES = {
   STATE: "STATE.md",
   REQUIREMENTS: "REQUIREMENTS.md",
   OVERRIDES: "OVERRIDES.md",
+  KNOWLEDGE: "KNOWLEDGE.md",
 } as const;
 
 export type GSDRootFileKey = keyof typeof GSD_ROOT_FILES;
@@ -259,6 +267,7 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
   STATE: "state.md",
   REQUIREMENTS: "requirements.md",
   OVERRIDES: "overrides.md",
+  KNOWLEDGE: "knowledge.md",
 };
 
 export function gsdRoot(basePath: string): string {

package/dist/resources/extensions/gsd/post-unit-hooks.ts

@@ -60,7 +60,8 @@ export function checkPostUnitHooks(
   }
 
   // Don't trigger hooks for other hook units (prevent hook-on-hook chains)
-  if (completedUnitType.startsWith("hook/")) return null;
+  // Don't trigger hooks for triage units (prevent hook-on-triage chains)
+  if (completedUnitType.startsWith("hook/") || completedUnitType === "triage-captures") return null;
 
   // Check if any hooks are configured for this unit type
   const hooks = resolvePostUnitHooks().filter(h =>

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

@@ -1,9 +1,11 @@
-import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, join } from "node:path";
 import { getAgentDir } from "@gsd/pi-coding-agent";
 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");
@@ -36,8 +38,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 {
@@ -128,8 +132,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 {
@@ -674,6 +680,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 ?? {};
@@ -780,6 +800,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 ?? {}) }
@@ -1100,6 +1123,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> = {};
@@ -1252,3 +1325,61 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
   return (prefs?.preferences.pre_dispatch_hooks ?? [])
     .filter(h => h.enabled !== false);
 }
+
+/**
+ * Validate a model ID string.
+ * Returns true if the ID looks like a valid model identifier.
+ */
+export function validateModelId(modelId: string): boolean {
+  if (!modelId || typeof modelId !== "string") return false;
+  const trimmed = modelId.trim();
+  if (trimmed.length === 0 || trimmed.length > 256) return false;
+  // Allow alphanumeric, hyphens, underscores, dots, slashes, colons
+  return /^[a-zA-Z0-9\-_./:]+$/.test(trimmed);
+}
+
+/**
+ * Update the models section of the global GSD preferences file.
+ * Performs a safe read-modify-write: reads current content, updates the models
+ * YAML block, and writes back. Creates the file if it doesn't exist.
+ */
+export function updatePreferencesModels(models: GSDModelConfigV2): void {
+  const prefsPath = getGlobalGSDPreferencesPath();
+
+  let content = "";
+  if (existsSync(prefsPath)) {
+    content = readFileSync(prefsPath, "utf-8");
+  }
+
+  // Build the new models block
+  const lines: string[] = ["models:"];
+  for (const [phase, value] of Object.entries(models)) {
+    if (typeof value === "string") {
+      lines.push(`  ${phase}: ${value}`);
+    } else if (value && typeof value === "object") {
+      const config = value as GSDPhaseModelConfig;
+      lines.push(`  ${phase}:`);
+      lines.push(`    model: ${config.model}`);
+      if (config.provider) {
+        lines.push(`    provider: ${config.provider}`);
+      }
+      if (config.fallbacks && config.fallbacks.length > 0) {
+        lines.push(`    fallbacks:`);
+        for (const fb of config.fallbacks) {
+          lines.push(`      - ${fb}`);
+        }
+      }
+    }
+  }
+  const modelsBlock = lines.join("\n");
+
+  // Replace existing models block or append
+  const modelsRegex = /^models:[\s\S]*?(?=\n[a-z_]|\n*$)/m;
+  if (modelsRegex.test(content)) {
+    content = content.replace(modelsRegex, modelsBlock);
+  } else {
+    content = content.trimEnd() + "\n\n" + modelsBlock + "\n";
+  }
+
+  writeFileSync(prefsPath, content, "utf-8");
+}

package/dist/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/dist/resources/extensions/gsd/prompts/execute-task.md

@@ -54,11 +54,12 @@ Then:
     - 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.
-13. Use the **Task Summary** output template from the inlined templates below
-14. Write `{{taskSummaryPath}}`
-15. Mark {{taskId}} done in `{{planPath}}` (change `[ ]` to `[x]`)
-16. Do not commit manually — the system auto-commits your changes after this unit completes.
-17. Update `.gsd/STATE.md`
+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
+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.
+18. Update `.gsd/STATE.md`
 
 All work stays in your working directory: `{{workingDirectory}}`.
 

package/dist/resources/extensions/gsd/prompts/reassess-roadmap.md

@@ -16,6 +16,12 @@ All relevant context has been preloaded below — the current roadmap, completed
 
 {{inlinedContext}}
 
+## Deferred Captures
+
+The following user thoughts were captured during execution and deferred to future slices during triage. Consider whether any should influence the remaining roadmap:
+
+{{deferredCaptures}}
+
 If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during reassessment, without relaxing required verification or artifact rules.
 
 Then assess whether the remaining roadmap still makes sense given what was just built.

package/dist/resources/extensions/gsd/prompts/replan-slice.md

@@ -12,6 +12,14 @@ All relevant context has been preloaded below — the roadmap, current slice pla
 
 {{inlinedContext}}
 
+## Capture Context
+
+The following user-captured thoughts triggered or informed this replan:
+
+{{captureContext}}
+
+Consider these captures when rewriting the remaining tasks — they represent the user's real-time insights about what needs to change.
+
 ## Hard Constraints
 
 - **Do NOT renumber or remove completed tasks.** All `[x]` tasks and their IDs must remain exactly as they are in the plan.

package/dist/resources/extensions/gsd/prompts/system.md

@@ -65,6 +65,7 @@ Titles live inside file content (headings, frontmatter), not in file or director
   PROJECT.md            (living doc - what the project is right now)
   REQUIREMENTS.md       (requirement contract - tracks active/validated/deferred/out-of-scope)
   DECISIONS.md          (append-only register of architectural and pattern decisions)
+  KNOWLEDGE.md          (append-only register of project-specific rules, patterns, and lessons learned)
   OVERRIDES.md          (user-issued overrides that supersede plan content via /gsd steer)
   QUEUE.md              (append-only log of queued milestones via /gsd queue)
   STATE.md
@@ -100,6 +101,7 @@ All auto-mode work happens inside a worktree at `.gsd/worktrees/<MID>/`. This is
 - **PROJECT.md** is a living document describing what the project is right now - current state only, updated at slice completion when stale
 - **REQUIREMENTS.md** tracks the requirement contract — requirements move between Active, Validated, Deferred, Blocked, and Out of Scope as slices prove or invalidate them. Update at slice completion when evidence supports a status change.
 - **DECISIONS.md** is an append-only register of architectural and pattern decisions - read it during planning/research, append to it during execution when a meaningful decision is made
+- **KNOWLEDGE.md** is an append-only register of project-specific rules, patterns, and lessons learned. Read it at the start of every unit. Append to it when you discover a recurring issue, a non-obvious pattern, or a rule that future agents should follow.
 - **CONTEXT.md** files (milestone or slice level) capture the brief — scope, goals, constraints, and key decisions from discussion. When present, they are the authoritative source for what a milestone or slice is trying to achieve. Read them before planning or executing.
 - **Milestones** are major project phases (M001, M002, ...)
 - **Slices** are demoable vertical increments (S01, S02, ...) ordered by risk. After each slice completes, the roadmap is reassessed before the next slice begins.