@holmes-lab/holmes-kit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,41 @@ 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.3.0] - 2026-08-31
+
+The semantic layer, shipped the way the measurements allow: a 3-tier semantic search over the knowledge graph, surfaced only as rerank, evidence and alternates — never as a hard filter — plus a graded impact surface with its Phase-B yardstick, and the governance hardening batch.
+
+### Added
+- **3-tier semantic search (REQ-476/477)**: local `Xenova/bge-m3` (CLS pooling — frozen after a mean-pooling instrument accident cost 4.4×) and opt-in cloud `gemini-embedding-001`. Vectors live in a content-hash `VectorCache` (`.ax/cpg_cache/`, gitignored); `rtm_reindex` warms document vectors; the analysis hot path only LOOKS UP vectors and never writes disk (the read-only contract is pinned). Credentials resolve env → macOS keychain → `~/.holmes/credentials.json` (0600) via `holmes-kit semantic-key set|unset|status` (stdin only — the key never appears in argv, logs or reports); `doctor` reports the active tier/key source and WARNs on an in-tree `.env` key; the pre-tool-use gate denies an agent self-granting the key env vars (egress self-consent).
+- **Uncited semantic head rerank (REQ-478) + direct-path parity (REQ-496)**: on requests that cite no spec, `maintenance_analyze` and `issue_localize` rerank the candidate head by cached-vector cosine (set fixed, covered candidates only, why-line attached). Measured +26%/+93% head accuracy on the two uncited corpora, replicated 3/3 on holdout windows (+26~122%); citation-rich requests are never reranked (−61% measured harm guards the gate).
+- **Semantic verification evidence (REQ-486)**: cloud tier attaches `sem-verify(<model>, cos=…, τ0.65 pass|fail)` to candidates and `semCos` to `rankedImpact` rows — display-only calibration (the ×1.7 precision multiple replicated in three independent windows, but its recall cost proved window-dependent, so it ships as evidence, never as a filter).
+- **`semanticAlternates` (REQ-493/494)**: the top-3 semantic matches the lexical emission missed, as an additive field — measured reach ceiling gain ×1.25–×2.25 in lexically-weak windows with precision rising too; sets, orders and gates untouched.
+- **Graded impact surface `impacts.rankedImpact` (REQ-467~469)**: personalized-PageRank grading (uni-d0.3-h0, k=10), the first of 29 graph mechanisms to win both impact metrics on all three corpora (HOLMES recall 0.035→0.571); the gate-facing closure is unchanged.
+- **Impact Phase-B yardstick (REQ-470)**: a frozen string-property baseline (same-dir/stem/prefix) scored beside `rankedImpact` on every replay — the shipped grading beats it on both metrics on all three corpora (up to ×17 recall), meeting the NECESSARY condition for any better-than-a-person phrasing on this axis.
+- **Consumer contract in the tool description (REQ-495)**: `maintenance_analyze` now tells the consuming agent the three evidence surfaces exist and how to use them.
+- **Measurement plumbing (flag-gated, absent by default)**: replay window offsets, per-case blind dumps with body excerpts, verification/gate/ceiling arms — none of it changes an un-flagged run; the pinned numbers did not move.
+- **Governance hardening batch (S-448~S-470, previously committed)**: gate-bypass closures (20-syntax enumeration), constitutional backstop, double-spend post-detection on the approval ledger, doctor visibility.
+
+### Changed
+- **`maintenance_analyze` description**: carries the semantic-evidence consumer contract; its length pin moved with cause (1200→1600).
+
+### Unverified (named)
+- Windows execution and CI remain program-level gaps. The judgment-axis result (content-access agent selection P 0.744 ≈ 83% of the modeled human precision band) is a self-judged pilot; the official capability grade stays L2 until an independent judge replicates it (protocol package pre-generated). The modeled-human comparison and its per-axis verdicts live in `docs/research/human-engineer-modeling-2026-08-30.md` (revisions 4–5).
+
+## [0.2.1] - 2026-08-28
+
+Codex governance that is actually wired: the MCP server holmes-kit writes for Codex now lives where Codex reads it.
+
+### Fixed
+- **Codex MCP wiring goes where Codex actually reads it (REQ-266)**: `init` wrote the Codex harness's MCP server to a project-local `.codex/mcp_config.json` (JSON) — a file Codex never loads. Codex reads `[mcp_servers.*]` tables from `.codex/config.toml` (TOML), so **every Codex wiring since it was added was dead**, and because Codex enforces no hooks (`HARNESS_ENFORCES.codex = false`) that MCP server is Codex's *only* governance path — so Codex was wired but ungoverned. `init` now writes `[mcp_servers.holmes-kit]` into `.codex/config.toml`, **merging** so the user's other Codex settings and servers are preserved byte-for-byte (the same discipline as the `.mcp.json` merge), migrates away the obsolete `.codex/mcp_config.json` (only after the new write is confirmed), and `doctor`'s `codex wiring` check now verifies the file Codex reads (a leftover JSON with no `config.toml` is a WARN). The merge is string/bracket-aware — a `[mcp_servers.holmes-kit]` line inside a neighbor's multi-line string or array is not mistaken for a real table, and an unrecognized foreign header always closes our region rather than swallowing it. The three-harness parity meta-test now asserts not only identical launch command/args but that each harness's wiring lands where that harness reads it. Existing Codex projects: re-run `holmes-kit init --agent codex` (doctor will flag the stale wiring).
+- **`.codex/config.toml` is protected from self-disarm like its siblings (REQ-266)**: because that file is now Codex's sole governance path, an un-approved `Write`/`Edit` to it is denied for a config-write approval, exactly as `.mcp.json` and `.agents/*` already were — a session can no longer quietly re-point or delete Codex's MCP wiring.
+
+### Changed
+- **`init` pre-selects every harness by default (REQ-266)**: the interactive harness picker now checks all harnesses (Claude Code, Antigravity, Codex) by default, matching its own "Select All (Recommended)" affordance; Codex was previously left unchecked. Deselecting a harness is one keystroke; a silently un-wired harness is not.
+
+### Unverified (named)
+- `doctor`'s `codex wiring` check does not WARN on an out-of-date npx pin the way the `.mcp.json` version-drift check does; porting that drift WARN to `.codex/config.toml` is a named follow-up (A-SPEC-251.2 family), not a wiring defect.
+
 ## [0.2.0] - 2026-08-27
 
 The approval decision surface, world-tier: the operator stays at one screen, and a grant is exactly what they saw.

