@holmes-lab/holmes-kit 0.2.1 → 0.3.1

package/dist/holmes/review/captured-stdin-guard.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.capturedStdinViolations = capturedStdinViolations;
+// @implements A-SPEC-331
+/**
+ * Forbid piping a CAPTURED process output (or file read) into a child process's stdin.
+ *
+ * A-SPEC-329 removed one instance of this after it failed three times in production with
+ * `spawnSync tar EPIPE`; A-SPEC-330's guard protects only the file it was fixed in. This one is
+ * repository-wide, and the difficulty is telling the hazard apart from legitimate use — `doctor.ts`
+ * and `antigravity.ts` both pass small hook payloads on stdin and must keep working. A rule that
+ * flags them is noise, and a noisy rule gets ignored, which is worse than no rule at all.
+ *
+ * Size cannot be measured statically, so the discriminator is SHAPE, not size:
+ *
+ *   dangerous — `const buf = execFileSync(…); child({ input: buf })`
+ *               the input grows with the repository, and nothing in the code bounds it.
+ *   fine      — `child({ input: JSON.stringify(payload) })`
+ *               the code decides how big it is.
+ *
+ * KNOWN LIMITS, stated rather than implied by silence: this is text matching, not an AST. A capture
+ * assigned through an intermediate variable, returned from a helper, or imported from another file
+ * is missed. The goal is not soundness — it is that the specific mistake already made cannot be
+ * retyped somewhere else and go unnoticed.
+ */
+const CAPTURE = /(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:await\s+)?(?:\w+\.)?(?:execFileSync|execSync|spawnSync|readFileSync)\s*\(/;
+const STDIN_INPUT = /\binput\s*:\s*([A-Za-z_$][\w$]*)\s*[,}]/;
+function capturedStdinViolations(source, file) {
+    const lines = source.split('\n');
+    // A comment describing the pattern is documentation, not a defect — and this file is full of them.
+    const code = lines.map((line) => (line.trim().startsWith('//') || line.trim().startsWith('*') ? '' : line));
+    const captured = new Set();
+    for (const line of code) {
+        const m = CAPTURE.exec(line);
+        if (m)
+            captured.add(m[1]);
+    }
+    if (captured.size === 0)
+        return [];
+    const out = [];
+    code.forEach((line, i) => {
+        const m = STDIN_INPUT.exec(line);
+        // Whole-name comparison: `tarball` must not match a capture named `tar`.
+        if (m && captured.has(m[1]))
+            out.push({ file, variable: m[1], line: i + 1 });
+    });
+    return out;
+}

