@opengsd/gsd-pi 1.1.1-dev.616a1a1 → 1.1.1-dev.74e8dd1

package/src/resources/extensions/gsd/bootstrap/exec-tools.ts

@@ -25,6 +25,57 @@ async function loadContextModePreferences(baseDir: string) {
 }
 
 export function registerExecTools(pi: ExtensionAPI): void {
+  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 as Parameters<typeof executeUatExec>[0], {
+        baseDir,
+        preferences: await loadContextModePreferences(baseDir),
+      });
+    },
+  });
+
   pi.registerTool({
     name: "gsd_exec",
     label: "Exec (Sandboxed)",

package/src/resources/extensions/gsd/bootstrap/register-hooks.ts

@@ -36,7 +36,9 @@ import { resolveSkillManifest } from "../skill-manifest.js";
 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_WORKFLOW_TOOL_NAMES } from "../tool-presentation-plan.js";
 
 let approvalQuestionAbortInFlight = false;
 
@@ -123,6 +125,7 @@ export const MINIMAL_GSD_TOOL_NAMES = [
   "gsd_resume",
   "gsd_milestone_status",
   "gsd_checkpoint_db",
+  "gsd_plan_milestone",
   "memory_query",
   "capture_thought",
 ] as const;
@@ -226,6 +229,9 @@ export function buildMinimalAutoGsdToolSet(
   unitType: string | undefined,
   registeredToolNames: readonly string[] = activeToolNames,
 ): string[] {
+  if (unitType === "run-uat") {
+    return buildRunUatGsdToolSet(activeToolNames, registeredToolNames);
+  }
   const unitTools = unitType ? AUTO_UNIT_SCOPED_TOOLS[unitType] ?? [] : [];
   const autoBaseTools = new Set<string>(MINIMAL_AUTO_BASE_TOOL_NAMES);
   const availableBaseTools = registeredToolNames.filter((name) => autoBaseTools.has(name));
@@ -240,6 +246,17 @@ export function buildMinimalAutoGsdToolSet(
   return withPreservedShimTools([...new Set([...preserved, ...scoped])]);
 }
 
+export function buildRunUatGsdToolSet(
+  activeToolNames: readonly string[],
+  registeredToolNames: readonly string[] = activeToolNames,
+): string[] {
+  const scoped = resolveScopedToolNames(
+    [...activeToolNames, ...registeredToolNames],
+    [...RUN_UAT_WORKFLOW_TOOL_NAMES, "subagent", ...RUN_UAT_BROWSER_TOOL_NAMES],
+  );
+  return [...new Set(scoped)];
+}
+
 export function buildMinimalGsdWorkflowToolSet(
   activeToolNames: readonly string[],
   registeredToolNames: readonly string[] = activeToolNames,
@@ -1022,9 +1039,8 @@ export function registerHooks(
     if (result.block) return result;
   });
 
-  // ── 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 as Record<string, unknown>);
 
@@ -1041,17 +1057,28 @@ export function registerHooks(
       }
     }
 
-    // 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 };
       }
     }
   });
