@holmes-lab/holmes-kit 0.40.1 → 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 (82) hide show
  1. package/CHANGELOG.md +78 -0
  2. package/README.md +11 -3
  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 +371 -250
  10. package/dist/holmes/cli/init.js +17 -6
  11. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  12. package/dist/holmes/cli/ledger-witness.js +212 -0
  13. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  14. package/dist/holmes/cli/playbook-skills.js +26 -349
  15. package/dist/holmes/config/config.d.ts +4 -0
  16. package/dist/holmes/config/config.js +10 -3
  17. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  18. package/dist/holmes/governance/approval-queue.js +279 -9
  19. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  20. package/dist/holmes/governance/autonomous-shell.js +157 -4
  21. package/dist/holmes/governance/autonomy.d.ts +209 -0
  22. package/dist/holmes/governance/autonomy.js +1127 -6
  23. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  24. package/dist/holmes/governance/install-manifest.js +144 -14
  25. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  26. package/dist/holmes/governance/ledger-witness.js +296 -0
  27. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  28. package/dist/holmes/governance/provenance-chain.js +23 -4
  29. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  30. package/dist/holmes/governance/recorded-pairs.js +25 -1
  31. package/dist/holmes/governance/session-context.d.ts +7 -0
  32. package/dist/holmes/governance/session-context.js +34 -6
  33. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  34. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  35. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  36. package/dist/holmes/guardrail/command-traits.js +379 -0
  37. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  38. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  39. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  40. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  41. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  42. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  43. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  44. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  45. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  46. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  47. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  48. package/dist/holmes/guardrail/write-target.js +7 -1
  49. package/dist/holmes/hooks/pre-tool-use.d.ts +60 -0
  50. package/dist/holmes/hooks/pre-tool-use.js +1423 -10
  51. package/dist/holmes/hooks/session-start.js +11 -1
  52. package/dist/holmes/hooks/stop.d.ts +7 -0
  53. package/dist/holmes/hooks/stop.js +39 -2
  54. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  55. package/dist/holmes/mcp/elicit-approval.js +5 -2
  56. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  57. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  58. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  59. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  60. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  61. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  62. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  63. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  64. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  65. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  66. package/dist/holmes/mcp/handlers/test-execution.js +4 -2
  67. package/dist/holmes/mcp/handlers.d.ts +5 -5
  68. package/dist/holmes/mcp/handlers.js +2 -1
  69. package/dist/holmes/mcp/tool-schemas.js +4 -4
  70. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  71. package/dist/holmes/project/playbook-reference.js +259 -0
  72. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  73. package/dist/holmes/project/playbook-skill-states.js +396 -0
  74. package/dist/holmes/project/root.d.ts +9 -1
  75. package/dist/holmes/project/root.js +23 -2
  76. package/dist/holmes/project/running-package.d.ts +15 -0
  77. package/dist/holmes/project/running-package.js +87 -0
  78. package/dist/holmes/review/test-runner.d.ts +2 -0
  79. package/dist/holmes/review/test-runner.js +27 -10
  80. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  81. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  82. package/package.json +5 -2
@@ -1,6 +1,214 @@
1
1
  import { Spec } from '../spec/spec-parser';
2
2
  export declare const AUTONOMY_ENV = "HOLMES_AUTONOMOUS_APPROVAL";
3
3
  export type ApprovalAutonomy = 'auto' | 'hitl';
