@opengsd/gsd-pi 1.1.1-dev.b2556262 → 1.2.0-dev.4813ead6

package/src/resources/extensions/gsd/native-git-bridge.ts

@@ -13,6 +13,7 @@ import { GSDError, GSD_GIT_ERROR } from "./errors.js";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { getErrorMessage } from "./error-utils.js";
 import { isInfrastructureError } from "./auto/infra-errors.js";
+import { debugCount } from "./debug-logger.js";
 
 // Issue #453: keep auto-mode bookkeeping on the stable git CLI path unless a
 // caller explicitly opts into the native helper.
@@ -140,6 +141,8 @@ function loadNative(): typeof nativeModule {
 
 /** Run a git command via execFileSync. Returns trimmed stdout. */
 function gitExec(basePath: string, args: string[], allowFailure = false): string {
+  // Counts git CLI shell-outs only (native libgit2 paths bypass this helper).
+  debugCount("gitInvocations");
   try {
     return execFileSync("git", args, {
       cwd: basePath,
@@ -169,6 +172,8 @@ function execGitFileSyncWithRetry(
   args: string[],
   options: Partial<ExecFileSyncOptionsWithStringEncoding>,
 ): string {
+  // Counts git CLI shell-outs only (native libgit2 paths bypass this helper).
+  debugCount("gitInvocations");
   try {
     return execFileSync("git", args, {
       cwd: basePath,
@@ -180,6 +185,8 @@ function execGitFileSyncWithRetry(
   } catch (err) {
     if (!isRetryableGitError(err)) throw err;
     sleepSync(GIT_RETRY_DELAY_MS);
+    // Retry is a second physical shell-out — count it too.
+    debugCount("gitInvocations");
     return execFileSync("git", args, {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
@@ -192,6 +199,8 @@ function execGitFileSyncWithRetry(
 
 /** Run a git command via execFileSync. Returns trimmed stdout. */
 function gitFileExec(basePath: string, args: string[], allowFailure = false): string {
+  // Counts git CLI shell-outs only (native libgit2 paths bypass this helper).
+  debugCount("gitInvocations");
   try {
     return execFileSync("git", args, {
       cwd: basePath,
@@ -1092,6 +1101,45 @@ export function nativeMergeSquash(basePath: string, branch: string): GitMergeRes
   }
 }
 
+/**
+ * Regular (non-squash) merge a branch (stages changes, does NOT commit).
+ * Uses --no-ff to ensure a proper merge commit and --no-commit so the caller
+ * can supply a custom commit message via nativeCommit.
+ * Respects the user's global git merge.ff config; --no-ff is additive here.
+ */
+export function nativeMergeRegular(basePath: string, branch: string): GitMergeResult {
+  try {
+    execFileSync("git", ["merge", "--no-ff", "--no-commit", branch], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    });
+    return { success: true, conflicts: [] };
+  } catch (err: unknown) {
+    const stderr =
+      err instanceof Error ? (err as Error & { stderr?: string }).stderr ?? err.message : String(err);
+    if (
+      stderr.includes("local changes would be overwritten") ||
+      stderr.includes("not possible because you have unmerged files") ||
+      stderr.includes("overwritten by merge")
+    ) {
+      const dirtyFiles = stderr
+        .split("\n")
+        .filter((line) => line.startsWith("\t"))
+        .map((line) => line.trim())
+        .filter(Boolean);
+      return { success: false, conflicts: ["__dirty_working_tree__"], dirtyFiles };
+    }
+    const conflictOutput = gitExec(basePath, ["diff", "--name-only", "--diff-filter=U"], true);
+    const conflicts = conflictOutput ? conflictOutput.split("\n").filter(Boolean) : [];
+    if (conflicts.length > 0) {
+      return { success: false, conflicts };
+    }
+    throw err;
+  }
+}
+
 /**
  * Abort an in-progress merge.
  * Native: libgit2 reset + cleanup.

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

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

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

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

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

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

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

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

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

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

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

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

package/src/resources/extensions/gsd/prompts/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.

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