@opengsd/gsd-pi 1.2.0-dev.844675c9 → 1.2.0-dev.84c56d87

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

@@ -16,7 +16,7 @@ import { spawnSync } from "node:child_process";
 import { nativeScanGsdTree } 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 ──────────────────────────────────────────────────
 const dirEntryCache = new Map();
 const dirListCache = new Map();
@@ -139,6 +139,33 @@ export function clearPathCache() {
     nativeTreeBase = null;
 }
 // ─── Name Builders ─────────────────────────────────────────────────────────
+/** Directories owned by the GSD framework — metadata, never project source. */
+export const FRAMEWORK_METADATA_DIRS = [".gsd", ".planning", ".audits"];
+/**
+ * Every artifact suffix used with the name builders below — the single source
+ * for the `<ID>-<SUFFIX>.md` naming vocabulary. Extend this list when a new
+ * artifact type is introduced; consumers (md-importer walking, pre-execution
+ * artifact detection) pick it up from here.
+ */
+export const PLANNING_ARTIFACT_SUFFIXES = [
+    "CONTEXT",
+    "CONTEXT-DRAFT",
+    "ROADMAP",
+    "PLAN",
+    "REPLAN",
+    "SUMMARY",
+    "RESEARCH",
+    "VALIDATION",
+    "ASSESSMENT",
+    "UAT",
+    "DISCUSSION",
+    "EVAL-REVIEW",
+    "PARKED",
+    "VERIFICATION-FAILED",
+    "CONTINUE",
+];
+/** Matches a bare planning-artifact file name, e.g. "M001-CONTEXT.md", "S01-PLAN.md". */
+export const PLANNING_ARTIFACT_NAME_RE = new RegExp(`^[MST]\\d+-(${PLANNING_ARTIFACT_SUFFIXES.join("|")})\\.md$`, "i");
 /**
  * Build a milestone-level file name.
  * ("M001", "CONTEXT") → "M001-CONTEXT.md"
@@ -422,31 +449,17 @@ function assertNotGlobalGsdHome(basePath, result) {
  * 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) {
-    // 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) {
     const contract = resolveGsdPathContract(rawBasePath);

package/dist/resources/extensions/gsd/pre-execution-checks.js

@@ -20,6 +20,7 @@ import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { isAbsolute, relative, resolve } from "node:path";
 import { validateVerificationCommand } from "./verification-gate.js";
+import { FRAMEWORK_METADATA_DIRS, PLANNING_ARTIFACT_NAME_RE } from "./paths.js";
 const NPM_COMMAND = process.platform === "win32" ? "npm.cmd" : "npm";
 function inputExistsOnDisk(normalizedFile, basePath, context) {
     if (existsSync(resolve(basePath, normalizedFile)))
@@ -510,6 +511,10 @@ export function checkFilePathConsistency(tasks, basePath, context) {
                 continue;
             if (!shouldValidateInputAsPath(file))
                 continue;
+            // Planning-artifact references are owned by checkPlanningArtifactReferences,
+            // which reports a precise removal message instead of "doesn't exist".
+            if (isPlanningArtifactReference(file, basePath, context))
+                continue;
             // Normalize path for consistent comparison
             const normalizedFile = toComparisonPath(file, basePath);
             if (containsGlobPattern(normalizedFile))
@@ -546,6 +551,71 @@ export function checkFilePathConsistency(tasks, basePath, context) {
     }
     return results;
 }
+// ─── Planning Artifact Reference Check ───────────────────────────────────────
+function isFrameworkMetadataPath(normalizedFile) {
+    return normalizedFile.split("/").some((segment) => FRAMEWORK_METADATA_DIRS.includes(segment.toLowerCase()));
+}
+/**
+ * True when a task IO entry references a GSD planning artifact.
+ *
+ * Task inputs are source files only — planning artifacts are projections of DB
+ * state that the framework preloads as composed context (see CONTEXT.md "Task
+ * Input"). Two triggers, deliberately different in strictness:
+ *
+ * - Any path entering framework-owned metadata (.gsd/, .planning/, .audits/)
+ *   is always a violation, even when the file exists.
+ * - A bare artifact-style basename (M001-CONTEXT.md, S01-PLAN.md, …) is a
+ *   violation only when it does NOT resolve to a real file. When such a file
+ *   genuinely exists in the source tree (e.g. a fixture), it is a source file
+ *   and stays legal; a path with directory components is likewise left to the
+ *   ordinary existence checks.
+ */
+function isPlanningArtifactReference(rawEntry, basePath, context) {
+    if (!shouldValidateInputAsPath(rawEntry))
+        return false;
+    const normalized = toComparisonPath(rawEntry, basePath);
+    if (isFrameworkMetadataPath(normalized))
+        return true;
+    return (!normalized.includes("/") &&
+        PLANNING_ARTIFACT_NAME_RE.test(normalized) &&
+        !inputExistsOnDisk(normalized, basePath, context));
+}
+/**
+ * Block GSD planning artifacts in task IO fields (inputs, files, expectedOutput).
+ *
+ * For inputs/files the violation smuggles a projection into the executor's
+ * preloaded source context; for expectedOutput it promises a write the runtime
+ * write-gate would reject mid-execution. Both get a precise message so the
+ * planning retry steers toward *removing* the reference, not creating the file.
+ * checkFilePathConsistency and checkTaskOrdering skip entries this check owns.
+ */
+export function checkPlanningArtifactReferences(tasks, basePath, context) {
+    const results = [];
+    for (const task of tasks) {
+        const fields = [
+            { label: "inputs", entries: task.inputs },
+            { label: "files", entries: task.files },
+            { label: "expectedOutput", entries: task.expected_output },
+        ];
+        for (const { label, entries } of fields) {
+            for (const file of entries) {
+                if (!isPlanningArtifactReference(file, basePath, context))
+                    continue;
+                const message = label === "expectedOutput"
+                    ? `Task ${task.id} lists '${file}' in expectedOutput — GSD planning artifacts are written by workflow tools (e.g. gsd_summary_save), never by tasks; remove it`
+                    : `Task ${task.id} lists '${file}' in ${label} — GSD planning artifacts are projections preloaded as context, never task ${label}; remove it`;
+                results.push({
+                    category: "file",
+                    target: file,
+                    passed: false,
+                    message,
+                    blocking: true,
+                });
+            }
+        }
+    }
+    return results;
+}
 // ─── Task Ordering Check ─────────────────────────────────────────────────────
 /**
  * Detect impossible task ordering: task N reads a file that task N+M creates.
@@ -583,6 +653,10 @@ export function checkTaskOrdering(tasks, basePath, context) {
                 continue;
             if (!shouldValidateInputAsPath(file))
                 continue;
+            // Owned by checkPlanningArtifactReferences — avoid a duplicate sequence
+            // finding on top of the removal message.
+            if (isPlanningArtifactReference(file, basePath, context))
+                continue;
             const normalizedFile = toComparisonPath(file, basePath);
             if (containsGlobPattern(normalizedFile))
                 continue;
@@ -611,6 +685,21 @@ export function checkTaskOrdering(tasks, basePath, context) {
     }
     return results;
 }
+// ─── Shared Path-Check Composition ───────────────────────────────────────────
+/**
+ * The synchronous path-shaped checks, in order. One list shared by the
+ * plan-persist gate (gsd_plan_slice) and the dispatch gate
+ * (runPreExecutionChecks) so the two cannot drift — the checks coordinate
+ * ownership of planning-artifact entries via isPlanningArtifactReference
+ * skips, which only works when they run as a set.
+ */
+export function runTaskPathChecks(tasks, basePath, context) {
+    return [
+        ...checkPlanningArtifactReferences(tasks, basePath, context),
+        ...checkFilePathConsistency(tasks, basePath, context),
+        ...checkTaskOrdering(tasks, basePath, context),
+    ];
+}
 /**
  * Extract function signatures from code blocks in task description.
  * Uses heuristic regex — not an AST parser.
@@ -741,11 +830,10 @@ export async function runPreExecutionChecks(tasks, basePath, context) {
     const startTime = Date.now();
     const allChecks = [];
     // Run sync checks first
-    const fileChecks = checkFilePathConsistency(tasks, basePath, context);
-    const orderingChecks = checkTaskOrdering(tasks, basePath, context);
+    const pathChecks = runTaskPathChecks(tasks, basePath, context);
     const contractChecks = checkInterfaceContracts(tasks, basePath);
     const verificationChecks = checkVerificationCommands(tasks);
-    allChecks.push(...fileChecks, ...orderingChecks, ...contractChecks, ...verificationChecks);
+    allChecks.push(...pathChecks, ...contractChecks, ...verificationChecks);
     // Run async package checks
     const packageChecks = await checkPackageExistence(tasks, basePath);
     allChecks.push(...packageChecks);

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

@@ -0,0 +1,67 @@
+import { loadGlobalGSDPreferences, loadProjectGSDPreferences, } from "./preferences.js";
+const notifiedPreferenceDiagnostics = new Set();
+export function collectPreferenceDiagnostics(basePath) {
+    const diagnostics = [
+        ...(loadGlobalGSDPreferences()?.diagnostics ?? []),
+        ...(loadProjectGSDPreferences(basePath)?.diagnostics ?? []),
+    ];
+    const seen = new Set();
+    const unique = [];
+    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) {
+    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) {
+    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, basePath, options) {
+    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() {
+    notifiedPreferenceDiagnostics.clear();
+}
+function preferenceDiagnosticSignature(diagnostic) {
+    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, surface = "default") {
+    return `${surface}\u0000${preferenceDiagnosticSignature(diagnostic)}`;
+}

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

@@ -11,6 +11,7 @@ import { join } from "node:path";
 import { gsdHome } from "./gsd-home.js";
 import { canonicalModelForTier, defaultRoutingConfig, resolveModelForTier } from "./model-router.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { getUnitPhaseChain } from "./unit-registry.js";
 /**
  * Resolve which model ID to use for a given auto-mode unit type.
  * Returns undefined if no model preference is set for this unit type.
@@ -29,53 +30,18 @@ export function resolveModelForUnit(unitType) {
  * (`resolveThinkingLevelForUnit`) so the two never drift (ADR-026).
  */
 export function phaseChainForUnit(unitType) {
-    switch (unitType) {
-        case "research-milestone":
-        case "research-slice":
-        // Deep-mode project research orchestrator. Reads PROJECT.md / REQUIREMENTS.md
-        // and fans out research subagents. Routes to the research bucket.
-        case "research-project":
-            return ["research"];
-        case "plan-milestone":
-        case "plan-slice":
-        case "refine-slice":
-        case "replan-slice":
-            return ["planning"];
-        // Deep-mode project-level discussion units route to the same model bucket
-        // as milestone-level discussion (interactive interview style). Workflow
-        // preferences and research-decision are tiny ask_user_questions style units
-        // that share the discuss bucket because they are conversational. All fall
-        // back to planning when no `discuss` bucket is set.
-        case "discuss-milestone":
-        case "discuss-slice":
-        case "discuss-project":
-        case "discuss-requirements":
-        case "workflow-preferences":
-        case "research-decision":
-            return ["discuss", "planning"];
-        case "execute-task":
-        case "reactive-execute":
-            return ["execution"];
-        case "execute-task-simple":
-            return ["execution_simple", "execution"];
-        case "complete-slice":
-        case "complete-milestone":
-        case "worktree-merge":
-            return ["completion"];
-        case "run-uat":
-            return ["uat", "completion"];
-        case "reassess-roadmap":
-        case "rewrite-docs":
-        case "gate-evaluate":
-        case "validate-milestone":
-            return ["validation", "planning"];
-        default:
-            // Subagent unit types (e.g., "subagent", "subagent/scout")
-            if (unitType === "subagent" || unitType.startsWith("subagent/")) {
-                return ["subagent"];
-            }
-            return undefined;
+    // Unit types declare their chain on their Unit Descriptor (ADR-033).
+    const declared = getUnitPhaseChain(unitType);
+    if (declared)
+        return [...declared];
+    // Dispatch types without a Unit Descriptor.
+    if (unitType === "worktree-merge")
+        return ["completion"];
+    // Subagent unit types (e.g., "subagent", "subagent/scout")
+    if (unitType === "subagent" || unitType.startsWith("subagent/")) {
+        return ["subagent"];
     }
+    return undefined;
 }
 /**
  * Find the phase bucket whose `models` entry wins the chain for a unit, plus

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

@@ -98,37 +98,41 @@ export function normalizePreferencesShape(loaded) {
 }
 // ─── Loading ────────────────────────────────────────────────────────────────
 export function loadGlobalGSDPreferences() {
-    return loadPreferencesFile(globalPreferencesPath(), "global")
-        ?? loadPreferencesFile(legacyGlobalPreferencesPathLowercase(), "global")
-        ?? loadPreferencesFile(legacyGlobalPreferencesPath(), "global");
+    return loadFirstUsablePreferencesFile([
+        globalPreferencesPath(),
+        legacyGlobalPreferencesPathLowercase(),
+        legacyGlobalPreferencesPath(),
+    ], "global");
 }
 export function loadProjectGSDPreferences(basePath) {
-    return loadPreferencesFile(projectPreferencesPath(basePath), "project")
-        ?? loadPreferencesFile(legacyProjectPreferencesPathLowercase(basePath), "project");
+    return loadFirstUsablePreferencesFile([
+        projectPreferencesPath(basePath),
+        legacyProjectPreferencesPathLowercase(basePath),
+    ], "project");
 }
 export function loadEffectiveGSDPreferences(basePath, opts) {
     const globalPreferences = loadGlobalGSDPreferences();
     const projectPreferences = loadProjectGSDPreferences(basePath);
-    const projectHasPlanningDepth = projectPreferences?.preferences.planning_depth !== undefined;
-    if (!globalPreferences && !projectPreferences)
+    const effectiveGlobalPreferences = globalPreferences?.ignored ? null : globalPreferences;
+    const effectiveProjectPreferences = projectPreferences?.ignored ? null : projectPreferences;
+    const projectHasPlanningDepth = effectiveProjectPreferences?.preferences.planning_depth !== undefined;
+    if (!effectiveGlobalPreferences && !effectiveProjectPreferences)
         return null;
     let result;
-    if (!globalPreferences) {
-        result = projectPreferences;
+    if (!effectiveGlobalPreferences) {
+        result = effectiveProjectPreferences;
     }
-    else if (!projectPreferences) {
-        result = globalPreferences;
+    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 } : {}),
         };
     }
     // Apply token-profile defaults as the lowest-priority layer so that
@@ -152,6 +156,35 @@ export function loadEffectiveGSDPreferences(basePath, opts) {
     result = stripInheritedPlanningDepth(result, projectHasPlanningDepth);
     return result;
 }
+function mergePreferenceMetadata(primary, secondary) {
+    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, scope) {
+    let ignoredPreferences = 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, projectHasPlanningDepth) {
     if (projectHasPlanningDepth || loaded.preferences.planning_depth === undefined) {
         return loaded;
@@ -167,16 +200,39 @@ function loadPreferencesFile(path, scope) {
     if (!existsSync(path))
         return null;
     const raw = readFileSync(path, "utf-8");
-    const preferences = parsePreferencesMarkdown(raw);
-    if (!preferences)
+    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 = [
+        ...parsed.diagnostics.map((diagnostic) => ({ ...diagnostic, path, scope })),
+        ...validation.errors.map((message) => ({
+            path,
+            scope,
+            severity: "error",
+            kind: "validation",
+            message,
+            sanitized: true,
+        })),
+        ...validation.warnings.map((message) => ({
+            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 } : {}),
     };
 }
 let _warnedUnrecognizedFormat = false;
@@ -189,20 +245,35 @@ export function _resetParseWarningFlag() {
 }
 /** @internal Exported for testing only */
 export function parsePreferencesMarkdown(content) {
+    return parsePreferencesMarkdownWithDiagnostics(content).preferences;
+}
+function parsePreferencesMarkdownWithDiagnostics(content) {
     // 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).
     if (content.trim().length > 0 && !_warnedUnrecognizedFormat) {
@@ -210,16 +281,37 @@ export function parsePreferencesMarkdown(content) {
         console.warn("[GSD] Warning: preferences file has unrecognized format — content does not use YAML frontmatter delimiters (---). " +
             "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) {
+function parseFrontmatterBlockWithDiagnostics(frontmatter, lineOffset) {
     try {
         const parsed = parseYaml(frontmatter);
         if (typeof parsed !== 'object' || parsed === null) {
-            return {};
+            return {
+                preferences: {},
+                diagnostics: [{
+                        severity: "error",
+                        kind: "validation",
+                        message: "preferences frontmatter must be a YAML object",
+                        ignored: true,
+                    }],
+            };
         }
-        return normalizeParsedPreferences(parsed);
+        return {
+            preferences: normalizeParsedPreferences(parsed),
+            diagnostics: [],
+        };
     }
     catch (e) {
         // Warn at most once per session to avoid flooding TUI (#3376)
@@ -227,9 +319,35 @@ function parseFrontmatterBlock(frontmatter) {
             _warnedFrontmatterParse = true;
             logWarning("guided", `YAML parse error in preferences frontmatter (suppressing further): ${e.message}`);
         }
-        return {};
+        const location = extractYamlErrorLocation(e, lineOffset);
+        return {
+            preferences: {},
+            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) {
+    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, lineOffset) {
+    const linePos = error?.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) {
     const remoteQuestions = preferences.remote_questions;
     if (remoteQuestions && typeof remoteQuestions === "object" && typeof remoteQuestions.channel_id === "number") {
@@ -581,6 +699,20 @@ export function getIsolationMode(basePath) {
         return "branch";
     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, isolationDegraded, strandedRecoveryIsolationMode = null) {
+    if (configuredMode === "worktree" && isolationDegraded)
+        return "branch";
+    return strandedRecoveryIsolationMode ?? configuredMode;
+}
 export function resolveParallelConfig(prefs) {
     return {
         enabled: prefs?.parallel?.enabled ?? false,

package/dist/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/dist/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.