@holmes-lab/holmes-kit 0.35.11 → 0.35.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,54 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
  <!-- @implements A-SPEC-209 -->
8
+ ## [0.35.13] - 2026-10-08
9
+
10
+ ### Changed
11
+
12
+ - **For a named change, `maintenance_analyze` also ranks by how often and how recently each file changes at
13
+ all** (A-SPEC-469.2). `impacts.rankedImpact` already fused the graph ranking with co-change (0.35.12); that
14
+ answers only for files that have changed together with the named one before. Work also concentrates on a few
15
+ files at a time, so the list is now fused once more with a seed-independent prior: every file's change frequency
16
+ over the same 400 commits, each commit counting `0.5^(age / 50)`, commits touching more than 30 files ignored.
17
+ A row may carry `changeFrequency`. Read in the same single `git log` as before. Measured through the product
18
+ path on 703 replayed changes made after both corpus pins — none seen by any earlier measurement — against the
19
+ previous build, history read strictly before each change. Recall and precision among the ten: on a second,
20
+ Python repository 0.485 -> 0.545 and 0.132 -> 0.157 (180 changes, +0.059 and +0.024, minimum detectable 0.050
21
+ and 0.019), replicated on 193 further changes (0.378 -> 0.540 and 0.076 -> 0.114, minimum detectable 0.065 and
22
+ 0.015); on this repository 0.521 -> 0.551 (180 changes, below the minimum detectable 0.036; precision 0.152 ->
23
+ 0.166 is detectable) and 0.419 -> 0.477 (150 changes, minimum detectable 0.052). **What this is not:** beside
24
+ the modelled human engineer this project measures itself against (recall 0.67-0.78, precision about 0.9, see
25
+ `docs/NORTH-STAR.md`), recall is still below the band and precision is about a sixth. Two arms that added
26
+ call-graph depth were measured alongside and rejected: neither beat the shipped list on any window. The
27
+ request-only list (no `changedFiles`) is unchanged.
28
+ - **`npm publish` refuses a release whose attest badge was not re-measured** (A-SPEC-669.1). When README.md
29
+ holds the `holmes-kit:attest` marker region and `.ax/badges/traced.svg` has not changed since the previous
30
+ release tag, the publish gate now refuses and names the command (`holmes-kit attest --badge --readme`). A
31
+ project whose README has no marker region is not asked. The publish playbook gains the re-measure step before
32
+ the release test lane, and its external-docs step now carries the badge file to the same repository as the
33
+ README and re-reads it. Observed 2026-10-07 on this repository: the badge still stated its 0.27.0 measurement
34
+ after more than ten releases, because no step asked for it.
35
+
36
+ ## [0.35.12] - 2026-10-07
37
+
38
+ ### Changed
39
+
40
+ - **For a named change, `maintenance_analyze` ranks what else moves by history as well as by the graph**
41
+ (A-SPEC-469.1). When a call passes `changedFiles`, `impacts.rankedImpact` now fuses the graph ranking with
42
+ recency-weighted co-change: which files were committed together with the changed ones in the last 400 commits,
43
+ each shared commit counting `0.5^(age / 50)`, commits touching more than 30 files ignored, the two lists merged
44
+ by reciprocal-rank fusion and the first ten kept. A row keeps its graph `score` (0 for a file the graph did not
45
+ rank) and carries `coChange` when history holds one. Measured through the product path on replayed changes, the
46
+ previous build against this one, history read strictly before each change: a file that really changed with the
47
+ named one is among the ten with recall 0.442 instead of 0.337 on a second, Python repository (79 changes, paired
48
+ +0.105, minimum detectable 0.091; precision +0.019), replicated on 93 further changes (+0.080, minimum
49
+ detectable 0.064); on this repository 0.502 instead of 0.465 (70 changes, +0.037, below the minimum detectable
50
+ 0.081 — no detectable change). One read-only `git log` per such call; without git history the list is the graph
51
+ ranking, as before. The list for a request alone (no `changedFiles`) and the ungraded closure the gates read are
52
+ unchanged. **Measured and not adopted:** walking the call graph one or two hops deeper reaches 5 to 14 points
53
+ more of the files that change together per hop, and still loses to the current list at ten on three of four
54
+ windows, because nothing ranks the larger set — depth is unchanged.
55
+
8
56
  ## [0.35.11] - 2026-10-07
9
57
 
10
58
  ### Fixed
package/README.md CHANGED
@@ -9,8 +9,8 @@
9
9
  <!-- holmes-kit:attest:begin -->
10
10
  ![traced files](.ax/badges/traced.svg)
11
11
 
