@holmes-lab/holmes-kit 0.40.0 → 0.41.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 (119) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +79 -5
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-context.js +4 -3
  5. package/dist/holmes/cli/approve.js +22 -12
  6. package/dist/holmes/cli/autonomy.d.ts +21 -0
  7. package/dist/holmes/cli/autonomy.js +35 -5
  8. package/dist/holmes/cli/doctor.js +58 -6
  9. package/dist/holmes/cli/index.js +394 -267
  10. package/dist/holmes/cli/init.js +17 -6
  11. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  12. package/dist/holmes/cli/interactive-prompt.js +98 -16
  13. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  14. package/dist/holmes/cli/ledger-witness.js +212 -0
  15. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  16. package/dist/holmes/cli/playbook-skills.js +26 -349
  17. package/dist/holmes/config/config.d.ts +21 -0
  18. package/dist/holmes/config/config.js +22 -3
  19. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  20. package/dist/holmes/governance/approval-queue.js +279 -9
  21. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  22. package/dist/holmes/governance/autonomous-shell.js +157 -4
  23. package/dist/holmes/governance/autonomy.d.ts +216 -0
  24. package/dist/holmes/governance/autonomy.js +1162 -10
  25. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  26. package/dist/holmes/governance/install-manifest.js +144 -14
  27. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  28. package/dist/holmes/governance/ledger-witness.js +296 -0
  29. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  30. package/dist/holmes/governance/provenance-chain.js +23 -4
  31. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  32. package/dist/holmes/governance/push-gate-runner.js +40 -3
  33. package/dist/holmes/governance/push-gate.d.ts +13 -2
  34. package/dist/holmes/governance/push-gate.js +106 -14
  35. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  36. package/dist/holmes/governance/recorded-pairs.js +25 -1
  37. package/dist/holmes/governance/session-context.d.ts +7 -0
  38. package/dist/holmes/governance/session-context.js +34 -6
  39. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  40. package/dist/holmes/guardrail/advisory-line.js +718 -0
  41. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  42. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  43. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  44. package/dist/holmes/guardrail/command-traits.js +379 -0
  45. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  46. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  47. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  48. package/dist/holmes/guardrail/impact-gate.js +32 -5
  49. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  50. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  51. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  52. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  53. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  54. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  55. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  56. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  57. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  58. package/dist/holmes/guardrail/write-target.js +7 -1
  59. package/dist/holmes/hooks/pre-tool-use.d.ts +71 -0
  60. package/dist/holmes/hooks/pre-tool-use.js +1466 -14
  61. package/dist/holmes/hooks/session-start.js +27 -1
  62. package/dist/holmes/hooks/stop.d.ts +7 -0
  63. package/dist/holmes/hooks/stop.js +39 -2
  64. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  65. package/dist/holmes/mcp/elicit-approval.js +5 -2
  66. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  67. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  68. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  69. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  70. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  71. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  72. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  73. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  74. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  75. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  76. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  77. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  78. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  79. package/dist/holmes/mcp/handlers/test-execution.js +201 -21
  80. package/dist/holmes/mcp/handlers.d.ts +473 -8
  81. package/dist/holmes/mcp/handlers.js +6 -1
  82. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  83. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  84. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  85. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  86. package/dist/holmes/mcp/tool-schemas.js +16 -10
  87. package/dist/holmes/project/baseline.d.ts +15 -2
  88. package/dist/holmes/project/baseline.js +11 -6
  89. package/dist/holmes/project/bounded-io.d.ts +1 -0
  90. package/dist/holmes/project/bounded-io.js +4 -2
  91. package/dist/holmes/project/change-source.d.ts +4 -0
  92. package/dist/holmes/project/change-source.js +13 -5
  93. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  94. package/dist/holmes/project/playbook-reference.js +259 -0
  95. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  96. package/dist/holmes/project/playbook-skill-states.js +396 -0
  97. package/dist/holmes/project/root.d.ts +9 -1
  98. package/dist/holmes/project/root.js +26 -3
  99. package/dist/holmes/project/running-package.d.ts +15 -0
  100. package/dist/holmes/project/running-package.js +87 -0
  101. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  102. package/dist/holmes/review/evidence-mode.js +33 -0
  103. package/dist/holmes/review/head-worktree.d.ts +55 -0
  104. package/dist/holmes/review/head-worktree.js +329 -0
  105. package/dist/holmes/review/mrp.js +13 -3
  106. package/dist/holmes/review/run-provenance.d.ts +45 -0
  107. package/dist/holmes/review/run-provenance.js +314 -0
  108. package/dist/holmes/review/test-evidence.d.ts +174 -0
  109. package/dist/holmes/review/test-evidence.js +330 -2
  110. package/dist/holmes/review/test-reports.d.ts +94 -0
  111. package/dist/holmes/review/test-reports.js +382 -0
  112. package/dist/holmes/review/test-runner.d.ts +178 -65
  113. package/dist/holmes/review/test-runner.js +551 -319
  114. package/dist/holmes/review/test-units.d.ts +159 -0
  115. package/dist/holmes/review/test-units.js +814 -0
  116. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  117. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  118. package/package.json +5 -2
  119. package/playbooks/publish/PLAYBOOK.md +2 -1
