@holmes-lab/holmes-kit 0.19.6 → 0.20.0

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

@@ -0,0 +1,260 @@
+"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.publishCurrentGraph = publishCurrentGraph;
+exports.warmSemanticCache = warmSemanticCache;
+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
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const hash_cache_1 = require("../../cpg/hash-cache");
+const root_1 = require("../../project/root");
+const rtm_builder_1 = require("../../rtm/rtm-builder");
+const graph_store_1 = require("../../rtm/graph-store");
+const assoc_arm_1 = require("../../assoc/assoc-arm");
+// @implements A-SPEC-478 — the semantic tier runtime stays at the async reindex edge.
+const tier_1 = require("../../semantic/tier");
+const vector_cache_1 = require("../../semantic/vector-cache");
+const embedder_1 = require("../../semantic/embedder");
+// @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.
+const RTM_GRAPH_SCHEMA = 'rtm-graph/3';
+// @implements A-SPEC-569.3 — how many impacted specs get their intent sentence attached. A prose
+// constant, never a verdict input: the impacted list itself is never truncated.
+const SUMMARY_CAP = 40;
+// @implements A-SPEC-569.1 (revision) — /2: pre-fix 0.16.0 builds could persist forged structural
+// characters in the summary column, and every other basis field would still match after upgrading.
+// A-SPEC-283's own rule applies to us too: an older build's artifact is rebuilt, never read with
+// new assumptions.
+const RTM_EXTRACTOR_VERSION = 'holmes-rtm/2';
+// @implements A-SPEC-632 — the two rebuild paths a completed integration's discharge runs are the
+// SAME functions explicit reindex runs, so a discharged graph and a reindexed graph are one artifact.
+/** Publish the complete graph for `specs` over `scanned` at the live path (A-SPEC-631 primitive). */
+function publishCurrentGraph(root, specs, scanned) {
+    // The publication basis: the same five fields rtm_impact expects (A-SPEC-283), so what this
+    // publishes is exactly what the next query reuses.
+    const basis = {
+        graphSchema: RTM_GRAPH_SCHEMA,
+        extractorVersion: RTM_EXTRACTOR_VERSION,
+        sourceCommit: (0, graph_store_1.headCommitOf)(root, (0, root_1.cleanSubprocessEnv)()) ?? '',
+        specFingerprint: (0, graph_store_1.specFingerprint)(specs),
+        scanDigest: (0, graph_store_1.scanDigest)(scanned),
+    };
+    const { nodes, edges } = (0, graph_store_1.publishGraph)(path.join(root, '.ax', 'rtm.sqlite'), basis, (g) => (0, rtm_builder_1.buildRtm)(specs, scanned, g));
+    return { basis, nodes, edges };
+}
+/**
+ * @implements A-SPEC-478 — the semantic cache WARMING lives in explicit heavy operations, so the
+ * ranking hot path only ever LOOKS UP vectors. Idempotent through the cache. The outcome says
+ * whether there was nothing to do (tier none), whether it happened, or whether a configured tier
+ * could not embed — a discharge must not record the last one as done.
+ */
+async function warmSemanticCache(root, scanned) {
+    const tier = (0, tier_1.resolveSemanticTier)();
+    if (tier.tier === 'none')
+        return { status: 'not-applicable', tier: 'none' };
+    const configured = tier.model ? `${tier.tier}:${tier.model}` : tier.tier;
+    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));
+    const w = await rt.warm(docTexts);
+    if (docTexts.length > 0 && w.computed + w.cached === 0)
+        return { status: 'unavailable', tier: rt.label };
+    return { status: 'discharged', tier: rt.label, computed: w.computed, cached: w.cached };
+}
+function createGraphOperationsHandlers(context) {
+    return {
+        async rtm_impact(a) {
+            context.assertStoreReachable('rtm_impact', a.root); // @implements A-SPEC-433
+            // @implements A-SPEC-614 — do not scan another workspace with this bound spec store.
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            // @implements A-SPEC-189 §14 (round 13) — `context.projectRootOf(a.root)` was called as a bare
+            // statement: its only effect was to throw on a bad path, and the advertised contract ("a
+            // subdirectory resolves up to it") was dropped on the floor. `taint_scan` one function away
+            // honours it, so the same argument answered about two different trees depending on which tool
+            // was asked. Bind the derivation and use it.
+            const root = context.projectRootOf(a.root);
+            const scanned = context.cachedScan(root);
+            // @implements A-SPEC-569.2 — the impact/advisory graph is APPROVED-ONLY. A draft needs no
+            // approval to exist, and the 0.16.0 adversarial round showed one reaching the agent-visible
+            // channels (impacted closure, advisory anchor summaries) — the trust boundary for those
+            // channels is the act of approval. NOT filterGoverned: that predicate passes drafts (it only
+            // drops outdated/legacy), which is exactly what let this in. Diagnosis (rtm_check) and
+            // matching (issue_localize / maintenance_analyze) keep their own populations — the replay
+            // pins were measured on them.
+            const specs = (await context.listSpecs()).filter((s) => s.status === 'approved');
+            // @implements A-SPEC-283
+            // Reuse the persisted graph when its basis still holds. Measured: on the warm path the graph
+            // build is ~81% of the cost and reopening is ~0ms. `scanDigest` is the field that makes this
+            // safe — an uncommitted edit never moves HEAD, so a commit-only basis would happily serve a
+            // graph describing content the working tree no longer has.
+            const expected = {
+                graphSchema: RTM_GRAPH_SCHEMA,
+                extractorVersion: RTM_EXTRACTOR_VERSION,
+                sourceCommit: (0, graph_store_1.headCommitOf)(root, (0, root_1.cleanSubprocessEnv)()) ?? '',
+                specFingerprint: (0, graph_store_1.specFingerprint)(specs),
+                scanDigest: (0, graph_store_1.scanDigest)(scanned),
+            };
+            // @implements A-SPEC-631 — the live file is NEVER cleared in place. `publishable`: reuse it
+            // while every basis field holds; otherwise build the complete graph in a private temporary
+            // database, answer from it, and publish it by one atomic rename only after the answer stands.
+            // Reproduced 2026-09-13: the previous in-place clear+rebuild (this is also the Stop hook's
+            // refresh path) let a concurrent approval read zero nodes as "no impact", and a refresher
+            // killed mid-way left an empty, basis-less file behind for every later reader.
+            const opened = (0, graph_store_1.openReusableGraph)(path.join(root, '.ax', 'rtm.sqlite'), expected, { publishable: true });
+            const g = opened.graph;
+            let answered = false;
+            try {
+                if (!opened.reusable) {
+                    (0, rtm_builder_1.buildRtm)(specs, scanned, g);
+                    opened.commitBasis();
+                }
+                // explainImpact, not impactedBy: the bounds and the breadth signal must reach the caller.
+                // An impact set is not just a list — a broad one means "review the contract", and a consumer
+                // that cannot tell the difference will try to bundle two hundred call sites.
+                const { specs: impactedRaw, reachedByDepth, stoppedAt, seedIsHub } = (0, rtm_builder_1.explainImpact)(g, a.changed);
+                // @implements A-SPEC-569.2 — the closure walks EDGES, and an implements edge is owned by
+                // the code file, so an anchor naming a draft (or a spec nobody wrote) still emits one —
+                // deliberately, for rtm_check's dangling diagnosis. The CHANNEL filter is node existence:
+                // approved-only specs were given nodes above, so only sealed intent reaches the caller.
+                const impacted = impactedRaw.filter((id) => g.hasNode(id));
+                // @implements A-SPEC-469 — the graded FILE surface beside the spec closure, same code path
+                // as the S-484 measurement (identity, not reimplementation). Seeds are the changed symbols'
+                // nodes; the files that own them are excluded — a prediction naming the change itself is
+                // vacuously true. The closure fields above stay exactly as they were: mass never enters a
+                // gate decision.
+                const riSeeds = new Map(a.changed.flatMap((qn) => g.codeNodeIds(qn)).map((id) => [id, 1]));
+                const riExclude = new Set([...riSeeds.keys()]
+                    .map((id) => (id.includes('@') ? id.slice(id.lastIndexOf('@') + 1) : ''))
+                    .filter((f) => f !== ''));
+                const rankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(g.dumpCanonical()), riSeeds, riExclude, assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
+                // @implements A-SPEC-568.2 — the intent sentence beside every impacted spec id, same order
+                // as `impacted` (which stays a bare id list for its existing consumers). Information only:
+                // nothing reads it back into the walk, the ranking or any gate.
+                // @implements A-SPEC-569.3 — capped: measured on this repository, uncapped summaries were
+                // 94% of a 104,706-byte response (a hub-grade impact of 339 specs). The omission is COUNTED,
+                // never silent, and `impacted` itself stays complete — only the annotation is bounded.
+                const shownSummaries = impacted.slice(0, SUMMARY_CAP);
+                const impactedSummaries = shownSummaries.map((id) => {
+                    let summary = null;
+                    try {
+                        summary = g.summaryOf(id);
+                    }
+                    catch { /* summary stays null */ }
+                    return { id, summary };
+                });
+                const summariesOmitted = impacted.length - shownSummaries.length;
+                answered = true;
+                return {
+                    impacted,
+                    impactedSummaries,
+                    ...(summariesOmitted > 0 ? { summariesOmitted } : {}),
+                    rankedImpact,
+                    reachedByDepth,
+                    bounded: stoppedAt.length > 0 ? stoppedAt.slice(0, 20) : undefined,
+                    ...(seedIsHub ? {
+                        breadthWarning: `a changed symbol has ${seedIsHub.callers} callers (hub threshold ${seedIsHub.threshold}) — this is a CONTRACT change; review the contract and its tests rather than bundling every impacted spec`,
+                    } : {}),
+                };
+            }
+            finally {
+                // Release the native SQLite handle even if build/query throws. A failed answer discards a
+                // private rebuild; a successful one publishes it — and a publication failure never
+                // overturns the answer, it only means the cache was not refreshed this time.
+                if (!answered)
+                    opened.discard();
+                else {
+                    try {
+                        opened.publish();
+                    }
+                    catch { /* answer stands; live graph unchanged */ }
+                }
+            }
+        },
+        async rtm_reindex(a) {
+            context.assertStoreReachable('rtm_reindex', a.root); // @implements A-SPEC-419
+            // Removal/re-derivation of changedFiles/changedSymbols is not needed
+            // here (rtm_reindex works off changes/specs/scanned/bySourcePath
+            // directly), but the guard+diff+scan prologue is identical to
+            // review_scope/review_prepare — see deriveChangedContext.
+            const { root, changes, specs, scanned, changeSource } = await context.deriveChangedContext(a.root, a, 'rtm_reindex');
+            const changed = changes.added.length + changes.modified.length + changes.deleted.length + changes.renamed.length;
+            // The HashCache records every changed file's content hash (A-SPEC-128 — project-root cache,
+            // no subdir leak) so an incremental consumer can skip files whose content did not move. The
+            // reindex itself publishes the FULL build below and no longer applies the diff on top of it.
+            const cache = new hash_cache_1.HashCache(context.cacheDirFor(root)); // @implements A-SPEC-128
+            const record = (files) => {
+                for (const relPath of files) {
+                    let content;
+                    try {
+                        content = fs.readFileSync(path.join(root, relPath), 'utf8');
+                    }
+                    catch {
+                        continue;
+                    }
+                    if (!cache.unchanged(relPath, content))
+                        cache.put(relPath, content);
+                }
+            };
+            record(changes.added);
+            record(changes.modified);
+            // @implements A-SPEC-631 — explicit reindex is a persistence operation: build the COMPLETE
+            // graph in a private temporary database, commit the matching basis, close it, and replace
+            // the live file by one atomic rename (A-SPEC-589's publication contract, now the same
+            // primitive rtm_impact uses). The post-build applyIncremental pass is gone: measured
+            // 2026-09-13, its per-file replacement rebuilt symbols but not the changed file's FILE node
+            // or imports edge, so the first reindex after a change published 4 nodes / 3 edges where the
+            // next run over the same tree published 5 / 4. The full build re-resolves every call edge
+            // against the whole scan, which is what A-SPEC-280 required (@implements A-SPEC-280).
+            const published = publishCurrentGraph(root, specs, scanned);
+            // @implements A-SPEC-478 — warming is best-effort here: reindex's own result is unaffected,
+            // and only an actual warm is reported (tier none or an unavailable tier adds no field).
+            let semanticWarm;
+            try {
+                const w = await warmSemanticCache(root, scanned);
+                if (w.status === 'discharged')
+                    semanticWarm = { tier: w.tier, computed: w.computed, cached: w.cached };
+            }
+            catch { /* warming is best-effort; reindex's own result is unaffected */ }
+            return { changed, nodes: published.nodes, edges: published.edges, changeSource,
+                ...(semanticWarm !== undefined ? { semanticWarm } : {}) };
+        },
+    };
+}

