@holmes-lab/holmes-kit 0.40.1 → 0.41.1

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 (88) hide show
  1. package/CHANGELOG.md +86 -0
  2. package/README.md +12 -4
  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 +26 -6
  11. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  12. package/dist/holmes/cli/ledger-witness.js +252 -0
  13. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  14. package/dist/holmes/cli/playbook-skills.js +63 -354
  15. package/dist/holmes/cli/test-platform.d.ts +6 -0
  16. package/dist/holmes/cli/test-platform.js +12 -0
  17. package/dist/holmes/config/config.d.ts +9 -1
  18. package/dist/holmes/config/config.js +10 -3
  19. package/dist/holmes/governance/approval-grants.d.ts +2 -0
  20. package/dist/holmes/governance/approval-grants.js +6 -5
  21. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  22. package/dist/holmes/governance/approval-queue.js +279 -9
  23. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  24. package/dist/holmes/governance/autonomous-shell.js +157 -4
  25. package/dist/holmes/governance/autonomy.d.ts +209 -0
  26. package/dist/holmes/governance/autonomy.js +1129 -6
  27. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  28. package/dist/holmes/governance/install-manifest.js +159 -15
  29. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  30. package/dist/holmes/governance/ledger-witness.js +296 -0
  31. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  32. package/dist/holmes/governance/provenance-chain.js +23 -4
  33. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  34. package/dist/holmes/governance/recorded-pairs.js +25 -1
  35. package/dist/holmes/governance/session-context.d.ts +7 -0
  36. package/dist/holmes/governance/session-context.js +34 -6
  37. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  38. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  39. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  40. package/dist/holmes/guardrail/command-traits.js +379 -0
  41. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  42. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  43. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  44. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  45. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  46. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  47. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  48. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  49. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  50. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  51. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  52. package/dist/holmes/guardrail/write-target.js +7 -1
  53. package/dist/holmes/hooks/pre-tool-use.d.ts +60 -0
  54. package/dist/holmes/hooks/pre-tool-use.js +1423 -10
  55. package/dist/holmes/hooks/session-start.js +11 -1
  56. package/dist/holmes/hooks/stop.d.ts +7 -0
  57. package/dist/holmes/hooks/stop.js +39 -2
  58. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  59. package/dist/holmes/mcp/elicit-approval.js +5 -2
  60. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  61. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  62. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  63. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  64. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  65. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  66. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  67. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  68. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  69. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  70. package/dist/holmes/mcp/handlers/test-execution.d.ts +6 -0
  71. package/dist/holmes/mcp/handlers/test-execution.js +37 -9
  72. package/dist/holmes/mcp/handlers.d.ts +5 -5
  73. package/dist/holmes/mcp/handlers.js +2 -1
  74. package/dist/holmes/mcp/tool-schemas.js +4 -4
  75. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  76. package/dist/holmes/project/playbook-reference.js +259 -0
  77. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  78. package/dist/holmes/project/playbook-skill-states.js +396 -0
  79. package/dist/holmes/project/root.d.ts +9 -1
  80. package/dist/holmes/project/root.js +23 -2
  81. package/dist/holmes/project/running-package.d.ts +15 -0
  82. package/dist/holmes/project/running-package.js +87 -0
  83. package/dist/holmes/review/head-worktree.js +9 -1
  84. package/dist/holmes/review/test-runner.d.ts +2 -0
  85. package/dist/holmes/review/test-runner.js +38 -11
  86. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  87. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  88. package/package.json +5 -2
@@ -33,6 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.r1Problem = r1Problem;
36
37
  exports.governanceStagingOnly = governanceStagingOnly;
37
38
  exports.stagingGrammar = stagingGrammar;
38
39
  exports.autonomousShellVerdict = autonomousShellVerdict;
@@ -42,8 +43,112 @@ const crypto = __importStar(require("node:crypto"));
42
43
  const fs = __importStar(require("node:fs"));
