@renzrollon/interlock 1.5.0 → 1.6.0

package/lib/coverage.mjs

@@ -0,0 +1,387 @@
+// The coverage reader — what an lcov report says about a whole project and about
+// the lines one change added.
+//
+// Nothing in the codebase read a coverage report before this: `coverage.report_path`
+// was written into a profile and consumed by nothing, and the verify agent's
+// result carried no figures, so the merge verdict's coverage signal had no
+// producer. This module is the pure half of that producer. The CLI owns git, the
+// filesystem and the clock (`interlock verify baseline`, `interlock verify
+// coverage`); every function here takes text or plain objects and returns plain
+// objects. No fs, no git, no clock.
+//
+// One thing the figures cannot say is what the report never saw. A report lists
+// the files the tests loaded, so a new source file no test loads is absent from
+// it, and its lines count neither for nor against any figure: the change that
+// most needs the signal would read "nothing to judge". `unreportedChangedSource`
+// names those files, from the report and the diff alone, and the coverage input
+// carries them so the verdict can say so (design D13 of
+// label-and-harden-the-merge-verdict). The changed-line figure itself is
+// unchanged: it still counts only lines the report instruments.
+//
+// The one thing worth being strict about is the path. An lcov `SF:` line is
+// spelt however the tool that wrote it felt like — `./lib/a.mjs`, an absolute
+// path, a path relative to the directory the report sits in — and a diff hunk
+// names `lib/a.mjs`. Matching the first against the second by string would give
+// "no changed lines" for a file that is fully covered, which reads exactly like
+// a change that touched no code. So every record is resolved to a repository-
+// relative path through `canonicalizePath` before anything is matched, and a
+// record that resolves outside the repository is counted and dropped, never
+// guessed at. design D2 of judge-against-base-and-living-specs.
+
+import { isCoverableSource } from './artifacts.mjs'
+import { canonicalizePath } from './risk.mjs'
+
+/** The identifier a coverage baseline file carries. */
+export const BASELINE_SCHEMA = 'interlock.coverage-baseline/1'
+
+/** Percentages round to one decimal, as `judgeCoverageResult` does. */
+function pct(numerator, denominator) {
+  if (!(denominator > 0)) return null
+  return Math.round((numerator / denominator) * 1000) / 10
+}
+
+/**
+ * Lexically normalise a slash-separated path: collapse `.`, `..` and repeated
+ * separators. Keeps a leading `/` or a `C:` drive prefix; a `..` that would climb
+ * above the start of a relative path is kept, so the caller can see it escaped.
+ */
+function lexical(path) {
+  const slashed = path.replace(/\\/g, '/')
+  const drive = slashed.match(/^[a-zA-Z]:(?=\/)/)?.[0] ?? ''
+  const body = drive ? slashed.slice(drive.length) : slashed
+  const absolute = body.startsWith('/')
+  const out = []
+  for (const segment of body.split('/')) {
+    if (!segment || segment === '.') continue
+    if (segment === '..') {
+      if (out.length && out[out.length - 1] !== '..') out.pop()
+      else if (!absolute) out.push('..')
+      continue
+    }
+    out.push(segment)
+  }
+  return `${drive}${absolute ? '/' : ''}${out.join('/')}`
+}
+
+const isAbsolute = path => path.startsWith('/') || /^[a-zA-Z]:\//.test(path)
+
+/**
+ * Resolve one `SF:` value to a canonical repository-relative path, or null when
+ * it lies outside the repository. A relative value is read against `reportDir`
+ * (the directory a profile's `report_path` is relative to), an absolute one
+ * against nothing.
+ */
+function resolveSourceFile(sf, root, reportDir) {
+  const given = sf.trim().replace(/\\/g, '/')
+  if (!given) return null
+  const absolute = lexical(isAbsolute(given) ? given : `${reportDir}/${given}`)
+  const base = lexical(root).replace(/\/+$/, '')
+  // `base + '/'` is the boundary: /work/repo-other shares a name prefix with
+  // /work/repo and is not inside it.
+  if (!absolute.startsWith(`${base}/`)) return null
+  return canonicalizePath(absolute.slice(base.length + 1))
+}
+
+/**
+ * Parse an lcov report into per-file records.
+ *
+ * A record is `{ path, lines: Map<line, hits>, lf, lh }`. `lf`/`lh` are the
+ * report's own LF/LH summary when the record carries one, and are counted from
+ * its DA lines otherwise. A path listed twice is one record, its DA hits summed.
+ * `outsideRoot` counts the records that resolved outside the repository: they
+ * are not kept and take no part in any figure.
+ *
+ * @param {string} text
+ * @param {{ root: string, reportDir?: string }} opts
+ * @returns {{ records: Array<{path: string, lines: Map<number, number>, lf: number, lh: number}>, outsideRoot: number }}
+ */
+export function parseLcov(text, { root, reportDir } = {}) {
+  const dir = reportDir || root
+  const byPath = new Map()
+  let outsideRoot = 0
+  let current = null // { path|null, lines, lf, lh } for the record being read
+
+  const finish = () => {
+    if (!current) return
+    const done = current
+    current = null
+    if (done.path === null) {
+      outsideRoot += 1
+      return
+    }
+    const existing = byPath.get(done.path)
+    if (!existing) {
+      byPath.set(done.path, done)
+      return
+    }
+    for (const [line, hits] of done.lines) existing.lines.set(line, (existing.lines.get(line) ?? 0) + hits)
+    // Two reports of one file: the summaries no longer describe the union, so
+    // both are dropped and the totals are counted from the merged lines.
+    existing.lf = null
+    existing.lh = null
+  }
+
+  for (const raw of String(text ?? '').split(/\r?\n/)) {
+    const line = raw.trim()
+    if (!line) continue
+    if (line.startsWith('SF:')) {
+      finish()
+      current = {
+        path: resolveSourceFile(line.slice(3), root, dir),
+        lines: new Map(),
+        lf: null,
+        lh: null
+      }
+    } else if (!current) {
+      continue
+    } else if (line.startsWith('DA:')) {
+      const [lineNo, hits] = line.slice(3).split(',')
+      const n = Number(lineNo)
+      const h = Number(hits)
+      if (Number.isInteger(n) && n > 0 && Number.isFinite(h)) {
+        current.lines.set(n, (current.lines.get(n) ?? 0) + h)
+      }
+    } else if (line.startsWith('LF:')) {
+      const n = Number(line.slice(3))
+      if (Number.isInteger(n) && n >= 0) current.lf = n
+    } else if (line.startsWith('LH:')) {
+      const n = Number(line.slice(3))
+      if (Number.isInteger(n) && n >= 0) current.lh = n
+    } else if (line === 'end_of_record') {
+      finish()
+    }
+  }
+  finish() // a report truncated before its last end_of_record
+
+  const records = [...byPath.values()].map(rec => {
+    const counted = [...rec.lines.values()]
+    return {
+      path: rec.path,
+      lines: rec.lines,
+      lf: rec.lf ?? counted.length,
+      lh: rec.lh ?? counted.filter(hits => hits > 0).length
+    }
+  })
+  return { records, outsideRoot }
+}
+
+/**
+ * The project total over every record. `totalPct` is null when no line is
+ * instrumented — a report with nothing in it has no percentage, and zero would
+ * read as "tested nothing".
+ *
+ * @param {Array<{lf: number, lh: number}>} records
+ * @returns {{ totalPct: number|null, lf: number, lh: number }}
+ */
+export function coverageTotals(records) {
+  let lf = 0
+  let lh = 0
+  for (const rec of Array.isArray(records) ? records : []) {
+    lf += rec.lf
+    lh += rec.lh
+  }
+  return { totalPct: pct(lh, lf), lf, lh }
+}
+
+const HUNK = /^@@ -\d+(?:,(\d+))? \+(\d+)(?:,(\d+))? @@/
+
+/** The path a `+++ ` header names, or null for a deletion or an unusable name. */
+function newSidePath(header) {
+  let name = header.slice(4).replace(/\t.*$/, '').trim()
+  if (name === '/dev/null') return null
+  if (name.startsWith('"') && name.endsWith('"') && name.length >= 2) {
+    // git quotes a path with unusual bytes; unescape what a repository path can carry.
+    name = name.slice(1, -1).replace(/\\(["\\])/g, '$1')
+  }
+  if (!name.startsWith('b/')) return null
+  return canonicalizePath(name.slice(2))
+}
+
+/**
+ * The lines a diff adds, by new-side path, from `git diff -U0 --no-color
+ * --no-ext-diff <base>...HEAD`. A rename lands on its new path; a deletion
+ * (`+++ /dev/null`) adds nothing and is not a key; a pure-deletion hunk
+ * (`+start,0`) adds nothing.
+ *
+ * A hunk is read by its own counts, so an added line whose content begins `++ `
+ * (which looks like a `+++ ` header) is not mistaken for one.
+ *
+ * @param {string} diffText
+ * @returns {Map<string, Set<number>>}
+ */
+export function parseAddedLines(diffText) {
+  const added = new Map()
+  let path = null
+  let remOld = 0
+  let remNew = 0
+  let next = 0
+
+  for (const line of String(diffText ?? '').split('\n')) {
+    if (remOld > 0 || remNew > 0) {
+      if (line.startsWith('\\')) continue // ""
+      if (remOld > 0 && line.startsWith('-')) {
+        remOld -= 1
+        continue
+      }
+      if (remNew > 0 && line.startsWith('+')) {
+        remNew -= 1
+        if (path !== null) {
+          if (!added.has(path)) added.set(path, new Set())
+          added.get(path).add(next)
+        }
+        next += 1
+        continue
+      }
+      // A hunk that ends early (a truncated diff): fall through to the headers.
+      remOld = 0
+      remNew = 0
+    }
+    if (line.startsWith('diff --git ')) {
+      path = null
+    } else if (line.startsWith('+++ ')) {
+      path = newSidePath(line)
+    } else {
+      const hunk = line.match(HUNK)
+      if (hunk) {
+        remOld = hunk[1] === undefined ? 1 : Number(hunk[1])
+        remNew = hunk[3] === undefined ? 1 : Number(hunk[3])
+        next = Number(hunk[2])
+      }
+    }
+  }
+  return added
+}
+
+/**
+ * Coverage of the lines a change added. An added line counts only if the report
+ * instruments it (a DA record exists): a comment, a blank line or a line in a
+ * file the report never saw is not a "changed line", so it can neither pass nor
+ * fail the figure. `diffPct` is null when no added line is measured — absent,
+ * never 100 and never 0.
+ *
+ * @param {Array<{path: string, lines: Map<number, number>}>} records
+ * @param {Map<string, Set<number>>} added
+ * @returns {{ changedLines: number, coveredLines: number, diffPct: number|null }}
+ */
+export function changedLineCoverage(records, added) {
+  const byPath = new Map((Array.isArray(records) ? records : []).map(rec => [rec.path, rec]))
+  let changedLines = 0
+  let coveredLines = 0
+  for (const [path, lines] of added instanceof Map ? added : []) {
+    const rec = byPath.get(path)
+    if (!rec) continue
+    for (const line of lines) {
+      if (!rec.lines.has(line)) continue
+      changedLines += 1
+      if (rec.lines.get(line) > 0) coveredLines += 1
+    }
+  }
+  return { changedLines, coveredLines, diffPct: pct(coveredLines, changedLines) }
+}
+
+/**
+ * The changed source files a report does not list: the files the diff adds at
+ * least one line to, that the project counts as coverable source (never a test,
+ * a configuration file or a document), and that the report holds no record for.
+ * `files` is in path order; `addedLines` is the lines the diff adds in them.
+ *
+ * A report cannot tell a file no test loaded from one the project left out of
+ * coverage on purpose, so this names and never judges.
+ *
+ * @param {Array<{path: string}>} records
+ * @param {Map<string, Set<number>>} added
+ * @returns {{ files: string[], addedLines: number }}
+ */
+export function unreportedChangedSource(records, added) {
+  const reported = new Set((Array.isArray(records) ? records : []).map(rec => rec.path))
+  const files = []
+  let addedLines = 0
+  for (const [path, lines] of added instanceof Map ? added : []) {
+    const count = lines instanceof Set ? lines.size : 0
+    if (!count || reported.has(path) || !isCoverableSource(path)) continue
+    files.push(path)
+    addedLines += count
+  }
+  files.sort()
+  return { files, addedLines }
+}
+
+/**
+ * The coverage input the merge verdict reads: exactly the nine fields
+ * `readCoverage` consumes, and nothing else. Seven are figures; `unreportedFiles`
+ * and `unreportedAddedLines` name the changed source the report does not list.
+ * They are null when coverage is not configured and when the caller did not
+ * hand them in: not stated is never an empty list.
+ *
+ * With no coverage configured every figure is null. With no baseline every base
+ * field is null and the head and changed-line figures remain. A baseline whose
+ * commit is not an ancestor of the head is passed through marked
+ * `baseIsAncestor: false` — dropped it would read as "no baseline", and banded
+ * it would judge a change against code it never descended from; the reader
+ * decides what that means.
+ *
+ * @param {{
+ *   configured: boolean,
+ *   head?: { totalPct: number|null }|null,
+ *   baseline?: { sha: string, totalPct: number }|null,
+ *   baseIsAncestor?: boolean|null,
+ *   changed?: { changedLines: number, diffPct: number|null }|null,
+ *   unreported?: { files: string[], addedLines: number }|null
+ * }} parts
+ */
+export function buildCoverageInput({ configured, head, baseline, baseIsAncestor, changed, unreported } = {}) {
+  if (configured !== true) {
+    return {
+      configured: false,
+      headTotalPct: null,
+      baseTotalPct: null,
+      baseSha: null,
+      baseIsAncestor: null,
+      diffPct: null,
+      changedLines: null,
+      unreportedFiles: null,
+      unreportedAddedLines: null
+    }
+  }
+  const hasBaseline = baseline !== null && baseline !== undefined
+  const stated = unreported !== null && typeof unreported === 'object' && Array.isArray(unreported.files)
+  return {
+    configured: true,
+    headTotalPct: head?.totalPct ?? null,
+    baseTotalPct: hasBaseline ? (baseline.totalPct ?? null) : null,
+    baseSha: hasBaseline ? (baseline.sha ?? null) : null,
+    baseIsAncestor: hasBaseline && typeof baseIsAncestor === 'boolean' ? baseIsAncestor : null,
+    diffPct: changed?.diffPct ?? null,
+    changedLines: changed?.changedLines ?? null,
+    unreportedFiles: stated ? [...unreported.files] : null,
+    unreportedAddedLines: stated ? (unreported.addedLines ?? null) : null
+  }
+}
+
+/**
+ * Check a parsed baseline file. `ref` is the branch the baseline was taken on and
+ * may be null (a detached HEAD); everything else is required.
+ *
+ * @param {unknown} obj
+ * @returns {{ ok: boolean, problems: string[] }}
+ */
+export function validateBaseline(obj) {
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) {
+    return { ok: false, problems: ['the baseline is not a JSON object'] }
+  }
+  const problems = []
+  if (obj.schema !== BASELINE_SCHEMA) {
+    problems.push(`schema must be ${BASELINE_SCHEMA}, found ${JSON.stringify(obj.schema ?? null)}`)
+  }
+  if (typeof obj.sha !== 'string' || !obj.sha.trim()) problems.push('sha must be a non-empty commit id')
+  if (obj.ref !== undefined && obj.ref !== null && typeof obj.ref !== 'string') {
+    problems.push('ref must be a branch name or null')
+  }
+  if (typeof obj.totalPct !== 'number' || !Number.isFinite(obj.totalPct) || obj.totalPct < 0 || obj.totalPct > 100) {
+    problems.push('totalPct must be a number from 0 to 100')
+  }
+  if (typeof obj.generatedAt !== 'string' || !obj.generatedAt.trim()) {
+    problems.push('generatedAt must be a timestamp string')
+  }
+  return { ok: problems.length === 0, problems }
+}

package/lib/doctor.mjs

@@ -917,12 +917,18 @@ function checkPermissions(root, required, { home, sources } = {}) {
  * Advice, never a gate: push notification is an optional feature, so this row
  * is `ok` or `skip` and NEVER `fail` — an operator who never configured it has
  * not degraded their run. Reads the same names `lib/notify.mjs` reads — the
- * plugin options `CLAUDE_PLUGIN_OPTION_NTFY_TOPIC` / `CLAUDE_PLUGIN_OPTION_NTFY_URL`
- * and the shell variables `INTERLOCK_NTFY_TOPIC` / `INTERLOCK_NTFY_URL` — by
- * literal string rather than by importing the transport. The default server
- * comes from `notify-defaults.mjs`, so this row cannot name a different one.
- * The topic value is never read into a string that could reach the report;
- * only the server URL, which is not a capability, is echoed.
+ * shell variables `INTERLOCK_NTFY_TOPIC` / `INTERLOCK_NTFY_URL`, and never the
+ * host's option variables — by literal string rather than by importing the
+ * transport. The default server comes from `notify-defaults.mjs`, so this row
+ * cannot name a different one. The topic value is never read into a string
+ * that could reach the report; only the server URL, which is not a
+ * capability, is echoed.
+ *
+ * The row reports the environment the check ran in. A plugin option reaches
+ * the session's commands through its own session-start hook, which runs
+ * beside the preflight, so a check at session start cannot see one; the
+ * `skip` detail says so and names both ways to set a topic
+ * (clear-the-plugin-directory-holds design D7).
  */
 function configuredValue(env, name) {
   return env && typeof env[name] === 'string' && env[name].trim() ? env[name].trim() : ''
@@ -930,19 +936,17 @@ function configuredValue(env, name) {
 
 function checkNotify(env) {
   try {
-    const topic =
-      configuredValue(env, 'CLAUDE_PLUGIN_OPTION_NTFY_TOPIC') || configuredValue(env, 'INTERLOCK_NTFY_TOPIC')
+    const topic = configuredValue(env, 'INTERLOCK_NTFY_TOPIC')
     if (!topic) {
       return check(
         'notify',
         'skip',
-        'INTERLOCK_NTFY_TOPIC is not set — optional; an unattended run that stops will not reach you'
+        "no topic in this environment: set the plugin's ntfy topic option (it reaches the session's commands at " +
+          'session start, so a check that runs beside it cannot see it) or INTERLOCK_NTFY_TOPIC; optional, but an ' +
+          'unattended run that stops will not reach you'
       )
     }
-    const url =
-      configuredValue(env, 'CLAUDE_PLUGIN_OPTION_NTFY_URL') ||
-      configuredValue(env, 'INTERLOCK_NTFY_URL') ||
-      DEFAULT_NTFY_URL
+    const url = configuredValue(env, 'INTERLOCK_NTFY_URL') || DEFAULT_NTFY_URL
     return check('notify', 'ok', `push configured: ${url}`)
   } catch (err) {
     // Fail-open, and never `fail`: an unreadable env is a reason to skip the

package/lib/drift.mjs

@@ -96,9 +96,12 @@ export function detectUnarchived(root = '.') {
   return found
 }
 
-/** Read the graph, or say why we could not. Never reports absence as cleanliness. */
-function readGraph(root) {
-  const path = join(root, GRAPH_PATH)
+/**
+ * Read the graph at a path, or say why we could not. Never reports absence as
+ * cleanliness. The path is the caller's, so a graph found anywhere (the state
+ * home, a run's recorded `graphPath`) is read by the same code as the root one.
+ */
+export function readGraphAt(path) {
   if (!existsSync(path)) {
     return { links: null, reason: 'no graph has been built — run /interlock:bootstrap once' }
   }
@@ -120,18 +123,39 @@ function readGraph(root) {
   }
 }
 
+/** The graph under a repository root. */
+function readGraph(root) {
+  return readGraphAt(join(root, GRAPH_PATH))
+}
+
+/**
+ * The reliable living-spec edges of a graph: weight-1 `implements_spec` links
+ * whose source is a living spec and whose target is a `file:` node. Returns the
+ * link objects themselves, in graph order, and `[]` for a graph with no links.
+ * Staleness, orphan detection, domain selection and the spec audit all read
+ * through this, so they cannot disagree about which edges count.
+ *
+ * @param {{ links?: any[]|null }|null|undefined} graph
+ * @returns {any[]}
+ */
+export function livingSpecEdges(graph) {
+  const links = graph && Array.isArray(graph.links) ? graph.links : []
+  return links.filter(link => {
+    if (!link || link.relation !== 'implements_spec') return false
+    if (link.weight !== RELIABLE_EDGE_WEIGHT) return false
+    const spec = typeof link.source_file === 'string' ? link.source_file : ''
+    if (!spec.startsWith(LIVING_SPEC_PREFIX)) return false
+    const target = typeof link.target === 'string' ? link.target : ''
+    return target.startsWith('file:') && target.length > 'file:'.length
+  })
+}
+
 /** spec path -> set of files it claims to describe. Living specs, weight-1 edges only. */
 function specToFiles(links) {
   const bySpec = new Map()
-  for (const link of links) {
-    if (!link || link.relation !== 'implements_spec') continue
-    if (link.weight !== RELIABLE_EDGE_WEIGHT) continue
-    const spec = typeof link.source_file === 'string' ? link.source_file : ''
-    if (!spec.startsWith(LIVING_SPEC_PREFIX)) continue
-    const target = typeof link.target === 'string' ? link.target : ''
-    if (!target.startsWith('file:')) continue
-    const file = target.slice('file:'.length)
-    if (!file) continue
+  for (const link of livingSpecEdges({ links })) {
+    const spec = link.source_file
+    const file = link.target.slice('file:'.length)
     if (!bySpec.has(spec)) bySpec.set(spec, new Set())
     bySpec.get(spec).add(file)
   }

package/lib/findings.mjs

@@ -55,7 +55,12 @@ export const FINDING_SCHEMA = {
           line: { type: 'integer' },
           title: { type: 'string' },
           description: { type: 'string' },
-          suggestion: { type: 'string' }
+          suggestion: { type: 'string' },
+          requirement: {
+            type: 'string',
+            description:
+              'Optional. The living requirement this finding rests on, as openspec/specs/<capability>/spec.md#<requirement heading>. A domain blocker carries one; the CLI checks its shape and never drops the finding for a bad one.'
+          }
         },
         required: ['severity', 'file', 'title', 'description']
       }
@@ -129,8 +134,17 @@ function fileOf(finding) {
   return trimmed
 }
 
-// Accept either a bare array, a single { dimension, findings } object, or an
-// array of those — reviewers emit all three shapes depending on fan-out.
+// Accept a bare array, a single { dimension, findings } object, an array of
+// those — reviewers emit all three shapes depending on fan-out — or the record
+// `interlock review --json` prints, whose `surviving` list is the findings a
+// gate or a remediation plan is meant to read.
+//
+// Total on purpose: an input in none of those shapes yields no findings rather
+// than throwing, because a run adjudicating mid-flight must not crash on it.
+// That is exactly why "no findings" from here proves nothing by itself. A
+// reader that cannot find the findings has not established that there are none,
+// so every consumer asks `carriesFindingsList` first and states its own
+// consequence (design D10 of label-and-harden-the-merge-verdict).
 function flatten(input) {
   if (Array.isArray(input)) {
     return input.flatMap(entry =>
@@ -142,9 +156,32 @@ function flatten(input) {
   if (input && Array.isArray(input.findings)) {
     return input.findings.map(f => ({ dimension: input.dimension, ...f }))
   }
+  if (input && Array.isArray(input.surviving)) return [...input.surviving]
   return []
 }
 
+/**
+ * Whether an input carries a findings list at all: a list (an empty one is a
+ * statement that nothing was found), a list of per-dimension records, one such
+ * record, or a review record with its `surviving` list. Anything else — `{}`,
+ * null, text, a number, an object with other keys — carries none, and no reader
+ * may count it as zero findings.
+ *
+ * @param {unknown} input
+ * @returns {boolean}
+ */
+export function carriesFindingsList(input) {
+  if (Array.isArray(input)) return true
+  if (!input || typeof input !== 'object') return false
+  return Array.isArray(input.findings) || Array.isArray(input.surviving)
+}
+
+/** What a reader says of an input that carries none: the shapes it would have read. */
+export const NO_FINDINGS_LIST =
+  'it carries no findings list — expected a list of findings, a list of { dimension, findings } records, ' +
+  'one such record, or the record "interlock review --json" prints (its "surviving" list); ' +
+  'an empty list is how to say nothing was found'
+
 /**
  * Group findings by file.
  * @returns {{ byFile: Array<{file: string, findings: Array}>, unscoped: Array }}

package/lib/graph/extract/openspec.mjs

@@ -1,15 +1,8 @@
 import path from 'node:path';
 import { readIndexed, rel } from '../paths.mjs';
 import { walkMarkdown } from './walk.mjs';
+import { specPathMentions } from '../../spec-text.mjs';
 
-// Any repo-relative path with an extension. Deliberately NOT restricted to a
-// directory allowlist or an extension allowlist: every match is gated below by
-// `knownFiles.has(mentioned)`, so the graph itself decides what is real. An
-// allowlist here can only produce false negatives — it used to drop Go/Rust/Java
-// layouts (cmd/, internal/, pkg/, apps/, services/) and indexed config files
-// entirely. The leading boundary class excludes URL path segments, which are
-// always preceded by `/`.
-const PATH_RE = /(?:^|[\s`"'(\[])((?:[\w.@-]+\/)+[\w.@-]+\.[A-Za-z0-9]{1,6})\b/gm;
 const SYMBOL_RE = /`([A-Z][A-Za-z0-9_]{2,})`|\b([A-Z][A-Za-z0-9_]{2,}(?:Service|Client|Router|Handler|Store|Provider|Context|Schema|Util|Utils)?)\b/g;
 
 /**
@@ -38,13 +31,10 @@ export function extractOpenspec(root, knownSymbols = new Set(), knownFiles = new
     });
 
     const seen = new Set();
-    let m;
-    PATH_RE.lastIndex = 0;
-    while ((m = PATH_RE.exec(text))) {
-      const mentioned = m[1];
-      if (seen.has(mentioned)) continue;
-      seen.add(mentioned);
-      const line = text.slice(0, m.index).split('\n').length;
+    // The rule for "a spec mentions this file" is one function shared with the
+    // spec-coverage signal; the gate on files the graph indexed stays here.
+    for (const { path: mentioned, index } of specPathMentions(text)) {
+      const line = text.slice(0, index).split('\n').length;
       if (knownFiles.has(mentioned)) {
         edges.push({
           source: id,
@@ -58,6 +48,7 @@ export function extractOpenspec(root, knownSymbols = new Set(), knownFiles = new
       }
     }
 
+    let m;
     SYMBOL_RE.lastIndex = 0;
     while ((m = SYMBOL_RE.exec(text))) {
       const name = m[1] || m[2];