package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts

@@ -0,0 +1,34 @@
+import { Spec } from '../../spec/spec-parser';
+import { ScannedFile } from '../../cpg/cpg-scanner';
+import { DecisionRecord, DecisionCitation } from '../../rtm/rtm-builder';
+import { ContentSource } from '../../context/bundler';
+import { MaintenanceGroundTruth, MaintenanceAnalysis } from '../maintenance-analyze';
+import { Basis } from '../basis';
+export interface MaintenanceAnalysisContext {
+    listSpecs(): Promise<Spec[]>;
+    foreignRootReason(root?: string): string | null;
+    refusal(reason: string): Error;
+    projectRootOf(root: string): string;
+    basisFor(root: string, withDisk: boolean): Basis;
+    collectDecisions(root: string, scanned: readonly ScannedFile[], specs: readonly Spec[]): {
+        decisions: DecisionRecord[];
+        citations: DecisionCitation[];
+    };
+    buildContentSource(specs: Spec[], scanned: ScannedFile[]): ContentSource;
+    specStoreBlindReason(root: string, count: number): string | null;
+    fileDigestOf(root: string, rel: string): string | null;
+}
+export declare function createMaintenanceAnalysisHandlers(context: MaintenanceAnalysisContext): {
+    maintenance_analyze(a: {
+        root: string;
+        request: string;
+        historyLimit?: number;
+        contextBudget?: number;
+        groundTruth?: MaintenanceGroundTruth;
+        persist?: boolean;
+        changedFiles?: string[];
+    }): Promise<MaintenanceAnalysis & {
+        persistedTo?: string;
+        bounded?: boolean;
+    }>;
+};

