@holmes-lab/holmes-kit 0.25.1 → 0.26.0

package/CHANGELOG.md

@@ -5,6 +5,76 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.26.0] - 2026-09-20
+
+Architecture you declare is now judged in every language the graph can follow, and the verdict
+reaches a person. Five of these slices were authored on Windows and merged; their spec numbers
+moved from REQ-674–678 to REQ-688–692 because `main` had already published those numbers.
+
+### Added
+- **`inherits` joins the forbidden edges** (A-SPEC-691). A C-SPEC's `## Forbidden Edges` takes a
+  third rule kind beside `import` and `call`: `- inherits src/app -x-> ConcreteBase`. It is an EXACT
+  match, for the reason `call` is — a prefix would let one `Base` swallow every `Base*`. Nothing is
+  inferred: the rule reads the graph's `inherits` edges and never asks which class is "abstract",
+  which is what makes it work in Go, where interface satisfaction cannot be inferred at all. The
+  pre-edit gate enforces it like the other two kinds.
+- **A baseline that expires** (A-SPEC-691). A project that already breaks a rule it wants to adopt
+  writes `- allow until 2026-09-27 : inherits src/legacy/a.ts -> LegacyBase` in the same section.
+  Exact on kind, file and target — never a prefix, or it becomes a way to switch the rule off. Past
+  its date the allowance still holds (an expiry that blocked would make the rule a barrier to
+  adoption) but it is reported as expired, with `(reconfirmed n since <date>)` carried along so a
+  twelfth renewal cannot hide. A malformed baseline line lands in `malformed`, never disappears.
+- **`ARCH` lines at the end of the turn** (A-SPEC-693). The scan-wide judgement existed and nothing
+  in the product called it — measured: zero consumers outside the tests — so an expired baseline was
+  neither blocked nor seen, and a time-boxed allowance could not be told from a permanent pardon.
+  The Stop hook now reports, on the non-blocking `tracked` channel: violations no baseline covers,
+  expired baselines with their renewal count, and **which rule kind could not be judged in which
+  extension** (`inherits rules NOT judged in: .js, .py, .tsx`). A project that declares no rule hears
+  nothing and pays nothing: the judgement shares the one scan the cycle ratchet already makes
+  (measured here: scan 6.6 s, judgement 0.14 s).
+- **A reporter hears that their defect was fixed** (A-SPEC-687). A defect filed through
+  `holmes-kit report` is matched, locally and once, against the list of resolved reports that ships
+  in the package; the session start says so. Nothing is sent anywhere.
+
+### Fixed
+- **The cycle ratchet judged one language family out of eight** (A-SPEC-688). The Stop hook
+  re-implemented import resolution beside the graph builder's — relative specifiers only, four
+  extensions. Measured on fixtures shaped the way each language requires: 16 import edges, 2
+  survived; 9 planted cycles, 1 found. It cost nothing in an all-TypeScript tree (919 edges either
+  way), which is how it survived, and everything in a Java, Go, Python or Rust consumer. There is now
+  ONE resolver (`cpg/import-resolver`), consumed by both. A cycle's member list is capped per cycle
+  with the dropped count declared (`filesOmitted`), and its identity is computed before the cut.
+- **`.cjs` relative `require()` was declared unrecoverable while being recovered** (A-SPEC-689). The
+  capability table under-declared, and its pin only tested the bare form, so the drift passed. Both
+  forms are pinned now.
+- **The id a refusal printed could not be granted** (A-SPEC-690). `approve --grant <id>` resolved
+  references against the tracked queue alone; a shell hard-HITL refusal lives in the per-machine
+  refusal log, so the reference failed before the fallback that handles it could run. Id and prefix
+  references now resolve across both stores; a number still means only the row the operator was
+  shown; a prefix that collides across the stores is refused by name; an unreadable log removes
+  candidates rather than granting. The inbox list is unchanged.
+- **The same Windows directory read as a foreign workspace** (A-SPEC-692). Three root comparisons
+  put one side through `realpathSync.native` and the other through the JS `realpathSync`, which
+  leaves an 8.3 alias (`SUNGNA~1`) spelled as it arrived. Both sides go through one canonicaliser.
+- **A kind-blind `scope`** (A-SPEC-693). With an `import` rule beside an `inherits` rule, an
+  extension that showed only imports read as *judged*. Scope is now asked per rule kind
+  (`scopeByKind`), over the files a rule of that kind actually judges; the flat lists fold toward the
+  honest side and are unchanged when one kind is in play.
+- **Lazy `require` stopped being recorded for plain JavaScript** (A-SPEC-693). Gating the edge
+  classifier on "does this language erase types" also switched it off for `.js/.cjs/.mjs/.jsx`.
+
+### Changed
+- Windows test baseline (A-SPEC-692): child-boundary waits ride the measured time factor, repository
+  files are read CRLF-tolerantly, and permission-bit assertions run only where the filesystem keeps
+  the bit — reported as skipped, with a reason, where it does not (A-SPEC-693).
+
+### Known
+- The cycle ratchet's own `tracked` line has never been emitted: the Stop hook computes the cycles
+  and records the observation, but does not hand them to the verdict. Found while wiring the `ARCH`
+  lines; not fixed here because in `strict` mode the fix introduces a new block. This repository
+  currently has 3 runtime cycles nobody is shown.
+- Two Windows-only reds remain (`entity-renumber-transaction` race, `supervisor-liveness` EPERM).
+
 ## [0.25.1] - 2026-09-19
 
 Test-only. No product behaviour changed; `dist/` behaves exactly as 0.25.0.