package/dist/.build-id

@@ -1 +1 @@
-f7a048d-mtbm5atb
+503a295-mth8qak7

package/dist/holmes/assoc/assoc-arm.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The measurement ARM around the PPR primitive — everything the replay harness needs to score
+ * associative recall beside the shipped ranker, and nothing the product itself consumes.
+ *
+ * Two modes, scored separately because they answer different questions and past mechanisms died
+ * on exactly this distinction (admission cost the spec layer 33% precision; caller closure added
+ * 59 files with zero correct):
+ *   - rerank: reorder the PRODUCT's candidate pool by mass. The pool is fixed; only aiming moves.
+ *   - admit:  rank every file by mass, pool ignored. Measures what association alone would name.
+ */
+import { type WeightProfile } from './ppr';
+export interface PprArmConfig {
+    label: string;
+    d: number;
+    weights: WeightProfile;
+}
+/** Citation seeds outweigh term seeds: the one signal measured strong on this corpus is the
+ * request naming its spec (recall 0.601→0.851 when extraction stopped mangling the ids). */
+export declare const SEED_CITATION_WEIGHT = 10;
+export interface GraphView {
+    edges: Array<{
+        src: string;
+        dst: string;
+        rel: string;
+    }>;
+    /** Node ids, lowercased once, paired with the original — term matching is case-insensitive. */
+    nodes: Array<{
+        id: string;
+        lower: string;
+    }>;
+}
+/** Parse the canonical dump (N/E TSV rows) once per case. */
+export declare function graphViewOf(dump: string): GraphView;
+/**
+ * Seeds from the request text, reusing the shipped extractors (A-SPEC-349: a second extractor is a
+ * second thing to drift): cited spec ids seed their SPEC nodes at fixed high weight; significant
+ * terms seed every node whose identifier contains them, at the term's IDF weight.
+ */
+export declare function seedNodes(request: string, specIds: ReadonlySet<string>, view: GraphView, idf: ReadonlyMap<string, number>): Map<string, number>;
+/** Aggregate node mass to source files: `CODE:sym@path` and `FILE:path` both land on `path`. */
+export declare function fileMass(mass: ReadonlyMap<string, number>): Map<string, number>;
+/** rerank mode: the pool is the product's; only the order moves. Zero-mass files keep their
+ * original relative order behind every massed file — a stable sort so the arm never DELETES an
+ * answer the pool already had (the ranker-deletes-its-own-answer lesson). */
+export declare function rerankPool(pool: readonly string[], fm: ReadonlyMap<string, number>): string[];
+/** admit mode: association alone, top-N by mass, nothing back-filled — a blur here would make the
+ * admission cost unattributable. */
+export declare function admitRank(fm: ReadonlyMap<string, number>, topN: number): string[];
+/** One case, one config: both modes from a single spread. */
+export declare function pprCaseRanking(view: GraphView, seeds: ReadonlyMap<string, number>, pool: readonly string[], topN: number, config: PprArmConfig): {
+    rerank: string[];
+    admit: string[];
+};
+/**
+ * @implements A-SPEC-468 — the impact-axis grading arm. The incumbent there is an UNGRADED
+ * transitive closure: measured, it reaches 84% of a commit's co-changed files and names 11% of
+ * them, with only 3 answers in the whole corpus sitting behind any stop — the bottleneck is
+ * selection within reach, which is exactly what damped mass grades. The seed FILE itself is
+ * excluded from the prediction: predicting "the changed file will change" is vacuously true and
+ * would inflate every metric it touches.
+ */
+export declare function pprImpactPredict(view: GraphView, seeds: ReadonlyMap<string, number>, seedFile: string, k: number, config: PprArmConfig): string[];
+/**
+ * @implements A-SPEC-469 — the SCORED form the product ships. One code path serves the
+ * measurement (pprImpactPredict above is a thin wrapper) and the shipped surface, so the S-484
+ * numbers transfer by identity rather than by reimplementation. The whole changed set is excluded
+ * — with several changed files, each predicting another member of the same commit is the same
+ * vacuous truth as predicting itself.
+ */
+export declare function pprImpactRanked(view: GraphView, seeds: ReadonlyMap<string, number>, excludeFiles: ReadonlySet<string>, k: number, config: PprArmConfig): Array<{
+    file: string;
+    score: number;
+}>;
+/**
+ * @implements A-SPEC-469 — the adopted configuration, frozen to the S-484 three-corpus winner:
+ * uni-d0.3-h0 at k=10 beat the ungraded closure on BOTH recall and precision on every corpus
+ * (HOLMES 0.0347/0.0413 → 0.5713/0.1611; JARVIS 0.0980/0.0125 → 0.3333/0.0588; GEMINI
+ * 0.3143/0.0203 → 0.3611/0.0533). Change these numbers only with a new sweep beside them.
+ */
+export declare const RANKED_IMPACT_CONFIG: PprArmConfig;
+export declare const RANKED_IMPACT_K = 10;
+/**
+ * @implements A-SPEC-471 — the emission rule, the knob that models the human high-precision
+ * profile ("say only what you are sure of"): keep everything scoring at least alpha of the top
+ * mass, cap at k. The RANKING never moves — only how much of it is spoken. Pure; sorts defensively
+ * so a caller's ordering mistake cannot masquerade as a confidence cut.
+ */
+export declare function emitByRule(scored: ReadonlyArray<{
+    file: string;
+    score: number;
+}>, alpha: number, k: number): string[];
+/** The first sweep, small on purpose: d × hub × two direction profiles. Values are recorded with
+ * the numbers they produce; widening the sweep is a decision the first numbers make. */
+export declare function defaultPprConfigs(): PprArmConfig[];

