@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
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.defaultRuntimeRegistry = void 0;
36
+ exports.ROUTER_CAPABILITIES = exports.defaultRuntimeRegistry = void 0;
37
37
  exports.holmesAgyWrapper = holmesAgyWrapper;
38
38
  exports.sameAgyCommand = sameAgyCommand;
39
39
  exports.runtimeHookCommand = runtimeHookCommand;
@@ -43,14 +43,17 @@ exports.registryWiringOwnership = registryWiringOwnership;
43
43
  exports.registryOwnedWiring = registryOwnedWiring;
44
44
  exports.codexDuplicateRoutes = codexDuplicateRoutes;
45
45
  exports.runtimeBindingStatus = runtimeBindingStatus;
46
+ exports.routerCapabilities = routerCapabilities;
47
+ exports.routerLacksLine = routerLacksLine;
46
48
  exports.runRuntimeBinding = runRuntimeBinding;
47
49
  exports.trackedWorkspacePaths = trackedWorkspacePaths;
48
- // @implements A-SPEC-751.8, A-SPEC-751.9, A-SPEC-769.22,A-SPEC-769.10,A-SPEC-752.11,A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8, A-SPEC-772.1, A-SPEC-772.2, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-772.12
50
+ // @implements A-SPEC-772.25, A-SPEC-794.133, A-SPEC-794.132,A-SPEC-751.8, A-SPEC-751.9, A-SPEC-769.22,A-SPEC-769.10,A-SPEC-752.11,A-SPEC-752.12, A-SPEC-752.13, A-SPEC-752.14, A-SPEC-752.15, A-SPEC-752.16, A-SPEC-752.17, A-SPEC-752.10, A-SPEC-752.9, A-SPEC-751.5, A-SPEC-751.6, A-SPEC-751, A-SPEC-752, A-SPEC-752.7, A-SPEC-752.8, A-SPEC-772.1, A-SPEC-772.2, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-772.12
49
51
  const fs = __importStar(require("node:fs"));
50
52
  const os = __importStar(require("node:os"));
51
53
  const path = __importStar(require("node:path"));
52
54
  const node_crypto_1 = require("node:crypto");
53
55
  const bounded_io_1 = require("../project/bounded-io");
56
+ const wiring_receipt_format_1 = require("../project/wiring-receipt-format");
54
57
  const smol_toml_1 = require("smol-toml");
55
58
  const binding_1 = require("../runtime/binding");
56
59
  const hook_process_1 = require("../runtime/hook-process");
@@ -63,7 +66,8 @@ const heartbeat_1 = require("../hooks/heartbeat");
63
66
  const root_1 = require("../project/root");
64
67
  const defaultRuntimeRegistry = () => path.join(os.homedir(), '.holmes', 'runtime', 'bindings.json');
65
68
  exports.defaultRuntimeRegistry = defaultRuntimeRegistry;
66
- const digest = (s) => (0, node_crypto_1.createHash)('sha256').update(s).digest('hex');
69
+ // @implements A-SPEC-794.132 — the receipt's one format (file name, digest, row choice), shared with governance
70
+ const digest = (s) => (0, wiring_receipt_format_1.receiptDigest)(s);
67
71
  const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
68
72
  const json = (v) => `${JSON.stringify(v, null, 2)}\n`;