package/README.md

@@ -16,18 +16,23 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🧬 **Declare your architecture, in every language the graph can follow** *(new in 0.26.0)*: a C-SPEC's `## Forbidden Edges` takes a third rule kind beside `import` and `call` — `- inherits src/app -x-> ConcreteBase`, an exact match enforced at the pre-edit gate. Nothing is inferred: the rule reads the graph's `inherits` edges and never asks which class is "abstract", which is what makes it hold in Go, where interface satisfaction cannot be inferred at all. A project that already breaks the rule it wants adopts it with a **baseline that expires** — `- allow until 2026-09-27 : inherits src/legacy/a.ts -> LegacyBase`, exact on kind, file and target, never a prefix. Past its date the allowance still holds, because an expiry that blocked would turn the rule into a barrier to adoption; it is **reported** instead, carrying `(reconfirmed n since <date>)` so a twelfth renewal cannot hide.
+- 🏛️ **The architecture verdict reaches the person closing the turn** *(new in 0.26.0)*: the scan-wide judgement existed and nothing in the product called it — measured, zero consumers outside the tests — so an expired baseline was neither blocked nor seen, and a time-boxed allowance could not be told from a permanent pardon. The Stop hook now prints `ARCH` lines on the non-blocking `tracked` channel: violations no baseline covers, expired baselines with their renewal count, and **which rule kind could not be judged in which extension** (`inherits rules NOT judged in: .js, .py, .tsx`) — asked per kind, over the files a rule of that kind actually judges, because a pooled answer called a language *judged* for a rule it could not see. No rule declared, nothing said and nothing paid: the judgement shares the one scan the cycle ratchet already makes (measured here: scan 6.6 s, judgement 0.14 s).
+- ♻️ **The cycle ratchet judges every language it can resolve** *(new in 0.26.0)*: the Stop hook had re-implemented import resolution beside the graph builder's — relative specifiers only, four extensions. Measured on fixtures shaped the way each language requires: 16 import edges, 2 survived; 9 planted cycles, 1 found. It cost nothing in an all-TypeScript tree (919 edges either way), which is how it survived to 0.25, and everything in a Java, Go, Python or Rust consumer. There is now **one** resolver, consumed by both; a language whose specifiers do not resolve stays `unavailable` rather than reading as clean, and a wide Go package cycle is capped per cycle with the dropped members counted.
+- 🔑 **The id a refusal prints can be granted** *(new in 0.26.0)*: `approve --grant <id>` resolved references against the decision inbox alone, and a shell hard-HITL refusal lives in the per-machine refusal log — so the very id the refusal printed failed before the fallback that handles it could run, and the owner had nothing to approve. Id and prefix references now resolve across both stores. A **number** still means only the row you were shown, a prefix that collides across the stores is refused by name, an unreadable log removes candidates rather than granting, and the inbox list is unchanged.
+- 📬 **A reporter hears that their defect was fixed** *(new in 0.26.0)*: a defect filed through `holmes-kit report` is matched — locally, once — against the list of resolved reports that ships in the package, and the session start says so. Nothing is sent anywhere.
 - 🔦 **A semantic layer that is inert says so** *(new in 0.25.0)*: the tier line said what was CONFIGURED, never whether one lookup would succeed. Measured on this repository: the resolved tier was `cloud` and **0 of 602 scanned files** had a cached document vector under it, so every lookup returned nothing — reranking reordered nothing, alternates emitted nothing, and the output was byte-identical to a layer that examined everything and agreed. A naive check would have counted the 532 vectors sitting in the cache and called it healthy; they keyed on symbol lists that no longer existed. `doctor` now reports coverage against the files scanned NOW, through the runtime's own accessor, in four states — the two that cannot be judged say so rather than passing quietly.
 - 🔁 **Vectors refresh on the channel that keeps the graph fresh** *(new in 0.25.0)*: the graph self-heals through the Stop hook's detached child; the vectors did not, because warming was reachable only from an explicit `rtm_reindex`. The cache key hashes the file's path plus its symbol names, so every edit that renames a symbol invalidates that file's vector — twelve days of work had taken coverage to zero. The refresh now warms too, and the Stop hook reports the verdict the child recorded rather than scanning (tree-sitter wasm must not ride into a gate process); **a missing verdict reads as "not run", never as a pass**. Warming under the cloud tier is egress, so it is automatic AND observed, with `HOLMES_NO_SEMANTIC_WARM` to switch the transfer off — an owner who switches it off is shown a switch, not a fault. The verdict records the commit it was taken at, so work merged from another machine reports **needs re-measuring** instead of yesterday's numbers as today's truth.
 - 🎣 **The graph can introduce a candidate your words never named** *(new in 0.25.0)*: `issue_localize`'s semantic rerank could only reorder what lexical matching already found, so a question phrased in intent vocabulary never reached the file that answers it. Measured with the tier live and the vectors warm: asking *who opens a URL in the user's browser* ranked an unrelated file first on the shared prose word "repository", at 3.3× the second score, and never returned `open-url.ts` — which the graph held the whole time. The same need in mechanism vocabulary found its answer at rank 4. `semanticAlternates` now carries the top cached-vector matches among files the emission missed, and that file comes back at cosine 0.754. **Pure addition on its own field**: the ranked hits are untouched in set, order and score, because admitting candidates INTO a ranked set is where this project measured precision being lost.
 - 🪧 **The semantic ladder reaches you without running `doctor`** *(new in 0.25.0)*: measured here on 305 traceability cases, recall goes 0.486 lexical → 0.667 local → **0.887 cloud**, and on requests lexical search misses entirely, recovery goes 0% → 52% → **92%** — and a consumer never learned any of it, because only `doctor` said so. `init` now names the ladder with those numbers and the command for each, and the session banner says it **once** per workspace on a machine and then never again. `local` is named before `cloud` on purpose: `none` is the default because egress needs consent, not because nobody got to it, and the cloud line states what leaves the machine. A consumer who has already chosen hears nothing.
 - 📮 **`holmes-kit report` — a defect can reach the maintainers** *(new in 0.24.0)*: until now a consumer's holmes-kit defect had no way back to us; the one we learned about arrived because someone pasted a transcript, and it had been reproducing for every consumer on every slice. The command writes a **redacted** report to `.ax/reports/<fingerprint>.md` and prints a prefilled GitHub issue link — title, assignee, body — plus a search link for the same fingerprint so you can see whether it is already known. `--open` opens it; on a headless box or over SSH the printed link is the whole of it. **No token, no API, nothing sent automatically**: you press Submit on GitHub's own page with the body in front of you and editable. Redaction is an allowlist rather than a scrubber — this project's own remote carries a token before the `@`, its replica ids carry a person's name, and its spec titles are unreleased product intent, so a path, a credential or a machine identifier withholds the field and the report says which. A spec id passes by shape; a spec title does not. And what holmes-kit cannot know, it says: no ledger keeps its own refusal text, so a report with no description states that rather than pretending.
 - 🧭 **A skipped graph analysis is visible** *(new in 0.24.0)*: `AGENTS.md` asks for `maintenance_analyze` before editing source, and nothing checked. Measured on this repository, the step had been skipped for seventeen consecutive commits — and the run that followed named child-process precedents a name search had missed completely, because the question was "who opens a browser" while the answer lived under "who spawns a child". The Stop hook now reports source changed with no analysis standing open: non-blocking, judged by commit rather than by clock, and silent in a workspace that never adopted the habit.
