gsd-pi 2.78.1-dev.0fdacd524 → 2.78.1-dev.42ef05fbe

package/dist/resources/extensions/gsd/eval-review-schema.js

@@ -0,0 +1,208 @@
+/**
+ * EVAL-REVIEW frontmatter schema and parser.
+ *
+ * The auditor agent for `/gsd eval-review` writes a markdown file whose
+ * machine-readable contract lives entirely in YAML frontmatter. The body
+ * after the closing `---` is human-only prose and is never parsed by any
+ * consumer (the design response to a prior parser that used regex over LLM-generated
+ * prose and produced silent failures).
+ *
+ * This module owns:
+ *   - The TypeBox schema for the frontmatter (single source of truth).
+ *   - A small frontmatter extractor (locates the YAML block).
+ *   - The validated parser (`parseEvalReviewFrontmatter`).
+ *   - Pure helpers for derived fields the handler must recompute server-side
+ *     (overall score, severity counts) — we never trust LLM arithmetic.
+ *
+ * Consumers: `commands-eval-review.ts` (writer), `commands-ship.ts` (reader
+ * for the soft pre-ship warning), and a future `commands-eval-fix.ts`.
+ */
+import { Type } from "@sinclair/typebox";
+import { Value } from "@sinclair/typebox/value";
+import { parse as parseYaml } from "yaml";
+// ─── Constants ────────────────────────────────────────────────────────────────
+/** Schema version literal embedded in every EVAL-REVIEW.md frontmatter. */
+export const EVAL_REVIEW_SCHEMA_VERSION = "eval-review/v1";
+/** Verdict values, ordered from worst to best for UI display purposes. */
+export const VERDICT_VALUES = [
+    "NOT_IMPLEMENTED",
+    "SIGNIFICANT_GAPS",
+    "NEEDS_WORK",
+    "PRODUCTION_READY",
+];
+/** Severity classifications used in `gaps[*].severity`. */
+export const SEVERITY_VALUES = ["blocker", "major", "minor"];
+/** Eval dimensions an auditor scores. `other` is the catch-all. */
+export const DIMENSION_VALUES = [
+    "observability",
+    "guardrails",
+    "tests",
+    "metrics",
+    "datasets",
+    "other",
+];
+/** Lower bound for any score in the schema. */
+export const MIN_SCORE = 0;
+/** Upper bound for any score in the schema. */
+export const MAX_SCORE = 100;
+/** Coverage's contribution to overall_score. See `docs/user-docs/eval-review.md` for rationale. */
+export const COVERAGE_WEIGHT = 0.6;
+/** Infrastructure's contribution to overall_score. See `docs/user-docs/eval-review.md` for rationale. */
+export const INFRASTRUCTURE_WEIGHT = 0.4;
+// ─── Schema ───────────────────────────────────────────────────────────────────
+const verdictSchema = Type.Union(VERDICT_VALUES.map((v) => Type.Literal(v)));
+const severitySchema = Type.Union(SEVERITY_VALUES.map((v) => Type.Literal(v)));
+const dimensionSchema = Type.Union(DIMENSION_VALUES.map((v) => Type.Literal(v)));
+/**
+ * One gap finding inside `gaps[]`. Every field is required — the prompt
+ * cannot emit a partial gap. `evidence` is mandatory; the anti-Goodhart
+ * guard depends on it.
+ */
+export const EvalReviewGap = Type.Object({
+    id: Type.String({ pattern: "^G\\d+$" }),
+    dimension: dimensionSchema,
+    severity: severitySchema,
+    description: Type.String({ minLength: 1 }),
+    evidence: Type.String({ minLength: 1 }),
+    suggested_fix: Type.String({ minLength: 1 }),
+});
+/** Severity histogram. The handler recomputes this from `gaps[]`. */
+export const EvalReviewCounts = Type.Object({
+    blocker: Type.Integer({ minimum: 0 }),
+    major: Type.Integer({ minimum: 0 }),
+    minor: Type.Integer({ minimum: 0 }),
+});
+/**
+ * The full frontmatter schema. Field order in the schema definition mirrors
+ * the order that the auditor prompt asks the LLM to emit, so a literal-eyeball
+ * comparison between this file and `prompts/eval-review.md` stays meaningful.
+ */
+export const EvalReviewFrontmatter = Type.Object({
+    schema: Type.Literal(EVAL_REVIEW_SCHEMA_VERSION),
+    verdict: verdictSchema,
+    coverage_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+    infrastructure_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+    overall_score: Type.Integer({ minimum: MIN_SCORE, maximum: MAX_SCORE }),
+    generated: Type.String({ pattern: "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$" }),
+    slice: Type.String({ pattern: "^S\\d+$" }),
+    milestone: Type.String({ minLength: 1 }),
+    gaps: Type.Array(EvalReviewGap),
+    counts: EvalReviewCounts,
+});
+// ─── Frontmatter extraction ───────────────────────────────────────────────────
+/**
+ * Locate the YAML block between two `---` lines and return its raw text.
+ *
+ * Tolerant to CRLF line endings. Does not interpret the YAML — that's the
+ * caller's job. The extractor only enforces the markdown frontmatter shape.
+ *
+ * @param raw - Full contents of an EVAL-REVIEW.md file.
+ * @returns `{ yaml }` with the inner YAML text on success, or `{ error }`
+ *   describing why the frontmatter could not be located.
+ */
+export function extractFrontmatterRaw(raw) {
+    const lines = raw.split(/\r?\n/);
+    if (lines[0] !== "---") {
+        return { error: "Missing opening `---` frontmatter delimiter on line 1" };
+    }
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i] === "---") {
+            return { yaml: lines.slice(1, i).join("\n") };
+        }
+    }
+    return { error: "Missing closing `---` frontmatter delimiter" };
+}
+/**
+ * Parse and validate the frontmatter of an EVAL-REVIEW.md file.
+ *
+ * Failure cases are exhaustive and deterministic:
+ *   - missing/unclosed frontmatter → `pointer: "/"`, message names the cause
+ *   - YAML syntax error → `pointer: "/"`, message contains "YAML"
+ *   - schema violation → `pointer` is the JSON-Pointer path of the bad field
+ *
+ * Body content after the closing `---` is never inspected. This is an
+ * response to a prior parser that used regex over the body and silently
+ * failed on prose / tables / numbered lists.
+ *
+ * @param raw - Full contents of an EVAL-REVIEW.md file.
+ * @returns A discriminated `ParseResult`.
+ */
+export function parseEvalReviewFrontmatter(raw) {
+    const fm = extractFrontmatterRaw(raw);
+    if ("error" in fm) {
+        return { ok: false, error: fm.error, pointer: "/" };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(fm.yaml, { schema: "core" });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { ok: false, error: `YAML parse error: ${msg}`, pointer: "/" };
+    }
+    const schema = EvalReviewFrontmatter;
+    if (!Value.Check(schema, parsed)) {
+        const errs = [...Value.Errors(schema, parsed)];
+        const first = errs[0];
+        return {
+            ok: false,
+            error: `Schema validation failed: ${first?.message ?? "unknown error"}`,
+            pointer: first?.path ?? "/",
+        };
+    }
+    return { ok: true, data: parsed };
+}
+// ─── Derived fields ───────────────────────────────────────────────────────────
+/**
+ * Compute `overall_score` from the two component scores using the rubric
+ * weights documented in `docs/user-docs/eval-review.md`.
+ *
+ * The handler always recomputes this value rather than trusting whatever the
+ * LLM emitted in `overall_score`. If the LLM-emitted value disagrees with the
+ * recomputed one, the disagreement is logged and the recomputed value wins.
+ *
+ * Clamps the result into `[MIN_SCORE, MAX_SCORE]` defensively. Schema-validated
+ * inputs are already in range, but the helper is exported and may be called
+ * from a code path that bypasses the schema (tests, future tools); the clamp
+ * keeps the contract honest in those cases.
+ *
+ * @param coverage - integer 0..100 from the auditor's coverage assessment.
+ * @param infrastructure - integer 0..100 from the auditor's infra assessment.
+ * @returns rounded integer 0..100.
+ */
+export function computeOverallScore(coverage, infrastructure) {
+    const raw = Math.round(coverage * COVERAGE_WEIGHT + infrastructure * INFRASTRUCTURE_WEIGHT);
+    return Math.max(MIN_SCORE, Math.min(MAX_SCORE, raw));
+}
+/**
+ * Build the severity histogram for a list of gaps.
+ *
+ * Used by the handler to overwrite whatever the LLM put in `counts` —
+ * we recompute server-side rather than trust LLM arithmetic.
+ *
+ * @param gaps - validated gap list.
+ * @returns counts keyed by severity literal.
+ */
+export function deriveCounts(gaps) {
+    const counts = { blocker: 0, major: 0, minor: 0 };
+    for (const g of gaps)
+        counts[g.severity]++;
+    return counts;
+}
+/**
+ * Map a numeric overall_score to its verdict literal using the bands from
+ * Bands per `docs/user-docs/eval-review.md`: ≥80 PRODUCTION_READY, 60..79 NEEDS_WORK, 40..59 SIGNIFICANT_GAPS,
+ * <40 NOT_IMPLEMENTED.
+ *
+ * @param overall - integer 0..100.
+ * @returns a verdict literal.
+ */
+export function verdictForScore(overall) {
+    if (overall >= 80)
+        return "PRODUCTION_READY";
+    if (overall >= 60)
+        return "NEEDS_WORK";
+    if (overall >= 40)
+        return "SIGNIFICANT_GAPS";
+    return "NOT_IMPLEMENTED";
+}

