@holmes-lab/holmes-kit 0.28.0 → 0.29.0

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.
Files changed (35) hide show
  1. package/CHANGELOG.md +38 -0
  2. package/README.md +19 -17
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/doctor.js +25 -1
  5. package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
  6. package/dist/holmes/cpg/ast-mutation.js +4 -2
  7. package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
  8. package/dist/holmes/cpg/foundation/cfg.js +27 -1
  9. package/dist/holmes/mcp/handlers/graph-operations.d.ts +7 -0
  10. package/dist/holmes/mcp/handlers/graph-operations.js +25 -1
  11. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +116 -0
  12. package/dist/holmes/mcp/handlers/requirement-triage.js +185 -0
  13. package/dist/holmes/mcp/handlers.d.ts +107 -0
  14. package/dist/holmes/mcp/handlers.js +11 -1
  15. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +11 -0
  16. package/dist/holmes/mcp/requirement-triage-evidence.js +79 -0
  17. package/dist/holmes/mcp/tool-schemas.js +14 -1
  18. package/dist/holmes/review/condition-hunk-replay.d.ts +33 -0
  19. package/dist/holmes/review/condition-hunk-replay.js +112 -0
  20. package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
  21. package/dist/holmes/review/condition-hunk-resolution.js +207 -0
  22. package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
  23. package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
  24. package/dist/holmes/review/requirement-triage.d.ts +61 -0
  25. package/dist/holmes/review/requirement-triage.js +143 -0
  26. package/dist/holmes/semantic/local-model.d.ts +3 -3
  27. package/dist/holmes/semantic/local-model.js +10 -12
  28. package/dist/holmes/semantic/model-cache.d.ts +15 -6
  29. package/dist/holmes/semantic/model-cache.js +77 -21
  30. package/dist/holmes/semantic/tier.d.ts +5 -1
  31. package/dist/holmes/semantic/tier.js +7 -6
  32. package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
  33. package/dist/holmes/semantic/vector-coverage.js +37 -0
  34. package/docs/install-guide.md +19 -24
  35. package/package.json +1 -1
@@ -33,35 +33,91 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.LOCAL_REVISION = exports.LOCAL_MODEL = void 0;
36
37
  exports.modelCacheDir = modelCacheDir;
38
+ exports.modelCacheFingerprint = modelCacheFingerprint;
39
+ exports.readLocalModelReadiness = readLocalModelReadiness;
40
+ exports.writeVerifiedModelReceipt = writeVerifiedModelReceipt;
37
41
  exports.modelCacheReady = modelCacheReady;
38
- // @implements A-SPEC-594
39
- /**
40
- * Where the local model's assets live, and whether they are actually there.
41
- *
42
- * A leaf on purpose: `tier.ts` must consult readiness, and `local-model.ts` already imports
43
- * `tier.ts`, so putting this in either one closes an import cycle. Nothing here imports
44
- * anything of ours.
45
- */
42
+ // @implements A-SPEC-594, A-SPEC-712
43
+ /** Shared local-model cache and its lightweight verified-readiness receipt. */
44
+ const crypto = __importStar(require("node:crypto"));
45
+ const fs = __importStar(require("node:fs"));
46
46
  const os = __importStar(require("node:os"));
47
47
  const path = __importStar(require("node:path"));
48
- const fs = __importStar(require("node:fs"));
48
+ exports.LOCAL_MODEL = 'Xenova/bge-m3';
49
+ exports.LOCAL_REVISION = '4de13258303883538bd53b696b452bf8099f0858';
50
+ const RECEIPT_FILE = '.holmes-bge-m3-readiness.json';
51
+ const RECEIPT_SCHEMA = 'holmes-local-model-readiness/1';
49
52
  function modelCacheDir(env = process.env, home = os.homedir()) {
50
53
  return path.resolve(env.HOLMES_MODEL_CACHE || path.join(home, '.holmes', 'models'));
51
54
  }
