@holmes-lab/holmes-kit 0.41.2 → 0.41.3

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 (103) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/README.md +28 -5
  3. package/bin/holmes-mcp.js +36 -1
  4. package/dist/.build-id +1 -1
  5. package/dist/holmes/cli/claude-switches.d.ts +9 -0
  6. package/dist/holmes/cli/claude-switches.js +11 -8
  7. package/dist/holmes/cli/doctor.d.ts +7 -1
  8. package/dist/holmes/cli/doctor.js +63 -20
  9. package/dist/holmes/cli/holmes-hook-id.d.ts +9 -0
  10. package/dist/holmes/cli/holmes-hook-id.js +22 -0
  11. package/dist/holmes/cli/hook-failure-posture.d.ts +44 -0
  12. package/dist/holmes/cli/hook-failure-posture.js +65 -0
  13. package/dist/holmes/cli/index.js +3 -1
  14. package/dist/holmes/cli/init.d.ts +6 -0
  15. package/dist/holmes/cli/init.js +151 -3
  16. package/dist/holmes/cli/native-deps.d.ts +10 -4
  17. package/dist/holmes/cli/native-deps.js +30 -29
  18. package/dist/holmes/cli/run-wiring.js +4 -2
  19. package/dist/holmes/cli/runtime-binding.d.ts +24 -0
  20. package/dist/holmes/cli/runtime-binding.js +67 -25
  21. package/dist/holmes/cli/settings-merge.d.ts +3 -2
  22. package/dist/holmes/cli/settings-merge.js +11 -9
  23. package/dist/holmes/config/config.d.ts +6 -0
  24. package/dist/holmes/config/config.js +23 -3
  25. package/dist/holmes/config/judgement-keys.d.ts +20 -0
  26. package/dist/holmes/config/judgement-keys.js +100 -0
  27. package/dist/holmes/config/project-caps.js +3 -2
  28. package/dist/holmes/governance/autonomous-shell.js +1 -1
  29. package/dist/holmes/governance/autonomy.d.ts +27 -1
  30. package/dist/holmes/governance/autonomy.js +126 -6
  31. package/dist/holmes/governance/wiring-receipt.d.ts +7 -0
  32. package/dist/holmes/governance/wiring-receipt.js +84 -0
  33. package/dist/holmes/guardrail/cli-root.d.ts +31 -0
  34. package/dist/holmes/guardrail/cli-root.js +261 -0
  35. package/dist/holmes/guardrail/command-traits.d.ts +2 -0
  36. package/dist/holmes/guardrail/command-traits.js +26 -1
  37. package/dist/holmes/guardrail/impact-gate.d.ts +17 -1
  38. package/dist/holmes/guardrail/impact-gate.js +44 -5
  39. package/dist/holmes/guardrail/outward-acts.js +10 -3
  40. package/dist/holmes/guardrail/package-manager-acts.d.ts +41 -0
  41. package/dist/holmes/guardrail/package-manager-acts.js +1298 -0
  42. package/dist/holmes/guardrail/refusal-codes.js +9 -1
  43. package/dist/holmes/guardrail/shell-syntax.d.ts +3 -0
  44. package/dist/holmes/guardrail/shell-syntax.js +7 -2
  45. package/dist/holmes/guardrail/write-target.d.ts +20 -0
  46. package/dist/holmes/guardrail/write-target.js +168 -2
  47. package/dist/holmes/hooks/pre-tool-use.d.ts +110 -3
  48. package/dist/holmes/hooks/pre-tool-use.js +1208 -60
  49. package/dist/holmes/mcp/evidence-artifact.d.ts +112 -0
  50. package/dist/holmes/mcp/evidence-artifact.js +2 -0
  51. package/dist/holmes/mcp/handlers/maintenance-evidence.d.ts +2 -1
  52. package/dist/holmes/mcp/handlers/maintenance-evidence.js +24 -2
  53. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +1 -1
  54. package/dist/holmes/mcp/handlers/operator-inspection.js +2 -2
  55. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +1 -1
  56. package/dist/holmes/mcp/handlers/requirement-triage.js +3 -2
  57. package/dist/holmes/mcp/handlers/spec-approval.d.ts +1 -1
  58. package/dist/holmes/mcp/handlers/spec-approval.js +6 -6
  59. package/dist/holmes/mcp/handlers/test-execution.d.ts +8 -0
  60. package/dist/holmes/mcp/handlers/test-execution.js +12 -6
  61. package/dist/holmes/mcp/handlers.d.ts +16 -7
  62. package/dist/holmes/mcp/maintenance-evidence.d.ts +11 -82
  63. package/dist/holmes/mcp/maintenance-evidence.js +57 -2
  64. package/dist/holmes/mcp/outcome-replay.d.ts +18 -0
  65. package/dist/holmes/mcp/outcome-replay.js +85 -0
  66. package/dist/holmes/mcp/outcome-windows.d.ts +136 -0
  67. package/dist/holmes/mcp/outcome-windows.js +236 -0
  68. package/dist/holmes/mcp/tool-schemas.js +1 -1
  69. package/dist/holmes/project/hook-specs-arg.d.ts +4 -0
  70. package/dist/holmes/project/hook-specs-arg.js +39 -0
  71. package/dist/holmes/project/install-layout.d.ts +11 -0
  72. package/dist/holmes/project/install-layout.js +109 -0
  73. package/dist/holmes/project/install-scripts-policy.d.ts +4 -1
  74. package/dist/holmes/project/install-scripts-policy.js +6 -3
  75. package/dist/holmes/project/native-recovery.d.ts +29 -0
  76. package/dist/holmes/project/native-recovery.js +62 -0
  77. package/dist/holmes/project/root.d.ts +6 -0
  78. package/dist/holmes/project/root.js +15 -3
  79. package/dist/holmes/project/wiring-receipt-format.d.ts +20 -0
  80. package/dist/holmes/project/wiring-receipt-format.js +42 -0
  81. package/dist/holmes/project/workspace-preflight.d.ts +9 -0
  82. package/dist/holmes/project/workspace-preflight.js +40 -1
  83. package/dist/holmes/review/classification-replay.d.ts +53 -0
  84. package/dist/holmes/review/classification-replay.js +78 -0
  85. package/dist/holmes/review/head-worktree.js +5 -4
  86. package/dist/holmes/review/run-provenance.js +3 -2
  87. package/dist/holmes/review/test-evidence.js +2 -2
  88. package/dist/holmes/review/test-outcomes.js +3 -1
  89. package/dist/holmes/rtm/graph-store.d.ts +5 -0
  90. package/dist/holmes/rtm/graph-store.js +12 -4
  91. package/dist/holmes/rtm/native-driver.d.ts +42 -0
  92. package/dist/holmes/rtm/native-driver.js +147 -0
  93. package/dist/holmes/rtm/rtm-graph.js +11 -2
  94. package/dist/holmes/runtime/dispatch.d.ts +6 -0
  95. package/dist/holmes/runtime/dispatch.js +51 -2
  96. package/dist/holmes/runtime/hook-process.d.ts +6 -0
  97. package/dist/holmes/runtime/hook-process.js +3 -3
  98. package/dist/holmes/update/semver-strict.d.ts +3 -0
  99. package/dist/holmes/update/semver-strict.js +58 -0
  100. package/docs/install-guide.md +8 -1
  101. package/package.json +1 -1
  102. package/playbooks/tdd-slice/PLAYBOOK.md +1 -1
  103. package/release-history.json +36 -1