-- 🧱 **A stale build is told, not discovered** *(new in 0.23.3)*: thirty suites in this project load `dist/` while they run, and nothing asserted that it still represented the source — only the release gate compared the build id to HEAD, and only at publish time. A stale build does not go red; it verifies old code and returns green. The Stop hook now reports it on the non-blocking `tracked` channel, judged by the **build id and never by mtime**: measured here, `.build-id` had a newer mtime than every source file while naming a commit nine behind HEAD, with two changed sources missing from `dist` entirely. A workspace that does not build hears nothing, `fresh` says nothing, and the two states that cannot be judged say **that** rather than passing quietly.
-- 📐 **Declarations are read as written** *(new in 0.23.2)*: `Files to Touch` is where a spec declares the files it will touch, and three things read it — fulfilment advisories, the declaration census and the approval impact note. The parser took only the **first word of a list item**, so measured over 678 approved specs here, **88 specs and 172 paths were declared and never read**; 24 of them parsed to zero while naming files plainly. Several paths on one line, an indented continuation, a Korean first word, a prose paragraph — all invisible. They are read now, wherever they sit, and a bare `name.ext` keeps its old position rule so a property access like `module.exports` is still not a file. A declared path that does not exist but is the suffix of exactly one repository file is reported as an abbreviation rather than a defect; two candidates stays an ambiguity and nothing is guessed. Cost, measured across the whole corpus: **zero** new `missing` findings.
-- 📄 **The publish gate reads the docs** *(new in 0.23.2)*: the publish playbook has demanded "bring README and CHANGELOG up to this release" since 0.16.0 and only prose enforced it, so it failed four times — including 0.21.0, 0.22.0 and 0.23.0, which each shipped with a feature list frozen at 0.20.0. The release gate now refuses two things it can decide: a missing CHANGELOG entry for the version being published, and an entry with `### Added` while `README.md` has not changed since the previous release. Replayed over eight releases it refuses exactly the three that were stale and passes the other five. What needs judgement — is the old wording still true? — stays with the person and is **reported**, never faked; a check that could not run says so instead of reading as a pass.
 
 **Earlier releases** — condensed to one line each; every release's full account lives in [CHANGELOG.md](CHANGELOG.md).
 
