gsd-pi 2.75.0-next.9c0ec0ba1 → 2.76.0-dev.b072ebb73

package/dist/resources/extensions/gsd/bootstrap/system-context.js

@@ -24,10 +24,30 @@ const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
  * hardcoding absolute paths in the system prompt template. Only skills
  * that actually exist on disk are included in the table. (#3575)
  */
-const BUNDLED_SKILL_TRIGGERS = [
+export const BUNDLED_SKILL_TRIGGERS = [
     { trigger: "Frontend UI - web components, pages, landing pages, dashboards, React/HTML/CSS, styling", skill: "frontend-design" },
     { trigger: "macOS or iOS apps - SwiftUI, Xcode, App Store", skill: "swiftui" },
     { trigger: "Debugging - complex bugs, failing tests, root-cause investigation after standard approaches fail", skill: "debug-like-expert" },
+    { trigger: "Code review - security, performance, bugs, quality review of staged/unstaged diffs or PRs", skill: "review" },
+    { trigger: "Test generation or execution - auto-detect framework, generate tests, run suite, analyze failures", skill: "test" },
+    { trigger: "Linting/formatting - run the detected linter/formatter with auto-fix, report remaining issues", skill: "lint" },
+    { trigger: "Polishing UI details - animations, hover states, typography, borders, micro-interactions, optical alignment", skill: "make-interfaces-feel-better" },
+    { trigger: "Accessibility audit - WCAG, screen reader, keyboard navigation, a11y review", skill: "accessibility" },
+    { trigger: "Planning interviews - stress-test a plan, grill the user, resolve decision trees one branch at a time", skill: "grill-me" },
+    { trigger: "Interface design - produce 3+ radically different designs for a module/API, compare in prose, synthesize", skill: "design-an-interface" },
+    { trigger: "TDD - red-green-refactor vertical slices, never refactor while red, tests survive refactors", skill: "tdd" },
+    { trigger: "Draft a milestone brief (M###-CONTEXT.md) or PRD from current conversation context", skill: "write-milestone-brief" },
+    { trigger: "Break a plan into vertical-slice roadmap slices (M###-ROADMAP.md) or GitHub issues with dependency ordering", skill: "decompose-into-slices" },
+    { trigger: "Package spike findings into a reusable project-local skill at .claude/skills/", skill: "spike-wrap-up" },
+    { trigger: "Block completion claims until verification evidence has been produced in this message", skill: "verify-before-complete" },
+    { trigger: "Create a Model Context Protocol (MCP) server — tool design, error handling, Inspector testing, evals", skill: "create-mcp-server" },
+    { trigger: "Write documentation, proposals, specs, RFCs, or READMEs for a fresh reader", skill: "write-docs" },
+    { trigger: "Post-mortem a failed GSD auto-mode run using .gsd/activity, .gsd/journal, and .gsd/metrics.json", skill: "forensics" },
+    { trigger: "Prepare a clean cross-session handoff — continue.md + summary updates (pause/resume work)", skill: "handoff" },
+    { trigger: "Security review with STRIDE threat modeling and exploit-scenario reporting", skill: "security-review" },
+    { trigger: "HTTP/REST/GraphQL API design — verbs, status codes, pagination, errors, idempotency, versioning", skill: "api-design" },
+    { trigger: "Dependency upgrades — risk-batched, verified between batches, one major per commit", skill: "dependency-upgrade" },
+    { trigger: "Agent-first observability — structured logs, persisted failure state, health surfaces, explicit failure modes", skill: "observability" },
 ];
 function buildBundledSkillsTable() {
     const cwd = process.cwd();
@@ -87,20 +107,20 @@ export async function buildBeforeAgentStartResult(event, ctx) {
     if (globalSizeKb > 4) {
         ctx.ui.notify(`GSD: ~/.gsd/agent/KNOWLEDGE.md is ${globalSizeKb.toFixed(1)}KB — consider trimming to keep system prompt lean.`, "warning");
     }
-    let memoryBlock = "";
+    // ADR-013 step 5: opportunistic decisions->memories backfill. Idempotent
+    // and best-effort — first run absorbs the existing decisions table into
+    // the memory store; subsequent runs are a single sentinel SELECT.
     try {
-        const { formatMemoriesForPrompt, getActiveMemoriesRanked } = await import("../memory-store.js");
-        const memories = getActiveMemoriesRanked(30);
-        if (memories.length > 0) {
-            const formatted = formatMemoriesForPrompt(memories, 2000);
-            if (formatted) {
-                memoryBlock = `\n\n${formatted}`;
-            }
+        const { backfillDecisionsToMemories } = await import("../memory-backfill.js");
+        const written = backfillDecisionsToMemories();
+        if (written > 0) {
+            ctx.ui.notify(`GSD: backfilled ${written} decision${written === 1 ? "" : "s"} into the memory store (ADR-013).`, "info");
         }
     }
     catch (e) {
-        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
+        logWarning("bootstrap", `decisions backfill failed: ${e.message}`);
     }
+    const memoryBlock = await loadMemoryBlock(event.prompt ?? "");
     let newSkillsBlock = "";
     if (hasSkillSnapshot()) {
         const newSkills = detectNewSkills();
@@ -170,6 +190,60 @@ export async function buildBeforeAgentStartResult(event, ctx) {
         ...(contextMessage ? { message: contextMessage } : {}),
     };
 }
+/**
+ * ADR-013 step 4 — auto-injection parity for the memories table.
+ *
+ * Mirrors loadKnowledgeBlock by producing a labeled, deterministic block
+ * combining two memory sets:
+ *
+ * 1. Always-on "critical" set — top-ranked active memories in categories
+ *    that future GSD turns generally want without asking. After ADR-013
+ *    expands this to include "architecture", these memories serve as the
+ *    auto-injected replacement for inlineDecisionsFromDb when the cutover
+ *    in step 6 lands.
+ * 2. Prompt-relevance set — FTS5/semantic hits against the current user
+ *    prompt, deduplicated against the critical set.
+ *
+ * Both sets are ranked, merged, and rendered via formatMemoriesForPrompt
+ * with a token-budget cap. Failures degrade gracefully — the function never
+ * throws and returns "" so the system prompt construction continues.
+ */
+export async function loadMemoryBlock(userPrompt) {
+    try {
+        const { formatMemoriesForPrompt, getActiveMemoriesRanked, queryMemoriesRanked } = await import("../memory-store.js");
+        // Categories that belong in every turn. Pre-ADR-013 this was just
+        // {gotcha, environment, convention}. ADR-013 adds "architecture" so
+        // decision-equivalent memories survive the inlineDecisionsFromDb cutover
+        // in step 6.
+        const CRITICAL_CATEGORIES = new Set(["gotcha", "environment", "convention", "architecture"]);
+        const CRITICAL_CAP = 8;
+        const QUERY_K = 10;
+        // ~1 token ≈ 4 chars. 4000 chars ≈ 1000 tokens — comfortably under the
+        // KNOWLEDGE.md 4KB warning threshold and roughly twice the pre-ADR-013
+        // budget so the absorbed DECISIONS surface fits.
+        const CHAR_BUDGET = 4000;
+        const allRanked = getActiveMemoriesRanked(80);
+        const critical = allRanked.filter((m) => CRITICAL_CATEGORIES.has(m.category)).slice(0, CRITICAL_CAP);
+        const criticalIds = new Set(critical.map((m) => m.id));
+        let relevant = [];
+        const trimmed = userPrompt.trim();
+        if (trimmed) {
+            const hits = queryMemoriesRanked({ query: trimmed, k: QUERY_K });
+            relevant = hits.map((h) => h.memory).filter((m) => !criticalIds.has(m.id));
+        }
+        const merged = [...critical, ...relevant];
+        if (merged.length === 0)
+            return "";
+        const formatted = formatMemoriesForPrompt(merged, CHAR_BUDGET);
+        if (!formatted)
+            return "";
+        return `\n\n[MEMORY — Critical and prompt-relevant memories from the GSD memory store]\n\n${formatted}`;
+    }
+    catch (e) {
+        logWarning("bootstrap", `memory block fetch failed: ${e.message}`);
+        return "";
+    }
+}
 export function loadKnowledgeBlock(gsdHomeDir, cwd) {
     // 1. Global knowledge (~/.gsd/agent/KNOWLEDGE.md) — cross-project, user-maintained
     let globalKnowledge = "";

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

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { loadRegistry } from "../workflow-templates.js";
 import { resolveProjectRoot } from "../worktree.js";
 const gsdHome = process.env.GSD_HOME || join(homedir(), ".gsd");
-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|parallel|cmux|park|unpark|init|setup|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language";
+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|parallel|cmux|park|unpark|init|setup|onboarding|inspect|extensions|update|fast|mcp|rethink|codebase|notifications|ship|do|session-report|backlog|pr-branch|add-tests|scan|language";
 export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "help", desc: "Categorized command reference with descriptions" },
     { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
@@ -32,7 +32,7 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { 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.)" },
-    { cmd: "config", desc: "Set API keys for external tools" },
+    { cmd: "config", desc: "(deprecated) Set tool API keys — use /gsd keys instead" },
     { cmd: "keys", desc: "API key manager — list, add, remove, test, rotate, doctor" },
     { cmd: "hooks", desc: "Show configured post-unit and pre-dispatch hooks" },
     { cmd: "run-hook", desc: "Manually trigger a specific hook" },
@@ -43,7 +43,8 @@ export const TOP_LEVEL_SUBCOMMANDS = [
     { cmd: "debug", desc: "Create and inspect persistent /gsd debug sessions" },
     { cmd: "forensics", desc: "Examine execution logs" },
     { cmd: "init", desc: "Project init wizard — detect, configure, bootstrap .gsd/" },
-    { cmd: "setup", desc: "Global setup status and configuration" },
+    { cmd: "setup", desc: "Configuration hub: status + sub-routes (llm, model, search, remote, keys, prefs, onboarding)" },
+    { cmd: "onboarding", desc: "Re-run the setup wizard  [--resume|--reset|--step <name>]" },
     { cmd: "migrate", desc: "Migrate a v1 .planning directory to .gsd format" },
     { cmd: "remote", desc: "Control remote auto-mode" },
     { cmd: "steer", desc: "Hard-steer plan documents during execution" },
@@ -102,11 +103,18 @@ const NESTED_COMPLETIONS = {
         { cmd: "watch", desc: "Live TUI dashboard monitoring all workers" },
     ],
     setup: [
-        { cmd: "llm", desc: "Configure LLM provider settings" },
+        { cmd: "llm", desc: "Configure LLM provider & auth" },
+        { cmd: "model", desc: "Pick default model for the active provider" },
         { cmd: "search", desc: "Configure web search provider" },
-        { cmd: "remote", desc: "Configure remote integrations" },
-        { cmd: "keys", desc: "Manage API keys" },
-        { cmd: "prefs", desc: "Configure global preferences" },
+        { cmd: "remote", desc: "Configure remote integrations (Discord/Slack/Telegram)" },
+        { cmd: "keys", desc: "Manage API keys (alias for /gsd keys)" },
+        { cmd: "prefs", desc: "Global preferences wizard (alias for /gsd prefs)" },
+        { cmd: "onboarding", desc: "Run the full onboarding wizard (alias for /gsd onboarding)" },
+    ],
+    onboarding: [
+        { cmd: "--resume", desc: "Resume from the last completed step" },
+        { cmd: "--reset", desc: "Reset onboarding state and start over (does not clear API keys)" },
+        { cmd: "--step", desc: "Run a single step: llm|model|search|remote|tool-keys|prefs|skills|doctor|project" },
     ],
     notifications: [
         { cmd: "clear", desc: "Clear all notifications" },

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

@@ -36,10 +36,12 @@ export function showHelp(ctx, args = "") {
         "  /gsd debug          Create/list/continue persistent debug sessions",
         "",
         "SETUP",
+        "  /gsd onboarding     Re-run setup wizard  [--resume|--reset|--step <name>]",
+        "  /gsd setup          Configuration hub  [llm|model|search|remote|keys|prefs|onboarding]",
         "  /gsd init           Project init wizard",
-        "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
         "  /gsd model          Switch active session model",
-        "  /gsd prefs          Manage preferences",
+        "  /gsd prefs          Manage preferences (alias for /gsd setup prefs)",
+        "  /gsd keys           API key manager (LLM + tool keys)",
         "  /gsd doctor         Diagnose and repair .gsd/ state",
         "",
         "Use /gsd help full for the complete command reference.",
@@ -83,14 +85,15 @@ export function showHelp(ctx, args = "") {
         "  /gsd codebase [generate|update|stats]   Manage the CODEBASE.md cache used in prompt context",
         "",
         "SETUP & CONFIGURATION",
+        "  /gsd onboarding     Re-run setup wizard  [--resume|--reset|--step <name>]",
+        "  /gsd setup          Configuration hub  [llm|model|search|remote|keys|prefs|onboarding]",
         "  /gsd init           Project init wizard — detect, configure, bootstrap .gsd/",
-        "  /gsd setup          Global setup status  [llm|search|remote|keys|prefs]",
         "  /gsd model          Switch active session model  [provider/model|model-id]",
         "  /gsd mode           Set workflow mode (solo/team)  [global|project]",
-        "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]",
+        "  /gsd prefs          Manage preferences  [global|project|status|wizard|setup|import-claude]  (alias for /gsd setup prefs)",
         "  /gsd cmux           Manage cmux integration  [status|on|off|notifications|sidebar|splits|browser]",
-        "  /gsd config         Set API keys for external tools",
-        "  /gsd keys           API key manager  [list|add|remove|test|rotate|doctor]",
+        "  /gsd keys           API key manager (LLM + tool keys)  [list|add|remove|test|rotate|doctor]",
+        "  /gsd config         (deprecated) Set tool API keys — use /gsd keys instead",
         "  /gsd show-config    Show effective configuration (models, routing, toggles)",
         "  /gsd hooks          Show post-unit hook configuration",
         "  /gsd extensions     Manage extensions  [list|enable|disable|info]",
@@ -155,29 +158,38 @@ 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 handleSetup(args, ctx) {
+export async function handleSetup(args, ctx, pi) {
     const { detectProjectState, hasGlobalSetup } = await import("../../detection.js");
-    const globalConfigured = hasGlobalSetup();
-    const detection = detectProjectState(projectRoot());
-    const statusLines = ["GSD Setup Status\n"];
-    statusLines.push(`  Global preferences: ${globalConfigured ? "configured" : "not set"}`);
-    statusLines.push(`  Project state: ${detection.state}`);
-    if (detection.projectSignals.primaryLanguage) {
-        statusLines.push(`  Detected: ${detection.projectSignals.primaryLanguage}`);
+    const { isOnboardingComplete, readOnboardingRecord } = await import("../../onboarding-state.js");
+    // Sub-route dispatch — keep redirects but route the canonical work to /gsd
+    // onboarding (single source for wizard steps) and /gsd keys (single source
+    // for credentials).
+    if (args === "onboarding" || args === "wizard") {
+        const { handleOnboarding } = await import("./onboarding.js");
+        await handleOnboarding("", ctx);
+        return;
     }
     if (args === "llm" || args === "auth") {
-        ctx.ui.notify("Use /login to configure LLM authentication.", "info");
+        const { handleOnboarding } = await import("./onboarding.js");
+        await handleOnboarding("--step llm", ctx);
         return;
     }
     if (args === "search") {
-        ctx.ui.notify("Use /search-provider to configure web search.", "info");
+        const { handleOnboarding } = await import("./onboarding.js");
+        await handleOnboarding("--step search", ctx);
         return;
     }
     if (args === "remote") {
-        ctx.ui.notify("Use /gsd remote to configure remote questions.", "info");
+        const { handleOnboarding } = await import("./onboarding.js");
+        await handleOnboarding("--step remote", ctx);
+        return;
+    }
+    if (args === "model") {
+        await handleModel("", ctx, pi);
         return;
     }
     if (args === "keys") {
+        ctx.ui.notify("Tip: /gsd keys is the canonical command for API key management.", "info");
         const { handleKeys } = await import("../../key-manager.js");
         await handleKeys("", ctx);
         return;
@@ -187,13 +199,30 @@ export async function handleSetup(args, ctx) {
         await handlePrefsWizard(ctx, "global");
         return;
     }
+    // Bare /gsd setup — render the hub: status + actions
+    const globalConfigured = hasGlobalSetup();
+    const detection = detectProjectState(projectRoot());
+    const onboardingDone = isOnboardingComplete();
+    const record = readOnboardingRecord();
+    const statusLines = ["GSD Setup\n"];
+    statusLines.push(onboardingDone
+        ? `  Onboarding:         ✓ complete${record.completedAt ? ` (${record.completedAt.slice(0, 10)})` : ""}`
+        : `  Onboarding:         ○ not complete  —  /gsd onboarding to start`);
+    statusLines.push(`  Global preferences: ${globalConfigured ? "configured" : "not set"}`);
+    statusLines.push(`  Project state:      ${detection.state}`);
+    if (detection.projectSignals.primaryLanguage) {
+        statusLines.push(`  Detected:           ${detection.projectSignals.primaryLanguage}`);
+    }
     ctx.ui.notify(statusLines.join("\n"), "info");
-    ctx.ui.notify("Available setup commands:\n" +
-        "  /gsd setup llm     — LLM authentication\n" +
-        "  /gsd setup search  — Web search provider\n" +
-        "  /gsd setup remote  — Remote questions (Discord/Slack/Telegram)\n" +
-        "  /gsd setup keys    — Tool API keys\n" +
-        "  /gsd setup prefs   — Global preferences wizard", "info");
+    ctx.ui.notify("Configuration hub:\n" +
+        "  /gsd setup llm        — LLM provider & auth\n" +
+        "  /gsd setup model      — Default model picker\n" +
+        "  /gsd setup search     — Web search provider\n" +
+        "  /gsd setup remote     — Remote questions (Discord/Slack/Telegram)\n" +
+        "  /gsd setup keys       — API keys (alias for /gsd keys)\n" +
+        "  /gsd setup prefs      — Global preferences (alias for /gsd prefs)\n" +
+        "  /gsd setup onboarding — Full wizard (alias for /gsd onboarding)\n\n" +
+        "Tip: /gsd onboarding --resume to continue an incomplete setup.", "info");
 }
 function sortModelsForSelection(models, currentModel) {
     return [...models].sort((a, b) => {
@@ -370,7 +399,12 @@ export async function handleCoreCommand(trimmed, ctx, pi) {
         return true;
     }
     if (trimmed === "setup" || trimmed.startsWith("setup ")) {
-        await handleSetup(trimmed.replace(/^setup\s*/, "").trim(), ctx);
+        await handleSetup(trimmed.replace(/^setup\s*/, "").trim(), ctx, pi);
+        return true;
+    }
+    if (trimmed === "onboarding" || trimmed.startsWith("onboarding ")) {
+        const { handleOnboarding } = await import("./onboarding.js");
+        await handleOnboarding(trimmed.replace(/^onboarding\s*/, "").trim(), ctx);
         return true;
     }
     return false;

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

@@ -0,0 +1,171 @@
+// GSD Extension — /gsd escalate Command Handler (ADR-011 Phase 2)
+// Surface and resolve mid-execution escalations from the CLI.
+import { projectRoot } from "../context.js";
+import { getActiveMilestoneId } from "../../state.js";
+import { readEscalationArtifact, formatEscalationForDisplay, resolveEscalation, listActionableEscalations, listAllEscalations, } from "../../escalation.js";
+import { saveDecisionToDb } from "../../db-writer.js";
+import { loadEffectiveGSDPreferences } from "../../preferences.js";
+import { invalidateStateCache } from "../../state.js";
+import { emitUokAuditEvent, buildAuditEnvelope } from "../../uok/audit.js";
+function helpMessage() {
+    return [
+        "/gsd escalate — manage mid-execution escalations (ADR-011 Phase 2)",
+        "",
+        "Subcommands:",
+        "  list [--all]           show pending escalations (use --all to include resolved)",
+        "  show <taskId>          print the escalation artifact",
+        "  resolve <taskId> <choice> [rationale...]",
+        "                         resolve an escalation — choice is an option id,",
+        "                         `accept` (use recommendation), or `reject-blocker`",
+        "                         (convert to a blocker and trigger slice replan)",
+        "",
+        "Note: disabling `phases.mid_execution_escalation` does NOT clear pending",
+        "escalations. If you need to drain them, re-enable the flag, resolve via",
+        "`/gsd escalate resolve`, then disable.",
+    ].join("\n");
+}
+function formatListEntries(rows, basePath) {
+    if (rows.length === 0)
+        return "No escalations.";
+    return rows.map((t) => {
+        const art = t.escalation_artifact_path ? readEscalationArtifact(t.escalation_artifact_path) : null;
+        const status = t.escalation_pending ? "PENDING (paused)" : t.escalation_awaiting_review ? "awaiting-review" : "resolved";
+        const question = art?.question ?? "(artifact missing)";
+        return `  ${t.slice_id}/${t.id}  [${status}]  ${question}`;
+    }).join("\n");
+}
+export async function handleEscalateCommand(args, ctx, pi) {
+    void pi;
+    const trimmed = args.trim();
+    if (trimmed === "" || trimmed === "help") {
+        ctx.ui.notify(helpMessage(), "info");
+        return;
+    }
+    const basePath = projectRoot();
+    const prefs = loadEffectiveGSDPreferences()?.preferences;
+    if (prefs?.phases?.mid_execution_escalation !== true) {
+        ctx.ui.notify("Escalation is off. Enable with `phases: { mid_execution_escalation: true }` in your PREFERENCES.md.", "warning");
+        return;
+    }
+    const milestoneId = await getActiveMilestoneId(basePath);
+    if (!milestoneId) {
+        ctx.ui.notify("No active milestone — cannot list escalations.", "warning");
+        return;
+    }
+    // ── list ────────────────────────────────────────────────────────────────
+    if (trimmed === "list" || trimmed === "list --all" || trimmed === "--all") {
+        const includeAll = trimmed.includes("--all");
+        const rows = includeAll ? listAllEscalations(milestoneId) : listActionableEscalations(milestoneId);
+        const body = formatListEntries(rows, basePath);
+        ctx.ui.notify(`${includeAll ? "All escalations" : "Actionable escalations"} for ${milestoneId}:\n${body}`, "info");
+        return;
+    }
+    // Parse a possibly-slice-qualified task id: "Sxx/Tyy" or plain "Tyy".
+    // Returns { sliceId?, taskId }.
+    const parseTaskRef = (ref) => {
+        const slash = ref.indexOf("/");
+        if (slash > 0) {
+            return { sliceId: ref.slice(0, slash), taskId: ref.slice(slash + 1) };
+        }
+        return { taskId: ref };
+    };
+    // Resolve a task ref to a single row, surfacing ambiguity when a bare task
+    // id matches more than one slice.
+    const locateRow = (ref) => {
+        const { sliceId, taskId } = parseTaskRef(ref);
+        const rows = listAllEscalations(milestoneId).filter((t) => t.id === taskId && (sliceId === undefined || t.slice_id === sliceId));
+        if (rows.length === 0)
+            return "not-found";
+        if (rows.length > 1)
+            return "ambiguous";
+        return rows[0];
+    };
+    // ── show <taskRef> ──────────────────────────────────────────────────────
+    if (trimmed.startsWith("show ")) {
+        const ref = trimmed.slice(5).trim();
+        const row = locateRow(ref);
+        if (row === "ambiguous") {
+            ctx.ui.notify(`Task ${ref} matches multiple slices. Use Sxx/Tyy format.`, "warning");
+            return;
+        }
+        if (row === "not-found" || !row.escalation_artifact_path) {
+            ctx.ui.notify(`No escalation found for ${ref} in ${milestoneId}.`, "warning");
+            return;
+        }
+        const art = readEscalationArtifact(row.escalation_artifact_path);
+        if (!art) {
+            ctx.ui.notify(`Escalation artifact at ${row.escalation_artifact_path} is missing or malformed.`, "error");
+            return;
+        }
+        ctx.ui.notify(formatEscalationForDisplay(art), "info");
+        return;
+    }
+    // ── resolve <taskRef> <choice> [rationale...] ───────────────────────────
+    if (trimmed.startsWith("resolve ")) {
+        const parts = trimmed.slice(8).trim().split(/\s+/);
+        const ref = parts[0];
+        const choice = parts[1];
+        const rationale = parts.slice(2).join(" ").trim();
+        if (!ref || !choice) {
+            ctx.ui.notify("Usage: /gsd escalate resolve <taskId|Sxx/Tyy> <choice> [rationale...]", "warning");
+            return;
+        }
+        const row = locateRow(ref);
+        if (row === "ambiguous") {
+            ctx.ui.notify(`Task ${ref} matches multiple slices. Use Sxx/Tyy format.`, "warning");
+            return;
+        }
+        if (row === "not-found") {
+            ctx.ui.notify(`No escalation found for ${ref} in ${milestoneId}.`, "warning");
+            return;
+        }
+        const taskId = row.id;
+        const result = resolveEscalation(basePath, milestoneId, row.slice_id, taskId, choice, rationale);
+        invalidateStateCache();
+        if (result.status !== "resolved" && result.status !== "rejected-to-blocker") {
+            ctx.ui.notify(result.message, result.status === "invalid-choice" ? "warning" : "error");
+            return;
+        }
+        // Persist the user's choice as a decision (only for resolved, not reject-blocker).
+        if (result.status === "resolved") {
+            try {
+                const art = row.escalation_artifact_path ? readEscalationArtifact(row.escalation_artifact_path) : null;
+                const scope = `${milestoneId}/${row.slice_id}/${taskId}`;
+                const decisionText = art?.question ?? `escalation on ${taskId}`;
+                const choiceLabel = choice === "accept"
+                    ? `${art?.recommendation ?? "accepted"} (recommended)`
+                    : (result.chosenOption?.label ?? choice);
+                const { id: decisionId } = await saveDecisionToDb({
+                    scope,
+                    decision: decisionText,
+                    choice: choiceLabel,
+                    rationale: rationale || result.chosenOption?.tradeoffs || "User-resolved escalation.",
+                    made_by: "human",
+                    source: "escalation",
+                    when_context: `ADR-011 escalation resolved ${new Date().toISOString()}`,
+                }, basePath);
+                emitUokAuditEvent(basePath, buildAuditEnvelope({
+                    traceId: `escalation:${milestoneId}:${row.slice_id}:${taskId}`,
+                    category: "gate",
+                    type: "escalation-decision-persisted",
+                    payload: {
+                        milestoneId,
+                        sliceId: row.slice_id,
+                        taskId,
+                        decisionId,
+                        choice,
+                    },
+                }));
+                ctx.ui.notify(`${result.message}\nDecision recorded as ${decisionId}. Run /gsd auto to continue.`, "success");
+            }
+            catch (decErr) {
+                ctx.ui.notify(`${result.message}\nWARN: decision persistence failed: ${decErr.message}`, "warning");
+            }
+            return;
+        }
+        // rejected-to-blocker path
+        ctx.ui.notify(`${result.message} Run /gsd auto to trigger the replan.`, "success");
+        return;
+    }
+    ctx.ui.notify(`Unknown subcommand. ${helpMessage()}`, "warning");
+}

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

@@ -0,0 +1,159 @@
+// GSD — /gsd onboarding command handler (re-entry hub)
+//
+// The first-run wizard in src/onboarding.ts uses @clack/prompts and takes over
+// raw stdin. Running it from inside the pi-coding-agent TUI wedges the TUI
+// (clack leaves stdin paused + cooked, pi-tui's data handler then receives no
+// keypresses). So re-entry cannot replay the clack wizard — instead it routes
+// to a setup hub built from ctx.ui.select, which the TUI owns.
+//
+// Clack-only steps (llm/search/remote/tool-keys via the first-run wizard) are
+// surfaced as notifications pointing the user at the canonical per-step
+// commands (/login, /gsd keys, /gsd remote) that are already ctx.ui-safe.
+import { ONBOARDING_STEPS, isValidStepId, } from "../../setup-catalog.js";
+import { isOnboardingComplete, readOnboardingRecord, resetOnboarding, } from "../../onboarding-state.js";
+function parseArgs(raw) {
+    const tokens = raw.split(/\s+/).filter(Boolean);
+    const out = { reset: false, step: null, stepValid: null };
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === "--reset" || t === "reset")
+            out.reset = true;
+        else if (t === "--resume" || t === "resume") {
+            // Re-entry no longer replays the wizard; --resume collapses into the hub.
+        }
+        else if (t === "--step" || t === "step") {
+            const next = tokens[i + 1];
+            if (next) {
+                out.step = next;
+                out.stepValid = isValidStepId(next);
+                i++;
+            }
+        }
+        else if (t.startsWith("--step=")) {
+            const v = t.slice(7);
+            out.step = v;
+            out.stepValid = isValidStepId(v);
+        }
+    }
+    return out;
+}
+// ─── Per-step routing ────────────────────────────────────────────────────────
+//
+// Clack-based steps are surfaced as notifications — running them inline from
+// the TUI would wedge stdin (see header comment). Everything else routes to an
+// existing ctx.ui-safe handler.
+async function runStep(ctx, stepId) {
+    switch (stepId) {
+        case "llm":
+            ctx.ui.notify("LLM provider setup: run /login to sign in via OAuth, or /gsd keys add to paste an API key.", "info");
+            return;
+        case "search":
+            ctx.ui.notify("Web search setup: run /gsd keys add and pick a search provider (brave, tavily, etc.).", "info");
+            return;
+        case "remote":
+            ctx.ui.notify("Remote questions setup: run /gsd remote to configure Discord / Slack / Telegram notifications.", "info");
+            return;
+        case "tool-keys":
+            ctx.ui.notify("Tool keys setup: run /gsd keys add to save API keys for Context7, Jina, Groq voice, etc.", "info");
+            return;
+        case "model": {
+            const { handleCoreCommand } = await import("./core.js");
+            await handleCoreCommand("model", ctx);
+            return;
+        }
+        case "prefs": {
+            const { ensurePreferencesFile, handlePrefsWizard } = await import("../../commands-prefs-wizard.js");
+            const { getGlobalGSDPreferencesPath } = await import("../../preferences.js");
+            await ensurePreferencesFile(getGlobalGSDPreferencesPath(), ctx, "global");
+            await handlePrefsWizard(ctx, "global");
+            return;
+        }
+        case "doctor": {
+            try {
+                const { runProviderDoctor } = await import("../../doctor-providers.js");
+                if (typeof runProviderDoctor === "function") {
+                    await runProviderDoctor(ctx);
+                    return;
+                }
+            }
+            catch { /* fall through */ }
+            ctx.ui.notify("Run /gsd doctor to validate your setup.", "info");
+            return;
+        }
+        case "skills":
+            ctx.ui.notify("Skill install runs during /gsd init. Use /gsd init or /skill manage.", "info");
+            return;
+        case "project": {
+            const { handleCoreCommand } = await import("./core.js");
+            await handleCoreCommand("init", ctx);
+            return;
+        }
+    }
+}
+// ─── Setup hub ───────────────────────────────────────────────────────────────
+async function renderSetupHub(ctx) {
+    const record = readOnboardingRecord();
+    const completed = new Set(record.completedSteps);
+    const skipped = new Set(record.skippedSteps);
+    const labels = ONBOARDING_STEPS.map(step => {
+        const mark = completed.has(step.id) ? "✓" : skipped.has(step.id) ? "↷" : "○";
+        const req = step.required ? " (required)" : "";
+        return `${mark} ${step.label}${req} — ${step.hint}`;
+    });
+    const labelToStep = new Map(labels.map((label, i) => [label, ONBOARDING_STEPS[i].id]));
+    const choice = await ctx.ui.select("GSD Setup — pick a step to configure", labels);
+    if (typeof choice !== "string")
+        return;
+    const stepId = labelToStep.get(choice);
+    if (!stepId)
+        return;
+    await runStep(ctx, stepId);
+}
+function renderStatus() {
+    const r = readOnboardingRecord();
+    const lines = ["GSD Onboarding\n"];
+    if (r.completedAt) {
+        lines.push(`  Completed: ${r.completedAt}`);
+    }
+    else {
+        lines.push(`  Status: not complete`);
+    }
+    if (r.lastResumePoint)
+        lines.push(`  Last step: ${r.lastResumePoint}`);
+    lines.push("");
+    lines.push("  Steps:");
+    for (const step of ONBOARDING_STEPS) {
+        const mark = r.completedSteps.includes(step.id)
+            ? "✓"
+            : r.skippedSteps.includes(step.id)
+                ? "↷"
+                : "○";
+        const reqTag = step.required ? " (required)" : "";
+        lines.push(`    ${mark} ${step.id.padEnd(10)} — ${step.label}${reqTag}`);
+    }
+    return lines.join("\n");
+}
+export async function handleOnboarding(rawArgs, ctx) {
+    const args = parseArgs(rawArgs.trim());
+    if (args.step !== null) {
+        if (!args.stepValid) {
+            const validIds = ONBOARDING_STEPS.map(s => s.id).join(", ");
+            ctx.ui.notify(`Unknown step "${args.step}". Valid: ${validIds}`, "warning");
+            return;
+        }
+        await runStep(ctx, args.step);
+        return;
+    }
+    if (args.reset) {
+        resetOnboarding();
+        ctx.ui.notify("Onboarding state cleared. API keys/credentials are unchanged — manage them with /gsd keys. Restart GSD to re-run the first-run wizard, or pick a step below.", "info");
+        await renderSetupHub(ctx);
+        return;
+    }
+    // No flags (or --resume). Show status if complete, then open the hub.
+    if (isOnboardingComplete()) {
+        ctx.ui.notify(renderStatus(), "info");
+    }
+    await renderSetupHub(ctx);
+}
+export { renderStatus as renderOnboardingStatus };