@dev-tren/mapd 0.21.0

package/src/agents/provider.js

@@ -0,0 +1,222 @@
+/**
+ * provider.js — LLM provider abstraction. The rest of Map'd depends on this
+ * interface, never on a vendor SDK type directly.
+ *
+ * `getProvider(config)` -> { name, model, available(), complete(system, user, maxTokens) }
+ *
+ * Implementations:
+ *   - anthropicProvider    — reuses @anthropic-ai/sdk (already a dependency)
+ *   - openaiCompatProvider — plain global fetch (Node 20+), no new SDK dependency
+ *   - kimiProvider         — Moonshot AI's Kimi models, over the same
+ *                            OpenAI-compatible chat/completions shape, its own
+ *                            KIMI_API_KEY/KIMI_BASE_URL so it never collides
+ *                            with a real OpenAI key in the same environment
+ *   - nullProvider         — deterministic-only: available() is false, complete()
+ *                            resolves null. This is what keeps chat/fix/mcp fully
+ *                            functional with zero API key configured.
+ *
+ * Never persists credentials: API keys are read from process.env only, never
+ * written to .mapdrc, config-state.json, or any audit record.
+ */
+
+import { createAnthropicClientLoader } from "./anthropicClient.js";
+import { resolveAnthropicModel, pinnedModel, FALLBACK_SONNET } from "./modelResolver.js";
+const DEFAULT_OPENAI_MODEL = "gpt-4o-mini";
+// Moonshot renames/adds Kimi model identifiers over time — verify the current
+// one at https://platform.moonshot.ai/docs before relying on this default;
+// override via .mapdrc `providers.kimi.model` at any time. (Confirmed present
+// in Moonshot's own "Models and Pricing" listing as of this writing.)
+const DEFAULT_KIMI_MODEL = "kimi-k2.6";
+
+function redactForError(message) {
+  return String(message ?? "")
+    .replace(/sk-[A-Za-z0-9-_]{10,}/g, "sk-***redacted***")
+    .replace(/\bBearer\s+[A-Za-z0-9-_.]{10,}/gi, "Bearer ***redacted***");
+}
+
+async function responseTextOrEmpty(res) {
+  try {
+    return await res.text();
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Shared client for any OpenAI-compatible chat/completions endpoint —
+ * openaiCompatProvider and kimiProvider both delegate here so the fetch/
+ * error-handling logic exists exactly once.
+ */
+const TRUNCATION_RETRY_CAP_TOKENS = 8000;
+const TRUNCATION_NOTICE = "\n\n[⚠ response was truncated by the token limit even after one retry — this answer may be incomplete]";
+
+function createOpenAiCompatibleProvider({ name, model, apiKeyEnv, baseUrl }) {
+  async function callOnce({ apiKey, system, user, maxTokens, signal }) {
+    let res;
+    try {
+      res = await fetch(`${baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+          model,
+          max_tokens: maxTokens,
+          messages: [{ role: "system", content: system }, { role: "user", content: user }],
+        }),
+        signal,
+      });
+    } catch (e) {
+      throw new Error(`${name} provider network error: ${redactForError(e.message)}`);
+    }
+    if (!res.ok) {
+      const body = await responseTextOrEmpty(res);
+      throw new Error(`${name} provider error: HTTP ${res.status} ${redactForError(body).slice(0, 500)}`);
+    }
+    const json = await res.json();
+    const choice = json.choices?.[0];
+    const message = choice?.message;
+    const content = message?.content?.trim();
+    // Reasoning models (Kimi K2, and others behind this same OpenAI-compatible
+    // shape) return chain-of-thought in `reasoning_content` separately from
+    // the final answer in `content`. On a long/complex prompt the model can
+    // spend its whole max_tokens budget reasoning and never reach `content`,
+    // leaving it empty — falling back to reasoning_content surfaces *something*
+    // real rather than nothing; it's the model's own scratchpad, not a
+    // polished answer, so callers should treat it as a lower-confidence result.
+    const reasoning = message?.reasoning_content?.trim();
+    return { text: content || reasoning || null, truncated: choice?.finish_reason === "length" };
+  }
+
+  return {
+    name,
+    model,
+    available: () => !!process.env[apiKeyEnv],
+    async complete(system, user, maxTokens = 1500, { signal } = {}) {
+      const apiKey = process.env[apiKeyEnv];
+      if (!apiKey) return null;
+      let result = await callOnce({ apiKey, system, user, maxTokens, signal });
+      // A response cut off mid-answer (finish_reason "length") is worse than
+      // no answer — it can leave an incomplete claim looking finished, or (on
+      // a reasoning model) leak unfinished chain-of-thought as if it were the
+      // polished answer. One bounded retry with a larger budget resolves this
+      // in most cases without unbounded cost/latency; if it's still truncated
+      // after that, disclose it explicitly rather than silently returning a
+      // cut-off answer as if it were complete.
+      if (result.truncated && maxTokens < TRUNCATION_RETRY_CAP_TOKENS) {
+        result = await callOnce({ apiKey, system, user, maxTokens: Math.min(maxTokens * 2, TRUNCATION_RETRY_CAP_TOKENS), signal });
+      }
+      if (!result.text) return null;
+      return result.truncated ? `${result.text}${TRUNCATION_NOTICE}` : result.text;
+    },
+  };
+}
+
+export function anthropicProvider(config = {}) {
+  const client = createAnthropicClientLoader();
+  let resolved = null; // { model, source } — resolved once per process, on first use
+  async function callOnce(c, { system, user, maxTokens, signal }) {
+    const msg = await c.messages.create(
+      { model: resolved.model, max_tokens: maxTokens, system, messages: [{ role: "user", content: user }] },
+      { signal },
+    );
+    if (msg.model) provider.lastModelUsed = msg.model; // what actually answered, as the API reports it
+    const text = msg.content.filter((b) => b.type === "text").map((b) => b.text).join("\n").trim();
+    return { text: text || null, truncated: msg.stop_reason === "max_tokens" };
+  }
+
+  const provider = {
+    name: "anthropic",
+    // Until resolved: the pin, or the fallback. Unpinned, the real value is the
+    // newest Sonnet the Models API lists (see modelResolver.js).
+    model: pinnedModel(config) ?? FALLBACK_SONNET,
+    modelSource: pinnedModel(config) ? "pinned" : "unresolved",
+    lastModelUsed: null,
+    available: () => !!process.env.ANTHROPIC_API_KEY,
+    async resolveModel() {
+      const c = await client();
+      if (!c) return { model: provider.model, source: provider.modelSource };
+      if (!resolved) {
+        resolved = await resolveAnthropicModel(c, { config });
+        provider.model = resolved.model;
+        provider.modelSource = resolved.source;
+      }
+      return resolved;
+    },
+    async complete(system, user, maxTokens = 1500, { signal } = {}) {
+      const c = await client();
+      if (!c) return null;
+      await provider.resolveModel();
+      try {
+        let result = await callOnce(c, { system, user, maxTokens, signal });
+        // Same bounded-retry-then-disclose policy as the OpenAI-compatible
+        // providers: a response cut off mid-answer must never be presented as
+        // if it were complete.
+        if (result.truncated && maxTokens < TRUNCATION_RETRY_CAP_TOKENS) {
+          result = await callOnce(c, { system, user, maxTokens: Math.min(maxTokens * 2, TRUNCATION_RETRY_CAP_TOKENS), signal });
+        }
+        if (!result.text) return null;
+        return result.truncated ? `${result.text}${TRUNCATION_NOTICE}` : result.text;
+      } catch (e) {
+        throw new Error(`anthropic provider error: ${redactForError(e.message)}`);
+      }
+    },
+  };
+  return provider;
+}
+
+export function openaiCompatProvider(config = {}) {
+  return createOpenAiCompatibleProvider({
+    name: "openai",
+    model: config.providers?.openai?.model || DEFAULT_OPENAI_MODEL,
+    apiKeyEnv: "OPENAI_API_KEY",
+    baseUrl: process.env.OPENAI_BASE_URL || "https://api.openai.com/v1",
+  });
+}
+
+/**
+ * Moonshot AI's Kimi models — an OpenAI-compatible chat/completions API, so
+ * this reuses the same shared client as openaiCompatProvider. Uses its own
+ * KIMI_API_KEY (not OPENAI_API_KEY) so a Kimi key and a real OpenAI key can
+ * both be configured in the same environment without colliding. KIMI_BASE_URL
+ * defaults to the global endpoint; override it for the China region
+ * (https://api.moonshot.cn/v1) if that's where your account is registered.
+ */
+export function kimiProvider(config = {}) {
+  return createOpenAiCompatibleProvider({
+    name: "kimi",
+    model: config.providers?.kimi?.model || DEFAULT_KIMI_MODEL,
+    apiKeyEnv: "KIMI_API_KEY",
+    baseUrl: process.env.KIMI_BASE_URL || "https://api.moonshot.ai/v1",
+  });
+}
+
+export function nullProvider() {
+  return {
+    name: "none",
+    model: null,
+    available: () => false,
+    async complete() { return null; },
+  };
+}
+
+/**
+ * Select a provider from config: "auto" tries anthropic, then openai, then
+ * kimi, then null; an explicit name pins to that provider (falling back to
+ * null if unavailable).
+ */
+export function getProvider(config = {}) {
+  const requested = config.chat?.provider ?? "auto";
+  const candidates = {
+    anthropic: anthropicProvider(config),
+    openai: openaiCompatProvider(config),
+    kimi: kimiProvider(config),
+    none: nullProvider(),
+  };
+  if (requested !== "auto") return candidates[requested] ?? nullProvider();
+  if (candidates.anthropic.available()) return candidates.anthropic;
+  if (candidates.openai.available()) return candidates.openai;
+  if (candidates.kimi.available()) return candidates.kimi;
+  return candidates.none;
+}

package/src/chat/commandRunner.js

@@ -0,0 +1,86 @@
+/**
+ * commandRunner.js — safe dev-command execution for chat/mcp. Never executes
+ * arbitrary shell text: every call is (cmd, args[]) through execFile/spawn
+ * (argument arrays, no shell interpolation), classified through
+ * core/policy.js before it's allowed to run at all, with a controlled cwd,
+ * a timeout, an output-character cap, and secret redaction on the way out.
+ *
+ * Long-running ("networked") commands (e.g. a dev server) are tracked in
+ * `activeChildren` so `mapd chat end` can terminate them before the chat
+ * process exits — nothing spawned by a chat session is left running after
+ * the session ends.
+ */
+
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { classifyCommand, isPermitted } from "../core/policy.js";
+import { redactSecrets } from "../core/security.js";
+import { platformCommand } from "../core/proc.js";
+
+const activeChildren = new Set();
+
+export function getActiveChildren() { return activeChildren; }
+
+export function killActiveChildren() {
+  for (const child of activeChildren) {
+    try {
+      // on Windows the child is a shell wrapping npm/node: kill the whole tree, not just the shell
+      if (process.platform === "win32" && child.pid) execFileSync("taskkill", ["/pid", String(child.pid), "/T", "/F"], { stdio: "ignore" });
+      else child.kill("SIGTERM");
+    } catch { /* already exited */ }
+  }
+  activeChildren.clear();
+}
+
+/**
+ * Runs a classified, policy-checked command. Returns:
+ *   { ok:false, denied:true, reason }                      — refused outright
+ *   { ok, classification, exitCode, stdout, stderr }         — completed
+ *   { ok:true, classification:"networked", longRunning:true, pid } — dev server started
+ */
+export async function runCommand(cmd, args, { cwd, config = {}, approved = false, timeoutMs = 120_000, maxOutputChars } = {}) {
+  const { classification, allowed, reason } = classifyCommand(cmd, args);
+  if (!allowed) return { ok: false, denied: true, reason };
+
+  const { permitted, requiresApproval } = isPermitted(classification, config, { approved });
+  if (!permitted) {
+    return {
+      ok: false, denied: true, classification, requiresApproval,
+      reason: `'${cmd} ${args.join(" ")}' is classified as '${classification}' and requires explicit approval`,
+    };
+  }
+
+  const outCap = maxOutputChars ?? config.chat?.maxCommandOutputCharacters ?? 30_000;
+  let pc;
+  try { pc = platformCommand(cmd, args, { cwd }); }
+  catch (e) { return { ok: false, denied: true, classification, reason: e.message }; }
+
+  if (classification === "networked") {
+    return new Promise((resolve) => {
+      const child = spawn(pc.file, pc.args, { ...pc.options, stdio: ["ignore", "pipe", "pipe"] });
+      activeChildren.add(child);
+      let out = "";
+      child.stdout?.on("data", (d) => { out += d; });
+      child.stderr?.on("data", (d) => { out += d; });
+      child.on("exit", () => activeChildren.delete(child));
+      child.on("error", () => activeChildren.delete(child));
+      setTimeout(() => resolve({
+        ok: true, classification, longRunning: true, pid: child.pid,
+        initialOutput: redactSecrets(out.slice(0, outCap)),
+      }), 300);
+    });
+  }
+
+  return new Promise((resolve) => {
+    const child = execFile(pc.file, pc.args, { ...pc.options, timeout: timeoutMs, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+      activeChildren.delete(child);
+      resolve({
+        ok: !err, classification,
+        exitCode: err?.code ?? 0,
+        stdout: redactSecrets((stdout ?? "").toString().slice(0, outCap)),
+        stderr: redactSecrets((stderr ?? "").toString().slice(0, outCap)),
+        timedOut: !!(err?.killed && err?.signal === "SIGTERM"),
+      });
+    });
+    activeChildren.add(child);
+  });
+}

package/src/chat/commands.js

@@ -0,0 +1,275 @@
+/**
+ * commands.js — the slash-command table. Every handler calls the exact same
+ * core services cli.js uses — no duplicated business logic. Dependency
+ * injection (`deps`) keeps this testable without spawning a real CLI process.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { buildScoredGraph, getWorkflowSummaries, getRepoStatusSummary, buildTaskContext } from "../core/intelligence.js";
+import { resolveFile, traceFile, tracePath, renderTraceFile, renderTracePath } from "../core/trace.js";
+import { analyzeResolution, renderResolution } from "../core/resolution.js";
+import { saveBaseline, loadBaseline, diffGraphs, saveFindings } from "../core/regression.js";
+import { renderDocs } from "../core/docs.js";
+import { runModernizationScan, saveModernizationReport } from "../core/modernize.js";
+import { loadPkg } from "../core/graph.js";
+import { pending, loadQueueWithStates } from "../core/review.js";
+import { buildFindingEvidence, renderFindingEvidence } from "../core/evidence.js";
+import { buildHandoff, renderHandoffPrompt } from "../core/handoff.js";
+import { buildSolutions, narrateSolutions, renderSolutions } from "../core/solutions.js";
+import { buildDiagnosis, renderDiagnosis } from "../core/diagnose.js";
+import { explainScore, ceilingScore, deltaScore, renderExplain, renderCeiling, renderDelta } from "../core/score.js";
+import { analyzeTestCoverage, testGaps, testCredit, renderTestGaps, renderTestCredit } from "../core/testGuidance.js";
+import { planImprovements, renderImprovePlan } from "../core/improve.js";
+import { runVerify, renderVerify } from "../core/verify.js";
+import { exportTranscriptMarkdown } from "../core/session.js";
+import { bold, dim, red, green, yellow, cyan } from "../core/theme.js";
+
+const themeHelpers = { bold, dim, red, green, yellow, cyan };
+
+function formatMapSummary(g) {
+  const lines = [`files: ${g.stats.fileCount}  loc: ${g.stats.totalLoc}  workflows: ${g.workflows.length}`,
+    `call resolution: ${(g.stats.callResolutionRate * 100).toFixed(1)}%  repo confidence: ${g.repoConfidence}`];
+  for (const wf of g.workflows) lines.push(`  [${wf.confidence.score}] ${wf.id} (${wf.files.length} files)`);
+  if (g.orphans.length) lines.push(`orphans: ${g.orphans.join(", ")}`);
+  return lines.join("\n");
+}
+
+/**
+ * `deps`: { rootDir, config, session? }. Returns a table of
+ * `command -> async (args[]) -> { ok, text }`.
+ */
+export function createCommandTable(deps) {
+  const abs = path.resolve(deps.rootDir);
+
+  return {
+    "/map": async () => {
+      const g = buildScoredGraph(abs);
+      return { ok: true, text: formatMapSummary(g) };
+    },
+
+    "/baseline": async () => {
+      const g = buildScoredGraph(abs);
+      const p = saveBaseline(abs, g);
+      return { ok: true, text: `Baseline saved → ${p} (repo confidence ${g.repoConfidence})` };
+    },
+
+    "/check": async () => {
+      const loaded = loadBaseline(abs);
+      if (!loaded) return { ok: false, text: "No baseline found. Run /baseline first." };
+      if (loaded.schemaMismatch) return { ok: false, text: "Baseline schema mismatch — run /baseline to re-snapshot." };
+      const current = buildScoredGraph(abs);
+      const findings = diffGraphs(loaded.graph, current);
+      const saved = saveFindings(abs, findings);
+      const resolvedNote = saved.resolvedNow ? `\n${saved.resolvedNow} previously-open finding(s) auto-resolved — not reproduced by this re-check.` : "";
+      if (!findings.length) return { ok: true, text: `No regressions. Repo confidence ${loaded.graph.repoConfidence} → ${current.repoConfidence}.${resolvedNote}` };
+      return { ok: true, text: findings.map((f) => `[${f.severity.toUpperCase()}] ${f.kind}: ${f.detail}`).join("\n") + resolvedNote };
+    },
+
+    "/docs": async () => {
+      const g = buildScoredGraph(abs);
+      const md = await renderDocs(g, { withNarration: false });
+      const out = path.join(abs, "MAP.md");
+      fs.writeFileSync(out, md);
+      return { ok: true, text: `Docs → ${out}` };
+    },
+
+    "/modernize": async (args = []) => {
+      const mode = ["light", "medium", "heavy"].includes(args[0]) ? args[0] : "medium";
+      const g = buildScoredGraph(abs);
+      const report = runModernizationScan(abs, g, loadPkg(abs), mode);
+      const freshCount = report.findings.length; // before the save merges in carried lifecycle entries
+      const saved = saveModernizationReport(abs, report);
+      const resolvedNote = saved.resolvedNow ? ` ${saved.resolvedNow} previously-open finding(s) auto-resolved.` : "";
+      return { ok: true, text: `${freshCount} modernization finding(s) (${mode} mode).${resolvedNote}` };
+    },
+
+    "/review": async () => {
+      const { items, freshness } = loadQueueWithStates(abs);
+      const open = pending(items);
+      if (!open.length) return { ok: true, text: "Queue is empty — nothing awaiting approval." };
+      const lines = open.map((i) => `${i.id}  [${i.source}] (${i.state}) ${i.kind}: ${i.detail}`);
+      if (freshness.stale && open.some((i) => i.state === "stale")) {
+        lines.push(`\n⚠ items marked (stale) come from ${freshness.staleReports.join(", ")}, which predate a newer source change — refresh with /check or /modernize before acting.`);
+      }
+      return { ok: true, text: lines.join("\n") };
+    },
+
+    "/findings": async () => {
+      const { items, freshness } = loadQueueWithStates(abs);
+      const open = pending(items).filter((i) => i.source === "check" || i.source.startsWith("modernize-"));
+      if (!open.length) return { ok: true, text: "No open findings." };
+      const lines = open.map((i) => `${i.id}  [${i.source}] (${i.state}) ${i.kind}: ${i.detail}`);
+      if (freshness.stale && open.some((i) => i.state === "stale")) {
+        lines.push(`\n⚠ items marked (stale) come from ${freshness.staleReports.join(", ")}, which predate a newer source change — refresh with /check or /modernize before acting.`);
+      }
+      return { ok: true, text: lines.join("\n") };
+    },
+
+    "/evidence": async (args = []) => {
+      const id = args[0];
+      if (!id) return { ok: false, text: "Usage: /evidence <finding-id> — list IDs with /findings or /review." };
+      const data = buildFindingEvidence(abs, id);
+      if (!data) return { ok: false, text: `No item with ID ${id}. List current IDs with /review.` };
+      return { ok: true, text: renderFindingEvidence(data) };
+    },
+
+    "/project": async () => {
+      const g = buildScoredGraph(abs);
+      const summary = getRepoStatusSummary(g);
+      return {
+        ok: true,
+        text: `root: ${abs}\nfiles: ${summary.fileCount}  workflows: ${summary.workflowCount}  confidence: ${summary.repoConfidence}\nworkflows:\n` +
+          getWorkflowSummaries(g).map((w) => `  [${w.confidence}] ${w.id} (${w.fileCount} files)`).join("\n"),
+      };
+    },
+
+    "/context": async () => {
+      const session = deps.session;
+      if (!session) return { ok: true, text: "No active session." };
+      const lines = [
+        `${session.turns.length} turn(s) in this session.`,
+        `files inspected: ${session.filesInspected.size ? [...session.filesInspected].join(", ") : "none yet"}`,
+        `findings discussed: ${session.findingsDiscussed.size ? [...session.findingsDiscussed].join(", ") : "none yet"}`,
+        `commands executed: ${session.commandsExecuted.length ? session.commandsExecuted.map((c) => c.label).join(", ") : "none yet"}`,
+        `patches proposed: ${session.patchesProposed.length ? session.patchesProposed.map((p) => `${p.id} (${p.status})`).join(", ") : "none yet"}`,
+        `patches applied: ${session.patchesApplied.length ? session.patchesApplied.map((p) => p.id).join(", ") : "none yet"}`,
+      ];
+      return { ok: true, text: lines.join("\n") };
+    },
+
+    "/status": async () => {
+      const g = buildScoredGraph(abs);
+      const loaded = loadBaseline(abs);
+      const { items } = loadQueueWithStates(abs);
+      const open = pending(items);
+      const staleCount = open.filter((i) => i.state === "stale").length;
+      // ceiling-awareness: chat should proactively disclose the honest maximum,
+      // never let a reader assume 1.0 is reachable when it structurally isn't.
+      const ceiling = ceilingScore(abs, g);
+      const ceilingNote = ceiling.ceilingSignalCoverage < 1
+        ? ` — 1.0 is not honestly reachable (signalCoverage caps at ${ceiling.ceilingSignalCoverage}: ${ceiling.caps.map((c) => c.cap).join(", ")})`
+        : "";
+      return {
+        ok: true,
+        text: `repo confidence: ${g.repoConfidence} (honest ceiling ${ceiling.ceiling}${ceilingNote})\nbaseline: ${loaded ? (loaded.schemaMismatch ? "schema mismatch — re-run /baseline" : "present") : "none"}\nopen findings: ${open.length}${staleCount ? ` (${staleCount} from stale report(s) — refresh with /check or /modernize)` : ""}\ntip: /improve for a ranked plan, /score explain for the breakdown`,
+      };
+    },
+
+    "/score": async (args = []) => {
+      const sub = (args[0] || "explain").toLowerCase();
+      const g = buildScoredGraph(abs);
+      if (sub === "ceiling") return { ok: true, text: renderCeiling(ceilingScore(abs, g)) };
+      if (sub === "delta") {
+        const loaded = loadBaseline(abs);
+        if (!loaded) return { ok: false, text: "No baseline found. Run /baseline first." };
+        if (loaded.schemaMismatch) return { ok: false, text: "Baseline schema mismatch — run /baseline to re-snapshot." };
+        return { ok: true, text: renderDelta(deltaScore(loaded.graph, g)) };
+      }
+      return { ok: true, text: renderExplain(explainScore(g), { workflow: sub !== "explain" ? args[0] : undefined }) };
+    },
+
+    "/ceiling": async () => {
+      const g = buildScoredGraph(abs);
+      return { ok: true, text: renderCeiling(ceilingScore(abs, g)) };
+    },
+
+    "/test-gaps": async (args = []) => {
+      const analysis = analyzeTestCoverage(abs, buildScoredGraph(abs));
+      const gaps = testGaps(analysis, { includeShallow: args.includes("--shallow") });
+      return { ok: true, text: renderTestGaps(analysis, gaps, themeHelpers) };
+    },
+
+    "/test-credit": async (args = []) => {
+      const paddingOnly = args.includes("--padding");
+      const analysis = analyzeTestCoverage(abs, buildScoredGraph(abs));
+      return { ok: true, text: renderTestCredit(testCredit(analysis, { paddingOnly }), themeHelpers, { paddingOnly }) };
+    },
+
+    "/improve": async (args = []) => {
+      let budget, risk = "low";
+      for (let i = 0; i < args.length; i++) {
+        if (args[i] === "--budget") budget = args[++i];
+        else if (args[i] === "--risk") risk = args[++i];
+      }
+      return { ok: true, text: renderImprovePlan(planImprovements(abs, { budget, risk })) };
+    },
+
+    "/verify": async (args = []) => {
+      return { ok: true, text: renderVerify(runVerify(abs, { strict: args.includes("--strict") })) };
+    },
+
+    "/transcript": async (args = []) => {
+      const session = deps.session;
+      if (!session) return { ok: false, text: "No active session to save." };
+      const md = exportTranscriptMarkdown(session);
+      const out = args[0] ? path.resolve(abs, args[0]) : path.join(abs, ".mapd", "sessions", `${session.id}.md`);
+      fs.mkdirSync(path.dirname(out), { recursive: true });
+      fs.writeFileSync(out, md);
+      return { ok: true, text: `Transcript (${session.turns.length} turn(s)) → ${out}` };
+    },
+
+    "/diagnose": async (args = []) => {
+      const top = Number.parseInt(args[0], 10) || 5;
+      return { ok: true, text: renderDiagnosis(buildDiagnosis(abs, { top })) };
+    },
+
+    "/handoff": async (args = []) => {
+      const top = Number.parseInt(args[0], 10) || 5;
+      const data = buildHandoff(abs, { top });
+      return { ok: true, text: renderHandoffPrompt(data) };
+    },
+
+    "/solutions": async (args = []) => {
+      const top = Number.parseInt(args[0], 10) || 5;
+      let data = buildSolutions(abs, { top });
+      // chat already has a provider in hand when one's configured — narrate
+      // automatically here, unlike the CLI's opt-in --narrate (no surprise
+      // network calls from a scripted `mapd solutions` invocation).
+      if (deps.provider) data = await narrateSolutions(data, deps.provider, { graph: buildScoredGraph(abs) });
+      return { ok: true, text: renderSolutions(data) };
+    },
+
+    "/trace": async (args = []) => {
+      const [fileArg, toArg] = args;
+      if (!fileArg) return { ok: false, text: "Usage: /trace <file> [to-file] — explain why a file is in/out of a workflow, or the chain connecting two files." };
+      const g = buildScoredGraph(abs);
+      const from = resolveFile(g, fileArg);
+      if (from.notFound) return { ok: false, text: `No file matching "${fileArg}". List files with /map.` };
+      if (from.ambiguous) return { ok: false, text: `"${fileArg}" is ambiguous — matches: ${from.ambiguous.join(", ")}` };
+      if (toArg) {
+        const target = resolveFile(g, toArg);
+        if (target.notFound) return { ok: false, text: `No file matching "${toArg}".` };
+        if (target.ambiguous) return { ok: false, text: `"${toArg}" is ambiguous — matches: ${target.ambiguous.join(", ")}` };
+        return { ok: true, text: renderTracePath(tracePath(g, from.file, target.file), themeHelpers) };
+      }
+      return { ok: true, text: renderTraceFile(traceFile(g, from.file), themeHelpers) };
+    },
+
+    "/resolution": async (args = []) => {
+      const top = Number.parseInt(args[0], 10) || 10;
+      const g = buildScoredGraph(abs);
+      return { ok: true, text: renderResolution(analyzeResolution(g, { top }), themeHelpers) };
+    },
+
+    "/find": async (args = []) => {
+      const query = args.join(" ").trim();
+      if (!query) return { ok: false, text: "Usage: /find <query> — ranked symbol/file hits for a task or question." };
+      const g = buildScoredGraph(abs);
+      const data = buildTaskContext(g, query, { maxHits: 8, maxFiles: 8 });
+      if (!data.hits.length && !data.files.length) return { ok: true, text: `No symbol or file matches for "${query}".` };
+      const lines = [];
+      if (data.hits.length) lines.push("Top hits:", ...data.hits.map((h) => `  ${h.file}#${h.function}  (score ${h.score})`));
+      if (data.files.length) lines.push("Relevant files:", ...data.files.map((f) => `  ${f.file}  (${f.loc} LOC)`));
+      if (data.workflows.length) lines.push("Matched workflows:", ...data.workflows.map((w) => `  ${w.id}`));
+      return { ok: true, text: lines.join("\n") };
+    },
+
+    "/help": async () => ({
+      ok: true,
+      text: "Slash commands: /map /baseline /check /docs /modernize /review /findings /evidence <id> /project /context /status /diagnose /handoff /solutions\n" +
+        "  /score [explain|ceiling|delta] /ceiling /trace <file> [to] /resolution /find <query> /test-gaps /test-credit [--padding] /improve [--budget 2h --risk low] /verify [--strict] /transcript [file] /help /clear /end\n" +
+        "Natural language also works: \"what's the honest ceiling\", \"what should I work on\", \"show test gaps\", \"is the project passing\", \"trace <file>\", \"what's dragging down the resolution rate\", \"find code related to <topic>\", \"approve finding <id>\", \"fix the highest-severity finding\".",
+    }),
+  };
+}