package/dist/holmes/review/coherence-verify.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Structural-coherence verification — the second verifier design, built on what S-497's negative
+ * proved: re-projected path/symbol text (lexical or semantic) is evidence the ranker already
+ * consumed, and it cannot answer "does this change actually touch this file". The evidence here
+ * is NEW to the emission: the graph relations AMONG the emitted candidates. A true change set is
+ * a connected working set (siblings that call/import each other or implement the same spec); a
+ * false tail candidate is a lexical coincidence with no edge to the head.
+ *
+ * Parent-time graph only — the same point-in-time discipline every arm obeys (A-SPEC-378).
+ * Absence from the graph is a verdict, not a coverage gap: a scanned file always has nodes, so
+ * "no relation to the head" is exactly the evidence this verifier exists to read. (Contrast with
+ * S-497's null-vector KEEP, where the signal simply had not spoken.)
+ */
+import type { GraphView } from '../assoc/assoc-arm';
+export interface CoherenceIndex {
+    /** file → files it shares at least one CODE↔CODE edge with (direction ignored, self excluded). */
+    fileEdges: Map<string, Set<string>>;
+    /** file → spec ids anchored to it (via SPEC↔CODE edges, either direction). */
+    fileSpecs: Map<string, Set<string>>;
+}
+export declare function buildCoherenceIndex(view: GraphView): CoherenceIndex;
+/** Coupled-member count per emission member — files outside the emission never count. */
+export declare function emissionDegree(idx: CoherenceIndex, members: readonly string[], rel: 'edge' | 'any'): Map<string, number>;
+/**
+ * Members of the largest connected component of the emission's induced coupling graph. Ties are
+ * kept as a union — with zero edges every member is a size-1 component and everyone survives,
+ * which is the honest verdict when the structure has nothing to say.
+ */
+export declare function largestCluster(idx: CoherenceIndex, members: readonly string[], rel: 'edge' | 'any'): Set<string>;
+export declare function anchoredConsensusAccept(anchor: (f: string) => boolean, deg: ReadonlyMap<string, number>, d: number, comb: 'or' | 'and'): (f: string) => boolean;
+export declare function coherentAccept(idx: CoherenceIndex, head: ReadonlySet<string>, mode: 'edge' | 'spec' | 'any'): (f: string) => boolean;

package/dist/holmes/review/coherence-verify.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCoherenceIndex = buildCoherenceIndex;
+exports.emissionDegree = emissionDegree;
+exports.largestCluster = largestCluster;
+exports.anchoredConsensusAccept = anchoredConsensusAccept;
+exports.coherentAccept = coherentAccept;
+const fileOf = (id) => {
+    if (id.startsWith('FILE:'))
+        return id.slice('FILE:'.length);
+    if (id.startsWith('CODE:')) {
+        const at = id.lastIndexOf('@');
+        return at >= 0 ? id.slice(at + 1) : null;
+    }
+    return null;
+};
+const specOf = (id) => (id.startsWith('SPEC:') ? id.slice('SPEC:'.length) : null);
+function buildCoherenceIndex(view) {
+    const fileEdges = new Map();
+    const fileSpecs = new Map();
+    const link = (m, a, b) => {
+        (m.get(a) ?? m.set(a, new Set()).get(a)).add(b);
+    };
+    for (const e of view.edges) {
+        const sf = fileOf(e.src), df = fileOf(e.dst);
+        if (sf !== null && df !== null) {
+            if (sf !== df) {
+                link(fileEdges, sf, df);
+                link(fileEdges, df, sf);
+            }
+            continue;
+        }
+        const spec = specOf(e.src) ?? specOf(e.dst);
+        const file = sf ?? df;
+        if (spec !== null && file !== null)
+            link(fileSpecs, file, spec);
+    }
+    return { fileEdges, fileSpecs };
+}
+// @implements A-SPEC-481 — position-independent verdicts. S-498 located the head-error failure
+// mode: the verdict's reference point (top-h) came from the ranking, so a wrong top-1 made
+// coherence cut truths. Degree and cluster judge the emission's own structure and have no head
+// to be wrong about; the explicit guard remains the only positional device, as a separate axis.
+/** Are two files coupled under the given relation? Symmetric; self-coupling is excluded upstream. */
+function coupled(idx, a, b, rel) {
+    if (idx.fileEdges.get(a)?.has(b) === true)
+        return true;
+    if (rel === 'edge')
+        return false;
+    const sa = idx.fileSpecs.get(a), sb = idx.fileSpecs.get(b);
+    if (sa === undefined || sb === undefined)
+        return false;
+    for (const s of sa)
+        if (sb.has(s))
+            return true;
+    return false;
+}
+/** Coupled-member count per emission member — files outside the emission never count. */
+function emissionDegree(idx, members, rel) {
+    const deg = new Map();
+    for (const f of members)
+        deg.set(f, 0);
+    for (let i = 0; i < members.length; i++) {
+        for (let j = i + 1; j < members.length; j++) {
+            if (members[i] !== members[j] && coupled(idx, members[i], members[j], rel)) {
+                deg.set(members[i], deg.get(members[i]) + 1);
+                deg.set(members[j], deg.get(members[j]) + 1);
+            }
+        }
+    }
+    return deg;
+}
+/**
+ * Members of the largest connected component of the emission's induced coupling graph. Ties are
+ * kept as a union — with zero edges every member is a size-1 component and everyone survives,
+ * which is the honest verdict when the structure has nothing to say.
+ */
+function largestCluster(idx, members, rel) {
+    const comp = new Map();
+    let n = 0;
+    for (const f of members) {
+        if (comp.has(f))
+            continue;
+        const stack = [f];
+        comp.set(f, n);
+        while (stack.length > 0) {
+            const cur = stack.pop();
+            for (const g of members) {
+                if (!comp.has(g) && coupled(idx, cur, g, rel)) {
+                    comp.set(g, n);
+                    stack.push(g);
+                }
+            }
+        }
+        n++;
+    }
+    const sizes = new Array(n).fill(0);
+    for (const c of comp.values())
+        sizes[c]++;
+    const max = Math.max(0, ...sizes);
+    return new Set([...comp.entries()].filter(([, c]) => sizes[c] === max).map(([f]) => f));
+}
+// @implements A-SPEC-482 — anchor + consensus, the last file-granularity combination: the anchor
+// carries the correctness prior S-499 proved indispensable, the degree carries the structure
+// S-498's head error could not see past. OR recovers truths a wrong head cut; AND refines away
+// coincidental couplings.
+function anchoredConsensusAccept(anchor, deg, d, comb) {
+    return (f) => {
+        const consensus = (deg.get(f) ?? 0) >= d;
+        return comb === 'or' ? anchor(f) || consensus : anchor(f) && consensus;
+    };
+}
+function coherentAccept(idx, head, mode) {
+    const byEdge = (f) => {
+        const n = idx.fileEdges.get(f);
+        if (n === undefined)
+            return false;
+        for (const h of head)
+            if (h !== f && n.has(h))
+                return true;
+        return false;
+    };
+    const bySpec = (f) => {
+        const s = idx.fileSpecs.get(f);
+        if (s === undefined)
+            return false;
+        for (const h of head) {
+            if (h === f)
+                continue;
+            const hs = idx.fileSpecs.get(h);
+            if (hs === undefined)
+                continue;
+            for (const id of s)
+                if (hs.has(id))
+                    return true;
+        }
+        return false;
+    };
+    if (mode === 'edge')
+        return byEdge;
+    if (mode === 'spec')
+        return bySpec;
+    return (f) => byEdge(f) || bySpec(f);
+}

package/dist/holmes/review/commit-text.d.ts

@@ -0,0 +1,50 @@
+/**
+ * What each file's commits have said about it.
+ *
+ * Eleven mechanisms have been measured and none of them read a commit message. The temporal arm used
+ * change recency — a timestamp, not text. The spec and call arms read only the vocabulary of code and
+ * specifications. But every file carries the prose of the commits that changed it, and that prose
+ * sits exactly between the language of a requirement and the names in the code: a report saying
+ * "uploads are being rejected" reaches `sanitizeIngest` through a commit that said "fix upload
+ * rejection on malformed payload".
+ *
+ * That is query → Commit → `MODIFIED_IN` → File: the knowledge graph used to retrieve, rather than
+ * to decorate a ranking that lexical matching already produced.
+ *
+ * **The window ends at the analysis basis.** Reading the answer commit's own message is reading the
+ * answer aloud — the subject of the very commit whose files are being predicted. A test pins that
+ * the profile at the parent does not contain it.
+ */
+export interface CommitTextProfile {
+    /**
+     * @implements A-SPEC-386
+     * Commit hashes the window actually read.
+     *
+     * Exposed for auditing rather than for use: this mechanism produced the largest gain in the whole
+     * project (uncited Top-10 recall 0.434 -> 0.751), and a repository that has already mistaken a
+     * leak for a result at recall 0.990 should be able to CHECK that the answer commit is absent
+     * rather than trust that it is.
+     */
+    commitIds: Set<string>;
+    /** file -> term -> how many commits in the window used that term while touching the file. */
+    byFile: Map<string, Map<string, number>>;
+    /** How many commits were read. 0 means unmeasured, not "no history". */
+    commits: number;
+    /** Commits each term appeared in, for weighting a term by how ordinary it is in this history. */
+    documentFrequency: Map<string, number>;
+}
+export declare function commitTextProfile(root: string, before: string, limit?: number): CommitTextProfile;
+/**
+ * Score files by how much their commit history talks like the request.
+ *
+ * Weighted by inverse commit frequency for the same reason file scoring is: a term appearing in
+ * every commit message ("fix", "test", "add") says nothing about which file is meant, and counting
+ * it equally with a rare one is the defect that cost this ranker its precision elsewhere.
+ *
+ * Returns an empty ranking when the window is empty — a caller must be able to tell "no history was
+ * read" from "history was read and matched nothing", so `commits === 0` is exposed on the profile.
+ */
+export declare function rankByCommitText(issueText: string, profile: CommitTextProfile, topN: number): Array<{
+    file: string;
+    score: number;
+}>;

package/dist/holmes/review/commit-text.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.commitTextProfile = commitTextProfile;
+exports.rankByCommitText = rankByCommitText;
+// @implements A-SPEC-385
+// @implements A-SPEC-386
+const node_child_process_1 = require("node:child_process");
+const maintenance_analyze_1 = require("../mcp/maintenance-analyze");
+const localize_1 = require("../rtm/localize");
+function commitTextProfile(root, before, limit = 400) {
+    const empty = { byFile: new Map(), commits: 0, documentFrequency: new Map(), commitIds: new Set() };
+    let raw;
+    try {
+        raw = (0, node_child_process_1.execFileSync)('git', ['-C', root, 'log', '--no-merges', `-${limit}`, '--format=%x00%H%x00%s', '--name-only', before], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    }
+    catch {
+        return empty;
+    }
+    const byFile = new Map();
+    const documentFrequency = new Map();
+    const commitIds = new Set();
+    let terms = [];
+    let commits = 0;
+    const flushTermsInto = (file) => {
+        const bucket = byFile.get(file) ?? byFile.set(file, new Map()).get(file);
+        for (const t of terms)
+            bucket.set(t, (bucket.get(t) ?? 0) + 1);
+    };
+    for (const line of raw.split('\n')) {
+        if (line.startsWith('\0')) {
+            const [hash, subject] = line.slice(1).split('\0');
+            commitIds.add(hash);
+            terms = [...new Set((0, localize_1.significantTerms)(subject ?? ''))];
+            for (const t of terms)
+                documentFrequency.set(t, (documentFrequency.get(t) ?? 0) + 1);
+            commits++;
+            continue;
+        }
+        const file = line.trim();
+        if (file.length === 0 || terms.length === 0)
+            continue;
+        flushTermsInto((0, maintenance_analyze_1.unquoteGitPath)(file));
+    }
+    return { byFile, commits, documentFrequency, commitIds };
+}
+/**
+ * Score files by how much their commit history talks like the request.
+ *
+ * Weighted by inverse commit frequency for the same reason file scoring is: a term appearing in
+ * every commit message ("fix", "test", "add") says nothing about which file is meant, and counting
+ * it equally with a rare one is the defect that cost this ranker its precision elsewhere.
+ *
+ * Returns an empty ranking when the window is empty — a caller must be able to tell "no history was
+ * read" from "history was read and matched nothing", so `commits === 0` is exposed on the profile.
+ */
+function rankByCommitText(issueText, profile, topN) {
+    if (profile.commits === 0)
+        return [];
+    const query = new Set((0, localize_1.significantTerms)(issueText));
+    if (query.size === 0)
+        return [];
+    const out = [];
+    for (const [file, bucket] of profile.byFile) {
+        let score = 0;
+        for (const t of query) {
+            const hits = bucket.get(t);
+            if (!hits)
+                continue;
+            const df = profile.documentFrequency.get(t) ?? 1;
+            score += hits * Math.log(1 + profile.commits / df);
+        }
+        if (score > 0)
+            out.push({ file, score });
+    }
+    return out.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file)).slice(0, topN);
+}

