@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
@@ -802,7 +802,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
802
802
  };
803
803
  }[];
804
804
  graph: {
805
- status: "absent" | "current" | "empty" | "unreadable" | "stale" | "unverified";
805
+ status: "absent" | "current" | "unreadable" | "empty" | "stale" | "unverified";
806
806
  sourceCommit: string | null;
807
807
  graphAsOf: string | null;
808
808
  resolutionLimits: string[];
@@ -862,7 +862,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
862
862
  };
863
863
  }[];
864
864
  graph: {
865
- status: "absent" | "current" | "empty" | "unreadable" | "stale" | "unverified";
865
+ status: "absent" | "current" | "unreadable" | "empty" | "stale" | "unverified";
866
866
  sourceCommit: string | null;
867
867
  graphAsOf: string | null;
868
868
  resolutionLimits: string[];
@@ -944,7 +944,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
944
944
  };
945
945
  }[];
946
946
  graph: {
947
- status: "absent" | "current" | "empty" | "unreadable" | "stale" | "unverified";
947
+ status: "absent" | "current" | "unreadable" | "empty" | "stale" | "unverified";
948
948
  sourceCommit: string | null;
949
949
  graphAsOf: string | null;
950
950
  resolutionLimits: string[];
@@ -1010,7 +1010,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1010
1010
  };
1011
1011
  }[];