package/dist/holmes/assoc/assoc-arm.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RANKED_IMPACT_K = exports.RANKED_IMPACT_CONFIG = exports.SEED_CITATION_WEIGHT = void 0;
+exports.graphViewOf = graphViewOf;
+exports.seedNodes = seedNodes;
+exports.fileMass = fileMass;
+exports.rerankPool = rerankPool;
+exports.admitRank = admitRank;
+exports.pprCaseRanking = pprCaseRanking;
+exports.pprImpactPredict = pprImpactPredict;
+exports.pprImpactRanked = pprImpactRanked;
+exports.emitByRule = emitByRule;
+exports.defaultPprConfigs = defaultPprConfigs;
+// @implements A-SPEC-467
+/**
+ * The measurement ARM around the PPR primitive — everything the replay harness needs to score
+ * associative recall beside the shipped ranker, and nothing the product itself consumes.
+ *
+ * Two modes, scored separately because they answer different questions and past mechanisms died
+ * on exactly this distinction (admission cost the spec layer 33% precision; caller closure added
+ * 59 files with zero correct):
+ *   - rerank: reorder the PRODUCT's candidate pool by mass. The pool is fixed; only aiming moves.
+ *   - admit:  rank every file by mass, pool ignored. Measures what association alone would name.
+ */
+const ppr_1 = require("./ppr");
+const localize_1 = require("../rtm/localize");
+/** Citation seeds outweigh term seeds: the one signal measured strong on this corpus is the
+ * request naming its spec (recall 0.601→0.851 when extraction stopped mangling the ids). */
+exports.SEED_CITATION_WEIGHT = 10;
+/** Parse the canonical dump (N/E TSV rows) once per case. */
+function graphViewOf(dump) {
+    const edges = [];
+    const nodes = [];
+    for (const line of dump.split('\n')) {
+        const cols = line.split('\t');
+        if (cols[0] === 'E' && cols[1] && cols[2] && cols[3])
+            edges.push({ src: cols[1], dst: cols[2], rel: cols[3] });
+        else if (cols[0] === 'N' && cols[1])
+            nodes.push({ id: cols[1], lower: cols[1].toLowerCase() });
+    }
+    return { edges, nodes };
+}
+/**
+ * Seeds from the request text, reusing the shipped extractors (A-SPEC-349: a second extractor is a
+ * second thing to drift): cited spec ids seed their SPEC nodes at fixed high weight; significant
+ * terms seed every node whose identifier contains them, at the term's IDF weight.
+ */
+function seedNodes(request, specIds, view, idf) {
+    const seeds = new Map();
+    for (const id of (0, localize_1.citationsIn)(request, specIds).cited) {
+        seeds.set(`SPEC:${id}`, (seeds.get(`SPEC:${id}`) ?? 0) + exports.SEED_CITATION_WEIGHT);
+    }
+    const terms = (0, localize_1.significantTerms)(request).slice(0, 16).map((t) => t.toLowerCase()).filter((t) => t.length >= 3);
+    for (const n of view.nodes) {
+        for (const t of terms) {
+            if (!n.lower.includes(t))
+                continue;
+            seeds.set(n.id, (seeds.get(n.id) ?? 0) + (idf.get(t) ?? 1));
+        }
+    }
+    return seeds;
+}
+/** Aggregate node mass to source files: `CODE:sym@path` and `FILE:path` both land on `path`. */
+function fileMass(mass) {
+    const fm = new Map();
+    for (const [id, m] of mass) {
+        let file = null;
+        if (id.startsWith('CODE:')) {
+            const at = id.lastIndexOf('@');
+            if (at > 0)
+                file = id.slice(at + 1);
+        }
+        else if (id.startsWith('FILE:')) {
+            file = id.slice('FILE:'.length);
+        }
+        if (file !== null && file !== '')
+            fm.set(file, (fm.get(file) ?? 0) + m);
+    }
+    return fm;
+}
+/** rerank mode: the pool is the product's; only the order moves. Zero-mass files keep their
+ * original relative order behind every massed file — a stable sort so the arm never DELETES an
+ * answer the pool already had (the ranker-deletes-its-own-answer lesson). */
+function rerankPool(pool, fm) {
+    return pool
+        .map((file, i) => ({ file, i, m: fm.get(file) ?? 0 }))
+        .sort((a, b) => (b.m - a.m) || (a.i - b.i))
+        .map((x) => x.file);
+}
+/** admit mode: association alone, top-N by mass, nothing back-filled — a blur here would make the
+ * admission cost unattributable. */
+function admitRank(fm, topN) {
+    return [...fm.entries()]
+        .filter(([, m]) => m > 0)
+        .sort((a, b) => (b[1] - a[1]) || (a[0] < b[0] ? -1 : 1))
+        .slice(0, topN)
+        .map(([file]) => file);
+}
+/** One case, one config: both modes from a single spread. */
+function pprCaseRanking(view, seeds, pool, topN, config) {
+    if (seeds.size === 0)
+        return { rerank: [...pool], admit: [] };
+    const adj = (0, ppr_1.buildAdjacency)(view.edges, config.weights);
+    const mass = (0, ppr_1.personalizedPageRank)(adj, seeds, { d: config.d });
+    const fm = fileMass(mass);
+    return { rerank: rerankPool(pool, fm), admit: admitRank(fm, topN) };
+}
+/**
+ * @implements A-SPEC-468 — the impact-axis grading arm. The incumbent there is an UNGRADED
+ * transitive closure: measured, it reaches 84% of a commit's co-changed files and names 11% of
+ * them, with only 3 answers in the whole corpus sitting behind any stop — the bottleneck is
+ * selection within reach, which is exactly what damped mass grades. The seed FILE itself is
+ * excluded from the prediction: predicting "the changed file will change" is vacuously true and
+ * would inflate every metric it touches.
+ */
+function pprImpactPredict(view, seeds, seedFile, k, config) {
+    return pprImpactRanked(view, seeds, new Set([seedFile]), k, config).map((r) => r.file);
+}
+/**
+ * @implements A-SPEC-469 — the SCORED form the product ships. One code path serves the
+ * measurement (pprImpactPredict above is a thin wrapper) and the shipped surface, so the S-484
+ * numbers transfer by identity rather than by reimplementation. The whole changed set is excluded
+ * — with several changed files, each predicting another member of the same commit is the same
+ * vacuous truth as predicting itself.
+ */
+function pprImpactRanked(view, seeds, excludeFiles, k, config) {
+    if (seeds.size === 0)
+        return [];
+    const adj = (0, ppr_1.buildAdjacency)(view.edges, config.weights);
+    const mass = (0, ppr_1.personalizedPageRank)(adj, seeds, { d: config.d });
+    const fm = fileMass(mass);
+    for (const f of excludeFiles)
+        fm.delete(f);
+    return [...fm.entries()]
+        .filter(([, m]) => m > 0)
+        .sort((a, b) => (b[1] - a[1]) || (a[0] < b[0] ? -1 : 1))
+        .slice(0, k)
+        .map(([file, score]) => ({ file, score: Math.round(score * 10000) / 10000 }));
+}
+/**
+ * @implements A-SPEC-469 — the adopted configuration, frozen to the S-484 three-corpus winner:
+ * uni-d0.3-h0 at k=10 beat the ungraded closure on BOTH recall and precision on every corpus
+ * (HOLMES 0.0347/0.0413 → 0.5713/0.1611; JARVIS 0.0980/0.0125 → 0.3333/0.0588; GEMINI
+ * 0.3143/0.0203 → 0.3611/0.0533). Change these numbers only with a new sweep beside them.
+ */
+exports.RANKED_IMPACT_CONFIG = {
+    label: 'uni-d0.3-h0',
+    d: 0.3,
+    weights: {
+        rels: { implements: { fwd: 2, back: 2 }, calls: { fwd: 1, back: 1 }, imports: { fwd: 0.5, back: 0.5 } },
+        hubExponent: 0,
+    },
+};
+exports.RANKED_IMPACT_K = 10;
+/**
+ * @implements A-SPEC-471 — the emission rule, the knob that models the human high-precision
+ * profile ("say only what you are sure of"): keep everything scoring at least alpha of the top
+ * mass, cap at k. The RANKING never moves — only how much of it is spoken. Pure; sorts defensively
+ * so a caller's ordering mistake cannot masquerade as a confidence cut.
+ */
+function emitByRule(scored, alpha, k) {
+    if (scored.length === 0)
+        return [];
+    const sorted = [...scored].sort((a, b) => (b.score - a.score) || (a.file < b.file ? -1 : 1));
+    const cut = alpha * sorted[0].score;
+    return sorted.filter((r) => r.score >= cut).slice(0, k).map((r) => r.file);
+}
+/** The first sweep, small on purpose: d × hub × two direction profiles. Values are recorded with
+ * the numbers they produce; widening the sweep is a decision the first numbers make. */
+function defaultPprConfigs() {
+    const uniform = (hub) => ({
+        rels: { implements: { fwd: 2, back: 2 }, calls: { fwd: 1, back: 1 }, imports: { fwd: 0.5, back: 0.5 } },
+        hubExponent: hub,
+    });
+    const callers = (hub) => ({
+        rels: { implements: { fwd: 2, back: 2 }, calls: { fwd: 0.3, back: 1 }, imports: { fwd: 0.5, back: 0.5 } },
+        hubExponent: hub,
+    });
+    const out = [];
+    for (const d of [0.3, 0.5, 0.85]) {
+        for (const hub of [0, 0.5]) {
+            out.push({ label: `uni-d${d}-h${hub}`, d, weights: uniform(hub) });
+            out.push({ label: `call-d${d}-h${hub}`, d, weights: callers(hub) });
+        }
+    }
+    return out;
+}