package/dist/holmes/mcp/handlers/maintenance-analysis.js

@@ -0,0 +1,288 @@
+"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.createMaintenanceAnalysisHandlers = createMaintenanceAnalysisHandlers;
+// @implements A-SPEC-612, A-SPEC-100.2, A-SPEC-128, A-SPEC-189, A-SPEC-267, A-SPEC-268, A-SPEC-269, A-SPEC-277, A-SPEC-283, A-SPEC-290, A-SPEC-292, A-SPEC-293, A-SPEC-378, A-SPEC-388, A-SPEC-418, A-SPEC-478, A-SPEC-571.2, A-SPEC-573.4, A-SPEC-578.5
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const spec_types_1 = require("../../spec/spec-types");
+const cpg_scanner_1 = require("../../cpg/cpg-scanner");
+const rtm_graph_1 = require("../../rtm/rtm-graph");
+const rtm_builder_1 = require("../../rtm/rtm-builder");
+const test_scope_1 = require("../../rtm/test-scope");
+const root_1 = require("../../project/root");
+const test_evidence_1 = require("../../review/test-evidence");
+const temporal_prior_1 = require("../../review/temporal-prior");
+const commit_text_1 = require("../../review/commit-text");
+const bundler_1 = require("../../context/bundler");
+const tier_1 = require("../../semantic/tier");
+const vector_cache_1 = require("../../semantic/vector-cache");
+const embedder_1 = require("../../semantic/embedder");
+const maintenance_analyze_1 = require("../maintenance-analyze");
+const maintenance_evidence_1 = require("../maintenance-evidence");
+const defuse_bound_1 = require("../defuse-bound");
+function createMaintenanceAnalysisHandlers(context) {
+    return {
+        async maintenance_analyze(a) {
+            const foreign = context.foreignRootReason(a.root);
+            if (foreign)
+                throw context.refusal(foreign);
+            const root = context.projectRootOf(a.root);
+            // This tool is advertised as read-only. Do not attach ScanFileCache: its normal save/prune
+            // behavior mutates `.ax/cpg_cache` even though the analysis itself is observational.
+            const scanner = new cpg_scanner_1.CpgScanner();
+            const scanned = scanner.scan(root, root);
+            const skipped = scanner.scanSkipped();
+            const specs = (0, spec_types_1.filterGoverned)(await context.listSpecs());
+            const anchors = (0, test_scope_1.scanTestAnchors)(root);
+            const detail = context.basisFor(root, true);
+            let head = '';
+            try {
+                head = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+            }
+            catch { /* non-git */ }
+            const supportedExtensions = new Set(cpg_scanner_1.SCANNABLE_EXTENSIONS);
+            const knownCodeExtensions = new Set(['.rb', '.php', '.kt', '.kts', '.swift', '.scala', '.sh', '.ex', '.exs', '.lua', '.r']);
+            const unsupportedLanguages = new Set();
+            try {
+                const files = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), maxBuffer: 8 * 1024 * 1024 }).split('\0');
+                for (const file of files) {
+                    const ext = path.extname(file).toLowerCase();
+                    if (knownCodeExtensions.has(ext) && !supportedExtensions.has(ext))
+                        unsupportedLanguages.add(ext);
+                }
+            }
+            catch {
+                // A non-git tree cannot be enumerated cheaply without reimplementing the scanner's ignore
+                // rules. Surface the missing axis rather than claiming every language was covered.
+                unsupportedLanguages.add('not-enumerated(non-git)');
+            }
+            const graph = new rtm_graph_1.RtmGraph();
+            try {
+                // @implements A-SPEC-292 — the resolution loop's own tally of what it declined to link.
+                const { resolution } = (0, rtm_builder_1.buildRtm)(specs, scanned, graph);
+                // @implements A-SPEC-293 — what constrains this change, not just what it touches.
+                const { decisions, citations } = context.collectDecisions(root, scanned, specs);
+                (0, rtm_builder_1.addDecisionEdges)(decisions, citations, graph);
+                const common = {
+                    request: a.request,
+                    scanned,
+                    specs,
+                    graph,
+                    testAnchors: anchors,
+                    basis: {
+                        head,
+                        loadedBuild: detail.loadedBuild,
+                        diskBuild: detail.diskBuild ?? 'unknown',
+                        specFingerprint: `count:${specs.length}/fp:${detail.specs ?? 'unknown'}`,
+                    },
+                    changedFiles: a.changedFiles,
+                    // @implements A-SPEC-290 — the stored run record. Freshness is judged inside the analysis
+                    // against its own basis, so a record from another commit is reported as stale rather than
+                    // quietly used.
+                    runtimeEvidence: (0, test_evidence_1.readTestEvidence)(root),
+                    resolution,
+                    coverage: {
+                        scannedFiles: scanned.length,
+                        skippedFiles: skipped.map((entry) => entry.file),
+                        unsupportedLanguages: [...unsupportedLanguages],
+                        historyStatus: 'not-requested',
+                    },
+                };
+                // @implements A-SPEC-478 — resolve the tier and precompute the query vector at the
+                // async edge; the sync analysis receives only a closure over cached vectors. Any failure
+                // (no tier, no module, no key, embed error) leaves `semantic` undefined = today's behavior.
+                let semantic;
+                try {
+                    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.request);
+                        semantic = { label: rt.label, queryVector: qv, cachedDocVector: rt.cachedDocVector };
+                    }
+                }
+                catch { /* the hot path never breaks on the semantic layer */ }
+                const preliminary = (0, maintenance_analyze_1.analyzeMaintenance)({ ...common, history: [], semantic });
+                const candidateFiles = preliminary.candidates.map((candidate) => candidate.file);
+                const limit = Math.max(0, Math.min(100, Math.floor(a.historyLimit ?? 20)));
+                const history = [];
+                let historyStatus = limit === 0 || candidateFiles.length === 0 ? 'not-requested' : 'unavailable';
+                if (limit > 0 && candidateFiles.length > 0) {
+                    try {
+                        const raw = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'log', `-${limit}`, '--date=short', '--format=%H%x00%ad%x00%s', '--name-only', '--', ...candidateFiles], { encoding: 'utf8', env: (0, root_1.cleanSubprocessEnv)(), maxBuffer: 2 * 1024 * 1024 });
+                        let current = null;
+                        for (const line of raw.split('\n')) {
+                            if (line.includes('\0')) {
+                                const [commit, date, subject] = line.split('\0');
+                                current = { commit, date, subject, files: [] };
+                                history.push(current);
+                            }
+                            else if (current && line.trim() !== '') {
+                                // git C-quotes any non-ASCII pathname here (core.quotepath). Left raw, it never
+                                // matched a candidate file, so the rationale came back empty while historyStatus
+                                // still reported `available` — a silent false negative with confident provenance.
+                                current.files.push((0, maintenance_analyze_1.unquoteGitPath)(line.trim()));
+                            }
+                        }
+                        historyStatus = 'available';
+                    }
+                    catch { /* history is evidence enrichment, not a prerequisite */ }
+                }
+                // Preserve localization rank for context: `impacts.direct` is deliberately sorted for a
+                // stable evidence contract, but sorting is not relevance. Seeding from it once selected a
+                // lexically earlier vendored symbol while the first ranked hit correctly named live code.
+                const directSeed = preliminary.candidates
+                    .flatMap((candidate) => candidate.symbols)
+                    .flatMap((qualifiedName) => graph.codeNodeIds(qualifiedName))[0];
+                const specSeed = preliminary.candidateSpecs.find((id) => id.startsWith('A-SPEC-'));
+                const seedId = directSeed ?? (specSeed ? `SPEC:${specSeed}` : undefined);
+                const budget = Math.max(100, Math.min(10_000, Math.floor(a.contextBudget ?? 2_000)));
+                const contextBundle = seedId
+                    ? new bundler_1.ContextBundler(graph, context.buildContentSource(specs, scanned)).getContextBundle(seedId, budget)
+                    : null;
+                // @implements A-SPEC-378
+                // Change recency over a WIDE window and ALL files — the enrichment history above is
+                // deliberately narrow (candidate files, 20 commits) and cannot serve as a prior: a file the
+                // lexical layer never ranked has no history there, which is precisely the file recency is
+                // supposed to promote. Failure is silent and total: no prior means the previous ranking,
+                // never a partial one, because a prior built from half the history would reorder on evidence
+                // nobody could audit.
+                const changePrior = {};
+                try {
+                    const prior = (0, temporal_prior_1.temporalPrior)(root, 'HEAD', 300);
+                    for (const [file, age] of prior.recency)
+                        changePrior[file] = 1 + Math.pow(0.5, age / 10);
+                }
+                catch { /* no history, no prior — the ranking falls back to lexical evidence alone */ }
+                // @implements A-SPEC-388
+                // What each file's commits have SAID, normalised to 0..1. Measured on history sampled away
+                // from the benchmarker's own recent work (A-SPEC-387): Top-1 0.244 -> 0.333 here and 0.400 ->
+                // 0.500 on a second repository, Top-10 recall 0.393 -> 0.601 there. Precision falls on both,
+                // and that is the trade, not a footnote to it.
+                const commitTextBoost = {};
+                try {
+                    const profile = (0, commit_text_1.commitTextProfile)(root, 'HEAD', 400);
+                    const ranked = (0, commit_text_1.rankByCommitText)(a.request, profile, 300);
+                    const top = ranked[0]?.score ?? 0;
+                    if (top > 0)
+                        for (const hit of ranked)
+                            commitTextBoost[hit.file] = hit.score / top;
+                }
+                catch { /* no history, no boost — the ranking falls back to lexical evidence alone */ }
+                const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
+                    semantic,
+                    ...common,
+                    coverage: { ...common.coverage, historyStatus },
+                    history,
+                    changePrior,
+                    commitTextBoost,
+                    contextBundle,
+                    groundTruth: a.groundTruth,
+                    defUse,
+                });
+                // @implements A-SPEC-573.4 — def-use for the TOP CANDIDATES ONLY. Extracting it for the whole
+                // repository costs +88.8% (measured 2026-09-08), well past this slice's budget; the first pass
+                // says which handful of files are worth parsing, and the second pass reads their data flow.
+                // Every step is fail-open: a parse failure, an unsupported language or a missing file leaves
+                // the candidate's symbols exactly as the first pass produced them.
+                const firstPass = analyzeWith();
+                const analysis = (() => {
+                    const targets = firstPass.candidates.slice(0, defuse_bound_1.DEFUSE_TOP_FILES).map((c) => c.file);
+                    if (targets.length === 0)
+                        return firstPass;
+                    const defUse = {};
+                    try {
+                        const { TreeSitterTsParser, hasDataFlowWalk } = require('../../cpg/language-parser');
+                        const { langForPath } = require('../../cpg/cpg-scanner');
+                        const parser = new TreeSitterTsParser();
+                        for (const file of targets) {
+                            try {
+                                // The LANGUAGE matters: the first wiring omitted it and parsed Python as TypeScript,
+                                // which produced wrong facts and cost the second corpus 0.2376 -> 0.1741 on the
+                                // symbol axis. A language with no walk is skipped rather than guessed at.
+                                const lang = langForPath(file);
+                                if (!hasDataFlowWalk(lang))
+                                    continue;
+                                const facts = parser.extractDataFlow(fs.readFileSync(path.join(root, file), 'utf8'), lang);
+                                if (facts !== undefined)
+                                    defUse[file] = facts;
+                            }
+                            catch { /* one unreadable or unparseable file must not cost the other nine */ }
+                        }
+                    }
+                    catch {
+                        return firstPass;
+                    }
+                    return Object.keys(defUse).length === 0 ? firstPass : analyzeWith(defUse);
+                })();
+                // @implements A-SPEC-268 — persistence is OPT-IN. The tool is advertised read-only, and a
+                // regression pins that a cold project gains no `.ax/cpg_cache`; writing evidence by default
+                // would break that contract for every caller who only wanted to look.
+                // One shape either way: `persistedTo` is present-or-undefined rather than a union, so a
+                // caller never has to narrow the result to ask whether anything was written.
+                const result = { ...analysis };
+                // @implements A-SPEC-418 — first line, because everything below it was computed without specs.
+                const blind = context.specStoreBlindReason(root, specs.length);
+                if (blind !== null)
+                    result.unknowns = [blind, ...result.unknowns];
+                if (a.persist) {
+                    // @implements A-SPEC-277 — record WHAT WAS ANALYSED, not just which paths. HEAD cannot see
+                    // an uncommitted edit to the analysed file; a content digest can.
+                    const fileDigests = {};
+                    for (const file of analysis.impacts.files) {
+                        const digest = context.fileDigestOf(root, file);
+                        if (digest)
+                            fileDigests[file] = digest;
+                    }
+                    // The artifact takes the WHOLE analysis, never the bounded one below: a file has no
+                    // context window, and the calibration that scores this prediction must score what the
+                    // product actually predicted.
+                    result.persistedTo = (0, maintenance_evidence_1.writeArtifact)(path.join(root, maintenance_evidence_1.EVIDENCE_DIR), (0, maintenance_evidence_1.artifactFrom)(analysis, new Date().toISOString(), fileDigests));
+                }
+                // @implements A-SPEC-578.5 — the response, and only the response, is bounded. Measured
+                // 2026-09-09: the full shape is 187,174 characters (~47k tokens) and the harness refuses
+                // it, which is why AGENTS.md step 3 had never once been obeyed with `persist: true`.
+                // `persistedTo` rides along so the caller knows where the whole thing is.
+                const bounded = (0, maintenance_analyze_1.boundAnalysis)(result);
+                if (JSON.stringify(bounded).length !== JSON.stringify(result).length)
+                    bounded.bounded = true;
+                return bounded;
+            }
+            finally {
+                graph.close();
+            }
+        },
+    };
+}

