@mmerterden/multi-agent-pipeline 16.12.0 → 16.14.0

package/pipeline/scripts/graph-report.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-report.mjs  -  GRAPH_REPORT.md, the human-and-model readable summary.
+ *
+ * Phase 1 reads this before deciding how wide to explore, and Phase 7 ships it
+ * next to the knowledge base. Sections are ordered by how much they narrow a
+ * search: hubs first (the types everything touches), then the module map, then
+ * the long tail that is usually safe to ignore.
+ *
+ * God-nodes exclude test files. A test base class is a hub of the test target,
+ * not of the architecture, and letting it rank pushes the real hubs off a list
+ * whose whole value is its first ten rows.
+ *
+ * Inputs:
+ *   --graph <path>   Graph file. Default: ~/.claude/knowledge/<cwd name>/code-graph.json
+ *   --out <path>     Report path. Default: GRAPH_REPORT.md beside the graph
+ *   --top N          Rows per ranked section. Default: 15
+ *   --stdout         Print instead of writing
+ *   --status         Print one header line and exit, writing nothing. This is
+ *                    what `/multi-agent:graph status` runs: the graph is a
+ *                    22MB JSON on a large repo, so "read the header yourself"
+ *                    would mean pulling the whole file into a model's context.
+ *
+ * Exit codes:
+ *   0  -  written
+ *   1  -  graph missing or unreadable
+ *
+ * @module pipeline/scripts/graph-report
+ */
+
+import { writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { join, dirname, resolve } from "node:path";
+import { parseFlags } from "./graph-build.mjs";
+import { loadGraph, defaultGraphPath } from "./graph-query.mjs";
+
+/**
+ * Top-level source directory of a path, used as the module bucket.
+ *
+ * @param {string} path
+ * @returns {string}
+ */
+export function moduleOf(path) {
+  if (!path) return "-";
+  const parts = path.split("/");
+  return parts.length > 1 ? parts[0] : ".";
+}
+
+/**
+ * Section inputs, derived once so the renderer stays declarative.
+ *
+ * @param {object} graph
+ * @param {number} top
+ * @returns {object}
+ */
+export function summarize(graph, top) {
+  const symbols = graph.nodes.filter((n) => n.kind === "symbol");
+  const files = graph.nodes.filter((n) => n.kind === "file");
+
+  const hubs = symbols
+    .filter((n) => !n.isTest)
+    .sort((a, b) => b.degree - a.degree)
+    .slice(0, top);
+
+  const modules = new Map();
+  for (const f of files) {
+    const key = moduleOf(f.path);
+    if (!modules.has(key)) modules.set(key, { files: 0, symbols: 0, tests: 0 });
+    const bucket = modules.get(key);
+    bucket.files++;
+    if (f.isTest) bucket.tests++;
+  }
+  for (const s of symbols) {
+    const key = moduleOf(s.path);
+    if (modules.has(key)) modules.get(key).symbols++;
+  }
+
+  const externals = graph.nodes
+    .filter((n) => n.kind === "module")
+    .sort((a, b) => b.degree - a.degree)
+    .slice(0, top);
+
+  const orphans = files.filter((f) => f.degree === 0);
+
+  const kinds = {};
+  for (const s of symbols) kinds[s.symbolKind] = (kinds[s.symbolKind] || 0) + 1;
+
+  return { hubs, modules, externals, orphans, kinds, fileCount: files.length };
+}
+
+/**
+ * @param {object} graph
+ * @param {number} top
+ * @returns {string} markdown
+ */
+export function render(graph, top) {
+  const s = summarize(graph, top);
+  const L = [];
+
+  L.push(`# Code graph report`);
+  L.push("");
+  L.push(`- Root: \`${graph.root}\``);
+  L.push(`- Stack: ${graph.stack}`);
+  L.push(`- Built: ${graph.generatedAt}`);
+  if (graph.baseCommit) L.push(`- Commit: \`${graph.baseCommit.slice(0, 12)}\``);
+  L.push(
+    `- Scale: ${graph.stats.files} files, ${graph.stats.nodes} nodes, ${graph.stats.edges} edges`,
+  );
+  L.push("");
+
+  L.push(`## Architectural hubs`);
+  L.push("");
+  L.push(`The most connected non-test symbols. A change here reaches the widest surface.`);
+  L.push("");
+  L.push(`| Degree | Symbol | Kind | Path |`);
+  L.push(`|---|---|---|---|`);
+  for (const h of s.hubs) {
+    L.push(`| ${h.degree} | \`${h.name}\` | ${h.symbolKind} | \`${h.path}:${h.line || 1}\` |`);
+  }
+  L.push("");
+
+  L.push(`## Modules`);
+  L.push("");
+  L.push(`| Module | Files | Symbols | Test files |`);
+  L.push(`|---|---|---|---|`);
+  const sortedModules = [...s.modules.entries()].sort((a, b) => b[1].files - a[1].files);
+  for (const [name, m] of sortedModules) {
+    L.push(`| \`${name}\` | ${m.files} | ${m.symbols} | ${m.tests} |`);
+  }
+  L.push("");
+
+  L.push(`## External dependencies`);
+  L.push("");
+  L.push(`Imported names with no declaring file in this repo.`);
+  L.push("");
+  L.push(`| Imports | Module |`);
+  L.push(`|---|---|`);
+  for (const e of s.externals) L.push(`| ${e.degree} | \`${e.name}\` |`);
+  L.push("");
+
+  L.push(`## Symbol kinds`);
+  L.push("");
+  const kindRows = Object.entries(s.kinds).sort((a, b) => b[1] - a[1]);
+  L.push(kindRows.map(([k, n]) => `${k}: ${n}`).join(" · "));
+  L.push("");
+
+  L.push(`## Unconnected files`);
+  L.push("");
+  if (s.orphans.length === 0) {
+    L.push(`None: every file has at least one edge.`);
+  } else {
+    L.push(
+      `${s.orphans.length} of ${s.fileCount} files have no edge at all. ` +
+        `Either they declare nothing this stack's rules recognise, or nothing references them.`,
+    );
+    L.push("");
+    for (const o of s.orphans.slice(0, top)) L.push(`- \`${o.path}\``);
+    if (s.orphans.length > top) L.push(`- ... ${s.orphans.length - top} more`);
+  }
+  L.push("");
+
+  return L.join("\n");
+}
+
+/**
+ * HEAD of a repo, or null when it is not a git checkout.
+ *
+ * @param {string} root
+ * @returns {string|null}
+ */
+function headCommit(root) {
+  try {
+    return execFileSync("git", ["-C", root, "rev-parse", "HEAD"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One line: what the graph covers and whether it still matches the tree.
+ *
+ * @param {object} graph
+ * @param {string} path
+ * @returns {string}
+ */
+export function statusLine(graph, path) {
+  const head = headCommit(graph.root);
+  let freshness = "freshness unknown (no git HEAD)";
+  if (graph.baseCommit && head) {
+    freshness =
+      graph.baseCommit === head
+        ? `current (${head.slice(0, 12)})`
+        : `STALE: built at ${graph.baseCommit.slice(0, 12)}, HEAD is ${head.slice(0, 12)}`;
+  } else if (!graph.baseCommit) {
+    freshness = "freshness unknown (graph carries no baseCommit)";
+  }
+  return (
+    `graph-status: ${graph.stack} | ${graph.stats.files} files, ${graph.stats.nodes} nodes, ` +
+    `${graph.stats.edges} edges | built ${graph.generatedAt} | ${freshness} | ${path}`
+  );
+}
+
+function main() {
+  const { flags } = parseFlags(process.argv.slice(2));
+  const path = flags.graph && flags.graph !== true ? resolve(flags.graph) : defaultGraphPath();
+
+  let graph;
+  try {
+    graph = loadGraph(path);
+  } catch (e) {
+    process.stderr.write(`graph-report: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  if (flags.status === true) {
+    process.stdout.write(statusLine(graph, path) + "\n");
+    return;
+  }
+
+  const top = Number(flags.top) > 0 ? Number(flags.top) : 15;
+  const markdown = render(graph, top);
+
+  if (flags.stdout === true) {
+    process.stdout.write(markdown);
+    return;
+  }
+  const out =
+    flags.out && flags.out !== true ? resolve(flags.out) : join(dirname(path), "GRAPH_REPORT.md");
+  writeFileSync(out, markdown, "utf8");
+  process.stdout.write(`graph-report: ${out}\n`);
+}
+
+if (process.argv[1] && process.argv[1].endsWith("graph-report.mjs")) main();

package/pipeline/scripts/smoke-cross-cli-behavior.sh

@@ -203,10 +203,13 @@ TRSCHEMA="${MA_SCHEMAS:+$MA_SCHEMAS/triage-output.schema.json}"
 
 if [ -z "$P4" ] || [ ! -f "$P4" ]; then
   echo "  ↷ SKIP: phase-4-review.md not present in this $MA_LAYOUT layout"
-elif grep -qiE "Claude Code (dispatches|=|:) ?3|Claude Code dispatches Fable \+ Opus \+ Sonnet" "$P4" \
-  && grep -qiE "Copilot CLI (dispatches|=|:) ?3|3-model" "$P4" \
-  && grep -qiE "Codex CLI (dispatches|=|:) ?3|Claude Code 3, Copilot CLI 3, Codex CLI 3" "$P4"; then
-  pass "phase-4-review declares Claude=3 / Copilot=3 / Codex=3 reviewers"
+# Two independent statements, because they can drift apart: the count sentence is
+# the contract, and the matrix is what a reader dispatches from. Three regexes over
+# overlapping prose used to stand in for this and let the count sentence 300 lines
+# further down go stale for a whole release without failing.
+elif grep -qF "Claude Code 3, Copilot CLI 3, Codex CLI 3" "$P4" \
+  && grep -qE '^\| Reviewer 3 .*\|.*\|.*\|.*\|' "$P4"; then
+  pass "phase-4-review declares Claude=3 / Copilot=3 / Codex=3 reviewers, and the matrix has all three host columns"
 else
   fail "phase-4-review does not declare the CLI-aware reviewer count for all three hosts"
 fi

package/pipeline/scripts/test-gap-rules/go.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "stack": "go",
+  "description": "Go test gap rules. Sources in *.go; tests are *_test.go beside the code they cover, which is why there is no test directory convention here.",
+  "sourceExtensions": [".go"],
+  "testPathSuffixes": ["_test.go"],
+  "testPathContains": [],
+  "excludePathGlobs": ["vendor/", "third_party/", "*.pb.go", "*_generated.go", "*_mock.go"],
+  "publicApiPatterns": [
+    {
+      "id": "exported_func",
+      "regex": "^func\\s+([A-Z][A-Za-z0-9_]*)\\s*\\("
+    },
+    {
+      "id": "exported_method",
+      "regex": "^func\\s+\\([^)]*\\)\\s+([A-Z][A-Za-z0-9_]*)\\s*\\("
+    },
+    {
+      "id": "exported_type",
+      "regex": "^type\\s+([A-Z][A-Za-z0-9_]*)\\s+(?:struct|interface|func|map|\\[|chan|\\*|[A-Za-z])"
+    }
+  ],
+  "hint": "Cover exported identifiers with a table-driven Test<Name> in the same package's <file>_test.go. An unexported identifier is covered through the exported one that calls it."
+}

package/pipeline/scripts/test-gap-rules/ios.json

@@ -13,20 +13,48 @@
     "Generated/",
     "Sourcery/",
     "_Generated.swift",
-    "Tests/Fixtures/"
+    "Tests/Fixtures/",
+    ".xctemplate/"
   ],
   "publicApiPatterns": [
-    { "id": "public_func", "regex": "\\bpublic\\s+func\\s+([A-Za-z_][A-Za-z0-9_]*)" },
-    { "id": "public_class", "regex": "\\bpublic\\s+(?:final\\s+)?class\\s+([A-Z][A-Za-z0-9_]*)" },
-    { "id": "public_struct", "regex": "\\bpublic\\s+struct\\s+([A-Z][A-Za-z0-9_]*)" },
-    { "id": "public_enum", "regex": "\\bpublic\\s+enum\\s+([A-Z][A-Za-z0-9_]*)" },
-    { "id": "public_proto", "regex": "\\bpublic\\s+protocol\\s+([A-Z][A-Za-z0-9_]*)" },
-    { "id": "public_init", "regex": "\\bpublic\\s+init\\b" },
-    { "id": "objc_export", "regex": "@objc(?:Members)?\\s+(?:public\\s+)?(?:func|class|var)" }
+    {
+      "id": "public_func",
+      "regex": "\\bpublic\\s+func\\s+([A-Za-z_][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "public_class",
+      "regex": "\\bpublic\\s+(?:final\\s+)?class\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "public_struct",
+      "regex": "\\bpublic\\s+struct\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "public_enum",
+      "regex": "\\bpublic\\s+enum\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "public_proto",
+      "regex": "\\bpublic\\s+protocol\\s+([A-Z][A-Za-z0-9_]*)"
+    },
+    {
+      "id": "public_init",
+      "regex": "\\bpublic\\s+init\\b"
+    },
+    {
+      "id": "objc_export",
+      "regex": "@objc(?:Members)?\\s+(?:public\\s+)?(?:func|class|var)"
+    }
   ],
   "swiftUiViewPatterns": [
-    { "id": "view_struct", "regex": "struct\\s+([A-Z][A-Za-z0-9_]*)\\s*:\\s*View\\b" },
-    { "id": "config_struct", "regex": "struct\\s+([A-Z][A-Za-z0-9_]*Configuration)\\b" }
+    {
+      "id": "view_struct",
+      "regex": "struct\\s+([A-Z][A-Za-z0-9_]*)\\s*:\\s*View\\b"
+    },
+    {
+      "id": "config_struct",
+      "regex": "struct\\s+([A-Z][A-Za-z0-9_]*Configuration)\\b"
+    }
   ],
   "expectedTestKindsForView": ["snapshot", "viewinspector", "unit"],
   "snapshotPathHints": ["SnapshotTests", "__Snapshots__"],

package/pipeline/scripts/test-gap-scan.mjs

@@ -42,6 +42,7 @@ import { readFileSync, existsSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { join, dirname, extname, basename } from "node:path";
 import { fileURLToPath } from "node:url";
+import { isExcludedBy } from "./_path-match.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -118,27 +119,7 @@ function loadDiff() {
 }
 
 function isExcluded(path) {
-  if (!Array.isArray(rules.excludePathGlobs)) return false;
-  for (const pat of rules.excludePathGlobs) {
-    if (pat.endsWith("/")) {
-      if (path.includes(pat) || path.startsWith(pat)) return true;
-    } else if (pat.includes("**")) {
-      // Tokenize ** before the single-* pass so the * rewrite cannot mangle
-      // the already-translated .* (which broke cross-directory matches).
-      const DOUBLE_STAR = "\u0000";
-      const re = new RegExp(
-        "^" +
-          pat
-            .replace(/\./g, "\\.")
-            .replace(/\*\*/g, DOUBLE_STAR)
-            .replace(/\*/g, "[^/]*")
-            .replace(new RegExp(DOUBLE_STAR, "g"), ".*") +
-          "$",
-      );
-      if (re.test(path)) return true;
-    } else if (path.endsWith(pat)) return true;
-  }
-  return false;
+  return isExcludedBy(path, rules.excludePathGlobs);
 }
 
 // git quotes a `diff --git` path (core.quotePath, on by default) whenever it

package/pipeline/scripts/uninstall.mjs

@@ -32,6 +32,7 @@
  *   - $HOME/.claude/multi-agent-preferences.json (pipeline settings)
  *   - $HOME/.claude/logs/multi-agent/ (task logs, state, metrics, audit trail)
  *   - $HOME/.claude/memory/multi-agent/ (per-repo learnings ledger + triage corpus)
+ *   - $HOME/.claude/knowledge/ (per-repo knowledge base + code graph)
  *
  * @module pipeline/scripts/runtime/uninstall
  */
@@ -726,6 +727,7 @@ export async function main() {
     console.log("    - ~/.claude/multi-agent-preferences.json (pipeline settings)");
     console.log("    - ~/.claude/logs/multi-agent/ (task logs, state, metrics, audit trail)");
     console.log("    - ~/.claude/memory/multi-agent/ (per-repo learnings ledger + triage corpus)");
+    console.log("    - ~/.claude/knowledge/ (per-repo knowledge base + code graph)");
     console.log("");
   }
   console.log("  PRESERVED (never touched):");
@@ -834,12 +836,19 @@ export async function main() {
   // architectural facts and past review findings written in prose about the
   // repos they were collected from. On a corporate checkout that is concrete
   // information about the codebase, and it survived even --all-data.
+  //
+  // The knowledge root is the same class of data and was missing for the same
+  // reason: architecture.md, patterns.md, gotchas.md and decisions.md are prose
+  // about a private codebase, and code-graph.json is every symbol name in it.
+  // Leaving that behind after "remove everything" is the worst version of this
+  // bug, because the graph is the most complete of the three.
   if (allData && HOME) {
     console.log("");
-    console.log("  [Full cleanup] Removing pipeline settings, logs + memory...");
+    console.log("  [Full cleanup] Removing pipeline settings, logs, memory + knowledge...");
     preservePrefsCredentialMapping(join(HOME, ".claude", "multi-agent-preferences.json"));
     rmIfExists(join(HOME, ".claude", "logs", "multi-agent"));
     rmIfExists(join(HOME, ".claude", "memory", "multi-agent"));
+    rmIfExists(join(HOME, ".claude", "knowledge"));
   }
 
   // Legacy adapter-file cleanup (adapters removed in v10.7.0). These blocks
@@ -917,7 +926,7 @@ export async function main() {
   if (!allData) {
     console.log("");
     console.log(
-      "  Kept your pipeline settings, logs + per-repo memory. To remove those too, re-run with --all-data.",
+      "  Kept your pipeline settings, logs, per-repo memory + knowledge base. To remove those too, re-run with --all-data.",
     );
   } else {
     console.log("");

package/pipeline/scripts/validate-code-graph.mjs

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// validate-code-graph.mjs  -  schema validator for graph-build.mjs output.
+//
+// Zero deps (ADR-0004). Reads JSON from path or STDIN, validates against
+// pipeline/schemas/code-graph.schema.json.
+//
+// Edge endpoints are checked against the node set, not just for type: a graph
+// whose edges point at ids no node declares still parses as valid JSON, but
+// every traversal built on it silently drops those hops.
+//
+// Exit codes:
+//   0  -  valid
+//   1  -  invalid
+//  64  -  usage error
+
+import { readFileSync } from "node:fs";
+
+const ALLOWED_STACK = new Set(["ios", "android", "node", "python", "go"]);
+const ALLOWED_NODE_KIND = new Set(["file", "symbol", "module"]);
+const ALLOWED_EDGE_KIND = new Set(["defines", "imports", "references"]);
+const MAX_REPORTED_DANGLING = 5;
+
+function readInput() {
+  const arg = process.argv[2];
+  if (!arg) {
+    console.error("error: provide a path or '-' for STDIN");
+    process.exit(64);
+  }
+  if (arg === "-") {
+    return new Promise((resolve, reject) => {
+      const chunks = [];
+      process.stdin.setEncoding("utf-8");
+      process.stdin.on("data", (c) => chunks.push(c));
+      process.stdin.on("end", () => resolve(chunks.join("")));
+      process.stdin.on("error", reject);
+    });
+  }
+  return Promise.resolve(readFileSync(arg, "utf-8"));
+}
+
+function validateStats(obj, errors) {
+  if (typeof obj.stats !== "object" || obj.stats === null || Array.isArray(obj.stats)) {
+    errors.push("stats must be an object");
+    return;
+  }
+  for (const key of ["files", "nodes", "edges"]) {
+    if (!Number.isInteger(obj.stats[key]) || obj.stats[key] < 0) {
+      errors.push(`stats.${key} must be a non-negative integer`);
+    }
+  }
+  if (Array.isArray(obj.nodes) && obj.stats.nodes !== obj.nodes.length) {
+    errors.push(
+      `stats.nodes (${obj.stats.nodes}) does not match nodes.length (${obj.nodes.length})`,
+    );
+  }
+  if (Array.isArray(obj.edges) && obj.stats.edges !== obj.edges.length) {
+    errors.push(
+      `stats.edges (${obj.stats.edges}) does not match edges.length (${obj.edges.length})`,
+    );
+  }
+}
+
+function validateNodes(obj, errors) {
+  if (!Array.isArray(obj.nodes)) {
+    errors.push("nodes must be an array");
+    return new Set();
+  }
+  const ids = new Set();
+  obj.nodes.forEach((n, i) => {
+    const p = `nodes[${i}]`;
+    if (typeof n !== "object" || n === null) {
+      errors.push(`${p} must be an object`);
+      return;
+    }
+    if (typeof n.id !== "string" || n.id.length === 0) errors.push(`${p}.id must be a string`);
+    else if (ids.has(n.id)) errors.push(`${p}.id is duplicated: ${n.id}`);
+    else ids.add(n.id);
+    if (!ALLOWED_NODE_KIND.has(n.kind))
+      errors.push(`${p}.kind must be one of ${[...ALLOWED_NODE_KIND].join(",")}`);
+    if (typeof n.name !== "string") errors.push(`${p}.name must be a string`);
+    if (!Number.isInteger(n.degree) || n.degree < 0)
+      errors.push(`${p}.degree must be a non-negative integer`);
+  });
+  return ids;
+}
+
+function validateEdges(obj, ids, errors) {
+  if (!Array.isArray(obj.edges)) {
+    errors.push("edges must be an array");
+    return;
+  }
+  const dangling = [];
+  obj.edges.forEach((e, i) => {
+    const p = `edges[${i}]`;
+    if (typeof e !== "object" || e === null) {
+      errors.push(`${p} must be an object`);
+      return;
+    }
+    if (typeof e.from !== "string") errors.push(`${p}.from must be a string`);
+    if (typeof e.to !== "string") errors.push(`${p}.to must be a string`);
+    if (!ALLOWED_EDGE_KIND.has(e.kind))
+      errors.push(`${p}.kind must be one of ${[...ALLOWED_EDGE_KIND].join(",")}`);
+    if (ids.size) {
+      if (typeof e.from === "string" && !ids.has(e.from)) dangling.push(`${p}.from -> ${e.from}`);
+      if (typeof e.to === "string" && !ids.has(e.to)) dangling.push(`${p}.to -> ${e.to}`);
+    }
+  });
+  if (dangling.length) {
+    errors.push(
+      `${dangling.length} edge endpoint(s) reference no node: ` +
+        dangling.slice(0, MAX_REPORTED_DANGLING).join("; ") +
+        (dangling.length > MAX_REPORTED_DANGLING ? "; ..." : ""),
+    );
+  }
+}
+
+function validateManifest(obj, errors) {
+  if (obj.manifest === undefined) return;
+  if (typeof obj.manifest !== "object" || obj.manifest === null || Array.isArray(obj.manifest)) {
+    errors.push("manifest must be an object");
+    return;
+  }
+  for (const [path, entry] of Object.entries(obj.manifest)) {
+    if (typeof entry !== "object" || entry === null) {
+      errors.push(`manifest["${path}"] must be an object`);
+      continue;
+    }
+    if (!Number.isInteger(entry.size) || entry.size < 0)
+      errors.push(`manifest["${path}"].size must be a non-negative integer`);
+    if (!Number.isInteger(entry.mtimeMs) || entry.mtimeMs < 0)
+      errors.push(`manifest["${path}"].mtimeMs must be a non-negative integer`);
+  }
+}
+
+export function validate(obj) {
+  const errors = [];
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj))
+    return ["root must be an object"];
+
+  if (obj.schemaVersion !== "1.0.0") errors.push(`schemaVersion must be "1.0.0"`);
+  if (!ALLOWED_STACK.has(obj.stack))
+    errors.push(`stack must be one of ${[...ALLOWED_STACK].join(",")}`);
+  if (typeof obj.root !== "string" || obj.root.length === 0)
+    errors.push("root must be a non-empty string");
+  if (typeof obj.generatedAt !== "string" || Number.isNaN(Date.parse(obj.generatedAt)))
+    errors.push("generatedAt must be an ISO 8601 timestamp");
+  if (obj.baseCommit !== undefined && obj.baseCommit !== null && typeof obj.baseCommit !== "string")
+    errors.push("baseCommit must be a string or null");
+
+  validateStats(obj, errors);
+  const ids = validateNodes(obj, errors);
+  validateEdges(obj, ids, errors);
+  validateManifest(obj, errors);
+
+  return errors;
+}
+
+(async () => {
+  const raw = await readInput();
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch (e) {
+    console.log(JSON.stringify({ ok: false, errors: [`JSON parse error: ${e.message}`] }));
+    process.exit(1);
+  }
+  const errors = validate(obj);
+  if (errors.length === 0) {
+    console.log(JSON.stringify({ ok: true, errors: [] }));
+    process.exit(0);
+  }
+  console.log(JSON.stringify({ ok: false, errors }));
+  process.exit(1);
+})();

package/pipeline/skills/.skills-index.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": "1.0.0",
-  "skillCount": 210,
+  "skillCount": 211,
   "entries": [
     {
       "name": "accessibility-compliance-accessibility-audit",
@@ -950,7 +950,7 @@
     },
     {
       "name": "multi-agent",
-      "description": "Task orchestrator: runs the full pipeline from a Jira ID or GitHub Issue URL  -  analysis → plan → TDD development → parallel review (Fable + Opus + Sonnet on Claude Code, GPT + Opus + Sonnet on Copilot CLI) → commit → log. Every step is written to agent-log.md. Use when given a Jira ID, a GitHub issue or ",
+      "description": "Task orchestrator: runs the full pipeline from a Jira ID or GitHub Issue URL  -  analysis → plan → TDD development → parallel review (Fable + Opus + Sonnet on Claude Code, GPT + Opus + Sonnet on Copilot CLI) → commit → log. Every step is written to agent-log.md. Use when given a Jira ID, a GitHub is",
       "platform": null,
       "group": "core",
       "plugin": null,
@@ -1135,6 +1135,17 @@
       "triggerPaths": [],
       "relativePath": "shared/core/multi-agent-garbage-collect/SKILL.md"
     },
+    {
+      "name": "multi-agent-graph",
+      "description": "Build and query this repo's code graph: a deterministic, LLM-free map of symbols, imports and references used to narrow Phase 1's Explore scope and to keep the knowledge base current. Read-only on code, costs no API tokens. Use when a task needs to know where something lives or what depends on it be",
+      "platform": null,
+      "group": "core",
+      "plugin": null,
+      "invokeAs": "multi-agent-graph",
+      "triggerKeywords": [],
+      "triggerPaths": [],
+      "relativePath": "shared/core/multi-agent-graph/SKILL.md"
+    },
     {
       "name": "multi-agent-help",
       "description": "Multi-agent pipeline usage guide  -  renders in EN or TR per prefs.global.outputLanguage (falls back to promptLanguage for backward compatibility). Use when asked what the pipeline can do, which mode to pick, or what a command means.",
@@ -1313,7 +1324,7 @@
     },
     {
       "name": "multi-agent-review",
-      "description": "Run parallel review on a branch diff or a Pull Request: 3 models on Claude Code (Fable + Opus + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments + approve/needs-work. With no input (interactive), lists open GitHub + Bitbucket PRs to multi-select. Use wh",
+      "description": "Run parallel review on a branch diff or a Pull Request: 3 models on Claude Code (Fable + Opus + Sonnet), 3 models on Copilot CLI (GPT + Opus + Sonnet). On PR input, posts per-finding inline comments + approve/needs-work. With no input (interactive), lists open GitHub + Bitbucket PRs to multi-select.",
       "platform": null,
       "group": "core",
       "plugin": null,