@holmes-lab/holmes-kit 0.29.0 → 0.31.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 (169) hide show
  1. package/CHANGELOG.md +556 -0
  2. package/README.md +15 -5
  3. package/bin/holmes-hook-antigravity.js +4 -0
  4. package/bin/holmes-kit.js +4 -0
  5. package/bin/holmes-pre-push.js +3 -0
  6. package/bin/holmes-stop-antigravity.js +4 -0
  7. package/dist/.build-id +1 -1
  8. package/dist/holmes/cli/agents-guidance-history.d.ts +1 -1
  9. package/dist/holmes/cli/agents-guidance-history.js +11 -2
  10. package/dist/holmes/cli/agents-guidance.d.ts +1 -0
  11. package/dist/holmes/cli/agents-guidance.js +11 -8
  12. package/dist/holmes/cli/agents.d.ts +41 -0
  13. package/dist/holmes/cli/agents.js +382 -2
  14. package/dist/holmes/cli/attest.d.ts +2 -0
  15. package/dist/holmes/cli/attest.js +66 -15
  16. package/dist/holmes/cli/ci-gate.js +16 -1
  17. package/dist/holmes/cli/claude-switches.d.ts +95 -0
  18. package/dist/holmes/cli/claude-switches.js +967 -0
  19. package/dist/holmes/cli/codex-hooks.d.ts +77 -0
  20. package/dist/holmes/cli/codex-hooks.js +802 -0
  21. package/dist/holmes/cli/codex-oracle.d.ts +194 -0
  22. package/dist/holmes/cli/codex-oracle.js +1245 -0
  23. package/dist/holmes/cli/codex-toml.d.ts +58 -1
  24. package/dist/holmes/cli/codex-toml.js +456 -40
  25. package/dist/holmes/cli/doctor.d.ts +108 -8
  26. package/dist/holmes/cli/doctor.js +1408 -98
  27. package/dist/holmes/cli/index.js +23 -11
  28. package/dist/holmes/cli/init.d.ts +13 -0
  29. package/dist/holmes/cli/init.js +749 -77
  30. package/dist/holmes/cli/interactive-prompt.js +2 -2
  31. package/dist/holmes/cli/mcp-launcher.d.ts +64 -6
  32. package/dist/holmes/cli/mcp-launcher.js +189 -6
  33. package/dist/holmes/cli/mcp-version.js +13 -2
  34. package/dist/holmes/cli/settings-merge.js +8 -2
  35. package/dist/holmes/cli/upgrade.d.ts +13 -0
  36. package/dist/holmes/cli/upgrade.js +116 -23
  37. package/dist/holmes/cli/workspace-scope.d.ts +22 -0
  38. package/dist/holmes/cli/workspace-scope.js +375 -0
  39. package/dist/holmes/cli/worktree-readiness.d.ts +1 -0
  40. package/dist/holmes/cli/worktree-readiness.js +17 -3
  41. package/dist/holmes/cpg/cpg-scanner.d.ts +29 -0
  42. package/dist/holmes/cpg/cpg-scanner.js +403 -3
  43. package/dist/holmes/cpg/cycle-detect.js +2 -1
  44. package/dist/holmes/cpg/forbidden-edges.js +9 -2
  45. package/dist/holmes/cpg/required-calls.js +8 -1
  46. package/dist/holmes/governance/autonomy.d.ts +9 -0
  47. package/dist/holmes/governance/autonomy.js +28 -1
  48. package/dist/holmes/governance/constitution-debt.js +3 -2
  49. package/dist/holmes/governance/constitution.js +15 -3
  50. package/dist/holmes/governance/provenance-chain.js +3 -2
  51. package/dist/holmes/governance/push-gate-runner.js +4 -3
  52. package/dist/holmes/guardrail/dependency-delta.js +4 -3
  53. package/dist/holmes/guardrail/linear-match.d.ts +57 -0
  54. package/dist/holmes/guardrail/linear-match.js +256 -0
  55. package/dist/holmes/guardrail/risk-classifier.d.ts +6 -7
  56. package/dist/holmes/guardrail/risk-classifier.js +931 -44
  57. package/dist/holmes/guardrail/risk-types.d.ts +6 -0
  58. package/dist/holmes/guardrail/scope-judgment.d.ts +4 -24
  59. package/dist/holmes/guardrail/scope-judgment.js +100 -23
  60. package/dist/holmes/guardrail/shell-words.d.ts +42 -0
  61. package/dist/holmes/guardrail/shell-words.js +1720 -0
  62. package/dist/holmes/guardrail/write-target.d.ts +168 -3
  63. package/dist/holmes/guardrail/write-target.js +2379 -87
  64. package/dist/holmes/hooks/adapters/antigravity.d.ts +3 -1
  65. package/dist/holmes/hooks/adapters/antigravity.js +115 -11
  66. package/dist/holmes/hooks/pre-tool-use.d.ts +32 -6
  67. package/dist/holmes/hooks/pre-tool-use.js +923 -87
  68. package/dist/holmes/hooks/rtm-refresh-child.d.ts +22 -1
  69. package/dist/holmes/hooks/rtm-refresh-child.js +102 -18
  70. package/dist/holmes/hooks/rtm-refresh.d.ts +20 -1
  71. package/dist/holmes/hooks/rtm-refresh.js +60 -15
  72. package/dist/holmes/hooks/session-start.d.ts +10 -0
  73. package/dist/holmes/hooks/session-start.js +31 -7
  74. package/dist/holmes/hooks/stop.d.ts +2 -1
  75. package/dist/holmes/hooks/stop.js +197 -91
  76. package/dist/holmes/mcp/approval-adapters.d.ts +22 -0
  77. package/dist/holmes/mcp/approval-adapters.js +21 -0
  78. package/dist/holmes/mcp/approval-commit.d.ts +20 -0
  79. package/dist/holmes/mcp/approval-commit.js +108 -0
  80. package/dist/holmes/mcp/approval-intent.d.ts +44 -0
  81. package/dist/holmes/mcp/approval-intent.js +67 -0
  82. package/dist/holmes/mcp/approval-policy.d.ts +14 -0
  83. package/dist/holmes/mcp/approval-policy.js +18 -0
  84. package/dist/holmes/mcp/elicit-approval.d.ts +2 -0
  85. package/dist/holmes/mcp/elicit-approval.js +8 -3
  86. package/dist/holmes/mcp/handlers/graph-operations.d.ts +17 -1
  87. package/dist/holmes/mcp/handlers/graph-operations.js +15 -6
  88. package/dist/holmes/mcp/handlers/maintenance-analysis.js +11 -5
  89. package/dist/holmes/mcp/handlers/maintenance-evidence.js +3 -2
  90. package/dist/holmes/mcp/handlers/phase-queries.d.ts +22 -7
  91. package/dist/holmes/mcp/handlers/phase-queries.js +81 -2
  92. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +26 -0
  93. package/dist/holmes/mcp/handlers/requirement-triage.js +48 -11
  94. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -1
  95. package/dist/holmes/mcp/handlers/review-evidence.js +15 -5
  96. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +18 -0
  97. package/dist/holmes/mcp/handlers/slice-orchestration.js +122 -16
  98. package/dist/holmes/mcp/handlers/spec-approval.d.ts +35 -2
  99. package/dist/holmes/mcp/handlers/spec-approval.js +175 -57
  100. package/dist/holmes/mcp/handlers/spec-authoring.js +36 -3
  101. package/dist/holmes/mcp/handlers/spec-queries.d.ts +39 -3
  102. package/dist/holmes/mcp/handlers/spec-queries.js +114 -7
  103. package/dist/holmes/mcp/handlers/test-execution.js +9 -3
  104. package/dist/holmes/mcp/handlers.d.ts +126 -8
  105. package/dist/holmes/mcp/handlers.js +109 -18
  106. package/dist/holmes/mcp/harness-attestation.d.ts +20 -0
  107. package/dist/holmes/mcp/harness-attestation.js +179 -0
  108. package/dist/holmes/mcp/maintenance-analyze.js +28 -4
  109. package/dist/holmes/mcp/maintenance-evidence.js +1 -1
  110. package/dist/holmes/mcp/requirement-triage-evidence.d.ts +72 -2
  111. package/dist/holmes/mcp/requirement-triage-evidence.js +227 -1
  112. package/dist/holmes/mcp/server.js +24 -3
  113. package/dist/holmes/mcp/supervisor.js +7 -3
  114. package/dist/holmes/mcp/tool-schemas.d.ts +8 -0
  115. package/dist/holmes/mcp/tool-schemas.js +54 -7
  116. package/dist/holmes/mcp/validate-args.js +12 -0
  117. package/dist/holmes/project/bounded-io.d.ts +102 -0
  118. package/dist/holmes/project/bounded-io.js +212 -0
  119. package/dist/holmes/project/change-source.js +3 -1
  120. package/dist/holmes/project/ci-runs.js +3 -2
  121. package/dist/holmes/project/ignore.d.ts +31 -2
  122. package/dist/holmes/project/ignore.js +409 -50
  123. package/dist/holmes/project/regular-file-guard.d.ts +13 -0
  124. package/dist/holmes/project/regular-file-guard.js +149 -0
  125. package/dist/holmes/project/root.js +12 -3
  126. package/dist/holmes/refresh/freshness-coordinator.d.ts +67 -0
  127. package/dist/holmes/refresh/freshness-coordinator.js +230 -0
  128. package/dist/holmes/reverse/anchor.js +4 -3
  129. package/dist/holmes/reverse/scan.js +6 -2
  130. package/dist/holmes/review/commit-text.js +3 -2
  131. package/dist/holmes/review/condition-hunk-replay.d.ts +12 -0
  132. package/dist/holmes/review/condition-hunk-replay.js +13 -2
  133. package/dist/holmes/review/condition-hunk-resolution.js +59 -8
  134. package/dist/holmes/review/failed-test-names.js +13 -10
  135. package/dist/holmes/review/findings.js +3 -1
  136. package/dist/holmes/review/kills-check.js +6 -1
  137. package/dist/holmes/review/point-in-time-replay.js +5 -4
  138. package/dist/holmes/review/replay-corpus.js +5 -4
  139. package/dist/holmes/review/requirement-triage-human-records.d.ts +59 -0
  140. package/dist/holmes/review/requirement-triage-human-records.js +119 -0
  141. package/dist/holmes/review/run-replay.js +3 -2
  142. package/dist/holmes/review/scope.js +6 -1
  143. package/dist/holmes/review/temporal-prior.js +3 -2
  144. package/dist/holmes/review/test-evidence.js +3 -2
  145. package/dist/holmes/review/test-outcomes.d.ts +28 -0
  146. package/dist/holmes/review/test-outcomes.js +92 -2
  147. package/dist/holmes/review/test-runner.d.ts +6 -0
  148. package/dist/holmes/review/test-runner.js +36 -15
  149. package/dist/holmes/rtm/advisory-outcomes.js +3 -2
  150. package/dist/holmes/rtm/anchor-ids.js +42 -2
  151. package/dist/holmes/rtm/file-anchors.js +4 -1
  152. package/dist/holmes/rtm/ftt-fulfilment.js +8 -3
  153. package/dist/holmes/rtm/git-changes.js +3 -1
  154. package/dist/holmes/rtm/graph-store.js +3 -2
  155. package/dist/holmes/rtm/test-scope.js +9 -4
  156. package/dist/holmes/spec/compat-impact.d.ts +25 -4
  157. package/dist/holmes/spec/compat-impact.js +682 -11
  158. package/dist/holmes/spec/entity-git-snapshot.js +3 -2
  159. package/dist/holmes/spec/entity-integration.js +3 -2
  160. package/dist/holmes/spec/entity-renumber-transaction.d.ts +19 -0
  161. package/dist/holmes/spec/entity-renumber-transaction.js +79 -6
  162. package/dist/holmes/spec/remote-spec-refs.js +3 -2
  163. package/dist/holmes/spec/renumber.js +25 -10
  164. package/dist/holmes/spec/spec-parser.js +9 -3
  165. package/dist/holmes/spec/yaml-scalar.js +2 -2
  166. package/dist/holmes/update/refresh.js +3 -1
  167. package/dist/holmes/update/update-notice.d.ts +6 -0
  168. package/dist/holmes/update/update-notice.js +18 -1
  169. package/package.json +11 -4