package/dist/holmes/assoc/explore.d.ts

@@ -0,0 +1,21 @@
+import { type GraphView } from './assoc-arm';
+export interface ExploreInput {
+    view: GraphView;
+    seedFile: string;
+    seedNodeIds: string[];
+    issueText: string;
+    idf: ReadonlyMap<string, number>;
+    /** Arm A's precomputed ranking (the static surface). */
+    staticList: readonly string[];
+}
+export interface ExploreOpts {
+    E?: number;
+    R?: number;
+    verify: (file: string) => boolean;
+}
+export interface RoundResult {
+    round: number;
+    emitted: string[];
+    hits: string[];
+}
+export declare function exploreIterative(input: ExploreInput, arm: 'A' | 'B' | 'C' | 'D', opts: ExploreOpts): RoundResult[];

package/dist/holmes/assoc/explore.js

@@ -0,0 +1,160 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.exploreIterative = exploreIterative;
+// @implements A-SPEC-472
+/**
+ * The three-arm iteration experiment: does an agent that FEEDS BACK what it learned each round
+ * beat the same budget spent statically?
+ *
+ * Arms, identical budget and oracle, differing ONLY in adaptation policy:
+ *   A — none: consume a precomputed static ranking (the S-486 shipped surface's list).
+ *   B — re-seed: confirmed files join the PPR seeds; the walk re-spreads each round.
+ *   C — judged expansion: typed edge candidates from the frontier, scored by a FROZEN
+ *       deterministic judge (lex + confirmation + type prior, equal weights — no tuning before
+ *       the first numbers; the judgment axis has a measured sign-flip precedent and earns nothing
+ *       on faith).
+ *
+ * The oracle (`verify`) simulates a developer actually checking a candidate. It is called on
+ * EXACTLY the emitted set — consulting it about unemitted files would leak ground truth into the
+ * trajectory, and the whole comparison would be theater. The loop owns that invariant; a test
+ * pins it with a spy.
+ *
+ * Literature this operationalizes (measured wins, see docs/research/iterative-graph-exploration):
+ * ToG's explore-think alternation, LocAgent's graph-tool traversal, KGCompass's finding that
+ * 89.7% of its successful localizations were reachable only by multi-hop traversal.
+ */
+const ppr_1 = require("./ppr");
+const assoc_arm_1 = require("./assoc-arm");
+const localize_1 = require("../rtm/localize");
+const TYPE_PRIOR = { implements: 1.0, calls: 0.8, imports: 0.5 };
+const fileOfNode = (id) => {
+    if (id.startsWith('CODE:')) {
+        const at = id.lastIndexOf('@');
+        return at > 0 ? id.slice(at + 1) : null;
+    }
+    if (id.startsWith('FILE:'))
+        return id.slice('FILE:'.length);
+    return null;
+};
+function exploreIterative(input, arm, opts) {
+    const E = opts.E ?? 2;
+    const R = opts.R ?? 10;
+    const emittedEver = new Set([input.seedFile]);
+    const confirmed = new Set();
+    const rounds = [];
+    // Precompute the structures every round reuses.
+    const adj = arm === 'B' ? (0, ppr_1.buildAdjacency)(input.view.edges, assoc_arm_1.RANKED_IMPACT_CONFIG.weights) : null;
+    // D = C's judged candidates first; the SHORTFALL — and only the shortfall — from the static
+    // ranking (@implements A-SPEC-473). C's measured failure was supply, not judgment: GEMINI used
+    // 9.4 of a 20-emission budget and saturated below the static arm. A fallback confirmation
+    // re-grows the frontier, so the starvation self-heals.
+    const nodesOfFile = new Map();
+    for (const n of input.view.nodes) {
+        const f = fileOfNode(n.id);
+        if (f !== null)
+            (nodesOfFile.get(f) ?? nodesOfFile.set(f, []).get(f)).push(n.id);
+    }
+    const terms = (0, localize_1.significantTerms)(input.issueText).slice(0, 16).map((t) => t.toLowerCase()).filter((t) => t.length >= 3);
+    const maxIdf = Math.max(1, ...[...input.idf.values()]);
+    const candidatesC = () => {
+        // Frontier = the seed file plus everything confirmed so far.
+        const frontier = new Set([input.seedFile, ...confirmed]);
+        const frontierNodes = new Set();
+        for (const f of frontier)
+            for (const id of nodesOfFile.get(f) ?? [])
+                frontierNodes.add(id);
+        // Typed expansion: calls both ways, implements-siblings via the shared SPEC, imports both ways.
+        const specsOfFrontier = new Set();
+        const reach = new Map();
+        const touch = (candFile, srcFile, prior) => {
+            if (candFile === null || frontier.has(candFile))
+                return;
+            const r = reach.get(candFile) ?? reach.set(candFile, { sources: new Set(), type: 0 }).get(candFile);
+            r.sources.add(srcFile);
+            r.type = Math.max(r.type, prior);
+        };
+        for (const e of input.view.edges) {
+            const sf = fileOfNode(e.src);
+            const df = fileOfNode(e.dst);
+            if (e.rel === 'implements' && sf !== null && frontier.has(sf))
+                specsOfFrontier.add(e.dst);
+            if (e.rel === 'calls' || e.rel === 'imports') {
+                const prior = TYPE_PRIOR[e.rel];
+                if (sf !== null && frontier.has(sf))
+                    touch(df, sf, prior);
+                if (df !== null && frontier.has(df))
+                    touch(sf, df, prior);
+            }
+        }
+        for (const e of input.view.edges) {
+            if (e.rel !== 'implements' || !specsOfFrontier.has(e.dst))
+                continue;
+            const sf = fileOfNode(e.src);
+            if (sf !== null && !frontier.has(sf))
+                touch(sf, `spec:${e.dst}`, TYPE_PRIOR.implements);
+        }
+        const lexOf = (file) => {
+            let best = 0;
+            for (const id of nodesOfFile.get(file) ?? []) {
+                const lower = id.toLowerCase();
+                for (const t of terms)
+                    if (lower.includes(t))
+                        best = Math.max(best, (input.idf.get(t) ?? 1) / maxIdf);
+            }
+            return best;
+        };
+        return [...reach.entries()].map(([file, r]) => ({
+            file,
+            score: lexOf(file) + Math.min(r.sources.size, 3) / 3 + r.type,
+        }));
+    };
+    for (let round = 1; round <= R; round++) {
+        let ranked;
+        if (arm === 'A') {
+            ranked = input.staticList.filter((f) => !emittedEver.has(f));
+        }
+        else if (arm === 'B') {
+            const seeds = new Map();
+            for (const id of input.seedNodeIds)
+                seeds.set(id, 1);
+            for (const f of confirmed)
+                for (const id of nodesOfFile.get(f) ?? [])
+                    seeds.set(id, 1);
+            const fm = (0, assoc_arm_1.fileMass)((0, ppr_1.personalizedPageRank)(adj, seeds, { d: assoc_arm_1.RANKED_IMPACT_CONFIG.d }));
+            ranked = [...fm.entries()]
+                .filter(([f, m]) => m > 0 && !emittedEver.has(f))
+                .sort((a, b) => (b[1] - a[1]) || (a[0] < b[0] ? -1 : 1))
+                .map(([f]) => f);
+        }
+        else {
+            ranked = candidatesC()
+                .filter((c) => !emittedEver.has(c.file))
+                .sort((a, b) => (b.score - a.score) || (a.file < b.file ? -1 : 1))
+                .map((c) => c.file);
+            if (arm === 'D' && ranked.length < E) {
+                const have = new Set(ranked);
+                for (const f of input.staticList) {
+                    if (ranked.length >= E)
+                        break;
+                    if (!emittedEver.has(f) && !have.has(f)) {
+                        ranked.push(f);
+                        have.add(f);
+                    }
+                }
+            }
+        }
+        const emitted = ranked.slice(0, E);
+        if (emitted.length === 0)
+            break;
+        const hits = [];
+        for (const f of emitted) {
+            emittedEver.add(f);
+            if (opts.verify(f)) {
+                hits.push(f);
+                confirmed.add(f);
+            }
+        }
+        rounds.push({ round, emitted, hits });
+    }
+    return rounds;
+}