4
+ /**
5
+ * @implements A-SPEC-794.88 — the seed judgements of principle 7 (design §3-7, M2): a module that imports or defines one
6
+ * reads or writes a grant, an actor, a seal or a decision, so it is in the category. The census test reads this list.
7
+ */
8
+ export declare const PRINCIPLE7_SEEDS: readonly string[];
9
+ /**
10
+ * @implements A-SPEC-794.88 — the category path a spec's scope names: an A-SPEC's own Files to Touch, a REQ's or an
11
+ * H-SPEC's A-SPECs beneath it; null when none. A T-SPEC is not judged here: its A-SPEC already went to a person.
12
+ */
13
+ export declare function principle7Category(spec: Spec, descendants?: Spec[]): string | null;
14
+ /** @implements A-SPEC-794.91 (N2) — the refusal a principle 7 write gets without a person-sealed spec naming the file. */
15
+ export declare const PRINCIPLE7_WRITE_REFUSAL = "a gate or approval-processing file is written only under a person-sealed spec that names it";
16
+ export declare const PRINCIPLE7_DIST_REFUSAL = "dist/ is written by the build (npm run build), not by Edit or Write";
17
+ /**
18
+ * @implements A-SPEC-794.91 (N2) — a file whose write principle 7 binds: Holmes-Kit's own gate source (a high-risk path
19
+ * under src/), its built gate (dist/holmes/) and its launchers (bin/holmes-*). Configuration paths (.claude, .ax/roles,
20
+ * .mcp.json) keep their own gates.
21
+ */
22
+ export declare function principle7WriteTarget(relPath: string, opts?: {
23
+ ownRepo?: boolean;
24
+ }): 'source' | 'dist' | null;
25
+ /**
26
+ * @implements A-SPEC-794.91 (N2; round 2, reviews A-M2 and B-H2) — the approved A-SPECs whose current seal a person made:
27
+ * a trusted `spec-approved` event names the spec and its current digest, and its actor is a person channel the mint writes
28
+ * (human-channel.ts, the one judgement: `elicitation:` or `host-gated:`). An allow-list: autonomous-timeout, a plain name
29
+ * (an environment approval names its actor freely, and no row records a grant nonce) and any new agent prefix do not
30
+ * count. The caller passes trusted events only, so a claimed channel written as `unattested:` never arrives.
31
+ */
32
+ /**
33
+ * @implements A-SPEC-794.95 — a spec-approved row a person made: a person channel the mint writes (elicitation:,
34
+ * host-gated:), and nothing else. Round-2 review A (critical): a grant file can be written by a patch and spent by
35
+ * spec_approve, and the server cannot tell a grant the CLI minted behind operatorActGuard from one a file write made, so
36
+ * a `channel:cli-terminal` row (still recorded, for audit) is not a person's seal. Proving a grant's origin from the
37
+ * ledger (a trusted granted row of the same nonce by a minted decider) is a 0.42 candidate.
38
+ */
39
+ export declare function isPersonSealRow(e: {
40
+ kind?: string;
41
+ actor?: unknown;
42
+ inputs?: unknown;
43
+ }): boolean;
44
+ /**
45
+ * @implements A-SPEC-794.95 (H1 = D2) — the approved A-SPECs a person's seal opens now: the latest person seal of the
46
+ * spec's current digest, timed by the ledger (the server's ts, never git's or the file system's), no older than `hours`
47
+ * and not in the future. Each open spec maps to that seal's time and actor.
48
+ */
49
+ export declare function openSealWindows(specs: ReadonlyArray<Spec>, events: ReadonlyArray<{
50
+ kind?: string;
51
+ actor?: unknown;
52
+ inputs?: unknown;
53
+ ts?: string;
54
+ }>, nowMs: number, hours: number): Map<string, {
55
+ ts: string;
56
+ actor: string;
57
+ }>;
58
+ type LedgerRow = {
59
+ kind?: string;
60
+ actor?: unknown;
61
+ inputs?: unknown;
62
+ ts?: string;
63
+ };
64
+ /** A-SPEC-794.113 — the one entry of a verdict that could not be reached because git cannot read the repository. */
65
+ export declare const PRINCIPLE7_GIT_UNREADABLE = "(git cannot read this repository)";
66
+ /** A-SPEC-794.113 — the one entry of a verdict closed because the latest baseline's commit is not in the repository. */
67
+ export declare const PRINCIPLE7_BASELINE_LOST = "(the baseline commit is not in this repository)";
68
+ /** A-SPEC-794.114 — the marker of a closed verdict: this writer's chain is not the one this repository wrote. */
69
+ export declare const PRINCIPLE7_WITNESS = "(the provenance ledger is not the one this repository wrote)";
70
+ /**
71
+ * @implements A-SPEC-794.114 — the witness verdict of this writer's own chain (governance/ledger-witness.ts): the one
72
+ * computation the principle 7 judgement, the record and the skills' reference read.
73
+ */
74
+ export declare function ownChainWitness(root: string): import('./ledger-witness').WitnessVerdict;
75
+ /** A-SPEC-794.113 — the longest a person's seal opens a window, whatever `autonomy.sealWindowHours` says. */
76
+ export declare const SEAL_WINDOW_MAX_HOURS = 12;
77
+ /**
78
+ * The environment of principle 7's git reads: the caller's without any inherited GIT_* variable but the two `gitEnv`
79
+ * keeps (one source, A-SPEC-792.42), with the judgment's own pins — no replace objects, no graft file, no prompt.
80
+ * A-SPEC-794.113.
81
+ */
82
+ export declare function principle7GitEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
83
+ /** A-SPEC-794.113 (review B, medium 3) — why a git read failed: it did not answer in time, git is not there, or git refused. */
84
+ export type GitFailure = {
85
+ kind: 'timeout' | 'missing' | 'refused';
86
+ detail: string;
87
+ };
88
+ export declare function gitFailureOf(e: unknown): GitFailure;
89
+ /**
90
+ * @implements A-SPEC-794.97 — the live gate's baseline: the commit of the latest trusted `principle7-baseline` row (the
91
+ * gate records one when it allows a build with no unopened gate change). The ledger is protected, so the baseline cannot
92
+ * be moved by a file write (dist/.build-id is not read: a shell write could move it). No row at all (a new clone or
93
+ * worktree): HEAD stands in, `known` is false and the hook's first-baseline rule decides the build. A latest row whose
94
+ * commit this repository does not hold: `lost` — nothing stands in (A-SPEC-794.113).
95
+ */
96
+ export interface Principle7Base {
97
+ commit: string;
98
+ known: boolean;
99
+ /** A-SPEC-794.97 r4b (L3) — how many baseline rows the ledger holds: 0 is a new clone or worktree, more with `known`
100
+ * false is a recorded commit this repository no longer holds. */
101
+ recorded: number;
102
+ /** A-SPEC-794.113 — the latest baseline row's commit this repository does not hold (no older row stands in). */
103
+ lost?: {
104
+ commit: string;
105
+ ts: string;
106
+ };
107
+ }
108
+ /**
109
+ * @implements A-SPEC-794.97 r4b (L5) — Holmes-Kit's own repository, where principle 7 applies: the one judgement.
110
+ * @implements A-SPEC-794.111 — the checkout the running gate is built from, read from the running package's real path.
111
+ * It was "a directory src/holmes exists under the root", which one shell line the hook allows (`mv src/holmes src/h2`)
112
+ * turned false, and with it the write judgement, the commit judgement and Stop (measured 2026-11-12). The module is
113
+ * read through its object at call time, and nothing here can be set (A-SPEC-794.112).
114
+ */
115
+ export declare function isHolmesKitOwnRepo(root: string): boolean;
116
+ export declare function principle7Baseline(root: string, events: ReadonlyArray<LedgerRow>): Principle7Base | null;
117
+ /**
118
+ * @implements A-SPEC-794.96, A-SPEC-794.97 — the principle 7 files changed since `base`: committed, staged and unstaged
119
+ * (`git diff --name-only <base>`, which also sees a file hidden with --skip-worktree) and untracked; the harness's runtime
120
+ * state excluded. Null when git cannot answer.
121
+ */
122
+ export declare function principle7Changes(root: string, base: string): string[] | null;
123
+ /**
124
+ * @implements A-SPEC-794.97 r4 (medium-2) — with no baseline, the first one is recorded only when every principle 7 file
125
+ * the commits made since the oldest open window changed is named by an open window: the files no window names.
126
+ */
127
+ export declare function principle7FirstBaselineGaps(root: string, ctx: Principle7Context): string[];
128
+ /** The window judgement's context, built once per judgement (B-M2: per-file reloads made 281 files take 18.6 s). */
129
+ export interface Principle7Context {
130
+ specs: ReadonlyArray<Spec>;
131
+ events: ReadonlyArray<LedgerRow>;
132
+ hours: number;
133
+ open: Map<string, {
134
+ ts: string;
135
+ actor: string;
136
+ }>;
137
+ blobs: Map<string, Set<string>>;
138
+ /** A-SPEC-794.113 — the trusted read failed: the rows are unknown, not absent. */
139
+ unread?: boolean;
140
+ }
141
+ export declare function principle7Context(root: string, specs: ReadonlyArray<Spec>, nowMs: number): Principle7Context;
142
+ /** @implements A-SPEC-794.95–794.97 — the open windows whose spec names `rel`, over a context built once. */
143
+ export declare function principle7OpenersIn(ctx: Principle7Context, rel: string): Array<{
144
+ id: string;
145
+ ts: string;
146
+ actor: string;
147
+ }>;
148
+ /** The single-file form the file tools use (the ledger read only when an approved A-SPEC could name the file). */
149
+ export declare function principle7OpenersFor(root: string, specs: ReadonlyArray<Spec>, nowMs: number, rel: string): {
150
+ openers: Array<{
151
+ id: string;
152
+ ts: string;
153
+ actor: string;
154
+ }>;
155
+ events: ReadonlyArray<LedgerRow>;
156
+ hours: number;
157
+ };
158
+ /**
159
+ * @implements A-SPEC-794.96, A-SPEC-794.97 — the one judgement Stop, commit and build read: every principle 7 file changed
160
+ * since the baseline, split into those an open window names now (`byWindow`, with their current blob, to be recorded),
161
+ * those whose current blob a window recorded before (open), and the rest (`unopened`). Null where nothing is judged (no
162
+ * src/holmes, git or the baseline unreadable).
163
+ */
164
+ export type Principle7Verdict = {
165
+ unopened: string[];
166
+ byWindow: Array<{
167
+ file: string;
168
+ id: string;
169
+ ts: string;
170
+ blob: string;
171
+ }>;
172
+ base: Principle7Base;
173
+ ctx: Principle7Context;
174
+ headSeen: string[];
175
+ localOnly: string[];
176
+ /** A-SPEC-794.113 — playbooks an open person's window names whose bytes are not the recorded reference's: to be recorded as seen. */
177
+ playbooks?: Array<{
178
+ file: string;
179
+ id: string;
180
+ ts: string;
181
+ sha256: string;
182
+ }>;
183
+ };
184
+ export declare function principle7Verdict(root: string, specs: ReadonlyArray<Spec>, nowMs: number): Principle7Verdict | null;
185
+ /**
186
+ * @implements A-SPEC-794.97 — the content a window saw: one `principle7-window-blob` row per (file, spec, seal, blob) not
187
+ * yet recorded, written where a judgement passes because a window was open (Stop, commit, build).
188
+ */
189
+ export declare function recordWindowBlobs(root: string, nowIso: string, v: Principle7Verdict): void;
190
+ /**
191
+ * @implements A-SPEC-794.97 r4b (M1, L2, L3, L4) — the warning comes before any restore (a restore from the baseline also
192
+ * discards commits made after it: a pull, an owner's terminal commit, a branch switch); the exits are a person's seal,
193
+ * undoing the branch switch or the pull, restoring from HEAD where a window saw HEAD's content, and making the file equal
194
+ * to the baseline; at most 20 files are listed; a new clone and a lost baseline commit are told apart.
195
+ */
196
+ export declare function principle7RefusalText(unopened: string[], base: Principle7Base, opts?: {
197
+ headSeen?: string[];
198
+ localOnly?: string[];
199
+ }): string;
200
+ /**
201
+ * @implements A-SPEC-794.97 — the live gate's baseline moves to HEAD; only the gate's allowed build records it.
202
+ * @implements A-SPEC-794.110 — the same row carries the sha256 of every playbook in the working tree the gate has just
203
+ * judged (playbooks/ is a principle 7 path, so an unopened playbook change refused the build before this): the recovery
204
+ * skills' reference, as values in the ledger instead of git objects a ref move or a gc changes.
205
+ */
206
+ export declare function recordBaseline(root: string, nowIso: string): void;
207
+ /**
208
+ * @implements A-SPEC-794.91 (M-b) — a root-level token that is project-wide configuration: any root file but a Markdown
209
+ * document, and of those the agent instruction files (AGENTS.md, CLAUDE.md, GEMINI.md) are configuration too.
210
+ */
211
+ export declare function rootConfigToken(token: string): boolean;
4
212
  export declare function isHighRiskPath(p: string): boolean;
5
213
  /**
6
214
  * The autonomy verdict for approving THIS spec. `resolveParent` is accepted for future
@@ -79,3 +287,4 @@ export declare function autonomyBanner(env: NodeJS.ProcessEnv, root: string, now
79
287
  export declare function autonomyMarkerShouldPrune(root: string, now: string): boolean;
80
288
  export declare function versionBumpKind(from: string, to: string): 'major' | 'minor' | 'patch' | 'none';
81
289
  export declare function releaseAutonomy(specs: Spec[], versionBump: 'major' | 'minor' | 'patch' | 'none', env: NodeJS.ProcessEnv, root?: string, now?: string): ApprovalAutonomy;
290
+ export {};