@dev-tren/mapd 0.21.0

package/src/core/improve.js

@@ -0,0 +1,226 @@
+/**
+ * improve.js — the planner. `mapd improve --budget 2h --risk low`.
+ *
+ * Turns the scored graph into a ranked, honest work queue: every candidate task
+ * is a real deficiency in a real signal, its expected lift is measured by
+ * re-running the actual scorer (simulateScore — never a guess), and each task
+ * carries what NOT to fake so the plan can't be satisfied deceptively. It also
+ * states the honest ceiling up front, so it never implies 1.0 is reachable when
+ * it isn't.
+ *
+ * It proposes; it never edits. The verification block tells you how to prove the
+ * work landed.
+ */
+
+import { buildScoredGraph } from "./intelligence.js";
+import { simulateScore, ceilingScore } from "./score.js";
+import { classifyTestCredit } from "./testGuidance.js";
+import { bold, dim, red, green, yellow, cyan, confidenceColor } from "./theme.js";
+
+const RISK_RANK = { low: 1, medium: 2, high: 3 };
+
+/** "2h" | "90m" | "120" → minutes. Missing/unparseable → Infinity (no cap). */
+export function parseBudget(b) {
+  if (b == null) return Infinity;
+  const m = String(b).trim().match(/^(\d+(?:\.\d+)?)\s*(h|hr|hrs|hour|hours|m|min|mins|minute|minutes)?$/i);
+  if (!m) return Infinity;
+  const n = parseFloat(m[1]);
+  return (m[2] || "m").toLowerCase().startsWith("h") ? n * 60 : n;
+}
+
+const fmtEffort = (min) => min >= 60 ? `~${Math.floor(min / 60)}h${min % 60 ? `${Math.round(min % 60)}m` : ""}` : `~${Math.round(min)}m`;
+
+/** Generate every candidate task from real graph deficiencies, each with a measured marginal lift. */
+function candidates(rootDir, graph) {
+  const out = [];
+  const wfOf = (file) => graph.workflows.filter((w) => w.files.includes(file)).map((w) => w.id);
+  const lift = (mutations) => simulateScore(rootDir, graph, mutations).delta;
+
+  const credit = classifyTestCredit(graph).filter((s) => s.inWorkflow);
+
+  // 1. untested workflow files → write a real test
+  for (const s of credit.filter((c) => c.status === "untested")) {
+    out.push({
+      kind: "add-test", files: [s.file], signal: "testPresence", risk: "low",
+      title: `Add a real test for ${s.file}`,
+      why: `untested file in ${wfOf(s.file).join(", ") || "a workflow"}`,
+      doStep: `import ${s.file} and exercise ${s.exportCount ? `its ${s.exportCount} export(s)` : "its behavior"}`,
+      dontFake: "an empty or import-only test earns nothing — testPresence now credits only tests that import the module and use its exports",
+      workflows: wfOf(s.file), effortMin: 15 + 5 * Math.min(s.exportCount, 5),
+      lift: lift({ addTests: [s.file] }),
+    });
+  }
+
+  // 2. name-only padding → replace the fake test with a real one
+  for (const s of credit.filter((c) => c.status === "tested-nameonly")) {
+    out.push({
+      kind: "replace-padding", files: [s.file], signal: "testPresence", risk: "low",
+      title: `Replace padding test for ${s.file}`,
+      why: `credited only by filename coincidence (${s.credits.map((c) => c.test).join(", ")}) — earns nothing today`,
+      doStep: `make the existing test actually import ${s.file} and assert on its exports`,
+      dontFake: "this file already LOOKS tested; the honest move is a real test, not a more convincing-looking fake",
+      workflows: wfOf(s.file), effortMin: 20,
+      lift: lift({ addTests: [s.file] }),
+    });
+  }
+
+  // 3. AST parse errors in workflow files → fix them
+  const astErr = graph.files.filter((f) => f.parserKind !== "heuristic" && f.parsed && f.parseErrors > 0 && wfOf(f.file).length);
+  for (const f of astErr) {
+    out.push({
+      kind: "fix-parse", files: [f.file], signal: "parseIntegrity", risk: "medium",
+      title: `Fix parse recovery errors in ${f.file}`,
+      why: `${f.parseErrors} parse error(s) reduce parseIntegrity for ${wfOf(f.file).join(", ")}`,
+      doStep: "resolve the syntax the parser recovered from (unsupported syntax, missing config)",
+      dontFake: "excluding the file to hide the error lowers coverage instead — fix the parse, don't mask it",
+      workflows: wfOf(f.file), effortMin: 15,
+      lift: lift({ fixParse: [f.file] }),
+    });
+  }
+
+  // 4. call resolution — one aggregate task (can't attribute per call site here)
+  const unresolved = (graph.stats.totalCalls ?? 0) - (graph.stats.resolvedCalls ?? 0);
+  if (unresolved > 0 && (graph.stats.callResolutionRate ?? 1) < 0.999) {
+    out.push({
+      kind: "resolve-calls", files: [], signal: "resolutionRate", risk: "medium",
+      title: `Resolve ${unresolved} unresolved call site(s)`,
+      why: `call resolution is ${(graph.stats.callResolutionRate * 100).toFixed(1)}% — dynamic dispatch / anonymous functions hide edges`,
+      doStep: "name anonymous functions and make dynamic require()/import() static where safe",
+      dontFake: "some calls into external packages genuinely can't resolve — don't force those; leave them and note it",
+      workflows: [], effortMin: Math.min(unresolved * 10, 240),
+      lift: lift({ resolutionRate: 1 }),
+    });
+  }
+
+  // 5. orphans → wire the top few into a workflow (coverage)
+  const allFiles = graph.files.length || 1;
+  const coveredNow = new Set(graph.workflows.flatMap((w) => w.files)).size;
+  (graph.orphans ?? []).slice(0, 5).forEach((file, i) => {
+    out.push({
+      kind: "wire-coverage", files: [file], signal: "coverageOfRepo", risk: "medium",
+      title: `Reach ${file} from a workflow`,
+      why: "orphan file reached by no entry point — lowers coverageOfRepo",
+      doStep: "import it from a reachable module, or confirm it is truly dead code",
+      dontFake: "if it is intentionally dormant, annotate it `intentional-dormant` — do NOT wire dead code in just to lift coverage",
+      workflows: [], effortMin: 15,
+      lift: lift({ coverageOfRepo: (coveredNow + i + 1) / allFiles }),
+    });
+  });
+
+  return out;
+}
+
+/**
+ * Build a budget- and risk-bounded plan. Ranks by lift-per-effort, greedily
+ * fills the budget, then measures the COMBINED projected score by simulating all
+ * selected tasks at once (so the headline number isn't a sum of rounded parts).
+ */
+export function planImprovements(rootDir, { budget, risk = "low" } = {}) {
+  const graph = buildScoredGraph(rootDir);
+  const budgetMin = parseBudget(budget);
+  const riskCap = RISK_RANK[risk] ?? RISK_RANK.low;
+
+  const eligible = candidates(rootDir, graph)
+    .filter((c) => RISK_RANK[c.risk] <= riskCap && c.lift > 0)
+    .sort((a, b) => (b.lift / b.effortMin) - (a.lift / a.effortMin) || b.lift - a.lift);
+
+  const selected = [];
+  let spent = 0;
+  for (const c of eligible) {
+    if (spent + c.effortMin > budgetMin) continue;
+    selected.push(c);
+    spent += c.effortMin;
+  }
+
+  // combined projection — merge every selected task's mutation and simulate once
+  const merged = { addTests: [], fixParse: [], coverageOfRepo: undefined, resolutionRate: undefined };
+  for (const c of selected) {
+    if (c.kind === "add-test" || c.kind === "replace-padding") merged.addTests.push(...c.files);
+    if (c.kind === "fix-parse") merged.fixParse.push(...c.files);
+    if (c.kind === "resolve-calls") merged.resolutionRate = 1;
+    if (c.kind === "wire-coverage") {
+      const coveredNow = new Set(graph.workflows.flatMap((w) => w.files)).size;
+      const wired = selected.filter((s) => s.kind === "wire-coverage").length;
+      merged.coverageOfRepo = (coveredNow + wired) / (graph.files.length || 1);
+    }
+  }
+  const projection = simulateScore(rootDir, graph, merged);
+  const ceiling = ceilingScore(rootDir, graph);
+
+  const doNotDo = [];
+  const padding = classifyTestCredit(graph).filter((c) => c.inWorkflow && c.status === "tested-nameonly");
+  if (padding.length) doNotDo.push(`${padding.length} name-only padding test(s) already earn nothing — replacing them is real work; making them look more like tests is not.`);
+  doNotDo.push("Don't create empty or import-only test files to move testPresence — Map'd credits only real/shallow test links now.");
+  if ((graph.orphans ?? []).length) doNotDo.push("Don't wire intentionally-dormant files into a workflow to lift coverage — annotate them `intentional-dormant` instead.");
+  if (ceiling.ceilingSignalCoverage < 1) doNotDo.push(`1.0 is not honestly reachable: even maxed, signalCoverage caps at ${ceiling.ceilingSignalCoverage} (${ceiling.caps.map((c) => c.cap).join(", ")}).`);
+
+  return {
+    budget: budgetMin === Infinity ? "unbounded" : fmtEffort(budgetMin),
+    risk,
+    current: graph.repoConfidence,
+    projected: projection.after,
+    totalLift: projection.delta,
+    effortMin: spent,
+    ceiling: { value: ceiling.ceiling, signalCoverage: ceiling.ceilingSignalCoverage },
+    tasks: selected,
+    deferred: eligible.length - selected.length,
+    doNotDo,
+    verify: ["mapd check --save-baseline   # once, to set the honest reference before you start", "# …do the work…", "mapd check   # or ask `mapd chat`: \"why did the score change\""],
+  };
+}
+
+/** A compact, paste-ready task pack for Codex / Claude Code — exact files, risk, expected lift, and what not to fake. */
+export function renderAgentPack(plan) {
+  const lines = [
+    "# Map'd improvement task pack",
+    "",
+    `Repo confidence **${plan.current} → target ${plan.projected}** (+${plan.totalLift}) within ${plan.budget}, risk ≤ ${plan.risk}. Honest ceiling ${plan.ceiling.value} (signalCoverage ${plan.ceiling.signalCoverage}).`,
+    "Do the tasks in order. Every lift below is measured by Map'd's real scorer — do not fake signals to hit the number.",
+    "",
+    "## Tasks",
+    "",
+  ];
+  if (!plan.tasks.length) lines.push("_No tasks fit this budget/risk with a positive score lift._", "");
+  plan.tasks.forEach((t, i) => {
+    lines.push(`### ${i + 1}. ${t.title}  \`[risk: ${t.risk} · expected +${t.lift}]\``);
+    lines.push(`- **Files:** ${t.files.length ? t.files.map((f) => `\`${f}\``).join(", ") : "(project-wide)"}`);
+    lines.push(`- **Why it matters:** ${t.why} (signal: ${t.signal})`);
+    lines.push(`- **Do:** ${t.doStep}`);
+    lines.push(`- **Do NOT fake:** ${t.dontFake}`);
+    if (t.workflows?.length) lines.push(`- **Workflows touched:** ${t.workflows.join(", ")}`);
+    lines.push("");
+  });
+  lines.push("## Do not do", "");
+  for (const d of plan.doNotDo) lines.push(`- ${d}`);
+  lines.push("", "## Verify when done", "", "```");
+  for (const v of plan.verify) lines.push(v);
+  lines.push("```");
+  return lines.join("\n");
+}
+
+export function renderImprovePlan(plan) {
+  const lines = [`\n${bold("Improve plan")} — budget ${plan.budget}, risk ${plan.risk}`];
+  lines.push(`  ${confidenceColor(plan.current)(plan.current)}  →  projected ${confidenceColor(plan.projected)(plan.projected)}  ${green(`+${plan.totalLift}`)} ${dim(`from ${plan.tasks.length} task(s), ${fmtEffort(plan.effortMin)}`)}`);
+  lines.push(`  ceiling ${confidenceColor(plan.ceiling.value)(plan.ceiling.value)} ${dim(`(signalCoverage ${plan.ceiling.signalCoverage})`)}`);
+
+  if (!plan.tasks.length) {
+    lines.push(green("\n  Nothing fits this budget/risk with a positive score lift."));
+  } else {
+    lines.push(`\n${bold("  Ranked tasks")} ${dim("(best lift per effort first)")}`);
+    plan.tasks.forEach((t, i) => {
+      const rc = t.risk === "low" ? green : t.risk === "medium" ? yellow : red;
+      lines.push(`\n  ${bold(`${i + 1}.`)} ${rc(`[${t.risk} · ${fmtEffort(t.effortMin)} · +${t.lift}]`)} ${t.title}`);
+      lines.push(dim(`       why:  ${t.why}`));
+      lines.push(dim(`       do:   ${t.doStep}`));
+      lines.push(`       ${red("don't fake:")} ${dim(t.dontFake)}`);
+    });
+  }
+  if (plan.deferred) lines.push(dim(`\n  ${plan.deferred} more eligible task(s) didn't fit the budget.`));
+
+  lines.push(`\n${bold("  Do not do")} ${dim("(score-chasing / deceptive)")}`);
+  for (const d of plan.doNotDo) lines.push(`   ${yellow("▪")} ${d}`);
+
+  lines.push(`\n${bold("  Verify")}`);
+  for (const v of plan.verify) lines.push(`   ${cyan(v)}`);
+  return lines.join("\n");
+}

package/src/core/integrate.js

@@ -0,0 +1,169 @@
+/**
+ * integrate.js — Function 1: integration / congruence resolution.
+ *
+ * Pipeline (LLM optional, verification mandatory):
+ *   1. DETECT     — attempt the merge in an isolated git worktree; collect
+ *                   conflicted files with base/ours/theirs content. Deterministic.
+ *   2. CLASSIFY   — parse ours & theirs; compare function sets and exported
+ *                   surface to label each conflict:
+ *                     "small-scale"    same functions, bodies diverged
+ *                     "workflow-scale" exports / function topology diverged
+ *                   Deterministic (this drives Devon's small-vs-POC routing).
+ *   3. PROPOSE    — (optional, needs API key) LLM drafts a merged file per
+ *                   conflict, receiving both sides + classification.
+ *   4. VERIFY     — every proposal must pass hard deterministic gates before
+ *                   it is even *saved as a proposal*:
+ *                     G1 parses cleanly (zero recovery errors)
+ *                     G2 preserves the UNION of both parents' exports
+ *                     G3 preserves the union of top-level function names
+ *                   A gate failure downgrades the proposal to "rejected-by-gate"
+ *                   with the failed gate named — it is never silently dropped.
+ *   5. APPLY      — only via explicit `mapd integrate --apply`, and only
+ *                   proposals whose derived score ≥ threshold. Default: never.
+ *
+ * Derived resolution score (per proposal — computed, not asserted):
+ *   gatePassRate (0.5)  fraction of gates passed
+ *   testPresence (0.3)  does the conflicted file have a matching test file
+ *   scaleFactor  (0.2)  small-scale=1.0, workflow-scale=0.4 (structural merges
+ *                       are inherently riskier; constant is a policy knob, not
+ *                       a guess about *this* merge)
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { parseSource, runStandardGates } from "./gates.js";
+import { applyRealTreeWrite } from "./changes.js";
+
+/** All git invocations use argument arrays — no shell, no interpolation, no injection. */
+function git(cwd, ...args) {
+  return execFileSync("git", args, { cwd, stdio: ["ignore", "pipe", "pipe"] }).toString();
+}
+
+/** Step 1+2: detect conflicts merging `branch` into HEAD, classify each. Deterministic. */
+export function detectConflicts(rootDir, branch) {
+  const abs = path.resolve(rootDir);
+  // integrate is inherently git-native (it merges in an isolated worktree). If
+  // this project isn't a git repo, say so cleanly instead of letting a raw
+  // `fatal: not a git repository` escape — the rest of Map'd degrades
+  // gracefully without git, and so must this.
+  try { git(abs, "rev-parse", "--git-dir"); }
+  catch { return { mergeable: false, conflicts: [], requiresGit: true }; }
+  const worktree = fs.mkdtempSync(path.join(os.tmpdir(), "mapd-merge-"));
+  const conflicts = [];
+  let mergeable = true;
+
+  try {
+    const head = git(abs, "rev-parse", "--abbrev-ref", "HEAD").trim();
+    git(abs, "worktree", "add", "--detach", worktree, head);
+    try {
+      git(worktree, "-c", "user.email=mapd@local", "-c", "user.name=mapd", "merge", "--no-commit", "--no-ff", branch);
+      // clean merge — nothing to resolve
+    } catch (e) {
+      const status = git(worktree, "status", "--porcelain");
+      const conflictedFiles = status.split("\n")
+        .filter((l) => /^(UU|AA|DU|UD|AU|UA) /.test(l))
+        .map((l) => l.slice(3).trim());
+      if (conflictedFiles.length === 0) {
+        // merge failed for a non-conflict reason — surface it, don't fabricate a clean/empty result
+        return { mergeable: false, conflicts: [], mergeError: (e.stderr ?? e.message ?? "").toString().trim() };
+      }
+      mergeable = false;
+
+      for (const file of conflictedFiles) {
+        const show = (ref) => {
+          try { return git(worktree, "show", `${ref}:${file}`); } catch { return null; }
+        };
+        const base = show(":1"), ours = show(":2"), theirs = show(":3");
+        const conflict = { file, base, ours, theirs, classification: "unknown" };
+
+        if (ours != null && theirs != null && /\.(js|ts|jsx|tsx|mjs|cjs)$/.test(file)) {
+          const po = parseSource(ours, `${file}@ours`);
+          const pt = parseSource(theirs, `${file}@theirs`);
+          if (po.parsed && pt.parsed) {
+            const fo = new Set(po.functions.map((f) => f.name));
+            const ft = new Set(pt.functions.map((f) => f.name));
+            const eo = new Set(po.exports), et = new Set(pt.exports);
+            const sameFns = fo.size === ft.size && [...fo].every((n) => ft.has(n));
+            const sameExports = eo.size === et.size && [...eo].every((n) => et.has(n));
+            conflict.classification = sameFns && sameExports ? "small-scale" : "workflow-scale";
+            conflict.evidence = {
+              oursFns: [...fo].sort(), theirsFns: [...ft].sort(),
+              oursExports: [...eo].sort(), theirsExports: [...et].sort(),
+            };
+            // union targets for verification gates
+            conflict.requiredExports = [...new Set([...eo, ...et])].sort();
+            conflict.requiredFunctions = [...new Set([...fo, ...ft])].sort();
+          } else {
+            conflict.classification = "unparseable-side";
+          }
+        } else if (ours == null || theirs == null) {
+          conflict.classification = "delete-modify"; // one side deleted — always workflow-scale severity
+        }
+        conflicts.push(conflict);
+      }
+      try { git(worktree, "merge", "--abort"); } catch { /* detached worktree, discarded anyway */ }
+    }
+  } finally {
+    try { git(abs, "worktree", "remove", "--force", worktree); } catch { /* best effort */ }
+    fs.rmSync(worktree, { recursive: true, force: true });
+  }
+  return { mergeable, conflicts };
+}
+
+/** Step 4: hard deterministic gates on a proposed merged source. Delegates to gates.js. */
+export function verifyProposal(conflict, mergedSource) {
+  return runStandardGates({
+    source: mergedSource,
+    label: `${conflict.file}@proposed`,
+    requiredExports: conflict.requiredExports,
+    requiredFunctions: conflict.requiredFunctions,
+  });
+}
+
+/** Derived resolution score. Every input measurable; policy constants documented above. */
+export function scoreResolution(conflict, gates, hasTest) {
+  const gatePassRate = gates.length ? gates.filter((g) => g.passed).length / gates.length : 0;
+  const scaleFactor = conflict.classification === "small-scale" ? 1.0
+    : conflict.classification === "workflow-scale" ? 0.4 : 0.2;
+  const signals = {
+    gatePassRate: { value: Number(gatePassRate.toFixed(3)), weight: 0.5 },
+    testPresence: { value: hasTest ? 1 : 0, weight: 0.3 },
+    scaleFactor: { value: scaleFactor, weight: 0.2 },
+  };
+  const score = Object.values(signals).reduce((a, s) => a + s.value * s.weight, 0);
+  return { score: Number(score.toFixed(3)), signals, method: "resolution-composite-v1" };
+}
+
+export function saveIntegrationReport(rootDir, branch, report) {
+  const dir = path.join(rootDir, ".mapd", "integration");
+  fs.mkdirSync(dir, { recursive: true });
+  const p = path.join(dir, `report-${branch.replace(/[^\w.-]/g, "_")}.json`);
+  fs.writeFileSync(p, JSON.stringify(report, null, 2));
+  // proposals as reviewable files next to the report
+  for (const c of report.conflicts) {
+    if (c.proposal?.mergedSource && c.proposal.status === "awaiting-approval") {
+      const pf = path.join(dir, c.file.replace(/[\\/]/g, "__") + ".proposed");
+      fs.writeFileSync(pf, c.proposal.mergedSource);
+      c.proposal.proposalFile = pf;
+    }
+  }
+  fs.writeFileSync(p, JSON.stringify(report, null, 2));
+  return p;
+}
+
+/** Step 5: apply approved proposals above threshold. Explicit opt-in only. */
+export function applyProposals(rootDir, report, threshold) {
+  const applied = [], skipped = [];
+  for (const c of report.conflicts) {
+    const pr = c.proposal;
+    if (pr?.status === "awaiting-approval" && pr.resolutionScore?.score >= threshold && pr.mergedSource) {
+      const change = applyRealTreeWrite(rootDir, c.file, pr.mergedSource, "integrate");
+      applied.push({ file: c.file, score: pr.resolutionScore.score, changeId: change.id });
+    } else {
+      skipped.push({ file: c.file, score: pr?.resolutionScore?.score ?? null, reason: pr ? "below threshold or gated" : "no proposal" });
+    }
+  }
+  return { applied, skipped };
+}

package/src/core/intelligence.js

@@ -0,0 +1,212 @@
+/**
+ * intelligence.js — the single source of truth for "build me a scored map of
+ * this project," shared by cli.js, chat/, mcp/, and fix.js. Extracted
+ * verbatim from cli.js's original inline `buildScoredGraph` helper so every
+ * consumer sees identical results from identical inputs.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseProject, ALWAYS_IGNORE } from "./parser.js";
+import { buildGraph, loadPkg } from "./graph.js";
+import { scoreGraph } from "./confidence.js";
+import { traceFile } from "./trace.js";
+import { loadConfig } from "../config/index.js";
+import { loadPersistentParseCache, savePersistentParseCache } from "./parseCache.js";
+
+export function buildScoredGraph(rootDir, { cache } = {}) {
+  const abs = path.resolve(rootDir);
+  if (!fs.existsSync(abs)) throw new Error(`project root does not exist: ${abs}`);
+  if (!fs.statSync(abs).isDirectory()) throw new Error(`project root is not a directory: ${abs}`);
+  const config = loadConfig(abs);
+  const parseCache = cache ?? (config.mapping?.cache === false ? null : loadPersistentParseCache(abs, config));
+  const parsed = parseProject(abs, {
+    cache: parseCache,
+    // Normal Map'd surfaces are governed by .mapdrc project.include/exclude.
+    // The low-level parser still keeps its historical defaults for direct
+    // callers/tests that do not go through buildScoredGraph.
+    ignore: ALWAYS_IGNORE,
+    include: config.project?.include ?? [],
+    exclude: config.project?.exclude ?? [],
+    maxFileSizeBytes: config.mapping?.maxFileSizeBytes ?? Infinity,
+    polyglot: config.mapping?.polyglot !== false,
+  });
+  if (!cache && config.mapping?.cache !== false) savePersistentParseCache(abs, config, parseCache);
+  // .mapdrc project.annotations: user-asserted generated/dynamically-loaded
+  // classifications flow into reachability through here, so every consumer
+  // (cli/chat/mcp/handoff/solutions) sees them without extra plumbing.
+  const annotations = config.project?.annotations ?? {};
+  const graph = buildGraph(abs, parsed, loadPkg(abs), { annotations });
+  return scoreGraph(abs, graph);
+}
+
+export function findFileNode(graph, relFile) {
+  return graph.files.find((f) => f.file === relFile) ?? null;
+}
+
+/** Keyword-overlap search over function names/files — used by retrieval and chat. */
+export function searchFunctions(graph, query) {
+  const terms = tokenize(query);
+  const phrase = String(query ?? "").toLowerCase().trim();
+  if (!terms.length) return [];
+
+  const workflowIdsByFile = new Map();
+  for (const wf of graph.workflows ?? []) {
+    for (const file of wf.files) {
+      if (!workflowIdsByFile.has(file)) workflowIdsByFile.set(file, []);
+      workflowIdsByFile.get(file).push(wf.id);
+    }
+  }
+
+  const hits = [];
+  for (const file of graph.files) {
+    const fileWorkflows = workflowIdsByFile.get(file.file) ?? [];
+    const fileFields = [
+      { text: file.file, weight: 5, label: "file" },
+      { text: path.posix.basename(file.file), weight: 5, label: "basename" },
+      { text: (file.exports ?? []).join(" "), weight: 4, label: "exports" },
+      { text: (file.imports ?? []).flatMap((i) => [i.source, ...(i.names ?? [])]).join(" "), weight: 2, label: "imports" },
+      { text: fileWorkflows.join(" "), weight: 2, label: "workflow" },
+    ];
+    for (const fn of file.functions) {
+      const fields = [
+        { text: fn.name, weight: 7, label: "function" },
+        { text: fn.exported ? "export exported public api" : "", weight: 1, label: "exported" },
+        { text: (fn.calls ?? []).join(" "), weight: 3, label: "calls" },
+        ...fileFields,
+      ];
+      const scored = scoreFields(fields, terms, phrase);
+      if (scored.score > 0) {
+        hits.push({
+          file: file.file,
+          function: fn.name,
+          score: scored.score,
+          exported: fn.exported,
+          loc: fn.loc,
+          workflows: fileWorkflows,
+          matches: scored.matches,
+        });
+      }
+    }
+  }
+  return hits.sort((a, b) => b.score - a.score);
+}
+
+function tokenize(text) {
+  return String(text ?? "")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .toLowerCase()
+    .split(/[^a-z0-9_#./-]+/)
+    .flatMap((t) => t.split(/[./-]+/))
+    .map((t) => t.trim())
+    .filter((t) => t.length >= 2);
+}
+
+function scoreFields(fields, terms, phrase) {
+  const matches = [];
+  let score = 0;
+  for (const field of fields) {
+    const text = String(field.text ?? "").toLowerCase();
+    if (!text) continue;
+    if (phrase && phrase.length >= 3 && text.includes(phrase)) {
+      score += field.weight * 4;
+      matches.push(field.label);
+    }
+    const fieldTokens = tokenize(text);
+    for (const term of terms) {
+      const exact = fieldTokens.filter((t) => t === term).length;
+      const partial = exact ? 0 : fieldTokens.filter((t) => t.includes(term) || term.includes(t)).length;
+      if (exact || partial) {
+        score += field.weight * (exact * 2 + partial);
+        if (!matches.includes(field.label)) matches.push(field.label);
+      }
+    }
+  }
+  return { score, matches };
+}
+
+export function buildTaskContext(graph, query, { maxHits = 8, maxFiles = 8 } = {}) {
+  const hits = searchFunctions(graph, query).slice(0, maxHits);
+  const hitFiles = [...new Set(hits.map((h) => h.file))].slice(0, maxFiles);
+  const workflows = graph.workflows
+    .filter((wf) => wf.files.some((f) => hitFiles.includes(f)))
+    .map((wf) => ({
+      id: wf.id,
+      entry: wf.entry,
+      fileCount: wf.files.length,
+      functionCount: wf.functionCount,
+      confidence: wf.confidence?.score,
+      matchedFiles: wf.files.filter((f) => hitFiles.includes(f)),
+    }));
+  const files = hitFiles.map((rel) => {
+    const node = findFileNode(graph, rel);
+    return {
+      file: rel,
+      parsed: node?.parsed ?? false,
+      parseErrors: node?.parseErrors ?? 0,
+      // deterministic reachability, same source as /trace — so an LLM answering
+      // "is this used / reachable?" reads the engine's verdict instead of guessing
+      reachability: reachabilityOf(graph, rel),
+      loc: node?.loc ?? 0,
+      exports: node?.exports ?? [],
+      imports: (node?.imports ?? []).map((i) => ({ source: i.source, names: i.names ?? [] })),
+      functions: (node?.functions ?? []).slice(0, 20).map((fn) => ({
+        name: fn.name,
+        exported: fn.exported,
+        async: fn.async,
+        loc: fn.loc,
+        calls: (fn.calls ?? []).slice(0, 20),
+      })),
+    };
+  });
+  const caveats = [];
+  if ((graph.stats?.callResolutionRate ?? 1) < 0.9) {
+    caveats.push(`Call resolution is ${(graph.stats.callResolutionRate * 100).toFixed(1)}%; dynamic or unresolved calls may hide relationships.`);
+  }
+  if (graph.unsupported?.length) {
+    caveats.push(`${graph.unsupported.length} unsupported-language file(s) were not parsed.`);
+  }
+  return {
+    query,
+    summary: getRepoStatusSummary(graph),
+    hits,
+    files,
+    workflows,
+    caveats,
+  };
+}
+
+function reachabilityOf(graph, rel) {
+  const t = traceFile(graph, rel);
+  if (t.inWorkflow) return { inWorkflow: true, workflows: t.workflows, importedBy: t.importers };
+  return { inWorkflow: false, classification: t.classification, reason: t.reason, importedBy: t.importers };
+}
+
+export function getWorkflowSummaries(graph) {
+  return graph.workflows.map((wf) => ({
+    id: wf.id, entry: wf.entry, fileCount: wf.files.length,
+    functionCount: wf.functionCount, confidence: wf.confidence.score,
+  }));
+}
+
+export function getRepoStatusSummary(graph) {
+  return {
+    fileCount: graph.stats.fileCount,
+    totalLoc: graph.stats.totalLoc,
+    workflowCount: graph.workflows.length,
+    repoConfidence: graph.repoConfidence,
+    callResolutionRate: graph.stats.callResolutionRate,
+    orphanCount: graph.orphans.length,
+  };
+}
+
+/** Shared by chat's startup banner and handoff.js's prompt header. */
+export function detectStack(pkg, graph) {
+  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  const frameworks = [];
+  if (deps.next) frameworks.push("Next.js");
+  else if (deps.react) frameworks.push("React");
+  if (deps.express) frameworks.push("Express");
+  const hasTs = graph.files.some((f) => /\.tsx?$/.test(f.file));
+  return { languages: [hasTs ? "TypeScript" : null, "JavaScript"].filter(Boolean), frameworks };
+}