@holmes-lab/holmes-kit 0.24.1 → 0.25.1

package/CHANGELOG.md

@@ -5,6 +5,95 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.25.1] - 2026-09-19
+
+Test-only. No product behaviour changed; `dist/` behaves exactly as 0.25.0.
+
+### Fixed
+- **The adopter outcome space is derived from the contract, not from the last observation**
+  (A-SPEC-638). A race in which adopters compete with initializers AND with each other sits on two
+  axes at once — *is there an identity yet* (`missing-workspace`, `unregistered`) and *is another
+  adopter winning* (`active`, `store-busy`, `entity-state-present`, `recovery-required`) — and the
+  mixed case had only ever enumerated the first. On Linux it met `store-busy`; widened by one, it
+  met `entity-state-present` on the very next run. Every one of those refusals is the product
+  behaving correctly and safely: `store-busy` is raised at lock acquisition before any mutation and
+  the staging directory is removed in the same catch, and the other two are planning-time refusals
+  that never reach a write. The two axes are now named once and shared by both halves of the case,
+  so they cannot drift again, and the assertion that a refused adopter left nothing behind covers
+  the whole axis rather than the one outcome that happened to be seen.
+
+  Measured: Linux 3-in-5 failing before the first repair, 1-in-5 after it, **20 in 20 passing**
+  after deriving the set from the contract. The CI matrix had been red on 38 of 45 rows since
+  2026-09-17 — a matrix that is always red reports nothing, which is the cost this closes.
+
+## [0.25.0] - 2026-09-19
+
+The semantic layer was dead on this repository and nothing said so. It is alive, it keeps itself
+alive, it can now introduce a candidate the lexical pass never found, and a consumer learns it
+exists without running `doctor`.
+
+### Added
+- **`holmes-kit doctor` reports document-vector coverage** (A-SPEC-682). The tier line says what is
+  CONFIGURED; it never said whether one lookup would succeed. Measured here 2026-09-19: the resolved
+  tier was `cloud` and **0 of 602 scanned files** had a cached vector under it, so every lookup
+  returned nothing — reranking reordered nothing, alternates emitted nothing, and the output was
+  byte-identical to a layer that examined everything and agreed. A naive check would have counted
+  532 cached vectors and called it healthy; those 532 keyed on symbol lists that no longer existed.
+  The count is therefore taken against the files scanned NOW, through the runtime's own accessor.
+  Four states: `covered`, `inert`, `not-adopted`, `unknown` — the two that cannot be judged say so
+  rather than passing quietly.
+- **Vectors refresh on the channel that keeps the graph fresh** (A-SPEC-683). The graph self-heals
+  through the Stop hook's detached child; the vectors did not, because warming was reachable only
+  from an explicit `rtm_reindex`. The cache key is a hash of the document text and that text is the
+  file's path plus its symbol names, so every edit that renames a symbol invalidates that file's
+  vector: twelve days of work had taken coverage to zero. The detached refresh now warms too, the
+  Stop hook reports the verdict the child recorded (it never scans — tree-sitter wasm must not ride
+  into a gate process), and **an absent verdict reads as "not run", never as a pass**. Warming
+  under the cloud tier is egress, so it is automatic AND observed, with `HOLMES_NO_SEMANTIC_WARM`
+  to switch the transfer off — an owner who switches it off is shown a switch, not a fault. The
+  verdict records the commit it was taken at: work merged from another machine changes the symbols
+  the vectors key on, so a verdict from another head reports **needs re-measuring** rather than
+  yesterday's numbers as today's truth.
+- **`issue_localize` admits what the lexical pass never returned** (A-SPEC-684). Its semantic
+  rerank could only reorder the array it was handed, so a question phrased in intent vocabulary
+  never reached the file that answers it. Measured with the tier live and the vectors warm: asking
+  *who opens a URL in the user's browser* ranked `LocalMarkdownRepository` first — the prose
+  contained the word "repository" — at 3.3x the second score, and never returned `open-url.ts`,
+  which the graph held throughout. The same need in mechanism vocabulary found its answer at rank 4.
+  `semanticAlternates` now carries the top cached-vector matches among files the emission missed;
+  `open-url.ts` comes back at cosine 0.754. **Pure addition on its own field**: the ranked `hits`
+  are untouched in set, order and score, because this repository measured that precision is lost by
+  admitting candidates INTO a ranked set. The mechanism is the one `maintenance_analyze` already
+  had (A-SPEC-494, measured ×1.25–×2.25 in weak windows across three corpora); it now exists once
+  and both surfaces call it.
+- **A consumer meets the semantic ladder without running `doctor`** (A-SPEC-686). The layer is
+  measured — on 305 traceability cases here, recall 0.486 lexical → 0.667 local → **0.887 cloud**,
+  and on requests lexical search misses entirely, recovery 0% → 52% → **92%** — and a consumer
+  never learned it existed. Probed against a tarball install: `init` announced the guardrail mode,
+  the wired harness and the role policy and said nothing about the tier; the session banner said
+  the version and the governance rule. `init` now names the ladder with its measured numbers and
+  the command for each, and the session banner says it **once** per workspace on a machine and then
+  never again. `local` is named before `cloud` deliberately: `none` is the default because egress
+  needs consent, not because nobody got to it, and the cloud line states what leaves the machine.
+  A consumer who has already chosen a tier hears nothing at either moment.
+
+### Fixed
+- **A project that never adopted the semantic layer hears nothing about it** (A-SPEC-683). Caught
+  by a consumer-shape probe before release, not by the suite: a tier-`none` workspace — the shipped
+  default, zero egress, never opted in — was told `semantic vectors: not run` on every turn. A
+  `null` verdict carries no tier, so "adopted but never refreshed" and "never adopted" looked
+  identical. The suite missed it because the not-adopted case was exercised through a verdict object
+  the consumer never has; the consumer reaches that code with no file at all.
+
+### Changed
+- **One definition of the semantic document text, enforced by a census** (A-SPEC-685). The formula
+  existed in eight places; A-SPEC-682 gave it one definition and pinned it with a hand-written list
+  of two files — a note of which call sites that slice happened to touch, not a rule. The pin now
+  walks the source tree, and it immediately found what the list could not: two copies in the replay
+  benchmark. They were byte-identical, so live impact was zero — but a benchmark that keys
+  differently from the product scores a pipeline the product does not run, and this repository has
+  had an adoption verdict reversed by exactly that.
+
 ## [0.24.1] - 2026-09-19
 
 Documentation only. No code changed; `dist/` is byte-identical in behaviour to 0.24.0.