package/dist/holmes/review/confidence-calibration.d.ts

@@ -0,0 +1,39 @@
+/**
+ * What `maintenance_analyze`'s `confidence` actually predicts.
+ *
+ * The activation log's earlier entry said the field was a constant 0.25 across sixty cases, and that
+ * after a fix its correlation with accuracy was −0.062 — no signal. Re-measured through the shipped
+ * path it now takes three values, and the correlation is not merely absent. It is NEGATIVE, on both
+ * corpora, with the highest band the worst in each:
+ *
+ *   holmes  conf 0.25 → recall 0.751   conf 0.70 → 0.306   conf 0.85 → 0.542   r = −0.309
+ *   jarvis  conf 0.25 → recall 0.669   conf 0.65 → 0.646   conf 0.85 → 0.000   r = −0.212
+ *
+ * A caller who trusts this field trusts the wrong answers most. On the second corpus the two cases
+ * the harness was surest about returned nothing correct at all.
+ *
+ * The formula is NOT changed here. There is no hypothesis yet for why it inverts, and changing a
+ * scorer without one is a mistake this repository has had to undo more than once (A-SPEC-430,
+ * A-SPEC-431). What this module does is make the fact impossible to quote away.
+ */
+export interface ConfidenceBand {
+    confidence: number;
+    n: number;
+    meanRecall: number;
+    meanPrecision: number;
+}
+export interface CorpusConfidence {
+    corpus: string;
+    cases: number;
+    bands: readonly ConfidenceBand[];
+    correlationWithRecall: number;
+}
+/** Measured 2026-08-29 through analyzeMaintenance on each corpus's 30-case clean slice. */
+export declare const CONFIDENCE_BY_CORPUS: readonly CorpusConfidence[];
+/** Pearson correlation, so the number above can be recomputed rather than trusted. */
+export declare function correlation(points: ReadonlyArray<{
+    confidence: number;
+    recall: number;
+}>): number;
+/** The band with the lowest recall — on both corpora it is not the lowest-confidence one. */
+export declare function worstBin(c: CorpusConfidence): ConfidenceBand;