1012
1012
  graph: {
1013
- status: "absent" | "current" | "empty" | "unreadable" | "stale" | "unverified";
1013
+ status: "absent" | "current" | "unreadable" | "empty" | "stale" | "unverified";
1014
1014
  sourceCommit: string | null;
1015
1015
  graphAsOf: string | null;
1016
1016
  resolutionLimits: string[];
@@ -1362,7 +1362,7 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
1362
1362
  advisoryIds?: Partial<Record<string, string>> | undefined;
1363
1363
  killsAdvisory?: import("../review/kills-check").KillsAdvisory | undefined;
1364
1364
  fttFulfilment?: import("../rtm/ftt-fulfilment").FttFulfilment | undefined;
1365
- impactAdvisoryUnavailable?: "empty" | "unreadable" | undefined;
1365
+ impactAdvisoryUnavailable?: "unreadable" | "empty" | undefined;
1366
1366
  impactGraph?: {
1367
1367
  status: "current" | "stale" | "unverified";
1368
1368
  sourceCommit: string | null;
@@ -39,7 +39,7 @@ exports.isHandlerRefusal = isHandlerRefusal;
39
39
  exports.unreadableAmong = unreadableAmong;
40
40
  exports.makeHandlers = makeHandlers;
41
41
  exports.collectDecisions = collectDecisions;
42
- // @implements A-SPEC-128.2, A-SPEC-128.5, A-SPEC-251.4,A-SPEC-466.2,A-SPEC-774.25, A-SPEC-770.12,A-SPEC-718.1, A-SPEC-718.2, A-SPEC-723, A-SPEC-723.1, A-SPEC-545.6, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754, A-SPEC-792.4
42
+ // @implements A-SPEC-794.85, A-SPEC-128.2, A-SPEC-128.5, A-SPEC-251.4,A-SPEC-466.2,A-SPEC-774.25, A-SPEC-770.12,A-SPEC-718.1, A-SPEC-718.2, A-SPEC-723, A-SPEC-723.1, A-SPEC-545.6, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-599, A-SPEC-603, A-SPEC-604, A-SPEC-605, A-SPEC-606, A-SPEC-607, A-SPEC-608, A-SPEC-609, A-SPEC-610, A-SPEC-611, A-SPEC-612, A-SPEC-613, A-SPEC-614, A-SPEC-615, A-SPEC-616, A-SPEC-617, A-SPEC-618, A-SPEC-621, A-SPEC-622, A-SPEC-624, A-SPEC-625, A-SPEC-627, A-SPEC-713, A-SPEC-732, A-SPEC-754, A-SPEC-792.4
43
43
  const operator_recovery_1 = require("./operator-recovery");
44
44
  // @implements A-SPEC-643
45
45
  // @implements A-SPEC-642
@@ -985,6 +985,7 @@ function makeRawHandlers(store, opts) {
985
985
  });
986
986
  // @implements A-SPEC-622, A-SPEC-100.2, A-SPEC-128, A-SPEC-132, A-SPEC-133, A-SPEC-151, A-SPEC-188, A-SPEC-189, A-SPEC-244, A-SPEC-245
987
987
  const specApproval = (0, spec_approval_1.createSpecApprovalHandlers)({
988
+ serverInstance: () => opts?.serverInstance?.(), // @implements A-SPEC-794.85 — the seal's session, injected
988
989
  store, resolver, projectRootOf, cachedScan, tryElicit, elicitApproval, autonomousApproval,
989
990
  approvalAdapter,
990
991
  approvalHarness: attestedHarness, // @implements A-SPEC-792.24 — the recorded harness is the attested one
@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
4
4
  exports.isWireTool = isWireTool;
5
5
  exports.wireDispatch = wireDispatch;
6
- // @implements A-SPEC-128.2, A-SPEC-128.4, A-SPEC-128.5, A-SPEC-128.7, A-SPEC-128.10, A-SPEC-743,A-SPEC-736,A-SPEC-735, A-SPEC-729, A-SPEC-719, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713, A-SPEC-774.25, A-SPEC-255.1, A-SPEC-466.1, A-SPEC-466.2, A-SPEC-466.3, A-SPEC-466.4, A-SPEC-466.6
6
+ // @implements A-SPEC-794.85, A-SPEC-128.2, A-SPEC-128.4, A-SPEC-128.5, A-SPEC-128.7, A-SPEC-128.10, A-SPEC-743,A-SPEC-736,A-SPEC-735, A-SPEC-729, A-SPEC-719, A-SPEC-720, A-SPEC-718, A-SPEC-703, A-SPEC-629, A-SPEC-628, A-SPEC-623, A-SPEC-277, A-SPEC-624, A-SPEC-627, A-SPEC-713, A-SPEC-774.25, A-SPEC-255.1, A-SPEC-466.1, A-SPEC-466.2, A-SPEC-466.3, A-SPEC-466.4, A-SPEC-466.6
7
7
  // @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
8
8
  // consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
9
9
  // @implements A-SPEC-642
@@ -87,7 +87,7 @@ exports.TOOL_SCHEMAS = {
87
87
  inputSchema: { type: 'object', properties: { root: ROOT_ANY, operation: { type: 'string', enum: ['plan', 'apply', 'recovery-plan', 'recover', 'abandon'] }, changes: { type: 'array', items: { type: 'object', properties: { entityId: { type: 'string' }, newDisplayId: { type: 'string' } }, required: ['entityId', 'newDisplayId'], additionalProperties: false } }, plan: { type: 'object' } } },
88
88
  },
89
89
  entity_store: {
90
- description: 'Inspect or plan entity adoption without writes by default. Explicit adopt requires config-write approval for the exact returned plan and preserves sealed document bytes. Adopted stores retain entity identity through journaled document creation, edits and classification moves. recovery-plan reports interrupted targets without changing them. recover requires separate exact-plan approval to complete interrupted transactions or release locks for verified completed writes. Sealing, unsealing and retirement additionally require current spec-approve authority for the affected ID and the same transition policy as official spec tools. Live or unknown owners, external changes and noncanonical transitions refuse. Recovery audit completion across crashes remains under development.',
90
+ description: 'Inspect or plan entity adoption without writes by default. Explicit adopt requires config-write approval for the exact returned plan and preserves sealed document bytes. Adopted stores retain entity identity through journaled document creation, edits and classification moves. recovery-plan reports interrupted targets without changing them. recover requires separate exact-plan approval to complete interrupted transactions or release locks for verified completed writes. Sealing, unsealing and retirement additionally require current authority of the kind of that transition for the affected ID (spec-approve, spec-unseal, spec-retire) and the same transition policy as official spec tools. Live or unknown owners, external changes and noncanonical transitions refuse. Recovery audit completion across crashes remains under development.',
91
91
  inputSchema: { type: 'object', properties: { root: ROOT_ANY, operation: { type: 'string', enum: ['status', 'plan-adoption', 'adopt', 'recovery-plan', 'recover'] }, plan: { type: 'object', description: 'The complete unmodified plan returned by plan-adoption or recovery-plan.' } } },
92
92
  },
93
93
  workspace_preflight: {
@@ -182,7 +182,7 @@ exports.TOOL_SCHEMAS = {
182
182
  },
183
183
  },
184
184
  spec_retire: {
185
- description: "Move ONE named spec to `status: outdated` — the only path to that state. Retirement WITHDRAWS authority, so it needs no approval key by default; two cases invert that, because there the withdrawal opens a gate. A SEALED spec requires the same out-of-band HOLMES_APPROVAL as spec_approve, fail-closed: retiring the approved T-SPEC that blocks the code gate would remove the demand, making retirement an approval bypass. And a spec that an APPROVED spec depends on is refused outright, with the dependents named — that chain is holding something up right now. Records `spec-retired` in the provenance ledger, writes the reason into `retired_reason` (omitted when blank, or when `superseded_by` already answers why), and is idempotent: retiring an already-outdated spec writes nothing rather than overwriting the first retirement's reason.",
185
+ description: "Move ONE named spec to `status: outdated` — the only path to that state. Retirement WITHDRAWS authority, so it needs no approval key by default; two cases invert that, because there the withdrawal opens a gate. A SEALED spec requires an out-of-band approval of its own kind, spec-retire (a spec-approve approval does not cover it), fail-closed: retiring the approved T-SPEC that blocks the code gate would remove the demand, making retirement an approval bypass. And a spec that an APPROVED spec depends on is refused outright, with the dependents named — that chain is holding something up right now. Records `spec-retired` in the provenance ledger, writes the reason into `retired_reason` (omitted when blank, or when `superseded_by` already answers why), and is idempotent: retiring an already-outdated spec writes nothing rather than overwriting the first retirement's reason.",
186
186
  inputSchema: {
187
187
  type: 'object',
188
188
  properties: {
@@ -229,7 +229,7 @@ exports.TOOL_SCHEMAS = {
229
229
  },
230
230
  },
231
231
  spec_unseal: {
232
- description: "The inverse of spec_approve: return ONE sealed (approved) spec to an editable `status: draft`, clearing `approved_digest` and `parent_digests` in a single ACT, and record `spec-unsealed` in the provenance ledger. Un-sealing WITHDRAWS a seal, so it requires the same out-of-band HOLMES_APPROVAL as spec_approve/spec_retire's sealed path (fail-closed): un-sealing an approved T-SPEC removes the code gate's demand, which unguarded would be an approval bypass. Refuses when an APPROVED spec depends on the target — that dependent's parent_digests would silently go stale — naming the blockers. Idempotent: un-sealing a spec that is already draft (never sealed) writes nothing and returns unsealed:false. Written only at the version this act read; a concurrent edit wins and the un-seal is refused for retry. Distinct from spec_retire (which withdraws authority to status:outdated); un-seal keeps the spec alive and editable.",
232
+ description: "The inverse of spec_approve: return ONE sealed (approved) spec to an editable `status: draft`, clearing `approved_digest` and `parent_digests` in a single ACT, and record `spec-unsealed` in the provenance ledger. Un-sealing WITHDRAWS a seal, so it requires an out-of-band approval of its own kind, spec-unseal (a spec-approve approval does not cover it), fail-closed: un-sealing an approved T-SPEC removes the code gate's demand, which unguarded would be an approval bypass. Refuses when an APPROVED spec depends on the target — that dependent's parent_digests would silently go stale — naming the blockers. Idempotent: un-sealing a spec that is already draft (never sealed) writes nothing and returns unsealed:false. Written only at the version this act read; a concurrent edit wins and the un-seal is refused for retry. Distinct from spec_retire (which withdraws authority to status:outdated); un-seal keeps the spec alive and editable.",
233
233
  inputSchema: {
234
234
  type: 'object',
235
235
  properties: {
@@ -0,0 +1,50 @@
1
+ import { type PlaybookSkillState } from './playbook-skill-states';
2
+ export type SkillReference = {
3
+ kind: 'package';
4
+ } | {
5
+ kind: 'ledger';
6
+ recordedAt: string;
7
+ commit: string;
8
+ replica: string;
9
+ } | {
10
+ kind: 'closed';
11
+ reason: string;
12
+ };
13
+ export interface JudgedSkills {
14
+ states: {
15
+ name: string;
16
+ state: PlaybookSkillState;
17
+ }[];
18
+ reference: SkillReference;
19
+ /** With a ledger reference: the playbooks whose working-tree body is not the recorded one (changed, added or gone since). */
20
+ moved: string[];
21
+ }
22
+ /**
23
+ * The `playbook:<name>:<sha256>` inputs a `principle7-baseline` row carries: one per playbook the package ships, the
24
+ * sha256 of its PLAYBOOK.md bytes. The digest is of the playbook's body, not of the installed skill: the row is written
25
+ * by the hook that runs BEFORE the build, and must not depend on that build's marker format. A playbook that cannot be
26
+ * read, or whose name could not be told apart in the input, is not recorded — so its skill is never `current`.
27
+ */
28
+ export declare function playbookDigestInputs(packageRoot: string): string[];
29
+ /**
30
+ * A-SPEC-794.113 — which digests a new baseline row may carry. `now` are the working tree's inputs, `before` the
31
+ * inputs of the latest digest-bearing row of this writer's chain, `anchored` the playbooks whose content a person's
32
+ * window of this chain saw and names now, `removed` those whose removal such a window names. A digest unchanged since
33
+ * `before`, or anchored, is written; any other keeps the digest `before` carried — the reference does not move for it —
34
+ * or, when `before` had none for it, is left out. A playbook the working tree no longer holds is carried on with the
35
+ * digest `before` had, unless it is in `removed`.
36
+ */
37
+ export declare function anchoredPlaybookInputs(now: string[], before: string[], anchored: ReadonlySet<string>, removed?: ReadonlySet<string>): string[];
38
+ /**
39
+ * The one choice of "the latest row" for the reader and the record (review A, L3: the two chose by different orders): in
40
+ * one writer's chain the sequence is the order rows were written in.
41
+ */
42
+ export declare function latestBySequence<T extends {
43
+ seq?: unknown;
44
+ }>(rows: T[]): T | null;
45
+ /**
46
+ * Every recovery skill's state in `target`, against the reference `packageRoot` has. With a ledger reference a playbook's
47
+ * working-tree body is the reference body only when its sha256 is the recorded one; otherwise its skill cannot be
48
+ * `current` and the playbook is listed in `moved`. Closed: no skill is `current`.
49
+ */
50
+ export declare function judgedSkillStates(packageRoot: string, target: string): JudgedSkills;
@@ -0,0 +1,259 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.playbookDigestInputs = playbookDigestInputs;
37
+ exports.anchoredPlaybookInputs = anchoredPlaybookInputs;
38
+ exports.latestBySequence = latestBySequence;
39
+ exports.judgedSkillStates = judgedSkillStates;
40
+ // @implements A-SPEC-794.110, A-SPEC-794.113
41
+ /**
42
+ * What an installed recovery skill is judged against — decided here, once, for doctor, init and the product-installed
43
+ * judgement of the autonomous shell approval. None of the three chooses a reference, so they agree when they run from
44
+ * the same install (doctor run from another install than the one the sessions load judges with that install's).
45
+ *
46
+ * The judgement was repaired three times in a row because the judged workspace could choose the reference: the working
47
+ * tree (794.100), HEAD (794.106), then a baseline commit whose binding read the target's index and core.worktree and whose
48
+ * commit could be rolled back through a fallback (794.107; re-check of d77e59d9, A 1/1/2/2). The contract now:
49
+ *
50
+ * - Binding: the running package's real path (project/running-package.ts). Deployed — a `node_modules` segment — is
51
+ * judged against the package's own playbook files. The hook refuses a write from the session to that package's
52
+ * playbooks and dist (A-SPEC-794.113, pre-tool-use.ts `referenceInputWrite`; measured 2026-11-12 before it: the
53
+ * playbooks were writable by the file tools and the shell, the dist by the shell and, outside the project, by the
54
+ * file tools too). No git command and no file of the target decides the binding.
55
+ * - Any other package is a checkout whose playbooks the workspace may be editing. Its reference is the playbook digests
56
+ * the gate recorded at its last allowed build, in the latest `principle7-baseline` row of THIS WRITER'S OWN ledger chain
57
+ * (the chain file in the working tree, read through the trusted read). Another replica's chain is not read: the trusted
58
+ * read takes it from HEAD's blob, which a ref move changes. Git decides nothing about the reference: neither this
59
+ * module nor the record reads a git object. The record (governance/autonomy.ts, recordBaseline) writes a digest only
60
+ * when it is the one the latest digest-bearing row of this chain carried, or when a person's window of this chain
61
+ * names the playbook in the build's own judgement and a window row after the baseline holds those bytes. So a
62
+ * chain's first digests are made by a window that names the playbooks, and the reference moves forward only
63
+ * (A-SPEC-794.113).
64
+ * - Closed, never a fallback: no such row, a latest row without digests, an own chain that does not verify, or a ledger
65
+ * that cannot be read. No skill is `current` then, and the reason is one line that names the way out.
66
+ *
67
+ * The ledger is as strong as a person's seal is: both are rows of the same protected chain (the hook refuses a shell
68
+ * append, copy, move, interpreter write and git checkout over it — measured 2026-11-12, A-SPEC-794.111).
69
+ */
70
+ const crypto = __importStar(require("node:crypto"));
71
+ const fs = __importStar(require("node:fs"));
72
+ const path = __importStar(require("node:path"));
73
+ const playbook_skill_states_1 = require("./playbook-skill-states");
74
+ const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
75
+ const PLAYBOOK_INPUT = /^playbook:([^:\s]+):([0-9a-f]{64})$/;
76
+ const playbookFile = (packageRoot, name) => path.join(packageRoot, 'playbooks', name, 'PLAYBOOK.md');
77
+ const digestOfPlaybook = (packageRoot, name) => {
78
+ try {
79
+ return sha256(fs.readFileSync(playbookFile(packageRoot, name)));
80
+ }
81
+ catch {
82
+ return null;
83
+ } // [no-substitution: unreadable → no digest, so its skill is never `current`]
84
+ };
85
+ /**
86
+ * The `playbook:<name>:<sha256>` inputs a `principle7-baseline` row carries: one per playbook the package ships, the
87
+ * sha256 of its PLAYBOOK.md bytes. The digest is of the playbook's body, not of the installed skill: the row is written
88
+ * by the hook that runs BEFORE the build, and must not depend on that build's marker format. A playbook that cannot be
89
+ * read, or whose name could not be told apart in the input, is not recorded — so its skill is never `current`.
90
+ */
91
+ function playbookDigestInputs(packageRoot) {
92
+ const out = [];
93
+ for (const name of (0, playbook_skill_states_1.playbookNames)(packageRoot)) {
94
+ const digest = digestOfPlaybook(packageRoot, name);
95
+ const input = `playbook:${name}:${digest}`;
96
+ if (digest !== null && PLAYBOOK_INPUT.test(input))
97
+ out.push(input);
98
+ }
99
+ return out.sort();
100
+ }
101
+ /**
102
+ * A-SPEC-794.113 — which digests a new baseline row may carry. `now` are the working tree's inputs, `before` the
103
+ * inputs of the latest digest-bearing row of this writer's chain, `anchored` the playbooks whose content a person's
104
+ * window of this chain saw and names now, `removed` those whose removal such a window names. A digest unchanged since
105
+ * `before`, or anchored, is written; any other keeps the digest `before` carried — the reference does not move for it —
106
+ * or, when `before` had none for it, is left out. A playbook the working tree no longer holds is carried on with the
107
+ * digest `before` had, unless it is in `removed`.
108
+ */
109
+ function anchoredPlaybookInputs(now, before, anchored, removed = new Set()) {
110
+ const parse = (i) => PLAYBOOK_INPUT.exec(i);
111
+ const earlier = new Map();
112
+ for (const i of before) {
113
+ const m = parse(i);
114
+ if (m)
115
+ earlier.set(m[1], m[2]);
116
+ }
117
+ const out = [];
118
+ const present = new Set();
119
+ for (const i of now) {
120
+ const m = parse(i);
121
+ if (!m)
122
+ continue;
123
+ const [, name, digest] = m;
124
+ present.add(name);
125
+ if (earlier.get(name) === digest || anchored.has(name))
126
+ out.push(i);
127
+ else if (earlier.has(name))
128
+ out.push(`playbook:${name}:${earlier.get(name)}`);
129
+ }
130
+ // a playbook the earlier row carried and the tree no longer holds (or that cannot be read now) is carried on: the
131
+ // reference does not forget it unless a person's window names its removal
132
+ for (const [name, digest] of earlier)
133
+ if (!present.has(name) && !removed.has(name))
134
+ out.push(`playbook:${name}:${digest}`);
135
+ return out.sort();
136
+ }
137
+ /**
138
+ * The one choice of "the latest row" for the reader and the record (review A, L3: the two chose by different orders): in
139
+ * one writer's chain the sequence is the order rows were written in.
140
+ */
141
+ function latestBySequence(rows) {
142
+ return rows.length === 0 ? null : rows.reduce((a, b) => (Number(b.seq) > Number(a.seq) ? b : a));
143
+ }
144
+ /** The latest build the gate recorded in this writer's own chain, or why there is none to trust (one line). */
145
+ function recordedBuild(packageRoot) {
146
+ // review B (low 2) — a package reached through a link (npm link, a file: dependency, a workspace) is the checkout the
147
+ // link points at: the text shows that path and says so, not the linked path that looks like an install
148
+ const real = (() => { try {
149
+ return fs.realpathSync.native(packageRoot);
150
+ }
151
+ catch {
152
+ return path.resolve(packageRoot);
153
+ } })(); // [no-substitution: nothing exists at the path → its spelling, where no ledger is found and the reference is closed]
154
+ const where = real === path.resolve(packageRoot)
155
+ // (review B, confirming, low 1 — the gate passes a real path, so a link is not seen here: the text says it once)
156
+ ? `this holmes-kit at ${real} is not an npm-installed package (one reached through npm link, a file: dependency or a workspace link is a checkout too)`
157
+ : `this holmes-kit at ${packageRoot} is a link to the checkout ${real}, not an npm-installed package`;
158
+ // review B (medium 2) — what records a build is the hook of a governed agent session, not the build script itself
159
+ // (worded without "in a terminal": the census of typed approval commands reads that phrase after "record" as one)
160
+ const governed = 'a build run in a governed agent session (a build run outside such a session records nothing)';
161
+ // review B (confirming, M1 and L4) — the causes as they are (a run and a changed replica id write a chain of their
162
+ // own, as a new clone or worktree does), and which seal opens it: one naming the playbooks, in a session here
163
+ const makes = `a person seals, in a session in this checkout, an A-SPEC whose Files to Touch names the playbooks (each \`playbooks/<name>/PLAYBOOK.md\`, or \`playbooks/**\`), and ${governed} inside that window records them`;
164
+ const noBaseline = `${where}, and this checkout has no baseline of its own (a new clone or worktree, a run or another replica id — each writes a chain of its own — or a package unpacked by hand) — ${makes}; `
165
+ + 'or install holmes-kit with npm, wire the project to that install (holmes-kit init) and reconnect the MCP server';
166
+ const dir = path.join(real, '.ax', 'ledger');
167
+ if (!fs.existsSync(dir))
168
+ return { closed: noBaseline };
169
+ let rows;
170
+ let own;
171
+ try {
172
+ const { TrustedLedgerStore } = require('../governance/recorded-pairs');
173
+ const store = new TrustedLedgerStore(dir);
174
+ own = store.replicaId();
175
+ // A-SPEC-794.114 — the chain must be the one this repository wrote (a tree move takes it back with the tree, and a
176
+ // chain extended outside comes in by git): otherwise no recorded build is trusted
177
+ // (the witness module itself, not autonomy.ts's helper: autonomy.ts imports this module — no cycle, A-SPEC-574.3)
178
+ const { chainWitnessVerdict } = require('../governance/ledger-witness');
179
+ const { writerChainFile } = require('../governance/ledger-store');
180
+ const witnessed = chainWitnessVerdict(writerChainFile(dir));
181
+ if (!witnessed.ok) {
182
+ return { closed: `${where}, and its provenance ledger is not the one this repository wrote (${witnessed.kind}: ${witnessed.detail}) — return the tree if it moved, or a person vouches for the chain as it is (\`holmes-kit ledger witness\`, decided in the session's approval form); nothing here stands in for it` };
183
+ }
184
+ if (store.ownChainBroken()) {
185
+ // review B (low 4) — the command, where one fits
186
+ return { closed: `${where}, and this writer's ledger chain under ${dir} does not verify, so no recorded build is trusted — a person repairs the ledger (\`holmes-kit ledger rechain\` re-chains a chain a merge forked; a row added or changed by hand is the person's to judge); nothing here stands in for it` };
187
+ }
188
+ rows = store.loadAll().filter((e) => e.replicaId === own && e.kind === 'principle7-baseline' && e.actor === 'holmes-kit'
189
+ && typeof e.ts === 'string' && Array.isArray(e.inputs) && e.inputs.some((i) => /^commit:[0-9a-f]{40,64}$/.test(String(i))));
190
+ }
191
+ catch { // [no-substitution: unreadable ledger → closed]
192
+ return { closed: `${where}, and its ledger under ${dir} cannot be read, so no recorded build is trusted — a person repairs the ledger; nothing here stands in for it` };
193
+ }
194
+ const latest = latestBySequence(rows);
195
+ // (which chain was read: a run, a worktree and a changed replica id each have their own)
196
+ if (latest === null)
197
+ return { closed: `${noBaseline} (the chain read: ${own})` };
198
+ const inputs = latest.inputs.map(String);
199
+ const commit = inputs.find((i) => /^commit:[0-9a-f]{40,64}$/.test(i)).slice('commit:'.length);
200
+ const digests = new Map();
201
+ for (const i of inputs) {
202
+ const m = PLAYBOOK_INPUT.exec(i);
203
+ if (m)
204
+ digests.set(m[1], m[2]);
205
+ }
206
+ if (digests.size === 0) {
207
+ // no fallback to an older row that has them: the latest allowed build is the product, and this one says nothing.
208
+ // The first digests of a chain are made by a window that names the playbooks (no bootstrap from the commit).
209
+ return { closed: `${where}, and the latest build its gate recorded (${String(latest.ts)}, ${commit.slice(0, 12)}, chain ${own}) carries no playbook digests yet (a gate older than 0.41.0 recorded it, or no window has named the playbooks here) — ${makes}` };
210
+ }
211
+ return { ts: String(latest.ts), commit, digests, replica: own };
212
+ }
213
+ /** Each playbook's bytes, read once (null when it cannot be read). */
214
+ function playbookBytes(packageRoot, names) {
215
+ return new Map(names.map((name) => { try {
216
+ return [name, fs.readFileSync(playbookFile(packageRoot, name))];
217
+ }
218
+ catch {
219
+ return [name, null];
220
+ } })); // [no-substitution: unreadable → null, and a skill with no body to compare is not `current`]
221
+ }
222
+ /**
223
+ * Every recovery skill's state in `target`, against the reference `packageRoot` has. With a ledger reference a playbook's
224
+ * working-tree body is the reference body only when its sha256 is the recorded one; otherwise its skill cannot be
225
+ * `current` and the playbook is listed in `moved`. Closed: no skill is `current`.
226
+ */
227
+ function judgedSkillStates(packageRoot, target) {
228
+ const running = require('./running-package');
229
+ if (running.isDeployedPackage(packageRoot))
230
+ return { states: (0, playbook_skill_states_1.playbookSkillStates)(packageRoot, target), reference: { kind: 'package' }, moved: [] };
231
+ // review A (L1) — each playbook is read once: the body the verdict compares the skill with and the digest compared
232
+ // with the record are the same bytes (two reads let a write between them split the two)
233
+ const names = (0, playbook_skill_states_1.playbookNames)(packageRoot);
234
+ const bytes = playbookBytes(packageRoot, names);
235
+ const working = (0, playbook_skill_states_1.playbookSkillStates)(packageRoot, target, { names: () => names, body: (name) => bytes.get(name)?.toString('utf8') ?? null });
236
+ const notCurrent = (s) => (s.state === 'current' ? { name: s.name, state: 'drifted' } : s);
237
+ const recorded = recordedBuild(packageRoot);
238
+ if ('closed' in recorded)
239
+ return { states: working.map(notCurrent), reference: { kind: 'closed', reason: recorded.closed }, moved: [] };
240
+ const shipped = new Set(names);
241
+ const moved = [];
242
+ // a playbook the recorded build shipped and the working tree no longer holds: the package's own damage, not an orphan
243
+ const gone = [...recorded.digests.keys()].filter((name) => !shipped.has(name));
244
+ const goneSkills = new Set(gone.map(playbook_skill_states_1.invocableSkillName));
245
+ const states = working.filter((s) => !(s.state === 'orphaned' && goneSkills.has(s.name))).map((s) => {
246
+ if (!shipped.has(s.name) || s.state === 'orphaned')
247
+ return s;
248
+ const b = bytes.get(s.name) ?? null;
249
+ if (b !== null && recorded.digests.get(s.name) === sha256(b))
250
+ return s;
251
+ moved.push(s.name);
252
+ return notCurrent(s);
253
+ });
254
+ for (const name of gone) {
255
+ moved.push(name);
256
+ states.push({ name, state: 'source-unreadable' });
257
+ }
258
+ return { states, reference: { kind: 'ledger', recordedAt: recorded.ts, commit: recorded.commit, replica: recorded.replica }, moved: moved.sort() };
259
+ }
@@ -0,0 +1,94 @@
1
+ /**
2
+ * (origin: A-SPEC-190 round 7)
3
+ * The bytes an install writes. The marker used to go FIRST, which put it ahead of the playbook's
4
+ * YAML frontmatter — and frontmatter is only frontmatter when it starts at byte 0. Measured on this
5
+ * repository's own installed skills: the agent's skill list rendered
6
+ * `holmes-adopt: <!-- installed by holmes-kit; edits will be replaced on upgrade -->` for all three,
7
+ * i.e. the `description` that quotes the deny text — the entire reason this layer exists, since a
8
+ * refusal is supposed to summon the playbook by that sentence — was destroyed at install time,
9
+ * while doctor certified the layout as `current`. The marker now follows the frontmatter block.
10
+ */
11
+ export declare function installedSkillBytes(body: string): string;
12
+ /**
13
+ * (origin: A-SPEC-172)
14
+ * What the user types to reach a playbook.
15
+ *
16
+ * The install directory is namespaced (`holmes-adopt`), but the internal playbook name is bare
17
+ * (`adopt`), and every message echoed the bare one. Measured 2026-08-12 on an installed tarball: init
18
+ * printed `Installed 3 recovery skill(s): adopt, author-slice, promote-slice` while nothing by those
19
+ * names existed. Anything shown to a user goes through here.
20
+ */
21
+ export declare function invocableSkillName(playbookName: string): string;
22
+ /** `<target>/.claude/skills/holmes-<name>/SKILL.md` */
23
+ export declare function skillPathFor(target: string, playbookName: string): string;
24
+ export declare function playbookNames(packageRoot: string): string[];
25
+ export declare const isOurs: (file: string) => boolean;
26
+ /**
27
+ * (origin: A-SPEC-190 round 8)
28
+ * Which shipped names resolve to the SAME file as another (a link between skill directories, at file
29
+ * or directory level). Shared by install and by the state report so both say the same thing.
30
+ */
31
+ export declare function aliasGroupsOf(packageRoot: string, target: string): Map<string, string[]>;
32
+ export declare function aliasedNames(packageRoot: string, target: string): Set<string>;
33
+ /**
34
+ * The skills root, but only if it is genuinely INSIDE the target.
35
+ *
36
+ * (origin: A-SPEC-190 §12 round 11) — the link was refused at `.claude/skills` and at each skill
37
+ * directory, and traversed one level ABOVE both: with `<target>/.claude` itself a link to a central
38
+ * store, install wrote five shipped skills into someone else's tree and reported success, and
39
+ * `--remove` then deleted marker-owned files there with `failed` empty. One containment question,
40
+ * asked once, cannot be walked around by moving the link up a level. It also names the component
41
+ * that is actually a link — the old wording blamed `.claude/skills` for `.claude`.
42
+ */
43
+ export declare function skillsRootInside(target: string): {
44
+ dir: string;
45
+ } | {
46
+ refusal: string;
47
+ };
48
+ export type PlaybookSkillState = 'current' | 'drifted' | 'foreign' | 'missing' | 'orphaned' | 'source-unreadable' | 'aliased' | 'unresolvable';
49
+ /**
50
+ * A-SPEC-794.106 — where the reference playbooks come from: the names the package ships and a body by name (null when it
51
+ * cannot be read). None passed is the package's own files.
52
+ *
53
+ * A-SPEC-794.110 — no caller in the product passes one any more. The judgement passed HEAD's blobs here (794.106), then
54
+ * the baseline commit's (794.107); both were git objects the judged workspace could move. What an installed skill is
55
+ * judged against is decided in playbook-reference.ts (`judgedSkillStates`), which calls this function with the package's
56
+ * files and then holds each verdict to the playbook digests the gate recorded. Doctor, init and the gate call that
57
+ * function, not this one. The parameter stays for the verdict's own tests.
58
+ */
59
+ export interface PlaybookSource {
60
+ names(): string[];
61
+ body(name: string): string | null;
62
+ }
63
+ /**
64
+ * (origin: A-SPEC-190)
65
+ * Per-playbook state of the installed copy, judged against the bytes install would write NOW
66
+ * (`marker + '\n' + shipped body`). An installed skill is a COPY: the kit's conventions move on
67
+ * while the copy stays frozen at install time. Measured 2026-08-15 in this very repository: all
68
+ * three installed skills had drifted (diff 50/38/64 lines) and the author-slice copy still taught
69
+ * the abolished `A-SPEC-125.5 → T-SPEC-1255` id convention — while the count-only doctor check
70
+ * reported "3 of 3 … PASS". Equality with the reconstruction is the single source of truth; a
71
+ * version stamp or hash file would be a second truth that itself goes stale.
72
+ *
73
+ * A shipped body that cannot be read (a race — playbookNames just confirmed it) yields no entry
74
+ * for that name: silence beats a wrong repair hint.
75
+ */
76
+ export declare function playbookSkillStates(packageRoot: string, target: string, source?: PlaybookSource): {
77
+ name: string;
78
+ state: PlaybookSkillState;
79
+ }[];
80
+ /**
81
+ * (origin: A-SPEC-190 §6)
82
+ * Which extra `.claude/skills` entries are ORPHANED marker-owned installs? Pure — the fs facts
83
+ * (inode identity, marker ownership) come in as functions, so the case-SENSITIVE world is testable
84
+ * on any machine (round-5 HIGH lived exactly in the branch this box's case-folding FS cannot
85
+ * exercise: `Holmes-adopt` sliced to `adopt`, matched shipped, and was swallowed BEFORE the
86
+ * variant/inode logic — doctor printed PASS over stale marker-owned guidance).
87
+ *
88
+ * - exact canonical entries are the shipped loop's business (skip);
89
+ * - a case-variant with the SAME inode is the same physical dir (case-insensitive FS — skip;
90
+ * round-2: double-counting made the orphan remedy delete the current skill);
91
+ * - everything else marker-owned is orphaned; unreadable/markerless stays silent (ownership is
92
+ * the marker's job — user territory).
93
+ */
94
+ export declare function classifyExtraEntries(entries: string[], shipped: string[], sameInode: (entry: string, canonicalDir: string) => boolean | undefined, owned: (entry: string) => boolean): string[];