@mmerterden/multi-agent-pipeline 20.22.0 → 20.23.1

package/pipeline/scripts/_diff-impact.mjs

@@ -23,14 +23,13 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { unquotePathIfNeeded } from "./git-path.mjs";
+import { diffHeaderPath } from "./git-path.mjs";
 
 const HUNK_RE = /^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/;
 
 /** The path of a `---`/`+++` line: git-quoted or not, one-letter prefix removed. */
 function sidePath(raw, prefix) {
-  const text = raw.startsWith('"') ? raw : raw.replace(/\t.*$/, "");
-  const path = unquotePathIfNeeded(text);
+  const path = diffHeaderPath(raw);
   if (path === "/dev/null") return null;
   return path.startsWith(prefix) ? path.slice(prefix.length) : path;
 }
@@ -39,7 +38,7 @@ function addLine(set, line) {
   set.add(Math.max(1, line));
 }
 
-function toRanges(lines) {
+function toRanges(lines, gaps = new Set()) {
   const sorted = [...lines].sort((a, b) => a - b);
   const out = [];
   for (const l of sorted) {
@@ -47,21 +46,28 @@ function toRanges(lines) {
     if (last && l === last.end + 1) last.end = l;
     else if (!last || l > last.end) out.push({ start: l, end: l });
   }
-  return out;
+  // A gap is a point between two lines where lines went in (or, on the new
+  // side, came out): `{start: before, end: before + 1, gap: true}`.
+  for (const before of gaps)
+    if (!sorted.includes(before) && !sorted.includes(before + 1))
+      out.push({ start: before, end: before + 1, gap: true });
+  return out.sort((a, b) => a.start - b.start);
 }
 
 /**
  * Every file of a unified diff with the lines it touched on each side.
  *
- * New side: an added line counts as itself, and a deletion as the line now
- * standing where the removed lines were. Old side: a removed line counts as
- * itself, and an insertion as the old line standing where it went in. Either way a hunk that
- * only adds or only removes still lands inside the declaration it changed.
+ * New side: an added line counts as itself, and a pure deletion as the gap
+ * between the two new lines it fell between. Old side: a removed line counts as
+ * itself, and a pure insertion as the gap between the two old lines it went in
+ * between. A gap belongs to the innermost declaration spanning both of its
+ * lines, so a hunk that only adds or only removes lands inside the declaration
+ * it changed, whatever the context size.
  * Hunks are counted from their headers, so concatenated `diff -u` output with
  * no `diff --git` lines parses too, CRLF included, at any context size.
  *
  * @param {string} diffText - unified diff
- * @returns {Array<{oldPath: string|null, newPath: string|null, oldRanges: Array<{start: number, end: number}>, newRanges: Array<{start: number, end: number}>}>}
+ * @returns {Array<{oldPath: string|null, newPath: string|null, oldRanges: Array<{start: number, end: number, gap?: boolean}>, newRanges: Array<{start: number, end: number, gap?: boolean}>}>}
  */
 export function parseDiffFiles(diffText) {
   const files = [];
@@ -71,23 +77,36 @@ export function parseDiffFiles(diffText) {
   let newLine = 0;
   let oldLeft = 0;
   let newLeft = 0;
+  // One run of -/+ lines. Its removed lines stand for it on the old side and
+  // its added lines on the new side; a run with nothing on one side is a gap
+  // there, between the lines either side of it.
+  let run = null;
+  const endRun = () => {
+    if (run && !run.removed) cur.oldGaps.add(run.oldBefore);
+    if (run && !run.added) cur.newGaps.add(run.newBefore);
+    run = null;
+  };
   for (const line of String(diffText).split("\n")) {
     const raw = line.endsWith("\r") ? line.slice(0, -1) : line;
     if (oldLeft > 0 || newLeft > 0) {
-      if (raw.startsWith("+")) {
-        addLine(cur.newLines, newLine);
-        addLine(cur.oldLines, oldLine);
-        newLine++;
-        newLeft--;
-        continue;
-      }
-      if (raw.startsWith("-")) {
-        addLine(cur.oldLines, oldLine);
-        addLine(cur.newLines, newLine);
-        oldLine++;
-        oldLeft--;
+      if (raw.startsWith("+") || raw.startsWith("-")) {
+        run = run || { oldBefore: oldLine - 1, newBefore: newLine - 1, removed: 0, added: 0 };
+        if (raw.startsWith("+")) {
+          addLine(cur.newLines, newLine);
+          run.added++;
+          newLine++;
+          newLeft--;
+        } else {
+          addLine(cur.oldLines, oldLine);
+          run.removed++;
+          oldLine++;
+          oldLeft--;
+        }
+        if (oldLeft <= 0 && newLeft <= 0) endRun();
         continue;
       }
+      if (raw.startsWith("\\")) continue;
+      endRun();
       if (raw.startsWith(" ") || raw === "") {
         oldLine++;
         newLine++;
@@ -95,7 +114,6 @@ export function parseDiffFiles(diffText) {
         newLeft--;
         continue;
       }
-      if (raw.startsWith("\\")) continue;
       oldLeft = 0;
       newLeft = 0;
     }
@@ -113,6 +131,8 @@ export function parseDiffFiles(diffText) {
         newPath: sidePath(raw.slice(4), "b/"),
         oldLines: new Set(),
         newLines: new Set(),
+        oldGaps: new Set(),
+        newGaps: new Set(),
       };
       files.push(cur);
       pendingOld = undefined;
@@ -122,12 +142,14 @@ export function parseDiffFiles(diffText) {
     if (hunk && cur) {
       const oldCount = hunk[2] === undefined ? 1 : Number(hunk[2]);
       const newCount = hunk[4] === undefined ? 1 : Number(hunk[4]);
-      oldLine = Number(hunk[1]);
-      newLine = Number(hunk[3]);
+      // An empty side names the line BEFORE the change; any other side names
+      // the change's first line.
+      oldLine = Number(hunk[1]) + (oldCount === 0 ? 1 : 0);
+      newLine = Number(hunk[3]) + (newCount === 0 ? 1 : 0);
       oldLeft = oldCount;
       newLeft = newCount;
-      if (newCount === 0) addLine(cur.newLines, newLine);
-      if (oldCount === 0) addLine(cur.oldLines, oldLine);
+      if (oldCount === 0) cur.oldGaps.add(oldLine - 1);
+      if (newCount === 0) cur.newGaps.add(newLine - 1);
     }
   }
   return files
@@ -135,8 +157,8 @@ export function parseDiffFiles(diffText) {
     .map((f) => ({
       oldPath: f.oldPath,
       newPath: f.newPath,
-      oldRanges: toRanges(f.oldLines),
-      newRanges: toRanges(f.newLines),
+      oldRanges: toRanges(f.oldLines, f.oldGaps),
+      newRanges: toRanges(f.newLines, f.newGaps),
     }));
 }
 
@@ -203,8 +225,13 @@ export function changedSymbols(graph, ranges) {
       continue;
     }
     for (const r of list) {
+      // A gap belongs to a declaration only when the lines on both sides do.
       const containing = spanned
-        .filter((s) => (s.startLine ?? s.line) <= r.end && s.endLine >= r.start)
+        .filter((s) =>
+          r.gap
+            ? (s.startLine ?? s.line) <= r.start && s.endLine >= r.end
+            : (s.startLine ?? s.line) <= r.end && s.endLine >= r.start,
+        )
         .sort((a, b) => b.line - a.line);
       if (!containing.length) {
         seeds.set(fileNode.id, fileNode);
@@ -268,16 +295,24 @@ export function graphFreshness(graph, { root = graph.root } = {}) {
 }
 
 /**
- * Which side of a diff the graph's line numbers describe. A graph that matches
+ * Which side of a diff the graph's line numbers describe. For a commit range
+ * (`range`, `<base>..<head>`) the graph's build commit decides: built at the
+ * head, the new side; at the base, the old side. Otherwise a graph that matches
  * the tree at `root` (same HEAD, no file edited since the build) describes the
  * new side; any other graph was built before the change - on the base checkout,
  * or before the edit - and its spans are old-side line numbers.
  *
  * @param {object} graph
- * @param {{root?: string}} [opts]
+ * @param {{root?: string, range?: string}} [opts]
  * @returns {"new"|"old"}
  */
 export function graphSide(graph, opts = {}) {
+  const parts = typeof opts.range === "string" ? opts.range.split("..") : [];
+  if (parts.length === 2 && opts.root && graph.baseCommit && parts.every((p) => REF_RE.test(p))) {
+    const sha = (ref) => gitOut(opts.root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+    if (sha(parts[1]) === graph.baseCommit) return "new";
+    if (sha(parts[0]) === graph.baseCommit) return "old";
+  }
   return graphFreshness(graph, opts).stale ? "old" : "new";
 }
 

package/pipeline/scripts/_supertypes.mjs

@@ -0,0 +1,146 @@
+/**
+ * @file _supertypes.mjs  -  the types a declaration header names as its parents.
+ *
+ * Reads the header text that follows a type's name in a stripped body (comments
+ * and strings already blanked) and returns the simple names of its superclass,
+ * protocols or interfaces. Three syntaxes cover the stacks the graph indexes:
+ *
+ *   colon    Swift and Kotlin: `Name<T>(ctor): A, B<X>() where ...  {`
+ *   parens   Python: `Name(A, B, metaclass=M):`, `Name[T](A):`
+ *   extends  TypeScript / JavaScript: `Name<T> extends A implements B, C {`
+ *
+ * Only names that start with a letter or underscore are kept, qualified names
+ * reduce to their last segment, and generic arguments, constructor calls and
+ * Kotlin delegation (`by impl`) are dropped. A name the graph does not define
+ * (String, Codable) simply produces no edge.
+ *
+ * Zero runtime dependencies (ADR-0004).
+ *
+ * @module pipeline/scripts/_supertypes
+ */
+
+const HEADER_MAX = 4000;
+const CALL_RE = /^\s*[A-Za-z_$][\w$.]*\s*(?:<[^()]*>)?\s*\(/;
+const OPEN = { "(": ")", "<": ">", "[": "]" };
+const CLOSE = new Set([")", ">", "]"]);
+
+/** `->` and `=>` are arrows, not the end of a generic argument list. */
+const isArrow = (text, i) => text[i] === ">" && (text[i - 1] === "-" || text[i - 1] === "=");
+
+/**
+ * The header from `start` to the `{` that opens the body (or `;`, or Python's
+ * closing `:`) at bracket depth 0, capped so a declaration with no body cannot
+ * read on into the file.
+ */
+function headerText(body, start, syntax) {
+  let depth = 0;
+  const end = Math.min(body.length, start + HEADER_MAX);
+  for (let i = start; i < end; i++) {
+    const c = body[i];
+    if (c in OPEN) depth++;
+    else if (CLOSE.has(c) && depth > 0 && !isArrow(body, i)) depth--;
+    else if (depth === 0 && (c === "{" || c === ";")) return body.slice(start, i);
+    else if (depth === 0 && syntax === "parens" && c === ":") return body.slice(start, i);
+  }
+  return body.slice(start, end);
+}
+
+/** Split on commas at bracket depth 0. */
+function splitTop(text) {
+  const parts = [];
+  let depth = 0;
+  let cur = "";
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (c in OPEN) depth++;
+    else if (CLOSE.has(c) && depth > 0 && !isArrow(text, i)) depth--;
+    if (c === "," && depth === 0) {
+      parts.push(cur);
+      cur = "";
+    } else cur += c;
+  }
+  parts.push(cur);
+  return parts;
+}
+
+/** Skip one balanced bracket group starting at `i` when `text[i]` is `open`. */
+function skipGroup(text, i, open) {
+  if (text[i] !== open) return i;
+  const close = OPEN[open];
+  let depth = 0;
+  for (let j = i; j < text.length; j++) {
+    if (text[j] === open) depth++;
+    else if (text[j] === close && !isArrow(text, j) && --depth === 0) return j + 1;
+  }
+  return text.length;
+}
+
+function simpleName(raw) {
+  const item = raw.replace(/^\s*(?:@[\w.]+(?:\([^)]*\))?\s*)+/, "").replace(/`/g, "");
+  const m = /^\s*(?:out\s+|in\s+)?([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)/.exec(item);
+  if (!m || item.includes("=")) return null;
+  return m[1].split(".").pop();
+}
+
+function names(list) {
+  const out = [];
+  for (const item of splitTop(list)) {
+    const n = simpleName(item);
+    if (n && !out.includes(n)) out.push(n);
+  }
+  return out;
+}
+
+/**
+ * @param {string} body - stripped source
+ * @param {number} start - offset just past the declared name
+ * @param {"colon"|"parens"|"extends"} syntax
+ * @returns {string[]} simple supertype names, in header order
+ */
+export function supertypesAt(body, start, syntax) {
+  const header = headerText(body, start, syntax);
+  if (syntax === "parens") {
+    let k = 0;
+    while (k < header.length && /\s/.test(header[k])) k++;
+    // PEP 695 type parameters come before the bases: `class Box[T](Base):`.
+    const rest = header.slice(skipGroup(header, k, "["));
+    const m = /^\s*\(/.exec(rest);
+    if (!m) return [];
+    const end = skipGroup(rest, m[0].length - 1, "(");
+    return names(rest.slice(m[0].length, end - 1));
+  }
+  if (syntax === "extends") {
+    let k = 0;
+    while (k < header.length && /\s/.test(header[k])) k++;
+    const rest = header.slice(skipGroup(header, k, "<"));
+    const out = [];
+    const ext = /\bextends\s+([\s\S]*?)(?=\bimplements\b|$)/.exec(rest);
+    const imp = /\bimplements\s+([\s\S]*)$/.exec(rest);
+    // A base built by a call (`extends mixin(Base)`) is the call's result,
+    // which names no type the graph can point at.
+    for (const part of [ext?.[1], imp?.[1]])
+      if (part)
+        for (const n of names(
+          splitTop(part)
+            .filter((p) => !CALL_RE.test(p))
+            .join(","),
+        ))
+          if (!out.includes(n)) out.push(n);
+    return out;
+  }
+  let i = 0;
+  while (i < header.length && /\s/.test(header[i])) i++;
+  i = skipGroup(header, i, "<");
+  let j = i;
+  while (j < header.length && /\s/.test(header[j])) j++;
+  const ctor =
+    /^(?:@[A-Za-z_][\w.]*(?:\([^)]*\))?\s+)*(?:(?:private|protected|internal|public)\s+)?constructor\s*/.exec(
+      header.slice(j),
+    );
+  if (ctor) j += ctor[0].length;
+  j = skipGroup(header, j, "(");
+  while (j < header.length && /\s/.test(header[j])) j++;
+  if (header[j] !== ":") return [];
+  const list = header.slice(j + 1).split(/\bwhere\b/)[0];
+  return names(list.replace(/\bby\s+[^,]*/g, ""));
+}

package/pipeline/scripts/analysis-story-body.mjs

@@ -16,6 +16,11 @@ import { escapeJiraWiki, wikiLink } from "./jira-wiki-escape.mjs";
 import { redesignSections } from "../lib/analysis-sections.mjs";
 
 const MAX_CRITERIA = 8;
+
+// Panel border colours of a story section, the ones testers read stories in:
+// the user story, the acceptance criteria, and every other section.
+const PANEL = { story: "#d4d39e", criteria: "#d4a19e", info: "#9eb6d4" };
+const panel = (colour, lines) => [`{panel:borderColor=${colour}}`, ...lines, "{panel}", ""];
 const MAX_DESIGN_LINKS = 5;
 
 // A criterion that describes a refusal, an error or an alternative path. One is
@@ -152,19 +157,30 @@ function linksOf(story, lines, ctx) {
 
 function render({ userStory, acceptance, currentVsTarget, links }, sourceIds) {
   const out = [];
-  if (userStory) out.push("h3. User story", escapeJiraWiki(userStory), "");
+  if (userStory) out.push(...panel(PANEL.story, ["h3. User story", escapeJiraWiki(userStory)]));
   if (acceptance.length) {
-    out.push("h3. Acceptance criteria", ...acceptance.map((a) => `# ${escapeJiraWiki(a)}`), "");
+    out.push(
+      ...panel(PANEL.criteria, [
+        "h3. Acceptance criteria",
+        ...acceptance.map((a) => `# ${escapeJiraWiki(a)}`),
+      ]),
+    );
   }
   if (currentVsTarget.length) {
-    out.push("h3. Current vs target", "||Id||Status||Where||");
-    for (const r of currentVsTarget) {
-      out.push(`|${escapeJiraWiki(r.id)}|${escapeJiraWiki(r.status)}|${escapeJiraWiki(r.where)}|`);
-    }
-    out.push("");
+    out.push(
+      ...panel(PANEL.info, [
+        "h3. Current vs target",
+        "||Id||Status||Where||",
+        ...currentVsTarget.map(
+          (r) => `|${escapeJiraWiki(r.id)}|${escapeJiraWiki(r.status)}|${escapeJiraWiki(r.where)}|`,
+        ),
+      ]),
+    );
   }
   if (links.length) {
-    out.push("h3. Links", ...links.map((l) => `* ${wikiLink(l.label, l.url)}`), "");
+    out.push(
+      ...panel(PANEL.info, ["h3. Links", ...links.map((l) => `* ${wikiLink(l.label, l.url)}`)]),
+    );
   }
   out.push(
     `Sources: ${escapeJiraWiki(sourceIds.length ? sourceIds.join(", ") : "derived from the section heading")}`,

package/pipeline/scripts/analysis-story-tree.mjs

@@ -153,7 +153,7 @@ export function identityLabel(prefix, docId, sourceIds) {
  *   issueTree.projectKey         where the tree is created
  *   issueTree.epicIssueType      the type name for an epic on this site
  *   issueTree.storyIssueType     the type name for a story
- *   issueTree.subtaskIssueType   null = discover from createmeta
+ *   issueTree.subtaskIssueType   a name, a {role: name} map, or null = discover
  *   issueTree.subtaskRoles       how a story is split; ships empty on purpose
  *   issueTree.channelComponents  channel -> this site's component name
  *   issueTree.channelTeams       channel -> this site's team name
@@ -195,6 +195,17 @@ function readPrefs() {
   }
 }
 
+/**
+ * The sub-task type a role is created as, from issueTree.subtaskIssueType: a
+ * name for every role, or a {role: name} map with "*" for any other role. Null
+ * means the writer discovers it from the site.
+ */
+export function subtaskTypeFor(setting, role) {
+  if (typeof setting === "string" && setting) return setting;
+  if (setting && typeof setting === "object") return setting[role] ?? setting["*"] ?? null;
+  return null;
+}
+
 /** Every open placeholder that makes a document unfit to become work. */
 export function openItems(text) {
   const found = [];
@@ -557,7 +568,10 @@ async function main() {
       for (const line of s.description.split("\n")) process.stdout.write(`        ${line}\n`);
     }
     for (const t of s.subtasks) {
-      process.stdout.write(`      subtask  ${t.role}  [${t.label}]\n`);
+      const type = subtaskTypeFor(result.prefsUsed.subtaskIssueType, t.role);
+      process.stdout.write(
+        `      subtask  ${t.role}  type ${type ?? "discovered from createmeta"}  [${t.label}]\n`,
+      );
     }
     for (const c of s.clones || []) {
       process.stdout.write(

package/pipeline/scripts/capture-flush.sh

@@ -66,7 +66,10 @@ LOGS="${LOGS_ROOT:-$HOME/.claude/logs/multi-agent}"
 SCRIPTS="$HOME/.claude/scripts"
 [ -d "$SCRIPTS" ] || SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
 
-say() { [ "$QUIET" -eq 1 ] && return 0; printf '%s\n' "$1"; }
+say() {
+  [ "$QUIET" -eq 1 ] && return 0
+  if [ "$JSON" -eq 1 ]; then printf '%s\n' "$1" >&2; else printf '%s\n' "$1"; fi
+}
 
 # Resolve the run to flush.
 #

package/pipeline/scripts/code-graph-rules/android.json

@@ -51,6 +51,7 @@
     }
   ],
   "referenceKinds": ["class", "interface", "object", "enum", "record", "typealias"],
+  "supertypes": { "syntax": "colon", "kinds": ["class", "interface", "object", "enum"] },
   "referenceKindsNote": "fun is deliberately absent, for the reason Swift's rules record for func: a bare lowercase name matched across files is almost never a call to that exact declaration, and on a large app the generic ones (invoke, build, create, get) take the top god-node slots purely because each happened to be declared once. Composables are the tempting exception - they are capitalised and behave like types - but they are declared with fun, so including them means including every other fun with them.",
   "ignoredIdentifiers": [
     "this",

package/pipeline/scripts/code-graph-rules/ios.json

@@ -47,10 +47,15 @@
   "importPatterns": [
     {
       "id": "import",
-      "regex": "^\\s*import\\s+(?:class|struct|enum|protocol|func|var|let|typealias)\\s+([A-Za-z_][A-Za-z0-9_]*)|^\\s*import\\s+([A-Za-z_][A-Za-z0-9_]*)"
+      "regex": "^\\s*(?:@[A-Za-z_]\\w*(?:\\([^)\\n]*\\))?\\s+)*import\\s+(?:class|struct|enum|protocol|func|var|let|typealias)\\s+([A-Za-z_][A-Za-z0-9_]*)|^\\s*(?:@[A-Za-z_]\\w*(?:\\([^)\\n]*\\))?\\s+)*import\\s+([A-Za-z_][A-Za-z0-9_]*)"
     }
   ],
   "referenceKinds": ["class", "struct", "enum", "protocol", "actor", "typealias"],
+  "supertypes": {
+    "syntax": "colon",
+    "kinds": ["class", "struct", "enum", "protocol", "actor"],
+    "extensionPattern": "\\bextension\\s+([A-Z][A-Za-z0-9_.]*)"
+  },
   "referenceKindsNote": "func is deliberately absent. A bare lowercase method name matched across files is almost never a call to that exact declaration: on a large Swift app `with`, `size`, `name`, `image` and `model` took the top god-node slots purely because each happened to be declared in exactly one file. Functions still reach the graph through their `defines` edge, so they stay findable by name.",
   "ignoredIdentifiers": [
     "self",

package/pipeline/scripts/code-graph-rules/node.json

@@ -46,6 +46,7 @@
     }
   ],
   "referenceKinds": ["class", "interface", "type", "enum", "const"],
+  "supertypes": { "syntax": "extends", "kinds": ["class", "interface"] },
   "referenceKindsNote": "function is deliberately absent, for the reason Swift's rules record for func: a bare name matched across files is almost never a call to that exact declaration, and the generic ones (run, main, get, parse, handler) would take the top god-node slots purely because each happened to be declared once. Functions still reach the graph through their defines edge, so they stay findable by name. const is present but narrowed to an uppercase-initial declaration at column 0, which is what a component, a singleton or an exported table looks like; a lowercase const is a local and is not a declaration anyone references across files. Measured on this repo (126 sources): including function put `ok` at degree 52, `f` at 38, `tokens` at 15 and `arg` at 12 - local helper names that happen to be declared exactly once, so the ambiguity rule does not catch them either. Excluding it leaves a thin symbol layer, and that is the honest shape of this stack: a JavaScript module's exported unit is usually a function, so the useful graph here is the import graph between files. `graph-affected \"<file>.mjs\"` answers who imports a module, which is the question this stack actually gets asked.",
   "ignoredIdentifiers": [
     "this",

package/pipeline/scripts/code-graph-rules/python.json

@@ -30,6 +30,7 @@
     }
   ],
   "referenceKinds": ["class"],
+  "supertypes": { "syntax": "parens", "kinds": ["class"] },
   "referenceKindsNote": "def is deliberately absent, for the reason Swift's rules record for func and the node rules record with measurements: a bare lowercase name matched across files is almost never a call to that exact declaration, and Python's convention of short module-level helpers (main, run, load, parse, setup) makes it worse than most. Functions still reach the graph through their defines edge, so they stay findable by name.",
   "ignoredIdentifiers": [
     "self",

package/pipeline/scripts/git-path.mjs

@@ -61,3 +61,24 @@ export function unquotePathIfNeeded(s) {
   }
   return s;
 }
+
+/**
+ * The path a `---` or `+++` diff header names (the text after that marker): a
+ * quoted path ends at its closing quote, which git may follow with a tab, and
+ * an unquoted one ends at a tab.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function diffHeaderPath(text) {
+  if (text.startsWith('"')) {
+    for (let i = 1; i < text.length; i++) {
+      if (text[i] === "\\") {
+        i++;
+        continue;
+      }
+      if (text[i] === '"') return unquoteGitPath(text.slice(1, i));
+    }
+  }
+  return text.replace(/\t.*$/, "");
+}

package/pipeline/scripts/graph-affected.mjs

@@ -171,7 +171,8 @@ function runDiff(flags, graph, depth, kinds) {
     text = diffFor(root, flags.diff);
   }
   const freshness = graphFreshness(graph, { root });
-  const side = graphSide(graph, { root });
+  const range = flags["diff-file"] && flags["diff-file"] !== true ? undefined : flags.diff;
+  const side = graphSide(graph, { root, range });
   const mapped = changedSymbols(graph, parseHunkRanges(text, side));
   const hits = affected({ graph, seeds: mapped.seeds, depth, kinds });
   const result = {

package/pipeline/scripts/graph-confirm.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+/**
+ * @file graph-confirm.mjs  -  a name-based blast radius, checked by a language server.
+ *
+ * The code graph joins files to declarations by name, so a dependent it lists
+ * may only share a name with the changed type, and a dependent behind an
+ * ambiguous name is missing. The toolkit's `code_references` answers the same
+ * question semantically when the project has an index. This merges the two
+ * without trusting either blindly:
+ *
+ *   confirmed  a direct dependent the server also found
+ *   name-only  a direct dependent a ready semantic index did not find
+ *   unchecked  a deeper ring the server did not name (it depends on an
+ *              intermediate declaration), or no answer could check it
+ *
+ * A deeper ring the server names directly is confirmed too.
+ *
+ * `lspOnly` lists files the server found that the graph did not. Only a result
+ * with `semantic: true` and `indexReady: true` confirms or demotes anything; a
+ * fallback answer or an index still building leaves every file unchecked,
+ * because "not found" from an unready index is not evidence.
+ *
+ * Inputs:
+ *   --affected <path>    graph-affected --json output
+ *   --references <path>  JSON array of code_references results, one per changed type
+ *   --root <path>        repository root the server's absolute paths are under
+ *
+ * Exit codes: 0 answered, 64 usage error.
+ *
+ * Zero runtime dependencies (ADR-0004).
+ *
+ * @module pipeline/scripts/graph-confirm
+ */
+
+import { readFileSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { invokedDirectly } from "../lib/invoked-directly.mjs";
+
+/**
+ * @param {{affected: Array<{path: string|null, dist: number}>}} affectedDoc
+ * @param {Array<{semantic?: boolean, indexReady?: boolean, results?: Array<{file: string}>}>} references
+ * @param {{root: string}} opts
+ */
+export function confirmImpact(affectedDoc, references, { root }) {
+  const usable = (references || []).filter(
+    (r) => r && r.semantic === true && r.indexReady === true,
+  );
+  const checked = usable.length > 0 && usable.length === (references || []).length;
+  const real = (p) => {
+    const abs = resolve(p);
+    try {
+      return realpathSync(abs);
+    } catch {
+      const parent = dirname(abs);
+      return parent === abs ? abs : join(real(parent), basename(abs));
+    }
+  };
+  const repo = real(root);
+  // A server answers with paths relative to its own workspace root (the
+  // nearest package), absolute ones through whatever spelling of a symlinked
+  // directory it was given, and files outside the repository (SDKs).
+  const rel = (file, serverRoot) => {
+    const abs = isAbsolute(file) ? file : resolve(serverRoot || root, file);
+    const r = relative(repo, real(abs));
+    return r && !r.startsWith("..") && !isAbsolute(r) ? r : null;
+  };
+  const found = new Set();
+  for (const r of usable)
+    for (const loc of r.results || []) {
+      const f = loc?.file ? rel(loc.file, r.root) : null;
+      if (f) found.add(f);
+    }
+
+  const seedPaths = new Set((affectedDoc.changedSymbols || []).map((c) => c.path).filter(Boolean));
+  for (const id of affectedDoc.seeds || []) {
+    const s = String(id);
+    if (s.startsWith("sym:")) seedPaths.add(s.slice(4, s.lastIndexOf("#")));
+    else if (s.startsWith("file:")) seedPaths.add(s.slice(5));
+  }
+  const graphPaths = new Set();
+  const affected = (affectedDoc.affected || []).map((row) => {
+    if (row.path) graphPaths.add(row.path);
+    let confirmation = "unchecked";
+    if (checked && row.path && found.has(row.path)) confirmation = "confirmed";
+    else if (checked && row.dist === 1 && row.path) confirmation = "name-only";
+    return { ...row, confirmation };
+  });
+
+  const lspOnly = checked
+    ? [...found].filter((f) => !graphPaths.has(f) && !seedPaths.has(f)).sort()
+    : [];
+  const byPath = new Map();
+  for (const a of affected) if (a.path && !byPath.has(a.path)) byPath.set(a.path, a.confirmation);
+  const count = (c) => [...byPath.values()].filter((v) => v === c).length;
+  return {
+    affected,
+    lspOnly,
+    summary: {
+      confirmed: count("confirmed"),
+      nameOnly: count("name-only"),
+      unchecked: count("unchecked"),
+      lspOnly: lspOnly.length,
+      checked,
+    },
+  };
+}
+
+function flag(argv, name) {
+  const i = argv.indexOf(name);
+  const v = i >= 0 ? argv[i + 1] : undefined;
+  return v && !v.startsWith("--") ? v : null;
+}
+
+function main(argv) {
+  const affectedPath = flag(argv, "--affected");
+  const referencesPath = flag(argv, "--references");
+  const root = flag(argv, "--root");
+  if (!affectedPath || !referencesPath || !root) {
+    process.stderr.write(
+      "usage: graph-confirm.mjs --affected <json> --references <json> --root <path>\n",
+    );
+    process.exitCode = 64;
+    return;
+  }
+  let affectedDoc;
+  let references;
+  try {
+    affectedDoc = JSON.parse(readFileSync(affectedPath, "utf8"));
+    references = JSON.parse(readFileSync(referencesPath, "utf8"));
+  } catch (e) {
+    process.stderr.write(`graph-confirm: ${e.message}\n`);
+    process.exitCode = 64;
+    return;
+  }
+  if (!Array.isArray(references)) references = [references];
+  process.stdout.write(`${JSON.stringify(confirmImpact(affectedDoc, references, { root }))}\n`);
+}
+
+if (invokedDirectly(import.meta.url)) main(process.argv.slice(2));