@holmes-lab/holmes-kit 0.40.0 → 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 (119) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/README.md +79 -5
  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 +394 -267
  10. package/dist/holmes/cli/init.js +17 -6
  11. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  12. package/dist/holmes/cli/interactive-prompt.js +98 -16
  13. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  14. package/dist/holmes/cli/ledger-witness.js +212 -0
  15. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  16. package/dist/holmes/cli/playbook-skills.js +26 -349
  17. package/dist/holmes/config/config.d.ts +21 -0
  18. package/dist/holmes/config/config.js +22 -3
  19. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  20. package/dist/holmes/governance/approval-queue.js +279 -9
  21. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  22. package/dist/holmes/governance/autonomous-shell.js +157 -4
  23. package/dist/holmes/governance/autonomy.d.ts +216 -0
  24. package/dist/holmes/governance/autonomy.js +1162 -10
  25. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  26. package/dist/holmes/governance/install-manifest.js +144 -14
  27. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  28. package/dist/holmes/governance/ledger-witness.js +296 -0
  29. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  30. package/dist/holmes/governance/provenance-chain.js +23 -4
  31. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  32. package/dist/holmes/governance/push-gate-runner.js +40 -3
  33. package/dist/holmes/governance/push-gate.d.ts +13 -2
  34. package/dist/holmes/governance/push-gate.js +106 -14
  35. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  36. package/dist/holmes/governance/recorded-pairs.js +25 -1
  37. package/dist/holmes/governance/session-context.d.ts +7 -0
  38. package/dist/holmes/governance/session-context.js +34 -6
  39. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  40. package/dist/holmes/guardrail/advisory-line.js +718 -0
  41. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  42. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  43. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  44. package/dist/holmes/guardrail/command-traits.js +379 -0
  45. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  46. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  47. package/dist/holmes/guardrail/impact-gate.d.ts +6 -0
  48. package/dist/holmes/guardrail/impact-gate.js +32 -5
  49. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  50. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  51. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  52. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  53. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  54. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  55. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  56. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  57. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  58. package/dist/holmes/guardrail/write-target.js +7 -1
  59. package/dist/holmes/hooks/pre-tool-use.d.ts +71 -0
  60. package/dist/holmes/hooks/pre-tool-use.js +1466 -14
  61. package/dist/holmes/hooks/session-start.js +27 -1
  62. package/dist/holmes/hooks/stop.d.ts +7 -0
  63. package/dist/holmes/hooks/stop.js +39 -2
  64. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  65. package/dist/holmes/mcp/elicit-approval.js +5 -2
  66. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  67. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  68. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  69. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  70. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  71. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  72. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  73. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  74. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  75. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  76. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  77. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  78. package/dist/holmes/mcp/handlers/test-execution.d.ts +470 -3
  79. package/dist/holmes/mcp/handlers/test-execution.js +201 -21
  80. package/dist/holmes/mcp/handlers.d.ts +473 -8
  81. package/dist/holmes/mcp/handlers.js +6 -1
  82. package/dist/holmes/mcp/maintenance-analyze.d.ts +5 -0
  83. package/dist/holmes/mcp/maintenance-analyze.js +4 -2
  84. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  85. package/dist/holmes/mcp/maintenance-evidence.js +4 -1
  86. package/dist/holmes/mcp/tool-schemas.js +16 -10
  87. package/dist/holmes/project/baseline.d.ts +15 -2
  88. package/dist/holmes/project/baseline.js +11 -6
  89. package/dist/holmes/project/bounded-io.d.ts +1 -0
  90. package/dist/holmes/project/bounded-io.js +4 -2
  91. package/dist/holmes/project/change-source.d.ts +4 -0
  92. package/dist/holmes/project/change-source.js +13 -5
  93. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  94. package/dist/holmes/project/playbook-reference.js +259 -0
  95. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  96. package/dist/holmes/project/playbook-skill-states.js +396 -0
  97. package/dist/holmes/project/root.d.ts +9 -1
  98. package/dist/holmes/project/root.js +26 -3
  99. package/dist/holmes/project/running-package.d.ts +15 -0
  100. package/dist/holmes/project/running-package.js +87 -0
  101. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  102. package/dist/holmes/review/evidence-mode.js +33 -0
  103. package/dist/holmes/review/head-worktree.d.ts +55 -0
  104. package/dist/holmes/review/head-worktree.js +329 -0
  105. package/dist/holmes/review/mrp.js +13 -3
  106. package/dist/holmes/review/run-provenance.d.ts +45 -0
  107. package/dist/holmes/review/run-provenance.js +314 -0
  108. package/dist/holmes/review/test-evidence.d.ts +174 -0
  109. package/dist/holmes/review/test-evidence.js +330 -2
  110. package/dist/holmes/review/test-reports.d.ts +94 -0
  111. package/dist/holmes/review/test-reports.js +382 -0
  112. package/dist/holmes/review/test-runner.d.ts +178 -65
  113. package/dist/holmes/review/test-runner.js +551 -319
  114. package/dist/holmes/review/test-units.d.ts +159 -0
  115. package/dist/holmes/review/test-units.js +814 -0
  116. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  117. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  118. package/package.json +5 -2
  119. package/playbooks/publish/PLAYBOOK.md +2 -1
