@holmes-lab/holmes-kit 0.40.1 → 0.41.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/CHANGELOG.md +86 -0
  2. package/README.md +12 -4
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/cli/approve-context.js +4 -3
  5. package/dist/holmes/cli/approve.js +22 -12
  6. package/dist/holmes/cli/autonomy.d.ts +21 -0
  7. package/dist/holmes/cli/autonomy.js +35 -5
  8. package/dist/holmes/cli/doctor.js +58 -6
  9. package/dist/holmes/cli/index.js +371 -250
  10. package/dist/holmes/cli/init.js +26 -6
  11. package/dist/holmes/cli/ledger-witness.d.ts +61 -0
  12. package/dist/holmes/cli/ledger-witness.js +252 -0
  13. package/dist/holmes/cli/playbook-skills.d.ts +3 -56
  14. package/dist/holmes/cli/playbook-skills.js +63 -354
  15. package/dist/holmes/cli/test-platform.d.ts +6 -0
  16. package/dist/holmes/cli/test-platform.js +12 -0
  17. package/dist/holmes/config/config.d.ts +9 -1
  18. package/dist/holmes/config/config.js +10 -3
  19. package/dist/holmes/governance/approval-grants.d.ts +2 -0
  20. package/dist/holmes/governance/approval-grants.js +6 -5
  21. package/dist/holmes/governance/approval-queue.d.ts +65 -1
  22. package/dist/holmes/governance/approval-queue.js +279 -9
  23. package/dist/holmes/governance/autonomous-shell.d.ts +13 -1
  24. package/dist/holmes/governance/autonomous-shell.js +157 -4
  25. package/dist/holmes/governance/autonomy.d.ts +209 -0
  26. package/dist/holmes/governance/autonomy.js +1129 -6
  27. package/dist/holmes/governance/install-manifest.d.ts +7 -4
  28. package/dist/holmes/governance/install-manifest.js +159 -15
  29. package/dist/holmes/governance/ledger-witness.d.ts +63 -0
  30. package/dist/holmes/governance/ledger-witness.js +296 -0
  31. package/dist/holmes/governance/provenance-chain.d.ts +8 -1
  32. package/dist/holmes/governance/provenance-chain.js +23 -4
  33. package/dist/holmes/governance/recorded-pairs.d.ts +4 -0
  34. package/dist/holmes/governance/recorded-pairs.js +25 -1
  35. package/dist/holmes/governance/session-context.d.ts +7 -0
  36. package/dist/holmes/governance/session-context.js +34 -6
  37. package/dist/holmes/guardrail/anchor-scope-text.d.ts +9 -0
  38. package/dist/holmes/guardrail/anchor-scope-text.js +7 -0
  39. package/dist/holmes/guardrail/command-traits.d.ts +102 -0
  40. package/dist/holmes/guardrail/command-traits.js +379 -0
  41. package/dist/holmes/guardrail/fixtures/manager-builtins.json +23 -0
  42. package/dist/holmes/guardrail/fixtures/npm-commands.json +7 -0
  43. package/dist/holmes/guardrail/outward-acts.d.ts +47 -0
  44. package/dist/holmes/guardrail/outward-acts.js +1102 -0
  45. package/dist/holmes/guardrail/refusal-codes.js +8 -1
  46. package/dist/holmes/guardrail/refusal-templates.d.ts +15 -0
  47. package/dist/holmes/guardrail/refusal-templates.js +71 -0
  48. package/dist/holmes/guardrail/risk-classifier.d.ts +22 -6
  49. package/dist/holmes/guardrail/risk-classifier.js +12 -118
  50. package/dist/holmes/guardrail/shell-lexer.d.ts +69 -0
  51. package/dist/holmes/guardrail/shell-lexer.js +567 -0
  52. package/dist/holmes/guardrail/write-target.js +7 -1
  53. package/dist/holmes/hooks/pre-tool-use.d.ts +60 -0
  54. package/dist/holmes/hooks/pre-tool-use.js +1423 -10
  55. package/dist/holmes/hooks/session-start.js +11 -1
  56. package/dist/holmes/hooks/stop.d.ts +7 -0
  57. package/dist/holmes/hooks/stop.js +39 -2
  58. package/dist/holmes/mcp/elicit-approval.d.ts +0 -21
  59. package/dist/holmes/mcp/elicit-approval.js +5 -2
  60. package/dist/holmes/mcp/handlers/approval-ask.js +3 -2
  61. package/dist/holmes/mcp/handlers/entity-integration.d.ts +1 -1
  62. package/dist/holmes/mcp/handlers/entity-integration.js +9 -6
  63. package/dist/holmes/mcp/handlers/entity-renumber.js +2 -1
  64. package/dist/holmes/mcp/handlers/entity-store.js +7 -2
  65. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +2 -0
  66. package/dist/holmes/mcp/handlers/operator-inspection.js +25 -4
  67. package/dist/holmes/mcp/handlers/spec-approval.d.ts +3 -1
  68. package/dist/holmes/mcp/handlers/spec-approval.js +28 -10
  69. package/dist/holmes/mcp/handlers/spec-lifecycle.js +10 -7
  70. package/dist/holmes/mcp/handlers/test-execution.d.ts +6 -0
  71. package/dist/holmes/mcp/handlers/test-execution.js +37 -9
  72. package/dist/holmes/mcp/handlers.d.ts +5 -5
  73. package/dist/holmes/mcp/handlers.js +2 -1
  74. package/dist/holmes/mcp/tool-schemas.js +4 -4
  75. package/dist/holmes/project/playbook-reference.d.ts +50 -0
  76. package/dist/holmes/project/playbook-reference.js +259 -0
  77. package/dist/holmes/project/playbook-skill-states.d.ts +94 -0
  78. package/dist/holmes/project/playbook-skill-states.js +396 -0
  79. package/dist/holmes/project/root.d.ts +9 -1
  80. package/dist/holmes/project/root.js +23 -2
  81. package/dist/holmes/project/running-package.d.ts +15 -0
  82. package/dist/holmes/project/running-package.js +87 -0
  83. package/dist/holmes/review/head-worktree.js +9 -1
  84. package/dist/holmes/review/test-runner.d.ts +2 -0
  85. package/dist/holmes/review/test-runner.js +38 -11
  86. package/dist/holmes/spec/entity-integration-transaction.d.ts +19 -2
  87. package/dist/holmes/spec/entity-integration-transaction.js +68 -7
  88. package/package.json +5 -2
