gsd-pi 2.80.0 → 2.81.0-dev.3cddbbba2

package/dist/resources/extensions/gsd/parallel-monitor-overlay.js

@@ -1,12 +1,5 @@
-/**
- * GSD Parallel Monitor Overlay
- *
- * Full-screen TUI overlay showing real-time parallel worker progress.
- * Opened via `/gsd parallel watch`, Ctrl+Alt+P (⌃⌥P on macOS),
- * or Ctrl+Shift+P fallback.
- * Reads the same data sources as `scripts/parallel-monitor.mjs` but
- * renders as a native pi-tui overlay with theme integration.
- */
+// Project/App: GSD-2
+// File Purpose: Parallel worker monitor overlay with width-safe operations-console rendering.
 import { existsSync, statSync, readFileSync, openSync, readSync, closeSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
@@ -14,6 +7,7 @@ import { matchesKey, Key } from "@gsd/pi-tui";
 import { formatDuration } from "../shared/mod.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { resolveGsdPathContract } from "./paths.js";
+import { renderBar, renderKeyHints, renderProgressBar, safeLine, statusGlyph, } from "./tui/render-kit.js";
 // ─── Data Helpers ─────────────────────────────────────────────────────────
 function readJsonSafe(filePath) {
     try {
@@ -226,17 +220,6 @@ function unitTypeLabel(unitType) {
     };
     return labels[unitType || ""] || (unitType || "---").toUpperCase().slice(0, 5);
 }
-function progressBar(done, total, width) {
-    if (total === 0)
-        return "░".repeat(width);
-    const filled = Math.round((done / total) * width);
-    return "█".repeat(filled) + "░".repeat(width - filled);
-}
-function healthGlyph(alive, heartbeatAge) {
-    if (!alive)
-        return "○";
-    return "●";
-}
 // ─── Overlay Class ────────────────────────────────────────────────────────
 export class ParallelMonitorOverlay {
     tui;
@@ -247,6 +230,7 @@ export class ParallelMonitorOverlay {
     workers = [];
     events = [];
     cachedLines;
+    cachedWidth;
     scrollOffset = 0;
     disposed = false;
     resizeHandler = null;
@@ -279,6 +263,7 @@ export class ParallelMonitorOverlay {
         }
         this.events = this.events.slice(-10);
         this.cachedLines = undefined;
+        this.cachedWidth = undefined;
         this.tui.requestRender();
     }
     dispose() {
@@ -313,13 +298,14 @@ export class ParallelMonitorOverlay {
     }
     invalidate() {
         this.cachedLines = undefined;
+        this.cachedWidth = undefined;
     }
     render(width) {
-        if (this.cachedLines)
+        if (this.cachedLines && this.cachedWidth === width)
             return this.cachedLines;
         const t = this.theme;
         const lines = [];
-        const w = Math.max(width, 60);
+        const w = Math.max(1, width);
         // Header
         const totalCost = this.workers.reduce((s, wk) => s + wk.cost, 0);
         const aliveCount = this.workers.filter((wk) => wk.alive).length;
@@ -328,7 +314,7 @@ export class ParallelMonitorOverlay {
         lines.push(t.fg("muted", `  ${now}  │  ${aliveCount}/${this.workers.length} alive  │  Total: `) +
             t.bold(`$${totalCost.toFixed(2)}`) +
             t.fg("muted", "  │  5s refresh"));
-        lines.push(t.fg("muted", "─".repeat(w)));
+        lines.push(renderBar(t, w));
         if (this.workers.length === 0) {
             lines.push("");
             lines.push(t.fg("warning", "  No parallel workers found."));
@@ -339,7 +325,7 @@ export class ParallelMonitorOverlay {
                 lines.push("");
                 // Health + ID + state
                 const healthColor = wk.alive ? "success" : "error";
-                const glyph = healthGlyph(wk.alive, wk.heartbeatAge);
+                const glyph = statusGlyph(t, wk.alive ? "active" : "idle");
                 const stateText = wk.alive
                     ? t.fg("success", "RUNNING")
                     : t.fg("error", t.bold("DEAD"));
@@ -374,21 +360,25 @@ export class ParallelMonitorOverlay {
                     });
                     lines.push(`     ${t.fg("muted", "slices")}  ${chips.join("  ")}`);
                     // Task progress bar
-                    const bar = progressBar(wk.doneTasks, wk.totalTasks, 25);
+                    const barWidth = Math.max(6, Math.min(25, w - 32));
+                    const bar = renderProgressBar(t, wk.doneTasks, wk.totalTasks, barWidth, {
+                        filledChar: "█",
+                        emptyChar: "░",
+                        emptyColor: "dim",
+                    });
                     const pct = wk.totalTasks > 0 ? Math.round((wk.doneTasks / wk.totalTasks) * 100) : 0;
-                    lines.push(`     ${t.fg("muted", "tasks")}   ${t.fg("success", bar)}  ${wk.doneTasks}/${wk.totalTasks} ` +
+                    lines.push(`     ${t.fg("muted", "tasks")}   ${bar}  ${wk.doneTasks}/${wk.totalTasks} ` +
                         t.fg("muted", `(${pct}%)  │  slices done ${wk.doneSlices}/${wk.totalSlices}`));
                 }
                 // Errors
                 for (const err of wk.errors.slice(-2)) {
-                    const truncated = err.length > w - 10 ? err.slice(0, w - 11) + "…" : err;
-                    lines.push(`     ${t.fg("error", "⚠ " + truncated)}`);
+                    lines.push(`     ${t.fg("error", "! " + err)}`);
                 }
             }
         }
         // Event feed
         lines.push("");
-        lines.push(t.fg("muted", "─".repeat(w)));
+        lines.push(renderBar(t, w));
         lines.push(`  ${t.bold("Recent Events")}`);
         if (this.events.length === 0) {
             lines.push(t.fg("muted", "  No events yet..."));
@@ -396,8 +386,7 @@ export class ParallelMonitorOverlay {
         else {
             for (const evt of this.events.slice(-8)) {
                 const mid = evt.match(/^✓ (M\d+)\//)?.[1] || "";
-                const truncated = evt.length > w - 10 ? evt.slice(0, w - 11) + "…" : evt;
-                lines.push(`  ${t.fg("muted", "│")} ${t.fg("accent", mid)} ${truncated.replace(/^✓ M\d+\//, "")}`);
+                lines.push(`  ${t.fg("muted", "│")} ${t.fg("accent", mid)} ${evt.replace(/^✓ M\d+\//, "")}`);
             }
         }
         // Footer
@@ -411,13 +400,16 @@ export class ParallelMonitorOverlay {
             }
             lines.push(`  ${t.bold("Total: $" + this.workers.reduce((s, wk) => s + wk.cost, 0).toFixed(2))}`);
         }
-        lines.push(t.fg("muted", `  ESC/q/${formattedShortcutPair("parallel")} close  │  ↑↓ scroll`));
+        lines.push(renderKeyHints(t, [`ESC/q/${formattedShortcutPair("parallel")} close`, "↑↓ scroll"], w));
         // Apply scroll — use terminal rows as height estimate
         const termHeight = process.stdout.rows || 40;
         const maxScroll = Math.max(0, lines.length - termHeight);
         this.scrollOffset = Math.min(Math.max(this.scrollOffset, 0), maxScroll);
-        const visible = lines.slice(this.scrollOffset, this.scrollOffset + termHeight);
+        const visible = lines
+            .slice(this.scrollOffset, this.scrollOffset + termHeight)
+            .map((line) => safeLine(line, w));
         this.cachedLines = visible;
+        this.cachedWidth = width;
         return visible;
     }
 }

package/dist/resources/extensions/gsd/parallel-orchestrator.js

@@ -12,7 +12,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath } from "./worktree-manager.js";
-import { autoWorktreeBranch, runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
+import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
 import { nativeBranchExists } from "./native-git-bridge.js";
 import { readIntegrationBranch } from "./git-service.js";
 import { resolveParallelConfig } from "./preferences.js";
@@ -368,7 +368,7 @@ export async function startParallel(basePath, milestoneIds, prefs) {
             // Create the worktree (without chdir — coordinator stays in project root)
             let wtPath;
             try {
-                wtPath = createMilestoneWorktree(basePath, mid);
+                wtPath = _createMilestoneWorktree(basePath, mid);
             }
             catch (e) {
                 logWarning("parallel", `createMilestoneWorktree fallback for ${mid}: ${e.message}`);
@@ -421,12 +421,22 @@ export async function startParallel(basePath, milestoneIds, prefs) {
 /**
  * Create a git worktree for a milestone without changing the coordinator's cwd.
  * Uses milestone/<MID> branch naming (same as auto-worktree.ts).
+ *
+ * Exported with the `_` prefix purely for tests — production callers stay on
+ * the closure-private name `createMilestoneWorktree` below.
  */
-function createMilestoneWorktree(basePath, milestoneId) {
+export function _createMilestoneWorktree(basePath, milestoneId) {
     const branch = autoWorktreeBranch(milestoneId);
     const branchExists = nativeBranchExists(basePath, branch);
     let info;
     if (branchExists) {
+        // #5549 post-merge audit (R3): match the fast-forward behavior added to
+        // `createAutoWorktree` in commit 8996cb68e. When a worker reuses an
+        // existing milestone branch, fast-forward it onto the integration branch
+        // when safe so per-worker worktrees don't fork from a stale base after a
+        // sibling milestone has merged. Same `nativeIsAncestor` + worktree-list
+        // safety guards apply.
+        fastForwardReusedMilestoneBranchIfSafe(basePath, milestoneId, branch);
         info = createWorktree(basePath, milestoneId, { branch, reuseExistingBranch: true });
     }
     else {

package/dist/resources/extensions/gsd/planning-path-scope.js

@@ -0,0 +1,26 @@
+import { isAbsolute, relative, resolve } from "node:path";
+import { normalizePlannedFileReference } from "./files.js";
+function isInsideBase(basePath, candidate) {
+    const base = resolve(basePath);
+    const abs = resolve(candidate);
+    const rel = relative(base, abs);
+    return rel === "" || (!!rel && !rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Planning IO fields are execution contracts. Absolute paths are only safe when
+ * they stay inside the active working directory; in worktree mode, an absolute
+ * path to the original checkout makes executors edit the wrong tree.
+ */
+export function validatePlanningPathScope(basePath, fields) {
+    for (const { field, values } of fields) {
+        for (const raw of values) {
+            const candidate = normalizePlannedFileReference(raw);
+            if (!isAbsolute(candidate))
+                continue;
+            if (isInsideBase(basePath, candidate))
+                continue;
+            return `${field} contains absolute path outside working directory: ${candidate}. Use a path relative to ${basePath}.`;
+        }
+    }
+    return null;
+}

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Post-execution validation checks for completed GSD task output.
 /**
  * Post-Execution Checks — Validate task output after execution completes.
  *

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

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

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

@@ -1,3 +1,5 @@
+// Project/App: GSD-2
+// File Purpose: Pre-execution validation checks for GSD task plans.
 /**
  * Pre-Execution Checks — Validate task plans before execution begins.
  *
@@ -326,6 +328,8 @@ function shouldValidateInputAsPath(raw) {
     const trimmed = raw.trim();
     if (!trimmed)
         return false;
+    if (isRuntimeOnlyInput(trimmed))
+        return false;
     const candidate = extractPathFromAnnotation(trimmed);
     if (!candidate)
         return false;
@@ -347,6 +351,9 @@ function shouldValidateInputAsPath(raw) {
         /[\\/]/.test(candidate) ||
         /[*?[\]{}]/.test(candidate));
 }
+function isRuntimeOnlyInput(raw) {
+    return /\(\s*runtime\s*\)/i.test(raw);
+}
 function containsGlobPattern(candidate) {
     return ["*", "?", "[", "]", "{", "}"].some((char) => candidate.includes(char));
 }
@@ -384,6 +391,15 @@ function getExpectedOutputsUpTo(tasks, taskIndex) {
  */
 export function checkFilePathConsistency(tasks, basePath) {
     const results = [];
+    // Build a set of all files created by any task at any position (normalized).
+    // Used to suppress consistency errors for files that will be caught with a
+    // more precise message by checkTaskOrdering (sequence violation).
+    const allTaskOutputs = new Set();
+    for (const t of tasks) {
+        for (const f of t.expected_output) {
+            allTaskOutputs.add(normalizeFilePath(f));
+        }
+    }
     for (let i = 0; i < tasks.length; i++) {
         const task = tasks[i];
         const priorOutputs = getExpectedOutputsUpTo(tasks, i);
@@ -414,6 +430,12 @@ export function checkFilePathConsistency(tasks, basePath) {
                         anyOutputUnderDirectory(normalizedFile, ownOutputs);
             }
             if (!existsOnDisk && !inPriorOutputs && !inOwnOutputs && !directorySatisfied) {
+                // If a later task claims to create this file, the ordering check will
+                // fire a more precise "sequence violation" error for the same file.
+                // Suppress the consistency error here to avoid duplicate noise.
+                if (allTaskOutputs.has(normalizedFile) && !ownOutputs.has(normalizedFile)) {
+                    continue;
+                }
                 results.push({
                     category: "file",
                     target: file,
@@ -459,6 +481,8 @@ export function checkTaskOrdering(tasks, basePath) {
         const task = tasks[i];
         const filesToCheck = [...task.inputs];
         for (const file of filesToCheck) {
+            if (isRuntimeOnlyInput(file))
+                continue;
             if (!shouldValidateInputAsPath(file))
                 continue;
             const normalizedFile = normalizeFilePath(file);

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

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

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

@@ -10,7 +10,7 @@
  * Templates are snapshotted shortly after module init via warmCache().
  * This keeps import/extension-registration fast while still preventing a
  * running session from being invalidated when another `gsd` launch overwrites
- * ~/.gsd/agent/ with newer templates via initResources(). Without caching, the
+ * the user-local agent tree with newer templates via initResources(). Without caching, the
  * in-memory extension code (which knows variable set A) can read a newer
  * template from disk (which expects variable set B), causing a
  * "template declares {{X}} but no value was provided" crash mid-session.
@@ -47,9 +47,9 @@ export function resolveExtensionDirFromCandidates(moduleDir, agentGsdDir, exists
  *
  * `import.meta.url` resolves to whichever copy of this module is executing.
  * On Windows (npm global install via MSYS2 / Git Bash) this can resolve to
- * the npm-global `AppData/Roaming/npm/…` path, which does NOT contain the
- * prompts/ and templates/ subtrees that initResources() copies to
- * `~/.gsd/agent/extensions/gsd/`. Detect the mismatch and fall back to
+ * the npm-global package path, which does NOT contain the prompts/ and
+ * templates/ subtrees that initResources() copies to the user-local agent
+ * extension directory. Detect the mismatch and fall back to
  * the user-local agent directory.
  */
 function resolveExtensionDir() {
@@ -62,7 +62,7 @@ const promptsDir = join(__extensionDir, "prompts");
 const templatesDir = join(__extensionDir, "templates");
 /**
  * Return the resolved templates directory path for use in prompts.
- * Avoids hardcoding `~/.gsd/agent/extensions/gsd/templates/` in templates. (#3575)
+ * Avoids hardcoding the user-local templates directory in templates. (#3575)
  */
 export function getTemplatesDir() {
     return templatesDir;
@@ -111,15 +111,41 @@ function warmCache() {
     }
 }
 let warmCacheScheduled = false;
+let warmCacheRan = false;
+let warmCacheTimer;
+/**
+ * Synchronously snapshot the prompt/template tree into the cache.
+ *
+ * Safe to call immediately after `initResources()` because that function uses
+ * synchronous fs APIs — there is no race window that requires deferring the
+ * cache warm via setTimeout. Idempotent: subsequent calls are no-ops.
+ *
+ * Cancels the fallback `scheduleWarmCache` timer if it is still pending.
+ */
+export function primeCache() {
+    if (warmCacheRan)
+        return;
+    if (warmCacheTimer) {
+        clearTimeout(warmCacheTimer);
+        warmCacheTimer = undefined;
+    }
+    warmCacheScheduled = true;
+    warmCacheRan = true;
+    warmCache();
+}
 function scheduleWarmCache() {
     if (warmCacheScheduled)
         return;
     warmCacheScheduled = true;
     const run = () => {
+        warmCacheTimer = undefined;
+        if (warmCacheRan)
+            return;
+        warmCacheRan = true;
         warmCache();
     };
-    const timer = setTimeout(run, 1000);
-    timer.unref?.();
+    warmCacheTimer = setTimeout(run, 1000);
+    warmCacheTimer.unref?.();
 }
 // Snapshot the full prompt/template tree after import so extension startup only
 // pays for prompts that are actually needed immediately.
@@ -138,6 +164,10 @@ export function loadPrompt(name, vars = {}) {
         templateCache.set(name, content);
     }
     const effectiveVars = {
+        templatesDir: getTemplatesDir(),
+        planTemplatePath: join(getTemplatesDir(), "plan.md"),
+        taskPlanTemplatePath: join(getTemplatesDir(), "task-plan.md"),
+        taskSummaryTemplatePath: join(getTemplatesDir(), "task-summary.md"),
         skillActivation: "If a `GSD Skill Preferences` block is present in system context, use it and the `<available_skills>` catalog in your system prompt to decide which skills to load and follow for this unit, without relaxing required verification or artifact rules.",
         ...vars,
     };