package/dist/holmes/review/confidence-calibration.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIDENCE_BY_CORPUS = void 0;
+exports.correlation = correlation;
+exports.worstBin = worstBin;
+/** Measured 2026-08-29 through analyzeMaintenance on each corpus's 30-case clean slice. */
+exports.CONFIDENCE_BY_CORPUS = [
+    {
+        corpus: 'holmes clean-30', cases: 30, correlationWithRecall: -0.309,
+        bands: [
+            { confidence: 0.25, n: 15, meanRecall: 0.751, meanPrecision: 0.133 },
+            { confidence: 0.70, n: 3, meanRecall: 0.306, meanPrecision: 0.100 },
+            { confidence: 0.85, n: 12, meanRecall: 0.542, meanPrecision: 0.133 },
+        ],
+    },
+    {
+        corpus: 'jarvis clean-30', cases: 30, correlationWithRecall: -0.212,
+        bands: [
+            { confidence: 0.25, n: 12, meanRecall: 0.669, meanPrecision: 0.175 },
+            { confidence: 0.65, n: 16, meanRecall: 0.646, meanPrecision: 0.119 },
+            { confidence: 0.85, n: 2, meanRecall: 0.000, meanPrecision: 0.000 },
+        ],
+    },
+];
+/** Pearson correlation, so the number above can be recomputed rather than trusted. */
+function correlation(points) {
+    if (points.length < 2)
+        return 0;
+    const mx = points.reduce((s, p) => s + p.confidence, 0) / points.length;
+    const my = points.reduce((s, p) => s + p.recall, 0) / points.length;
+    const cov = points.reduce((s, p) => s + (p.confidence - mx) * (p.recall - my), 0);
+    const vx = Math.sqrt(points.reduce((s, p) => s + (p.confidence - mx) ** 2, 0));
+    const vy = Math.sqrt(points.reduce((s, p) => s + (p.recall - my) ** 2, 0));
+    return vx === 0 || vy === 0 ? 0 : cov / (vx * vy);
+}
+/** The band with the lowest recall — on both corpora it is not the lowest-confidence one. */
+function worstBin(c) {
+    return [...c.bands].sort((a, b) => a.meanRecall - b.meanRecall)[0];
+}

