gsd-pi 2.57.0 → 2.58.0-dev.394cb18

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -680,6 +680,16 @@ export function nativeAddAll(basePath: string): void {
   gitFileExec(basePath, ["add", "-A"]);
 }
 
+/**
+ * Stage only already-tracked files (git add -u).
+ * Does NOT add new untracked files — only updates modifications and deletions
+ * for files git already knows about. Safe for automated snapshots where
+ * pulling in unknown untracked files (secrets, binaries) would be dangerous.
+ */
+export function nativeAddTracked(basePath: string): void {
+  gitFileExec(basePath, ["add", "-u"]);
+}
+
 /**
  * Stage all files with pathspec exclusions (git add -A -- ':!pattern' ...).
  * Excluded paths are never hashed by git, preventing hangs on large
@@ -931,6 +941,37 @@ export function nativeResetHard(basePath: string): void {
   execSync("git reset --hard HEAD", { cwd: basePath, stdio: "pipe" });
 }
 
+/**
+ * Soft reset to a target ref (git reset --soft <ref>).
+ * Moves HEAD to `target` while keeping all changes staged in the index.
+ * Used to squash snapshot commits back into a single real commit.
+ */
+export function nativeResetSoft(basePath: string, target: string): void {
+  execFileSync("git", ["reset", "--soft", target], {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    env: GIT_NO_PROMPT_ENV,
+  });
+}
+
+/**
+ * Get the subject line of a commit (git log -1 --format=%s <ref>).
+ * Returns empty string if the ref doesn't exist.
+ */
+export function nativeCommitSubject(basePath: string, ref: string): string {
+  try {
+    return execFileSync("git", ["log", "-1", "--format=%s", ref], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+
 /**
  * Delete a branch.
  * Native: libgit2 branch delete.

package/src/resources/extensions/gsd/notifications.ts

@@ -23,7 +23,13 @@ export function sendDesktopNotification(
   message: string,
   level: NotifyLevel = "info",
   kind: NotificationKind = "complete",
+  projectName?: string,
 ): void {
+  // 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;
 
@@ -64,6 +70,16 @@ export function shouldSendDesktopNotification(
   }
 }
 
+/**
+ * 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?: string): string {
+  const trimmed = projectName?.trim();
+  if (trimmed) return `GSD — ${trimmed}`;
+  return "GSD";
+}
+
 export function buildDesktopNotificationCommand(
   platform: NodeJS.Platform,
   title: string,

package/src/resources/extensions/gsd/parallel-eligibility.ts

@@ -112,7 +112,20 @@ export async function analyzeParallelEligibility(
   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") {
@@ -126,7 +139,7 @@ export async function analyzeParallelEligibility(
     }
 
     // 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/src/resources/extensions/gsd/parallel-merge.ts

@@ -5,6 +5,9 @@
  * 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";
@@ -28,22 +31,102 @@ export type MergeOrder = "sequential" | "by-completion";
 
 // ─── 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: string, mid: string): boolean {
+  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: string): Set<string> {
+  const completed = new Set<string>();
+  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: WorkerInfo[],
   order: MergeOrder = "sequential",
+  basePath?: string,
 ): string[] {
-  const completed = workers.filter(w => w.state === "stopped");
+  // 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<string>();
+
+  // 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: WorkerInfo[] = [];
+  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);
 }
@@ -114,7 +197,7 @@ export async function mergeAllCompleted(
   workers: WorkerInfo[],
   order: MergeOrder = "sequential",
 ): Promise<MergeResult[]> {
-  const mergeOrder = determineMergeOrder(workers, order);
+  const mergeOrder = determineMergeOrder(workers, order, basePath);
   const results: MergeResult[] = [];
 
   for (const mid of mergeOrder) {

package/src/resources/extensions/gsd/parallel-orchestrator.ts

@@ -519,8 +519,19 @@ function createMilestoneWorktree(basePath: string, milestoneId: string): string
 
 /**
  * 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: string,
@@ -537,7 +548,7 @@ export function spawnWorker(
 
   let child: ChildProcess;
   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,
@@ -577,9 +588,10 @@ export function spawnWorker(
   }
 
   // ── 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: Buffer) => {
@@ -808,7 +820,12 @@ export async function stopParallel(
       } 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/src/resources/extensions/gsd/parsers-legacy.ts

@@ -196,18 +196,28 @@ function _parsePlanImpl(content: string): SlicePlan {
   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: TaskPlanEntry[] = [];
 
-  if (tasksSection) {
-    const taskLines = tasksSection.split('\n');
+  // Parse task entries from a set of lines, appending to `tasks`.
+  const parseTaskLines = (lines: string[], knownIds: Set<string>): void => {
     let currentTask: TaskPlanEntry | null = 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) {
@@ -259,8 +269,17 @@ function _parsePlanImpl(content: string): SlicePlan {
       }
     }
     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) : [];
 

package/src/resources/extensions/gsd/paths.ts

@@ -264,6 +264,7 @@ export const GSD_ROOT_FILES = {
   REQUIREMENTS: "REQUIREMENTS.md",
   OVERRIDES: "OVERRIDES.md",
   KNOWLEDGE: "KNOWLEDGE.md",
+  CODEBASE: "CODEBASE.md",
 } as const;
 
 export type GSDRootFileKey = keyof typeof GSD_ROOT_FILES;
@@ -276,6 +277,7 @@ const LEGACY_GSD_ROOT_FILES: Record<GSDRootFileKey, string> = {
   REQUIREMENTS: "requirements.md",
   OVERRIDES: "overrides.md",
   KNOWLEDGE: "knowledge.md",
+  CODEBASE: "codebase.md",
 };
 
 // ─── GSD Root Discovery ───────────────────────────────────────────────────────
@@ -307,16 +309,58 @@ export function gsdRoot(basePath: string): string {
   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: string): boolean {
+  // 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: string): string {
   // 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: string;
   try { basePath = realpathSync.native(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/src/resources/extensions/gsd/preferences-models.ts

@@ -69,6 +69,7 @@ export function resolveModelWithFallbacksForUnit(unitType: string): ResolvedMode
       break;
     case "complete-slice":
     case "complete-milestone":
+    case "worktree-merge":
     case "run-uat":
       phaseConfig = m.completion;
       break;
@@ -137,6 +138,18 @@ export function getNextFallbackModel(
   }
 }
 
+/**
+ * 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: string): boolean {
+  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.
@@ -308,7 +321,7 @@ export function resolveContextSelection(): import("./types.js").ContextSelection
 }
 
 /**
- * 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(): GSDPreferences["search_provider"] | undefined {

package/src/resources/extensions/gsd/preferences-types.ts

@@ -93,6 +93,7 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
   "service_tier",
   "forensics_dedup",
   "show_token_cost",
+  "stale_commit_threshold_minutes",
   "experimental",
 ]);
 
@@ -100,7 +101,8 @@ export const KNOWN_PREFERENCE_KEYS = new Set<string>([
 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",
 ] as const;
 export type UnitType = (typeof KNOWN_UNIT_TYPES)[number];
 
@@ -252,6 +254,13 @@ export interface GSDPreferences {
   forensics_dedup?: boolean;
   /** Opt-in: show per-prompt and cumulative session token cost in the footer. Default: false. */
   show_token_cost?: boolean;
+  /**
+   * Minutes without a commit before flagging uncommitted changes as stale.
+   * When the threshold is exceeded and the working tree is dirty, doctor will
+   * auto-commit a safety snapshot tagged with `[gsd safety]`. Default: 30.
+   * Set to 0 to disable.
+   */
+  stale_commit_threshold_minutes?: number;
   /**
    * Opt-in experimental features. All features here are disabled by default.
    * See the preferences reference for details on each feature.

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

@@ -22,6 +22,7 @@ import { normalizeStringArray } from "../shared/format-utils.js";
 import { resolveProfileDefaults as _resolveProfileDefaults } from "./preferences-models.js";
 
 import {
+  KNOWN_PREFERENCE_KEYS,
   MODE_DEFAULTS,
   type WorkflowMode,
   type GSDPreferences,
@@ -68,6 +69,7 @@ export {
   resolveModelForUnit,
   resolveModelWithFallbacksForUnit,
   getNextFallbackModel,
+  isTransientNetworkError,
   validateModelId,
   updatePreferencesModels,
   resolveDynamicRoutingConfig,
@@ -86,7 +88,7 @@ function gsdHome(): string {
 }
 
 function globalPreferencesPath(): string {
-  return join(gsdHome(), "PREFERENCES.md");
+  return join(gsdHome(), "preferences.md");
 }
 
 function legacyGlobalPreferencesPath(): string {
@@ -94,15 +96,15 @@ function legacyGlobalPreferencesPath(): string {
 }
 
 function projectPreferencesPath(): string {
-  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(): string {
-  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(): string {
+  return join(gsdHome(), "PREFERENCES.md");
 }
-function projectPreferencesPathLegacy(): string {
-  return join(gsdRoot(process.cwd()), "preferences.md");
+function projectPreferencesPathUppercase(): string {
+  return join(gsdRoot(process.cwd()), "PREFERENCES.md");
 }
 
 export function getGlobalGSDPreferencesPath(): string {
@@ -121,13 +123,13 @@ export function getProjectGSDPreferencesPath(): string {
 
 export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
   return loadPreferencesFile(globalPreferencesPath(), "global")
-    ?? loadPreferencesFile(globalPreferencesPathLegacy(), "global")
+    ?? loadPreferencesFile(globalPreferencesPathUppercase(), "global")
     ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
 }
 
 export function loadProjectGSDPreferences(): LoadedGSDPreferences | null {
   return loadPreferencesFile(projectPreferencesPath(), "project")
-    ?? loadPreferencesFile(projectPreferencesPathLegacy(), "project");
+    ?? loadPreferencesFile(projectPreferencesPathUppercase(), "project");
 }
 
 export function loadEffectiveGSDPreferences(): LoadedGSDPreferences | null {
@@ -222,7 +224,7 @@ export function parsePreferencesMarkdown(content: string): GSDPreferences | null
 
   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;
 }
@@ -250,7 +252,7 @@ function parseFrontmatterBlock(frontmatter: string): GSDPreferences {
  *   - planner: sonnet
  */
 function parseHeadingListFormat(content: string): GSDPreferences {
-  const result: Record<string, Record<string, string>> = {};
+  const result: Record<string, string[]> = {};
   let currentSection: string | null = null;
 
   for (const rawLine of content.split('\n')) {
@@ -258,27 +260,44 @@ function parseHeadingListFormat(content: string): GSDPreferences {
     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: Record<string, unknown> = {};
-  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: unknown = 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 as Record<string, unknown>)[onlyKey];
+          }
+        }
+      }
+
+      typed[targetSection] = value;
     } catch {
-      typed[section] = entries;
+      /* malformed section — skip */
     }
   }
 
@@ -352,9 +371,6 @@ function mergePreferences(base: GSDPreferences, override: GSDPreferences): GSDPr
     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,
   };
 }
 
@@ -501,7 +517,7 @@ export function resolvePreDispatchHooks(): PreDispatchHookConfig[] {
  * 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/src/resources/extensions/gsd/prompt-loader.ts

@@ -134,7 +134,10 @@ export function loadPrompt(name: string, vars: Record<string, string> = {}): str
   }
 
   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();