gsd-pi 2.82.0 → 3.0.0-dev.04f5ccf82

package/dist/resources/extensions/gsd/clean-root-preflight.js

@@ -8,14 +8,200 @@
  *
  * 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";
+function gitText(basePath, args) {
+    return execFileSync("git", args, {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        encoding: "utf-8",
+        env: GIT_NO_PROMPT_ENV,
+    });
+}
+function gitBuffer(basePath, args) {
+    return execFileSync("git", args, {
+        cwd: basePath,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: GIT_NO_PROMPT_ENV,
+    });
+}
+function errorText(err) {
+    if (!err || typeof err !== "object")
+        return String(err);
+    const parts = [];
+    const stderr = err.stderr;
+    const stdout = err.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) {
+    const paths = [];
+    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) {
+    return output.split("\0").filter(Boolean);
+}
+function listDirtyPaths(basePath) {
+    try {
+        const paths = new Set();
+        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, milestoneId) {
+    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, milestoneId) {
+    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, stashRef) {
+    try {
+        const output = gitText(basePath, ["ls-tree", "-r", "-z", "--name-only", `${stashRef}^3`]);
+        return readZeroDelimitedPaths(output);
+    }
+    catch {
+        return null;
+    }
+}
+function listStashTrackedPaths(basePath, stashRef) {
+    try {
+        const output = gitText(basePath, ["diff", "--name-only", "-z", `${stashRef}^1`, stashRef]);
+        return readZeroDelimitedPaths(output);
+    }
+    catch {
+        return null;
+    }
+}
+function isWorktreeClean(basePath) {
+    try {
+        return gitText(basePath, ["status", "--porcelain"]).trim() === "";
+    }
+    catch {
+        return null;
+    }
+}
+function stashBlobEqualsWorktreeFile(basePath, stashRef, path) {
+    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, milestoneId, stashRef, err) {
+    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, milestoneId, stashMarker) {
     const markerPrefix = `gsd-preflight-stash:${milestoneId}:`;
     let fallbackRef = null;
@@ -67,6 +253,56 @@ export function preflightCleanRoot(basePath, milestoneId, notify) {
     if (!isDirty) {
         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");
@@ -115,28 +351,50 @@ export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
                 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 = 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 {
@@ -144,6 +402,7 @@ export function postflightPopStash(basePath, milestoneId, stashMarker, notify) {
             needsManualRecovery: true,
             message: msg,
             ...(stashRef ? { stashRef } : {}),
+            resolution: "manual-recovery",
         };
     }
 }

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

@@ -2,7 +2,8 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { gsdHome } from "../gsd-home.js";
-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";
+import { VISUAL_BRIEF_MODES } from "../../visual-brief/prompts.js";
+export const GSD_COMMAND_DESCRIPTION = "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 = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -12,6 +13,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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" },
@@ -19,6 +21,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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)" },
@@ -75,6 +78,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "eval-review", desc: "Audit a slice's AI evaluation strategy and write a scored EVAL-REVIEW.md (--force, --show)" },
 ];
 const NESTED_COMPLETIONS = {
+    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" },
@@ -232,6 +236,11 @@ const NESTED_COMPLETIONS = {
         { 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/dist/resources/extensions/gsd/commands/handlers/core.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { computeProgressScore, formatProgressLine } from "../../progress-score.js";
 import { getGlobalGSDPreferencesPath, getProjectGSDPreferencesPath } from "../../preferences.js";
 import { ensurePreferencesFile, handlePrefs, handlePrefsMode, handlePrefsWizard, handleLanguage } from "../../commands-prefs-wizard.js";
@@ -7,6 +8,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, args = "") {
     const summaryLines = [
         "GSD — Get Shit Done\n",
@@ -22,6 +25,7 @@ export function showHelp(ctx, args = "") {
         `  /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",
@@ -61,6 +65,7 @@ export function showHelp(ctx, args = "") {
         "  /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]",
         "",
@@ -69,6 +74,7 @@ export function showHelp(ctx, args = "") {
         `  /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]",
@@ -90,7 +96,7 @@ export function showHelp(ctx, args = "") {
         "  /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",
@@ -182,6 +188,34 @@ export async function handleVisualize(ctx) {
         ctx.ui.notify("Visualizer requires an interactive terminal. Use /gsd status for a text-based overview.", "warning");
     }
 }
+export async function handleBrief(args, ctx, pi) {
+    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() {
+    const envVersion = process.env.GSD_VERSION?.trim();
+    if (envVersion)
+        return envVersion;
+    try {
+        const pkg = briefRequire("../../../../../../package.json");
+        const fromPkg = typeof pkg.version === "string" ? pkg.version.trim() : "";
+        return fromPkg || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 export async function handleSetup(args, ctx, pi) {
     const { detectProjectState, hasGlobalSetup } = await import("../../detection.js");
     const { isOnboardingComplete, readOnboardingRecord } = await import("../../onboarding-state.js");
@@ -370,6 +404,10 @@ export async function handleCoreCommand(trimmed, ctx, pi) {
         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/dist/resources/extensions/gsd/commands/handlers/ops.js

@@ -14,6 +14,21 @@ import { handleSessionReport } from "../../commands-session-report.js";
 import { handlePrBranch } from "../../commands-pr-branch.js";
 import { currentDirectoryRoot, projectRoot } from "../context.js";
 export async function handleOpsCommand(trimmed, ctx, pi) {
+    const directDispatchAlias = new Map([
+        ["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");
@@ -183,6 +198,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/dist/resources/extensions/gsd/commands-bootstrap.js

@@ -1,4 +1,5 @@
 import { importExtensionModule } 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" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -7,6 +8,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" },
@@ -75,6 +77,9 @@ function getGsdArgumentCompletions(prefix) {
             { cmd: "--dry-run", desc: "Preview next step without executing" },
         ], "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/dist/resources/extensions/gsd/commands-handlers.js

@@ -101,6 +101,8 @@ export async function handleDoctor(args, ctx, pi) {
     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,
@@ -303,8 +305,21 @@ export async function handleKnowledge(args, ctx) {
     const scope = state.activeMilestone?.id
         ? `${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, ctx, pi) {
     const parts = args.trim().split(/\s+/);

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

@@ -13,6 +13,10 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { ensureProjectWorkflowMcpConfig } from "./mcp-project-config.js";
 import { gsdHome } from "./gsd-home.js";
+export function hasHostMcpTool(systemPrompt, serverName) {
+    const marker = `mcp__${serverName}__`;
+    return systemPrompt.includes(marker);
+}
 export function formatMcpInitResult(status, configPath, targetPath) {
     const summary = status === "created"
         ? "Created project MCP config."
@@ -132,6 +136,7 @@ export async function handleMcpStatus(args, ctx) {
     const trimmed = args.trim();
     const lowered = trimmed.toLowerCase();
     const configs = readMcpConfigs();
+    const systemPrompt = ctx.getSystemPrompt();
     // /gsd mcp init [dir]
     if (!lowered || lowered === "status") {
         // handled below
@@ -175,6 +180,8 @@ export async function handleMcpStatus(args, ctx) {
         catch {
             // mcp-client may not expose status helpers — that's fine
         }
+        if (!connected && !error && hasHostMcpTool(systemPrompt, serverName))
+            connected = true;
         ctx.ui.notify(formatMcpServerDetail({
             name: config.name,
             transport: config.transport,
@@ -206,6 +213,8 @@ export async function handleMcpStatus(args, ctx) {
             catch {
                 // Fall back to unknown state
             }
+            if (!connected && !error && hasHostMcpTool(systemPrompt, config.name))
+                connected = true;
             statuses.push({
                 name: config.name,
                 transport: config.transport,

package/dist/resources/extensions/gsd/commands-prefs-wizard.js

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { getGlobalGSDPreferencesPath, getLegacyGlobalGSDPreferencesPath, getProjectGSDPreferencesPath, loadGlobalGSDPreferences, loadProjectGSDPreferences, loadEffectiveGSDPreferences, resolveAllSkillReferences, } from "./preferences.js";
+import { getGlobalGSDPreferencesPath, getLegacyGlobalGSDPreferencesPath, getProjectGSDPreferencesPath, loadGlobalGSDPreferences, loadProjectGSDPreferences, loadEffectiveGSDPreferences, normalizePreferencesShape, resolveAllSkillReferences, } from "./preferences.js";
 import { loadFile, saveFile, splitFrontmatter, parseFrontmatterMap } from "./files.js";
 import { runClaudeImportFlow } from "./claude-import.js";
 /** Extract body content after frontmatter closing delimiter, or null if none. */
@@ -571,10 +571,18 @@ async function configureModels(ctx, prefs) {
     ];
     const models = prefs.models ?? {};
     const availableModels = ctx.modelRegistry.getAvailable();
-    if (availableModels.length > 0) {
+    // Call getAllWithDiscovered as a method so `this` stays bound to the
+    // registry — invoking a detached reference loses `this` and the method's
+    // internal `this.models` access throws.
+    const registry = ctx.modelRegistry;
+    const availableProviders = new Set(availableModels.map((m) => m.provider));
+    const selectableModels = typeof registry.getAllWithDiscovered === "function"
+        ? registry.getAllWithDiscovered().filter((m) => availableProviders.has(m.provider))
+        : availableModels;
+    if (selectableModels.length > 0) {
         // Group models by provider, sorted alphabetically
         const byProvider = new Map();
-        for (const m of availableModels) {
+        for (const m of selectableModels) {
             let group = byProvider.get(m.provider);
             if (!group) {
                 group = [];
@@ -1511,8 +1519,12 @@ export async function handlePrefsWizard(ctx, scope, prefill, opts) {
     // Order: existing-on-disk values, overlaid with prefill (caller's seeded answers).
     // Callers like /gsd init pass freshly-collected init answers as prefill so the
     // wizard menu shows them populated and writeable in one place.
+    // `normalizePreferencesShape` tolerates a missing preferences file, a malformed
+    // wrapper (`{ preferences: undefined }`), or a bare prefs object so the wizard
+    // never reaches the category menu with a half-formed root. See issue: /gsd setup
+    // prefs crashed with "Cannot read properties of undefined (reading 'models')".
     const prefs = {
-        ...(existing?.preferences ?? {}),
+        ...normalizePreferencesShape(existing),
         ...(prefill ?? {}),
     };
     ctx.ui.notify(`GSD preferences (${scope}) — pick a category to configure.`, "info");