@mmerterden/multi-agent-pipeline 12.4.0 → 12.6.0

package/pipeline/scripts/cost-budget-check.mjs

@@ -33,6 +33,7 @@
 
 import { readFileSync, existsSync } from "fs";
 import { dirname, join } from "path";
+import { homedir } from "os";
 import { fileURLToPath } from "url";
 import { costUsd } from "./_cost.mjs";
 
@@ -103,10 +104,11 @@ function resolveTracker() {
   const id = flags["task-id"];
   if (!id) die("either --tracker or --task-id is required");
   const bare = String(id).replace(/^#/, "");
+  const logRoot = join(homedir(), ".claude", "logs", "multi-agent");
   for (const c of [
-    join(process.cwd(), ".worktrees", String(id), "phase-tracker.json"),
-    join(process.cwd(), ".worktrees", bare, "phase-tracker.json"),
-    join(process.cwd(), ".worktrees", `task-${bare}`, "phase-tracker.json"),
+    join(logRoot, String(id), "tracker-state.json"),
+    join(logRoot, bare, "tracker-state.json"),
+    join(logRoot, `task-${bare}`, "tracker-state.json"),
   ]) {
     if (existsSync(c)) return c;
   }
@@ -134,15 +136,17 @@ if (!rate) die(`no price for model "${cfg.pricingModel}" in cost-table.json`);
 
 let tokensIn = 0;
 let tokensOut = 0;
+let tokensCached = 0;
 for (const p of Object.values(tracker.phases || {})) {
   tokensIn += Number(p?.tokens_in || 0);
   tokensOut += Number(p?.tokens_out || 0);
+  tokensCached += Number(p?.tokens_cached || 0);
 }
 
-const usd = costUsd(rate, tokensIn, tokensOut);
+const usd = costUsd(rate, tokensIn, tokensOut, tokensCached);
 const pctOfMax = (usd / cfg.maxUsd) * 100;
 const usdStr = `$${usd.toFixed(2)}`;
-const totalTok = tokensIn + tokensOut;
+const totalTok = tokensIn + tokensOut + tokensCached;
 
 const base =
   `cost-budget: ${usdStr} of $${cfg.maxUsd.toFixed(2)} ` +

package/pipeline/scripts/eval-mine-corpus.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // eval-mine-corpus.mjs  -  grow the triage eval set from real production runs.
 //
-// The pipeline already records every Phase 4 triage decision to
-// `~/.claude/logs/multi-agent/triage-corpus.jsonl` (one line per finding:
+// The pipeline already records every Phase 4 triage decision to the per-repo
+// `~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl` (one line per finding:
 // severity/file/line/issue/fix/reviewer + the classification the run gave it,
 // plus an optional human `reason`/`reviewer`). Hand-authoring eval fixtures is
 // the bottleneck; this closes the loop by turning those real decisions into
@@ -38,19 +38,33 @@ const candidatesDir = join(root, "pipeline", "eval", "triage-candidates");
 const validator = join(root, "pipeline", "scripts", "validate-triage.mjs");
 
 const args = process.argv.slice(2);
-const opts = { corpus: null, limit: Infinity, dryRun: false };
+const opts = { corpus: null, limit: Infinity, dryRun: false, repoSlug: null };
 for (let i = 0; i < args.length; i++) {
   if (args[i] === "--corpus") opts.corpus = args[++i];
+  else if (args[i] === "--repo-slug") opts.repoSlug = args[++i];
   else if (args[i] === "--limit") opts.limit = Number(args[++i]) || Infinity;
   else if (args[i] === "--dry-run") opts.dryRun = true;
   else if (args[i] === "-h" || args[i] === "--help") {
-    console.log("Usage: eval-mine-corpus.mjs [--corpus <path>] [--limit N] [--dry-run]");
+    console.log("Usage: eval-mine-corpus.mjs [--corpus <path>] [--repo-slug <slug>] [--limit N] [--dry-run]");
     process.exit(0);
   }
 }
 
+// Resolve the corpus path the SAME way triage-memory.mjs writes it:
+// ~/.claude/memory/multi-agent/<repo-slug>/triage-corpus.jsonl (per repo).
+// (The old default read ~/.claude/logs/.../triage-corpus.jsonl - a flat path
+// nothing writes to - so without --corpus it always found nothing.)
+function resolveRepoSlug() {
+  if (opts.repoSlug) return String(opts.repoSlug);
+  if (process.env.MULTI_AGENT_REPO_SLUG) return process.env.MULTI_AGENT_REPO_SLUG;
+  const r = spawnSync("git", ["rev-parse", "--show-toplevel"], { encoding: "utf-8" });
+  if (r.status === 0 && r.stdout.trim()) return r.stdout.trim().split("/").pop();
+  return "default";
+}
+
 const corpusPath =
-  opts.corpus || join(homedir(), ".claude", "logs", "multi-agent", "triage-corpus.jsonl");
+  opts.corpus ||
+  join(homedir(), ".claude", "memory", "multi-agent", resolveRepoSlug(), "triage-corpus.jsonl");
 
 if (!existsSync(corpusPath)) {
   console.log(`eval-mine-corpus: no corpus at ${corpusPath} - nothing to mine.`);

package/pipeline/scripts/fixtures/install-layout.tsv

@@ -1,19 +1,19 @@
 .claude/.pipeline-version	1
 .claude/CLAUDE.md	1
 .claude/agents	8
-.claude/commands	47
+.claude/commands	48
 .claude/lib	27
 .claude/multi-agent-preferences.json	1
-.claude/multi-agent-refs	51
+.claude/multi-agent-refs	52
 .claude/rules	12
-.claude/schemas	24
-.claude/scripts	197
+.claude/schemas	25
+.claude/scripts	201
 .claude/settings.json	1
 .claude/skills	428
 .copilot/.pipeline-version	1
 .copilot/agents	8
 .copilot/copilot-instructions.md	1
 .copilot/lib	27
-.copilot/schemas	24
-.copilot/scripts	197
-.copilot/skills	470
+.copilot/schemas	25
+.copilot/scripts	201
+.copilot/skills	471

package/pipeline/scripts/gc-worktrees.sh

@@ -64,6 +64,13 @@ if ! git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
   exit 0
 fi
 REPO="$(cd "$REPO" && pwd -P)"
+# Anchor on the MAIN worktree (first porcelain entry) so a run started from a
+# subdirectory OR from inside a linked worktree still targets
+# <main-repo>/.worktrees/ rather than a bogus <subdir>/.worktrees/ (which
+# silently found nothing and left residue behind).
+MAIN_WT="$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p' | head -1)"
+MAIN_WT="$(cd "$MAIN_WT" 2>/dev/null && pwd -P)" || MAIN_WT=""
+[ -n "$MAIN_WT" ] && REPO="$MAIN_WT"
 WT_ROOT="$REPO/.worktrees"
 
 changed=0
@@ -76,9 +83,24 @@ pruned=$(git -C "$REPO" worktree prune -v 2>&1 | grep -c . || true)
 # 2. Orphan dirs: present under .worktrees/ but not registered as worktrees.
 orphans=()
 if [ -d "$WT_ROOT" ]; then
-  registered=$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
+  # Resolve every registered worktree path to its physical form so the
+  # orphan test below compares like-for-like against `pwd -P`-resolved dirs.
+  # A raw (unresolved) registered path with a symlinked component would fail
+  # the match and get a HEALTHY worktree misclassified as an orphan and
+  # deleted under --yes; resolving both sides removes that risk (this mirrors
+  # purge.sh, which resolves both sides).
+  registered=""
+  while IFS= read -r regpath; do
+    [ -n "$regpath" ] || continue
+    regphys="$(cd "$regpath" 2>/dev/null && pwd -P)" || regphys=""
+    [ -n "$regphys" ] && registered="$registered$regphys
+"
+  done <<EOF
+$(git -C "$REPO" worktree list --porcelain 2>/dev/null | sed -n 's/^worktree //p')
+EOF
   for d in "$WT_ROOT"/*/; do
     [ -d "$d" ] || continue
+    [ -L "${d%/}" ] && continue  # never follow a symlinked entry out of the tree
     dir="$(cd "$d" && pwd -P)"
     # Path guard: only ever consider dirs strictly inside <repo>/.worktrees/.
     case "$dir" in "$WT_ROOT"/*) ;; *) continue ;; esac

package/pipeline/scripts/learning-curve.mjs

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+// learning-curve.mjs  -  time-bucketed TREND over metrics.jsonl.
+//
+// aggregate-metrics.mjs reports lifetime totals; this reports the CURVE: how
+// the pipeline's per-task quality/cost move over time as it accumulates
+// learnings on a repo. Without a trend you cannot tell whether "it gets better
+// over time" is real - this is the measurement layer for the learning loop.
+//
+// Buckets tasks by the timestamp of their first event, then per bucket reports:
+//   tasks, first-pass-clean rate, avg review cycles, rework/task,
+//   tokens/task, cache-reuse ratio. Prints a first->last trend for the
+//   headline KPIs. Read-only, zero deps, no API/model calls.
+//
+// Usage:
+//   learning-curve.mjs [--bucket=<days>] [--since=ISO] [--json|--markdown]
+// Env: METRICS_FILE overrides the default ~/.claude/logs/multi-agent/metrics.jsonl
+//
+// Exit: 0 always (advisory; empty/missing metrics -> friendly note).
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const args = process.argv.slice(2);
+const opts = { json: false, markdown: false, since: null, bucketDays: 7 };
+for (const a of args) {
+  if (a === "--json") opts.json = true;
+  else if (a === "--markdown" || a === "--md") opts.markdown = true;
+  else if (a.startsWith("--since=")) opts.since = a.slice(8);
+  else if (a.startsWith("--bucket=")) opts.bucketDays = Math.max(1, parseInt(a.slice(9), 10) || 7);
+  else if (a === "--help" || a === "-h") {
+    console.log("Usage: learning-curve.mjs [--bucket=<days>] [--since=ISO] [--json|--markdown]");
+    process.exit(0);
+  }
+}
+
+const METRICS_FILE =
+  process.env.METRICS_FILE || join(homedir(), ".claude", "logs", "multi-agent", "metrics.jsonl");
+
+function emitEmpty(reason) {
+  if (opts.json) console.log(JSON.stringify({ ok: false, reason, buckets: [] }));
+  else console.error(`learning-curve: ${reason}`);
+  process.exit(0);
+}
+
+if (!existsSync(METRICS_FILE)) emitEmpty(`no metrics file at ${METRICS_FILE}`);
+
+const events = [];
+for (const line of readFileSync(METRICS_FILE, "utf-8").split("\n")) {
+  if (!line.trim()) continue;
+  try {
+    const e = JSON.parse(line);
+    if (opts.since && e.ts && e.ts < opts.since) continue;
+    events.push(e);
+  } catch {
+    /* skip corrupted line */
+  }
+}
+if (events.length === 0) emitEmpty("no metrics events in range");
+
+// Fold events into per-task aggregates.
+const num = (v) => (typeof v === "number" ? v : Number(v)) || 0;
+const tasks = new Map();
+for (const e of events) {
+  const id = e.task_id;
+  if (!id) continue;
+  let t = tasks.get(id);
+  if (!t) {
+    t = { firstTs: e.ts, reviewCycles: null, rework: 0, tokensIn: 0, tokensOut: 0, tokensCached: 0 };
+    tasks.set(id, t);
+  }
+  if (e.ts && (!t.firstTs || e.ts < t.firstTs)) t.firstTs = e.ts;
+  const d = e.details || {};
+  if (e.event === "review.completed" && d.review_cycles != null) t.reviewCycles = num(d.review_cycles);
+  if (e.event === "rework.started") t.rework += 1;
+  t.tokensIn += num(d.tokens_in);
+  t.tokensOut += num(d.tokens_out);
+  t.tokensCached += num(d.tokens_cached);
+}
+
+// Bucket tasks by first-seen day / bucketDays window (UTC).
+const DAY = 86400000;
+const bucketOf = (ts) => {
+  const ms = Date.parse(ts);
+  if (Number.isNaN(ms)) return null;
+  const dayIndex = Math.floor(ms / DAY);
+  const b = Math.floor(dayIndex / opts.bucketDays) * opts.bucketDays;
+  return new Date(b * DAY).toISOString().slice(0, 10);
+};
+
+const byBucket = new Map();
+for (const t of tasks.values()) {
+  const key = bucketOf(t.firstTs);
+  if (!key) continue;
+  if (!byBucket.has(key)) byBucket.set(key, []);
+  byBucket.get(key).push(t);
+}
+
+const round = (n, p = 2) => Math.round(n * 10 ** p) / 10 ** p;
+const buckets = [...byBucket.keys()].sort().map((start) => {
+  const list = byBucket.get(start);
+  const n = list.length;
+  const withReview = list.filter((t) => t.reviewCycles != null);
+  const firstPassClean = withReview.filter((t) => t.reviewCycles <= 1).length;
+  const totIn = list.reduce((s, t) => s + t.tokensIn, 0);
+  const totOut = list.reduce((s, t) => s + t.tokensOut, 0);
+  const totCached = list.reduce((s, t) => s + t.tokensCached, 0);
+  return {
+    bucketStart: start,
+    tasks: n,
+    firstPassCleanRate: withReview.length ? round(firstPassClean / withReview.length) : null,
+    avgReviewCycles: withReview.length
+      ? round(withReview.reduce((s, t) => s + t.reviewCycles, 0) / withReview.length)
+      : null,
+    reworkPerTask: round(list.reduce((s, t) => s + t.rework, 0) / n),
+    tokensPerTask: Math.round((totIn + totOut) / n),
+    cacheRatio: totIn ? round(totCached / totIn) : null,
+  };
+});
+
+// first->last trend for the headline KPIs (only when >=2 buckets).
+let trend = null;
+if (buckets.length >= 2) {
+  const a = buckets[0];
+  const z = buckets[buckets.length - 1];
+  const delta = (x, y) => (x == null || y == null ? null : round(y - x));
+  trend = {
+    from: a.bucketStart,
+    to: z.bucketStart,
+    firstPassCleanRate: delta(a.firstPassCleanRate, z.firstPassCleanRate),
+    avgReviewCycles: delta(a.avgReviewCycles, z.avgReviewCycles),
+    tokensPerTask: a.tokensPerTask && z.tokensPerTask ? z.tokensPerTask - a.tokensPerTask : null,
+    cacheRatio: delta(a.cacheRatio, z.cacheRatio),
+  };
+}
+
+const out = { ok: true, bucketDays: opts.bucketDays, buckets, trend };
+
+if (opts.json) {
+  console.log(JSON.stringify(out, null, 2));
+  process.exit(0);
+}
+
+// Markdown / text (default)
+const arrow = (v, goodIsUp) => {
+  if (v == null || v === 0) return "-";
+  const up = v > 0;
+  const good = up === goodIsUp;
+  return `${up ? "+" : ""}${v} ${good ? "(better)" : "(worse)"}`;
+};
+console.log(`# Learning curve (${opts.bucketDays}-day buckets)\n`);
+console.log("| Bucket | Tasks | First-pass clean | Avg review cycles | Rework/task | Tokens/task | Cache ratio |");
+console.log("|---|---|---|---|---|---|---|");
+for (const b of buckets) {
+  console.log(
+    `| ${b.bucketStart} | ${b.tasks} | ${b.firstPassCleanRate ?? "-"} | ${b.avgReviewCycles ?? "-"} | ${b.reworkPerTask} | ${b.tokensPerTask} | ${b.cacheRatio ?? "-"} |`,
+  );
+}
+if (trend) {
+  console.log(`\n**Trend ${trend.from} -> ${trend.to}:**`);
+  console.log(`- First-pass clean: ${arrow(trend.firstPassCleanRate, true)}`);
+  console.log(`- Avg review cycles: ${arrow(trend.avgReviewCycles, false)}`);
+  console.log(`- Tokens/task: ${arrow(trend.tokensPerTask, false)}`);
+  console.log(`- Cache ratio: ${arrow(trend.cacheRatio, true)}`);
+} else {
+  console.log("\n(need >= 2 buckets for a trend; keep running the pipeline)");
+}

package/pipeline/scripts/learnings-ledger.mjs

@@ -74,9 +74,27 @@ function die(msg, code = 1) {
   process.exit(code);
 }
 
+// Resolves to the MAIN repository name even when called from inside a pipeline
+// worktree. `--show-toplevel` returns the worktree root, whose basename is the
+// task id, which would shard the per-repo ledger one directory per task and make
+// the learning replay always miss. `--git-common-dir` points at the main
+// repository's .git for every linked worktree.
 function repoSlug() {
   if (flags["repo-slug"]) return String(flags["repo-slug"]);
   if (process.env.MULTI_AGENT_REPO_SLUG) return process.env.MULTI_AGENT_REPO_SLUG;
+  try {
+    const commonDir = execFileSync(
+      "git",
+      ["rev-parse", "--path-format=absolute", "--git-common-dir"],
+      { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+    ).trim();
+    if (commonDir) {
+      const base = basename(commonDir);
+      const root = base === ".git" ? dirname(commonDir) : commonDir.replace(/\.git$/, "");
+      const slug = basename(root);
+      if (slug) return slug;
+    }
+  } catch { /* not a git repo, or git too old for --path-format */ }
   try {
     const top = execFileSync("git", ["rev-parse", "--show-toplevel"], {
       encoding: "utf8",
@@ -120,7 +138,7 @@ function writeRow(slug, row) {
 
 /** Append one entry unless an entry with the same kind + normalized statement
  *  already exists (idempotent). Returns true when written. */
-function addEntry(slug, { kind, statement, scope, task, confidence }, existing) {
+function addEntry(slug, { kind, statement, scope, task, confidence, diagnosis }, existing) {
   const stmt = String(statement || "").trim();
   if (!stmt) return false;
   const seenKey = `${kind}::${normStatement(stmt)}`;
@@ -135,6 +153,11 @@ function addEntry(slug, { kind, statement, scope, task, confidence }, existing)
     source_task: task || null,
     confidence: CONFIDENCES.has(confidence) ? confidence : "medium",
   };
+  // Optional causal diagnosis (Reflexion P5): the "why it failed" behind a
+  // lesson. Verbal diagnosis is what turns a detected error into a prevented
+  // one; a bare outcome does not. Stored only when supplied.
+  const diag = String(diagnosis || "").trim();
+  if (diag) row.diagnosis = diag;
   writeRow(slug, row);
   existing.add(seenKey);
   return true;
@@ -152,6 +175,7 @@ function cmdAdd() {
     scope: flags.scope && flags.scope !== true ? String(flags.scope) : "global",
     task: flags.task && flags.task !== true ? String(flags.task) : null,
     confidence: flags.confidence && flags.confidence !== true ? String(flags.confidence) : "medium",
+    diagnosis: flags.diagnosis && flags.diagnosis !== true ? String(flags.diagnosis) : null,
   }, existing);
   process.stdout.write(JSON.stringify({ ok: true, slug, added: wrote ? 1 : 0, deduped: wrote ? 0 : 1 }) + "\n");
   process.exit(wrote ? 0 : 2);
@@ -247,7 +271,8 @@ function cmdBrief() {
     lines.push("", `## ${labels[kind]}`);
     for (const r of items) {
       const scope = r.scope && r.scope !== "global" ? ` [${r.scope}]` : "";
-      lines.push(`- ${r.statement}${scope}`);
+      const why = r.diagnosis ? ` (why: ${r.diagnosis})` : "";
+      lines.push(`- ${r.statement}${scope}${why}`);
     }
   }
   lines.push("</repo-learnings>");

package/pipeline/scripts/lint-mcp-refs.mjs

@@ -0,0 +1,207 @@
+#!/usr/bin/env node
+// lint-mcp-refs.mjs  -  every mcp__<server>__<tool> reference must be callable.
+//
+// A host composes an MCP tool name as mcp__<registered-server-name>__<tool>.
+// The pipeline had 100 references to `mcp__dev_toolkit__*` while the server is
+// registered as `dev-toolkit`, so the real names are `mcp__dev-toolkit__*`.
+// Nothing caught it: prose is not executed, and a wrong name inside an
+// `allowed-tools:` allowlist silently denies the tool instead of erroring.
+//
+// Checks (errors - fail the gate):
+//   1. the server segment must be a known registered server name
+//   2. the known-bad snake_case spellings are called out with their fix
+//
+// Optional deep check (advisory - never fails):
+//   3. when the companion dev-toolkit repo resolves locally (via
+//      prefs.global.devToolkit.localPath, or the mcpServers registration in
+//      ~/.claude.json / ~/.claude/settings.json), handshake it over stdio and
+//      confirm every referenced dev-toolkit tool actually exists in tools/list.
+//      CI has no local checkout, so an unresolvable repo is a skip, not a fail.
+//
+// Zero-dependency. Runs inside `npm test` and ci-lite.
+//
+// Usage: node pipeline/scripts/lint-mcp-refs.mjs [--strict-tools]
+// Exit: 0 clean, 1 unknown server segment (or a missing tool with --strict-tools).
+
+import { readFileSync, existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const strictTools = process.argv.includes("--strict-tools");
+
+// Servers the pipeline is allowed to reference. The key is the registered
+// server name as it appears in an mcpServers config, which is what the host
+// interpolates into the tool name.
+const KNOWN_SERVERS = {
+  "dev-toolkit": "companion device/browser toolkit (@mmerterden/dev-toolkit-mcp)",
+  claude_ai_Figma: "Figma MCP (analysis phase only)",
+  XcodeBuildMCP: "optional third-party Xcode build server",
+};
+// Spellings that look right but cannot resolve to a registered server.
+const KNOWN_BAD = { dev_toolkit: "dev-toolkit", "claude-ai-Figma": "claude_ai_Figma" };
+
+const SCAN_DIRS = ["pipeline/commands", "pipeline/skills", "pipeline/multi-agent-refs"];
+const SCAN_EXT = /\.(md|sh|mjs|json)$/;
+const PRUNE = new Set(["node_modules", ".git", ".worktrees", "Pods", ".build", "DerivedData", ".next"]);
+
+function walk(dir, out = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of entries) {
+    if (PRUNE.has(e.name)) continue;
+    const p = join(dir, e.name);
+    if (e.isDirectory()) walk(p, out);
+    else if (SCAN_EXT.test(e.name)) out.push(p);
+  }
+  return out;
+}
+
+const files = SCAN_DIRS.flatMap((d) => walk(join(repoRoot, d)));
+const REF = /mcp__([A-Za-z0-9_-]+?)__([a-z0-9_]+)/g;
+
+const errors = [];
+const refs = new Map(); // server -> Map(tool -> Set(file:line))
+
+for (const file of files) {
+  const rel = file.slice(repoRoot.length + 1);
+  const lines = readFileSync(file, "utf8").split("\n");
+  lines.forEach((line, i) => {
+    for (const m of line.matchAll(REF)) {
+      const [, server, tool] = m;
+      // Prose writes families as mcp__dev-toolkit__ios_* - a wildcard, not a tool.
+      const next = line[m.index + m[0].length];
+      if (next === "*" || tool.endsWith("_")) continue;
+      const where = `${rel}:${i + 1}`;
+      if (!refs.has(server)) refs.set(server, new Map());
+      const tools = refs.get(server);
+      if (!tools.has(tool)) tools.set(tool, new Set());
+      tools.get(tool).add(where);
+    }
+  });
+}
+
+for (const [server, tools] of refs) {
+  if (server in KNOWN_SERVERS) continue;
+  const fix = KNOWN_BAD[server];
+  const sample = [...tools.values()][0].values().next().value;
+  errors.push(
+    fix
+      ? `unknown MCP server segment "${server}" (${tools.size} tool refs, e.g. ${sample}) - the registered server is "${fix}", so the prefix must be mcp__${fix}__`
+      : `unknown MCP server segment "${server}" (${tools.size} tool refs, e.g. ${sample}) - add it to KNOWN_SERVERS in lint-mcp-refs.mjs if this server is expected, or fix the prefix to match the registered server name`,
+  );
+}
+
+// ---- optional deep check: do the referenced dev-toolkit tools exist? --------
+
+function resolveToolkitRepo() {
+  const prefsPath = join(homedir(), ".claude", "multi-agent-preferences.json");
+  if (existsSync(prefsPath)) {
+    try {
+      const dt = JSON.parse(readFileSync(prefsPath, "utf8"))?.global?.devToolkit;
+      if (dt && dt.enabled === false) return null;
+      if (dt?.localPath) {
+        const p = dt.localPath.replace(/^~|\$HOME/, homedir());
+        if (existsSync(join(p, "package.json"))) return p;
+      }
+    } catch {
+      /* fall through to registration lookup */
+    }
+  }
+  const candidates = [];
+  const collect = (obj) => {
+    for (const [name, cfg] of Object.entries(obj || {})) {
+      const arg = Array.isArray(cfg?.args) ? cfg.args.find((a) => /\.(mjs|js)$/.test(a)) : null;
+      if (name.includes("dev") && arg) candidates.push(dirname(resolve(arg)));
+    }
+  };
+  for (const cfgPath of [join(homedir(), ".claude.json"), join(homedir(), ".claude", "settings.json")]) {
+    if (!existsSync(cfgPath)) continue;
+    try {
+      const json = JSON.parse(readFileSync(cfgPath, "utf8"));
+      collect(json.mcpServers);
+      for (const proj of Object.values(json.projects || {})) collect(proj.mcpServers);
+    } catch {
+      /* ignore unreadable config */
+    }
+  }
+  for (const c of candidates) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(c, "package.json"), "utf8"));
+      if (pkg.dependencies?.["@modelcontextprotocol/sdk"] && statSync(join(c, ".git"))) return c;
+    } catch {
+      /* not the toolkit */
+    }
+  }
+  return null;
+}
+
+function listTools(repo) {
+  const frames =
+    [
+      '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"lint-mcp-refs","version":"1"}}}',
+      '{"jsonrpc":"2.0","method":"notifications/initialized"}',
+      '{"jsonrpc":"2.0","id":2,"method":"tools/list"}',
+    ].join("\n") + "\n";
+  const r = spawnSync(process.execPath, ["index.js"], {
+    cwd: repo,
+    input: frames,
+    encoding: "utf8",
+    timeout: 20000,
+    maxBuffer: 32 * 1024 * 1024,
+  });
+  if (r.error || !r.stdout) return null;
+  for (const line of r.stdout.split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      const msg = JSON.parse(line);
+      if (msg.id === 2 && msg.result?.tools) return msg.result.tools.map((t) => t.name);
+    } catch {
+      /* not a frame */
+    }
+  }
+  return null;
+}
+
+const referencedToolkitTools = refs.get("dev-toolkit");
+let deep = "skipped (no local dev-toolkit checkout)";
+if (referencedToolkitTools) {
+  const repo = resolveToolkitRepo();
+  const served = repo ? listTools(repo) : null;
+  if (!served) {
+    deep = repo ? `skipped (${repo} did not answer tools/list)` : deep;
+  } else {
+    const missing = [...referencedToolkitTools.keys()].filter((t) => !served.includes(t));
+    if (missing.length === 0) {
+      deep = `all ${referencedToolkitTools.size} referenced tools exist in the live server (${served.length} served)`;
+    } else {
+      const msg = `dev-toolkit tools referenced but not served (${served.length} served): ${missing
+        .map((t) => `${t} [${[...referencedToolkitTools.get(t)][0]}]`)
+        .join(", ")}`;
+      deep = `${missing.length} referenced tool(s) not served`;
+      if (strictTools) errors.push(msg);
+      else console.warn(`  WARNING - ${msg}`);
+    }
+  }
+}
+
+const totalRefs = [...refs.values()].reduce((n, tools) => n + tools.size, 0);
+console.log(
+  `lint-mcp-refs: ${totalRefs} distinct tool references across ${refs.size} server(s) in ${files.length} files`,
+);
+for (const [server, tools] of refs) {
+  console.log(`  ${server in KNOWN_SERVERS ? "✓" : "✗"} mcp__${server}__* : ${tools.size} tools`);
+}
+console.log(`  tool-existence check: ${deep}`);
+
+if (errors.length > 0) {
+  console.error(`lint-mcp-refs: ${errors.length} error(s)`);
+  for (const e of errors) console.error("  " + e);
+  process.exit(1);
+}

package/pipeline/scripts/memory-load.sh

@@ -16,9 +16,13 @@ PROJECT_ROOT="${1:?usage: memory-load.sh <project-root>}"
 MEM_DIR="$PROJECT_ROOT/.multi-agent/memory"
 MEM_INDEX="$MEM_DIR/MEMORY.md"
 
-# Pref-gate: locate prefs.json (home-dir first, then project-specific).
+# Pref-gate: locate the preferences file (home-dir first, then XDG config).
+# The canonical name written by the installer is multi-agent-preferences.json;
+# the bare preferences.json names are kept only as legacy fallbacks.
 prefs_file=""
 for candidate in \
+  "$HOME/.claude/multi-agent-preferences.json" \
+  "$HOME/.config/multi-agent-pipeline/multi-agent-preferences.json" \
   "$HOME/.claude/preferences.json" \
   "$HOME/.config/multi-agent-pipeline/preferences.json"
 do

package/pipeline/scripts/render-work-summary.sh

@@ -126,7 +126,10 @@ fi
 changed_block=""
 files_count=0
 total_add=0; total_del=0
-if [ -n "$WORKTREE" ] && [ -d "$WORKTREE/.git" -o -d "$WORKTREE" ]; then
+# Only the directory needs to exist here; `git rev-parse HEAD` below is the real
+# repository check. Testing -d "$WORKTREE/.git" would be wrong regardless: in a
+# linked worktree .git is a file, not a directory.
+if [ -n "$WORKTREE" ] && [ -d "$WORKTREE" ]; then
   if git -C "$WORKTREE" rev-parse HEAD >/dev/null 2>&1; then
     diffstat=$(git -C "$WORKTREE" diff --numstat "$state_base"...HEAD 2>/dev/null || true)
     if [ -n "$diffstat" ]; then

package/pipeline/scripts/repo-map.mjs

@@ -82,7 +82,7 @@ function parseArgs(argv) {
 // ---- File walking ----------------------------------------------------------
 
 const DEFAULT_IGNORE = new Set([
-  '.git', 'node_modules', 'Pods', '.build', 'DerivedData', '.next',
+  '.git', '.worktrees', 'node_modules', 'Pods', '.build', 'DerivedData', '.next',
   'dist', 'build', '__pycache__', '.venv', 'venv', '.cache',
   '.gradle', '.idea', '.vscode', 'target',
 ]);