@mmerterden/multi-agent-pipeline 20.22.0 → 20.23.0

package/pipeline/multi-agent-refs/features/usage-reporting.md

@@ -70,8 +70,10 @@ registered after the stamp and `update` from an unknown version on one that
 registered before it), `v`, `vf`, `hs` (the host trees at that version) and `t`
 (the stamp time), and moves `reportedVersion` forward once the server accepted
 it. The id is derived from the version and the stamp time, so a resend replaces
-the record. It runs after a successful registration, after setup or update finds
-a token already onboarded, and after every accepted run event. The panel lists
+the record. The installer starts it, detached, right after it writes the stamps
+(`MULTI_AGENT_SKIP_USAGE_REPORT=1` turns that off); it also runs after a
+successful registration, after setup or update finds a token already onboarded,
+and after every accepted run event. The panel lists
 the records under "Kurulumlar" and keeps them out of the run counts.
 
 The panel derives a run's status from the last event it received. A run still
@@ -137,23 +139,33 @@ undo it (`decideRegistration`). So the personal account has to be reachable only
 once, at the moment of registration.
 
 `usage-register.mjs --json` reports `needsPersonalAccount: true` only when the
-machine is not pinned and no account was found at all: no gh account, no
-credential-helper token and no SSH key with access. That is the last resort.
-Setup and update then ask once (AskUserQuestion per
-`$HOME/.claude/multi-agent-refs/picker-contract.md`; label
-`Add personal account (Recommended)` / `Skip`) and offer either fix:
-
-- **gh**: note the active account (`gh api user --jq .login`), have the person
-  run the browser login for the account that holds access in their own terminal
-  (in Claude Code: `! gh auth login --hostname github.com --web`; gh keeps both
-  accounts), then switch the work account back so pull requests keep their
-  author: `gh auth switch --hostname github.com --user <the noted account>`.
-- **SSH key**: add this machine's public key (for example `~/.ssh/id_ed25519.pub`)
-  under the personal account's GitHub Settings > SSH and GPG keys. Nothing else
-  changes on the machine.
-
-Then `node "$HOME/.claude/scripts/usage-register.mjs" --refresh --json` finds
-the account and pins it. Skip leaves reporting off; the next update asks again.
+machine is not pinned, no account with access was found (no gh account, no
+credential-helper token, no SSH key) and no name was declared. Setup and update
+then ask once for the person's GitHub username (free text; Skip leaves
+reporting off) and run:
+
+```bash
+node "$HOME/.claude/scripts/usage-register.mjs" --login "$GITHUB_LOGIN" --json
+```
+
+`$GITHUB_LOGIN` is the name the person typed. `--login` keeps it as
+`usageLog.declaredLogin` and prefers it. When this
+machine can prove that account (gh, credential helper or SSH key), the proof is
+used as below. When it cannot, which is the usual case on a machine signed in
+with a work account only, the name is registered as declared: the server issues
+a token only for a collaborator (the repository owner registers with a proof),
+and marks its row `claimed:<machine>`. Later runs (the Phase 0 backstop) register a declared name
+the same way, without asking again. A name that is not a collaborator answers
+`not_collaborator` (the owner's name, `proof_required`) and is forgotten, so the
+next setup or update asks again once the repository owner has added it.
+
+A declared name never replaces a proof: it is used only when the machine proves
+no account, and never over a stored token that was issued for a proven login
+(`usageLog.registeredClaim` marks a declared one, which a later proof replaces).
+Declared registrations are run records only. The server refuses one for the
+repository owner, rate-limits each login, caps declared tokens per login apart
+from proven ones, marks their run records `claimed`, and does not accept them
+for `/multi-agent:feedback`, which needs a proven registration.
 
 ## 4. The server side
 
@@ -174,6 +186,8 @@ The proof depends on how the account was found:
   with `{ "u", "c", "ssh": { "challenge", "signature" } }` and no
   Authorization header.
 
+- **declared**: no proof. `{ "u", "c", "claim": true }`, no Authorization header.
+
 For a bearer, the server resolves the token to a GitHub login and refuses a
 mismatch. For an SSH proof, the challenge is stateless and HMAC-bound to the
 login, valid for five minutes; the server checks it, then accepts the signature
@@ -196,7 +210,8 @@ another host.
 | `401` `ssh_signature_invalid` | the signature did not verify |
 | `401` `ssh_key_not_on_account` | the key is not on that account; add its `.pub` to it |
 | `401` `ssh_key_unsupported` | the key type is not accepted; use an ed25519, rsa or ecdsa-p256 key |
-| `403` (no access) | the login needs collaborator access |
+| `403` `not_collaborator` | the login is not a collaborator; the owner adds it (a declared name is forgotten and asked for again) |
+| `403` `proof_required` | the declared name is the repository owner's, which registers only with a proof (gh or an SSH key); the name is forgotten |
 | challenge `404` / `405` | the endpoint does not accept an SSH key as proof yet |
 | signing failed | the key needs a passphrase and is not in ssh-agent: `ssh-add <key>` |
 | `accepted: false` | `declined` |
@@ -276,6 +291,8 @@ is off, it turns the switch on and says so rather than reporting "unchanged".
 
 ## 8. Where it is NOT called
 
-The installer. `install.js` lays down files and nothing else; seeding state is the
-one thing the install contract forbids, and a fresh machine has no preferences
-file for the registration to write into. Setup creates it; registration follows.
+The installer. `install.js` never registers: seeding state is the one thing the
+install contract forbids, and a fresh machine has no preferences file for the
+registration to write into. Setup creates it; registration follows. The only
+reporting the installer starts is `usage-report.mjs --lifecycle`, which sends the
+install record with a token that already resolves and registers nothing.

package/pipeline/multi-agent-refs/generate-issue.md

@@ -58,6 +58,16 @@ Each type has a standard section skeleton. `A` = always present. `C` = condition
 | | Screenshots | C | user pasted image(s) or Figma screenshot fetched |
 | | Dependencies / Notes | C | real content only |
 
+**Story panels.** Each Story section renders inside a coloured wiki panel, its `h3.` heading as the panel's first line, so testers see the story, the criteria and the rest at a glance:
+
+| Story section | Panel |
+|---|---|
+| User Story | `{panel:borderColor=#d4d39e}` |
+| Acceptance Criteria | `{panel:borderColor=#d4a19e}` |
+| Every other section | `{panel:borderColor=#9eb6d4}` |
+
+Each panel closes with `{panel}` on its own line. Task and Bug keep plain `h3.` sections.
+
 Section headings render in `outputLanguage` (e.g. tr: "Detaylı Açıklama", "Kapsam", "Kabul Kriterleri", "Test Senaryoları", "Adımlar", "Beklenen Sonuç", "Gerçekleşen Sonuç", "Ortam", "Ekran Görüntüleri", "API Contract", "Design Reference", "Notlar").
 
 ## Flow
@@ -172,7 +182,7 @@ curl -s "$SWAGGER_URL" -o /tmp/generate-issue-$$-swagger.json  # add auth header
 
 Write summary + description in `outputLanguage` from the type's **standard template** (baseline, not mined headings):
 - **Summary**: `{minedPrefix} {concise title}`, truncated to 255 chars.
-- **Description**: render the type's standard section skeleton in Jira wiki markup (`h3.` headings), applying auto-sizing:
+- **Description**: render the type's standard section skeleton in Jira wiki markup (`h3.` headings; for a Story each section inside its coloured panel, see Story panels), applying auto-sizing:
   - **Always-present** sections are filled from `FREE_TEXT` (+ mining for Test Scenarios style). If an always-present section has no user content and cannot be derived, it stays an explicit open question for step 8  -  it is not fabricated.
   - **Conditional** sections render only when their trigger fired (see the Standard templates table): Design Reference when `FIGMA_URL` set (`[Figma|{FIGMA_URL}]` + frame name + node id); API Contract when 6b produced a body; Screenshots when images were staged; Notes/Dependencies only with real content. Otherwise the heading is omitted entirely.
   - Bug: logs / stack traces / device+OS mentions from `FREE_TEXT` map into Environment and Screenshots / Logs; anything underivable becomes a step-8 question.

package/pipeline/multi-agent-refs/knowledge.md

@@ -50,6 +50,24 @@ Each task teaches the project a bit more. Token cost decreases over time.
 
 They all complement each other  -  no conflicts.
 
+### Which store a run fills without a model
+
+The four `.md` files are the one layer only a model writes: Phase 5 Step 3
+distils what the run learned into prose. Everything a run can record
+mechanically has its own store and its own Phase 1 injection:
+
+| Store | Filled by, when | Reaches Phase 1 through |
+|---|---|---|
+| `memory/multi-agent/<repo>/learnings-ledger.jsonl` | `learnings-ledger.mjs from-triage`, by `capture-flush.sh` at every phase boundary | `learnings-ledger.mjs profile` and `brief` (Step 1) |
+| `memory/multi-agent/<repo>/triage-corpus.jsonl` | `triage-memory.mjs ingest`, by `capture-flush.sh` at every phase boundary | `triage-memory.mjs query` (prior findings) |
+| `knowledge/<repo>/code-graph.json`, `GRAPH_REPORT.md` | `graph-build.mjs`, `graph-report.mjs`, in Phase 1 and after Phase 5 | `graph-query.mjs` / `graph-affected.mjs`, when `codeGraph.enabled` |
+| `knowledge/<repo>/product-context.jsonl` | `product-context.mjs record`, Phase 1 Step 1.6 | `product-context.mjs recall` (Step 1.6) |
+| repo profile | `repo-profile.mjs ensure`, Phase 1 Step 1 | `state.repoProfile` |
+
+A run that stops before Phase 5 therefore still teaches the next one; only the
+prose layer waits for a run that finishes. Generated copies of these stores in
+the `.md` files would inject the same rows twice, so none are written.
+
 ### Knowledge Maintenance
 
 Knowledge files grow over time. Maintenance rules:

package/pipeline/multi-agent-refs/phases/phase-1-plan.md

@@ -168,9 +168,9 @@ This informs:
 
 Gated by `prefs.global.repoMap.enabled` (default: `false`). When enabled, runs `$HOME/.claude/scripts/repo-map.mjs` and injects the budgeted result into each Explore prompt as `${REPO_MAP}`. Aider-style: deterministic, no embeddings, sub-second, advisory only. Full wiring (helper invocation, properties, when-to-enable): `$HOME/.claude/multi-agent-refs/features/repo-map.md`.
 
-#### Step 2.6  -  Code Graph Injection (advisory, opt-in)
+#### Step 2.6  -  Code Graph Injection (advisory)
 
-Gated by `prefs.global.codeGraph.enabled` (default: `false`). With a rule file for `detectedStack`, Phase 1 refreshes the graph and queries it; `graph-affected` feeds `analysis.touchedAreas[]`. Zero API cost, read-only. Commands and measurements: `$HOME/.claude/multi-agent-refs/features/code-graph.md`.
+Gated by `prefs.global.codeGraph.enabled` (default: `true`). With a rule file for `detectedStack`, Phase 1 refreshes the graph and queries it; `graph-affected` feeds `analysis.touchedAreas[]`. Zero API cost, read-only. Commands and measurements: `$HOME/.claude/multi-agent-refs/features/code-graph.md`.
 
 **A valid result REPLACES the opening sweep** rather than sitting beside it: Explore starts from those files and walks outward, with no broad `Glob`/`Grep` pass first - running both pays twice, and the second re-derives what the graph said. No graph (missing rule, stale, or disabled) leaves the previous behaviour untouched; a task naming a symbol or path is still grepped directly.
 

package/pipeline/schemas/code-graph.schema.json

@@ -8,8 +8,8 @@
   "additionalProperties": false,
   "properties": {
     "schemaVersion": {
-      "enum": ["1.0.0", "1.1.0"],
-      "description": "1.1.0 adds endLine on symbol nodes. A 1.0.0 graph stays readable; diff mapping falls back to file level for it."
+      "enum": ["1.0.0", "1.1.0", "1.2.0"],
+      "description": "1.1.0 adds endLine on symbol nodes; 1.2.0 adds inherits edges (subtype to supertype). Older graphs stay readable; diff mapping falls back to file level for a 1.0.0 graph."
     },
     "stack": {
       "type": "string",
@@ -81,7 +81,7 @@
         "properties": {
           "from": { "type": "string" },
           "to": { "type": "string" },
-          "kind": { "type": "string", "enum": ["defines", "imports", "references"] }
+          "kind": { "type": "string", "enum": ["defines", "imports", "references", "inherits"] }
         }
       }
     },

package/pipeline/schemas/prefs.schema.json

@@ -1273,9 +1273,14 @@
               "type": "string",
               "description": "Shared ingest token the receiving endpoint validates. May be left empty here and supplied via env MULTI_AGENT_USAGE_TOKEN instead. Local prefs only, never synced."
             },
