gsd-pi 2.78.1-dev.82bcf6b71 → 2.78.1-dev.84c045fd2

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

@@ -64,6 +64,7 @@ const QUEUE_SAFE_TOOLS = new Set([
 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 verifiedDepthMilestones = new Set<string>();
+const verifiedApprovalGates = new Set<string>();
 let activeQueuePhase = false;
 
 /**
@@ -87,17 +88,22 @@ const GATE_QUESTION_PATTERNS = [
 
 /**
  * Tools that are safe to call while a gate is pending.
- * Includes read-only tools and ask_user_questions itself (so the model can re-ask).
+ * Only ask_user_questions may run: once the assistant asks for confirmation,
+ * further reads/searches bury the actual question in tool output.
  */
 const GATE_SAFE_TOOLS = new Set([
   "ask_user_questions",
-  "read", "grep", "find", "ls", "glob",
-  "search-the-web", "resolve_library", "get_library_docs", "fetch_page",
-  "search_and_read",
 ]);
 
+export function canonicalToolName(toolName: string): string {
+  if (!toolName.startsWith("mcp__")) return toolName;
+  const toolSeparator = toolName.indexOf("__", "mcp__".length);
+  return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
+}
+
 export interface WriteGateSnapshot {
   verifiedDepthMilestones: string[];
+  verifiedApprovalGates?: string[];
   activeQueuePhase: boolean;
   pendingGateId: string | null;
 }
@@ -120,6 +126,7 @@ function writeGateSnapshotPath(basePath: string = process.cwd()): string {
 function currentWriteGateSnapshot(): WriteGateSnapshot {
   return {
     verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
+    verifiedApprovalGates: [...verifiedApprovalGates].sort(),
     activeQueuePhase,
     pendingGateId,
   };
@@ -160,8 +167,12 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
   const verified = Array.isArray(record.verifiedDepthMilestones)
     ? record.verifiedDepthMilestones.filter((item): item is string => typeof item === "string")
     : [];
+  const verifiedGates = Array.isArray(record.verifiedApprovalGates)
+    ? record.verifiedApprovalGates.filter((item): item is string => typeof item === "string")
+    : [];
   return {
     verifiedDepthMilestones: [...new Set(verified)].sort(),
+    verifiedApprovalGates: [...new Set(verifiedGates)].sort(),
     activeQueuePhase: record.activeQueuePhase === true,
     pendingGateId: typeof record.pendingGateId === "string" ? record.pendingGateId : null,
   };
@@ -169,6 +180,7 @@ function normalizeWriteGateSnapshot(value: unknown): WriteGateSnapshot {
 
 const EMPTY_SNAPSHOT: WriteGateSnapshot = {
   verifiedDepthMilestones: [],
+  verifiedApprovalGates: [],
   activeQueuePhase: false,
   pendingGateId: null,
 };
@@ -220,12 +232,14 @@ export function setQueuePhaseActive(active: boolean): void {
 
 export function resetWriteGateState(): void {
   verifiedDepthMilestones.clear();
+  verifiedApprovalGates.clear();
   pendingGateId = null;
   persistWriteGateSnapshot();
 }
 
 export function clearDiscussionFlowState(): void {
   verifiedDepthMilestones.clear();
+  verifiedApprovalGates.clear();
   activeQueuePhase = false;
   pendingGateId = null;
   clearPersistedWriteGateSnapshot();
@@ -237,6 +251,20 @@ export function markDepthVerified(milestoneId?: string | null, basePath: string
   persistWriteGateSnapshot(basePath);
 }
 
+export function markApprovalGateVerified(gateId?: string | null, basePath: string = process.cwd()): void {
+  if (!gateId) return;
+  verifiedApprovalGates.add(gateId);
+  persistWriteGateSnapshot(basePath);
+}
+
+export function isApprovalGateVerifiedInSnapshot(
+  snapshot: WriteGateSnapshot,
+  gateId?: string | null,
+): boolean {
+  if (!gateId) return false;
+  return (snapshot.verifiedApprovalGates ?? []).includes(gateId);
+}
+
 /**
  * Check whether a question ID matches a recognized gate pattern.
  */
@@ -266,6 +294,9 @@ function extractContextMilestoneId(inputPath: string): string | null {
  */
 export function setPendingGate(gateId: string): void {
   pendingGateId = gateId;
+  verifiedApprovalGates.delete(gateId);
+  const milestoneId = extractDepthVerificationMilestoneId(gateId);
+  if (milestoneId) verifiedDepthMilestones.delete(milestoneId);
   persistWriteGateSnapshot();
 }
 
@@ -289,7 +320,7 @@ export function getPendingGate(): string | null {
  * is pending (ask_user_questions was called but not confirmed).
  *
  * Returns { block: true, reason } if the tool should be blocked.
- * Read-only tools and ask_user_questions itself are always allowed.
+ * ask_user_questions itself is allowed so the model can re-ask the gate.
  */
 export function shouldBlockPendingGate(
   toolName: string,
@@ -307,16 +338,14 @@ export function shouldBlockPendingGateInSnapshot(
 ): { block: boolean; reason?: string } {
   if (!snapshot.pendingGateId) return { block: false };
 
-  if (GATE_SAFE_TOOLS.has(toolName)) return { block: false };
-
-  // Bash read-only commands are also safe
-  if (toolName === "bash") return { block: false }; // bash is checked separately below
+  if (GATE_SAFE_TOOLS.has(canonicalToolName(toolName))) return { block: false };
 
   return {
     block: true,
     reason: [
       `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
-      `You MUST re-call ask_user_questions with the gate question before making any other tool calls.`,
+      `The assistant already asked for user confirmation, so do not call more tools.`,
+      `Wait for the user's answer, or re-call ask_user_questions with the gate question if the question was not delivered.`,
       `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
       `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
       `Do NOT proceed, do NOT use alternative approaches, do NOT skip the gate.`,
@@ -326,7 +355,7 @@ export function shouldBlockPendingGateInSnapshot(
 
 /**
  * Check whether a bash command should be blocked because a discussion gate is pending.
- * Read-only bash commands are allowed; mutating commands are blocked.
+ * All bash is blocked while waiting for confirmation so the question stays visible.
  */
 export function shouldBlockPendingGateBash(
   command: string,
@@ -344,14 +373,12 @@ export function shouldBlockPendingGateBashInSnapshot(
 ): { block: boolean; reason?: string } {
   if (!snapshot.pendingGateId) return { block: false };
 
-  // Allow read-only bash commands
-  if (BASH_READ_ONLY_RE.test(command)) return { block: false };
-
   return {
     block: true,
     reason: [
       `HARD BLOCK: Discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
-      `You MUST re-call ask_user_questions with the gate question before running mutating commands.`,
+      `The assistant already asked for user confirmation, so do not run bash commands.`,
+      `Wait for the user's answer, or re-call ask_user_questions with the gate question if the question was not delivered.`,
       `If the previous ask_user_questions call failed, errored, was cancelled, or the user's response`,
       `did not match a provided option, you MUST re-ask — never rationalize past the block.`,
     ].join(" "),
@@ -465,6 +492,56 @@ export function shouldBlockContextArtifactSaveInSnapshot(
   };
 }
 
+const FINAL_ROOT_ARTIFACTS = new Set(["PROJECT", "REQUIREMENTS"]);
+
+function requiredRootApprovalGateForArtifact(artifactType: string): string | null {
+  if (artifactType === "PROJECT") return "depth_verification_project_confirm";
+  if (artifactType === "REQUIREMENTS") return "depth_verification_requirements_confirm";
+  return null;
+}
+
+/**
+ * Final root project artifacts are the output of the project/requirements
+ * approval gates. Drafts remain writable so the agent can prepare previews,
+ * but PROJECT.md and REQUIREMENTS.md must wait for explicit approval. Deep
+ * mode can additionally require a positive verified gate, not just no pending
+ * gate, so missed detectors fail closed.
+ */
+export function shouldBlockRootArtifactSaveInSnapshot(
+  snapshot: WriteGateSnapshot,
+  artifactType: string,
+  opts: { requireVerifiedApproval?: boolean } = {},
+): { block: boolean; reason?: string } {
+  if (!FINAL_ROOT_ARTIFACTS.has(artifactType)) return { block: false };
+
+  if (snapshot.pendingGateId) {
+    return {
+      block: true,
+      reason: [
+        `HARD BLOCK: Cannot save ${artifactType}.md because discussion gate "${snapshot.pendingGateId}" has not been confirmed by the user.`,
+        `This is a mechanical gate — wait for explicit user approval before writing final project setup artifacts.`,
+        `If approval was requested in plain text, the user must reply with explicit approval before this write is allowed.`,
+      ].join(" "),
+    };
+  }
+
+  if (opts.requireVerifiedApproval) {
+    const requiredGate = requiredRootApprovalGateForArtifact(artifactType);
+    if (requiredGate && !isApprovalGateVerifiedInSnapshot(snapshot, requiredGate)) {
+      return {
+        block: true,
+        reason: [
+          `HARD BLOCK: Cannot save ${artifactType}.md before explicit approval gate "${requiredGate}" is verified.`,
+          `Deep planning root artifacts are fail-closed: absence of a pending gate is not approval.`,
+          `Ask the user to confirm the ${artifactType}.md preview and wait for an explicit approval response.`,
+        ].join(" "),
+      };
+    }
+  }
+
+  return { block: false };
+}
+
 /**
  * Queue-mode execution guard (#2545).
  *

package/src/resources/extensions/gsd/branch-patterns.ts

@@ -3,7 +3,7 @@
  *
  * gsd/<worktree>/<milestone>/<slice>  → SLICE_BRANCH_RE
  * gsd/quick/<id>-<slug>               → QUICK_BRANCH_RE
- * gsd/<workflow>/<...>                 → WORKFLOW_BRANCH_RE (non-milestone gsd/ branches)
+ * gsd/<workflow-template>/<...>        → WORKFLOW_BRANCH_RE
  */
 
 /** Matches gsd/ slice branches: gsd/[worktree/]M001[-hash]/S01 */
@@ -12,5 +12,5 @@ export const SLICE_BRANCH_RE = /^gsd\/(?:([a-zA-Z0-9_-]+)\/)?(M\d+(?:-[a-z0-9]{6
 /** Matches gsd/quick/ task branches */
 export const QUICK_BRANCH_RE = /^gsd\/quick\//;
 
-/** Matches gsd/ workflow branches (non-milestone, e.g. gsd/workflow-name/...) */
-export const WORKFLOW_BRANCH_RE = /^gsd\/(?!M\d)[\w-]+\//;
+/** Matches GSD-generated workflow template branches, not arbitrary user gsd/* branches. */
+export const WORKFLOW_BRANCH_RE = /^gsd\/(?:hotfix|bugfix|small-feature|refactor|spike|security-audit|dep-upgrade|full-project)\//;

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

@@ -1,10 +1,9 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 
 import { loadRegistry } from "../workflow-templates.js";
+import { gsdHome } from "../gsd-home.js";
 
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
 
 export interface GsdCommandDefinition {
   cmd: string;
@@ -14,7 +13,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|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";
+  "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";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -62,6 +61,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "inspect", desc: "Show SQLite DB diagnostics" },
   { cmd: "knowledge", desc: "Add persistent project knowledge (rule, pattern, or lesson)" },
   { cmd: "new-milestone", desc: "Create a milestone from a specification document (headless)" },
+  { cmd: "new-project", desc: "Bootstrap a new project (use --deep for staged project-level discovery)" },
   { cmd: "parallel", desc: "Parallel milestone orchestration (start, status, stop, merge, watch)" },
   { cmd: "cmux", desc: "Manage cmux integration (status, sidebar, notifications, splits)" },
   { cmd: "park", desc: "Park a milestone — skip without deleting" },
@@ -84,6 +84,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "scan", desc: "Rapid codebase assessment — lightweight alternative to full map (--focus tech|arch|quality|concerns|tech+arch)" },
   { cmd: "language", desc: "Set or clear the global response language (e.g. /gsd language Chinese)" },
   { cmd: "worktree", desc: "Manage worktrees from the TUI (list, merge, clean, remove)" },
+  { cmd: "eval-review", desc: "Audit a slice's AI evaluation strategy and write a scored EVAL-REVIEW.md (--force, --show)" },
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
@@ -325,7 +326,7 @@ function filterOptions(
 
 function getExtensionCompletions(prefix: string, action: string) {
   try {
-    const extDir = join(gsdHome, "agent", "extensions");
+    const extDir = join(gsdHome(), "agent", "extensions");
     const ids: Array<{ id: string; name: string }> = [];
     for (const entry of readdirSync(extDir, { withFileTypes: true })) {
       if (!entry.isDirectory()) continue;
@@ -414,7 +415,7 @@ function resolveProjectRootForCompletion(basePath: string): string {
   const gsdIdx = basePath.indexOf(gsdMarker);
   const candidate = gsdIdx !== -1 ? basePath.slice(0, gsdIdx) : basePath.slice(0, segment.gsdIdx);
 
-  const normalizedGsdHome = normalizePathForCompare(gsdHome);
+  const normalizedGsdHome = normalizePathForCompare(gsdHome());
   const candidateGsdPath = normalizePathForCompare(join(candidate, ".gsd"));
   if (candidateGsdPath === normalizedGsdHome || candidateGsdPath.startsWith(`${normalizedGsdHome}/`)) {
     return resolveProjectRootFromGitFile(basePath) ?? basePath;
@@ -523,7 +524,7 @@ export function getGsdArgumentCompletions(prefix: string) {
       const base = resolveProjectRootForCompletion(process.cwd());
       scanDir(join(base, ".gsd", "workflows"), "project");
       scanDir(join(base, ".gsd", "workflow-defs"), "project-legacy");
-      scanDir(join(gsdHome, "workflows"), "global");
+      scanDir(join(gsdHome(), "workflows"), "global");
     } catch { /* ignore */ }
     // Also include bundled template names.
     try {

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

@@ -5,6 +5,7 @@ import { validateDirectory } from "../validate-directory.js";
 import { resolveProjectRoot } from "../worktree.js";
 import { showNextAction } from "../../shared/tui.js";
 import { handleStatus } from "./handlers/core.js";
+import { homedir } from "node:os";
 
 export interface GsdDispatchContext {
   ctx: ExtensionCommandContext;
@@ -23,13 +24,29 @@ export class GSDNoProjectError extends Error {
   }
 }
 
+let commandCwdOverride: string | null = null;
+
+export async function withCommandCwd<T>(cwd: string | undefined, fn: () => Promise<T>): Promise<T> {
+  const previous = commandCwdOverride;
+  commandCwdOverride = cwd || null;
+  try {
+    return await fn();
+  } finally {
+    commandCwdOverride = previous;
+  }
+}
+
 export function projectRoot(): string {
   let cwd: string;
-  try {
-    cwd = process.cwd();
-  } catch {
-    // cwd directory was deleted (e.g. worktree teardown) — fall back to HOME (#3598)
-    cwd = process.env.HOME ?? "/";
+  if (commandCwdOverride) {
+    cwd = commandCwdOverride;
+  } else {
+    try {
+      cwd = process.cwd();
+    } catch {
+      // cwd directory was deleted (e.g. worktree teardown) — fall back to home (#3598)
+      cwd = homedir();
+    }
   }
   const root = resolveProjectRoot(cwd);
   const pathToCheck = root !== cwd ? cwd : root;
@@ -40,6 +57,24 @@ export function projectRoot(): string {
   return root;
 }
 
+export function currentDirectoryRoot(): string {
+  let cwd: string;
+  if (commandCwdOverride) {
+    cwd = commandCwdOverride;
+  } else {
+    try {
+      cwd = process.cwd();
+    } catch {
+      cwd = process.env.HOME ?? "/";
+    }
+  }
+  const result = validateDirectory(cwd);
+  if (result.severity === "blocked") {
+    throw new GSDNoProjectError(result.reason ?? "GSD must be run inside a project directory.");
+  }
+  return cwd;
+}
+
 export async function guardRemoteSession(
   ctx: ExtensionCommandContext,
   pi: ExtensionAPI,
@@ -122,4 +157,3 @@ export async function guardRemoteSession(
 
   return choice === "force";
 }
-

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

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 
-import { GSDNoProjectError } from "./context.js";
+import { GSDNoProjectError, withCommandCwd } from "./context.js";
 import { handleAutoCommand } from "./handlers/auto.js";
 import { handleCoreCommand } from "./handlers/core.js";
 import { handleOpsCommand } from "./handlers/ops.js";
@@ -22,12 +22,16 @@ export async function handleGSDCommand(
     () => handleOpsCommand(trimmed, ctx, pi),
   ];
 
+  let handled = false;
   try {
-    for (const handler of handlers) {
-      if (await handler()) {
-        return;
+    handled = await withCommandCwd(ctx.cwd, async () => {
+      for (const handler of handlers) {
+        if (await handler()) {
+          return true;
+        }
       }
-    }
+      return false;
+    });
   } catch (err) {
     if (err instanceof GSDNoProjectError) {
       ctx.ui.notify(
@@ -39,5 +43,7 @@ export async function handleGSDCommand(
     throw err;
   }
 
+  if (handled) return;
+
   ctx.ui.notify(`Unknown: /gsd ${trimmed}. Run /gsd help for available commands.`, "warning");
 }

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

@@ -150,7 +150,8 @@ export async function handleAutoCommand(trimmed: string, ctx: ExtensionCommandCo
 
   if (trimmed === "") {
     if (!(await guardRemoteSession(ctx, pi))) return true;
-    startAutoDetached(ctx, pi, projectRoot(), false, { step: true });
+    const { showSmartEntry } = await import("../../guided-flow.js");
+    await showSmartEntry(ctx, pi, projectRoot(), { step: true });
     return true;
   }
 

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -64,6 +64,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd pause          Pause auto-mode (preserves state, /gsd auto to resume)",
     "  /gsd discuss        Start guided milestone/slice discussion",
     "  /gsd new-milestone  Create milestone from headless context (used by gsd headless)",
+    "  /gsd new-project    Bootstrap a new project (use --deep for staged project-level discovery)",
     "  /gsd quick          Execute a quick task without full planning overhead",
     "  /gsd dispatch       Dispatch a specific phase directly  [research|plan|execute|complete|uat|replan]",
     "  /gsd parallel       Parallel milestone orchestration  [start|status|stop|pause|resume|merge|watch]",
@@ -105,6 +106,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd backlog        Manage backlog items  [add|promote|remove|list]",
     "  /gsd pr-branch      Create a clean PR branch filtering .gsd/ commits  [--dry-run|--name]",
     "  /gsd add-tests      Generate tests for completed slices",
+    "  /gsd eval-review <sliceId>  Audit a slice's AI evaluation strategy  [--force|--show]",
     "  /gsd scan           Rapid codebase assessment  [--focus tech|arch|quality|concerns|tech+arch]",
     "",
     "SETUP & CONFIGURATION",

package/src/resources/extensions/gsd/commands/handlers/ops.ts

@@ -246,6 +246,11 @@ Examples:
     await handleAddTests(trimmed.replace(/^add-tests\s*/, "").trim(), ctx, pi);
     return true;
   }
+  if (trimmed === "eval-review" || trimmed.startsWith("eval-review ")) {
+    const { handleEvalReview } = await import("../../commands-eval-review.js");
+    await handleEvalReview(trimmed.replace(/^eval-review\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   if (trimmed === "extract-learnings" || trimmed.startsWith("extract-learnings ")) {
     const { handleExtractLearnings } = await import("../../commands-extract-learnings.js");
     await handleExtractLearnings(trimmed.replace(/^extract-learnings\s*/, "").trim(), ctx, pi);

package/src/resources/extensions/gsd/commands/handlers/workflow.ts

@@ -11,9 +11,10 @@ import { gsdRoot } from "../../paths.js";
 import { deriveState } from "../../state.js";
 import { isParked, parkMilestone, unparkMilestone } from "../../milestone-actions.js";
 import { loadEffectiveGSDPreferences } from "../../preferences.js";
+import { setPlanningDepth } from "../../planning-depth.js";
 import { nextMilestoneId } from "../../milestone-ids.js";
 import { findMilestoneIds } from "../../guided-flow.js";
-import { projectRoot } from "../context.js";
+import { currentDirectoryRoot, projectRoot } from "../context.js";
 import { createRun, listRuns } from "../../run-manager.js";
 import {
   setActiveEngineId,
@@ -525,9 +526,14 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
     await handleQuick(trimmed.replace(/^quick\s*/, "").trim(), ctx, pi);
     return true;
   }
-  if (trimmed === "new-milestone") {
+  if (trimmed === "new-milestone" || trimmed.startsWith("new-milestone ")) {
     if (requireNotAutoActive("/gsd new-milestone", ctx)) return true;
     const basePath = projectRoot();
+    const args = trimmed.replace(/^new-milestone\s*/, "").trim();
+    if (/(^|\s)--deep(\s|$)/.test(args)) {
+      setPlanningDepth(basePath, "deep");
+      ctx.ui.notify("Deep planning mode enabled (.gsd/PREFERENCES.md updated).", "info");
+    }
     const headlessContextPath = join(gsdRoot(basePath), "runtime", "headless-context.md");
     if (existsSync(headlessContextPath)) {
       const seedContext = readFileSync(headlessContextPath, "utf-8");
@@ -539,6 +545,21 @@ export async function handleWorkflowCommand(trimmed: string, ctx: ExtensionComma
     }
     return true;
   }
+  if (trimmed === "new-project" || trimmed.startsWith("new-project ")) {
+    // Direct entrypoint for new-project bootstrap.
+    // Routes through showSmartEntry (same as new-milestone for first project),
+    // but accepts --deep to opt into staged project-level discovery (deep mode).
+    if (requireNotAutoActive("/gsd new-project", ctx)) return true;
+    const basePath = currentDirectoryRoot();
+    const args = trimmed.replace(/^new-project\s*/, "").trim();
+    if (/(^|\s)--deep(\s|$)/.test(args)) {
+      setPlanningDepth(basePath, "deep");
+      ctx.ui.notify("Deep planning mode enabled (.gsd/PREFERENCES.md updated).", "info");
+    }
+    const { showSmartEntry } = await import("../../guided-flow.js");
+    await showSmartEntry(ctx, pi, basePath);
+    return true;
+  }
   if (trimmed === "start" || trimmed.startsWith("start ")) {
     await handleStart(trimmed.replace(/^start\s*/, "").trim(), ctx, pi);
     return true;

package/src/resources/extensions/gsd/commands-bootstrap.ts

@@ -38,6 +38,7 @@ const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "inspect", desc: "Show SQLite DB diagnostics" },
   { cmd: "knowledge", desc: "Add persistent project knowledge" },
   { cmd: "new-milestone", desc: "Create a milestone from a specification document" },
+  { cmd: "new-project", desc: "Bootstrap a new project (use --deep for staged project-level discovery)" },
   { cmd: "parallel", desc: "Parallel milestone orchestration" },
   { cmd: "park", desc: "Park a milestone" },
   { cmd: "unpark", desc: "Reactivate a parked milestone" },
@@ -86,6 +87,12 @@ function getGsdArgumentCompletions(prefix: string) {
     ], "next");
   }
 
+  if ((parts[0] === "new-project" || parts[0] === "new-milestone") && parts.length <= 2) {
+    return filterStartsWith(partial, [
+      { cmd: "--deep", desc: "Enable deep planning mode (staged project-level discovery)" },
+    ], parts[0]);
+  }
+
   if (parts[0] === "mode" && parts.length <= 2) {
     return filterStartsWith(partial, [
       { cmd: "global", desc: "Edit global workflow mode" },

package/src/resources/extensions/gsd/commands-codebase.ts

@@ -16,6 +16,7 @@ import {
 } from "./codebase-generator.js";
 import { loadEffectiveGSDPreferences } from "./preferences.js";
 import type { CodebaseMapOptions } from "./codebase-generator.js";
+import { currentDirectoryRoot } from "./commands/context.js";
 
 const USAGE =
   "Usage: /gsd codebase [generate|update|stats]\n\n" +
@@ -36,7 +37,7 @@ export async function handleCodebase(
   ctx: ExtensionCommandContext,
   _pi: ExtensionAPI,
 ): Promise<void> {
-  const basePath = process.cwd();
+  const basePath = currentDirectoryRoot();
   const parts = args.trim().split(/\s+/);
   const sub = parts[0] ?? "";
 

package/src/resources/extensions/gsd/commands-config.ts

@@ -8,7 +8,7 @@ import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
 import { AuthStorage } from "@gsd/pi-coding-agent";
 import { existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
-import { getHomeDir } from "./home-dir.js";
+import { gsdHome } from "./gsd-home.js";
 
 /**
  * Tool API key configurations.
@@ -35,7 +35,7 @@ function getStoredToolKey(auth: AuthStorage, providerId: string): string | undef
  */
 export function loadToolApiKeys(): void {
   try {
-    const authPath = join(getHomeDir(), ".gsd", "agent", "auth.json");
+    const authPath = join(gsdHome(), "agent", "auth.json");
     if (!existsSync(authPath)) return;
 
     const auth = AuthStorage.create(authPath);
@@ -51,7 +51,7 @@ export function loadToolApiKeys(): void {
 }
 
 export function getConfigAuthStorage(): AuthStorage {
-  const authPath = join(getHomeDir(), ".gsd", "agent", "auth.json");
+  const authPath = join(gsdHome(), "agent", "auth.json");
   mkdirSync(dirname(authPath), { recursive: true });
   return AuthStorage.create(authPath);
 }

package/src/resources/extensions/gsd/commands-debug.ts

@@ -116,6 +116,8 @@ export async function handleDebug(args: string, ctx: ExtensionCommandContext, pi
     try {
       const created = createDebugSession(basePath, { issue });
       const s = created.session;
+      const canDispatch = pi != null && typeof (pi as ExtensionAPI).sendMessage === "function";
+      const dispatchNote = canDispatch ? `\ndispatchMode=find_and_fix` : "";
       ctx.ui.notify(
         [
           `Debug session started: ${s.slug}`,
@@ -123,9 +125,33 @@ export async function handleDebug(args: string, ctx: ExtensionCommandContext, pi
           `Artifact: ${created.artifactPath}`,
           `Log: ${s.logPath}`,
           `Next: /gsd debug status ${s.slug} or /gsd debug continue ${s.slug}`,
-        ].join("\n"),
+        ].join("\n") + dispatchNote,
         "info",
       );
+      if (canDispatch) {
+        try {
+          const prompt = loadPrompt("debug-session-manager", {
+            goal: "find_and_fix",
+            issue: s.issue,
+            slug: s.slug,
+            mode: s.mode,
+            workingDirectory: basePath,
+            checkpointContext: "",
+            tddContext: "",
+            specialistContext: "",
+          });
+          pi.sendMessage(
+            { customType: "gsd-debug-start", content: prompt, display: false },
+            { triggerTurn: true },
+          );
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          ctx.ui.notify(
+            `Debug dispatch failed: ${msg}\nSession '${s.slug}' is persisted; retry with /gsd debug continue ${s.slug}`,
+            "warning",
+          );
+        }
+      }
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       ctx.ui.notify(