@@ -1,5 +1,12 @@
1
1
  import { NativeEvidence } from './native-deps';
2
2
  import { type SemanticTier } from '../semantic/tier';
3
+ import { type CodexVerdict } from './codex-oracle';
4
+ /**
5
+ * @implements A-SPEC-251.2 (round 45) — whether `p` is this install's own `bin/<name>`, by `resolvesToPackage`'s rule: a path
6
+ * inside the install as written is compared as written; any other is compared by its walked real path (round 44 compared the walk
7
+ * of an install on a path doctor never looks up — null — and read a false FAIL, measured).
8
+ */
9
+ export declare function isInstallScript(p: string, name: string, packageRoot: string): boolean;
3
10
  /**
4
11
  * Checks if a script path belongs to the packageRoot, supporting symlinked global installs.
5
12
  */
@@ -18,6 +25,22 @@ export interface DoctorOptions {
18
25
  run?: ProbeRunner;
19
26
  autoFix?: boolean;
20
27
  agent?: Agent;
28
+ /** Test/integration override for Codex's active default user configuration. */
29
+ codexConfigPath?: string;
30
+ /** @implements A-SPEC-727 — test/integration override for Codex's user-level hooks file. */
31
+ codexHooksPath?: string;
32
+ /** Test seam for Codex's local plugin registry; production reads its JSON CLI output. */
33
+ readCodexPluginList?: () => string | undefined;
34
+ /** A-SPEC-251.2 (round 46): test/integration override for agy's user-level hooks file (`~/.gemini/config/hooks.json`). */
35
+ agyUserHooksPath?: string;
36
+ /** A-SPEC-738: how to ask Codex whether its files load (tests inject; default: the installed codex). */
37
+ codexOracle?: (input: {
38
+ configBytes: Buffer | null;
39
+ hooksBytes: Buffer | null;
40
+ cwd: string;
41
+ realConfigPath?: string;
42
+ realHooksPath?: string;
43
+ }) => CodexVerdict;
21
44
  }
