@holmes-lab/holmes-kit 0.15.0 → 0.16.0

package/dist/holmes/mcp/handlers.js

@@ -151,7 +151,8 @@ const cacheDirFor = (root) => {
 };
 // @implements A-SPEC-283 — bumped whenever the graph's node/edge shape changes, so a store written
 // by an older build is rebuilt rather than read with new assumptions.
-const RTM_GRAPH_SCHEMA = 'rtm-graph/2';
+// @implements A-SPEC-568.1 — /3: nodes gained the intent `summary` column.
+const RTM_GRAPH_SCHEMA = 'rtm-graph/3';
 const RTM_EXTRACTOR_VERSION = 'holmes-rtm/1';
 const cachedScan = (root, repoRoot = root) => new cpg_scanner_1.CpgScanner(undefined, new scan_cache_1.ScanFileCache(cacheDirFor(root))).scan(root, repoRoot);
 // @implements A-SPEC-131
@@ -1684,7 +1685,46 @@ function makeRawHandlers(store, opts) {
             if (approveResolved.source === 'grant' && approveResolved.root && approveResolved.approval.nonce) {
                 (0, approval_grants_1.consumeGrantFile)(approveResolved.root, approveResolved.approval.nonce);
             }
-            return { approved: a.id, digest };
+            // @implements A-SPEC-566.2 — the impact advisory rides the SUCCESS, after the seal is done:
+            // the verdict is already committed, so nothing here can change it (advisory, never gate —
+            // Judgments must not be budgeted). Reuses the persisted graph READ-ONLY; it never scans,
+            // parses or builds (scan:build measured 20~38x — an approval must not pay that), and every
+            // failure below degrades to "no advisory field" on an otherwise identical response.
+            let impactAdvisory;
+            try {
+                if (spec.type === 'A-SPEC' && a.root) {
+                    const dbPath = path.join(a.root, '.ax', 'rtm.sqlite');
+                    if (fs.existsSync(dbPath)) {
+                        const { declaredImpactGap, appendImpactAdvisory } = require('../rtm/impact-advisory');
+                        const { filesToTouch } = require('../spec/compat-impact');
+                        const { RtmGraph } = require('../rtm/rtm-graph');
+                        const graph = new RtmGraph(dbPath);
+                        const gap = declaredImpactGap(filesToTouch(candidate), graph, (rel) => { try {
+                            return fs.readFileSync(path.join(a.root, rel), 'utf8');
+                        }
+                        catch {
+                            return null;
+                        } });
+                        if (gap) {
+                            const graphAsOf = (() => { try {
+                                return fs.statSync(dbPath).mtime.toISOString();
+                            }
+                            catch {
+                                return undefined;
+                            } })();
+                            impactAdvisory = { ...gap, ...(graphAsOf ? { graphAsOf } : {}) };
+                            appendImpactAdvisory(a.root, {
+                                aspec: a.id, files: gap.files.map((f) => f.path), more: gap.more,
+                                ...(graphAsOf ? { graphAsOf } : {}), ts: new Date().toISOString(),
+                            });
+                        }
+                    }
+                }
+            }
+            catch {
+                impactAdvisory = undefined;
+            }
+            return { approved: a.id, digest, ...(impactAdvisory ? { impactAdvisory } : {}) };
         },
         async spec_list(a) {
             assertSpecStoreReachable('spec_list', store, a.root); // @implements A-SPEC-419
@@ -2205,6 +2245,9 @@ function makeRawHandlers(store, opts) {
             // (cached vectors only, set fixed, covered hits move, why-line attached). Any missing
             // signal — no tier, no key, cold cache, embed failure — leaves the report untouched;
             // localization itself never fails because of the semantic layer.
+            //
+            // A spec-intent-vector assist (REQ-568 S3) was wired ahead of localizeIssue here and REVERTED
+            // on its pre-registered replay — see rtm/localize.ts at the matchedSpecs join for the numbers.
             try {
                 if (report.hits.length > 1
                     && (0, localize_1.citationsIn)(a.issue, new Set(governed.map((s) => s.id))).cited.length === 0) {
@@ -2508,8 +2551,20 @@ function makeRawHandlers(store, opts) {
                     .map((id) => (id.includes('@') ? id.slice(id.lastIndexOf('@') + 1) : ''))
                     .filter((f) => f !== ''));
                 const rankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(g.dumpCanonical()), riSeeds, riExclude, assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
+                // @implements A-SPEC-568.2 — the intent sentence beside every impacted spec id, same order
+                // as `impacted` (which stays a bare id list for its existing consumers). Information only:
+                // nothing reads it back into the walk, the ranking or any gate.
+                const impactedSummaries = impacted.map((id) => {
+                    let summary = null;
+                    try {
+                        summary = g.summaryOf(id);
+                    }
+                    catch { /* summary stays null */ }
+                    return { id, summary };
+                });
                 return {
                     impacted,
+                    impactedSummaries,
                     rankedImpact,
                     reachedByDepth,
                     bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,

package/dist/holmes/mcp/server.js

@@ -42,6 +42,17 @@ const handlers = (0, handlers_1.makeHandlers)(store, {
         return 'unknown';
     } },
 });
+// @implements A-SPEC-564.1 — the session-context stamp: WHO attached, name AND version (the version
+// was received and dropped for months). Written HERE because the server is the one place all three
+// harnesses pass through; lazy-once via the call path (clientInfo exists only after initialize, and
+// the ledger's root arrives with the first rooted call). Fail-open by construction.
+const { makeSessionStamper } = require('../governance/session-context');
+const stampSession = makeSessionStamper(() => { try {
+    return server.getClientVersion();
+}
+catch {
+    return undefined;
+} });
 // @implements A-SPEC-259 — the advertised version is the package's own, not a literal that froze at
 // 0.1.0: a hardcoded serverInfo.version blinds any client-side drift diagnosis.
 const PKG_VERSION = (() => {
@@ -109,6 +120,7 @@ const TOOLS = Object.keys(handlers)
 });
 server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
+    stampSession(req.params.arguments?.root);
     // @implements A-SPEC-189
     // The server is the first consumer of its own advertised schemas. Before this check, 15 of 26
     // handlers threw raw internal errors at `{}` over the wire, and a one-key typo in reverse_anchor

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/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)