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

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

@@ -2,6 +2,7 @@ import { Type } from "@sinclair/typebox";
 import { Text } from "@gsd/pi-tui";
 import { loadEffectiveGSDPreferences } from "../preferences.js";
 import { ensureDbOpen } from "./dynamic-tools.js";
+import { loadWriteGateSnapshot, shouldBlockRootArtifactSaveInSnapshot } from "./write-gate.js";
 import { StringEnum } from "@gsd/pi-ai";
 import { logError } from "../workflow-logger.js";
 async function loadWorkflowExecutors() {
@@ -20,6 +21,16 @@ function registerAlias(pi, toolDef, aliasName, canonicalName) {
         promptGuidelines: [`Alias for ${canonicalName} — prefer the canonical name.`],
     });
 }
+function requirementRootWriteGuard(operation) {
+    const guard = shouldBlockRootArtifactSaveInSnapshot(loadWriteGateSnapshot(process.cwd()), "REQUIREMENTS");
+    if (!guard.block)
+        return null;
+    return {
+        content: [{ type: "text", text: `Error ${operation} requirement: ${guard.reason ?? "requirements write blocked"}` }],
+        details: { operation, error: "root_artifact_write_blocked" },
+        isError: true,
+    };
+}
 /**
  * Read a tool result's structured payload, accommodating MCP's `details` →
  * `structuredContent` rename (#4472, #4477). In-process executions still
@@ -119,6 +130,9 @@ export function registerDbTools(pi) {
     registerAlias(pi, decisionSaveTool, "gsd_save_decision", "gsd_decision_save");
     // ─── gsd_requirement_update (formerly gsd_update_requirement) ───────────
     const requirementUpdateExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const gateBlock = requirementRootWriteGuard("update_requirement");
+        if (gateBlock)
+            return gateBlock;
         const dbAvailable = await ensureDbOpen();
         if (!dbAvailable) {
             return {
@@ -201,6 +215,9 @@ export function registerDbTools(pi) {
     registerAlias(pi, requirementUpdateTool, "gsd_update_requirement", "gsd_requirement_update");
     // ─── gsd_requirement_save ─────────────────────────────────────────────
     const requirementSaveExecute = async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+        const gateBlock = requirementRootWriteGuard("save_requirement");
+        if (gateBlock)
+            return gateBlock;
         const dbAvailable = await ensureDbOpen();
         if (!dbAvailable) {
             return {
@@ -242,13 +259,28 @@ export function registerDbTools(pi) {
             "Requirement IDs are auto-assigned — never provide an ID manually.",
         promptSnippet: "Record a new GSD requirement to the database (auto-assigns ID, regenerates REQUIREMENTS.md)",
         promptGuidelines: [
-            "Use gsd_requirement_save when recording a new functional, non-functional, or operational requirement.",
+            "Use gsd_requirement_save when recording a new capability, quality attribute, constraint, or anti-feature requirement.",
+            "Use one of these classes: core-capability, primary-user-loop, launchability, continuity, failure-visibility, integration, quality-attribute, operability, admin/support, compliance/security, differentiator, constraint, anti-feature.",
             "Requirement IDs are auto-assigned (R001, R002, ...) — never guess or provide an ID.",
             "class, description, why, and source are required. All other fields are optional.",
             "The tool writes to the DB and regenerates .gsd/REQUIREMENTS.md automatically.",
         ],
         parameters: Type.Object({
-            class: Type.String({ description: "Requirement class (e.g. 'functional', 'non-functional', 'operational')" }),
+            class: StringEnum([
+                "core-capability",
+                "primary-user-loop",
+                "launchability",
+                "continuity",
+                "failure-visibility",
+                "integration",
+                "quality-attribute",
+                "operability",
+                "admin/support",
+                "compliance/security",
+                "differentiator",
+                "constraint",
+                "anti-feature",
+            ], { description: "Requirement class" }),
             description: Type.String({ description: "Short description of the requirement" }),
             why: Type.String({ description: "Why this requirement matters" }),
             source: Type.String({ description: "Origin of the requirement (e.g. 'user-research', 'design', 'M001')" }),
@@ -291,19 +323,29 @@ export function registerDbTools(pi) {
             "Computes the file path from milestone/slice/task IDs automatically.",
         promptSnippet: "Save a GSD artifact (summary/research/context/assessment) to DB and disk",
         promptGuidelines: [
-            "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT).",
-            "milestone_id is required. slice_id and task_id are optional — they determine the file path.",
+            "Use gsd_summary_save to persist structured artifacts (SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT).",
+            "milestone_id is required for milestone/slice/task artifacts. Omit milestone_id only for root-level PROJECT/PROJECT-DRAFT/REQUIREMENTS/REQUIREMENTS-DRAFT.",
             "The tool computes the relative path automatically: milestones/M001/M001-SUMMARY.md, milestones/M001/slices/S01/S01-SUMMARY.md, etc.",
-            "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT.",
+            "Root-level artifact paths are PROJECT.md, PROJECT-DRAFT.md, REQUIREMENTS.md, and REQUIREMENTS-DRAFT.md.",
+            "artifact_type must be one of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT, PROJECT, PROJECT-DRAFT, REQUIREMENTS, REQUIREMENTS-DRAFT.",
             "Use CONTEXT-DRAFT for incremental draft persistence; use CONTEXT for the final milestone context after depth verification.",
         ],
-        parameters: Type.Object({
-            milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
-            slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
-            task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
-            artifact_type: Type.String({ description: "One of: SUMMARY, RESEARCH, CONTEXT, ASSESSMENT, CONTEXT-DRAFT" }),
-            content: Type.String({ description: "The full markdown content of the artifact" }),
-        }),
+        parameters: Type.Union([
+            Type.Object({
+                milestone_id: Type.String({ description: "Milestone ID (e.g. M001)" }),
+                slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+                task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
+                artifact_type: StringEnum(["SUMMARY", "RESEARCH", "CONTEXT", "ASSESSMENT", "CONTEXT-DRAFT"], { description: "Milestone-scoped artifact type" }),
+                content: Type.String({ description: "The full markdown content of the artifact" }),
+            }),
+            Type.Object({
+                milestone_id: Type.Optional(Type.String({ description: "Omit for root artifacts" })),
+                slice_id: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+                task_id: Type.Optional(Type.String({ description: "Task ID (e.g. T01)" })),
+                artifact_type: StringEnum(["PROJECT", "PROJECT-DRAFT", "REQUIREMENTS", "REQUIREMENTS-DRAFT"], { description: "Root artifact type" }),
+                content: Type.String({ description: "The full markdown content of the artifact" }),
+            }),
+        ]),
         execute: summarySaveExecute,
         renderCall(args, theme) {
             let text = theme.fg("toolTitle", theme.bold("summary_save "));

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

@@ -2,7 +2,7 @@ import { join } from "node:path";
 import { isToolCallEventType } from "@gsd/pi-coding-agent";
 import { updateSnapshot } from "../ecosystem/gsd-extension-api.js";
 import { buildMilestoneFileName, resolveMilestonePath, resolveSliceFile, resolveSlicePath } from "../paths.js";
-import { clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
+import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer, isQueuePhaseActive, markApprovalGateVerified, markDepthVerified, resetWriteGateState, shouldBlockContextWrite, shouldBlockPlanningUnit, shouldBlockQueueExecution, isGateQuestionId, setPendingGate, clearPendingGate, getPendingGate, shouldBlockPendingGate, shouldBlockPendingGateBash, extractDepthVerificationMilestoneId } from "./write-gate.js";
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
@@ -17,9 +17,11 @@ import { installNotifyInterceptor } from "./notify-interceptor.js";
 import { initNotificationStore } from "../notification-store.js";
 import { initNotificationWidget } from "../notification-widget.js";
 import { extractSubagentAgentClasses } from "./subagent-input.js";
+import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserApprovalQuestion } from "../user-input-boundary.js";
 // Skip the welcome screen on the very first session_start — cli.ts already
 // printed it before the TUI launched. Only re-print on /clear (subsequent sessions).
 let isFirstSession = true;
+let approvalQuestionAbortInFlight = false;
 async function deriveGsdState(basePath) {
     const { deriveState } = await import("../state.js");
     return deriveState(basePath);
@@ -60,6 +62,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         }
         resetWriteGateState();
         resetToolCallLoopGuard();
+        approvalQuestionAbortInFlight = false;
         await resetAskUserQuestionsTurnCache();
         await syncServiceTierStatus(ctx);
         await applyDisabledModelProviderPolicy(ctx);
@@ -134,6 +137,14 @@ export function registerHooks(pi, ecosystemHandlers) {
         // Wait for ecosystem loader to finish (no-op after first turn).
         const { getEcosystemReadyPromise } = await import("../ecosystem/loader.js");
         await getEcosystemReadyPromise();
+        const pendingApprovalGate = getPendingGate();
+        if (pendingApprovalGate && isExplicitApprovalResponse(event.prompt, pendingApprovalGate)) {
+            markApprovalGateVerified(pendingApprovalGate);
+            const milestoneId = extractDepthVerificationMilestoneId(pendingApprovalGate);
+            if (milestoneId)
+                markDepthVerified(milestoneId);
+            clearPendingGate();
+        }
         // GSD's own context injection (existing behavior — unchanged).
         const { buildBeforeAgentStartResult } = await import("./system-context.js");
         const gsdResult = await buildBeforeAgentStartResult(event, ctx);
@@ -173,6 +184,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         };
     });
     pi.on("agent_end", async (event, ctx) => {
+        approvalQuestionAbortInFlight = false;
         resetToolCallLoopGuard();
         await resetAskUserQuestionsTurnCache();
         const { handleAgentEnd } = await import("./agent-end-recovery.js");
@@ -278,6 +290,44 @@ export function registerHooks(pi, ecosystemHandlers) {
             safetyLogWarning("context-mode", `failed to write compaction snapshot: ${err instanceof Error ? err.message : String(err)}`);
         }
     });
+    pi.on("message_update", async (event, ctx) => {
+        if (approvalQuestionAbortInFlight)
+            return;
+        const dash = getAutoRuntimeSnapshot();
+        let unitType = dash.currentUnit?.type;
+        let unitId = dash.currentUnit?.id;
+        if (!unitType) {
+            try {
+                const { getPendingDeepProjectSetupUnitForContext } = await import("../guided-flow.js");
+                const pending = getPendingDeepProjectSetupUnitForContext(ctx, process.cwd());
+                unitType = pending?.unitType;
+                unitId = pending?.unitId;
+            }
+            catch {
+                // Best-effort foreground detection only.
+            }
+        }
+        if (!unitType) {
+            const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
+            if (milestoneId) {
+                unitType = "discuss-milestone";
+                unitId = milestoneId;
+            }
+        }
+        if (!shouldPauseForUserApprovalQuestion(unitType, [event.message]))
+            return;
+        const gateId = approvalGateIdForUnit(unitType, unitId);
+        if (gateId)
+            setPendingGate(gateId);
+        approvalQuestionAbortInFlight = true;
+        ctx.ui.notify(`${unitType}${unitId ? ` ${unitId}` : ""} is waiting for your approval - pausing before more tool calls run.`, "info");
+        // The pending gate set above blocks subsequent non-read-only tool calls
+        // via the tool_call hook below, so we do not abort the in-flight stream.
+        // Aborting mid-stream eats the model's question text on external CLI
+        // providers (Claude Code SDK) because lastTextContent isn't populated
+        // from in-flight builder state — the user only ever sees "Claude Code
+        // stream aborted by caller" instead of the question.
+    });
     pi.on("session_shutdown", async (_event, ctx) => {
         const { isParallelActive, shutdownParallel } = await import("../parallel-orchestrator.js");
         if (isParallelActive()) {
@@ -297,15 +347,16 @@ export function registerHooks(pi, ecosystemHandlers) {
     });
     pi.on("tool_call", async (event) => {
         const discussionBasePath = process.cwd();
+        const toolName = canonicalToolName(event.toolName);
         // ── Loop guard: block repeated identical tool calls ──
-        const loopCheck = checkToolCallLoop(event.toolName, event.input);
+        const loopCheck = checkToolCallLoop(toolName, event.input);
         if (loopCheck.block) {
             return { block: true, reason: loopCheck.reason };
         }
         // ── Discussion gate enforcement: track pending gate questions ─────────
         // Only gate-shaped ask_user_questions calls should block execution.
         // The gate stays pending until the user selects the approval option.
-        if (event.toolName === "ask_user_questions") {
+        if (toolName === "ask_user_questions") {
             const questions = event.input?.questions ?? [];
             const questionId = questions.find((question) => typeof question?.id === "string" && isGateQuestionId(question.id))?.id;
             if (typeof questionId === "string") {
@@ -323,7 +374,7 @@ export function registerHooks(pi, ecosystemHandlers) {
                     return bashGuard;
             }
             else {
-                const gateGuard = shouldBlockPendingGate(event.toolName, milestoneId, isQueuePhaseActive());
+                const gateGuard = shouldBlockPendingGate(toolName, milestoneId, isQueuePhaseActive());
                 if (gateGuard.block)
                     return gateGuard;
             }
@@ -343,7 +394,7 @@ export function registerHooks(pi, ecosystemHandlers) {
             else if (isToolCallEventType("bash", event)) {
                 queueInput = event.input.command;
             }
-            const queueGuard = shouldBlockQueueExecution(event.toolName, queueInput, true);
+            const queueGuard = shouldBlockQueueExecution(toolName, queueInput, true);
             if (queueGuard.block)
                 return queueGuard;
         }
@@ -447,7 +498,8 @@ export function registerHooks(pi, ecosystemHandlers) {
             // errors and deterministic policy rejections are handled consistently.
             recordToolInvocationError(event.toolName, errorText);
         }
-        if (event.toolName !== "ask_user_questions")
+        const toolName = canonicalToolName(event.toolName);
+        if (toolName !== "ask_user_questions")
             return;
         const milestoneId = await getDiscussionMilestoneIdFor(process.cwd());
         const queueActive = isQueuePhaseActive();
@@ -461,14 +513,30 @@ export function registerHooks(pi, ecosystemHandlers) {
         const currentPendingGate = getPendingGate();
         if (currentPendingGate) {
             if (details?.cancelled || !details?.response) {
-                // Gate stays pending — model will be blocked from non-read-only tools
-                // until it re-asks and gets a valid response
+                // Gate stays pending. Return a hard instruction as the tool result so
+                // the model cannot reinterpret a cancelled prompt as prior approval.
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `HARD BLOCK: approval gate "${currentPendingGate}" is still pending.`,
+                                "No user response was received for the confirmation question.",
+                                "Do not infer approval from earlier or prior messages.",
+                                "Do not proceed, write files, save artifacts, or call more tools.",
+                                "Ask the user to confirm in plain chat, then stop and wait for their next message.",
+                            ].join(" "),
+                        }],
+                };
             }
             else {
                 const pendingQuestion = questions.find((question) => question?.id === currentPendingGate);
                 if (pendingQuestion) {
                     const answer = details.response?.answers?.[currentPendingGate];
                     if (isDepthConfirmationAnswer(answer?.selected, pendingQuestion.options)) {
+                        markApprovalGateVerified(currentPendingGate);
+                        const milestoneIdFromGate = extractDepthVerificationMilestoneId(currentPendingGate);
+                        if (milestoneIdFromGate)
+                            markDepthVerified(milestoneIdFromGate);
                         clearPendingGate();
                     }
                 }
@@ -483,6 +551,9 @@ export function registerHooks(pi, ecosystemHandlers) {
                 const answer = details.response?.answers?.[question.id];
                 const inferredMilestoneId = extractDepthVerificationMilestoneId(question.id) ?? milestoneId;
                 if (isDepthConfirmationAnswer(answer?.selected, question.options)) {
+                    if (currentPendingGate && question.id !== currentPendingGate)
+                        break;
+                    markApprovalGateVerified(question.id);
                     markDepthVerified(inferredMilestoneId);
                     clearPendingGate();
                 }

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync, unlinkSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
 import { logWarning } from "../workflow-logger.js";
 import { debugTime } from "../debug-logger.js";
@@ -17,7 +16,7 @@ import { deriveState } from "../state.js";
 import { formatOverridesSection, formatShortcut, loadActiveOverrides, loadFile, parseContinue, parseSummary } from "../files.js";
 import { toPosixPath } from "../../shared/mod.js";
 import { autoEnableCmuxPreferences } from "../commands-cmux.js";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
+import { gsdHome } from "../gsd-home.js";
 /**
  * Bundled skill triggers — resolved dynamically at runtime instead of
  * hardcoding absolute paths in the system prompt template. Only skills
@@ -75,7 +74,7 @@ function buildBundledSkillsTable() {
 }
 function warnDeprecatedAgentInstructions() {
     const paths = [
-        join(gsdHome, "agent-instructions.md"),
+        join(gsdHome(), "agent-instructions.md"),
         join(process.cwd(), ".gsd", "agent-instructions.md"),
     ];
     for (const path of paths) {
@@ -119,7 +118,7 @@ export async function buildBeforeAgentStartResult(event, ctx) {
             ctx.ui.notify(`GSD skill preferences: ${report.warnings.length} unresolved skill${report.warnings.length === 1 ? "" : "s"}: ${report.warnings.join(", ")}`, "warning");
         }
     }
-    const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome, process.cwd());
+    const { block: knowledgeBlock, globalSizeKb } = loadKnowledgeBlock(gsdHome(), process.cwd());
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
     }

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

@@ -56,6 +56,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();
+const verifiedApprovalGates = new Set();
 let activeQueuePhase = false;
 /**
  * Discussion gate enforcement state.
@@ -76,14 +77,18 @@ 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) {
+    if (!toolName.startsWith("mcp__"))
+        return toolName;
+    const toolSeparator = toolName.indexOf("__", "mcp__".length);
+    return toolSeparator >= 0 ? toolName.slice(toolSeparator + 2) : toolName;
+}
 /**
  * Persistence is ON by default (opt-out).
  * Set GSD_PERSIST_WRITE_GATE_STATE="0" or GSD_PERSIST_WRITE_GATE_STATE="false"
@@ -100,6 +105,7 @@ function writeGateSnapshotPath(basePath = process.cwd()) {
 function currentWriteGateSnapshot() {
     return {
         verifiedDepthMilestones: [...verifiedDepthMilestones].sort(),
+        verifiedApprovalGates: [...verifiedApprovalGates].sort(),
         activeQueuePhase,
         pendingGateId,
     };
@@ -142,14 +148,19 @@ function normalizeWriteGateSnapshot(value) {
     const verified = Array.isArray(record.verifiedDepthMilestones)
         ? record.verifiedDepthMilestones.filter((item) => typeof item === "string")
         : [];
+    const verifiedGates = Array.isArray(record.verifiedApprovalGates)
+        ? record.verifiedApprovalGates.filter((item) => 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,
     };
 }
 const EMPTY_SNAPSHOT = {
     verifiedDepthMilestones: [],
+    verifiedApprovalGates: [],
     activeQueuePhase: false,
     pendingGateId: null,
 };
@@ -195,11 +206,13 @@ export function setQueuePhaseActive(active) {
 }
 export function resetWriteGateState() {
     verifiedDepthMilestones.clear();
+    verifiedApprovalGates.clear();
     pendingGateId = null;
     persistWriteGateSnapshot();
 }
 export function clearDiscussionFlowState() {
     verifiedDepthMilestones.clear();
+    verifiedApprovalGates.clear();
     activeQueuePhase = false;
     pendingGateId = null;
     clearPersistedWriteGateSnapshot();
@@ -210,6 +223,17 @@ export function markDepthVerified(milestoneId, basePath = process.cwd()) {
     verifiedDepthMilestones.add(milestoneId);
     persistWriteGateSnapshot(basePath);
 }
+export function markApprovalGateVerified(gateId, basePath = process.cwd()) {
+    if (!gateId)
+        return;
+    verifiedApprovalGates.add(gateId);
+    persistWriteGateSnapshot(basePath);
+}
+export function isApprovalGateVerifiedInSnapshot(snapshot, gateId) {
+    if (!gateId)
+        return false;
+    return (snapshot.verifiedApprovalGates ?? []).includes(gateId);
+}
 /**
  * Check whether a question ID matches a recognized gate pattern.
  */
