gsd-pi 2.76.0 → 2.77.0-dev.1594b263e

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

@@ -43,6 +43,7 @@ export const MODEL_CAPABILITY_TIER = {
     "gpt-5.2-codex": "heavy",
     "gpt-5.3-codex": "heavy",
     "gpt-5.4": "heavy",
+    "gpt-5.5": "heavy",
     "o1": "heavy",
     "o3": "heavy",
     "o4-mini": "heavy",
@@ -76,6 +77,7 @@ const MODEL_COST_PER_1K_INPUT = {
     "gpt-5.3-codex": 0.005,
     "gpt-5.3-codex-spark": 0.0003,
     "gpt-5.4": 0.005,
+    "gpt-5.5": 0.005,
     "o4-mini": 0.005,
     "o4-mini-deep-research": 0.005,
     "gemini-2.0-flash": 0.0001,
@@ -116,6 +118,10 @@ export const MODEL_CAPABILITY_PROFILES = {
     "gpt-5.3-codex": { coding: 94, debugging: 91, research: 74, reasoning: 89, speed: 50, longContext: 80, instruction: 89 },
     "gpt-5.3-codex-spark": { coding: 68, debugging: 58, research: 42, reasoning: 52, speed: 90, longContext: 50, instruction: 74 },
     "gpt-5.4": { coding: 95, debugging: 92, research: 88, reasoning: 94, speed: 42, longContext: 88, instruction: 92 },
+    // GPT-5.5 scores are relative to the existing gpt-5.4 profile and backed by
+    // OpenAI's 2026-04-23 published eval deltas across coding, tool use, and long context.
+    // Source: https://openai.com/index/introducing-gpt-5-5/
+    "gpt-5.5": { coding: 96, debugging: 93, research: 89, reasoning: 95, speed: 42, longContext: 90, instruction: 93 },
     // ── OpenAI o-series (reasoning-first) ──────────────────────────────────────
     "o1": { coding: 78, debugging: 82, research: 78, reasoning: 90, speed: 20, longContext: 65, instruction: 82 },
     "o3": { coding: 80, debugging: 85, research: 80, reasoning: 92, speed: 25, longContext: 70, instruction: 85 },
@@ -440,6 +446,20 @@ function getModelCost(modelId) {
 function bareModelId(modelId) {
     return modelId.includes("/") ? modelId.split("/").pop() : modelId;
 }
+// ─── Provider-specific Tool Limits ─────────────────────────────────────────
+/**
+ * Groq enforces a hard limit of 128 tools per request.
+ * Requests exceeding this limit receive a 400 error:
+ * "maximum number of items is 128"
+ * @see https://console.groq.com/docs/tool-use
+ */
+export const GROQ_MAX_TOOLS = 128;
+/**
+ * Provider IDs that map to the Groq API backend.
+ * Used to detect Groq at the GSD routing layer where only the provider string
+ * is available (the pi-ai openai-completions adapter is shared across providers).
+ */
+const GROQ_PROVIDER_IDS = new Set(["groq"]);
 // ─── Tool Compatibility Filter (ADR-005 Phase 3) ───────────────────────────
 /**
  * Check if a tool is compatible with a provider's capabilities.
@@ -461,8 +481,14 @@ export function isToolCompatibleWithProvider(toolName, providerCaps) {
 /**
  * Filter a list of tool names to only those compatible with a provider.
  * Used by the routing pipeline to adjust tool sets when switching providers.
+ *
+ * @param toolNames - The full list of active tool names to filter.
+ * @param providerApi - The pi-ai API string (e.g. "openai-completions").
+ * @param provider - Optional provider ID (e.g. "groq"). Used to apply
+ *   provider-specific limits that can't be expressed as API-level capabilities
+ *   (e.g. Groq's 128-tool hard limit on the shared openai-completions adapter).
  */
-export function filterToolsForProvider(toolNames, providerApi) {
+export function filterToolsForProvider(toolNames, providerApi, provider) {
     const providerCaps = getProviderCapabilities(providerApi);
     // Provider doesn't support tool calling at all
     if (!providerCaps.toolCalling) {
@@ -478,6 +504,14 @@ export function filterToolsForProvider(toolNames, providerApi) {
             filtered.push(name);
         }
     }
+    // Groq enforces a hard limit of 128 tools per request (#4376).
+    // Trim the compatible list to GROQ_MAX_TOOLS and move the excess to filtered.
+    if (provider && GROQ_PROVIDER_IDS.has(provider) && compatible.length > GROQ_MAX_TOOLS) {
+        const trimmed = compatible.splice(GROQ_MAX_TOOLS);
+        filtered.push(...trimmed);
+        console.warn(`[gsd] Groq tool limit: ${compatible.length + trimmed.length} tools active but Groq allows at most ${GROQ_MAX_TOOLS}. ` +
+            `Trimming to the first ${GROQ_MAX_TOOLS} tools. Removed: ${trimmed.join(", ")}`);
+    }
     return { compatible, filtered };
 }
 /**
@@ -486,8 +520,13 @@ export function filterToolsForProvider(toolNames, providerApi) {
  *
  * This is a hard filter only — it removes tools that would fail at the
  * provider level. It does NOT remove tools based on soft heuristics.
+ *
+ * @param activeToolNames - The full list of currently active tool names.
+ * @param selectedModelApi - The pi-ai API string for the selected model.
+ * @param provider - Optional provider ID (e.g. "groq") for provider-specific
+ *   limits beyond what the API-level capability profile expresses.
  */
-export function adjustToolSet(activeToolNames, selectedModelApi) {
-    const { compatible, filtered } = filterToolsForProvider(activeToolNames, selectedModelApi);
+export function adjustToolSet(activeToolNames, selectedModelApi, provider) {
+    const { compatible, filtered } = filterToolsForProvider(activeToolNames, selectedModelApi, provider);
     return { toolNames: compatible, removedTools: filtered };
 }

package/dist/resources/extensions/gsd/native-git-bridge.js

@@ -740,15 +740,44 @@ export function nativeResetPaths(basePath, paths) {
         gitExec(basePath, ["reset", "HEAD", "--", p], true);
     }
 }
+/**
+ * Read `commit.gpgsign` from the repo config. Returns true only if the value
+ * is the literal string "true". Any other state (unset, false, error) → false.
+ *
+ * Used by nativeCommit to route signing-required commits through the git CLI,
+ * because the libgit2 native path does not invoke configured signers.
+ * (Issue #4980 CRIT-2)
+ */
+function shouldSignCommits(basePath) {
+    try {
+        const result = execFileSync("git", ["config", "--get", "commit.gpgsign"], {
+            cwd: basePath,
+            stdio: ["ignore", "pipe", "pipe"],
+            encoding: "utf-8",
+            env: GIT_NO_PROMPT_ENV,
+        }).trim();
+        return result === "true";
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Create a commit from the current index.
  * Returns the commit SHA on success, or null if nothing to commit.
  * Native: libgit2 commit create.
- * Fallback: `git commit --no-verify -F -`.
+ * Fallback: `git commit -F -` (runs hooks; honors commit.gpgsign).
+ *
+ * The fallback intentionally does NOT use --no-verify — user pre-commit /
+ * commit-msg / prepare-commit-msg hooks must fire on every GSD-automated
+ * commit. (Issue #4980 CRIT-1)
  */
 export function nativeCommit(basePath, message, options) {
     const native = loadNative();
-    if (native) {
+    // libgit2's commit-create does not invoke configured GPG/SSH signers. When
+    // commit.gpgsign=true, route through the git CLI fallback so signing
+    // happens. (Issue #4980 CRIT-2)
+    if (native && !shouldSignCommits(basePath)) {
         try {
             return native.gitCommit(basePath, message, options?.allowEmpty);
         }
@@ -759,9 +788,10 @@ export function nativeCommit(basePath, message, options) {
             throw e;
         }
     }
-    // Fallback: use git commit with stdin pipe for safe multi-line messages
+    // Fallback / signed-commit path: use git CLI with stdin pipe for safe
+    // multi-line messages. Hooks run; commit.gpgsign honored.
     try {
-        const args = ["commit", "--no-verify", "-F", "-"];
+        const args = ["commit", "-F", "-"];
         if (options?.allowEmpty)
             args.push("--allow-empty");
         const result = execFileSync("git", args, {

package/dist/resources/extensions/gsd/notifications.js

@@ -2,7 +2,6 @@
 // Cross-platform desktop notifications for auto-mode events.
 import { execFileSync } from "node:child_process";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
-import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/index.js";
 import { sendRemoteNotification } from "../remote-questions/notify.js";
 /**
  * Send a native desktop notification. Non-blocking, non-fatal.
@@ -20,22 +19,37 @@ export function sendDesktopNotification(title, message, level = "info", kind = "
     void sendRemoteNotification(title, message).catch(() => { });
     if (!shouldSendDesktopNotification(kind, loaded?.notifications))
         return;
-    const cmux = resolveCmuxConfig(loaded);
-    if (cmux.notifications) {
-        const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
-        if (delivered)
-            return;
-        emitOsc777Notification(title, message);
-    }
-    try {
-        const command = buildDesktopNotificationCommand(process.platform, title, message, level);
-        if (!command)
+    // cmux delivery and desktop delivery are independent — if cmux import or
+    // delivery fails, we must still attempt the native desktop notification.
+    const runCmux = async () => {
+        try {
+            const { CmuxClient, emitOsc777Notification, resolveCmuxConfig } = await import("../cmux/index.js");
+            const cmux = resolveCmuxConfig(loaded);
+            if (cmux.notifications) {
+                const delivered = CmuxClient.fromPreferences(loaded).notify(title, message);
+                if (delivered)
+                    return true;
+                emitOsc777Notification(title, message);
+            }
+        }
+        catch {
+            // cmux unavailable — fall through to desktop notification
+        }
+        return false;
+    };
+    void runCmux().then((deliveredByCmux) => {
+        if (deliveredByCmux)
             return;
-        execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
-    }
-    catch {
-        // Non-fatal — desktop notifications are best-effort
-    }
+        try {
+            const command = buildDesktopNotificationCommand(process.platform, title, message, level);
+            if (!command)
+                return;
+            execFileSync(command.file, command.args, { timeout: 3000, stdio: "ignore" });
+        }
+        catch {
+            // Non-fatal — desktop notifications are best-effort
+        }
+    }).catch(() => { });
 }
 export function shouldSendDesktopNotification(kind, preferences = loadEffectiveGSDPreferences()?.preferences.notifications) {
     if (preferences?.enabled === false)

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

@@ -68,8 +68,13 @@ export function extractPackageReferences(description) {
             }
         }
     }
-    // require('pkg') or import from 'pkg' in code blocks
-    const importPattern = /(?:require\s*\(\s*['"]|from\s+['"])([a-zA-Z0-9@/_-]+)['"\)]/g;
+    // require('pkg') or `import ... from 'pkg'` in code blocks.
+    // The `from\s+['"]` branch MUST be preceded by an `import` keyword so that
+    // natural-language prose like `from "What's Next"` or `from 'master'` does
+    // not produce false package-existence failures.  Requiring the leading import
+    // keyword anchors the match to JavaScript/TypeScript syntax.
+    // See: https://github.com/gsd-build/gsd-2/issues/4388
+    const importPattern = /(?:require\s*\(\s*['"]|import\b[\s\S]*?\bfrom\s+['"])([a-zA-Z0-9@/_-]+)['"\)]/g;
     let importMatch;
     while ((importMatch = importPattern.exec(description)) !== null) {
         // Skip relative imports and node builtins
@@ -276,9 +281,23 @@ function extractPathFromAnnotation(raw) {
     if (backtickMatch) {
         return backtickMatch[2].trim();
     }
+    // Strip leading/trailing double or single quotes wrapping the whole value.
+    // Plan documents sometimes emit `"src/foo.ts"` or `'src/bar.ts'` as input
+    // annotations. Stripping the wrapper allows the inner path to be checked
+    // correctly instead of producing a false-positive "file not found" error
+    // for a literal string with quote characters in it (#3747).
+    const quoteMatch = trimmed.match(/^(["'])([^"']+)\1$/);
+    if (quoteMatch) {
+        return quoteMatch[2].trim();
+    }
     const annotatedMatch = trimmed.match(/^(.+?)\s+[—–-]\s+.+$/);
     if (annotatedMatch) {
-        return annotatedMatch[1].trim();
+        const prefix = annotatedMatch[1].trim();
+        const prefixBacktickMatch = prefix.match(/`([^`]+)`/);
+        if (prefixBacktickMatch && looksLikePathOrUrl(prefixBacktickMatch[1].trim())) {
+            return prefixBacktickMatch[1].trim();
+        }
+        return prefix.replace(/`/g, "").trim();
     }
     // Fallback: scan all backticked tokens and return the first one that looks
     // like a path or URL. Handles prose-annotated bullets such as:
@@ -333,13 +352,19 @@ function containsGlobPattern(candidate) {
 }
 /**
  * Build a set of files that will be created by tasks up to (but not including) taskIndex.
+ * Also includes outputs of completed tasks at any position — a completed task has already
+ * run and its outputs are available regardless of sequence position or disk state (#4071).
  * All paths are normalized for consistent comparison.
  */
 function getExpectedOutputsUpTo(tasks, taskIndex) {
     const outputs = new Set();
-    for (let i = 0; i < taskIndex; i++) {
-        for (const file of tasks[i].expected_output) {
-            outputs.add(normalizeFilePath(file));
+    for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i];
+        // Include prior tasks (i < taskIndex) OR completed tasks at any position
+        if (i < taskIndex || task.status === "completed") {
+            for (const file of task.expected_output) {
+                outputs.add(normalizeFilePath(file));
+            }
         }
     }
     return outputs;
@@ -416,8 +441,14 @@ export function checkTaskOrdering(tasks, basePath) {
         const task = tasks[i];
         for (const file of task.expected_output) {
             const normalizedFile = normalizeFilePath(file);
-            if (!fileCreators.has(normalizedFile)) {
-                fileCreators.set(normalizedFile, { taskId: task.id, index: i, originalPath: file });
+            const existing = fileCreators.get(normalizedFile);
+            if (!existing || (!existing.completed && task.status === "completed")) {
+                fileCreators.set(normalizedFile, {
+                    taskId: task.id,
+                    index: i,
+                    originalPath: file,
+                    completed: task.status === "completed",
+                });
             }
         }
     }
@@ -441,7 +472,11 @@ export function checkTaskOrdering(tasks, basePath) {
             const creator = fileCreators.get(normalizedFile);
             const absolutePath = resolve(basePath, normalizedFile);
             const existsOnDisk = existsSync(absolutePath);
-            if (creator && creator.index > i && !existsOnDisk) {
+            // Skip if the creating task has already completed — its output is available
+            // regardless of disk state (e.g. file was a temp artifact cleaned up after
+            // the task ran, or a replan introduced a new earlier-sequence task that
+            // reads this pre-execution output). (#4071)
+            if (creator && creator.index > i && !existsOnDisk && !creator.completed) {
                 // Task reads file that is created later — impossible ordering
                 results.push({
                     category: "file",

package/dist/resources/extensions/gsd/preferences-types.js

@@ -5,6 +5,14 @@
  * both the validation and runtime modules can import them without pulling
  * in filesystem or loading logic.
  */
+/**
+ * Resolve whether context-mode features (gsd_exec sandbox + compaction
+ * snapshot) should be active. Default is ON: missing config or missing
+ * `enabled` is treated as true. Only `enabled: false` disables.
+ */
+export function isContextModeEnabled(prefs) {
+    return prefs?.context_mode?.enabled !== false;
+}
 /** Default preference values for each workflow mode. */
 export const MODE_DEFAULTS = {
     solo: {
@@ -87,6 +95,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "flat_rate_providers",
     "language",
     "context_window_override",
+    "context_mode",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [

package/dist/resources/extensions/gsd/preferences-validation.js

@@ -660,6 +660,55 @@ export function validatePreferences(preferences) {
             errors.push("context_management must be an object");
         }
     }
+    // ─── Context Mode (gsd_exec sandbox) ────────────────────────────────────
+    if (preferences.context_mode !== undefined) {
+        if (typeof preferences.context_mode === "object" && preferences.context_mode !== null) {
+            const cmode = preferences.context_mode;
+            const validCmode = {};
+            if (cmode.enabled !== undefined) {
+                if (typeof cmode.enabled === "boolean")
+                    validCmode.enabled = cmode.enabled;
+                else
+                    errors.push("context_mode.enabled must be a boolean");
+            }
+            if (cmode.exec_timeout_ms !== undefined) {
+                const t = cmode.exec_timeout_ms;
+                if (typeof t === "number" && t >= 1000 && t <= 600_000)
+                    validCmode.exec_timeout_ms = Math.floor(t);
+                else
+                    errors.push("context_mode.exec_timeout_ms must be a number between 1000 and 600000");
+            }
+            if (cmode.exec_stdout_cap_bytes !== undefined) {
+                const b = cmode.exec_stdout_cap_bytes;
+                if (typeof b === "number" && b >= 4096 && b <= 16_777_216)
+                    validCmode.exec_stdout_cap_bytes = Math.floor(b);
+                else
+                    errors.push("context_mode.exec_stdout_cap_bytes must be a number between 4096 and 16777216");
+            }
+            if (cmode.exec_digest_chars !== undefined) {
+                const c = cmode.exec_digest_chars;
+                if (typeof c === "number" && c >= 0 && c <= 4000)
+                    validCmode.exec_digest_chars = Math.floor(c);
+                else
+                    errors.push("context_mode.exec_digest_chars must be a number between 0 and 4000");
+            }
+            if (cmode.exec_env_allowlist !== undefined) {
+                if (Array.isArray(cmode.exec_env_allowlist) &&
+                    cmode.exec_env_allowlist.every((v) => typeof v === "string" && /^[A-Z_][A-Z0-9_]*$/i.test(v))) {
+                    validCmode.exec_env_allowlist = cmode.exec_env_allowlist;
+                }
+                else {
+                    errors.push("context_mode.exec_env_allowlist must be an array of valid env var names");
+                }
+            }
+            if (Object.keys(validCmode).length > 0) {
+                validated.context_mode = validCmode;
+            }
+        }
+        else {
+            errors.push("context_mode must be an object");
+        }
+    }
     // ─── Parallel Config ────────────────────────────────────────────────────
     if (preferences.parallel && typeof preferences.parallel === "object") {
         const p = preferences.parallel;
@@ -716,6 +765,40 @@ export function validatePreferences(preferences) {
             validated.parallel = parallel;
         }
     }
+    // ─── Slice Parallel Config ───────────────────────────────────────────────
+    if (preferences.slice_parallel !== undefined) {
+        if (typeof preferences.slice_parallel === "object" && preferences.slice_parallel !== null) {
+            const sp = preferences.slice_parallel;
+            const validSp = {};
+            if (sp.enabled !== undefined) {
+                if (typeof sp.enabled === "boolean")
+                    validSp.enabled = sp.enabled;
+                else
+                    errors.push("slice_parallel.enabled must be a boolean");
+            }
+            if (sp.max_workers !== undefined) {
+                const maxWorkers = typeof sp.max_workers === "number" ? sp.max_workers : Number(sp.max_workers);
+                if (Number.isFinite(maxWorkers) && maxWorkers >= 1 && maxWorkers <= 8) {
+                    validSp.max_workers = Math.floor(maxWorkers);
+                }
+                else {
+                    errors.push("slice_parallel.max_workers must be a number between 1 and 8");
+                }
+            }
+            const knownSliceParallelKeys = new Set(["enabled", "max_workers"]);
+            for (const key of Object.keys(sp)) {
+                if (!knownSliceParallelKeys.has(key)) {
+                    warnings.push(`unknown slice_parallel key "${key}" — ignored`);
+                }
+            }
+            if (Object.keys(validSp).length > 0) {
+                validated.slice_parallel = validSp;
+            }
+        }
+        else {
+            errors.push("slice_parallel must be an object");
+        }
+    }
     // ─── Reactive Execution ─────────────────────────────────────────────────
     if (preferences.reactive_execution !== undefined) {
         if (typeof preferences.reactive_execution === "object" && preferences.reactive_execution !== null) {
@@ -948,6 +1031,29 @@ export function validatePreferences(preferences) {
         if (g.merge_to_main !== undefined) {
             warnings.push("git.merge_to_main is deprecated — milestone-level merge is now always used. Remove this setting.");
         }
+        // #4765 — collapse cadence + milestone resquash
+        if (g.collapse_cadence !== undefined) {
+            const validCadence = new Set(["milestone", "slice"]);
+            if (typeof g.collapse_cadence === "string" && validCadence.has(g.collapse_cadence)) {
+                git.collapse_cadence = g.collapse_cadence;
+            }
+            else {
+                errors.push("git.collapse_cadence must be one of: milestone, slice");
+            }
+        }
+        if (g.milestone_resquash !== undefined) {
+            if (typeof g.milestone_resquash === "boolean") {
+                git.milestone_resquash = g.milestone_resquash;
+                const cadence = git.collapse_cadence
+                    ?? (typeof g.collapse_cadence === "string" ? g.collapse_cadence : undefined);
+                if (cadence !== "slice") {
+                    warnings.push('git.milestone_resquash is ignored unless git.collapse_cadence is "slice"');
+                }
+            }
+            else {
+                errors.push("git.milestone_resquash must be a boolean");
+            }
+        }
         if (Object.keys(git).length > 0) {
             validated.git = git;
         }

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

@@ -26,12 +26,12 @@ export { resolveAllSkillReferences } from "./preferences-skills.js";
 // These lived in preferences-skills.ts but imported loadEffectiveGSDPreferences
 // back from this file, creating a circular dependency. Moved here since they
 // are trivial wrappers over loadEffectiveGSDPreferences.
-export function resolveSkillDiscoveryMode() {
-    const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillDiscoveryMode(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath);
     return prefs?.preferences.skill_discovery ?? "suggest";
 }
-export function resolveSkillStalenessDays() {
-    const prefs = loadEffectiveGSDPreferences();
+export function resolveSkillStalenessDays(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath);
     return prefs?.preferences.skill_staleness_days ?? 60;
 }
 // ─── Re-exports: models ─────────────────────────────────────────────────────
@@ -46,16 +46,16 @@ function globalPreferencesPath() {
 function legacyGlobalPreferencesPath() {
     return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
-function projectPreferencesPath() {
-    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+function projectPreferencesPath(basePath = process.cwd()) {
+    return join(gsdRoot(basePath), "PREFERENCES.md");
 }
 // Legacy lowercase files can still exist in older projects. Keep them as a
 // compatibility-only fallback, but route new reads/writes through PREFERENCES.md.
 function legacyGlobalPreferencesPathLowercase() {
     return join(gsdHome(), "preferences.md");
 }
-function legacyProjectPreferencesPathLowercase() {
-    return join(gsdRoot(process.cwd()), "preferences.md");
+function legacyProjectPreferencesPathLowercase(basePath = process.cwd()) {
+    return join(gsdRoot(basePath), "preferences.md");
 }
 export function getGlobalGSDPreferencesPath() {
     return globalPreferencesPath();
@@ -63,8 +63,8 @@ export function getGlobalGSDPreferencesPath() {
 export function getLegacyGlobalGSDPreferencesPath() {
     return legacyGlobalPreferencesPath();
 }
-export function getProjectGSDPreferencesPath() {
-    return projectPreferencesPath();
+export function getProjectGSDPreferencesPath(basePath) {
+    return projectPreferencesPath(basePath);
 }
 // ─── Loading ────────────────────────────────────────────────────────────────
 export function loadGlobalGSDPreferences() {
@@ -72,13 +72,13 @@ export function loadGlobalGSDPreferences() {
         ?? loadPreferencesFile(legacyGlobalPreferencesPathLowercase(), "global")
         ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
-export function loadProjectGSDPreferences() {
-    return loadPreferencesFile(projectPreferencesPath(), "project")
-        ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(), "project");
+export function loadProjectGSDPreferences(basePath) {
+    return loadPreferencesFile(projectPreferencesPath(basePath), "project")
+        ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
 }
-export function loadEffectiveGSDPreferences() {
+export function loadEffectiveGSDPreferences(basePath) {
     const globalPreferences = loadGlobalGSDPreferences();
-    const projectPreferences = loadProjectGSDPreferences();
+    const projectPreferences = loadProjectGSDPreferences(basePath);
     if (!globalPreferences && !projectPreferences)
         return null;
     let result;
@@ -489,8 +489,8 @@ export function resolvePreDispatchHooks() {
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */
-export function getIsolationMode() {
-    const prefs = loadEffectiveGSDPreferences()?.preferences?.git;
+export function getIsolationMode(basePath) {
+    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences?.git;
     if (prefs?.isolation === "worktree")
         return "worktree";
     if (prefs?.isolation === "branch")

package/dist/resources/extensions/gsd/prompt-cache-optimizer.js

@@ -24,6 +24,10 @@ const SEMI_STATIC_LABELS = new Set([
     "prior-summaries",
     "project-context",
     "overrides",
+    // KNOWLEDGE is milestone-scoped (stable within a session), so it belongs
+    // in the cacheable prefix. See issue #4719.
+    "knowledge",
+    "project-knowledge",
 ]);
 /** Labels that change per-task */
 const DYNAMIC_LABELS = new Set([

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

@@ -22,6 +22,27 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { logWarning } from "./workflow-logger.js";
+function hasRequiredExtensionAssets(rootDir, exists = existsSync) {
+    return (exists(join(rootDir, "prompts")) &&
+        exists(join(rootDir, "templates", "task-summary.md")));
+}
+export function resolveExtensionDirFromCandidates(moduleDir, agentGsdDir, exists = existsSync) {
+    const moduleUsable = hasRequiredExtensionAssets(moduleDir, exists);
+    const agentUsable = hasRequiredExtensionAssets(agentGsdDir, exists);
+    // Prefer the user-local extension tree when both are valid. This avoids
+    // leaking npm/global-install paths into prompts on Windows.
+    if (agentUsable)
+        return agentGsdDir;
+    if (moduleUsable)
+        return moduleDir;
+    // Degraded fallback: if required template is missing in both locations,
+    // keep previous behavior and prefer whichever still has prompts/.
+    if (exists(join(moduleDir, "prompts")))
+        return moduleDir;
+    if (exists(join(agentGsdDir, "prompts")))
+        return agentGsdDir;
+    return moduleDir;
+}
 /**
  * Resolve the GSD extension directory.
  *
@@ -34,15 +55,9 @@ import { logWarning } from "./workflow-logger.js";
  */
 function resolveExtensionDir() {
     const moduleDir = dirname(fileURLToPath(import.meta.url));
-    if (existsSync(join(moduleDir, "prompts")))
-        return moduleDir;
-    // Fallback: user-local agent directory
     const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
     const agentGsdDir = join(gsdHome, "agent", "extensions", "gsd");
-    if (existsSync(join(agentGsdDir, "prompts")))
-        return agentGsdDir;
-    // Last resort: return the module dir (warmCache will silently handle the miss)
-    return moduleDir;
+    return resolveExtensionDirFromCandidates(moduleDir, agentGsdDir);
 }
 const __extensionDir = resolveExtensionDir();
 const promptsDir = join(__extensionDir, "prompts");

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

@@ -10,7 +10,11 @@ Your working directory is `{{workingDirectory}}`. All file reads, writes, and sh
 
 All slices are done. You are closing out the milestone — verifying that the assembled work actually delivers the promised outcome, writing the milestone summary, and updating project state. The milestone summary is the final record. After you finish, the system merges the worktree back to the integration branch. If there are queued milestones, the next one starts its own research → plan → execute cycle from a clean slate — the milestone summary is how it learns what was already built.
 
-All relevant context has been preloaded below — the roadmap, all slice summaries, requirements, decisions, and project context are inlined. Start working immediately without re-reading these files.
+Preloaded context below — the roadmap, compact slice-summary excerpts, requirements, decisions, and project context. **Slice summaries are excerpts, not full files.** They include frontmatter fields, section heads (deviations, known limitations, follow-ups), and short narrative only. When drafting LEARNINGS, the Decision Re-evaluation table, or cross-slice narrative, Read the full slice SUMMARY.md files listed under "On-demand Slice Summaries" — do that selectively as needed, not preemptively.
+
+Start with what the excerpts give you. Read full files when the section heads signal richer context you need.
+
+**On-demand Read ordering:** Complete all slice SUMMARY Reads you need for cross-slice synthesis, the Decision Re-evaluation table, and LEARNINGS **before** calling `gsd_complete_milestone` (step 10). Once that tool runs, the milestone is marked complete in the DB — running out of tool budget between step 10 and the LEARNINGS write (step 12) leaves the milestone committed without its LEARNINGS artifact.
 
 {{inlinedContext}}
 
@@ -59,7 +63,7 @@ Then:
    - `followUps` (string) — Follow-up items for future milestones
    - `deviations` (string) — Deviations from the original plan
 11. Update `.gsd/PROJECT.md`: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting milestone completion and current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.
-12. Extract structured learnings from this milestone and persist them to the cross-session knowledge surfaces. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md`, appends Patterns and Lessons to `.gsd/KNOWLEDGE.md`, and persists Decisions via the `gsd_save_decision` MCP tool.
+12. Extract structured learnings from this milestone and persist them to the GSD memory store. Follow the procedure block immediately below — it writes `{{milestoneId}}-LEARNINGS.md` as the audit trail and persists Patterns, Lessons, and Decisions via `capture_thought` (categories: pattern, gotcha/convention, architecture). The memory store is the single source of truth for cross-session durable knowledge (ADR-013).
 
 {{extractLearningsSteps}}
 

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

@@ -29,8 +29,8 @@ Then:
 6. If this slice produced evidence that a requirement changed status (Active → Validated, Active → Deferred, etc.), call `gsd_requirement_update` with the requirement ID, updated `status`, and `validation` evidence. Do NOT write `.gsd/REQUIREMENTS.md` directly — the engine renders it from the database.
 7. Prepare the slice completion content you will pass to `gsd_complete_slice` using the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}` — the DB-backed tool is the canonical write path for both artifacts.
 8. Draft the UAT content you will pass as `uatContent` — a concrete UAT script with real test cases derived from the slice plan and task summaries. Include preconditions, numbered steps with expected outcomes, and edge cases. This must NOT be a placeholder or generic template — tailor every test case to what this slice actually built.
-9. Review task summaries for `key_decisions`. Append any significant decisions to `.gsd/DECISIONS.md` if missing.
-10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. If any would save future agents from repeating investigation or hitting the same issues, append them to `.gsd/KNOWLEDGE.md`. Only add entries that are genuinely useful — don't pad with obvious observations.
+9. Review task summaries for `key_decisions`. For each significant decision, call `capture_thought` with `category: "architecture"` (or `"pattern"`) and a `structuredFields` payload of `{ scope, decision, choice, rationale, made_by: "agent", revisable }`.
+10. Review task summaries for patterns, gotchas, or non-obvious lessons learned. For each one that would save future agents from repeating investigation, call `capture_thought` with the matching category (`gotcha`, `convention`, `pattern`, `environment`). The memory store is the single source of truth (ADR-013); do not append to `.gsd/DECISIONS.md` or `.gsd/KNOWLEDGE.md` directly.
 11. Call `gsd_complete_slice` with the camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`, plus any optional enrichment fields you have. Do NOT manually mark the roadmap checkbox — the tool writes to the DB, renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}`, and updates the ROADMAP.md projection automatically.
 12. Do not run git commands — the system commits your changes and handles any merge after this unit succeeds.
 13. Update `.gsd/PROJECT.md` if it exists — refresh current state if needed: use the `write` tool with `path: ".gsd/PROJECT.md"` and `content` containing the full updated document reflecting current project state. Do NOT use the `edit` tool for this — PROJECT.md is a full-document refresh.

package/dist/resources/extensions/gsd/prompts/debug-diagnose.md

@@ -18,8 +18,10 @@ Goal semantics:
 ## Instructions
 
 1. Read `.gsd/debug/sessions/{{slug}}.json` for any prior session context.
+1a. Call `memory_query` with keywords from the issue (error text, subsystem, file paths). A prior session may have captured this exact gotcha — finding it now saves the investigation.
 2. Investigate the reported issue in `{{workingDirectory}}`.
 3. Follow the goal constraint above strictly.
 4. When complete, surface a clear summary: what failed, why, and what was done (or what a fix would require for root-cause-only mode).
+5. Once root cause is identified, call `capture_thought` with `category: "gotcha"` so future debug sessions can find it via `memory_query`. Keep the content to 1–3 sentences — the symptom, the root cause, and the fix or guard.
 
 {{skillActivation}}