@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.0b870afa

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/projection-flush.ts

@@ -0,0 +1,20 @@
+// Project/App: gsd-pi
+// File Purpose: Single workflow projection flush seam for mutation exits.
+
+import { renderAllProjections } from "./workflow-projections.js";
+
+export interface ProjectionFlushScope {
+  milestoneId: string;
+}
+
+export interface ProjectionFlushResult {
+  milestoneId: string;
+}
+
+export async function flushWorkflowProjections(
+  basePath: string,
+  scope: ProjectionFlushScope,
+): Promise<ProjectionFlushResult> {
+  await renderAllProjections(basePath, scope.milestoneId);
+  return { milestoneId: scope.milestoneId };
+}

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

@@ -24,7 +24,7 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 1. Use the inlined Slice Summary and UAT templates.
 2. {{skillActivation}}
-3. Run all slice-level verification through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands.
+3. Run all slice-level verification through `gsd_exec` / Context Mode evidence; refresh current state if needed. Do not use direct `bash` for verification commands. See the prepended **Tool Surface** block for unavailable tools.
 4. Complete only when every required check passes. If verification fails or source changes are needed, do **not** edit source files in this unit and do **not** call `gsd_slice_complete`.
 5. If verification fails:
    - Task-specific regressions: if the failure is in files the task touched and pre-task verification evidence shows it was absent before that task ran, call `gsd_task_reopen` with that task and reason.
@@ -36,7 +36,8 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 8. Address every Gate to Close. Q8 = **Operational Readiness**: health signal, failure signal, recovery, monitoring gaps. Omit empty sections.
 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.
+11. Draft concrete UAT with preconditions, steps, expected outcomes, edge cases, and UAT Type. Declare the type as a bullet under a `## UAT Type` heading, exactly like `- UAT mode: browser-executable`.
+    **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.
@@ -48,4 +49,4 @@ Use `subagent` only when useful: reviewer, security, or tester. Apply findings b
 
 **You MUST call `gsd_slice_complete` with summary and UAT content only after verification passes.**
 
-When done, say: "Slice {{sliceId}} complete."
+When done, say: "Slice {{sliceId}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/src/resources/extensions/gsd/prompts/discuss.md

@@ -31,18 +31,17 @@ After reflection is confirmed, choose the approach from actual scope, not a labe
 
 {{preparationContext}}
 
-## Mandatory Investigation Before First Question Round
+## Ground the First Question Round
 
-Before the first question round, gather enough evidence for grounded questions:
-1. Scout relevant code with `ls`, `find`, `rg`, or `scout`.
-2. Check mentioned tech with `resolve_library` / `get_library_docs`.
-3. Use web tools only for current external facts.
+Ground your questions in the **Preparation Context above** (codebase snapshot, prior context) plus the user's reflected vision — that is authoritative. **Do not survey the codebase** with `ls`/`find`/`rg`/`scout` before asking; the snapshot already covers code reality. Read a specific file only when a question's answer genuinely hinges on it.
+1. Check mentioned tech with `resolve_library` / `get_library_docs`.
+2. Use web tools only for current external facts.
 
-Budget searches across the discussion; prefer docs and one-shot `search_and_read`. Re-investigate only when answers expose new gaps.
+Budget searches across the discussion; prefer docs and one-shot `search_and_read`. Read on-demand only when an answer exposes a specific gap.
 
 ## Layered Question Rounds
 
-Questions have four layers. At each layer, ask 1-3 open questions per round, investigate as needed, and gate before advancing.
+Questions have four layers. At each layer, ask 1-3 open questions per round, read a specific file on-demand if an answer needs it, and gate before advancing.
 
 **Default to open questions.** Use `ask_user_questions` only for 2-3 distinct paths with clear tradeoffs. Use plain text for nuanced design questions.
 

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.
@@ -74,4 +76,4 @@ Keep about **{{verificationBudget}}** for verification and summary. If context i
 
 **You MUST call `gsd_task_complete` before finishing, including when the stale-path safety rule stops execution.**
 
-When done, say: "Task {{taskId}} complete."
+When done, say: "Task {{taskId}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/src/resources/extensions/gsd/prompts/guided-discuss-milestone.md

