@holmes-lab/holmes-kit 0.28.0 → 0.30.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 (83) hide show
  1. package/CHANGELOG.md +100 -0
  2. package/README.md +24 -21
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  5. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  6. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  7. package/dist/holmes/cli/agents-guidance.js +11 -8
  8. package/dist/holmes/cli/codex-toml.d.ts +23 -1
  9. package/dist/holmes/cli/codex-toml.js +151 -4
  10. package/dist/holmes/cli/doctor.d.ts +11 -1
  11. package/dist/holmes/cli/doctor.js +113 -13
  12. package/dist/holmes/cli/init.d.ts +2 -0
  13. package/dist/holmes/cli/init.js +20 -40
  14. package/dist/holmes/cli/interactive-prompt.js +2 -2
  15. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  16. package/dist/holmes/cli/worktree-readiness.js +17 -3
  17. package/dist/holmes/cpg/ast-mutation.d.ts +2 -0
  18. package/dist/holmes/cpg/ast-mutation.js +4 -2
  19. package/dist/holmes/cpg/foundation/cfg.d.ts +10 -0
  20. package/dist/holmes/cpg/foundation/cfg.js +27 -1
  21. package/dist/holmes/governance/autonomy.d.ts +9 -0
  22. package/dist/holmes/governance/autonomy.js +28 -1
  23. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  24. package/dist/holmes/hooks/rtm-refresh-child.js +100 -18
  25. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  26. package/dist/holmes/hooks/rtm-refresh.js +56 -15
  27. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  28. package/dist/holmes/mcp/approval-adapters.js +21 -0
  29. package/dist/holmes/mcp/approval-commit.d.ts +21 -0
  30. package/dist/holmes/mcp/approval-commit.js +92 -0
  31. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  32. package/dist/holmes/mcp/approval-intent.js +67 -0
  33. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  34. package/dist/holmes/mcp/approval-policy.js +18 -0
  35. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  36. package/dist/holmes/mcp/elicit-approval.js +5 -2
  37. package/dist/holmes/mcp/handlers/graph-operations.d.ts +24 -1
  38. package/dist/holmes/mcp/handlers/graph-operations.js +38 -6
  39. package/dist/holmes/mcp/handlers/maintenance-evidence.js +1 -1
  40. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +142 -0
  41. package/dist/holmes/mcp/handlers/requirement-triage.js +220 -0
  42. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  43. package/dist/holmes/mcp/handlers/review-evidence.js +9 -5
  44. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +7 -0
  45. package/dist/holmes/mcp/handlers/slice-orchestration.js +8 -1
  46. package/dist/holmes/mcp/handlers/spec-approval.d.ts +26 -2
  47. package/dist/holmes/mcp/handlers/spec-approval.js +72 -47
  48. package/dist/holmes/mcp/handlers/spec-authoring.js +20 -2
  49. package/dist/holmes/mcp/handlers.d.ts +153 -0
  50. package/dist/holmes/mcp/handlers.js +67 -13
  51. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  52. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  53. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +45 -0
  54. package/dist/holmes/mcp/requirement-triage-evidence.js +149 -0
  55. package/dist/holmes/mcp/server.js +5 -3
  56. package/dist/holmes/mcp/supervisor.js +7 -3
  57. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  58. package/dist/holmes/mcp/tool-schemas.js +44 -1
  59. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  60. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  61. package/dist/holmes/review/condition-hunk-replay.d.ts +45 -0
  62. package/dist/holmes/review/condition-hunk-replay.js +122 -0
  63. package/dist/holmes/review/condition-hunk-resolution.d.ts +65 -0
  64. package/dist/holmes/review/condition-hunk-resolution.js +258 -0
  65. package/dist/holmes/review/requirement-triage-benchmark.d.ts +45 -0
  66. package/dist/holmes/review/requirement-triage-benchmark.js +72 -0
  67. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  68. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  69. package/dist/holmes/review/requirement-triage.d.ts +61 -0
  70. package/dist/holmes/review/requirement-triage.js +143 -0
  71. package/dist/holmes/review/scope.js +6 -1
  72. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  73. package/dist/holmes/review/test-outcomes.js +90 -1
  74. package/dist/holmes/semantic/local-model.d.ts +3 -3
  75. package/dist/holmes/semantic/local-model.js +10 -12
  76. package/dist/holmes/semantic/model-cache.d.ts +15 -6
  77. package/dist/holmes/semantic/model-cache.js +77 -21
  78. package/dist/holmes/semantic/tier.d.ts +5 -1
  79. package/dist/holmes/semantic/tier.js +7 -6
  80. package/dist/holmes/semantic/vector-coverage.d.ts +17 -0
  81. package/dist/holmes/semantic/vector-coverage.js +37 -0
  82. package/docs/install-guide.md +19 -24
  83. package/package.json +1 -1
@@ -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.30.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",