@@ -75,7 +75,7 @@ exports.wiringHandshakeChecks = wiringHandshakeChecks;
75
75
  exports.semanticCoverageCheck = semanticCoverageCheck;
76
76
  exports.semanticTierVerdict = semanticTierVerdict;
77
77
  exports.detectTreeKeyTemporary = detectTreeKeyTemporary;
78
- // @implements A-SPEC-794.59, A-SPEC-794.55, A-SPEC-792.46, A-SPEC-792.48, A-SPEC-245.8, A-SPEC-251.5, A-SPEC-476.1, A-SPEC-476.5, A-SPEC-751.4, A-SPEC-751.9, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-774.22, A-SPEC-781.2, A-SPEC-182.3, A-SPEC-182.4,A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-102.28, A-SPEC-102.29
78
+ // @implements A-SPEC-794.113, A-SPEC-794.110, A-SPEC-794.59, A-SPEC-794.55, A-SPEC-792.46, A-SPEC-792.48, A-SPEC-245.8, A-SPEC-251.5, A-SPEC-476.1, A-SPEC-476.5, A-SPEC-751.4, A-SPEC-751.9, A-SPEC-770.3, A-SPEC-770.6, A-SPEC-770.7, A-SPEC-770.9, A-SPEC-770.10,A-SPEC-733,A-SPEC-727, A-SPEC-774.22, A-SPEC-781.2, A-SPEC-182.3, A-SPEC-182.4,A-SPEC-721, A-SPEC-738, A-SPEC-734, A-SPEC-751, A-SPEC-751.2, A-SPEC-772.1, A-SPEC-772.5, A-SPEC-772.6, A-SPEC-772.7, A-SPEC-772.8, A-SPEC-772.9, A-SPEC-772.10, A-SPEC-772.11, A-SPEC-102.28, A-SPEC-102.29
79
79
  // @implements A-SPEC-704, A-SPEC-710, A-SPEC-712, A-SPEC-769.14, A-SPEC-769.16, A-SPEC-769.17, A-SPEC-769.18, A-SPEC-769.19, A-SPEC-769.20, A-SPEC-769.21
80
80
  const doctor_guidance_1 = require("./doctor-guidance");
81
81
  // @implements A-SPEC-264, A-SPEC-423, A-SPEC-549.1, A-SPEC-590
@@ -718,6 +718,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
718
718
  const add = (name, level, detail, fix) => checks.push({ name, level, detail, fix });
719
719
  const runtimeRegistry = opts?.runtimeRegistryPath ?? (0, runtime_binding_1.defaultRuntimeRegistry)();
720
720
  let routed;