@@ -19,15 +19,13 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify real gray are
 Before asking, read `.gsd/PROJECT.md` and find `## Project Shape` -> `**Complexity:**`. Use `simple` or `complex`; default to `complex` if missing, stale, or unclear.
 
 - `simple`: 1-2 plain-text rounds; skip parallel-research investigation; use `ask_user_questions` only for concrete alternatives.
-- `complex`: investigate first, use 3-4-option structured questions, and expect multiple rounds.
+- `complex`: ground in the preloaded context first, use 3-4-option structured questions, and expect multiple rounds.
 
 ### Before your first question round
 
-Investigate enough to avoid assumption-driven questions:
-- Scout existing code with `rg`, `find`, or `scout`.
-- Check roadmap context above for surrounding scope.
-- Use `resolve_library` / `get_library_docs` for unfamiliar libraries; prefer them over web search.
+Ground your questions in the **preloaded context above** (milestone roadmap/context/research, the decisions register, prior-milestone summaries) plus any Preparation Context snapshot — those are authoritative. **Do not survey the codebase** with `rg`/`find`/`scout` before asking; the preloaded files are marked do-not-re-read. Read a specific file only when a question's answer genuinely hinges on it.
 - Identify the 3-5 behavioral or architectural unknowns that materially change what gets built.
+- Use `resolve_library` / `get_library_docs` for unfamiliar libraries; prefer them over web search.
 
 **Web search budget:** Limited per turn, typically 3-5. Prefer docs tools and `search_and_read`; use 2-3 searches in the first pass and save the rest.
 
@@ -43,13 +41,13 @@ Ask **1–3 questions per round**. Target one focus at a time:
 
 **Never fabricate or simulate user input.** Never generate fake transcript markers like `[User]`, `[Human]`, or `User:`. Ask one question round, then wait for the user's actual response before continuing.
 
-**Single user-facing message (NON-BYPASSABLE):** After investigation, send **one** assistant message that contains your questions (and at most a short recap — 2-3 sentences, not a feature catalog). **End the turn there.** Do not send a second message that restates the same ask ("what do you want M00X to be?", "before I can write the context file…", etc.). If you already asked, stop — do not elaborate in a follow-up message in the same turn.
+**Single user-facing message (NON-BYPASSABLE):** After grounding in the preloaded context, send **one** assistant message that contains your questions (and at most a short recap — 2-3 sentences, not a feature catalog). **End the turn there.** Do not send a second message that restates the same ask ("what do you want M00X to be?", "before I can write the context file…", etc.). If you already asked, stop — do not elaborate in a follow-up message in the same turn.
 
 **If `{{structuredQuestionsAvailable}}` is `true`:** use `ask_user_questions` exactly once per turn with 1-3 question objects. Keep labels short (3-5 words). In `complex` mode, multi-choice questions MUST offer **3 or 4 concrete, researched options** plus **"Other — let me discuss"**; options must be grounded in the investigation, not placeholders. In `simple` mode, 2 options is fine for binary alternatives. Binary depth-check/wrap-up gates are exempt. If the user chooses "Other — let me discuss" or gives a long freeform answer, switch to plain-text follow-up before resuming structured questions.
 
 **If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions. Wait for answers before asking the next round.
 
-After each answer, investigate only new unknowns, then ask the next round.
+After each answer, resolve only the new unknowns from context (re-read a specific file only if one is needed), then ask the next round.
 
 ### Round cadence
 

package/src/resources/extensions/gsd/prompts/guided-discuss-project.md

@@ -36,11 +36,11 @@ After the opening answer, classify project shape as **`simple`** or **`complex`*
 
 Persist the verdict through `gsd_summary_save` with `artifact_type: "PROJECT"` into `## Project Shape`; downstream `discuss-requirements`, `discuss-milestone`, and `discuss-slice` read the rendered projection.
 
+When the project is browser-facing (web app, SPA, static site with UI, Next/React/Vue, etc.), also record **`Web stack:`** under `## Project Shape` (framework + whether Playwright or browser UAT is expected). Downstream planning uses this to choose `browser-executable` / `runtime-executable` UAT instead of deferring UI proof to humans.
+
 ### Before deeper rounds
 