+- 🧱 **A stale build is told, not discovered** *(0.23.3)*: the Stop hook reports a `dist/` that no longer represents the source, judged by the **build id and never by mtime** — a stale build does not go red, it verifies old code and returns green; the two states that cannot be judged say that rather than passing quietly.
+- 📐 **Declarations are read as written** *(0.23.2)*: `Files to Touch` is read wherever a path sits — several on one line, an indented continuation, a Korean first word — after 88 specs and 172 declared paths were measured as never read; an unambiguous abbreviation is reported as one, and nothing is guessed.
+- 📄 **The publish gate reads the docs** *(0.23.2)*: the release gate refuses a missing CHANGELOG entry for the version being published, and an `### Added` entry while `README.md` has not changed since the previous release; what needs judgement stays with the person and is reported, never faked.
 - 🧩 **Your config files survive a re-wire** *(0.23.0)*: `init --agent antigravity|codex` refreshes only the holmes-kit entry instead of replacing `.agents/mcp_config.json`, `hooks.json` and `marketplace.json` whole — a neighbour server, hook, plugin and your own `disabled` flag all survive, and an unreadable JSON file is refused with a reason rather than overwritten.
 - 🫀 **The MCP supervisor notices a child that died** *(0.23.0)*: a crashed child used to leave the server **permanently deaf**; outstanding requests now get a JSON-RPC error first, then the supervisor resets, respawns and replays the opening exchange — with a restart budget spent only by a child that never answered.
 - 🧮 **Coverage you can explain** *(0.23.0, corrected in 0.23.2)*: the RTM census says *what each unlinked spec declared* (`scanned-source`, `file-anchor-target`, `test-target`, `unreachable-target`, `no-declaration`). The "zero" 0.23.0 published here was the Files-to-Touch parser's, not the corpus's — the corrected census reads three, with five real trace gaps behind it.

package/dist/.build-id

@@ -1 +1 @@
-6277a6d6-mu7vpg1b
+a53bfcd1-mu95v98e

package/dist/holmes/cli/approve.js

@@ -100,32 +100,13 @@ const findPending = (root, id) => {
     // — exactly the "grant is for what the human saw" contract. A decided id never promotes: the
     // granted/denied event in the queue closes the request, same single-use convention as pending.
     try {
-        const { readRefusals } = require('../governance/approval-queue');
-        let mine = readRefusals(root).filter((r) => r.id === id);
-        // A decided id closes the request — UNLESS the gate refused it again afterwards. The fold has
-        // the same rule for pending (a later `requested` re-inserts after granted/denied): a human may
-        // change their mind, and the retry is what re-opens the question.
-        const decided = state.decisions[id];
-        if (decided) {
-            // Clock-free reopening: the decision recorded HOW MANY occurrences it covered, so a retry is
-            // simply everything past that count — millisecond ties (measured flaky under the full suite)
-            // cannot lose it. Legacy decisions without the count fall back to the timestamp rule.
-            if (typeof decided.covered === 'number')
-                mine = mine.slice(decided.covered);
-            else
-                mine = mine.filter((r) => r.ts > decided.ts);
-        }
-        if (mine.length > 0) {
-            const latest = mine[mine.length - 1];
-            return {
-                entry: {
-                    id, kind: latest.kind, target: latest.target, why: latest.why,
-                    count: mine.length, firstTs: mine[0].ts, lastTs: latest.ts,
-                    ...(latest.replica ? { replica: latest.replica } : {}),
-                },
-                state,
-            };
-        }
+        // @implements A-SPEC-690 — the reopening rule and the queue-shape conversion live in ONE place
+        // now (approval-queue). They used to be spelled out here as well, and a second copy of a
+        // judgement is how two paths quietly disagree about whether a request is open.
+        const { readRefusals, openOccurrences, asPendingRequest } = require('../governance/approval-queue');
+        const mine = openOccurrences(readRefusals(root).filter((r) => r.id === id), state.decisions[id]);
+        if (mine.length > 0)
+            return { entry: asPendingRequest(id, mine), state };
     }
     catch { /* a broken refusal log must not break the decision surface */ }
     return { entry: undefined, state };

package/dist/holmes/cli/index.js

@@ -821,8 +821,15 @@ async function main(argv) {
             // the same filtered list or `--grant 3` would act on a row nobody saw. An ID or prefix is the
             // operator naming a specific request — including a `shell` refusal they approved out of band
             // (A-SPEC-563.2), which the inbox filter hides from the list but must never make ungrantable.
+            // @implements A-SPEC-690 — `includeAllKinds` only unfilters KINDS inside the tracked queue;
+            // a shell refusal is not in that file at all (A-SPEC-563.1 routes it to this machine's
+            // refusal log). So the id/prefix path failed here, before approve.ts's refusal-log fallback
+            // could ever run — making the very id the refusal printed ungrantable, which the comment
+            // above says must never happen. The NUMBER path is untouched: an index must mean the row the
+            // operator was shown.
             const byIndex = /^\d+$/.test(ref.trim());
-            const r = resolveRequestRef(readQueue(root, byIndex ? undefined : { includeAllKinds: true }).pending, ref);
+            const { grantableRequests } = require('../governance/approval-queue');
+            const r = resolveRequestRef(byIndex ? readQueue(root).pending : grantableRequests(root), ref);
             return r.ok ? { id: r.entry.id, subject: (prefix) => decisionSubject(r.entry, prefix), detail: (tail) => decisionDetail(r.entry, tail) } : { refusal: r.reason };
         };
         const root = typeof flags.target === 'string' ? path.resolve(flags.target) : process.cwd();

package/dist/holmes/cpg/cycle-observation.d.ts

@@ -7,6 +7,17 @@ import { type Cycle } from './cycle-detect';
  * that makes it unreadable. What is dropped is COUNTED, never silently cut.
  */
 export declare const CYCLE_LIST_CAP = 50;
+/**
+ * @implements A-SPEC-688
+ * The same rule applied one level down: a single cycle must not grow with the tree either.
+ *
+ * `CYCLE_LIST_CAP` bounded how many cycles a record holds; nothing bounded how many FILES one cycle
+ * holds. That was harmless while only TypeScript was judged, because a TS cycle is a handful of
+ * files. Judging Go activates it — a package import names EVERY file of the package, so one
+ * strongly connected component can carry a package's worth of paths into every turn's record.
+ * What is dropped is counted here too, per cycle, in `filesOmitted`.
+ */
+export declare const CYCLE_FILES_CAP = 25;
 /**
  * One turn's observation — paths, integers and enums only.
  *
@@ -20,6 +31,8 @@ export interface CycleObservationRecord {
     cycles: Array<{
         key: string;
         files: string[];
+        /** Members beyond CYCLE_FILES_CAP: counted, so a wide cycle is never mistaken for a narrow one. */
+        filesOmitted: number;
         runtime: boolean;
         edges: number;
     }>;