22
45
  /**
23
46
  * Environment variables removed before spawning a probe.
@@ -54,7 +77,7 @@ export declare function globalInstallDir(prefix: string, platform: string): stri
54
77
  * matches neither (measured) — null there, and the caller keeps the plain-'npm' spawn, which is
55
78
  * today's behavior and has no .cmd problem on POSIX. env/execPath are injectable for tests only.
56
79
  */
57
- export declare function npmCliEntry(env?: NodeJS.ProcessEnv, execPath?: string): string | null;
80
+ export declare function npmCliEntry(env?: NodeJS.ProcessEnv, execPath?: string, keep?: (place: string) => boolean): string | null;
58
81
  /** What the global-prefix probe saw. `unreadable` carries WHY npm could not be consulted. */
59
82
  export interface PrefixProbe {
60
83
  prefix?: unknown;
@@ -108,6 +131,11 @@ export declare function grammarProbe(packageRoot: string): {
108
131
  failed: string[];
109
132
  error?: string;
110
133
  };
134
+ /**
135
+ * @implements A-SPEC-251.2 (round 27) — the home directory, only when it is one: a missing HOME made the spawn fail as
136
+ * `spawnSync npm ENOENT`, which named npm as missing (measured); the npm child then keeps the default directory.
137
+ */
138
+ export declare function npmHome(home?: string): string | undefined;
111
139
  /**
112
140
  * @implements A-SPEC-580
113
141
  * Everything observable about the better-sqlite3 install, gathered for `nativeVerdict`. Each probe
@@ -134,7 +162,7 @@ export declare function grammarProbe(packageRoot: string): {
134
162
  * how we look, never whether a real miss is reported.
135
163
  */
136
164
  export declare function resolveDepDir(fromRoot: string, name: string): string | null;
137
- export declare function gatherNativeEvidence(packageRoot: string): NativeEvidence;
165
+ export declare function gatherNativeEvidence(packageRoot: string, target?: string): NativeEvidence;
138
166
  /** The parent environment minus the variables that legitimately change a gate decision. Pure. */
139
167
  export declare function probeEnv(parent: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
140
168
  /** Seam for the gate probe's child process. Default is a real `spawnSync`; tests inject a fake. */
@@ -160,13 +188,15 @@ export interface ProbeRunner {
160
188
  */
161
189
  export declare function resolveWiringPath(target: string, arg: string): string;
162
190
  export declare function runDoctor(packageRoot: string, target?: string, opts?: DoctorOptions, extraChecks?: Check[]): Promise<Check[]>;
191
+ export declare function resetWiringSpawns(): void;
192
+ export declare function wiringSpawnShared(command: string, args: string[], cwd: string): Promise<Check>;
193
+ export declare function wiringSpawnCheck(command: string, args: string[], timeoutMs?: number, platform?: NodeJS.Platform, cwd?: string): Promise<Check>;
163
194
  /**
164
- * Drive a real MCP stdio handshake: initialize -> initialized -> tools/list, with a timeout.
165
- * Async by necessity — the protocol is a ROUND TRIP, so a spawnSync that writes everything at once
166
- * and closes stdin makes the server exit before answering (a false FAIL this check produced on its
167
- * very first run against a healthy server).
195
+ * @implements A-SPEC-251.2 (round 52, fourth repair) — the environment of the 'MCP server' probe's child: the wiring
196
+ * probes' PATH (doctor's node's directory, then the absolute entries outside the workspace). With the environment handed
197
+ * over as it was, the server's supervisor (`HOLMES_MCP_AUTORELOAD=1`) started the `node` the workspace had put on PATH.
168
198
  */
169
- export declare function wiringSpawnCheck(command: string, args: string[], timeoutMs?: number, platform?: NodeJS.Platform, cwd?: string): Promise<Check>;
199
+ export declare function mcpProbeEnv(env: NodeJS.ProcessEnv, target: string, platform?: NodeJS.Platform): NodeJS.ProcessEnv;
170
200
  /**
171
201
  * Push-gate presence, diagnosed only where it applies: a repo that opted into governance (.ax)
172
202
  * AND has git. Absence or a hook without our signature is a WARN carrying the install command —
@@ -174,6 +204,13 @@ export declare function wiringSpawnCheck(command: string, args: string[], timeou
174
204
  */
175
205
  export declare function pushGateCheck(target: string): Check | null;
176
206
  export declare function ciMatrixCheck(target: string): Check | null;
207
+ /**
208
+ * @implements A-SPEC-251.2 (round 43) — no control character from a file reaches the terminal (an `env` key holding ESC and BEL
209
+ * retitled it and cleared the screen — measured); line breaks and tabs stay. `--json` escapes them already.
210
+ */
211
+ export declare const terminalSafe: (s: string) => string;
212
+ /** Round 44: `--json` — JSON.stringify leaves C1 and the line separators raw; they are escaped as JSON escapes. */
213
+ export declare function checksJson(checks: Check[]): string;
177
214
  export declare function formatChecks(checks: Check[]): string;
178
215
  /**
179
216
  * Prove that EVERY wired harness can actually start a server, not merely that its file parses.
@@ -193,7 +230,70 @@ export declare function formatChecks(checks: Check[]): string;
193
230
  * The `node` fast-path is gone. Existence survives as a fast FAIL, because spending a 30s deadline on
194
231
  * a path that does not exist tells nobody anything new.
195
232
  */
196
- export declare function wiringHandshakeChecks(target: string): Promise<Check[]>;
233
+ /**
234
+ * @implements A-SPEC-721 — the target itself carries Codex wiring (plugin directory, or a legacy
235
+ * repository-local config/JSON). The active config is shared by every workspace, so only such a
236
+ * target is told that the shared file lacks a Holmes entry.
237
+ */
238
+ export declare function codexWiredTarget(target: string): boolean;
239
+ /**
240
+ * @implements A-SPEC-251.2 (0.31.0) — each harness whose Holmes wiring runs npx gets a WARN: npx runs npm in every
241
+ * session workspace, and that workspace's .npmrc (node-options, registry) and node_modules replaced the server
242
+ * (measured 2026-09-25/26). A node wiring gets no line.
243
+ */
244
+ export declare function wiringLauncherChecks(target: string, codexConfigPath?: string): Check[];
245
+ /**
246
+ * @implements A-SPEC-251.2 (confirmation round 22) — the version a Codex or Antigravity wiring launches, against this
247
+ * CLI (Claude's `.mcp.json` has its own 'mcp server version' line). Codex and Antigravity node wirings pointing at a
248
+ * 0.20.0 install read PASS or nothing (measured). Offline: the pin, or the local package.json above the node bin.
249
+ */
250
+ export declare function wiringVersionChecks(target: string, codexConfigPath: string | undefined, cliVersion: string): Check[];
251
+ /**
252
+ * @implements A-SPEC-251.2 (round 52, repair) — what a wiring probe starts: never a bare word. The word `node` is the file
253
+ * that runs doctor; another bare word is the file found for it under doctor's PATH (the one `commandPlace` judged); a `.cmd`
254
+ * or `.bat` shim goes through the command interpreter named by ComSpec, as an absolute path. Null when nothing is found.
255
+ * A bare word is looked up by Windows in the child's directory — the target — before PATH, so a PATH in front did not
256
+ * keep `<target>\node.exe` from starting (code reading, not measured on Windows); and where the file that runs doctor is
257
+ * not named `node`, its directory holds no `node` and PATH's ran (measured).
258
+ */
259
+ export interface ProbeOptions {
260
+ platform?: NodeJS.Platform;
261
+ env?: NodeJS.ProcessEnv;
262
+ /** Whether the file that runs doctor is the `node` of its own directory. */
263
+ ownNode?: boolean;
264
+ /** Whether doctor's node lies inside the workspace (a nodeenv in the project). */
265
+ ownInside?: boolean;
266
+ /** The directory of doctor's node. */
267
+ ownDir?: string;
268
+ /** Whether a place is one the probe keeps (outside the workspace) — asked of `ComSpec`. */
269
+ keep?: (place: string) => boolean;
270
+ }
271
+ /** Fifth repair: what the harness line says doctor did — it checked the server only where the launch was run. */
272
+ export declare function harnessClause(ran: boolean): string;
273
+ /**
274
+ * @implements A-SPEC-251.2 (round 52, tenth repair; owner decision 2026-09-29) — the npx launch holmes-kit writes: the bare
275
+ * command `npx` and exactly `-y -p @holmes-lab/holmes-kit@<version> holmes-mcp`. doctor starts no npx wiring: npx runs npm,
276
+ * and npm walks up from where it starts, reading `.npmrc` and putting every parent's `node_modules/.bin` on PATH — each place
277
+ * doctor started it (the target, an empty temporary directory, one pinned with `--prefix`, a root only the user could
278
+ * write) ran a program someone else chose, or failed where the harness would not (oracle waves 60 to 63).
279
+ */
280
+ export declare function npxLaunchWritten(command: string, args: readonly unknown[]): boolean;
281
+ /** Why `probeSpawn` starts nothing for this command, or null when it starts something. */
282
+ export declare function probeRefusal(command: string, args: string[], cwd: string, opts?: ProbeOptions): string | null;
283
+ export declare function probeSpawn(command: string, args: string[], cwd: string, opts?: ProbeOptions): {
284
+ file: string;
285
+ args: string[];
286
+ verbatim?: true;
287
+ } | null;
288
+ /**
289
+ * What a probe started from `target` is given: whether doctor's node lies inside the workspace, and which PATH entries its
290
+ * children keep (absolute ones outside the workspace; with a target that holds the home directory, every absolute one).
291
+ */
292
+ export declare function probeContext(target: string): {
293
+ ownInside: boolean;
294
+ keep: (entry: string) => boolean;
295
+ };
296
+ export declare function wiringHandshakeChecks(target: string, codexConfigPath?: string, packageRoot?: string): Promise<Check[]>;
197
297
  /**
198
298
  * @implements A-SPEC-476
199
299
  * The semantic tier's doctor verdict, pure so the three states are unit-testable offline.