-Investigate enough to avoid assumption-driven questions:
-- Scout code with `rg`, `find`, or `scout` for greenfield/brownfield and framework signals.
-- Check prior `.planning/` or `.gsd/` artifacts.
+Ground your questions in the **Preparation Context snapshot above** (stack, structure, greenfield/brownfield and framework signals) plus any prior `.planning/` or `.gsd/` artifacts — those are authoritative. **Do not survey the codebase** with `rg`/`find`/`scout` before asking; read a specific file only when a question's answer genuinely hinges on it.
 - Use `resolve_library` / `get_library_docs` for unfamiliar mentioned libraries.
 
 **Web search budget:** typically 3-5 per turn. Prefer docs tools; use 2-3 searches first and save the rest.
@@ -53,13 +53,13 @@ Ask **1–3 questions per round**, one focus at a time: what, who, core value, a
 
 **Shape-dependent cadence:**
 - **`simple`**: 1-2 plain-text rounds; use `ask_user_questions` only for concrete alternatives; reach the depth checklist quickly.
-- **`complex`**: full investigation, multiple rounds, structured questions when meaningful alternatives exist.
+- **`complex`**: ground in the snapshot and prior artifacts, multiple rounds, structured questions when meaningful alternatives exist.
 
 **If `{{structuredQuestionsAvailable}}` is `true` and you use `ask_user_questions`:** ask 1-3 questions per call. Every question needs stable lowercase `id`. Keep labels short (3-5 words). In **`complex`** mode, multi-choice questions MUST offer **3 or 4 concrete, researched options** plus **"Other — let me discuss"**; options must be grounded in the investigation, not placeholders. In **`simple`** mode, 2 options is fine. Binary depth-check/wrap-up gates are exempt. Wait for each tool result before the next round.
 
 **If `{{structuredQuestionsAvailable}}` is `false`:** ask questions in plain text. Keep each round to 1–3 focused questions.
 
-After each round, investigate only new unknowns, then ask the next round.
+After each round, resolve only new unknowns from context (read a specific file only if one is needed), then ask the next round.
 
 ### Round cadence
 
@@ -105,7 +105,7 @@ Once the user confirms depth:
 
 1. Use the **Project** output template (inlined above).
 2. Call `gsd_summary_save` with `artifact_type: "PROJECT"` and full project markdown as `content`; omit `milestone_id`. The tool persists the DB-backed PROJECT artifact and renders `.gsd/PROJECT.md`. Preserve the user's terms and framing.
-3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. Downstream stages read this line.
+3. The `## Project Shape` section MUST contain `**Complexity:** simple` or `**Complexity:** complex` (matching the verdict you announced) plus a one-line `**Why:**` rationale. For browser-facing projects, also include `**Web stack:**` (framework and expected browser/Playwright UAT approach). Downstream stages read these lines.
 4. The `## Capability Contract` section MUST reference `.gsd/REQUIREMENTS.md` — that file does not yet exist; the next stage (`discuss-requirements`) will produce it.
 5. The `## Milestone Sequence` MUST list at least M001 with title and one-liner. Subsequent milestones may be listed as known intents; they will be elaborated in their own discuss-milestone stages.
 6. Do NOT use `artifact_type: "CONTEXT"` and do NOT pass `milestone_id: "PROJECT"`; that creates a fake milestone named PROJECT.

package/src/resources/extensions/gsd/prompts/guided-discuss-requirements.md

@@ -34,8 +34,7 @@ Before your first action, print this banner verbatim in chat:
 
 ### Before your first question round
 
-Before questioning, investigate enough to avoid assumption-driven requirements:
-- Scout existing capabilities; already-built work is `Validated` or `Active`.
+Ground your requirements in **PROJECT.md, any existing REQUIREMENTS.md, and the Preparation Context snapshot** — those are authoritative for what already exists (already-built work is `Validated` or `Active`). **Do not survey the codebase**; read a specific file only when a requirement's scope genuinely hinges on it.
 - Cross-check milestone sequence; every milestone needs at least one owned Active requirement.
 - Use `resolve_library` / `get_library_docs` for libraries that imply capabilities.
 - Identify domain table-stakes only when PROJECT.md confidence is low.

