@opengsd/gsd-pi 1.0.2-dev.e9a1b49 → 1.0.2-dev.fb7ddf1

package/src/resources/extensions/gsd/mcp-filter.ts

@@ -6,37 +6,84 @@ import { resolveModelMcpConfig } from "./preferences-mcp.js";
 
 interface McpJsonFile {
   mcpServers?: Record<string, unknown>;
+  servers?: Record<string, unknown>;
 }
 
 interface ClaudeSettingsFile {
   mcpServers?: Record<string, unknown>;
 }
 
-export function discoverMcpServerNames(projectDir: string): string[] {
+interface DiscoveredMcpServer {
+  name: string;
+  config: unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function readJsonFile(path: string, ignoreParseErrors = false): unknown | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf-8")) as unknown;
+  } catch (err) {
+    if (!ignoreParseErrors) throw err;
+    return undefined;
+  }
+}
+
+function collectServerEntries(servers: unknown): DiscoveredMcpServer[] {
+  if (!isRecord(servers)) return [];
+  return Object.entries(servers).map(([name, config]) => ({ name, config }));
+}
+
+export function discoverMcpServers(projectDir: string): DiscoveredMcpServer[] {
   const mcpJsonPath = resolve(projectDir, ".mcp.json");
   const settingsPath = resolve(projectDir, ".claude", "settings.json");
 
-  let mcpJsonServers: string[] = [];
-  if (existsSync(mcpJsonPath)) {
-    const raw = readFileSync(mcpJsonPath, "utf-8");
-    const parsed = JSON.parse(raw) as McpJsonFile;
-    mcpJsonServers = Object.keys(parsed.mcpServers ?? {});
+  const mcpJson = readJsonFile(mcpJsonPath) as McpJsonFile | undefined;
+  const settings = readJsonFile(settingsPath, true) as ClaudeSettingsFile | undefined;
+
+  const seen = new Set<string>();
+  const discovered: DiscoveredMcpServer[] = [];
+  for (const entry of [
+    ...collectServerEntries(mcpJson?.mcpServers),
+    ...collectServerEntries(mcpJson?.servers),
+    ...collectServerEntries(settings?.mcpServers),
+  ]) {
+    if (seen.has(entry.name)) continue;
+    seen.add(entry.name);
+    discovered.push(entry);
   }
+  return discovered;
+}
 
-  let settingsServers: string[] = [];
-  if (existsSync(settingsPath)) {
-    try {
-      const raw = readFileSync(settingsPath, "utf-8");
-      const parsed = JSON.parse(raw) as ClaudeSettingsFile;
-      if (parsed.mcpServers) {
-        settingsServers = Object.keys(parsed.mcpServers);
-      }
-    } catch {
-      // settings.json parse errors are silently ignored
+function isWorkflowMcpServerConfig(config: unknown): boolean {
+  if (!isRecord(config)) return false;
+  const env = config.env;
+  if (isRecord(env)) {
+    if (
+      typeof env.GSD_WORKFLOW_PROJECT_ROOT === "string"
+      || typeof env.GSD_WORKFLOW_EXECUTORS_MODULE === "string"
+      || typeof env.GSD_WORKFLOW_WRITE_GATE_MODULE === "string"
+      || typeof env.GSD_PERSIST_WRITE_GATE_STATE === "string"
+    ) {
+      return true;
     }
   }
 
-  return [...new Set([...mcpJsonServers, ...settingsServers])];
+  const command = typeof config.command === "string" ? config.command : "";
+  if (command.includes("gsd-mcp-server")) return true;
+  const args = Array.isArray(config.args) ? config.args.filter((arg): arg is string => typeof arg === "string") : [];
+  return args.some((arg) => arg.includes("gsd-mcp-server") || arg.includes("packages/mcp-server"));
+}
+
+export function discoverWorkflowMcpServerName(projectDir: string): string | undefined {
+  return discoverMcpServers(projectDir).find((server) => isWorkflowMcpServerConfig(server.config))?.name;
+}
+
+export function discoverMcpServerNames(projectDir: string): string[] {
+  return discoverMcpServers(projectDir).map((server) => server.name);
 }
 
 export function computeMcpDisallowedTools(

package/src/resources/extensions/gsd/mcp-project-config.ts

@@ -21,6 +21,11 @@ export interface EnsureProjectWorkflowMcpConfigResult {
   status: "created" | "updated" | "unchanged";
 }
 
+interface ProjectWorkflowMcpServerSpec {
+  serverName: string;
+  server: ProjectMcpServerConfig;
+}
+
 interface McpConfigFile {
   mcpServers?: Record<string, ProjectMcpServerConfig>;
   servers?: Record<string, ProjectMcpServerConfig>;
@@ -48,6 +53,13 @@ export function buildProjectWorkflowMcpServerConfig(
   projectRoot: string,
   env: NodeJS.ProcessEnv = process.env,
 ): ProjectMcpServerConfig {
+  return buildProjectWorkflowMcpServerSpec(projectRoot, env).server;
+}
+
+function buildProjectWorkflowMcpServerSpec(
+  projectRoot: string,
+  env: NodeJS.ProcessEnv = process.env,
+): ProjectWorkflowMcpServerSpec {
   const resolvedProjectRoot = resolve(projectRoot);
   const gsdCliPath = resolveBundledGsdCliPath(env);
   const launch = detectWorkflowMcpLaunchConfig(resolvedProjectRoot, {
@@ -62,10 +74,13 @@ export function buildProjectWorkflowMcpServerConfig(
   }
 
   return {
-    command: launch.command,
-    ...(launch.args && launch.args.length > 0 ? { args: launch.args } : {}),
-    ...(launch.cwd ? { cwd: launch.cwd } : {}),
-    ...(launch.env ? { env: launch.env } : {}),
+    serverName: launch.name || GSD_WORKFLOW_MCP_SERVER_NAME,
+    server: {
+      command: launch.command,
+      ...(launch.args && launch.args.length > 0 ? { args: launch.args } : {}),
+      ...(launch.cwd ? { cwd: launch.cwd } : {}),
+      ...(launch.env ? { env: launch.env } : {}),
+    },
   };
 }
 
@@ -92,23 +107,23 @@ export function ensureProjectWorkflowMcpConfig(
 
   const configPath = resolve(resolvedProjectRoot, ".mcp.json");
   const existing = readExistingConfig(configPath);
-  const desiredServer = buildProjectWorkflowMcpServerConfig(resolvedProjectRoot, env);
+  const { serverName, server: desiredServer } = buildProjectWorkflowMcpServerSpec(resolvedProjectRoot, env);
   const previousServers = existing.mcpServers ?? {};
   const nextServers = {
     ...previousServers,
-    [GSD_WORKFLOW_MCP_SERVER_NAME]: desiredServer,
+    [serverName]: desiredServer,
   };
 
   const alreadyPresent = existsSync(configPath);
   const unchanged =
-    JSON.stringify(previousServers[GSD_WORKFLOW_MCP_SERVER_NAME] ?? null)
+    JSON.stringify(previousServers[serverName] ?? null)
       === JSON.stringify(desiredServer)
     && existing.mcpServers !== undefined;
 
   if (unchanged) {
     return {
       configPath,
-      serverName: GSD_WORKFLOW_MCP_SERVER_NAME,
+      serverName,
       status: "unchanged",
     };
   }
@@ -122,7 +137,7 @@ export function ensureProjectWorkflowMcpConfig(
 
   return {
     configPath,
-    serverName: GSD_WORKFLOW_MCP_SERVER_NAME,
+    serverName,
     status: alreadyPresent ? "updated" : "created",
   };
 }

package/src/resources/extensions/gsd/migration-auto-check.ts

@@ -6,6 +6,7 @@ import {
   getMilestoneSlices,
   getSliceTasks,
   isDbAvailable,
+  refreshOpenDatabaseFromDisk,
 } from "./gsd-db.js";
 import { parsePlan, parseRoadmap } from "./parsers-legacy.js";
 import {
@@ -100,6 +101,11 @@ export async function checkMarkdownHierarchyAgainstDb(
     throw new Error(`failed to open or create the GSD database at ${basePath}`);
   }
 
+  // The markdown projections may have just been written by a workflow/MCP
+  // server in another process. Reopen before comparing so startup does not
+  // warn from a stale long-lived SQLite handle.
+  refreshOpenDatabaseFromDisk();
+
   const beforeDb = countDbHierarchy();
   if (sameCounts(markdown, beforeDb)) {
     return { action: "none", reason: "in-sync", markdown, beforeDb, afterDb: beforeDb };

package/src/resources/extensions/gsd/milestone-actions.ts

@@ -162,6 +162,8 @@ export function discardMilestone(basePath: string, milestoneId: string): boolean
     } catch (err) {
       logWarning("engine", `discardMilestone DB cleanup failed for ${milestoneId}: ${(err as Error).message}`);
     }
+  } else {
+    logWarning("engine", `discardMilestone DB cleanup skipped for ${milestoneId}: database unavailable`);
   }
 
   invalidateAllCaches();

package/src/resources/extensions/gsd/milestone-reopen-events.ts

@@ -0,0 +1,28 @@
+import { join } from "node:path";
+
+import { gsdRoot } from "./paths.js";
+import { readEvents } from "./workflow-events.js";
+
+export function latestExplicitReopenAt(basePath: string, milestoneId: string): string | null {
+  const root = gsdRoot(basePath);
+  const candidates = [
+    join(root, "event-log.jsonl"),
+    join(root, `event-log-${milestoneId}.jsonl.archived`),
+  ];
+
+  let latest: string | null = null;
+  for (const file of candidates) {
+    for (const event of readEvents(file)) {
+      const eventMilestoneId = (event.params as { milestoneId?: unknown }).milestoneId;
+      if (event.cmd !== "reopen-milestone" || eventMilestoneId !== milestoneId) continue;
+      if (!latest || event.ts > latest) latest = event.ts;
+    }
+  }
+  return latest;
+}
+
+export function isAfter(value: string | null | undefined, cutoff: string | null): boolean {
+  if (!cutoff) return true;
+  if (!value) return true;
+  return Date.parse(value) > Date.parse(cutoff);
+}

package/src/resources/extensions/gsd/notification-overlay.ts

@@ -15,7 +15,7 @@ import {
 import { formattedShortcutPair } from "./shortcut-defs.js";
 import {
   padRightVisible,
-  renderFrame,
+  renderDialogFrame,
   renderKeyHints,
   rightAlign,
   wrapVisibleText,
@@ -200,13 +200,20 @@ export class GSDNotificationOverlay {
       availableRows,
       Math.max(1, Math.floor((terminalRows * OVERLAY_MAX_HEIGHT_PERCENT) / 100)),
     );
-    const maxVisibleRows = Math.max(5, overlayRows - 2);
+    const maxVisibleRows = Math.max(5, overlayRows - 4);
     const visibleContentRows = Math.min(content.length, maxVisibleRows);
     const maxScroll = Math.max(0, content.length - visibleContentRows);
     this.scrollOffset = Math.min(this.scrollOffset, maxScroll);
     const visibleContent = content.slice(this.scrollOffset, this.scrollOffset + visibleContentRows);
-
-    const lines = renderFrame(this.theme, visibleContent, width);
+    const footer = renderKeyHints(
+      this.theme,
+      ["↑/↓ scroll", "f filter", "c clear", `Esc/${formattedShortcutPair("notifications")} close`],
+      Math.max(1, width - 4),
+    );
+    const lines = renderDialogFrame(this.theme, "Notifications", visibleContent, width, {
+      footer,
+      scroll: { offset: this.scrollOffset, visibleRows: visibleContentRows, totalRows: content.length },
+    });
 
     this.cachedWidth = width;
     this.cachedLines = lines;
@@ -256,8 +263,6 @@ export class GSDNotificationOverlay {
     const blank = () => row("");
     const hr = () => row(th.fg("dim", "─".repeat(contentWidth)));
 
-    // Header
-    const title = th.fg("accent", th.bold("Notifications"));
     const filterLabel = this.filter === "all"
       ? th.fg("dim", "all")
       : th.fg(
@@ -269,15 +274,11 @@ export class GSDNotificationOverlay {
       );
     const count = `${this.filteredEntries.length} entries`;
     lines.push(row(rightAlign(
-      `${title}  ${th.fg("dim", "filter:")} ${filterLabel}`,
+      `${th.fg("dim", "filter:")} ${filterLabel}`,
       th.fg("dim", count),
       contentWidth,
     )));
     lines.push(hr());
-
-    // Controls
-    const closeShortcut = formattedShortcutPair("notifications");
-    lines.push(row(renderKeyHints(th, ["↑/↓ scroll", "f filter", "c clear", `Esc/${closeShortcut} close`], contentWidth)));
     lines.push(blank());
 
     // Entries

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

@@ -154,12 +154,13 @@ export async function mergeCompletedMilestone(
   // to read it from. Only use the worktree path when git actually knows
   // about it (`getAutoWorktreePath` returns non-null). When the directory
   // exists on disk but isn't a registered git worktree (e.g. a stale
-  // session-status marker dir), fall back to the project root and let the
-  // standalone's mode detection pick branch-mode or skipped — using the
-  // un-registered dir as `worktreeBasePath` would cause `getCurrentBranch`
-  // to fail with a "Worktree HEAD diverged" error.
+  // session-status marker dir), recover through branch mode from the project
+  // root. Letting worktree-mode run from the project root can auto-commit
+  // overlapping root files to the integration branch before the squash merge,
+  // creating a synthetic conflict.
   const registeredWtPath = getAutoWorktreePath(basePath, milestoneId);
   const worktreeBasePath = registeredWtPath ?? basePath;
+  const isolationModeOverride = registeredWtPath ? undefined : "branch";
 
   let result: MergeStandaloneResult;
   try {
@@ -167,6 +168,7 @@ export async function mergeCompletedMilestone(
       originalBasePath: basePath,
       worktreeBasePath,
       milestoneId,
+      isolationModeOverride,
       // Parallel context never runs with degraded isolation — workers only
       // exist when isolation succeeded. Pass `false` explicitly so the
       // standalone's degraded-skip branch is not reached.

package/src/resources/extensions/gsd/parallel-monitor-overlay.ts

@@ -13,6 +13,7 @@ import { formattedShortcutPair } from "./shortcut-defs.js";
 import { resolveGsdPathContract } from "./paths.js";
 import {
   renderBar,
+  renderDialogFrame,
   renderKeyHints,
   renderProgressBar,
   safeLine,
@@ -378,19 +379,18 @@ export class ParallelMonitorOverlay {
     const t = this.theme;
     const lines: string[] = [];
     const w = Math.max(1, width);
+    const contentWidth = Math.max(1, w - 4);
 
-    // Header
     const totalCost = this.workers.reduce((s, wk) => s + wk.cost, 0);
     const aliveCount = this.workers.filter((wk) => wk.alive).length;
     const now = new Date().toLocaleTimeString();
 
-    lines.push(t.bold(t.fg("accent", " GSD Parallel Monitor ")));
     lines.push(
       t.fg("muted", `  ${now}  │  ${aliveCount}/${this.workers.length} alive  │  Total: `) +
       t.bold(`$${totalCost.toFixed(2)}`) +
       t.fg("muted", "  │  5s refresh"),
     );
-    lines.push(renderBar(t, w));
+    lines.push(renderBar(t, contentWidth));
 
     if (this.workers.length === 0) {
       lines.push("");
@@ -444,7 +444,7 @@ export class ParallelMonitorOverlay {
           lines.push(`     ${t.fg("muted", "slices")}  ${chips.join("  ")}`);
 
           // Task progress bar
-          const barWidth = Math.max(6, Math.min(25, w - 32));
+          const barWidth = Math.max(6, Math.min(25, contentWidth - 32));
           const bar = renderProgressBar(t, wk.doneTasks, wk.totalTasks, barWidth, {
             filledChar: "█",
             emptyChar: "░",
@@ -466,7 +466,7 @@ export class ParallelMonitorOverlay {
 
     // Event feed
     lines.push("");
-    lines.push(renderBar(t, w));
+    lines.push(renderBar(t, contentWidth));
     lines.push(`  ${t.bold("Recent Events")}`);
 
     if (this.events.length === 0) {
@@ -478,7 +478,6 @@ export class ParallelMonitorOverlay {
       }
     }
 
-    // Footer
     lines.push("");
     const allDone = this.workers.length > 0 && this.workers.every((wk) => !wk.alive);
     if (allDone) {
@@ -491,17 +490,22 @@ export class ParallelMonitorOverlay {
       }
       lines.push(`  ${t.bold("Total: $" + this.workers.reduce((s, wk) => s + wk.cost, 0).toFixed(2))}`);
     }
-    lines.push(renderKeyHints(t, [`ESC/q/${formattedShortcutPair("parallel")} close`, "↑↓ scroll"], w));
 
     // Apply scroll — use terminal rows as height estimate
     const termHeight = process.stdout.rows || 40;
-    const maxScroll = Math.max(0, lines.length - termHeight);
+    const maxBodyRows = Math.max(1, Math.min(lines.length, termHeight - 12));
+    const maxScroll = Math.max(0, lines.length - maxBodyRows);
     this.scrollOffset = Math.min(Math.max(this.scrollOffset, 0), maxScroll);
     const visible = lines
-      .slice(this.scrollOffset, this.scrollOffset + termHeight)
-      .map((line) => safeLine(line, w));
-    this.cachedLines = visible;
+      .slice(this.scrollOffset, this.scrollOffset + maxBodyRows)
+      .map((line) => safeLine(line, contentWidth));
+    const footer = renderKeyHints(t, [`ESC/q/${formattedShortcutPair("parallel")} close`, "↑↓ scroll"], contentWidth);
+
+    this.cachedLines = renderDialogFrame(t, "GSD Parallel Monitor", visible, w, {
+      footer,
+      scroll: { offset: this.scrollOffset, visibleRows: maxBodyRows, totalRows: lines.length },
+    });
     this.cachedWidth = width;
-    return visible;
+    return this.cachedLines;
   }
 }

package/src/resources/extensions/gsd/post-execution-checks.ts

@@ -318,10 +318,13 @@ export function checkImportResolution(
     const imports = extractRelativeImports(source);
 
     for (const { importPath, lineNum } of imports) {
-      // React Router generated +types modules may not exist on disk during
-      // post-exec checks (generated during framework build). Don't block task
-      // completion on these imports.
-      if (/^\.{1,2}\/\+types\//.test(importPath)) {
+      // Framework-generated type modules may not exist on disk during post-exec
+      // checks (typically generated during framework builds/typegen). Don't
+      // block task completion on these imports.
+      if (
+        /^\.{1,2}\/\+types\//.test(importPath) ||
+        /^(?:\.{1,2}\/)+(?:[^/]+\/)*\$types(?:$|\/)/.test(importPath)
+      ) {
         continue;
       }
 

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

@@ -23,10 +23,17 @@ import { validatePreferences } from "./preferences-validation.js";
 export type { GSDSkillRule, SkillDiscoveryMode, SkillResolution, SkillResolutionReport } from "./preferences-types.js";
 
 /**
- * Known skill directories, in priority order.
- * GSD bundled skills live in ~/.gsd/agent/skills/ and win name collisions.
- * User-global and project-local ecosystem directories remain available as
- * read-only discovery sources, followed by Claude Code compatibility paths.
+ * Known skill directories for **preference reference resolution** (bare skill names).
+ *
+ * Search order (first match wins):
+ * 1. ~/.gsd/agent/skills/ (GSD bundled)
+ * 2. ~/.agents/skills/ (ecosystem global)
+ * 3. .agents/skills/ (project ecosystem)
+ * 4. ~/.claude/skills/ and .claude/skills/ (Claude Code compatibility)
+ *
+ * Note: the ResourceLoader catalog uses PackageManager precedence instead —
+ * project `.gsd/skills` and `.agents/skills` can override bundled GSD skills
+ * on name collision. See docs/dev/what-is-pi/09-the-customization-stack.md.
  */
 export function getSkillSearchDirs(cwd: string): Array<{ dir: string; method: SkillResolution["method"] }> {
   const dirs: Array<{ dir: string; method: SkillResolution["method"] }> = [

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

@@ -570,9 +570,14 @@ function mergePreDispatchHooks(
 
 // ─── System Prompt Rendering ──────────────────────────────────────────────────
 
-export function renderPreferencesForSystemPrompt(preferences: GSDPreferences, resolutions?: Map<string, SkillResolution>): string {
+export function renderPreferencesForSystemPrompt(
+  preferences: GSDPreferences,
+  resolutions?: Map<string, SkillResolution>,
+  options?: { includeResolvedPaths?: boolean },
+): string {
   const validated = validatePreferences(preferences);
   const lines: string[] = ["## GSD Skill Preferences"];
+  const includeResolvedPaths = options?.includeResolvedPaths ?? true;
 
   if (validated.errors.length > 0) {
     lines.push("- Validation: some preference values were ignored because they were invalid.");
@@ -589,7 +594,17 @@ export function renderPreferencesForSystemPrompt(preferences: GSDPreferences, re
     "- Current user instructions still override these defaults.",
   );
 
-  const fmt = (ref: string) => resolutions ? formatSkillRef(ref, resolutions) : ref;
+  const fmt = (ref: string) => {
+    if (!resolutions) return ref;
+    if (!includeResolvedPaths) {
+      const resolution = resolutions.get(ref);
+      if (!resolution || resolution.method === "unresolved") {
+        return `${ref} (⚠ not found — check skill name or path)`;
+      }
+      return ref;
+    }
+    return formatSkillRef(ref, resolutions);
+  };
 
   if (preferences.always_use_skills && preferences.always_use_skills.length > 0) {
     lines.push("- Always use these skills when relevant:");

package/src/resources/extensions/gsd/prompt-loader.ts

@@ -22,6 +22,7 @@ import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { logWarning } from "./workflow-logger.js";
 import { gsdHome } from "./gsd-home.js";
+import { chooseVisionAskVariant } from "./vision-ask.js";
 
 type ExistsFn = (path: string) => boolean;
 
@@ -184,6 +185,7 @@ export function loadPrompt(name: string, vars: Record<string, string> = {}): str
     planTemplatePath: join(getTemplatesDir(), "plan.md"),
     taskPlanTemplatePath: join(getTemplatesDir(), "task-plan.md"),
     taskSummaryTemplatePath: join(getTemplatesDir(), "task-summary.md"),
+    visionAsk: chooseVisionAskVariant(),
     skillActivation: "If a `GSD Skill Preferences` block is present in system context, use it and the `<available_skills>` catalog in your system prompt to decide which skills to load and follow for this unit, without relaxing required verification or artifact rules.",
     ...vars,
   };

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

@@ -1,8 +1,10 @@
 {{preamble}}
 
-Ask: "What's the vision?" once, then use the reply as vision input.
+Ask exactly this once: "{{visionAsk}}" Then use the user's reply as vision input.
 
-**Special handling:** If the **user's** message is status, branch state, clarification, or any other non-project-description, treat it as vision input and proceed instead of repeating "What's the vision?" Do **not** treat the system preamble above (e.g. "New milestone M00X.") as vision input — wait for the user.
+The opener is intentionally variable so GSD feels alive across project starts. Keep it natural, easy to answer, and assistant/developer shaped: plain language, light guidance, no corporate wording, no roleplay.
+
+**Special handling:** If the **user's** message is status, branch state, clarification, or any other non-project-description, treat it as vision input and proceed instead of repeating the opener. Do **not** treat the system preamble above (e.g. "New milestone M00X.") as vision input — wait for the user.
 
 ## Reflection Step
 

package/src/resources/extensions/gsd/prompts/gate-evaluate.md

@@ -35,7 +35,7 @@ You are evaluating **quality gates in parallel** for this slice. Each gate is an
 2. **Wait for all subagents** to complete.
 3. **Verify each gate wrote its result** by checking that `gsd_save_gate_result` was called for each gate ID.
    - Call it **directly** — do **not** use `ToolSearch` (it is not available in GSD).
-   - Inside Claude Code use `mcp__gsd-workflow__gsd_save_gate_result`; otherwise use `gsd_save_gate_result`.
+   - Inside Claude Code use the active MCP-scoped workflow name for `gsd_save_gate_result`; otherwise use `gsd_save_gate_result`.
    - Always pass all required fields (camelCase): `milestoneId`, `sliceId`, `gateId`, `verdict`, `rationale`. Never call with an empty `{}` object.
 4. **Report the batch outcome** — which gates passed, which flagged concerns, and which were omitted as not applicable.
 

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

@@ -4,6 +4,8 @@ Discuss milestone {{milestoneId}} ("{{milestoneTitle}}"). Identify real gray are
 
 **Structured questions available: {{structuredQuestionsAvailable}}**
 
+**Conversation opener:** For the first user-facing question round, if you need a broad starting question, use: "{{visionAsk}}" Pair it with investigation-shaped follow-ups. Keep the tone natural and easy to answer, like an assistant/developer helping the user shape the next piece of work.
+
 {{inlinedTemplates}}
 
 ---

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

@@ -19,9 +19,7 @@ Leave the project ready for the next agent to understand and continue. Artifacts
 
 ## Skills
 
-GSD ships with bundled skills. When the task matches, load the relevant skill file with `read` before starting. Use bare skill names; GSD resolves paths.
-
-{{bundledSkillsTable}}
+GSD ships with bundled skills. Installed skills are listed in `<available_skills>` in your system prompt — load the relevant skill file with `read` using the path shown there before starting matching work. Use bare skill names in preferences; GSD resolves paths.
 
 ## Hard Rules
 
@@ -122,18 +120,7 @@ Templates are in `{{templatesDir}}`.
 
 **Browser verification:** Verify frontend work against a running app. Discovery: `browser_find`/`browser_snapshot_refs`. Action: refs/selectors -> `browser_batch`. Verification: `browser_assert`. Diagnostics: `browser_diff` -> console/network logs -> full inspection as last resort. Retry only with a new hypothesis.
 
-### Anti-patterns — never do these
-
-- Never use `cat` to read a file you might edit; use `read`.
-- Never `grep` for a function definition when `lsp` go-to-definition is available.
-- Never poll servers with `sleep` loops; use `bg_shell wait_for_ready`.
-- Never background with `bash` + `&`; use `bg_shell start`.
-- Never use `bg_shell output` for status; use `digest`.
-- Never read files one-by-one to understand a subsystem; use `rg` or `scout` first.
-- Never guess library APIs; use `get_library_docs`.
-- Never ask the user to run/check/set something you can do.
-- Never await stale async jobs after editing source; cancel then re-run.
-- Never query `.gsd/gsd.db` directly via `sqlite3`, `better-sqlite3`, or `node -e require('better-sqlite3')`; the engine owns a single-writer WAL connection. Use `gsd_milestone_status`, `gsd_journal_query`, or other `gsd_*` tools.
+**Database:** Never query `.gsd/gsd.db` directly via `sqlite3`, `better-sqlite3`, or `node -e require('better-sqlite3')`; the engine owns a single-writer WAL connection. Use `gsd_milestone_status`, `gsd_journal_query`, or other `gsd_*` tools.
 
 ### Ask vs infer
 
@@ -173,8 +160,4 @@ Fix root causes, not symptoms. If applying temporary mitigation, label it and pr
 - When debugging, stay curious. Problems are puzzles. Say what's interesting about the failure before reaching for fixes.
 - After completing a task, give a brief summary and 2-4 numbered next-step options; last option is always "Other". Omit the list for strict output formats.
 
-Good narration: "Three existing handlers follow a middleware pattern - using that instead of a custom wrapper."
-Good narration: "Tests pass. Running slice-level verification."
-Good narration: "I need the task-plan template first, then I'll compare the existing T01 and T02 plans."
-Bad narration: "Reading the file now." / "Let me check this." / "I'll look at the tests next."
-Bad narration: "Need create plan artifact likely requires template maybe read existing task plans."
+Good narration states a decision or finding: "Three handlers follow a middleware pattern - using that instead of a custom wrapper." Bad narration just announces the next call ("Reading the file now.") or emits compressed planner notes ("Need create plan artifact maybe read existing plans.").