@@ -236,6 +260,10 @@ function extractContextMilestoneId(inputPath) {
  */
 export function setPendingGate(gateId) {
     pendingGateId = gateId;
+    verifiedApprovalGates.delete(gateId);
+    const milestoneId = extractDepthVerificationMilestoneId(gateId);
+    if (milestoneId)
+        verifiedDepthMilestones.delete(milestoneId);
     persistWriteGateSnapshot();
 }
 /**
@@ -256,7 +284,7 @@ export function getPendingGate() {
  * 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, milestoneId, queuePhaseActive) {
     return shouldBlockPendingGateInSnapshot(currentWriteGateSnapshot(), toolName, milestoneId, queuePhaseActive);
@@ -264,16 +292,14 @@ export function shouldBlockPendingGate(toolName, milestoneId, queuePhaseActive)
 export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneId, _queuePhaseActive) {
     if (!snapshot.pendingGateId)
         return { block: false };
-    if (GATE_SAFE_TOOLS.has(toolName))
+    if (GATE_SAFE_TOOLS.has(canonicalToolName(toolName)))
         return { block: false };
-    // Bash read-only commands are also safe
-    if (toolName === "bash")
-        return { block: false }; // bash is checked separately below
     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.`,
@@ -282,7 +308,7 @@ export function shouldBlockPendingGateInSnapshot(snapshot, toolName, _milestoneI
 }
 /**
  * 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, milestoneId, queuePhaseActive) {
     return shouldBlockPendingGateBashInSnapshot(currentWriteGateSnapshot(), command, milestoneId, queuePhaseActive);
@@ -290,14 +316,12 @@ export function shouldBlockPendingGateBash(command, milestoneId, queuePhaseActiv
 export function shouldBlockPendingGateBashInSnapshot(snapshot, command, _milestoneId, _queuePhaseActive) {
     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(" "),
@@ -390,6 +414,49 @@ export function shouldBlockContextArtifactSaveInSnapshot(snapshot, artifactType,
         ].join(" "),
     };
 }
+const FINAL_ROOT_ARTIFACTS = new Set(["PROJECT", "REQUIREMENTS"]);
+function requiredRootApprovalGateForArtifact(artifactType) {
+    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, artifactType, opts = {}) {
+    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/dist/resources/extensions/gsd/commands/catalog.js

@@ -1,9 +1,8 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
-import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
-const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-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";
+import { gsdHome } from "../gsd-home.js";
+export const GSD_COMMAND_DESCRIPTION = "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -50,6 +49,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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" },
@@ -72,6 +72,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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 = {
     auto: [
@@ -306,7 +307,7 @@ function filterOptions(partial, options, prefix = "") {
 }
 function getExtensionCompletions(prefix, action) {
     try {
-        const extDir = join(gsdHome, "agent", "extensions");
+        const extDir = join(gsdHome(), "agent", "extensions");
         const ids = [];
         for (const entry of readdirSync(extDir, { withFileTypes: true })) {
             if (!entry.isDirectory())
@@ -394,7 +395,7 @@ function resolveProjectRootForCompletion(basePath) {
     const gsdMarker = `${separator}.gsd${separator}`;
     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;
@@ -500,7 +501,7 @@ export function getGsdArgumentCompletions(prefix) {
             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.

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

@@ -3,6 +3,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";
 /**
  * Typed error for when GSD is run outside a valid project directory.
  * Command handlers catch this to show a friendly message instead of a raw exception.
@@ -19,8 +20,8 @@ export function projectRoot() {
         cwd = process.cwd();
     }
     catch {
-        // cwd directory was deleted (e.g. worktree teardown) — fall back to HOME (#3598)
-        cwd = process.env.HOME ?? "/";
+        // 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;
@@ -30,6 +31,20 @@ export function projectRoot() {
     }
     return root;
 }
+export function currentDirectoryRoot() {
+    let cwd;
+    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, pi) {
     if (isAutoActive() || isAutoPaused())
         return true;