52
- /**
53
- * Ready means the cache holds SOMETHING. An interrupted download leaves the directory created
54
- * and empty, and reading that as ready is the whole failure mode this predicate exists to stop.
55
- * Proof of a working model is `semantic-check`'s actual inference — deliberately not here, because
56
- * doctor calls this on every run and must stay cheap and offline.
57
- */
58
- function modelCacheReady(cacheDir = modelCacheDir()) {
59
- if (cacheDir === '')
60
- return false;
55
+ function assetEntries(cacheDir) {
56
+ try {
57
+ const rows = [];
58
+ const visit = (dir, prefix) => {
59
+ for (const name of fs.readdirSync(dir).sort()) {
60
+ if (prefix === '' && name === RECEIPT_FILE)
61
+ continue;
62
+ const absolute = path.join(dir, name), relative = prefix ? `${prefix}/${name}` : name, stat = fs.statSync(absolute);
63
+ if (stat.isDirectory())
64
+ visit(absolute, relative);
65
+ else if (stat.isFile())
66
+ rows.push(`${relative}:${stat.size}:${Math.floor(stat.mtimeMs)}`);
67
+ }
68
+ };
69
+ visit(cacheDir, '');
70
+ return rows;
71
+ }
72
+ catch {
73
+ return null;
74
+ }
75
+ }
76
+ /** A metadata fingerprint cheap enough for offline tier resolution. */
77
+ function modelCacheFingerprint(cacheDir = modelCacheDir()) {
78
+ const entries = assetEntries(cacheDir);
79
+ return entries === null || entries.length === 0 ? null
80
+ : `sha256:${crypto.createHash('sha256').update(entries.join('\n')).digest('hex')}`;
81
+ }
82
+ const receiptPath = (cacheDir) => path.join(cacheDir, RECEIPT_FILE);
83
+ /** Missing or malformed proof is never promoted to readiness. */
84
+ function readLocalModelReadiness(cacheDir = modelCacheDir()) {
85
+ const fingerprint = modelCacheFingerprint(cacheDir);
86
+ if (fingerprint === null)
87
+ return { ready: false, state: 'missing-cache', recovery: 'Run holmes-kit semantic-setup to download and verify BGE-M3.' };
88
+ let receipt;
89
+ try {
90
+ receipt = JSON.parse(fs.readFileSync(receiptPath(cacheDir), 'utf8'));
91
+ }
92
+ catch {
93
+ return { ready: false, state: 'unverified-cache', recovery: 'Run holmes-kit semantic-setup to verify the existing BGE-M3 cache offline.' };
94
+ }
95
+ if (receipt.schema !== RECEIPT_SCHEMA || receipt.model !== exports.LOCAL_MODEL || receipt.revision !== exports.LOCAL_REVISION || typeof receipt.fingerprint !== 'string') {
96
+ return { ready: false, state: 'invalid-receipt', recovery: 'Run holmes-kit semantic-setup to replace the invalid BGE-M3 readiness receipt.' };
97
+ }
98
+ if (receipt.fingerprint !== fingerprint)
99
+ return { ready: false, state: 'stale-receipt', recovery: 'Run holmes-kit semantic-setup to re-verify the changed BGE-M3 cache.' };
100
+ return { ready: true, state: 'verified', recovery: '' };
101
+ }
102
+ /** Only successful actual inference may write the same-directory atomic receipt. */
103
+ function writeVerifiedModelReceipt(cacheDir = modelCacheDir()) {
104
+ const fingerprint = modelCacheFingerprint(cacheDir);
105
+ if (fingerprint === null)
106
+ return { ready: false, state: 'missing-cache', recovery: 'Run holmes-kit semantic-setup to download and verify BGE-M3.' };
107
+ const target = receiptPath(cacheDir), temp = `${target}.${process.pid}.tmp`;
61
108
  try {
62
- return fs.readdirSync(cacheDir).length > 0;
109
+ fs.mkdirSync(cacheDir, { recursive: true });
110
+ fs.writeFileSync(temp, JSON.stringify({ schema: RECEIPT_SCHEMA, model: exports.LOCAL_MODEL, revision: exports.LOCAL_REVISION, fingerprint }));
111
+ fs.renameSync(temp, target);
63
112
  }
64
113
  catch {
65
- return false;
66
- } // absent, unreadable, not a directory — none of them are ready
114
+ try {
115
+ fs.rmSync(temp, { force: true });
116
+ }
117
+ catch { /* best effort */ }
118
+ return { ready: false, state: 'invalid-receipt', recovery: 'Check HOLMES_MODEL_CACHE permissions, then run holmes-kit semantic-setup.' };
119
+ }
120
+ return readLocalModelReadiness(cacheDir);
67
121
  }
122
+ /** Compatibility boolean: actual verified inference, never directory presence. */
123
+ function modelCacheReady(cacheDir = modelCacheDir()) { return readLocalModelReadiness(cacheDir).ready; }
@@ -11,8 +11,9 @@
11
11
  * network; presence signals only, so doctor can call it offline.
