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

package/dist/resources/extensions/gsd/milestone-readiness.js

@@ -0,0 +1,77 @@
+// Project/App: gsd-pi
+// File Purpose: Classify milestone readiness from DB status, slices, and artifacts.
+import { readFileSync } from "node:fs";
+import { getMilestone, getMilestoneSlices, isDbAvailable } from "./gsd-db.js";
+import { parseRoadmapSlices } from "./roadmap-slices.js";
+import { logWarning } from "./workflow-logger.js";
+export function classifyMilestoneReadiness(input) {
+    const hasContext = input.hasContext === true;
+    const hasDraftContext = !hasContext && input.hasDraftContext === true;
+    const hasSummary = input.hasSummary === true;
+    const sliceCount = input.sliceCount ?? 0;
+    const hasExecutablePlan = sliceCount > 0;
+    const status = input.status ?? null;
+    if (status === "complete" || hasSummary) {
+        return { kind: "terminal", hasContext, hasDraftContext, hasExecutablePlan };
+    }
+    if (status === "queued" && !hasContext && sliceCount === 0) {
+        return { kind: "queued-shell", hasContext, hasDraftContext, hasExecutablePlan };
+    }
+    if ((status === "needs-discussion" && !hasContext) || hasDraftContext) {
+        return { kind: "needs-discussion", hasContext, hasDraftContext, hasExecutablePlan };
+    }
+    if (hasExecutablePlan) {
+        return { kind: "executable-plan", hasContext, hasDraftContext, hasExecutablePlan };
+    }
+    return { kind: "planning-pending", hasContext, hasDraftContext, hasExecutablePlan };
+}
+export function readinessNeedsDiscussion(readiness) {
+    return readiness.kind === "needs-discussion" ||
+        (readiness.kind === "queued-shell" && readiness.hasDraftContext);
+}
+export function describeMilestoneReadinessPhase(phase) {
+    switch (phase) {
+        case "needs-discussion":
+            return {
+                label: "Discuss milestone draft",
+                description: "Milestone has a draft context — needs discussion before planning.",
+            };
+        case "pre-planning":
+            return {
+                label: "Research & plan milestone",
+                description: "Scout the landscape and create the roadmap.",
+            };
+        default:
+            return null;
+    }
+}
+function executablePlanSliceCount(milestoneId, roadmapFile) {
+    if (isDbAvailable()) {
+        return getMilestoneSlices(milestoneId).length;
+    }
+    if (!roadmapFile)
+        return 0;
+    try {
+        return parseRoadmapSlices(readFileSync(roadmapFile, "utf-8")).length;
+    }
+    catch (e) {
+        logWarning("guided", `failed to parse roadmap slices for ${milestoneId}: ${e.message}`);
+        return 0;
+    }
+}
+export function assessMilestoneHandoffReadiness(input) {
+    const milestone = isDbAvailable() ? getMilestone(input.milestoneId) : null;
+    return classifyMilestoneReadiness({
+        status: milestone?.status,
+        hasContext: input.contextFile != null,
+        sliceCount: executablePlanSliceCount(input.milestoneId, input.roadmapFile),
+    });
+}
+export function formatAcceptedDiscussHandoffMessage(milestoneId, readiness) {
+    if (readiness.hasExecutablePlan)
+        return `Milestone ${milestoneId} ready.`;
+    if (readiness.hasContext) {
+        return `Milestone ${milestoneId} context captured. Continuing the planning pipeline.`;
+    }
+    return `Milestone ${milestoneId} planning artifacts captured. Continuing the planning pipeline.`;
+}

package/dist/resources/extensions/gsd/milestone-settlement.js

@@ -0,0 +1,50 @@
+// Project/App: gsd-pi
+// File Purpose: Milestone closeout settlement state across DB proof, artifacts, merge, and cleanup.
+import { isInAutoWorktree } from "./auto-worktree.js";
+import { formatCloseoutProofBlock, proveMilestoneCloseout, } from "./milestone-closeout-proof.js";
+import { resolveCloseoutArtifactProjection } from "./artifact-projection.js";
+function isActiveUnmergedWorktree(input) {
+    if (!input.milestoneId || input.milestoneMerged)
+        return false;
+    return isInAutoWorktree(input.basePath);
+}
+export function evaluateAllCompleteSettlement(input) {
+    if (input.statePhase !== "complete") {
+        return { ok: true, reason: "not-applicable" };
+    }
+    if (!isActiveUnmergedWorktree(input)) {
+        return { ok: true, reason: "settled" };
+    }
+    const milestoneId = input.milestoneId;
+    if (!milestoneId) {
+        return { ok: true, reason: "settled" };
+    }
+    const projection = resolveCloseoutArtifactProjection({
+        milestoneId,
+        basePath: input.basePath,
+        originalBasePath: input.originalBasePath,
+    });
+    const proof = proveMilestoneCloseout(milestoneId, {
+        refreshFromDisk: true,
+        summaryArtifactBasePath: projection.summaryArtifactBasePath,
+    });
+    if (!proof.ok) {
+        return {
+            ok: false,
+            reason: "closeout-blocked",
+            action: "pause",
+            message: `${formatCloseoutProofBlock(proof)} The milestone branch has not been merged to main.`,
+            nextAction: `Resolve closeout blockers, then retry \`/gsd dispatch complete-milestone ${milestoneId}\`.`,
+            milestoneId,
+        };
+    }
+    return {
+        ok: false,
+        reason: "merge-pending",
+        action: "pause",
+        message: `Milestone ${milestoneId} is complete, but its worktree branch has not been merged to main. ` +
+            `Retry with \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+        nextAction: `Retry \`/gsd dispatch complete-milestone ${milestoneId}\` or merge manually.`,
+        milestoneId,
+    };
+}