12
- **386/386** source files (100%) trace to an approved spec · **629/680** approved A-SPECs (92.5%) are anchored from code.
13
- Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `holmes-kit attest --exclude dist-tools/,docs/goals/probes/,reference/`.
12
+ **436/436** source files (100%) trace to an approved spec · **751/814** approved A-SPECs (92.2%) are anchored from code.
13
+ Measured at `22ddb0979f45` (specs `sha256:5a9f37e1c454`) — reproduce with `holmes-kit attest --exclude dist-tools/,docs/goals/probes/,reference/`.
14
14
  <!-- holmes-kit:attest:end -->
15
15
 
16
16
  ---
@@ -23,6 +23,8 @@ Measured at `173b99650442` (specs `sha256:215f84d4e9f4`) — reproduce with `hol
23
23
 
24
24
  ### 🛡️ Currently Supported Features (Production Features)
25
25
 
26
+ - **The impact list also knows where work is concentrating, and a release cannot ship a stale badge** *(new in 0.35.13)*: for a named change, `impacts.rankedImpact` is fused once more with each file's recency-weighted change frequency (same single `git log`; rows may carry `changeFrequency`). On 703 replayed changes neither corpus had been measured on before, recall among the ten rose 0.485 → 0.545 and 0.378 → 0.540 on a second, Python repository (both above the minimum detectable effect) and 0.521 → 0.551 / 0.419 → 0.477 here; precision rose detectably on all four windows. Stated plainly: against the modelled human engineer this project aims at (`docs/NORTH-STAR.md` — recall 0.67–0.78, precision ≈ 0.9) recall is still below the band and precision about a sixth. Separately, `npm publish` now refuses when the README shows the attest badge and `.ax/badges/traced.svg` was not re-measured since the previous release.
27
+ - **What else moves when you change this file — ranked by history too** *(new in 0.35.12)*: when `maintenance_analyze` is given `changedFiles`, its graded impact list (`impacts.rankedImpact`) fuses the call-graph ranking with recency-weighted co-change from git history (files committed together with the changed ones, recent commits counting more). On replayed changes of a second, Python repository a file that really changed with the named one is among the ten shown with recall 0.44 instead of 0.34 (beyond the minimum detectable difference, and replicated on further changes); on this repository the difference is positive and not detectable. Walking the call graph deeper was measured at the same time and not adopted: it reaches more and ranks worse.
26
28
  - **The graph states what the code does, and intake answers in one call** *(new in 0.35.11)*: three corrections to what the traceability graph and `requirement_triage` say, each measured before it was built. `requirement_triage` ranked every requirement lineage on the first 64 distinct words of its text; it now reads the whole text (right lineage in the top five: 0.28 → 0.66 on this repository, 0.76 → 0.85 on a second one, both beyond the minimum detectable difference). A call with `persist: true` waits up to 20 seconds for the refresh it requested instead of returning `ambiguous` and asking to be repeated (`HOLMES_TRIAGE_WAIT_MS` sets the bound, 0 turns it off). `maintenance_analyze` lists `relevantTests` in relevance order — tests named after the changed file first — so the ten a bounded response shows are no longer the alphabetically first ten (a test the change also touched is among them with recall 0.48 instead of 0.21 here). TypeScript `calls` edges are bound by the compiler's symbol resolution — 21% of the name-bound edges linked a standard-library call such as `xs.map()` to an unrelated symbol — using only the files the scan already read plus TypeScript's bundled library; and an `@implements` anchor written in or directly above a function links the spec to that function instead of to every function of the file. **What is not claimed:** on replayed changes neither graph correction moved what `maintenance_analyze` returns beyond the minimum detectable difference; they change what the graph states, and the CHANGELOG records one measured cost.
27
29
  - **The protected store is recognised however a shell command spells it** *(new in 0.35.2 — security fix, upgrade recommended)*: through 0.35.1 a path into `.ax/specs`, `.ax/ledger`, `.ax/approvals` or `.ax/state` written directly after a shell expansion, a variable, or a character the shell removes at run time was not seen as protected, so a removal, move or overwrite of governance state could pass the gate. The store spelling now counts wherever it appears in a command, and an output redirect to a computed target is not a read. Reads still pass. A directory that merely ends in `.ax` and has a child named like the store's is judged as the store. Limit: a path assembled so the spelling never appears in the command text is outside this rule.
28
30
  - **The session-start banner in Codex** *(new in 0.35.8)*: with a runtime registry, `runtime-binding setup --activate-hooks codex` (or the `runtime_binding` tool) adds a SessionStart entry to the workspace's `.codex/hooks.json`, so a Codex session starts by being told which Holmes build governs it and whether autonomous approval is on — as Claude Code sessions are. It runs after you trust it in Codex's `/hooks`. Antigravity passes no hook output to the model, so nothing is wired there.
package/dist/.build-id CHANGED
@@ -1 +1 @@
1
- e768a6ae-muxcf7lv
1
+ 2e2d630f-muyc2rb3
@@ -34,7 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.createMaintenanceAnalysisHandlers = createMaintenanceAnalysisHandlers;
37
- // @implements A-SPEC-745, A-SPEC-741, A-SPEC-741.1, 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, A-SPEC-734, A-SPEC-278.3
37
+ // @implements A-SPEC-745, A-SPEC-469.1, A-SPEC-469.2, A-SPEC-741, A-SPEC-741.1, 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, A-SPEC-734, A-SPEC-278.3
38
38
  const fs = __importStar(require("node:fs"));
39
39
  const path = __importStar(require("node:path"));
40
40
  const node_child_process_1 = require("node:child_process");
@@ -47,6 +47,8 @@ const test_scope_1 = require("../../rtm/test-scope");
47
47
  const root_1 = require("../../project/root");
48
48
  const test_evidence_1 = require("../../review/test-evidence");
49
49
  const temporal_prior_1 = require("../../review/temporal-prior");
50
+ const co_change_1 = require("../../review/co-change");
51
+ const test_files_1 = require("../../cpg/test-files");
50
52
  const commit_text_1 = require("../../review/commit-text");
51
53
  const bundler_1 = require("../../context/bundler");
52
54
  const tier_1 = require("../../semantic/tier");
@@ -213,9 +215,28 @@ function createMaintenanceAnalysisHandlers(context) {
213
215
  commitTextBoost[hit.file] = hit.score / top;
214
216
  }
215
217
  catch { /* no history, no boost — the ranking falls back to lexical evidence alone */ }
218
+ // @implements A-SPEC-469.1 — for a NAMED change: what history says changed together with those
219
+ // files, recency-weighted. One bounded read-only `git log`; no history, no signal.
220
+ // @implements A-SPEC-469.2 — the same read also gives every path's recency-weighted change
221
+ // frequency, fused after co-change.
222
+ let coChange;
223
+ let changeFrequency;
224
+ const changedSources = (a.changedFiles ?? []).filter((file) => typeof file === 'string' && !(0, test_files_1.isTestFile)(file));
225
+ if (changedSources.length > 0) {
226
+ try {
227
+ const read = (0, co_change_1.changeHistoryFromGit)(root, 'HEAD', changedSources);
228
+ if (read.coChange.size > 0)
229
+ coChange = Object.fromEntries(read.coChange);
230
+ if (read.changeFrequency.size > 0)
231
+ changeFrequency = Object.fromEntries(read.changeFrequency);
232
+ }
233
+ catch { /* the graph ranking alone */ }
234
+ }
216
235
  const analyzeWith = (defUse) => (0, maintenance_analyze_1.analyzeMaintenance)({
217
236
  semantic,
218
237
  ...common,
238
+ ...(coChange !== undefined ? { coChange } : {}),
239
+ ...(changeFrequency !== undefined ? { changeFrequency } : {}),
219
240
  coverage: { ...common.coverage, historyStatus },
220
241
  history,
221
242
  changePrior,
@@ -102,6 +102,20 @@ export interface MaintenanceAnalysisInput {
102
102
  * property that lets the replay benchmark run it against a materialised tree.
103
103
  */
104
104
  changePrior?: Record<string, number>;
105
+ /**
106
+ * @implements A-SPEC-469.1
107
+ * Recency-weighted co-change of each path with the CHANGED files (`review/co-change.ts`), read by
108
+ * the caller from history up to the analysed state. Used only when `changedFiles` names a file, and
109
+ * only to rank `impacts.rankedImpact`. Absent: that list is the graph ranking alone.
110
+ */
111
+ coChange?: Record<string, number>;
112
+ /**
113
+ * @implements A-SPEC-469.2
114
+ * Recency-weighted change frequency of each path, whatever it changed with (`review/co-change.ts`),
115
+ * read by the caller in the same history read. Used only when `changedFiles` names a file, and only
116
+ * to rank `impacts.rankedImpact`, after co-change.
117
+ */
118
+ changeFrequency?: Record<string, number>;
105
119
  /**
106
120
  * @implements A-SPEC-388
107
121
  * Per-file multipliers from how much each file's COMMIT PROSE talks like the request, normalised
@@ -311,10 +325,13 @@ export interface MaintenanceAnalysis {
311
325
  * (HOLMES), the graded top-10's 0.5713 / 0.1611, and both metrics won on all three corpora,
312
326
  * which is the bar that A-SPEC-309/313 set and their expansions failed.
313
327
  */
328
+ /** @implements A-SPEC-469.1 — `coChange`: the row's recency-weighted co-change with the changed files, when it has one. */
314
329
  rankedImpact: Array<{
315
330
  file: string;
316
331
  score: number;
317
332
  semCos?: number;
333
+ coChange?: number;
334
+ changeFrequency?: number;
318
335
  }>;
319
336
  /**
320
337
  * @implements A-SPEC-289
@@ -5,7 +5,7 @@ exports.testNameMatches = testNameMatches;
5
5
  exports.unquoteGitPath = unquoteGitPath;
6
6
  exports.analyzeMaintenance = analyzeMaintenance;
7
7
  exports.boundAnalysis = boundAnalysis;
8
- // @implements A-SPEC-745, A-SPEC-745.1, A-SPEC-741, A-SPEC-741.1, A-SPEC-740, A-SPEC-725, A-SPEC-310
8
+ // @implements A-SPEC-745, A-SPEC-745.1, A-SPEC-469.1, A-SPEC-469.2, A-SPEC-741, A-SPEC-741.1, A-SPEC-740, A-SPEC-725, A-SPEC-310
9
9
  // @implements A-SPEC-295
10
10
  // @implements A-SPEC-294
11
11
  // @implements A-SPEC-293
@@ -30,6 +30,7 @@ const unreadable_paths_1 = require("../semantic/unreadable-paths");
30
30
  const dense_retrieval_1 = require("../review/dense-retrieval");
31
31
  const test_scope_1 = require("../rtm/test-scope");
32
32
  const test_files_1 = require("../cpg/test-files");
33
+ const co_change_1 = require("../review/co-change");
33
34
  const scope_1 = require("../review/scope");
34
35
  // @implements A-SPEC-469 — the SAME code path the S-484 measurement ran; identity is the reason
35
36
  // the measured numbers transfer to the shipped surface.
@@ -693,7 +694,54 @@ function analyzeMaintenance(input) {
693
694
  const rankedImpactSeeds = new Map(rankedImpactSeedSymbols
694
695
  .flatMap((qualifiedName) => input.graph.codeNodeIds(qualifiedName))
695
696
  .map((id) => [id, 1]));
696
- const rankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(input.graph.dumpCanonical()), rankedImpactSeeds, new Set(input.changedFiles ?? []), assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
697
+ const graphRankedImpact = (0, assoc_arm_1.pprImpactRanked)((0, assoc_arm_1.graphViewOf)(input.graph.dumpCanonical()), rankedImpactSeeds, new Set(input.changedFiles ?? []), assoc_arm_1.RANKED_IMPACT_K, assoc_arm_1.RANKED_IMPACT_CONFIG);
698
+ // @implements A-SPEC-469.1 — for a NAMED change, fuse the graph ranking with what history says
699
+ // changed together with those files (recency-weighted, supplied by the caller: no I/O here).
700
+ // Reciprocal-rank fusion, the first ten kept. A row keeps its graph score (0 when the graph did not
701
+ // rank the file) and carries its co-change weight. Only scanned, unchanged files can enter — the
702
+ // scan holds no test files. Measured: recall@10 0.337 -> 0.442 on the second corpus, replicated;
703
+ // the request-only list was not measured and is left as it was.
704
+ const coChangeRankedImpact = (() => {
705
+ const weights = input.coChange;
706
+ const changed = new Set(input.changedFiles ?? []);
707
+ if (weights === undefined || changed.size === 0)
708
+ return graphRankedImpact;
709
+ const scannedPaths = new Set(scanned.map((file) => file.sourcePath));
710
+ const coList = Object.entries(weights)
711
+ .filter(([file, weight]) => weight > 0 && scannedPaths.has(file) && !changed.has(file))
712
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
713
+ .map(([file]) => file);
714
+ if (coList.length === 0)
715
+ return graphRankedImpact;
716
+ const graphRow = new Map(graphRankedImpact.map((row) => [row.file, row]));
717
+ return (0, co_change_1.fuseRanked)(graphRankedImpact.map((row) => row.file), coList).slice(0, assoc_arm_1.RANKED_IMPACT_K).map(({ file }) => ({
718
+ ...(graphRow.get(file) ?? { file, score: 0 }),
719
+ ...(weights[file] !== undefined && weights[file] > 0 ? { coChange: weights[file] } : {}),
720
+ }));
721
+ })();
722
+ // @implements A-SPEC-469.2 — then fuse that list (already cut to ten) with a seed-independent prior:
723
+ // how often and how recently each file has changed at all. Same rules of entry — scanned, unchanged.
724
+ // Measured on cases after both pins: recall@10 0.485 -> 0.545 on the second corpus, replicated
725
+ // (0.378 -> 0.540); +0.031 and +0.058 here. The request-only list is left as it was: a frequency
726
+ // term was measured harmful there (A-SPEC-378).
727
+ const rankedImpact = (() => {
728
+ const weights = input.changeFrequency;
729
+ const changed = new Set(input.changedFiles ?? []);
730
+ if (weights === undefined || changed.size === 0)
731
+ return coChangeRankedImpact;
732
+ const scannedPaths = new Set(scanned.map((file) => file.sourcePath));
733
+ const frequencyList = Object.entries(weights)
734
+ .filter(([file, weight]) => weight > 0 && scannedPaths.has(file) && !changed.has(file))
735
+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
736
+ .map(([file]) => file);
737
+ if (frequencyList.length === 0)
738
+ return coChangeRankedImpact;
739
+ const earlierRow = new Map(coChangeRankedImpact.map((row) => [row.file, row]));
740
+ return (0, co_change_1.fuseRanked)(coChangeRankedImpact.map((row) => row.file), frequencyList).slice(0, assoc_arm_1.RANKED_IMPACT_K).map(({ file }) => ({
741
+ ...(earlierRow.get(file) ?? { file, score: 0 }),
742
+ ...(weights[file] !== undefined && weights[file] > 0 ? { changeFrequency: weights[file] } : {}),
743
+ }));
744
+ })();
697
745
  // @implements A-SPEC-486 — the same additive verdict on the graded impact surface: a cached
698
746
  // cosine per row, no row added or removed, score untouched.
699
747
  {
@@ -0,0 +1,47 @@
1
+ export interface CoChangeOptions {
2
+ /** Commits read, newest first. */
3
+ limit: number;
4
+ /** A commit touching more files than this says nothing about any pair (a mass rename, a release). */
5
+ maxCommitFiles: number;
6
+ /** Age, in commits, at which a shared commit counts half. */
7
+ halfLife: number;
8
+ }
9
+ /** The values measured. Not tuned afterwards: a change here is a new measurement. */
10
+ export declare const CO_CHANGE_DEFAULTS: CoChangeOptions;
11
+ /**
12
+ * Recency-weighted co-change of every path with the seeds, from commits listed newest first.
13
+ * A commit that touches a seed adds `0.5^(age / halfLife)` to every other path it touches; `age` is
14
+ * the commit's position in the list. Seeds themselves are never returned.
15
+ */
16
+ export declare function coChangeWeights(commits: ReadonlyArray<readonly string[]>, seeds: readonly string[], opts?: CoChangeOptions): Map<string, number>;
17
+ /**
18
+ * The same, read from git: the `limit` non-merge commits reachable from `before`, itself included and
19
+ * nothing after it. Unreadable history is an empty answer, never an error — the caller ranks without
20
+ * the signal.
21
+ */
22
+ export declare function coChangeFromGit(root: string, before: string, seeds: readonly string[], opts?: CoChangeOptions): Map<string, number>;
23
+ /**
24
+ * Recency-weighted change frequency of every path, whatever it changed with: a commit of at most
25
+ * `maxCommitFiles` files adds `0.5^(age / halfLife)` to each path in it. Work concentrates — the
26
+ * files being changed again and again are likely to join the next change too. Measured 2026-10-07
27
+ * on cases no earlier measurement had seen, fused after co-change: recall@10 0.485 -> 0.545 on the
28
+ * second corpus (n=180, MDE80 0.050), replicated (0.378 -> 0.540, n=193); +0.031 and +0.058 here.
29
+ */
30
+ export declare function changeFrequencyWeights(commits: ReadonlyArray<readonly string[]>, opts?: CoChangeOptions): Map<string, number>;
31
+ /**
32
+ * @implements A-SPEC-469.2
33
+ * Both history signals from ONE `git log`: co-change with the seeds, and every path's change
34
+ * frequency. Unreadable history is two empty maps.
35
+ */
36
+ export declare function changeHistoryFromGit(root: string, before: string, seeds: readonly string[], opts?: CoChangeOptions): {
37
+ coChange: Map<string, number>;
38
+ changeFrequency: Map<string, number>;
39
+ };
40
+ /**
41
+ * Reciprocal-rank fusion of two ranked lists (k = 60, the constant of the original paper, untuned):
42
+ * a file's score is the sum of 1 / (k + rank) over the lists that hold it. Ties keep path order.
43
+ */
44
+ export declare function fuseRanked(a: readonly string[], b: readonly string[], k?: number): Array<{
45
+ file: string;
46
+ score: number;
47
+ }>;
@@ -0,0 +1,105 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CO_CHANGE_DEFAULTS = void 0;
4
+ exports.coChangeWeights = coChangeWeights;
5
+ exports.coChangeFromGit = coChangeFromGit;
6
+ exports.changeFrequencyWeights = changeFrequencyWeights;
7
+ exports.changeHistoryFromGit = changeHistoryFromGit;
8
+ exports.fuseRanked = fuseRanked;
9
+ // @implements A-SPEC-469.1, A-SPEC-469.2
10
+ // Which files have changed together with these, how often, and how recently? Evolutionary coupling is
11
+ // the oldest evidence there is for "what else moves when I change this" (ROSE, 2004; combined with
12
+ // retrieval in Kagdi et al., 2010), and this repository had tried it once: twelve cases, as a
13
+ // threshold admitting candidates for a request. Measured 2026-10-07 as a RANKING for a named change,
14
+ // fused with the graph ranking: recall@10 0.337 -> 0.442 on the second corpus (n=79, MDE80 0.091),
15
+ // replicated on 93 further cases (+0.080, MDE80 0.064); no detectable loss on this repository.
16
+ const node_child_process_1 = require("node:child_process");
17
+ const bounded_io_1 = require("../project/bounded-io");
18
+ /** The values measured. Not tuned afterwards: a change here is a new measurement. */
19
+ exports.CO_CHANGE_DEFAULTS = { limit: 400, maxCommitFiles: 30, halfLife: 50 };
20
+ /**
21
+ * Recency-weighted co-change of every path with the seeds, from commits listed newest first.
22
+ * A commit that touches a seed adds `0.5^(age / halfLife)` to every other path it touches; `age` is
23
+ * the commit's position in the list. Seeds themselves are never returned.
24
+ */
25
+ function coChangeWeights(commits, seeds, opts = exports.CO_CHANGE_DEFAULTS) {
26
+ const seedSet = new Set(seeds);
27
+ const weights = new Map();
28
+ if (seedSet.size === 0)
29
+ return weights;
30
+ commits.slice(0, opts.limit).forEach((files, age) => {
31
+ if (files.length > opts.maxCommitFiles || !files.some((file) => seedSet.has(file)))
32
+ return;
33
+ const weight = Math.pow(0.5, age / opts.halfLife);
34
+ for (const file of new Set(files))
35
+ if (!seedSet.has(file))
36
+ weights.set(file, (weights.get(file) ?? 0) + weight);
37
+ });
38
+ return weights;
39
+ }
40
+ /**
41
+ * The same, read from git: the `limit` non-merge commits reachable from `before`, itself included and
42
+ * nothing after it. Unreadable history is an empty answer, never an error — the caller ranks without
43
+ * the signal.
44
+ */
45
+ function coChangeFromGit(root, before, seeds, opts = exports.CO_CHANGE_DEFAULTS) {
46
+ if (seeds.length === 0)
47
+ return new Map();
48
+ const commits = commitsFromGit(root, before, opts);
49
+ return commits === null ? new Map() : coChangeWeights(commits, seeds, opts);
50
+ }
51
+ /** The `limit` non-merge commits reachable from `before`, newest first, each as its paths; null when unreadable. */
52
+ function commitsFromGit(root, before, opts) {
53
+ let raw;
54
+ try {
55
+ // `core.quotePath=false`: non-ASCII paths come out as themselves. A path holding a quote, a tab or
56
+ // a newline is still quoted by git; it then matches no scanned path and simply carries no weight.
57
+ raw = (0, node_child_process_1.execFileSync)('git', ['-C', root, '-c', 'core.quotePath=false', 'log', '--no-merges', `-${opts.limit}`, '--format=%x1e', '--name-only', before], { timeout: bounded_io_1.GIT_TIMEOUT_MS, encoding: 'utf8', maxBuffer: bounded_io_1.GIT_MAX_BUFFER, stdio: ['ignore', 'pipe', 'ignore'] });
58
+ }
59
+ catch {
60
+ return null;
61
+ }
62
+ return raw.split('\x1e').slice(1)
63
+ .map((block) => block.split('\n').map((line) => line.trim()).filter((line) => line !== ''));
64
+ }
65
+ // @implements A-SPEC-469.2
66
+ /**
67
+ * Recency-weighted change frequency of every path, whatever it changed with: a commit of at most
68
+ * `maxCommitFiles` files adds `0.5^(age / halfLife)` to each path in it. Work concentrates — the
69
+ * files being changed again and again are likely to join the next change too. Measured 2026-10-07
70
+ * on cases no earlier measurement had seen, fused after co-change: recall@10 0.485 -> 0.545 on the
71
+ * second corpus (n=180, MDE80 0.050), replicated (0.378 -> 0.540, n=193); +0.031 and +0.058 here.
72
+ */
73
+ function changeFrequencyWeights(commits, opts = exports.CO_CHANGE_DEFAULTS) {
74
+ const weights = new Map();
75
+ commits.slice(0, opts.limit).forEach((files, age) => {
76
+ if (files.length > opts.maxCommitFiles)
77
+ return;
78
+ const weight = Math.pow(0.5, age / opts.halfLife);
79
+ for (const file of new Set(files))
80
+ weights.set(file, (weights.get(file) ?? 0) + weight);
81
+ });
82
+ return weights;
83
+ }
84
+ /**
85
+ * @implements A-SPEC-469.2
86
+ * Both history signals from ONE `git log`: co-change with the seeds, and every path's change
87
+ * frequency. Unreadable history is two empty maps.
88
+ */
89
+ function changeHistoryFromGit(root, before, seeds, opts = exports.CO_CHANGE_DEFAULTS) {
90
+ const commits = commitsFromGit(root, before, opts);
91
+ if (commits === null)
92
+ return { coChange: new Map(), changeFrequency: new Map() };
93
+ return { coChange: coChangeWeights(commits, seeds, opts), changeFrequency: changeFrequencyWeights(commits, opts) };
94
+ }
95
+ /**
96
+ * Reciprocal-rank fusion of two ranked lists (k = 60, the constant of the original paper, untuned):
97
+ * a file's score is the sum of 1 / (k + rank) over the lists that hold it. Ties keep path order.
98
+ */
99
+ function fuseRanked(a, b, k = 60) {
100
+ const score = new Map();
101
+ for (const list of [a, b])
102
+ list.forEach((file, i) => score.set(file, (score.get(file) ?? 0) + 1 / (k + i + 1)));
103
+ return [...score.entries()].map(([file, s]) => ({ file, score: s }))
104
+ .sort((x, y) => y.score - x.score || x.file.localeCompare(y.file));
105
+ }
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.uncitedDiffs = uncitedDiffs;
37
37
  exports.runReplay = runReplay;
38
38
  exports.semanticCaseRanking = semanticCaseRanking;
39
- // @implements A-SPEC-346, A-SPEC-734, A-SPEC-758
39
+ // @implements A-SPEC-346, A-SPEC-734, A-SPEC-758, A-SPEC-469.1, A-SPEC-469.2
40
40
  // @implements A-SPEC-347
41
41
  // @implements A-SPEC-348
42
42
  // @implements A-SPEC-349
@@ -81,6 +81,7 @@ const dense_retrieval_1 = require("./dense-retrieval");
81
81
  // @implements A-SPEC-472 — the three-arm iteration experiment (static / re-seed / judged).
82
82
  const explore_1 = require("../assoc/explore");
83
83
  const temporal_prior_1 = require("./temporal-prior");
84
+ const co_change_1 = require("./co-change");
84
85
  const commit_text_1 = require("./commit-text");
85
86
  const bounded_io_1 = require("../project/bounded-io");
86
87
  // @implements A-SPEC-756.1 — the anchor-binding arms: file-level, place, place plus history.
@@ -716,9 +717,17 @@ async function runReplay(corpus, limit, opts = {}) {
716
717
  const seed = [...c.files].sort()[0];
717
718
  const expected = c.files.filter((f) => f !== seed);
718
719
  if (expected.length > 0) {
720
+ // @implements A-SPEC-469.1 — what the product's handler passes for a named change: co-change
721
+ // with the seed, read up to the PARENT and never the answer commit.
722
+ // @implements A-SPEC-469.2 — and, from the same read, every path's change frequency.
723
+ const historyRead = (0, co_change_1.changeHistoryFromGit)(corpus.root, parent, [seed]);
724
+ const coChange = {
725
+ ...(historyRead.coChange.size > 0 ? { coChange: Object.fromEntries(historyRead.coChange) } : {}),
726
+ ...(historyRead.changeFrequency.size > 0 ? { changeFrequency: Object.fromEntries(historyRead.changeFrequency) } : {}),
727
+ };
719
728
  const run = (0, maintenance_analyze_1.analyzeMaintenance)({
720
729
  request: c.subject, scanned, specs, graph, testAnchors: anchors, history: [],
721
- changedFiles: [seed], changePrior, commitTextBoost,
730
+ changedFiles: [seed], changePrior, commitTextBoost, ...coChange,
722
731
  basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
723
732
  coverage: { scannedFiles: scanned.length, skippedFiles: [], unsupportedLanguages: [] },
724
733
  });
@@ -736,7 +745,7 @@ async function runReplay(corpus, limit, opts = {}) {
736
745
  emitCall('compiler', run);
737
746
  onNameGraph((byName, g) => emitCall('name', (0, maintenance_analyze_1.analyzeMaintenance)({
738
747
  request: c.subject, scanned: byName, specs, graph: g, testAnchors: anchors, history: [],
739
- changedFiles: [seed], changePrior, commitTextBoost,
748
+ changedFiles: [seed], changePrior, commitTextBoost, ...coChange,
740
749
  basis: { head: parent, loadedBuild: 'b', diskBuild: 'b', specFingerprint: 'fp' },
741
750
  coverage: { scannedFiles: byName.length, skippedFiles: [], unsupportedLanguages: [] },
742
751
  })));
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "//": "@implements A-SPEC-209",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.35.11",
4
+ "version": "0.35.13",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",
@@ -58,6 +58,27 @@ README 에 현재형으로 남은 사고, 그리고 **0.16.0 — 신기능 3건
58
58
 
59
59
  ---
60
60
 
61
+ ### 2.55단계: 추적 배지 재측정 (Attest Badge Currency) — 숫자는 잰 날의 것이다
62
+
63
+ README 의 추적 배지(`.ax/badges/traced.svg`)와 그 아래 측정 문구는 **잰 커밋의 사실**이다. 다시 재지
64
+ 않으면 옛 숫자가 현재형으로 남는다. (사고 이력: 0.27.0 에서 한 번 잰 배지가 **열 번 넘는 릴리스
65
+ 동안** 그대로였고, 저장소 첫 화면이 그 파일을 보여 주고 있었다 — 어느 단계도 요구하지 않았기 때문이다.)
66
+
67
+ 1. README 에 `holmes-kit:attest` 마커 구간이 있는지 본다. **마커 구간이 없으면 SKIP** — 이 프로젝트는
68
+ 배지를 쓰지 않는다고 명시하고 다음으로 간다.
69
+ 2. 있으면 다시 잰다: `holmes-kit attest --badge --readme` (제외 목록 `--exclude` 는 README 측정 문구의
70
+ 재현 명령에 적힌 그대로 — 목록을 바꾸면 다른 측정이다).
71
+ 3. 바뀐 두 파일(`README.md`, `.ax/badges/traced.svg`)을 커밋한다. **릴리스 시험 lane 을 기록하기 전에**
72
+ 한다 — 배지는 자기보다 앞선 커밋을 가리키는 것이 정상이다.
73
+ 4. 숫자가 내려갔으면 그대로 싣는다. 배지는 주장이 아니라 측정이다.
74
+
75
+ > [!CAUTION]
76
+ > 이 단계는 기계가 지킨다: README 에 마커 구간이 있는데 배지 파일이 직전 릴리스 태그 이후 바뀌지
77
+ > 않았으면 `npm publish` 가 거부된다(A-SPEC-669.1). 게이트는 파일이 움직였는지만 본다 — 숫자가
78
+ > 맞는지는 2 의 재측정이 보증한다.
79
+
80
+ ---
81
+
61
82
  ### 2.6단계: 해결된 현장 보고 기록 (Resolved Field Reports) — 소비자에게 닫히는 고리
62
83
 
63
84
  소비자가 `holmes-kit report` 로 보고한 결함을 이번 릴리스가 고쳤다면, 그 **fingerprint 를
@@ -131,6 +152,10 @@ GitHub 리모트가 없어(origin 이 로컬 gitea) 0.16.0·0.17.0·0.18.0 **세
131
152
  3. **동기화**: 로컬 `README.md` 를 `gh api --method PUT` 으로 올린다(`sha` 는 2 에서 읽은 값).
132
153
  4. **재조회 검증**: 다시 읽어 로컬과 일치하는지 확인한다. **쓴 것과 남은 것은 다를 수 있다** —
133
154
  검증 없는 "갱신했다"는 주장이지 사실이 아니다.
155
+ 4a. **추적 배지도 같은 표면이다**: 로컬에 `.ax/badges/traced.svg` 가 있으면 README 와 **같은 대상
156
+ `<owner>/<repo>`** 의 같은 경로를 2~4 와 똑같이 다룬다 — 원격을 먼저 읽어 차이를 보고하고, 올리고,
157
+ **배지도 다시 읽어** 로컬과 일치하는지 확인한다. README 만 올리면 원격 README 는 새 숫자를 말하고
158
+ 그림은 옛 숫자를 보여 준다. 배지 파일이 없으면 **SKIP(사유: 배지를 쓰지 않는 프로젝트)**.
134
159
  5. **profile README drift 감지 (자동 수정 금지)**: `<owner>/.github` 의 `profile/README.md` 를 읽어
135
160
  `profileDriftFindings` 로 주장-현실 불일치를 **보고만** 한다. 포지셔닝 문안은 오너 결정이며
136
161
  릴리스 절차가 정할 것이 아니다.