12
12
  */
13
13
  import { type CredentialOpts, type KeySource } from './credentials';
14
+ import { LOCAL_MODEL, type LocalModelReadiness } from './model-cache';
14
15
  /** The local tier's model. CLS-pooled — see POOLING_OF. */
15
- export declare const LOCAL_MODEL = "Xenova/bge-m3";
16
+ export { LOCAL_MODEL };
16
17
  /** The opt-in cloud tier's model (S-491 four-arm winner). */
17
18
  export declare const CLOUD_MODEL = "gemini-embedding-001";
18
19
  export interface SemanticTier {
@@ -28,6 +29,8 @@ export interface SemanticTier {
28
29
  * because reporting this one as 'local' claims a recall the tier cannot deliver.
29
30
  */
30
31
  localRuntimePresent?: boolean;
32
+ /** Why local BGE-M3 was not activated, when readiness was observed. */
33
+ localState?: LocalModelReadiness['state'];
31
34
  }
32
35
  /**
33
36
  * Which pooling a model's dense head expects. bge-m3 is CLS-pooled: mean-pooling it was the
@@ -40,5 +43,6 @@ export declare function resolveSemanticTier(opts?: {
40
43
  env?: NodeJS.ProcessEnv;
41
44
  hasLocalModule?: boolean;
42
45
  hasLocalModel?: boolean;
46
+ localReadiness?: LocalModelReadiness;
43
47
  credentials?: CredentialOpts;
44
48
  }): SemanticTier;
@@ -1,5 +1,5 @@
1
1
  "use strict";
2
- // @implements A-SPEC-476
2
+ // @implements A-SPEC-476, A-SPEC-712
3
3
  /**
4
4
  * The semantic layer's tier structure — the owner's two-lever design made a contract:
5
5
  * maximize what the harness can do WITHOUT egress (a local model), and let an explicit opt-in
@@ -18,8 +18,7 @@ exports.POOLING_OF = POOLING_OF;
18
18
  exports.resolveSemanticTier = resolveSemanticTier;
19
19
  const credentials_1 = require("./credentials");
20
20
  const model_cache_1 = require("./model-cache");
21
- /** The local tier's model. CLS-pooled — see POOLING_OF. */
22
- exports.LOCAL_MODEL = 'Xenova/bge-m3';
21
+ Object.defineProperty(exports, "LOCAL_MODEL", { enumerable: true, get: function () { return model_cache_1.LOCAL_MODEL; } });
23
22
  /** The opt-in cloud tier's model (S-491 four-arm winner). */
24
23
  exports.CLOUD_MODEL = 'gemini-embedding-001';
25
24
  /**
@@ -53,8 +52,10 @@ function resolveSemanticTier(opts = {}) {
53
52
  // discriminating; a resolvable runtime with no model produces no embedding at all. Wiring
54
53
  // presence is not readiness.
55
54
  const hasModule = opts.hasLocalModule ?? localModulePresent();
56
- const hasModel = opts.hasLocalModel ?? (0, model_cache_1.modelCacheReady)();
55
+ const observed = opts.localReadiness ?? (opts.hasLocalModel === undefined ? (0, model_cache_1.readLocalModelReadiness)() : undefined);
56
+ const hasModel = opts.hasLocalModel ?? observed?.ready ?? false;
57
57
  if (hasModule && hasModel)
58
- return { tier: 'local', model: exports.LOCAL_MODEL, egress: false };
59
- return { tier: 'none', egress: false, ...(hasModule ? { localRuntimePresent: true } : {}) };
58
+ return { tier: 'local', model: model_cache_1.LOCAL_MODEL, egress: false };
59
+ return { tier: 'none', egress: false, ...(hasModule ? { localRuntimePresent: true } : {}),
60
+ ...(hasModule && observed && !observed.ready ? { localState: observed.state } : {}) };
60
61
  }
@@ -20,6 +20,15 @@ export interface ScannedLike {
20
20
  qualifiedName: string;
21
21
  }>;
22
22
  }
23
+ /** The governed fields which contribute to a requirement-document vector. */
24
+ export interface RequirementDocumentLike {
25
+ id: string;
26
+ type: string;
27
+ title: string;
28
+ status: string;
29
+ dependsOn?: readonly string[];
30
+ sections?: Readonly<Record<string, string>>;
31
+ }
23
32
  export type CoverageState = 'covered' | 'inert' | 'not-adopted' | 'unknown';
24
33
  export interface CoverageInput {
25
34
  /** The RESOLVED tier. `none` is the shipped default (zero egress) and means never opted in. */
@@ -50,6 +59,14 @@ export declare const DOC_TEXT_LIMIT = 2000;
50
59
  export declare function docTextOf(file: ScannedLike): string;
51
60
  /** The same text, indexed by source path — the form the three ranking passes consume. */
52
61
  export declare function docTextIndex(scanned: ReadonlyArray<ScannedLike>): Map<string, string>;
62
+ /** A requirement vector has its own versioned namespace and cannot share a source-file key. */
63
+ export declare function canonicalRequirementDocument(doc: RequirementDocumentLike, lineageId: string): string;
64
+ /** Every eligible REQ/H/A/T document paired with its REQ lineage and cache text. */
65
+ export declare function requirementDocumentTexts<T extends RequirementDocumentLike>(documents: readonly T[]): Array<{
66
+ document: T;
67
+ lineageId: string;
68
+ text: string;
69
+ }>;
53
70
  /**
54
71
  * Pure: the caller supplies the counts. Keeping the filesystem out means the judgement is testable
55
72
  * without a cache on disk, and it cannot be wrong about ordering or locking.
@@ -52,6 +52,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
52
52
  exports.COVERAGE_STATE_FILE = exports.DOC_TEXT_LIMIT = void 0;
53
53
  exports.docTextOf = docTextOf;
54
54
  exports.docTextIndex = docTextIndex;
55
+ exports.canonicalRequirementDocument = canonicalRequirementDocument;
56
+ exports.requirementDocumentTexts = requirementDocumentTexts;
55
57
  exports.vectorCoverage = vectorCoverage;
56
58
  exports.coverageLine = coverageLine;
57
59
  exports.countCovered = countCovered;
@@ -77,6 +79,41 @@ function docTextOf(file) {
77
79
  function docTextIndex(scanned) {
78
80
  return new Map(scanned.map((f) => [f.sourcePath, docTextOf(f)]));
79
81
  }
82
+ /** A requirement vector has its own versioned namespace and cannot share a source-file key. */
83
+ function canonicalRequirementDocument(doc, lineageId) {
84
+ const sections = Object.entries(doc.sections ?? {})
85
+ .sort(([a], [b]) => a.localeCompare(b))
86
+ .map(([heading, body]) => `${heading}\n${body}`)
87
+ .join('\n');
88
+ return [
89
+ 'holmes-requirement-document/v1', `id:${doc.id}`, `kind:${doc.type}`,
90
+ `lineage:${lineageId}`, `status:${doc.status}`, `dependsOn:${[...(doc.dependsOn ?? [])].sort().join(',')}`,
91
+ `title:${doc.title}`, sections,
92
+ ].join('\n');
93
+ }
94
+ /** Every eligible REQ/H/A/T document paired with its REQ lineage and cache text. */
95
+ function requirementDocumentTexts(documents) {
96
+ const byId = new Map(documents.map((doc) => [doc.id, doc]));
97
+ const lineageOf = (id) => {
98
+ const seen = new Set();
99
+ let current = byId.get(id);
100
+ while (current) {
101
+ if (seen.has(current.id))
102
+ return null;
103
+ seen.add(current.id);
104
+ if (current.type === 'REQ')
105
+ return current.id;
106
+ current = (current.dependsOn ?? []).map((parent) => byId.get(parent)).find((parent) => parent !== undefined);
107
+ }
108
+ return null;
109
+ };
110
+ return documents.flatMap((document) => {
111
+ if (!['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC'].includes(document.type))
112
+ return [];
113
+ const lineageId = lineageOf(document.id);
114
+ return lineageId === null ? [] : [{ document, lineageId, text: canonicalRequirementDocument(document, lineageId) }];
115
+ });
116
+ }
80
117
  const isCount = (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
81
118
  /**
82
119
  * Pure: the caller supplies the counts. Keeping the filesystem out means the judgement is testable
@@ -210,37 +210,33 @@ The failure happens while npm is still installing dependencies — before Holmes
210
210
  `doctor` cannot diagnose it and this note is the only warning available. If `npm install` dies with
211
211
  `gyp ERR!` in `tree_sitter_runtime_binding`, switch to Node 20 or 22 on that machine.
212
212
 
213
- # Default local embeddings (Windows, macOS, Linux)
213
+ # Default local embeddings (macOS and Linux npm lifecycle)
214
214
 
215
- Holmes-Kit ships with the **Xenova/bge-m3** local tier available, but **preparing it is
216
- opt-in**: neither package installation, nor `holmes-kit init`, nor the Windows bootstrap
217
- downloads model assets on its own. Run one command when you want it:
215
+ Holmes-Kit prepares the pinned **Xenova/bge-m3** local tier by default when a normal npm
216
+ installation runs its lifecycle scripts. The package activates the tier only after an actual
217
+ offline inference produces a finite, normalized 1024-dimensional vector. `holmes-kit init` does
218
+ not add a second download path. Run this command to retry preparation or recover an unavailable
219
+ cache:
218
220
 
219
221
  ```text
220
222
  holmes-kit semantic-setup
221
223
  ```
222
224
 
223
- To prepare it during installation instead, set `HOLMES_AUTO_MODEL_INSTALL=1` before
224
- installing. `HOLMES_SKIP_MODEL_INSTALL=1` still refuses preparation and **outranks** the
225
- opt-in, so an explicit refusal is never overridden. All three harnesses and all three
226
- operating systems share this default — Windows does not prepare the model when macOS and
227
- Linux do not.
225
+ `HOLMES_SKIP_MODEL_INSTALL=1` explicitly refuses automatic preparation. It is the only automatic
226
+ opt-out and never prevents an explicit `semantic-setup` or `semantic-check`. The Node lifecycle
227
+ implementation is shared by the three harnesses. Windows PowerShell-bootstrap default-preparation
228
+ behavior is retained for separate consumer validation; do not treat this document as evidence that
229
+ that bootstrap path has completed the same acceptance run.
228
230
 
229
231
  The first setup downloads public model assets from Hugging Face; it sends no repository
230
232
  text. Normal embedding inference is offline and will not download missing assets.
231
233
  The model revision is pinned to `4de13258303883538bd53b696b452bf8099f0858`.
232
234
 
233
- Until the model is prepared, `doctor` reports the semantic tier as **none** and names what
234
- it costs — requests lexical search misses (measured 16.4%) have 0% recall — together with the
235
- command that changes it. A runtime that resolves is not a tier that answers, so an unprepared
236
- local runtime is never reported as the `local` tier.
237
-
238
- The Windows `scripts/install.ps1` bootstrap honours the same opt-in. With
239
- `HOLMES_AUTO_MODEL_INSTALL=1` it prepares the model after npm installation and when the
240
- requested Holmes-Kit version is already installed, printing readiness only after successful
241
- inference; failure prints `semantic-setup` / `semantic-check` recovery commands while preserving
242
- the installed graph tools. Without the opt-in it prepares nothing and names the command. Dry runs
243
- and the explicit skip flag do no model work.
235
+ When setup cannot run because lifecycle scripts are blocked, the network is unavailable, or the
236
+ cache fails verification, the package and BM25/citation/graph features stay usable. `doctor`
237
+ reports **unavailable** or **degraded** local semantics and tells the user whether
238
+ `semantic-setup` will download, verify, or re-verify the cache. A nonempty cache directory or a
239
+ resolvable runtime alone is never reported as a local embedding tier.
244
240
 
245
241
  Run `holmes-kit semantic-check` after installation. Success means an actual CPU inference
246
242
  produced a finite, normalized 1024-dimensional vector. `doctor` deliberately reports local
@@ -252,10 +248,9 @@ hide successful lifecycle output, so use `--foreground-scripts` when inspecting
252
248
 
253
249
  Models are shared between projects in `~/.holmes/models` (Windows:
254
250
  `%USERPROFILE%\.holmes\models`). Set `HOLMES_MODEL_CACHE` to override this directory,
255
- including for a prepopulated offline cache. Set `HOLMES_SKIP_MODEL_INSTALL=1` to refuse
256
- automatic preparation explicitly; it outranks `HOLMES_AUTO_MODEL_INSTALL=1` and does not
257
- disable an explicit setup/check command. An empty cache directory counts as not prepared —
258
- an interrupted download leaves exactly that, and reading it as ready would be a false PASS.
251
+ including for a prepopulated offline cache. An empty, unverified, malformed, or changed cache
252
+ receipt counts as unavailable/degraded — only a receipt written after successful offline inference
253
+ activates the local tier.
259
254
  For source checkouts, build first, then run `node bin/holmes-kit.js semantic-setup`.
260
255
 
261
256
  If npm blocks lifecycle scripts, run `npm install-scripts ls`, review the blocked versions,
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.28.0",
4
+ "version": "0.29.0",
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",