gsd-pi 2.82.0-dev.ed17d078d → 3.0.0-dev.2e8b124f7

package/dist/resources/extensions/gsd/bootstrap/agent-end-recovery.js

@@ -10,6 +10,7 @@ import { shouldIgnoreAgentEndForActiveUnit } from "../auto/unit-runner-events.js
 import { resolveModelId } from "../auto-model-selection.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { clearDiscussionFlowState } from "./write-gate.js";
+import { clearGuidedUnitContext } from "../guided-unit-context.js";
 import { resumeAutoAfterProviderDelay } from "./provider-error-resume.js";
 import { classifyError, createRetryState, resetRetryState, isTransient, } from "../error-classifier.js";
 import { blockModel, isModelBlocked } from "../blocked-models.js";
@@ -18,6 +19,9 @@ const MAX_NETWORK_RETRIES = 2;
 function isObjectRecord(value) {
     return !!value && typeof value === "object";
 }
+export function _hasEmptyAgentEndContent(content) {
+    return content == null || (Array.isArray(content) && content.length === 0);
+}
 /**
  * Cap on auto-resume attempts for sustained transient-provider errors.
  *
@@ -57,6 +61,11 @@ export function isUserInitiatedAbortMessage(message) {
         return false;
     return /\b(?:claude code process aborted by user|request aborted by user|process aborted by user)\b/i.test(message);
 }
+export function shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg) {
+    if (!isTransient(cls) || cls.kind === "rate-limit")
+        return false;
+    return !/retry failed after \d+ attempts:/i.test(rawErrorMsg);
+}
 function isBareClaudeCodeSessionSwitchAbortMarker(message) {
     if (!message)
         return false;
@@ -150,6 +159,13 @@ export function resolveAgentEndErrorDisplay(rawErrorMsg, content) {
     }
     return rawErrorMsg;
 }
+export function isTerminalDeletedWorktreeProviderError(message) {
+    if (!message)
+        return false;
+    if (!/\bdoes not exist\b/i.test(message))
+        return false;
+    return /[/\\]\.gsd[/\\](?:projects[/\\][^/\\]+[/\\])?worktrees[/\\][^/\\\s"']+/i.test(message);
+}
 async function pauseTransientWithBackoff(cls, pi, ctx, errorDetail, isRateLimit) {
     retryState.consecutiveTransientCount += 1;
     const baseRetryAfterMs = "retryAfterMs" in cls ? cls.retryAfterMs : 15_000;
@@ -187,8 +203,10 @@ export async function handleAgentEnd(pi, event, ctx) {
     // falsely report files as missing — producing a spurious "ready signal
     // rejected" loop even though the files are on disk.
     clearPathCache();
+    const basePath = resolveAgentEndBasePath();
+    clearGuidedUnitContext(basePath);
     try {
-        if (await checkDeepProjectSetupAfterTurn(event, ctx, resolveAgentEndBasePath())) {
+        if (await checkDeepProjectSetupAfterTurn(event, ctx, basePath)) {
             return;
         }
     }
@@ -196,22 +214,22 @@ export async function handleAgentEnd(pi, event, ctx) {
         const message = err instanceof Error ? err.message : String(err);
         logWarning("bootstrap", `checkDeepProjectSetupAfterTurn failed: ${message}`);
     }
-    if (checkAutoStartAfterDiscuss()) {
-        clearDiscussionFlowState(resolveAgentEndBasePath() ?? process.cwd());
+    if (checkAutoStartAfterDiscuss(basePath)) {
+        clearDiscussionFlowState(basePath ?? process.cwd());
         return;
     }
     // #4573 — When the LLM emits "Milestone X ready." but the required files
     // are missing, `checkAutoStartAfterDiscuss` returns false silently. Surface
     // that and nudge the LLM to complete the writes before the user hits the
     // downstream "All milestones complete" warning loop.
-    if (maybeHandleReadyPhraseWithoutFiles(event))
+    if (maybeHandleReadyPhraseWithoutFiles(event, basePath))
         return;
     // #4573 — Empty-turn recovery: if the LLM announced intent in prose but
     // emitted no tool calls, nudge it to execute. Fires only when auto-mode is
     // active or a discussion autostart is pending (non-auto interactive discuss
     // is user-driven). Runs before `isAutoActive` early return so pending
     // discussions (where isAutoActive may be false) still get recovered.
-    if (maybeHandleEmptyIntentTurn(event, isAutoActive()))
+    if (maybeHandleEmptyIntentTurn(event, isAutoActive(), basePath))
         return;
     if (!isAutoActive())
         return;
@@ -246,7 +264,7 @@ export async function handleAgentEnd(pi, event, ctx) {
         // that carry error context — e.g. errorMessage field or non-empty content
         // indicating a mid-stream failure. (#2695)
         const content = "content" in lastMsg ? lastMsg.content : undefined;
-        const hasEmptyContent = Array.isArray(content) && content.length === 0;
+        const hasEmptyContent = _hasEmptyAgentEndContent(content);
         const hasErrorMessage = "errorMessage" in lastMsg && !!lastMsg.errorMessage;
         if (hasEmptyContent && !hasErrorMessage) {
             // Non-fatal: treat as a normal agent end so the loop can continue
@@ -292,6 +310,12 @@ export async function handleAgentEnd(pi, event, ctx) {
         // the assistant message text content for display purposes only.
         // Classification still uses rawErrorMsg to avoid false positives from prose.
         const displayMsg = resolveAgentEndErrorDisplay(rawErrorMsg, "content" in lastMsg ? lastMsg.content : undefined);
+        if (isAutoCompletionStopInProgress() &&
+            isTerminalDeletedWorktreeProviderError(`${rawErrorMsg}\n${displayMsg}`)) {
+            resetRetryState(retryState);
+            logWarning("bootstrap", `Ignoring stale deleted-worktree provider error during terminal completion reroot: ${displayMsg || rawErrorMsg}`);
+            return;
+        }
         const errorDetail = displayMsg ? `: ${displayMsg}` : "";
         const explicitRetryAfterMs = ("retryAfterMs" in lastMsg && typeof lastMsg.retryAfterMs === "number") ? lastMsg.retryAfterMs : undefined;
         // ── 1. Classify using rawErrorMsg to avoid prose false-positives ────
@@ -375,7 +399,7 @@ export async function handleAgentEnd(pi, event, ctx) {
         // Core retries transient failures in-session after this handler.
         // Keep that behavior for non-rate-limit classes to avoid pause/retry races,
         // but let rate-limit continue into model fallback logic below (#4373).
-        if (isTransient(cls) && cls.kind !== "rate-limit") {
+        if (shouldDeferTransientErrorToCoreRetry(cls, rawErrorMsg)) {
             return;
         }
         // Cap rate-limit backoff for CLI-style providers (openai-codex, google-gemini-cli)

package/dist/resources/extensions/gsd/bootstrap/db-tools.js

@@ -468,17 +468,18 @@ export function registerDbTools(pi) {
         promptGuidelines: [
             "Use gsd_plan_milestone for milestone planning instead of writing ROADMAP.md directly.",
             "Keep parameters flat and provide the full milestone planning payload, including slices.",
+            "Milestone and slice titles must not contain forward slash (/), en dash, or em dash characters.",
             "The tool validates input, writes milestone and slice planning data transactionally, renders ROADMAP.md from DB, and clears both state and parse caches after success.",
             "Use the canonical name gsd_plan_milestone; gsd_milestone_plan is only an alias.",
         ],
         parameters: Type.Object({
             // ── Core identification + content (required) ──────────────────────
             milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
-            title: Type.String({ description: "Milestone title" }),
+            title: Type.String({ description: "Milestone title; must not contain forward slash (/), en dash, or em dash characters" }),
             vision: Type.String({ description: "Milestone vision" }),
             slices: Type.Array(Type.Object({
                 sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
-                title: Type.String({ description: "Slice title" }),
+                title: Type.String({ description: "Slice title; must not contain forward slash (/), en dash, or em dash characters" }),
                 risk: Type.String({ description: "Slice risk" }),
                 depends: Type.Array(Type.String(), { description: "Slice dependency IDs" }),
                 demo: Type.String({ description: "Roadmap demo text / After this" }),
@@ -546,10 +547,10 @@ export function registerDbTools(pi) {
                 title: Type.String({ description: "Task title" }),
                 description: Type.String({ description: "Task description / steps block" }),
                 estimate: Type.String({ description: "Task estimate string" }),
-                files: Type.Array(Type.String(), { description: "Files likely touched" }),
+                files: Type.Array(Type.String(), { description: "Array<string> of files likely touched; pass [\"path\"] or [], never a single string" }),
                 verify: Type.String({ description: "Verification command or block" }),
-                inputs: Type.Array(Type.String(), { description: "Input files or references" }),
-                expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
+                inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
+                expectedOutput: Type.Array(Type.String(), { description: "Array<string> of expected output files or artifacts; pass [\"path\"] or [], never a single string" }),
                 observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
             }), { description: "Planned tasks for the slice" }),
             // ── Enrichment metadata (optional — defaults to empty) ────────────
@@ -622,10 +623,10 @@ export function registerDbTools(pi) {
             title: Type.String({ description: "Task title" }),
             description: Type.String({ description: "Task description / steps block" }),
             estimate: Type.String({ description: "Task estimate string" }),
-            files: Type.Array(Type.String(), { description: "Files likely touched" }),
+            files: Type.Array(Type.String(), { description: "Array<string> of files likely touched; pass [\"path\"] or [], never a single string" }),
             verify: Type.String({ description: "Verification command or block" }),
-            inputs: Type.Array(Type.String(), { description: "Input files or references" }),
-            expectedOutput: Type.Array(Type.String(), { description: "Expected output files or artifacts" }),
+            inputs: Type.Array(Type.String(), { description: "Array<string> of input files or references; pass [\"path\"] or [], never a single string" }),
+            expectedOutput: Type.Array(Type.String(), { description: "Array<string> of expected output files or artifacts; pass [\"path\"] or [], never a single string" }),
             observabilityImpact: Type.Optional(Type.String({ description: "Task observability impact" })),
             // Single-writer v3 audit trail (Stream 2): caller-provided actor identity + causation.
             actorName: Type.Optional(Type.String({ description: "Caller-provided actor identity for the audit trail (e.g. 'executor-01', 'gsd-orchestrator')" })),
@@ -847,7 +848,7 @@ export function registerDbTools(pi) {
         name: "gsd_skip_slice",
         label: "Skip Slice",
         description: "Mark a slice as skipped so auto-mode advances past it without executing. " +
-            "Non-closed tasks within the slice are cascaded to skipped so milestone completion is not blocked by leftover pending tasks (#4375). " +
+            "Non-closed tasks within the slice are cascaded to skipped so milestone completion is not blocked by leftover pending tasks. " +
             "The slice data is preserved for reference. The state machine treats skipped slices like completed ones for dependency satisfaction.",
         promptSnippet: "Skip a GSD slice (mark as skipped, auto-mode will advance past it)",
         promptGuidelines: [

package/dist/resources/extensions/gsd/bootstrap/register-hooks.js

@@ -24,6 +24,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;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -675,7 +676,8 @@ export function registerHooks(pi, ecosystemHandlers) {
         // 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) {
@@ -694,7 +696,7 @@ export function registerHooks(pi, ecosystemHandlers) {
                     // Subagent inputs use { agent }, { tasks: [{ agent }] }, or { chain: [{ agent }] }.
                     agentClasses = extractSubagentAgentClasses(event.input);
                 }
-                const planningGuard = shouldBlockPlanningUnit(event.toolName, planningInput, dash.basePath || discussionBasePath, activeUnitType, manifest.tools, agentClasses);
+                const planningGuard = shouldBlockPlanningUnit(event.toolName, planningInput, dash.basePath || guidedUnit?.basePath || discussionBasePath, activeUnitType, manifest.tools, agentClasses);
                 if (planningGuard.block)
                     return planningGuard;
             }
@@ -704,8 +706,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         // 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, isAutoActive(), dash.currentUnit?.type);
+            const wtGuard = shouldBlockWorktreeWrite(event.toolName, event.input.path, dash.basePath ?? discussionBasePath, isAutoActive(), dash.currentUnit?.type);
             if (wtGuard.block)
                 return wtGuard;
         }

package/dist/resources/extensions/gsd/bootstrap/subagent-input.js

@@ -1,22 +1,34 @@
 export function extractSubagentAgentClasses(input) {
     if (!input || typeof input !== "object")
         return [];
-    const record = input;
     const agentClasses = [];
+    const visited = new WeakSet();
     const addAgentClass = (value) => {
-        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) => {
+    const visitItems = (value) => {
         if (!Array.isArray(value))
             return;
         for (const item of value) {
-            if (item && typeof item === "object")
-                addAgentClass(item.agent);
+            visit(item);
         }
     };
-    addAgentClass(record.agent);
-    addFromItems(record.tasks);
-    addFromItems(record.chain);
+    const visit = (value) => {
+        if (!value || typeof value !== "object")
+            return;
+        if (visited.has(value))
+            return;
+        visited.add(value);
+        const record = value;
+        addAgentClass(record.agent);
+        visitItems(record.tasks);
+        visitItems(record.chain);
+        visitItems(record.parallel);
+    };
+    visit(input);
     return agentClasses;
 }

package/dist/resources/extensions/gsd/bootstrap/write-gate.js

@@ -3,6 +3,7 @@ import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkS
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
 import { getIsolationMode } from "../preferences.js";
+import { compileSubagentPermissionContract } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
 import { isGsdWorktreePath, resolveWorktreeProjectRoot } from "../worktree-root.js";
 /**
@@ -57,7 +58,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)/;
 function createEmptyWriteGateState() {
     return {
         verifiedDepthMilestones: new Set(),
@@ -623,7 +625,7 @@ function matchesAllowedGlob(absPath, basePath, globs) {
 function blockReason(unitType, mode, what) {
     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(" ");
@@ -642,6 +644,9 @@ function blockReason(unitType, mode, what) {
  *                    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.
@@ -673,7 +678,7 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         // Unknown tool in read-only mode — block by default.
         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_"))
@@ -681,7 +686,8 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
     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
@@ -718,6 +724,14 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
     }
     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 {
@@ -796,9 +810,9 @@ function isPathContained(target, container) {
  * 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).
@@ -832,10 +846,11 @@ export function shouldBlockWorktreeWrite(toolName, targetPath, effectiveBasePath
             ].join(" "),
         };
     }
-    // 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/dist/resources/extensions/gsd/clean-root-preflight.js

@@ -8,14 +8,153 @@
  *
  * 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";
+function gitText(basePath, args) {
+    return execFileSync("git", args, {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+    });
+}
+function gitBuffer(basePath, args) {
+    return execFileSync("git", args, {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: GIT_NO_PROMPT_ENV,
+    });
+}
+function errorText(err) {
+    if (!err || typeof err !== "object")
+        return String(err);
+    const parts = [];
+    const stderr = err.stderr;
+    const stdout = err.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) {
+    const paths = [];
+    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) {
+    return output.split("\0").filter(Boolean);
+}
+function listStashUntrackedPaths(basePath, stashRef) {
+    try {
+        const output = gitText(basePath, ["ls-tree", "-r", "-z", "--name-only", `${stashRef}^3`]);
+        return readZeroDelimitedPaths(output);
+    }
+    catch {
+        return null;
+    }
+}
+function listStashTrackedPaths(basePath, stashRef) {
+    try {
+        const output = gitText(basePath, ["diff", "--name-only", "-z", `${stashRef}^1`, stashRef]);
+        return readZeroDelimitedPaths(output);
+    }
+    catch {
+        return null;
+    }
+}
+function isWorktreeClean(basePath) {
+    try {
+        return gitText(basePath, ["status", "--porcelain"]).trim() === "";
+    }
+    catch {
+        return null;
+    }
+}
+function stashBlobEqualsWorktreeFile(basePath, stashRef, path) {
+    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, milestoneId, stashRef, err) {
+    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, milestoneId, stashMarker) {
     const markerPrefix = `gsd-preflight-stash:${milestoneId}:`;
     let fallbackRef = null;
@@ -115,28 +254,50 @@ export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
                 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 = 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 {
@@ -144,6 +305,7 @@ export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
             needsManualRecovery: true,
             message: msg,
             ...(stashRef ? { stashRef } : {}),
+            resolution: "manual-recovery",
         };
     }
 }

package/dist/resources/extensions/gsd/commands/catalog.js

@@ -2,7 +2,8 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
-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";
+import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
+export const GSD_COMMAND_DESCRIPTION = "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 = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -12,6 +13,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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" },
@@ -19,6 +21,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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)" },
@@ -75,6 +78,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "eval-review", desc: "Audit a slice's AI evaluation strategy and write a scored EVAL-REVIEW.md (--force, --show)" },
 ];
 const NESTED_COMPLETIONS = {
+    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" },
@@ -232,6 +236,11 @@ const NESTED_COMPLETIONS = {
         { 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" },