package/dist/holmes/assoc/impact-baseline.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The impact axis's Phase-B external yardstick — a deliberately POOR baseline: the first
+ * instinct of a person who just saw the changed file, using string properties only. No graph,
+ * no specs, no IDF, no history; the poverty is the point (operating principle 10: any
+ * better-than-a-person phrasing needs this comparison as its NECESSARY condition).
+ *
+ * Frozen scoring (pre-registered in REQ-470, adjusted only via a new slice):
+ *   3 × [same directory as the seed]
+ * + 2 × [shares the seed's stem (≥4 chars; test/spec/d suffix tokens stripped)]
+ * + 1 × per shared leading directory segment.
+ * Zero scores are not emitted; ties break lexicographically; the seed never appears.
+ */
+export declare function impactBaselinePredict(seed: string, files: readonly string[], k?: number): string[];

package/dist/holmes/assoc/impact-baseline.js

@@ -0,0 +1,48 @@
+"use strict";
+// @implements A-SPEC-470
+/**
+ * The impact axis's Phase-B external yardstick — a deliberately POOR baseline: the first
+ * instinct of a person who just saw the changed file, using string properties only. No graph,
+ * no specs, no IDF, no history; the poverty is the point (operating principle 10: any
+ * better-than-a-person phrasing needs this comparison as its NECESSARY condition).
+ *
+ * Frozen scoring (pre-registered in REQ-470, adjusted only via a new slice):
+ *   3 × [same directory as the seed]
+ * + 2 × [shares the seed's stem (≥4 chars; test/spec/d suffix tokens stripped)]
+ * + 1 × per shared leading directory segment.
+ * Zero scores are not emitted; ties break lexicographically; the seed never appears.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.impactBaselinePredict = impactBaselinePredict;
+const SUFFIX_TOKENS = new Set(['test', 'spec', 'd']);
+const stemOf = (file) => {
+    const base = file.slice(file.lastIndexOf('/') + 1).replace(/\.[^.]+$/, '');
+    const tokens = base.split(/[._-]/).filter((t) => t.length > 0);
+    while (tokens.length > 1 && SUFFIX_TOKENS.has(tokens[tokens.length - 1]))
+        tokens.pop();
+    return tokens[0] ?? '';
+};
+const dirOf = (file) => file.slice(0, Math.max(0, file.lastIndexOf('/')));
+const sharedPrefixDepth = (a, b) => {
+    const as = dirOf(a).split('/');
+    const bs = dirOf(b).split('/');
+    let n = 0;
+    while (n < as.length && n < bs.length && as[n] === bs[n] && as[n] !== '')
+        n++;
+    return n;
+};
+function impactBaselinePredict(seed, files, k = 10) {
+    const seedDir = dirOf(seed);
+    const seedStem = stemOf(seed);
+    const scored = [];
+    for (const f of files) {
+        if (f === seed)
+            continue;
+        const stemShare = seedStem.length >= 4 && stemOf(f) === seedStem;
+        const score = (dirOf(f) === seedDir ? 3 : 0) + (stemShare ? 2 : 0) + sharedPrefixDepth(f, seed);
+        if (score > 0)
+            scored.push({ file: f, score });
+    }
+    scored.sort((a, b) => b.score - a.score || (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+    return scored.slice(0, k).map((x) => x.file);
+}

package/dist/holmes/assoc/ppr.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Personalized PageRank over the RTM/CPG edge set — the associative-recall primitive.
+ *
+ * Why this exists: the shipped retrieval primitives sit at two extremes. `issue_localize` stops at
+ * one spec hop (its own comment defers anything further), and `rtm_impact` returns an UNGRADED
+ * transitive closure — measured on the replay corpus, 84% of a commit's co-changed files are
+ * reachable through that closure while the analysis names 11% of them: the bottleneck is selection
+ * within reach, not reach. What is missing between the two is graded multi-hop mass —
+ * Score(1-hop) > Score(2-hop) > … > 0 — which is exactly what a damped random walk provides.
+ *
+ * Eleven graph/semantic mechanisms were measured and rejected on this corpus before this one
+ * (binary k-hop expansion, caller closure, co-change retrieval, dense embeddings, …). PPR is
+ * structurally different from all of them: it produces a RANKING over nodes rather than an
+ * admission set, and the geometric damping suppresses the crowd problem that sank the closure.
+ * That difference is the reason this module exists; whether it PAYS is decided by the replay arm
+ * (rerank and admit modes scored separately, three corpora), never assumed here.
+ *
+ * Deterministic, pure, no I/O. PPR mass never enters a gate decision — association proposes,
+ * the deterministic layers judge.
+ */
+/** Per-rel directed weights. `fwd` follows the edge, `back` walks it in reverse — direction is
+ * meaning in a software graph: diagnosis walks callers-ward, impact walks callee-ward. A rel
+ * absent from the profile contributes nothing. */
+export interface WeightProfile {
+    rels: Record<string, {
+        fwd: number;
+        back: number;
+    }>;
+    /** Divide each contribution INTO a node by degree^hubExponent — utility hubs otherwise soak up
+     * the mass of every walk that grazes them (the fan-in problem the closure already measured). */
+    hubExponent: number;
+}
+export interface PprOptions {
+    /** Damping: probability of continuing the walk instead of teleporting back to the seeds. */
+    d: number;
+    maxIter?: number;
+    /** L1 convergence threshold; 0 means run all iterations. */
+    eps?: number;
+}
+interface OutEdge {
+    to: string;
+    w: number;
+}
+export interface Adjacency {
+    /** Out-transition lists, weight-normalized to sum 1 per node. */
+    out: Map<string, OutEdge[]>;
+    nodes: Set<string>;
+}
+/** Build the weighted, direction-aware, hub-damped transition structure once per graph. */
+export declare function buildAdjacency(edges: Iterable<{
+    src: string;
+    dst: string;
+    rel: string;
+}>, profile: WeightProfile): Adjacency;
+/**
+ * Power iteration: v' = d·(Wᵀv + danglingMass·s) + (1−d)·s.
+ *
+ * Dangling mass refluxes to the SEEDS, not uniformly — a node with no out-edges returns the walk
+ * to the question rather than to the whole graph, and this is also what keeps a disconnected
+ * component at exactly zero. The vector always sums to 1 (asserted by test): a distribution that
+ * silently leaks mass would make cross-config comparisons meaningless.
+ */
+export declare function personalizedPageRank(adj: Adjacency, seeds: ReadonlyMap<string, number>, opts: PprOptions): Map<string, number>;
+export {};