gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.2ff77b0ce

package/src/resources/extensions/gsd/unit-context-manifest.ts

@@ -325,6 +325,12 @@ export const KNOWN_UNIT_TYPES = [
   "run-uat",
   "gate-evaluate",
   "rewrite-docs",
+  // Deep planning mode (project-level) units
+  "workflow-preferences",
+  "discuss-project",
+  "discuss-requirements",
+  "research-decision",
+  "research-project",
 ] as const;
 
 export type UnitType = typeof KNOWN_UNIT_TYPES[number];
@@ -381,7 +387,11 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     memory: "prompt-relevant",
     codebaseMap: false,
     preferences: "active-only",
-    tools: TOOLS_PLANNING,
+    // planning-dispatch: validation is a verification-fan-out unit. It reads
+    // the milestone surface and dispatches reviewer/security/tester subagents
+    // to report findings without touching user source. Mirrors
+    // complete-milestone's policy. Write isolation to .gsd/ is preserved.
+    tools: TOOLS_PLANNING_DISPATCH_REVIEW,
     artifacts: {
       inline: ["roadmap", "slice-summary", "slice-uat", "requirements", "decisions", "templates"],
       excerpt: [],
@@ -590,6 +600,92 @@ export const UNIT_MANIFESTS: Record<UnitType, UnitContextManifest> = {
     },
     maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
   },
