@holmes-lab/holmes-kit 0.14.0 → 0.16.0

package/dist/holmes/mcp/tool-schemas.js

@@ -330,7 +330,7 @@ exports.TOOL_SCHEMAS = {
         },
     },
     rtm_impact: {
-        description: 'Given changed symbol qualified-names, return the impacted SPEC node ids reachable through @implements/depends_on edges ({ impacted }).',
+        description: 'Given changed symbol qualified-names, return the impacted SPEC node ids reachable through @implements/depends_on edges ({ impacted, impactedSummaries: [{id, summary}] — the spec intent sentence beside each id, informational only }).',
         inputSchema: {
             type: 'object',
             properties: {

package/dist/holmes/review/judgement-bundle.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The judgement bundle: what the reviewing agent RECEIVES, split by epistemic kind.
+ *
+ * The owner's correction is the whole design: this is a TECHNICAL graph, and technical facts are
+ * crisp — a symbol is defined in one file or it is not. Every measured failure of graded tools on
+ * crisp facts (the ranker deleting its own answer, anchor noise, the 0.25-constant confidence)
+ * says the same thing, and the S0 misjudgement decomposition (revision 7) named the exact shapes:
+ * 17% of false picks were facts a single crisp query would have refuted (symbol ownership, surface
+ * presence), and the other 83% — target attribution — are best treated with HISTORY facts
+ * (git log -S is deterministic), not with more similarity.
+ *
+ * So: FACT results carry a verdict, the query that produced it, and the tree it was true of. There
+ * is no field for a similarity or a score — the type is the wall (the QueueEventLite idiom).
+ * Candidates stay labeled 'candidate' and never get promoted. One self-evaluation, one optional
+ * reinforcement, bounded by structure.
+ */
+export interface FactResult {
+    kind: 'symbol-owner' | 'surface-presence' | 'feature-history';
+    query: string;
+    verdict: boolean | string[];
+    basis: string;
+    asOf: string;
+}
+export interface GitFacts {
+    /** Files defining the named symbol (assignment/def/class shapes) in the pinned tree. */
+    grepOwners(name: string): string[];
+    /** Does the file already carry any of these terms, in the pinned tree? */
+    grepInFile(file: string, terms: string[]): boolean;
+    /** Files last touching this term/feature across pre-pin history (git log -S shape). */
+    logTouched(term: string): string[];
+    /** The pinned tree these answers are true of. */
+    asOf(): string;
+}
+export interface JudgementBundle {
+    header: string;
+    facts: FactResult[];
+    reinforced: boolean;
+    candidates: Array<{
+        file: string;
+        excerpt: string;
+        label: 'candidate';
+    }>;
+}
+export declare const MAX_FACT_QUERIES = 8;
+export declare const BUNDLE_HEADER: string;
+export declare function buildJudgementBundle(subject: string, candidates: Array<{
+    file: string;
+    excerpt: string;
+}>, facts: GitFacts): JudgementBundle;

package/dist/holmes/review/judgement-bundle.js

@@ -0,0 +1,108 @@
+"use strict";
+// @implements A-SPEC-567.1
+/**
+ * The judgement bundle: what the reviewing agent RECEIVES, split by epistemic kind.
+ *
+ * The owner's correction is the whole design: this is a TECHNICAL graph, and technical facts are
+ * crisp — a symbol is defined in one file or it is not. Every measured failure of graded tools on
+ * crisp facts (the ranker deleting its own answer, anchor noise, the 0.25-constant confidence)
+ * says the same thing, and the S0 misjudgement decomposition (revision 7) named the exact shapes:
+ * 17% of false picks were facts a single crisp query would have refuted (symbol ownership, surface
+ * presence), and the other 83% — target attribution — are best treated with HISTORY facts
+ * (git log -S is deterministic), not with more similarity.
+ *
+ * So: FACT results carry a verdict, the query that produced it, and the tree it was true of. There
+ * is no field for a similarity or a score — the type is the wall (the QueueEventLite idiom).
+ * Candidates stay labeled 'candidate' and never get promoted. One self-evaluation, one optional
+ * reinforcement, bounded by structure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUNDLE_HEADER = exports.MAX_FACT_QUERIES = void 0;
+exports.buildJudgementBundle = buildJudgementBundle;
+exports.MAX_FACT_QUERIES = 8;
+exports.BUNDLE_HEADER = 'fact 는 검증된 참/거짓(조회식·기준 트리 동봉), candidate 는 미검증 후보다. 조회가 기억을 이긴다 — '
+    + 'fact 와 충돌하는 전제는 버려라. 기존 소유 파일이 후보에 없으면 신규-파일 가설(빈 선택)을 고려하라.';
+/** Decidable subquery tokens out of a subject line: quoted strings, identifier-shaped words and
+ * feature tags — deterministic order, capped. Whatever cannot be extracted stays EVIDENCE-only. */
+function extractTokens(subject) {
+    const out = [];
+    const push = (t) => { if (t.length >= 3 && !out.includes(t))
+        out.push(t); };
+    for (const m of subject.matchAll(/"([^"]+)"|'([^']+)'/g))
+        push(m[1] ?? m[2]);
+    for (const m of subject.matchAll(/\b([A-Za-z_][A-Za-z0-9_]*(?:_[A-Za-z0-9_]+)+|[A-Z]{2,}[A-Z0-9_]*)\b/g))
+        push(m[1]);
+    for (const m of subject.matchAll(/\bF\d{3}\b/g))
+        push(m[0]);
+    return out.slice(0, exports.MAX_FACT_QUERIES);
+}
+function buildJudgementBundle(subject, candidates, facts) {
+    const asOf = (() => { try {
+        return facts.asOf();
+    }
+    catch {
+        return 'unknown';
+    } })();
+    const results = [];
+    const candidateFiles = new Set(candidates.map((c) => c.file));
+    const tokens = extractTokens(subject);
+    let historyRan = false;
+    let reinforced = false;
+    // Decidable-first: close what a crisp query CAN close. Each answer carries the query that made it
+    // and the tree it is true of — an unanswerable (throwing) query is silently absent, never guessed.
+    for (const tok of tokens) {
+        try {
+            const owners = facts.grepOwners(tok);
+            if (owners.length > 0) {
+                results.push({ kind: 'symbol-owner', query: tok, verdict: owners,
+                    basis: `git grep -l '${tok} =' | def/class — 정의 소유 파일`, asOf });
+            }
+        }
+        catch { /* absent, not guessed */ }
+    }
+    for (const c of candidates) {
+        try {
+            if (tokens.length > 0 && facts.grepInFile(c.file, tokens)) {
+                results.push({ kind: 'surface-presence', query: `${c.file} ∋ {${tokens.slice(0, 3).join(',')}}`,
+                    verdict: true, basis: 'git grep — 후보가 해당 표면을 이미 보유', asOf });
+            }
+        }
+        catch { /* absent, not guessed */ }
+    }
+    const featureTag = tokens.find((t) => /^F\d{3}$/.test(t)) ?? tokens[0];
+    if (featureTag !== undefined) {
+        try {
+            const touched = facts.logTouched(featureTag);
+            historyRan = true;
+            if (touched.length > 0) {
+                results.push({ kind: 'feature-history', query: featureTag, verdict: touched,
+                    basis: `git log -S '${featureTag}' — 이 피처를 마지막으로 만진 파일들`, asOf });
+                // Self-evaluation, once: owners entirely OUTSIDE the candidate set is the S0 shape that
+                // misled the judge (c0/c17/c25 …) — reinforce with ONE more history probe on the next token.
+                if (!touched.some((f) => candidateFiles.has(f))) {
+                    reinforced = true;
+                    const second = tokens.find((t) => t !== featureTag);
+                    if (second !== undefined) {
+                        try {
+                            const more = facts.logTouched(second);
+                            if (more.length > 0) {
+                                results.push({ kind: 'feature-history', query: second, verdict: more,
+                                    basis: `git log -S '${second}' — 보강 1회(소유 파일이 후보 밖)`, asOf });
+                            }
+                        }
+                        catch { /* the reinforcement is best-effort too */ }
+                    }
+                }
+            }
+        }
+        catch {
+            void historyRan;
+        }
+    }
+    return {
+        header: exports.BUNDLE_HEADER,
+        facts: results,
+        reinforced,
+        candidates: candidates.map((c) => ({ ...c, label: 'candidate' })),
+    };
+}

package/dist/holmes/review/run-replay.d.ts

@@ -203,6 +203,9 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
     contentVerify?: boolean;
     /** @implements A-SPEC-485 — holdout window start; default 0 is the pinned main window. */
     offset?: number;
+    /** @implements A-SPEC-567.2 — attach the judgement bundle (FACT channel + labels) to each
+     * caseDump row. Absent = the row is byte-identical to the pre-option shape. */
+    judgementBundle?: boolean;
     /**
      * @implements A-SPEC-487 — per-case dump for the blind judgment protocol. The pins stay on
      * the 1-pass result; the dump carries the 2-pass (semantic-injected) output when
@@ -225,6 +228,8 @@ export declare function runReplay(corpus: ReplayCorpus, limit: number, opts?: {
         truthFiles: string[];
         /** @implements A-SPEC-489 — present only when dumpBodies was asked. */
         bodies?: Record<string, string>;
+        /** @implements A-SPEC-567.2 — present only when judgementBundle was asked. */
+        judgementBundle?: import('./judgement-bundle').JudgementBundle;
     }) => void;
     /** @implements A-SPEC-487 — 2-pass semantic injection for the dump only, never the pins. */
     productSemantic?: {

package/dist/holmes/review/run-replay.js

@@ -42,6 +42,7 @@ exports.semanticCaseRanking = semanticCaseRanking;
 // @implements A-SPEC-378
 // @implements A-SPEC-402
 const fs = __importStar(require("node:fs"));
+const node_child_process_1 = require("node:child_process");
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
 const cpg_scanner_1 = require("../cpg/cpg-scanner");
@@ -275,12 +276,43 @@ async function runReplay(corpus, limit, opts = {}) {
                             catch { /* unreadable candidate: omitted */ }
                         }
                     }
+                    // @implements A-SPEC-567.2 — the FACT channel reads the PARENT tree and pre-case history
+                    // only (git object queries by sha — deterministic, and the case commit itself is never
+                    // consulted, so the blind protocol survives). Every query failure is a silent absence.
+                    let judgementBundle;
+                    if (opts.judgementBundle === true) {
+                        try {
+                            const { buildJudgementBundle } = require('./judgement-bundle');
+                            const gitQ = (args) => {
+                                try {
+                                    return (0, node_child_process_1.execFileSync)('git', ['-C', corpus.root, ...args], { encoding: 'utf8', stdio: 'pipe' });
+                                }
+                                catch {
+                                    return '';
+                                }
+                            };
+                            const stripRef = (line) => line.replace(/^[^:]*:/, '');
+                            const gitFacts = {
+                                grepOwners: (name) => [...new Set(gitQ(['grep', '-l', '-E', `(^|[^A-Za-z0-9_])${name}\\s*=|def ${name}|class ${name}`, parent, '--', ...corpus.sourcePathspec])
+                                        .split('\n').filter(Boolean).map(stripRef))].slice(0, 5),
+                                grepInFile: (file, terms) => gitQ(['grep', '-c', '-E', terms.map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|'), parent, '--', file]).trim() !== '',
+                                logTouched: (term) => [...new Set(gitQ(['log', '-S', term, '--name-only', '--format=', '-n', '8', parent, '--', ...corpus.sourcePathspec])
+                                        .split('\n').filter((f) => f && corpus.isSource(f)))].slice(0, 5),
+                                asOf: () => parent,
+                            };
+                            judgementBundle = buildJudgementBundle(c.subject, dumpResult.candidates.map((x) => ({ file: x.file, excerpt: bodies?.[x.file] ?? '' })), gitFacts);
+                        }
+                        catch {
+                            judgementBundle = undefined;
+                        }
+                    }
                     opts.caseDump({
                         commit: c.commit, subject: c.subject,
                         candidates: dumpResult.candidates,
                         rankedImpact: dumpResult.impacts?.rankedImpact ?? [],
                         truthFiles: c.files,
                         ...(bodies !== undefined ? { bodies } : {}),
+                        ...(judgementBundle !== undefined ? { judgementBundle } : {}),
                     });
                 }
                 // Same case, same truth, same `topN` the product used — an arm scored against a different

package/dist/holmes/review/test-outcomes.d.ts

@@ -1,5 +1,7 @@
 import { TestOutcome } from './test-runner';
 export declare const OUTCOMES_FILE: string;
+export declare function outcomesFilename(replica: string): string;
+export declare function isOutcomesFilename(name: string): boolean;
 /**
  * A durable, append-only record of a per-A-SPEC test outcome (REQ-534 RED-first evidence). Unlike
  * `test-evidence.json` (overwritten each run), the SEQUENCE matters here — a red-assertion followed
@@ -14,9 +16,22 @@ export interface OutcomeRecord {
     head: string;
     testFileDigest?: string;
 }
-/** Append outcome records as JSONL lines. Fail-open (recording must never break a run). */
+/**
+ * Append outcome records as JSONL lines. Fail-open (recording must never break a run).
+ *
+ * @implements A-SPEC-562.1 — writes to THIS machine's chain (`test-outcomes.<replica>.jsonl`), never
+ * to the shared legacy file, so two machines appending in parallel produce two files git merges
+ * without a conflict. The call site is unchanged; only the destination moved.
+ */
 export declare function appendOutcomes(root: string, records: OutcomeRecord[]): boolean;
-/** Read every outcome record; missing file → [], broken lines skipped (same convention as the other ledgers). */
+/**
+ * Read every outcome record; missing file → [], broken lines skipped (same convention as the other ledgers).
+ *
+ * @implements A-SPEC-562.1 — reads the legacy file AND every replica chain, merged by `ts`. The sort
+ * is what keeps ART-8 honest after a merge: the article reads a red-assertion FOLLOWED BY a green, and
+ * with two machines that pair can straddle two files. A stable sort keeps same-timestamp records in
+ * read order rather than inventing an ordering between them.
+ */
 export declare function readOutcomes(root: string): OutcomeRecord[];
 /**
  * @implements A-SPEC-534.5

package/dist/holmes/review/test-outcomes.js

@@ -34,6 +34,8 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OUTCOMES_FILE = void 0;
+exports.outcomesFilename = outcomesFilename;
+exports.isOutcomesFilename = isOutcomesFilename;
 exports.appendOutcomes = appendOutcomes;
 exports.readOutcomes = readOutcomes;
 exports.buildOutcomeRecords = buildOutcomeRecords;
@@ -41,11 +43,30 @@ exports.groupOutcomesByAspec = groupOutcomesByAspec;
 // @implements A-SPEC-534.3
 const fs = __importStar(require("node:fs"));
 const path = __importStar(require("node:path"));
+const replica_id_1 = require("../governance/replica-id");
 exports.OUTCOMES_FILE = path.join('.ax', 'ledger', 'test-outcomes.jsonl');
-/** Append outcome records as JSONL lines. Fail-open (recording must never break a run). */
+// @implements A-SPEC-562.1 — outcomes join the ledger's REPLICA convention (A-SPEC-148): one file per
+// machine, so two machines appending never conflict on merge and a colleague's clone carries both
+// histories. The shape mirrors `isLedgerFilename` exactly — legacy single file OR a dot-free segment —
+// because two rules disagreeing about the same file is worse than either being wrong. Wired below.
+const OUTCOMES_LEGACY = 'test-outcomes.jsonl';
+const OUTCOMES_REPLICA_FILE = /^test-outcomes\.([^.]+)\.jsonl$/;
+function outcomesFilename(replica) {
+    return `test-outcomes.${replica}.jsonl`;
+}
+function isOutcomesFilename(name) {
+    return name === OUTCOMES_LEGACY || OUTCOMES_REPLICA_FILE.test(name);
+}
+/**
+ * Append outcome records as JSONL lines. Fail-open (recording must never break a run).
+ *
+ * @implements A-SPEC-562.1 — writes to THIS machine's chain (`test-outcomes.<replica>.jsonl`), never
+ * to the shared legacy file, so two machines appending in parallel produce two files git merges
+ * without a conflict. The call site is unchanged; only the destination moved.
+ */
 function appendOutcomes(root, records) {
     try {
-        const file = path.join(root, exports.OUTCOMES_FILE);
+        const file = path.join(root, '.ax', 'ledger', outcomesFilename((0, replica_id_1.resolveReplicaId)(root)));
         fs.mkdirSync(path.dirname(file), { recursive: true });
         fs.appendFileSync(file, records.map((r) => `${JSON.stringify(r)}\n`).join(''));
         return true;
@@ -54,30 +75,48 @@ function appendOutcomes(root, records) {
         return false;
     }
 }
-/** Read every outcome record; missing file → [], broken lines skipped (same convention as the other ledgers). */
+/**
+ * Read every outcome record; missing file → [], broken lines skipped (same convention as the other ledgers).
+ *
+ * @implements A-SPEC-562.1 — reads the legacy file AND every replica chain, merged by `ts`. The sort
+ * is what keeps ART-8 honest after a merge: the article reads a red-assertion FOLLOWED BY a green, and
+ * with two machines that pair can straddle two files. A stable sort keeps same-timestamp records in
+ * read order rather than inventing an ordering between them.
+ */
 function readOutcomes(root) {
-    let text;
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
     try {
-        text = fs.readFileSync(path.join(root, exports.OUTCOMES_FILE), 'utf8');
+        names = fs.readdirSync(dir).filter(isOutcomesFilename).sort();
     }
     catch {
         return [];
     }
     const out = [];
-    for (const line of text.split('\n')) {
-        const s = line.trim();
-        if (!s)
-            continue;
+    let i = 0;
+    for (const name of names) {
+        let text;
         try {
-            const r = JSON.parse(s);
-            if (r && typeof r === 'object' && typeof r.aspec === 'string' && typeof r.outcome === 'string'
-                && typeof r.ts === 'string' && typeof r.head === 'string') {
-                out.push(r);
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && typeof r.aspec === 'string' && typeof r.outcome === 'string'
+                    && typeof r.ts === 'string' && typeof r.head === 'string') {
+                    out.push({ r: r, i: i++ });
+                }
             }
+            catch { /* skip a corrupt line rather than fail the whole read */ }
         }
-        catch { /* skip a corrupt line rather than fail the whole read */ }
     }
-    return out;
+    return out.sort((a, b) => (a.r.ts < b.r.ts ? -1 : a.r.ts > b.r.ts ? 1 : a.i - b.i)).map((e) => e.r);
 }
 /**
  * @implements A-SPEC-534.5

package/dist/holmes/rtm/impact-advisory.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The impact advisory: what the Files-to-Touch declaration MISSES, computed from the call graph at
+ * the moment of sealing. jarvis proposal #1, admitted on our own measured record — of fourteen
+ * graph mechanisms, the only win was the IMPACT axis (PPR, three corpora), and REQ-565 established
+ * the "declaration vs machine" gate pattern this extends.
+ *
+ * ONE HOP, NEVER CLOSURE: caller closure measured 59 extra files and zero answers across twelve
+ * commits ("closure is impact, not localization"). ADVISORY, NEVER VERDICT: nothing here can change
+ * ok/refuse/grant (Judgments must not be budgeted). NO GUESSING: an unreadable graph yields null,
+ * not an estimate.
+ */
+export interface GraphLike {
+    nodeIdsInFile(relPath: string): string[];
+    callersOf(id: string): string[];
+    /** @implements A-SPEC-568.2 — the node's intent sentence, or null; information only, never a verdict input. */
+    summaryOf(id: string): string | null;
+}
+export interface ImpactAdvisory {
+    files: Array<{
+        path: string;
+        anchors: Array<{
+            id: string;
+            summary: string | null;
+        }>;
+    }>;
+    more: number;
+    graphAsOf?: string;
+}
+export declare const ADVISORY_CAP = 10;
+export declare function declaredImpactGap(fttFiles: string[], graph: GraphLike, readFile: (rel: string) => string | null, opts?: {
+    cap?: number;
+}): ImpactAdvisory | null;
+/**
+ * @implements A-SPEC-566.2
+ * The observation ledger: every advisory the act produced, so its false-positive rate can be
+ * MEASURED before anyone proposes promoting it to a hard gate (the August rtm_reindex lesson).
+ * Repo-relative paths, spec ids and integers only — nothing else has a field.
+ */
+export interface AdvisoryRecord {
+    aspec: string;
+    files: string[];
+    more: number;
+    graphAsOf?: string;
+    ts: string;
+    replica?: string;
+}
+export declare function appendImpactAdvisory(root: string, rec: AdvisoryRecord): boolean;
+export declare function readImpactAdvisories(root: string): AdvisoryRecord[];

package/dist/holmes/rtm/impact-advisory.js

@@ -0,0 +1,175 @@
+"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.ADVISORY_CAP = void 0;
+exports.declaredImpactGap = declaredImpactGap;
+exports.appendImpactAdvisory = appendImpactAdvisory;
+exports.readImpactAdvisories = readImpactAdvisories;
+// @implements A-SPEC-566.1
+// @implements A-SPEC-566.2
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const replica_id_1 = require("../governance/replica-id");
+exports.ADVISORY_CAP = 10;
+/** The ONLY shape allowed into the ledger: `seg/seg/…` of word characters, dots and dashes —
+ * no leading slash, no drive letter, no backslash, no empty or `..` segment. */
+function isRepoRelative(p) {
+    if (p === '' || p.includes('\\') || p.includes(':'))
+        return false;
+    const segs = p.split('/');
+    // Round-4: '.' segments made `src/./b.ts` dodge a declared `src/b.ts`, and the ASCII-only \w
+    // silently dropped findings in non-ASCII filenames (the 한글파일 evidence discipline of 563.3).
+    // Unicode letters/digits are leak-safe; dot-segments are not path characters, they are aliases.
+    return segs.every((s) => /^[\p{L}\p{N}_.-]+$/u.test(s) && s !== '..' && s !== '.');
+}
+/** `@implements <spec-id>` ids out of a file's text — the anchor idiom, read-only. */
+function anchorsIn(text) {
+    const out = [];
+    for (const m of text.matchAll(/@implements\s+((?:A|T|H|C)-SPEC-[\d.]+|REQ-\d+)/g)) {
+        if (!out.includes(m[1]))
+            out.push(m[1]);
+    }
+    return out;
+}
+function declaredImpactGap(fttFiles, graph, readFile, opts) {
+    try {
+        const cap = opts?.cap ?? exports.ADVISORY_CAP;
+        const declared = new Set(fttFiles.map((f) => f.replace(/\\/g, '/')));
+        const outside = new Set();
+        for (const ftt of declared) {
+            for (const nodeId of graph.nodeIdsInFile(ftt)) {
+                for (const caller of graph.callersOf(nodeId)) {
+                    const at = caller.lastIndexOf('@');
+                    if (at === -1)
+                        continue; // a node without a file cannot be a finding
+                    const file = caller.slice(at + 1);
+                    // Adversarial rounds 2-3: the record's no-secret contract says REPO-RELATIVE ONLY. A deny
+                    // list (round-2: '/', 'C:', '..') let UNC paths through one round later — so this is an
+                    // ALLOW list: plain slash-separated word segments, no '..' segment, nothing else. What
+                    // does not look like an in-repo relative path is dropped, never normalized into one.
+                    if (!isRepoRelative(file))
+                        continue;
+                    if (!declared.has(file))
+                        outside.add(file);
+                }
+            }
+        }
+        if (outside.size === 0)
+            return null;
+        const sorted = [...outside].sort();
+        const shown = sorted.slice(0, cap);
+        return {
+            files: shown.map((path) => {
+                let ids = [];
+                try {
+                    const text = readFile(path);
+                    if (typeof text === 'string')
+                        ids = anchorsIn(text);
+                }
+                catch { /* anchors stay [] */ }
+                // @implements A-SPEC-568.2 — the anchor's intent sentence rides BESIDE the id, read from the
+                // graph S1 built. Information only: nothing below this line feeds files/more/ordering, and a
+                // failing lookup downgrades to null rather than killing the finding (an advisory never guesses).
+                return {
+                    path,
+                    anchors: ids.map((id) => {
+                        let summary = null;
+                        try {
+                            summary = graph.summaryOf(`SPEC:${id}`);
+                        }
+                        catch { /* summary stays null */ }
+                        return { id, summary };
+                    }),
+                };
+            }),
+            more: sorted.length - shown.length,
+        };
+    }
+    catch {
+        return null;
+    } // an advisory never guesses
+}
+const ADVISORY_FILE_RE = /^impact-advisories\.([^.]+)\.jsonl$/;
+function appendImpactAdvisory(root, rec) {
+    try {
+        if (!fs.existsSync(path.join(root, '.ax')))
+            return false;
+        let replica = 'local';
+        try {
+            replica = (0, replica_id_1.resolveReplicaId)(root) || 'local';
+        }
+        catch { /* keep the fallback */ }
+        const file = path.join(root, '.ax', 'ledger', `impact-advisories.${replica}.jsonl`);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.appendFileSync(file, `${JSON.stringify({ ...rec, replica })}\n`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function readImpactAdvisories(root) {
+    const dir = path.join(root, '.ax', 'ledger');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter((n) => ADVISORY_FILE_RE.test(n)).sort();
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const name of names) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split('\n')) {
+            const s = line.trim();
+            if (!s)
+                continue;
+            try {
+                const r = JSON.parse(s);
+                if (r && typeof r === 'object' && typeof r.aspec === 'string' && Array.isArray(r.files) && typeof r.ts === 'string') {
+                    out.push(r);
+                }
+            }
+            catch { /* a corrupt line never breaks the read */ }
+        }
+    }
+    return out;
+}

package/dist/holmes/rtm/localize.js

@@ -223,6 +223,13 @@ function localizeIssue(issueText, scanned, specs, topN = 10) {
     for (const id of citations.cited)
         if (!matchedSpecs.includes(id))
             matchedSpecs.push(id);
+    // A spec-intent-vector injection was wired here (REQ-568 S3) and REVERTED on its pre-registered
+    // replay: over 441 held-out traceability cases the assist was byte-identical to this lexical
+    // path — long queries already match ~371 specs lexically (the semantic top-3 was a subset in
+    // 23/23 samples), and in the lexical-zero segment the A-SPEC-399 reorder-not-admit rule forbids
+    // exactly the admission recovery would need. The S-491 embedding win belongs to direct
+    // query→file ranking, not to this layer. Do not re-add without a NEW pre-registered corpus of
+    // short uncited requests AND an admission rule of its own.
     const matchedSpecSet = new Set(matchedSpecs);
     // Vendored/mirrored trees (review D4): an identical copy under reference/vendor must not outrank —
     // or lexically tie-break above — the live source. Their scores are halved and ties break toward

package/dist/holmes/rtm/rtm-builder.d.ts

@@ -57,6 +57,14 @@ export interface BuildRtmOptions {
      */
     fileDigest?: (sourcePath: string) => string | undefined;
 }
+/**
+ * @implements A-SPEC-568.1
+ * `"<title> — <intent first sentence>"`, EXTRACTED — never generated. Same spec store, same bytes:
+ * the whole function is whitespace folding, one regex, one slice. A missing, blank or still-TODO
+ * intent section degrades to the title alone (spec_create stubs sections as `TODO`, and "TODO" as
+ * an intent sentence would be noise wearing a dash).
+ */
+export declare function specSummary(s: Spec): string;
 /**
  * Adds one scanned file's CODE nodes and `implements` edges to the graph,
  * tagged with that file's sourcePath so RtmGraph.removeBySource(f.sourcePath)