package/dist/resources/extensions/gsd/forensics.js

@@ -10,7 +10,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getHomeDir } from "./home-dir.js";
+import { gsdHome } from "./gsd-home.js";
 import { extractTrace } from "./session-forensics.js";
 import { nativeParseJsonlTail } from "./native-parser-bridge.js";
 import { MAX_JSONL_BYTES, parseJSONL } from "./jsonl-utils.js";
@@ -30,6 +30,7 @@ import { loadEffectiveGSDPreferences, loadGlobalGSDPreferences, getGlobalGSDPref
 import { showNextAction } from "../shared/tui.js";
 import { ensurePreferencesFile, serializePreferencesToFrontmatter } from "./commands-prefs-wizard.js";
 import { summarizeWorktreeTelemetry, percentile } from "./worktree-telemetry.js";
+import { homedir } from "node:os";
 // ─── Duplicate Detection ──────────────────────────────────────────────────────
 const DEDUP_PROMPT_SECTION = `
 ## Pre-Investigation: Duplicate Check (REQUIRED)
@@ -135,8 +136,7 @@ export async function handleForensics(args, ctx, pi) {
     // when import.meta.url resolves to the npm-global install path (Windows).
     let gsdSourceDir = dirname(fileURLToPath(import.meta.url));
     if (!existsSync(join(gsdSourceDir, "prompts"))) {
-        const gsdHome = process.env.GSD_HOME || join(getHomeDir(), ".gsd");
-        const fallback = join(gsdHome, "agent", "extensions", "gsd");
+        const fallback = join(gsdHome(), "agent", "extensions", "gsd");
         if (existsSync(join(fallback, "prompts")))
             gsdSourceDir = fallback;
     }
@@ -1115,7 +1115,13 @@ function redactForGitHub(text, basePath) {
     const pathRe = (p) => new RegExp(esc(p.replace(/\\/g, "/")).replace(/\//g, "[/\\\\]"), "gi");
     // Replace absolute paths
     result = result.replace(pathRe(basePath), ".");
-    result = result.replace(pathRe(getHomeDir()), "~");
+    // Redact GSD_HOME first (when it's outside ~), then OS home.
+    // Order matters: longer path must be replaced before the shorter prefix.
+    const gsdHomePath = gsdHome();
+    if (!gsdHomePath.startsWith(homedir())) {
+        result = result.replace(pathRe(gsdHomePath), "~/.gsd");
+    }
+    result = result.replace(pathRe(homedir()), "~");
     // Strip API key patterns
     result = result.replace(/sk-[a-zA-Z0-9]{20,}/g, "sk-***");
     result = result.replace(/Bearer\s+\S+/g, "Bearer ***");

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

@@ -26,6 +26,7 @@ import { GSDError, GSD_STALE_STATE } from "./errors.js";
 import { getGateIdsForTurn } from "./gate-registry.js";
 import { logError, logWarning } from "./workflow-logger.js";
 const _require = createRequire(import.meta.url);
+const BETTER_SQLITE3_PACKAGE = ["better", "sqlite3"].join("-");
 let providerName = null;
 let providerModule = null;
 let loadAttempted = false;
@@ -63,7 +64,7 @@ function loadProvider() {
         // unavailable
     }
     try {
-        const mod = _require("better-sqlite3");
+        const mod = _require(BETTER_SQLITE3_PACKAGE);
         if (typeof mod === "function" || (mod && mod.default)) {
             providerModule = mod.default || mod;
             providerName = "better-sqlite3";
@@ -1191,7 +1192,7 @@ export function openDatabase(path) {
         // node:sqlite loaded but failed to open this file — try better-sqlite3 as fallback.
         if (providerName === "node:sqlite") {
             try {
-                const mod = _require("better-sqlite3");
+                const mod = _require(BETTER_SQLITE3_PACKAGE);
                 const Db = (mod && mod.default) ? mod.default : mod;
                 if (typeof Db === "function") {
                     rawDb = new Db(path);

package/dist/resources/extensions/gsd/gsd-home.js

@@ -0,0 +1,29 @@
+/**
+ * GSD home directory resolution.
+ *
+ * Exports gsdHome() which returns the GSD configuration directory,
+ * defaulting to ~/.gsd with a GSD_HOME env var override.
+ *
+ * For the user's home directory, use os.homedir() directly — it handles
+ * platform-specific env lookup (USERPROFILE on Windows, HOME on POSIX)
+ * with appropriate fallbacks.
+ *
+ * @see https://github.com/gsd-build/gsd-2/issues/5015
+ */
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+/**
+ * Resolve the GSD home directory (typically ~/.gsd).
+ *
+ * `GSD_HOME` env var overrides the default location.
+ * Falls back to `homedir()/.gsd`.
+ *
+ * Always returns an absolute, normalized path — `resolve()` canonicalizes
+ * any relative or non-canonical `GSD_HOME` value so downstream comparison
+ * and redaction sites don't have to.
+ */
+export function gsdHome() {
+    return process.env.GSD_HOME
+        ? resolve(process.env.GSD_HOME)
+        : join(homedir(), ".gsd");
+}

package/dist/resources/extensions/gsd/guided-flow.js

@@ -18,12 +18,12 @@ import { clearLock } from "./crash-recovery.js";
 import { assessInterruptedSession, formatInterruptedSessionRunningMessage, formatInterruptedSessionSummary, } from "./interrupted-session.js";
 import { listUnitRuntimeRecords, clearUnitRuntimeRecord } from "./unit-runtime.js";
 import { resolveExpectedArtifactPath } from "./auto.js";
-import { getHomeDir } from "./home-dir.js";
+import { gsdHome } from "./gsd-home.js";
 import { gsdRoot, milestonesDir, resolveMilestoneFile, resolveSliceFile, resolveSlicePath, resolveGsdRootFile, relGsdRootFile, relMilestoneFile, relSliceFile, } from "./paths.js";
 import { join } from "node:path";
-import { readFileSync, existsSync, mkdirSync, readdirSync, unlinkSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync, readdirSync, rmSync, unlinkSync } from "node:fs";
 import { readSessionLockData, isSessionLockProcessAlive } from "./session-lock.js";
-import { nativeIsRepo, nativeInit } from "./native-git-bridge.js";
+import { nativeAddAll, nativeCommit, nativeHasCommittedHead, nativeIsRepo, nativeInit } from "./native-git-bridge.js";
 import { isInheritedRepo } from "./repo-identity.js";
 import { ensureGitignore, ensurePreferences, untrackRuntimeFiles } from "./gitignore.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
@@ -42,6 +42,7 @@ import { selectAndApplyModel } from "./auto-model-selection.js";
 import { DISCUSS_TOOLS_ALLOWLIST } from "./constants.js";
 import { getWorkflowTransportSupportError, getRequiredWorkflowToolsForGuidedUnit, supportsStructuredQuestions, } from "./workflow-mcp.js";
 import { runPreparation, formatCodebaseBrief, formatPriorContextBrief, } from "./preparation.js";
+import { verifyExpectedArtifact } from "./auto-recovery.js";
 // ─── Re-exports (preserve public API for existing importers) ────────────────
 export { MILESTONE_ID_RE, generateMilestoneSuffix, nextMilestoneId, extractMilestoneSeq, parseMilestoneId, milestoneIdSort, maxMilestoneNum, findMilestoneIds, reserveMilestoneId, claimReservedId, getReservedMilestoneIds, clearReservedMilestoneIds, } from "./milestone-ids.js";
 export { showQueue, handleQueueReorder, showQueueAdd, buildExistingMilestonesContext, } from "./guided-flow-queue.js";
@@ -53,7 +54,7 @@ function needsPlanV2Gate(state) {
         || state.phase === "completing-milestone";
 }
 function runPlanV2Gate(ctx, basePath, state) {
-    const prefs = loadEffectiveGSDPreferences()?.preferences;
+    const prefs = loadEffectiveGSDPreferences(basePath)?.preferences;
     const uokFlags = resolveUokFlags(prefs);
     if (!uokFlags.planV2 || !needsPlanV2Gate(state))
         return "pass";
@@ -81,6 +82,31 @@ const MAX_READY_REJECTS = 2;
 // suffix) with optional trailing punctuation.
 const READY_PHRASE_RE = /\bMilestone\s+M\d{3}[A-Z0-9-]*\s+ready\.?/i;
 const pendingAutoStartMap = new Map();
+const pendingDeepProjectSetupMap = new Map();
+const USER_DRIVEN_DEEP_SETUP_UNITS = new Set([
+    "discuss-project",
+    "discuss-requirements",
+    "research-decision",
+]);
+const FOREGROUND_DEEP_SETUP_RULE_NAMES = new Set([
+    "deep: pre-planning (no workflow prefs) → workflow-preferences",
+    "deep: pre-planning (no PROJECT) → discuss-project",
+    "deep: pre-planning (no REQUIREMENTS) → discuss-requirements",
+    "deep: pre-planning (no research decision) → research-decision",
+]);
+const LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS = new Set([
+    "PROJECT",
+    "REQUIREMENTS",
+    "RESEARCH-DECISION",
+    "RESEARCH-PROJECT",
+    "WORKFLOW-PREFS",
+]);
+const FOREGROUND_DEEP_SETUP_QUESTION_POLICY = `## Foreground Deep Setup Question Policy
+
+This stage is running inside the foreground \`/gsd new-project --deep\` interview. Ask user questions in plain chat only.
+
+- Do NOT call \`ask_user_questions\`, \`AskUserQuestion\`, or ToolSearch to discover user-input tools.
+- Ask one focused round, then stop and wait for the user's normal chat response.`;
 /**
  * Backward-compat bridge: returns a mutable reference to the entry matching
  * basePath, or the sole entry when only one session exists.
@@ -93,6 +119,39 @@ function _getPendingAutoStart(basePath) {
         return pendingAutoStartMap.values().next().value;
     return null;
 }
+function hasNestedFileOrSymlink(dir) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.isFile() || entry.isSymbolicLink())
+            return true;
+        if (entry.isDirectory() && hasNestedFileOrSymlink(join(dir, entry.name)))
+            return true;
+    }
+    return false;
+}
+function clearEmptyLegacyDeepSetupPseudoMilestones(basePath, entries) {
+    const mDir = milestonesDir(basePath);
+    const remaining = [];
+    for (const entry of entries) {
+        if (!LEGACY_DEEP_SETUP_PSEUDO_MILESTONE_DIRS.has(entry)) {
+            remaining.push(entry);
+            continue;
+        }
+        const entryPath = join(mDir, entry);
+        try {
+            if (hasNestedFileOrSymlink(entryPath)) {
+                remaining.push(entry);
+                continue;
+            }
+            rmSync(entryPath, { recursive: true, force: true });
+            logWarning("guided", `Self-heal: removed empty legacy deep setup pseudo-milestone directory ${entry}`);
+        }
+        catch (err) {
+            remaining.push(entry);
+            logWarning("guided", `legacy deep setup pseudo-milestone cleanup failed for ${entry}: ${err.message}`);
+        }
+    }
+    return remaining;
+}
 /**
  * Store pending auto-start state for a project.
  * Exported for testing (#2985).
@@ -113,6 +172,14 @@ export function clearPendingAutoStart(basePath) {
         pendingAutoStartMap.clear();
     }
 }
+export function clearPendingDeepProjectSetup(basePath) {
+    if (basePath) {
+        pendingDeepProjectSetupMap.delete(basePath);
+    }
+    else {
+        pendingDeepProjectSetupMap.clear();
+    }
+}
 /**
  * Returns the milestoneId being discussed for the given project.
  * When basePath is omitted and only one session is active, returns that
@@ -129,6 +196,122 @@ export function getDiscussionMilestoneId(basePath) {
     }
     return null;
 }
+function _getPendingDeepProjectSetup(basePath) {
+    if (basePath)
+        return pendingDeepProjectSetupMap.get(basePath) ?? null;
+    if (pendingDeepProjectSetupMap.size === 1)
+        return pendingDeepProjectSetupMap.values().next().value;
+    return null;
+}
+function getDeepSetupSessionId(ctx) {
+    return ctx?.sessionManager?.getSessionId?.();
+}
+function _getPendingDeepProjectSetupForContext(ctx, basePath) {
+    if (basePath) {
+        const direct = pendingDeepProjectSetupMap.get(basePath);
+        if (direct)
+            return direct;
+    }
+    if (!ctx)
+        return _getPendingDeepProjectSetup();
+    const sessionId = getDeepSetupSessionId(ctx);
+    if (sessionId) {
+        const matches = [...pendingDeepProjectSetupMap.values()].filter(entry => entry.sessionId === sessionId);
+        if (matches.length === 1)
+            return matches[0];
+    }
+    const matches = [...pendingDeepProjectSetupMap.values()].filter(entry => entry.ctx === ctx);
+    return matches.length === 1 ? matches[0] : null;
+}
+export function getPendingDeepProjectSetupUnitForContext(ctx, basePath) {
+    const entry = _getPendingDeepProjectSetupForContext(ctx, basePath);
+    if (!entry?.currentUnitType || !entry.currentUnitId)
+        return null;
+    return {
+        unitType: entry.currentUnitType,
+        unitId: entry.currentUnitId,
+    };
+}
+export async function startDeepProjectSetupForeground(ctx, pi, basePath, step) {
+    const entry = {
+        ctx,
+        pi,
+        basePath,
+        step,
+        createdAt: Date.now(),
+        sessionId: getDeepSetupSessionId(ctx),
+    };
+    pendingDeepProjectSetupMap.set(basePath, entry);
+    await dispatchNextDeepProjectSetupStage(entry);
+}
+export async function checkDeepProjectSetupAfterTurn(_event, ctx, basePath) {
+    const entry = _getPendingDeepProjectSetupForContext(ctx, basePath);
+    if (!entry)
+        return false;
+    if (entry.currentUnitType && entry.currentUnitId) {
+        const artifactReady = verifyExpectedArtifact(entry.currentUnitType, entry.currentUnitId, entry.basePath);
+        if (!artifactReady) {
+            return false;
+        }
+    }
+    return dispatchNextDeepProjectSetupStage(entry);
+}
+async function dispatchNextDeepProjectSetupStage(entry) {
+    invalidateAllCaches();
+    const prefs = loadEffectiveGSDPreferences(entry.basePath)?.preferences;
+    const { DISPATCH_RULES, hasPendingDeepStage } = await import("./auto-dispatch.js");
+    if (!hasPendingDeepStage(prefs, entry.basePath)) {
+        pendingDeepProjectSetupMap.delete(entry.basePath);
+        startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+        return true;
+    }
+    const state = await deriveState(entry.basePath);
+    const dispatchCtx = {
+        basePath: entry.basePath,
+        mid: "PROJECT",
+        midTitle: "Project setup",
+        state,
+        prefs,
+        // Claude Code currently surfaces workflow-MCP question calls as tool-request
+        // UI that can be cancelled outside the normal chat flow. During the
+        // foreground deep project setup interview, keep user input in plain chat so
+        // `/gsd new-project --deep` cannot bounce through cancelled tool requests.
+        structuredQuestionsAvailable: "false",
+    };
+    let result = null;
+    for (const rule of DISPATCH_RULES) {
+        // Only evaluate foreground setup gates here. Later deep rules such as
+        // research-project have dispatch-time side effects (e.g. claiming an
+        // inflight marker) and must be left to auto-mode once the interview is
+        // complete.
+        if (!FOREGROUND_DEEP_SETUP_RULE_NAMES.has(rule.name))
+            continue;
+        result = await rule.match(dispatchCtx);
+        if (result)
+            break;
+    }
+    if (!result || result.action !== "dispatch") {
+        if (result?.action === "stop") {
+            entry.ctx.ui.notify(result.reason, result.level);
+        }
+        else if (hasPendingDeepStage(prefs, entry.basePath)) {
+            pendingDeepProjectSetupMap.delete(entry.basePath);
+            startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+            return true;
+        }
+        return false;
+    }
+    if (!USER_DRIVEN_DEEP_SETUP_UNITS.has(result.unitType)) {
+        pendingDeepProjectSetupMap.delete(entry.basePath);
+        startAutoDetached(entry.ctx, entry.pi, entry.basePath, false, { step: entry.step });
+        return true;
+    }
+    entry.currentUnitType = result.unitType;
+    entry.currentUnitId = result.unitId;
+    entry.createdAt = Date.now();
+    await dispatchWorkflow(entry.pi, `${result.prompt}\n\n${FOREGROUND_DEEP_SETUP_QUESTION_POLICY}`, "gsd-run", entry.ctx, result.unitType);
+    return true;
+}
 /** Called from agent_end to check if auto-mode should start after discuss */
 export function checkAutoStartAfterDiscuss() {
     const entry = _getPendingAutoStart();
@@ -357,7 +540,12 @@ const emptyTurnCounterByBase = new Map();
 const MAX_EMPTY_TURN_RETRIES = 2;
 // Phrases that indicate the LLM is about to do something but has not yet.
 // Kept tight to avoid flagging legitimate narration like "I'll wait for your answer."
-const COMMIT_INTENT_RE = /\b(?:I['’]ll|I will|Next,? I['’]ll|Now I['’]ll|Let me|I['’]m going to|I am going to)\s+(?:now\s+)?(?:write|create|call|invoke|update|add|make|run|execute|generate|produce|emit|compose|implement|save|apply|commit)\b/i;
+//
+// "make" was previously in the verb list but matches conversational meta phrases
+// like "Let me make sure I understand…" which are NOT action announcements —
+// removed to prevent the empty-turn nudge from auto-replying to user questions
+// in discuss flows.
+const COMMIT_INTENT_RE = /\b(?:I['’]ll|I will|Next,? I['’]ll|Now I['’]ll|Let me|I['’]m going to|I am going to)\s+(?:now\s+)?(?:write|create|call|invoke|update|add|run|execute|generate|produce|emit|compose|implement|save|apply|commit)\b/i;
 /**
  * Reset the empty-turn counter for a basePath after a successful tool-use turn.
  * Called from handleAgentEnd when the last message contains tool_use blocks.
@@ -385,12 +573,14 @@ export function maybeHandleEmptyIntentTurn(event, isAuto) {
     // path, handled by maybeHandleReadyPhraseWithoutFiles.
     if (READY_PHRASE_RE.test(text))
         return false;
-    // Skip if the LLM is clearly handing back to the user. Keep the heuristic
-    // tight: a trailing question mark on the last non-empty line is the common
-    // signal for "I asked the user a question and stopped."
+    // Skip if the LLM is clearly handing back to the user. Last-line `?` is
+    // the strongest signal, but discuss flows often end with a freeform
+    // question followed by a closing remark ("…what should we build? I'll
+    // pick one if you don't care."). Treat ANY non-empty line ending in `?`
+    // as a question-asked signal — false negatives here auto-reply to the
+    // user, which is a much worse failure mode than a missed nudge.
     const lines = text.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
-    const lastLine = lines[lines.length - 1] ?? "";
-    if (lastLine.endsWith("?"))
+    if (lines.some((l) => l.endsWith("?")))
         return false;
     // Must contain a commit-intent phrase — this is the stall we care about.
     if (!COMMIT_INTENT_RE.test(text))
@@ -496,7 +686,7 @@ async function dispatchWorkflow(pi, note, customType = "gsd-run", ctx, unitType)
             removed: currentTools.length - scopedTools.length,
         });
     }
-    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(getHomeDir(), ".gsd", "agent", "GSD-WORKFLOW.md");
+    const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
     const workflow = readFileSync(workflowPath, "utf-8");
     pi.sendMessage({
         customType,
@@ -1288,6 +1478,19 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     // ── Ensure .gitignore has baseline patterns ──────────────────────────
     ensureGitignore(basePath);
     untrackRuntimeFiles(basePath);
+    // Deep setup can pre-create .gsd/PREFERENCES.md before the normal init
+    // wizard path runs. If that path also initialized git, make HEAD reachable
+    // now so later worktree/git-log operations do not run on an unborn branch.
+    if (nativeIsRepo(basePath) && !nativeHasCommittedHead(basePath)) {
+        try {
+            nativeAddAll(basePath);
+            nativeCommit(basePath, "chore: init project");
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logWarning("guided", `initial git commit failed; worktree isolation will remain disabled until HEAD exists: ${message}`);
+        }
+    }
     {
         const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
         await ensureDbOpen(basePath);
@@ -1343,6 +1546,22 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
     catch (err) {
         logWarning("guided", `STATE.md rebuild failed: ${err.message}`);
     }
+    // ── Deep planning mode kickoff ────────────────────────────────────────
+    // When `planning_depth: deep` is set (e.g. via `/gsd new-project --deep`)
+    // and any project-level stage gate is still pending, keep the user-question
+    // stages in the foreground conversation. Auto-mode is resumed only after
+    // the project interview artifacts exist, so questions do not look like
+    // cancelled auto-mode runs.
+    // Light mode and fully-completed deep projects fall through to the
+    // standard wizard below.
+    {
+        const prefs = loadEffectiveGSDPreferences(basePath)?.preferences;
+        const { hasPendingDeepStage } = await import("./auto-dispatch.js");
+        if (hasPendingDeepStage(prefs, basePath)) {
+            await startDeepProjectSetupForeground(ctx, pi, basePath, stepMode);
+            return;
+        }
+    }
     const planV2GateDecision = runPlanV2Gate(ctx, basePath, state);
     if (planV2GateDecision === "block")
         return;
@@ -1376,7 +1595,7 @@ export async function showSmartEntry(ctx, pi, basePath, options) {
             const mDir = milestonesDir(basePath);
             if (existsSync(mDir)) {
                 try {
-                    const entries = readdirSync(mDir);
+                    const entries = clearEmptyLegacyDeepSetupPseudoMilestones(basePath, readdirSync(mDir));
                     if (entries.length > 0) {
                         ctx.ui.notify(`Milestone directory has ${entries.length} entries but none were recognized as milestones. ` +
                             `This may indicate a corrupted state or wrong working directory. Run \`/gsd doctor\` to diagnose.`, "warning");