69
73
  function readOptional(file) {
@@ -289,22 +293,16 @@ function codexProjectUntrusted(target, configPath) {
289
293
  function registryWiringOwnership(file, registryPath = (0, exports.defaultRuntimeRegistry)()) {
290
294
  const none = { owned: false, matches: false };
291
295
  try {
292
- const manifest = readOptional(path.join(path.dirname(registryPath), 'installation.json'));
296
+ const manifest = readOptional(path.join(path.dirname(registryPath), wiring_receipt_format_1.RECEIPT_FILE));
293
297
  if (manifest === null)
294
298
  return none;
295
- const rows = JSON.parse(manifest).files;
296
- if (!Array.isArray(rows))
299
+ // A-SPEC-794.133 — the last well-formed row for the path; a malformed row is skipped (tolerant), so an unrelated bad row
300
+ // does not disown a reviewed wiring file. Principle 7 reads the same receipt strictly, because its answer only excuses.
301
+ const row = (0, wiring_receipt_format_1.lastReceiptRow)(JSON.parse(manifest).files, [canonicalFuture(file), file], { tolerant: true });
302
+ if (row === null || row === 'malformed')
297
303
  return none;
298
- const wanted = canonicalFuture(file);
299
- for (const row of rows) {
300
- if (!object(row) || typeof row.path !== 'string' || typeof row.digest !== 'string')
301
- return none;
302
- if (row.path !== wanted && row.path !== file)
303
- continue;
304
- const current = readOptional(row.path);
305
- return { owned: true, matches: current !== null && (digest(wiringViewOf(row.path, current)) === row.digest || digest(current) === row.digest) };
306
- }
307
- return none;
304
+ const current = readOptional(row.path);
305
+ return { owned: true, matches: current !== null && (digest(wiringViewOf(row.path, current)) === row.digest || digest(current) === row.digest) };
308
306
  }
309
307
  catch {
310
308
  return none;
@@ -389,7 +387,7 @@ function codexDuplicateRoutes(codexHome, workspace) {
389
387
  function runtimeBindingStatus(registryPath, workspace, opts) {
390
388
  const registry = (0, binding_1.readRuntimeRegistry)(registryPath);
391
389
  const selection = (0, binding_1.selectRuntime)(registry, { cwd: workspace });
392
- const manifest = readOptional(path.join(path.dirname(registryPath), 'installation.json'));
390
+ const manifest = readOptional(path.join(path.dirname(registryPath), wiring_receipt_format_1.RECEIPT_FILE));
393
391
  const conflicts = [];
394
392
  // @implements A-SPEC-769.3 — a row that differs from the receipt is classified, not only counted. Measured 2026-10-12
395
393
  // (X1): every router file under the registry directory matched, and the "conflicts" were operator-owned configuration
@@ -412,7 +410,7 @@ function runtimeBindingStatus(registryPath, workspace, opts) {
412
410
  routerChanged = true;
413
411
  }
414
412
  else {
415
- const rows = document(manifest, 'installation.json').files;
413
+ const rows = document(manifest, wiring_receipt_format_1.RECEIPT_FILE).files;
416
414
  if (!Array.isArray(rows))
417
415
  throw new Error('Invalid runtime installation receipt');
418
416
  for (const row of rows) {
@@ -501,11 +499,55 @@ function runtimeBindingStatus(registryPath, workspace, opts) {
501
499
  // @implements A-SPEC-772.7 — the deployed dispatcher of 2026-10-15 did not pass HOLMES_HOOK_MODE while `router` said
502
500
  // intact (round 3). @implements A-SPEC-772.8 — judged by that capability, not by bytes: one machine-wide copy serves
503
501
  // every binding, so comparing it with the selected package was outdated forever for a development binding (round 4).
504
- const routerOutdated = [];
505
- const deployedDispatch = readOptional(path.join(path.dirname(registryPath), 'dispatch.js'));
506
- if (deployedDispatch !== null && !deployedDispatch.includes('HOLMES_HOOK_MODE'))
507
- routerOutdated.push('dispatch.js');
508
- return { selection, conflicts, drift, duplicateRoutes, router: routerChanged ? 'changed' : 'intact', routerOutdated, activation, observed, observedUnrouted, observedOther };
502
+ // @implements A-SPEC-772.25 — every capability the router carries, not the routing mode alone (a 0.40.0–0.41.2 copy
503
+ // passed that one marker and lacked the 772.20 and 772.22 refusals).
504
+ const routerLacks = routerCapabilities(path.dirname(registryPath));
505
+ const routerOutdated = [...new Set(routerLacks.flatMap((l) => l.files))];
506
+ return { selection, conflicts, drift, duplicateRoutes, router: routerChanged ? 'changed' : 'intact', routerOutdated, routerLacks, activation, observed, observedUnrouted, observedOther };
507
+ }
508
+ /**
509
+ * @implements A-SPEC-772.25 — what each router capability is, in which deployed file a text marks it, and what a router
510
+ * without it lets through. One row per capability (a later one is one more row).
511
+ */
512
+ exports.ROUTER_CAPABILITIES = [
513
+ { capability: 'routing mode', spec: 'A-SPEC-772.7', effect: 'doctor cannot tell which build a hook ran under',
514
+ markers: [{ file: 'dispatch.js', marker: 'HOLMES_HOOK_MODE' }] },
515
+ { capability: 'signal refusal', spec: 'A-SPEC-772.20', effect: 'a gate ended by a signal (an out-of-memory kill included) lets the tool through',
516
+ markers: [{ file: 'dispatch.js', marker: 'result.external' }, { file: 'hook-process.js', marker: 'external: true' }] },
517
+ { capability: 'answer check', spec: 'A-SPEC-772.22', effect: 'an empty, `null` or `{}` gate answer lets the tool through',
518
+ markers: [{ file: 'dispatch.js', marker: 'preToolUseAnswerProblem' }] },
519
+ ];
520
+ /** @implements A-SPEC-772.25 — the capabilities the router deployed in `registryDir` lacks; no `dispatch.js`, no router. */
521
+ function routerCapabilities(registryDir) {
522
+ // A-SPEC-772.31 (review low): the code without its comments — a marker named only in a comment is no capability
523
+ const code = (text) => text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
524
+ const read = (file) => { try {
525
+ return code((0, binding_1.readBounded)(path.join(registryDir, file)));
526
+ }
527
+ catch {
528
+ return null;
529
+ } };
530
+ // a broken link at dispatch.js's path is a deployed router that cannot be read, not "no router" (lstat, not exists)
531
+ try {
532
+ fs.lstatSync(path.join(registryDir, 'dispatch.js'));
533
+ }
534
+ catch {
535
+ return [];
536
+ }
537
+ const text = new Map();
538
+ const of = (file) => { if (!text.has(file))
539
+ text.set(file, read(file)); return text.get(file) ?? null; };
540
+ return exports.ROUTER_CAPABILITIES
541
+ .filter((c) => c.markers.some((m) => !(of(m.file) ?? '').includes(m.marker)))
542
+ .map((c) => ({ capability: c.capability, files: [...new Set(c.markers.map((m) => m.file))], spec: c.spec, effect: c.effect }));
543
+ }
544
+ /** @implements A-SPEC-772.25 — doctor's words: what the router lets through, and that the owner's setup (not upgrade) fixes it. */
545
+ function routerLacksLine(lacks) {
546
+ if (!lacks.length)
547
+ return '';
548
+ const files = [...new Set(lacks.flatMap((l) => l.files))].join(', ');
549
+ return `; the deployed router (${files}) lacks ${lacks.map((l) => `${l.capability} (${l.spec}: ${l.effect})`).join('; ')}`
550
+ + ' — the owner re-runs holmes-kit runtime-binding setup with this build to deploy it (holmes-kit upgrade does not refresh the router)';
509
551
  }
510
552
  function runRuntimeBinding(opts) {
511
553
  if (opts.activateHooks !== undefined && (!Array.isArray(opts.activateHooks)
@@ -519,7 +561,7 @@ function runRuntimeBinding(opts) {
519
561
  throw new Error('runtime-binding expects setup, status or remove');
520
562
  if (!path.isAbsolute(opts.registryPath))
521
563
  throw new Error('Registry path must be absolute');
522
- if (['binding.js', 'dispatch.js', 'hook-process.js', 'installation.json'].includes(path.basename(opts.registryPath))
564
+ if (['binding.js', 'dispatch.js', 'hook-process.js', wiring_receipt_format_1.RECEIPT_FILE].includes(path.basename(opts.registryPath))
523
565
  || /^(?:claude|codex|antigravity)-(?:mcp|pre-tool-use|stop|session-start)\.js$/.test(path.basename(opts.registryPath)))
524
566
  throw new Error('Registry filename conflicts with an installed runtime file');
525
567
  // @implements A-SPEC-752.14 — a remove may name a workspace whose directory is gone (measured: G0GnMK); its root is
@@ -1008,7 +1050,7 @@ function runRuntimeBinding(opts) {
1008
1050
  conflicts.push(e.message);
1009
1051
  }
1010
1052
  add(destination, after);
1011
- const manifestPath = path.join(dir, 'installation.json');
1053
+ const manifestPath = path.join(dir, wiring_receipt_format_1.RECEIPT_FILE);
1012
1054
  const receipt = readOptional(manifestPath);
1013
1055
  const recorded = new Map();
1014
1056
  const runtimeIdentities = {};
@@ -14,6 +14,7 @@ export interface HookEntry {
14
14
  type: 'command';
15
15
  command: string;
16
16
  timeout?: number;
17
+ onFailure?: 'block';
17
18
  }
18
19
  export interface HookGroup {
19
20
  matcher?: string;
@@ -35,8 +36,8 @@ export interface HookPlan {
35
36
  stopCommand: string;
36
37
  sessionStartCommand?: string;
37
38
  }
38
- /** A hook entry belongs to holmes-kit iff its command references our hook scripts. */
39
- export declare function isHolmesCommand(command: string): boolean;
39
+ import { isHolmesCommand } from './holmes-hook-id';
40
+ export { isHolmesCommand };
40
41
  /**
41
42
  * The script path out of a hook command line, e.g. `node "/pkg/dist/.../stop.js"` -> `/pkg/dist/.../stop.js`.
42
43
  * `init` quotes the path (installs live under paths that may contain spaces), so an unquoting parse is
@@ -1,7 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.AUTONOMY_MCP_ENV = exports.HOLMES_OWNED_MCP_ENV = void 0;
4
- exports.isHolmesCommand = isHolmesCommand;
3
+ exports.AUTONOMY_MCP_ENV = exports.HOLMES_OWNED_MCP_ENV = exports.isHolmesCommand = void 0;
5
4
  exports.hookScriptPath = hookScriptPath;
6
5
  exports.mergeHooks = mergeHooks;
7
6
  exports.removeHooks = removeHooks;
@@ -12,10 +11,9 @@ exports.removeMcpServer = removeMcpServer;
12
11
  // @implements A-SPEC-100.2
13
12
  // @implements A-SPEC-769.12
14
13
  const hook_process_1 = require("../runtime/hook-process");
15
- /** A hook entry belongs to holmes-kit iff its command references our hook scripts. */
16
- function isHolmesCommand(command) {
17
- return /dist[/\\]holmes[/\\]hooks[/\\](pre-tool-use|stop|session-start)\.js/.test(command) || /\bholmes-(kit|mcp|pre-tool-use|stop)\b/.test(command);
18
- }
14
+ // @implements A-SPEC-772.18 — the patterns live in one module; re-exported for the callers that import them from here
15
+ const holmes_hook_id_1 = require("./holmes-hook-id");
16
+ Object.defineProperty(exports, "isHolmesCommand", { enumerable: true, get: function () { return holmes_hook_id_1.isHolmesCommand; } });
19
17
  /**
20
18
  * The script path out of a hook command line, e.g. `node "/pkg/dist/.../stop.js"` -> `/pkg/dist/.../stop.js`.
21
19
  * `init` quotes the path (installs live under paths that may contain spaces), so an unquoting parse is
@@ -26,7 +24,7 @@ function hookScriptPath(command) {
26
24
  const m = /(?:^|\s)(?:node(?:\.exe)?\s+)?(?:"([^"]+)"|'([^']+)'|([^\s"']*[/\\][^\s"']*))/.exec(command);
27
25
  return m?.[1] ?? m?.[2] ?? m?.[3] ?? '';
28
26
  }
29
- const hasHolmes = (g) => (g.hooks ?? []).some((h) => isHolmesCommand(h.command));
27
+ const hasHolmes = (g) => (g.hooks ?? []).some((h) => (0, holmes_hook_id_1.isHolmesCommand)(h.command));
30
28
  /**
31
29
  * Add or replace holmes-kit's PreToolUse + Stop entries. Every other hook group, every other event,
32
30
  * and all unrelated top-level keys (permissions, …) are preserved byte-for-byte in value.
@@ -43,7 +41,11 @@ function mergeHooks(existing, plan) {
43
41
  groups.push(group);
44
42
  hooks[event] = groups;
45
43
  };
46
- upsert('PreToolUse', { matcher: plan.preToolUseMatcher, hooks: [{ type: 'command', command: plan.preToolUseCommand }] });
44
+ // @implements A-SPEC-772.18 — a person's `onFailure: "block"` on the Holmes gate entry survives the rewrite (it was dropped
45
+ // without a word, leaving the gate open on a failure again)
46
+ const kept = (hooks.PreToolUse ?? []).filter((g) => Array.isArray(g?.hooks))
47
+ .some((g) => g.hooks.some((h) => h !== null && typeof h === 'object' && (0, holmes_hook_id_1.namesHolmesGate)(h) && h.onFailure === 'block'));
48
+ upsert('PreToolUse', { matcher: plan.preToolUseMatcher, hooks: [{ type: 'command', command: plan.preToolUseCommand, ...(kept ? { onFailure: 'block' } : {}) }] });
47
49
  // Stop takes NO matcher. @implements A-SPEC-769.12 — and carries the Stop timeout: without one Claude applied its own
48
50
  // default, unrelated to the dispatcher's 60 s Stop budget.
49
51
  upsert('Stop', { hooks: [{ type: 'command', command: plan.stopCommand, timeout: hook_process_1.STOP_HOOK_TIMEOUT_SECONDS }] });
@@ -69,7 +71,7 @@ function removeHooks(existing) {
69
71
  continue;
70
72
  }
71
73
  const kept = groups
72
- .map((g) => ({ ...g, hooks: (Array.isArray(g?.hooks) ? g.hooks : []).filter((h) => !isHolmesCommand(h?.command)) }))
74
+ .map((g) => ({ ...g, hooks: (Array.isArray(g?.hooks) ? g.hooks : []).filter((h) => !(0, holmes_hook_id_1.isHolmesCommand)(h?.command)) }))
73
75
  .filter((g) => g.hooks.length > 0);
74
76
  if (kept.length > 0)
75
77
  hooks[event] = kept;
@@ -115,3 +115,9 @@ export declare const RUN_APPROVAL_WAIT_DEFAULT = 60;
115
115
  export type AutonomyCeiling = 'off' | 'tests' | 'no-gate' | 'default';
116
116
  export declare const DEFAULT_CONFIG: AxConfig;
117
117
  export declare function loadConfig(root: string): AxConfig;
118
+ /**
119
+ * @implements A-SPEC-476.8 — the effective config of an ax.config.json text, exactly as loadConfig reads the file: `null`
120
+ * is no file (the defaults); `undefined` is a file that cannot be read (the closed fallback). The gate compares two texts
121
+ * through this, so it judges the values the runtime will use.
122
+ */
123
+ export declare function configOfText(text: string | null | undefined): AxConfig;
@@ -35,7 +35,8 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.DEFAULT_CONFIG = exports.RUN_APPROVAL_WAIT_DEFAULT = exports.RUN_REFUSAL_LIMIT_DEFAULT = exports.DEFAULT_STAGES = void 0;
37
37
  exports.loadConfig = loadConfig;
38
- // @implements A-SPEC-794.95, A-SPEC-794.86, A-SPEC-278, A-SPEC-781.2, A-SPEC-476.3, A-SPEC-128.5, A-SPEC-128.7, A-SPEC-128.13
38
+ exports.configOfText = configOfText;
39
+ // @implements A-SPEC-476.8, A-SPEC-794.95, A-SPEC-794.86, A-SPEC-278, A-SPEC-781.2, A-SPEC-476.3, A-SPEC-128.5, A-SPEC-128.7, A-SPEC-128.13
39
40
  // @implements A-SPEC-125.5
40
41
  // src/holmes/config/config.ts
41
42
  const fs = __importStar(require("node:fs"));
@@ -174,12 +175,31 @@ function deepMerge(base, ov) {
174
175
  function loadConfig(root) {
175
176
  const f = path.join(root, 'ax.config.json');
176
177
  if (!fs.existsSync(f))
178
+ return configOfText(null);
179
+ let text;
180
+ try {
181
+ text = fs.readFileSync(f, 'utf8');
182
+ }
183
+ catch {
184
+ text = undefined;
185
+ }
186
+ return configOfText(text);
187
+ }
188
+ /**
189
+ * @implements A-SPEC-476.8 — the effective config of an ax.config.json text, exactly as loadConfig reads the file: `null`
190
+ * is no file (the defaults); `undefined` is a file that cannot be read (the closed fallback). The gate compares two texts
191
+ * through this, so it judges the values the runtime will use.
192
+ */
193
+ function configOfText(text) {
194
+ if (text === null)
177
195
  return structuredClone(exports.DEFAULT_CONFIG);
178
196
  // FAIL-SAFE: a malformed/unreadable config must never crash the loader (it gates the guardrail).
179
197
  // Fall back to the strict DEFAULT_CONFIG (enforcement:'block') so a broken file cannot silently
180
198
  // weaken or disable governance — a bad config degrades to the safest posture, not to an exception.
181
199
  try {
182
- const merged = structuredClone(deepMerge(exports.DEFAULT_CONFIG, JSON.parse(fs.readFileSync(f, 'utf8'))));
200
+ if (text === undefined)
201
+ throw new Error('unreadable');
202
+ const merged = structuredClone(deepMerge(exports.DEFAULT_CONFIG, JSON.parse(text)));
183
203
  // @implements A-SPEC-694 — `deepMerge` copies a non-object override as it arrived, so
184
204
  // `"architecture": "x"` or `"cycleIgnore": "reference"` would reach the ratchet as written. An
185
205
  // exception list must never fail TOWARD a wider exception: anything that is not an array of
@@ -225,7 +245,7 @@ function loadConfig(root) {
225
245
  // @implements A-SPEC-781 — read from the file as written, not from the deep merge with the default machine.
226
246
  let declaredStages;
227
247
  try {
228
- declaredStages = JSON.parse(fs.readFileSync(f, 'utf8')).stages;
248
+ declaredStages = JSON.parse(text).stages;
229
249
  }
230
250
  catch {
231
251
  declaredStages = undefined;
@@ -0,0 +1,20 @@
1
+ /**
2
+ * @implements A-SPEC-476.9 — calibration.unscoredPaths of an ax.config.json text: an array of strings, or null (the
3
+ * default then applies). The one parser: maintenance-evidence imports it (it kept its own copy before).
4
+ */
5
+ export declare function unscoredPathsOfText(text: string | null | undefined): string[] | null;
6
+ /**
7
+ * @implements A-SPEC-476.9 (B2) — every key read from ax.config.json outside the `AxConfig` schema, in one place. A row
8
+ * with `read` is compared; a cap row names what A-SPEC-476.3 judges instead.
9
+ */
10
+ export declare const JUDGEMENT_RAW_READERS: ReadonlyArray<{
11
+ key: string;
12
+ reader: string;
13
+ read?: (text: string | null | undefined) => unknown;
14
+ }>;
15
+ /**
16
+ * The dotted judgement keys whose effective values differ between two ax.config.json texts. `null` is no file;
17
+ * `undefined` is a text that cannot be known (read fails, or a write's result cannot be computed) and reads as the
18
+ * closed fallback, so it differs wherever the other side is not already closed.
19
+ */
20
+ export declare function judgementKeyChanges(before: string | null | undefined, after: string | null | undefined): string[];
@@ -0,0 +1,100 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.JUDGEMENT_RAW_READERS = void 0;
4
+ exports.unscoredPathsOfText = unscoredPathsOfText;
5
+ exports.judgementKeyChanges = judgementKeyChanges;
6
+ // @implements A-SPEC-476.8, A-SPEC-476.9
7
+ /**
8
+ * The judgement keys of ax.config.json — every key Holmes reads to judge — compared by their effective values. An
9
+ * agent's write that changes one changes its own gate, whichever direction it goes (measured 2026-11-15: Edit, Write,
10
+ * MultiEdit, sed, >, cp and rm all switched preEditEvidence from block to off), so the hook makes it the owner's act.
11
+ *
12
+ * The census is loadConfig itself: every top-level key it returns is compared, read through the same `configOfText`, so
13
+ * a key added to the schema is covered with no list to edit. `calibration.unscoredPaths`, read outside the schema by
14
+ * maintenance-evidence, is compared as that reader takes it. The two caps (`semantic.maxTier`, `autonomy.ceiling`) are
15
+ * left out: A-SPEC-476.3 judges them, and lowering a cap stays free (owner decision 2026-10-19).
16
+ */
17
+ const config_1 = require("./config");
18
+ /** Keys compared as one value (no sub-keys reported). */
19
+ const WHOLE = new Set(['stages', 'highRiskDomains']);
20
+ /** Keys the caps rule owns. */
21
+ const CAPS = new Set(['autonomy.ceiling']);
22
+ const stable = (v) => JSON.stringify(v, (_k, x) => (x !== null && typeof x === 'object' && !Array.isArray(x)
23
+ ? Object.fromEntries(Object.keys(x).sort().map((k) => [k, x[k]])) : x));
24
+ const isPlain = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
25
+ /**
26
+ * @implements A-SPEC-476.9 — calibration.unscoredPaths of an ax.config.json text: an array of strings, or null (the
27
+ * default then applies). The one parser: maintenance-evidence imports it (it kept its own copy before).
28
+ */
29
+ function unscoredPathsOfText(text) {
30
+ if (typeof text !== 'string')
31
+ return null;
32
+ try {
33
+ const v = JSON.parse(text)?.calibration?.unscoredPaths;
34
+ return Array.isArray(v) && v.every((x) => typeof x === 'string') ? v : null;
35
+ }
36
+ catch {
37
+ return null;
38
+ }
39
+ }
40
+ /** The raw value of a dotted key in an ax.config.json text, as a reader outside the schema sees it (undefined: absent). */
41
+ function rawOf(text, key) {
42
+ if (typeof text !== 'string')
43
+ return undefined;
44
+ try {
45
+ let v = JSON.parse(text);
46
+ for (const k of key.split('.'))
47
+ v = v !== null && typeof v === 'object' ? v[k] : undefined;
48
+ return v;
49
+ }
50
+ catch {
51
+ return undefined;
52
+ }
53
+ }
54
+ /**
55
+ * @implements A-SPEC-476.9 (B2) — every key read from ax.config.json outside the `AxConfig` schema, in one place. A row
56
+ * with `read` is compared; a cap row names what A-SPEC-476.3 judges instead.
57
+ */
58
+ exports.JUDGEMENT_RAW_READERS = [
59
+ { key: 'calibration.unscoredPaths', reader: 'mcp/handlers/maintenance-evidence.ts', read: unscoredPathsOfText },
60
+ { key: 'testRun.prepare', reader: 'mcp/handlers/test-execution.ts (HEAD\'s file, raw)', read: (t) => rawOf(t, 'testRun.prepare') },
61
+ { key: 'semantic.maxTier', reader: 'semantic/tier.ts — a cap (A-SPEC-476.3)' },
62
+ { key: 'autonomy.ceiling', reader: 'config.ts — a cap (A-SPEC-476.3)' },
63
+ ];
64
+ /**
65
+ * The dotted judgement keys whose effective values differ between two ax.config.json texts. `null` is no file;
66
+ * `undefined` is a text that cannot be known (read fails, or a write's result cannot be computed) and reads as the
67
+ * closed fallback, so it differs wherever the other side is not already closed.
68
+ */
69
+ function judgementKeyChanges(before, after) {
70
+ const a = (0, config_1.configOfText)(before);
71
+ const b = (0, config_1.configOfText)(after);
72
+ const out = [];
73
+ for (const top of Object.keys(config_1.DEFAULT_CONFIG)) {
74
+ const x = a[top];
75
+ const y = b[top];
76
+ if (WHOLE.has(top) || !isPlain(x) || !isPlain(y)) {
77
+ if (stable(x) !== stable(y))
78
+ out.push(top);
79
+ continue;
80
+ }
81
+ // A-SPEC-476.9 (B2) — every sub-key either side carries: the defaults' and any other (a new optional key with no
82
+ // default, guardrail's included, was missed when guardrail compared the defaults' keys only)
83
+ const known = Object.keys(config_1.DEFAULT_CONFIG[top] ?? {});
84
+ for (const sub of [...new Set([...known, ...Object.keys(x), ...Object.keys(y)])].sort()) {
85
+ const key = `${top}.${sub}`;
86
+ if (CAPS.has(key))
87
+ continue;
88
+ if (stable(x[sub]) !== stable(y[sub]))
89
+ out.push(key);
90
+ }
91
+ }
92
+ // the registry of readers outside the schema (A-SPEC-476.9): a raw value the schema drops still reaches its reader
93
+ for (const r of exports.JUDGEMENT_RAW_READERS) {
94
+ if (r.read === undefined)
95
+ continue;
96
+ if (stable(r.read(before)) !== stable(r.read(after)) && !out.includes(r.key))
97
+ out.push(r.key);
98
+ }
99
+ return out;
100
+ }
@@ -86,10 +86,11 @@ function ceilingOf(obj) {
86
86
  /** The caps `after` sets wider than `before` (an absent cap is its widest value, so removing a set cap is a raise). */
87
87
  function raisedCaps(before, after) {
88
88
  const out = [];
89
+ // A-SPEC-794.138: these reach an agent inside a refusal — they name the cap, not its key
89
90
  if (SEMANTIC_ORDER.indexOf(after.semantic) > SEMANTIC_ORDER.indexOf(before.semantic))
90
- out.push(`semantic.maxTier ${before.semantic} → ${after.semantic}`);
91
+ out.push(`the semantic search cap ${before.semantic} → ${after.semantic}`);
91
92
  if (CEILING_ORDER.indexOf(after.ceiling) > CEILING_ORDER.indexOf(before.ceiling))
92
- out.push(`autonomy.ceiling ${before.ceiling} → ${after.ceiling}`);
93
+ out.push(`the autonomy cap ${before.ceiling} → ${after.ceiling}`);
93
94
  return out;
94
95
  }
95
96
  function capsAtWidest(c) {
@@ -300,7 +300,7 @@ const PROVERS = [
300
300
  function autonomousShellVerdict(input, deps) {
301
301
  const fail = (failed, detail) => ({ ok: false, failed, detail });
302
302
  if (input.shellStaging !== 'on')
303
- return fail('switch', 'autonomy.shellStaging is off');
303
+ return fail('switch', 'autonomous shell staging is off — the owner turns it on'); // A-SPEC-794.138
304
304
  // @implements A-SPEC-792.32 — one path base: the verdict resolves pathspecs from the root, so the act must run there (N2)
305
305
  if (input.base !== undefined && path.resolve(input.base) !== path.resolve(input.root))
306
306
  return fail('base', `the command runs from ${input.base}, not the workspace root; its paths are judged only from the root`);
@@ -180,8 +180,34 @@ export type Principle7Verdict = {
180
180
  ts: string;
181
181
  sha256: string;
182
182
  }>;
183
+ /** A-SPEC-794.131 — local-only files let through because their bytes are exactly the runtime binding receipt's. */
184
+ receiptOwned?: string[];
185
+ /** A-SPEC-772.31 — the receipt digest each excused file matched when judged: what its audit row records. */
186
+ receiptDigests?: Record<string, string>;
183
187
  };
184
- export declare function principle7Verdict(root: string, specs: ReadonlyArray<Spec>, nowMs: number): Principle7Verdict | null;
188
+ export declare function principle7Verdict(root: string, specs: ReadonlyArray<Spec>, nowMs: number, opts?: {
189
+ home?: string;
190
+ }): Principle7Verdict | null;
191
+ /**
192
+ * @implements A-SPEC-794.132 — whether `f` changed in the working tree alone: present in the baseline, the index and HEAD,
193
+ * all three equal, and no conflict entry. A missing key (a git read that failed or did not list the file) is never equal.
194
+ */
195
+ export declare function receiptExcusable(f: string, atBase: Map<string, string>, atIndex: Map<string, string>, atHead: Map<string, string>): boolean;
196
+ /**
197
+ * @implements A-SPEC-794.133 — the excuse step the verdict calls: a local-only file leaves `unopened` and `localOnly` only
198
+ * when its three git reads are present and equal (receiptExcusable) and the injected receipt check says its bytes are the
199
+ * receipt's. Returns the excused files. The maps are passed unchanged, so an empty read excuses nothing.
200
+ */
201
+ export declare function excuseByReceipt(localOnly: string[], unopened: string[], atBase: Map<string, string>, atIndex: Map<string, string>, atHead: Map<string, string>, root: string, home: string, recordsExactly: (abs: string, home: string) => boolean): string[];
202
+ /**
203
+ * @implements A-SPEC-772.31 — the audit rows for the excused files: the digest each matched when judged (review of 772.29,
204
+ * M2: the row was the bytes read at record time, so a change in between wrote a match that was never judged), skipping a
205
+ * file whose latest row already holds it. A file with no judged digest takes no row. Reads nothing.
206
+ */
207
+ export declare function receiptExcuseRows(owned: readonly string[], judged: Readonly<Record<string, string>>, last: ReadonlyMap<string, string>): Array<{
208
+ file: string;
209
+ sha256: string;
210
+ }>;
185
211
  /**
186
212
  * @implements A-SPEC-794.97 — the content a window saw: one `principle7-window-blob` row per (file, spec, seal, blob) not
187
213
  * yet recorded, written where a judgement passes because a window was open (Stop, commit, build).