package/src/resources/extensions/gsd/prompts/guided-discuss-slice.md

@@ -13,12 +13,11 @@ Do **not** center the discussion on tech stack trivia, naming, or speculative ar
 Before the first question round, read `.gsd/PROJECT.md` and look for `## Project Shape` → `**Complexity:**`. Verdicts are **`simple`** or **`complex`**; default to `complex` if missing or unclear.
 
 - **`simple`** — use 1–2 plain-text rounds, then write context. Skip parallel-research investigation.
-- **`complex`** — investigate first, then ask structured 3–4-option questions.
+- **`complex`** — ground in the preloaded context first, then ask structured 3–4-option questions.
 
-### Investigation
+### Grounding
 
-Do enough targeted investigation that questions reflect reality:
-- Scout touched code with `rg`, `find`, or `scout` for broad unfamiliar areas.
+Ground your questions in the **preloaded slice context above** plus any Preparation Context snapshot — those are authoritative. **Do not survey the codebase** with `rg`/`find`/`scout` before asking; read a specific file only when a question's answer genuinely hinges on it.
 - Check roadmap context for predecessor and dependent work.
 - For unfamiliar libraries, prefer `resolve_library` / `get_library_docs` over `search-the-web`.
 - Identify the 3–5 biggest behavioural unknowns where the user's answer materially changes the build.
@@ -31,7 +30,7 @@ Do **not** go deep; stop when you can ask grounded questions.
 
 **Never fabricate or simulate user input.** Never generate fake transcript markers like `[User]`, `[Human]`, or `User:`. Ask one question round, then wait for the user's actual response before continuing.
 
-**If `{{structuredQuestionsAvailable}}` is `true`:** Ask **1–3 questions per round** using `ask_user_questions`. In **`complex`** mode, each multi-choice question MUST present **3 or 4 concrete, researched options** plus final **"Other — let me discuss"** option; options must be grounded in the investigation above (codebase signals, library docs, prior `.gsd/` artifacts), not placeholders. In **`simple`** mode, 2 options is fine. Binary wrap-up gates are exempt. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.**
+**If `{{structuredQuestionsAvailable}}` is `true`:** Ask **1–3 questions per round** using `ask_user_questions`. In **`complex`** mode, each multi-choice question MUST present **3 or 4 concrete, researched options** plus final **"Other — let me discuss"** option; options must be grounded in the preloaded context above (slice context, codebase snapshot, library docs, prior `.gsd/` artifacts), not placeholders. In **`simple`** mode, 2 options is fine. Binary wrap-up gates are exempt. **Call `ask_user_questions` exactly once per turn — never make multiple calls with the same or overlapping questions. Wait for the user's response before asking the next round.**
 **If `{{structuredQuestionsAvailable}}` is `false`:** Ask **1–3 numbered plain-text questions per round**, then wait.
 Focus questions on:
 - **UX and user-facing behaviour** — what users see, click, trigger, or experience.
@@ -39,7 +38,7 @@ Focus questions on:
 - **Scope boundaries** — what is in, out, or deferred.
 - **Feel and experience** — tone, responsiveness, feedback, transitions, and what "done" feels like.
 
-After answers, investigate new unknowns if needed, then ask the next round.
+After answers, resolve new unknowns from context (read a specific file only if needed), then ask the next round.
 
 ### Round cadence
 

package/src/resources/extensions/gsd/prompts/plan-milestone.md

@@ -47,6 +47,8 @@ If milestone research is inlined, trust it and skip redundant exploration. If fi
 
 Narrate decomposition reasoning in complete sentences: grouping, risk order, verification strategy.
 
+**Web apps:** when inlined Web App UAT guidance is present, set milestone `Verification Classes` → UAT to browser-observable acceptance (Playwright spec or `browser_*` checks). Order an early slice to add Playwright smoke scaffolding when the dependency is missing.
+
 Then:
 1. Use the **Roadmap** output template from the inlined context above
 2. {{skillActivation}}
@@ -116,4 +118,4 @@ If external API keys or secrets are required, use the inlined **Secrets Manifest
 
 If no external API keys or secrets are required, skip this step; do not create an empty manifest.
 
