@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.955e4da0

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

@@ -5,11 +5,11 @@
  * dependency satisfaction and file overlap across slice plans.
  */
 
-import { existsSync } from "node:fs";
 import { deriveState } from "./state.js";
-import { resolveGsdPathContract, resolveMilestoneFile, resolveSliceFile } from "./paths.js";
+import { resolveMilestoneFile, resolveSliceFile } from "./paths.js";
 import { findMilestoneIds } from "./guided-flow.js";
-import { isDbAvailable, getMilestoneSlices, getSliceTasks, openDatabase } from "./gsd-db.js";
+import { isDbAvailable, getMilestoneSlices, getSliceTasks } from "./gsd-db.js";
+import { openExistingWorkflowDatabase } from "./db-workspace.js";
 import type { MilestoneRegistryEntry } from "./types.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -98,8 +98,7 @@ export async function analyzeParallelEligibility(
   basePath: string,
 ): Promise<ParallelCandidates> {
   if (!isDbAvailable()) {
-    const { projectDb } = resolveGsdPathContract(basePath);
-    if (existsSync(projectDb)) openDatabase(projectDb);
+    openExistingWorkflowDatabase(basePath);
   }
 
   const milestoneIds = findMilestoneIds(basePath);

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

@@ -9,6 +9,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { spawnSync } from "node:child_process";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import { getAutoWorktreePath } from "./auto-worktree.js";
 import { buildWorktreeLifecycleDeps } from "./auto.js";
 import {
@@ -42,7 +43,7 @@ export type MergeOrder = "sequential" | "by-completion";
  * Returns true when milestones.status = 'complete' in project gsd.db.
  */
 export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): boolean {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return false;
 
@@ -65,15 +66,17 @@ export function isMilestoneCompleteInProjectDb(basePath: string, mid: string): b
  */
 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") && isMilestoneCompleteInProjectDb(basePath, entry)) {
-        completed.add(entry);
+  for (const worktreeDir of worktreesDirs(basePath)) {
+    if (!existsSync(worktreeDir)) continue;
+    try {
+      for (const entry of readdirSync(worktreeDir)) {
+        if (entry.startsWith("M") && isMilestoneCompleteInProjectDb(basePath, entry)) {
+          completed.add(entry);
+        }
       }
+    } catch (e) {
+      logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`);
     }
-  } catch (e) {
-    logWarning("parallel", `readdirSync for completed set failed: ${(e as Error).message}`);
   }
   return completed;
 }
@@ -120,7 +123,7 @@ export function determineMergeOrder(
         title: mid,
         pid: 0,
         process: null,
-        worktreePath: basePath ? join(basePath, ".gsd", "worktrees", mid) : "",
+        worktreePath: basePath ? worktreePathFor(basePath, mid) : "",
         startedAt: 0,
         state: "stopped",
         cost: 0,

package/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -11,6 +11,7 @@ import { matchesKey, Key } from "@gsd/pi-tui";
 import { formatDuration } from "../shared/mod.js";
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import { resolveGsdPathContract } from "./paths.js";
+import { worktreePathFor, worktreesDirs } from "./worktree-placement.js";
 import {
   renderBar,
   renderDialogFrame,
@@ -101,7 +102,6 @@ function tailRead(filePath: string, maxBytes: number): string {
 
 function discoverWorkers(basePath: string): string[] {
   const parallelDir = join(basePath, ".gsd", "parallel");
-  const worktreeDir = join(basePath, ".gsd", "worktrees");
   const mids = new Set<string>();
 
   if (existsSync(parallelDir)) {
@@ -114,7 +114,8 @@ function discoverWorkers(basePath: string): string[] {
     } catch { /* skip */ }
   }
 
-  if (existsSync(worktreeDir)) {
+  for (const worktreeDir of worktreesDirs(basePath)) {
+    if (!existsSync(worktreeDir)) continue;
     try {
       for (const d of readdirSync(worktreeDir)) {
         if (d.startsWith("M") && existsSync(join(worktreeDir, d, ".gsd", "auto.lock"))) {
@@ -128,7 +129,7 @@ function discoverWorkers(basePath: string): string[] {
 }
 
 function querySliceProgress(basePath: string, mid: string): SliceProgress[] {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
 
@@ -169,7 +170,7 @@ function extractCostFromNdjson(basePath: string, mid: string): number {
 }
 
 function queryRecentCompletions(basePath: string, mid: string): string[] {
-  const workRoot = join(basePath, ".gsd", "worktrees", mid);
+  const workRoot = worktreePathFor(basePath, mid);
   const dbPath = resolveGsdPathContract(workRoot, basePath).projectDb;
   if (!existsSync(dbPath)) return [];
   try {
@@ -193,7 +194,7 @@ function collectWorkerData(basePath: string): WorkerView[] {
 
   for (const mid of mids) {
     const status = readJsonSafe<StatusJson>(join(parallelDir, `${mid}.status.json`));
-    const lock = readJsonSafe<AutoLock>(join(basePath, ".gsd", "worktrees", mid, ".gsd", "auto.lock"));
+    const lock = readJsonSafe<AutoLock>(join(worktreePathFor(basePath, mid), ".gsd", "auto.lock"));
     const slices = querySliceProgress(basePath, mid);
 
     const pid = lock?.pid || status?.pid || 0;

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

@@ -21,9 +21,10 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { gsdRoot } from "./paths.js";
 import { createWorktree, worktreePath } from "./worktree-manager.js";
-import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, runWorktreePostCreateHook, syncGsdStateToWorktree } from "./auto-worktree.js";
+import { autoWorktreeBranch, fastForwardReusedMilestoneBranchIfSafe, runWorktreePostCreateHook, syncGsdStateToWorktreeByScope } from "./auto-worktree.js";
 import { nativeBranchExists } from "./native-git-bridge.js";
 import { readIntegrationBranch } from "./git-service.js";
+import { createWorkspace, scopeMilestone } from "./workspace.js";
 import { resolveParallelConfig } from "./preferences.js";
 import type { GSDPreferences } from "./preferences.js";
 import type { ParallelConfig } from "./types.js";
@@ -561,7 +562,10 @@ export function _createMilestoneWorktree(basePath: string, milestoneId: string):
   // Copy .gsd/ planning artifacts (milestones, CONTEXT, ROADMAP, etc.) from the
   // project root into the worktree. Without this, workers for newly-planned
   // milestones can't find their roadmap and exit immediately (#2184 Bug 4).
-  syncGsdStateToWorktree(basePath, info.path);
+  syncGsdStateToWorktreeByScope(
+    scopeMilestone(createWorkspace(basePath), milestoneId),
+    scopeMilestone(createWorkspace(info.path), milestoneId),
+  );
 
   return info.path;
 }

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

@@ -17,7 +17,7 @@ import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree, type GsdTreeEntry } from "./native-parser-bridge.js";
 import { DIR_CACHE_MAX } from "./constants.js";
 import { gsdHome } from "./gsd-home.js";
-import { isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
+import { findWorktreeSegment, isGsdWorktreePath, resolveExternalStateProjectGsdFromWorktreePath, resolveWorktreeProjectRoot } from "./worktree-root.js";
 
 // ─── Directory Listing Cache ──────────────────────────────────────────────────
 
@@ -458,29 +458,16 @@ function assertNotGlobalGsdHome(basePath: string, result: string): void {
  * 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.
+ * Layout matching is owned by worktree-root's findWorktreeSegment; this
+ * only adds the requirement that a non-empty worktree name follows the
+ * marker (the worktrees container dir itself is not a worktree).
  */
 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;
+  const normalized = p.replaceAll("\\", "/");
+  const segment = findWorktreeSegment(normalized);
+  if (!segment) return false;
+  const name = normalized.slice(segment.afterWorktrees).split("/")[0];
+  return name.length > 0;
 }
 
 function probeGsdRoot(rawBasePath: string): string {

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

@@ -0,0 +1,98 @@
+import type { PreferenceDiagnostic } from "./preferences-types.js";
+import {
+  loadGlobalGSDPreferences,
+  loadProjectGSDPreferences,
+} from "./preferences.js";
+
+interface PreferenceNotificationContext {
+  ui: {
+    notify(message: string, type?: "info" | "warning" | "error" | "success"): void;
+  };
+}
+
+interface PreferenceDiagnosticNotificationOptions {
+  surface?: string;
+}
+
+const notifiedPreferenceDiagnostics = new Set<string>();
+
+export function collectPreferenceDiagnostics(basePath?: string): PreferenceDiagnostic[] {
+  const diagnostics = [
+    ...(loadGlobalGSDPreferences()?.diagnostics ?? []),
+    ...(loadProjectGSDPreferences(basePath)?.diagnostics ?? []),
+  ];
+
+  const seen = new Set<string>();
+  const unique: PreferenceDiagnostic[] = [];
+  for (const diagnostic of diagnostics) {
+    const signature = preferenceDiagnosticSignature(diagnostic);
+    if (seen.has(signature)) continue;
+    seen.add(signature);
+    unique.push(diagnostic);
+  }
+  return unique;
+}
+
+export function formatPreferenceDiagnostic(diagnostic: PreferenceDiagnostic): string {
+  const scope = diagnostic.scope === "global" ? "global" : "project";
+  const level = diagnostic.severity === "error" ? "error" : "warning";
+  const heading = diagnostic.kind === "parse"
+    ? `GSD ${scope} preferences ${level}: ${diagnostic.path} could not be parsed.`
+    : `GSD ${scope} preferences ${level}: ${diagnostic.path} contains invalid settings.`;
+  const detail = formatPreferenceDiagnosticDetail(diagnostic);
+  const impact = diagnostic.ignored
+    ? "Preferences from this file were ignored; auto-mode may be using defaults."
+    : "Invalid settings were ignored or sanitized; auto-mode may be using defaults for them.";
+  return `${heading}\n${detail}\n${impact}\nRun /gsd doctor for details.`;
+}
+
+export function formatPreferenceDiagnosticDetail(diagnostic: PreferenceDiagnostic): string {
+  if (diagnostic.line !== undefined && diagnostic.column !== undefined) {
+    return `YAML error at line ${diagnostic.line}, column ${diagnostic.column}: ${diagnostic.message}`;
+  }
+  return diagnostic.message;
+}
+
+export function notifyPreferenceDiagnostics(
+  ctx: PreferenceNotificationContext,
+  basePath?: string,
+  options?: PreferenceDiagnosticNotificationOptions,
+): number {
+  let notified = 0;
+  for (const diagnostic of collectPreferenceDiagnostics(basePath)) {
+    const signature = preferenceDiagnosticNotificationSignature(diagnostic, options?.surface);
+    if (notifiedPreferenceDiagnostics.has(signature)) continue;
+    notifiedPreferenceDiagnostics.add(signature);
+    ctx.ui.notify(
+      formatPreferenceDiagnostic(diagnostic),
+      diagnostic.severity === "error" ? "error" : "warning",
+    );
+    notified++;
+  }
+  return notified;
+}
+
+export function _resetPreferenceDiagnosticNotificationsForTests(): void {
+  notifiedPreferenceDiagnostics.clear();
+}
+
+function preferenceDiagnosticSignature(diagnostic: PreferenceDiagnostic): string {
+  return [
+    diagnostic.path,
+    diagnostic.scope,
+    diagnostic.severity,
+    diagnostic.kind,
+    diagnostic.message,
+    diagnostic.line ?? "",
+    diagnostic.column ?? "",
+    diagnostic.ignored === true ? "ignored" : "",
+    diagnostic.sanitized === true ? "sanitized" : "",
+  ].join("\u0000");
+}
+
+function preferenceDiagnosticNotificationSignature(
+  diagnostic: PreferenceDiagnostic,
+  surface = "default",
+): string {
+  return `${surface}\u0000${preferenceDiagnosticSignature(diagnostic)}`;
+}

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

@@ -594,8 +594,24 @@ export interface LoadedGSDPreferences {
   path: string;
   scope: "global" | "project";
   preferences: GSDPreferences;
+  /** True when the file exists but its contents were ignored before merging. */
+  ignored?: boolean;
   /** Validation warnings (unknown keys, type mismatches, deprecations). Empty when preferences are clean. */
   warnings?: string[];
+  /** Structured parse/validation diagnostics for user-visible reporting. */
+  diagnostics?: PreferenceDiagnostic[];
+}
+
+export interface PreferenceDiagnostic {
+  path: string;
+  scope: "global" | "project";
+  severity: "error" | "warning";
+  kind: "parse" | "validation";
+  message: string;
+  line?: number;
+  column?: number;
+  ignored?: boolean;
+  sanitized?: boolean;
 }
 
 export interface SkillResolution {

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

@@ -29,6 +29,7 @@ import {
   type WorkflowMode,
   type GSDPreferences,
   type LoadedGSDPreferences,
+  type PreferenceDiagnostic,
   type SkillResolution,
   type SkillDiscoveryMode,
   formatSkillRef,
@@ -59,6 +60,7 @@ export type {
   ClaudeCodeMcpConfig,
   GSDPreferences,
   LoadedGSDPreferences,
+  PreferenceDiagnostic,
   SkillResolution,
   SkillResolutionReport,
 } from "./preferences-types.js";
@@ -173,14 +175,18 @@ export function normalizePreferencesShape(
 // ─── Loading ────────────────────────────────────────────────────────────────
 
 export function loadGlobalGSDPreferences(): LoadedGSDPreferences | null {
-  return loadPreferencesFile(globalPreferencesPath(), "global")
-    ?? loadPreferencesFile(legacyGlobalPreferencesPathLowercase(), "global")
-    ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
+  return loadFirstUsablePreferencesFile([
+    globalPreferencesPath(),
+    legacyGlobalPreferencesPathLowercase(),
+    legacyGlobalPreferencesPath(),
+  ], "global");
 }
 
 export function loadProjectGSDPreferences(basePath?: string): LoadedGSDPreferences | null {
-  return loadPreferencesFile(projectPreferencesPath(basePath), "project")
-    ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
+  return loadFirstUsablePreferencesFile([
+    projectPreferencesPath(basePath),
+    legacyProjectPreferencesPathLowercase(basePath),
+  ], "project");
 }
 
 export function loadEffectiveGSDPreferences(
@@ -189,25 +195,25 @@ export function loadEffectiveGSDPreferences(
 ): LoadedGSDPreferences | null {
   const globalPreferences = loadGlobalGSDPreferences();
   const projectPreferences = loadProjectGSDPreferences(basePath);
-  const projectHasPlanningDepth = projectPreferences?.preferences.planning_depth !== undefined;
+  const effectiveGlobalPreferences = globalPreferences?.ignored ? null : globalPreferences;
+  const effectiveProjectPreferences = projectPreferences?.ignored ? null : projectPreferences;
+  const projectHasPlanningDepth = effectiveProjectPreferences?.preferences.planning_depth !== undefined;
 
-  if (!globalPreferences && !projectPreferences) return null;
+  if (!effectiveGlobalPreferences && !effectiveProjectPreferences) return null;
 
   let result: LoadedGSDPreferences;
-  if (!globalPreferences) {
-    result = projectPreferences!;
-  } else if (!projectPreferences) {
-    result = globalPreferences;
+  if (!effectiveGlobalPreferences) {
+    result = effectiveProjectPreferences!;
+  } else if (!effectiveProjectPreferences) {
+    result = mergePreferenceMetadata(effectiveGlobalPreferences, projectPreferences);
   } else {
-    const mergedWarnings = [
-      ...(globalPreferences.warnings ?? []),
-      ...(projectPreferences.warnings ?? []),
-    ];
+    const metadata = mergePreferenceMetadata(effectiveGlobalPreferences, effectiveProjectPreferences);
     result = {
-      path: projectPreferences.path,
+      path: effectiveProjectPreferences.path,
       scope: "project",
-      preferences: mergePreferences(globalPreferences.preferences, projectPreferences.preferences),
-      ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
+      preferences: mergePreferences(effectiveGlobalPreferences.preferences, effectiveProjectPreferences.preferences),
+      ...(metadata.warnings ? { warnings: metadata.warnings } : {}),
+      ...(metadata.diagnostics ? { diagnostics: metadata.diagnostics } : {}),
     };
   }
 
@@ -240,6 +246,43 @@ export function loadEffectiveGSDPreferences(
   return result;
 }
 
+function mergePreferenceMetadata(
+  primary: LoadedGSDPreferences,
+  secondary: LoadedGSDPreferences | null,
+): LoadedGSDPreferences {
+  const mergedWarnings = [
+    ...(primary.warnings ?? []),
+    ...(secondary?.warnings ?? []),
+  ];
+  const mergedDiagnostics = [
+    ...(primary.diagnostics ?? []),
+    ...(secondary?.diagnostics ?? []),
+  ];
+  return {
+    ...primary,
+    ...(mergedWarnings.length > 0 ? { warnings: mergedWarnings } : {}),
+    ...(mergedDiagnostics.length > 0 ? { diagnostics: mergedDiagnostics } : {}),
+  };
+}
+
+function loadFirstUsablePreferencesFile(
+  paths: string[],
+  scope: "global" | "project",
+): LoadedGSDPreferences | null {
+  let ignoredPreferences: LoadedGSDPreferences | null = null;
+
+  for (const path of paths) {
+    const loaded = loadPreferencesFile(path, scope);
+    if (!loaded) continue;
+    if (!loaded.ignored) return mergePreferenceMetadata(loaded, ignoredPreferences);
+    ignoredPreferences = ignoredPreferences
+      ? mergePreferenceMetadata(ignoredPreferences, loaded)
+      : loaded;
+  }
+
+  return ignoredPreferences;
+}
+
 function stripInheritedPlanningDepth(
   loaded: LoadedGSDPreferences,
   projectHasPlanningDepth: boolean,
@@ -260,17 +303,40 @@ function loadPreferencesFile(path: string, scope: "global" | "project"): LoadedG
   if (!existsSync(path)) return null;
 
   const raw = readFileSync(path, "utf-8");
-  const preferences = parsePreferencesMarkdown(raw);
-  if (!preferences) return null;
+  const parsed = parsePreferencesMarkdownWithDiagnostics(raw);
+  if (!parsed.preferences && parsed.diagnostics.length === 0) return null;
 
+  const ignored = parsed.diagnostics.some((diagnostic) => diagnostic.ignored === true);
+  const preferences = parsed.preferences ?? {};
   const validation = validatePreferences(preferences);
   const allWarnings = [...validation.warnings, ...validation.errors];
+  const diagnostics: PreferenceDiagnostic[] = [
+    ...parsed.diagnostics.map((diagnostic) => ({ ...diagnostic, path, scope })),
+    ...validation.errors.map((message): PreferenceDiagnostic => ({
+      path,
+      scope,
+      severity: "error",
+      kind: "validation",
+      message,
+      sanitized: true,
+    })),
+    ...validation.warnings.map((message): PreferenceDiagnostic => ({
+      path,
+      scope,
+      severity: "warning",
+      kind: "validation",
+      message,
+      sanitized: true,
+    })),
+  ];
 
   return {
     path,
     scope,
     preferences: validation.preferences,
+    ...(ignored ? { ignored: true } : {}),
     ...(allWarnings.length > 0 ? { warnings: allWarnings } : {}),
+    ...(diagnostics.length > 0 ? { diagnostics } : {}),
   };
 }
 
@@ -286,20 +352,44 @@ export function _resetParseWarningFlag(): void {
 
 /** @internal Exported for testing only */
 export function parsePreferencesMarkdown(content: string): GSDPreferences | null {
+  return parsePreferencesMarkdownWithDiagnostics(content).preferences;
+}
+
+type PreferenceParseDiagnostic = Omit<PreferenceDiagnostic, "path" | "scope">;
+
+interface PreferenceParseResult {
+  preferences: GSDPreferences | null;
+  diagnostics: PreferenceParseDiagnostic[];
+}
+
+function parsePreferencesMarkdownWithDiagnostics(content: string): PreferenceParseResult {
   // Use indexOf instead of [\s\S]*? regex to avoid backtracking (#468)
   const startMarker = content.startsWith('---\r\n') ? '---\r\n' : '---\n';
   if (content.startsWith(startMarker)) {
     const searchStart = startMarker.length;
     const endIdx = content.indexOf('\n---', searchStart);
-    if (endIdx === -1) return null;
+    if (endIdx === -1) {
+      return {
+        preferences: null,
+        diagnostics: [{
+          severity: "error",
+          kind: "parse",
+          message: "preferences frontmatter is missing a closing --- delimiter",
+          ignored: true,
+        }],
+      };
+    }
     const block = content.slice(searchStart, endIdx);
-    return parseFrontmatterBlock(block.replace(/\r/g, ''));
+    return parseFrontmatterBlockWithDiagnostics(block.replace(/\r/g, ''), 1);
   }
 
   // Fallback: heading+list format (e.g. "## Git\n- isolation: none") (#2036)
   // GSD agents may write preferences files without frontmatter delimiters.
   if (/^##\s+\w/m.test(content)) {
-    return parseHeadingListFormat(content);
+    return {
+      preferences: parseHeadingListFormat(content),
+      diagnostics: [],
+    };
   }
 
   // Warn when a non-empty file exists but lacks frontmatter delimiters (#2036).
@@ -310,27 +400,82 @@ export function parsePreferencesMarkdown(content: string): GSDPreferences | null
       "Wrap your preferences in --- fences. See https://github.com/open-gsd/gsd-pi/issues/2036",
     );
   }
-  return null;
+  return {
+    preferences: null,
+    diagnostics: content.trim().length > 0
+      ? [{
+          severity: "error",
+          kind: "parse",
+          message: "preferences file has unrecognized format; expected YAML frontmatter delimiters (---) or markdown preference sections",
+          ignored: true,
+        }]
+      : [],
+  };
 }
 
 let _warnedFrontmatterParse = false;
-function parseFrontmatterBlock(frontmatter: string): GSDPreferences {
+function parseFrontmatterBlockWithDiagnostics(
+  frontmatter: string,
+  lineOffset: number,
+): { preferences: GSDPreferences; diagnostics: PreferenceParseDiagnostic[] } {
   try {
     const parsed = parseYaml(frontmatter);
     if (typeof parsed !== 'object' || parsed === null) {
-      return {} as GSDPreferences;
+      return {
+        preferences: {} as GSDPreferences,
+        diagnostics: [{
+          severity: "error",
+          kind: "validation",
+          message: "preferences frontmatter must be a YAML object",
+          ignored: true,
+        }],
+      };
     }
-    return normalizeParsedPreferences(parsed as GSDPreferences);
+    return {
+      preferences: normalizeParsedPreferences(parsed as GSDPreferences),
+      diagnostics: [],
+    };
   } catch (e) {
     // Warn at most once per session to avoid flooding TUI (#3376)
     if (!_warnedFrontmatterParse) {
       _warnedFrontmatterParse = true;
       logWarning("guided", `YAML parse error in preferences frontmatter (suppressing further): ${(e as Error).message}`);
     }
-    return {} as GSDPreferences;
+    const location = extractYamlErrorLocation(e, lineOffset);
+    return {
+      preferences: {} as GSDPreferences,
+      diagnostics: [{
+        severity: "error",
+        kind: "parse",
+        message: cleanYamlErrorMessage(e),
+        ...(location.line !== undefined ? { line: location.line } : {}),
+        ...(location.column !== undefined ? { column: location.column } : {}),
+        ignored: true,
+      }],
+    };
   }
 }
 
+function cleanYamlErrorMessage(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  const firstLine = message.split("\n")[0]?.trim() ?? "unknown YAML parse error";
+  return firstLine.replace(/\s+at line \d+, column \d+:?$/, "");
+}
+
+function extractYamlErrorLocation(
+  error: unknown,
+  lineOffset: number,
+): { line?: number; column?: number } {
+  const linePos = (error as { linePos?: Array<{ line?: unknown; col?: unknown }> })?.linePos;
+  const first = Array.isArray(linePos) ? linePos[0] : undefined;
+  const line = typeof first?.line === "number" ? first.line + lineOffset : undefined;
+  const column = typeof first?.col === "number" ? first.col : undefined;
+  return {
+    ...(line !== undefined ? { line } : {}),
+    ...(column !== undefined ? { column } : {}),
+  };
+}
+
 function normalizeParsedPreferences(preferences: GSDPreferences): GSDPreferences {
   const remoteQuestions = preferences.remote_questions;
   if (remoteQuestions && typeof remoteQuestions === "object" && typeof remoteQuestions.channel_id === "number") {
@@ -722,6 +867,24 @@ export function getIsolationMode(basePath?: string): "none" | "worktree" | "bran
   return "none"; // default — no isolation, work on current branch
 }
 
+/**
+ * Resolve the isolation mode a unit actually runs under. A session whose
+ * worktree isolation has degraded (worktree creation failed) falls back to
+ * the milestone branch in the project root, so configured "worktree" becomes
+ * effective "branch". A stranded-work recovery session likewise runs under
+ * the adopted mode (`strandedRecoveryIsolationMode`) rather than the
+ * configured one until the recovered milestone merges — adopting the
+ * milestone branch in the project root is intentional, not degraded.
+ */
+export function resolveEffectiveUnitIsolationMode(
+  configuredMode: ReturnType<typeof getIsolationMode>,
+  isolationDegraded: boolean,
+  strandedRecoveryIsolationMode: "worktree" | "branch" | null = null,
+): ReturnType<typeof getIsolationMode> {
+  if (configuredMode === "worktree" && isolationDegraded) return "branch";
+  return strandedRecoveryIsolationMode ?? configuredMode;
+}
+
 export function resolveParallelConfig(prefs: GSDPreferences | undefined): import("./types.js").ParallelConfig {
   return {
     enabled: prefs?.parallel?.enabled ?? false,

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

@@ -37,6 +37,7 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 9. If requirement status changed, call `gsd_requirement_update`; do not write `.gsd/REQUIREMENTS.md` directly.
 10. Prepare `gsd_slice_complete` content with camelCase fields `milestoneId`, `sliceId`, `sliceTitle`, `oneLiner`, `narrative`, `verification`, and `uatContent`.
 11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type.
+    **Web apps:** when inlined Web App UAT guidance is present, declare `browser-executable` or `runtime-executable` (not `artifact-driven`) for localhost/browser/screenshot steps; include dev-server preconditions and name Playwright specs when they exist.
 12. Review the inlined task-summary excerpts for DECISIONS.md/KNOWLEDGE.md-worthy decisions and gotchas. Read full `*-SUMMARY.md` only if needed. Capture with `capture_thought`; do not append knowledge files.
 13. When verification passes, call `gsd_slice_complete`. The DB-backed tool is the canonical write path. Do **not** manually write `{{sliceSummaryPath}}`. Do **not** manually write `{{sliceUatPath}}`. Do not edit roadmap checkboxes.
 14. Do not run git commands.

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

@@ -32,6 +32,8 @@ You execute. The inlined task plan is authoritative. Verify referenced files and
 - Prior task summaries:
 {{priorTaskLines}}
 
+{{onDemandContext}}
+
 ## Execution Rules
 
 1. Tersely narrate transitions, decisions, and verification outcomes between tool-call clusters.