package/README.md

@@ -16,6 +16,10 @@
 
 ### 🛡️ Currently Supported Features (Production Features)
 
+- 🔦 **A semantic layer that is inert says so** *(new in 0.25.0)*: the tier line said what was CONFIGURED, never whether one lookup would succeed. Measured on this repository: the resolved tier was `cloud` and **0 of 602 scanned files** had a cached document vector under it, so every lookup returned nothing — reranking reordered nothing, alternates emitted nothing, and the output was byte-identical to a layer that examined everything and agreed. A naive check would have counted the 532 vectors sitting in the cache and called it healthy; they keyed on symbol lists that no longer existed. `doctor` now reports coverage against the files scanned NOW, through the runtime's own accessor, in four states — the two that cannot be judged say so rather than passing quietly.
+- 🔁 **Vectors refresh on the channel that keeps the graph fresh** *(new in 0.25.0)*: the graph self-heals through the Stop hook's detached child; the vectors did not, because warming was reachable only from an explicit `rtm_reindex`. The cache key hashes the file's path plus its symbol names, so every edit that renames a symbol invalidates that file's vector — twelve days of work had taken coverage to zero. The refresh now warms too, and the Stop hook reports the verdict the child recorded rather than scanning (tree-sitter wasm must not ride into a gate process); **a missing verdict reads as "not run", never as a pass**. Warming under the cloud tier is egress, so it is automatic AND observed, with `HOLMES_NO_SEMANTIC_WARM` to switch the transfer off — an owner who switches it off is shown a switch, not a fault. The verdict records the commit it was taken at, so work merged from another machine reports **needs re-measuring** instead of yesterday's numbers as today's truth.
+- 🎣 **The graph can introduce a candidate your words never named** *(new in 0.25.0)*: `issue_localize`'s semantic rerank could only reorder what lexical matching already found, so a question phrased in intent vocabulary never reached the file that answers it. Measured with the tier live and the vectors warm: asking *who opens a URL in the user's browser* ranked an unrelated file first on the shared prose word "repository", at 3.3× the second score, and never returned `open-url.ts` — which the graph held the whole time. The same need in mechanism vocabulary found its answer at rank 4. `semanticAlternates` now carries the top cached-vector matches among files the emission missed, and that file comes back at cosine 0.754. **Pure addition on its own field**: the ranked hits are untouched in set, order and score, because admitting candidates INTO a ranked set is where this project measured precision being lost.
+- 🪧 **The semantic ladder reaches you without running `doctor`** *(new in 0.25.0)*: measured here on 305 traceability cases, recall goes 0.486 lexical → 0.667 local → **0.887 cloud**, and on requests lexical search misses entirely, recovery goes 0% → 52% → **92%** — and a consumer never learned any of it, because only `doctor` said so. `init` now names the ladder with those numbers and the command for each, and the session banner says it **once** per workspace on a machine and then never again. `local` is named before `cloud` on purpose: `none` is the default because egress needs consent, not because nobody got to it, and the cloud line states what leaves the machine. A consumer who has already chosen hears nothing.
 - 📮 **`holmes-kit report` — a defect can reach the maintainers** *(new in 0.24.0)*: until now a consumer's holmes-kit defect had no way back to us; the one we learned about arrived because someone pasted a transcript, and it had been reproducing for every consumer on every slice. The command writes a **redacted** report to `.ax/reports/<fingerprint>.md` and prints a prefilled GitHub issue link — title, assignee, body — plus a search link for the same fingerprint so you can see whether it is already known. `--open` opens it; on a headless box or over SSH the printed link is the whole of it. **No token, no API, nothing sent automatically**: you press Submit on GitHub's own page with the body in front of you and editable. Redaction is an allowlist rather than a scrubber — this project's own remote carries a token before the `@`, its replica ids carry a person's name, and its spec titles are unreleased product intent, so a path, a credential or a machine identifier withholds the field and the report says which. A spec id passes by shape; a spec title does not. And what holmes-kit cannot know, it says: no ledger keeps its own refusal text, so a report with no description states that rather than pretending.
 - 🧭 **A skipped graph analysis is visible** *(new in 0.24.0)*: `AGENTS.md` asks for `maintenance_analyze` before editing source, and nothing checked. Measured on this repository, the step had been skipped for seventeen consecutive commits — and the run that followed named child-process precedents a name search had missed completely, because the question was "who opens a browser" while the answer lived under "who spawns a child". The Stop hook now reports source changed with no analysis standing open: non-blocking, judged by commit rather than by clock, and silent in a workspace that never adopted the habit.
 - 🧱 **A stale build is told, not discovered** *(new in 0.23.3)*: thirty suites in this project load `dist/` while they run, and nothing asserted that it still represented the source — only the release gate compared the build id to HEAD, and only at publish time. A stale build does not go red; it verifies old code and returns green. The Stop hook now reports it on the non-blocking `tracked` channel, judged by the **build id and never by mtime**: measured here, `.build-id` had a newer mtime than every source file while naming a commit nine behind HEAD, with two changed sources missing from `dist` entirely. A workspace that does not build hears nothing, `fresh` says nothing, and the two states that cannot be judged say **that** rather than passing quietly.