-When done, say: "Milestone {{milestoneId}} planned."
+When done, say: "Milestone {{milestoneId}} planned." Say this exactly once — if you already said it in a prior message, do not repeat it.

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

@@ -38,13 +38,14 @@ If slice research is inlined, trust its architectural findings, but verify every
 
 1. If requirements are preloaded, identify owned and supporting Active requirements.
 2. Call `memory_query` with keywords from the slice title and source files.
-3. Read `{{planTemplatePath}}` and `{{taskPlanTemplatePath}}`.
+3. Use the inlined Output Template sections already present in this prompt. Do not read template files from disk.
 4. {{skillActivation}} Record expected executor skills in each task plan's `skills_used` frontmatter.
 5. Define slice verification before tasks. Non-trivial slices need real tests or executable assertions; boundary contracts need contract-exercising checks. Tests must not read .gitignore/gitignored paths such as `.gsd/`, `.planning/`, or `.audits/`.
+   **Web apps:** when inlined Web App UAT guidance is present, follow it — add Playwright smoke scaffolding on the first UI slice if missing, name localhost preconditions, and plan verification commands that match browser-capable UAT modes at slice closeout.
 6. Include Threat Surface (Q3), Requirement Impact (Q4), proof level, observability, integration closure, Failure Modes (Q5), Load Profile (Q6), and Negative Tests (Q7) only where applicable.
 7. Right-size tasks. Simple slices can be one task; split only when context, ownership, or verification boundaries justify it.
 8. Task `verify` commands must be safe, simple commands. Do not use shell pipes, redirects, semicolons, backticks, command substitution, output trimming, or grep regex alternation with `|`. If multiple checks are needed, create a small test file and run it with `node --test` or a package test script, or use separate simple commands joined only with `&&`. For absence checks, verify a pattern does not exist with `! grep -q 'pattern' file` or `! rg -q 'pattern' file`; do not use `grep -c` or `rg -c` to assert zero matches because count commands exit 1 when they find zero matches, and the verification gate treats that as failure.
-9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does.
+9. Each task needs the exact `gsd_plan_slice.tasks[]` shape: `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. `description` should contain the Why / Do / Done-when narrative. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even when there is only one path (for example, `"inputs": ["src/index.ts"]`, never `"inputs": "src/index.ts"`). Use paths relative to `{{workingDirectory}}`; do not put absolute paths to the original checkout or any directory outside `{{workingDirectory}}` in `files`, `inputs`, `expectedOutput`, or verification commands. **`expectedOutput` must only list files the task actually creates or overwrites on disk.** Do NOT include files the task merely reads, verifies, tests, or describes — those belong in `inputs`, `verify`, `description`, or slice success criteria. If a task is a pure verification or test task that produces no new files, `expectedOutput` must be `[]`; if it writes a test-result log or assertion output file, list only that concrete file path. A file that does not yet exist on disk and is needed as an `input` must be produced by an earlier task's `expectedOutput` — if no prior task creates it, add a task before this one that does. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
 10. Persist with `gsd_plan_slice` using `milestoneId`, `sliceId`, `goal`, optional `successCriteria`/`proofLevel`/`integrationClosure`/`observabilityImpact`, and `tasks`. `gsd_plan_slice` handles task persistence transactionally and renders `{{outputPath}}` plus task plans; do not call `gsd_plan_task`. The DB-backed tool is the canonical write path. Do **not** rely on direct `PLAN.md` writes as the source of truth.
 11. Self-audit before finishing: goal/demo closure, requirement coverage, deliverable coverage audit (cross-check every file listed in CONTEXT.md `## Scope` / `### In Scope` against task `files` or `expectedOutput`), locked decisions, concrete paths, dependency order, wiring, scope size, proof truthfulness, feature completeness, and quality gates. Quality gates: non-trivial slices/tasks include specific Q3-Q7 coverage where applicable.
 12. If planning creates structural decisions, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.
@@ -56,4 +57,4 @@ The slice directory already exists. Do not mkdir.
 
 **You MUST call `gsd_plan_slice` to persist planning state before finishing, unless the stale-path safety rule above stops the unit before safe planning can occur.**
 