@@ -39,6 +39,8 @@ export interface EditEvidenceInput {
39
39
  id: string;
40
40
  file: string;
41
41
  }>;
42
+ /** @implements A-SPEC-580.3 — why no analysis can exist here (the native driver did not load), when that is so */
43
+ driverUnavailable?: string;
42
44
  /** @implements A-SPEC-278.4 — the digest the artifact is stored under, so a verdict can name the analysis it read. */
43
45
  artifactDigest?: string | null;
44
46
  }
@@ -63,6 +65,18 @@ export declare function editEvidenceCodes(): Array<EditEvidenceReason['code']>;
63
65
  export declare function remediationFor(code: EditEvidenceReason['code']): string;
64
66
  /** @implements A-SPEC-333.1 — lead with whichever refusal the caller must fix FIRST; a widen reason never speaks for a refusal. */
65
67
  export declare function primaryReason(reasons: EditEvidenceReason[]): EditEvidenceReason | undefined;
68
+ export type DriverProbe = () => {
69
+ ok: true;
70
+ } | {
71
+ ok: false;
72
+ error: Error;
73
+ };
74
+ /**
75
+ * @implements A-SPEC-580.4 — why no analysis can exist here: the cause text when the driver does not load, else null.
76
+ * An injected probe is asked directly; the default is the real probe, once per process. Known limit: this probes with
77
+ * the hook process's Node, which can differ from the MCP server's Node.
78
+ */
79
+ export declare function driverCauseOf(probe?: DriverProbe): string | null;
66
80
  export declare function evaluateEditEvidence(inputArgs: EditEvidenceInput): EditEvidenceVerdict;
