@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
@@ -36,7 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.settingsPathOf = exports.MATCHERS = exports.SERVER_NAME = void 0;
37
37
  exports.buildHookPlan = buildHookPlan;
38
38
  exports.runInit = runInit;
39
- // @implements A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-476.1
39
+ // @implements A-SPEC-794.110, A-SPEC-794.107, A-SPEC-727, A-SPEC-724, A-SPEC-721, A-SPEC-738, A-SPEC-752.8, A-SPEC-772.2, A-SPEC-772.4, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-476.1
40
40
  // @implements A-SPEC-709
41
41
  // @implements A-SPEC-769.11
42
42
  // @implements A-SPEC-340
@@ -990,8 +990,9 @@ function runInitUnguarded(opts) {
990
990
  // shipped states, so `--remove` under-reported (orphaned marker-owned skills are deleted by the
991
991
  // real run and were absent from the plan: 3 announced, 4 deleted), and every planned path was
992
992
  // rendered by the caller's write-verb.
993
- const { playbookSkillStates } = require('./playbook-skills');
994
- const states = playbookSkillStates(opts.packageRoot, opts.target);
993
+ // A-SPEC-794.110 — the one reference doctor and the gate read (init read the working tree's playbooks)
994
+ const { judgedSkillStates } = require('../project/playbook-reference');
995
+ const states = judgedSkillStates(opts.packageRoot, opts.target).states;
995
996
  if (opts.remove) {
996
997
  // removePlaybookSkills deletes every marker-owned `holmes-*` SKILL.md — shipped or orphaned.
997
998
  const planned = states.filter((x) => x.state === 'current' || x.state === 'drifted' || x.state === 'orphaned' || x.state === 'aliased');
@@ -1207,7 +1208,7 @@ function runInitUnguarded(opts) {
1207
1208
  // skill's own (round 28: one representative path let a link at `.claude/skills/holmes-tdd-slice` overwrite another
1208
1209
  // project's SKILL.md — measured).
1209
1210
  const skillStates = (() => { try {
1210
- return require('./playbook-skills').playbookSkillStates(opts.packageRoot, opts.target);
1211
+ return require('../project/playbook-reference').judgedSkillStates(opts.packageRoot, opts.target).states;
1211
1212
  }
1212
1213
  catch {
1213
1214
  return [];
@@ -1386,11 +1387,21 @@ function runInitUnguarded(opts) {
1386
1387
  return [];
1387
1388
  return fs.readdirSync(p).flatMap((n) => filesUnder(path.join(p, n)));
1388
1389
  };
1390
+ // @implements A-SPEC-794.107 (B-M2) — a skill init left untouched ("Left your own … untouched") is the user's, not
1391
+ // the product's: it is not recorded, and a record an earlier init made of it is dropped
1392
+ const nowStates = (() => { try {
1393
+ return require('../project/playbook-reference').judgedSkillStates(opts.packageRoot, opts.target).states;
1394
+ }
1395
+ catch {
1396
+ return [];
1397
+ } })();
1398
+ const foreignNow = new Set(nowStates.filter((x) => x.state === 'foreign').map((x) => x.name));
1399
+ const foreignFiles = [...foreignNow].flatMap((n) => filesUnder(path.dirname((0, playbook_skills_1.skillPathFor)(opts.target, n))));
1389
1400
  manifest.writeInstallManifest(opts.target, [
1390
1401
  ...changes.filter((c) => c.after !== null).map((c) => c.path),
1391
- ...skillStates.flatMap((x) => filesUnder(path.dirname((0, playbook_skills_1.skillPathFor)(opts.target, x.name)))),
1402
+ ...skillStates.filter((x) => !foreignNow.has(x.name)).flatMap((x) => filesUnder(path.dirname((0, playbook_skills_1.skillPathFor)(opts.target, x.name)))),
1392
1403
  path.join(opts.target, '.ax', 'roles', 'README.md'),
1393
- ].flatMap(filesUnder), (0, mcp_launcher_1.readPackageVersion)(opts.packageRoot) ?? 'unknown');
1404
+ ].flatMap(filesUnder), (0, mcp_launcher_1.readPackageVersion)(opts.packageRoot) ?? 'unknown', { drop: foreignFiles });
1394
1405
  }
1395
1406
  }
1396
1407
  catch (e) {
@@ -0,0 +1,61 @@
1
+ export type WitnessGateVerdict = {
2
+ proceed: true;
3
+ spend?: string;
4
+ approval?: {
5
+ nonce?: string;
6
+ };
7
+ } | {
8
+ proceed: false;
9
+ id: string;
10
+ message: string;
11
+ };
12
+ export interface WitnessGateDeps {
13
+ guard: () => string | null;
14
+ resolve: (askRoot: string, env: unknown, action: {
15
+ kind: string;
16
+ target: string;
17
+ subject: string;
18
+ }, now: string) => {
19
+ approval: {
20
+ nonce?: string;
21
+ };
22
+ source: 'env' | 'grant';
23
+ } | undefined;
24
+ enqueue: (askRoot: string, req: {
25
+ kind: string;
26
+ target: string;
27
+ why: string;
28
+ subject: string;
29
+ title: string;
30
+ }) => void;
31
+ }
32
+ export interface WitnessFacts {
33
+ text: string;
34
+ subject: string;
35
+ upstream: 'none' | 'same' | 'extends' | 'shorter' | 'diverged';
36
+ }
37
+ /** The facts a person vouches on, for this writer's chain in `root`. */
38
+ export declare function ledgerWitnessFacts(root: string): WitnessFacts;
39
+ /** May `holmes-kit ledger witness` write the witness for the chain as it is now? */
40
+ export declare function ledgerWitnessGate(input: {
41
+ root: string;
42
+ askRoot: string;
43
+ now: string;
44
+ envApproval?: unknown;
45
+ }, deps: WitnessGateDeps): WitnessGateVerdict;
46
+ /**
47
+ * Runs `act` under the grant the gate found (claimed before, spent and committed after it succeeds, released if it
48
+ * throws), as `autonomy on` does (A-SPEC-245.4). With no grant to spend, `act` simply runs.
49
+ */
50
+ export declare function underGrant<T>(root: string, verdict: {
51
+ spend?: string;
52
+ approval?: unknown;
53
+ }, what: string, act: () => T): T;
54
+ /** May `holmes-kit ledger rechain` apply this plan? */
55
+ export declare function rechainGate(input: {
56
+ root: string;
57
+ askRoot: string;
58
+ now: string;
59
+ plan: string;
60
+ envApproval?: unknown;
61
+ }, deps: WitnessGateDeps): WitnessGateVerdict;
@@ -0,0 +1,212 @@
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.ledgerWitnessFacts = ledgerWitnessFacts;
37
+ exports.ledgerWitnessGate = ledgerWitnessGate;
38
+ exports.underGrant = underGrant;
39
+ exports.rechainGate = rechainGate;
40
+ // @implements A-SPEC-794.114, A-SPEC-794.116
41
+ /**
42
+ * The person's acts over the ledger witness (A-SPEC-794.114):
43
+ * - `holmes-kit ledger witness` — vouch for this repository's provenance chain as it is. From a session it files a
44
+ * `ledger-witness` request whose subject is the chain's head (the sha256 of the whole file) and whose text is what the
45
+ * person reads in the session's approval form; run again after the person's grant for that head, it writes the
46
+ * witness. A chain that moved since is not covered (another head is another subject).
47
+ * - the guard of `holmes-kit ledger rechain` — a rechain rewrites the chain wholesale; measured 11-12 it had no guard of
48
+ * its own inside a session. It applies only to a plan (its subject) a person approved; --dry-run needs none.
49
+ * Both follow `autonomy on`'s order (A-SPEC-718.7): a grant from the session form that covers this subject, a person at
50
+ * their own terminal (the operator guard finds no agent), or a request filed for the form.
51
+ *
52
+ * What the form shows is computed here once and comes from the judgement's own verdict (`chainWitnessVerdict`), not a
53
+ * second computation: a hash means nothing to a person, so the text gives the comparison with the pushed chain first —
54
+ * "shorter" in words — then the rows a person acts on, the gate rows, and the baseline.
55
+ */
56
+ const fs = __importStar(require("node:fs"));
57
+ const path = __importStar(require("node:path"));
58
+ const node_child_process_1 = require("node:child_process");
59
+ const ledger_store_1 = require("../governance/ledger-store");
60
+ const ledger_witness_1 = require("../governance/ledger-witness");
61
+ const approval_queue_1 = require("../governance/approval-queue");
62
+ const rowsOf = (text) => text.split('\n').filter((l) => l.trim() !== '').map((l) => { try {
63
+ return JSON.parse(l);
64
+ }
65
+ catch {
66
+ return {};
67
+ } }); // [no-substitution: an unparsable line is an empty row, shown as such]
68
+ const LIST_MAX = 40;
69
+ /** Read with principle 7's pinned git (no inherited GIT_* variable, no replacement objects); null when git cannot answer. */
70
+ function gitText(root, args) {
71
+ try {
72
+ const { principle7GitEnv } = require('../governance/autonomy');
73
+ return (0, node_child_process_1.execFileSync)('git', ['--no-replace-objects', ...args], { cwd: root, env: principle7GitEnv(), encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000, maxBuffer: 256 * 1024 * 1024 });
74
+ }
75
+ catch {
76
+ return null;
77
+ } // [no-substitution: git cannot answer → the form says it could not compare]
78
+ }
79
+ /** The facts a person vouches on, for this writer's chain in `root`. */
80
+ function ledgerWitnessFacts(root) {
81
+ const chain = (0, ledger_store_1.writerChainFile)(path.join(root, '.ax', 'ledger'));
82
+ const verdict = (0, ledger_witness_1.chainWitnessVerdict)(chain);
83
+ const head = (0, ledger_witness_1.currentHead)(chain);
84
+ let text = '';
85
+ try {
86
+ text = fs.readFileSync(chain, 'utf8');
87
+ }
88
+ catch { /* [no-substitution: absent is the empty chain, as its head says] */ }
89
+ const rows = rowsOf(text);
90
+ // 1. against the pushed chain
91
+ const rel = path.relative(gitText(root, ['rev-parse', '--show-toplevel'])?.trim() || root, chain).split(path.sep).join('/');
92
+ const upstreamRef = gitText(root, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'])?.trim() || null;
93
+ const pushedText = upstreamRef === null ? null : gitText(root, ['show', `${upstreamRef}:${rel}`]);
94
+ const pushed = pushedText === null ? null : rowsOf(pushedText);
95
+ let upstream = 'none';
96
+ let from = 0; // the compared point: rows after it are listed
97
+ let first;
98
+ if (upstreamRef === null) {
99
+ first = 'There is no upstream branch to compare this chain with, so judge from the rows below and the baseline alone.';
100
+ from = verdict.ok ? 0 : (verdict.witnessed ? verdict.witnessed.seq + 1 : 0);
101
+ }
102
+ else if (pushed === null) {
103
+ first = `The upstream ${upstreamRef} holds no copy of this chain (${rel}), so judge from the rows below and the baseline alone.`;
104
+ from = verdict.ok ? 0 : (verdict.witnessed ? verdict.witnessed.seq + 1 : 0);
105
+ }
106
+ else {
107
+ let common = 0;
108
+ while (common < Math.min(rows.length, pushed.length) && rows[common].hash !== undefined && rows[common].hash === pushed[common].hash)
109
+ common++;
110
+ if (common === rows.length && common === pushed.length) {
111
+ upstream = 'same';
112
+ first = `This chain is the pushed one (${upstreamRef}, ${pushed.length} rows).`;
113
+ from = rows.length;
114
+ }
115
+ else if (common === pushed.length) {
116
+ upstream = 'extends';
117
+ first = `This chain extends the pushed one (${upstreamRef}, ${pushed.length} rows) by ${rows.length - common} row(s).`;
118
+ from = common;
119
+ }
120
+ else if (common === rows.length) {
121
+ upstream = 'shorter';
122
+ first = `THIS CHAIN IS SHORTER than the pushed one (${upstreamRef}: ${pushed.length} rows, here ${rows.length}) — it was taken back. Do not vouch unless you mean to make this older chain the reference; return the tree instead.`;
123
+ from = rows.length;
124
+ }
125
+ else {
126
+ upstream = 'diverged';
127
+ first = `This chain has DIVERGED from the pushed one (${upstreamRef}) after row ${common}: ${rows.length - common} row(s) here are not in it, and ${pushed.length - common} there are not here.`;
128
+ from = common;
129
+ }
130
+ }
131
+ // 2. the judgement's own verdict, as it reads now
132
+ const lines = [first, `The judgement reads this chain as: ${verdict.ok ? 'ok' : `${verdict.kind} — ${verdict.detail}`}. Vouching makes the chain as it is now (${head.seq + 1} rows, sha256 ${head.sha256.slice(0, 16)}…) the one this repository wrote.`];
133
+ // 3. the rows a person acts on after the compared point, and the gate's own rows
134
+ const after = rows.slice(from);
135
+ const { isHumanChannelActor } = require('../governance/human-channel');
136
+ const personal = after.filter((r) => isHumanChannelActor(r.actor) || /^grant:/.test(String(r.actor ?? '')) || /^spec-(?:approved|unsealed|retired)$/.test(String(r.kind ?? '')));
137
+ const name = (r) => `${r.ts ?? '?'} ${r.kind ?? '?'}${Array.isArray(r.inputs) && r.inputs.length > 0 ? ` ${String(r.inputs[0])}` : ''} by ${String(r.actor ?? '?')}`;
138
+ lines.push(personal.length === 0
139
+ ? `Rows a person acts on after row ${from}: none.`
140
+ : `Rows a person acts on after row ${from} — recognise each one: ${personal.slice(-LIST_MAX).map(name).join('; ')}${personal.length > LIST_MAX ? ` (and ${personal.length - LIST_MAX} earlier)` : ''}.`);
141
+ const gateRows = after.filter((r) => String(r.actor ?? '') === 'holmes-kit');
142
+ const baselines = gateRows.filter((r) => r.kind === 'principle7-baseline');
143
+ lines.push(`Gate rows after row ${from}: ${gateRows.length} (refusals and records the gate wrote, including while the judgement was closed)${baselines.length > 0 ? `; baselines recorded: ${baselines.map((b) => `${String(b.inputs?.[0] ?? '').replace(/^commit:/, '').slice(0, 12)} at ${b.ts}`).join(', ')}` : ''}.`);
144
+ // 4. the latest baseline and the principle 7 files changed from it to HEAD
145
+ const latest = [...rows].reverse().find((r) => r.kind === 'principle7-baseline' && String(r.actor ?? '') === 'holmes-kit');
146
+ const commit = latest && Array.isArray(latest.inputs) ? String(latest.inputs.find((i) => /^commit:/.test(String(i))) ?? '').slice(7) : '';
147
+ if (commit === '')
148
+ lines.push('No baseline is recorded in this chain.');
149
+ else {
150
+ const ancestor = gitText(root, ['merge-base', '--is-ancestor', commit, 'HEAD']) !== null;
151
+ let changed = null;
152
+ try {
153
+ changed = require('../governance/autonomy').principle7Changes(root, commit);
154
+ }
155
+ catch {
156
+ changed = null;
157
+ } // [no-substitution: unreadable → the form says so]
158
+ lines.push(`The latest baseline is ${commit.slice(0, 12)} (${latest?.ts}); it is ${ancestor ? '' : 'NOT '}an ancestor of HEAD; principle 7 files changed from it: ${changed === null ? 'cannot be read' : changed.length === 0 ? 'none' : changed.slice(0, LIST_MAX).join(', ')}.`);
159
+ }
160
+ return { text: lines.join('\n'), subject: `head=${head.sha256}`, upstream };
161
+ }
162
+ function gate(kind, input, subject, why, title, deps) {
163
+ const action = { kind, target: input.root, subject };
164
+ const covering = deps.resolve(input.askRoot, input.envApproval, action, input.now);
165
+ // a grant from the session form counts; an environment approval only where no agent runs the act (A-SPEC-794.91)
166
+ if (covering !== undefined && (covering.source === 'grant' || deps.guard() === null)) {
167
+ const nonce = covering.approval.nonce;
168
+ return { proceed: true, approval: covering.approval, ...(covering.source === 'grant' && typeof nonce === 'string' ? { spend: nonce } : {}) };
169
+ }
170
+ const refusal = deps.guard();
171
+ if (refusal === null)
172
+ return { proceed: true };
173
+ deps.enqueue(input.askRoot, { ...action, why: why(), title });
174
+ const id = (0, approval_queue_1.approvalRequestId)(kind, input.root);
175
+ return { proceed: false, id, message: `${refusal}${(0, approval_queue_1.pendingRequestLine)(id, kind, input.askRoot, title, input.root)}` };
176
+ }
177
+ /** May `holmes-kit ledger witness` write the witness for the chain as it is now? */
178
+ function ledgerWitnessGate(input, deps) {
179
+ const facts = ledgerWitnessFacts(input.root);
180
+ return gate('ledger-witness', input, facts.subject, () => facts.text, 'vouch for this repository\'s provenance chain as it is', deps);
181
+ }
182
+ /**
183
+ * Runs `act` under the grant the gate found (claimed before, spent and committed after it succeeds, released if it
184
+ * throws), as `autonomy on` does (A-SPEC-245.4). With no grant to spend, `act` simply runs.
185
+ */
186
+ function underGrant(root, verdict, what, act) {
187
+ if (verdict.spend === undefined)
188
+ return act();
189
+ const { claimGrant, spendGrantApprovals } = require('../governance/approval-grants');
190
+ const claim = claimGrant(root, verdict.spend);
191
+ if (claim === null)
192
+ throw new Error('the approval grant for this act is in use by another act — nothing was done; retry');
193
+ let out;
194
+ try {
195
+ out = act();
196
+ spendGrantApprovals(root, [verdict.approval], what);
197
+ }
198
+ catch (e) {
199
+ claim.release();
200
+ throw e;
201
+ } // [no-substitution: the act failed → the grant is released, nothing is spent, the failure is thrown on]
202
+ claim.commit();
203
+ return out;
204
+ }
205
+ /** May `holmes-kit ledger rechain` apply this plan? */
206
+ function rechainGate(input, deps) {
207
+ // A-SPEC-794.116 — the request shows the chain's state as the judgement reads it now, and says that approving the
208
+ // rechain does not vouch for the chain (the witness is moved only by `holmes-kit ledger witness`)
209
+ const verdict = (0, ledger_witness_1.chainWitnessVerdict)((0, ledger_store_1.writerChainFile)(path.join(input.root, '.ax', 'ledger')));
210
+ const state = verdict.ok ? 'the judgement reads this writer\'s chain as the one this repository wrote (ok)' : `the judgement reads this writer's chain as ${verdict.kind} — ${verdict.detail}`;
211
+ return gate('ledger-rechain', input, `plan=${input.plan}`, () => `rechain the provenance chains of ${input.root} — plan ${input.plan}: it rewrites each chain against the committed mainline and re-chains the rows outside it (see \`holmes-kit ledger rechain --dry-run\`). Now ${state}. Approving the rechain does not vouch for the chain: the ledger witness is not moved, and a chain that is not the witnessed one stays closed until a person runs \`holmes-kit ledger witness\``, 'rechain the provenance ledger (rewrites the chain; does not vouch)', deps);
212
+ }
@@ -13,29 +13,9 @@
13
13
  */
14
14
  import { PLAYBOOK_SKILL_MARKER, carriesMarker, frontmatterEnd } from '../project/installer-markers';
15
15
  export { PLAYBOOK_SKILL_MARKER, carriesMarker, frontmatterEnd };
16
- /**
17
- * @implements A-SPEC-190 (round 7)
18
- * The bytes an install writes. The marker used to go FIRST, which put it ahead of the playbook's
19
- * YAML frontmatter — and frontmatter is only frontmatter when it starts at byte 0. Measured on this
20
- * repository's own installed skills: the agent's skill list rendered
21
- * `holmes-adopt: <!-- installed by holmes-kit; edits will be replaced on upgrade -->` for all three,
22
- * i.e. the `description` that quotes the deny text — the entire reason this layer exists, since a
23
- * refusal is supposed to summon the playbook by that sentence — was destroyed at install time,
24
- * while doctor certified the layout as `current`. The marker now follows the frontmatter block.
25
- */
26
- export declare function installedSkillBytes(body: string): string;
27
- /**
28
- * @implements A-SPEC-172
29
- * What the user types to reach a playbook.
30
- *
31
- * The install directory is namespaced (`holmes-adopt`), but the internal playbook name is bare
32
- * (`adopt`), and every message echoed the bare one. Measured 2026-08-12 on an installed tarball: init
33
- * printed `Installed 3 recovery skill(s): adopt, author-slice, promote-slice` while nothing by those
34
- * names existed. Anything shown to a user goes through here.
35
- */
36
- export declare function invocableSkillName(playbookName: string): string;
37
- /** `<target>/.claude/skills/holmes-<name>/SKILL.md` */
38
- export declare function skillPathFor(target: string, playbookName: string): string;
16
+ import { installedSkillBytes, invocableSkillName, skillPathFor, playbookSkillStates, classifyExtraEntries, type PlaybookSkillState } from '../project/playbook-skill-states';
17
+ export { installedSkillBytes, invocableSkillName, skillPathFor, playbookSkillStates, classifyExtraEntries, type PlaybookSkillState };
18
+ export { judgedSkillStates, type JudgedSkills, type SkillReference } from '../project/playbook-reference';
39
19
  export interface PlaybookInstallResult {
40
20
  /** Playbook names written (new, or refreshed because the destination was ours). */
41
21
  written: string[];
@@ -72,38 +52,5 @@ export declare function removePlaybookSkills(target: string): PlaybookRemoveResu
72
52
  * already looks like a path is a path.
73
53
  */
74
54
  export declare function skillLabel(name: string): string;
75
- export type PlaybookSkillState = 'current' | 'drifted' | 'foreign' | 'missing' | 'orphaned' | 'source-unreadable' | 'aliased' | 'unresolvable';
76
- /**
77
- * @implements A-SPEC-190
78
- * Per-playbook state of the installed copy, judged against the bytes install would write NOW
79
- * (`marker + '\n' + shipped body`). An installed skill is a COPY: the kit's conventions move on
80
- * while the copy stays frozen at install time. Measured 2026-08-15 in this very repository: all
81
- * three installed skills had drifted (diff 50/38/64 lines) and the author-slice copy still taught
82
- * the abolished `A-SPEC-125.5 → T-SPEC-1255` id convention — while the count-only doctor check
83
- * reported "3 of 3 … PASS". Equality with the reconstruction is the single source of truth; a
84
- * version stamp or hash file would be a second truth that itself goes stale.
85
- *
86
- * A shipped body that cannot be read (a race — playbookNames just confirmed it) yields no entry
87
- * for that name: silence beats a wrong repair hint.
88
- */
89
- export declare function playbookSkillStates(packageRoot: string, target: string): {
90
- name: string;
91
- state: PlaybookSkillState;
92
- }[];
93
- /**
94
- * @implements A-SPEC-190 (§6)
95
- * Which extra `.claude/skills` entries are ORPHANED marker-owned installs? Pure — the fs facts
96
- * (inode identity, marker ownership) come in as functions, so the case-SENSITIVE world is testable
97
- * on any machine (round-5 HIGH lived exactly in the branch this box's case-folding FS cannot
98
- * exercise: `Holmes-adopt` sliced to `adopt`, matched shipped, and was swallowed BEFORE the
99
- * variant/inode logic — doctor printed PASS over stale marker-owned guidance).
100
- *
101
- * - exact canonical entries are the shipped loop's business (skip);
102
- * - a case-variant with the SAME inode is the same physical dir (case-insensitive FS — skip;
103
- * round-2: double-counting made the orphan remedy delete the current skill);
104
- * - everything else marker-owned is orphaned; unreadable/markerless stays silent (ownership is
105
- * the marker's job — user territory).
106
- */
107
- export declare function classifyExtraEntries(entries: string[], shipped: string[], sameInode: (entry: string, canonicalDir: string) => boolean | undefined, owned: (entry: string) => boolean): string[];
108
55
  /** How many recovery skills are installed — the fact `doctor` reports. */
109
56
  export declare function installedPlaybookCount(target: string): number;