gsd-pi 2.51.0 → 2.52.0-dev.655ad8a

package/src/resources/extensions/gsd/claude-import.ts

@@ -103,16 +103,47 @@ function isMarketplacePath(pluginPath: string): boolean {
 
 /**
  * Detect which plugin roots are marketplaces and which are legacy flat paths.
+ *
+ * Claude Code stores marketplace sources under ~/.claude/plugins/marketplaces/.
+ * Each subdirectory (e.g. marketplaces/confluent/) is a marketplace repo that
+ * contains .claude-plugin/marketplace.json. The parent directory itself does not
+ * have a marketplace.json, so we scan one level deeper when the root isn't
+ * directly a marketplace.
  */
-function categorizePluginRoots(pluginRoots: string[]): { marketplaces: string[]; flat: string[] } {
+export function categorizePluginRoots(pluginRoots: string[]): { marketplaces: string[]; flat: string[] } {
   const marketplaces: string[] = [];
   const flat: string[] = [];
+  const seen = new Set<string>();
 
   for (const root of pluginRoots) {
     if (isMarketplacePath(root)) {
-      marketplaces.push(root);
+      if (!seen.has(root)) {
+        marketplaces.push(root);
+        seen.add(root);
+      }
     } else {
-      flat.push(root);
+      // The root itself isn't a marketplace — check if it's a container of
+      // marketplaces (e.g. ~/.claude/plugins/marketplaces/ contains subdirs
+      // like confluent/, claude-hud/, each with their own marketplace.json).
+      let foundChild = false;
+      try {
+        const entries = readdirSync(root, { withFileTypes: true });
+        for (const entry of entries) {
+          if (!entry.isDirectory()) continue;
+          if (SKIP_DIRS.has(entry.name)) continue;
+          const childPath = join(root, entry.name);
+          if (isMarketplacePath(childPath) && !seen.has(childPath)) {
+            marketplaces.push(childPath);
+            seen.add(childPath);
+            foundChild = true;
+          }
+        }
+      } catch {
+        // Can't read directory — fall through to flat
+      }
+      if (!foundChild) {
+        flat.push(root);
+      }
     }
   }
 
@@ -170,18 +201,36 @@ export function discoverClaudePlugins(cwd: string): ClaudePluginCandidate[] {
 
   for (const root of pluginRoots) {
     walkDirs(root, (dir) => {
+      // Recognize both npm-style plugins (package.json) and Claude Code plugins
+      // (.claude-plugin/plugin.json). Claude marketplace-installed plugins use
+      // the latter format exclusively.
       const pkgPath = join(dir, "package.json");
-      if (!existsSync(pkgPath)) return;
+      const claudePluginPath = join(dir, ".claude-plugin", "plugin.json");
+      const hasPkg = existsSync(pkgPath);
+      const hasClaudePlugin = existsSync(claudePluginPath);
+      if (!hasPkg && !hasClaudePlugin) return;
+
       const resolvedDir = resolve(dir);
       if (seen.has(resolvedDir)) return;
       seen.add(resolvedDir);
+
       let packageName: string | undefined;
-      try {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
-        packageName = pkg.name;
-      } catch {
-        packageName = undefined;
+      if (hasPkg) {
+        try {
+          const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
+          packageName = pkg.name;
+        } catch {
+          packageName = undefined;
+        }
+      } else if (hasClaudePlugin) {
+        try {
+          const manifest = JSON.parse(readFileSync(claudePluginPath, "utf8")) as { name?: string };
+          packageName = manifest.name;
+        } catch {
+          packageName = undefined;
+        }
       }
+
       results.push({
         type: "plugin",
         name: packageName || basename(dir),

package/src/resources/extensions/gsd/commands/handlers/auto.ts

@@ -7,6 +7,7 @@ import { enableDebug } from "../../debug-logger.js";
 import { getAutoDashboardData, isAutoActive, isAutoPaused, pauseAuto, startAuto, stopAuto, stopAutoRemote } from "../../auto.js";
 import { handleRate } from "../../commands-rate.js";
 import { guardRemoteSession, projectRoot } from "../context.js";
+import { findMilestoneIds } from "../../milestone-id-utils.js";
 
 /**
  * Parse --yolo flag and optional file path from the auto command string.
@@ -28,6 +29,39 @@ function parseYoloFlag(trimmed: string): { yoloSeedFile: string | null; rest: st
   return { yoloSeedFile: filePath, rest };
 }
 
+/**
+ * Extract a milestone ID (e.g. M016 or M001-a3b4c5) from the command string.
+ * Returns the matched ID and the remaining string with the ID removed.
+ * The milestone ID pattern matches the format used by findMilestoneIds: M\d+ with
+ * an optional -[a-z0-9]{6} suffix for unique milestone IDs.
+ */
+export function parseMilestoneTarget(input: string): { milestoneId: string | null; rest: string } {
+  const match = input.match(/\b(M\d+(?:-[a-z0-9]{6})?)\b/);
+  if (!match) return { milestoneId: null, rest: input };
+  const rest = input.replace(match[0], "").replace(/\s+/g, " ").trim();
+  return { milestoneId: match[1], rest };
+}
+
+/**
+ * Set GSD_MILESTONE_LOCK to target a specific milestone, then run `fn`.
+ * Clears the env var when `fn` resolves or rejects, so the lock does not
+ * leak into subsequent commands in the same process.
+ */
+async function withMilestoneLock(milestoneId: string, fn: () => Promise<void>): Promise<void> {
+  const previous = process.env.GSD_MILESTONE_LOCK;
+  process.env.GSD_MILESTONE_LOCK = milestoneId;
+  try {
+    await fn();
+  } finally {
+    // Restore previous value (undefined → delete, else restore).
+    if (previous === undefined) {
+      delete process.env.GSD_MILESTONE_LOCK;
+    } else {
+      process.env.GSD_MILESTONE_LOCK = previous;
+    }
+  }
+}
+
 export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
   if (trimmed === "next" || trimmed.startsWith("next ")) {
     if (trimmed.includes("--dry-run")) {
@@ -35,21 +69,48 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
       await handleDryRun(ctx, projectRoot());
       return true;
     }
-    const verboseMode = trimmed.includes("--verbose");
-    const debugMode = trimmed.includes("--debug");
+    const { milestoneId, rest: afterMilestone } = parseMilestoneTarget(trimmed);
+    const verboseMode = afterMilestone.includes("--verbose");
+    const debugMode = afterMilestone.includes("--debug");
     if (debugMode) enableDebug(projectRoot());
     if (!(await guardRemoteSession(ctx, pi))) return true;
-    await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
+
+    // Validate the milestone target exists and is not already complete.
+    if (milestoneId) {
+      const allIds = findMilestoneIds(projectRoot());
+      if (!allIds.includes(milestoneId)) {
+        ctx.ui.notify(`Milestone ${milestoneId} does not exist. Available: ${allIds.join(", ") || "(none)"}`, "error");
+        return true;
+      }
+    }
+
+    if (milestoneId) {
+      await withMilestoneLock(milestoneId, () =>
+        startAuto(ctx, pi, projectRoot(), verboseMode, { step: true }),
+      );
+    } else {
+      await startAuto(ctx, pi, projectRoot(), verboseMode, { step: true });
+    }
     return true;
   }
 
   if (trimmed === "auto" || trimmed.startsWith("auto ")) {
-    const { yoloSeedFile, rest } = parseYoloFlag(trimmed);
-    const verboseMode = rest.includes("--verbose");
-    const debugMode = rest.includes("--debug");
+    const { yoloSeedFile, rest: afterYolo } = parseYoloFlag(trimmed);
+    const { milestoneId, rest: afterMilestone } = parseMilestoneTarget(afterYolo);
+    const verboseMode = afterMilestone.includes("--verbose");
+    const debugMode = afterMilestone.includes("--debug");
     if (debugMode) enableDebug(projectRoot());
     if (!(await guardRemoteSession(ctx, pi))) return true;
 
+    // Validate the milestone target exists and is not already complete.
+    if (milestoneId) {
+      const allIds = findMilestoneIds(projectRoot());
+      if (!allIds.includes(milestoneId)) {
+        ctx.ui.notify(`Milestone ${milestoneId} does not exist. Available: ${allIds.join(", ") || "(none)"}`, "error");
+        return true;
+      }
+    }
+
     if (yoloSeedFile) {
       const resolved = resolve(projectRoot(), yoloSeedFile);
       if (!existsSync(resolved)) {
@@ -66,6 +127,12 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
       // when the LLM says "Milestone X ready."
       const { showHeadlessMilestoneCreation } = await import("../../guided-flow.js");
       await showHeadlessMilestoneCreation(ctx, pi, projectRoot(), seedContent);
+    } else if (milestoneId) {
+      // Target a specific milestone — use GSD_MILESTONE_LOCK so state
+      // derivation only sees this milestone (#2521).
+      await withMilestoneLock(milestoneId, () =>
+        startAuto(ctx, pi, projectRoot(), verboseMode),
+      );
     } else {
       await startAuto(ctx, pi, projectRoot(), verboseMode);
     }

package/src/resources/extensions/gsd/commands-config.ts

@@ -22,6 +22,12 @@ export const TOOL_KEYS = [
   { id: "groq",     env: "GROQ_API_KEY",      label: "Groq Voice",        hint: "console.groq.com" },
 ] as const;
 
+function getStoredToolKey(auth: AuthStorage, providerId: string): string | undefined {
+  const creds = auth.getCredentialsForProvider(providerId);
+  const cred = creds.find((c) => c.type === "api_key" && c.key);
+  return cred?.type === "api_key" ? cred.key : undefined;
+}
+
 /**
  * Load tool API keys from auth.json into environment variables.
  * Called at session startup to ensure tools have access to their credentials.
@@ -33,9 +39,9 @@ export function loadToolApiKeys(): void {
 
     const auth = AuthStorage.create(authPath);
     for (const tool of TOOL_KEYS) {
-      const cred = auth.get(tool.id);
-      if (cred && cred.type === "api_key" && cred.key && !process.env[tool.env]) {
-        process.env[tool.env] = cred.key;
+      const key = getStoredToolKey(auth, tool.id);
+      if (key && !process.env[tool.env]) {
+        process.env[tool.env] = key;
       }
     }
   } catch {
@@ -55,14 +61,14 @@ export async function handleConfig(ctx: ExtensionCommandContext): Promise<void>
   // Show current status
   const statusLines = ["GSD Tool Configuration\n"];
   for (const tool of TOOL_KEYS) {
-    const hasKey = !!process.env[tool.env] || !!(auth.get(tool.id) as { key?: string })?.key;
+    const hasKey = !!process.env[tool.env] || !!getStoredToolKey(auth, tool.id);
     statusLines.push(`  ${hasKey ? "\u2713" : "\u2717"} ${tool.label}${hasKey ? "" : ` \u2014 get key at ${tool.hint}`}`);
   }
   ctx.ui.notify(statusLines.join("\n"), "info");
 
   // Ask which tools to configure
   const options = TOOL_KEYS.map(t => {
-    const hasKey = !!process.env[t.env] || !!(auth.get(t.id) as { key?: string })?.key;
+    const hasKey = !!process.env[t.env] || !!getStoredToolKey(auth, t.id);
     return `${t.label} ${hasKey ? "(configured \u2713)" : "(not set)"}`;
   });
   options.push("(done)");

package/src/resources/extensions/gsd/commands-prefs-wizard.ts

@@ -390,7 +390,7 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string,
   const gitBooleanFields = [
     { key: "auto_push", label: "Auto-push commits after committing", defaultVal: false },
     { key: "push_branches", label: "Push milestone branches to remote", defaultVal: false },
-    { key: "snapshots", label: "Create WIP snapshot commits during long tasks", defaultVal: false },
+    { key: "snapshots", label: "Create WIP snapshot commits during long tasks", defaultVal: true },
   ] as const;
 
   for (const field of gitBooleanFields) {
@@ -423,7 +423,7 @@ async function configureGit(ctx: ExtensionCommandContext, prefs: Record<string,
   // pre_merge_check
   const currentPreMerge = git.pre_merge_check !== undefined ? String(git.pre_merge_check) : "";
   const preMergeChoice = await ctx.ui.select(
-    `Pre-merge check${currentPreMerge ? ` (current: ${currentPreMerge})` : " (default: false)"}:`,
+    `Pre-merge check${currentPreMerge ? ` (current: ${currentPreMerge})` : " (default: auto)"}:`,
     ["true", "false", "auto", "(keep current)"],
   );
   if (preMergeChoice && preMergeChoice !== "(keep current)") {
@@ -588,7 +588,7 @@ export async function configureMode(ctx: ExtensionCommandContext, prefs: Record<
     if (modeStr.startsWith("solo")) {
       prefs.mode = "solo";
       ctx.ui.notify(
-        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=false, merge_strategy=squash, isolation=worktree, unique_milestone_ids=false",
+        "Mode: solo — defaults: auto_push=true, push_branches=false, pre_merge_check=auto, merge_strategy=squash, isolation=worktree, unique_milestone_ids=false",
         "info",
       );
     } else if (modeStr.startsWith("team")) {
@@ -771,7 +771,7 @@ export async function ensurePreferencesFile(
   scope: "global" | "project",
 ): Promise<void> {
   if (!existsSync(path)) {
-    const template = await loadFile(join(dirname(fileURLToPath(import.meta.url)), "templates", "preferences.md"));
+    const template = await loadFile(join(dirname(fileURLToPath(import.meta.url)), "templates", "PREFERENCES.md"));
     if (!template) {
       ctx.ui.notify("Could not load GSD preferences template.", "error");
       return;

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

@@ -359,8 +359,8 @@ function detectV2Gsd(basePath: string): V2Detection | null {
   if (!existsSync(gsdPath)) return null;
 
   const hasPreferences =
-    existsSync(join(gsdPath, "preferences.md")) ||
-    existsSync(join(gsdPath, "PREFERENCES.md"));
+    existsSync(join(gsdPath, "PREFERENCES.md")) ||
+    existsSync(join(gsdPath, "preferences.md"));
 
   const hasContext = existsSync(join(gsdPath, "CONTEXT.md"));
 
@@ -714,8 +714,8 @@ function detectVerificationCommands(
  */
 export function hasGlobalSetup(): boolean {
   return (
-    existsSync(join(gsdHome, "preferences.md")) ||
-    existsSync(join(gsdHome, "PREFERENCES.md"))
+    existsSync(join(gsdHome, "PREFERENCES.md")) ||
+    existsSync(join(gsdHome, "preferences.md"))
   );
 }
 
@@ -728,8 +728,8 @@ export function isFirstEverLaunch(): boolean {
 
   // If we have preferences, not first launch
   if (
-    existsSync(join(gsdHome, "preferences.md")) ||
-    existsSync(join(gsdHome, "PREFERENCES.md"))
+    existsSync(join(gsdHome, "PREFERENCES.md")) ||
+    existsSync(join(gsdHome, "preferences.md"))
   ) {
     return false;
   }

package/src/resources/extensions/gsd/docs/preferences-reference.md

@@ -1,6 +1,6 @@
 # GSD Preferences Reference
 
-Full documentation for `~/.gsd/preferences.md` (global) and `.gsd/preferences.md` (project).
+Full documentation for `~/.gsd/PREFERENCES.md` (global) and `.gsd/PREFERENCES.md` (project).
 
 ---
 
@@ -51,8 +51,8 @@ skill_rules: []
 
 Preferences are loaded from two locations and merged:
 
-1. **Global:** `~/.gsd/preferences.md` — applies to all projects
-2. **Project:** `.gsd/preferences.md` — applies to the current project only
+1. **Global:** `~/.gsd/PREFERENCES.md` — applies to all projects
+2. **Project:** `.gsd/PREFERENCES.md` — applies to the current project only
 
 **Merge behavior** (see `mergePreferences()` in `preferences.ts`):
 
@@ -126,8 +126,8 @@ Setting `prefer_skills: []` does **not** disable skill discovery — it just mea
   - `auto_push`: boolean — automatically push commits to the remote after committing. Default: `false`.
   - `push_branches`: boolean — push the milestone branch to the remote after commits. Default: `false`.
   - `remote`: string — git remote name to push to. Default: `"origin"`.
-  - `snapshots`: boolean — create snapshot commits (WIP saves) during long-running tasks. Default: `false`.
-  - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `false`.
+  - `snapshots`: boolean — create snapshot commits (WIP saves) during long-running tasks. Default: `true`.
+  - `pre_merge_check`: boolean or `"auto"` — run pre-merge checks before merging a worktree back to the integration branch. `true` always runs, `false` never runs, `"auto"` runs when CI is detected. Default: `"auto"`.
   - `commit_type`: string — override the conventional commit type prefix. Must be one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`, `build`, `style`. Default: inferred from diff content.
   - `main_branch`: string — the primary branch name for new git repos (e.g., `"main"`, `"master"`, `"trunk"`). Also used by `getMainBranch()` as the preferred branch when auto-detection is ambiguous. Default: `"main"`.
   - `merge_strategy`: `"squash"` or `"merge"` — controls how worktree branches are merged back. `"squash"` combines all commits into one; `"merge"` preserves individual commits. Default: `"squash"`.

package/src/resources/extensions/gsd/error-classifier.ts

@@ -0,0 +1,139 @@
+/**
+ * Unified error classifier for provider/network/server errors.
+ *
+ * Consolidates patterns from:
+ *  - isTransientNetworkError()  in preferences-models.ts
+ *  - classifyProviderError()    in provider-error-pause.ts
+ *
+ * Single entry point: classifyError(errorMsg, retryAfterMs?)
+ *
+ * @see https://github.com/gsd-build/gsd/issues/2577
+ */
+
+// ── ErrorClass discriminated union ──────────────────────────────────────────
+
+export type ErrorClass =
+  | { kind: "network";      retryAfterMs: number }
+  | { kind: "rate-limit";   retryAfterMs: number }
+  | { kind: "server";       retryAfterMs: number }
+  | { kind: "stream";       retryAfterMs: number }
+  | { kind: "connection";   retryAfterMs: number }
+  | { kind: "model-error" }
+  | { kind: "permanent" }
+  | { kind: "unknown" };
+
+// ── RetryState ──────────────────────────────────────────────────────────────
+
+export interface RetryState {
+  networkRetryCount: number;
+  consecutiveTransientCount: number;
+  currentRetryModelId: string | undefined;
+}
+
+export function createRetryState(): RetryState {
+  return { networkRetryCount: 0, consecutiveTransientCount: 0, currentRetryModelId: undefined };
+}
+
+export function resetRetryState(state: RetryState): void {
+  state.networkRetryCount = 0;
+  state.consecutiveTransientCount = 0;
+  state.currentRetryModelId = undefined;
+}
+
+// ── Classification ──────────────────────────────────────────────────────────
+
+const PERMANENT_RE = /auth|unauthorized|forbidden|invalid.*key|invalid.*api|billing|quota exceeded|account/i;
+const RATE_LIMIT_RE = /rate.?limit|too many requests|429/i;
+const NETWORK_RE = /network|ECONNRESET|ETIMEDOUT|ECONNREFUSED|socket hang up|fetch failed|connection.*reset|dns/i;
+const SERVER_RE = /internal server error|500|502|503|overloaded|server_error|api_error|service.?unavailable/i;
+// ECONNRESET/ECONNREFUSED are in NETWORK_RE (same-model retry first).
+const CONNECTION_RE = /terminated|connection.?refused|other side closed|EPIPE|network.?(?:is\s+)?unavailable|stream_exhausted(?:_without_result)?/i;
+const STREAM_RE = /Unexpected end of JSON|Unexpected token.*JSON|Expected double-quoted property name|SyntaxError.*JSON/i;
+const RESET_DELAY_RE = /reset in (\d+)s/i;
+
+/**
+ * Classify an error message into one of the ErrorClass kinds.
+ *
+ * Classification order:
+ *  1. Permanent (auth/billing/quota) — unless also rate-limited
+ *  2. Rate limit (429, rate.?limit, too many requests)
+ *  3. Network (ECONNRESET, ETIMEDOUT, socket hang up, fetch failed, dns)
+ *  4. Server (500/502/503, overloaded, server_error)
+ *  5. Connection (terminated, ECONNREFUSED, EPIPE, other side closed)
+ *  6. Stream truncation (malformed JSON from mid-stream cut)
+ *  7. Unknown
+ */
+export function classifyError(errorMsg: string, retryAfterMs?: number): ErrorClass {
+  const isPermanent = PERMANENT_RE.test(errorMsg);
+  const isRateLimit = RATE_LIMIT_RE.test(errorMsg);
+
+  // 1. Permanent — but rate limit takes precedence
+  if (isPermanent && !isRateLimit) {
+    return { kind: "permanent" };
+  }
+
+  // 2. Rate limit
+  if (isRateLimit) {
+    if (retryAfterMs != null && retryAfterMs > 0) {
+      return { kind: "rate-limit", retryAfterMs };
+    }
+    const resetMatch = errorMsg.match(RESET_DELAY_RE);
+    const delayMs = resetMatch ? Number(resetMatch[1]) * 1000 : 60_000;
+    return { kind: "rate-limit", retryAfterMs: delayMs };
+  }
+
+  // 3. Network errors — same-model retry candidate
+  if (NETWORK_RE.test(errorMsg)) {
+    // Exclude if also matches permanent signals (already handled above for
+    // rate-limit, but double-check for non-rate-limit permanent overlap like
+    // "billing" appearing alongside "network").
+    return { kind: "network", retryAfterMs: retryAfterMs ?? 3_000 };
+  }
+
+  // 4. Server errors — try fallback model
+  if (SERVER_RE.test(errorMsg)) {
+    return { kind: "server", retryAfterMs: retryAfterMs ?? 30_000 };
+  }
+
+  // 5. Connection errors — try fallback model
+  if (CONNECTION_RE.test(errorMsg)) {
+    return { kind: "connection", retryAfterMs: retryAfterMs ?? 15_000 };
+  }
+
+  // 6. Stream truncation — downstream symptom of connection drop
+  if (STREAM_RE.test(errorMsg)) {
+    return { kind: "stream", retryAfterMs: retryAfterMs ?? 15_000 };
+  }
+
+  // 7. Unknown
+  return { kind: "unknown" };
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+/** Returns true for all transient (auto-resumable) error kinds. */
+export function isTransient(cls: ErrorClass): boolean {
+  switch (cls.kind) {
+    case "network":
+    case "rate-limit":
+    case "server":
+    case "stream":
+    case "connection":
+      return true;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Backward-compatible thin wrapper.
+ *
+ * Returns true when the error is a transient *network* error specifically
+ * (worth retrying the same model). Permanent signals (auth, billing, quota)
+ * cause this to return false even if a network keyword is present.
+ */
+export function isTransientNetworkError(errorMsg: string): boolean {
+  if (!errorMsg) return false;
+  const cls = classifyError(errorMsg);
+  return cls.kind === "network";
+}

package/src/resources/extensions/gsd/git-service.ts

@@ -605,11 +605,12 @@ export class GitServiceImpl {
 
   /**
    * Create a snapshot ref for the given label (typically a slice branch name).
-   * Gated on prefs.snapshots === true. Ref path: refs/gsd/snapshots/<label>/<timestamp>
+   * Enabled by default; opt out with prefs.snapshots === false.
+   * Ref path: refs/gsd/snapshots/<label>/<timestamp>
    * The ref points at HEAD, capturing the current commit before destructive operations.
    */
   createSnapshot(label: string): void {
-    if (this.prefs.snapshots !== true) return;
+    if (this.prefs.snapshots === false) return;
 
     const now = new Date();
     const ts = now.getFullYear().toString()
@@ -631,7 +632,7 @@ export class GitServiceImpl {
    * Stub: to be implemented in T03.
    */
   runPreMergeCheck(): PreMergeCheckResult {
-    if (this.prefs.pre_merge_check === false || this.prefs.pre_merge_check === undefined) {
+    if (this.prefs.pre_merge_check === false) {
       return { passed: true, skipped: true };
     }
 

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

@@ -1,8 +1,8 @@
 /**
- * GSD bootstrappers for .gitignore and preferences.md
+ * GSD bootstrappers for .gitignore and PREFERENCES.md
  *
  * Ensures baseline .gitignore exists with universally-correct patterns.
- * Creates an empty preferences.md template if it doesn't exist.
+ * Creates an empty PREFERENCES.md template if it doesn't exist.
  * Both idempotent — non-destructive if already present.
  */
 
@@ -216,16 +216,16 @@ export function untrackRuntimeFiles(basePath: string): void {
 }
 
 /**
- * Ensure basePath/.gsd/preferences.md exists as an empty template.
+ * Ensure basePath/.gsd/PREFERENCES.md exists as an empty template.
  * Creates the file with frontmatter only if it doesn't exist.
  * Returns true if created, false if already exists.
  *
- * Checks both lowercase (canonical) and uppercase (legacy) to avoid
- * creating a duplicate when an uppercase file already exists.
+ * Checks both uppercase (canonical) and lowercase (legacy) to avoid
+ * creating a duplicate when a lowercase file already exists.
  */
 export function ensurePreferences(basePath: string): boolean {
-  const preferencesPath = join(gsdRoot(basePath), "preferences.md");
-  const legacyPath = join(gsdRoot(basePath), "PREFERENCES.md");
+  const preferencesPath = join(gsdRoot(basePath), "PREFERENCES.md");
+  const legacyPath = join(gsdRoot(basePath), "preferences.md");
 
   if (existsSync(preferencesPath) || existsSync(legacyPath)) {
     return false;