gsd-pi 2.57.0 → 2.58.0-dev.394cb18

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

@@ -7,7 +7,12 @@ import { CmuxClient, emitOsc777Notification, resolveCmuxConfig } from "../cmux/i
  * Send a native desktop notification. Non-blocking, non-fatal.
  * macOS: osascript, Linux: notify-send, Windows: skipped.
  */
-export function sendDesktopNotification(title, message, level = "info", kind = "complete") {
+export function sendDesktopNotification(title, message, level = "info", kind = "complete", projectName) {
+    // When a projectName is provided and the title is the default "GSD",
+    // replace it with a project-qualified title for multi-project clarity.
+    if (projectName && title === "GSD") {
+        title = formatNotificationTitle(projectName);
+    }
     const loaded = loadEffectiveGSDPreferences()?.preferences;
     if (!shouldSendDesktopNotification(kind, loaded?.notifications))
         return;
@@ -45,6 +50,16 @@ export function shouldSendDesktopNotification(kind, preferences = loadEffectiveG
             return preferences?.on_complete ?? true;
     }
 }
+/**
+ * Format a notification title that includes the project name for context.
+ * Returns "GSD — projectName" when a project name is available, otherwise "GSD".
+ */
+export function formatNotificationTitle(projectName) {
+    const trimmed = projectName?.trim();
+    if (trimmed)
+        return `GSD — ${trimmed}`;
+    return "GSD";
+}
 export function buildDesktopNotificationCommand(platform, title, message, level = "info") {
     const normalizedTitle = normalizeNotificationText(title);
     const normalizedMessage = normalizeNotificationText(message);

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

@@ -74,7 +74,18 @@ export async function analyzeParallelEligibility(basePath) {
     for (const mid of milestoneIds) {
         const entry = registryMap.get(mid);
         const title = entry?.title ?? mid;
-        const status = entry?.status ?? "pending";
+        // Rule 0: milestones with no registry entry (ghost directories, unknown
+        // state) are ineligible — we cannot determine their status or deps (#2501)
+        if (!entry) {
+            ineligible.push({
+                milestoneId: mid,
+                title,
+                eligible: false,
+                reason: "Milestone has no planning data — cannot determine eligibility.",
+            });
+            continue;
+        }
+        const status = entry.status;
         // Rule 1: skip complete and parked milestones
         if (status === "complete" || status === "parked") {
             ineligible.push({
@@ -86,7 +97,7 @@ export async function analyzeParallelEligibility(basePath) {
             continue;
         }
         // Rule 2: check dependency satisfaction
-        const deps = entry?.dependsOn ?? [];
+        const deps = entry.dependsOn ?? [];
         const unsatisfied = deps.filter(dep => {
             const depEntry = registryMap.get(dep);
             return !depEntry || depEntry.status !== "complete";

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

@@ -4,6 +4,9 @@
  * Handles merging completed milestone worktrees back to main branch
  * with safety checks for parallel execution context.
  */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
 import { loadFile } from "./files.js";
 import { resolveMilestoneFile } from "./paths.js";
 import { mergeMilestoneToMain } from "./auto-worktree.js";
@@ -11,19 +14,89 @@ import { MergeConflictError } from "./git-service.js";
 import { removeSessionStatus } from "./session-status-io.js";
 import { getErrorMessage } from "./error-utils.js";
 // ─── Merge Queue ───────────────────────────────────────────────────────────
+/**
+ * Check whether a milestone is complete by querying its worktree SQLite DB.
+ * Uses a subprocess to avoid disrupting the global DB singleton.
+ * Returns true when milestones.status = 'complete' in the worktree's gsd.db.
+ */
+export function isMilestoneCompleteInWorktreeDb(basePath, mid) {
+    const dbPath = join(basePath, ".gsd", "worktrees", mid, ".gsd", "gsd.db");
+    if (!existsSync(dbPath))
+        return false;
+    try {
+        const result = spawnSync("sqlite3", [dbPath, `SELECT status FROM milestones WHERE id='${mid}' LIMIT 1`], { timeout: 3000, encoding: "utf-8" });
+        return (result.stdout || "").trim() === "complete";
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Discover milestone IDs with status='complete' in their worktree DB,
+ * scanning .gsd/worktrees/<MID>/.gsd/gsd.db for each worktree directory.
+ */
+function discoverDbCompletedMilestones(basePath) {
+    const completed = new Set();
+    const worktreeDir = join(basePath, ".gsd", "worktrees");
+    try {
+        for (const entry of readdirSync(worktreeDir)) {
+            if (entry.startsWith("M") && isMilestoneCompleteInWorktreeDb(basePath, entry)) {
+                completed.add(entry);
+            }
+        }
+    }
+    catch {
+        // worktrees dir may not exist
+    }
+    return completed;
+}
 /**
  * Determine safe merge order for completed milestones.
  * Sequential: merge in milestone ID order (M001 before M002).
  * By-completion: merge in the order milestones finished.
+ *
+ * When basePath is provided, also checks worktree SQLite DBs as the
+ * source of truth — workers with stale orchestrator state (e.g. "error")
+ * are included if their worktree DB shows status='complete'.
+ * See: https://github.com/gsd-build/gsd-2/issues/2812
  */
-export function determineMergeOrder(workers, order = "sequential") {
-    const completed = workers.filter(w => w.state === "stopped");
+export function determineMergeOrder(workers, order = "sequential", basePath) {
+    // Start with workers the orchestrator already knows are stopped
+    const stoppedIds = new Set(workers.filter(w => w.state === "stopped").map(w => w.milestoneId));
+    // When basePath is available, also check worktree DBs for milestones
+    // whose orchestrator state is stale but are actually complete (#2812)
+    const dbCompleted = basePath ? discoverDbCompletedMilestones(basePath) : new Set();
+    // Union: milestone is mergeable if stopped OR DB-complete
+    const mergeableIds = new Set([...stoppedIds, ...dbCompleted]);
+    // Build the list from tracked workers + any DB-discovered milestones
+    // not tracked by the orchestrator at all
+    const workerMap = new Map(workers.map(w => [w.milestoneId, w]));
+    const allMergeable = [];
+    for (const mid of mergeableIds) {
+        const w = workerMap.get(mid);
+        if (w) {
+            allMergeable.push(w);
+        }
+        else {
+            // Milestone discovered from worktree DB but not in workers list
+            allMergeable.push({
+                milestoneId: mid,
+                title: mid,
+                pid: 0,
+                process: null,
+                worktreePath: basePath ? join(basePath, ".gsd", "worktrees", mid) : "",
+                startedAt: 0,
+                state: "stopped",
+                cost: 0,
+            });
+        }
+    }
     if (order === "by-completion") {
-        return completed
+        return allMergeable
             .sort((a, b) => a.startedAt - b.startedAt) // earliest first
             .map(w => w.milestoneId);
     }
-    return completed
+    return allMergeable
         .sort((a, b) => a.milestoneId.localeCompare(b.milestoneId))
         .map(w => w.milestoneId);
 }
@@ -82,7 +155,7 @@ export async function mergeCompletedMilestone(basePath, milestoneId) {
  * Stops on first conflict and returns results so far.
  */
 export async function mergeAllCompleted(basePath, workers, order = "sequential") {
-    const mergeOrder = determineMergeOrder(workers, order);
+    const mergeOrder = determineMergeOrder(workers, order, basePath);
     const results = [];
     for (const mid of mergeOrder) {
         const result = await mergeCompletedMilestone(basePath, mid);

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

@@ -406,8 +406,19 @@ function createMilestoneWorktree(basePath, milestoneId) {
 // ─── Worker Spawning ───────────────────────────────────────────────────
 /**
  * Spawn a worker process for a milestone.
- * The worker runs `gsd --print "/gsd auto"` in the milestone's worktree
+ * The worker runs `gsd headless --json auto` in the milestone's worktree
  * with GSD_MILESTONE_LOCK set to isolate state derivation.
+ *
+ * IMPORTANT: We use `headless --json auto` instead of `--print "/gsd auto"`.
+ * --print mode calls session.prompt() which returns immediately after the
+ * extension command handler fires, because auto-mode's ctx.newSession()
+ * resets the session and unblocks the outer prompt() await. This causes
+ * process.exit(0) to fire before any LLM work happens. See #2792.
+ *
+ * The headless subcommand uses an RPC client that keeps the process alive
+ * until auto-mode emits a terminal notification or the idle timer fires.
+ * It outputs NDJSON events to stdout (with --json), which our
+ * processWorkerLine() parser already understands.
  */
 export function spawnWorker(basePath, milestoneId) {
     if (!state)
@@ -423,7 +434,7 @@ export function spawnWorker(basePath, milestoneId) {
         return false;
     let child;
     try {
-        child = spawn(process.execPath, [binPath, "--mode", "json", "--print", "/gsd auto"], {
+        child = spawn(process.execPath, [binPath, "headless", "--json", "auto"], {
             cwd: worker.worktreePath,
             env: {
                 ...process.env,
@@ -461,9 +472,10 @@ export function spawnWorker(basePath, milestoneId) {
         return false;
     }
     // ── NDJSON stdout monitoring ────────────────────────────────────────
-    // Workers run with --mode json, emitting one JSON event per line.
-    // We parse message_end events to extract cost/token usage, keeping
-    // the coordinator's cost tracking in sync with actual API spend.
+    // Workers run via `headless --json`, which forwards all RPC events
+    // as NDJSON to stdout. We parse message_end events to extract
+    // cost/token usage, keeping the coordinator's cost tracking in sync
+    // with actual API spend.
     if (child.stdout) {
         let stdoutBuffer = "";
         child.stdout.on("data", (data) => {
@@ -674,7 +686,12 @@ export async function stopParallel(basePath, milestoneId) {
             }
             catch { /* process may already be dead */ }
         }
-        const exitedAfterTerm = await waitForWorkerExit(worker, 750);
+        // Wait for the headless process to cascade SIGTERM to its RPC child.
+        // The headless signal handler calls client.stop() which sends SIGTERM
+        // to the RPC child and waits up to 1000ms. The previous 750ms window
+        // was insufficient — the parent got SIGKILL before the child died,
+        // leaving orphaned RPC processes holding auto.lock. See #2798.
+        const exitedAfterTerm = await waitForWorkerExit(worker, 3000);
         if (!exitedAfterTerm && worker.pid > 0) {
             try {
                 if (worker.process) {

package/dist/resources/extensions/gsd/parsers-legacy.js

@@ -165,16 +165,26 @@ function _parsePlanImpl(content) {
     const demo = extractBoldField(body, 'Demo') || '';
     const mhSection = extractSection(body, 'Must-Haves');
     const mustHaves = mhSection ? parseBullets(mhSection) : [];
+    // Parse tasks from ## Tasks section first, then scan the full body for any
+    // task checkboxes that were missed. Multi-task plans can interleave T01 detail
+    // headings (## Steps, ## Must-Haves) before T02's checkbox, which causes
+    // extractSection("Tasks") to stop at the first ## heading and miss T02+ (#3105).
     const tasksSection = extractSection(body, 'Tasks');
     const tasks = [];
-    if (tasksSection) {
-        const taskLines = tasksSection.split('\n');
+    // Parse task entries from a set of lines, appending to `tasks`.
+    const parseTaskLines = (lines, knownIds) => {
         let currentTask = null;
-        for (const line of taskLines) {
+        for (const line of lines) {
             const cbMatch = line.match(/^-\s+\[([ xX])\]\s+\*\*([\w.]+):\s+(.+?)\*\*\s*(.*)/);
             // Heading-style: ### T01 -- Title, ### T01: Title, ### T01 — Title
             const hdMatch = !cbMatch ? line.match(/^#{2,4}\s+([\w.]+)\s*(?:--|—|:)\s*(.+)/) : null;
             if (cbMatch || hdMatch) {
+                const taskId = cbMatch ? cbMatch[2] : hdMatch[1];
+                // Skip tasks already found in the Tasks section
+                if (knownIds.has(taskId)) {
+                    currentTask = null;
+                    continue;
+                }
                 if (currentTask)
                     tasks.push(currentTask);
                 if (cbMatch) {
@@ -229,7 +239,14 @@ function _parsePlanImpl(content) {
         }
         if (currentTask)
             tasks.push(currentTask);
+    };
+    if (tasksSection) {
+        parseTaskLines(tasksSection.split('\n'), new Set());
     }
+    // Second pass: scan the full body for task checkboxes outside ## Tasks.
+    // This handles interleaved plans where T02+ appear after T01's detail headings.
+    const foundIds = new Set(tasks.map(t => t.id));
+    parseTaskLines(body.split('\n'), foundIds);
     const filesSection = extractSection(body, 'Files Likely Touched');
     const filesLikelyTouched = filesSection ? parseBullets(filesSection) : [];
     const result = { id, title, goal, demo, mustHaves, tasks, filesLikelyTouched };

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

@@ -254,6 +254,7 @@ export const GSD_ROOT_FILES = {
     REQUIREMENTS: "REQUIREMENTS.md",
     OVERRIDES: "OVERRIDES.md",
     KNOWLEDGE: "KNOWLEDGE.md",
+    CODEBASE: "CODEBASE.md",
 };
 const LEGACY_GSD_ROOT_FILES = {
     PROJECT: "project.md",
@@ -263,6 +264,7 @@ const LEGACY_GSD_ROOT_FILES = {
     REQUIREMENTS: "requirements.md",
     OVERRIDES: "overrides.md",
     KNOWLEDGE: "knowledge.md",
+    CODEBASE: "codebase.md",
 };
 // ─── GSD Root Discovery ───────────────────────────────────────────────────────
 const gsdRootCache = new Map();
@@ -289,11 +291,51 @@ export function gsdRoot(basePath) {
     gsdRootCache.set(basePath, result);
     return result;
 }
+/**
+ * Detect if a path is inside a .gsd/worktrees/<name>/ structure.
+ *
+ * GSD auto-worktrees live at <project>/.gsd/worktrees/<milestoneId>/.
+ * When gsdRoot() is called with such a path, we must NOT walk up to the
+ * project root's .gsd — each worktree manages its own .gsd state (#2594).
+ *
+ * Matches both forward-slash and platform-native separators to handle
+ * Windows paths (path.sep = '\\') and normalized Unix paths.
+ */
+function isInsideGsdWorktree(p) {
+    // Match /.gsd/worktrees/<name> where <name> is the final segment or
+    // followed by a separator. The <name> segment must be non-empty.
+    const sepFwd = "/";
+    const sepNative = "\\";
+    const markers = [
+        `${sepFwd}.gsd${sepFwd}worktrees${sepFwd}`,
+        `${sepNative}.gsd${sepNative}worktrees${sepNative}`,
+    ];
+    for (const marker of markers) {
+        const idx = p.indexOf(marker);
+        if (idx === -1)
+            continue;
+        // Verify there's a non-empty worktree name after the marker
+        const afterMarker = p.slice(idx + marker.length);
+        // The name is everything up to the next separator (or end of string)
+        const nameEnd = afterMarker.search(/[/\\]/);
+        const name = nameEnd === -1 ? afterMarker : afterMarker.slice(0, nameEnd);
+        if (name.length > 0)
+            return true;
+    }
+    return false;
+}
 function probeGsdRoot(rawBasePath) {
     // 1. Fast path — check the input path directly
     const local = join(rawBasePath, ".gsd");
     if (existsSync(local))
         return local;
+    // 1b. Worktree guard (#2594) — if basePath is inside a .gsd/worktrees/<name>/
+    //     structure, return the worktree-local .gsd path immediately. Without this,
+    //     the git-root probe (step 2) or walk-up (step 3) escapes to the project
+    //     root's .gsd, causing ensurePreconditions() and deriveState() to read/write
+    //     state in the wrong location.
+    if (isInsideGsdWorktree(rawBasePath))
+        return local;
     // Resolve symlinks so path comparisons work correctly across platforms
     // (e.g. macOS /var → /private/var). Use rawBasePath as fallback if not resolvable.
     let basePath;
@@ -303,6 +345,9 @@ function probeGsdRoot(rawBasePath) {
     catch {
         basePath = rawBasePath;
     }
+    // Also check the resolved path for the worktree pattern (macOS /tmp → /private/tmp)
+    if (basePath !== rawBasePath && isInsideGsdWorktree(basePath))
+        return local;
     // 2. Git root anchor — used as both probe target and walk-up boundary
     //    Only walk if we're inside a git project — prevents escaping into
     //    unrelated filesystem territory when running outside any repo.

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

@@ -53,6 +53,7 @@ export function resolveModelWithFallbacksForUnit(unitType) {
             break;
         case "complete-slice":
         case "complete-milestone":
+        case "worktree-merge":
         case "run-uat":
             phaseConfig = m.completion;
             break;
@@ -110,6 +111,18 @@ export function getNextFallbackModel(currentModelId, modelConfig) {
         return modelsToTry[0];
     }
 }
+/**
+ * Detect whether an error message indicates a transient network error
+ * (worth retrying the same model) vs a permanent provider error
+ * (auth failure, quota exceeded, etc. -- should fall back immediately).
+ */
+export function isTransientNetworkError(errorMsg) {
+    if (!errorMsg)
+        return false;
+    const hasNetworkSignal = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i.test(errorMsg);
+    const hasPermanentSignal = /auth|unauthorized|forbidden|invalid.*key|quota|billing/i.test(errorMsg);
+    return hasNetworkSignal && !hasPermanentSignal;
+}
 /**
  * Validate a model ID string.
  * Returns true if the ID looks like a valid model identifier.
@@ -273,7 +286,7 @@ export function resolveContextSelection() {
     return profile === "budget" ? "smart" : "full";
 }
 /**
- * Resolve the search provider preference from PREFERENCES.md.
+ * Resolve the search provider preference from preferences.md.
  * Returns undefined if not configured (caller falls back to existing behavior).
  */
 export function resolveSearchProviderFromPreferences() {

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

@@ -70,12 +70,14 @@ export const KNOWN_PREFERENCE_KEYS = new Set([
     "service_tier",
     "forensics_dedup",
     "show_token_cost",
+    "stale_commit_threshold_minutes",
     "experimental",
 ]);
 /** Canonical list of all dispatch unit types. */
 export const KNOWN_UNIT_TYPES = [
     "research-milestone", "plan-milestone", "research-slice", "plan-slice",
     "execute-task", "reactive-execute", "gate-evaluate", "complete-slice", "replan-slice", "reassess-roadmap",
-    "run-uat", "complete-milestone",
+    "run-uat", "complete-milestone", "validate-milestone", "rewrite-docs",
+    "discuss-milestone", "discuss-slice", "worktree-merge",
 ];
 export const SKILL_ACTIONS = new Set(["use", "prefer", "avoid"]);

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

@@ -16,7 +16,7 @@ import { gsdRoot } from "./paths.js";
 import { parse as parseYaml } from "yaml";
 import { normalizeStringArray } from "../shared/format-utils.js";
 import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
-import { MODE_DEFAULTS, } from "./preferences-types.js";
+import { KNOWN_PREFERENCE_KEYS, MODE_DEFAULTS, } from "./preferences-types.js";
 import { validatePreferences } from "./preferences-validation.js";
 import { formatSkillRef } from "./preferences-skills.js";
 // ─── Re-exports: validation ─────────────────────────────────────────────────
@@ -24,27 +24,27 @@ export { validatePreferences } from "./preferences-validation.js";
 // ─── Re-exports: skills ─────────────────────────────────────────────────────
 export { resolveAllSkillReferences, resolveSkillDiscoveryMode, resolveSkillStalenessDays, } from "./preferences-skills.js";
 // ─── Re-exports: models ─────────────────────────────────────────────────────
-export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, resolveEffectiveProfile, resolveInlineLevel, resolveContextSelection, resolveSearchProviderFromPreferences, } from "./preferences-models.js";
+export { resolveModelForUnit, resolveModelWithFallbacksForUnit, getNextFallbackModel, isTransientNetworkError, validateModelId, updatePreferencesModels, resolveDynamicRoutingConfig, resolveAutoSupervisorConfig, resolveProfileDefaults, resolveEffectiveProfile, resolveInlineLevel, resolveContextSelection, resolveSearchProviderFromPreferences, } from "./preferences-models.js";
 // ─── Path Constants & Getters ───────────────────────────────────────────────
 function gsdHome() {
     return process.env.GSD_HOME || join(homedir(), ".gsd");
 }
 function globalPreferencesPath() {
-    return join(gsdHome(), "PREFERENCES.md");
+    return join(gsdHome(), "preferences.md");
 }
 function legacyGlobalPreferencesPath() {
     return join(homedir(), ".pi", "agent", "gsd-preferences.md");
 }
 function projectPreferencesPath() {
-    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
+    return join(gsdRoot(process.cwd()), "preferences.md");
 }
-// Legacy: older versions used lowercase preferences.md.
-// Check lowercase as a fallback so those files aren't silently ignored.
-function globalPreferencesPathLegacy() {
-    return join(gsdHome(), "preferences.md");
+// Bootstrap in gitignore.ts historically created PREFERENCES.md (uppercase) by mistake.
+// Check uppercase as a fallback so those files aren't silently ignored.
+function globalPreferencesPathUppercase() {
+    return join(gsdHome(), "PREFERENCES.md");
 }
-function projectPreferencesPathLegacy() {
-    return join(gsdRoot(process.cwd()), "preferences.md");
+function projectPreferencesPathUppercase() {
+    return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }
 export function getGlobalGSDPreferencesPath() {
     return globalPreferencesPath();
@@ -58,12 +58,12 @@ export function getProjectGSDPreferencesPath() {
 // ─── Loading ────────────────────────────────────────────────────────────────
 export function loadGlobalGSDPreferences() {
     return loadPreferencesFile(globalPreferencesPath(), "global")
-        ?? loadPreferencesFile(globalPreferencesPathLegacy(), "global")
+        ?? loadPreferencesFile(globalPreferencesPathUppercase(), "global")
         ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 export function loadProjectGSDPreferences() {
     return loadPreferencesFile(projectPreferencesPath(), "project")
-        ?? loadPreferencesFile(projectPreferencesPathLegacy(), "project");
+        ?? loadPreferencesFile(projectPreferencesPathUppercase(), "project");
 }
 export function loadEffectiveGSDPreferences() {
     const globalPreferences = loadGlobalGSDPreferences();
@@ -149,7 +149,7 @@ export function parsePreferencesMarkdown(content) {
     }
     if (!_warnedUnrecognizedFormat) {
         _warnedUnrecognizedFormat = true;
-        console.warn("[parsePreferencesMarkdown] PREFERENCES.md exists but uses an unrecognized format — skipping.");
+        console.warn("[parsePreferencesMarkdown] preferences.md exists but uses an unrecognized format — skipping.");
     }
     return null;
 }
@@ -183,28 +183,42 @@ function parseHeadingListFormat(content) {
         const headingMatch = line.match(/^##\s+(.+)$/);
         if (headingMatch) {
             currentSection = headingMatch[1].trim().toLowerCase().replace(/\s+/g, '_');
+            if (!result[currentSection])
+                result[currentSection] = [];
             continue;
         }
-        if (currentSection) {
-            const itemMatch = line.match(/^-\s+([^:]+):\s*(.*)$/);
-            if (itemMatch) {
-                if (!result[currentSection])
-                    result[currentSection] = {};
-                const value = itemMatch[2].trim();
-                // Coerce "true"/"false" strings and numbers
-                result[currentSection][itemMatch[1].trim()] = value;
-            }
+        if (currentSection && line.trim() && !line.trimStart().startsWith('#')) {
+            result[currentSection].push(line);
         }
     }
-    // Convert string values to appropriate types via YAML parser for each section
     const typed = {};
-    for (const [section, entries] of Object.entries(result)) {
-        const yamlLines = Object.entries(entries).map(([k, v]) => `${k}: ${v}`).join('\n');
+    for (const [section, lines] of Object.entries(result)) {
+        if (lines.length === 0)
+            continue;
+        const usesLegacyListItems = lines.every((line) => /^\s*-\s+[^:]+:\s*.*$/.test(line));
+        const yamlBlock = usesLegacyListItems
+            ? lines.map((line) => line.replace(/^\s*-\s+/, '')).join('\n')
+            : lines.join('\n');
         try {
-            typed[section] = parseYaml(yamlLines);
+            const parsed = parseYaml(yamlBlock);
+            if (typeof parsed !== 'object' || parsed === null)
+                continue;
+            let targetSection = section;
+            let value = parsed;
+            if (!Array.isArray(parsed)) {
+                const keys = Object.keys(parsed);
+                if (keys.length === 1) {
+                    const [onlyKey] = keys;
+                    if (onlyKey === section || (!KNOWN_PREFERENCE_KEYS.has(section) && KNOWN_PREFERENCE_KEYS.has(onlyKey))) {
+                        targetSection = onlyKey;
+                        value = parsed[onlyKey];
+                    }
+                }
+            }
+            typed[targetSection] = value;
         }
         catch {
-            typed[section] = entries;
+            /* malformed section — skip */
         }
     }
     return typed;
@@ -275,9 +289,6 @@ function mergePreferences(base, override) {
         service_tier: override.service_tier ?? base.service_tier,
         forensics_dedup: override.forensics_dedup ?? base.forensics_dedup,
         show_token_cost: override.show_token_cost ?? base.show_token_cost,
-        experimental: (base.experimental || override.experimental)
-            ? { ...(base.experimental ?? {}), ...(override.experimental ?? {}) }
-            : undefined,
     };
 }
 function mergeStringLists(base, override) {
@@ -398,7 +409,7 @@ export function resolvePreDispatchHooks() {
  * Resolve the effective git isolation mode from preferences.
  * Returns "none" (default), "worktree", or "branch".
  *
- * Default is "none" so GSD works out of the box without PREFERENCES.md.
+ * Default is "none" so GSD works out of the box without preferences.md.
  * Worktree isolation requires explicit opt-in because it depends on git
  * branch infrastructure that must be set up before use.
  */

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

@@ -124,7 +124,10 @@ export function loadPrompt(name, vars = {}) {
         }
     }
     for (const [key, value] of Object.entries(effectiveVars)) {
-        content = content.replaceAll(`{{${key}}}`, value);
+        // Use split/join instead of replaceAll to avoid JavaScript's special
+        // replacement patterns ($', $`, $&) being interpreted in the value.
+        // See: https://github.com/gsd-build/gsd-2/issues/2968
+        content = content.split(`{{${key}}}`).join(value);
     }
     return content.trim();
 }

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

@@ -56,7 +56,7 @@ Then:
    - `followUps` (string) — Follow-up items for future milestones
    - `deviations` (string) — Deviations from the original plan
 10. For each requirement whose status changed in step 8, call `gsd_requirement_update` with the requirement ID and updated `status` and `validation` fields — the tool regenerates `.gsd/REQUIREMENTS.md` automatically.
-11. Update `.gsd/PROJECT.md` to reflect milestone completion and current project state.
+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. Review all slice summaries for cross-cutting lessons, patterns, or gotchas that emerged during this milestone. Append any non-obvious, reusable insights to `.gsd/KNOWLEDGE.md`.
 13. Do not commit manually — the system auto-commits your changes after this unit completes.
 - Say: "Milestone {{milestoneId}} complete."

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

@@ -29,9 +29,11 @@ Then:
 8. Write `{{sliceUatPath}}` — 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.
-11. Call `gsd_complete_slice` with milestone_id, slice_id, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders the ROADMAP.md projection automatically.
+11. Call `gsd_complete_slice` with milestoneId, sliceId, the slice summary, and the UAT result. Do NOT manually mark the roadmap checkbox — the tool writes to the DB and renders 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.
+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.
+
+**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the slice summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
 
 **You MUST call `gsd_complete_slice` with the slice summary and UAT content before finishing. The tool persists to both DB and disk and renders `{{sliceSummaryPath}}` and `{{sliceUatPath}}` automatically.**
 

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

@@ -38,7 +38,7 @@ Do a mandatory investigation pass before making any decisions. This is not optio
 3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the spec references external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough.
 
 **Web search budget:** Budget carefully across investigation + focused research:
-- Prefer `resolve_library` / `get_library_docs` over `web_search` for library documentation.
+- Prefer `resolve_library` / `get_library_docs` over `search-the-web` for library documentation.
 - Prefer `search_and_read` for one-shot topic research.
 - Target 2-3 web searches in this investigation pass. Save remaining budget for focused research.
 - Do NOT repeat the same or similar queries.

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

@@ -37,7 +37,7 @@ Before asking your first question, do a mandatory investigation pass. This is no
 3. **Web search** — `search-the-web` if the domain is unfamiliar, if you need current best practices, or if the user referenced external services/APIs you need facts about. Use `fetch_page` for full content when snippets aren't enough.
 
 **Web search budget:** You have a limited number of web searches per turn (typically 3-5). The discuss phase spans many turns (investigation, question rounds, focused research, requirements), so budget carefully:
-- Prefer `resolve_library` / `get_library_docs` over `web_search` for library documentation — they don't consume the web search budget.
+- Prefer `resolve_library` / `get_library_docs` over `search-the-web` for library documentation — they don't consume the web search budget.
 - Prefer `search_and_read` for one-shot topic research — it combines search + page fetch in a single call.
 - Target 2-3 web searches in the investigation pass. Save remaining budget for the focused research pass before roadmap creation.
 - Do NOT repeat the same or similar queries. If a search didn't find what you need, rephrase once or move on.

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

@@ -68,11 +68,13 @@ Then:
 17. If you discover a non-obvious rule, recurring gotcha, or useful pattern during execution, append it to `.gsd/KNOWLEDGE.md`. Only add entries that would save future agents from repeating your investigation. Don't add obvious things.
 18. Read the template at `~/.gsd/agent/extensions/gsd/templates/task-summary.md`
 19. Write `{{taskSummaryPath}}`
-20. Call `gsd_complete_task` with milestone_id, slice_id, task_id, and a summary of what was accomplished. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, and renders PLAN.md automatically.
+20. Call `gsd_complete_task` with milestoneId, sliceId, taskId, and a summary of what was accomplished. This is your final required step — do NOT manually edit PLAN.md checkboxes. The tool marks the task complete, updates the DB, and renders PLAN.md automatically.
 21. Do not run git commands — the system reads your task summary after completion and creates a meaningful commit from it (type inferred from title, message from your one-liner, key files from frontmatter). Write a clear, specific one-liner in the summary — it becomes the commit message.
 
 All work stays in your working directory: `{{workingDirectory}}`.
 
+**Autonomous execution:** Do not call `ask_user_questions` or `secure_env_collect`. You are running in auto-mode — there is no human available to answer questions. Make reasonable assumptions and document them in the task summary. If a decision genuinely requires human input, note it in the summary and proceed with the best available option.
+
 **You MUST call `gsd_complete_task` AND write `{{taskSummaryPath}}` before finishing.**
 
 When done, say: "Task {{taskId}} complete."