gsd-pi 2.11.0 → 2.13.0

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

@@ -3,6 +3,7 @@ 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 } from "./types.js";
 import { VALID_BRANCH_NAME } from "./git-service.js";
 
 const GLOBAL_PREFERENCES_PATH = join(homedir(), ".gsd", "preferences.md");
@@ -93,6 +94,8 @@ export interface GSDPreferences {
   budget_ceiling?: number;
   remote_questions?: RemoteQuestionsConfig;
   git?: GitPreferences;
+  post_unit_hooks?: PostUnitHookConfig[];
+  pre_dispatch_hooks?: PreDispatchHookConfig[];
 }
 
 export interface LoadedGSDPreferences {
@@ -626,10 +629,12 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     git: (base.git || override.git)
       ? { ...(base.git ?? {}), ...(override.git ?? {}) }
       : 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),
   };
 }
 
-function validatePreferences(preferences: GSDPreferences): {
+export function validatePreferences(preferences: GSDPreferences): {
   preferences: GSDPreferences;
   errors: string[];
 } {
@@ -713,6 +718,138 @@ function validatePreferences(preferences: GSDPreferences): {
     }
   }
 
+  // ─── Post-Unit Hooks ─────────────────────────────────────────────────
+  if (preferences.post_unit_hooks && Array.isArray(preferences.post_unit_hooks)) {
+    const validHooks: PostUnitHookConfig[] = [];
+    const seenNames = new Set<string>();
+    const knownUnitTypes = new Set([
+      "research-milestone", "plan-milestone", "research-slice", "plan-slice",
+      "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+      "run-uat", "fix-merge", "complete-milestone",
+    ]);
+    for (const hook of preferences.post_unit_hooks) {
+      if (!hook || typeof hook !== "object") {
+        errors.push("post_unit_hooks entry must be an object");
+        continue;
+      }
+      const name = typeof hook.name === "string" ? hook.name.trim() : "";
+      if (!name) {
+        errors.push("post_unit_hooks entry missing name");
+        continue;
+      }
+      if (seenNames.has(name)) {
+        errors.push(`duplicate post_unit_hooks name: ${name}`);
+        continue;
+      }
+      const after = normalizeStringList(hook.after);
+      if (after.length === 0) {
+        errors.push(`post_unit_hooks "${name}" missing after`);
+        continue;
+      }
+      for (const ut of after) {
+        if (!knownUnitTypes.has(ut)) {
+          errors.push(`post_unit_hooks "${name}" unknown unit type in after: ${ut}`);
+        }
+      }
+      const prompt = typeof hook.prompt === "string" ? hook.prompt.trim() : "";
+      if (!prompt) {
+        errors.push(`post_unit_hooks "${name}" missing prompt`);
+        continue;
+      }
+      const validHook: PostUnitHookConfig = { name, after, prompt };
+      if (hook.max_cycles !== undefined) {
+        const mc = typeof hook.max_cycles === "number" ? hook.max_cycles : Number(hook.max_cycles);
+        validHook.max_cycles = Number.isFinite(mc) ? Math.max(1, Math.min(10, Math.round(mc))) : 1;
+      }
+      if (typeof hook.model === "string" && hook.model.trim()) {
+        validHook.model = hook.model.trim();
+      }
+      if (typeof hook.artifact === "string" && hook.artifact.trim()) {
+        validHook.artifact = hook.artifact.trim();
+      }
+      if (typeof hook.retry_on === "string" && hook.retry_on.trim()) {
+        validHook.retry_on = hook.retry_on.trim();
+      }
+      if (typeof hook.agent === "string" && hook.agent.trim()) {
+        validHook.agent = hook.agent.trim();
+      }
+      if (hook.enabled !== undefined) {
+        validHook.enabled = !!hook.enabled;
+      }
+      seenNames.add(name);
+      validHooks.push(validHook);
+    }
+    if (validHooks.length > 0) {
+      validated.post_unit_hooks = validHooks;
+    }
+  }
+
+  // ─── Pre-Dispatch Hooks ─────────────────────────────────────────────────
+  if (preferences.pre_dispatch_hooks && Array.isArray(preferences.pre_dispatch_hooks)) {
+    const validPreHooks: PreDispatchHookConfig[] = [];
+    const seenPreNames = new Set<string>();
+    const knownUnitTypes = new Set([
+      "research-milestone", "plan-milestone", "research-slice", "plan-slice",
+      "execute-task", "complete-slice", "replan-slice", "reassess-roadmap",
+      "run-uat", "fix-merge", "complete-milestone",
+    ]);
+    const validActions = new Set(["modify", "skip", "replace"]);
+    for (const hook of preferences.pre_dispatch_hooks) {
+      if (!hook || typeof hook !== "object") {
+        errors.push("pre_dispatch_hooks entry must be an object");
+        continue;
+      }
+      const name = typeof hook.name === "string" ? hook.name.trim() : "";
+      if (!name) {
+        errors.push("pre_dispatch_hooks entry missing name");
+        continue;
+      }
+      if (seenPreNames.has(name)) {
+        errors.push(`duplicate pre_dispatch_hooks name: ${name}`);
+        continue;
+      }
+      const before = normalizeStringList(hook.before);
+      if (before.length === 0) {
+        errors.push(`pre_dispatch_hooks "${name}" missing before`);
+        continue;
+      }
+      for (const ut of before) {
+        if (!knownUnitTypes.has(ut)) {
+          errors.push(`pre_dispatch_hooks "${name}" unknown unit type in before: ${ut}`);
+        }
+      }
+      const action = typeof hook.action === "string" ? hook.action.trim() : "";
+      if (!validActions.has(action)) {
+        errors.push(`pre_dispatch_hooks "${name}" invalid action: ${action} (must be modify, skip, or replace)`);
+        continue;
+      }
+      const validHook: PreDispatchHookConfig = { name, before, action: action as PreDispatchHookConfig["action"] };
+      if (typeof hook.prepend === "string" && hook.prepend.trim()) validHook.prepend = hook.prepend.trim();
+      if (typeof hook.append === "string" && hook.append.trim()) validHook.append = hook.append.trim();
+      if (typeof hook.prompt === "string" && hook.prompt.trim()) validHook.prompt = hook.prompt.trim();
+      if (typeof hook.unit_type === "string" && hook.unit_type.trim()) validHook.unit_type = hook.unit_type.trim();
+      if (typeof hook.skip_if === "string" && hook.skip_if.trim()) validHook.skip_if = hook.skip_if.trim();
+      if (typeof hook.model === "string" && hook.model.trim()) validHook.model = hook.model.trim();
+      if (hook.enabled !== undefined) validHook.enabled = !!hook.enabled;
+
+      // Validation: action-specific required fields
+      if (action === "replace" && !validHook.prompt) {
+        errors.push(`pre_dispatch_hooks "${name}" action "replace" requires prompt`);
+        continue;
+      }
+      if (action === "modify" && !validHook.prepend && !validHook.append) {
+        errors.push(`pre_dispatch_hooks "${name}" action "modify" requires prepend or append`);
+        continue;
+      }
+
+      seenPreNames.add(name);
+      validPreHooks.push(validHook);
+    }
+    if (validPreHooks.length > 0) {
+      validated.pre_dispatch_hooks = validPreHooks;
+    }
+  }
+
   // ─── Git Preferences ───────────────────────────────────────────────────
   if (preferences.git && typeof preferences.git === "object") {
     const git: Record<string, unknown> = {};
@@ -768,6 +905,22 @@ function validatePreferences(preferences: GSDPreferences): {
         errors.push("git.main_branch must be a valid branch name (alphanumeric, _, -, /, .)");
       }
     }
+    if (g.isolation !== undefined) {
+      const validIsolation = new Set(["worktree", "branch"]);
+      if (typeof g.isolation === "string" && validIsolation.has(g.isolation)) {
+        git.isolation = g.isolation as "worktree" | "branch";
+      } else {
+        errors.push("git.isolation must be one of: worktree, branch");
+      }
+    }
+    if (g.merge_to_main !== undefined) {
+      const validMergeToMain = new Set(["milestone", "slice"]);
+      if (typeof g.merge_to_main === "string" && validMergeToMain.has(g.merge_to_main)) {
+        git.merge_to_main = g.merge_to_main as "milestone" | "slice";
+      } else {
+        errors.push("git.merge_to_main must be one of: milestone, slice");
+      }
+    }
 
     if (Object.keys(git).length > 0) {
       validated.git = git as GitPreferences;
@@ -794,3 +947,58 @@ function normalizeStringList(value: unknown): string[] {
     .map((item) => item.trim())
     .filter(Boolean);
 }
+
+function mergePostUnitHooks(
+  base?: PostUnitHookConfig[],
+  override?: PostUnitHookConfig[],
+): PostUnitHookConfig[] | undefined {
+  if (!base?.length && !override?.length) return undefined;
+  const merged = [...(base ?? [])];
+  for (const hook of override ?? []) {
+    // Override hooks with same name replace base hooks
+    const idx = merged.findIndex(h => h.name === hook.name);
+    if (idx >= 0) {
+      merged[idx] = hook;
+    } else {
+      merged.push(hook);
+    }
+  }
+  return merged.length > 0 ? merged : undefined;
+}
+
+/**
+ * Resolve enabled post-unit hooks from effective preferences.
+ * Returns an empty array when no hooks are configured.
+ */
+export function resolvePostUnitHooks(): PostUnitHookConfig[] {
+  const prefs = loadEffectiveGSDPreferences();
+  return (prefs?.preferences.post_unit_hooks ?? [])
+    .filter(h => h.enabled !== false);
+}
+
+function mergePreDispatchHooks(
+  base?: PreDispatchHookConfig[],
+  override?: PreDispatchHookConfig[],
+): PreDispatchHookConfig[] | undefined {
+  if (!base?.length && !override?.length) return undefined;
+  const merged = [...(base ?? [])];
+  for (const hook of override ?? []) {
+    const idx = merged.findIndex(h => h.name === hook.name);
+    if (idx >= 0) {
+      merged[idx] = hook;
+    } else {
+      merged.push(hook);
+    }
+  }
+  return merged.length > 0 ? merged : undefined;
+}
+
+/**
+ * Resolve enabled pre-dispatch hooks from effective preferences.
+ * Returns an empty array when no hooks are configured.
+ */
+export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
+  const prefs = loadEffectiveGSDPreferences();
+  return (prefs?.preferences.pre_dispatch_hooks ?? [])
+    .filter(h => h.enabled !== false);
+}

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

@@ -19,7 +19,9 @@ import { readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const promptsDir = join(dirname(fileURLToPath(import.meta.url)), "prompts");
+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.
@@ -63,3 +65,28 @@ export function loadPrompt(name: string, vars: Record<string, string> = {}): str
 
   return content.trim();
 }
+
+/**
+ * Load a raw template file from the templates/ directory.
+ * Cached with a `tpl:` prefix to avoid collisions with prompt cache keys.
+ */
+export function loadTemplate(name: string): string {
+  const cacheKey = `tpl:${name}`;
+  let content = templateCache.get(cacheKey);
+  if (content === undefined) {
+    const path = join(templatesDir, `${name}.md`);
+    content = readFileSync(path, "utf-8");
+    templateCache.set(cacheKey, content);
+  }
+  return content.trim();
+}
+
+/**
+ * Load a template and wrap it with a labeled footer for inlining into prompts.
+ * The template body is emitted first so that any YAML frontmatter (---) remains
+ * at the first non-whitespace line of the template content.
+ */
+export function inlineTemplate(name: string, label: string): string {
+  const content = loadTemplate(name);
+  return `${content}\n\n### Output Template: ${label}\nSource: \`templates/${name}.md\``;
+}

package/dist/resources/extensions/gsd/prompts/complete-milestone.md

@@ -7,7 +7,7 @@ All relevant context has been preloaded below — the roadmap, all slice summari
 {{inlinedContext}}
 
 Then:
-1. Read the milestone-summary template at `~/.gsd/agent/extensions/gsd/templates/milestone-summary.md`
+1. Use the **Milestone Summary** output template from the inlined context above
 2. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
 3. Verify each **success criterion** from the milestone definition in `{{roadmapPath}}`. For each criterion, confirm it was met with specific evidence from slice summaries, test results, or observable behavior. List any criterion that was NOT met.
 4. Verify the milestone's **definition of done** — all slices are `[x]`, all slice summaries exist, and any cross-slice integration points work correctly.

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

@@ -9,9 +9,7 @@ All relevant context has been preloaded below — the slice plan, all task summa
 **Match effort to complexity.** A simple slice with 1-2 tasks needs a brief summary and lightweight verification. A complex slice with 5 tasks across multiple subsystems needs thorough verification and a detailed summary. Scale the work below accordingly.
 
 Then:
-1. Read the templates:
-   - `~/.gsd/agent/extensions/gsd/templates/slice-summary.md`
-   - `~/.gsd/agent/extensions/gsd/templates/uat.md`
+1. Use the **Slice Summary** and **UAT** output templates from the inlined context above
 2. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules
 3. Run all slice-level verification checks defined in the slice plan. All must pass before marking the slice done. If any fail, fix them first.
 4. If the slice plan includes observability/diagnostic surfaces, confirm they work. Skip this for simple slices that don't have observability sections.

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

@@ -186,14 +186,14 @@ Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside file co
 
 Once the user is satisfied, in a single pass:
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
-2. Write or update `.gsd/PROJECT.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/project.md` first. Describe what the project is, its current state, and list the milestone sequence.
-3. Write or update `.gsd/REQUIREMENTS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/requirements.md` first. Confirm requirement states, ownership, and traceability before roadmap creation.
+2. Write or update `.gsd/PROJECT.md` — use the **Project** output template below. Describe what the project is, its current state, and list the milestone sequence.
+3. Write or update `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Confirm requirement states, ownership, and traceability before roadmap creation.
 **Depth-Preservation Guidance for context.md:**
 When writing context.md, preserve the user's exact terminology, emphasis, and specific framing from the discussion. Do not paraphrase user nuance into generic summaries. If the user said "craft feel," write "craft feel" — not "high-quality user experience." If they emphasized a specific constraint or negative requirement, carry that emphasis through verbatim. The context file is downstream agents' only window into this conversation — flattening specifics into generics loses the signal that shaped every decision.
 
-4. Write `{{contextPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/context.md` first. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
-5. Write `{{roadmapPath}}` — read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md` first. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
-6. Seed `.gsd/DECISIONS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` first. Append rows for any architectural or pattern decisions made during discussion.
+4. Write `{{contextPath}}` — use the **Context** output template below. Preserve key risks, unknowns, existing codebase constraints, integration points, and relevant requirements surfaced during discussion.
+5. Write `{{roadmapPath}}` — use the **Roadmap** output template below. Decompose into demoable vertical slices with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, requirement coverage, and a boundary map. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment.
+6. Seed `.gsd/DECISIONS.md` — use the **Decisions** output template below. Append rows for any architectural or pattern decisions made during discussion.
 7. Update `.gsd/STATE.md`
 8. Commit: `docs({{milestoneId}}): context, requirements, and roadmap`
 
@@ -206,9 +206,9 @@ Once the user confirms the milestone split:
 #### Phase 1: Shared artifacts
 
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices` for each milestone
-2. Write `.gsd/PROJECT.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/project.md` first.
-3. Write `.gsd/REQUIREMENTS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/requirements.md` first. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
-4. Seed `.gsd/DECISIONS.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` first.
+2. Write `.gsd/PROJECT.md` — use the **Project** output template below.
+3. Write `.gsd/REQUIREMENTS.md` — use the **Requirements** output template below. Capture Active, Deferred, Out of Scope, and any already Validated requirements. Later milestones may have provisional ownership where slice plans do not exist yet.
+4. Seed `.gsd/DECISIONS.md` — use the **Decisions** output template below.
 
 #### Phase 2: Primary milestone
 
@@ -233,3 +233,5 @@ Each context file (full or draft) should be rich enough that a future agent enco
 8. Commit: `docs: project plan — N milestones` (replace N with the actual milestone count)
 
 After writing the files and committing, say exactly: "Milestone M001 ready." — nothing else. Auto-mode will start automatically.
+
+{{inlinedTemplates}}

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

@@ -47,8 +47,8 @@ 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` (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. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
+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.
@@ -58,4 +58,6 @@ You are on the slice branch. All work stays here.
 
 **You MUST mark {{taskId}} as `[x]` in `{{planPath}}` AND write `{{taskSummaryPath}}` before finishing.**
 
+{{inlinedTemplates}}
+
 When done, say: "Task {{taskId}} complete."

package/dist/resources/extensions/gsd/prompts/guided-complete-slice.md

@@ -1 +1,3 @@
-Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. All tasks are done. Read the templates at `~/.gsd/agent/extensions/gsd/templates/slice-summary.md` and `uat.md`. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.gsd/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update STATE.md, update milestone summary, and leave the slice branch clean for the extension to squash-merge back into the integration branch automatically.
+Complete slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. All tasks are done. Use the **Slice Summary** and **UAT** output templates below. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during completion, without relaxing required verification or artifact rules. Write `{{sliceId}}-SUMMARY.md` (compress task summaries), write `{{sliceId}}-UAT.md`, and fill the `UAT Type` plus `Not Proven By This UAT` sections explicitly so the artifact states what class of acceptance it covers and what still remains unproven. Review task summaries for `key_decisions` and ensure any significant ones are in `.gsd/DECISIONS.md`. Mark the slice checkbox done in the roadmap, update STATE.md, update milestone summary, and leave the slice branch clean for the extension to squash-merge back into the integration branch automatically.
+
+{{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -1,3 +1,5 @@
-Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Read the template at `~/.gsd/agent/extensions/gsd/templates/context.md` first. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
+Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify gray areas, ask the user about them, and write `{{milestoneId}}-CONTEXT.md` in the milestone directory with the decisions. Use the **Context** output template below. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules.
+
+{{inlinedTemplates}}
 
 **Investigate between question rounds to make your questions smarter.** Before each round of questions, do enough lightweight research that your questions are grounded in reality — not guesses about what exists or what's possible. Check library docs (`resolve_library`/`get_library_docs`) when tech choices are relevant, search the web (`search-the-web` with `freshness`/`domain` filters, then `fetch_page` for full content) to verify the landscape, scout the codebase (`rg`, `find`, `scout`) to understand what already exists. Don't go deep — just enough that your next question reflects what's actually true. The goal is to ask questions the user can't answer by saying "did you check the docs?" or "look at the code."

package/dist/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -45,7 +45,7 @@ If the user wants to keep going, keep asking. Stop when they say wrap up.
 
 Once the user is ready to wrap up:
 
-1. Read the slice context template at `~/.gsd/agent/extensions/gsd/templates/slice-context.md`
+1. Use the **Slice Context** output template below
 2. `mkdir -p {{sliceDirPath}}`
 3. Write `{{contextPath}}` — use the template structure, filling in:
    - **Goal** — one sentence: what this slice delivers
@@ -57,3 +57,5 @@ Once the user is ready to wrap up:
    - **Open Questions** — anything still unresolved, with current thinking
 4. Commit: `git -C {{projectRoot}} add {{contextPath}} && git -C {{projectRoot}} commit -m "docs({{milestoneId}}/{{sliceId}}): slice context from discuss"`
 5. Say exactly: `"{{sliceId}} context written."` — nothing else.
+
+{{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/guided-execute-task.md

@@ -1 +1,3 @@
-Execute the next task: {{taskId}} ("{{taskTitle}}") in slice {{sliceId}} of milestone {{milestoneId}}. Read the task plan (`{{taskId}}-PLAN.md`), load relevant summaries from prior tasks, and execute each step. Verify must-haves when done. If the task touches UI, browser flows, DOM behavior, or user-visible web state, exercise the real flow in the browser, prefer `browser_batch` for obvious sequences, prefer `browser_assert` for explicit pass/fail verification, use `browser_diff` when an action's effect is ambiguous, and use browser diagnostics when validating async or failure-prone UI. If you made an architectural, pattern, or library decision, append it to `.gsd/DECISIONS.md`. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`. Write `{{taskId}}-SUMMARY.md`, mark it done, commit, and advance. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules. If running long and not all steps are finished, stop implementing and prioritize writing a clean partial summary over attempting one more step — a recoverable handoff is more valuable than a half-finished step with no documentation. If verification fails, debug methodically: form a hypothesis and test that specific theory before changing anything, change one variable at a time, read entire functions not just the suspect line, distinguish observable facts from assumptions, and if 3+ fixes fail without progress stop and reassess your mental model — list what you know for certain, what you've ruled out, and form fresh hypotheses. Don't fix symptoms — understand why something fails before changing code.
+Execute the next task: {{taskId}} ("{{taskTitle}}") in slice {{sliceId}} of milestone {{milestoneId}}. Read the task plan (`{{taskId}}-PLAN.md`), load relevant summaries from prior tasks, and execute each step. Verify must-haves when done. If the task touches UI, browser flows, DOM behavior, or user-visible web state, exercise the real flow in the browser, prefer `browser_batch` for obvious sequences, prefer `browser_assert` for explicit pass/fail verification, use `browser_diff` when an action's effect is ambiguous, and use browser diagnostics when validating async or failure-prone UI. If you made an architectural, pattern, or library decision, append it to `.gsd/DECISIONS.md`. Use the **Task Summary** output template below. Write `{{taskId}}-SUMMARY.md`, mark it done, commit, and advance. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during execution, without relaxing required verification or artifact rules. If running long and not all steps are finished, stop implementing and prioritize writing a clean partial summary over attempting one more step — a recoverable handoff is more valuable than a half-finished step with no documentation. If verification fails, debug methodically: form a hypothesis and test that specific theory before changing anything, change one variable at a time, read entire functions not just the suspect line, distinguish observable facts from assumptions, and if 3+ fixes fail without progress stop and reassess your mental model — list what you know for certain, what you've ruled out, and form fresh hypotheses. Don't fix symptoms — understand why something fails before changing code.
+
+{{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/guided-plan-milestone.md

@@ -1,4 +1,4 @@
-Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists and treat Active requirements as the capability contract. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage. Read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md`. Create `{{milestoneId}}-ROADMAP.md` in the milestone directory with slices, risk levels, dependencies, demo sentences, verification classes, milestone definition of done, requirement coverage, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. If planning produces structural decisions, append them to `.gsd/DECISIONS.md`. 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 roadmap formatting.
+Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists and treat Active requirements as the capability contract. If `REQUIREMENTS.md` is missing, continue in legacy compatibility mode but explicitly note missing requirement coverage. Use the **Roadmap** output template below. Create `{{milestoneId}}-ROADMAP.md` in the milestone directory with slices, risk levels, dependencies, demo sentences, verification classes, milestone definition of done, requirement coverage, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment. If planning produces structural decisions, append them to `.gsd/DECISIONS.md`. 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 roadmap formatting.
 
 ## Requirement Rules
 
@@ -24,4 +24,6 @@ Plan milestone {{milestoneId}} ("{{milestoneTitle}}"). Read `.gsd/DECISIONS.md`
 
 ## Secret Forecasting
 
-After writing the roadmap, analyze the slices and their boundary maps for external service dependencies (third-party APIs, SaaS platforms, cloud providers, databases requiring credentials, OAuth providers, etc.). If this milestone requires any external API keys or secrets, read the template at `~/.gsd/agent/extensions/gsd/templates/secrets-manifest.md` for the expected format and write `{{secretsOutputPath}}` listing every predicted secret as an H3 section with the Service name, a direct Dashboard URL to the console page where the key is created, a Format hint showing what the key looks like, Status set to `pending`, and Destination (`dotenv`, `vercel`, or `convex`). Include numbered step-by-step guidance for obtaining each key. If this milestone does not require any external API keys or secrets, skip this step entirely — do not create an empty manifest.
+After writing the roadmap, analyze the slices and their boundary maps for external service dependencies (third-party APIs, SaaS platforms, cloud providers, databases requiring credentials, OAuth providers, etc.). If this milestone requires any external API keys or secrets, use the **Secrets Manifest** output template below for the expected format and write `{{secretsOutputPath}}` listing every predicted secret as an H3 section with the Service name, a direct Dashboard URL to the console page where the key is created, a Format hint showing what the key looks like, Status set to `pending`, and Destination (`dotenv`, `vercel`, or `convex`). Include numbered step-by-step guidance for obtaining each key. If this milestone does not require any external API keys or secrets, skip this step entirely — do not create an empty manifest.
+
+{{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/guided-plan-slice.md

@@ -1 +1,3 @@
-Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Read the templates at `~/.gsd/agent/extensions/gsd/templates/plan.md` and `task-plan.md`. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.gsd/decisions.md`. 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. Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.
+Plan slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements the roadmap says this slice owns or supports, and ensure the plan delivers them. Read the roadmap boundary map, any existing context/research files, and dependency summaries. Use the **Slice Plan** and **Task Plan** output templates below. Decompose into tasks with must-haves. Fill the `Proof Level` and `Integration Closure` sections truthfully so the plan says what class of proof this slice really delivers and what end-to-end wiring still remains. Write `{{sliceId}}-PLAN.md` and individual `T##-PLAN.md` files in the `tasks/` subdirectory. If planning produces structural decisions, append them to `.gsd/DECISIONS.md`. 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. Before committing, self-audit the plan: every must-have maps to at least one task, every task has complete sections (steps, must-haves, verification, observability impact, inputs, and expected output), task ordering is consistent with no circular references, every pair of artifacts that must connect has an explicit wiring step, task scope targets 2–5 steps and 3–8 files (6–8 steps or 8–10 files — consider splitting; 10+ steps or 12+ files — must split), the plan honors locked decisions from context/research/decisions artifacts, the proof-level wording does not overclaim live integration if only fixture/contract proof is planned, every Active requirement this slice owns has at least one task with verification that proves it is met, and every task produces real user-facing progress — if the slice has a UI surface at least one task builds the real UI, if it has an API at least one task connects it to a real data source, and showing the completed result to a non-technical stakeholder would demonstrate real product progress rather than developer artifacts.
+
+{{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/guided-research-slice.md

@@ -1,4 +1,4 @@
-Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules. Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs`. Read the template at `~/.gsd/agent/extensions/gsd/templates/research.md`. Write `{{sliceId}}-RESEARCH.md` in the slice directory with summary, don't-hand-roll, common pitfalls, and relevant code sections.
+Research slice {{sliceId}} ("{{sliceTitle}}") of milestone {{milestoneId}}. Read `.gsd/DECISIONS.md` if it exists — respect existing decisions, don't contradict them. Read `.gsd/REQUIREMENTS.md` if it exists — identify which Active requirements this slice owns or supports and target research toward risks, unknowns, and constraints that could affect delivery of those requirements. If a `GSD Skill Preferences` block is present in system context, use it to decide which skills to load and follow during research, without relaxing required verification or artifact rules. Explore the relevant code — use `rg`/`find` for targeted reads, or `scout` if the area is broad or unfamiliar. Check libraries with `resolve_library`/`get_library_docs`. Use the **Research** output template below. Write `{{sliceId}}-RESEARCH.md` in the slice directory with summary, don't-hand-roll, common pitfalls, and relevant code sections.
 
 ## Strategic Questions to Answer
 
@@ -9,3 +9,5 @@ Research should drive planning decisions, not just collect facts. Explicitly add
 - **What boundary contracts matter?** What interfaces, data shapes, event formats, or invariants will slices need to agree on?
 - **What constraints does the existing codebase impose?** What can't be changed, what's expensive to change, what patterns must be respected?
 - **Are there known failure modes that should shape slice ordering?** Pitfalls that mean certain work should come before or after other work?
+
+{{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/plan-milestone.md

@@ -9,14 +9,13 @@ All relevant context has been preloaded below — start working immediately with
 Narrate your decomposition reasoning — why you're grouping work this way, what risks are driving the order, what verification strategy you're choosing and why.
 
 Then:
-1. Read the template at `~/.gsd/agent/extensions/gsd/templates/roadmap.md`
-2. Read `.gsd/REQUIREMENTS.md` if it exists. Treat **Active** requirements as the capability contract for planning. If it does not exist, continue in legacy compatibility mode but explicitly note that requirement coverage is operating without a contract.
-3. 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 roadmap formatting
-4. Create the roadmap: decompose into demoable vertical slices — as many as the work genuinely needs, no more. A simple feature might be 1 slice. Don't decompose for decomposition's sake.
-5. Order by risk (high-risk first)
-6. Write `{{outputPath}}` with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, **requirement coverage**, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment
-7. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.gsd/DECISIONS.md` (read the template at `~/.gsd/agent/extensions/gsd/templates/decisions.md` if the file doesn't exist yet)
-8. Update `.gsd/STATE.md`
+1. Use the **Roadmap** output template from the inlined context above
+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 roadmap formatting
+3. Create the roadmap: decompose into demoable vertical slices — as many as the work genuinely needs, no more. A simple feature might be 1 slice. Don't decompose for decomposition's sake.
+4. Order by risk (high-risk first)
+5. Write `{{outputPath}}` with checkboxes, risk, depends, demo sentences, proof strategy, verification classes, milestone definition of done, **requirement coverage**, and a boundary map. Write success criteria as observable truths, not implementation tasks. If the milestone crosses multiple runtime boundaries, include an explicit final integration slice that proves the assembled system works end-to-end in a real environment
+6. If planning produced structural decisions (e.g. slice ordering rationale, technology choices, scope exclusions), append them to `.gsd/DECISIONS.md` (use the **Decisions** output template from the inlined context above if the file doesn't exist yet)
+7. Update `.gsd/STATE.md`
 
 ## Requirement Mapping Rules
 
@@ -49,9 +48,7 @@ Apply these when decomposing and ordering slices:
 
 If the roadmap has only one slice, also write the slice plan and task plans inline during this unit — don't leave them for a separate planning session.
 
-1. Read the templates:
-   - `~/.gsd/agent/extensions/gsd/templates/plan.md`
-   - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`
+1. Use the **Slice Plan** and **Task Plan** output templates from the inlined context above
 2. `mkdir -p {{milestonePath}}/slices/S01/tasks`
 3. Write the S01 plan file at `{{milestonePath}}/slices/S01/S01-PLAN.md`
 4. Write individual task plans at `{{milestonePath}}/slices/S01/tasks/T01-PLAN.md`, etc.
@@ -65,7 +62,7 @@ After writing the roadmap, analyze the slices and their boundary maps for extern
 
 If this milestone requires any external API keys or secrets:
 
-1. Read the template at `~/.gsd/agent/extensions/gsd/templates/secrets-manifest.md` for the expected format
+1. Use the **Secrets Manifest** output template from the inlined context above for the expected format
 2. Write `{{secretsOutputPath}}` listing every predicted secret as an H3 section with:
    - **Service** — the external service name
    - **Dashboard** — direct URL to the console/dashboard page where the key is created (not a generic homepage)

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

@@ -18,9 +18,7 @@ Narrate your decomposition reasoning — why you're grouping work this way, what
 
 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. Read the templates:
-   - `~/.gsd/agent/extensions/gsd/templates/plan.md`
-   - `~/.gsd/agent/extensions/gsd/templates/task-plan.md`
+1. Use the **Slice Plan** and **Task Plan** output templates from the inlined context above
 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.

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

@@ -82,7 +82,7 @@ Determine where the new milestones should go in the overall sequence. Consider d
 Once the user is satisfied, in a single pass for **each** new milestone (starting from {{nextId}}):
 
 1. `mkdir -p .gsd/milestones/<ID>/slices`
-2. Write `.gsd/milestones/<ID>/<ID>-CONTEXT.md` — read the template at `~/.gsd/agent/extensions/gsd/templates/context.md` first. Capture intent, scope, risks, constraints, integration points, and relevant requirements. Mark the status as "Queued — pending auto-mode execution."
+2. Write `.gsd/milestones/<ID>/<ID>-CONTEXT.md` — use the **Context** output template below. Capture intent, scope, risks, constraints, integration points, and relevant requirements. Mark the status as "Queued — pending auto-mode execution."
 
 Then, after all milestone directories and context files are written:
 
@@ -96,3 +96,5 @@ Then, after all milestone directories and context files are written:
 **Do NOT update `.gsd/STATE.md`.**
 
 After writing the files and committing, say exactly: "Queued N milestone(s). Auto-mode will pick them up after current work completes." — nothing else.
+
+{{inlinedTemplates}}

package/dist/resources/extensions/gsd/prompts/research-milestone.md

@@ -11,7 +11,7 @@ Then research the codebase and relevant technologies. Narrate key findings and s
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code. For small/familiar codebases, use `rg`, `find`, and targeted reads. For large or unfamiliar codebases, use `scout` to build a broad map efficiently before diving in.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries
-5. Read the template at `~/.gsd/agent/extensions/gsd/templates/research.md`
+5. Use the **Research** output template from the inlined context above
 6. If `.gsd/REQUIREMENTS.md` exists, research against it. Identify which Active requirements are table stakes, likely omissions, overbuilt risks, or domain-standard behaviors the user may or may not want.
 7. Write `{{outputPath}}` with:
    - Summary (2-3 paragraphs, primary recommendation)

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

@@ -18,7 +18,7 @@ Then research what this slice needs. Narrate key findings and surprises as you g
 2. **Skill Discovery ({{skillDiscoveryMode}}):**{{skillDiscoveryInstructions}}
 3. Explore relevant code for this slice's scope. For targeted exploration, use `rg`, `find`, and reads. For broad or unfamiliar subsystems, use `scout` to map the relevant area first.
 4. Use `resolve_library` / `get_library_docs` for unfamiliar libraries
-5. Read the template at `~/.gsd/agent/extensions/gsd/templates/research.md`
+5. Use the **Research** output template from the inlined context above
 6. Write `{{outputPath}}`
 
 The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir — just write the file.