@opengsd/gsd-pi 1.2.0-dev.fbdca60b → 1.3.0-dev.65546769

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

@@ -0,0 +1,868 @@
+/**
+ * GSD Command — additional workflows (implemented, prompt-driven)
+ *
+ * Each command here is implemented as a real prompt-driven workflow (not an alias).
+ * Commands load a prompt template and dispatch it to the agent via `pi.sendMessage`,
+ * mirroring how /gsd scan and /gsd quick work. Prompt templates work against the
+ * milestone / slice / `.gsd/` model.
+ */
+import { existsSync, mkdirSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { loadPrompt } from "./prompt-loader.js";
+import { currentDirectoryRoot, GSDNoProjectError, projectRoot, withCommandCwd } from "./commands/context.js";
+import { getUnmergedMilestoneBlockMessageForBase } from "./unmerged-milestone-guard.js";
+import { getValidationBlockMessageForBase } from "./validation-block-guard.js";
+/**
+ * Catalog entries for commands IMPLEMENTED natively in this module.
+ * Spread into TOP_LEVEL_SUBCOMMANDS so autocomplete surfaces them.
+ * Keep in sync with the handlers below and the help section in core.ts.
+ */
+export const GSD_CORE_IMPLEMENTED_CATALOG = [
+    { cmd: "explore", desc: "Socratic ideation — think an idea through before committing" },
+    { cmd: "spike", desc: "Validate an idea through focused throwaway experiments" },
+    { cmd: "sketch", desc: "Explore UI/design ideas with throwaway HTML mockups" },
+    { cmd: "map-codebase", desc: "Analyze the codebase into structured reference docs under .gsd/codebase/" },
+    { cmd: "docs-update", desc: "Generate, update, and verify project docs against the live codebase" },
+    { cmd: "graphify", desc: "Build/query/inspect a lightweight project knowledge graph in .gsd/knowledge/" },
+    { cmd: "stats", desc: "Display project statistics — milestones, slices, git metrics, timeline" },
+    { cmd: "progress", desc: "Situational awareness — recent work and what's next" },
+    { cmd: "health", desc: "Validate .gsd/ directory integrity and optionally repair" },
+    { cmd: "surface", desc: "Manage which skills/extensions are surfaced in the session" },
+    { cmd: "code-review", desc: "Review changed source for bugs, security, and quality" },
+    { cmd: "review", desc: "Peer review of recent work across reviewer perspectives" },
+    { cmd: "audit-milestone", desc: "Verify a milestone met its definition of done" },
+    { cmd: "audit-uat", desc: "Cross-milestone audit of outstanding UAT/verification items" },
+    { cmd: "audit-fix", desc: "Audit-to-fix pipeline — classify, fix, test, commit" },
+    { cmd: "ui-review", desc: "Retroactive 6-pillar visual audit of frontend code" },
+    { cmd: "secure-phase", desc: "Verify threat mitigations for completed work" },
+    { cmd: "validate-phase", desc: "Audit and fill validation/test coverage gaps" },
+    { cmd: "verify-work", desc: "Conversational UAT of built features" },
+    { cmd: "plan-review-convergence", desc: "Iterate a plan through review cycles until concerns resolve" },
+    { cmd: "discuss-phase", desc: "Gather milestone/slice context through adaptive questioning" },
+    { cmd: "plan-phase", desc: "Create a detailed slice plan with a verification loop" },
+    { cmd: "execute-phase", desc: "Execute slice tasks with wave-based parallelization" },
+    { cmd: "spec-phase", desc: "Clarify WHAT a milestone delivers, with ambiguity scoring" },
+    { cmd: "mvp-phase", desc: "Plan a milestone as a vertical MVP slice" },
+    { cmd: "ui-phase", desc: "Produce a UI design contract (UI-SPEC) for a frontend milestone" },
+    { cmd: "ai-integration-phase", desc: "Produce an AI design contract (AI-SPEC) for AI milestones" },
+    { cmd: "ultraplan-phase", desc: "Extended-reasoning plan pass, review, then import" },
+    { cmd: "autonomous", desc: "Run all remaining lifecycle work continuously" },
+    { cmd: "pause-work", desc: "Create a context handoff when pausing mid-stream" },
+    { cmd: "resume-work", desc: "Resume work with full context restoration" },
+    { cmd: "manager", desc: "Interactive command center for multiple milestones" },
+    { cmd: "phase", desc: "CRUD for milestone queue ordering" },
+    { cmd: "thread", desc: "Persistent context threads for cross-session work" },
+    { cmd: "workstreams", desc: "Manage parallel workstreams via /gsd parallel" },
+    { cmd: "workspace", desc: "Manage isolated workspaces via /gsd worktree" },
+    { cmd: "milestone-summary", desc: "Comprehensive project/milestone summary for onboarding" },
+    { cmd: "review-backlog", desc: "Review and promote backlog items to milestones" },
+    { cmd: "inbox", desc: "Triage open GitHub issues and PRs against conventions" },
+    { cmd: "import", desc: "Ingest external plans with conflict detection" },
+    { cmd: "ingest-docs", desc: "Bootstrap .gsd/ from existing ADRs/PRDs/SPECs/docs" },
+    { cmd: "profile-user", desc: "Generate and persist a developer behavioral profile" },
+    { cmd: "settings", desc: "Configure workflow toggles and model profile" },
+];
+const FLAG_RE = /(^|\s)--(quick|text|wrap-up|force|verbose|dry-run|all|auto|interactive|tdd|research|skip-research|gaps-only)(?=\s|$)/g;
+/**
+ * Parse the common workflow flags out of a raw arg string.
+ * `frontier` is detected as a bare token or empty input.
+ * Exported for unit testing.
+ */
+export function parseCoreFlags(raw) {
+    let text = raw;
+    const quick = /(^|\s)--quick(?=\s|$)/.test(text);
+    const textMode = /(^|\s)--text(?=\s|$)/.test(text);
+    // Strip recognized --flags so they don't pollute the idea text.
+    text = text.replace(FLAG_RE, " ").replace(/\s+/g, " ").trim();
+    const frontier = text === "" || text.toLowerCase() === "frontier";
+    return { text, quick, textMode, frontier };
+}
+/** Boolean → human-readable phrase for prompt interpolation. */
+function flagPhrase(on) {
+    return on ? "ON" : "off";
+}
+/** Slugify text into a URL/path-safe form (max 40 chars). */
+export function slugify(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-|-$/g, "")
+        .slice(0, 40)
+        .replace(/-$/, "");
+}
+/**
+ * Return the next zero-padded 3-digit id for a numbered artifact directory.
+ * Looks at existing `<dir>/[0-9][0-9][0-9]-*` entries.
+ * Exported for unit testing.
+ */
+export function nextArtifactId(dir) {
+    let max = 0;
+    try {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const m = entry.name.match(/^(\d{3})-/);
+            if (m)
+                max = Math.max(max, Number.parseInt(m[1], 10));
+        }
+    }
+    catch {
+        // dir does not exist yet
+    }
+    return String(max + 1).padStart(3, "0");
+}
+function dispatchPrompt(args, ctx, pi) {
+    ctx.ui.notify(args.notify ?? `Running ${args.verb.toLowerCase()}…`, "info");
+    try {
+        const prompt = loadPrompt(args.prompt, args.vars ?? {});
+        pi.sendMessage({ customType: args.customType, content: prompt, display: false }, { triggerTurn: true });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ctx.ui.notify(`Failed to dispatch ${args.verb.toLowerCase()}: ${msg}`, "error");
+    }
+}
+function splitAction(args) {
+    const trimmed = args.trim();
+    if (!trimmed)
+        return { action: "", rest: "" };
+    const [action = "", ...rest] = trimmed.split(/\s+/);
+    return { action: action.toLowerCase(), rest: rest.join(" ") };
+}
+const MANAGER_ACTIONS_NORMAL = [
+    "3. **Offer actions**, one at a time:",
+    "   - Switch the active milestone (`/gsd queue`).",
+    "   - Reorder queued milestones (`/gsd queue`).",
+    "   - Park or unpark a milestone (`/gsd park` / `/gsd unpark`).",
+    "   - Start/stop auto-mode on the active milestone (`/gsd auto` / `/gsd stop`).",
+    "   - Run parallel milestones (`/gsd parallel`).",
+].join("\n");
+const MANAGER_SUCCESS_NORMAL = [
+    "- The dashboard reflects canonical milestone state, not memory.",
+    "- Actions route to the real gsd-pi commands, not duplicates.",
+    "- Dependency analysis (when requested) is grounded in actual file/API overlap.",
+].join("\n");
+const MANAGER_SUCCESS_READ_ONLY = [
+    "- The dashboard reflects canonical milestone state, not memory.",
+    "- Read-only mode does not route to any gsd-pi command.",
+    "- Dependency analysis (when requested) is grounded in actual file/API overlap.",
+].join("\n");
+const MANAGER_SELECTION_NORMAL = "5. **Act on the selection** by routing to the matching gsd-pi command — do not reimplement queue/park/parallel logic inline.";
+const MANAGER_SELECTION_READ_ONLY = "5. **Skip action routing.** Do not act on selections or invoke gsd-pi commands while this blocker is present.";
+async function dispatchGSDCommand(command, ctx, pi) {
+    const { handleGSDCommand } = await import("./commands/dispatcher.js");
+    await handleGSDCommand(command, ctx, pi);
+}
+function managerReadOnlyActions(blocker) {
+    return [
+        "3. **Stay read-only.** Only display the dashboard and blockers.",
+        "",
+        "Do not offer actions or route to queue, park, auto-mode, or parallel commands until the blocker is resolved.",
+        "",
+        "Blocked state:",
+        blocker,
+    ].join("\n");
+}
+async function resolveManagerVars(args, ctx) {
+    const vars = {
+        analyzeDepsFlag: flagPhrase(/(?:^|\s)--analyze-deps(?=\s|$)/.test(args)),
+        managerActions: MANAGER_ACTIONS_NORMAL,
+        managerSelectionStep: MANAGER_SELECTION_NORMAL,
+        managerSuccessCriteria: MANAGER_SUCCESS_NORMAL,
+    };
+    // Use ctx.cwd when set; when absent fall back to process.cwd() so that the read-only
+    // downgrade still fires even if the caller did not populate ctx.cwd. Wrap in try/catch
+    // so that a missing project context (no .gsd/) returns the normal vars gracefully.
+    try {
+        return await withCommandCwd(ctx.cwd, async () => {
+            const base = projectRoot();
+            const blocker = await getUnmergedMilestoneBlockMessageForBase(base, "manager") ??
+                await getValidationBlockMessageForBase(base, "manager");
+            if (!blocker)
+                return vars;
+            return {
+                ...vars,
+                managerActions: managerReadOnlyActions(blocker),
+                managerSelectionStep: MANAGER_SELECTION_READ_ONLY,
+                managerSuccessCriteria: MANAGER_SUCCESS_READ_ONLY,
+            };
+        });
+    }
+    catch (err) {
+        if (err instanceof GSDNoProjectError)
+            return vars;
+        throw err;
+    }
+}
+// ─── Individual command handlers ─────────────────────────────────────────────
+/** /gsd explore [topic] — Socratic ideation. */
+export async function handleExplore(args, ctx, pi) {
+    const topic = args.trim();
+    dispatchPrompt({
+        prompt: "explore",
+        customType: "gsd-explore",
+        verb: "Explore",
+        vars: { topic: topic || "(no topic — ask the developer what's on their mind)" },
+    }, ctx, pi);
+}
+/** /gsd spike [idea] [--quick] [--text] | frontier */
+export async function handleSpike(args, ctx, pi) {
+    const flags = parseCoreFlags(args);
+    const basePath = currentDirectoryRoot();
+    const spikesDir = join(basePath, ".gsd", "spikes");
+    mkdirSync(spikesDir, { recursive: true });
+    const spikeId = nextArtifactId(spikesDir);
+    dispatchPrompt({
+        prompt: "spike",
+        customType: "gsd-spike",
+        verb: "Spike",
+        vars: {
+            input: flags.text || "(frontier mode — propose what to spike next)",
+            quickFlag: flagPhrase(flags.quick),
+            textFlag: flagPhrase(flags.textMode),
+            frontierFlag: flagPhrase(flags.frontier),
+            spikeId,
+        },
+    }, ctx, pi);
+}
+/** /gsd sketch [idea] [--quick] [--text] | frontier */
+export async function handleSketch(args, ctx, pi) {
+    const flags = parseCoreFlags(args);
+    const basePath = currentDirectoryRoot();
+    const sketchesDir = join(basePath, ".gsd", "sketches");
+    mkdirSync(sketchesDir, { recursive: true });
+    const sketchId = nextArtifactId(sketchesDir);
+    dispatchPrompt({
+        prompt: "sketch",
+        customType: "gsd-sketch",
+        verb: "Sketch",
+        vars: {
+            input: flags.text || "(frontier mode — propose what to sketch next)",
+            quickFlag: flagPhrase(flags.quick),
+            textFlag: flagPhrase(flags.textMode),
+            frontierFlag: flagPhrase(flags.frontier),
+            sketchId,
+        },
+    }, ctx, pi);
+}
+// ─── Batch 2: codebase intelligence ──────────────────────────────────────────
+/**
+ * Parse a `--paths a,b,c` flag safely for map-codebase incremental remap.
+ * Rejects values containing `..`, leading `/`, or shell metacharacters.
+ * Exported for unit testing.
+ */
+export function parsePathsFlag(args) {
+    const m = args.match(/--paths\s+(\S+)/i);
+    if (!m)
+        return "";
+    const raw = m[1];
+    const parts = raw.split(",").map((p) => p.trim()).filter(Boolean);
+    const bad = /[;`$&|<>]/;
+    const safe = parts.filter((p) => !p.startsWith("/") && !p.includes("..") && !bad.test(p));
+    return safe.length ? safe.join(",") : "";
+}
+/** /gsd map-codebase [--paths a,b] [--focus ...] — produce .gsd/codebase/ docs. */
+export async function handleMapCodebase(args, ctx, pi) {
+    const basePath = currentDirectoryRoot();
+    const outputDir = join(basePath, ".gsd", "codebase");
+    mkdirSync(outputDir, { recursive: true });
+    const paths = parsePathsFlag(args);
+    const focus = parseFlagValue(args, "--focus") ?? "";
+    const scopeParts = [];
+    if (paths)
+        scopeParts.push(`Incremental remap — scope exploration to: ${paths}`);
+    else
+        scopeParts.push("Whole-repo scan.");
+    if (focus)
+        scopeParts.push(`Focus area: ${focus}`);
+    dispatchPrompt({
+        prompt: "map-codebase",
+        customType: "gsd-map-codebase",
+        verb: "Map codebase",
+        vars: { scope: scopeParts.join(" "), outputDir: outputDir.replaceAll("\\", "/") },
+    }, ctx, pi);
+}
+/** /gsd docs-update [--force] [--verify-only] — generate/update/verify docs. */
+export async function handleDocsUpdate(args, ctx, pi) {
+    const force = /(^|\s)--force(?=\s|$)/.test(args);
+    const verifyOnly = /(^|\s)--verify-only(?=\s|$)/.test(args);
+    const mode = verifyOnly
+        ? "Verify-only — check existing docs against the codebase; do not write new docs."
+        : force
+            ? "Force — regenerate all canonical docs even if they look current."
+            : "Default — generate missing docs, update stale ones, verify existing claims.";
+    const docsProcess = verifyOnly
+        ? [
+            "1. **Detect the doc structure.** Find existing Markdown docs (README, docs/, ADRs, API docs, CONTRIBUTING, etc.) and any doc tooling (docusaurus, vitepress, mkdocs, storybook). Detect project type (monorepo, cli-tool, saas, open-source-library, generic) from manifests and routes.",
+            "",
+            "2. **Assemble a read-only review manifest.** List existing hand-written docs to review for accuracy. Note missing canonical docs as gaps only; do not create them.",
+            "",
+            "3. **Verify existing docs.** For each existing doc, check factual claims against the codebase: function signatures, file paths, configuration keys, CLI flags, environment variables. Flag inaccuracies and gaps.",
+            "",
+            "4. **Summarize.** Report verified docs, inaccuracies found, missing-doc gaps, and fixes that would need a writable follow-up. Do not edit files.",
+        ].join("\n")
+        : [
+            "1. **Detect the doc structure.** Find existing Markdown docs (README, docs/, ADRs, API docs, CONTRIBUTING, etc.) and any doc tooling (docusaurus, vitepress, mkdocs, storybook). Detect project type (monorepo, cli-tool, saas, open-source-library, generic) from manifests and routes.",
+            "",
+            "2. **Assemble a work manifest.** List every doc item to touch: canonical doc types the project is missing, and existing hand-written docs to review for accuracy. Track each item so nothing is lost between steps.",
+            "",
+            "3. **Write missing canonical docs.** For the detected project type, create the docs that should exist (e.g. README, CONTRIBUTING, ARCHITECTURE, API reference, CHANGELOG). Ground every claim in the live code.",
+            "",
+            "4. **Verify existing docs.** For each existing doc, check factual claims against the codebase: function signatures, file paths, configuration keys, CLI flags, environment variables. Flag inaccuracies and gaps.",
+            "",
+            "5. **Fix loop (bounded).** Correct verified inaccuracies directly. Do not rewrite docs wholesale — fix the specific wrong claims.",
+            "",
+            "6. **Summarize.** Report: docs created, docs updated, inaccuracies fixed, gaps that need a human decision.",
+        ].join("\n");
+    const docsSuccessCriteria = verifyOnly
+        ? [
+            "- Every existing doc claim that references code (paths, signatures, flags, env vars) is checked against the live codebase.",
+            "- Missing docs and inaccuracies are reported as findings only.",
+            "- No documentation files are created, edited, renamed, or deleted.",
+            "- No work item from the manifest is silently dropped.",
+        ].join("\n")
+        : [
+            "- Every doc claim that references code (paths, signatures, flags, env vars) is verified against the live codebase.",
+            "- New docs match the project's detected type and existing style.",
+            "- Fixes are surgical, not rewrites.",
+            "- No work item from the manifest is silently dropped.",
+        ].join("\n");
+    dispatchPrompt({
+        prompt: "docs-update",
+        customType: "gsd-docs-update",
+        verb: "Docs update",
+        vars: { mode, process: docsProcess, successCriteria: docsSuccessCriteria },
+    }, ctx, pi);
+}
+/** /gsd graphify [build|query <term>|status|diff] — knowledge graph. */
+export async function handleGraphify(args, ctx, pi) {
+    const basePath = currentDirectoryRoot();
+    const knowledgeDir = join(basePath, ".gsd", "knowledge");
+    if (!existsSync(knowledgeDir))
+        mkdirSync(knowledgeDir, { recursive: true });
+    const action = args.trim() || "build";
+    dispatchPrompt({ prompt: "graphify", customType: "gsd-graphify", verb: "Graphify", vars: { action } }, ctx, pi);
+}
+/** /gsd stats — project statistics. */
+export async function handleStats(_args, ctx, pi) {
+    dispatchPrompt({ prompt: "stats", customType: "gsd-stats", verb: "Stats" }, ctx, pi);
+}
+/**
+ * Resolve the progress mode from flags. Exported for unit testing.
+ */
+export function parseProgressMode(args) {
+    if (/(?:^|\s)--forensic(?=\s|$)/.test(args))
+        return "forensic";
+    const doMatch = args.match(/--do\s+"([^"]*)"/);
+    if (doMatch)
+        return `do: ${doMatch[1]}`;
+    if (/(?:^|\s)--next(?=\s|$)/.test(args))
+        return "next";
+    return "default";
+}
+/** /gsd progress [--forensic|--next|--do "..."] — situational awareness. */
+export async function handleProgress(args, ctx, pi) {
+    if (/(?:^|\s)--next(?=\s|$)/.test(args)) {
+        await dispatchGSDCommand("next", ctx, pi);
+        return;
+    }
+    const doMatch = args.match(/--do\s+"([^"]*)"/);
+    if (doMatch) {
+        // Re-dispatch as a quick task so the task actually runs.
+        // `quick` is not in either blocked-command set, so the re-dispatch passes guards cleanly.
+        await dispatchGSDCommand(`quick ${doMatch[1]}`, ctx, pi);
+        return;
+    }
+    const mode = parseProgressMode(args);
+    dispatchPrompt({ prompt: "progress", customType: "gsd-progress", verb: "Progress", vars: { mode } }, ctx, pi);
+}
+/** /gsd health [--repair] [--context] — .gsd/ integrity check. */
+export async function handleHealth(args, ctx, pi) {
+    const repair = /(^|\s)--repair(?=\s|$)/.test(args);
+    const contextMode = /(^|\s)--context(?=\s|$)/.test(args);
+    dispatchPrompt({
+        prompt: "health",
+        customType: "gsd-health",
+        verb: "Health check",
+        vars: {
+            repairFlag: flagPhrase(repair),
+            contextFlag: flagPhrase(contextMode),
+        },
+    }, ctx, pi);
+}
+/** /gsd surface [list|status|profile <name>|disable <cluster>|enable <cluster>|reset] */
+export async function handleSurface(args, ctx, pi) {
+    const action = args.trim() || "status";
+    dispatchPrompt({ prompt: "surface", customType: "gsd-surface", verb: "Surface", vars: { action } }, ctx, pi);
+}
+// ─── Batch 3: review / audit ─────────────────────────────────────────────────
+/**
+ * Extract a comma-separated value list for a `--flag value1,value2` option.
+ * Exported for unit testing.
+ */
+export function parseListFlag(args, flag) {
+    const re = new RegExp(`(?:^|\\s)${flag}\\s+([^\\s]+)`, "i");
+    const m = args.match(re);
+    return m ? m[1] : "";
+}
+/**
+ * Determine the review id (zero-padded) for the next review artifact under
+ * `.gsd/reviews/`. Exported for unit testing.
+ */
+export function nextReviewId(reviewsDir) {
+    return nextArtifactId(reviewsDir);
+}
+/** /gsd code-review [target] [--depth quick|standard|deep] [--files ...] [--fix] */
+export async function handleCodeReview(args, ctx, pi) {
+    const depthMatch = args.match(/--depth\s+(quick|standard|deep)/i);
+    const depth = depthMatch ? depthMatch[1].toLowerCase() : "standard";
+    const files = parseListFlag(args, "--files");
+    const fix = /(?:^|\s)--fix(?=\s|$)/.test(args);
+    const scope = files
+        ? `Explicit files: ${files}`
+        : "Changed source files for the active slice (derived from recent commits / SUMMARY), excluding .gsd/, lockfiles, generated, and docs.";
+    const basePath = currentDirectoryRoot();
+    const reviewsDir = join(basePath, ".gsd", "reviews");
+    mkdirSync(reviewsDir, { recursive: true });
+    const reviewId = nextReviewId(reviewsDir);
+    dispatchPrompt({
+        prompt: "code-review",
+        customType: "gsd-code-review",
+        verb: "Code review",
+        vars: {
+            scope,
+            depth,
+            fixMode: flagPhrase(fix),
+            reviewId,
+        },
+    }, ctx, pi);
+}
+const REVIEWER_FLAGS = ["--gemini", "--claude", "--codex", "--opencode", "--qwen", "--cursor", "--agy", "--all"];
+/** /gsd review [--milestone Mxxx] [--claude] [--codex] ... [--all] */
+export async function handleReview(args, ctx, pi) {
+    const milestoneMatch = args.match(/--milestone\s+(\S+)/i);
+    const target = milestoneMatch ? `Milestone ${milestoneMatch[1]}` : "Active slice (plan + recent execution)";
+    const requested = REVIEWER_FLAGS.filter((f) => new RegExp(`(?:^|\\s)${f}(?=\\s|$)`).test(args));
+    const reviewers = requested.length ? requested.map((f) => f.slice(2)).join(", ") : "default (single internal reviewer)";
+    dispatchPrompt({
+        prompt: "review",
+        customType: "gsd-review",
+        verb: "Review",
+        vars: { target, reviewers },
+    }, ctx, pi);
+}
+/** /gsd audit-milestone [Mxxx] */
+export async function handleAuditMilestone(args, ctx, pi) {
+    const id = args.trim();
+    const target = id ? `Milestone ${id}` : "Active or most-recently-completed milestone";
+    dispatchPrompt({ prompt: "audit-milestone", customType: "gsd-audit-milestone", verb: "Audit milestone", vars: { target } }, ctx, pi);
+}
+/** /gsd audit-uat [--verify] */
+export async function handleAuditUat(args, ctx, pi) {
+    const verify = /(?:^|\s)--verify(?=\s|$)/.test(args);
+    dispatchPrompt({
+        prompt: "audit-uat",
+        customType: "gsd-audit-uat",
+        verb: "Audit UAT",
+        vars: { verifyMode: flagPhrase(verify) },
+    }, ctx, pi);
+}
+/** /gsd audit-fix [--source <audit>] [--severity medium|high|all] [--max N] [--dry-run] */
+export async function handleAuditFix(args, ctx, pi) {
+    const sourceMatch = args.match(/--source\s+(\S+)/i);
+    const sevMatch = args.match(/--severity\s+(medium|high|all)/i);
+    const maxMatch = args.match(/--max\s+(\d+)/);
+    const dryRun = /(?:^|\s)--dry-run(?=\s|$)/.test(args);
+    dispatchPrompt({
+        prompt: "audit-fix",
+        customType: "gsd-audit-fix",
+        verb: "Audit-fix",
+        vars: {
+            source: sourceMatch ? sourceMatch[1] : "most recent audit-uat / scan findings",
+            severity: sevMatch ? sevMatch[1] : "all",
+            maxFixes: maxMatch ? maxMatch[1] : "(no cap)",
+            dryRun: flagPhrase(dryRun),
+        },
+    }, ctx, pi);
+}
+/** /gsd ui-review [target] */
+export async function handleUiReview(args, ctx, pi) {
+    const target = args.trim() || "Implemented frontend for the active milestone/slice";
+    const basePath = currentDirectoryRoot();
+    const reviewsDir = join(basePath, ".gsd", "reviews");
+    mkdirSync(reviewsDir, { recursive: true });
+    const reviewId = nextReviewId(reviewsDir);
+    dispatchPrompt({ prompt: "ui-review", customType: "gsd-ui-review", verb: "UI review", vars: { target, reviewId } }, ctx, pi);
+}
+/** /gsd secure-phase [target] */
+export async function handleSecurePhase(args, ctx, pi) {
+    const target = args.trim() || "Active milestone/slice";
+    dispatchPrompt({ prompt: "secure-phase", customType: "gsd-secure-phase", verb: "Security audit", vars: { target } }, ctx, pi);
+}
+/** /gsd validate-phase [target] */
+export async function handleValidatePhase(args, ctx, pi) {
+    const target = args.trim() || "Active milestone/slice";
+    dispatchPrompt({ prompt: "validate-phase", customType: "gsd-validate-phase", verb: "Validation audit", vars: { target } }, ctx, pi);
+}
+/** /gsd verify-work [target] */
+export async function handleVerifyWork(args, ctx, pi) {
+    const target = args.trim() || "Active milestone/slice";
+    dispatchPrompt({ prompt: "verify-work", customType: "gsd-verify-work", verb: "Verify work (UAT)", vars: { target } }, ctx, pi);
+}
+/** /gsd plan-review-convergence [target] [--claude] [--codex] ... [--max-cycles N] */
+export async function handlePlanReviewConvergence(args, ctx, pi) {
+    const milestoneMatch = args.match(/--milestone\s+(\S+)/i);
+    const target = milestoneMatch ? `Milestone ${milestoneMatch[1]}` : "Active slice/milestone plan";
+    const requested = REVIEWER_FLAGS.filter((f) => new RegExp(`(?:^|\\s)${f}(?=\\s|$)`).test(args));
+    const reviewers = requested.length ? requested.map((f) => f.slice(2)).join(", ") : "default (single internal reviewer)";
+    const maxMatch = args.match(/--max-cycles\s+(\d+)/);
+    dispatchPrompt({
+        prompt: "plan-review-convergence",
+        customType: "gsd-plan-review-convergence",
+        verb: "Plan convergence",
+        vars: { target, reviewers, maxCycles: maxMatch ? maxMatch[1] : "3" },
+    }, ctx, pi);
+}
+// ─── Batch 4: workflow phases ────────────────────────────────────────────────
+/** Resolve a milestone/slice target from --milestone/--slice flags. */
+function resolveMsTarget(args, fallback) {
+    const m = args.match(/--milestone\s+(\S+)/i);
+    if (m)
+        return `Milestone ${m[1]}`;
+    const s = args.match(/--slice\s+(\S+)/i);
+    if (s)
+        return `Slice ${s[1]}`;
+    return fallback;
+}
+/** /gsd discuss-phase [--milestone Mxxx] [--auto] [--text] */
+export async function handleDiscussPhase(args, ctx, pi) {
+    const target = resolveMsTarget(args, "Active milestone/slice");
+    dispatchPrompt({
+        prompt: "discuss-phase",
+        customType: "gsd-discuss-phase",
+        verb: "Discuss phase",
+        vars: {
+            target,
+            autoFlag: flagPhrase(/(?:^|\s)--auto(?=\s|$)/.test(args)),
+            textFlag: flagPhrase(parseCoreFlags(args).textMode),
+        },
+    }, ctx, pi);
+}
+/** /gsd plan-phase [--milestone Mxxx] [--auto] [--research|--skip-research] [--tdd] */
+export async function handlePlanPhase(args, ctx, pi) {
+    const target = resolveMsTarget(args, "Active milestone/slice");
+    const research = /(?:^|\s)--research(?=\s|$)/.test(args);
+    const skipResearch = /(?:^|\s)--skip-research(?=\s|$)/.test(args);
+    const researchFlag = skipResearch ? "skip-research" : research ? "research" : "off";
+    dispatchPrompt({
+        prompt: "plan-phase",
+        customType: "gsd-plan-phase",
+        verb: "Plan phase",
+        vars: {
+            target,
+            autoFlag: flagPhrase(/(?:^|\s)--auto(?=\s|$)/.test(args)),
+            researchFlag,
+            tddFlag: flagPhrase(/(?:^|\s)--tdd(?=\s|$)/.test(args)),
+        },
+    }, ctx, pi);
+}
+/** /gsd execute-phase [--milestone Mxxx] [--wave N] [--gaps-only] [--interactive] [--tdd] */
+export async function handleExecutePhase(args, ctx, pi) {
+    const target = resolveMsTarget(args, "Active milestone/slice");
+    const waveMatch = args.match(/--wave\s+(\d+)/);
+    dispatchPrompt({
+        prompt: "execute-phase",
+        customType: "gsd-execute-phase",
+        verb: "Execute phase",
+        vars: {
+            target,
+            waveFlag: waveMatch ? waveMatch[1] : "(sequential)",
+            gapsOnlyFlag: flagPhrase(/(?:^|\s)--gaps-only(?=\s|$)/.test(args)),
+            interactiveFlag: flagPhrase(/(?:^|\s)--interactive(?=\s|$)/.test(args)),
+            tddFlag: flagPhrase(/(?:^|\s)--tdd(?=\s|$)/.test(args)),
+        },
+    }, ctx, pi);
+}
+/** /gsd spec-phase [--milestone Mxxx] [--auto] [--text] */
+export async function handleSpecPhase(args, ctx, pi) {
+    const target = resolveMsTarget(args, "Active milestone/slice");
+    dispatchPrompt({
+        prompt: "spec-phase",
+        customType: "gsd-spec-phase",
+        verb: "Spec phase",
+        vars: {
+            target,
+            autoFlag: flagPhrase(/(?:^|\s)--auto(?=\s|$)/.test(args)),
+            textFlag: flagPhrase(parseCoreFlags(args).textMode),
+        },
+    }, ctx, pi);
+}
+/** /gsd mvp-phase [--milestone Mxxx] */
+export async function handleMvpPhase(args, ctx, pi) {
+    const target = resolveMsTarget(args, "Active milestone");
+    dispatchPrompt({ prompt: "mvp-phase", customType: "gsd-mvp-phase", verb: "MVP phase", vars: { target } }, ctx, pi);
+}
+/** /gsd ui-phase [--milestone Mxxx] */
+export async function handleUiPhase(args, ctx, pi) {
+    const target = resolveMsTarget(args, "Active frontend milestone/slice");
+    dispatchPrompt({ prompt: "ui-phase", customType: "gsd-ui-phase", verb: "UI phase", vars: { target } }, ctx, pi);
+}
+/** /gsd ai-integration-phase [--milestone Mxxx] */
+export async function handleAiIntegrationPhase(args, ctx, pi) {
+    const target = resolveMsTarget(args, "Active AI milestone/slice");
+    dispatchPrompt({ prompt: "ai-integration-phase", customType: "gsd-ai-integration-phase", verb: "AI integration phase", vars: { target } }, ctx, pi);
+}
+/** /gsd ultraplan-phase [--milestone Mxxx] */
+export async function handleUltraplanPhase(args, ctx, pi) {
+    const target = resolveMsTarget(args, "Active milestone/slice");
+    dispatchPrompt({ prompt: "ultraplan-phase", customType: "gsd-ultraplan-phase", verb: "Ultraplan phase", vars: { target } }, ctx, pi);
+}
+/**
+ * Parse autonomous scope flags (--from/--to/--only). Exported for unit testing.
+ */
+export function parseAutonomousScope(args) {
+    const from = args.match(/--from\s+(\d+)/);
+    const to = args.match(/--to\s+(\d+)/);
+    const only = args.match(/--only\s+(\d+)/);
+    if (only)
+        return `Only slice/milestone ${only[1]}`;
+    const parts = [];
+    if (from)
+        parts.push(`from ${from[1]}`);
+    if (to)
+        parts.push(`to ${to[1]}`);
+    return parts.length ? `All remaining work ${parts.join(" ")}` : "All remaining work on the active milestone";
+}
+/** /gsd autonomous [--from N] [--to N] [--only N] [--interactive] [--converge] */
+export async function handleAutonomous(args, ctx, pi) {
+    dispatchPrompt({
+        prompt: "autonomous",
+        customType: "gsd-autonomous",
+        verb: "Autonomous",
+        vars: {
+            scope: parseAutonomousScope(args),
+            interactiveFlag: flagPhrase(/(?:^|\s)--interactive(?=\s|$)/.test(args)),
+            convergeFlag: flagPhrase(/(?:^|\s)--converge(?=\s|$)/.test(args)),
+        },
+    }, ctx, pi);
+}
+/** /gsd pause-work [--report] */
+export async function handlePauseWork(args, ctx, pi) {
+    dispatchPrompt({
+        prompt: "pause-work",
+        customType: "gsd-pause-work",
+        verb: "Pause work",
+        vars: { reportFlag: flagPhrase(/(?:^|\s)--report(?=\s|$)/.test(args)) },
+    }, ctx, pi);
+}
+/** /gsd resume-work */
+export async function handleResumeWork(_args, ctx, pi) {
+    dispatchPrompt({ prompt: "resume-work", customType: "gsd-resume-work", verb: "Resume work" }, ctx, pi);
+}
+// ─── Batch 5: project management ─────────────────────────────────────────────
+/** /gsd manager [--analyze-deps] */
+export async function handleManager(args, ctx, pi) {
+    const vars = await resolveManagerVars(args, ctx);
+    dispatchPrompt({
+        prompt: "manager",
+        customType: "gsd-manager",
+        verb: "Manager",
+        vars,
+    }, ctx, pi);
+}
+/** /gsd phase [add|insert|remove|edit|list] <target> */
+export async function handlePhase(args, ctx, pi) {
+    const action = args.trim() || "list";
+    const parsed = splitAction(action);
+    if (parsed.action === "list" || parsed.action === "status") {
+        await dispatchGSDCommand("queue", ctx, pi);
+        return;
+    }
+    if (["add", "create", "new"].includes(parsed.action) && !parsed.rest) {
+        await dispatchGSDCommand("new-milestone", ctx, pi);
+        return;
+    }
+    dispatchPrompt({ prompt: "phase", customType: "gsd-phase", verb: "Phase", vars: { action } }, ctx, pi);
+}
+/** /gsd thread [list|close <slug>|status <slug>|<name>] */
+export async function handleThread(args, ctx, pi) {
+    const action = args.trim() || "list";
+    dispatchPrompt({ prompt: "thread", customType: "gsd-thread", verb: "Thread", vars: { action } }, ctx, pi);
+}
+/** /gsd workstreams [list|create|switch|progress|pause|resume|complete] [milestone] */
+export async function handleWorkstreams(args, ctx, pi) {
+    const action = args.trim() || "list";
+    const parsed = splitAction(action);
+    let parallelAction = "";
+    if (parsed.action === "list" || parsed.action === "status" || parsed.action === "progress") {
+        parallelAction = "status";
+    }
+    else if (parsed.action === "create") {
+        parallelAction = "start";
+    }
+    else if (parsed.action === "complete") {
+        parallelAction = "merge";
+    }
+    else if (parsed.action === "switch") {
+        parallelAction = "watch";
+    }
+    else if (["start", "stop", "pause", "resume", "merge", "watch"].includes(parsed.action)) {
+        parallelAction = parsed.action;
+    }
+    if (parallelAction) {
+        if ((parsed.action === "create" || parsed.action === "start") && parsed.rest) {
+            ctx.ui.notify("workstreams create does not accept a milestone target. Run /gsd parallel start to start all eligible milestones.", "warning");
+            return;
+        }
+        if (parsed.action === "progress" && parsed.rest) {
+            ctx.ui.notify("workstreams progress does not accept a milestone target. Run /gsd parallel status to show worker status.", "warning");
+            return;
+        }
+        if (parsed.action === "switch" && parsed.rest) {
+            ctx.ui.notify("workstreams switch does not accept a milestone target. Run /gsd parallel watch to monitor workers.", "warning");
+            return;
+        }
+        await dispatchGSDCommand(`parallel ${parallelAction} ${parsed.rest}`.trim(), ctx, pi);
+        return;
+    }
+    dispatchPrompt({ prompt: "workstreams", customType: "gsd-workstreams", verb: "Workstreams", vars: { action } }, ctx, pi);
+}
+/** /gsd workspace [--list|--remove|--merge|--clean] [name] */
+export async function handleWorkspace(args, ctx, pi) {
+    const action = args.trim() || "--list";
+    const parsed = splitAction(action);
+    if (parsed.action === "--list" || parsed.action === "list" || parsed.action === "ls") {
+        await dispatchGSDCommand("worktree list", ctx, pi);
+        return;
+    }
+    if (parsed.action === "--remove" || parsed.action === "remove" || parsed.action === "rm") {
+        await dispatchGSDCommand(`worktree remove ${parsed.rest}`.trim(), ctx, pi);
+        return;
+    }
+    if (parsed.action === "--merge" || parsed.action === "merge") {
+        await dispatchGSDCommand(`worktree merge ${parsed.rest}`.trim(), ctx, pi);
+        return;
+    }
+    if (parsed.action === "--clean" || parsed.action === "clean") {
+        await dispatchGSDCommand("worktree clean", ctx, pi);
+        return;
+    }
+    if (parsed.action === "--new" || parsed.action === "new" || parsed.action === "create") {
+        ctx.ui.notify("Unsupported workspace action. Use /gsd worktree list, remove, merge, or clean.", "warning");
+        return;
+    }
+    dispatchPrompt({ prompt: "workspace", customType: "gsd-workspace", verb: "Workspace", vars: { action } }, ctx, pi);
+}
+/** /gsd milestone-summary [Mxxx] */
+export async function handleMilestoneSummary(args, ctx, pi) {
+    const id = args.trim();
+    const target = id ? `Milestone ${id}` : "Whole project (all milestones)";
+    dispatchPrompt({ prompt: "milestone-summary", customType: "gsd-milestone-summary", verb: "Milestone summary", vars: { target } }, ctx, pi);
+}
+/** /gsd review-backlog */
+export async function handleReviewBacklog(_args, ctx, pi) {
+    dispatchPrompt({ prompt: "review-backlog", customType: "gsd-review-backlog", verb: "Review backlog" }, ctx, pi);
+}
+/**
+ * Parse inbox focus flags. Exported for unit testing.
+ */
+export function parseInboxFocus(args) {
+    const issues = /(?:^|\s)--issues(?=\s|$)/.test(args);
+    const prs = /(?:^|\s)--prs(?=\s|$)/.test(args);
+    if (issues && prs)
+        return "issues and PRs";
+    if (issues)
+        return "issues only";
+    if (prs)
+        return "PRs only";
+    return "issues and PRs (default)";
+}
+function parseFlagValue(args, flag) {
+    const escaped = flag.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`(?:^|\\s)${escaped}\\s+` +
+        `(?!--)` +
+        `(?:"([^"]*)"|'([^']*)'|([^\\s].*?))` +
+        `(?=\\s--[\\w-]+|$)`);
+    const match = args.match(pattern);
+    if (!match)
+        return null;
+    return (match[1] ?? match[2] ?? match[3] ?? "").trim();
+}
+/** /gsd inbox [--issues|--prs] [--label <name>] [--close-incomplete] [--repo owner/repo] */
+export async function handleInbox(args, ctx, pi) {
+    const repo = parseFlagValue(args, "--repo");
+    const label = parseFlagValue(args, "--label");
+    if (/(?:^|\s)--repo(?=\s|$)/.test(args) && !repo) {
+        ctx.ui.notify("--repo requires a value. Example: /gsd inbox --repo owner/repo", "warning");
+        return;
+    }
+    if (/(?:^|\s)--label(?=\s|$)/.test(args) && !label) {
+        ctx.ui.notify("--label requires a value. Example: /gsd inbox --label \"help wanted\"", "warning");
+        return;
+    }
+    dispatchPrompt({
+        prompt: "inbox",
+        customType: "gsd-inbox",
+        verb: "Inbox",
+        vars: {
+            focusFlag: parseInboxFocus(args),
+            labelFlag: label ?? "(none)",
+            closeIncompleteFlag: flagPhrase(/(?:^|\s)--close-incomplete(?=\s|$)/.test(args)),
+            repo: repo ?? "the project's repo",
+        },
+    }, ctx, pi);
+}
+/** /gsd import --from <filepath> | --from-gsd2 [--resolve auto|interactive] */
+export async function handleImport(args, ctx, pi) {
+    const fromMatch = args.match(/--from\s+(\S+)/);
+    const isGsd2 = /(?:^|\s)--from-gsd2(?=\s|$)/.test(args);
+    const resolveMatch = args.match(/--resolve\s+(auto|interactive)/i);
+    const source = fromMatch
+        ? `External plan file: ${fromMatch[1]}`
+        : isGsd2
+            ? "legacy .planning/ directory (migration source)"
+            : "(no source specified — ask for --from <filepath> or --from-gsd2)";
+    dispatchPrompt({
+        prompt: "import",
+        customType: "gsd-import",
+        verb: "Import",
+        vars: {
+            source,
+            resolveFlag: resolveMatch ? resolveMatch[1] : "interactive",
+        },
+    }, ctx, pi);
+}
+/** /gsd ingest-docs [path] [--mode new|merge] [--manifest <file>] [--resolve auto|interactive] */
+export async function handleIngestDocs(args, ctx, pi) {
+    const modeMatch = args.match(/--mode\s+(new|merge)/i);
+    const manifestMatch = args.match(/--manifest\s+(\S+)/);
+    const resolveMatch = args.match(/--resolve\s+(auto|interactive)/i);
+    const flagStripped = args.replace(/--\S+(\s+\S+)?/g, "").trim();
+    dispatchPrompt({
+        prompt: "ingest-docs",
+        customType: "gsd-ingest-docs",
+        verb: "Ingest docs",
+        vars: {
+            path: flagStripped || "(repo root)",
+            modeFlag: modeMatch ? modeMatch[1] : "new",
+            manifestFlag: manifestMatch ? manifestMatch[1] : "(none — discover all)",
+            resolveFlag: resolveMatch ? resolveMatch[1] : "interactive",
+        },
+    }, ctx, pi);
+}
+/** /gsd profile-user [--questionnaire] [--refresh] */
+export async function handleProfileUser(args, ctx, pi) {
+    dispatchPrompt({
+        prompt: "profile-user",
+        customType: "gsd-profile-user",
+        verb: "Profile user",
+        vars: {
+            questionnaireFlag: flagPhrase(/(?:^|\s)--questionnaire(?=\s|$)/.test(args)),
+            refreshFlag: flagPhrase(/(?:^|\s)--refresh(?=\s|$)/.test(args)),
+        },
+    }, ctx, pi);
+}
+/** /gsd settings */
+export async function handleSettings(_args, ctx, pi) {
+    dispatchPrompt({ prompt: "settings", customType: "gsd-settings", verb: "Settings" }, ctx, pi);
+}