-When done, say: "Slice {{sliceId}} planned."
+When done, say: "Slice {{sliceId}} planned." Say this exactly once — if you already said it in a prior message, do not repeat it.

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

@@ -37,4 +37,4 @@ You are executing a GSD quick task — a lightweight, focused unit of work outsi
 - <what was tested/verified>
 ```
 
-When done, say: "Quick task {{taskNum}} complete."
+When done, say: "Quick task {{taskNum}} complete." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/src/resources/extensions/gsd/prompts/reassess-roadmap.md

@@ -67,4 +67,4 @@ If `.gsd/REQUIREMENTS.md` exists and requirement ownership or status changed, up
 
 **DB access safety:** Do NOT query `.gsd/gsd.db` directly via `sqlite3` or `node -e require('better-sqlite3')`. Use `gsd_milestone_status` to read current milestone and slice state. All roadmap mutations go through `gsd_reassess_roadmap` — the tool writes to the DB and re-renders ROADMAP.md atomically.
 
-When done, say: "Roadmap reassessed."
+When done, say: "Roadmap reassessed." Say this exactly once — if you already said it in a prior message, do not repeat it.

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

@@ -63,8 +63,9 @@ Then:
    - `{{taskPlanTemplatePath}}`
 2. {{skillActivation}} Record the installed skills you expect executors to use in each task plan's `skills_used` frontmatter.
 3. Define slice-level verification: the objective stopping condition. Plan real test files with real assertions; for simple slices, executable commands are fine.
+   **Web apps:** when inlined Web App UAT guidance is present, follow it for Playwright scaffolding and browser-capable verification commands.
 4. For non-trivial slices, plan observability / proof level / integration closure, threat surface, and requirement impact. Omit entirely for simple slices.
-5. Decompose the slice into tasks that fit one context window each. Every task passed to `gsd_plan_slice` must use the exact keys `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. Put Why / Do / Done-when detail in `description`. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even for one path (for example, `"expectedOutput": ["src/index.ts"]`, never `"expectedOutput": "src/index.ts"`). `expectedOutput` is path-only: list only files the task creates or overwrites, and use `[]` for pure verification tasks.
+5. Decompose the slice into tasks that fit one context window each. Every task passed to `gsd_plan_slice` must use the exact keys `taskId`, `title`, `description`, `estimate`, `files`, `verify`, `inputs`, `expectedOutput`, and optional `observabilityImpact`. Put Why / Do / Done-when detail in `description`. `files`, `inputs`, and `expectedOutput` must be JSON arrays of strings, even for one path (for example, `"expectedOutput": ["src/index.ts"]`, never `"expectedOutput": "src/index.ts"`). `expectedOutput` is path-only: list only files the task creates or overwrites, and use `[]` for pure verification tasks. Never list GSD planning artifacts — anything under `.gsd/`, `.planning/`, or `.audits/`, or artifact names like `M001-CONTEXT.md` / `S01-PLAN.md` — in `inputs`, `files`, or `expectedOutput`: their content is preloaded as context, and they are written by workflow tools, not by tasks.
 6. **Persist planning state through `gsd_plan_slice`.** Call it with the full payload. The tool writes to the DB and renders `{{outputPath}}` and `{{slicePath}}/tasks/T##-PLAN.md` automatically. Do NOT rely on direct `PLAN.md` writes.
 7. **Self-audit the plan.** If every task were completed exactly as written, the slice goal/demo should be true. Every must-have maps to a task. Inputs and Expected Output are backtick-wrapped file paths.
 8. If refinement produced structural decisions that diverge from the sketch, call `gsd_decision_save` for each; the tool persists the decision and regenerates `.gsd/DECISIONS.md`.
@@ -76,4 +77,4 @@ The slice directory and tasks/ subdirectory already exist. Do NOT mkdir.
 
 **You MUST call `gsd_plan_slice` to persist planning state before finishing.** After success, the pipeline clears the sketch flag on next state derivation; the on-disk PLAN file is the signal.
 
-When done, say: "Slice {{sliceId}} refined."
+When done, say: "Slice {{sliceId}} refined." Say this exactly once — if you already said it in a prior message, do not repeat it.