43
44
  const path = __importStar(require("node:path"));
44
45
  const spec_parser_1 = require("../spec/spec-parser");
46
+ const scope_judgment_1 = require("../guardrail/scope-judgment"); // @implements A-SPEC-794.86
47
+ const autonomy_1 = require("./autonomy"); // @implements A-SPEC-794.89, A-SPEC-794.91
45
48
  const succession_1 = require("../spec/succession");
46
49
  const spec_seam_1 = require("./spec-seam");
50
+ /** @implements A-SPEC-794.86 — where R1 expects each type it covers: `<dir>/…/<id>.md` (an H-SPEC may sit in a sub-folder). */
51
+ const R1_DIR = { REQ: '01_req', 'H-SPEC': '02_h-spec', 'A-SPEC': '03_a-spec', 'T-SPEC': '05_t-spec' };
52
+ /**
53
+ * The A-SPEC's code scope is outside the gate category and not root-only, or why not.
54
+ * A-SPEC-794.89 — the category is principle 7's (one judgement with the R7 grader), and a root-only scope goes to a
55
+ * person as the grader's A-SPEC-654 rule does.
56
+ */
57
+ function r1ScopeProblem(a) {
58
+ const paths = (0, scope_judgment_1.fttPathTokens)(a.sections['Files to Touch'] ?? '');
59
+ if (paths.length === 0)
60
+ return `${a.id}'s Files to Touch names no path, so its scope is unbounded`;
61
+ const gate = (0, autonomy_1.principle7Category)(a);
62
+ if (gate !== null)
63
+ return `${a.id}'s Files to Touch names ${gate}, in the gate category (principle 7: a person reviews it)`;
64
+ if (!paths.some((p) => p.includes('/')))
65
+ return `${a.id}'s Files to Touch is root-only (project-wide configuration goes to a person)`;
66
+ // A-SPEC-794.91 (M-b) — one judgement with the grader: a root configuration file in the scope goes to a person
67
+ const cfg = paths.find(autonomy_1.rootConfigToken);
68
+ if (cfg !== undefined)
69
+ return `${a.id}'s Files to Touch names ${cfg}, a root-level configuration file (project-wide configuration goes to a person)`;
70
+ return null;
71
+ }
72
+ /**
73
+ * @implements A-SPEC-794.89 — every ancestor up to the REQ: in the store, approved, its seal holding, pinned by its child
74
+ * and named by a trusted spec-approved event with that digest. Null when the whole chain holds.
75
+ */
76
+ function r1ChainProblem(s, deps, events, seen) {
77
+ const pins = (s.frontmatter.parent_digests ?? {});
78
+ for (const id of s.dependsOn ?? []) {
79
+ if (seen.has(id))
80
+ continue;
81
+ seen.add(id);
82
+ const p = deps.specById?.(id) ?? null;
83
+ if (p === null)
84
+ return `${s.id}'s parent ${id} is not in the store`;
85
+ const d = p.frontmatter.approved_digest;
86
+ if (p.status !== 'approved' || !(0, succession_1.sealHolds)(p) || typeof d !== 'string')
87
+ return `${s.id}'s parent ${id} is not sealed`;
88
+ if (pins[id] !== d)
89
+ return `${s.id}'s parent ${id} is sealed as ${d}, not as ${s.id} pins it`;
90
+ if (!events.some((e) => e.kind === 'spec-approved' && inputsOf(e)[0] === id && inputsOf(e)[1] === d))
91
+ return `${s.id}'s parent ${id}: no trusted spec-approved event names its seal`;
92
+ const up = r1ChainProblem(p, deps, events, seen);
93
+ if (up !== null)
94
+ return up;
95
+ }
96
+ return null;
97
+ }
98
+ /**
99
+ * @implements A-SPEC-794.86 — R1 sealed-spec-staging: a staged spec is approved without a person only when its approval
100
+ * chain is unbroken and its scope is outside the gate category. The seal itself is the prover's (the seal holds and a
101
+ * trusted spec-approved event names [id, digest]); this adds the chain and the scope. Null when R1 holds.
102
+ */
103
+ function r1Problem(rel, text, deps) {
104
+ let s;
105
+ try {
106
+ s = (0, spec_parser_1.parseSpec)(text);
107
+ }
108
+ catch {
109
+ return `${rel} is not a readable spec`;
110
+ }
111
+ if (s.status !== 'approved')
112
+ return `${s.id} is ${s.status}: R1 covers sealed specs only`;
113
+ const dir = R1_DIR[s.type];
114
+ if (dir === undefined)
115
+ return `${s.id} is a ${s.type}, which goes to a person`;
116
+ const parts = rel.split('/');
117
+ if (parts[2] !== dir || parts[parts.length - 1] !== `${s.id}.md` || (s.type !== 'H-SPEC' && parts.length !== 4)) {
118
+ return `${rel} is not where its type and id say (${dir}/${s.id}.md)`;
119
+ }
120
+ // A-SPEC-794.89 — an A-SPEC or T-SPEC hangs from a parent; the whole chain to the REQ holds
121
+ if ((s.type === 'A-SPEC' || s.type === 'T-SPEC') && (s.dependsOn ?? []).length === 0)
122
+ return `${s.id} has no parent, so its chain is not judged`;
123
+ const chain = r1ChainProblem(s, deps, deps.ledgerEvents(), new Set());
124
+ if (chain !== null)
125
+ return chain;
126
+ const parents = (s.dependsOn ?? []).map((id) => deps.specById?.(id) ?? null).filter((p) => p !== null);
127
+ if (s.type === 'A-SPEC')
128
+ return r1ScopeProblem(s);
129
+ // A-SPEC-794.91 (L-a) — a REQ or an H-SPEC is judged by the A-SPECs beneath it, as the seal path judges it
130
+ if (s.type === 'REQ' || s.type === 'H-SPEC') {
131
+ const beneath = (0, autonomy_1.descendantAspecs)(s, deps.allSpecs?.() ?? []);
132
+ if (beneath.length === 0)
133
+ return `${s.id} has no A-SPEC beneath it, so its scope is unknown (a person reviews it)`;
134
+ for (const a of beneath) {
135
+ const why = r1ScopeProblem(a);
136
+ if (why !== null)
137
+ return why;
138
+ }
139
+ }
140
+ if (s.type === 'T-SPEC') {
141
+ const aspecs = parents.filter((p) => p.type === 'A-SPEC');
142
+ if (aspecs.length === 0)
143
+ return `${s.id} depends on no A-SPEC, so its scope is unknown`;
144
+ for (const a of aspecs) {
145
+ const why = r1ScopeProblem(a);
146
+ if (why !== null)
147
+ return why;
148
+ }
149
+ }
150
+ return null;
151
+ }
47
152
  /** The classifier's two verdicts on staging the governance store (risk-classifier.ts; full-autonomy.ts reads the same). */