@@ -4,6 +4,7 @@ import { Approval } from '../guardrail/risk-gate';
4
4
  import { GrantSettlement, type GrantSettlementPending, type GrantSettlementResult } from '../governance/approval-grants';
5
5
  import { RiskAction, RiskAssessment, RmSignal, StagedStoreSignal } from '../guardrail/risk-types';
6
6
  import { type PreEditEvidenceMode } from '../guardrail/impact-gate';
7
+ import { type AdvisoryContext } from '../guardrail/advisory-line';
7
8
  export declare function resolveRmSignals(command: string, cwd: string, projectRoot?: string, specsDir?: string, scratchTmpdir?: string): Record<string, RmSignal> | undefined;
8
9
  /**
9
10
  * @implements A-SPEC-226.3 — what `git status` says about the spec store, for a command that holds a staging verb. One
@@ -31,6 +32,66 @@ export declare function readApprovalFromEnv(): Approval | undefined;
31
32
  * the empty word as its suffix. Words are read quote-aware; an operand that is only a glob or a variable still counts.
32
33
  */
33
34
  export declare function sedInPlaceFiles(text: string): string[];
35
+ /**
36
+ * @implements A-SPEC-794.95 (A-M1) — the paths a git command writes from git's own store: `checkout [<tree>] [--] <paths>`
37
+ * and `restore [--source X] <paths>` (their path arguments), `apply <patch>` (the patch's `+++ b/` and `diff --git`
38
+ * targets), `stash pop|apply [<ref>]` (git's own list of the stash's files). Null when the command runs none of them;
39
+ * `unreadable` when a patch or a stash cannot be listed (the caller refuses in a repository with principle 7 paths).
40
+ */
41
+ export declare function gitStoreWrites(command: string, root: string): string[] | 'unreadable' | null;
42
+ /**
43
+ * @implements A-SPEC-794.113 — what the reference judgements read and the session has no business writing:
44
+ * - the repository's object store (`objects`, with `info/alternates` and the packs) and the `.git` entry itself — git's
45
+ * comparison of tree objects is what principle 7's working-tree judgement trusts, and nothing but git writes them
46
+ * (measured 2026-11-12: a copy, a move, an interpreter write and the Write tool there, `mv .git …` and `.git` replaced by
47
+ * a file were all allowed);
48
+ * - the files of the running package when it is deployed — its playbooks are the recovery skills' reference and its dist
49
+ * is the gate (review A, H-C: the playbooks were writable; measured while building this: a shell write to the dist was
50
+ * too, and so was the Write tool for a package outside the project).
51
+ * Judged where the write lands — the written path and its real path, so a link, `..`, a doubled slash and another case on
52
+ * a file system that folds case do not change the answer. Null when the path is none of these. The repository is the one
53
+ * the root is in (the nearest `.git` at or above it); for a linked worktree, the store of the repository it belongs to.
54
+ */
55
+ export declare function referenceInputWrite(projectRoot: string, written: string): ReferenceInput | null;
56
+ /**
57
+ * What a write is refused as: the repository's store (`git`), the deployed package that governs the session (`package`),
58
+ * or the runtime that dispatches every hook (`runtime`: `~/.holmes/runtime` — the registry `bindings.json` that says which
59
+ * build governs which workspace, and the launchers the harness settings run). Supervisor decision 11-12: the runtime was
60
+ * writable from any governed session (the Write tool and the shell; measured), so every rule after it could be turned off.
61
+ */
62
+ export type ReferenceInput = 'git' | 'package' | 'runtime';
63
+ /**
64
+ * The judgement for one hook call: what is protected is found once, and a real path is looked up once per directory —
65
+ * a command naming one destination 20,000 times, or thousands of files of one directory, must not cost a file-system
66
+ * walk each (the hook's 2-second bound on a 120 KB command; measured 7.4 s before this).
67
+ */
68
+ export declare function referenceInputJudge(projectRoot: string, home?: string): (written: string) => ReferenceInput | null;
69
+ export declare function governedCliAct(command: string, depth?: number): {
70
+ act: string;
71
+ } | {
72
+ unjudged: string;
73
+ } | null;
74
+ /**
75
+ * @implements A-SPEC-794.96 (S2, S3) — a `git commit` (its staged principle 7 changes; with -a, its tracked ones too) and a
76
+ * build command from one table (npm, pnpm, yarn `run build` or `build`; tsc; npx tsc) are judged against the working
77
+ * tree; null when the command is neither. An unfamiliar build spelling is a named limit.
78
+ */
79
+ export declare function commitOrBuildOf(command: string, root?: string): 'commit' | 'commit-all' | 'build' | 'build-after-move' | null;
80
+ /**
81
+ * @implements A-SPEC-794.97 r4 (high-1, high-2) — git writes the principle 7 judgement must not lose sight of: a
82
+ * replacement object (`git replace`, a refs/replace ref), which makes the baseline read as another commit, and the index
83
+ * entries of a category file (update-index: --cacheinfo, --assume-unchanged, --skip-worktree, --index-info). Null when none.
84
+ */
85
+ export declare function gitHiddenWriteOf(command: string, root: string): string | null;
86
+ /**
87
+ * @implements A-SPEC-794.91 (L-b) — whether a clause of the command widens autonomy, read by words per clause with the
88
+ * shell lexer (quotes, escapes and line continuations resolved by it; case folded). A clause counts when it holds the word
89
+ * `autonomy` and, after it, a word full|on|delegate or a first non-option word the gate cannot read statically (`$S`,
90
+ * `$'…'`); or when a word it cannot read statically ends in `nomy` (`${A}nomy`). The program is not required: an alias
91
+ * (`hk`) runs the same CLI. An `on` in another clause is not read; a command the lexer cannot read keeps the 794.89
92
+ * reading over the whole text (fail-closed).
93
+ */
94
+ export declare function runsAutonomyWidening(command: string): boolean;
34
95
  /**
35
96
  * @implements A-SPEC-245.9 (1b-5, item 7) — `holmes-kit lock recover` retires a lock another process may hold: the
36
97
  * operator's act. The CLI refuses it from an agent by the environment and the process ancestry, which a process
@@ -179,6 +240,8 @@ export interface HookInput {
179
240
  cwd?: string;
180
241
  /** @implements A-SPEC-774.9 — the harness session id, so a run record can bind the session itself. */
