gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.04f5ccf82

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

@@ -17,6 +17,43 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve, dirname, extname } from "node:path";
 // ─── Import Resolution Check ─────────────────────────────────────────────────
+/**
+ * Replace the contents of single- and double-quoted string literals on a single
+ * source line with spaces so import patterns do not match text inside strings.
+ * Template-literal spans are handled separately via the inTemplateLiteral flag.
+ */
+function stripStringLiterals(line) {
+    let result = "";
+    let i = 0;
+    while (i < line.length) {
+        const ch = line[i];
+        if (ch === '"' || ch === "'") {
+            result += ch;
+            i++;
+            while (i < line.length) {
+                const c = line[i];
+                if (c === "\\" && i + 1 < line.length) {
+                    result += "  ";
+                    i += 2;
+                }
+                else if (c === ch) {
+                    result += ch;
+                    i++;
+                    break;
+                }
+                else {
+                    result += " ";
+                    i++;
+                }
+            }
+        }
+        else {
+            result += ch;
+            i++;
+        }
+    }
+    return result;
+}
 /**
  * Extract relative import paths from TypeScript/JavaScript source code.
  * Returns array of { importPath, lineNum } for relative imports.
@@ -30,11 +67,19 @@ export function extractRelativeImports(source) {
     //   import './path'
     //   require('./path')
     //   require("../path")
-    const importPattern = /(?:import\s+(?:.*?\s+from\s+)?|require\s*\(\s*)(['"])(\.\.?\/[^'"]+)\1/g;
+    const importPattern = /(?:^|[;{}]\s*)import\s+(?:.*?\s+from\s+)?(['"])(\.\.?\/[^'"]+)\1/g;
+    const requirePattern = /require\s*\(\s*(['"])(\.\.?\/[^'"]+)\1/g;
     // Track if we're inside a block comment
     let inBlockComment = false;
+    let inTemplateLiteral = false;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
+        if (inTemplateLiteral) {
+            if ((line.match(/(?<!\\)`/g) ?? []).length % 2 === 1) {
+                inTemplateLiteral = false;
+            }
+            continue;
+        }
         // Handle block comment boundaries
         if (inBlockComment) {
             if (line.includes("*/")) {
@@ -61,9 +106,17 @@ export function extractRelativeImports(source) {
         let match;
         // Reset lastIndex for each line
         importPattern.lastIndex = 0;
+        requirePattern.lastIndex = 0;
+        const strippedLine = stripStringLiterals(line);
         while ((match = importPattern.exec(line)) !== null) {
+            const importOffset = match[0].indexOf("import");
+            const importStart = match.index + importOffset;
+            if (strippedLine.slice(importStart, importStart + "import".length) !==
+                "import") {
+                continue;
+            }
             // Check if this match is after a // comment marker on the same line
-            const beforeMatch = line.substring(0, match.index);
+            const beforeMatch = strippedLine.substring(0, match.index);
             if (beforeMatch.includes("//")) {
                 continue;
             }
@@ -72,6 +125,24 @@ export function extractRelativeImports(source) {
                 lineNum: i + 1,
             });
         }