48
153
  const STAGING_REASONS = [/^staging command reaches changed files in the protected \.ax spec store/, /^shell command over a protected \.ax governance path is not recognisably read-only/];
49
154
  function governanceStagingOnly(reasons) {
@@ -250,13 +355,59 @@ function autonomousShellVerdict(input, deps) {
250
355
  // @implements A-SPEC-792.31 — last, so every other condition is still named as before: a spec path is out of scope
251
356
  // (A-SPEC-792.32: `specStaging` lifts the stop for the tests only; the gate sets it from no environment or config)
252
357
  const specsRel = (input.specsRel ?? '.ax/specs').replace(/\/+$/, '');
253
- const spec = governance.find((s) => s.path === specsRel || s.path.startsWith(`${specsRel}/`));
254
- if (spec && input.specStaging !== true)
358
+ const specs = governance.filter((s) => s.path === specsRel || s.path.startsWith(`${specsRel}/`));
359
+ const spec = specs[0];
360
+ // @implements A-SPEC-794.86 — the R1 row lifts the stop for a spec path whose chain and scope hold; off, it stands
361
+ if (spec && input.specStaging !== true && input.specRow !== 'on')
255
362
  return fail('scope', `${spec.path} is in the spec store, which autonomous approval does not cover; a person approves spec staging`);
256
- return { ok: true, paths: governance.map((s) => s.path).sort(), proven, conditions: { grammar: 'pass', reversible: 'pass', 'product-installed': 'pass', integrity: 'pass', provenance: 'pass' } };
363
+ if (spec && input.specStaging !== true) {
364
+ for (const s of specs) {
365
+ const bytes = deps.readBytes(s.path);
366
+ const why = bytes === null ? `${s.path} cannot be read` : r1Problem(s.path.replace(new RegExp(`^${specsRel.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/`), '.ax/specs/'), bytes.toString('utf8'), deps);
367
+ if (why !== null)
368
+ return fail('scope', `${s.path}: R1 (sealed-spec staging) does not hold — ${why}; a person approves this staging`);
369
+ }
370
+ }
371
+ return { ok: true, paths: governance.map((s) => s.path).sort(), proven,
372
+ conditions: { grammar: 'pass', reversible: 'pass', 'product-installed': 'pass', integrity: 'pass', provenance: 'pass', ...(spec ? { R1: 'pass' } : {}) } };
257
373
  }
258
374
  /** The real readers: git in the workspace, its provenance ledger, its queue and its install manifest. */
259
- function realShellDeps(root) {
375
+ function realShellDeps(root, specsRel = '.ax/specs') {
376
+ // @implements A-SPEC-794.86 — the store's specs by id, read once per verdict (R1 reads parents)
377
+ let byId;
378
+ const specIndex = () => {
379
+ if (byId !== undefined)
380
+ return byId;
381
+ byId = new Map();
382
+ const walk = (dir, depth) => {
383
+ if (depth > 6)
384
+ return;
385
+ let entries;
386
+ try {
387
+ entries = fs.readdirSync(dir, { withFileTypes: true });
388
+ }
389
+ catch {
390
+ return;
391
+ }
392
+ for (const e of entries) {
393
+ const p = path.join(dir, e.name);
394
+ if (e.isDirectory()) {
395
+ walk(p, depth + 1);
396
+ continue;
397
+ }
398
+ if (!e.isFile() || !e.name.endsWith('.md'))
399
+ continue;
400
+ try {
401
+ const s = (0, spec_parser_1.parseSpec)(fs.readFileSync(p, 'utf8'));
402
+ if (s.id === e.name.slice(0, -3) && !byId.has(s.id))
403
+ byId.set(s.id, s);
404
+ }
405
+ catch { /* not a spec */ }
406
+ }
407
+ };
408
+ walk(path.join(root, specsRel), 0);
409
+ return byId;
410
+ };
260
411
  const { FileLedgerStore } = require('./ledger-store');
261
412
  const store = new FileLedgerStore(path.join(root, '.ax', 'ledger'));
262
413
  // @implements A-SPEC-222.9 — H1: a proof is taken only from trusted events (one port with the gate and spec_retire);
@@ -316,6 +467,8 @@ function realShellDeps(root) {
316
467
  // target, an executable is not the 100644 entry the seam grants
317
468
  readBytes: (rel) => (0, spec_seam_1.grantableBytes)(path.join(root, rel)),
318
469
  objectFormat: () => (0, spec_seam_1.objectFormatOf)(root),
470
+ specById: (id) => specIndex().get(id) ?? null,
471
+ allSpecs: () => [...specIndex().values()],
319
472
  };
320
473
  }
321
474
  /** For approve --list: the last autonomous shell approvals (time, command digest, path count). */
@@ -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 {};