package/dist/holmes/cpg/cycle-observation.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CYCLE_LIST_CAP = void 0;
+exports.CYCLE_FILES_CAP = exports.CYCLE_LIST_CAP = void 0;
 exports.buildCycleObservation = buildCycleObservation;
 exports.appendCycleObservation = appendCycleObservation;
 exports.readCycleObservations = readCycleObservations;
@@ -61,6 +61,17 @@ const cycle_detect_1 = require("./cycle-detect");
  * that makes it unreadable. What is dropped is COUNTED, never silently cut.
  */
 exports.CYCLE_LIST_CAP = 50;
+/**
+ * @implements A-SPEC-688
+ * The same rule applied one level down: a single cycle must not grow with the tree either.
+ *
+ * `CYCLE_LIST_CAP` bounded how many cycles a record holds; nothing bounded how many FILES one cycle
+ * holds. That was harmless while only TypeScript was judged, because a TS cycle is a handful of
+ * files. Judging Go activates it — a package import names EVERY file of the package, so one
+ * strongly connected component can carry a package's worth of paths into every turn's record.
+ * What is dropped is counted here too, per cycle, in `filesOmitted`.
+ */
+exports.CYCLE_FILES_CAP = 25;
 /**
  * Build the record. PURE — the clock is an argument, so a test can pin it and two callers cannot
  * disagree about what "now" was.
@@ -77,7 +88,19 @@ function buildCycleObservation(ev, ts) {
     return {
         ts,
         mode: ev.mode,
-        cycles: listed.map((c) => ({ key: (0, cycle_detect_1.cycleKey)(c.files), files: [...c.files].sort(), runtime: c.runtime, edges: c.edges.length })),
+        cycles: listed.map((c) => {
+            const all = [...c.files].sort();
+            return {
+                // Identity comes from the FULL membership. Keying off the truncated list would make one
+                // wide cycle look like a different cycle whenever a member outside the window changed —
+                // and the ledger's whole job is to say whether this is the same finding as last turn.
+                key: (0, cycle_detect_1.cycleKey)(c.files),
+                files: all.slice(0, exports.CYCLE_FILES_CAP),
+                filesOmitted: Math.max(0, all.length - exports.CYCLE_FILES_CAP),
+                runtime: c.runtime,
+                edges: c.edges.length,
+            };
+        }),
         cyclesOmitted: Math.max(0, ev.current.length - listed.length),
         violations,
         allowed: ev.allowed.length,

package/dist/holmes/cpg/forbidden-edge-report.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The forbidden-edge judgement, as lines a person closing a turn can act on.
+ *
+ * `judgeForbiddenEdges` (A-SPEC-691) computed an honest answer — what is violated, which allowance
+ * has run out and how many times it was renewed, which languages could not be judged — and nothing
+ * in the product read it. Measured 2026-09-20: zero consumers outside the tests. An expired baseline
+ * does not block (owner decision, 2026-09-19), so while it was also invisible a time-boxed baseline
+ * was indistinguishable from a permanent pardon — the decay A-SPEC-691 was written to prevent.
+ *
+ * Pure: a judgement in, strings out. A line is spent only on something the reader can do something
+ * about, so a baseline inside its window and a kind that was judged everywhere say nothing.
+ */
+import type { judgeForbiddenEdges } from './forbidden-edges';
+/**
+ * How many violation LINES are printed. It bounds the rendering and nothing else — no verdict reads
+ * it (REQ-569 S5, REQ-691: counts never enter a judgement). What is folded is counted, never dropped:
+ * a truncation that does not announce itself reads as the whole list.
+ */
+export declare const FORBIDDEN_EDGE_LINE_CAP = 10;
+export declare function forbiddenEdgeStatusLines(j: ReturnType<typeof judgeForbiddenEdges>): string[];

