@holmes-lab/holmes-kit 0.25.1 → 0.26.0

package/dist/holmes/cpg/import-resolver.js

@@ -0,0 +1,215 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createImportResolver = createImportResolver;
+// @implements A-SPEC-688
+/**
+ * The ONE place an import specifier becomes a scanned file path.
+ *
+ * It used to be two. `rtm/addImportEdges` grew the per-language rules (see A-SPEC-289, A-SPEC-406,
+ * A-SPEC-525.1, A-SPEC-527.1) while the Stop hook's cycle ratchet re-implemented a crippled
+ * version beside it — relative specifiers only, four extensions. Measured 2026-09-18 on fixtures
+ * shaped the way each language's rules require: this resolver reached 18 of 20 specifiers and
+ * found all 9 planted cycles; the ratchet's copy reached 2 and found 1. The defect cost nothing in
+ * this repository (all TypeScript, where the two agree exactly: 919 edges each), which is why it
+ * survived to v0.23.2 — and everything in a consumer written in Java, Go, Python or Rust.
+ *
+ * Extracted here rather than left in `rtm/` because resolution is a fact about CODE, not about the
+ * requirement graph, and because `rtm/` and `hooks/` both already import `cpg/` — so this placement
+ * adds no layer edge. Choosing the direction at design time is the cheap moment; that is the whole
+ * subject of the slice this module belongs to.
+ *
+ * The founding rule is unchanged and is what makes every branch safe: resolve ONLY to a file the
+ * scan actually contains. An unresolvable specifier emits nothing rather than a guess.
+ *
+ * The rules below are MOVED, not rewritten. Their originating specs are cited by number rather
+ * than anchored, because the authority for this file is A-SPEC-688 alone.
+ */
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+function fsReadGoMod(p) {
+    try {
+        return fs.readFileSync(p, 'utf8').match(/^module\s+(\S+)/m)?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function createImportResolver(scanned, opts) {
+    const known = new Set(scanned.map((f) => f.sourcePath));
+    const EXTENSIONS = ['', '.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs', '.jsx', '.py',
+        '/index.ts', '/index.js', '/__init__.py'];
+    const firstKnown = (base) => EXTENSIONS.map((ext) => `${base}${ext}`).find((candidate) => known.has(candidate)) ?? null;
+    // A-SPEC-525.1 — the five languages' resolution rules, selected by the IMPORTING file's
+    // extension because resolution IS per-language semantics. The founding rule is unchanged
+    // everywhere: resolve only to files the scan actually contains; the ambiguous resolve to none.
+    const knownList = [...known];
+    const uniqueSuffix = (suffix) => {
+        const hits = knownList.filter((k) => k === suffix || k.endsWith(`/${suffix}`));
+        return hits.length === 1 ? hits[0] : null; // two files may not become a guess
+    };
+    // go.mod discovery: injected via opts when the caller knows it; otherwise walked up from the
+    // first Go file's ABSOLUTE path (bounded), so production builds resolve without extra wiring.
+    let goModCache;
+    const goModuleOf = () => {
+        if (opts?.goModule)
+            return opts.goModule;
+        if (goModCache !== undefined)
+            return goModCache ?? undefined;
+        goModCache = null;
+        const anyGo = scanned.find((f) => /\.go$/.test(f.sourcePath) && f.path);
+        if (anyGo) {
+            let dir = path.dirname(anyGo.path);
+            for (let hops = 0; hops < 12; hops++) {
+                try {
+                    const txt = fsReadGoMod(path.join(dir, 'go.mod'));
+                    if (txt !== null) {
+                        goModCache = txt;
+                        break;
+                    }
+                }
+                catch { /* keep walking */ }
+                const up = path.dirname(dir);
+                if (up === dir)
+                    break;
+                dir = up;
+            }
+        }
+        return goModCache ?? undefined;
+    };
+    const goPackage = (spec) => {
+        const mod = goModuleOf();
+        if (!mod || !(spec === mod || spec.startsWith(`${mod}/`)))
+            return []; // external, honestly
+        const dir = spec === mod ? '' : spec.slice(mod.length + 1);
+        const prefix = dir === '' ? '' : `${dir}/`;
+        return knownList.filter((k) => k.startsWith(prefix) && k.endsWith('.go')
+            && !k.endsWith('_test.go') && !k.slice(prefix.length).includes('/'));
+    };
+    const rustResolve = (fromFile, spec) => {
+        const segs = spec.split('::');
+        const head = segs.shift();
+        let baseDir;
+        if (head === 'crate') {
+            // the crate root is the src/ directory nearest above the importing file
+            const m = fromFile.match(/^(.*?src)\//);
+            baseDir = m ? m[1] : 'src';
+        }
+        else if (head === 'super') {
+            baseDir = path.posix.dirname(path.posix.dirname(fromFile));
+            while (segs[0] === 'super') {
+                // A-SPEC-527.1 — super:: above the crate root is an rustc error; resolving it pinned '.'
+                // and produced edges to repo-root files (adversarial sweep). Refuse.
+                if (baseDir === '.' || baseDir === '/')
+                    return null;
+                segs.shift();
+                baseDir = path.posix.dirname(baseDir);
+            }
+        }
+        else if (head === 'self') {
+            baseDir = path.posix.dirname(fromFile);
+        }
+        else {
+            return null; // external crate
+        }
+        const tryPath = (parts) => {
+            if (parts.length === 0)
+                return null;
+            const base = path.posix.normalize(path.posix.join(baseDir, ...parts));
+            if (known.has(`${base}.rs`))
+                return `${base}.rs`;
+            if (known.has(`${base}/mod.rs`))
+                return `${base}/mod.rs`;
+            return null;
+        };
+        // the last segment may be an ITEM, not a module — drop it once and retry
+        return tryPath(segs) ?? tryPath(segs.slice(0, -1));
+    };
+    const resolve = (fromFile, spec) => {
+        // A-SPEC-525.1 — language branches BEFORE the JS/Python-shaped fallthrough.
+        if (/\.go$/.test(fromFile))
+            return null; // Go fans out separately (a package is its files)
+        if (/\.rs$/.test(fromFile))
+            return rustResolve(fromFile, spec);
+        if (/\.java$/.test(fromFile))
+            return uniqueSuffix(`${spec.split('.').join('/')}.java`);
+        if (/\.cs$/.test(fromFile))
+            return uniqueSuffix(`${spec.split('.').join('/')}.cs`);
+        if (/\.(cpp|cc|cxx|hpp|h)$/.test(fromFile)) {
+            // A-SPEC-527.1 — an ABSOLUTE include is not a repository coordinate: joining it into the
+            // repo frame let `#include "/etc/passwd"` match a coincidentally-shaped scanned file
+            // (adversarial sweep). Absolute means absolute; it resolves to nothing here.
+            if (spec.startsWith('/'))
+                return null;
+            // extension preserved: the dotted split below would butcher `util/env.h`
+            const relative = path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), spec));
+            if (known.has(relative))
+                return relative;
+            return known.has(spec) ? spec : null; // repo-root-relative include
+        }
+        // A-SPEC-406
+        // A specifier without a leading dot used to be refused outright, on the ground that it names an
+        // external package. That holds for `node:fs` and `js-yaml`; it does NOT hold for Python, which
+        // writes intra-repository modules absolutely — `from src.core.memory_audit import X`. Measured
+        // on the jarvis corpus: 1060 specifiers, 0 relative, 542 naming a file the scan already had, and
+        // 0 import edges in the graph. The whole import layer was missing for that language because the
+        // resolver's shape was JS's.
+        //
+        // The rule the original was written under is unchanged and is what makes this safe: resolve
+        // ONLY to a file the scan actually contains. `os.path` becomes `os/path.py`, which is in no
+        // scan, so it still emits nothing. Nothing is invented; the dotted form is simply also read.
+        if (!spec.startsWith('.')) {
+            if (spec.includes(':'))
+                return null; // `node:fs` and friends are never a repository path
+            return firstKnown(path.posix.normalize(spec.split('.').filter(Boolean).join('/')));
+        }
+        // A-SPEC-289
+        // Python writes a relative import as `.b` / `..pkg.mod`, where the leading dots are LEVELS and
+        // the remaining dots are path separators — not the `./b` form JS uses. Treating `.b` as a path
+        // yields the literal name `.b`, which matches nothing. Detected by the absence of a slash: a
+        // specifier that already contains one is a JS-style path and is left alone.
+        let relative = spec;
+        if (!spec.includes('/')) {
+            const dots = spec.match(/^\.+/)[0].length;
+            const rest = spec.slice(dots).split('.').filter(Boolean).join('/');
+            relative = `${'../'.repeat(Math.max(0, dots - 1)) || './'}${rest}`;
+        }
+        return firstKnown(path.posix.normalize(path.posix.join(path.posix.dirname(fromFile), relative)));
+    };
+    return {
+        resolve,
+        fanOut: (fromFile, spec) => (/\.go$/.test(fromFile) ? goPackage(spec) : []),
+    };
+}