package/dist/holmes/review/content-baseline.d.ts

@@ -0,0 +1,38 @@
+/**
+ * A baseline that reads the files.
+ *
+ * Every advantage claimed in this work compares against a baseline that matches the request's words
+ * against symbol names and paths — and never opens a file. A developer with `grep -r` reads bodies.
+ * The Goal's Phase B asked for "a strong model using plain file search" as the comparison, and a
+ * name-only matcher is weaker than that, which means every margin measured against it may be an
+ * artefact of an opponent that was not allowed to look.
+ *
+ * BM25 over file contents is what grepping approximates: it counts where the request's terms appear
+ * anywhere in the text, rewards rare terms, and corrects for length so a long file does not win by
+ * containing everything.
+ *
+ * Built to make the harness's claim HARDER to make. If this beats the shipped pipeline, the
+ * advantage recorded in this document is withdrawn.
+ */
+export interface ContentHit {
+    file: string;
+    score: number;
+}
+export interface ContentIndex {
+    /** file -> term -> count */
+    termFrequency: Map<string, Map<string, number>>;
+    documentFrequency: Map<string, number>;
+    averageLength: number;
+    lengths: Map<string, number>;
+    /** Files that could not be read — disclosed, never counted as empty. */
+    unreadable: string[];
+}
+export declare function indexContents(root: string, files: readonly string[]): ContentIndex;
+/**
+ * Rank files by BM25 over their contents.
+ *
+ * The same k1 and b as the spec retriever, untuned — tuning two constants against the corpus they
+ * are scored on would make the baseline look worse for a reason that is about the fitting rather
+ * than about the method, and this baseline exists to be strong.
+ */
+export declare function rankByContent(issueText: string, index: ContentIndex, topN: number): ContentHit[];

