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

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

@@ -26,6 +26,7 @@ import type {
   AutoSupervisorConfig,
 } from "./preferences-types.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath } from "./preferences.js";
+import { getUnitPhaseChain } from "./unit-registry.js";
 
 // Re-export types so existing consumers of ./preferences-models.js keep working
 export type { GSDPhaseModelConfig, GSDModelConfig, GSDModelConfigV2, ResolvedModelConfig } from "./preferences-types.js";
@@ -49,53 +50,16 @@ export function resolveModelForUnit(unitType: string): string | undefined {
  * (`resolveThinkingLevelForUnit`) so the two never drift (ADR-026).
  */
 export function phaseChainForUnit(unitType: string): GSDModelPhaseKey[] | undefined {
-  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;
 }
 
 /**
@@ -221,8 +185,9 @@ export function resolveThinkingLevelForUnit(unitType: string): GSDThinkingLevel
  */
 export function resolveDefaultSessionModel(
   sessionProvider?: string,
+  basePath?: string,
 ): { provider: string; id: string } | undefined {
-  const prefs = loadEffectiveGSDPreferences(undefined, { availableModelIds: [] });
+  const prefs = loadEffectiveGSDPreferences(basePath, { availableModelIds: [] });
   const models = prefs?.preferences?.models;
   if (!models) return undefined;
 

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

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

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

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

package/src/resources/extensions/gsd/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,8 +36,9 @@ 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.
-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.
+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 `gsd_capture_thought` (MCP-scoped `mcp__...__gsd_capture_thought`), not bare `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.
 15. If the current project state needs refresh, call `gsd_summary_save` with `artifact_type: "PROJECT"` and the full updated project markdown as `content`; omit `milestone_id`. Do not write or edit `.gsd/PROJECT.md` directly.
@@ -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/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.
@@ -50,6 +52,7 @@ You execute. The inlined task plan is authoritative. Verify referenced files and
 
 - If task sections exist for Failure Modes (Q5), Load Profile (Q6), Negative Tests (Q7), or Observability Impact, implement and verify them.
 - Verify must-haves with concrete commands or observable behavior.
+- Run verification commands through `gsd_exec` / Context Mode evidence when workflow MCP tools are presented. Use `gsd_exec_search` before rerunning noisy checks, and `gsd_resume` after compaction or resume. Do not call direct `bash` for final verification evidence in this unit.
 - Run slice-level verification from the slice plan. Final tasks need all checks passing; intermediate tasks should record partial passes.
 - Populate `## Verification Evidence` with `formatEvidenceTable` rows: command, exit code, verdict, duration. If no checks were found, say so.
 - For UI/browser/DOM/user-visible web changes, exercise the real flow and record explicit checks.
@@ -62,7 +65,7 @@ Keep about **{{verificationBudget}}** for verification and summary. If context i
 
 - If the plan is fundamentally invalid, set `blocker_discovered: true` in the summary and explain.
 - For downstream-impacting ambiguity that cannot be resolved from code, plans, or decisions, include an `escalation` object with question, options, recommendation, rationale, and `continueWithDefault`.
-- Capture meaningful architecture/pattern/observability decisions with `capture_thought`; capture non-obvious gotchas or conventions only when they save future investigation.
+- Capture meaningful architecture/pattern/observability decisions with `gsd_capture_thought` (or MCP-scoped `mcp__...__gsd_capture_thought`) when workflow MCP tools are presented; capture non-obvious gotchas or conventions only when they save future investigation.
 - Use the inlined Task Summary template below. Read `{{taskSummaryTemplatePath}}` only if the inlined template is absent or visibly truncated.
 - Call `gsd_task_complete` with camelCase fields `milestoneId`, `sliceId`, `taskId`, `oneLiner`, `narrative`, `verification`, and `verificationEvidence`. Include `blockerDiscovered: true` when a stale-path safety failure or other plan-invalidating blocker prevents execution.
 - The DB-backed tool is the canonical write path. Do **not** manually write `{{taskSummaryPath}}` or edit PLAN.md checkboxes; the tool renders the summary and updates state.
@@ -74,4 +77,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-project.md

@@ -36,6 +36,8 @@ 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
 
 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.
@@ -103,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/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

@@ -41,10 +41,11 @@ If slice research is inlined, trust its architectural findings, but verify every
 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.

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

@@ -34,8 +34,8 @@ Consider these captures when rewriting the remaining tasks — they represent th
 
 1. Use the inlined blocker summary excerpt first. Read the full blocker task summary only if the excerpt is absent, marked truncated, or lacks the specific blocker evidence needed to replan.
 2. Analyze the remaining `[ ]` tasks in the slice plan. Determine which are still valid, which need modification, and which should be replaced.
-3. **Persist replan state through `gsd_replan_slice`.** Call it with: `milestoneId`, `sliceId`, `blockerTaskId`, `blockerDescription`, `whatChanged`, `updatedTasks` (array of task objects with taskId, title, description, estimate, files, verify, inputs, expectedOutput), `removedTaskIds` (array of task ID strings). The tool structurally enforces preservation of completed tasks, writes replan history to the DB, re-renders `{{planPath}}`, and renders `{{replanPath}}`. Preserve or update the Threat Surface and Requirement Impact sections if the replan changes the slice's security posture or requirement coverage.
+3. **Persist replan state through `gsd_replan_slice`.** Call it with: `milestoneId`, `sliceId`, `blockerTaskId`, `blockerDescription`, `whatChanged`, `updatedTasks` (array of task objects with taskId, title, description, estimate, files, verify, inputs, expectedOutput), `removedTaskIds` (array of task ID strings). 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. The tool structurally enforces preservation of completed tasks, writes replan history to the DB, re-renders `{{planPath}}`, and renders `{{replanPath}}`. Preserve or update the Threat Surface and Requirement Impact sections if the replan changes the slice's security posture or requirement coverage.
 4. If any incomplete task had a `T0x-PLAN.md`, remove or rewrite it to match the new task description.
 5. Do not commit manually — the system auto-commits your changes after this unit completes.
 
-When done, say: "Slice {{sliceId}} replanned."
+When done, say: "Slice {{sliceId}} replanned." Say this exactly once — if you already said it in a prior message, do not repeat it.

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

@@ -46,4 +46,4 @@ Then research the codebase and relevant technologies. Narrate key findings and s
 
 **You MUST call `gsd_summary_save` with the research content before finishing.**
 
-When done, say: "Milestone {{milestoneId}} researched."
+When done, say: "Milestone {{milestoneId}} researched." Say this exactly once — if you already said it in a prior message, do not repeat it.

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

@@ -55,4 +55,4 @@ The slice directory already exists at `{{slicePath}}/`. Do NOT mkdir.
 
 **You MUST call `gsd_summary_save` with the research content before finishing.**
 
-When done, say: "Slice {{sliceId}} researched."
+When done, say: "Slice {{sliceId}} researched." Say this exactly once — if you already said it in a prior message, do not repeat it.