@opengsd/gsd-pi 1.1.1-dev.74e8dd1 → 1.1.1-dev.75048e7

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

@@ -1774,10 +1774,17 @@ export function createWiredAutoOrchestrationModule(ctx, pi, dispatchBasePath, ru
             async reconcileBeforeDispatch() {
                 const activeBasePath = getLiveDispatchBasePath();
                 const result = await reconcileBeforeDispatch(activeBasePath);
-                if (result.blockers.length > 0) {
+                // Failure-path summaries written by gsd_summary_save create
+                // artifact-db-status-divergence blockers for tasks that are still
+                // pending (gsd_task_complete never ran). These tasks can still be
+                // dispatched and the drift self-heals once they complete successfully.
+                const hardBlockers = result.blockers.filter((b) => !b.includes("has SUMMARY artifact while DB status is") &&
+                    !b.includes("has SUMMARY on disk while DB status is") &&
+                    !b.includes("has task SUMMARY artifacts but no DB tasks"));
+                if (hardBlockers.length > 0) {
                     return {
                         ok: false,
-                        reason: result.blockers[0],
+                        reason: hardBlockers[0],
                         stateSnapshot: result.stateSnapshot,
                     };
                 }

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

@@ -65,6 +65,9 @@ function readDetails(result) {
 }
 // eslint-disable-next-line @typescript-eslint/no-explicit-any -- result shape varies by tool
 function formatToolErrorText(result, details) {
+    if (typeof details?.displayReason === "string" && details.displayReason) {
+        return details.displayReason;
+    }
     const message = details?.error
         ?? result?.content?.find((entry) => entry.type === "text")?.text
         ?? "unknown";
@@ -405,6 +408,9 @@ export function registerDbTools(pi) {
         kind: StringEnum(["gsd_uat_exec", "gsd_exec", "screenshot", "log", "url", "browser"], { description: "Evidence kind" }),
         ref: Type.String({ description: "Evidence ID, approved .gsd path, or URL" }),
         note: Type.Optional(Type.String({ description: "Short evidence note" })),
+        unitType: Type.Optional(Type.String({ description: "Unit that produced the evidence" })),
+        tool: Type.Optional(Type.String({ description: "Tool that produced the evidence" })),
+        executionId: Type.Optional(Type.String({ description: "Stable execution or artifact id" })),
     });
     const uatCheck = Type.Object({
         id: Type.String({ description: "Stable check ID from the UAT spec" }),
@@ -416,17 +422,17 @@ export function registerDbTools(pi) {
         nonAutomatable: Type.Optional(Type.Boolean({ description: "True when the check is explicitly non-automatable" })),
     });
     const toolPresentationBlock = Type.Object({
-        surface: StringEnum(["provider-tools", "claude-code-sdk", "mcp", "hybrid"], { description: "Tool presentation surface" }),
+        surface: Type.Optional(StringEnum(["provider-tools", "claude-code-sdk", "mcp", "hybrid"], { description: "Tool presentation surface" })),
         model: Type.Optional(Type.Object({
             provider: Type.Optional(Type.String()),
             api: Type.Optional(Type.String()),
             id: Type.Optional(Type.String()),
         })),
-        presentedTools: Type.Array(Type.String(), { description: "Tool names actually presented to the model" }),
-        blockedTools: Type.Array(Type.Object({
+        presentedTools: Type.Optional(Type.Array(Type.String(), { description: "Tool names actually presented to the model" })),
+        blockedTools: Type.Optional(Type.Array(Type.Object({
             name: Type.String(),
             reason: Type.String(),
-        }), { description: "Tool names blocked from the model with reasons" }),
+        }), { description: "Tool names blocked from the model with reasons" })),
         aliases: Type.Optional(Type.Array(Type.Object({
             requested: Type.String(),
             canonical: Type.String(),
@@ -448,12 +454,12 @@ export function registerDbTools(pi) {
             "Do not use raw gsd_summary_save as a substitute for UAT results.",
         ],
         parameters: Type.Object({
-            milestoneId: Type.String({ description: "Milestone ID (e.g. M001)" }),
-            sliceId: Type.String({ description: "Slice ID (e.g. S01)" }),
-            uatType: StringEnum(["artifact-driven", "browser-executable", "runtime-executable", "live-runtime", "mixed", "human-experience"], { description: "Declared UAT mode" }),
-            verdict: StringEnum(["PASS", "FAIL", "PARTIAL"], { description: "Overall UAT verdict" }),
-            checks: Type.Array(uatCheck, { description: "Structured check results" }),
-            presentation: toolPresentationBlock,
+            milestoneId: Type.Optional(Type.String({ description: "Milestone ID (e.g. M001)" })),
+            sliceId: Type.Optional(Type.String({ description: "Slice ID (e.g. S01)" })),
+            uatType: Type.Optional(Type.String({ description: "Declared UAT mode" })),
+            verdict: Type.Optional(Type.String({ description: "Overall UAT verdict: PASS, FAIL, or PARTIAL" })),
+            checks: Type.Optional(Type.Array(uatCheck, { description: "Structured check results" })),
+            presentation: Type.Optional(toolPresentationBlock),
             notes: Type.Optional(Type.String({ description: "Overall verdict rationale" })),
             attempt: Type.Optional(Type.String({ description: "Attempt number or auto" })),
             previousAttemptId: Type.Optional(Type.String({ description: "Prior attempt ID, when retrying" })),
@@ -788,7 +794,7 @@ export function registerDbTools(pi) {
                 recommendation: Type.String({ description: "Option id the executor recommends." }),
                 recommendationRationale: Type.String({ description: "Why the recommendation — 1–2 sentences." }),
                 continueWithDefault: Type.Boolean({
-                    description: "When true, loop continues (artifact logged for later review). When false, auto-mode pauses until the user resolves via /gsd escalate resolve.",
+                    description: "When true, the recommendation is recorded as the default, but auto-mode still pauses until the user resolves via /gsd escalate resolve.",
                 }),
             }, { description: "ADR-011 Phase 2: optional escalation payload. Only honored when phases.mid_execution_escalation is true." })),
             verificationEvidence: Type.Optional(Type.Array(Type.Object({
@@ -829,7 +835,7 @@ export function registerDbTools(pi) {
             sliceTitle: Type.String({ description: "Title of the slice" }),
             oneLiner: Type.String({ description: "One-line summary of what the slice accomplished" }),
             narrative: Type.String({ description: "Detailed narrative of what happened across all tasks" }),
-            verification: Type.String({ description: "What was verified across all tasks" }),
+            verification: Type.Optional(Type.String({ description: "What was verified across all tasks — if omitted, summary records verification as passed without detail." })),
             uatContent: Type.String({ description: "UAT test content (markdown body)" }),
             // ── Enrichment metadata (optional — defaults to empty) ────────────
             deviations: Type.Optional(Type.String({ description: "Deviations from the slice plan, or 'None.'" })),
@@ -1010,7 +1016,7 @@ export function registerDbTools(pi) {
         promptGuidelines: [
             "Use gsd_validate_milestone when all slices are done and the milestone needs validation before completion.",
             "Parameters: milestoneId, verdict, remediationRound, successCriteriaChecklist, sliceDeliveryAudit, crossSliceIntegration, requirementCoverage, verificationClasses (optional), verdictRationale, remediationPlan (optional).",
-            "If verification classes were planned, verificationClasses must include canonical class rows using the exact class names Contract, Integration, Operational, and UAT when present in planning.",
+            "If verification classes were planned, verificationClasses must be a complete canonical table with one row for every applicable planned class using the exact class names Contract, Integration, Operational, and UAT. Do not submit a partial table.",
             "Planned verification text marked as none/not required/not applicable/N/A (including suffixed variants such as 'not required - backend-only') is treated as not applicable and does not require a class row.",
             "If verdict is 'needs-remediation', also provide remediationPlan and use gsd_reassess_roadmap to add remediation slices to the roadmap.",
             "On success, returns validationPath where VALIDATION.md was written.",
@@ -1023,7 +1029,7 @@ export function registerDbTools(pi) {
             sliceDeliveryAudit: Type.String({ description: "Markdown table auditing each slice's claimed vs delivered output" }),
             crossSliceIntegration: Type.String({ description: "Markdown describing any cross-slice boundary mismatches" }),
             requirementCoverage: Type.String({ description: "Markdown describing any unaddressed requirements" }),
-            verificationClasses: Type.Optional(Type.String({ description: "Markdown describing verification class compliance and gaps using canonical class names (Contract, Integration, Operational, UAT) for each applicable planned class" })),
+            verificationClasses: Type.Optional(Type.String({ description: "Complete markdown table describing verification class compliance and gaps; include one canonical row for every applicable planned class (Contract, Integration, Operational, UAT)" })),
             verdictRationale: Type.String({ description: "Why this verdict was chosen" }),
             remediationPlan: Type.Optional(Type.String({ description: "Remediation plan (required if verdict is needs-remediation)" })),
         }),

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";
@@ -30,7 +30,7 @@ import { getGuidedUnitContext } from "../guided-unit-context.js";
 import { registerPlanMilestoneSchemaRecovery } from "./plan-milestone-schema-recovery.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_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.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 = [];
@@ -204,7 +204,12 @@ export function buildMinimalAutoGsdToolSet(activeToolNames, unitType, registered
     return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
 }
 export function buildRunUatGsdToolSet(activeToolNames, registeredToolNames = activeToolNames) {
-    const scoped = resolveScopedToolNames([...activeToolNames, ...registeredToolNames], [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent", ...RUN_UAT_BROWSER_TOOL_NAMES]);
+    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) {
@@ -382,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 };
@@ -389,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);
@@ -424,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);
         }
@@ -445,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();
@@ -464,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");
@@ -750,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 {
@@ -759,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);
                 }
             }
         }
@@ -843,8 +857,9 @@ 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 blocking ──
     pi.on("tool_call", async (event, ctx) => {

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";
@@ -643,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:
@@ -690,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))
@@ -711,10 +718,7 @@ export function shouldBlockPlanningUnit(toolName, pathOrCommand, basePath, unitT
             // instead of silently bypassing the gate.
             if (agentClasses === undefined) {
                 warnMissingControlledDispatchAgentClasses(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`),
-                };
+                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
@@ -724,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 ${policy.mode} 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.
@@ -768,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/handlers/ops.js

@@ -266,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 ")) {

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

@@ -5,6 +5,8 @@
  * handleRunHook, handleUpdate, handleSkillHealth
  */
 import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { createRequire } from "node:module";
 import { join, resolve as resolvePath, sep } from "node:path";
 import { homedir } from "node:os";
 import { deriveState } from "./state.js";
@@ -20,7 +22,10 @@ import { loadPrompt } from "./prompt-loader.js";
 import { isPnpmInstall } from "../../shared/package-manager-detection.js";
 import { buildDoctorHealIssuePayload, buildDoctorHealSummary, buildWorkflowDispatchContent, } from "./workflow-protocol.js";
 import { restoreGsdWorkflowTools, scopeGsdWorkflowToolsForDispatch, } from "./bootstrap/register-hooks.js";
+const GSD_PI_PACKAGE = "@opengsd/gsd-pi";
+const GSD_BROWSER_PACKAGE = "@opengsd/gsd-browser";
 const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/@opengsd%2fgsd-pi/latest";
+const BROWSER_UPDATE_REGISTRY_URL = "https://registry.npmjs.org/@opengsd%2fgsd-browser/latest";
 const UPDATE_FETCH_TIMEOUT_MS = 5000;
 // Detects a bun-installed gsd via `process.argv[1]`. Mirrors isBunInstall in
 // src/update-check.ts — duplicated because tsconfig.resources.json rootDir
@@ -47,11 +52,11 @@ function resolveInstallCommand(pkg) {
         return `pnpm add -g ${pkg}`;
     return `npm install -g ${pkg}`;
 }
-async function fetchLatestVersionForCommand() {
+async function fetchLatestVersionForCommand(registryUrl = UPDATE_REGISTRY_URL) {
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), UPDATE_FETCH_TIMEOUT_MS);
     try {
-        const res = await fetch(UPDATE_REGISTRY_URL, { signal: controller.signal });
+        const res = await fetch(registryUrl, { signal: controller.signal });
         if (!res.ok)
             return null;
         const data = (await res.json());
@@ -65,6 +70,19 @@ async function fetchLatestVersionForCommand() {
         clearTimeout(timeout);
     }
 }
+function resolveInstalledPackageVersionForCommand(packageName) {
+    try {
+        const requireFromHere = createRequire(import.meta.url);
+        const packageJsonPath = requireFromHere.resolve(`${packageName}/package.json`);
+        const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+        return typeof pkg.version === "string" && pkg.version.trim().length > 0
+            ? pkg.version.trim().replace(/^v/, "")
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function dispatchDoctorHeal(pi, scope, reportText, structuredIssues) {
     const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
     const workflow = readFileSync(workflowPath, "utf-8");
@@ -386,27 +404,74 @@ function compareSemverLocal(a, b) {
     }
     return 0;
 }
-export async function handleUpdate(ctx) {
+function formatCommandVersion(version) {
+    return version ? `v${version}` : "unknown";
+}
+function pickHigherVersionForCommand(a, b) {
+    if (!a)
+        return b;
+    if (!b)
+        return a;
+    return compareSemverLocal(a, b) >= 0 ? a : b;
+}
+// Mirrors resolveGsdBrowserPathVersion in src/update-check.ts — duplicated because
+// tsconfig.resources.json rootDir prevents importing from src/.
+function resolveGsdBrowserPathVersionForCommand(env = process.env) {
+    const explicit = env.GSD_BROWSER_PATH_VERSION?.trim();
+    if (explicit)
+        return explicit.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+    try {
+        const out = execFileSync("gsd-browser", ["--version"], {
+            encoding: "utf-8",
+            env,
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        });
+        return out.match(/\b(\d+\.\d+\.\d+)\b/)?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function handleUpdate(ctx, args = "") {
     const { execSync } = await import("node:child_process");
-    const NPM_PACKAGE = "@opengsd/gsd-pi";
-    const current = process.env.GSD_VERSION || "0.0.0";
-    ctx.ui.notify(`Current version: v${current}\nChecking npm registry...`, "info");
-    const latest = await fetchLatestVersionForCommand();
+    const target = args.trim();
+    const browserUpdate = target === "browser" || target === "gsd-browser";
+    if (target && !browserUpdate) {
+        ctx.ui.notify("Usage: /gsd update [browser]", "warning");
+        return;
+    }
+    const NPM_PACKAGE = browserUpdate ? GSD_BROWSER_PACKAGE : GSD_PI_PACKAGE;
+    const registryUrl = browserUpdate ? BROWSER_UPDATE_REGISTRY_URL : UPDATE_REGISTRY_URL;
+    const bundledVersion = browserUpdate
+        ? resolveInstalledPackageVersionForCommand(GSD_BROWSER_PACKAGE)
+        : null;
+    const current = browserUpdate
+        ? pickHigherVersionForCommand(bundledVersion, resolveGsdBrowserPathVersionForCommand())
+        : process.env.GSD_VERSION || "0.0.0";
+    const label = browserUpdate ? "gsd-browser version" : "version";
+    ctx.ui.notify(`Current ${label}: ${formatCommandVersion(current)}\nChecking npm registry...`, "info");
+    const latest = await fetchLatestVersionForCommand(registryUrl);
     if (!latest) {
         ctx.ui.notify("Failed to reach npm registry. Check your network connection.", "error");
         return;
     }
-    if (compareSemverLocal(latest, current) <= 0) {
-        ctx.ui.notify(`Already up to date (v${current}).`, "info");
+    if (current && compareSemverLocal(latest, current) <= 0) {
+        ctx.ui.notify(`Already up to date (${formatCommandVersion(current)}).`, "info");
         return;
     }
-    ctx.ui.notify(`Updating: v${current} → v${latest}...`, "info");
+    ctx.ui.notify(`Updating: ${formatCommandVersion(current)} → v${latest}...`, "info");
     const installCmd = resolveInstallCommand(`${NPM_PACKAGE}@latest`);
     try {
         execSync(installCmd, {
             stdio: ["ignore", "pipe", "ignore"],
         });
-        ctx.ui.notify(`Updated to v${latest}. Restart your GSD session to use the new version.`, "info");
+        const newPathVersion = browserUpdate ? resolveGsdBrowserPathVersionForCommand() : null;
+        const pathReady = !browserUpdate || (!!newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0);
+        ctx.ui.notify(browserUpdate
+            ? `Updated gsd-browser to v${latest}. Restart your GSD session to use the new browser automation version.` +
+                (pathReady ? "" : "\nNote: Ensure the npm global bin directory is on your PATH so MCP automation uses the updated binary.")
+            : `Updated to v${latest}. Restart your GSD session to use the new version.`, "info");
     }
     catch {
         ctx.ui.notify(`Update failed. Try manually: ${installCmd}`, "error");

package/dist/resources/extensions/gsd/commands-mcp-status.js

@@ -33,7 +33,8 @@ export function formatMcpInitResult(status, configPath, targetPath) {
         `Project: ${targetPath}`,
         `Config:   ${configPath}`,
         "",
-        "MCP-capable clients can now load the GSD workflow MCP server from this folder.",
+        "MCP-capable clients can now load the GSD workflow and gsd-browser MCP servers from this folder.",
+        "Pi Providers use the managed gsd-browser engine directly; this project config is for External MCP Clients.",
         "Restart or reconnect any client that already has this project open.",
     ].join("\n");
 }