package/dist/holmes/review/content-baseline.js

@@ -0,0 +1,103 @@
+"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.indexContents = indexContents;
+exports.rankByContent = rankByContent;
+// @implements A-SPEC-403
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const localize_1 = require("../rtm/localize");
+const K1 = 1.2;
+const B = 0.75;
+/** Files above this are read but truncated — a megabyte of minified vendor code is not evidence. */
+const MAX_BYTES = 200_000;
+function indexContents(root, files) {
+    const termFrequency = new Map();
+    const documentFrequency = new Map();
+    const lengths = new Map();
+    const unreadable = [];
+    for (const file of files) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(root, file), 'utf8').slice(0, MAX_BYTES);
+        }
+        catch {
+            unreadable.push(file);
+            continue;
+        }
+        const terms = (0, localize_1.significantTerms)(text);
+        const counts = new Map();
+        for (const t of terms)
+            counts.set(t, (counts.get(t) ?? 0) + 1);
+        termFrequency.set(file, counts);
+        lengths.set(file, terms.length);
+        for (const t of counts.keys())
+            documentFrequency.set(t, (documentFrequency.get(t) ?? 0) + 1);
+    }
+    const total = [...lengths.values()].reduce((a, b) => a + b, 0);
+    return {
+        termFrequency, documentFrequency, lengths, unreadable,
+        averageLength: lengths.size === 0 ? 0 : total / lengths.size,
+    };
+}
+/**
+ * Rank files by BM25 over their contents.
+ *
+ * The same k1 and b as the spec retriever, untuned — tuning two constants against the corpus they
+ * are scored on would make the baseline look worse for a reason that is about the fitting rather
+ * than about the method, and this baseline exists to be strong.
+ */
+function rankByContent(issueText, index, topN) {
+    const query = [...new Set((0, localize_1.significantTerms)(issueText))];
+    const n = index.lengths.size;
+    if (query.length === 0 || n === 0)
+        return [];
+    const hits = [];
+    for (const [file, counts] of index.termFrequency) {
+        const len = index.lengths.get(file) ?? 0;
+        let score = 0;
+        for (const q of query) {
+            const f = counts.get(q) ?? 0;
+            if (f === 0)
+                continue;
+            const df = index.documentFrequency.get(q) ?? 0;
+            const idf = Math.max(Math.log(1 + (n - df + 0.5) / (df + 0.5)), 0);
+            score += idf * (f * (K1 + 1)) / (f + K1 * (1 - B + B * (len / (index.averageLength || 1))));
+        }
+        if (score > 0)
+            hits.push({ file, score });
+    }
+    return hits.sort((a, b) => b.score - a.score || a.file.localeCompare(b.file)).slice(0, topN);
+}

package/dist/holmes/review/content-verify.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Content-level verification — the first member of the file-CONTENT evidence class, opened
+ * after the file-granularity class (graph relations, name-projected embeddings) measured out
+ * at ×1.7–×2.5 against a modeled-human ×5.4 (S-497…S-502).
+ *
+ * The evidence here is what a human verifier actually reads when they open a candidate: does
+ * the request's rare vocabulary occur in the body at all, and does the candidate reference the
+ * change site by name (or the change site reference the candidate)? The ranker never consumed
+ * any of this — it ranked on path + symbol names alone. Bodies come from the MATERIALIZED
+ * parent tree only; reading the present tree would leak future content into a point-in-time
+ * benchmark.
+ */
+/** Top-k subject terms by IDF, descending, stable, lowercased. Unknown terms weigh 1.0. */
+export declare function topIdfTerms(terms: readonly string[], idf: ReadonlyMap<string, number>, k: number): string[];
+/** How many of the terms occur in the body (substring containment; body pre-lowercased). */
+export declare function bodyHitCount(bodyLower: string, terms: readonly string[]): number;
+/** The head's referenceable names: basename sans extension + symbol names; ≥3 chars, ≤20. */
+export declare function mentionNames(headPath: string, headSymbols: readonly string[]): string[];
+export declare function skipLicenseHeader(text: string): string;
+export declare function mentionsAny(bodyLower: string, names: readonly string[]): boolean;

