gsd-pi 2.78.0 → 2.78.1-dev.42ef05fbe

package/src/resources/extensions/gsd/memory-store.ts

@@ -7,6 +7,7 @@ import {
   isDbAvailable,
   _getAdapter,
   transaction,
+  isInTransaction,
   insertMemoryRow,
   rewriteMemoryId,
   updateMemoryContentRow,
@@ -19,6 +20,7 @@ import {
   deleteMemoryRelationsFor,
 } from './gsd-db.js';
 import { createMemoryRelation, isValidRelation } from './memory-relations.js';
+import { logWarning } from './workflow-logger.js';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -487,7 +489,13 @@ export function nextMemoryId(): string {
  * Insert a new memory with a race-safe auto-assigned ID.
  * Uses AUTOINCREMENT seq to derive the ID after insert, avoiding
  * the read-then-write race in concurrent scenarios (e.g. worktrees).
- * Returns the assigned ID, or null on failure.
+ * Returns the assigned ID, or null when the DB is unavailable.
+ *
+ * Throws on genuine SQL errors (corruption, missing tables, constraint
+ * violations) so callers can surface the underlying message instead of
+ * collapsing the failure to a generic "create_failed". See issue #4967 —
+ * the previous bare-catch swallowed "database disk image is malformed"
+ * errors, leaving the memory subsystem broken without any signal.
  */
 export function createMemory(fields: {
   category: string;
@@ -504,34 +512,70 @@ export function createMemory(fields: {
   if (!adapter) return null;
 
   try {
-    const now = new Date().toISOString();
-    // Insert with a temporary placeholder ID — seq is auto-assigned
-    const placeholder = `_TMP_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-    insertMemoryRow({
-      id: placeholder,
-      category: fields.category,
-      content: fields.content,
-      confidence: fields.confidence ?? 0.8,
-      sourceUnitType: fields.source_unit_type ?? null,
-      sourceUnitId: fields.source_unit_id ?? null,
-      createdAt: now,
-      updatedAt: now,
-      scope: fields.scope ?? 'project',
-      tags: fields.tags ?? [],
-      structuredFields: fields.structuredFields ?? null,
-    });
-    // Derive the real ID from the assigned seq (SELECT is still fine via adapter)
-    const row = adapter.prepare('SELECT seq FROM memories WHERE id = :id').get({ ':id': placeholder });
-    if (!row) return placeholder; // fallback — should not happen
-    const seq = row['seq'] as number;
-    const realId = `MEM${String(seq).padStart(3, '0')}`;
-    rewriteMemoryId(placeholder, realId);
-    return realId;
-  } catch {
-    return null;
+    return transaction(() => doCreateMemory(adapter, fields));
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    // Targeted recovery: a malformed memory store can sometimes be rebuilt
+    // by VACUUM. Skip when inside a transaction — SQLite refuses VACUUM
+    // there and a secondary throw would mask the real fault.
+    if (message.toLowerCase().includes('malformed') && !isInTransaction()) {
+      try {
+        adapter.prepare('VACUUM').run();
+        const recoveryMessage = 'recovered malformed memory store via VACUUM';
+        process.stderr.write(`memory-store: ${recoveryMessage}\n`);
+        logWarning('memory-store', recoveryMessage);
+        return transaction(() => doCreateMemory(adapter, fields));
+      } catch (retryErr) {
+        const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr);
+        logWarning('memory-store', `VACUUM recovery for memory store failed: ${retryMsg}`);
+        // Surface the *original* malformed error — it's the actionable signal.
+        throw err;
+      }
+    }
+
+    throw err;
   }
 }
 
+function doCreateMemory(
+  adapter: NonNullable<ReturnType<typeof _getAdapter>>,
+  fields: {
+    category: string;
+    content: string;
+    confidence?: number;
+    source_unit_type?: string;
+    source_unit_id?: string;
+    scope?: string;
+    tags?: string[];
+    structuredFields?: Record<string, unknown> | null;
+  },
+): string {
+  const now = new Date().toISOString();
+  // Insert with a temporary placeholder ID — seq is auto-assigned
+  const placeholder = `_TMP_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+  insertMemoryRow({
+    id: placeholder,
+    category: fields.category,
+    content: fields.content,
+    confidence: fields.confidence ?? 0.8,
+    sourceUnitType: fields.source_unit_type ?? null,
+    sourceUnitId: fields.source_unit_id ?? null,
+    createdAt: now,
+    updatedAt: now,
+    scope: fields.scope ?? 'project',
+    tags: fields.tags ?? [],
+    structuredFields: fields.structuredFields ?? null,
+  });
+  // Derive the real ID from the assigned seq (SELECT is still fine via adapter)
+  const row = adapter.prepare('SELECT seq FROM memories WHERE id = :id').get({ ':id': placeholder });
+  if (!row) return placeholder; // fallback — should not happen
+  const seq = row['seq'] as number;
+  const realId = `MEM${String(seq).padStart(3, '0')}`;
+  rewriteMemoryId(placeholder, realId);
+  return realId;
+}
+
 /**
  * Update a memory's content and optionally its confidence.
  */
@@ -728,8 +772,17 @@ export function applyMemoryActions(
       }
       enforceMemoryCap();
     });
-  } catch {
-    // non-fatal — transaction will have rolled back
+  } catch (err) {
+    // Non-fatal — the transaction has rolled back. We log a warning so a
+    // degraded memory subsystem (e.g. malformed store, missing tables) is
+    // visible to forensics instead of silently dropping every CREATE — see
+    // issue #4967, where this swallow combined with createMemory's bare
+    // catch hid SQLite corruption from the auto-mode flow entirely.
+    const message = err instanceof Error ? err.message : String(err);
+    logWarning(
+      'memory-store',
+      `applyMemoryActions failed (memory subsystem degraded): ${message}`,
+    );
   }
 }
 

package/src/resources/extensions/gsd/migrate/command.ts

@@ -24,6 +24,7 @@ import {
 } from "./index.js";
 
 import type { MigrationPreview } from "./writer.js";
+import { homedir } from "node:os";
 
 /** Format preview stats for embedding in the review prompt. */
 function formatPreviewStats(preview: MigrationPreview): string {
@@ -85,9 +86,9 @@ export async function handleMigrate(
   // Default to cwd when no args given; expand ~ to HOME
   let rawPath = args.trim() || ".";
   if (rawPath.startsWith("~/")) {
-    rawPath = join(process.env.HOME ?? "~", rawPath.slice(2));
+    rawPath = join(homedir(), rawPath.slice(2));
   } else if (rawPath === "~") {
-    rawPath = process.env.HOME ?? "~";
+    rawPath = homedir();
   }
 
   let sourcePath = resolve(process.cwd(), rawPath);

package/src/resources/extensions/gsd/milestone-id-reservation.ts

@@ -0,0 +1,47 @@
+import { isDbAvailable, getAllMilestones } from "./gsd-db.js";
+import {
+  getReservedMilestoneIds,
+  milestoneIdSort,
+  nextMilestoneId,
+  reserveMilestoneId,
+} from "./milestone-ids.js";
+import { isReusableGhostMilestone } from "./state.js";
+
+function getDatabaseMilestoneIds(): string[] {
+  if (!isDbAvailable()) return [];
+  return getAllMilestones().map((milestone) => milestone.id);
+}
+
+/**
+ * Generate the next milestone ID, accounting for DB rows and in-process
+ * reservations, and reserve it.
+ */
+export function nextMilestoneIdReserved(
+  existingIds: string[],
+  uniqueEnabled: boolean,
+  basePath?: string,
+): string {
+  const reservedIds = getReservedMilestoneIds();
+  const allIds = [
+    ...new Set([
+      ...existingIds,
+      ...reservedIds,
+      ...getDatabaseMilestoneIds(),
+    ]),
+  ];
+
+  if (basePath) {
+    const sorted = [...allIds].sort(milestoneIdSort);
+    for (const candidate of sorted) {
+      if (reservedIds.has(candidate)) continue;
+      if (isReusableGhostMilestone(basePath, candidate)) {
+        reserveMilestoneId(candidate);
+        return candidate;
+      }
+    }
+  }
+
+  const id = nextMilestoneId(allIds, uniqueEnabled);
+  reserveMilestoneId(id);
+  return id;
+}

package/src/resources/extensions/gsd/milestone-scope-classifier.ts

@@ -164,13 +164,19 @@ function mentionsWithoutNegation(text: string, term: string): boolean {
     const start = m.index ?? 0;
     const windowStart = Math.max(0, start - 30);
     const window = lower.slice(windowStart, start);
-    // Negator anywhere in the 30-char lookback window counts as negation —
-    // covers "no backend", "without a server", "not using api", "zero
-    // dependencies on an api". If a sentence break intervenes between the
-    // negator and the term, treat as a different clause (positive mention).
-    const hasNegator = /(^|[^a-z0-9])(no|without|not|zero|skip(s|ping)?|drops?)\b/i.test(window);
-    const hasSentenceBreak = /[.;!?]/.test(window);
-    if (hasNegator && !hasSentenceBreak) continue;
+    // Negator anywhere in the same clause counts as negation — covers "no
+    // backend", "without a server", "not using api", "zero dependencies on
+    // an api". Only inspect text after the most recent sentence break so
+    // "No backend. Add API" still treats API as a positive mention.
+    const lastBreak = Math.max(
+      window.lastIndexOf("."),
+      window.lastIndexOf(";"),
+      window.lastIndexOf("!"),
+      window.lastIndexOf("?"),
+    );
+    const clauseWindow = window.slice(lastBreak + 1);
+    const hasNegator = /(^|[^a-z0-9])(no|without|not|zero|skip(s|ping)?|drops?)\b/i.test(clauseWindow);
+    if (hasNegator) continue;
     return true;
   }
   return false;
@@ -279,7 +285,8 @@ export function classifyMilestoneScope(input: MilestoneScopeInput): ScopeClassif
     input.verificationUat ?? "",
   ].join("\n");
 
-  const overrideHits = containsAnyKeyword(haystack, OVERRIDE_KEYWORDS);
+  const overrideHits = containsAnyKeyword(haystack, OVERRIDE_KEYWORDS)
+    .filter((kw) => mentionsWithoutNegation(haystack, kw));
   const complexHits = containsAnyKeyword(haystack, COMPLEX_KEYWORDS);
   const trivialHits = containsAnyKeyword(haystack, TRIVIAL_KEYWORDS);
   const fileCountHint = extractFileCountHint(haystack);

package/src/resources/extensions/gsd/model-router.ts

@@ -320,11 +320,8 @@ export function getEligibleModels(
     // Exact match
     if (availableModelIds.includes(explicitModel)) return [explicitModel];
     // Provider-prefix-stripped match
-    const match = availableModelIds.find(id => {
-      const bareAvail = id.includes("/") ? id.split("/").pop()! : id;
-      const bareExplicit = explicitModel.includes("/") ? explicitModel.split("/").pop()! : explicitModel;
-      return bareAvail === bareExplicit;
-    });
+    const bareExplicit = bareModelId(explicitModel);
+    const match = availableModelIds.find(id => bareModelId(id) === bareExplicit);
     if (match) return [match];
   }
 
@@ -430,12 +427,38 @@ export function resolveModelForComplexity(
 
   // Downgrade-only: if requested tier >= configured tier, no change
   if (tierOrdinal(requestedTier) >= tierOrdinal(configuredTier)) {
+    // If the configured primary is directly available, use it
+    if (isModelAvailable(configuredPrimary, availableModelIds)) {
+      return {
+        modelId: configuredPrimary,
+        fallbacks: phaseConfig.fallbacks,
+        tier: requestedTier,
+        wasDowngraded: false,
+        reason: `tier ${requestedTier} >= configured ${configuredTier}`,
+        selectionMethod: "tier-only",
+      };
+    }
+
+    // Configured primary is unavailable (e.g. Anthropic model configured but
+    // running on a non-Anthropic provider). Find the best available model at
+    // the same capability tier so routing still works cross-provider.
+    const crossProviderEquivalent = findModelForTier(
+      configuredTier,
+      routingConfig,
+      availableModelIds,
+      routingConfig.cross_provider !== false,
+    );
+
     return {
-      modelId: configuredPrimary,
-      fallbacks: phaseConfig.fallbacks,
+      modelId: crossProviderEquivalent ?? configuredPrimary,
+      fallbacks: crossProviderEquivalent
+        ? [...phaseConfig.fallbacks.filter(f => f !== crossProviderEquivalent), configuredPrimary]
+        : phaseConfig.fallbacks,
       tier: requestedTier,
       wasDowngraded: false,
-      reason: `tier ${requestedTier} >= configured ${configuredTier}`,
+      reason: crossProviderEquivalent
+        ? `cross-provider ${configuredTier}-tier equivalent`
+        : `tier ${requestedTier} >= configured ${configuredTier}`,
       selectionMethod: "tier-only",
     };
   }
@@ -519,8 +542,131 @@ export function defaultRoutingConfig(): DynamicRoutingConfig {
   };
 }
 
+// ─── Tier-Based Model Resolution (for profile defaults) ─────────────────────
+
+/**
+ * Fallback-only canonical model IDs per tier. Returned when the
+ * available-model list is empty (e.g., preferences are loaded before the
+ * model registry is populated at bootstrap), or when a non-empty registry has
+ * no model at the requested tier.
+ *
+ * Precedence (resolveModelForTier):
+ *   1. configured `tier_models[tier]` (via getEligibleModels) — exact/bare match
+ *   2. cheapest available model whose tier matches `tier`
+ *   3. CANONICAL_TIER_MODELS[tier] as last-resort fallback
+ */
+const CANONICAL_TIER_MODELS: Record<ComplexityTier, string> = {
+  light: "claude-haiku-4-5",
+  standard: "claude-sonnet-4-6",
+  heavy: "claude-opus-4-6",
+};
+
+export function canonicalModelForTier(tier: ComplexityTier): string {
+  return CANONICAL_TIER_MODELS[tier];
+}
+
+/**
+ * Single source of truth for tier-based model selection.
+ * Returns the cheapest available model whose capability tier matches `tier`,
+ * honoring `routingConfig.tier_models[tier]` when set. Returns undefined when
+ * no available model matches the tier.
+ *
+ * `crossProvider`: when false, restricts the search to models that share the
+ * canonical (Anthropic) provider for the tier. When true, any provider is
+ * eligible.
+ */
+function findModelForTier(
+  tier: ComplexityTier,
+  routingConfig: DynamicRoutingConfig,
+  availableModelIds: string[],
+  crossProvider: boolean,
+): string | undefined {
+  const eligible = getEligibleModels(tier, availableModelIds, routingConfig);
+  if (eligible.length === 0) return undefined;
+
+  if (crossProvider) {
+    return eligible[0];
+  }
+
+  // Same-provider only: keep models whose bare ID matches a canonical
+  // Anthropic ID at this tier (i.e., a claude-* model in the tier map).
+  const sameProvider = eligible.filter(id => {
+    const bare = bareModelId(id);
+    return MODEL_CAPABILITY_TIER[bare] === tier && bare.startsWith("claude-");
+  });
+  return sameProvider[0];
+}
+
+/**
+ * Resolve a concrete model ID for a given capability tier using the
+ * available model list. Provider-agnostic: picks the best available
+ * model at the requested tier.
+ *
+ * Precedence:
+ *   1. configured `tier_models[tier]`, if provided and available
+ *   2. tier-matching model from any provider in `availableModelIds`
+ *   3. canonical Anthropic ID as a fallback only when nothing else matches
+ *      (or `availableModelIds` is empty, e.g., during early bootstrap)
+ *
+ * @param tier              The capability tier to resolve
+ * @param availableModelIds List of available model IDs (REQUIRED for
+ *                          provider-agnostic resolution; pass [] only when
+ *                          the model registry is genuinely unavailable)
+ * @param routingConfig     Optional routing config, or legacy crossProvider boolean
+ * @param crossProvider     Whether to consider models from other providers
+ */
+export function resolveModelForTier(
+  tier: ComplexityTier,
+  availableModelIds: string[],
+  crossProvider?: boolean,
+): string;
+export function resolveModelForTier(
+  tier: ComplexityTier,
+  availableModelIds: string[],
+  routingConfig?: DynamicRoutingConfig,
+  crossProvider?: boolean,
+): string;
+export function resolveModelForTier(
+  tier: ComplexityTier,
+  availableModelIds: string[],
+  routingConfigOrCrossProvider: DynamicRoutingConfig | boolean = defaultRoutingConfig(),
+  crossProvider?: boolean,
+): string {
+  const routingConfig = typeof routingConfigOrCrossProvider === "boolean"
+    ? defaultRoutingConfig()
+    : { ...defaultRoutingConfig(), ...routingConfigOrCrossProvider };
+  const allowCrossProvider = typeof routingConfigOrCrossProvider === "boolean"
+    ? routingConfigOrCrossProvider
+    : crossProvider ?? routingConfig.cross_provider !== false;
+
+  // No available models known — return canonical fallback
+  if (availableModelIds.length === 0) {
+    return canonicalModelForTier(tier);
+  }
+
+  // Cross-provider tier search
+  const resolved = findModelForTier(tier, routingConfig, availableModelIds, allowCrossProvider);
+  return resolved
+    ? normalizeResolvedTierModelId(resolved, tier, routingConfig)
+    : canonicalModelForTier(tier);
+}
+
 // ─── Internal ────────────────────────────────────────────────────────────────
 
+/**
+ * Check whether a model ID is present in the available models list.
+ * Handles bare IDs ("claude-opus-4-6") and provider-prefixed IDs ("anthropic/claude-opus-4-6").
+ */
+function isModelAvailable(modelId: string, availableModelIds: string[]): boolean {
+  if (availableModelIds.includes(modelId)) return true;
+  // Strip provider prefix for comparison. Treat trailing-slash IDs ("provider/")
+  // as no-bare-ID rather than empty-string match (which would erroneously match
+  // any other "provider/" ID).
+  const bare = bareModelId(modelId);
+  if (!bare) return false;
+  return availableModelIds.some(id => bareModelId(id) === bare);
+}
+
 function getModelTier(modelId: string): ComplexityTier {
   // Strip provider prefix if present
   const bareId = bareModelId(modelId);
@@ -563,8 +709,25 @@ function getModelCost(modelId: string): number {
   return 999;
 }
 
+function normalizeResolvedTierModelId(
+  modelId: string,
+  tier: ComplexityTier,
+  routingConfig: DynamicRoutingConfig,
+): string {
+  const explicitModel = routingConfig.tier_models?.[tier];
+  if (explicitModel?.includes("/")) {
+    return modelId;
+  }
+
+  const bareId = bareModelId(modelId);
+  return MODEL_CAPABILITY_TIER[bareId] ? bareId : modelId;
+}
+
 function bareModelId(modelId: string): string {
-  return modelId.includes("/") ? modelId.split("/").pop()! : modelId;
+  if (!modelId.includes("/")) return modelId;
+  // .pop() never returns undefined on a non-empty string but ?? guards future
+  // refactors and avoids the misleading non-null assertion.
+  return modelId.split("/").pop() ?? modelId;
 }
 
 // ─── Provider-specific Tool Limits ─────────────────────────────────────────

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

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { getErrorMessage } from "./error-utils.js";
+import { isInfrastructureError } from "./auto/infra-errors.js";
 
 // Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
 // caller explicitly opts into the native helper.
@@ -330,6 +331,20 @@ export function nativeIsRepo(basePath: string): boolean {
   }
 }
 
+/** Return true only when the repository has a reachable committed HEAD. */
+export function nativeHasCommittedHead(basePath: string): boolean {
+  try {
+    execFileSync("git", ["rev-parse", "--verify", "HEAD"], {
+      cwd: basePath,
+      stdio: ["ignore", "ignore", "ignore"],
+      env: GIT_NO_PROMPT_ENV,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Check if there are staged changes (index differs from HEAD).
  * Native: libgit2 tree-to-index diff.
@@ -846,6 +861,10 @@ export function nativeAddAllWithExclusions(basePath: string, exclusions: readonl
     });
   } catch (err: unknown) {
     const stderr = (err as { stderr?: string })?.stderr ?? "";
+    const infraCode = isInfrastructureError(err) ?? isInfrastructureError(stderr);
+    if (infraCode) {
+      throw err;
+    }
     // git exits 1 when pathspec exclusions reference paths already covered
     // by .gitignore. The staging itself succeeds — only suppress that case.
     if (stderr.includes("ignored by one of your .gitignore files")) {
@@ -860,7 +879,8 @@ export function nativeAddAllWithExclusions(basePath: string, exclusions: readonl
       fallbackStageWithSymlinkedDotGsd(basePath);
       return;
     }
-    throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}`);
+    const stderrDetail = stderr.trim() ? `; stderr: ${stderr.trim()}` : "";
+    throw new GSDError(GSD_GIT_ERROR, `git add -A with exclusions failed in ${basePath}: ${getErrorMessage(err)}${stderrDetail}`);
   }
 }
 

package/src/resources/extensions/gsd/onboarding-state.ts

@@ -5,9 +5,9 @@
 // "settings.defaultProvider exists" heuristic.
 
 import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs"
-import { homedir } from "node:os"
 import { dirname, join } from "node:path"
 import { logWarning } from "./workflow-logger.js"
+import { gsdHome } from "./gsd-home.js";
 
 /**
  * Bump `FLOW_VERSION` whenever a new required step is added to ONBOARDING_STEPS.
@@ -22,7 +22,7 @@ const RECORD_VERSION = 1
 // outside src/resources and breaks the build.
 const AGENT_DIR =
   process.env.GSD_CODING_AGENT_DIR ||
-  join(process.env.GSD_HOME || join(homedir(), ".gsd"), "agent")
+  join(gsdHome(), "agent")
 const FILE = join(AGENT_DIR, "onboarding.json")
 
 export interface OnboardingRecord {

package/src/resources/extensions/gsd/planning-depth.ts

@@ -0,0 +1,138 @@
+// gsd-2 / Deep planning mode — Helper to set planning_depth in .gsd/PREFERENCES.md.
+//
+// Persists the user's deep-mode opt-in across sessions. Reads the existing
+// preferences file (if any), parses its YAML frontmatter, sets/updates
+// planning_depth, and writes the file back preserving body content and other
+// frontmatter keys.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { getProjectGSDPreferencesPath } from "./preferences.js";
+import { logWarning } from "./workflow-logger.js";
+import {
+  researchDecisionPath,
+  writeDefaultResearchSkipDecision,
+} from "./deep-project-setup-policy.js";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+/**
+ * Set planning_depth in the project's .gsd/PREFERENCES.md.
+ * Creates the file if it does not exist. Preserves existing frontmatter
+ * keys and body content. Intended to be called when the user opts into
+ * (or out of) deep mode via `/gsd new-project --deep` or similar.
+ */
+export function setPlanningDepth(
+  basePath: string,
+  depth: "light" | "deep",
+): void {
+  const path = getProjectGSDPreferencesPath(basePath);
+  const { frontmatter, body } = readProjectPreferencesParts(path);
+
+  frontmatter.planning_depth = depth;
+  if (depth === "deep") {
+    applyDeepWorkflowPreferenceDefaults(frontmatter);
+  }
+
+  writeProjectPreferencesParts(path, frontmatter, body);
+  if (depth === "deep") {
+    ensureResearchDecisionDefault(basePath);
+  }
+}
+
+export function ensureWorkflowPreferencesCaptured(basePath: string): void {
+  const path = getProjectGSDPreferencesPath(basePath);
+  const { frontmatter, body } = readProjectPreferencesParts(path);
+
+  frontmatter.planning_depth = "deep";
+  applyDeepWorkflowPreferenceDefaults(frontmatter);
+
+  writeProjectPreferencesParts(path, frontmatter, body);
+  ensureResearchDecisionDefault(basePath);
+}
+
+function readProjectPreferencesParts(path: string): {
+  frontmatter: Record<string, unknown>;
+  body: string;
+} {
+  let frontmatter: Record<string, unknown> = {};
+  let body = "";
+  if (existsSync(path)) {
+    const content = readFileSync(path, "utf-8");
+    const match = content.match(FRONTMATTER_RE);
+    if (match) {
+      try {
+        const parsed = parseYaml(match[1]);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+          frontmatter = parsed as Record<string, unknown>;
+        }
+        body = match[2];
+      } catch (err) {
+        // Invalid YAML — don't lose user content. Treat the whole file as
+        // a legacy non-frontmatter document and preserve it via the body
+        // path. The depth setter then prepends a fresh frontmatter block.
+        logWarning("guided", `PREFERENCES.md frontmatter has invalid YAML — preserving body and rewriting frontmatter: ${err instanceof Error ? err.message : String(err)}`);
+        body = content;
+      }
+    } else {
+      // No frontmatter delimiters — preserve existing content as body.
+      body = content;
+    }
+  }
+  return { frontmatter, body };
+}
+
+function writeProjectPreferencesParts(
+  path: string,
+  frontmatter: Record<string, unknown>,
+  body: string,
+): void {
+  // yaml.stringify emits a trailing newline. Strip if present so we control framing.
+  const yamlBlock = stringifyYaml(frontmatter).replace(/\n$/, "");
+  const newContent = body
+    ? `---\n${yamlBlock}\n---\n\n${body.replace(/^\n+/, "")}`
+    : `---\n${yamlBlock}\n---\n`;
+
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, newContent, "utf-8");
+}
+
+function applyDeepWorkflowPreferenceDefaults(frontmatter: Record<string, unknown>): void {
+  if (frontmatter.commit_policy === undefined) {
+    frontmatter.commit_policy = "per-task";
+  }
+  if (frontmatter.branch_model === undefined) {
+    frontmatter.branch_model = "single";
+  }
+  if (frontmatter.uat_dispatch === undefined) {
+    frontmatter.uat_dispatch = true;
+  }
+
+  const existingModels = frontmatter.models;
+  const models = existingModels && typeof existingModels === "object" && !Array.isArray(existingModels)
+    ? existingModels as Record<string, unknown>
+    : {};
+  if (models.executor_class === undefined) {
+    models.executor_class = "balanced";
+  }
+  frontmatter.models = models;
+  frontmatter.workflow_prefs_captured = true;
+}
+
+function ensureResearchDecisionDefault(basePath: string): void {
+  const decisionPath = researchDecisionPath(basePath);
+  if (existsSync(decisionPath)) {
+    try {
+      const parsed = JSON.parse(readFileSync(decisionPath, "utf-8")) as Record<string, unknown>;
+      const source = typeof parsed.source === "string" ? parsed.source : undefined;
+      if (parsed.decision === "research" && (source === "research-decision" || source === "user")) {
+        return;
+      }
+      if (parsed.decision === "skip" && source !== "workflow-preferences") return;
+    } catch {
+      // Invalid runtime marker is replaced with the default decision.
+    }
+  }
+  writeDefaultResearchSkipDecision(basePath);
+}