67
81
  /**
68
82
  * @implements A-SPEC-278
@@ -78,7 +92,9 @@ export type PreEditEvidenceMode = 'off' | 'warn' | 'block';
78
92
  * be an opinion: if this gate were ever consulted ahead of another, its `allow` could mask that
79
93
  * gate's denial. A gate that has nothing to say should say nothing.
80
94
  */
81
- export declare function preEditEvidenceDecision(verdict: EditEvidenceVerdict, mode: PreEditEvidenceMode): {
95
+ export declare function preEditEvidenceDecision(verdict: EditEvidenceVerdict, mode: PreEditEvidenceMode, opts?: {
96
+ driverProbe?: DriverProbe;
97
+ }): {
82
98
  permissionDecision: 'allow' | 'deny';
83
99
  permissionDecisionReason?: string;
84
100
  refusal?: string;
@@ -37,10 +37,11 @@ exports.isLowRiskTarget = isLowRiskTarget;
37
37
  exports.editEvidenceCodes = editEvidenceCodes;
38
38
  exports.remediationFor = remediationFor;
39
39
  exports.primaryReason = primaryReason;
40
+ exports.driverCauseOf = driverCauseOf;
40
41
  exports.evaluateEditEvidence = evaluateEditEvidence;
41
42
  exports.preEditEvidenceDecision = preEditEvidenceDecision;
42
43
  exports.loadEditEvidence = loadEditEvidence;
43
- // @implements A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3, A-SPEC-278.4, A-SPEC-278.6, A-SPEC-333.1, A-SPEC-333.9, A-SPEC-333.10
44
+ // @implements A-SPEC-580.7, A-SPEC-580.5, A-SPEC-580.4, A-SPEC-580.3, A-SPEC-279, A-SPEC-278.1, A-SPEC-278.2, A-SPEC-278.3, A-SPEC-278.4, A-SPEC-278.6, A-SPEC-333.1, A-SPEC-333.9, A-SPEC-333.10
44
45
  // @implements A-SPEC-278
45
46
  // @implements A-SPEC-277
46
47
  // @implements A-SPEC-276
@@ -104,6 +105,36 @@ const REMEDIATION = {
104
105
  'trace-gap': 'The target is declared in the Files to Touch of approved A-SPEC(s) that no source file anchors, so the graph cannot see their impact — anchor the implementing source (spec_remediate) or include those specs in the analysis request and re-run maintenance_analyze.',
105
106
  };
106
107
  const RANK = { allow: 0, widen: 1, refuse: 2 };
108
+ /** @implements A-SPEC-580.3 — the way out when maintenance_analyze cannot run in this install (A6 of W1). */
109
+ function noAnalysisCause(driverUnavailable) {
110
+ return driverUnavailable
111
+ // A-SPEC-580.5 — no fixed cause (doctor and preflight name the class) and no setting named (ask the owner)
112
+ ? ` maintenance_analyze cannot run in this install: ${driverUnavailable.split('. ')[0]}. Recover as \`holmes-kit doctor\` and workspace_preflight say, then restart the MCP server; until then no digest can be issued. Without rights over the global prefix: a privileged shell, or a project install of holmes-kit. ${require('../rtm/native-driver').ASK_THE_OWNER}`
113
+ : '';
114
+ }
115
+ let driverProbe;
116
+ const causeOf = (probe) => {
117
+ try {
118
+ const p = probe();
119
+ return p.ok ? null : String(p.error.message);
120
+ }
121
+ catch {
122
+ return null;
123
+ } // [no-substitution: the probe only adds advice; without it the reason is as before]
124
+ };
125
+ /**
126
+ * @implements A-SPEC-580.4 — why no analysis can exist here: the cause text when the driver does not load, else null.
127
+ * An injected probe is asked directly; the default is the real probe, once per process. Known limit: this probes with
128
+ * the hook process's Node, which can differ from the MCP server's Node.
129
+ */
130
+ function driverCauseOf(probe) {
131
+ if (probe)
132
+ return causeOf(probe);
133
+ if (driverProbe !== undefined)
134
+ return driverProbe;
135
+ driverProbe = causeOf(() => require('../rtm/native-driver').probeNativeDriver());
136
+ return driverProbe;
137
+ }
107
138
  function evaluateEditEvidence(inputArgs) {
108
139
  const target = inputArgs.target.replace(/\\/g, '/');
109
140
  const lowRisk = isLowRiskTarget(target);
@@ -132,9 +163,13 @@ function evaluateEditEvidence(inputArgs) {
132
163
  // `isLowRiskTarget` has already excluded those.
133
164
  if (lowRisk)
134
165
  return { decision: 'allow', reasons: [], remediation: '', lowRisk: true };
135
- reasons.push({ code: 'no-analysis', detail: `No impact analysis backs an edit to ${target}.` });
166
+ reasons.push({ code: 'no-analysis', detail: `No impact analysis backs an edit to ${target}.${noAnalysisCause(inputArgs.driverUnavailable)}` });
136
167
  traceGapReason(); // two reasons, both stated; the remediation stays the refusal's
137
- return { decision: 'refuse', reasons, remediation: REMEDIATION['no-analysis'], lowRisk };
168
+ // @implements A-SPEC-580.7 — with the driver out, maintenance_analyze cannot run: the remediation is the recovery
169
+ const remediation = inputArgs.driverUnavailable
170
+ ? 'Recover the native SQLite driver first: rebuild it as `holmes-kit doctor` and workspace_preflight say, restart the MCP server, then run maintenance_analyze({ root, request, persist: true }) for this change.'
171
+ : REMEDIATION['no-analysis'];
172
+ return { decision: 'refuse', reasons, remediation, lowRisk };
138
173
  }
139
174
  // (2) An analysis describes one commit. Once HEAD moves, its claims are about a tree that no
140
175
  // longer exists — the one condition that makes every other check meaningless.
@@ -250,13 +285,17 @@ function evaluateEditEvidence(inputArgs) {
250
285
  * be an opinion: if this gate were ever consulted ahead of another, its `allow` could mask that
251
286
  * gate's denial. A gate that has nothing to say should say nothing.
252
287
  */
253
- function preEditEvidenceDecision(verdict, mode) {
288
+ function preEditEvidenceDecision(verdict, mode, opts = {}) {
254
289
  if (mode === 'off')
255
290
  return null;
256
291
  if (verdict.decision === 'allow')
257
292
  return null;
258
293
  const codes = verdict.reasons.map((r) => r.code).join(', ');
259
- const detail = verdict.reasons.map((r) => r.detail).join(' ');
294
+ // @implements A-SPEC-580.3, A-SPEC-580.4, A-SPEC-580.5 — the hook's edit gate passes here and learns why no analysis can
295
+ // exist. impact_gate_check gives its cause through evaluateEditEvidence and never reaches this function, so no reason
296
+ // arrives already carrying it (580.5 removed the guard that said otherwise).
297
+ const cause = verdict.reasons.some((r) => r.code === 'no-analysis') ? driverCauseOf(opts.driverProbe) : null;
298
+ const detail = verdict.reasons.map((r) => (r.code === 'no-analysis' && cause ? `${r.detail}${noAnalysisCause(cause)}` : r.detail)).join(' ');
260
299
  // @implements A-SPEC-333
261
300
  // OUTCOME first, verdict second. Dogfooding the raised default (A-SPEC-332) showed this message
262
301
  // saying `(refuse)` while the hook returned `allow` — the first words contradicted what happened,
@@ -37,7 +37,7 @@ exports.MAX_LISTED = void 0;
37
37
  exports.renderFinding = renderFinding;
38
38
  exports.judgeOutward = judgeOutward;
39
39
  exports.outwardActsOf = outwardActsOf;
40
- // @implements A-SPEC-794.92, A-SPEC-794.87, A-SPEC-794.82, A-SPEC-794.80, A-SPEC-794.78, A-SPEC-794.77, A-SPEC-794.76, A-SPEC-794.75, A-SPEC-794.74, A-SPEC-794.71, A-SPEC-794.70, A-SPEC-794.69
40
+ // @implements A-SPEC-794.149, A-SPEC-794.148, A-SPEC-794.147, A-SPEC-794.92, A-SPEC-794.87, A-SPEC-794.82, A-SPEC-794.80, A-SPEC-794.78, A-SPEC-794.77, A-SPEC-794.76, A-SPEC-794.75, A-SPEC-794.74, A-SPEC-794.71, A-SPEC-794.70, A-SPEC-794.69
41
41
  /**
42
42
  * The outward judgement: which outward acts (push, publish) a shell command performs, for a full profile's push and
43
43
  * publish flags (REQ-792). It carries forward A-SPEC-794.49–794.54, 794.65, 794.66, 794.68 and 794.69.
@@ -202,7 +202,12 @@ const firstPositional = (args) => args.find((a) => !a.startsWith('-'));
202
202
  /** A shell word quoted back so a list of values can be judged again as a command. */
203
203
  const quote = (v) => (/^[\w@%+=:,./-]+$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`);
204
204
  /** A program word as a name: its basename, a scoped package kept whole, the version dropped. */
205
- const programToken = (v) => (/^@[^/\s]+\/[^/\s]+$/.test(v) ? v : path.basename(v)).replace(/(?!^)@[^@/]*$/, '');
205
+ // @implements A-SPEC-794.148 (Behavior 6) — a Windows program suffix (.cmd, .bat, .ps1, .exe; any case) is the program
206
+ const programToken = (v) => {
207
+ // A-SPEC-794.149: a backslash path is a path too (`C:\tools\npm.CMD publish`)
208
+ const t = (/^@[^/\s]+\/[^/\s]+$/.test(v) ? v : path.basename(v.replace(/\\/g, '/'))).replace(/(?!^)@[^@/]*$/, '');
209
+ return /\.(?:cmd|bat|ps1|exe)$/i.test(t) ? t.replace(/\.(?:cmd|bat|ps1|exe)$/i, '').toLowerCase() : t;
210
+ };
206
211
  /** A directory word resolved: literal, or a `$NAME` (with a literal suffix) whose literal value is known. */
207
212
  function resolveDir(word, base, vars) {
208
213
  if (word === undefined || !base.known || base.dir === undefined)
@@ -667,7 +672,9 @@ function releaseTool(name, args, clause, run) {
667
672
  return;
668
673
  if (args.some((a) => command_traits_1.RELEASE_HELP.has(a)))
669
674
  return; // its help or version (A-SPEC-794.74)
670
- run.findings.push({ act: 'publish', clause: around(clause.source, name), word: name, why: `\`${name}\` is a release tool that publishes`, rewrite: tool.dry.length > 0 ? `run it with ${tool.dry[0]} first, or ask the owner` : 'ask the owner' });
675
+ // @implements A-SPEC-794.147 (item 8) — a forge names its release subcommand
676
+ const why = tool.label !== undefined ? `\`${name} ${tool.label(args)}\` writes a release` : `\`${name}\` is a release tool that publishes`;
677
+ run.findings.push({ act: 'publish', clause: around(clause.source, name), word: name, why, rewrite: tool.dry.length > 0 ? `run it with ${tool.dry[0]} first, or ask the owner` : 'ask the owner' });
671
678
  }
672
679
  /** A write rule's verdict for a subcommand's remaining words: the writing word, null (reads), or undefined (no rule). */
673
680
  function writeOf(rule, rest) {
@@ -0,0 +1,41 @@
1
+ /** @implements A-SPEC-794.136 — the one lockfile list (the hook reads it; B-M3). */
2
+ export declare const LOCKFILES: readonly string[];
3
+ export interface PackageCtx {
4
+ /** The `name` of the package.json at a path word, read in the command's directory; null when it cannot be read. */
5
+ nameAt?: (word: string) => string | null;
6
+ /** The governing holmes-kit's version: a named version strictly higher than it stays free. */
7
+ current?: string;
8
+ /** @implements A-SPEC-794.142 (item 6) — the package.json text of a directory, so pkg set judges the entry it replaces. */
9
+ readManifest?: (dir: string) => string | null;
10
+ /** A-SPEC-794.149 — tests only: the work budget in place of the length-based one (the hook never sets it). */
11
+ workBudget?: number;
12
+ /** A-SPEC-794.152 — tests and measurement only: FREE_COPY in place of PACKAGE_FREE_COPY (the hook never sets it). */
13
+ freeCopy?: number;
14
+ }
15
+ /**
16
+ * @implements A-SPEC-794.144 — the comment rule of the shell that reads the text, chosen by the re-read wrapper: `posix`
17
+ * for the tool's own command and `bash -c`/`eval` bodies; `cmd` for a `cmd /c|/k` body (`#` is text; `REM` or `::` at
18
+ * the head of a command comments out the rest of its line, `&` included); `powershell` for a `powershell|pwsh` body
19
+ * (`#` at a word start to the line end, and `<# … #>` block comments, across lines).
20
+ */
21
+ export type CommentRule = 'posix' | 'cmd' | 'powershell';
22
+ /** @implements A-SPEC-794.148 — how many readings holmesPackageAct has judged (for the linear test; no behavior). */
23
+ export declare const packageReadingCount: () => number;
24
+ /** @implements A-SPEC-794.152 — words one copy or scan takes without charge (measured: see the release draft). */
25
+ export declare const PACKAGE_FREE_COPY = 1024;
26
+ export declare const packageWorkCount: () => number;
27
+ /** @implements A-SPEC-794.150 — how many words the wrapper loop has copied (for the linear test; no behavior). */
28
+ export declare const packageCopyCount: () => number;
29
+ export declare function holmesPackageAct(command: string, ctx?: PackageCtx, depth?: number, comments?: CommentRule): string | null;
30
+ /** Whether a write to `file` removes, lowers or swaps how holmes-kit resolves in a manifest or lockfile. */
31
+ export declare function manifestHolmesChange(file: string, before: string | null, after: string | null, current?: string): boolean;
32
+ /**
33
+ * @implements A-SPEC-794.136 (A-M1), A-SPEC-794.137, A-SPEC-794.139 (decision 6, unchanged) — a shell write over a
34
+ * manifest or lockfile whose text names holmes-kit: the act's name, or null. A shell write cannot be read, so the file's
35
+ * present text decides. `readText` reads a word as the shell resolves it in this segment (null: absent or unreadable).
36
+ * Write signals: an output redirect, `tee`, `sed|perl|ruby -i`, `awk -i inplace`, and the destinations of `cp`, `mv`,
37
+ * `install`, `dd of=`, `truncate`, `rm`.
38
+ */
39
+ export declare function shellManifestWrite(command: string, readText: (word: string) => string | null): string | null;
40
+ /** @implements A-SPEC-794.136 — whether a file name is a manifest or lockfile the holmes-kit entry can live in. */
41
+ export declare function isManifestName(file: string): boolean;