package/dist/holmes/cpg/language-capability.d.ts

@@ -54,6 +54,20 @@ export interface LanguageGap {
  * meet would bury the ones this answer actually rests on. A language with nothing missing drops out
  * entirely, so the report shrinks to nothing as extraction catches up rather than becoming noise.
  */
+/**
+ * @implements A-SPEC-689
+ * The gap shape for ONE capability, as a pure function of it.
+ *
+ * Split out so the concept can be pinned on a constructed capability instead of on whichever real
+ * language happens to lag. That was already the stated intent of the sibling test, but not its
+ * practice: the pin was moved from `.java` to `.cjs` when Java graduated, and `.cjs` has now
+ * graduated too, which would have moved it a third time — to nothing, because no advertised
+ * extension lags any more. A test that must be rewritten every time the product improves is not
+ * pinning the product; it is following it.
+ *
+ * Returns null when the capability has no gap at all.
+ */
+export declare function gapOf(ext: string, cap: LanguageCapability): LanguageGap | null;
 export declare function capabilityGapsFor(sourcePaths: readonly string[]): LanguageGap[];
 /** Every advertised extension must have an entry; a blank would be a silent overclaim. */
 export declare const ADVERTISED_EXTENSIONS: readonly string[];

package/dist/holmes/cpg/language-capability.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ADVERTISED_EXTENSIONS = exports.LANGUAGE_CAPABILITY = exports.EXTRACTABLE_RELATIONS = void 0;
 exports.capabilityFor = capabilityFor;
+exports.gapOf = gapOf;
 exports.capabilityGapsFor = capabilityGapsFor;
 exports.languageFamilyOf = languageFamilyOf;
 // @implements A-SPEC-289
@@ -67,8 +68,9 @@ exports.EXTRACTABLE_RELATIONS = ['calls', 'imports', 'inherits'];
 // @implements A-SPEC-289 — imports now resolve to FILE nodes when the specifier is relative and
 // names a scanned file; bare specifiers stay external and unresolved by design.
 const TS_FAMILY = { symbols: true, relations: ['calls', 'imports', 'inherits'], graphResolved: ['calls', 'imports', 'inherits'] };
-/** Symbols and calls only — no import edges, no inheritance. */
-const CALLS_ONLY = { symbols: true, relations: ['calls'], graphResolved: ['calls'] };
+// @implements A-SPEC-689 — CALLS_ONLY used to live here, for `.cjs` alone. `.cjs` graduated once it
+// was measured rather than assumed, leaving the shape with no member; the history it carried now
+// lives on the `.cjs` cell itself, where the correction can be read next to the value.
 // @implements A-SPEC-511.1
 /**
  * Calls AND inheritance. The five non-TS/Python languages moved here once their inheritance was
@@ -98,8 +100,16 @@ const FULL_RELATIONS = {
 exports.LANGUAGE_CAPABILITY = {
     '.ts': TS_FAMILY, '.mts': TS_FAMILY, '.cts': TS_FAMILY, '.tsx': TS_FAMILY,
     '.js': TS_FAMILY, '.mjs': TS_FAMILY, '.jsx': TS_FAMILY,
-    // CommonJS `require()` is not recovered as an import, unlike ESM `import` — measured.
-    '.cjs': CALLS_ONLY,
+    // @implements A-SPEC-689 — `.cjs` is the TS family, measured rather than assumed.
+    // This cell said CALLS_ONLY on the strength of `require('os')` producing no import. That much is
+    // true and stays pinned: an external package has no node to point at. But it was written as a
+    // statement about `require()` itself, and it is not. Measured 2026-09-18: a RELATIVE
+    // `require('./b')` IS recovered as an import, and `class Child extends Base` as an inherit, in
+    // `.cjs` exactly as in `.js`. The table under-declared two relations for as long as the only
+    // pinned case was the bare one — an error with no visible symptom, which is why it lasted. The
+    // sibling test now pins both forms, so the claim above this table is finally true in BOTH
+    // directions.
+    '.cjs': TS_FAMILY,
     // @implements A-SPEC-286 — the first language whose inheritance is both extracted AND resolved.
     '.py': { symbols: true, relations: ['calls', 'imports', 'inherits'], graphResolved: ['calls', 'imports', 'inherits'] },
     // @implements A-SPEC-511.1 — inheritance recovered: Java extends/implements, C# base_list,
@@ -122,6 +132,27 @@ function capabilityFor(ext) {
  * meet would bury the ones this answer actually rests on. A language with nothing missing drops out
  * entirely, so the report shrinks to nothing as extraction catches up rather than becoming noise.
  */
+/**
+ * @implements A-SPEC-689
+ * The gap shape for ONE capability, as a pure function of it.
+ *
+ * Split out so the concept can be pinned on a constructed capability instead of on whichever real
+ * language happens to lag. That was already the stated intent of the sibling test, but not its
+ * practice: the pin was moved from `.java` to `.cjs` when Java graduated, and `.cjs` has now
+ * graduated too, which would have moved it a third time — to nothing, because no advertised
+ * extension lags any more. A test that must be rewritten every time the product improves is not
+ * pinning the product; it is following it.
+ *
+ * Returns null when the capability has no gap at all.
+ */
+function gapOf(ext, cap) {
+    const gap = {
+        ext,
+        missing: exports.EXTRACTABLE_RELATIONS.filter((r) => !cap.relations.includes(r)),
+        extractedButUnresolved: cap.relations.filter((r) => !cap.graphResolved.includes(r)),
+    };
+    return gap.missing.length > 0 || gap.extractedButUnresolved.length > 0 ? gap : null;
+}
 function capabilityGapsFor(sourcePaths) {
     const present = new Set();
     for (const p of sourcePaths) {
@@ -130,15 +161,8 @@ function capabilityGapsFor(sourcePaths) {
             present.add(ext);
     }
     return [...present].sort()
-        .map((ext) => {
-        const cap = capabilityFor(ext);
-        return {
-            ext,
-            missing: exports.EXTRACTABLE_RELATIONS.filter((r) => !cap.relations.includes(r)),
-            extractedButUnresolved: cap.relations.filter((r) => !cap.graphResolved.includes(r)),
-        };
-    })
-        .filter((gap) => gap.missing.length > 0 || gap.extractedButUnresolved.length > 0);
+        .map((ext) => gapOf(ext, capabilityFor(ext)))
+        .filter((gap) => gap !== null);
 }
 /** Every advertised extension must have an entry; a blank would be a silent overclaim. */
 exports.ADVERTISED_EXTENSIONS = cpg_scanner_1.SCANNABLE_EXTENSIONS;

package/dist/holmes/cpg/proposed-content.d.ts

@@ -1,10 +1,16 @@
 import { CodeEdge } from './language-parser';
-import { ForbiddenEdgeRule } from './forbidden-edges';
+import { ForbiddenEdgeRule, type BaselineEntry } from './forbidden-edges';
 import { RequiredCallRule } from './required-calls';
 /** What the gate could actually see. `none` means no verdict was formed, not that nothing was wrong. */
 export type JudgedAs = 'full' | 'fragment' | 'none';
 export interface ProposedContentCheck {
     forbidden: ForbiddenEdgeRule[];
+    /**
+     * @implements A-SPEC-691
+     * Violations the project declared it already carries. Optional so every existing caller keeps
+     * working unchanged — absent means "no allowances", which is what the gate did before.
+     */
+    baselines?: BaselineEntry[];
     required: RequiredCallRule[];
     sourcePath: string;
     content: string;

package/dist/holmes/cpg/proposed-content.js

@@ -51,6 +51,13 @@ function checkProposedContent(opts) {
     const asScanned = [{ path: sourcePath, sourcePath, symbols: [], edges, implementsSpecs: [] }];
     const violations = [];
     for (const v of (0, forbidden_edges_1.findForbiddenEdgeViolations)(asScanned, forbidden ?? [])) {
+        // @implements A-SPEC-691 — a violation the project already declared it carries is not a denial.
+        // Without this the gate would be live while the escape hatch stayed dead: a project with legacy
+        // could declare a rule and then be unable to edit the files it named. "A rule that blocks
+        // adoption is not a rule, it is a barrier" (REQ-574). The predicate is SHARED with the
+        // scan-wide path, so a baseline cannot mean one thing in a report and another at the gate.
+        if ((0, forbidden_edges_1.isBaselined)(v, opts.baselines ?? []))
+            continue;
         violations.push(`${v.sourcePath}: ${v.rule}  (${v.kind} → ${v.to})`);
     }
     // Obligations only where the whole file is visible — see the asymmetry above.

package/dist/holmes/governance/approval-queue.d.ts

@@ -202,3 +202,36 @@ export declare function queueHint(root: string, req: {
 } & RequestDetails, opts?: {
     baseReasonBytes?: number;
 }): string;
+/**
+ * @implements A-SPEC-690
+ * Every request an operator can name — the candidate set a REFERENCE resolves against.
+ *
+ * The tracked queue is a decision inbox and deliberately excludes gate refusals (A-SPEC-563.1,
+ * measured 1,412 requests against 8 decisions). That routing is right and this does not undo it:
+ * the LIST still shows the inbox. But a reference is not a list — it is the operator naming the
+ * id the refusal just printed, and A-SPEC-576.1 already says such an id "must never make
+ * ungrantable". It did: `--grant <id>` resolved against the queue alone, so a shell refusal failed
+ * at reference resolution and never reached the refusal-log fallback that approve.ts already has.
+ *
+ * Measured 2026-09-19: `readRefusals` found req-9e92e52bd233 while `approve --grant` refused it.
+ */
+export declare function grantableRequests(root: string): PendingRequest[];
+/**
+ * @implements A-SPEC-690
+ * Which occurrences a decision has NOT already covered.
+ *
+ * Shared with `approve.ts`'s own lookup so the two never disagree about whether a request is open.
+ * A decision records HOW MANY occurrences it covered, so a retry is everything past that count —
+ * millisecond ties (measured flaky under the full suite) cannot lose it. Decisions written before
+ * the count existed fall back to the timestamp rule.
+ */
+export declare function openOccurrences(all: readonly RefusalRecord[], decided?: {
+    ts: string;
+    covered?: number;
+}): RefusalRecord[];
+/**
+ * @implements A-SPEC-690
+ * One id's refusals, in the shape a queue entry has — so the decision surface reads the same
+ * whichever store the request came from.
+ */
+export declare function asPendingRequest(id: string, occurrences: readonly RefusalRecord[]): PendingRequest;

package/dist/holmes/governance/approval-queue.js

@@ -44,6 +44,9 @@ exports.enqueueApprovalRequestDetailed = enqueueApprovalRequestDetailed;
 exports.appendQueueEvent = appendQueueEvent;
 exports.readQueue = readQueue;
 exports.queueHint = queueHint;
+exports.grantableRequests = grantableRequests;
+exports.openOccurrences = openOccurrences;
+exports.asPendingRequest = asPendingRequest;
 // @implements A-SPEC-244, A-SPEC-626
 const execution_context_1 = require("../project/execution-context");
 const root_1 = require("../project/root");
@@ -503,3 +506,85 @@ function queueHint(root, req, opts) {
         ? hint
         : denialLine;
 }
+/**
+ * @implements A-SPEC-690
+ * Every request an operator can name — the candidate set a REFERENCE resolves against.
+ *
+ * The tracked queue is a decision inbox and deliberately excludes gate refusals (A-SPEC-563.1,
+ * measured 1,412 requests against 8 decisions). That routing is right and this does not undo it:
+ * the LIST still shows the inbox. But a reference is not a list — it is the operator naming the
+ * id the refusal just printed, and A-SPEC-576.1 already says such an id "must never make
+ * ungrantable". It did: `--grant <id>` resolved against the queue alone, so a shell refusal failed
+ * at reference resolution and never reached the refusal-log fallback that approve.ts already has.
+ *
+ * Measured 2026-09-19: `readRefusals` found req-9e92e52bd233 while `approve --grant` refused it.
+ */
+function grantableRequests(root) {
+    const state = readQueue(root, { includeAllKinds: true });
+    const seen = new Set(state.pending.map((p) => p.id));
+    let refusals;
+    // Fail toward REFUSAL, never toward approval: an unreadable log removes candidates, so a
+    // reference stops resolving and no grant goes out. The opposite bias would turn a read error
+    // into an approval path.
+    try {
+        refusals = readRefusals(root);
+    }
+    catch {
+        refusals = [];
+    }
+    const byId = new Map();
+    for (const r of refusals) {
+        const list = byId.get(r.id);
+        if (list)
+            list.push(r);
+        else
+            byId.set(r.id, [r]);
+    }
+    const out = [...state.pending];
+    for (const [id, all] of byId) {
+        // The queue copy carries the decision history the single-use rule reads; the refusal copy does
+        // not. When both exist the queue wins, or granting once would stop closing the request.
+        if (seen.has(id))
+            continue;
+        const live = openOccurrences(all, state.decisions[id]);
+        if (live.length === 0)
+            continue;
+        out.push(asPendingRequest(id, live));
+    }
+    return out;
+}
+/**
+ * @implements A-SPEC-690
+ * Which occurrences a decision has NOT already covered.
+ *
+ * Shared with `approve.ts`'s own lookup so the two never disagree about whether a request is open.
+ * A decision records HOW MANY occurrences it covered, so a retry is everything past that count —
+ * millisecond ties (measured flaky under the full suite) cannot lose it. Decisions written before
+ * the count existed fall back to the timestamp rule.
+ */
+function openOccurrences(all, decided) {
+    if (!decided)
+        return [...all];
+    if (typeof decided.covered === 'number')
+        return all.slice(decided.covered);
+    return all.filter((r) => r.ts > decided.ts);
+}
+/**
+ * @implements A-SPEC-690
+ * One id's refusals, in the shape a queue entry has — so the decision surface reads the same
+ * whichever store the request came from.
+ */
+function asPendingRequest(id, occurrences) {
+    const latest = occurrences[occurrences.length - 1];
+    return {
+        id,
+        // The NEWEST occurrence is what the operator just saw, so it is what the decision names.
+        kind: latest.kind,
+        target: latest.target,
+        why: latest.why,
+        count: occurrences.length,
+        firstTs: occurrences[0].ts,
+        lastTs: latest.ts,
+        ...(latest.replica ? { replica: latest.replica } : {}),
+    };
+}

package/dist/holmes/hooks/pre-tool-use.js

@@ -1156,15 +1156,22 @@ function evaluateHook(input, specsDir, opts) {
         if (proposed && (0, write_target_1.specTargetOf)(opts.projectRoot, specsDir, p) === null) {
             const forbidden = [];
             const required = [];
+            // @implements A-SPEC-691 — the allowances travel with the rules. They come out of the SAME
+            // section and the same parse, so a rule and the baseline that tempers it can never be read
+            // from documents that disagree.
+            const baselines = [];
             for (const sp of specs) {
                 if (sp.type !== 'C-SPEC' || sp.status !== 'approved')
                     continue;
-                forbidden.push(...(0, forbidden_edges_1.parseForbiddenEdges)(sp.sections?.['Forbidden Edges'] ?? '').rules);
+                const parsed = (0, forbidden_edges_1.parseForbiddenEdges)(sp.sections?.['Forbidden Edges'] ?? '');
+                forbidden.push(...parsed.rules);
+                baselines.push(...parsed.baselines);
                 required.push(...(0, required_calls_1.parseRequiredCalls)(sp.sections?.['Layer Rules'] ?? '').rules);
             }
             if (forbidden.length > 0 || required.length > 0) {
                 const { violations } = (0, proposed_content_1.checkProposedContent)({
                     forbidden,
+                    baselines,
                     required,
                     // @implements A-SPEC-231 — the path is normalised before the prefix test. Adversarial
                     // pass 3, 2026-08-22: `./src/a/x.ts` and `src//a/x.ts` both walked past a rule scoped to

package/dist/holmes/hooks/session-start.js

@@ -197,6 +197,45 @@ if (require.main === module) {
                     }
                 }
                 catch { /* the banner is never a gate */ }
+                // @implements A-SPEC-687 — the other end of the loop `report` opened. Until now nothing read
+                // reported.jsonl, so a consumer who took the trouble to report a defect learned nothing when
+                // it was fixed. A LOCAL set intersection: a file this machine wrote against a list that
+                // shipped in the package. Nothing is sent; there is no device id and no MAC address, because
+                // a fingerprint identifies a DEFECT and not a person. Said once, then never again.
+                try {
+                    const { RESOLVED_REPORTS } = require('../project/resolved-reports');
+                    const { briefingLines, reportedFrom, announcedFrom, announcedTo } = require('../project/report-briefing');
+                    const dir = path.join(process.cwd(), '.ax', 'reports');
+                    const read = (f) => { try {
+                        return fs.readFileSync(path.join(dir, f), 'utf8');
+                    }
+                    catch {
+                        return null;
+                    } };
+                    const announced = announcedFrom(read('briefed.json'));
+                    const lines = briefingLines({
+                        reported: reportedFrom(read('reported.jsonl')),
+                        resolved: RESOLVED_REPORTS,
+                        installed: pkgVersion(),
+                        shipped: RESOLVED_REPORTS.map((r) => r.version),
+                        announced,
+                    });
+                    if (lines.length > 0) {
+                        out.hookSpecificOutput.additionalContext += '\n[Holmes-Kit] ' + lines.join('\n[Holmes-Kit] ');
+                        // Written ONLY when something was said: a marker recording an announcement that never
+                        // happened would silence a future briefing that should have spoken.
+                        const said = new Set(announced);
+                        for (const r of RESOLVED_REPORTS)
+                            if (lines.some((l) => l.includes(r.fingerprint)))
+                                said.add(r.fingerprint);
+                        try {
+                            fs.mkdirSync(dir, { recursive: true });
+                            fs.writeFileSync(path.join(dir, 'briefed.json'), announcedTo(said));
+                        }
+                        catch { /* the briefing is delivered; recording it is best-effort */ }
+                    }
+                }
+                catch { /* the banner is never a gate */ }
                 process.stdout.write(JSON.stringify({ hookSpecificOutput: out.hookSpecificOutput }));
                 if (out.shouldRefresh) {
                     // Detached, unref'd child so the session start does not wait on the network. The refresh

package/dist/holmes/hooks/stop.d.ts

@@ -5,6 +5,10 @@ import { type KnownDefectJudgement } from '../rtm/known-defects';
 import { type CiVerdict } from '../project/ci-runs';
 import { type DistVerdict } from '../project/dist-freshness';
 import { type AnalysisVerdict } from '../project/analysis-currency';
+import { judgeForbiddenEdges } from '../cpg/forbidden-edges';
+import type { ScannedFile } from '../cpg/cpg-scanner';
+/** @implements A-SPEC-693 */
+export type ForbiddenEdgeJudgement = ReturnType<typeof judgeForbiddenEdges>;
 export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;
 export declare function collectSemanticCoverage(root: string, tier?: {
     tier: string;
@@ -55,6 +59,11 @@ export interface StopEvidence {
      * turn's source edits. Absent when the workspace never analysed anything.
      */
     analysis?: AnalysisVerdict;
+    /**
+     * @implements A-SPEC-693 — the scan-wide forbidden-edge judgement over the approved C-SPECs.
+     * Absent when the project declares no rule, or when the hook could not look; never a block.
+     */
+    forbiddenEdges?: ForbiddenEdgeJudgement;
     /** @implements A-SPEC-683 — the rendered coverage line the refresh child recorded; already judged. */
     semantic?: string;
     /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
@@ -315,7 +324,34 @@ export declare function __setWiredSpecsForTest(v: string | undefined): void;
 export declare function guardCountOrZero(sessionId: string, read?: (id: string) => number): number;
 export declare function readGuardCount(sessionId: string): number;
 /**
- * Exported for the §19 race discriminator: the persistence layer was the untested half (round-11),
- * and a test that can only reach it through a spawned hook cannot pin what the lock does.
+ * @implements A-SPEC-693
+ * The scan-wide forbidden-edge judgement, over the SAME rules the pre-edit gate reads: approved
+ * C-SPECs only, rules and baselines out of one parse of one section.
+ *
+ * Returns `undefined` when no rule is declared — the project never adopted this, so it pays nothing
+ * and hears nothing. The scan is handed in rather than made here: the Stop hook already scans once a
+ * turn for the cycle ratchet, and scanning is that hook's dominant cost.
+ */
+export declare function collectForbiddenEdgeJudgement(specs: readonly Spec[], scanned: ScannedFile[], now: Date): ForbiddenEdgeJudgement | undefined;
+/**
+ * @implements A-SPEC-688
+ * The code graph's cycles, judged where the code exists — extracted from the hook body so the
+ * judgement is observable without driving a whole Stop turn.
+ *
+ * Returns `undefined` when the scan could not run at all. That is NOT "no cycles": the caller must
+ * keep the article silent rather than report a clean tree, because "we could not look" and "there
+ * is nothing there" are different facts (REQ-574).
+ *
+ * @implements A-SPEC-693 — `shared` is a scan the caller already made. When given it is BELIEVED
+ * and no second scan runs, so one turn pays for one scan however many judgements read it.
  */
+export declare function scanCodeCycles(root: string, shared?: ScannedFile[]): {
+    current: import('../cpg/cycle-detect').Cycle[];
+    allowed: string[];
+    mode: 'strict' | 'track' | 'off';
+    scope: {
+        judged: string[];
+        unavailable: string[];
+    };
+} | undefined;
 export declare function writeGuardCount(sessionId: string, n: number): boolean;