721
+ // A-SPEC-794.113 (review A, M2) — the package the sessions' gate loads, when it is not the one doctor runs from
722
+ let gatePackage = null;
721
723
  if (fs.existsSync(runtimeRegistry)) {
722
724
  try {
723
725
  // @implements A-SPEC-769.8 — the Codex home the duplicate-route check reads is the one doctor was pointed at.
@@ -744,6 +746,8 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
744
746
  const routedReal = real(s.packageRoot);
745
747
  const ownReal = real(packageRoot);
746
748
  let own = '';
749
+ if (routedReal !== null && ownReal !== null && routedReal !== ownReal)
750
+ gatePackage = routedReal;
747
751
  if (routedReal === null || ownReal === null || routedReal !== ownReal) {
748
752
  let ownBuild = 'unknown';
749
753
  try {
@@ -1050,7 +1054,14 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1050
1054
  // the all-current PASS too (the count check never counted them either), but the wording keeps
1051
1055
  // ownership distinct and never promises that init will fix what init deliberately skips.
1052
1056
  const skillsDir = path.join(target, '.claude', 'skills');
1053
- const states = (0, playbook_skills_1.playbookSkillStates)(packageRoot, target);
1057
+ // @implements A-SPEC-794.110 — the reference the gate's product-installed judgement reads, from the one function it
1058
+ // calls (doctor read the working tree's playbooks while the gate read the recorded build: "7 current … PASS" here,
1059
+ // seven skills named there — re-check of d77e59d9, A-M1 and B-M2)
1060
+ const judgedSkills = (0, playbook_skills_1.judgedSkillStates)(packageRoot, target);
1061
+ const states = judgedSkills.states;
1062
+ const skillReference = judgedSkills.reference;
1063
+ // the drifted skills whose playbook is not the one the recorded build held: a refresh alone cannot make them current
1064
+ const movedSkills = judgedSkills.moved.filter((n) => states.some((x) => x.name === n && x.state === 'drifted'));
1054
1065
  const of = (s) => states.filter((x) => x.state === s).map((x) => (0, playbook_skills_1.invocableSkillName)(x.name));
1055
1066
  // Orphan rows already carry the RAW directory name (round-6: re-prefixing a case-variant
1056
1067
  // produced the CURRENT skill's name in a delete instruction).
@@ -1074,7 +1085,15 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1074
1085
  'This holmes-kit package ships no playbooks — reinstall or upgrade holmes-kit itself.');
1075
1086
  }
1076
1087
  else if (current === states.length) {
1077
- add('recovery skills', 'PASS', `${states.length} recovery skill(s) current under ${skillsDir}`);
1088
+ // review B (low 6) — against what: the package doctor runs from (the ledger and closed cases have their own row)
1089
+ const against = skillReference.kind !== 'package' ? ''
1090
+ : ` — judged against the playbooks of holmes-kit ${(() => { try {
1091
+ return String(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version ?? 'unknown');
1092
+ }
1093
+ catch {
1094
+ return 'unknown';
1095
+ } })()} at ${packageRoot}`;
1096
+ add('recovery skills', 'PASS', `${states.length} recovery skill(s) current under ${skillsDir}${against}`);
1078
1097
  }
1079
1098
  else {
1080
1099
  const KNOWN_STATES = new Set(['current', 'drifted', 'missing', 'foreign', 'orphaned', 'source-unreadable', 'aliased']);
@@ -1093,11 +1112,21 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1093
1112
  // The remedy must actually WORK: `init --target` on a wired target exits 2 (self-disarm
1094
1113
  // guard) and --force demands governance approval — a refusal loop for three advisory files
1095
1114
  // (round-1 HIGH). `skills refresh` touches only marker-owned skills, never wiring.
1115
+ // A-SPEC-794.110 — with no reference a refresh cannot make a skill current, and a playbook that left the recorded
1116
+ // build needs the build that records it: the remedy named is the one that works for the state found
1117
+ const refreshable = drifted.length - movedSkills.length + missing.length;
1118
+ // review B (confirming, L2) — a path with a space is quoted where a command is shown
1119
+ const sq = (p) => (/[\s"'$`\\]/.test(p) ? `'${p.replace(/'/g, '\'\\\'\'')}'` : p);
1096
1120
  const fixes = [
1097
- drifted.length + missing.length > 0
1098
- ? `Run \`holmes-kit skills refresh --target ${target}\` to refresh the skills holmes-kit owns.` : '',
1121
+ // review B (low 1) — the reason is said once, on the reference row
1122
+ skillReference.kind === 'closed'
1123
+ ? 'No recorded build to judge against — the `recovery skills reference` row says why and what makes one.' : '',
1124
+ skillReference.kind !== 'closed' && movedSkills.length > 0
1125
+ ? `${movedSkills.map((n) => path.join(packageRoot, 'playbooks', n, 'PLAYBOOK.md')).join(', ')} ${movedSkills.length === 1 ? 'is' : 'are'} not what the gate last recorded there, and the recorded one is the reference (the recorded digest is an earlier build's: at the last build no person's window naming ${movedSkills.length === 1 ? 'it' : 'them'} was open): if the change is wanted, a person seals an A-SPEC naming ${movedSkills.length === 1 ? 'it' : 'them'} in a session in that checkout — \`spec_approve\` again on the A-SPEC that names ${movedSkills.length === 1 ? 'it' : 'them'} (the form says it is a re-seal), or a new one; in Holmes-Kit's own repository the spec names the SKILL.md under .claude/skills too — a build run in a governed agent session inside that window records it (a build run outside such a session records nothing), then \`holmes-kit skills refresh --target ${sq(target)}\` and the refreshed SKILL.md is committed; if it is not wanted, restore the playbook.` : '',
1126
+ skillReference.kind !== 'closed' && refreshable > 0
1127
+ ? `Run \`holmes-kit skills refresh --target ${sq(target)}\` to refresh the skills holmes-kit owns.` : '',
1099
1128
  foreign.length > 0 && drifted.length + missing.length === 0
1100
- ? `A file holmes-kit cannot prove it owns occupies it (no readable marker); holmes-kit leaves it untouched — if it is not yours, restore permissions or remove it and re-run \`holmes-kit skills refresh --target ${target}\`.` : '',
1129
+ ? `A file holmes-kit cannot prove it owns occupies it (no readable marker); holmes-kit leaves it untouched — if it is not yours, restore permissions or remove it and re-run \`holmes-kit skills refresh --target ${sq(target)}\`.` : '',
1101
1130
  orphaned.length > 0
1102
1131
  ? 'holmes-kit no longer ships it; delete the directory if you no longer want it.' : '',
1103
1132
  sourceUnreadable.length > 0
@@ -1109,6 +1138,29 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
1109
1138
  ].filter(Boolean).join(' ');
1110
1139
  add('recovery skills', 'WARN', `${current} of ${states.length} recovery skill(s) current under ${skillsDir} — ${parts}`, fixes);
1111
1140
  }
1141
+ // A-SPEC-794.110 — what the skills were judged against, when it is not simply this package's own files
1142
+ // A-SPEC-794.113 (review A, M2; review B, low 6) — and when it is, which package: doctor judges with the package
1143
+ // it runs from, the gate with the package the sessions load, and the two can be different installs
1144
+ const quoted = (p) => (/[\s"'$`\\]/.test(p) ? `'${p.replace(/'/g, '\'\\\'\'')}'` : p);
1145
+ const elsewhere = gatePackage === null ? ''
1146
+ : `. This project's sessions load the gate from ${gatePackage}: the gate judges against that install's reference, which this doctor did not read — run \`node ${quoted(path.join(gatePackage, 'bin', 'holmes-kit.js'))} doctor --target ${quoted(target)}\` for its answer`;
1147
+ if (skillReference.kind === 'ledger') {
1148
+ // review B (confirming, L6 and M1) — the row is the place the digests are read from, not the build that made each
1149
+ // of them (a digest no window moved is carried from an earlier build); and which chain was read
1150
+ add('recovery skills reference', gatePackage === null ? 'PASS' : 'WARN', `judged against the playbook digests in the build the gate recorded at ${skillReference.recordedAt} (${skillReference.commit.slice(0, 12)}, chain ${skillReference.replica}) in ${packageRoot}, not against the working tree's playbooks — a digest there is the one a person's window last recorded, carried from an earlier build when none moved it; it is the reference the gate's product-installed judgement reads when it runs from this install${elsewhere}`);
1151
+ }
1152
+ else if (skillReference.kind === 'closed') {
1153
+ add('recovery skills reference', 'WARN', `no recorded build to judge against, so no skill is shown current (the gate's product-installed judgement reads the same when it runs from this install): ${skillReference.reason}${elsewhere}`);
1154
+ }
1155
+ else if (gatePackage !== null) {
1156
+ const version = (() => { try {
1157
+ return String(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version ?? 'unknown');
1158
+ }
1159
+ catch {
1160
+ return 'unknown';
1161
+ } })();
1162
+ add('recovery skills reference', 'WARN', `judged against the playbooks of holmes-kit ${version} at ${packageRoot}${elsewhere}`);
1163
+ }
1112
1164
  }
1113
1165
  else {
1114
1166
  // @implements A-SPEC-190 (round 7) — without --target this check simply did not appear, so the