package/dist/.build-id

@@ -1 +1 @@
-22a30fa1-mu77dmb2
+6277a6d6-mu7vpg1b

package/dist/holmes/cli/doctor.d.ts

@@ -200,6 +200,7 @@ export declare function wiringHandshakeChecks(target: string): Promise<Check[]>;
  * quotes the measured stakes (lexical-zero recovery 0% -> 52% local / 92% cloud, S-491) so the
  * user decides the trade with numbers rather than adjectives.
  */
+export declare function semanticCoverageCheck(root: string, tier: SemanticTier): Check | null;
 export declare function semanticTierVerdict(t: SemanticTier): {
     level: 'PASS' | 'WARN';
     detail: string;

package/dist/holmes/cli/doctor.js

@@ -50,6 +50,7 @@ exports.pushGateCheck = pushGateCheck;
 exports.ciMatrixCheck = ciMatrixCheck;
 exports.formatChecks = formatChecks;
 exports.wiringHandshakeChecks = wiringHandshakeChecks;
+exports.semanticCoverageCheck = semanticCoverageCheck;
 exports.semanticTierVerdict = semanticTierVerdict;
 exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
 // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -68,6 +69,7 @@ const tier_1 = require("../semantic/tier");
 const probe_process_1 = require("./probe-process");
 const npx_cache_check_1 = require("./npx-cache-check");
 const ci_runs_1 = require("../project/ci-runs");
+const vector_coverage_1 = require("../semantic/vector-coverage");
 const path = __importStar(require("node:path"));
 const role_policy_1 = require("../governance/role-policy");
 const blind_spots_1 = require("../guardrail/blind-spots");
@@ -1248,6 +1250,16 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
         const t = (0, tier_1.resolveSemanticTier)();
         const v = semanticTierVerdict(t);
         add('semantic tier', v.level, v.detail, v.fix);
+        // @implements A-SPEC-682 — the tier line says what is CONFIGURED. Measured 2026-09-19 on this
+        // repository, the configured tier was cloud while 0 of 602 scanned files had a cached document
+        // vector under it, so every lookup returned nothing and both semantic surfaces were inert —
+        // output-identical to a layer that examined everything and agreed. doctor renders the verdict;
+        // it does not compute it (this file already carries 51 anchors against a p90 of 10).
+        {
+            const cov = semanticCoverageCheck(target ?? process.cwd(), t);
+            if (cov)
+                checks.push(cov);
+        }
         // @implements A-SPEC-477 — the ".env stopgap" detection: a key in a project-tree file is a
         // commit-accident surface, world-readable at 644, and readable by every in-session tool. The
         // value is read to detect the pattern and never printed.
@@ -1689,6 +1701,50 @@ function entryOf(value) {
  * quotes the measured stakes (lexical-zero recovery 0% -> 52% local / 92% cloud, S-491) so the
  * user decides the trade with numbers rather than adjectives.
  */
+// @implements A-SPEC-682 — the coverage CHECK: the I/O half, kept out of the pure judgement.
+//
+// The count is taken against the files scanned NOW, through the runtime's own `cachedDocVector` —
+// the exact accessor the ranking surfaces call. Rebuilding the cache tag here would duplicate a
+// rule that differs by tier (local carries a revision and a pooling mode, cloud does not), and a
+// duplicated rule is the drift this whole slice exists to remove.
+//
+// Counting cache ENTRIES instead would have read 532 vectors on this repository on 2026-09-19 and
+// called it healthy, while 0 of them answered a lookup for a current file: the key is
+// sha256(document text), and that text changes whenever a file's symbols do. The reassuring
+// number is the wrong number.
+function semanticCoverageCheck(root, tier) {
+    if (tier.tier === 'none')
+        return null; // never opted in; it hears nothing about this
+    const unjudgeable = () => ({
+        name: 'semantic coverage', level: 'WARN',
+        detail: (0, vector_coverage_1.coverageLine)((0, vector_coverage_1.vectorCoverage)({ tier: tier.tier, modelTag: null, total: 1, covered: 0 })),
+    });
+    try {
+        const { CpgScanner } = require('../cpg/cpg-scanner');
+        const { ScanFileCache } = require('../cpg/scan-cache');
+        const { VectorCache } = require('../semantic/vector-cache');
+        const { makeTierEmbedder } = require('../semantic/embedder');
+        const crypto = require('node:crypto');
+        const runtime = makeTierEmbedder(tier, new VectorCache(root));
+        if (runtime === null)
+            return unjudgeable();
+        const dir = path.join(os.tmpdir(), 'holmes-cpg-cache-' + crypto.createHash('sha256').update(root).digest('hex').slice(0, 16));
+        const scanned = new CpgScanner(undefined, new ScanFileCache(dir)).scan(root, root);
+        const covered = (0, vector_coverage_1.countCovered)(scanned, (t) => runtime.cachedDocVector(t) !== null);
+        const v = (0, vector_coverage_1.vectorCoverage)({ tier: tier.tier, modelTag: runtime.label, total: scanned.length, covered });
+        const line = (0, vector_coverage_1.coverageLine)(v);
+        if (line === '')
+            return null;
+        return v.state === 'inert'
+            ? { name: 'semantic coverage', level: 'WARN', detail: line,
+                fix: 'Re-warm the vectors for the resolved model — `rtm_reindex` carries the only warm pass.' }
+            : { name: 'semantic coverage', level: 'PASS', detail: line };
+    }
+    catch {
+        // A count that could not be taken says so — it must not read as 0 (inert) or as full.
+        return unjudgeable();
+    }
+}
 function semanticTierVerdict(t) {
     if (t.tier === 'cloud') {
         // @implements A-SPEC-477 — the SOURCE of the consent is shown (env/keychain/file); the value

package/dist/holmes/cli/init.js

@@ -606,5 +606,18 @@ function runInit(opts) {
             (0, roles_readme_1.installRolesReadme)(opts.target);
         messages.push('Role policy is OPTIONAL and currently off — see .ax/roles/README.md to enable it.');
     }
+    // @implements A-SPEC-686 — the tier, said where the consumer is already reading posture.
+    // Probed 2026-09-19: init announced the guardrail mode, the harness, the skills and the role
+    // policy, and said nothing about the semantic layer; only `doctor` did, and a consumer who never
+    // runs doctor never met it. One-time by the nature of the act, so no marker is needed here.
+    // Fail-open: an invitation is not worth failing a wiring over.
+    try {
+        const { resolveSemanticTier } = require('../semantic/tier');
+        const { tierAdviceLines } = require('../semantic/tier-advice');
+        for (const line of tierAdviceLines(resolveSemanticTier()))
+            messages.push(line);
+    }
+    catch { /* the wiring is the point; the invitation is not */
+    }
     return { ok: true, exitCode: 0, messages, changes, removals };
 }

package/dist/holmes/hooks/rtm-refresh-child.js

@@ -49,7 +49,18 @@ if (require.main === module) {
             const { makeHandlers } = require('../mcp/handlers');
             const { LocalMarkdownRepository } = require('../spec/spec-store');
             const h = makeHandlers(new LocalMarkdownRepository(path.join(root, '.ax', 'specs')));
-            void h.rtm_impact({ root, changed: [] }).catch(() => undefined);
+            void h.rtm_impact({ root, changed: [] }).then(() => {
+                // @implements A-SPEC-683 — the vectors ride the channel that already refreshes the graph.
+                // Detached, TTL-gated and fail-soft are properties this child already has; warming inherits
+                // all three rather than needing a schedule of its own. Measured 2026-09-19: without this,
+                // coverage reached 0 of 602 in twelve days while the graph stayed current.
+                const { refreshSemanticVectors } = require('../mcp/handlers/graph-operations');
+                const { CpgScanner } = require('../cpg/cpg-scanner');
+                const { ScanFileCache } = require('../cpg/scan-cache');
+                const crypto = require('node:crypto');
+                const dir = path.join(require('node:os').tmpdir(), 'holmes-cpg-cache-' + crypto.createHash('sha256').update(root).digest('hex').slice(0, 16));
+                return refreshSemanticVectors(root, process.env, undefined, () => new CpgScanner(undefined, new ScanFileCache(dir)).scan(root, root));
+            }).catch(() => undefined);
         }
     }
     catch { /* fail-soft: a failed refresh leaves the old graph, which the advisory tolerates */ }

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

@@ -175,6 +175,28 @@ if (require.main === module) {
                     }
                 }
                 catch { /* the banner is never a gate */ }
+                // @implements A-SPEC-686 — invite ONCE. The measured layer reached consumers only through
+                // the README and doctor; a consumer who runs neither never learns it exists. This is an
+                // every-session surface, so it says it once per workspace on this machine and then never
+                // again — a recurring advertisement for an opt-in feature is the noise class this project
+                // removed the same day. Fail-open, exactly like the autonomy banner above it.
+                try {
+                    const { resolveSemanticTier } = require('../semantic/tier');
+                    const { tierAdviceLines, shouldInvite, markInvited } = require('../semantic/tier-advice');
+                    const cwd = process.cwd();
+                    const tier = resolveSemanticTier();
+                    if (shouldInvite(tier, cwd, (p) => fs.existsSync(p))) {
+                        const lines = tierAdviceLines(tier);
+                        if (lines.length > 0) {
+                            out.hookSpecificOutput.additionalContext += '\n[Holmes-Kit] ' + lines.join('\n');
+                            markInvited(cwd, (p, data) => {
+                                fs.mkdirSync(path.dirname(p), { recursive: true });
+                                fs.writeFileSync(p, data);
+                            });
+                        }
+                    }
+                }
+                catch { /* the banner is never a gate */ }
                 process.stdout.write(JSON.stringify({ hookSpecificOutput: out.hookSpecificOutput }));
                 if (out.shouldRefresh) {
                     // Detached, unref'd child so the session start does not wait on the network. The refresh

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

@@ -6,6 +6,9 @@ import { type CiVerdict } from '../project/ci-runs';
 import { type DistVerdict } from '../project/dist-freshness';
 import { type AnalysisVerdict } from '../project/analysis-currency';
 export declare function collectKnownDefects(root: string, now: Date): KnownDefectJudgement | undefined;
+export declare function collectSemanticCoverage(root: string, tier?: {
+    tier: string;
+}): string;
 export declare function collectAnalysisCurrency(root: string, changedSources: number): AnalysisVerdict | undefined;
 export declare function collectDistFreshness(root: string): DistVerdict | undefined;
 export declare function collectCiVerdicts(root: string, now?: Date): CiVerdict[];
@@ -52,6 +55,8 @@ export interface StopEvidence {
      * turn's source edits. Absent when the workspace never analysed anything.
      */
     analysis?: AnalysisVerdict;
+    /** @implements A-SPEC-683 — the rendered coverage line the refresh child recorded; already judged. */
+    semantic?: string;
     /** Provenance-chain verification result (CLI-supplied). A broken chain blocks the stop. */
     provenance?: {
         ok: boolean;

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 */ }
+}

package/dist/holmes/semantic/vector-coverage.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Whether the semantic layer is doing anything at all.
+ *
+ * Measured on this repository 2026-09-19: the resolved tier was `cloud`, and of 602 scanned files
+ * ZERO had a cached document vector under that model — while 327 sat in the same cache under
+ * `bge-m3`, a model this project no longer resolves to. Every `cachedDocVector` returned null, so
+ * `rerankHitsBySemantic` reordered nothing and `semanticAlternates` emitted nothing. Neither said
+ * so, and `doctor` printed `PASS semantic tier` throughout — a statement about a key and a model
+ * name, not about whether one lookup would succeed.
+ *
+ * An inert layer and a layer that examined every candidate and agreed with the lexical ordering
+ * produce byte-identical output. That is the defect this module removes: it makes zero say zero.
+ *
+ * OBSERVATION ONLY. Nothing here reads into a ranking, a selection or any verdict.
+ */
+/** The shape the scanner returns, narrowed to what the document text needs. */
+export interface ScannedLike {
+    sourcePath: string;
+    symbols: ReadonlyArray<{
+        qualifiedName: string;
+    }>;
+}
+export type CoverageState = 'covered' | 'inert' | 'not-adopted' | 'unknown';
+export interface CoverageInput {
+    /** The RESOLVED tier. `none` is the shipped default (zero egress) and means never opted in. */
+    tier: string;
+    /** The resolved model's cache tag. null when it cannot be determined. */
+    modelTag: string | null;
+    total: number;
+    covered: number;
+}
+export interface VectorCoverage {
+    state: CoverageState;
+    covered: number;
+    total: number;
+    /** null whenever a ratio would be invented — an unjudgeable count or an empty scan. */
+    ratio: number | null;
+    modelTag: string | null;
+}
+/** The maximum document text length; part of the cache key, so it is part of the contract. */
+export declare const DOC_TEXT_LIMIT = 2000;
+/**
+ * THE definition of the text whose hash keys a document vector.
+ *
+ * It existed as an inline expression in five places, four of them in `maintenance-analyze.ts` and
+ * one in `issue_localize`'s rerank — two of which are the surfaces this module's coverage claims to
+ * describe. A separate copy here would be free to drift, and a drifted instrument reports a
+ * coverage the product does not have. One definition, or the build fails.
+ */
+export declare function docTextOf(file: ScannedLike): string;
+/** The same text, indexed by source path — the form the three ranking passes consume. */
+export declare function docTextIndex(scanned: ReadonlyArray<ScannedLike>): Map<string, string>;
+/**
+ * Pure: the caller supplies the counts. Keeping the filesystem out means the judgement is testable
+ * without a cache on disk, and it cannot be wrong about ordering or locking.
+ */
+export declare function vectorCoverage(input: CoverageInput): VectorCoverage;
+/** Empty when there is nothing to say. Never silent when there is. */
+export declare function coverageLine(v: VectorCoverage): string;
+/**
+ * How many scanned files have a cached document vector, judged by a lookup the CALLER supplies.
+ *
+ * The lookup is injected so this module stays free of the cache's I/O and locking, and so the
+ * count is taken through the same public accessor the ranking surfaces use — a private key
+ * recomputed here could agree with the cache today and drift from it tomorrow.
+ */
+export declare function countCovered(scanned: ReadonlyArray<ScannedLike>, isCached: (docText: string) => boolean): number;
+export type WarmReason = 'warmed' | 'suppressed' | 'not-adopted';
+export interface PersistedCoverage {
+    coverage: VectorCoverage;
+    reason: WarmReason;
+    at: string;
+    stored?: number;
+    head?: string;
+}
+export declare const COVERAGE_STATE_FILE = "semantic-coverage.json";
+/** Best-effort: a verdict that cannot be written is not worth failing a refresh over. */
+export declare function writeCoverageState(root: string, p: PersistedCoverage): void;
+/** null means NOT RUN — missing, unreadable, or not shaped like a verdict. Never throws. */
+export declare function readCoverageState(root: string): PersistedCoverage | null;
+/**
+ * The turn-boundary line. Empty when there is nothing to say; NEVER empty when there is.
+ *
+ * `null` is the case this exists for. A workspace whose refresh never ran looks exactly like a
+ * healthy one if absence is allowed to be silent, and that silence is what hid zero coverage for
+ * twelve days.
+ */
+export declare function coverageStopLine(p: PersistedCoverage | null, currentHead?: string): string;

package/dist/holmes/semantic/vector-coverage.js

@@ -0,0 +1,210 @@
+"use strict";
+// @implements A-SPEC-682
+/**
+ * Whether the semantic layer is doing anything at all.
+ *
+ * Measured on this repository 2026-09-19: the resolved tier was `cloud`, and of 602 scanned files
+ * ZERO had a cached document vector under that model — while 327 sat in the same cache under
+ * `bge-m3`, a model this project no longer resolves to. Every `cachedDocVector` returned null, so
+ * `rerankHitsBySemantic` reordered nothing and `semanticAlternates` emitted nothing. Neither said
+ * so, and `doctor` printed `PASS semantic tier` throughout — a statement about a key and a model
+ * name, not about whether one lookup would succeed.
+ *
+ * An inert layer and a layer that examined every candidate and agreed with the lexical ordering
+ * produce byte-identical output. That is the defect this module removes: it makes zero say zero.
+ *
+ * OBSERVATION ONLY. Nothing here reads into a ranking, a selection or any verdict.
+ */
+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.COVERAGE_STATE_FILE = exports.DOC_TEXT_LIMIT = void 0;
+exports.docTextOf = docTextOf;
+exports.docTextIndex = docTextIndex;
+exports.vectorCoverage = vectorCoverage;
+exports.coverageLine = coverageLine;
+exports.countCovered = countCovered;
+exports.writeCoverageState = writeCoverageState;
+exports.readCoverageState = readCoverageState;
+exports.coverageStopLine = coverageStopLine;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+/** The maximum document text length; part of the cache key, so it is part of the contract. */
+exports.DOC_TEXT_LIMIT = 2000;
+/**
+ * THE definition of the text whose hash keys a document vector.
+ *
+ * It existed as an inline expression in five places, four of them in `maintenance-analyze.ts` and
+ * one in `issue_localize`'s rerank — two of which are the surfaces this module's coverage claims to
+ * describe. A separate copy here would be free to drift, and a drifted instrument reports a
+ * coverage the product does not have. One definition, or the build fails.
+ */
+function docTextOf(file) {
+    return (file.sourcePath + ' ' + file.symbols.map((sy) => sy.qualifiedName).join(' ')).slice(0, exports.DOC_TEXT_LIMIT);
+}
+/** The same text, indexed by source path — the form the three ranking passes consume. */
+function docTextIndex(scanned) {
+    return new Map(scanned.map((f) => [f.sourcePath, docTextOf(f)]));
+}
+const isCount = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+/**
+ * Pure: the caller supplies the counts. Keeping the filesystem out means the judgement is testable
+ * without a cache on disk, and it cannot be wrong about ordering or locking.
+ */
+function vectorCoverage(input) {
+    const total = isCount(input.total) ? Math.floor(input.total) : 0;
+    const covered = isCount(input.covered) ? Math.min(Math.floor(input.covered), total) : 0;
+    const modelTag = typeof input.modelTag === 'string' && input.modelTag !== '' ? input.modelTag : null;
+    const base = { covered, total, modelTag };
+    // A project at the shipped default never opted in. It is not failing at something it declined.
+    if (input.tier === 'none' || input.tier === '')
+        return { state: 'not-adopted', ratio: null, ...base };
+    // No model tag means no lookup key: the count could not be taken. Saying `covered: 0` here would
+    // report an inert layer that may well be working — the two must not share a shape.
+    if (modelTag === null)
+        return { state: 'unknown', ratio: null, ...base };
+    // Nothing was scanned, so nothing was missed. An empty scan is evidence about the scan, not the
+    // cache, and a ratio over zero files would be invented.
+    if (total === 0)
+        return { state: 'unknown', ratio: null, ...base };
+    if (covered === 0)
+        return { state: 'inert', ratio: 0, ...base };
+    return { state: 'covered', ratio: covered / total, ...base };
+}
+/** Empty when there is nothing to say. Never silent when there is. */
+function coverageLine(v) {
+    if (v.state === 'not-adopted')
+        return '';
+    if (v.state === 'unknown') {
+        // An empty scan has nothing to report; an unjudgeable count with files present does.
+        if (v.total === 0)
+            return '';
+        return 'document-vector coverage could not be judged — the resolved model has no cache tag, '
+            + 'so whether a lookup would succeed is unknown';
+    }
+    if (v.state === 'inert') {
+        return `the semantic layer is INERT: 0 of ${v.total} scanned files have a cached document vector `
+            + `under ${v.modelTag ?? 'the resolved model'} — every lookup returns nothing, so reranking `
+            + 'reorders nothing and alternates emit nothing. This reads identically to agreement.';
+    }
+    const pct = v.ratio === null ? '' : ` (${(v.ratio * 100).toFixed(1)}%)`;
+    return `document-vector coverage ${v.covered} of ${v.total}${pct} under ${v.modelTag ?? 'the resolved model'}`;
+}
+/**
+ * How many scanned files have a cached document vector, judged by a lookup the CALLER supplies.
+ *
+ * The lookup is injected so this module stays free of the cache's I/O and locking, and so the
+ * count is taken through the same public accessor the ranking surfaces use — a private key
+ * recomputed here could agree with the cache today and drift from it tomorrow.
+ */
+function countCovered(scanned, isCached) {
+    let n = 0;
+    for (const f of scanned) {
+        if (isCached(docTextOf(f)))
+            n++;
+    }
+    return n;
+}
+exports.COVERAGE_STATE_FILE = 'semantic-coverage.json';
+const statePath = (root) => path.join(root, '.ax', 'state', exports.COVERAGE_STATE_FILE);
+/** Best-effort: a verdict that cannot be written is not worth failing a refresh over. */
+function writeCoverageState(root, p) {
+    try {
+        const file = statePath(root);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(p, null, 2) + '\n');
+    }
+    catch { /* the refresh is fail-soft; so is recording it */ }
+}
+/** null means NOT RUN — missing, unreadable, or not shaped like a verdict. Never throws. */
+function readCoverageState(root) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(statePath(root), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const o = parsed;
+    const c = o.coverage;
+    if (typeof c !== 'object' || c === null)
+        return null;
+    if (typeof c.state !== 'string' || typeof c.covered !== 'number' || typeof c.total !== 'number')
+        return null;
+    if (o.reason !== 'warmed' && o.reason !== 'suppressed' && o.reason !== 'not-adopted')
+        return null;
+    return { coverage: c, reason: o.reason, at: typeof o.at === 'string' ? o.at : '',
+        ...(typeof o.stored === 'number' ? { stored: o.stored } : {}),
+        ...(typeof o.head === 'string' && o.head !== '' ? { head: o.head } : {}) };
+}
+/**
+ * The turn-boundary line. Empty when there is nothing to say; NEVER empty when there is.
+ *
+ * `null` is the case this exists for. A workspace whose refresh never ran looks exactly like a
+ * healthy one if absence is allowed to be silent, and that silence is what hid zero coverage for
+ * twelve days.
+ */
+function coverageStopLine(p, currentHead) {
+    if (p === null) {
+        return 'semantic vectors: not run — no refresh has recorded a coverage verdict for this '
+            + 'workspace, so whether the semantic layer contributes anything is unknown';
+    }
+    if (p.reason === 'not-adopted' || p.coverage.state === 'not-adopted')
+        return '';
+    // The verdict is machine-local; the CODE it describes arrives from other machines through Git.
+    // A pull brings in symbols this verdict never saw, and the document text those symbols key is
+    // what every vector lookup hashes — so a verdict from another commit describes a tree that no
+    // longer exists. Report it as needing re-measurement: neither healthy nor broken. Absence of a
+    // head on either side is not a mismatch; it is simply unjudgeable, and silence is correct there
+    // because the other states already speak for themselves.
+    if (typeof p.head === 'string' && p.head !== '' && typeof currentHead === 'string'
+        && currentHead !== '' && p.head !== currentHead) {
+        return `semantic vectors: the coverage verdict was recorded at another commit (${p.head.slice(0, 7)}, `
+            + `now ${currentHead.slice(0, 7)}) — work merged since then changes the symbols the vectors key on, `
+            + 'so coverage needs re-measuring';
+    }
+    if (p.reason === 'suppressed') {
+        // An owner who turned the transfer off must not be shown a fault. Report the number, name the
+        // switch, and say nothing that reads as breakage.
+        return `semantic vectors: automatic warming is switched off (HOLMES_NO_SEMANTIC_WARM); `
+            + `coverage stands at ${p.coverage.covered} of ${p.coverage.total} — run rtm_reindex to warm on demand`;
+    }
+    const line = coverageLine(p.coverage);
+    if (p.coverage.state === 'covered' && p.stored !== undefined && p.stored < p.coverage.covered) {
+        return `${line} — ${p.coverage.covered - p.stored} vector(s) were computed but never stored`;
+    }
+    return p.coverage.state === 'covered' ? '' : line;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.24.1",
+  "version": "0.25.1",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",