package/dist/resources/extensions/gsd/milestone-validation-evidence.js

@@ -0,0 +1,73 @@
+// Project/App: gsd-pi
+// File Purpose: Forwarded validation evidence rules for milestone validation.
+import { getArtifact, getMilestone, getMilestoneSlices } from "./gsd-db.js";
+import { loadFile } from "./files.js";
+import { resolveSliceFile } from "./paths.js";
+import { compactTextParts, hasBrowserEvidenceText, hasBrowserRequiredText, } from "./browser-evidence.js";
+export function hasRuntimeExecutableUatEvidenceText(text) {
+    if (!/\buatType:\s*runtime-executable\b/i.test(text))
+        return false;
+    if (!/\bverdict:\s*PASS\b/i.test(text))
+        return false;
+    return /^\|\s*[^|\n]+\s*\|\s*runtime\s*\|\s*PASS\s*\|[^|\n]*\bgsd_uat_exec\b/mi.test(text);
+}
+export async function browserEvidenceGateRequiresAttention(params, basePath) {
+    if (params.verdict !== "pass")
+        return false;
+    const milestone = getMilestone(params.milestoneId);
+    const slices = getMilestoneSlices(params.milestoneId);
+    const requirementText = compactTextParts([
+        milestone?.vision,
+        milestone?.success_criteria,
+        milestone?.verification_uat,
+        params.successCriteriaChecklist,
+        params.verificationClasses,
+        ...slices.flatMap((slice) => [
+            slice.demo,
+            slice.goal,
+            slice.success_criteria,
+        ]),
+    ]);
+    if (!hasBrowserRequiredText(requirementText))
+        return false;
+    const sliceEvidencePairs = [];
+    for (const slice of slices) {
+        const chunks = [];
+        const artifactPath = `milestones/${params.milestoneId}/slices/${slice.id}/${slice.id}-ASSESSMENT.md`;
+        const artifact = getArtifact(artifactPath);
+        if (artifact?.full_content)
+            chunks.push(artifact.full_content);
+        const assessmentPath = resolveSliceFile(basePath, params.milestoneId, slice.id, "ASSESSMENT");
+        const assessmentContent = assessmentPath ? await loadFile(assessmentPath) : null;
+        if (assessmentContent)
+            chunks.push(assessmentContent);
+        sliceEvidencePairs.push({
+            sliceRequirementText: compactTextParts([slice.demo, slice.goal, slice.success_criteria]),
+            evidenceText: chunks.join("\n\n"),
+        });
+    }
+    const browserRequiringSlices = sliceEvidencePairs.filter((slice) => hasBrowserRequiredText(slice.sliceRequirementText));
+    const runtimeBypasses = browserRequiringSlices.length > 0
+        ? browserRequiringSlices.every((slice) => hasRuntimeExecutableUatEvidenceText(slice.evidenceText))
+        : sliceEvidencePairs.some((slice) => hasRuntimeExecutableUatEvidenceText(slice.evidenceText));
+    if (runtimeBypasses)
+        return false;
+    const persistedEvidence = sliceEvidencePairs.map((slice) => slice.evidenceText).join("\n\n");
+    const validationEvidence = compactTextParts([
+        params.successCriteriaChecklist,
+        params.verificationClasses,
+        params.verdictRationale,
+        params.remediationPlan,
+    ]);
+    return !hasBrowserEvidenceText(`${persistedEvidence}\n\n${validationEvidence}`);
+}
+export function applyBrowserEvidenceGate(params) {
+    const note = "Browser evidence gate: Browser-observable acceptance criteria were detected, but no persisted ASSESSMENT or validation evidence recorded browser actions with assertions. Downgraded from pass to needs-attention.";
+    return {
+        ...params,
+        verdict: "needs-attention",
+        verdictRationale: params.verdictRationale.trim()
+            ? `${params.verdictRationale.trim()}\n\n${note}`
+            : note,
+    };
+}