+            "declaredLogin": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,38}$",
+              "description": "The GitHub username the person typed at setup or update (usage-register.mjs --login). Registered as declared when this machine cannot prove that account; the server issues a token only when it is a collaborator (the repository owner registers with a proof). Forgotten when the server refuses it. Local prefs only, never synced."
+            },
             "reportAs": {
               "type": "string",
-              "description": "Preferred GitHub login when more than one account is logged in to gh. It is checked first, and used only if that account can read accessRepo; otherwise the next logged-in account with access is used. Local prefs only, never synced."
+              "description": "Preferred GitHub login when more than one account is logged in to gh. usage-register.mjs --login sets it to the declared name, and removes it with that name when the server refuses the name. It is checked first, and used only if that account can read accessRepo; otherwise the next logged-in account with access is used. Local prefs only, never synced."
             },
             "accessRepo": {
               "type": "string",
@@ -1320,6 +1325,23 @@
               "type": "string",
               "description": "ISO time of the registration that issued the stored token."
             },
+            "claimNonce": {
+              "type": "string",
+              "pattern": "^[0-9a-f]{8,32}$",
+              "description": "Random suffix of the machine label a declared registration is sent with, so nobody else can name the label and replace this machine's token. Written once by usage-register.mjs."
+            },
+            "claimFailedAt": {
+              "type": "string",
+              "description": "ISO time a declared registration last failed for a reason other than a refusal of the name (rate limit, cap, endpoint down). The claim is not sent again for a day unless the name is typed again."
+            },
+            "reportAsBefore": {
+              "type": "string",
+              "description": "The reportAs a declared name replaced, put back when that name is refused."
+            },
+            "registeredClaim": {
+              "type": "boolean",
+              "description": "true when the stored token was issued for a declared login rather than a proven one. A proof found later, for any login with access, replaces it; a declared name never replaces a proven registration."
+            },
             "registeredFallback": {
               "type": "boolean",
               "description": "Deprecated (20.17.0). true marked a registration made with an account that cannot read accessRepo; it is not treated as pinned and is replaced once an account with access is found."
@@ -1520,12 +1542,12 @@
         "codeGraph": {
           "type": "object",
           "additionalProperties": false,
-          "description": "v16.1+  -  deterministic, LLM-free code graph (symbols, imports, references) built by pipeline/scripts/graph-build.mjs into ~/.claude/knowledge/<project>/code-graph.json. Phase 1 Step 2.6 queries it to narrow the Explore starting set; Phase 5 Step 3 refreshes it after the branch changed code. Zero API cost, zero runtime dependencies (ADR-0004), read-only on the repo. Off by default: with it off the pipeline behaves exactly as it did before. Measured on a 4,300-file Swift app at a fixed 30k retrieval budget, it roughly doubled coverage at under half the token cost on domain-word searches, and was marginally worse than plain grep when the task already names an exact symbol.",
+          "description": "v16.1+  -  deterministic, LLM-free code graph (symbols, imports, references) built by pipeline/scripts/graph-build.mjs into ~/.claude/knowledge/<project>/code-graph.json. Phase 1 Step 2.6 queries it to narrow the Explore starting set; Phase 5 Step 3 refreshes it after the branch changed code. Zero API cost, zero runtime dependencies (ADR-0004), read-only on the repo. On by default; with it off no graph is built or refreshed. Measured on a 4,300-file Swift app at a fixed 30k retrieval budget, it roughly doubled coverage at under half the token cost on domain-word searches, and was marginally worse than plain grep when the task already names an exact symbol.",
           "properties": {
             "enabled": {
               "type": "boolean",
-              "default": false,
-              "description": "Master switch. When false, Phase 1 Step 2.6 and the Phase 5 refresh are skipped entirely and no graph file is written."
+              "default": true,
+              "description": "Master switch, on by default. When false, Phase 1 Step 2.6 and the Phase 5 refresh are skipped and no graph is built or refreshed; a graph file already on disk is still read by Phase 3 and the analysis ranking."
             },
             "autoRefresh": {
               "type": "boolean",

package/pipeline/scripts/_code-graph.mjs

@@ -32,10 +32,11 @@ import { execFileSync } from "node:child_process";
 import { join, dirname, relative, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { isExcludedBy } from "./_path-match.mjs";
+import { supertypesAt } from "./_supertypes.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-export const GRAPH_SCHEMA_VERSION = "1.1.0";
+export const GRAPH_SCHEMA_VERSION = "1.2.0";
 
 /**
  * Stack words the pipeline uses elsewhere, mapped to the rule-file id.
@@ -107,6 +108,13 @@ export function loadRules(requested, baseDir = __dirname) {
     importSpecifiersAreStrings: graph.importSpecifiersAreStrings === true,
     ignoredIdentifiers: new Set(graph.ignoredIdentifiers || []),
     referenceKinds: new Set(graph.referenceKinds || []),
+    supertypes: graph.supertypes
+      ? {
+          syntax: graph.supertypes.syntax,
+          kinds: new Set(graph.supertypes.kinds || []),
+          extensionPattern: graph.supertypes.extensionPattern || null,
+        }
+      : null,
   };
 }
 
@@ -263,10 +271,57 @@ const OPENS_BLOCK_RE = /(?:[{:=]|=>|->)[ \t]*$/;
 const DIRECTIVE_RE = /^#(?:if|elseif|else|endif)\b/;
 const STORED_PROPERTY_RE = /\b(?:var|let|val)\b/;
 
+const ATTRIBUTE_BLOCK_MAX = 80;
+const count = (text, re) => (text.match(re) || []).length;
+const bracketBalance = (text) =>
+  count(text, /\(/g) - count(text, /\)/g) + count(text, /\[/g) - count(text, /\]/g);
+const CLOSER_ONLY_RE = /^[ \t]*[)\]]+[ \t,]*$/;
+const DECLARES_RE =
+  /\b(?:func|init|class|struct|enum|protocol|actor|extension|typealias|def|fun|interface|object|var|let|val)\b/;
+
+/** What follows an attribute's argument list on its line; empty when the list runs on. */
+function afterArguments(rest) {
+  if (!/^\s*\(/.test(rest)) return rest;
+  let depth = 0;
+  for (let i = 0; i < rest.length; i++) {
+    if (rest[i] === "(" || rest[i] === "[") depth++;
+    else if ((rest[i] === ")" || rest[i] === "]") && --depth === 0) return rest.slice(i + 1);
+  }
+  return "";
+}
+
+/**
+ * The first line of an attribute whose arguments span several lines and close
+ * right above line `start` - `@available(iOS 16,` / `macOS 13, *)`, or a
+ * bracket list closed by `)` or `])` on its own line at the declaration's
+ * indentation - or null. The block opens at the declaration's indentation,
+ * keeps every other line deeper, balances its brackets, and is never a stored
+ * property's or another declaration that merely leads with an attribute.
+ */
+function attributeBlockStart(lines, start, indent) {
+  for (let k = start - 1; k >= 1 && start - k <= ATTRIBUTE_BLOCK_MAX; k--) {
+    const text = lines[k - 1];
+    if (!text.trim()) return null;
+    if (leading(text) === indent && ATTRIBUTE_RE.test(text)) {
+      const rest = afterArguments(text.replace(/^[ \t]*@[\w.]+/, ""));
+      if (STORED_PROPERTY_RE.test(rest) || text.includes("{") || DECLARES_RE.test(rest))
+        return null;
+      return bracketBalance(lines.slice(k - 1, start - 1).join("\n")) === 0 && k < start - 1
+        ? k
+        : null;
+    }
+    if (leading(text) > indent) continue;
+    if (k === start - 1 && leading(text) === indent && CLOSER_ONLY_RE.test(text)) continue;
+    return null;
+  }
+  return null;
+}
+
 /**
  * Give every definition a span: `startLine` (the declaration line, or the first
- * of the attribute or decorator lines directly above it, never a stored
- * property) and `endLine` (the last line indented deeper than the declaration,
+ * of the attribute or decorator lines directly above it, including one whose
+ * parenthesised arguments run over several lines, never a stored property)
+ * and `endLine` (the last line indented deeper than the declaration,
  * plus a closing bracket at the declaration's own indentation when one
  * follows). A closing bracket that opens the body again - the end of a
  * multi-line parameter list, `) -> Int {`, `):`, `) : Base() {` - continues the
@@ -286,12 +341,16 @@ export function assignSpans(definitions, lines) {
     while (start > 1) {
       const above = lines[start - 2];
       if (
-        !ATTRIBUTE_RE.test(above) ||
-        leading(above) !== d.indent ||
-        STORED_PROPERTY_RE.test(above)
-      )
-        break;
-      start--;
+        ATTRIBUTE_RE.test(above) &&
+        leading(above) === d.indent &&
+        !STORED_PROPERTY_RE.test(above)
+      ) {
+        start--;
+        continue;
+      }
+      const block = attributeBlockStart(lines, start, d.indent);
+      if (!block) break;
+      start = block;
     }
     d.startLine = start;
   }
@@ -366,20 +425,34 @@ export function extractFile(text, rules) {
       const key = `${name}:${pattern.kind || pattern.id}`;
       if (seen.has(key)) continue;
       seen.add(key);
+      const kind = pattern.kind || pattern.id;
+      const st = rules.supertypes;
+      const supertypes =
+        st && st.kinds.has(kind) ? supertypesAt(body, m.index + m[0].length, st.syntax) : [];
       definitions.push({
         name,
-        kind: pattern.kind || pattern.id,
+        kind,
         patternId: pattern.id,
         line: lineOf(body, m.index),
         indent: indentOf(body, m.index),
         nested: indentOf(body, m.index) > 0,
+        ...(supertypes.length ? { supertypes } : {}),
       });
     }
   }
 
+  const conformances = [];
+  if (rules.supertypes?.extensionPattern) {
+    for (const m of body.matchAll(new RegExp(rules.supertypes.extensionPattern, "gm"))) {
+      const type = captured(m)?.split(".").pop();
+      const supertypes = supertypesAt(body, m.index + m[0].length, rules.supertypes.syntax);
+      if (type && supertypes.length) conformances.push({ type, supertypes });
+    }
+  }
+
   assignSpans(definitions, body.split("\n"));
   for (const d of definitions) delete d.indent;
-  return { definitions, imports, tokens: identifiers(body) };
+  return { definitions, imports, tokens: identifiers(body), conformances };
 }
 
 /**
@@ -399,6 +472,7 @@ export function listSourceFiles(root, rules) {
     const out = execFileSync("git", ["-C", root, "ls-files", "-z", "-co", "--exclude-standard"], {
       encoding: "utf8",
       maxBuffer: 64 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"],
     });
     candidates = out.split("\0").filter(Boolean);
   } catch {
@@ -442,7 +516,8 @@ function walkDir(dir, root, acc = []) {
  */
 export function isTestPath(path, rules) {
   if (rules.testPathSuffixes.some((s) => path.endsWith(s))) return true;
-  return rules.testPathContains.some((c) => path.includes(c));
+  const rooted = `/${path}`;
+  return rules.testPathContains.some((c) => rooted.includes(c));
 }
 
 export const fileNodeId = (path) => `file:${path}`;
@@ -546,6 +621,10 @@ export function buildGraph({
     }
   }
 
+  // Production code cannot depend on a type a test file declares, so a
+  // non-test file never gains an edge to one: a test helper named after a
+  // framework type (`protocol View` in a fake) would otherwise collect every
+  // file that mentions the framework's own.
   for (const [path, data] of extracted) {
     const fid = fileNodeId(path);
     const emitted = new Set();
@@ -556,6 +635,7 @@ export function buildGraph({
       const sid = candidates[0];
       const target = nodes.get(sid);
       if (target.path === path) continue;
+      if (target.isTest && !nodes.get(fid).isTest) continue;
       if (!rules.referenceKinds.has(target.symbolKind)) continue;
       if (emitted.has(sid)) continue;
       emitted.add(sid);
@@ -563,6 +643,35 @@ export function buildGraph({
     }
   }
 
+  // A subtype points at each supertype the graph defines once: its superclass,
+  // the protocols or interfaces it adopts, and conformances an extension adds.
+  // The file that names the supertype already references it; this edge says
+  // how, so a walk restricted to `inherits` answers "who implements this".
+  const unique = (name) => {
+    const c = symbolsByName.get(name);
+    return c && c.length === 1 ? c[0] : null;
+  };
+  const inherited = new Set();
+  const inherit = (from, superName) => {
+    const to = unique(superName);
+    const key = `${from}>${to}`;
+    if (!from || !to || from === to || inherited.has(key)) return;
+    if (nodes.get(to).isTest && !nodes.get(from).isTest) return;
+    inherited.add(key);
+    edges.push({ from, to, kind: "inherits" });
+  };
+  for (const [path, data] of extracted) {
+    for (const def of data.definitions) {
+      for (const sup of def.supertypes || []) inherit(symbolNodeId(path, def.name), sup);
+    }
+    const testFile = isTestPath(path, rules);
+    for (const c of data.conformances || []) {
+      const from = unique(c.type);
+      if (testFile && from && !nodes.get(from).isTest) continue;
+      for (const sup of c.supertypes) inherit(from, sup);
+    }
+  }
+
   for (const edge of edges) {
     if (nodes.has(edge.from)) nodes.get(edge.from).degree++;
     if (nodes.has(edge.to)) nodes.get(edge.to).degree++;

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;
 }
@@ -268,16 +267,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,133 @@
+/**
+ * @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):`
+ *   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 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") {
+    const m = /^\s*\(/.exec(header);
+    if (!m) return [];
+    const end = skipGroup(header, m[0].length - 1, "(");
+    return names(header.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);
+    for (const part of [ext?.[1], imp?.[1]])
+      if (part) for (const n of names(part)) 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, ""));
+}