+        while ((match = requirePattern.exec(line)) !== null) {
+            if (strippedLine.slice(match.index, match.index + "require".length) !==
+                "require") {
+                continue;
+            }
+            // Check if this match is after a // comment marker on the same line
+            const beforeMatch = strippedLine.substring(0, match.index);
+            if (beforeMatch.includes("//")) {
+                continue;
+            }
+            imports.push({
+                importPath: match[2],
+                lineNum: i + 1,
+            });
+        }
+        if ((strippedLine.match(/(?<!\\)`/g) ?? []).length % 2 === 1) {
+            inTemplateLiteral = true;
+        }
     }
     return imports;
 }
@@ -109,13 +180,6 @@ export function resolveImportPath(importPath, sourceFile, basePath) {
             ".woff", ".woff2", ".ttf", ".otf", ".eot",
         ]);
         const runtimeFallbackExtensions = new Set([".js", ".jsx", ".mjs", ".cjs"]);
-        const dottedStemFallbackExtensions = new Set([".server", ".client", ".webhook"]);
-        if (explicitExt !== "" &&
-            !runtimeFallbackExtensions.has(explicitExt) &&
-            !nonFallbackExtensions.has(explicitExt) &&
-            !dottedStemFallbackExtensions.has(explicitExt)) {
-            return { exists: false, resolvedPath: null };
-        }
         if (nonFallbackExtensions.has(explicitExt) && !runtimeFallbackExtensions.has(explicitExt)) {
             return { exists: false, resolvedPath: null };
         }

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

@@ -18,8 +18,34 @@
 import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { resolve } from "node:path";
+import { isAbsolute, relative, resolve } from "node:path";
+import { validateVerificationCommand } from "./verification-gate.js";
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";
+export function checkVerificationCommands(tasks) {
+    const results = [];
+    for (const task of tasks) {
+        const verify = task.verify.trim();
+        if (!verify)
+            continue;
+        const commands = verify
+            .split("&&")
+            .map((command) => command.trim())
+            .filter(Boolean);
+        for (const command of commands) {
+            const validation = validateVerificationCommand(command);
+            if (!validation.ok) {
+                results.push({
+                    category: "tool",
+                    target: `${task.id} Verify`,
+                    passed: false,
+                    message: `Unsafe or non-runnable Verify command: ${command} (${validation.reason})`,
+                    blocking: true,
+                });
+            }
+        }
+    }
+    return results;
+}
 // ─── Package Existence Check ─────────────────────────────────────────────────
 /**
  * Extract npm package names from task descriptions.
@@ -81,7 +107,7 @@ export function extractPackageReferences(description) {
     while ((importMatch = importPattern.exec(description)) !== null) {
         // Skip relative imports and node builtins
         const pkg = importMatch[1];
-        if (!pkg.startsWith(".") && !pkg.startsWith("node:")) {
+        if (!pkg.startsWith(".") && !pkg.startsWith("node:") && !pkg.startsWith("@/")) {
             packages.add(normalizePackageName(pkg));
         }
     }
@@ -292,7 +318,7 @@ function extractPathFromAnnotation(raw) {
     if (quoteMatch) {
         return quoteMatch[2].trim();
     }
-    const annotatedMatch = trimmed.match(/^(.+?)\s+[—–-]\s+.+$/);
+    const annotatedMatch = trimmed.match(/^(.+?)(?:\s+[—–-]\s+.+|\s+\([^()]+\))$/);
     if (annotatedMatch) {
         const prefix = annotatedMatch[1].trim();
         const prefixBacktickMatch = prefix.match(/`([^`]+)`/);
@@ -357,6 +383,14 @@ function isRuntimeOnlyInput(raw) {
 function containsGlobPattern(candidate) {
     return ["*", "?", "[", "]", "{", "}"].some((char) => candidate.includes(char));
 }
+function toComparisonPath(filePath, basePath) {
+    const normalized = normalizeFilePath(filePath);
+    if (!isAbsolute(normalized))
+        return normalized;
+    const normalizedBasePath = normalizeFilePath(basePath);
+    const rel = normalizeFilePath(relative(normalizedBasePath, normalized));
+    return rel && !rel.startsWith("..") && rel !== "." ? rel : normalized;
+}
 /**
  * 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
@@ -389,21 +423,22 @@ function getExpectedOutputsUpTo(tasks, taskIndex) {
  *
  * All paths are normalized before comparison to ensure ./src/a.ts matches src/a.ts.
  */
-export function checkFilePathConsistency(tasks, basePath) {
+export function checkFilePathConsistency(tasks, basePath, context) {
     const results = [];
+    const resolutionRoots = [basePath, ...(context?.additionalRoots ?? [])];
     // 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));
+            allTaskOutputs.add(toComparisonPath(f, basePath));
         }
     }
     for (let i = 0; i < tasks.length; i++) {
         const task = tasks[i];
-        const priorOutputs = getExpectedOutputsUpTo(tasks, i);
-        const ownOutputs = new Set(task.expected_output.map(normalizeFilePath));
+        const priorOutputs = new Set(Array.from(getExpectedOutputsUpTo(tasks, i), (filePath) => toComparisonPath(filePath, basePath)));
+        const ownOutputs = new Set(task.expected_output.map((filePath) => toComparisonPath(filePath, basePath)));
         const filesToCheck = [...task.inputs];
         for (const file of filesToCheck) {
             // Skip empty strings
@@ -412,12 +447,11 @@ export function checkFilePathConsistency(tasks, basePath) {
             if (!shouldValidateInputAsPath(file))
                 continue;
             // Normalize path for consistent comparison
-            const normalizedFile = normalizeFilePath(file);
+            const normalizedFile = toComparisonPath(file, basePath);
             if (containsGlobPattern(normalizedFile))
                 continue;
             // Check if file exists on disk
-            const absolutePath = resolve(basePath, normalizedFile);
-            const existsOnDisk = existsSync(absolutePath);
+            const existsOnDisk = resolutionRoots.some((root) => existsSync(resolve(root, normalizedFile)));
             // Check if file is in prior expected outputs (priorOutputs already normalized)
             const inPriorOutputs = priorOutputs.has(normalizedFile);
             const inOwnOutputs = ownOutputs.has(normalizedFile);
@@ -455,14 +489,15 @@ export function checkFilePathConsistency(tasks, basePath) {
  *
  * All paths are normalized before comparison to ensure ./src/a.ts matches src/a.ts.
  */
-export function checkTaskOrdering(tasks, basePath) {
+export function checkTaskOrdering(tasks, basePath, context) {
     const results = [];
+    const resolutionRoots = [basePath, ...(context?.additionalRoots ?? [])];
     // Build map: normalized file → task index that creates it
     const fileCreators = new Map();
     for (let i = 0; i < tasks.length; i++) {
         const task = tasks[i];
         for (const file of task.expected_output) {
-            const normalizedFile = normalizeFilePath(file);
+            const normalizedFile = toComparisonPath(file, basePath);
             const existing = fileCreators.get(normalizedFile);
             if (!existing || (!existing.completed && task.status === "completed")) {
                 fileCreators.set(normalizedFile, {
@@ -485,7 +520,7 @@ export function checkTaskOrdering(tasks, basePath) {
                 continue;
             if (!shouldValidateInputAsPath(file))
                 continue;
-            const normalizedFile = normalizeFilePath(file);
+            const normalizedFile = toComparisonPath(file, basePath);
             if (containsGlobPattern(normalizedFile))
                 continue;
             // A directory reference like `artifacts/M009-S03/` is never a concrete
@@ -494,8 +529,7 @@ export function checkTaskOrdering(tasks, basePath) {
             if (isDirectoryReference(file))
                 continue;
             const creator = fileCreators.get(normalizedFile);
-            const absolutePath = resolve(basePath, normalizedFile);
-            const existsOnDisk = existsSync(absolutePath);
+            const existsOnDisk = resolutionRoots.some((root) => existsSync(resolve(root, normalizedFile)));
             // 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
@@ -640,14 +674,15 @@ export function checkInterfaceContracts(tasks, _basePath) {
  * @param basePath - Base path for resolving file references
  * @returns PreExecutionResult with status, checks, and duration
  */
-export async function runPreExecutionChecks(tasks, basePath) {
+export async function runPreExecutionChecks(tasks, basePath, context) {
     const startTime = Date.now();
     const allChecks = [];
     // Run sync checks first
-    const fileChecks = checkFilePathConsistency(tasks, basePath);
-    const orderingChecks = checkTaskOrdering(tasks, basePath);
+    const fileChecks = checkFilePathConsistency(tasks, basePath, context);
+    const orderingChecks = checkTaskOrdering(tasks, basePath, context);
     const contractChecks = checkInterfaceContracts(tasks, basePath);
-    allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks);
+    const verificationChecks = checkVerificationCommands(tasks);
+    allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks, ...verificationChecks);
     // Run async package checks
     const packageChecks = await checkPackageExistence(tasks, basePath);
     allChecks.push(...packageChecks);

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

@@ -0,0 +1,19 @@
+/**
+ * Resolve MCP server config for a given model ID using longest-prefix-wins matching.
+ *
+ * Keys in config.per_model are model-ID prefixes. When modelId.startsWith(key),
+ * the key is a candidate; the longest matching key wins. Returns undefined when
+ * no key matches or per_model is empty.
+ */
+export function resolveModelMcpConfig(modelId, config) {
+    let bestKey;
+    const perModel = config.per_model ?? {};
+    for (const key of Object.keys(perModel)) {
+        if (modelId.startsWith(key)) {
+            if (bestKey === undefined || key.length > bestKey.length) {
+                bestKey = key;
+            }
+        }
+    }
+    return bestKey !== undefined ? perModel[bestKey] : undefined;
+}

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

@@ -29,9 +29,10 @@ export function resolveModelForUnit(unitType) {
  */
 export function resolveModelWithFallbacksForUnit(unitType) {
     const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
-    if (!prefs?.preferences.models)
+    const models = prefs?.preferences?.models;
+    if (!models)
         return undefined;
-    const m = prefs.preferences.models;
+    const m = models;
     let phaseConfig;
     switch (unitType) {
         case "research-milestone":
@@ -128,9 +129,10 @@ export function resolveModelWithFallbacksForUnit(unitType) {
  */
 export function resolveDefaultSessionModel(sessionProvider) {
     const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
-    if (!prefs?.preferences.models)
+    const models = prefs?.preferences?.models;
+    if (!models)
         return undefined;
-    const m = prefs.preferences.models;
+    const m = models;
     // Priority: execution → planning → first configured value
     const candidates = [
         m.execution,

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

@@ -71,6 +71,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "verification_commands",
     "verification_auto_fix",
     "verification_max_retries",
+    "per_unit_cost_cap_usd",
     "search_provider",
     "context_selection",
     "widget_mode",
@@ -99,6 +100,8 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "context_window_override",
     "context_mode",
     "planning_depth",
+    "claude_code_mcp",
+    "workspace",
 ]);
 /**
  * Broad union of every recognized unit-type *label* used across the codebase.

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

@@ -5,6 +5,7 @@
  * Accepts a raw GSDPreferences object and returns a sanitized copy
  * together with any errors and warnings.
  */
+import { isAbsolute } from "node:path";
 import { VALID_BRANCH_NAME } from "./git-service.js";
 import { normalizeStringArray } from "../shared/format-utils.js";
 import { KNOWN_PREFERENCE_KEYS, KNOWN_UNIT_LABELS, SKILL_ACTIONS, } from "./preferences-types.js";
@@ -949,6 +950,15 @@ export function validatePreferences(preferences) {
             errors.push("verification_max_retries must be a non-negative number");
         }
     }
+    if (preferences.per_unit_cost_cap_usd !== undefined) {
+        const raw = preferences.per_unit_cost_cap_usd;
+        if (typeof raw === "number" && Number.isFinite(raw) && raw > 0) {
+            validated.per_unit_cost_cap_usd = raw;
+        }
+        else {
+            errors.push("per_unit_cost_cap_usd must be a positive number");
+        }
+    }
     // ─── Git Preferences ───────────────────────────────────────────────────
     if (preferences.git && typeof preferences.git === "object") {
         const git = {};
@@ -1264,6 +1274,143 @@ export function validatePreferences(preferences) {
             errors.push("codebase must be an object");
         }
     }
+    // ─── Claude Code MCP Per-Model Config ───────────────────────────────────────
+    if (preferences.claude_code_mcp !== undefined) {
+        if (typeof preferences.claude_code_mcp === "object" && preferences.claude_code_mcp !== null) {
+            const raw = preferences.claude_code_mcp;
+            if (typeof raw.per_model !== "object" || raw.per_model === null || Array.isArray(raw.per_model)) {
+                warnings.push("claude_code_mcp.per_model must be an object — ignoring claude_code_mcp");
+            }
+            else {
+                const perModel = raw.per_model;
+                const validPerModel = {};
+                for (const [prefix, entry] of Object.entries(perModel)) {
+                    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+                        warnings.push(`claude_code_mcp.per_model["${prefix}"] must be an object — ignoring entry`);
+                        continue;
+                    }
+                    const e = entry;
+                    const validEntry = {};
+                    for (const field of ["allowed_servers", "blocked_servers"]) {
+                        if (e[field] !== undefined) {
+                            if (Array.isArray(e[field]) && e[field].every((s) => typeof s === "string")) {
+                                validEntry[field] = e[field];
+                            }
+                            else {
+                                warnings.push(`claude_code_mcp.per_model["${prefix}"].${field} must be an array of strings — ignoring field`);
+                            }
+                        }
+                    }
+                    validPerModel[prefix] = validEntry;
+                }
+                validated.claude_code_mcp = { per_model: validPerModel };
+            }
+        }
+        else {
+            warnings.push("claude_code_mcp must be an object — ignoring");
+        }
+    }
+    // ─── Workspace Repository Registry ─────────────────────────────────
+    if (preferences.workspace !== undefined) {
+        if (typeof preferences.workspace === "object" && preferences.workspace !== null && !Array.isArray(preferences.workspace)) {
+            const workspace = preferences.workspace;
+            const validWorkspace = {};
+            if (workspace.mode !== undefined) {
+                if (workspace.mode === "project" || workspace.mode === "parent") {
+                    validWorkspace.mode = workspace.mode;
+                }
+                else {
+                    errors.push('workspace.mode must be one of: project, parent');
+                }
+            }
+            if (workspace.repositories !== undefined) {
+                if (typeof workspace.repositories === "object" &&
+                    workspace.repositories !== null &&
+                    !Array.isArray(workspace.repositories)) {
+                    const repos = workspace.repositories;
+                    const validRepos = {};
+                    const normalizedPaths = new Set();
+                    for (const [repoId, repoValue] of Object.entries(repos)) {
+                        if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(repoId)) {
+                            errors.push(`workspace.repositories key "${repoId}" must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/`);
+                            continue;
+                        }
+                        if (typeof repoValue !== "object" || repoValue === null || Array.isArray(repoValue)) {
+                            errors.push(`workspace.repositories.${repoId} must be an object`);
+                            continue;
+                        }
+                        const repo = repoValue;
+                        const validRepo = { path: "" };
+                        if (typeof repo.path === "string" && repo.path.trim().length > 0) {
+                            validRepo.path = repo.path.trim();
+                            if (isAbsolute(validRepo.path)) {
+                                errors.push(`workspace.repositories.${repoId}.path must be a relative path`);
+                                continue;
+                            }
+                            const normalizedPathKey = validRepo.path.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+                            if (normalizedPaths.has(normalizedPathKey)) {
+                                errors.push(`workspace.repositories contains duplicate path: ${validRepo.path}`);
+                                continue;
+                            }
+                            normalizedPaths.add(normalizedPathKey);
+                        }
+                        else {
+                            errors.push(`workspace.repositories.${repoId}.path must be a non-empty string`);
+                            continue;
+                        }
+                        if (repo.role !== undefined) {
+                            if (typeof repo.role === "string" && repo.role.trim().length > 0)
+                                validRepo.role = repo.role.trim();
+                            else
+                                errors.push(`workspace.repositories.${repoId}.role must be a non-empty string`);
+                        }
+                        if (repo.verification !== undefined) {
+                            if (Array.isArray(repo.verification) &&
+                                repo.verification.every((v) => typeof v === "string" && v.trim().length > 0)) {
+                                validRepo.verification = repo.verification.map((v) => v.trim());
+                            }
+                            else {
+                                errors.push(`workspace.repositories.${repoId}.verification must be an array of non-empty strings`);
+                            }
+                        }
+                        if (repo.commit_policy !== undefined) {
+                            if (repo.commit_policy === "auto" || repo.commit_policy === "skip") {
+                                validRepo.commit_policy = repo.commit_policy;
+                            }
+                            else {
+                                errors.push(`workspace.repositories.${repoId}.commit_policy must be one of: auto, skip`);
+                            }
+                        }
+                        const knownRepoKeys = new Set(["path", "role", "verification", "commit_policy"]);
+                        for (const key of Object.keys(repo)) {
+                            if (!knownRepoKeys.has(key)) {
+                                warnings.push(`unknown workspace.repositories.${repoId} key "${key}" — ignored`);
+                            }
+                        }
+                        validRepos[repoId] = validRepo;
+                    }
+                    if (Object.keys(validRepos).length > 0) {
+                        validWorkspace.repositories = validRepos;
+                    }
+                }
+                else {
+                    errors.push("workspace.repositories must be an object mapping repo ids to config");
+                }
+            }
+            const knownWorkspaceKeys = new Set(["mode", "repositories"]);
+            for (const key of Object.keys(workspace)) {
+                if (!knownWorkspaceKeys.has(key)) {
+                    warnings.push(`unknown workspace key "${key}" — ignored`);
+                }
+            }
+            if (Object.keys(validWorkspace).length > 0) {
+                validated.workspace = validWorkspace;
+            }
+        }
+        else {
+            errors.push("workspace must be an object");
+        }
+    }
     // ─── Enhanced Verification ──────────────────────────────────────────────────
     if (preferences.enhanced_verification !== undefined) {
         if (typeof preferences.enhanced_verification === "boolean") {

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

@@ -38,6 +38,8 @@ export function resolveSkillStalenessDays(basePath) {
 }
 // ─── Re-exports: models ─────────────────────────────────────────────────────
 export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, isTransientNetworkError, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, getProfileTierMap, resolveEffectiveProfile, resolveInlineLevel, resolveContextSelection, resolveSearchProviderFromPreferences, resolveDisabledModelProvidersFromPreferences, } from "./preferences-models.js";
+// ─── Re-exports: MCP ────────────────────────────────────────────────────────
+export { resolveModelMcpConfig } from "./preferences-mcp.js";
 // ─── Path Constants & Getters ───────────────────────────────────────────────
 function globalPreferencesPath() {
     return join(gsdHome(), "PREFERENCES.md");
@@ -65,6 +67,35 @@ export function getLegacyGlobalGSDPreferencesPath() {
 export function getProjectGSDPreferencesPath(basePath) {
     return projectPreferencesPath(basePath);
 }
+/**
+ * Normalize a value loaded from disk (or passed from another component) into
+ * a plain, mutable bare preferences object.
+ *
+ * Accepts:
+ *   - a `LoadedGSDPreferences` wrapper (`{ path, scope, preferences, ... }`)
+ *   - a bare `GSDPreferences` object
+ *   - `null` / `undefined` / any malformed value
+ *
+ * Returns a fresh `Record<string, unknown>` so callers may spread additional
+ * values without mutating the input. This is the single boundary the
+ * preferences wizard funnels existing-on-disk data through, so missing or
+ * partially-formed preference shapes can no longer reach code that assumes
+ * a fully-populated wrapper.
+ */
+export function normalizePreferencesShape(loaded) {
+    if (!loaded || typeof loaded !== "object")
+        return {};
+    const obj = loaded;
+    // Wrapper shape (`LoadedGSDPreferences`) carries the nested preferences
+    // under a `.preferences` key. Bare `GSDPreferences` never declares one
+    // (see preferences-types.ts), so the presence of that key is a reliable
+    // discriminator. Tolerate `preferences: undefined` by falling through to
+    // the empty-object return below.
+    const candidate = "preferences" in obj ? obj.preferences : obj;
+    if (!candidate || typeof candidate !== "object")
+        return {};
+    return { ...candidate };
+}
 // ─── Loading ────────────────────────────────────────────────────────────────
 export function loadGlobalGSDPreferences() {
     return loadPreferencesFile(globalPreferencesPath(), "global")
@@ -272,6 +303,10 @@ export function applyModeDefaults(mode, prefs) {
 }
 function mergePreferences(base, override) {
     return {
+        // Preserve validated preference keys that do not need custom merge logic.
+        // The explicit fields below still own defaults, arrays, and deep merges.
+        ...base,
+        ...override,
         version: override.version ?? base.version,
         mode: override.mode ?? base.mode,
         always_use_skills: mergeStringLists(base.always_use_skills, override.always_use_skills),

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

@@ -181,7 +181,7 @@ export function loadPrompt(name, vars = {}) {
             .map(m => m.slice(2, -2))
             .filter(key => !(key in effectiveVars));
         if (missing.length > 0) {
-            throw new GSDError(GSD_PARSE_ERROR, `loadPrompt("${name}"): template declares {{${missing.join("}}, {{")}}}} but no value was provided. ` +
+            throw new GSDError(GSD_PARSE_ERROR, `loadPrompt("${name}"): template declares {{${missing.join("}}, {{")}}} but no value was provided. ` +
                 `This usually means the extension code in memory is older than the template on disk. ` +
                 `Restart pi to reload the extension.`);
         }

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

@@ -57,7 +57,7 @@ Subagents report only; they do not write user source. Fold any findings into Dec
 **Success path** (all verifications passed):
 
 10. For each requirement whose status changed in step 9, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically. Do this BEFORE completing the milestone so requirement updates are persisted.
-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.
+11. Refresh the project state through `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Do not write or edit `.gsd/PROJECT.md` directly.
 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

@@ -34,7 +34,7 @@ Use `subagent` only for fresh-context review when useful: reviewer for cross-cut
 12. Review the inlined task-summary excerpts for DECISIONS.md and KNOWLEDGE.md-worthy decisions, patterns, and gotchas. Read full `*-SUMMARY.md` files only when an excerpt is absent, truncated, or lacks the specific evidence needed for the slice narrative. Capture significant items with `capture_thought`; do not append knowledge files directly.
 13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes; the tool renders files and updates projections.
 14. Do not run git commands.
-15. Update `.gsd/PROJECT.md` with a full `write` only if the current project state needs refresh.
+15. If the current project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. Do not write or edit `.gsd/PROJECT.md` directly.
 
 **Autonomous execution:** no human is available. Do not call `ask_user_questions` or `secure_env_collect`; make reasonable assumptions and document them.
 

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

@@ -106,8 +106,8 @@ Directories use bare IDs. Files use ID-SUFFIX format. Titles live inside content
 
 In a single pass:
 1. `mkdir -p .gsd/milestones/{{milestoneId}}/slices`
-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 states, ownership, and traceability before roadmap creation.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Describe what the project is, its current state, and list the milestone sequence.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. Confirm states, ownership, and traceability before roadmap creation.
 
 **Depth-Preservation Guidance for context.md:** Preserve the specification's exact terminology, emphasis, and framing. Do not flatten domain-specific language into generics. CONTEXT.md is downstream agents' only window into this spec.
 
@@ -120,8 +120,8 @@ In a single pass:
 
 Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-- [ ] Written `.gsd/PROJECT.md` (step 2)
-- [ ] Written `.gsd/REQUIREMENTS.md` (step 3)
+- [ ] Called `gsd_summary_save` for the PROJECT artifact (step 2)
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact (step 3)
 - [ ] Written `{{contextPath}}` (step 4)
 - [ ] Called `gsd_plan_milestone` (step 5)
 
@@ -145,8 +145,8 @@ Next steps:
 #### Phase 1: Shared artifacts
 
 1. For each milestone, call `gsd_milestone_generate_id`; never invent IDs. Then `mkdir -p .gsd/milestones/<ID>/slices`.
-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.
+2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full Project template content so the tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`.
+3. Persist requirements with `gsd_requirement_save` or `gsd_requirement_update`, then call `gsd_summary_save` with `artifact_type: "REQUIREMENTS"` so the tool renders `.gsd/REQUIREMENTS.md` from DB rows. 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. For any architectural or pattern decisions, call `gsd_decision_save` — the tool auto-assigns IDs and regenerates `.gsd/DECISIONS.md` automatically.
 
 #### Phase 2: Primary milestone
@@ -214,8 +214,8 @@ For single-milestone projects, do NOT write this file.
 
 Before emitting the ready phrase, verify in the CURRENT turn that you have:
 
-- [ ] Written `.gsd/PROJECT.md`
-- [ ] Written `.gsd/REQUIREMENTS.md`
+- [ ] Called `gsd_summary_save` for the PROJECT artifact
+- [ ] Persisted requirements and called `gsd_summary_save` for the REQUIREMENTS artifact
 - [ ] Written the primary milestone `CONTEXT.md`
 - [ ] Called `gsd_plan_milestone` for the primary milestone
 - [ ] Written `.gsd/DISCUSSION-MANIFEST.json` with `gates_completed === total`