package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts

@@ -0,0 +1,40 @@
+interface MaintenanceEvidenceContext {
+    foreignRootReason(root: string): string | null;
+    projectRootOf(root: string): string;
+    refusal(reason: string): Error;
+    fileDigestOf(root: string, relativePath: string): string | null;
+}
+/** Raw handlers: the public facade attaches basis exactly once. */
+export declare function createMaintenanceEvidenceHandlers(context: MaintenanceEvidenceContext): {
+    maintenance_outcome(a: {
+        root: string;
+        digest: string;
+        actualFiles?: string[];
+        actualSymbols?: string[];
+        actualTests?: string[];
+        actualClassification?: string;
+    }): Promise<import("../maintenance-evidence").EvidenceArtifact>;
+    impact_gate_check(a: {
+        root: string;
+        target: string;
+        digest?: string;
+    }): Promise<import("../../guardrail/impact-gate").EditEvidenceVerdict>;
+    maintenance_calibration(a: {
+        root: string;
+        minSamples?: number;
+    }): Promise<{
+        artifacts: number;
+        unreadable: string[];
+        skippedSchema: number;
+        schema: string;
+        n: number;
+        withoutClassification: number;
+        bins: import("../maintenance-evidence").CalibrationBin[];
+        brierScore: number | null;
+        falsePositives: number;
+        falseNegatives: number;
+        minSamples: number;
+        status: "measured" | "insufficient-data";
+    }>;
+};
+export {};