@@ -1320,19 +1347,27 @@ export function registerHooks(
     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,
+      guidedUnit?.unitType === "run-uat" ? aliasFilteredCompatible : providerCompatible,
       event.requestCustomMessages,
-      registeredToolNames,
+      guidedUnit?.unitType === "run-uat" ? compatibleRegisteredToolNames : registeredToolNames,
       guidedUnit?.unitType,
     );
     if (requestScoped) {
@@ -1342,9 +1377,11 @@ export function registerHooks(
     if (dash.active && dash.currentUnit) {
       return {
         toolNames: buildMinimalAutoGsdToolSet(
-          providerCompatible,
+          dash.currentUnit.type === "run-uat" ? aliasFilteredCompatible : providerCompatible,
           dash.currentUnit.type,
-          resolveRegisteredToolNames(pi, event.activeToolNames),
+          dash.currentUnit.type === "run-uat"
+            ? compatibleRegisteredToolNames
+            : resolveRegisteredToolNames(pi, event.activeToolNames),
         ),
       };
     }

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

@@ -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, {
@@ -777,8 +787,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.
@@ -825,7 +836,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,7 +845,7 @@ 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);
+        warnMissingControlledDispatchAgentClasses(unitType, policy.mode, tool);
         return {
           block: true,
           reason: blockReason(
@@ -857,7 +868,7 @@ export function shouldBlockPlanningUnit(
           reason: blockReason(
             unitType,
             policy.mode,
-            `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from planning-dispatch units`,
+            `subagent dispatch of "${globallyDisallowed}" not permitted; only read-only specialists (${allowedPlanningDispatchAgentsList()}) may be dispatched from ${policy.mode} units`,
           ),
         };
       }

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 ")) {

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

@@ -1,11 +1,14 @@
 /**
  * GSD Maintenance — cleanup, skip, dry-run, and recover handlers.
  *
- * Contains: handleCleanupBranches, handleCleanupSnapshots, handleCleanupWorktrees, handleSkip, handleDryRun, handleRecover
+ * Contains: handleCleanupBranches, handleCleanupSnapshots, handleCleanupWorktrees, handleSkip, handleDryRun, handleRecover, handleRebuild
  */
 
 import type { ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
 import { deriveState } from "./state.js";
+import { gsdProjectionRoot, gsdRoot } from "./paths.js";
 import { nativeBranchList, nativeDetectMainBranch, nativeBranchListMerged, nativeBranchDelete, nativeForEachRef, nativeUpdateRef } from "./native-git-bridge.js";
 import { logWarning } from "./workflow-logger.js";
 
@@ -478,6 +481,39 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC
   ctx.ui.notify(lines.join("\n"), "info");
 }
 
+function recoverConfirmed(args: string): boolean {
+  return args
+    .split(/\s+/)
+    .map((part) => part.trim().toLowerCase())
+    .some((part) => part === "--confirm" || part === "--yes" || part === "confirm");
+}
+
+async function confirmRecover(ctx: ExtensionCommandContext, args: string): Promise<boolean> {
+  if (recoverConfirmed(args)) return true;
+
+  const warning = [
+    "gsd recover imports markdown into the database.",
+    "It clears and reconstructs milestone, slice, and task hierarchy rows from rendered markdown.",
+    "Use /gsd rebuild markdown for normal DB-to-markdown realignment.",
+  ].join("\n");
+
+  if (typeof ctx.ui.confirm === "function") {
+    const confirmed = await ctx.ui.confirm(
+      "Import markdown into the DB?",
+      `${warning}\n\nContinue only if the DB is lost or corrupt and markdown is the source you intend to import.`,
+    );
+    if (confirmed) return true;
+    ctx.ui.notify("gsd recover cancelled. No database changes made.", "info");
+    return false;
+  }
+
+  ctx.ui.notify(
+    `${warning}\n\nNo database changes made. Re-run /gsd recover --confirm to proceed.`,
+    "warning",
+  );
+  return false;
+}
+
 /**
  * `gsd recover` — Reconstruct DB hierarchy state from rendered markdown on disk.
  *
@@ -487,7 +523,7 @@ export async function handleCleanupProjects(args: string, ctx: ExtensionCommandC
  *
  * Prints counts of recovered items and the resulting project phase.
  */
-export async function handleRecover(ctx: ExtensionCommandContext, basePath: string): Promise<void> {
+export async function handleRecover(ctx: ExtensionCommandContext, basePath: string, args = ""): Promise<void> {
   const { isDbAvailable: dbAvailable, clearEngineHierarchy, transaction: dbTransaction } = await import("./gsd-db.js");
   const { migrateHierarchyToDb } = await import("./md-importer.js");
   const { invalidateStateCache } = await import("./state.js");
@@ -497,6 +533,8 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri
     return;
   }
 
+  if (!(await confirmRecover(ctx, args))) return;
+
   try {
     // 1. Delete + re-populate inside a single transaction for atomicity.
     //    clearEngineHierarchy() uses transaction() internally but transaction()
@@ -542,3 +580,160 @@ export async function handleRecover(ctx: ExtensionCommandContext, basePath: stri
     ctx.ui.notify(`gsd recover failed: ${msg}`, "error");
   }
 }
+
+function normalizeArtifactPath(value: string): string {
+  return value.replace(/\\/g, "/");
+}
+
+function pathWithin(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel.length === 0 || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function artifactPathForDb(basePath: string, absPath: string): string {
+  const projectionRoot = gsdProjectionRoot(basePath);
+  const root = pathWithin(projectionRoot, absPath) ? projectionRoot : gsdRoot(basePath);
+  return normalizeArtifactPath(relative(root, absPath));
+}
+
+function quarantineRelativePath(basePath: string, absPath: string): string {
+  for (const root of [gsdProjectionRoot(basePath), gsdRoot(basePath)]) {
+    if (pathWithin(root, absPath)) {
+      return normalizeArtifactPath(relative(root, absPath));
+    }
+  }
+  return normalizeArtifactPath(absPath.replace(/^[/\\]+/, ""));
+}
+
+function uniquePath(path: string): string {
+  if (!existsSync(path)) return path;
+  let idx = 2;
+  while (existsSync(`${path}.${idx}`)) idx++;
+  return `${path}.${idx}`;
+}
+
+function resolveDiskArtifactPath(basePath: string, artifactPath: string): string {
+  if (isAbsolute(artifactPath)) return artifactPath;
+  const candidates = [
+    join(gsdProjectionRoot(basePath), artifactPath),
+    join(gsdRoot(basePath), artifactPath),
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0]!;
+}
+
+function quarantineProjectionFile(basePath: string, absPath: string, stamp: string): string {
+  const rel = quarantineRelativePath(basePath, absPath);
+  const target = uniquePath(join(gsdProjectionRoot(basePath), "quarantine", "projections", stamp, rel));
+  mkdirSync(dirname(target), { recursive: true });
+  renameSync(absPath, target);
+  return target;
+}
+
+type RebuildTarget = "markdown" | "database" | "usage";
+
+function parseRebuildTarget(args: string): RebuildTarget {
+  const trimmed = args.trim().toLowerCase();
+  if (!trimmed || trimmed === "markdown") return "markdown";
+  if (trimmed === "database" || trimmed === "db") return "database";
+  return "usage";
+}
+
+/**
+ * `gsd rebuild markdown` — Re-render markdown projections from the authoritative DB.
+ *
+ * This is the DB-first realignment command. It does not import markdown into
+ * the DB. Completion SUMMARY files that contradict open DB rows are preserved
+ * under `.gsd/quarantine/projections/` before DB projections are rendered.
+ */
+export async function handleRebuild(ctx: ExtensionCommandContext, basePath: string, args = ""): Promise<void> {
+  const { isDbAvailable: dbAvailable, deleteArtifactByPath } = await import("./gsd-db.js");
+  const { detectArtifactDbDrift } = await import("./state-reconciliation/drift/artifact-db.js");
+  const { renderAllFromDb } = await import("./markdown-renderer.js");
+  const { invalidateStateCache } = await import("./state.js");
+
+  const target = parseRebuildTarget(args);
+  if (target === "usage") {
+    ctx.ui.notify(
+      [
+        "Usage:",
+        "  /gsd rebuild markdown   Rebuild markdown projections from the canonical DB",
+        "  /gsd rebuild database   Reserved for DB-native rebuilds; does not import markdown",
+      ].join("\n"),
+      "warning",
+    );
+    return;
+  }
+
+  if (target === "database") {
+    ctx.ui.notify(
+      [
+        "gsd rebuild database is reserved for DB-native rebuilds.",
+        "It will not import markdown projections into the DB.",
+        "For normal realignment, run /gsd rebuild markdown.",
+        "If the DB is lost or corrupt and markdown is the source to import, run /gsd recover --confirm.",
+      ].join("\n"),
+      "warning",
+    );
+    return;
+  }
+
+  if (!dbAvailable()) {
+    ctx.ui.notify("gsd rebuild markdown: No database open. Run a GSD command first to initialize the DB.", "error");
+    return;
+  }
+
+  try {
+    invalidateStateCache();
+    const state = await deriveState(basePath);
+    const drifts = detectArtifactDbDrift(state, { basePath, state });
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    const quarantined: string[] = [];
+    const seen = new Set<string>();
+
+    for (const drift of drifts) {
+      if (drift.kind !== "artifact-db-status-divergence") continue;
+      if (drift.artifactType !== "SUMMARY" || !drift.artifactPath) continue;
+      const absPath = resolveDiskArtifactPath(basePath, drift.artifactPath);
+      if (seen.has(absPath) || !existsSync(absPath)) continue;
+      seen.add(absPath);
+      const artifactDbPath = artifactPathForDb(basePath, absPath);
+      const target = quarantineProjectionFile(basePath, absPath, stamp);
+      deleteArtifactByPath(artifactDbPath);
+      quarantined.push(target);
+    }
+
+    const rendered = await renderAllFromDb(basePath);
+    invalidateStateCache();
+
+    const lines = [
+      "gsd rebuild markdown: rebuilt markdown projections from the canonical DB",
+      `  Rendered:    ${rendered.rendered}`,
+      `  Skipped:     ${rendered.skipped}`,
+      `  Quarantined: ${quarantined.length}`,
+    ];
+    if (rendered.errors.length > 0) {
+      lines.push(`  Errors:      ${rendered.errors.length}`);
+      for (const err of rendered.errors.slice(0, 5)) {
+        lines.push(`    - ${err}`);
+      }
+      if (rendered.errors.length > 5) {
+        lines.push(`    - ${rendered.errors.length - 5} more`);
+      }
+    }
+    if (quarantined.length > 0) {
+      lines.push("", "  Quarantine:");
+      for (const target of quarantined.slice(0, 5)) {
+        lines.push(`    - ${target}`);
+      }
+      if (quarantined.length > 5) {
+        lines.push(`    - ${quarantined.length - 5} more`);
+      }
+    }
+
+    ctx.ui.notify(lines.join("\n"), rendered.errors.length > 0 ? "warning" : "success");
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logWarning("command", `rebuild failed: ${msg}`);
+    ctx.ui.notify(`gsd rebuild failed: ${msg}`, "error");
+  }
+}