@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.75048e7

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

@@ -20,6 +20,49 @@ async function loadContextModePreferences(baseDir) {
     }
 }
 export function registerExecTools(pi) {
+    pi.registerTool({
+        name: "gsd_uat_exec",
+        label: "UAT Exec",
+        description: "Run a UAT-scoped bash/node/python check with milestone/slice/check metadata. " +
+            "Uses the same capped .gsd/exec evidence store as gsd_exec, but rejects commands that mutate dependencies, git state, credentials, or destructive files.",
+        promptSnippet: "Run one UAT check and save typed evidence under .gsd/exec",
+        promptGuidelines: [
+            "Use gsd_uat_exec for each automated UAT check.",
+            "Every PASS/FAIL check saved by gsd_uat_result_save must reference objective evidence from this tool or another approved GSD evidence path.",
+            "Do not install packages, mutate git state, edit source files, or dump credentials during UAT.",
+        ],
+        parameters: Type.Object({
+            milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
+            sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
+            checkId: Type.String({ description: "Stable check ID from the UAT spec (e.g. UAT-01)" }),
+            intent: Type.String({
+                description: "UAT command intent. Use one canonical value: uat-artifact-check, uat-runtime-check, " +
+                    "uat-browser-check, uat-service-start, or uat-log-inspection. Short aliases such as artifact, " +
+                    "runtime, browser, service-start, and log-inspection are accepted.",
+            }),
+            runtime: Type.Optional(Type.String({
+                description: "Optional interpreter. Defaults to bash. Supported: bash, node, python; sh/shell, js/nodejs, and py/python3 aliases are accepted.",
+            })),
+            script: Type.Optional(Type.String({ description: "Script body. Keep output small (log the finding, not the data)." })),
+            command: Type.Optional(Type.String({ description: "Alias for script; defaults to bash when runtime is omitted." })),
+            cmd: Type.Optional(Type.String({ description: "Short alias for script." })),
+            code: Type.Optional(Type.String({ description: "Alias for script, useful for node/python snippets." })),
+            expected: Type.Optional(Type.String({ description: "Expected outcome for this UAT check." })),
+            timeout_ms: Type.Optional(Type.Number({
+                description: "Per-invocation timeout (ms). Capped at 600000. Default from preferences.",
+                minimum: 1_000,
+                maximum: 600_000,
+            })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            const { executeUatExec } = await import("../tools/exec-tool.js");
+            const baseDir = resolveCtxCwd(_ctx);
+            return executeUatExec(params, {
+                baseDir,
+                preferences: await loadContextModePreferences(baseDir),
+            });
+        },
+    });
     pi.registerTool({
         name: "gsd_exec",
         label: "Exec (Sandboxed)",

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

@@ -11,7 +11,7 @@ import { canonicalToolName, clearDiscussionFlowState, isDepthConfirmationAnswer,
 import { resolveManifest } from "../unit-context-manifest.js";
 import { isBlockedStateFile, isBashWriteToStateFile, BLOCKED_WRITE_ERROR } from "../write-intercept.js";
 import { loadFile, saveFile, formatContinue } from "../files.js";
-import { clearToolInvocationError, getAutoRuntimeSnapshot, isAutoActive, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto-runtime-state.js";
+import { clearToolInvocationError, getAutoRuntimeSnapshot, isAutoActive, isAutoCompletionStopInProgress, isAutoPaused, markToolEnd, markToolStart, recordToolInvocationError } from "../auto-runtime-state.js";
 import { checkToolCallLoop, resetToolCallLoopGuard } from "./tool-call-loop-guard.js";
 import { maybePauseAutoForApprovalGate, resetPendingGatePauseGuard } from "./pending-gate-pause.js";
 import { saveActivityLog } from "../activity-log.js";
@@ -28,7 +28,9 @@ import { approvalGateIdForUnit, isExplicitApprovalResponse, shouldPauseForUserAp
 import { applyUnitSkillVisibility, unitHasSkillManifest } from "../skill-scope.js";
 import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.js";
-import { AUTO_UNIT_SCOPED_TOOLS, isWorkflowAliasTool } from "../auto-unit-tool-scope.js";
+import { AUTO_UNIT_SCOPED_TOOLS, RUN_UAT_BROWSER_TOOL_NAMES, isWorkflowAliasTool } from "../auto-unit-tool-scope.js";
+import { filterToolsForProvider } from "../model-router.js";
+import { RUN_UAT_READ_ONLY_TOOL_NAMES, RUN_UAT_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
 let approvalQuestionAbortInFlight = false;
 async function loadWelcomeScreenModule() {
     const candidates = [];
@@ -104,6 +106,7 @@ export const MINIMAL_GSD_TOOL_NAMES = [
     "gsd_resume",
     "gsd_milestone_status",
     "gsd_checkpoint_db",
+    "gsd_plan_milestone",
     "memory_query",
     "capture_thought",
 ];
@@ -187,6 +190,9 @@ export function buildMinimalGsdToolSet(activeToolNames) {
     return withPreservedShimTools([...new Set([...preserved, ...minimal])]);
 }
 export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registeredToolNames = activeToolNames) {
+    if (unitType === "run-uat") {
+        return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
+    }
     const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
     const autoBaseTools = new Set(MINIMAL_AUTO_BASE_TOOL_NAMES);
     const availableBaseTools = registeredToolNames.filter((name) => autoBaseTools.has(name));
@@ -197,6 +203,15 @@ export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registered
     const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [...MINIMAL_GSD_TOOL_NAMES, ...unitTools]);
     return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
 }
+export function buildRunUatGsdToolSet(activeToolNames, registeredToolNames = activeToolNames) {
+    const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [
+        ...RUN_UAT_WORKFLOW_TOOL_NAMES,
+        ...RUN_UAT_READ_ONLY_TOOL_NAMES,
+        "subagent",
+        ...RUN_UAT_BROWSER_TOOL_NAMES,
+    ]);
+    return [...new Set(scoped)];
+}
 export function buildMinimalGsdWorkflowToolSet(activeToolNames, registeredToolNames = activeToolNames) {
     const autoBaseTools = new Set(MINIMAL_AUTO_BASE_TOOL_NAMES);
     const availableBaseTools = registeredToolNames.filter((name) => autoBaseTools.has(name));
@@ -372,6 +387,11 @@ function isContextDraftSummarySave(toolName, input) {
         return false;
     return input.artifact_type === "CONTEXT-DRAFT";
 }
+function withDepthGateDisplayReason(result, displayReason = "Depth confirmation is waiting for your answer.") {
+    if (!result.block)
+        return result;
+    return { ...result, displayReason };
+}
 function shouldBlockDeferredApprovalTool(toolName, input, basePath) {
     if (deferredApprovalGate?.basePath !== basePath)
         return { block: false };
@@ -379,14 +399,14 @@ function shouldBlockDeferredApprovalTool(toolName, input, basePath) {
         return { block: false };
     if (isContextDraftSummarySave(toolName, input))
         return { block: false };
-    return {
+    return withDepthGateDisplayReason({
         block: true,
         reason: [
             `HARD BLOCK: Approval question "${deferredApprovalGate.gateId}" has been shown to the user.`,
             `Only CONTEXT-DRAFT persistence may finish in this same assistant turn.`,
             `Wait for the user's answer before calling additional tools.`,
         ].join(" "),
-    };
+    });
 }
 export function resolveNotificationStoreBasePath(basePath) {
     return resolveWorktreeProjectRoot(basePath);
@@ -414,8 +434,9 @@ export function registerHooks(pi, ecosystemHandlers) {
     registerPlanMilestoneSchemaRecovery(pi);
     pi.on("session_start", async (_event, ctx) => {
         const basePath = contextBasePath(ctx);
+        const preserveCloseoutSurface = isAutoCompletionStopInProgress();
         initSessionNotifications(ctx);
-        if (!isAutoActive()) {
+        if (!isAutoActive() && !preserveCloseoutSurface) {
             const { initHealthWidget } = await import("../health-widget.js");
             initHealthWidget(ctx);
         }
@@ -435,14 +456,17 @@ export function registerHooks(pi, ecosystemHandlers) {
             process.env.GSD_SHOW_TOKEN_COST = prefs?.preferences.show_token_cost ? "1" : "";
         }
         catch { /* non-fatal */ }
-        await installWelcomeHeader(ctx);
+        if (!preserveCloseoutSurface) {
+            await installWelcomeHeader(ctx);
+        }
         await loadToolApiKeysForSession();
-        if (isAutoActive()) {
+        if (isAutoActive() || preserveCloseoutSurface) {
             ctx.ui.setWidget("gsd-health", undefined);
         }
     });
     pi.on("session_switch", async (_event, ctx) => {
         const basePath = contextBasePath(ctx);
+        const preserveCloseoutSurface = isAutoCompletionStopInProgress();
         initSessionNotifications(ctx);
         resetWriteGateState(basePath);
         resetToolCallLoopGuard();
@@ -454,7 +478,7 @@ export function registerHooks(pi, ecosystemHandlers) {
         await applyCompactionThresholdOverride(ctx);
         await prepareWorkflowMcpForHookContext(ctx, basePath);
         await loadToolApiKeysForSession();
-        if (!isAutoActive()) {
+        if (!isAutoActive() && !preserveCloseoutSurface) {
             ctx.ui.setWidget("gsd-progress", undefined);
             ctx.ui.setWidget("gsd-outcome", undefined);
             const { initHealthWidget } = await import("../health-widget.js");
@@ -740,7 +764,7 @@ export function registerHooks(pi, ecosystemHandlers) {
                     if (ctx) {
                         await maybePauseAutoForApprovalGate(ctx, pi, true, "Depth confirmation is waiting for your answer — pausing auto-mode.");
                     }
-                    return bashGuard;
+                    return withDepthGateDisplayReason(bashGuard);
                 }
             }
             else {
@@ -749,7 +773,7 @@ export function registerHooks(pi, ecosystemHandlers) {
                     if (ctx) {
                         await maybePauseAutoForApprovalGate(ctx, pi, true, "Depth confirmation is waiting for your answer — pausing auto-mode.");
                     }
-                    return gateGuard;
+                    return withDepthGateDisplayReason(gateGuard);
                 }
             }
         }
@@ -833,13 +857,12 @@ export function registerHooks(pi, ecosystemHandlers) {
         if (!isToolCallEventType("write", event))
             return;
         const result = shouldBlockContextWrite(event.toolName, event.input.path, await getDiscussionMilestoneIdFor(discussionBasePath), isQueuePhaseActive(discussionBasePath), discussionBasePath);
-        if (result.block)
-            return result;
+        if (result.block) {
+            return withDepthGateDisplayReason(result, "Depth check required before writing milestone context.");
+        }
     });
-    // ── Safety harness: evidence collection + destructive command warnings ──
+    // ── Safety harness: evidence collection + destructive command blocking ──
     pi.on("tool_call", async (event, ctx) => {
-        if (!isAutoActive())
-            return;
         markToolStart(event.toolCallId, event.toolName);
         safetyRecordToolCall(event.toolCallId, event.toolName, event.input);
         // Persist immediately at dispatch so a mid-unit re-dispatch — which calls
@@ -854,14 +877,23 @@ export function registerHooks(pi, ecosystemHandlers) {
                 saveEvidenceToDisk(callDash.basePath, cMid, cSid, cTid);
             }
         }
-        // Destructive command classification (warn only, never block)
+        // Destructive command classification + hard gate in all modes.
         if (isToolCallEventType("bash", event)) {
             const classification = classifyCommand(event.input.command);
             if (classification.destructive) {
+                const reason = [
+                    "HARD BLOCK: destructive Bash command requires explicit human confirmation.",
+                    `Detected: ${classification.labels.join(", ")}`,
+                    "Run this via ask_user_questions, wait for the user's response,",
+                    "then issue the command only when confirmed in the current turn.",
+                ].join(" ");
                 safetyLogWarning("safety", `destructive command: ${classification.labels.join(", ")}`, {
                     command: String(event.input.command).slice(0, 200),
                 });
-                ctx.ui.notify(`Destructive command detected: ${classification.labels.join(", ")}`, "warning");
+                if (ctx) {
+                    await maybePauseAutoForApprovalGate(ctx, pi, isAutoActive(), "Depth confirmation is waiting for your answer — pausing auto-mode.");
+                }
+                return { block: true, reason };
             }
         }
     });
@@ -1123,21 +1155,25 @@ export function registerHooks(pi, ecosystemHandlers) {
         const fullToolsRequested = isFullGsdToolSurfaceRequested();
         const dropAliases = !fullToolsRequested;
         const dropBrowser = !fullToolsRequested && !isBrowserToolSurfaceRequested();
-        const providerCompatible = compatible.filter((name) => !(dropAliases && isWorkflowAliasTool(name)) && !(dropBrowser && isBrowserTool(name)));
+        const aliasFilteredCompatible = compatible.filter((name) => !(dropAliases && isWorkflowAliasTool(name)));
+        const providerCompatible = aliasFilteredCompatible.filter((name) => !(dropBrowser && isBrowserTool(name)));
         const surfaceReduced = providerCompatible.length !== compatible.length;
         if (fullToolsRequested) {
             return surfaceReduced ? { toolNames: providerCompatible } : undefined;
         }
         const registeredToolNames = resolveRegisteredToolNames(pi, event.activeToolNames);
+        const compatibleRegisteredToolNames = filterToolsForProvider(registeredToolNames, event.selectedModelApi, event.selectedModelProvider).compatible.filter((name) => !(dropAliases && isWorkflowAliasTool(name)));
         const guidedUnit = getGuidedUnitContext();
-        const requestScoped = buildRequestScopedGsdToolSet(providerCompatible, event.requestCustomMessages, registeredToolNames, guidedUnit?.unitType);
+        const requestScoped = buildRequestScopedGsdToolSet(guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible, event.requestCustomMessages, guidedUnit?.unitType === "run-uat" ? compatibleRegisteredToolNames : registeredToolNames, guidedUnit?.unitType);
         if (requestScoped) {
             return { toolNames: requestScoped };
         }
         const dash = getAutoRuntimeSnapshot();
         if (dash.active && dash.currentUnit) {
             return {
-                toolNames: buildMinimalAutoGsdToolSet(providerCompatible, dash.currentUnit.type, resolveRegisteredToolNames(pi, event.activeToolNames)),
+                toolNames: buildMinimalAutoGsdToolSet(dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible, dash.currentUnit.type, dash.currentUnit.type === "run-uat"
+                    ? compatibleRegisteredToolNames
+                    : resolveRegisteredToolNames(pi, event.activeToolNames)),
             };
         }
         if (isGeneralGsdToolScopingRequested()) {

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

@@ -2,7 +2,7 @@
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { minimatch } from "minimatch";
-import { shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
+import { GSD_PHASE_SCOPE_DISPLAY_REASON, shouldBlockAutoUnitToolCall } from "../auto-unit-tool-scope.js";
 import { getIsolationMode } from "../preferences.js";
 import { compileSubagentPermissionContract } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
@@ -565,6 +565,7 @@ const PLANNING_SUBAGENT_TOOLS = new Set(["subagent", "task"]);
  * manifests still declare per-unit subsets via ToolsPolicy.allowedSubagents.
  */
 const PLANNING_DISPATCH_AGENT_REGISTRY = {
+    mnemo: { readOnlySpecialist: true },
     scout: { readOnlySpecialist: true },
     planner: { readOnlySpecialist: true },
     reviewer: { readOnlySpecialist: true },
@@ -574,7 +575,7 @@ const PLANNING_DISPATCH_AGENT_REGISTRY = {
 export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set(Object.entries(PLANNING_DISPATCH_AGENT_REGISTRY)
     .filter(([, metadata]) => metadata.readOnlySpecialist)
     .map(([agentId]) => agentId));
-let warnedMissingPlanningDispatchAgentClasses = false;
+let warnedMissingControlledDispatchAgentClasses = false;
 function isReadOnlySpecialist(agentId) {
     const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId];
     return metadata?.readOnlySpecialist === true;
@@ -582,12 +583,16 @@ function isReadOnlySpecialist(agentId) {
 function allowedPlanningDispatchAgentsList() {
     return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
 }
-function warnMissingPlanningDispatchAgentClasses(unitType, mode, toolName) {
-    if (warnedMissingPlanningDispatchAgentClasses)
+function allowsControlledSubagentDispatch(policy) {
+    return ((policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+        Array.isArray(policy.allowedSubagents));
+}
+function warnMissingControlledDispatchAgentClasses(unitType, mode, toolName) {
+    if (warnedMissingControlledDispatchAgentClasses)
         return;
-    warnedMissingPlanningDispatchAgentClasses = true;
+    warnedMissingControlledDispatchAgentClasses = true;
     // TODO(#5060): Remove this migration shim once all subagent/task callers are verified to forward agent identities.
-    const message = `[write-gate] planning-dispatch: shouldBlockPlanningUnit called for tool "${toolName}" ` +
+    const message = `[write-gate] controlled-dispatch: shouldBlockPlanningUnit called for tool "${toolName}" ` +
         `on unit "${unitType}" without agentClasses - stale caller; blocking dispatch.`;
     console.warn(message);
     logWarning("intercept", message, {
@@ -638,6 +643,13 @@ function blockReason(unitType, mode, what) {
         `the work belongs in execute-task, not in a planning unit.`,
     ].join(" ");
 }
+function planningBlock(unitType, mode, what) {
+    return {
+        block: true,
+        reason: blockReason(unitType, mode, what),
+        displayReason: GSD_PHASE_SCOPE_DISPLAY_REASON,
+    };
+}
 /**
  * Planning-unit tool-policy enforcement. Returns { block } per the policy
  * resolved from the active unit's manifest:
@@ -653,8 +665,9 @@ function blockReason(unitType, mode, what) {
  *   - "docs"       → like "planning" but also allows writes to paths
  *                    matching `allowedPathGlobs` relative to basePath.
  *   - "verification"
- *                  → allows Bash for project verification commands, but keeps
- *                    writes restricted to .gsd/ and blocks subagent dispatch.
+ *                  → allows Bash for project verification commands, keeps
+ *                    writes restricted to .gsd/, and permits subagent dispatch
+ *                    only when the manifest declares allowedSubagents.
  *
  * `pathOrCommand` is the file path for write/edit-shaped tools and the
  * shell command for bash. Other tools ignore this argument.
@@ -684,10 +697,10 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         if (tool.startsWith("gsd_"))
             return { block: false };
         if (PLANNING_WRITE_TOOLS.has(tool) || tool === "bash" || PLANNING_SUBAGENT_TOOLS.has(tool)) {
-            return { block: true, reason: blockReason(unitType, policy.mode, `${tool} is not permitted (read-only)`) };
+            return planningBlock(unitType, policy.mode, `${tool} is not permitted (read-only)`);
         }
         // Unknown tool in read-only mode — block by default.
-        return { block: true, reason: blockReason(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`) };
+        return planningBlock(unitType, policy.mode, `tool "${tool}" is not on the read-only allowlist`);
     }
     // planning / planning-dispatch / docs / verification modes share the same surface for safe tools, bash, and subagent.
     if (PLANNING_SAFE_TOOLS.has(tool))
@@ -695,7 +708,7 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
     if (tool.startsWith("gsd_"))
         return { block: false };
     if (PLANNING_SUBAGENT_TOOLS.has(tool)) {
-        if (policy.mode === "planning-dispatch") {
+        if (allowsControlledSubagentDispatch(policy)) {
             const requested = (agentClasses ?? []).map(a => a.trim()).filter(Boolean);
             const dispatchContract = compileSubagentPermissionContract(policy);
             const allowedSubagents = dispatchContract.allowedSubagents;
@@ -704,11 +717,8 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
             // agent identities yet. Block and warn so stale callers surface in telemetry
             // instead of silently bypassing the gate.
             if (agentClasses === undefined) {
-                warnMissingPlanningDispatchAgentClasses(unitType, policy.mode, tool);
-                return {
-                    block: true,
-                    reason: blockReason(unitType, policy.mode, `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`),
-                };
+                warnMissingControlledDispatchAgentClasses(unitType, policy.mode, tool);
+                return planningBlock(unitType, policy.mode, `subagent dispatch blocked: stale caller did not supply agent identities for "${tool}"; update extractSubagentAgentClasses to handle this input shape`);
             }
             // agentClasses was explicitly provided but resolved to an empty list (for
             // example, a bare tool call with no agent field). Pass through; no agents
@@ -718,41 +728,29 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
             }
             const globallyDisallowed = requested.find(a => !isReadOnlySpecialist(a));
             if (globallyDisallowed) {
-                return {
-                    block: true,
-                    reason: blockReason(unitType, policy.mode, `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from planning-dispatch units`),
-                };
+                return planningBlock(unitType, policy.mode, `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from ${policy.mode} units`);
             }
             const disallowedByPolicy = requested.find(a => !allowed.has(a));
             if (disallowedByPolicy) {
-                return {
-                    block: true,
-                    reason: blockReason(unitType, policy.mode, `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`),
-                };
+                return planningBlock(unitType, policy.mode, `subagent dispatch of "${disallowedByPolicy}" not permitted by ToolsPolicy.allowedSubagents; permitted agents for this unit: ${allowedSubagents.join(", ")}`);
             }
             return { block: false };
         }
-        return { block: true, reason: blockReason(unitType, policy.mode, `subagent dispatch is not permitted in planning units`) };
+        return planningBlock(unitType, policy.mode, "subagent dispatch is not permitted in planning units");
     }
     if (tool === "bash") {
         if (policy.mode === "verification") {
             if (BASH_VERIFICATION_RE.test(pathOrCommand) || BASH_READ_ONLY_RE.test(pathOrCommand))
                 return { block: false };
-            return {
-                block: true,
-                reason: blockReason(unitType, policy.mode, `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`),
-            };
+            return planningBlock(unitType, policy.mode, `bash is restricted to build/test verification commands (npm run build, npm test, etc.); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`);
         }
         if (BASH_READ_ONLY_RE.test(pathOrCommand))
             return { block: false };
-        return {
-            block: true,
-            reason: blockReason(unitType, policy.mode, `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`),
-        };
+        return planningBlock(unitType, policy.mode, `bash is restricted to read-only commands (cat/grep/git log/etc); cannot run "${pathOrCommand.slice(0, 80)}${pathOrCommand.length > 80 ? "…" : ""}"`);
     }
     if (PLANNING_WRITE_TOOLS.has(tool)) {
         if (!pathOrCommand) {
-            return { block: true, reason: blockReason(unitType, policy.mode, `${tool} called with empty path`) };
+            return planningBlock(unitType, policy.mode, `${tool} called with empty path`);
         }
         const absPath = isAbsolute(pathOrCommand) ? pathOrCommand : resolve(basePath, pathOrCommand);
         // Always allow .gsd/ writes — that's where planning artifacts live.
@@ -762,10 +760,7 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
         if (policy.mode === "docs" && matchesAllowedGlob(absPath, basePath, policy.allowedPathGlobs)) {
             return { block: false };
         }
-        return {
-            block: true,
-            reason: blockReason(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`),
-        };
+        return planningBlock(unitType, policy.mode, `cannot ${tool} "${pathOrCommand}" — writes are restricted to .gsd/${policy.mode === "docs" ? " and " + policy.allowedPathGlobs.join(", ") : ""}`);
     }
     // Unknown tool name — pass through. Other layers (queue, pending-gate,
     // CONTEXT.md write) catch known mutating shapes; defaulting to allow here

package/dist/resources/extensions/gsd/browser-evidence.js

@@ -1,17 +1,44 @@
 // Project/App: gsd-pi
 // File Purpose: Shared browser-observable UAT requirement and evidence detection.
-export const BROWSER_REQUIREMENT_RE = /\b(?:browser|file:\/\/|localhost|dom|localstorage|click(?:ing|ed)?|button|screenshot|snapshot|reload(?:ed)?|page refresh|user-visible|strikethrough|search box)\b/i;
+export const BROWSER_REQUIREMENT_RE = /\b(?:file:\/\/|localhost|playwright|chrome|screenshot|snapshot|browser_(?:assert|batch|find|verify|snapshot_refs))\b|\b(?:open|launch|navigate|load|visit|serve|start)\b.{0,80}\b(?:browser|page|localhost|file:\/\/)\b|\bbrowser\s+(?:check|session|test|uat|tool|automation|interaction|flow)\b/i;
 export const NO_BROWSER_EVIDENCE_RE = /\b(?:no|without|not|wasn'?t|isn'?t)\s+(?:automated\s+)?(?:live\s+)?browser(?:\s+(?:session|test|uat))?|\bno\s+automated\s+browser\b|\bnot\s+conducted\b/i;
 export const BROWSER_RUNTIME_RE = /\b(?:browser|playwright|chrome|camoufox|browser_(?:assert|batch|find|verify|snapshot_refs)|screenshot|snapshot|file:\/\/|localhost)\b/i;
 export const BROWSER_ACTION_RE = /\b(?:open(?:ed)?|navigate(?:d)?|click(?:ed)?|type(?:d)?|reload(?:ed)?|capture(?:d)?|screenshot|snapshot)\b/i;
 export const BROWSER_ASSERTION_RE = /\b(?:assert(?:ed|ion)?|observed|confirmed|verified|expected|visible|text|count|label|strikethrough|localstorage|screenshot|snapshot|passed)\b/i;
+const NON_REQUIREMENT_BROWSER_HEADING_RE = /^(?:not\s+proven|not\s+covered|out\s+of\s+scope|deferred|follow-?ups?|known\s+limitations|notes\s+for\s+tester)\b/i;
+const NON_REQUIREMENT_BROWSER_LINE_RE = /\b(?:deferred|not\s+proven|not\s+covered|out\s+of\s+scope|future\s+slice|follow-?up|no\s+(?:live\s+)?browser|without\s+(?:a\s+)?browser|not\s+(?:a\s+)?browser)\b/i;
 export function compactTextParts(parts) {
     return parts.flatMap((part) => Array.isArray(part) ? part : [part])
         .filter((part) => typeof part === "string" && part.trim().length > 0)
         .join("\n");
 }
 export function hasBrowserRequiredText(text) {
-    return BROWSER_REQUIREMENT_RE.test(text);
+    let inNonRequirementSection = false;
+    let nonRequirementDepth = 0;
+    for (const line of text.split(/\r?\n/)) {
+        const headingMatch = line.match(/^(#{1,6})\s+(.+?)\s*$/);
+        if (headingMatch) {
+            const depth = headingMatch[1].length;
+            const title = headingMatch[2] ?? "";
+            // Only update section context when at the same or higher level than the
+            // heading that opened the non-requirement zone. A sub-heading deeper than
+            // the opening heading must not escape or re-enter the zone on its own.
+            if (!inNonRequirementSection || depth <= nonRequirementDepth) {
+                inNonRequirementSection = NON_REQUIREMENT_BROWSER_HEADING_RE.test(title);
+                nonRequirementDepth = inNonRequirementSection ? depth : 0;
+            }
+            // Check the heading title itself — section state is already updated, so
+            // we correctly skip headings that opened a non-requirement zone.
+            if (!inNonRequirementSection && BROWSER_REQUIREMENT_RE.test(title))
+                return true;
+            continue;
+        }
+        if (inNonRequirementSection || NON_REQUIREMENT_BROWSER_LINE_RE.test(line))
+            continue;
+        if (BROWSER_REQUIREMENT_RE.test(line))
+            return true;
+    }
+    return false;
 }
 export function hasBrowserEvidenceText(text) {
     if (!text.trim())

package/dist/resources/extensions/gsd/closeout-consistency-gate.js

@@ -0,0 +1,61 @@
+// Project/App: gsd-pi
+// File Purpose: Shared DB-backed guard for milestone closeout finalization.
+import { getDbPath, getLatestAssessmentByScope, getMilestone, getMilestoneSlices, getPendingGates, getSliceTasks, isDbAvailable, refreshOpenDatabaseFromDisk, } from "./gsd-db.js";
+import { isClosedStatus } from "./status-guards.js";
+export const CLOSEOUT_CONSISTENCY_BLOCKED_REASON = "closeout-consistency-blocked";
+function blocked(reason, message) {
+    return {
+        ok: false,
+        reason,
+        recoveryReason: CLOSEOUT_CONSISTENCY_BLOCKED_REASON,
+        message,
+    };
+}
+function isFileBackedDbPath(path) {
+    return Boolean(path && path !== ":memory:");
+}
+export function checkCloseoutConsistencyGate(milestoneId, options = {}) {
+    if (!isDbAvailable()) {
+        return blocked("db-unavailable", `Closeout consistency blocked for ${milestoneId}: canonical DB is unavailable.`);
+    }
+    if (options.refreshFromDisk && isFileBackedDbPath(getDbPath()) && !refreshOpenDatabaseFromDisk()) {
+        return blocked("db-refresh-failed", `Closeout consistency blocked for ${milestoneId}: canonical DB refresh failed.`);
+    }
+    const milestone = getMilestone(milestoneId);
+    if (!milestone) {
+        return blocked("milestone-missing", `Closeout consistency blocked for ${milestoneId}: milestone is missing from canonical DB.`);
+    }
+    if (!isClosedStatus(milestone.status)) {
+        return blocked("milestone-open", `Closeout consistency blocked for ${milestoneId}: canonical DB milestone status is "${milestone.status}".`);
+    }
+    if (milestone.status !== "skipped") {
+        const validation = getLatestAssessmentByScope(milestoneId, "milestone-validation");
+        if (validation?.status !== "pass") {
+            return blocked("validation-not-pass", `Closeout consistency blocked for ${milestoneId}: latest milestone validation is "${validation?.status ?? "absent"}".`);
+        }
+    }
+    const slices = getMilestoneSlices(milestoneId);
+    if (slices.length === 0 && milestone.status !== "skipped") {
+        return blocked("slice-missing", `Closeout consistency blocked for ${milestoneId}: no slices exist in canonical DB.`);
+    }
+    for (const slice of slices) {
+        if (!isClosedStatus(slice.status)) {
+            return blocked("slice-open", `Closeout consistency blocked for ${milestoneId}: slice ${slice.id} status is "${slice.status}".`);
+        }
+        for (const task of getSliceTasks(milestoneId, slice.id)) {
+            if (!isClosedStatus(task.status)) {
+                return blocked("task-open", `Closeout consistency blocked for ${milestoneId}: task ${slice.id}/${task.id} status is "${task.status}".`);
+            }
+        }
+        const pendingGate = getPendingGates(milestoneId, slice.id)[0];
+        if (pendingGate) {
+            return blocked("quality-gate-pending", `Closeout consistency blocked for ${milestoneId}: quality gate ${pendingGate.gate_id} is still pending for ${slice.id}.`);
+        }
+    }
+    return { ok: true };
+}
+export function formatCloseoutConsistencyBlock(result) {
+    if (result.ok)
+        return "";
+    return `${result.message} Recovery reason: ${result.recoveryReason}. Resolve the canonical DB state and run /gsd auto to retry.`;
+}

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

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
 import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
-export const GSD_COMMAND_DESCRIPTION = "GSD — Git Ship Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|report|queue|quick|discuss|capture|triage|dispatch|verdict|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|closeout|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|memory|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|upgrade|fast|mcp|rethink|workflow|codebase|notifications|ship|do|usage|context|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
+export const GSD_COMMAND_DESCRIPTION = "GSD — Git Ship Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|report|queue|quick|discuss|capture|triage|dispatch|verdict|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|closeout|rebuild|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|memory|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|upgrade|fast|mcp|rethink|workflow|codebase|notifications|ship|do|usage|context|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 — run one unit, then pause" },
@@ -32,6 +32,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "export", desc: "Alias for /gsd report" },
     { cmd: "cleanup", desc: "Remove merged branches or snapshots" },
     { cmd: "closeout", desc: "Recover failed git closeout actions (status, retry, resolve)" },
+    { cmd: "rebuild", desc: "Rebuild markdown projections from the canonical DB" },
     { cmd: "model", desc: "Switch the active session model or open a picker" },
     { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
     { cmd: "prefs", desc: "Manage preferences (model selection, timeouts, etc.)" },
@@ -201,6 +202,10 @@ const NESTED_COMPLETIONS = {
         { cmd: "retry", desc: "Retry the latest failed closeout git action" },
         { cmd: "resolve", desc: "Mark closeout resolved after the worktree is clean" },
     ],
+    rebuild: [
+        { cmd: "markdown", desc: "Rebuild markdown projections from the canonical DB" },
+        { cmd: "database", desc: "Reserved for DB-native rebuilds; does not import markdown" },
+    ],
     knowledge: [
         { cmd: "rule", desc: "Add a project rule (always/never do X)" },
         { cmd: "pattern", desc: "Add a code pattern to follow" },

package/dist/resources/extensions/gsd/commands/handlers/core.js

@@ -51,6 +51,7 @@ export function showHelp(ctx, args = "") {
         "  /gsd keys           API key manager (LLM + tool keys)",
         "  /gsd doctor         Diagnose and repair .gsd/ state",
         "  /gsd closeout       Recover failed git closeout actions",
+        "  /gsd rebuild        Rebuild markdown projections from the DB  [markdown]",
         "",
         "Use /gsd help full for the complete command reference.",
     ];
@@ -68,7 +69,7 @@ export function showHelp(ctx, args = "") {
         "  /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 dispatch       Dispatch a specific phase directly  [research|plan|execute|complete|validate|reassess|uat|replan]",
         "  /gsd verdict <v>    Override milestone validation verdict  [pass|needs-attention|needs-remediation] [--milestone Mxxx] [--rationale \"...\"]",
         "  /gsd parallel       Parallel milestone orchestration  [start|status|stop|pause|resume|merge|watch]",
         "  /gsd workflow       Custom workflow lifecycle  [new|run|list|validate|pause|resume]",
@@ -132,7 +133,7 @@ export function showHelp(ctx, args = "") {
         "  /gsd skill-health   Skill lifecycle dashboard",
         "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
         "  /gsd fast           Toggle OpenAI service tier  [on|off|flex|status]",
-        "  /gsd mcp            MCP server management  [status|check|test|enable|disable|import|delete|init]",
+        "  /gsd mcp            MCP server management  [status|check|discover|test|enable|disable|import|delete|init]",
         "",
         "MAINTENANCE",
         "  /gsd doctor         Diagnose and repair .gsd/ state  [audit|fix|heal] [scope]",
@@ -141,6 +142,9 @@ export function showHelp(ctx, args = "") {
         "  /gsd export         Alias for /gsd report",
         "  /gsd cleanup        Remove merged branches or snapshots  [branches|snapshots]",
         "  /gsd closeout       Recover failed git closeout actions  [status|retry|resolve] [unit-id]",
+        "  /gsd rebuild markdown  Rebuild markdown projections from the canonical DB",
+        "  /gsd rebuild database  Reserved for DB-native rebuilds; does not import markdown",
+        "  /gsd recover --confirm Import markdown into the DB after DB loss/corruption",
         "  /gsd worktree       Manage worktrees from the TUI  [list|merge|clean|remove]",
         "  /gsd migrate        Migrate .planning/ (v1) to DB-backed .gsd/ with backup + audit",
         "  /gsd remote         Control remote auto-mode  [slack|discord|status|disconnect]",

package/dist/resources/extensions/gsd/commands/handlers/ops.js

@@ -4,7 +4,7 @@ import { handleDoctor, handleCapture, handleKnowledge, handleRunHook, handleSkil
 import { handleInspect } from "../../commands-inspect.js";
 import { handleLogs } from "../../commands-logs.js";
 import { handleDebug } from "../../commands-debug.js";
-import { handleCleanupBranches, handleCleanupSnapshots, handleSkip, handleCleanupProjects, handleCleanupWorktrees, handleRecover } from "../../commands-maintenance.js";
+import { handleCleanupBranches, handleCleanupSnapshots, handleSkip, handleCleanupProjects, handleCleanupWorktrees, handleRecover, handleRebuild } from "../../commands-maintenance.js";
 import { handleExport } from "../../export.js";
 import { handleHistory } from "../../history.js";
 import { handleUndo } from "../../undo.js";
@@ -130,8 +130,12 @@ export async function handleOpsCommand(trimmed, ctx, pi) {
         await handleSkip(trimmed.replace(/^skip\s*/, "").trim(), ctx, projectRoot());
         return true;
     }
-    if (trimmed === "recover") {
-        await handleRecover(ctx, projectRoot());
+    if (trimmed === "recover" || trimmed.startsWith("recover ")) {
+        await handleRecover(ctx, projectRoot(), trimmed.replace(/^recover\s*/, "").trim());
+        return true;
+    }
+    if (trimmed === "rebuild" || trimmed.startsWith("rebuild ")) {
+        await handleRebuild(ctx, projectRoot(), trimmed.replace(/^rebuild\s*/, "").trim());
         return true;
     }
     if (trimmed === "closeout" || trimmed.startsWith("closeout ")) {
@@ -262,8 +266,8 @@ Examples:
         await handleInspect(ctx);
         return true;
     }
-    if (trimmed === "update" || trimmed === "upgrade") {
-        await handleUpdate(ctx);
+    if (trimmed === "update" || trimmed.startsWith("update ") || trimmed === "upgrade" || trimmed.startsWith("upgrade ")) {
+        await handleUpdate(ctx, trimmed.replace(/^(?:update|upgrade)\s*/, "").trim());
         return true;
     }
     if (trimmed === "fast" || trimmed.startsWith("fast ")) {