181
242
  session_id?: string;
243
+ /** @implements A-SPEC-333.1 — the subagent the harness names, so a parent's first sighting is not a subagent's. */
244
+ agent_id?: string;
182
245
  /**
183
246
  * @implements A-SPEC-163
184
247
  * The raw payload carried a path field that was NOT a string, or `tool_input` was not an object.
@@ -254,6 +317,11 @@ export declare function preEditEvidenceGate(o: {
254
317
  mode: PreEditEvidenceMode;
255
318
  declaredDigest: string | null;
256
319
  currentHead: string;
320
+ /**
321
+ * @implements A-SPEC-333.1, A-SPEC-333.2 — who is reading, and where the records of what was said wait for the final decision.
322
+ * Without it (no session, a counterfactual re-ask) every warning is said in full and nothing is read or recorded.
323
+ */
324
+ advisory?: AdvisoryContext;
257
325
  }): {
258
326
  permissionDecision: 'allow' | 'deny';
259
327
  permissionDecisionReason?: string;
@@ -349,6 +417,7 @@ declare function judgeHook(input: {
349
417
  };
350
418
  cwd?: string;
351
419
  session_id?: string;
420
+ agent_id?: string;
352
421
  }, specsDir: string, opts: {
353
422
  assess?: (a: RiskAction) => RiskAssessment;
354
423
  /**
@@ -387,6 +456,8 @@ declare function judgeHook(input: {
387
456
  autonomySpecStaging?: boolean;
388
457
  /** @implements A-SPEC-245.4 — where this judgement holds the grants it resolved; the caller settles it once. */
389
458
  settlement?: GrantSettlement;
459
+ /** @implements A-SPEC-333.2 — the decision being made, never a counterfactual re-ask: what its warnings may record. */
460
+ advisory?: AdvisoryContext;
390
461
  filed?: {
391
462
  request?: string;
392
463
  };