gsd-pi 2.80.0-dev.8b3a59f5c → 2.80.0-dev.b2a374d5b

package/src/resources/extensions/gsd/auto/phases.ts

@@ -32,13 +32,13 @@ import { detectStuck } from "./detect-stuck.js";
 import { runUnit } from "./run-unit.js";
 import { debugLog } from "../debug-logger.js";
 import { resolveWorktreeProjectRoot, normalizeWorktreePathForCompare } from "../worktree-root.js";
-import { PROJECT_FILES, hasProjectFileInAncestor } from "../detection.js";
+import { classifyProject } from "../detection.js";
 import { MergeConflictError } from "../git-service.js";
 import { setCurrentPhase, clearCurrentPhase } from "../../shared/gsd-phase-state.js";
 import { pauseAutoForProviderError } from "../provider-error-pause.js";
 import { resumeAutoAfterProviderDelay } from "../bootstrap/provider-error-resume.js";
 import { join, basename } from "node:path";
-import { existsSync, cpSync, readdirSync } from "node:fs";
+import { existsSync, cpSync } from "node:fs";
 import {
   logWarning,
   logError,
@@ -684,6 +684,7 @@ export async function runPreDispatch(
       deps.postflightPopStash(
         s.originalBasePath || s.basePath,
         s.currentMilestoneId!,
+        preflightTransition.stashMarker,
         ctx.ui.notify.bind(ctx.ui),
       );
     }
@@ -797,6 +798,7 @@ export async function runPreDispatch(
           deps.postflightPopStash(
             s.originalBasePath || s.basePath,
             s.currentMilestoneId,
+            preflightAllComplete.stashMarker,
             ctx.ui.notify.bind(ctx.ui),
           );
         }
@@ -925,6 +927,7 @@ export async function runPreDispatch(
         deps.postflightPopStash(
           s.originalBasePath || s.basePath,
           s.currentMilestoneId,
+          preflightComplete.stashMarker,
           ctx.ui.notify.bind(ctx.ui),
         );
       }
@@ -1484,8 +1487,9 @@ export async function runUnitPhase(
   // Verify the working directory is a valid git checkout with project
   // files before dispatching work. A broken worktree causes agents to
   // hallucinate summaries since they cannot read or write any files.
-  // Uses the shared PROJECT_FILES list from detection.ts to support all
-  // ecosystems (Rust, Go, Python, Java, etc.), not just JS.
+  // Uses project classification so project presence is not conflated with
+  // ecosystem marker detection. Static/minimal repos become untyped-existing.
+  let projectClassification: ReturnType<typeof classifyProject> | null = null;
   if (s.basePath && unitType === "execute-task") {
     const gitMarker = join(s.basePath, ".git");
     const hasGit = deps.existsSync(gitMarker);
@@ -1496,30 +1500,29 @@ export async function runUnitPhase(
       await deps.stopAuto(ctx, pi, msg);
       return { action: "break", reason: "worktree-invalid" };
     }
-    const hasProjectFile = PROJECT_FILES.some((f) => deps.existsSync(join(s.basePath, f)));
-    const hasSrcDir = deps.existsSync(join(s.basePath, "src"));
-    // Xcode bundles have project-specific names (*.xcodeproj, *.xcworkspace)
-    // that cannot be matched by exact filename — scan the directory by suffix.
-    let hasXcodeBundle = false;
-    try {
-      const entries = deps.existsSync(s.basePath) ? readdirSync(s.basePath) : [];
-      hasXcodeBundle = entries.some((e: string) => e.endsWith(".xcodeproj") || e.endsWith(".xcworkspace"));
-    } catch (err) {
-      debugLog("runUnitPhase", { phase: "xcode-bundle-scan-failed", basePath: s.basePath, error: String(err) });
-    }
-    // Monorepo support (#2347): if no project files in the worktree directory,
-    // walk parent directories up to the filesystem root. In monorepos,
-    // package.json / Cargo.toml etc. live in a parent directory.
-    const hasProjectFileInParent =
-      !hasProjectFile && !hasSrcDir && !hasXcodeBundle
-        ? hasProjectFileInAncestor(s.basePath, deps.existsSync)
-        : false;
-    if (!hasProjectFile && !hasSrcDir && !hasXcodeBundle && !hasProjectFileInParent) {
-      // Greenfield projects won't have project files yet — the first task creates them.
-      // Log a warning but allow execution to proceed. The .git check above is sufficient
-      // to ensure we're in a valid working directory.
-      debugLog("runUnitPhase", { phase: "worktree-health-warn-greenfield", basePath: s.basePath, hasProjectFile, hasSrcDir, hasXcodeBundle });
-      ctx.ui.notify(`Warning: ${s.basePath} has no recognized project files — proceeding as greenfield project`, "warning");
+    projectClassification = classifyProject(s.basePath);
+    if (projectClassification.kind === "invalid-repo") {
+      const msg = `Worktree health check failed: ${s.basePath} classified as invalid-repo (${projectClassification.reason}) — refusing to dispatch ${unitType} ${unitId}`;
+      debugLog("runUnitPhase", { phase: "worktree-health-invalid-repo", basePath: s.basePath, classification: projectClassification });
+      if (projectClassification.reason === "missing .git" && hasGit) {
+        ctx.ui.notify(
+          `Warning: ${s.basePath} project classification could not confirm .git; assuming it has no project content yet — proceeding as greenfield project because worktree health reported .git present`,
+          "warning",
+        );
+      } else {
+        ctx.ui.notify(msg, "error");
+        await deps.stopAuto(ctx, pi, msg);
+        return { action: "break", reason: "worktree-invalid" };
+      }
+    } else if (projectClassification.kind === "greenfield") {
+      debugLog("runUnitPhase", { phase: "worktree-health-greenfield", basePath: s.basePath, classification: projectClassification });
+      ctx.ui.notify(`Warning: ${s.basePath} has no project content yet — proceeding as greenfield project`, "warning");
+    } else if (projectClassification.kind === "untyped-existing") {
+      debugLog("runUnitPhase", { phase: "worktree-health-untyped-existing", basePath: s.basePath, classification: projectClassification });
+      ctx.ui.notify(
+        `Notice: ${s.basePath} has existing project content but no recognized tooling markers — using generic file-level workflow guidance`,
+        "info",
+      );
     }
   }
 
@@ -1598,6 +1601,17 @@ export async function runUnitPhase(
   // Prompt injection
   let finalPrompt = prompt;
 
+  if (unitType === "execute-task") {
+    projectClassification ??= classifyProject(s.basePath);
+    if (projectClassification.kind === "untyped-existing") {
+      const samples = projectClassification.contentFiles.slice(0, 8).join(", ") || "project files";
+      finalPrompt +=
+        "\n\n**Project classification:** Existing untyped project. No recognized build/tooling markers were detected, " +
+        "so use generic file-level workflow guidance. Task plans and completion summaries must list every concrete " +
+        `project file changed in \`files\` or \`expected_output\`. Detected content sample: ${samples}.`;
+    }
+  }
+
   if (s.pendingVerificationRetry) {
     const retryCtx = s.pendingVerificationRetry;
     s.pendingVerificationRetry = null;

package/src/resources/extensions/gsd/auto-dispatch.ts

@@ -211,6 +211,23 @@ export function hasPendingDeepStage(prefs: GSDPreferences | undefined, basePath:
   return gate.status === "pending" || gate.status === "blocked";
 }
 
+export function shouldRunDeepProjectSetup(
+  state: Pick<GSDState, "phase">,
+  prefs: GSDPreferences | undefined,
+  basePath: string,
+  options: { hasSurvivorBranch?: boolean } = {},
+): boolean {
+  if (options.hasSurvivorBranch === true) return false;
+  if (
+    state.phase !== "pre-planning" &&
+    state.phase !== "needs-discussion" &&
+    state.phase !== "planning"
+  ) {
+    return false;
+  }
+  return hasPendingDeepStage(prefs, basePath);
+}
+
 function missingSliceStop(mid: string, phase: string): DispatchAction {
   return {
     action: "stop",

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -43,7 +43,7 @@ import {
 import { regenerateIfMissing } from "./workflow-projections.js";
 import { syncStateToProjectRoot } from "./auto-worktree.js";
 import { normalizeWorktreePathForCompare } from "./worktree-root.js";
-import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter } from "./gsd-db.js";
+import { isDbAvailable, getTask, getSlice, getMilestone, updateTaskStatus, _getAdapter, getVerificationEvidence } from "./gsd-db.js";
 import { renderPlanCheckboxes } from "./markdown-renderer.js";
 import { consumeSignal } from "./session-status-io.js";
 import {
@@ -852,22 +852,22 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
         }
 
         // Evidence cross-reference (execute-task only)
-        // Verification evidence is passed via the complete-task tool call and
-        // stored in the SUMMARY.md on disk — not available as structured data
-        // in the DB. The evidence collector tracks actual bash tool calls, so
-        // we can still detect units that claimed success but ran no commands.
+        // Only compare against concrete command evidence persisted by the task
+        // completion tool. A prose Verify field can be satisfied later by the
+        // host verification gate, so it is not enough to accuse the unit.
         if (safetyConfig.evidence_cross_reference && s.currentUnit.type === "execute-task") {
           try {
             const actual = getEvidence();
             const bashCalls = actual.filter(e => e.kind === "bash");
-            // If the task is marked complete but zero bash commands were run,
-            // it's suspicious — the LLM may have fabricated results.
             if (sMid && sSid && sTid && isDbAvailable()) {
               const taskRow = getTask(sMid, sSid, sTid);
-              if (taskRow?.status === "complete" && taskRow.verify && bashCalls.length === 0) {
-                logWarning("safety", "task marked complete with verification commands but no bash calls were executed");
+              const claimedCommands = getVerificationEvidence(sMid, sSid, sTid)
+                .map((row) => row.command)
+                .filter((command): command is string => typeof command === "string" && command.trim().length > 0);
+              if (taskRow?.status === "complete" && claimedCommands.length > 0 && bashCalls.length === 0) {
+                logWarning("safety", "task claimed verification command evidence but no execution tool calls were recorded");
                 ctx.ui.notify(
-                  `Safety: task ${sTid} has verification commands but no bash calls were recorded`,
+                  `Safety: task ${sTid} claimed command evidence but no execution tool calls were recorded`,
                   "warning",
                 );
               }

package/src/resources/extensions/gsd/auto-prompts.ts

@@ -8,7 +8,7 @@
 
 import { loadFile, parseContinue, parseSummary, loadActiveOverrides, formatOverridesSection, parseTaskPlanFile } from "./files.js";
 import type { Override, UatType } from "./files.js";
-import { hasVerdict, getUatType } from "./verdict-parser.js";
+import { hasVerdict, getUatType, extractVerdict } from "./verdict-parser.js";
 import { loadPrompt, inlineTemplate } from "./prompt-loader.js";
 import {
   resolveMilestoneFile, resolveSliceFile, resolveSlicePath,
@@ -39,6 +39,7 @@ import { logWarning } from "./workflow-logger.js";
 import { inlineGraphSubgraph } from "./graph-context.js";
 import { buildExtractionStepsBlock } from "./commands-extract-learnings.js";
 import { resolveSkillManifest, warnIfManifestHasMissingSkills } from "./skill-manifest.js";
+import { classifyProject, type ProjectClassification } from "./detection.js";
 
 // ─── Preamble Cap ─────────────────────────────────────────────────────────────
 
@@ -80,6 +81,108 @@ function resolveSummaryBudgetChars(): number {
   return resolvePromptBudgets().summaryBudgetChars;
 }
 
+function formatProjectClassificationForPlanning(classification: ProjectClassification): string {
+  const sampleFiles = classification.contentFiles.slice(0, 8);
+  const sample = sampleFiles.length > 0 ? sampleFiles.map((file) => `\`${file}\``).join(", ") : "(none)";
+  const lines = [
+    "### Project Classification",
+    "",
+    `- **Kind:** ${classification.kind}`,
+    `- **Content files:** ${classification.contentFiles.length}`,
+    `- **Sample files:** ${sample}`,
+    `- **Reason:** ${classification.reason}`,
+    "",
+  ];
+
+  if (classification.kind === "untyped-existing") {
+    if (classification.contentFiles.length <= 2) {
+      lines.push(
+        "**Workflow sizing:** This is a tiny existing untyped project. Prefer exactly one slice unless the milestone request clearly spans multiple independent user-visible capabilities.",
+      );
+    } else if (classification.contentFiles.length <= 5) {
+      lines.push(
+        "**Workflow sizing:** This is a small existing untyped project. Prefer 1-2 slices unless the milestone request clearly spans multiple independent user-visible capabilities.",
+      );
+    } else {
+      lines.push(
+        "**Workflow sizing:** Existing untyped project. Use generic file-level workflow guidance and size slices by real capability boundaries, not by missing tooling markers.",
+      );
+    }
+  } else if (classification.kind === "greenfield") {
+    lines.push("**Workflow sizing:** No project content exists yet. Use normal greenfield sizing for the requested scope.");
+  } else if (classification.kind === "typed-existing") {
+    lines.push("**Workflow sizing:** Known project markers exist. Use normal ecosystem-aware planning guidance.");
+  } else {
+    lines.push("**Workflow sizing:** Invalid repository state. Planning should surface this as a blocker rather than inventing project structure.");
+  }
+
+  return lines.join("\n");
+}
+
+function normalizeArtifactRef(value: string): string {
+  return value.trim().replace(/^[-\s]+/, "").replace(/^["'`]+|["'`]+$/g, "").replaceAll("\\", "/").replace(/^\.\//, "");
+}
+
+function parseCoveredArtifacts(validationContent: string): Set<string> {
+  const covered = new Set<string>();
+  const lines = validationContent.split(/\r?\n/);
+  let inCoveredArtifacts = false;
+  for (const line of lines) {
+    if (/^\s*covered[-_]?artifacts\s*:/i.test(line)) {
+      inCoveredArtifacts = true;
+      const inline = line.split(/covered[-_]?artifacts\s*:/i)[1]?.trim();
+      if (inline && inline !== "[]") {
+        inline.replace(/^\[|\]$/g, "").split(",").map(normalizeArtifactRef).filter(Boolean).forEach((item) => covered.add(item));
+      }
+      continue;
+    }
+    if (!inCoveredArtifacts) continue;
+    if (/^\S/.test(line) && !/^\s*-/.test(line)) break;
+    const item = line.match(/^\s*-\s*(.+)$/)?.[1];
+    if (item) covered.add(normalizeArtifactRef(item));
+  }
+  return covered;
+}
+
+function isValidationFreshOrApplicable(validationContent: string | null, currentArtifacts: string[]): boolean {
+  if (!validationContent) return false;
+  if (!/validation_metadata:/i.test(validationContent)) return false;
+  const coveredArtifacts = parseCoveredArtifacts(validationContent);
+  if (coveredArtifacts.size === 0) return false;
+  return currentArtifacts
+    .map(normalizeArtifactRef)
+    .filter(Boolean)
+    .every((artifact) => coveredArtifacts.has(artifact));
+}
+
+function formatCloseoutReviewInstructions(validationContent: string | null, validationRel: string, currentArtifacts: string[]): string {
+  const verdict = validationContent ? extractVerdict(validationContent) : null;
+  const validationFresh = isValidationFreshOrApplicable(validationContent, currentArtifacts);
+  if (verdict === "pass" && validationFresh) {
+    return [
+      "### Passing Validation Artifact",
+      "",
+      `A passing validation artifact is present at \`${validationRel}\`. Treat it as authoritative for success criteria, requirement coverage, verification classes, and cross-slice integration.`,
+      "",
+      "Do not delegate fresh reviewer/security/tester audits and do not redo the validation evidence review unless the artifact is internally inconsistent with the inlined summaries. Focus this unit on final milestone narrative, learnings, PROJECT/requirements updates, and `gsd_complete_milestone`.",
+    ].join("\n");
+  }
+
+  if (verdict) {
+    return [
+      "### Validation Requires Attention",
+      "",
+      `A validation artifact is present at \`${validationRel}\` with verdict \`${verdict}\`, but it is missing freshness metadata or does not cover current milestone artifacts. Do not treat the milestone as complete unless the issues are resolved and evidence supports completion.`,
+    ].join("\n");
+  }
+
+  return [
+    "### No Passing Validation Artifact",
+    "",
+    `No passing validation artifact was found at \`${validationRel}\`. Use the full closeout review path before completion.`,
+  ].join("\n");
+}
+
 function capPreamble(preamble: string): string {
   // Cap inlined context at min(historical 30K ceiling, scaled inline budget).
   // The ceiling preserves pre-fix behavior for large-window users; the scaled
@@ -1658,6 +1761,8 @@ export async function buildPlanMilestonePrompt(mid: string, midTitle: string, ba
   const researchAnchor = readPhaseAnchor(base, mid, "research-milestone");
   if (researchAnchor) inlined.push(formatAnchorForPrompt(researchAnchor));
 
+  inlined.push(formatProjectClassificationForPlanning(classifyProject(base)));
+
   inlined.push(await inlineFile(contextPath, contextRel, "Milestone Context"));
   const researchInline = await inlineFileOptional(researchPath, researchRel, "Milestone Research");
   if (researchInline) inlined.push(researchInline);
@@ -2348,6 +2453,9 @@ export async function buildCompleteMilestonePrompt(
   const inlineLevel = level ?? resolveInlineLevel();
   const roadmapPath = resolveMilestoneFile(base, mid, "ROADMAP");
   const roadmapRel = relMilestoneFile(base, mid, "ROADMAP");
+  const validationPath = resolveMilestoneFile(base, mid, "VALIDATION");
+  const validationRel = relMilestoneFile(base, mid, "VALIDATION");
+  const validationContent = validationPath ? await loadFile(validationPath) : null;
 
   const inlined: string[] = [];
   inlined.push(await inlineFile(roadmapPath, roadmapRel, "Milestone Roadmap"));
@@ -2389,6 +2497,13 @@ export async function buildCompleteMilestonePrompt(
       `### On-demand Slice Summaries\n\nExcerpted above. Read the full file for any slice when the excerpt's section heads don't carry enough narrative for the milestone summary you're drafting:\n\n${pathList}`,
     );
   }
+  const validationContext = [
+    formatCloseoutReviewInstructions(validationContent, validationRel, [validationRel, roadmapRel, ...summaryRelPaths]),
+  ];
+  if (validationContent) {
+    validationContext.push(`### Milestone Validation\nSource: \`${validationRel}\`\n\n${validationContent.trim()}`);
+  }
+  inlined.unshift(...validationContext);
 
   // Inline root GSD files (skip for minimal — completion can read these if needed)
   if (inlineLevel !== "minimal") {

package/src/resources/extensions/gsd/auto-start.ts

@@ -664,12 +664,13 @@ export async function bootstrapAutoSession(
     }
 
     const effectivePrefs = loadEffectiveGSDPreferences(base)?.preferences;
-    const deepProjectStagePending = !hasSurvivorBranch
-      ? (await import("./auto-dispatch.js")).hasPendingDeepStage(
-          effectivePrefs,
-          base,
-        )
-      : false;
+    const { shouldRunDeepProjectSetup } = await import("./auto-dispatch.js");
+    const deepProjectStagePending = shouldRunDeepProjectSetup(
+      state,
+      effectivePrefs,
+      base,
+      { hasSurvivorBranch },
+    );
 
     if (deepProjectStagePending) {
       // Deep project-level setup runs before the first milestone exists. Let

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

@@ -293,11 +293,15 @@ const STATE_REBUILD_MIN_INTERVAL_MS = 30_000;
  * the DB is unavailable (e.g. fresh project before init) we skip registration
  * silently rather than blocking session start.
  */
-function registerAutoWorkerForSession(session: AutoSession): void {
+function registerAutoWorkerForSession(
+  session: AutoSession,
+  projectRootOverride?: string,
+): void {
   if (session.workerId) return; // already registered (e.g. resume re-runs)
   try {
     const projectRootRealpath = normalizeRealPath(
-      session.scope?.workspace.projectRoot
+      projectRootOverride
+        ?? session.scope?.workspace.projectRoot
         ?? (session.originalBasePath || session.basePath),
     );
     session.workerId = registerAutoWorker({ projectRootRealpath });
@@ -420,6 +424,17 @@ export function _synthesizePausedSessionRecoveryForTest(
   return synthesizePausedSessionRecovery(basePath, unitType, unitId, sessionFile);
 }
 
+const DETACHED_AUTO_KEEPALIVE_INTERVAL_MS = 30_000;
+
+function withDetachedAutoKeepalive<T>(run: Promise<T>): Promise<T> {
+  const keepAlive = setInterval(() => {}, DETACHED_AUTO_KEEPALIVE_INTERVAL_MS);
+  return run.finally(() => {
+    clearInterval(keepAlive);
+  });
+}
+
+export const _withDetachedAutoKeepaliveForTest = withDetachedAutoKeepalive;
+
 export function startAutoDetached(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
@@ -431,7 +446,7 @@ export function startAutoDetached(
     milestoneLock?: string | null;
   },
 ): void {
-  void startAuto(ctx, pi, base, verboseMode, options).catch((err) => {
+  void withDetachedAutoKeepalive(startAuto(ctx, pi, base, verboseMode, options)).catch((err) => {
     const message = getErrorMessage(err);
     ctx.ui.notify(`Auto-start failed: ${message}`, "error");
     logWarning("engine", `auto start error: ${message}`, { file: "auto.ts" });
@@ -2046,6 +2061,11 @@ export async function startAuto(
     buildResolver,
   };
 
+  // Register the worker before bootstrap enters a milestone worktree.
+  // This ensures enterMilestone can claim a lease and seed dispatch claims
+  // for crash-recovery fidelity (#5405).
+  registerAutoWorkerForSession(s, base);
+
   const ready = await bootstrapAutoSession(
     s,
     ctx,

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

@@ -65,6 +65,26 @@ async function applyDisabledModelProviderPolicy(ctx: ExtensionContext): Promise<
   }
 }
 
+/**
+ * Bridge `context_management.compaction_threshold_percent` from GSD preferences
+ * into the agent's runtime compaction settings (#5475). The preference is
+ * validated to (0.5, 0.95) at load time, but defense-in-depth normalization
+ * here protects against a stale or hand-edited prefs file. Calling with
+ * `undefined` clears any prior override so a removed preference does not leak.
+ */
+async function applyCompactionThresholdOverride(ctx: ExtensionContext): Promise<void> {
+  try {
+    const { loadEffectiveGSDPreferences } = await import("../preferences.js");
+    const prefs = loadEffectiveGSDPreferences();
+    const raw = prefs?.preferences.context_management?.compaction_threshold_percent;
+    const value =
+      typeof raw === "number" && Number.isFinite(raw) && raw > 0 && raw < 1 ? raw : undefined;
+    ctx.setCompactionThresholdOverride(value);
+  } catch {
+    // Non-fatal: leave any existing override in place.
+  }
+}
+
 export function resolveNotificationStoreBasePath(cwd: string = process.cwd()): string {
   return resolveWorktreeProjectRoot(cwd);
 }
@@ -123,6 +143,7 @@ export function registerHooks(
     await resetAskUserQuestionsTurnCache();
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
+    await applyCompactionThresholdOverride(ctx);
     // Skip MCP auto-prep when running inside an auto-worktree (see session_switch below).
     const { isInAutoWorktree } = await import("../auto-worktree.js");
     if (!isInAutoWorktree(process.cwd())) {
@@ -172,6 +193,7 @@ export function registerHooks(
     clearDiscussionFlowState(process.cwd());
     await syncServiceTierStatus(ctx);
     await applyDisabledModelProviderPolicy(ctx);
+    await applyCompactionThresholdOverride(ctx);
     // Skip MCP auto-prep when running inside an auto-worktree. The worktree
     // already has .mcp.json from createAutoWorktree, and re-running the writer
     // post-chdir rewrites the file mid-run (non-idempotent due to cwd-relative

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

@@ -21,10 +21,34 @@ import { nativeHasChanges } from "./native-git-bridge.js";
 export interface PreflightResult {
   /** true when a stash was pushed and postflightPopStash should be called */
   stashPushed: boolean;
+  /** Unique marker embedded in the stash message for targeted restoration */
+  stashMarker?: string;
   /** human-readable summary of what happened (empty string for clean trees) */
   summary: string;
 }
 
+function findPreflightStashRef(basePath: string, milestoneId: string, stashMarker?: string): string | null {
+  const markerPrefix = `gsd-preflight-stash:${milestoneId}:`;
+  let fallbackRef: string | null = null;
+  try {
+    const list = execFileSync("git", ["stash", "list", "--format=%gd%x00%s"], {
+      cwd: basePath,
+      stdio: ["ignore", "pipe", "pipe"],
+      encoding: "utf-8",
+      env: GIT_NO_PROMPT_ENV,
+    });
+    for (const line of list.split("\n")) {
+      const [ref, subject] = line.split("\x00");
+      if (!ref || !subject) continue;
+      if (stashMarker && subject.includes(stashMarker)) return ref;
+      if (!fallbackRef && subject.includes(markerPrefix)) fallbackRef = ref;
+    }
+  } catch (err) {
+    logWarning("preflight", `stash list failed before restore: ${err instanceof Error ? err.message : String(err)}`);
+  }
+  return fallbackRef;
+}
+
 /**
  * Check the working tree for dirty files before a milestone merge.
  *
@@ -62,7 +86,8 @@ export function preflightCleanRoot(
 
   // Push the stash
   try {
-    execFileSync("git", ["stash", "push", "--include-untracked", "-m", "gsd-preflight-stash"], {
+    const stashMarker = `gsd-preflight-stash:${milestoneId}:${process.pid}:${Date.now()}:${process.hrtime.bigint().toString(36)}`;
+    execFileSync("git", ["stash", "push", "--include-untracked", "-m", `gsd-preflight-stash [${stashMarker}]`], {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
@@ -70,6 +95,7 @@ export function preflightCleanRoot(
     });
     return {
       stashPushed: true,
+      stashMarker,
       summary: `Stashed uncommitted changes before merge (milestone ${milestoneId}).`,
     };
   } catch (err) {
@@ -91,10 +117,19 @@ export function preflightCleanRoot(
 export function postflightPopStash(
   basePath: string,
   milestoneId: string,
+  stashMarker: string | undefined,
   notify: (message: string, level: "info" | "warning" | "error") => void,
 ): void {
+  let stashRef: string | null = null;
   try {
-    execFileSync("git", ["stash", "pop"], {
+    stashRef = findPreflightStashRef(basePath, milestoneId, stashMarker);
+    if (!stashRef) {
+      const msg = `No matching GSD preflight stash found for milestone ${milestoneId}; leaving stash list untouched.`;
+      logWarning("preflight", msg);
+      notify(msg, "warning");
+      return;
+    }
+    execFileSync("git", ["stash", "pop", stashRef], {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
@@ -104,7 +139,10 @@ export function postflightPopStash(
   } catch (err) {
     // Pop conflicts mean the merged code collides with the stashed changes.
     // Log a warning — the user needs to resolve manually, but the merge succeeded.
-    const msg = `git stash pop failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. Run "git stash pop" manually to restore your changes.`;
+    const restoreHint = stashRef
+      ? `Run "git stash pop ${stashRef}" or "git stash apply ${stashRef}" manually to restore the correct stash.`
+      : `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}`;
     logWarning("preflight", msg);
     notify(msg, "warning");
   }

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

@@ -45,5 +45,11 @@ export async function handleGSDCommand(
 
   if (handled) return;
 
+  if (trimmed.includes(" ")) {
+    const { handleDo } = await import("../commands-do.js");
+    await handleDo(trimmed, ctx, pi);
+    return;
+  }
+
   ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
 }