+
+  // ─── Deep planning mode (project-level) units ────────────────────────
+  // workflow-preferences: default-writing stage that records
+  // commit_policy / branch_model in PREFERENCES.md, defaults
+  // uat_dispatch/executor_class, and records the research decision. No project artifacts needed.
+  "workflow-preferences": {
+    skills: { mode: "none" },
+    knowledge: "none",
+    memory: "none",
+    codebaseMap: false,
+    preferences: "none",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: [],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_SMALL,
+  },
+  // discuss-project: PROJECT.md interview (deep mode only). Project-scoped
+  // discussion runs before any milestone exists, so milestone artifacts are
+  // not loaded. Keeps templates available for PROJECT.md scaffolding.
+  "discuss-project": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: ["templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
+  // discuss-requirements: REQUIREMENTS.md interview. PROJECT.md is the
+  // primary context input; templates carry the requirements format.
+  "discuss-requirements": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: ["project", "templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
+  // research-decision: lightweight one-question yes/no unit. Writes a
+  // marker JSON; no project artifacts needed.
+  "research-decision": {
+    skills: { mode: "none" },
+    knowledge: "none",
+    memory: "none",
+    codebaseMap: false,
+    preferences: "none",
+    tools: TOOLS_PLANNING,
+    artifacts: {
+      inline: [],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_SMALL,
+  },
+  // research-project: orchestrator that fans out 4 parallel scout subagents
+  // for project research (stack, features, architecture, pitfalls). Needs the
+  // planning-dispatch policy to dispatch them. PROJECT.md + REQUIREMENTS.md
+  // give the orchestrator the framing context.
+  "research-project": {
+    skills: { mode: "all" },
+    knowledge: "scoped",
+    memory: "prompt-relevant",
+    codebaseMap: true,
+    preferences: "active-only",
+    tools: { mode: "planning-dispatch", allowedSubagents: ["scout"] },
+    artifacts: {
+      inline: ["project", "requirements", "templates"],
+      excerpt: [],
+      onDemand: [],
+    },
+    maxSystemPromptChars: COMMON_BUDGET_MEDIUM,
+  },
 };
 
 // ─── Lookup helper ────────────────────────────────────────────────────────

package/src/resources/extensions/gsd/unit-runtime.ts

@@ -1,5 +1,6 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
+import { closeSync, existsSync, mkdirSync, openSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
 import {
   gsdRoot,
   relSliceFile,
@@ -10,6 +11,57 @@ import {
 import { loadFile, parseTaskPlanMustHaves, countMustHavesMentionedInSummary } from "./files.js";
 import { parseUnitId } from "./unit-id.js";
 
+// Per-record advisory lock — prevents read-modify-write races between
+// concurrent writers updating disjoint fields of the same runtime record.
+// Within a single Node process this is moot (writeUnitRuntimeRecord is sync),
+// but cross-process callers (parallel slice executors, doctor --fix while a
+// detached auto-mode session is alive) can otherwise clobber each other.
+const RECORD_LOCK_TIMEOUT_MS = 2_000;
+const RECORD_LOCK_STALE_MS = 5_000;
+const RECORD_LOCK_SLEEP_BUFFER = new SharedArrayBuffer(4);
+const RECORD_LOCK_SLEEP_VIEW = new Int32Array(RECORD_LOCK_SLEEP_BUFFER);
+
+function withRecordLock<T>(recordPath: string, fn: () => T): T {
+  const lockPath = recordPath + ".lock";
+  try {
+    mkdirSync(dirname(lockPath), { recursive: true });
+  } catch {
+    // best-effort
+  }
+  const deadline = Date.now() + RECORD_LOCK_TIMEOUT_MS;
+  while (true) {
+    try {
+      // O_EXCL atomic create-if-not-exists.
+      closeSync(openSync(lockPath, "wx"));
+      break;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "EEXIST") throw err;
+      // Existing lock — check for staleness before either waiting or stealing.
+      try {
+        const stat = statSync(lockPath);
+        if (Date.now() - stat.mtimeMs > RECORD_LOCK_STALE_MS) {
+          try { unlinkSync(lockPath); } catch { /* race: already removed */ }
+          continue;
+        }
+      } catch {
+        // stat failed (file removed between EEXIST and stat) — retry create.
+        continue;
+      }
+      if (Date.now() >= deadline) {
+        // Last-resort steal — unlikely in practice but avoids permanent wedge.
+        try { unlinkSync(lockPath); } catch { /* race */ }
+        continue;
+      }
+      Atomics.wait(RECORD_LOCK_SLEEP_VIEW, 0, 0, 5);
+    }
+  }
+  try {
+    return fn();
+  } finally {
+    try { unlinkSync(lockPath); } catch { /* best-effort */ }
+  }
+}
+
 export type UnitRuntimePhase =
   | "dispatched"
   | "wrapup-warning-sent"
@@ -65,29 +117,29 @@ export function writeUnitRuntimeRecord(
   startedAt: number,
   updates: Partial<AutoUnitRuntimeRecord> = {},
 ): AutoUnitRuntimeRecord {
-  const dir = runtimeDir(basePath);
-  mkdirSync(dir, { recursive: true });
   const path = runtimePath(basePath, unitType, unitId);
-  const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
-  const next: AutoUnitRuntimeRecord = {
-    version: 1,
-    unitType,
-    unitId,
-    startedAt,
-    updatedAt: Date.now(),
-    phase: updates.phase ?? prev?.phase ?? "dispatched",
-    wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
-    continueHereFired: updates.continueHereFired ?? prev?.continueHereFired ?? false,
-    timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
-    lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
-    progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
-    lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
-    recovery: updates.recovery ?? prev?.recovery,
-    recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
-    lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
-  };
-  writeFileSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
-  return next;
+  return withRecordLock(path, () => {
+    const prev = readUnitRuntimeRecord(basePath, unitType, unitId);
+    const next: AutoUnitRuntimeRecord = {
+      version: 1,
+      unitType,
+      unitId,
+      startedAt,
+      updatedAt: Date.now(),
+      phase: updates.phase ?? prev?.phase ?? "dispatched",
+      wrapupWarningSent: updates.wrapupWarningSent ?? prev?.wrapupWarningSent ?? false,
+      continueHereFired: updates.continueHereFired ?? prev?.continueHereFired ?? false,
+      timeoutAt: updates.timeoutAt ?? prev?.timeoutAt ?? null,
+      lastProgressAt: updates.lastProgressAt ?? prev?.lastProgressAt ?? Date.now(),
+      progressCount: updates.progressCount ?? prev?.progressCount ?? 0,
+      lastProgressKind: updates.lastProgressKind ?? prev?.lastProgressKind ?? "dispatch",
+      recovery: updates.recovery ?? prev?.recovery,
+      recoveryAttempts: updates.recoveryAttempts ?? prev?.recoveryAttempts ?? 0,
+      lastRecoveryReason: updates.lastRecoveryReason ?? prev?.lastRecoveryReason,
+    };
+    atomicWriteSync(path, JSON.stringify(next, null, 2) + "\n", "utf-8");
+    return next;
+  });
 }
 
 export function readUnitRuntimeRecord(basePath: string, unitType: string, unitId: string): AutoUnitRuntimeRecord | null {

package/src/resources/extensions/gsd/uok/plan-v2.ts

@@ -21,8 +21,10 @@ export function isExecutionEntryPhase(phase: Phase): boolean {
 export interface PlanV2CompileResult {
   ok: boolean;
   reason?: string;
+  emptyGraph?: boolean;
   graphPath?: string;
   nodeCount?: number;
+  sliceCount?: number;
   clarifyRoundLimit?: number;
   researchSynthesized?: boolean;
   draftContextIncluded?: boolean;
@@ -73,6 +75,10 @@ export function isMissingFinalizedContextResult(result: PlanV2CompileResult): bo
   return !result.ok && result.finalizedContextIncluded === false;
 }
 
+export function isEmptyPlanV2GraphResult(result: PlanV2CompileResult): boolean {
+  return !result.ok && result.emptyGraph === true;
+}
+
 function countSliceResearchArtifacts(basePath: string, milestoneId: string, slices: SliceRow[]): number {
   let count = 0;
   for (const slice of slices) {
@@ -170,6 +176,7 @@ export function compileUnitGraphFromState(basePath: string, state: GSDState): Pl
     ok: true,
     graphPath: outPath,
     nodeCount: nodes.length,
+    sliceCount: slices.length,
     clarifyRoundLimit,
     researchSynthesized: output.pipeline.researchSynthesized,
     draftContextIncluded: output.pipeline.draftContextIncluded,
@@ -181,7 +188,18 @@ export function ensurePlanV2Graph(basePath: string, state: GSDState): PlanV2Comp
   const compiled = compileUnitGraphFromState(basePath, state);
   if (!compiled.ok) return compiled;
   if ((compiled.nodeCount ?? 0) <= 0) {
-    return { ok: false, reason: "compiled graph is empty" };
+    if (
+      (state.phase === "validating-milestone" || state.phase === "completing-milestone") &&
+      (compiled.sliceCount ?? 0) > 0
+    ) {
+      return compiled;
+    }
+    return {
+      ...compiled,
+      ok: false,
+      reason: "compiled graph is empty",
+      emptyGraph: true,
+    };
   }
   return compiled;
 }

package/src/resources/extensions/gsd/user-input-boundary.ts

@@ -0,0 +1,166 @@
+const USER_APPROVAL_UNIT_TYPES = new Set([
+  "discuss-project",
+  "discuss-requirements",
+  "discuss-milestone",
+  "research-decision",
+]);
+
+const REMOTE_QUESTION_FAILURE_RE =
+  /(?:Remote (?:auth failed|questions failed|channel configured but returned no result|questions timed out|questions timed out or failed)|Failed to send questions via)/i;
+
+const APPROVAL_WAIT_RE =
+  /\bwait(?:ing)?\s+for\s+(?:your\s+)?(?:confirmation|approval|input|response|answer)\b/i;
+
+const APPROVAL_QUESTION_RE =
+  /\b(?:confirm|confirmation|approve|approval|approved|captured|correct|correctly|happy\s+with|ready\s+to\s+(?:write|save|proceed|ship)|(?:want|need)\s+to\s+adjust|should\s+I\s+(?:write|save|proceed)|do\s+you\s+want\s+me\s+to\s+(?:write|save|proceed)|ship\s+it)\b/i;
+
+const APPROVAL_RIGHT_QUESTION_RE =
+  /\b(?:does|do|is|are|was|were|did)\b[^\n?]{0,120}\bright\b/i;
+
+const APPROVAL_CHANGE_QUESTION_RE =
+  /\b(?:anything\s+else|anything|something)\s+to\s+(?:adjust|add|remove|reclassify)\b/i;
+
+const RESEARCH_DECISION_QUESTION_RE =
+  /\b(?:research|skip)\b/i;
+
+function extractTextFromMessage(msg: unknown): string {
+  if (!msg || typeof msg !== "object") return "";
+  const content = (msg as { content?: unknown }).content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== "object") continue;
+    const typed = block as { type?: unknown; text?: unknown };
+    if (typed.type === "text" && typeof typed.text === "string") {
+      parts.push(typed.text);
+    }
+  }
+  return parts.join("\n");
+}
+
+function lastAssistantText(messages: unknown[] | undefined): string {
+  if (!Array.isArray(messages)) return "";
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (!msg || typeof msg !== "object") continue;
+    if ((msg as { role?: unknown }).role !== "assistant") continue;
+    const text = extractTextFromMessage(msg).trim();
+    if (text) return text;
+  }
+  return "";
+}
+
+function anyMessageMatches(messages: unknown[] | undefined, pattern: RegExp): boolean {
+  if (!Array.isArray(messages)) return false;
+  return messages.some((msg) => {
+    if (!msg || typeof msg !== "object") return false;
+    if ((msg as { role?: unknown }).role === "user") return false;
+    return pattern.test(extractTextFromMessage(msg));
+  });
+}
+
+function hasApprovalQuestion(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "?") continue;
+    const previousBreak = Math.max(
+      text.lastIndexOf("\n", i),
+      text.lastIndexOf(".", i),
+      text.lastIndexOf("!", i),
+      text.lastIndexOf("?", i - 1),
+    );
+    const fragment = text.slice(previousBreak + 1, i + 1);
+    if (APPROVAL_QUESTION_RE.test(fragment)) return true;
+    if (APPROVAL_RIGHT_QUESTION_RE.test(fragment)) return true;
+    if (APPROVAL_CHANGE_QUESTION_RE.test(fragment)) return true;
+  }
+  return false;
+}
+
+function hasResearchDecisionQuestion(text: string): boolean {
+  for (let i = 0; i < text.length; i++) {
+    if (text[i] !== "?") continue;
+    const previousBreak = Math.max(
+      text.lastIndexOf("\n", i),
+      text.lastIndexOf(".", i),
+      text.lastIndexOf("!", i),
+      text.lastIndexOf("?", i - 1),
+    );
+    const fragment = text.slice(previousBreak + 1, i + 1);
+    if (RESEARCH_DECISION_QUESTION_RE.test(fragment)) return true;
+  }
+  return false;
+}
+
+export function approvalGateIdForUnit(
+  unitType: string | undefined,
+  unitId?: string | null,
+): string | null {
+  if (!unitType) return null;
+  if (unitType === "discuss-project") return "depth_verification_project_confirm";
+  if (unitType === "discuss-requirements") return "depth_verification_requirements_confirm";
+  if (unitType === "research-decision") return "depth_verification_research_decision_confirm";
+  if (unitType === "discuss-milestone") {
+    const safeUnitId = typeof unitId === "string" && /^[A-Za-z0-9_-]+$/.test(unitId)
+      ? unitId
+      : "milestone";
+    return `depth_verification_${safeUnitId}_confirm`;
+  }
+  return null;
+}
+
+const CHANGE_REQUEST_RESPONSE_RE =
+  /\b(?:no|nope|nah|not\s+yet|don't|do\s+not|change|add|remove|reclassify|adjust|clarify|missing|instead|but|however|wait|hold)\b/i;
+
+const APPROVAL_RESPONSE_RE =
+  /^(?:y|yes|yeah|yep|approve|approved|confirm|confirmed|correct|right|looks\s+(?:good|right)|sounds\s+good|all\s+good|ok|okay|go\s+ahead|proceed|write\s+it|save\s+it|do\s+it)\b/i;
+
+const RESEARCH_DECISION_RESPONSE_RE =
+  /^(?:research|run\s+research|do\s+research|skip|skip\s+research|no\s+research)\b/i;
+
+export function isExplicitApprovalResponse(
+  input: string | undefined,
+  pendingGateId?: string | null,
+): boolean {
+  const text = input?.trim() ?? "";
+  if (!text) return false;
+  if (pendingGateId?.includes("research_decision")) {
+    return RESEARCH_DECISION_RESPONSE_RE.test(text);
+  }
+  if (CHANGE_REQUEST_RESPONSE_RE.test(text)) return false;
+  return APPROVAL_RESPONSE_RE.test(text);
+}
+
+export function isAwaitingUserInput(messages: unknown[] | undefined): boolean {
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.some((line) => line.endsWith("?"))) return true;
+  return hasApprovalQuestion(text);
+}
+
+export function isAwaitingApprovalBoundary(messages: unknown[] | undefined): boolean {
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  return hasApprovalQuestion(text);
+}
+
+export function shouldPauseForUserApprovalQuestion(
+  unitType: string | undefined,
+  messages: unknown[] | undefined,
+): boolean {
+  if (!unitType || !USER_APPROVAL_UNIT_TYPES.has(unitType)) return false;
+  if (anyMessageMatches(messages, /ask_user_questions was cancelled before receiving a response/i)) return true;
+  if (anyMessageMatches(messages, REMOTE_QUESTION_FAILURE_RE)) return true;
+  const text = lastAssistantText(messages);
+  if (!text) return false;
+  if (APPROVAL_WAIT_RE.test(text)) return true;
+  if (unitType === "research-decision") return hasResearchDecisionQuestion(text);
+  return hasApprovalQuestion(text);
+}

package/src/resources/extensions/gsd/watch/header-renderer.ts

@@ -7,6 +7,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { visibleWidth, truncateToWidth } from "@gsd/pi-tui";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
+import { gsdHome } from "../gsd-home.js";
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
@@ -106,7 +107,7 @@ export function readMcpServerNames(projectRoot: string): string[] {
   const configPaths = [
     join(projectRoot, ".mcp.json"),
     join(projectRoot, ".gsd", "mcp.json"),
-    join(process.env.GSD_HOME || join(homedir(), ".gsd"), "mcp.json"),
+    join(gsdHome(), "mcp.json"),
   ];
   const names: string[] = [];
   const seen = new Set<string>();

package/src/resources/extensions/gsd/workflow-install.ts

@@ -22,12 +22,12 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { homedir } from "node:os";
 import { extname, join, resolve, sep as pathSep } from "node:path";
 import { createHash } from "node:crypto";
 import { parse as parseYaml } from "yaml";
 
 import { validateDefinition } from "./definition-loader.js";
+import { gsdHome } from "./gsd-home.js";
 
 // ─── Constants ───────────────────────────────────────────────────────────
 
@@ -73,8 +73,7 @@ export interface InstallTarget {
 }
 
 export function globalInstallDir(): string {
-  const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-  return join(gsdHome, "workflows");
+  return join(gsdHome(), "workflows");
 }
 
 export function projectInstallDir(basePath: string): string {

package/src/resources/extensions/gsd/workflow-manifest.ts

@@ -76,7 +76,9 @@ export function snapshotState(): StateManifest {
   // Wrap all reads in a deferred transaction so the snapshot is consistent
   // (all SELECTs see the same DB state even if a concurrent write lands between them).
   return readTransaction(() => {
-  const rawMilestones = db.prepare("SELECT * FROM milestones ORDER BY id").all() as Record<string, unknown>[];
+  const rawMilestones = db.prepare(
+    "SELECT * FROM milestones ORDER BY CASE WHEN sequence > 0 THEN 0 ELSE 1 END, sequence, id",
+  ).all() as Record<string, unknown>[];
   const milestones: MilestoneRow[] = rawMilestones.map((r) => ({
     id: r["id"] as string,
     title: r["title"] as string,
@@ -95,6 +97,7 @@ export function snapshotState(): StateManifest {
     definition_of_done: JSON.parse((r["definition_of_done"] as string) || "[]"),
     requirement_coverage: (r["requirement_coverage"] as string) ?? "",
     boundary_map_markdown: (r["boundary_map_markdown"] as string) ?? "",
+    sequence: Number(r["sequence"] ?? 0),
   }));
 
   const rawSlices = db.prepare("SELECT * FROM slices ORDER BY milestone_id, sequence, id").all() as Record<string, unknown>[];

package/src/resources/extensions/gsd/workflow-mcp-auto-prep.ts

@@ -29,29 +29,13 @@ function getAuthModeSafe(
   }
 }
 
-function hasClaudeCodeProvider(ctx: WorkflowMcpAutoPrepContext): boolean {
-  return getAuthModeSafe(ctx, "claude-code") === "externalCli";
-}
-
-function isClaudeCodeProviderReady(ctx: WorkflowMcpAutoPrepContext): boolean {
-  const readyCheck = ctx.modelRegistry?.isProviderRequestReady;
-  if (typeof readyCheck !== "function") return false;
-  try {
-    return readyCheck("claude-code");
-  } catch {
-    return false;
-  }
-}
-
 export function shouldAutoPrepareWorkflowMcp(ctx: WorkflowMcpAutoPrepContext): boolean {
   const provider = ctx.model?.provider;
   const baseUrl = ctx.model?.baseUrl;
   const authMode = getAuthModeSafe(ctx, provider);
 
-  if (usesWorkflowMcpTransport(authMode as any, baseUrl)) return true;
-  if (provider === "claude-code") return true;
-  if (hasClaudeCodeProvider(ctx)) return true;
-  return isClaudeCodeProviderReady(ctx);
+  if (provider !== "claude-code") return false;
+  return usesWorkflowMcpTransport(authMode as any, baseUrl) || authMode === "externalCli";
 }
 
 export function prepareWorkflowMcpForProject(

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

@@ -207,7 +207,7 @@ function buildWorkflowLaunchEnv(
 
   return {
     ...(explicitEnv ?? {}),
-    ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath } : {}),
+    ...(gsdCliPath ? { GSD_CLI_PATH: gsdCliPath, GSD_BIN_PATH: gsdCliPath } : {}),
     ...(executorModulePath ? { GSD_WORKFLOW_EXECUTORS_MODULE: executorModulePath } : {}),
     ...(writeGateModulePath ? { GSD_WORKFLOW_WRITE_GATE_MODULE: writeGateModulePath } : {}),
     ...(nodeOptions ? { NODE_OPTIONS: nodeOptions } : {}),
@@ -225,7 +225,11 @@ export function detectWorkflowMcpLaunchConfig(
   const explicitArgs = parseJsonEnv<unknown>(env, "GSD_WORKFLOW_MCP_ARGS");
   const explicitEnv = parseJsonEnv<Record<string, string>>(env, "GSD_WORKFLOW_MCP_ENV");
   const explicitCwd = env.GSD_WORKFLOW_MCP_CWD?.trim();
-  const gsdCliPath = env.GSD_CLI_PATH?.trim() || env.GSD_BIN_PATH?.trim();
+  const gsdCliPath =
+    explicitEnv?.GSD_CLI_PATH?.trim()
+    || explicitEnv?.GSD_BIN_PATH?.trim()
+    || env.GSD_CLI_PATH?.trim()
+    || env.GSD_BIN_PATH?.trim();
   const workflowProjectRoot =
     explicitEnv?.GSD_WORKFLOW_PROJECT_ROOT?.trim() ||
     env.GSD_WORKFLOW_PROJECT_ROOT?.trim() ||
@@ -298,6 +302,12 @@ export function buildWorkflowMcpServers(
 
 export function getRequiredWorkflowToolsForGuidedUnit(unitType: string): string[] {
   switch (unitType) {
+    case "discuss-project":
+      return ["ask_user_questions", "gsd_summary_save"];
+    case "discuss-requirements":
+      return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
+    case "research-decision":
+      return ["ask_user_questions"];
     case "discuss-milestone":
       return ["gsd_summary_save", "gsd_plan_milestone"];
     case "discuss-slice":
@@ -320,6 +330,12 @@ export function getRequiredWorkflowToolsForGuidedUnit(unitType: string): string[
 
 export function getRequiredWorkflowToolsForAutoUnit(unitType: string): string[] {
   switch (unitType) {
+    case "discuss-project":
+      return ["ask_user_questions", "gsd_summary_save"];
+    case "discuss-requirements":
+      return ["ask_user_questions", "gsd_requirement_save", "gsd_summary_save"];
+    case "research-decision":
+      return ["ask_user_questions"];
     case "discuss-milestone":
       return ["gsd_summary_save", "gsd_plan_milestone"];
     case "research-milestone":
@@ -358,11 +374,32 @@ export function usesWorkflowMcpTransport(
   return authMode === "externalCli" && typeof baseUrl === "string" && baseUrl.startsWith("local://");
 }
 
+function hasAskUserQuestionsTool(activeTools: string[]): boolean {
+  return activeTools.some((toolName) => {
+    if (toolName === "ask_user_questions") return true;
+    if (!toolName.startsWith("mcp__")) return false;
+    const toolSeparator = toolName.indexOf("__", "mcp__".length);
+    return toolSeparator >= 0 && toolName.slice(toolSeparator + 2) === "ask_user_questions";
+  });
+}
+
+function workflowMcpStructuredQuestionsOptIn(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = env.GSD_WORKFLOW_MCP_STRUCTURED_QUESTIONS;
+  return value === "1" || value === "true";
+}
+
 export function supportsStructuredQuestions(
   activeTools: string[],
-  options: Pick<WorkflowCapabilityOptions, "authMode" | "baseUrl"> = {},
+  options: Pick<WorkflowCapabilityOptions, "authMode" | "baseUrl" | "env"> = {},
 ): boolean {
-  if (!activeTools.includes("ask_user_questions")) return false;
+  if (!hasAskUserQuestionsTool(activeTools)) return false;
+  if (usesWorkflowMcpTransport(options.authMode, options.baseUrl)) {
+    // Claude Code local workflow-MCP exposes ask_user_questions, but form
+    // elicitation can return an immediate cancel outside GSD's chat turn. Keep
+    // checkpoints in plain chat unless a caller deliberately opts into testing
+    // that transport.
+    return workflowMcpStructuredQuestionsOptIn(options.env);
+  }
 
   return true;
 }

package/src/resources/extensions/gsd/workflow-migration.ts

@@ -8,6 +8,7 @@ import { join } from "node:path";
 import { _getAdapter, bulkInsertLegacyHierarchy } from "./gsd-db.js";
 import { parseRoadmap, parsePlan } from "./parsers-legacy.js";
 import { logWarning } from "./workflow-logger.js";
+import { resolveMilestoneFile } from "./paths.js";
 
 // ─── needsAutoMigration ───────────────────────────────────────────────────
 
@@ -117,12 +118,12 @@ export function migrateFromMarkdown(basePath: string): void {
     const mDir = join(milestonesDir, mId);
 
     // Determine milestone status: done if a milestone-level SUMMARY.md exists
-    const milestoneSummaryPath = join(mDir, "SUMMARY.md");
+    const milestoneSummaryPath = resolveMilestoneFile(basePath, mId, "SUMMARY") ?? join(mDir, "SUMMARY.md");
     const milestoneDone = existsSync(milestoneSummaryPath);
     const milestoneStatus = milestoneDone ? "done" : "active";
 
     // Parse ROADMAP.md for slices list
-    const roadmapPath = join(mDir, "ROADMAP.md");
+    const roadmapPath = resolveMilestoneFile(basePath, mId, "ROADMAP") ?? join(mDir, "ROADMAP.md");
     let roadmapSlices: Array<{ id: string; title: string; done: boolean; risk: string }> = [];
 
     if (existsSync(roadmapPath)) {
@@ -286,7 +287,7 @@ export function validateMigration(basePath: string): { discrepancies: string[] }
 
     for (const mId of milestoneDirs) {
       const mDir = join(milestonesDir, mId);
-      const roadmapPath = join(mDir, "ROADMAP.md");
+      const roadmapPath = resolveMilestoneFile(basePath, mId, "ROADMAP") ?? join(mDir, "ROADMAP.md");
 
       if (existsSync(roadmapPath)) {
         try {