package/dist/holmes/cpg/forbidden-edge-report.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FORBIDDEN_EDGE_LINE_CAP = void 0;
+exports.forbiddenEdgeStatusLines = forbiddenEdgeStatusLines;
+/**
+ * How many violation LINES are printed. It bounds the rendering and nothing else — no verdict reads
+ * it (REQ-569 S5, REQ-691: counts never enter a judgement). What is folded is counted, never dropped:
+ * a truncation that does not announce itself reads as the whole list.
+ */
+exports.FORBIDDEN_EDGE_LINE_CAP = 10;
+function forbiddenEdgeStatusLines(j) {
+    const lines = [];
+    for (const v of j.violations.slice(0, exports.FORBIDDEN_EDGE_LINE_CAP)) {
+        lines.push(`forbidden edge: ${v.sourcePath}: ${v.rule}  (${v.kind} → ${v.to})`);
+    }
+    const folded = j.violations.length - exports.FORBIDDEN_EDGE_LINE_CAP;
+    if (folded > 0)
+        lines.push(`… and ${folded} more forbidden edge violation(s)`);
+    for (const b of j.baselines) {
+        if (!b.expired)
+            continue;
+        const since = b.since ? ` since ${b.since}` : '';
+        lines.push(`baseline expired ${b.until}: ${b.kind} ${b.sourcePath} -> ${b.target} (reconfirmed ${b.reconfirmed}${since})`);
+    }
+    for (const kind of Object.keys(j.scopeByKind).sort()) {
+        const missed = j.scopeByKind[kind]?.unavailable ?? [];
+        if (missed.length > 0)
+            lines.push(`${kind} rules NOT judged in: ${missed.join(', ')}`);
+    }
+    return lines;
+}

package/dist/holmes/cpg/forbidden-edges.d.ts

