@holmes-lab/holmes-kit 0.24.0 → 0.25.0

package/dist/holmes/hooks/stop.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MAX_CONSECUTIVE_BLOCKS = void 0;
 exports.collectKnownDefects = collectKnownDefects;
+exports.collectSemanticCoverage = collectSemanticCoverage;
 exports.collectAnalysisCurrency = collectAnalysisCurrency;
 exports.collectDistFreshness = collectDistFreshness;
 exports.collectCiVerdicts = collectCiVerdicts;
@@ -137,6 +138,36 @@ function collectKnownDefects(root, now) {
 // @implements A-SPEC-681 — the I/O half of the analysis line: count the analyses still open against
 // the source files this turn changed. A workspace that never analysed anything did not adopt the
 // discipline and hears nothing; a count that cannot be taken says so rather than passing.
+// @implements A-SPEC-683 — the hook READS; it never computes. Scanning here would pull tree-sitter
+// wasm into a gate process, which A-SPEC-510.2 forbids and which the detached refresh child exists
+// to prevent. So the child writes its verdict and this reads it — and an absent verdict reads as
+// NOT RUN, never as a pass, exactly like a missing CI matrix row.
+function collectSemanticCoverage(root, tier) {
+    try {
+        // @implements A-SPEC-683 — ADOPTION FIRST. `null` means no verdict file, and a tier-none
+        // workspace never produces one: no refresh runs, so nothing is written. Without this check the
+        // shipped default — zero egress, never opted in — was told "not run" on EVERY turn about a
+        // layer it never asked for. Found by a consumer-shape probe before release, not by the suite,
+        // because the not-adopted case was exercised through a verdict object the consumer never has.
+        const { resolveSemanticTier } = require('../semantic/tier');
+        const t = tier ?? resolveSemanticTier();
+        if (t.tier === 'none')
+            return '';
+        const { readCoverageState, coverageStopLine } = require('../semantic/vector-coverage');
+        let head;
+        try {
+            const { execFileSync } = require('node:child_process');
+            head = execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || undefined;
+        }
+        catch {
+            head = undefined;
+        }
+        return coverageStopLine(readCoverageState(root), head);
+    }
+    catch {
+        return '';
+    }
+}
 function collectAnalysisCurrency(root, changedSources) {
     if (!(0, analysis_currency_1.hasAnalysisDir)(root))
         return undefined;
@@ -579,6 +610,7 @@ const TRACK_LABELS = {
     'CI': 'matrix',
     'DIST': 'build freshness',
     'ANALYSIS': 'graph analysis',
+    'SEMANTIC': 'semantic vectors',
 };
 /**
  * One line per ARTICLE, each under its own name.
@@ -667,6 +699,12 @@ function evaluateStop(specs, evidence) {
         if (detail)
             tracked = [...(tracked ?? []), { article: 'ANALYSIS', detail }];
     }
+    // @implements A-SPEC-683 — the vector-coverage line rides the same non-blocking channel. It is a
+    // STRING here, not a verdict object: the hook read what the refresh child wrote and has nothing
+    // to judge. An absent verdict already reads as "not run" inside coverageStopLine.
+    if (evidence?.semantic) {
+        tracked = [...(tracked ?? []), { article: 'SEMANTIC', detail: evidence.semantic }];
+    }
     const problems = violations.map((x) => `[${x.article}] ${x.detail}`);
     // @implements A-SPEC-247 — structured list so the caller can ask acknowledgeStop which of these
     // are waiting on an owner. Mirrors `problems` exactly, including the two synthesized below.
@@ -1275,7 +1313,16 @@ if (require.main === module) {
             catch {
                 analysis = undefined;
             }
-            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}) });
+            // @implements A-SPEC-683 — read-only: the refresh child computed this, the hook only reports.
+            let semantic;
+            try {
+                const s = collectSemanticCoverage(stopProjectRoot());
+                semantic = s === '' ? undefined : s;
+            }
+            catch {
+                semantic = undefined;
+            }
+            let out = evaluateStop(specs, { testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}) });
             // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
             // the operator observes RED-first gaps before an owner promotes the posture to strict.
             // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty

package/dist/holmes/mcp/handlers/graph-operations.d.ts

@@ -2,6 +2,7 @@ import { Spec } from '../../spec/spec-parser';
 import { ScannedFile } from '../../cpg/cpg-scanner';
 import { ChangeSet, ChangeSourceInfo } from '../../project/change-source';
 import { type GraphBasis } from '../../rtm/graph-store';
+import { type PersistedCoverage } from '../../semantic/vector-coverage';
 export interface GraphOperationsContext {
     listSpecs(): Promise<Spec[]>;
     assertStoreReachable(tool: string, root: unknown): void;
@@ -48,6 +49,20 @@ export type SemanticWarmOutcome = {
  * could not embed — a discharge must not record the last one as done.
  */
 export declare function warmSemanticCache(root: string, scanned: readonly ScannedFile[]): Promise<SemanticWarmOutcome>;
+/**
+ * @implements A-SPEC-683 — vectors refresh on the channel that keeps the graph fresh.
+ *
+ * The graph self-heals through the Stop hook's detached child; the vectors did not, because
+ * `warmSemanticCache` was reachable only from `rtm_reindex`. The cache key is a hash of the
+ * document text and that text is the file's path plus its symbol names, so every edit that adds or
+ * renames a symbol invalidates that file's vector — measured 2026-09-19, twelve days of work had
+ * taken coverage to 0 of 602 while 532 stale vectors sat in the cache answering nothing.
+ *
+ * Warming under the cloud tier is EGRESS. The owner decided it should be automatic AND observed,
+ * with a switch; silent automatic transfer was considered and refused. `HOLMES_NO_SEMANTIC_WARM`
+ * records SUPPRESSED rather than a failure, so an owner who turned it off is never shown a fault.
+ */
+export declare function refreshSemanticVectors(root: string, env?: NodeJS.ProcessEnv, warm?: (r: string, s: readonly ScannedFile[]) => Promise<SemanticWarmOutcome>, scan?: () => readonly ScannedFile[]): Promise<PersistedCoverage | null>;
 export declare function createGraphOperationsHandlers(context: GraphOperationsContext): {
     rtm_impact(a: {
         root: string;
@@ -82,6 +97,7 @@ export declare function createGraphOperationsHandlers(context: GraphOperationsCo
             tier: string;
             computed: number;
             cached: number;
+            stored?: number;
         } | undefined;
         changed: number;
         nodes: number;

package/dist/holmes/mcp/handlers/graph-operations.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.publishCurrentGraph = publishCurrentGraph;
 exports.warmSemanticCache = warmSemanticCache;
+exports.refreshSemanticVectors = refreshSemanticVectors;
 exports.createGraphOperationsHandlers = createGraphOperationsHandlers;
 // @implements A-SPEC-614, A-SPEC-613, A-SPEC-100.2, A-SPEC-121.2, A-SPEC-128, A-SPEC-139, A-SPEC-189, A-SPEC-280, A-SPEC-282, A-SPEC-283, A-SPEC-419, A-SPEC-433, A-SPEC-469, A-SPEC-478, A-SPEC-568.1, A-SPEC-568.2, A-SPEC-569.1, A-SPEC-569.2, A-SPEC-569.3, A-SPEC-589
 // @implements A-SPEC-632
@@ -50,6 +51,7 @@ const trace_gaps_1 = require("../../rtm/trace-gaps");
 const tier_1 = require("../../semantic/tier");
 const vector_cache_1 = require("../../semantic/vector-cache");
 const embedder_1 = require("../../semantic/embedder");
+const vector_coverage_1 = require("../../semantic/vector-coverage");
 // @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.
 // @implements A-SPEC-568.1 — /3: nodes gained the intent `summary` column.
@@ -92,12 +94,78 @@ async function warmSemanticCache(root, scanned) {
     const rt = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
     if (rt === null)
         return { status: 'unavailable', tier: configured };
-    const docTexts = scanned.map((f) => (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000));
+    // @implements A-SPEC-683 — the WRITER keys through the shared definition. If the writer's key
+    // ever differs from the readers', every lookup misses for ever while both sides look correct.
+    const docTexts = scanned.map((f) => (0, vector_coverage_1.docTextOf)(f));
     const w = await rt.warm(docTexts);
     if (docTexts.length > 0 && w.computed + w.cached === 0)
         return { status: 'unavailable', tier: rt.label };
+    // @implements A-SPEC-683 — `stored` is measured by refreshSemanticVectors, NOT returned here.
+    // This outcome flows into entity_integrate's discharge record, a PERSISTED artifact whose shape
+    // A-SPEC-632 pins by toEqual and validates by RECORD_KEYS; widening it is a persisted-artifact
+    // breaking change this slice never declared. The suite refused the first attempt and was right.
     return { status: 'discharged', tier: rt.label, computed: w.computed, cached: w.cached };
 }
+/** The commit the verdict describes. null when this is not a Git tree — never a fabricated value. */
+function headOf(root) {
+    try {
+        const { execFileSync } = require('node:child_process');
+        return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @implements A-SPEC-683 — vectors refresh on the channel that keeps the graph fresh.
+ *
+ * The graph self-heals through the Stop hook's detached child; the vectors did not, because
+ * `warmSemanticCache` was reachable only from `rtm_reindex`. The cache key is a hash of the
+ * document text and that text is the file's path plus its symbol names, so every edit that adds or
+ * renames a symbol invalidates that file's vector — measured 2026-09-19, twelve days of work had
+ * taken coverage to 0 of 602 while 532 stale vectors sat in the cache answering nothing.
+ *
+ * Warming under the cloud tier is EGRESS. The owner decided it should be automatic AND observed,
+ * with a switch; silent automatic transfer was considered and refused. `HOLMES_NO_SEMANTIC_WARM`
+ * records SUPPRESSED rather than a failure, so an owner who turned it off is never shown a fault.
+ */
+async function refreshSemanticVectors(root, env = process.env, warm = warmSemanticCache, scan) {
+    const tier = (0, tier_1.resolveSemanticTier)();
+    if (tier.tier === 'none')
+        return null; // never opted in: nothing transferred, nothing said
+    const at = new Date().toISOString();
+    const scanned = scan ? scan() : [];
+    const off = typeof env.HOLMES_NO_SEMANTIC_WARM === 'string' && env.HOLMES_NO_SEMANTIC_WARM !== '';
+    const head = headOf(root);
+    if (off) {
+        // Still MEASURE — the owner turned off the transfer, not the observation.
+        const rt = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
+        const covered = rt === null ? 0 : (0, vector_coverage_1.countCovered)(scanned, (t) => rt.cachedDocVector(t) !== null);
+        const state = {
+            coverage: (0, vector_coverage_1.vectorCoverage)({ tier: tier.tier, modelTag: rt?.label ?? null, total: scanned.length, covered }),
+            reason: 'suppressed', at, ...(head !== null ? { head } : {}),
+        };
+        (0, vector_coverage_1.writeCoverageState)(root, state);
+        return state;
+    }
+    const outcome = await warm(root, scanned); // throws leave the previous verdict untouched
+    if (outcome.status !== 'discharged')
+        return null;
+    // What LANDED, not what was attempted. Measured 2026-09-19 the warm answered `computed: 603`
+    // while 26 vectors were never stored; a count of attempts reported as a success is the same
+    // class of dishonesty as a tier that says PASS while covering nothing.
+    const rt = (0, embedder_1.makeTierEmbedder)(tier, new vector_cache_1.VectorCache(root));
+    const stored = rt === null ? 0 : (0, vector_coverage_1.countCovered)(scanned, (t) => rt.cachedDocVector(t) !== null);
+    const state = {
+        coverage: (0, vector_coverage_1.vectorCoverage)({
+            tier: tier.tier, modelTag: outcome.tier, total: scanned.length, covered: stored,
+        }),
+        reason: 'warmed', at, stored,
+        ...(headOf(root) !== null ? { head: headOf(root) } : {}),
+    };
+    (0, vector_coverage_1.writeCoverageState)(root, state);
+    return state;
+}
 function createGraphOperationsHandlers(context) {
     return {
         async rtm_impact(a) {

package/dist/holmes/mcp/handlers/workspace-queries.js

@@ -51,6 +51,9 @@ const embedder_1 = require("../../semantic/embedder");
 // @implements A-SPEC-496 — policy parity: the direct localization path reranks with the exact
 // A-SPEC-478 math, extracted pure.
 const hit_rerank_1 = require("../../semantic/hit-rerank");
+// @implements A-SPEC-682 — the shared document-text definition (see vector-coverage.ts).
+const vector_coverage_1 = require("../../semantic/vector-coverage");
+const admission_1 = require("../../semantic/admission");
 function createWorkspaceQueryHandlers(context) {
     return {
         async rtm_check(a) {
@@ -177,12 +180,26 @@ function createWorkspaceQueryHandlers(context) {
                     const rt = (0, embedder_1.makeTierEmbedder)((0, tier_1.resolveSemanticTier)(), new vector_cache_1.VectorCache(root));
                     if (rt !== null) {
                         const qv = await rt.embedQuery(a.issue);
-                        const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
-                            (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+                        const docTextByFile = (0, vector_coverage_1.docTextIndex)(scanned);
                         (0, hit_rerank_1.rerankHitsBySemantic)(report.hits, qv, (file) => {
-                            const dt = docTextOf.get(file);
+                            const dt = docTextByFile.get(file);
                             return dt !== undefined ? rt.cachedDocVector(dt) : null;
                         }, rt.label);
+                        // @implements A-SPEC-684 — and ADMIT what the lexical pass never produced. The rerank
+                        // above can only move rows inside `report.hits`; measured 2026-09-19, asking who opens
+                        // a URL in the user's browser ranked `LocalMarkdownRepository` first on the word
+                        // "repository" and never returned `open-url.ts`, which the graph held throughout.
+                        //
+                        // PURE ADDITION, on its own field: the admitted rows do not enter `hits`, because this
+                        // repository measured that precision is lost by admitting candidates into a ranked set.
+                        // Cloud-only, matching A-SPEC-494's bound, and cached lookups only — no embed here.
+                        if (rt.label.startsWith('cloud:')) {
+                            const emitted = new Set(report.hits.map((h) => h.file));
+                            const alts = (0, admission_1.semanticAdmissions)(scanned, emitted, qv, (dt) => rt.cachedDocVector(dt), 3);
+                            if (alts.length > 0) {
+                                report.semanticAlternates = alts;
+                            }
+                        }
                     }
                 }
             }

package/dist/holmes/mcp/handlers.d.ts

@@ -428,6 +428,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
             tier: string;
             computed: number;
             cached: number;
+            stored?: number;
         } | undefined;
         changed: number;
         nodes: number;

package/dist/holmes/mcp/maintenance-analyze.js

@@ -21,6 +21,10 @@ exports.boundAnalysis = boundAnalysis;
 // @implements A-SPEC-267
 const crypto_1 = require("crypto");
 const localize_1 = require("../rtm/localize");
+// @implements A-SPEC-682 — one definition of the document text; the instrument and these
+// lookups must key identically or the coverage reported is about nothing.
+const vector_coverage_1 = require("../semantic/vector-coverage");
+const admission_1 = require("../semantic/admission");
 const dense_retrieval_1 = require("../review/dense-retrieval");
 const test_scope_1 = require("../rtm/test-scope");
 const scope_1 = require("../review/scope");
@@ -439,12 +443,11 @@ function analyzeMaintenance(input) {
         const sem = input.semantic;
         const citedForSem = (0, localize_1.citationsIn)(input.request, new Set(specs.map((sp) => sp.id))).cited;
         if (sem !== undefined && sem.queryVector !== null && citedForSem.length === 0 && candidates.length > 1) {
-            const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
-                (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+            const docTextByFile = (0, vector_coverage_1.docTextIndex)(scanned);
             const sim = new Map();
             let covered = 0;
             for (const c of candidates) {
-                const dt = docTextOf.get(c.file);
+                const dt = docTextByFile.get(c.file);
                 const dv = dt !== undefined ? sem.cachedDocVector(dt) : null;
                 if (dv !== null) {
                     sim.set(c.file, (0, dense_retrieval_1.cosine)(sem.queryVector, dv));
@@ -469,10 +472,9 @@ function analyzeMaintenance(input) {
     {
         const sem = input.semantic;
         if (sem !== undefined && sem.queryVector !== null && sem.label.startsWith('cloud:')) {
-            const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
-                (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+            const docTextByFile = (0, vector_coverage_1.docTextIndex)(scanned);
             for (const c of candidates) {
-                const dt = docTextOf.get(c.file);
+                const dt = docTextByFile.get(c.file);
                 const dv = dt !== undefined ? sem.cachedDocVector(dt) : null;
                 if (dv === null)
                     continue;
@@ -599,10 +601,9 @@ function analyzeMaintenance(input) {
     {
         const sem = input.semantic;
         if (sem !== undefined && sem.queryVector !== null && sem.label.startsWith('cloud:')) {
-            const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
-                (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+            const docTextByFile = (0, vector_coverage_1.docTextIndex)(scanned);
             for (const row of rankedImpact) {
-                const dt = docTextOf.get(row.file);
+                const dt = docTextByFile.get(row.file);
                 const dv = dt !== undefined ? sem.cachedDocVector(dt) : null;
                 if (dv !== null)
                     row.semCos = Math.round((0, dense_retrieval_1.cosine)(sem.queryVector, dv) * 1e4) / 1e4;
@@ -615,20 +616,12 @@ function analyzeMaintenance(input) {
     {
         const sem = input.semantic;
         if (sem !== undefined && sem.queryVector !== null && sem.label.startsWith('cloud:')) {
+            // @implements A-SPEC-684 — the mechanism moved to one shared function so `issue_localize`
+            // could have it too. Behaviour here is unchanged; only the definition's address moved.
             const emitted = new Set([...candidates.map((c) => c.file), ...rankedImpact.map((r) => r.file)]);
-            const scoredAlt = [];
-            for (const f of scanned) {
-                if (emitted.has(f.sourcePath))
-                    continue;
-                const dt = (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000);
-                const dv = sem.cachedDocVector(dt);
-                if (dv === null)
-                    continue;
-                scoredAlt.push({ file: f.sourcePath, cos: Math.round((0, dense_retrieval_1.cosine)(sem.queryVector, dv) * 1e4) / 1e4 });
-            }
-            scoredAlt.sort((a, b) => b.cos - a.cos);
+            const scoredAlt = (0, admission_1.semanticAdmissions)(scanned, emitted, sem.queryVector, (t) => sem.cachedDocVector(t), 3);
             if (scoredAlt.length > 0)
-                semanticAlternates = scoredAlt.slice(0, 3);
+                semanticAlternates = scoredAlt;
         }
     }
     // @implements A-SPEC-274 — the prediction is the RANKED set. The closure's files are reported on

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

@@ -308,7 +308,7 @@ exports.TOOL_SCHEMAS = {
         },
     },
     issue_localize: {
-        description: 'N1 localization: free-text issue -> structured, ranked candidate locations (files+symbols+evidence) fusing CPG lexical match with the RTM spec link ({ terms, hits, matchedSpecs }).',
+        description: 'N1 localization: free-text issue -> structured, ranked candidate locations (files+symbols+evidence) fusing CPG lexical match with the RTM spec link ({ terms, hits, matchedSpecs }). @implements A-SPEC-684 — also read `semanticAlternates`: the top cached-vector matches among files the LEXICAL pass never returned, which the ranked `hits` by construction cannot contain. Measured on this repository, a question phrased in intent vocabulary ("who opens a URL in the browser") ranked an unrelated file first on a shared prose word and never returned the answer, while the same need in mechanism vocabulary found it — the alternates are the channel that crosses that gap. Additive evidence (cloud tier only, cached lookups): the hits are untouched by it, and selection stays with the consumer. Absent when the gate is shut or nothing off-emission is covered.',
         inputSchema: {
             type: 'object',
             properties: {

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

@@ -68,6 +68,7 @@ const union_verify_1 = require("./union-verify");
 // @implements A-SPEC-480 — coherence verification: the emission's internal graph relations.
 const coherence_verify_1 = require("./coherence-verify");
 const localize_1 = require("../rtm/localize");
+const vector_coverage_1 = require("../semantic/vector-coverage");
 // @implements A-SPEC-483 — content-level verification: the candidate's BODY, read from the
 // materialized parent tree.
 const content_verify_1 = require("./content-verify");
@@ -323,8 +324,10 @@ async function runReplay(corpus, limit, opts = {}) {
                 if (opts.caseDump !== undefined) {
                     let dumpResult = result;
                     if (opts.productSemantic !== undefined) {
-                        const dumpDocText = new Map(scanned.map((f) => [f.sourcePath,
-                            (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
+                        // @implements A-SPEC-685 — the SHARED key. A benchmark that keys differently from
+                        // the product scores a pipeline the product does not run, and this repository has
+                        // already had an adoption verdict reversed by that class of instrument defect.
+                        const dumpDocText = (0, vector_coverage_1.docTextIndex)(scanned);
                         const targets = [...new Set([...result.candidates.map((x) => x.file),
                                 ...(result.impacts?.rankedImpact ?? []).map((r) => r.file)])];
                         const texts = targets.map((f) => dumpDocText.get(f)).filter((t) => t !== undefined);
@@ -580,9 +583,9 @@ async function runReplay(corpus, limit, opts = {}) {
                 // A candidate the signal cannot see (no doc text, no vector) is KEPT: recall is spent only
                 // where the verdict actually spoke.
                 if (opts.unionVerify !== undefined && unionList.length > 0) {
-                    const docTextOf = new Map(scanned.map((f) => [f.sourcePath,
-                        (f.sourcePath + ' ' + f.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, 2000)]));
-                    const known = unionList.map((f, i) => ({ text: docTextOf.get(f), i })).filter((x) => x.text !== undefined);
+                    // @implements A-SPEC-685 — the SHARED key (see the dump arm above for why).
+                    const docTextByFile = (0, vector_coverage_1.docTextIndex)(scanned);
+                    const known = unionList.map((f, i) => ({ text: docTextByFile.get(f), i })).filter((x) => x.text !== undefined);
                     const [qv] = await opts.unionVerify.embedBatch([c.subject], 'query');
                     const dvs = known.length > 0
                         ? await opts.unionVerify.embedBatch(known.map((x) => x.text), 'doc') : [];

package/dist/holmes/semantic/admission.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The semantic layer ADMITS — it does not only reorder.
+ *
+ * `rerankHitsBySemantic` moves rows inside the array it is handed, so a candidate the lexical pass
+ * never produced can never appear however similar it is. Measured 2026-09-19 with the cloud tier
+ * live and the vectors warm: asking who opens a URL in the user's browser returned
+ * `LocalMarkdownRepository` at 39.97 — the prose contained the word "repository" — and
+ * `open-url.ts` was absent, while the graph held `CODE:openUrl@src/holmes/cli/open-url.ts` the
+ * whole time. Asking the same need in mechanism vocabulary returned `Supervisor.spawnChild` at
+ * rank 4. Same graph, same tool, same second; the only variable was the question's vocabulary.
+ *
+ * This is the mechanism `maintenance_analyze` already had (A-SPEC-494) and `issue_localize` did
+ * not. It lives here once so the two cannot drift.
+ *
+ * It is PURE ADDITION. The admitted rows never enter a ranked set: this repository measured that
+ * precision is lost by admitting candidates into one (7.09 -> 9.27 candidates), and practitioners
+ * reject inspecting more than about five things. Reordering what was found and surfacing what was
+ * missed are different jobs, reported separately.
+ */
+import { type ScannedLike } from './vector-coverage';
+export interface Admitted {
+    file: string;
+    cos: number;
+}
+/**
+ * The top `limit` scanned files that the emission MISSED, by cosine against the query.
+ *
+ * `docVecOf` is injected and is a cached LOOKUP, never an embed: this runs on a ranking path and
+ * must not reach the network. A file with no cached vector is skipped rather than scored zero —
+ * scoring it would let an unjudged file occupy a slot a genuinely similar file needs.
+ */
+export declare function semanticAdmissions(scanned: readonly ScannedLike[], emitted: ReadonlySet<string>, queryVec: readonly number[] | null, docVecOf: (docText: string) => readonly number[] | null, limit: number): Admitted[];

package/dist/holmes/semantic/admission.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.semanticAdmissions = semanticAdmissions;
+// @implements A-SPEC-684
+/**
+ * The semantic layer ADMITS — it does not only reorder.
+ *
+ * `rerankHitsBySemantic` moves rows inside the array it is handed, so a candidate the lexical pass
+ * never produced can never appear however similar it is. Measured 2026-09-19 with the cloud tier
+ * live and the vectors warm: asking who opens a URL in the user's browser returned
+ * `LocalMarkdownRepository` at 39.97 — the prose contained the word "repository" — and
+ * `open-url.ts` was absent, while the graph held `CODE:openUrl@src/holmes/cli/open-url.ts` the
+ * whole time. Asking the same need in mechanism vocabulary returned `Supervisor.spawnChild` at
+ * rank 4. Same graph, same tool, same second; the only variable was the question's vocabulary.
+ *
+ * This is the mechanism `maintenance_analyze` already had (A-SPEC-494) and `issue_localize` did
+ * not. It lives here once so the two cannot drift.
+ *
+ * It is PURE ADDITION. The admitted rows never enter a ranked set: this repository measured that
+ * precision is lost by admitting candidates into one (7.09 -> 9.27 candidates), and practitioners
+ * reject inspecting more than about five things. Reordering what was found and surfacing what was
+ * missed are different jobs, reported separately.
+ */
+const vector_coverage_1 = require("./vector-coverage");
+function cosine(a, b) {
+    let dot = 0, na = 0, nb = 0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        na += a[i] * a[i];
+        nb += b[i] * b[i];
+    }
+    if (na === 0 || nb === 0)
+        return 0;
+    return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+/**
+ * The top `limit` scanned files that the emission MISSED, by cosine against the query.
+ *
+ * `docVecOf` is injected and is a cached LOOKUP, never an embed: this runs on a ranking path and
+ * must not reach the network. A file with no cached vector is skipped rather than scored zero —
+ * scoring it would let an unjudged file occupy a slot a genuinely similar file needs.
+ */
+function semanticAdmissions(scanned, emitted, queryVec, docVecOf, limit) {
+    if (queryVec === null || !Number.isFinite(limit) || limit <= 0)
+        return [];
+    const scored = [];
+    for (const f of scanned) {
+        if (emitted.has(f.sourcePath))
+            continue;
+        // The SHARED document text. A local copy here would key on something the writer never stored,
+        // and every admission would silently miss — the failure REQ-682 found in eight places.
+        const dv = docVecOf((0, vector_coverage_1.docTextOf)(f));
+        if (dv === null)
+            continue;
+        scored.push({ file: f.sourcePath, cos: Math.round(cosine(queryVec, dv) * 1e4) / 1e4 });
+    }
+    // Deterministic under ties: cosine descending, then path, so two runs over the same tree agree.
+    scored.sort((x, y) => (y.cos - x.cos) || (x.file < y.file ? -1 : x.file > y.file ? 1 : 0));
+    return scored.slice(0, Math.floor(limit));
+}

package/dist/holmes/semantic/tier-advice.d.ts

@@ -0,0 +1,18 @@
+/** One spelling, shared by the writer and the reader — they cannot disagree about where it lives. */
+export declare const INVITE_MARKER: readonly [".ax", "state", "semantic-invite.json"];
+/** Empty when a tier is already configured: that consumer has decided, and deciding earns silence. */
+export declare function tierAdviceLines(tier: {
+    tier: string;
+}): string[];
+/**
+ * True only for a consumer who has not decided AND has not been told.
+ *
+ * A throwing `exists` reads as "not invited yet" ON PURPOSE: hearing the invitation twice is a
+ * smaller harm than a consumer who never hears it, and a failed stat must not silently suppress a
+ * whole feature's existence.
+ */
+export declare function shouldInvite(tier: {
+    tier: string;
+}, root: string, exists: (p: string) => boolean): boolean;
+/** Records the invitation. A failure leaves it delivered and unrecorded — it may appear once more. */
+export declare function markInvited(root: string, write: (p: string, data: string) => void): void;

package/dist/holmes/semantic/tier-advice.js

@@ -0,0 +1,102 @@
+"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.INVITE_MARKER = void 0;
+exports.tierAdviceLines = tierAdviceLines;
+exports.shouldInvite = shouldInvite;
+exports.markInvited = markInvited;
+// @implements A-SPEC-686
+/**
+ * The invitation. Holmes-Kit's semantic layer is measured and the measurement is good; a consumer
+ * never learns it exists.
+ *
+ * Probed 2026-09-19 against a tarball install: `init` announces the guardrail mode, the wired
+ * harness, the recovery skills and the role policy, and says nothing about the tier. The session
+ * banner says the version and the governance rule. Only `doctor` names it — and `doctor` already
+ * names it WELL, stating the default and what it costs. The gap was never the wording. It was that
+ * a consumer who does not run `doctor` never meets the sentence.
+ *
+ * Two rules shape the text.
+ *
+ * **Local comes first.** `none` is the shipped default because egress needs consent, not because
+ * nobody got to it. `local` buys most of the distance with nothing leaving the machine; `cloud` is
+ * the further step and must say what it sends. An invitation that led with cloud would contradict
+ * the posture the product deliberately holds.
+ *
+ * **The numbers are this corpus's.** 305 traceability cases measured here. They are quoted as
+ * measured, never promised for the reader's repository.
+ */
+const path = __importStar(require("node:path"));
+/** One spelling, shared by the writer and the reader — they cannot disagree about where it lives. */
+exports.INVITE_MARKER = ['.ax', 'state', 'semantic-invite.json'];
+const markerPath = (root) => path.join(root, ...exports.INVITE_MARKER);
+/** Empty when a tier is already configured: that consumer has decided, and deciding earns silence. */
+function tierAdviceLines(tier) {
+    if (tier.tier !== 'none' && tier.tier !== '')
+        return [];
+    return [
+        'Semantic layer: tier none — the shipped default, and zero egress.',
+        '  Measured here on 305 traceability cases: recall 0.486 lexical -> 0.667 local -> 0.887 cloud;',
+        '  on requests lexical search misses entirely, recovery 0% -> 52% -> 92%.',
+        '    local  no egress, nothing leaves this machine   holmes-kit semantic-setup',
+        '    cloud  sends spec prose, file paths and symbol names to an external service',
+        '           holmes-kit semantic-key set   (setting the key IS the consent to that transfer)',
+        '  Neither is required. `holmes-kit doctor` reports which tier is live.',
+    ];
+}
+/**
+ * True only for a consumer who has not decided AND has not been told.
+ *
+ * A throwing `exists` reads as "not invited yet" ON PURPOSE: hearing the invitation twice is a
+ * smaller harm than a consumer who never hears it, and a failed stat must not silently suppress a
+ * whole feature's existence.
+ */
+function shouldInvite(tier, root, exists) {
+    if (tier.tier !== 'none' && tier.tier !== '')
+        return false;
+    try {
+        return !exists(markerPath(root));
+    }
+    catch {
+        return true;
+    }
+}
+/** Records the invitation. A failure leaves it delivered and unrecorded — it may appear once more. */
+function markInvited(root, write) {
+    try {
+        write(markerPath(root), JSON.stringify({ invitedAt: new Date().toISOString() }) + '\n');
+    }
+    catch { /* a banner is never a gate, and neither is its bookkeeping */ }
+}