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

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

@@ -4,7 +4,7 @@ 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, type ToolsPolicy } from "../unit-context-manifest.js";
 import { logWarning } from "../workflow-logger.js";
@@ -679,6 +679,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 },
@@ -692,7 +693,7 @@ export const ALLOWED_PLANNING_DISPATCH_AGENTS = new Set<string>(
     .map(([agentId]) => agentId),
 );
 
-let warnedMissingPlanningDispatchAgentClasses = false;
+let warnedMissingControlledDispatchAgentClasses = false;
 
 function isReadOnlySpecialist(agentId: string): boolean {
   const metadata = PLANNING_DISPATCH_AGENT_REGISTRY[agentId as keyof typeof PLANNING_DISPATCH_AGENT_REGISTRY];
@@ -703,11 +704,20 @@ function allowedPlanningDispatchAgentsList(): string {
   return [...ALLOWED_PLANNING_DISPATCH_AGENTS].join(", ");
 }
 
-function warnMissingPlanningDispatchAgentClasses(unitType: string, mode: string, toolName: string): void {
-  if (warnedMissingPlanningDispatchAgentClasses) return;
-  warnedMissingPlanningDispatchAgentClasses = true;
+function allowsControlledSubagentDispatch(
+  policy: ToolsPolicy,
+): policy is ToolsPolicy & { readonly allowedSubagents: readonly string[] } {
+  return (
+    (policy.mode === "planning-dispatch" || policy.mode === "verification") &&
+    Array.isArray((policy as { readonly allowedSubagents?: unknown }).allowedSubagents)
+  );
+}
+
+function warnMissingControlledDispatchAgentClasses(unitType: string, mode: string, toolName: string): void {
+  if (warnedMissingControlledDispatchAgentClasses) return;
+  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, {
@@ -762,6 +772,20 @@ function blockReason(unitType: string, mode: string, what: string): string {
   ].join(" ");
 }
 
+function planningBlock(unitType: string, mode: string, what: string): PlanningUnitBlockResult {
+  return {
+    block: true,
+    reason: blockReason(unitType, mode, what),
+    displayReason: GSD_PHASE_SCOPE_DISPLAY_REASON,
+  };
+}
+
+type PlanningUnitBlockResult = {
+  block: boolean;
+  reason?: string;
+  displayReason?: string;
+};
+
 /**
  * Planning-unit tool-policy enforcement. Returns { block } per the policy
  * resolved from the active unit's manifest:
@@ -777,8 +801,9 @@ function blockReason(unitType: string, mode: string, what: string): string {
  *   - "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.
@@ -801,7 +826,7 @@ export function shouldBlockPlanningUnit(
   agentClasses?: readonly string[],
   toolInput?: unknown,
   unitId?: string,
-): { block: boolean; reason?: string } {
+): PlanningUnitBlockResult {
   const tool = canonicalToolName(toolName);
   const autoScopeGuard = shouldBlockAutoUnitToolCall(unitType, toolName, toolInput, unitId);
   if (autoScopeGuard.block) return autoScopeGuard;
@@ -814,10 +839,10 @@ export function shouldBlockPlanningUnit(
     if (PLANNING_SAFE_TOOLS.has(tool)) return { block: false };
     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.
@@ -825,7 +850,7 @@ export function shouldBlockPlanningUnit(
   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;
@@ -834,15 +859,12 @@ export function shouldBlockPlanningUnit(
       // 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
@@ -852,57 +874,45 @@ export function shouldBlockPlanningUnit(
       }
       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 ? "…" : ""}"`,
-        ),
-      };
-    }
-    if (BASH_READ_ONLY_RE.test(pathOrCommand)) return { block: false };
-    return {
-      block: true,
-      reason: blockReason(
+      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 ? "…" : ""}"`,
-      ),
-    };
+        `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 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);
 
@@ -914,14 +924,11 @@ export function shouldBlockPlanningUnit(
       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,

package/src/resources/extensions/gsd/browser-evidence.ts

@@ -1,11 +1,13 @@
 // 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: Array<string | string[] | null | undefined>): string {
   return parts.flatMap((part) => Array.isArray(part) ? part : [part])
@@ -14,7 +16,29 @@ export function compactTextParts(parts: Array<string | string[] | null | undefin
 }
 
 export function hasBrowserRequiredText(text: string): boolean {
-  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: string): boolean {

package/src/resources/extensions/gsd/closeout-consistency-gate.ts

@@ -0,0 +1,137 @@
+// 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";
+
+export type CloseoutConsistencyFailureReason =
+  | "db-unavailable"
+  | "db-refresh-failed"
+  | "milestone-missing"
+  | "milestone-open"
+  | "validation-not-pass"
+  | "slice-missing"
+  | "slice-open"
+  | "task-open"
+  | "quality-gate-pending";
+
+export type CloseoutConsistencyResult =
+  | { ok: true }
+  | {
+      ok: false;
+      reason: CloseoutConsistencyFailureReason;
+      recoveryReason: typeof CLOSEOUT_CONSISTENCY_BLOCKED_REASON;
+      message: string;
+    };
+
+export interface CloseoutConsistencyOptions {
+  refreshFromDisk?: boolean;
+}
+
+function blocked(reason: CloseoutConsistencyFailureReason, message: string): CloseoutConsistencyResult {
+  return {
+    ok: false,
+    reason,
+    recoveryReason: CLOSEOUT_CONSISTENCY_BLOCKED_REASON,
+    message,
+  };
+}
+
+function isFileBackedDbPath(path: string | null): boolean {
+  return Boolean(path && path !== ":memory:");
+}
+
+export function checkCloseoutConsistencyGate(
+  milestoneId: string,
+  options: CloseoutConsistencyOptions = {},
+): CloseoutConsistencyResult {
+  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: CloseoutConsistencyResult): string {
+  if (result.ok) return "";
+  return `${result.message} Recovery reason: ${result.recoveryReason}. Resolve the canonical DB state and run /gsd auto to retry.`;
+}

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

@@ -14,7 +14,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 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";
+  "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: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -44,6 +44,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { 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.)" },
@@ -214,6 +215,10 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { 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/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -56,6 +56,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /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.",
   ];
@@ -74,7 +75,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /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]",
@@ -138,7 +139,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /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]",
@@ -147,6 +148,9 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /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/src/resources/extensions/gsd/commands/handlers/ops.ts

@@ -9,7 +9,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";
@@ -146,8 +146,12 @@ export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandCon
     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 ")) {
@@ -278,8 +282,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/src/resources/extensions/gsd/commands-handlers.ts

@@ -7,6 +7,8 @@
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@gsd/pi-coding-agent";
 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";
@@ -37,7 +39,10 @@ import {
   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
@@ -62,12 +67,12 @@ function resolveInstallCommand(pkg: string): string {
   return `npm install -g ${pkg}`;
 }
 
-async function fetchLatestVersionForCommand(): Promise<string | null> {
+async function fetchLatestVersionForCommand(registryUrl: string = UPDATE_REGISTRY_URL): Promise<string | null> {
   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()) as { version?: string };
     const latest = typeof data.version === "string" ? data.version.trim().replace(/^v/, "") : "";
@@ -79,6 +84,19 @@ async function fetchLatestVersionForCommand(): Promise<string | null> {
   }
 }
 
+function resolveInstalledPackageVersionForCommand(packageName: string): string | null {
+  try {
+    const requireFromHere = createRequire(import.meta.url);
+    const packageJsonPath = requireFromHere.resolve(`${packageName}/package.json`);
+    const pkg = JSON.parse(readFileSync(packageJsonPath, "utf-8")) as { version?: unknown };
+    return typeof pkg.version === "string" && pkg.version.trim().length > 0
+      ? pkg.version.trim().replace(/^v/, "")
+      : null;
+  } catch {
+    return null;
+  }
+}
+
 export function dispatchDoctorHeal(pi: ExtensionAPI, scope: string | undefined, reportText: string, structuredIssues: string): void {
   const workflowPath = process.env.GSD_WORKFLOW_PATH ?? join(gsdHome(), "agent", "GSD-WORKFLOW.md");
   const workflow = readFileSync(workflowPath, "utf-8");
@@ -473,34 +491,81 @@ function compareSemverLocal(a: string, b: string): number {
   return 0
 }
 
-export async function handleUpdate(ctx: ExtensionCommandContext): Promise<void> {
+function formatCommandVersion(version: string | null): string {
+  return version ? `v${version}` : "unknown";
+}
+
+function pickHigherVersionForCommand(a: string | null, b: string | null): string | null {
+  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: NodeJS.ProcessEnv = process.env): string | null {
+  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: ExtensionCommandContext, args = ""): Promise<void> {
   const { execSync } = await import("node:child_process");
 
-  const NPM_PACKAGE = "@opengsd/gsd-pi";
-  const current = process.env.GSD_VERSION || "0.0.0";
+  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 version: v${current}\nChecking npm registry...`, "info");
+  ctx.ui.notify(`Current ${label}: ${formatCommandVersion(current)}\nChecking npm registry...`, "info");
 
-  const latest = await fetchLatestVersionForCommand();
+  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"],
     });
+    const newPathVersion = browserUpdate ? resolveGsdBrowserPathVersionForCommand() : null;
+    const pathReady = !browserUpdate || (!!newPathVersion && compareSemverLocal(newPathVersion, latest) >= 0);
     ctx.ui.notify(
-      `Updated to v${latest}. Restart your GSD session to use the new version.`,
+      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 {