gsd-pi 2.82.0 → 3.0.0-dev.8b8d129d7

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -31,6 +31,7 @@ import { resolveWorktreeProjectRoot } from "../worktree-root.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
 import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 import { resolveSkillManifest } from "../skill-manifest.js";
+import { getGuidedUnitContext } from "../guided-unit-context.js";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -423,6 +424,10 @@ export function registerHooks(
   pi: ExtensionAPI,
   ecosystemHandlers: GSDEcosystemBeforeAgentStartHandler[],
 ): void {
+  // ADR-005 Phase 3b: surface pi-ai ProviderSwitchReport via audit, notification, and counter.
+  // Idempotent — only the first registerHooks call installs.
+  void import("../provider-switch-observer.js").then((m) => m.installProviderSwitchObserver());
+
   pi.on("session_start", async (_event, ctx) => {
     const basePath = contextBasePath(ctx);
     initSessionNotifications(ctx);
@@ -480,6 +485,8 @@ export function registerHooks(
     }
     await loadToolApiKeysForSession();
     if (!isAutoActive()) {
+      ctx.ui.setWidget("gsd-progress", undefined);
+      ctx.ui.setWidget("gsd-outcome", undefined);
       const { initHealthWidget } = await import("../health-widget.js");
       initHealthWidget(ctx);
     } else {
@@ -766,7 +773,8 @@ export function registerHooks(
     // subagent dispatch. Closes the b23 bug class where a discuss-milestone
     // turn used the host Edit tool to modify user source files.
     const dash = getAutoRuntimeSnapshot();
-    const activeUnitType = dash.currentUnit?.type;
+    const guidedUnit = getGuidedUnitContext(discussionBasePath);
+    const activeUnitType = dash.currentUnit?.type ?? guidedUnit?.unitType;
     if (activeUnitType) {
       const manifest = resolveManifest(activeUnitType);
       if (manifest) {
@@ -785,7 +793,7 @@ export function registerHooks(
         const planningGuard = shouldBlockPlanningUnit(
           event.toolName,
           planningInput,
-          dash.basePath || discussionBasePath,
+          dash.basePath || guidedUnit?.basePath || discussionBasePath,
           activeUnitType,
           manifest.tools,
           agentClasses,
@@ -799,11 +807,10 @@ export function registerHooks(
     // git.isolation=worktree but auto-mode hasn't created the milestone
     // worktree yet. Without this, writes silently orphan outside git history.
     if (isToolCallEventType("write", event) || isToolCallEventType("edit", event)) {
-      const wtBasePath = resolveWorktreeProjectRoot(dash.basePath ?? discussionBasePath);
       const wtGuard = shouldBlockWorktreeWrite(
         event.toolName,
         event.input.path,
-        wtBasePath,
+        dash.basePath ?? discussionBasePath,
         isAutoActive(),
         dash.currentUnit?.type,
       );

package/src/resources/extensions/gsd/bootstrap/subagent-input.ts

@@ -1,20 +1,32 @@
 export function extractSubagentAgentClasses(input: unknown): string[] {
   if (!input || typeof input !== "object") return [];
 
-  const record = input as Record<string, unknown>;
   const agentClasses: string[] = [];
+  const visited = new WeakSet<object>();
   const addAgentClass = (value: unknown): void => {
-    if (typeof value === "string" && value.trim().length > 0) agentClasses.push(value.trim());
+    if (typeof value !== "string") return;
+    const normalized = value.trim().replace(/\.md$/i, "");
+    if (normalized.length > 0) agentClasses.push(normalized);
   };
-  const addFromItems = (value: unknown): void => {
+
+  const visitItems = (value: unknown): void => {
     if (!Array.isArray(value)) return;
     for (const item of value) {
-      if (item && typeof item === "object") addAgentClass((item as Record<string, unknown>).agent);
+      visit(item);
     }
   };
 
-  addAgentClass(record.agent);
-  addFromItems(record.tasks);
-  addFromItems(record.chain);
+  const visit = (value: unknown): void => {
+    if (!value || typeof value !== "object") return;
+    if (visited.has(value)) return;
+    visited.add(value);
+    const record = value as Record<string, unknown>;
+    addAgentClass(record.agent);
+    visitItems(record.tasks);
+    visitItems(record.chain);
+    visitItems(record.parallel);
+  };
+
+  visit(input);
   return agentClasses;
 }

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -13,6 +13,7 @@ import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffect
 import { resolveModelWithFallbacksForUnit } from "../preferences-models.js";
 import { resolveSkillReference } from "../preferences-skills.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
+import { extractIntroAndRules } from "../knowledge-parser.js";
 import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
@@ -131,9 +132,14 @@ export async function buildBeforeAgentStartResult(
     logWarning("bootstrap", `cmux prompt setup skipped: ${(e as Error).message}`);
   }
 
+  const ctxProjectRoot = (ctx as { projectRoot?: unknown }).projectRoot;
+  const basePath = typeof ctxProjectRoot === "string" && ctxProjectRoot.length > 0
+    ? ctxProjectRoot
+    : process.cwd();
+
   let preferenceBlock = "";
   if (loadedPreferences) {
-    const cwd = process.cwd();
+    const cwd = basePath;
     const report = resolveAllSkillReferences(loadedPreferences.preferences, cwd);
     preferenceBlock = `\n\n${renderPreferencesForSystemPrompt(loadedPreferences.preferences, report.resolutions)}`;
     if (report.warnings.length > 0) {
@@ -144,14 +150,6 @@ export async function buildBeforeAgentStartResult(
     }
   }
 
-  const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), process.cwd());
-  if (globalSizeKb > 4) {
-    ctx.ui.notify(
-      `GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`,
-      "warning",
-    );
-  }
-
   // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
   // and best-effort — first run absorbs the existing decisions table into
   // the memory store; subsequent runs are a single sentinel SELECT.
@@ -159,12 +157,50 @@ export async function buildBeforeAgentStartResult(
     const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
     const written = backfillDecisionsToMemories();
     if (written > 0) {
-      ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store (ADR-013).`, "info");
+      ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store.`, "info");
     }
   } catch (e) {
     logWarning("bootstrap", `decisions backfill failed: ${(e as Error).message}`);
   }
 
+  // ADR-013 Stage 2b: KNOWLEDGE.md Patterns + Lessons backfill, then
+  // re-render the hybrid projection (manual Rules + projected Patterns +
+  // projected Lessons). Both are idempotent and best-effort — failures here
+  // can't block agent startup.
+  try {
+    const { backfillKnowledgeToMemories } = await import("../knowledge-backfill.js");
+    const writtenK = backfillKnowledgeToMemories(basePath);
+    if (writtenK > 0) {
+      ctx.ui.notify(`GSD: backfilled ${writtenK} KNOWLEDGE.md row${writtenK === 1 ? "" : "s"} into the memory store.`, "info");
+    }
+  } catch (e) {
+    logWarning("bootstrap", `KNOWLEDGE.md backfill failed: ${(e as Error).message}`);
+  }
+  try {
+    const { renderKnowledgeProjection } = await import("../knowledge-projection.js");
+    renderKnowledgeProjection(basePath);
+  } catch (e) {
+    logWarning("bootstrap", `KNOWLEDGE.md projection render failed: ${(e as Error).message}`);
+  }
+
+  // ADR-013 step 6 preflight: warn when decisions / KNOWLEDGE.md rows are not
+  // yet in the memories table. Read-only; never throws. Runs after the two
+  // backfills above so the gap report reflects post-backfill state.
+  try {
+    const { reportConsolidationGaps } = await import("../memory-consolidation-scanner.js");
+    reportConsolidationGaps(basePath);
+  } catch (e) {
+    logWarning("bootstrap", `memory consolidation scan failed: ${(e as Error).message}`);
+  }
+
+  const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), basePath);
+  if (globalSizeKb > 4) {
+    ctx.ui.notify(
+      `GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`,
+      "warning",
+    );
+  }
+
   let newSkillsBlock = "";
   if (hasSkillSnapshot()) {
     const newSkills = detectNewSkills();
@@ -370,7 +406,9 @@ export async function loadMemoryBlock(
 }
 
 export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: string; globalSizeKb: number } {
-  // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
+  // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project,
+  //    user-maintained. NOT migrated to memories (which are project-scoped),
+  //    so the full file is injected unchanged.
   let globalKnowledge = "";
   let globalSizeKb = 0;
   const globalKnowledgePath = join(gsdHomeDir, "agent", "KNOWLEDGE.md");
@@ -386,13 +424,18 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st
     }
   }
 
-  // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific
+  // 2. Project knowledge (.gsd/KNOWLEDGE.md) — project-specific.
+  //    ADR-013 Stage 2b: Patterns and Lessons are projected from the
+  //    memories table and already reach the LLM via loadMemoryBlock. Inject
+  //    only the intro prose + `## Rules` section here to avoid duplicating
+  //    Patterns/Lessons content in the prompt. Rules stay manual per
+  //    ADR-013 line 39 and have no memory equivalent.
   let projectKnowledge = "";
   const knowledgePath = resolveGsdRootFile(cwd, "KNOWLEDGE");
   if (existsSync(knowledgePath)) {
     try {
-      const content = readFileSync(knowledgePath, "utf-8").trim();
-      if (content) projectKnowledge = content;
+      const raw = readFileSync(knowledgePath, "utf-8").trim();
+      if (raw) projectKnowledge = extractIntroAndRules(raw).trim();
     } catch (e) {
       logWarning("bootstrap", `project knowledge file read failed: ${(e as Error).message}`);
     }
@@ -411,7 +454,7 @@ export function loadKnowledgeBlock(gsdHomeDir: string, cwd: string): { block: st
   }
   const body = limitKnowledgeBlock(parts.join("\n\n"), getKnowledgeCharLimit());
   return {
-    block: `\n\n[KNOWLEDGE — Rules, patterns, and lessons learned]\n\n${body}`,
+    block: `\n\n[KNOWLEDGE — Rules from KNOWLEDGE.md (Patterns and Lessons reach the LLM via the memory block)]\n\n${body}`,
     globalSizeKb,
   };
 }

package/src/resources/extensions/gsd/bootstrap/write-gate.ts

@@ -5,7 +5,7 @@ import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
 
 import { getIsolationMode } from "../preferences.js";
-import type { ToolsPolicy } from "../unit-context-manifest.js";
+import { compileSubagentPermissionContract, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 
@@ -64,7 +64,8 @@ const QUEUE_SAFE_TOOLS = new Set([
  *   env / printenv      — print environment variables
  *   true / false        — shell no-ops / test exit codes
  */
-const BASH_READ_ONLY_RE = /^\s*(cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
+const BASH_READ_ONLY_RE = /^\s*((?:cd|pushd|popd)(?:\s|$)|cat|head|tail|less|more|wc|file|stat|du|df|which|type|echo|printf|ls|find|grep|rg|awk|sed\b(?!.*-i)|sort|uniq|diff|comm|tr|cut|tee\s+-a\s+\/dev\/null|git\s+(log|show|diff|status|branch|tag|remote|rev-parse|ls-files|blame|shortlog|describe|stash\s+list|config\s+--get|cat-file)|gh\s+(issue|pr|api|repo|release)\s+(view|list|diff|status|checks)|mkdir\s+-p\s+\.gsd|rtk\s|npm\s+run\s+(test|test:\w+|lint|lint:\w+|typecheck|type-check|type-check:\w+|check|verify|audit|outdated|format:check|ci|validate)\b|npm\s+(ls|list|info|view|show|outdated|audit|explain|doctor|ping|--version|-v)\b|npx\s|tsx\s|node\s+(--print|--version|-v\b)|python[23]?\s+(-c\s+'[^']*'|--version|-V\b|-m\s+(pip\s+show|pip\s+list|site))|pip[23]?\s+(show|list|freeze|check|index\s+versions)\b|jq\s|yq\s|curl\s+(-s\b|--silent\b)(?!\s+[^|>]*\s-[oO]\b)(?!\s+[^|>]*\s--output\b)[^|>]*$|openssl\s+(version|x509|s_client)|env\b|printenv\b|true\b|false\b)/;
+const BASH_VERIFICATION_RE = /^\s*(npm\s+(run\s+(build|test|test:\w+|lint|lint:\w+|typecheck|type-check|verify|ci|validate)\b|test\b)|pnpm\s+(build|test|lint|typecheck|verify)\b|yarn\s+(build|test|lint|typecheck|verify)\b|vitest\b|jest\b|go\s+test\b)/;
 
 interface InMemoryWriteGateState {
   verifiedDepthMilestones: Set<string>;
@@ -747,7 +748,7 @@ function matchesAllowedGlob(absPath: string, basePath: string, globs: readonly s
 function blockReason(unitType: string, mode: string, what: string): string {
   return [
     `HARD BLOCK: unit "${unitType}" runs under tools-policy "${mode}" — ${what}.`,
-    `This is a mechanical gate enforced by manifest.tools (#4934). You MUST NOT proceed,`,
+    `This is a mechanical gate enforced by manifest.tools. You MUST NOT proceed,`,
     `retry the same call, or rationalize past this block. If you need to write user source,`,
     `the work belongs in execute-task, not in a planning unit.`,
   ].join(" ");
@@ -767,6 +768,9 @@ function blockReason(unitType: string, mode: string, what: string): string {
  *                    and listed in the policy's allowedSubagents.
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
+ *   - "verification"
+ *                  → allows Bash for project verification commands, but keeps
+ *                    writes restricted to .gsd/ and blocks subagent dispatch.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -804,14 +808,15 @@ export function shouldBlockPlanningUnit(
     return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
   }
 
-  // planning / planning-dispatch / docs modes share the same surface for safe tools, bash, and subagent.
+  // planning / planning-dispatch / docs / verification modes share the same surface for safe tools, bash, and subagent.
   if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
   if (tool.startsWith("gsd_")) return { block: false };
 
   if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
     if (policy.mode === "planning-dispatch") {
       const requested = (agentClasses ?? []).map(a => a.trim()).filter(Boolean);
-      const allowedSubagents = Array.isArray(policy.allowedSubagents) ? policy.allowedSubagents : [];
+      const dispatchContract = compileSubagentPermissionContract(policy);
+      const allowedSubagents = dispatchContract.allowedSubagents;
       const allowed = new Set(allowedSubagents);
       // When agentClasses is undefined, the caller has not been updated to extract
       // agent identities yet. Block and warn so stale callers surface in telemetry
@@ -861,6 +866,17 @@ export function shouldBlockPlanningUnit(
   }
 
   if (tool === "bash") {
+    if (policy.mode === "verification") {
+      if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
+      return {
+        block: true,
+        reason: blockReason(
+          unitType,
+          policy.mode,
+          `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`,
+        ),
+      };
+    }
     if (BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
     return {
       block: true,
@@ -951,9 +967,9 @@ function isPathContained(target: string, container: string): boolean {
  * while `git.isolation: worktree` is in effect and auto-mode hasn't created
  * (or flipped cwd into) the milestone worktree.
  *
- * Pure / unit-testable. Callers in `register-hooks.ts` supply the resolved
- * project root and current auto liveness; this function does no I/O beyond
- * realpath resolution.
+ * Pure / unit-testable. Callers in `register-hooks.ts` supply the effective
+ * execution base path (worker cwd or project root) and current auto liveness;
+ * this function does no I/O beyond realpath resolution.
  *
  * Allow rules (in order):
  *   1. Tool isn't a planning-write (write/edit/multi_edit/notebook_edit).
@@ -991,10 +1007,11 @@ export function shouldBlockWorktreeWrite(
     };
   }
 
-  // Resolve the target relative to the project root, then realpath to defeat
+  // Resolve relative targets against the effective execution base path, then
+  // canonicalize against the project root to defeat
   // symlink-based escapes and prefix tricks (e.g. .gsd/worktrees-extra/).
   const projectRoot = resolveWorktreeProjectRoot(effectiveBasePath);
-  const absTarget = isAbsolute(targetPath) ? targetPath : resolve(projectRoot, targetPath);
+  const absTarget = isAbsolute(targetPath) ? targetPath : resolve(effectiveBasePath, targetPath);
   const realTarget = realpathOrResolve(absTarget);
   const realRoot = realpathOrResolve(projectRoot);
   const realGsd = realpathOrResolve(join(projectRoot, ".gsd"));

package/src/resources/extensions/gsd/clean-root-preflight.ts

@@ -8,12 +8,14 @@
  *
  * Design constraints (from Trek-e approval):
  *  - Warn the user before stashing (no silent surprises)
- *  - git stash push / git stash pop only — no custom stash management layer
- *  - Stash/pop errors are logged but MUST NOT block the merge itself
+ *  - git stash push / git stash apply+drop for targeted restore
+ *  - Stash/apply errors are logged but MUST NOT block the merge itself
  *  - Fast-path status check — clean trees pay no extra cost
  */
 
 import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { logWarning } from "./workflow-logger.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
@@ -32,6 +34,148 @@ export interface PostflightResult {
   needsManualRecovery: boolean;
   message: string;
   stashRef?: string;
+  resolution?: "applied" | "already-present-dropped" | "already-present-preserved" | "manual-recovery";
+  collidedPaths?: string[];
+}
+
+function gitText(basePath: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    env: GIT_NO_PROMPT_ENV,
+  });
+}
+
+function gitBuffer(basePath: string, args: string[]): Buffer {
+  return execFileSync("git", args, {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: GIT_NO_PROMPT_ENV,
+  });
+}
+
+function errorText(err: unknown): string {
+  if (!err || typeof err !== "object") return String(err);
+  const parts: string[] = [];
+  const stderr = (err as { stderr?: unknown }).stderr;
+  const stdout = (err as { stdout?: unknown }).stdout;
+  for (const value of [stderr, stdout]) {
+    if (typeof value === "string") parts.push(value);
+    else if (value instanceof Uint8Array) parts.push(Buffer.from(value).toString("utf-8"));
+  }
+  parts.push(err instanceof Error ? err.message : String(err));
+  return parts.filter(Boolean).join("\n");
+}
+
+function parseAlreadyExistsNoCheckoutPaths(text: string): string[] {
+  const paths: string[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^(.+?) already exists, no checkout$/i.exec(line.trim());
+    if (match?.[1]) paths.push(match[1]);
+  }
+  return [...new Set(paths)];
+}
+
+function readZeroDelimitedPaths(output: string): string[] {
+  return output.split("\0").filter(Boolean);
+}
+
+function listStashUntrackedPaths(basePath: string, stashRef: string): string[] | null {
+  try {
+    const output = gitText(basePath, ["ls-tree", "-r", "-z", "--name-only", `${stashRef}^3`]);
+    return readZeroDelimitedPaths(output);
+  } catch {
+    return null;
+  }
+}
+
+function listStashTrackedPaths(basePath: string, stashRef: string): string[] | null {
+  try {
+    const output = gitText(basePath, ["diff", "--name-only", "-z", `${stashRef}^1`, stashRef]);
+    return readZeroDelimitedPaths(output);
+  } catch {
+    return null;
+  }
+}
+
+function isWorktreeClean(basePath: string): boolean | null {
+  try {
+    return gitText(basePath, ["status", "--porcelain"]).trim() === "";
+  } catch {
+    return null;
+  }
+}
+
+function stashBlobEqualsWorktreeFile(basePath: string, stashRef: string, path: string): boolean | null {
+  try {
+    const worktreePath = join(basePath, path);
+    if (!existsSync(worktreePath)) return false;
+    const worktreeContent = readFileSync(worktreePath);
+    const stashContent = gitBuffer(basePath, ["show", `${stashRef}^3:${path}`]);
+    return Buffer.compare(worktreeContent, stashContent) === 0;
+  } catch {
+    return null;
+  }
+}
+
+function reconcileAlreadyPresentUntrackedStash(
+  basePath: string,
+  milestoneId: string,
+  stashRef: string,
+  err: unknown,
+): PostflightResult | null {
+  const text = errorText(err);
+  const collidedPaths = parseAlreadyExistsNoCheckoutPaths(text);
+  if (collidedPaths.length === 0) return null;
+
+  const untrackedPaths = listStashUntrackedPaths(basePath, stashRef);
+  if (!untrackedPaths || untrackedPaths.length === 0) return null;
+
+  const trackedPaths = listStashTrackedPaths(basePath, stashRef);
+  if (trackedPaths === null || trackedPaths.length > 0) return null;
+
+  const untrackedPathSet = new Set(untrackedPaths);
+  if (!collidedPaths.every((path) => untrackedPathSet.has(path))) return null;
+  if (!untrackedPaths.every((path) => existsSync(join(basePath, path)))) return null;
+  if (isWorktreeClean(basePath) !== true) return null;
+
+  const blobComparisons = untrackedPaths.map((path) => stashBlobEqualsWorktreeFile(basePath, stashRef, path));
+  if (blobComparisons.some((result) => result === null)) return null;
+  const allIdentical = blobComparisons.every(Boolean);
+  if (allIdentical) {
+    let dropped = true;
+    try {
+      execFileSync("git", ["stash", "drop", stashRef], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      });
+    } catch (err) {
+      dropped = false;
+      logWarning("preflight", `git stash drop ${stashRef} failed after identical preflight stash reconciliation: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+      restored: true,
+      needsManualRecovery: false,
+      message: dropped
+        ? `Preflight stash for milestone ${milestoneId} contained files already present after merge; identical stash dropped.`
+        : `Preflight stash for milestone ${milestoneId} contained files already present after merge, but ${stashRef} could not be dropped and remains as a backup.`,
+      stashRef,
+      resolution: dropped ? "already-present-dropped" : "already-present-preserved",
+      collidedPaths,
+    };
+  }
+
+  return {
+    restored: false,
+    needsManualRecovery: false,
+    message: `Preflight stash for milestone ${milestoneId} contained untracked files already present after merge. Keeping merged files and preserving ${stashRef} as a backup.`,
+    stashRef,
+    resolution: "already-present-preserved",
+    collidedPaths,
+  };
 }
 
 function findPreflightStashRef(basePath: string, milestoneId: string, stashMarker?: string): string | null {
@@ -141,27 +285,48 @@ export function postflightPopStash(
         message: msg,
       };
     }
-    execFileSync("git", ["stash", "pop", stashRef], {
+    execFileSync("git", ["stash", "apply", stashRef], {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
       env: GIT_NO_PROMPT_ENV,
     });
+    let dropWarning: string | null = null;
+    try {
+      execFileSync("git", ["stash", "drop", stashRef], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      });
+    } catch (err) {
+      dropWarning = ` Stash was restored, but git stash drop ${stashRef} failed: ${err instanceof Error ? err.message : String(err)}.`;
+      logWarning("preflight", dropWarning.trim());
+    }
     const msg = `Restored stashed changes after milestone ${milestoneId} merge.`;
-    notify(msg, "info");
+    notify(`${msg}${dropWarning ?? ""}`, dropWarning ? "warning" : "info");
     return {
       restored: true,
       needsManualRecovery: false,
-      message: msg,
+      message: `${msg}${dropWarning ?? ""}`,
       stashRef,
+      resolution: "applied",
     };
   } catch (err) {
-    // Pop conflicts mean the merged code collides with the stashed changes.
+    if (stashRef) {
+      const reconciled = reconcileAlreadyPresentUntrackedStash(basePath, milestoneId, stashRef, err);
+      if (reconciled) {
+        logWarning("preflight", reconciled.message);
+        notify(reconciled.message, reconciled.resolution === "already-present-preserved" ? "warning" : "info");
+        return reconciled;
+      }
+    }
+    // Apply conflicts mean the merged code collides with the stashed changes.
     // Log a warning — the user needs to resolve manually, but the merge succeeded.
     const restoreHint = stashRef
-      ? `Run "git stash pop ${stashRef}" or "git stash apply ${stashRef}" manually to restore the correct stash.`
+      ? `Run "git stash apply ${stashRef}" manually to restore the correct stash, then "git stash drop ${stashRef}" after recovery.`
       : `Run "git stash list" to find the matching GSD preflight stash before restoring manually.`;
-    const msg = `git stash pop ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
+    const msg = `git stash apply ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
     logWarning("preflight", msg);
     notify(msg, "warning");
     return {
@@ -169,6 +334,7 @@ export function postflightPopStash(
       needsManualRecovery: true,
       message: msg,
       ...(stashRef ? { stashRef } : {}),
+      resolution: "manual-recovery",
     };
   }
 }

package/src/resources/extensions/gsd/commands/catalog.ts

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
+import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
 
 
 export interface GsdCommandDefinition {
@@ -13,7 +14,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|queue|quick|discuss|capture|triage|dispatch|verdict|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -24,6 +25,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "status", desc: "Progress dashboard" },
   { cmd: "widget", desc: "Cycle widget: full → small → min → off" },
   { cmd: "visualize", desc: "Open 10-tab workflow visualizer (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)" },
+  { cmd: "brief", desc: "Generate a visual HTML brief: diagram, plan, diff review, recap, table, or slides" },
   { cmd: "queue", desc: "Queue and reorder future milestones" },
   { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
   { cmd: "discuss", desc: "Discuss architecture and decisions" },
@@ -31,6 +33,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "changelog", desc: "Show categorized release notes" },
   { cmd: "triage", desc: "Manually trigger triage of pending captures" },
   { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
+  { cmd: "verdict", desc: "Override the recorded milestone validation verdict (pass|needs-attention|needs-remediation)" },
   { cmd: "history", desc: "View execution history" },
   { cmd: "undo", desc: "Revert last completed unit" },
   { cmd: "undo-task", desc: "Reset a specific task's completion state (DB + markdown)" },
@@ -88,6 +91,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
+  brief: VISUAL_BRIEF_MODES.map((mode) => ({ cmd: mode.mode, desc: mode.description })),
   auto: [
     { cmd: "--verbose", desc: "Show detailed execution output" },
     { cmd: "--debug", desc: "Enable debug logging" },
@@ -245,6 +249,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "uat", desc: "Run user acceptance testing" },
     { cmd: "replan", desc: "Replan the current slice" },
   ],
+  verdict: [
+    { cmd: "pass", desc: "Override the milestone validation verdict to pass" },
+    { cmd: "needs-attention", desc: "Override the verdict to needs-attention (requires --rationale)" },
+    { cmd: "needs-remediation", desc: "Override the verdict to needs-remediation (requires --rationale)" },
+  ],
   rate: [
     { cmd: "over", desc: "Model was overqualified for this task" },
     { cmd: "ok", desc: "Model was appropriate for this task" },