package/dist/resources/extensions/gsd/milestone-validation-verdict.js

@@ -0,0 +1,57 @@
+// Project/App: gsd-pi
+// File Purpose: Resolve the authoritative milestone validation verdict across DB and disk projections.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveExpectedArtifactPath } from "./auto-artifact-paths.js";
+import { loadFile } from "./files.js";
+import { getLatestAssessmentByScope, isDbAvailable } from "./gsd-db.js";
+import { gsdProjectionRoot } from "./paths.js";
+import { extractVerdict, isValidMilestoneVerdict, } from "./verdict-parser.js";
+import { resolveCanonicalMilestoneRoot } from "./worktree-manager.js";
+import { resolveWorktreeProjectRoot } from "./worktree-root.js";
+function verdictFromContent(content) {
+    if (!content)
+        return undefined;
+    const verdict = extractVerdict(content);
+    return verdict && isValidMilestoneVerdict(verdict) ? verdict : undefined;
+}
+function verdictFromDb(milestoneId) {
+    if (!isDbAvailable())
+        return undefined;
+    const assessment = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+    const status = typeof assessment?.status === "string" ? assessment.status : undefined;
+    return status && isValidMilestoneVerdict(status) ? status : undefined;
+}
+async function verdictFromValidationPath(path) {
+    if (!path || !existsSync(path))
+        return undefined;
+    return verdictFromContent(await loadFile(path));
+}
+/**
+ * Resolve the milestone validation verdict using the same authority order as
+ * DB-backed state derivation, with filesystem fallbacks that mirror
+ * `resolveExpectedArtifactPath` (canonical worktree projection, then project
+ * root). Manual `/gsd verdict` overrides persist to the DB first; a stale
+ * worktree-local VALIDATION.md must not re-block auto-mode after the override.
+ */
+export async function resolveMilestoneValidationVerdict(basePath, milestoneId) {
+    const dbVerdict = verdictFromDb(milestoneId);
+    if (dbVerdict)
+        return dbVerdict;
+    const canonicalBase = resolveCanonicalMilestoneRoot(basePath, milestoneId);
+    const canonicalPath = resolveExpectedArtifactPath("validate-milestone", milestoneId, canonicalBase);
+    const canonicalVerdict = await verdictFromValidationPath(canonicalPath);
+    if (canonicalVerdict)
+        return canonicalVerdict;
+    const projectRoot = resolveWorktreeProjectRoot(basePath);
+    if (projectRoot !== canonicalBase) {
+        const projectPath = resolveExpectedArtifactPath("validate-milestone", milestoneId, projectRoot);
+        const projectVerdict = await verdictFromValidationPath(projectPath);
+        if (projectVerdict)
+            return projectVerdict;
+    }
+    // Last resort: direct canonical projection path even when resolveDir helpers
+    // have not materialized the milestone directory yet.
+    const directPath = join(gsdProjectionRoot(canonicalBase), "milestones", milestoneId, `${milestoneId}-VALIDATION.md`);
+    return verdictFromValidationPath(directPath);
+}

package/dist/resources/extensions/gsd/parallel-eligibility.js

@@ -4,11 +4,10 @@
  * Analyzes which milestones can safely run in parallel by checking
  * dependency satisfaction and file overlap across slice plans.
  */
-import { existsSync } from "node:fs";
 import { deriveState } from "./state.js";
-import { resolveGsdPathContract } 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";
 // ─── File Collection ─────────────────────────────────────────────────────────
 /**
  * Collect all `filesLikelyTouched` across every slice plan in a milestone.
@@ -64,9 +63,7 @@ function detectFileOverlaps(fileSets) {
  */
 export async function analyzeParallelEligibility(basePath) {
     if (!isDbAvailable()) {
-        const { projectDb } = resolveGsdPathContract(basePath);
-        if (existsSync(projectDb))
-            openDatabase(projectDb);
+        openExistingWorkflowDatabase(basePath);
     }
     const milestoneIds = findMilestoneIds(basePath);
     const state = await deriveState(basePath);

package/dist/resources/extensions/gsd/parallel-orchestrator.js

@@ -12,9 +12,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 { writeSessionStatus, readAllSessionStatuses, readSessionStatus, removeSessionStatus, sendSignal, cleanupStaleSessions, } from "./session-status-io.js";
 import { analyzeParallelEligibility, } from "./parallel-eligibility.js";
@@ -448,7 +449,7 @@ export function _createMilestoneWorktree(basePath, milestoneId) {
     // 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;
 }
 // ─── Worker Spawning ───────────────────────────────────────────────────

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.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") {

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.