gsd-pi 2.82.0 → 3.0.0-dev.04f5ccf82

package/src/resources/extensions/gsd/clean-root-preflight.ts

@@ -8,21 +8,32 @@
  *
  * Design constraints (from Trek-e approval):
  *  - Warn the user before stashing (no silent surprises)
- *  - git stash push / git stash pop only — no custom stash management layer
- *  - Stash/pop errors are logged but MUST NOT block the merge itself
+ *  - git stash push / git stash apply+drop for targeted restore
+ *  - Stash/apply errors are logged but MUST NOT block the merge itself
  *  - Fast-path status check — clean trees pay no extra cost
  */
 
 import { execFileSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { GIT_NO_PROMPT_ENV } from "./git-constants.js";
 import { logWarning } from "./workflow-logger.js";
 import { nativeHasChanges } from "./native-git-bridge.js";
+import { listUnmergedGitPaths } from "./git-conflict-state.js";
 
 export interface PreflightResult {
   /** true when a stash was pushed and postflightPopStash should be called */
   stashPushed: boolean;
+  /** true when the merge must not start because dirty files need user action */
+  blocked?: boolean;
+  /** Machine-readable reason for blocked preflight. */
+  blockedReason?: "dirty-overlap" | "dirty-overlap-eval-failed" | "unmerged-conflicts" | "unmerged-conflicts-eval-failed";
   /** Unique marker embedded in the stash message for targeted restoration */
   stashMarker?: string;
+  /** Dirty paths that overlap the milestone branch diff and would conflict after merge */
+  overlappingPaths?: string[] | null;
+  /** Paths with unresolved Git conflict stages. */
+  conflictedPaths?: string[] | null;
   /** human-readable summary of what happened (empty string for clean trees) */
   summary: string;
 }
@@ -32,6 +43,193 @@ export interface PostflightResult {
   needsManualRecovery: boolean;
   message: string;
   stashRef?: string;
+  resolution?: "applied" | "already-present-dropped" | "already-present-preserved" | "manual-recovery";
+  collidedPaths?: string[];
+}
+
+function gitText(basePath: string, args: string[]): string {
+  return execFileSync("git", args, {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding: "utf-8",
+    env: GIT_NO_PROMPT_ENV,
+  });
+}
+
+function gitBuffer(basePath: string, args: string[]): Buffer {
+  return execFileSync("git", args, {
+    cwd: basePath,
+    stdio: ["ignore", "pipe", "pipe"],
+    env: GIT_NO_PROMPT_ENV,
+  });
+}
+
+function errorText(err: unknown): string {
+  if (!err || typeof err !== "object") return String(err);
+  const parts: string[] = [];
+  const stderr = (err as { stderr?: unknown }).stderr;
+  const stdout = (err as { stdout?: unknown }).stdout;
+  for (const value of [stderr, stdout]) {
+    if (typeof value === "string") parts.push(value);
+    else if (value instanceof Uint8Array) parts.push(Buffer.from(value).toString("utf-8"));
+  }
+  parts.push(err instanceof Error ? err.message : String(err));
+  return parts.filter(Boolean).join("\n");
+}
+
+function parseAlreadyExistsNoCheckoutPaths(text: string): string[] {
+  const paths: string[] = [];
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^(.+?) already exists, no checkout$/i.exec(line.trim());
+    if (match?.[1]) paths.push(match[1]);
+  }
+  return [...new Set(paths)];
+}
+
+function readZeroDelimitedPaths(output: string): string[] {
+  return output.split("\0").filter(Boolean);
+}
+
+function listDirtyPaths(basePath: string): string[] | null {
+  try {
+    const paths = new Set<string>();
+    for (const args of [
+      ["diff", "--name-only", "-z"],
+      ["diff", "--cached", "--name-only", "-z"],
+      ["ls-files", "--others", "--exclude-standard", "-z"],
+    ]) {
+      for (const path of readZeroDelimitedPaths(gitText(basePath, args))) {
+        paths.add(path);
+      }
+    }
+    return [...paths];
+  } catch {
+    return null;
+  }
+}
+
+function listMilestoneChangedPaths(basePath: string, milestoneId: string): string[] | null {
+  const milestoneBranch = `milestone/${milestoneId}`;
+  try {
+    gitText(basePath, ["rev-parse", "--verify", "--quiet", `refs/heads/${milestoneBranch}`]);
+  } catch {
+    return [];
+  }
+  try {
+    const mergeBase = gitText(basePath, ["merge-base", "HEAD", milestoneBranch]).trim();
+    if (!mergeBase) return null;
+    return readZeroDelimitedPaths(gitText(basePath, ["diff", "--name-only", "-z", mergeBase, milestoneBranch]));
+  } catch {
+    return null;
+  }
+}
+
+function findOverlappingDirtyMilestonePaths(basePath: string, milestoneId: string): string[] | null {
+  const dirtyPaths = listDirtyPaths(basePath);
+  const changedPaths = listMilestoneChangedPaths(basePath, milestoneId);
+  if (!dirtyPaths || !changedPaths) return null;
+
+  const changedPathSet = new Set(changedPaths.filter((path) => !path.startsWith(".gsd/")));
+  return dirtyPaths
+    .filter((path) => !path.startsWith(".gsd/") && changedPathSet.has(path))
+    .sort();
+}
+
+function listStashUntrackedPaths(basePath: string, stashRef: string): string[] | null {
+  try {
+    const output = gitText(basePath, ["ls-tree", "-r", "-z", "--name-only", `${stashRef}^3`]);
+    return readZeroDelimitedPaths(output);
+  } catch {
+    return null;
+  }
+}
+
+function listStashTrackedPaths(basePath: string, stashRef: string): string[] | null {
+  try {
+    const output = gitText(basePath, ["diff", "--name-only", "-z", `${stashRef}^1`, stashRef]);
+    return readZeroDelimitedPaths(output);
+  } catch {
+    return null;
+  }
+}
+
+function isWorktreeClean(basePath: string): boolean | null {
+  try {
+    return gitText(basePath, ["status", "--porcelain"]).trim() === "";
+  } catch {
+    return null;
+  }
+}
+
+function stashBlobEqualsWorktreeFile(basePath: string, stashRef: string, path: string): boolean | null {
+  try {
+    const worktreePath = join(basePath, path);
+    if (!existsSync(worktreePath)) return false;
+    const worktreeContent = readFileSync(worktreePath);
+    const stashContent = gitBuffer(basePath, ["show", `${stashRef}^3:${path}`]);
+    return Buffer.compare(worktreeContent, stashContent) === 0;
+  } catch {
+    return null;
+  }
+}
+
+function reconcileAlreadyPresentUntrackedStash(
+  basePath: string,
+  milestoneId: string,
+  stashRef: string,
+  err: unknown,
+): PostflightResult | null {
+  const text = errorText(err);
+  const collidedPaths = parseAlreadyExistsNoCheckoutPaths(text);
+  if (collidedPaths.length === 0) return null;
+
+  const untrackedPaths = listStashUntrackedPaths(basePath, stashRef);
+  if (!untrackedPaths || untrackedPaths.length === 0) return null;
+
+  const trackedPaths = listStashTrackedPaths(basePath, stashRef);
+  if (trackedPaths === null || trackedPaths.length > 0) return null;
+
+  const untrackedPathSet = new Set(untrackedPaths);
+  if (!collidedPaths.every((path) => untrackedPathSet.has(path))) return null;
+  if (!untrackedPaths.every((path) => existsSync(join(basePath, path)))) return null;
+  if (isWorktreeClean(basePath) !== true) return null;
+
+  const blobComparisons = untrackedPaths.map((path) => stashBlobEqualsWorktreeFile(basePath, stashRef, path));
+  if (blobComparisons.some((result) => result === null)) return null;
+  const allIdentical = blobComparisons.every(Boolean);
+  if (allIdentical) {
+    let dropped = true;
+    try {
+      execFileSync("git", ["stash", "drop", stashRef], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      });
+    } catch (err) {
+      dropped = false;
+      logWarning("preflight", `git stash drop ${stashRef} failed after identical preflight stash reconciliation: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return {
+      restored: true,
+      needsManualRecovery: false,
+      message: dropped
+        ? `Preflight stash for milestone ${milestoneId} contained files already present after merge; identical stash dropped.`
+        : `Preflight stash for milestone ${milestoneId} contained files already present after merge, but ${stashRef} could not be dropped and remains as a backup.`,
+      stashRef,
+      resolution: dropped ? "already-present-dropped" : "already-present-preserved",
+      collidedPaths,
+    };
+  }
+
+  return {
+    restored: false,
+    needsManualRecovery: false,
+    message: `Preflight stash for milestone ${milestoneId} contained untracked files already present after merge. Keeping merged files and preserving ${stashRef} as a backup.`,
+    stashRef,
+    resolution: "already-present-preserved",
+    collidedPaths,
+  };
 }
 
 function findPreflightStashRef(basePath: string, milestoneId: string, stashMarker?: string): string | null {
@@ -87,6 +285,62 @@ export function preflightCleanRoot(
     return { stashPushed: false, summary: "" };
   }
 
+  const conflictedPaths = listUnmergedGitPaths(basePath);
+  if (conflictedPaths === null) {
+    const msg =
+      `Unable to verify unresolved Git conflicts before milestone ${milestoneId} merge. ` +
+      `Resolve Git/worktree state manually before resuming auto-mode.`;
+    notify(msg, "error");
+    return {
+      stashPushed: false,
+      blocked: true,
+      blockedReason: "unmerged-conflicts-eval-failed",
+      conflictedPaths: null,
+      summary: msg,
+    };
+  }
+  if (conflictedPaths.length > 0) {
+    const msg =
+      `Working tree has unresolved Git conflicts before milestone ${milestoneId} merge: ` +
+      `${conflictedPaths.join(", ")}. Resolve these files manually before resuming auto-mode.`;
+    notify(msg, "error");
+    return {
+      stashPushed: false,
+      blocked: true,
+      blockedReason: "unmerged-conflicts",
+      conflictedPaths,
+      summary: msg,
+    };
+  }
+
+  const overlappingPaths = findOverlappingDirtyMilestonePaths(basePath, milestoneId);
+  if (overlappingPaths === null) {
+    const msg =
+      `Unable to verify dirty-path overlap for milestone ${milestoneId}. ` +
+      `Resolve Git/worktree state manually before resuming auto-mode.`;
+    notify(msg, "error");
+    return {
+      stashPushed: false,
+      blocked: true,
+      blockedReason: "dirty-overlap-eval-failed",
+      overlappingPaths: null,
+      summary: msg,
+    };
+  }
+  if (overlappingPaths && overlappingPaths.length > 0) {
+    const msg =
+      `Working tree has uncommitted files that overlap milestone ${milestoneId} changes: ` +
+      `${overlappingPaths.join(", ")}. Commit, stash, or discard those files before resuming auto-mode.`;
+    notify(msg, "error");
+    return {
+      stashPushed: false,
+      blocked: true,
+      blockedReason: "dirty-overlap",
+      overlappingPaths,
+      summary: msg,
+    };
+  }
+
   // Warn the user before stashing
   const warnMsg = `Working tree has uncommitted changes before milestone ${milestoneId} merge. Auto-stashing to allow clean merge (stash will be restored after merge).`;
   notify(warnMsg, "warning");
@@ -141,27 +395,48 @@ export function postflightPopStash(
         message: msg,
       };
     }
-    execFileSync("git", ["stash", "pop", stashRef], {
+    execFileSync("git", ["stash", "apply", stashRef], {
       cwd: basePath,
       stdio: ["ignore", "pipe", "pipe"],
       encoding: "utf-8",
       env: GIT_NO_PROMPT_ENV,
     });
+    let dropWarning: string | null = null;
+    try {
+      execFileSync("git", ["stash", "drop", stashRef], {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+      });
+    } catch (err) {
+      dropWarning = ` Stash was restored, but git stash drop ${stashRef} failed: ${err instanceof Error ? err.message : String(err)}.`;
+      logWarning("preflight", dropWarning.trim());
+    }
     const msg = `Restored stashed changes after milestone ${milestoneId} merge.`;
-    notify(msg, "info");
+    notify(`${msg}${dropWarning ?? ""}`, dropWarning ? "warning" : "info");
     return {
       restored: true,
       needsManualRecovery: false,
-      message: msg,
+      message: `${msg}${dropWarning ?? ""}`,
       stashRef,
+      resolution: "applied",
     };
   } catch (err) {
-    // Pop conflicts mean the merged code collides with the stashed changes.
+    if (stashRef) {
+      const reconciled = reconcileAlreadyPresentUntrackedStash(basePath, milestoneId, stashRef, err);
+      if (reconciled) {
+        logWarning("preflight", reconciled.message);
+        notify(reconciled.message, reconciled.resolution === "already-present-preserved" ? "warning" : "info");
+        return reconciled;
+      }
+    }
+    // Apply conflicts mean the merged code collides with the stashed changes.
     // Log a warning — the user needs to resolve manually, but the merge succeeded.
     const restoreHint = stashRef
-      ? `Run "git stash pop ${stashRef}" or "git stash apply ${stashRef}" manually to restore the correct stash.`
+      ? `Run "git stash apply ${stashRef}" manually to restore the correct stash, then "git stash drop ${stashRef}" after recovery.`
       : `Run "git stash list" to find the matching GSD preflight stash before restoring manually.`;
-    const msg = `git stash pop ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
+    const msg = `git stash apply ${stashRef ?? ""}`.trim() + ` failed after merge of milestone ${milestoneId}: ${err instanceof Error ? err.message : String(err)}. ${restoreHint}`;
     logWarning("preflight", msg);
     notify(msg, "warning");
     return {
@@ -169,6 +444,7 @@ export function postflightPopStash(
       needsManualRecovery: true,
       message: msg,
       ...(stashRef ? { stashRef } : {}),
+      resolution: "manual-recovery",
     };
   }
 }

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

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
+import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
 
 
 export interface GsdCommandDefinition {
@@ -13,7 +14,7 @@ export interface GsdCommandDefinition {
 type CompletionMap = Record<string, readonly GsdCommandDefinition[]>;
 
 export const GSD_COMMAND_DESCRIPTION =
-  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|queue|quick|discuss|capture|triage|dispatch|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
+  "GSD — Get Shit Done: /gsd help|start|templates|next|auto|stop|pause|status|widget|visualize|brief|queue|quick|discuss|capture|triage|dispatch|verdict|history|undo|undo-task|reset-slice|rate|skip|export|cleanup|model|mode|prefs|config|keys|hooks|run-hook|skill-health|doctor|debug|logs|forensics|changelog|migrate|remote|steer|knowledge|new-milestone|new-project|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|workflow|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language|worktree|eval-review";
 
 export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -24,6 +25,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "status", desc: "Progress dashboard" },
   { cmd: "widget", desc: "Cycle widget: full → small → min → off" },
   { cmd: "visualize", desc: "Open 10-tab workflow visualizer (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)" },
+  { cmd: "brief", desc: "Generate a visual HTML brief: diagram, plan, diff review, recap, table, or slides" },
   { cmd: "queue", desc: "Queue and reorder future milestones" },
   { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
   { cmd: "discuss", desc: "Discuss architecture and decisions" },
@@ -31,6 +33,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
   { cmd: "changelog", desc: "Show categorized release notes" },
   { cmd: "triage", desc: "Manually trigger triage of pending captures" },
   { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
+  { cmd: "verdict", desc: "Override the recorded milestone validation verdict (pass|needs-attention|needs-remediation)" },
   { cmd: "history", desc: "View execution history" },
   { cmd: "undo", desc: "Revert last completed unit" },
   { cmd: "undo-task", desc: "Reset a specific task's completion state (DB + markdown)" },
@@ -88,6 +91,7 @@ export const TOP_LEVEL_SUBCOMMANDS: readonly GsdCommandDefinition[] = [
 ];
 
 const NESTED_COMPLETIONS: CompletionMap = {
+  brief: VISUAL_BRIEF_MODES.map((mode) => ({ cmd: mode.mode, desc: mode.description })),
   auto: [
     { cmd: "--verbose", desc: "Show detailed execution output" },
     { cmd: "--debug", desc: "Enable debug logging" },
@@ -245,6 +249,11 @@ const NESTED_COMPLETIONS: CompletionMap = {
     { cmd: "uat", desc: "Run user acceptance testing" },
     { cmd: "replan", desc: "Replan the current slice" },
   ],
+  verdict: [
+    { cmd: "pass", desc: "Override the milestone validation verdict to pass" },
+    { cmd: "needs-attention", desc: "Override the verdict to needs-attention (requires --rationale)" },
+    { cmd: "needs-remediation", desc: "Override the verdict to needs-remediation (requires --rationale)" },
+  ],
   rate: [
     { cmd: "over", desc: "Model was overqualified for this task" },
     { cmd: "ok", desc: "Model was appropriate for this task" },

package/src/resources/extensions/gsd/commands/handlers/core.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@gsd/pi-coding-agent";
 import type { Model } from "@gsd/pi-ai";
 import type { GSDState } from "../../types.js";
+import { createRequire } from "node:module";
 
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
 import { loadEffectiveGSDPreferences, getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath } from "../../preferences.js";
@@ -11,6 +12,8 @@ import { handleCmux } from "../../commands-cmux.js";
 import { setSessionModelOverride } from "../../session-model-override.js";
 import { projectRoot } from "../context.js";
 import { formattedShortcutPair } from "../../shortcut-defs.js";
+import { getVisualBriefOutputDir } from "../../../visual-brief/artifact-policy.js";
+import { buildVisualBriefPrompt, parseVisualBriefArgs, VISUAL_BRIEF_USAGE } from "../../../visual-brief/prompts.js";
 
 export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
   const summaryLines = [
@@ -27,6 +30,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     `  /gsd parallel watch Parallel monitor  (${formattedShortcutPair("parallel")})`,
     `  /gsd notifications  Notification history  (${formattedShortcutPair("notifications")})`,
     "  /gsd visualize      Interactive 10-tab TUI",
+    "  /gsd brief <mode>   Visual HTML brief (diagram, plan, diff, recap, table, slides)",
     "  /gsd queue          Show queued/dispatched units",
     "",
     "COURSE CORRECTION",
@@ -67,6 +71,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /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 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]",
     "",
@@ -75,6 +80,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     `  /gsd parallel watch Open parallel worker monitor  (${formattedShortcutPair("parallel")})`,
     "  /gsd widget         Cycle status widget  [full|small|min|off]",
     "  /gsd visualize      Interactive 10-tab TUI (progress, timeline, deps, metrics, health, agent, changes, knowledge, captures, export)",
+    "  /gsd brief <mode>   Generate a visual HTML brief  [diagram|plan|diff|recap|table|slides] [topic] [--slides]",
     "  /gsd queue          Show queued/dispatched units and execution order",
     "  /gsd history        View execution history  [--cost] [--phase] [--model] [N]",
     "  /gsd changelog      Show categorized release notes  [version]",
@@ -96,7 +102,7 @@ export function showHelp(ctx: ExtensionCommandContext, args = ""): void {
     "  /gsd unpark [id]    Reactivate a parked milestone",
     "",
     "PROJECT KNOWLEDGE",
-    "  /gsd knowledge <type> <text>   Add rule, pattern, or lesson to KNOWLEDGE.md",
+    "  /gsd knowledge <type> <text>   Add a rule to KNOWLEDGE.md or capture a pattern/lesson to memories",
     "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
     "",
     "SHIPPING & BACKLOG",
@@ -203,6 +209,37 @@ export async function handleVisualize(ctx: ExtensionCommandContext): Promise<voi
   }
 }
 
+export async function handleBrief(args: string, ctx: ExtensionCommandContext, pi?: ExtensionAPI): Promise<void> {
+  const request = parseVisualBriefArgs(args);
+  if (!request) {
+    ctx.ui.notify(VISUAL_BRIEF_USAGE, "info");
+    return;
+  }
+
+  if (!pi?.sendUserMessage) {
+    ctx.ui.notify("Visual brief generation is unavailable in this context.", "warning");
+    return;
+  }
+
+  const outputDir = getVisualBriefOutputDir();
+  const version = resolveGsdVersion();
+  pi.sendUserMessage(buildVisualBriefPrompt(request, { outputDir, version }));
+}
+
+const briefRequire = createRequire(import.meta.url);
+
+function resolveGsdVersion(): string | undefined {
+  const envVersion = process.env.GSD_VERSION?.trim();
+  if (envVersion) return envVersion;
+  try {
+    const pkg = briefRequire("../../../../../../package.json") as { version?: unknown };
+    const fromPkg = typeof pkg.version === "string" ? pkg.version.trim() : "";
+    return fromPkg || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export async function handleSetup(args: string, ctx: ExtensionCommandContext, pi?: ExtensionAPI): Promise<void> {
   const { detectProjectState, hasGlobalSetup } = await import("../../detection.js");
   const { isOnboardingComplete, readOnboardingRecord } = await import("../../onboarding-state.js");
@@ -429,6 +466,10 @@ export async function handleCoreCommand(
     await handleVisualize(ctx);
     return true;
   }
+  if (trimmed === "brief" || trimmed.startsWith("brief ")) {
+    await handleBrief(trimmed.replace(/^brief\s*/, "").trim(), ctx, pi);
+    return true;
+  }
   if (trimmed === "widget" || trimmed.startsWith("widget ")) {
     const { cycleWidgetMode, setWidgetMode, getWidgetMode } = await import("../../auto-dashboard.js");
     const arg = trimmed.replace(/^widget\s*/, "").trim();

package/src/resources/extensions/gsd/commands/handlers/ops.ts

@@ -20,6 +20,22 @@ import { handlePrBranch } from "../../commands-pr-branch.js";
 import { currentDirectoryRoot, projectRoot } from "../context.js";
 
 export async function handleOpsCommand(trimmed: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<boolean> {
+  const directDispatchAlias = new Map<string, string>([
+    ["research-milestone", "research"],
+    ["research-slice", "research"],
+    ["plan-milestone", "plan"],
+    ["plan-slice", "plan"],
+    ["execute-task", "execute"],
+    ["complete-slice", "complete"],
+    ["validate-milestone", "uat"],
+    ["complete-milestone", "complete"],
+  ]);
+  const aliasPhase = directDispatchAlias.get(trimmed);
+  if (aliasPhase) {
+    await dispatchDirectPhase(ctx, pi, aliasPhase, projectRoot());
+    return true;
+  }
+
   if (trimmed === "init") {
     const { detectProjectState } = await import("../../detection.js");
     const { handleReinit, showProjectInit } = await import("../../init-wizard.js");
@@ -188,6 +204,11 @@ Examples:
     await dispatchDirectPhase(ctx, pi, phase, projectRoot());
     return true;
   }
+  if (trimmed === "verdict" || trimmed.startsWith("verdict ")) {
+    const { handleVerdict } = await import("../../commands-verdict.js");
+    await handleVerdict(trimmed.replace(/^verdict\s*/, "").trim(), ctx, projectRoot());
+    return true;
+  }
   if (trimmed === "notifications" || trimmed.startsWith("notifications ")) {
     const { handleNotificationsCommand } = await import("./notifications-handler.js");
     await handleNotificationsCommand(trimmed.replace(/^notifications\s*/, "").trim(), ctx, pi);

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

@@ -1,4 +1,5 @@
 import { importExtensionModule, type ExtensionAPI, type ExtensionCommandContext } from "@gsd/pi-coding-agent";
+import { VISUAL_BRIEF_MODES } from "../visual-brief/prompts.js";
 
 const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "help", desc: "Categorized command reference with descriptions" },
@@ -8,6 +9,7 @@ const TOP_LEVEL_SUBCOMMANDS = [
   { cmd: "pause", desc: "Pause auto-mode (preserves state, /gsd auto to resume)" },
   { cmd: "status", desc: "Progress dashboard" },
   { cmd: "visualize", desc: "Open workflow visualizer" },
+  { cmd: "brief", desc: "Generate a visual HTML brief" },
   { cmd: "queue", desc: "Queue and reorder future milestones" },
   { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
   { cmd: "discuss", desc: "Discuss architecture and decisions" },
@@ -87,6 +89,14 @@ function getGsdArgumentCompletions(prefix: string) {
     ], "next");
   }
 
+  if (parts[0] === "brief" && parts.length <= 2) {
+    return filterStartsWith(
+      partial,
+      VISUAL_BRIEF_MODES.map((mode) => ({ cmd: mode.mode, desc: mode.description })),
+      "brief",
+    );
+  }
+
   if ((parts[0] === "new-project" || parts[0] === "new-milestone") && parts.length <= 2) {
     return filterStartsWith(partial, [
       { cmd: "--deep", desc: "Enable deep planning mode (staged project-level discovery)" },

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

@@ -123,6 +123,8 @@ export async function handleDoctor(args: string, ctx: ExtensionCommandContext, p
   const { jsonMode, dryRun, fixFlag, includeBuild, includeTests, mode, requestedScope } = parseDoctorArgs(args);
   const scope = await selectDoctorScope(projectRoot(), requestedScope);
   const effectiveScope = mode === "audit" ? requestedScope : scope;
+  const { ensureDbOpen } = await import("./bootstrap/dynamic-tools.js");
+  await ensureDbOpen(projectRoot());
   const report = await runGSDDoctor(projectRoot(), {
     fix: mode === "fix" || mode === "heal" || dryRun || fixFlag,
     dryRun,
@@ -368,8 +370,25 @@ export async function handleKnowledge(args: string, ctx: ExtensionCommandContext
     ? `${state.activeMilestone.id}${state.activeSlice ? `/${state.activeSlice.id}` : ""}`
     : "global";
 
-  await appendKnowledge(basePath, type, entryText, scope);
-  ctx.ui.notify(`Added ${type} to KNOWLEDGE.md: "${entryText}"`, "success");
+  // ADR-013 Stage 2c: Patterns and Lessons land in the memories table; the
+  // next session-start projection render emits them back into KNOWLEDGE.md.
+  // Rules stay file-canonical per ADR-013 line 39 — Rules are not migrated.
+  if (type === "rule") {
+    await appendKnowledge(basePath, type, entryText, scope);
+    ctx.ui.notify(`Added rule to KNOWLEDGE.md: "${entryText}"`, "success");
+    return;
+  }
+
+  const { captureKnowledgeEntry } = await import("./knowledge-capture.js");
+  const { id, written } = captureKnowledgeEntry(basePath, type, entryText, scope);
+  if (!written) {
+    ctx.ui.notify(`Could not persist ${type} — see logs for details.`, "error");
+    return;
+  }
+  ctx.ui.notify(
+    `Captured ${type} ${id} to memories; KNOWLEDGE.md will render it on next session start.`,
+    "success",
+  );
 }
 
 export async function handleRunHook(args: string, ctx: ExtensionCommandContext, pi: ExtensionAPI): Promise<void> {

package/src/resources/extensions/gsd/commands-mcp-status.ts

@@ -32,6 +32,11 @@ export interface McpServerDetail extends McpServerStatus {
   tools: string[];
 }
 
+export function hasHostMcpTool(systemPrompt: string, serverName: string): boolean {
+  const marker = `mcp__${serverName}__`;
+  return systemPrompt.includes(marker);
+}
+
 export function formatMcpInitResult(
   status: "created" | "updated" | "unchanged",
   configPath: string,
@@ -184,6 +189,7 @@ export async function handleMcpStatus(
   const trimmed = args.trim();
   const lowered = trimmed.toLowerCase();
   const configs = readMcpConfigs();
+  const systemPrompt = ctx.getSystemPrompt();
 
   // /gsd mcp init [dir]
   if (!lowered || lowered === "status") {
@@ -233,6 +239,7 @@ export async function handleMcpStatus(
     } catch {
       // mcp-client may not expose status helpers — that's fine
     }
+    if (!connected && !error && hasHostMcpTool(systemPrompt, serverName)) connected = true;
 
     ctx.ui.notify(
       formatMcpServerDetail({
@@ -270,6 +277,7 @@ export async function handleMcpStatus(
       } catch {
         // Fall back to unknown state
       }
+      if (!connected && !error && hasHostMcpTool(systemPrompt, config.name)) connected = true;
 
       statuses.push({
         name: config.name,