package/dist/holmes/review/content-verify.js

@@ -0,0 +1,73 @@
+"use strict";
+// @implements A-SPEC-483
+/**
+ * Content-level verification — the first member of the file-CONTENT evidence class, opened
+ * after the file-granularity class (graph relations, name-projected embeddings) measured out
+ * at ×1.7–×2.5 against a modeled-human ×5.4 (S-497…S-502).
+ *
+ * The evidence here is what a human verifier actually reads when they open a candidate: does
+ * the request's rare vocabulary occur in the body at all, and does the candidate reference the
+ * change site by name (or the change site reference the candidate)? The ranker never consumed
+ * any of this — it ranked on path + symbol names alone. Bodies come from the MATERIALIZED
+ * parent tree only; reading the present tree would leak future content into a point-in-time
+ * benchmark.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.topIdfTerms = topIdfTerms;
+exports.bodyHitCount = bodyHitCount;
+exports.mentionNames = mentionNames;
+exports.skipLicenseHeader = skipLicenseHeader;
+exports.mentionsAny = mentionsAny;
+/** Top-k subject terms by IDF, descending, stable, lowercased. Unknown terms weigh 1.0. */
+function topIdfTerms(terms, idf, k) {
+    return terms
+        .map((t, i) => ({ t: t.toLowerCase(), w: idf.get(t.toLowerCase()) ?? 1.0, i }))
+        .sort((a, b) => b.w - a.w || a.i - b.i)
+        .slice(0, k)
+        .map((x) => x.t);
+}
+/** How many of the terms occur in the body (substring containment; body pre-lowercased). */
+function bodyHitCount(bodyLower, terms) {
+    let n = 0;
+    for (const t of terms)
+        if (t.length > 0 && bodyLower.includes(t))
+            n++;
+    return n;
+}
+/** The head's referenceable names: basename sans extension + symbol names; ≥3 chars, ≤20. */
+function mentionNames(headPath, headSymbols) {
+    const base = (headPath.split('/').pop() ?? '').replace(/\.[^.]+$/, '').toLowerCase();
+    const names = [base, ...headSymbols.map((s) => s.toLowerCase())].filter((n) => n.length >= 3);
+    return [...new Set(names)].slice(0, 20);
+}
+// @implements A-SPEC-490 — the excerpt fix S-507 demanded: a 400-char excerpt of a Google-style
+// file is ALL license header, and a judge reading it learns nothing. Only blocks that actually
+// talk about licensing are dropped; an informative leading comment (a Korean docstring) is
+// exactly what made the JARVIS judgments strong and must survive.
+const LICENSE_RE = /license|copyright|spdx/i;
+function skipLicenseHeader(text) {
+    let rest = text;
+    for (;;) {
+        const lead = rest.replace(/^\s*/, '');
+        let block = null;
+        if (lead.startsWith('/*')) {
+            const end = lead.indexOf('*/');
+            if (end >= 0)
+                block = lead.slice(0, end + 2);
+        }
+        else if (lead.startsWith('//') || lead.startsWith('#')) {
+            const m = lead.match(/^(?:(?:\/\/|#)[^\n]*\n?)+/);
+            if (m !== null)
+                block = m[0];
+        }
+        if (block === null || !LICENSE_RE.test(block))
+            return rest === text ? text : rest;
+        rest = lead.slice(block.length).replace(/^\s*\n/, '');
+    }
+}
+function mentionsAny(bodyLower, names) {
+    for (const n of names)
+        if (bodyLower.includes(n))
+            return true;
+    return false;
+}