@@ -25,7 +25,15 @@ export declare function splitCorpus(prefix: string): {
  * to remove.
  */
 export interface ForbiddenEdgeRule {
-    kind: 'import' | 'call';
+    /**
+     * @implements A-SPEC-691
+     * `inherits` joined the two originals because the sentence above stopped being true. It named
+     * the kinds "the two things the D-CPG can actually see", measured 2026-08-22 — when `inherits`
+     * reached the graph from NO language at all. It now resolves in eight families (A-SPEC-286,
+     * A-SPEC-288, A-SPEC-511.1). Counting again and widening is what that rule asks for; offering a
+     * shape for something still invisible is what it forbids.
+     */
+    kind: 'import' | 'call' | 'inherits';
     /** Which corpus this rule judges. @implements A-SPEC-229 */
     corpus: RuleCorpus;
     /** Repo-relative prefix of the files the rule judges. */
@@ -41,7 +49,33 @@ export interface ForbiddenEdgeViolation {
     /** The enclosing definition the edge leaves from — `<module>` for a top-level import. */
     from: string;
     to: string;
-    kind: 'import' | 'call';
+    kind: 'import' | 'call' | 'inherits';
+}
+/**
+ * @implements A-SPEC-691
+ * One grandfathered violation — how a project adopts a rule it already breaks.
+ *
+ * Its whole worth is that it EXPIRES. An expiry that blocked would make the rule a barrier to
+ * adoption, which REQ-574 named the failure mode ("a rule that blocks adoption is not a rule, it is
+ * a barrier"), so expiry SHOWS instead. That only works if the showing is real: `reconfirmed` and
+ * `since` travel with the entry so a twelfth renewal cannot hide. Not blocking and not being seen
+ * are different things.
+ */
+export interface BaselineEntry {
+    kind: 'import' | 'call' | 'inherits';
+    /** The exact file this allowance covers — never a prefix. */
+    sourcePath: string;
+    /** The exact edge target this allowance covers. */
+    target: string;
+    /** ISO date the allowance runs to. */
+    until: string;
+    /** How many times the author has renewed it. */
+    reconfirmed: number;
+    /** When the allowance was first taken, if the author recorded it. */
+    since?: string;
+    /** Past `until` at judgement time. Reported, never enforced. */
+    expired: boolean;
+    text: string;
 }
 /**
  * Read the rules out of a `## Forbidden Edges` section.
@@ -56,6 +90,8 @@ export interface ForbiddenEdgeViolation {
  */
 export declare function parseForbiddenEdges(section: string): {
     rules: ForbiddenEdgeRule[];
+    /** @implements A-SPEC-691 — grandfathered violations, living in the same section on purpose. */
+    baselines: BaselineEntry[];
     malformed: string[];
 };
 /**
@@ -71,3 +107,50 @@ export declare function parseForbiddenEdges(section: string): {
  * would make `list` catch `listFiles`.
  */
 export declare function findForbiddenEdgeViolations(files: ScannedFile[], rules: ForbiddenEdgeRule[]): ForbiddenEdgeViolation[];
+/**
+ * @implements A-SPEC-691
+ * Is this violation one the project already declared it carries?
+ *
+ * EXACT on all three fields. A prefix here would turn "these violations" into "this whole area",
+ * which is a way to switch the rule off rather than a way to carry legacy forward.
+ *
+ * Exported because BOTH judgement paths need it — the scan-wide one and the pre-edit gate — and a
+ * second copy of this predicate is how a baseline comes to mean one thing in the report and another
+ * at the gate.
+ */
+export declare function isBaselined(v: {
+    kind: string;
+    sourcePath: string;
+    to: string;
+}, baselines: readonly BaselineEntry[]): boolean;
+/**
+ * @implements A-SPEC-691
+ * The judgement with its own honesty attached: what was found, what was grandfathered, and which
+ * languages could be judged at all.
+ *
+ * `findForbiddenEdgeViolations` keeps its array return, so every existing caller and pin is
+ * untouched — this WRAPS it rather than replacing it, because a second copy of the matching rule is
+ * how two paths quietly disagree.
+ *
+ * `scope` follows the distinction REQ-688 established for cycles. An extension that produced edges
+ * but NONE of the kind a rule reads is `unavailable`: it was looked at and could not be judged. An
+ * extension that produced nothing at all is in neither list, because "there was nothing to see" and
+ * "we could not see" are different facts, and reporting them as one lets an empty scan read as a
+ * clean one.
+ */
+export declare function judgeForbiddenEdges(files: ScannedFile[], rules: ForbiddenEdgeRule[], opts?: {
+    baselines?: BaselineEntry[];
+    now?: Date;
+}): {
+    violations: ForbiddenEdgeViolation[];
+    baselines: BaselineEntry[];
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+    /** @implements A-SPEC-693 — the same question asked once per rule kind in play. */
+    scopeByKind: Partial<Record<ForbiddenEdgeRule['kind'], {
+        judged: string[];
+        unavailable: string[];
+    }>>;
+};

package/dist/holmes/cpg/forbidden-edges.js

@@ -36,6 +36,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.splitCorpus = splitCorpus;
 exports.parseForbiddenEdges = parseForbiddenEdges;
 exports.findForbiddenEdgeViolations = findForbiddenEdgeViolations;
+exports.isBaselined = isBaselined;
+exports.judgeForbiddenEdges = judgeForbiddenEdges;
 // @implements A-SPEC-224
 const path = __importStar(require("node:path"));
 const test_files_1 = require("./test-files");
@@ -45,7 +47,15 @@ function splitCorpus(prefix) {
         ? { corpus: 'tests', sourcePrefix: prefix.slice('tests:'.length) }
         : { corpus: 'production', sourcePrefix: prefix };
 }
-const RULE = /^(import|call)\s+(\S+)\s+-x->\s+(\S+)$/;
+const RULE = /^(import|call|inherits)\s+(\S+)\s+-x->\s+(\S+)$/;
+/**
+ * @implements A-SPEC-691
+ * `allow until <date> [(reconfirmed <n> since <date>)] : <kind> <path> -> <target>`
+ *
+ * The arrow differs from a rule's `-x->` on purpose: the two shapes cannot be confused for each
+ * other, and a baseline written wrong falls through to `malformed` rather than disappearing.
+ */
+const BASELINE = /^allow until (\d{4}-\d{2}-\d{2})(?:\s*\(reconfirmed (\d+)(?: since (\d{4}-\d{2}-\d{2}))?\))?\s*:\s*(import|call|inherits)\s+(\S+)\s+->\s+(\S+)$/;
 /**
  * Read the rules out of a `## Forbidden Edges` section.
  *
@@ -59,6 +69,7 @@ const RULE = /^(import|call)\s+(\S+)\s+-x->\s+(\S+)$/;
  */
 function parseForbiddenEdges(section) {
     const rules = [];
+    const baselines = [];
     const malformed = [];
     for (const raw of String(section ?? '').split('\n')) {
         const line = raw.trim();
@@ -67,6 +78,26 @@ function parseForbiddenEdges(section) {
         // Strip a trailing comment and the backticks a Markdown author naturally reaches for, so the
         // rule reads the same whether or not it was written for a human eye.
         const body = line.slice(2).replace(/\s+#.*$/, '').replace(/`/g, '').trim().replace(/\s+/g, ' ');
+        // @implements A-SPEC-691 — a baseline is tried first; its `allow until` opening cannot be a
+        // rule, so trying the rule shape first would only ever produce a confusing `malformed`.
+        if (body.startsWith('allow until')) {
+            const b = BASELINE.exec(body);
+            if (!b) {
+                malformed.push(raw.trim());
+                continue;
+            }
+            baselines.push({
+                kind: b[4],
+                sourcePath: b[5],
+                target: b[6],
+                until: b[1],
+                reconfirmed: b[2] ? Number(b[2]) : 0,
+                ...(b[3] ? { since: b[3] } : {}),
+                expired: false, // decided at judgement time, against that call's clock
+                text: body,
+            });
+            continue;
+        }
         const m = RULE.exec(body);
         if (!m) {
             malformed.push(raw.trim());
@@ -75,7 +106,7 @@ function parseForbiddenEdges(section) {
         const { corpus, sourcePrefix } = splitCorpus(m[2]);
         rules.push({ kind: m[1], corpus, sourcePrefix, target: m[3], text: body });
     }
-    return { rules, malformed };
+    return { rules, baselines, malformed };
 }
 /**
  * Where an import specifier lands, as a repo-relative path.
@@ -126,6 +157,14 @@ function findForbiddenEdgeViolations(files, rules) {
                     if (!importTargetOf(sourcePath, e.to).startsWith(r.target))
                         continue;
                 }
+                else if (r.kind === 'inherits') {
+                    // @implements A-SPEC-691 — EXACT, for the reason `call` is exact: a prefix would let one
+                    // `Base` rule swallow every `Base*` and the rule would stop meaning anything.
+                    if (e.rel !== 'inherits')
+                        continue;
+                    if (e.to !== r.target)
+                        continue;
+                }
                 else {
                     if (e.rel !== 'calls')
                         continue;
@@ -138,3 +177,97 @@ function findForbiddenEdgeViolations(files, rules) {
     }
     return out;
 }
+/**
+ * @implements A-SPEC-691
+ * Is this violation one the project already declared it carries?
+ *
+ * EXACT on all three fields. A prefix here would turn "these violations" into "this whole area",
+ * which is a way to switch the rule off rather than a way to carry legacy forward.
+ *
+ * Exported because BOTH judgement paths need it — the scan-wide one and the pre-edit gate — and a
+ * second copy of this predicate is how a baseline comes to mean one thing in the report and another
+ * at the gate.
+ */
+function isBaselined(v, baselines) {
+    return baselines.some((b) => b.kind === v.kind && b.sourcePath === v.sourcePath && b.target === v.to);
+}
+/** @implements A-SPEC-691 — which edge relation each rule kind reads. */
+const REL_OF = {
+    import: 'imports', call: 'calls', inherits: 'inherits',
+};
+/**
+ * @implements A-SPEC-691
+ * The judgement with its own honesty attached: what was found, what was grandfathered, and which
+ * languages could be judged at all.
+ *
+ * `findForbiddenEdgeViolations` keeps its array return, so every existing caller and pin is
+ * untouched — this WRAPS it rather than replacing it, because a second copy of the matching rule is
+ * how two paths quietly disagree.
+ *
+ * `scope` follows the distinction REQ-688 established for cycles. An extension that produced edges
+ * but NONE of the kind a rule reads is `unavailable`: it was looked at and could not be judged. An
+ * extension that produced nothing at all is in neither list, because "there was nothing to see" and
+ * "we could not see" are different facts, and reporting them as one lets an empty scan read as a
+ * clean one.
+ */
+function judgeForbiddenEdges(files, rules, opts) {
+    const today = (opts?.now ?? new Date()).toISOString().slice(0, 10);
+    const baselines = (opts?.baselines ?? []).map((b) => ({ ...b, expired: b.until < today }));
+    const all = findForbiddenEdgeViolations(files, rules);
+    // @implements A-SPEC-693 — asked ONCE PER KIND. The first version pooled the kinds in play, so an
+    // extension that showed imports read as `judged` beside an `inherits` rule it could not be judged
+    // for (measured 2026-09-20 on exactly the mix C-SPEC-224 declares). Which relations an extension
+    // produced is recorded per extension; each kind then reads its own relation out of that.
+    //
+    // A kind's scope counts only the files a rule OF THAT KIND actually judges — the same corpus and
+    // prefix test the matcher applies. Measured on this repository: counted over the whole scan, an
+    // import rule scoped to `src/holmes/cpg/` reported fixture extensions from elsewhere as "not
+    // judged", every turn, about files no rule speaks of. True, and nothing anyone can act on.
+    const kindsInPlay = [...new Set(rules.map((r) => r.kind))].sort();
+    const relsByKindExt = new Map();
+    const seenExt = new Set();
+    for (const f of files) {
+        const sourcePath = f?.sourcePath;
+        if (typeof sourcePath !== 'string' || (f.edges ?? []).length === 0)
+            continue;
+        const corpus = (0, test_files_1.isTestFile)(sourcePath) ? 'tests' : 'production';
+        const ext = sourcePath.slice(sourcePath.lastIndexOf('.'));
+        for (const kind of kindsInPlay) {
+            if (!rules.some((r) => r.kind === kind && r.corpus === corpus && sourcePath.startsWith(r.sourcePrefix)))
+                continue;
+            seenExt.add(ext);
+            const byExt = relsByKindExt.get(kind) ?? new Map();
+            relsByKindExt.set(kind, byExt);
+            const rels = byExt.get(ext) ?? new Set();
+            byExt.set(ext, rels);
+            for (const e of f.edges ?? [])
+                rels.add(e.rel);
+        }
+    }
+    const scopeByKind = {};
+    const unavailable = new Set();
+    for (const kind of kindsInPlay) {
+        const judgedHere = [];
+        const unavailableHere = [];
+        for (const [ext, rels] of relsByKindExt.get(kind) ?? []) {
+            if (rels.has(REL_OF[kind]))
+                judgedHere.push(ext);
+            else {
+                unavailableHere.push(ext);
+                unavailable.add(ext);
+            }
+        }
+        scopeByKind[kind] = { judged: judgedHere.sort(), unavailable: unavailableHere.sort() };
+    }
+    return {
+        violations: all.filter((v) => !isBaselined(v, baselines)),
+        baselines,
+        // The flat lists fold toward the honest side: unjudged for ANY kind in play is unavailable, and
+        // only an extension judged for EVERY kind is judged. With one kind this is what it always was.
+        scope: {
+            judged: [...seenExt].filter((e) => !unavailable.has(e)).sort(),
+            unavailable: [...unavailable].sort(),
+        },
+        scopeByKind,
+    };
+}

package/dist/holmes/cpg/import-resolver.d.ts

@@ -0,0 +1,12 @@
+import { ScannedFile } from './cpg-scanner';
+export interface ImportResolver {
+    /** One specifier → a scanned file path, or null when it names nothing the scan holds. */
+    resolve(fromFile: string, spec: string): string | null;
+    /** Go only: a package specifier → every scanned file of that package. Empty elsewhere. */
+    fanOut(fromFile: string, spec: string): string[];
+}
+export interface ImportResolverOptions {
+    /** Injected go.mod module path; when absent it is walked up from the first Go file. */
+    goModule?: string;
+}
+export declare function createImportResolver(scanned: readonly ScannedFile[], opts?: ImportResolverOptions): ImportResolver;