@@ -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) {
@@ -12,11 +12,48 @@ export declare function promptAgentSelection(availableAgents?: readonly Agent[],
12
12
  * The project autonomy-posture prompt. TTY-only (its raw-terminal read is the human-presence proof —
13
13
  * an agent's non-TTY Bash cannot reach it, so a `true` here is a human answer, not a self-grant).
14
14
  * Non-TTY returns false (leave HITL); the caller does not treat that as an interactive answer.
15
- * Default is NO — autonomy is opt-in.
15
+ * A-SPEC-552.2: Enter means the default — ON for a first install, the current value on a re-init.
16
16
  */
17
17
  /**
18
18
  * @implements A-SPEC-769.1 — what the prompt says matches the grader (X1, 2026-10-12: the old text said REQ/H-SPEC
19
19
  * "ALWAYS ask", while A-SPEC-587 seals an upstream autonomously when every A-SPEC beneath it is low-risk).
20
20
  */
21
21
  export declare const AUTONOMY_PROMPT_TEXT: string;
22
- export declare function promptAutonomy(): Promise<boolean>;
22
+ /**
23
+ * @implements A-SPEC-552.2, A-SPEC-552.3 — Enter takes the default: the current value, else ON at a person's own
24
+ * terminal and OFF under an agent harness or CI; y/yes and n/no decide; anything else is OFF.
25
+ */
26
+ export declare function autonomyAnswer(answer: string, current: boolean | undefined, underHarness?: boolean): boolean;
27
+ /** The question, its brackets naming what Enter means. */
28
+ export declare function autonomyQuestion(current: boolean | undefined, underHarness?: boolean): string;
29
+ /** @implements A-SPEC-552.3 — the target's current posture, read by the runtime's own reader (governance/autonomy). */
30
+ export declare function currentAutonomyAt(target: string): boolean | undefined;
31
+ /**
32
+ * @implements A-SPEC-552.3 — whether init runs where an agent could be answering: an agent harness among its parents
33
+ * (operatorActGuard names one, A-SPEC-102.29) or a CI environment. A pty an agent allocated still has one.
34
+ */
35
+ export declare function initUnderHarness(target: string, env?: NodeJS.ProcessEnv): boolean;
36
+ export interface AutonomyPromptIO {
37
+ stdinTTY: boolean;
38
+ stdoutTTY: boolean;
39
+ underHarness: boolean;
40
+ write: (text: string) => void;
41
+ ask: (question: string) => Promise<string>;
42
+ }
43
+ export interface InitAutonomy {
44
+ autonomy: boolean | undefined;
45
+ interactive: boolean;
46
+ }
47
+ /**
48
+ * @implements A-SPEC-552.2 — init's interactive choice. No TTY asks nothing and decides nothing (`autonomy` undefined:
49
+ * the posture is preserved, A-SPEC-552.1). ON is returned only with `interactive: true`, the proof a person answered.
50
+ */
51
+ export declare function initAutonomyChoice(target: string, io: AutonomyPromptIO): Promise<InitAutonomy>;
52
+ /**
53
+ * @implements A-SPEC-552.3 — init's whole autonomy decision, so index.ts makes none of its own: the flags first
54
+ * (`--autonomy` is gated in runInit, `--no-autonomy` is free), then the acts that ask nothing, then the question.
55
+ */
56
+ export declare function resolveInitAutonomy(flags: Record<string, unknown>, target: string, io: AutonomyPromptIO): Promise<InitAutonomy>;
57
+ /** The real terminal's io for `target`. */
58
+ export declare const terminalAutonomyIO: (target: string) => AutonomyPromptIO;
59
+ export declare function promptAutonomy(target?: string): Promise<boolean>;
@@ -33,13 +33,23 @@ var __importStar = (this && this.__importStar) || (function () {
33
33
  };
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
- exports.AUTONOMY_PROMPT_TEXT = void 0;
36
+ exports.terminalAutonomyIO = exports.AUTONOMY_PROMPT_TEXT = void 0;
37
37
  exports.parseAgentList = parseAgentList;
38
38
  exports.promptAgentSelection = promptAgentSelection;
39
+ exports.autonomyAnswer = autonomyAnswer;
40
+ exports.autonomyQuestion = autonomyQuestion;
41
+ exports.currentAutonomyAt = currentAutonomyAt;
42
+ exports.initUnderHarness = initUnderHarness;
43
+ exports.initAutonomyChoice = initAutonomyChoice;
44
+ exports.resolveInitAutonomy = resolveInitAutonomy;
39
45
  exports.promptAutonomy = promptAutonomy;
40
- // @implements A-SPEC-724, A-SPEC-200
46
+ // @implements A-SPEC-724, A-SPEC-200, A-SPEC-552.2, A-SPEC-552.3, A-SPEC-552.4
41
47
  const readline = __importStar(require("node:readline"));
42
48
  const agents_1 = require("./agents");
49
+ const autonomy_1 = require("../governance/autonomy");
50
+ const harness_catalog_1 = require("../governance/harness-catalog");
51
+ const operator_person_1 = require("../guardrail/operator-person");
52
+ const verdicts_1 = require("../review/verdicts");
43
53
  /**
44
54
  * Parses user input or CLI flag string into normalized Agent array.
45
55
  */
@@ -156,7 +166,7 @@ async function promptAgentSelection(availableAgents = agents_1.AGENTS, currentWi
156
166
  * The project autonomy-posture prompt. TTY-only (its raw-terminal read is the human-presence proof —
157
167
  * an agent's non-TTY Bash cannot reach it, so a `true` here is a human answer, not a self-grant).
158
168
  * Non-TTY returns false (leave HITL); the caller does not treat that as an interactive answer.
159
- * Default is NO — autonomy is opt-in.
169
+ * A-SPEC-552.2: Enter means the default — ON for a first install, the current value on a re-init.
160
170
  */
161
171
  /**
162
172
  * @implements A-SPEC-769.1 — what the prompt says matches the grader (X1, 2026-10-12: the old text said REQ/H-SPEC
@@ -165,18 +175,90 @@ async function promptAgentSelection(availableAgents = agents_1.AGENTS, currentWi
165
175
  exports.AUTONOMY_PROMPT_TEXT = '\n 🔑 Autonomous spec approval\n'
166
176
  + ' The agent may self-approve LOW-RISK specs (tests, benign changes). High-risk and irreversible\n'
167
177
  + ' specs (C-SPEC/ADR, gate/security/architecture files, root-only or unbounded Files to Touch)\n'
168
- + ' still ask you; a REQ or H-SPEC seals on its own only when every A-SPEC beneath it is low-risk,\n'
169
- + ' and a REQ never admitted through requirement_triage always asks. You can turn this off\n'
170
- + ' anytime: holmes-kit autonomy off.\n';
171
- async function promptAutonomy() {
172
- if (!process.stdin.isTTY || !process.stdout.isTTY)
173
- return false;
174
- return new Promise((resolve) => {
178
+ + ' and governance-critical ones still ask you; a REQ or H-SPEC seals on its own only\n'
179
+ + ' when every A-SPEC beneath it is low-risk, and a REQ never admitted through requirement_triage always asks.\n'
180
+ + ' The default is Y on a first install at your own terminal (recommended since 0.41): only low-risk\n'
181
+ + ' specs approve themselves. Under an agent harness or CI, Enter keeps the current value (off on a\n'
182
+ + ' first install). y or yes turns it on; any other answer turns it off.\n'
183
+ + ' To turn it off later: holmes-kit init --no-autonomy (or remove HOLMES_AUTONOMOUS_APPROVAL from\n'
184
+ + ' .mcp.json); holmes-kit autonomy off ends session autonomy only.\n';
185
+ /**
186
+ * @implements A-SPEC-552.2, A-SPEC-552.3 — Enter takes the default: the current value, else ON at a person's own
187
+ * terminal and OFF under an agent harness or CI; y/yes and n/no decide; anything else is OFF.
188
+ */
189
+ function autonomyAnswer(answer, current, underHarness = false) {
190
+ const a = answer.trim().toLowerCase();
191
+ if (a === '')
192
+ return current ?? !underHarness;
193
+ return a === 'y' || a === 'yes';
194
+ }
195
+ /** The question, its brackets naming what Enter means. */
196
+ function autonomyQuestion(current, underHarness = false) {
197
+ return ` Grant autonomous spec approval for this project? ${(current ?? !underHarness) ? '[Y/n]' : '[y/N]'} `;
198
+ }
199
+ /** @implements A-SPEC-552.3 — the target's current posture, read by the runtime's own reader (governance/autonomy). */
200
+ function currentAutonomyAt(target) {
201
+ return (0, autonomy_1.projectAutonomyState)(target);
202
+ }
203
+ /**
204
+ * @implements A-SPEC-552.3 — whether init runs where an agent could be answering: an agent harness among its parents
205
+ * (operatorActGuard names one, A-SPEC-102.29) or a CI environment. A pty an agent allocated still has one.
206
+ */
207
+ function initUnderHarness(target, env = process.env) {
208
+ if (typeof env.CI === 'string' && env.CI !== '' && env.CI !== 'false')
209
+ return true;
210
+ // @implements A-SPEC-552.4 — the given environment's harness markers, over the project's catalog; a catalog that
211
+ // cannot be read counts as a harness (Enter then keeps the value, the safe side)
212
+ try {
213
+ if ((0, verdicts_1.agentHarnessMarker)(env, (0, harness_catalog_1.liveHarnessCatalog)(target)) !== null)
214
+ return true;
215
+ }
216
+ catch {
217
+ return true;
218
+ }
219
+ return (0, operator_person_1.operatorActGuard)('turning on autonomous spec approval with Enter', target) !== null;
220
+ }
221
+ /**
222
+ * @implements A-SPEC-552.2 — init's interactive choice. No TTY asks nothing and decides nothing (`autonomy` undefined:
223
+ * the posture is preserved, A-SPEC-552.1). ON is returned only with `interactive: true`, the proof a person answered.
224
+ */
225
+ async function initAutonomyChoice(target, io) {
226
+ if (!io.stdinTTY || !io.stdoutTTY)
227
+ return { autonomy: undefined, interactive: false };
228
+ const current = currentAutonomyAt(target);
229
+ io.write(exports.AUTONOMY_PROMPT_TEXT);
230
+ const answer = await io.ask(autonomyQuestion(current, io.underHarness));
231
+ // @implements A-SPEC-552.4 — Enter that keeps a value writes nothing: the posture stays where the runtime reads it,
232
+ // and a switch another server entry holds is never copied into Holmes-Kit's own entry
233
+ if (answer.trim() === '' && current !== undefined)
234
+ return { autonomy: undefined, interactive: false };
235
+ const on = autonomyAnswer(answer, current, io.underHarness);
236
+ return { autonomy: on, interactive: on };
237
+ }
238
+ /**
239
+ * @implements A-SPEC-552.3 — init's whole autonomy decision, so index.ts makes none of its own: the flags first
240
+ * (`--autonomy` is gated in runInit, `--no-autonomy` is free), then the acts that ask nothing, then the question.
241
+ */
242
+ async function resolveInitAutonomy(flags, target, io) {
243
+ if (flags.autonomy === true)
244
+ return { autonomy: true, interactive: false };
245
+ if (flags['no-autonomy'] === true)
246
+ return { autonomy: false, interactive: false };
247
+ if (flags['dry-run'] === true || flags.remove === true || flags['no-mcp'] === true)
248
+ return { autonomy: undefined, interactive: false };
249
+ return initAutonomyChoice(target, io);
250
+ }
251
+ /** The real terminal's io for `target`. */
252
+ const terminalAutonomyIO = (target) => ({
253
+ stdinTTY: Boolean(process.stdin.isTTY), stdoutTTY: Boolean(process.stdout.isTTY),
254
+ underHarness: Boolean(process.stdin.isTTY && process.stdout.isTTY) && initUnderHarness(target),
255
+ write: (text) => { process.stdout.write(text); },
256
+ ask: (question) => new Promise((resolve) => {
175
257
  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
176
- process.stdout.write(exports.AUTONOMY_PROMPT_TEXT);
177
- rl.question(' Grant autonomous spec approval for this project? [y/N] ', (ans) => {
178
- rl.close();
179
- resolve(/^\s*y(es)?\s*$/i.test(ans));
180
- });
181
- });
258
+ rl.question(question, (ans) => { rl.close(); resolve(ans); });
259
+ }),
260
+ });
261
+ exports.terminalAutonomyIO = terminalAutonomyIO;
262
+ async function promptAutonomy(target = process.cwd()) {
263
+ return (await initAutonomyChoice(target, (0, exports.terminalAutonomyIO)(target))).autonomy === true;
182
264
  }
@@ -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;