@holmes-lab/holmes-kit 0.38.0 → 0.40.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 (308) hide show
  1. package/CHANGELOG.md +370 -6
  2. package/README.md +58 -40
  3. package/dist/.build-id +1 -1
  4. package/dist/holmes/admission/core/admission-policy.d.ts +37 -0
  5. package/dist/holmes/admission/core/admission-policy.js +147 -0
  6. package/dist/holmes/admission/core/bounded-reader.d.ts +56 -0
  7. package/dist/holmes/admission/core/bounded-reader.js +135 -0
  8. package/dist/holmes/admission/core/change-classifier.d.ts +34 -0
  9. package/dist/holmes/admission/core/change-classifier.js +278 -0
  10. package/dist/holmes/admission/core/config-loader.d.ts +30 -0
  11. package/dist/holmes/admission/core/config-loader.js +145 -0
  12. package/dist/holmes/admission/core/event-judgement.d.ts +37 -0
  13. package/dist/holmes/admission/core/event-judgement.js +251 -0
  14. package/dist/holmes/admission/core/path-rules.d.ts +35 -0
  15. package/dist/holmes/admission/core/path-rules.js +88 -0
  16. package/dist/holmes/admission/core/pin.d.ts +7 -0
  17. package/dist/holmes/admission/core/pin.js +29 -0
  18. package/dist/holmes/admission/core/ports.d.ts +48 -0
  19. package/dist/holmes/admission/core/ports.js +11 -0
  20. package/dist/holmes/admission/core/range-resolver.d.ts +32 -0
  21. package/dist/holmes/admission/core/range-resolver.js +51 -0
  22. package/dist/holmes/admission/core/self-containment.d.ts +1 -0
  23. package/dist/holmes/admission/core/self-containment.js +125 -0
  24. package/dist/holmes/admission/core/signature-source.d.ts +9 -0
  25. package/dist/holmes/admission/core/signature-source.js +4 -0
  26. package/dist/holmes/admission/core/transition-planner.d.ts +15 -0
  27. package/dist/holmes/admission/core/transition-planner.js +14 -0
  28. package/dist/holmes/admission/core/verdict.d.ts +38 -0
  29. package/dist/holmes/admission/core/verdict.js +17 -0
  30. package/dist/holmes/admission/core/wiring.d.ts +44 -0
  31. package/dist/holmes/admission/core/wiring.js +618 -0
  32. package/dist/holmes/admission/forge/git-object-port.d.ts +4 -0
  33. package/dist/holmes/admission/forge/git-object-port.js +132 -0
  34. package/dist/holmes/assoc/assoc-arm.d.ts +1 -1
  35. package/dist/holmes/assoc/assoc-arm.js +1 -1
  36. package/dist/holmes/cli/agents.d.ts +8 -0
  37. package/dist/holmes/cli/agents.js +9 -5
  38. package/dist/holmes/cli/approve-cli.d.ts +2 -0
  39. package/dist/holmes/cli/approve-cli.js +392 -0
  40. package/dist/holmes/cli/approve-ref.d.ts +13 -7
  41. package/dist/holmes/cli/approve-ref.js +30 -10
  42. package/dist/holmes/cli/approve-status.d.ts +26 -2
  43. package/dist/holmes/cli/approve-status.js +98 -18
  44. package/dist/holmes/cli/approve-watch.d.ts +5 -0
  45. package/dist/holmes/cli/approve-watch.js +10 -5
  46. package/dist/holmes/cli/approve.d.ts +50 -13
  47. package/dist/holmes/cli/approve.js +260 -67
  48. package/dist/holmes/cli/attest.js +2 -1
  49. package/dist/holmes/cli/autonomy.d.ts +4 -1
  50. package/dist/holmes/cli/autonomy.js +17 -10
  51. package/dist/holmes/cli/codex-oracle.d.ts +11 -0
  52. package/dist/holmes/cli/codex-oracle.js +5 -1
  53. package/dist/holmes/cli/codex-toml.d.ts +10 -0
  54. package/dist/holmes/cli/codex-toml.js +36 -2
  55. package/dist/holmes/cli/doctor-boundary.d.ts +76 -0
  56. package/dist/holmes/cli/doctor-boundary.js +308 -0
  57. package/dist/holmes/cli/doctor-locks.d.ts +15 -0
  58. package/dist/holmes/cli/doctor-locks.js +119 -0
  59. package/dist/holmes/cli/doctor.d.ts +2 -0
  60. package/dist/holmes/cli/doctor.js +45 -5
  61. package/dist/holmes/cli/flags.d.ts +23 -0
  62. package/dist/holmes/cli/flags.js +89 -0
  63. package/dist/holmes/cli/index.d.ts +5 -1
  64. package/dist/holmes/cli/index.js +206 -424
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  67. package/dist/holmes/cli/lock-recover.js +126 -0
  68. package/dist/holmes/cli/mcp-processes.d.ts +32 -0
  69. package/dist/holmes/cli/mcp-processes.js +132 -0
  70. package/dist/holmes/cli/release-docs.js +1 -1
  71. package/dist/holmes/cli/run-exec.d.ts +141 -0
  72. package/dist/holmes/cli/run-exec.js +1435 -0
  73. package/dist/holmes/cli/run-provision.d.ts +8 -0
  74. package/dist/holmes/cli/run-provision.js +325 -0
  75. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  76. package/dist/holmes/cli/run-wiring.js +270 -0
  77. package/dist/holmes/cli/run.d.ts +26 -0
  78. package/dist/holmes/cli/run.js +364 -83
  79. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  80. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  81. package/dist/holmes/cli/screen-safe.js +18 -756
  82. package/dist/holmes/config/config.d.ts +2 -0
  83. package/dist/holmes/config/config.js +5 -2
  84. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  85. package/dist/holmes/cpg/import-resolver.js +1 -1
  86. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  87. package/dist/holmes/governance/approval-decisions.js +29 -0
  88. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  89. package/dist/holmes/governance/approval-grants.js +612 -33
  90. package/dist/holmes/governance/approval-queue.d.ts +31 -0
  91. package/dist/holmes/governance/approval-queue.js +122 -11
  92. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  93. package/dist/holmes/governance/approval-spend.js +191 -0
  94. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  95. package/dist/holmes/governance/autonomous-shell.js +332 -0
  96. package/dist/holmes/governance/autonomy.d.ts +5 -0
  97. package/dist/holmes/governance/autonomy.js +16 -11
  98. package/dist/holmes/governance/constitution.d.ts +5 -0
  99. package/dist/holmes/governance/constitution.js +32 -12
  100. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  101. package/dist/holmes/governance/full-autonomy.js +103 -7
  102. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  103. package/dist/holmes/governance/harness-catalog.js +348 -0
  104. package/dist/holmes/governance/human-channel.d.ts +38 -0
  105. package/dist/holmes/governance/human-channel.js +49 -0
  106. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  107. package/dist/holmes/governance/install-manifest.js +160 -0
  108. package/dist/holmes/governance/ledger-rechain.js +2 -0
  109. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  110. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  111. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  112. package/dist/holmes/governance/ledger-store.js +186 -8
  113. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  114. package/dist/holmes/governance/provenance-chain.js +19 -4
  115. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  116. package/dist/holmes/governance/provenance-ledger.js +53 -18
  117. package/dist/holmes/governance/push-gate-runner.js +11 -7
  118. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  119. package/dist/holmes/governance/recorded-pairs.js +522 -0
  120. package/dist/holmes/governance/replica-id.d.ts +1 -1
  121. package/dist/holmes/governance/replica-id.js +1 -1
  122. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  123. package/dist/holmes/governance/spec-seam.js +587 -0
  124. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  125. package/dist/holmes/governance/spend-kinds.js +18 -0
  126. package/dist/holmes/governance/tool-actions.js +2 -0
  127. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  128. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  129. package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
  130. package/dist/holmes/guardrail/impact-gate.js +1 -1
  131. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  132. package/dist/holmes/guardrail/line-continuation.js +39 -0
  133. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  134. package/dist/holmes/guardrail/operator-person.js +57 -11
  135. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  136. package/dist/holmes/guardrail/refusal-codes.js +70 -10
  137. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  138. package/dist/holmes/guardrail/risk-classifier.js +245 -15
  139. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  140. package/dist/holmes/guardrail/risk-gate.js +7 -34
  141. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  142. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  143. package/dist/holmes/guardrail/run-refusals.d.ts +6 -1
  144. package/dist/holmes/guardrail/run-refusals.js +36 -14
  145. package/dist/holmes/guardrail/run-stages.d.ts +10 -0
  146. package/dist/holmes/guardrail/run-stages.js +46 -6
  147. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  148. package/dist/holmes/guardrail/shell-words.js +24 -3
  149. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  150. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  151. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  152. package/dist/holmes/guardrail/write-target.js +26 -5
  153. package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
  154. package/dist/holmes/hooks/pre-tool-use.js +1167 -168
  155. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  156. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  157. package/dist/holmes/hooks/session-start.d.ts +5 -0
  158. package/dist/holmes/hooks/session-start.js +29 -1
  159. package/dist/holmes/hooks/stop.d.ts +23 -0
  160. package/dist/holmes/hooks/stop.js +88 -33
  161. package/dist/holmes/mcp/approval-adapters.js +3 -1
  162. package/dist/holmes/mcp/approval-commit.js +3 -2
  163. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  164. package/dist/holmes/mcp/approval-policy.js +3 -1
  165. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  166. package/dist/holmes/mcp/handlers/approval-ask.d.ts +14 -0
  167. package/dist/holmes/mcp/handlers/approval-ask.js +31 -6
  168. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  169. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  170. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  171. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  172. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  173. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  174. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  175. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  176. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  177. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  178. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  179. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  180. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  181. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  182. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  183. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  184. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  185. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  186. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  187. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  188. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  189. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  190. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  191. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  192. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  193. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  194. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  195. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  196. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  197. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  198. package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
  199. package/dist/holmes/mcp/handlers/workspace-preflight.d.ts +5 -0
  200. package/dist/holmes/mcp/handlers/workspace-preflight.js +10 -2
  201. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  202. package/dist/holmes/mcp/handlers.d.ts +99 -79
  203. package/dist/holmes/mcp/handlers.js +93 -25
  204. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  205. package/dist/holmes/mcp/harness-attestation.js +325 -53
  206. package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
  207. package/dist/holmes/mcp/maintenance-analyze.js +9 -9
  208. package/dist/holmes/mcp/maintenance-evidence.js +31 -2
  209. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  210. package/dist/holmes/mcp/server-staleness.d.ts +43 -0
  211. package/dist/holmes/mcp/server-staleness.js +158 -0
  212. package/dist/holmes/mcp/server.js +34 -9
  213. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  214. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  215. package/dist/holmes/mcp/tool-schemas.js +42 -2
  216. package/dist/holmes/project/act-root.d.ts +19 -0
  217. package/dist/holmes/project/act-root.js +100 -0
  218. package/dist/holmes/project/baseline.js +4 -3
  219. package/dist/holmes/project/bounded-group.d.ts +47 -0
  220. package/dist/holmes/project/bounded-group.js +140 -0
  221. package/dist/holmes/project/bounded-io.d.ts +50 -2
  222. package/dist/holmes/project/bounded-io.js +138 -6
  223. package/dist/holmes/project/change-source.js +2 -2
  224. package/dist/holmes/project/instance-id.d.ts +10 -0
  225. package/dist/holmes/project/instance-id.js +233 -0
  226. package/dist/holmes/project/machine-identity.d.ts +25 -0
  227. package/dist/holmes/project/machine-identity.js +133 -0
  228. package/dist/holmes/project/owned-lock.d.ts +84 -0
  229. package/dist/holmes/project/owned-lock.js +263 -0
  230. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  231. package/dist/holmes/project/plain-lock-fs.js +126 -0
  232. package/dist/holmes/project/request-lock.d.ts +85 -0
  233. package/dist/holmes/project/request-lock.js +459 -0
  234. package/dist/holmes/project/root.d.ts +12 -4
  235. package/dist/holmes/project/root.js +26 -7
  236. package/dist/holmes/project/run-records.d.ts +19 -0
  237. package/dist/holmes/project/run-records.js +94 -12
  238. package/dist/holmes/project/screen-text.d.ts +94 -0
  239. package/dist/holmes/project/screen-text.js +763 -0
  240. package/dist/holmes/project/spend-lock.d.ts +82 -0
  241. package/dist/holmes/project/spend-lock.js +413 -0
  242. package/dist/holmes/project/workspace-preflight.d.ts +5 -0
  243. package/dist/holmes/project/workspace-preflight.js +24 -1
  244. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  245. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  246. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  247. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  248. package/dist/holmes/review/confidence-calibration.js +1 -1
  249. package/dist/holmes/review/content-verify.js +1 -1
  250. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  251. package/dist/holmes/review/hop-ablation.js +5 -5
  252. package/dist/holmes/review/point-in-time-replay.js +12 -3
  253. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  254. package/dist/holmes/review/rank-diagnosis.js +1 -1
  255. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  256. package/dist/holmes/review/replay-corpus.js +25 -9
  257. package/dist/holmes/review/requirement-triage.js +2 -2
  258. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  259. package/dist/holmes/review/semantic-arm.js +3 -3
  260. package/dist/holmes/review/test-outcomes.js +3 -1
  261. package/dist/holmes/review/test-runner.d.ts +11 -0
  262. package/dist/holmes/review/test-runner.js +31 -10
  263. package/dist/holmes/review/test-selection-breadth.js +2 -2
  264. package/dist/holmes/review/verdicts.d.ts +109 -7
  265. package/dist/holmes/review/verdicts.js +653 -34
  266. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  267. package/dist/holmes/rtm/anchor-census.js +151 -0
  268. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  269. package/dist/holmes/rtm/anchor-ids.js +45 -2
  270. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  271. package/dist/holmes/rtm/comment-ranges.js +104 -0
  272. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  273. package/dist/holmes/rtm/counted-tests.js +63 -0
  274. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  275. package/dist/holmes/rtm/known-defects.js +1 -1
  276. package/dist/holmes/rtm/localize.js +1 -1
  277. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  278. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  279. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  280. package/dist/holmes/rtm/test-scope.js +166 -5
  281. package/dist/holmes/rtm/trace-gaps.js +1 -1
  282. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  283. package/dist/holmes/runtime/dispatch.js +12 -1
  284. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  285. package/dist/holmes/semantic/cloud-usage.js +1 -1
  286. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  287. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  288. package/dist/holmes/spec/approval-blockers.js +1 -1
  289. package/dist/holmes/spec/entity-store.d.ts +6 -1
  290. package/dist/holmes/spec/entity-store.js +16 -2
  291. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  292. package/dist/holmes/spec/entity-transaction.js +87 -170
  293. package/dist/holmes/spec/spec-store.d.ts +12 -6
  294. package/dist/holmes/spec/spec-store.js +4 -2
  295. package/dist/holmes/spec/spec-types.js +1 -1
  296. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  297. package/dist/holmes/spec/succession-guard.js +187 -0
  298. package/dist/holmes/spec/succession.d.ts +70 -0
  299. package/dist/holmes/spec/succession.js +171 -0
  300. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  301. package/docs/install-guide.md +9 -3
  302. package/docs/language-support.md +78 -0
  303. package/package.json +4 -3
  304. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  305. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  306. package/playbooks/publish/PLAYBOOK.md +45 -33
  307. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  308. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -42,7 +42,7 @@ exports.everSealedInLedger = everSealedInLedger;
42
42
  exports.validateTriageArtifact = validateTriageArtifact;
43
43
  exports.intakeHead = intakeHead;
44
44
  exports.validateRequirementIntake = validateRequirementIntake;
45
- // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734, A-SPEC-719.6
45
+ // @implements A-SPEC-730, A-SPEC-729, A-SPEC-724, A-SPEC-719, A-SPEC-734, A-SPEC-719.6, A-SPEC-245.9, A-SPEC-222.10, A-SPEC-794.4
46
46
  // @implements A-SPEC-713
47
47
  /** Content-addressed, isolated persistence for advisory requirement triage results. */
48
48
  const crypto = __importStar(require("node:crypto"));
@@ -50,7 +50,9 @@ const fs = __importStar(require("node:fs"));
50
50
  const path = __importStar(require("node:path"));
51
51
  const freshness_coordinator_1 = require("../refresh/freshness-coordinator");
52
52
  const ledger_store_1 = require("../governance/ledger-store");
53
+ const recorded_pairs_1 = require("../governance/recorded-pairs");
53
54
  const provenance_chain_1 = require("../governance/provenance-chain");
55
+ const spend_kinds_1 = require("../governance/spend-kinds");
54
56
  const ledger_lock_1 = require("../governance/ledger-lock");
55
57
  const display_id_aliases_1 = require("../governance/display-id-aliases");
56
58
  const bounded_io_1 = require("../project/bounded-io");
@@ -124,17 +126,19 @@ function issueRequirementTriageEvidence(root, artifact) {
124
126
  * unobtainable lock is a refusal, never a silent pass.
125
127
  */
126
128
  function consumeRequirementTriageEvidence(root, digest, reqId) {
127
- const ledgerFile = (0, ledger_store_1.writerChainFile)(ledgerDirOf(root));
128
129
  const key = spendKeyOf(digest);
129
130
  try {
130
- const won = (0, provenance_chain_1.consumeNonceExclusively)(key, ledgerFile, {
131
- ts: new Date().toISOString(), actor: 'holmes-kit', kind: 'nonce-consumed',
132
- summary: `requirement triage evidence spent on ${reqId}`, inputs: [(0, provenance_chain_1.nonceFingerprint)(key)],
133
- }, { isNonceConsumed: (0, ledger_store_1.nonceConsumedIn)(ledgerFile) });
134
- return won ? { ok: true } : { ok: false, reason: SPENT };
131
+ // @implements A-SPEC-245.9 (1b-1) — spent under the workspace spend lock, across every replica chain
132
+ const { spendApprovals } = require('../governance/approval-spend');
133
+ const r = spendApprovals(root, [{ nonce: key, actor: 'holmes-kit', summary: `requirement triage evidence spent on ${reqId}`, rationale: reqId }], {});
134
+ if (r.ok)
135
+ return { ok: true };
136
+ return { ok: false, reason: r.reason === 'spent' ? SPENT
137
+ : r.reason === 'revoked' ? '새 REQ triage evidence was revoked — it admits nothing; re-run requirement_triage.' // A-SPEC-245.16
138
+ : `새 REQ triage evidence could not be confirmed as spent once (${r.reason}: a spend-conflict-detected row names it) — re-run requirement_triage.` };
135
139
  }
136
140
  catch (e) {
137
- const busy = e instanceof ledger_lock_1.LedgerLockError;
141
+ const busy = e instanceof ledger_lock_1.LedgerLockError || e?.code === 'lock-busy';
138
142
  return { ok: false, reason: busy
139
143
  ? `새 REQ triage evidence could not be spent (ledger busy: ${e.message}) — 다시 시도하십시오.`
140
144
  : `새 REQ triage evidence could not be spent (${e instanceof Error ? e.message : String(e)}) — the ledger could not record it; check it with holmes-kit doctor.` };
@@ -149,10 +153,10 @@ function hasRequirementIntakeRecord(root, reqId, digest) {
149
153
  if (typeof digest !== 'string' || !DIGEST.test(digest))
150
154
  return false;
151
155
  try {
152
- const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
156
+ const store = new recorded_pairs_1.TrustedLedgerStore(ledgerDirOf(root)); // A-SPEC-222.10 H-C: a proof, from trusted events
153
157
  const broken = new Set(store.verifyAll().broken.map((b) => b.replicaId));
154
158
  const fp = (0, provenance_chain_1.nonceFingerprint)(spendKeyOf(digest));
155
- return store.loadAll().some((e) => e.kind === 'nonce-consumed' && !broken.has(e.replicaId)
159
+ return store.loadAll().some((e) => e.kind === (0, spend_kinds_1.spendKind)('grant') && !broken.has(e.replicaId)
156
160
  && (e.inputs ?? []).includes(fp) && e.summary === `requirement triage evidence spent on ${reqId}`);
157
161
  }
158
162
  catch {
@@ -165,7 +169,7 @@ function hasRequirementIntakeRecord(root, reqId, digest) {
165
169
  */
166
170
  function everSealedInLedger(root, specId) {
167
171
  try {
168
- const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
172
+ const store = new recorded_pairs_1.TrustedLedgerStore(ledgerDirOf(root)); // A-SPEC-222.10 H-C: a proof, from trusted events
169
173
  const broken = new Set(store.verifyAll().broken.map((b) => b.replicaId));
170
174
  // @implements A-SPEC-729 (round 7) — the mark follows RECORDED renames, in ledger order: a sealed
171
175
  // REQ renumbered away freed its id, and an untriaged REQ renumbered onto it read as "sealed
@@ -279,12 +283,17 @@ function validateRequirementIntake(root, triageEvidence) {
279
283
  // must not have been spent on another REQ yet (the spend itself happens at the write).
280
284
  // Only a chain that VERIFIES counts (round 1: a planted `provenance.<x>.jsonl` minted issuance). With
281
285
  // HOLMES_LEDGER_KEY set, verification checks signatures, so a forged chain cannot pass.
286
+ // A-SPEC-222.10 H-C: issuance is a proof, so it is accepted only from trusted events; the raw rows only say where an
287
+ // untrusted record sits, so the refusal can name the repair (round 2 below)
282
288
  const store = new ledger_store_1.FileLedgerStore(ledgerDirOf(root));
283
289
  let issuedOn = [];
290
+ let trustedOn = new Set();
284
291
  let broken = new Map();
285
292
  let own = null;
286
293
  try {
287
- issuedOn = store.loadAll().filter((e) => e.kind === 'triage-issued' && (e.inputs ?? []).includes(evidence.digest)).map((e) => e.replicaId);
294
+ const issued = (e) => e.kind === 'triage-issued' && (e.inputs ?? []).includes(evidence.digest);
295
+ issuedOn = store.loadAll().filter(issued).map((e) => e.replicaId);
296
+ trustedOn = new Set(new recorded_pairs_1.TrustedLedgerStore(ledgerDirOf(root)).loadAll().filter(issued).map((e) => e.replicaId));
288
297
  broken = new Map(store.verifyAll().broken.map((b) => [b.replicaId, b.detail]));
289
298
  }
290
299
  catch (e) {
@@ -299,7 +308,7 @@ function validateRequirementIntake(root, triageEvidence) {
299
308
  catch {
300
309
  own = null;
301
310
  }
302
- const verified = issuedOn.filter((r) => !broken.has(r));
311
+ const verified = issuedOn.filter((r) => !broken.has(r) && trustedOn.has(r));
303
312
  if (verified.length === 0) {
304
313
  // Round 2: when the broken chain is this writer's OWN, re-triage would land on the same chain —
305
314
  // the only recovery is repairing the ledger, so the refusal says that instead.
@@ -0,0 +1,43 @@
1
+ export interface InstallIdentity {
2
+ version: string;
3
+ buildId: string;
4
+ }
5
+ export interface StaleFact {
6
+ loaded: InstallIdentity;
7
+ onDisk: InstallIdentity;
8
+ pid: number;
9
+ startedAt: string;
10
+ fix: string;
11
+ }
12
+ export interface StaleNotice {
13
+ loaded: string;
14
+ onDisk: string;
15
+ fix: string;
16
+ }
17
+ export interface McpBeat {
18
+ schema: 'holmes-mcp-heartbeat/1';
19
+ client: string;
20
+ pid: number;
21
+ version: string;
22
+ buildId: string;
23
+ packageRoot: string;
24
+ startedAt: string;
25
+ at: string;
26
+ }
27
+ export declare const MCP_HEARTBEAT_DIR: string;
28
+ /** The package root's version and build id, or null when the version cannot be read (absence is not staleness). */
29
+ export declare function readInstallIdentity(pkgRoot: string): InstallIdentity | null;
30
+ /** At most one disk read per `everyMs` (default 30 s); the last answer is kept between reads. */
31
+ export declare function makeStalenessProbe(pkgRoot: string, loaded: InstallIdentity, opts?: {
32
+ now?: () => number;
33
+ everyMs?: number;
34
+ pid?: number;
35
+ startedAt?: string;
36
+ }): () => StaleFact | null;
37
+ export declare function staleNotice(f: StaleFact): StaleNotice;
38
+ /** Best effort: at most one write per client a minute; every failure is swallowed. */
39
+ export declare function writeMcpHeartbeat(projectRoot: string, beat: Omit<McpBeat, 'schema' | 'at'>, now: number): void;
40
+ /** Valid beats under `.ax/state/mcp-heartbeat`, each with whether its process is alive and the beat under 24 h old. */
41
+ export declare function readMcpHeartbeats(projectRoot: string, now: number): Array<McpBeat & {
42
+ alive: boolean;
43
+ }>;
@@ -0,0 +1,158 @@
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.MCP_HEARTBEAT_DIR = void 0;
37
+ exports.readInstallIdentity = readInstallIdentity;
38
+ exports.makeStalenessProbe = makeStalenessProbe;
39
+ exports.staleNotice = staleNotice;
40
+ exports.writeMcpHeartbeat = writeMcpHeartbeat;
41
+ exports.readMcpHeartbeats = readMcpHeartbeats;
42
+ // @implements A-SPEC-251.4
43
+ /**
44
+ * Whether the install a running MCP server was loaded from has changed under it, and the server's heartbeat.
45
+ *
46
+ * Measured 2026-10-23 (D1): a consumer workspace session's holmes-kit MCP served v0.36.0 while the global install its `.mcp.json`
47
+ * names was 0.38.0 — the process had started before the install was upgraded in place — so `approval_ask`,
48
+ * `review_verdict` and `phase_check` were missing and nothing said so. A-SPEC-251.2 compares the WIRING with the CLI
49
+ * (they matched); A-SPEC-156's basis compares the loaded build with the WORKSPACE's dist (a consumer has none).
50
+ *
51
+ * The probe states two facts the process can read and compares them by string inequality only, so a server running
52
+ * old code still computes it correctly (A-SPEC-156's caution about a stale build judging itself). Nothing here
53
+ * restarts, kills or refuses; a heartbeat is information only (A-SPEC-772.5).
54
+ */
55
+ const fs = __importStar(require("node:fs"));
56
+ const path = __importStar(require("node:path"));
57
+ const SCHEMA = 'holmes-mcp-heartbeat/1';
58
+ exports.MCP_HEARTBEAT_DIR = path.join('.ax', 'state', 'mcp-heartbeat');
59
+ const WRITE_EVERY_MS = 60_000;
60
+ const ALIVE_WITHIN_MS = 24 * 3600_000;
61
+ const MAX_RECORD_BYTES = 4096;
62
+ /** The package root's version and build id, or null when the version cannot be read (absence is not staleness). */
63
+ function readInstallIdentity(pkgRoot) {
64
+ try {
65
+ const version = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'package.json'), 'utf8')).version;
66
+ if (typeof version !== 'string' || version === '')
67
+ return null;
68
+ let buildId = 'unknown';
69
+ try {
70
+ buildId = fs.readFileSync(path.join(pkgRoot, 'dist', '.build-id'), 'utf8').trim() || 'unknown';
71
+ }
72
+ catch { /* unstamped */ }
73
+ return { version, buildId: buildId.slice(0, 200) };
74
+ }
75
+ catch {
76
+ return null;
77
+ }
78
+ }
79
+ const label = (i) => `v${i.version} (build ${i.buildId})`;
80
+ /** At most one disk read per `everyMs` (default 30 s); the last answer is kept between reads. */
81
+ function makeStalenessProbe(pkgRoot, loaded, opts = {}) {
82
+ const now = opts.now ?? Date.now;
83
+ const every = opts.everyMs ?? 30_000;
84
+ const pid = opts.pid ?? process.pid;
85
+ const startedAt = opts.startedAt ?? new Date(now()).toISOString();
86
+ let checkedAt = -Infinity;
87
+ let last = null;
88
+ return () => {
89
+ const t = now();
90
+ if (t - checkedAt < every)
91
+ return last;
92
+ checkedAt = t;
93
+ const onDisk = readInstallIdentity(pkgRoot);
94
+ last = onDisk !== null && (onDisk.version !== loaded.version || onDisk.buildId !== loaded.buildId)
95
+ ? { loaded, onDisk, pid, startedAt,
96
+ fix: `this MCP server process (pid ${pid}, started ${startedAt}) loaded v${loaded.version} but its install is now v${onDisk.version}; `
97
+ + `tools added since v${loaded.version} are missing — restart the harness session (or its MCP server) to load v${onDisk.version}` }
98
+ : null;
99
+ return last;
100
+ };
101
+ }
102
+ function staleNotice(f) {
103
+ return { loaded: label(f.loaded), onDisk: label(f.onDisk), fix: f.fix };
104
+ }
105
+ const fileFor = (projectRoot, client) => path.join(projectRoot, exports.MCP_HEARTBEAT_DIR, `${client.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 64) || 'unknown'}.json`);
106
+ /** Best effort: at most one write per client a minute; every failure is swallowed. */
107
+ function writeMcpHeartbeat(projectRoot, beat, now) {
108
+ try {
109
+ const file = fileFor(projectRoot, beat.client);
110
+ try {
111
+ const prev = JSON.parse(fs.readFileSync(file, 'utf8'));
112
+ if (prev.pid === beat.pid && typeof prev.at === 'string' && now - Date.parse(prev.at) < WRITE_EVERY_MS)
113
+ return;
114
+ }
115
+ catch { /* none yet, or unreadable: write */ }
116
+ fs.mkdirSync(path.dirname(file), { recursive: true });
117
+ const tmp = `${file}.${process.pid}.tmp`;
118
+ fs.writeFileSync(tmp, JSON.stringify({ schema: SCHEMA, ...beat, at: new Date(now).toISOString() }) + '\n');
119
+ fs.renameSync(tmp, file);
120
+ }
121
+ catch { /* information only */ }
122
+ }
123
+ const alivePid = (pid) => {
124
+ try {
125
+ process.kill(pid, 0);
126
+ return true;
127
+ }
128
+ catch (e) {
129
+ return e.code === 'EPERM';
130
+ }
131
+ };
132
+ /** Valid beats under `.ax/state/mcp-heartbeat`, each with whether its process is alive and the beat under 24 h old. */
133
+ function readMcpHeartbeats(projectRoot, now) {
134
+ const dir = path.join(projectRoot, exports.MCP_HEARTBEAT_DIR);
135
+ let names = [];
136
+ try {
137
+ names = fs.readdirSync(dir).filter((n) => n.endsWith('.json'));
138
+ }
139
+ catch {
140
+ return [];
141
+ }
142
+ const out = [];
143
+ for (const n of names.slice(0, 32)) {
144
+ try {
145
+ const p = path.join(dir, n);
146
+ if (fs.lstatSync(p).size > MAX_RECORD_BYTES)
147
+ continue;
148
+ const b = JSON.parse(fs.readFileSync(p, 'utf8'));
149
+ if (b.schema !== SCHEMA || typeof b.pid !== 'number' || typeof b.version !== 'string' || typeof b.buildId !== 'string'
150
+ || typeof b.client !== 'string' || typeof b.at !== 'string')
151
+ continue;
152
+ const age = now - Date.parse(b.at);
153
+ out.push({ ...b, alive: Number.isFinite(age) && age >= 0 && age < ALIVE_WITHIN_MS && alivePid(b.pid) });
154
+ }
155
+ catch { /* skip */ }
156
+ }
157
+ return out;
158
+ }
@@ -1,7 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.HOOK_ENFORCED_TOOLS = void 0;
4
- // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1, A-SPEC-732, A-SPEC-734, A-SPEC-751.3
4
+ // @implements A-SPEC-720, A-SPEC-718, A-SPEC-625, A-SPEC-564.1, A-SPEC-732, A-SPEC-734, A-SPEC-751.3, A-SPEC-251.4, A-SPEC-779.7, A-SPEC-732.4
5
5
  const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
6
6
  const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
7
7
  const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
@@ -51,15 +51,15 @@ const elicit = async (req) => {
51
51
  }
52
52
  };
53
53
  // @implements A-SPEC-732 (round 2) — who launched this server, asked once, on first need.
54
- const { attestHarness, systemProcLookup, dispatcherVerifier } = require('./harness-attestation');
55
54
  // @implements A-SPEC-751.3 — the operator runtime registry's dispatcher is a launcher (it sits between the harness and
56
- // this server on a registered machine); the path is the registry's fixed default, never taken from the request.
57
- const runtimeRegistryPath = require('node:path').join(require('node:os').homedir(), '.holmes', 'runtime', 'bindings.json');
55
+ // this server on a registered machine); its path is the registry's fixed default under this home.
56
+ // @implements A-SPEC-732.4 — built in one entry (serverAttestation), which the tests reach with their own home and env
57
+ const { serverAttestation } = require('./harness-attestation');
58
58
  let attested;
59
59
  const harnessAttestation = () => {
60
60
  if (attested === undefined) {
61
61
  try {
62
- attested = attestHarness(process.ppid, systemProcLookup(), 8, dispatcherVerifier(runtimeRegistryPath));
62
+ attested = serverAttestation(process.ppid, { env: process.env, home: require('node:os').homedir() });
63
63
  }
64
64
  catch {
65
65
  attested = { attested: false, chain: [], reason: 'the process table could not be read' };
@@ -67,11 +67,35 @@ const harnessAttestation = () => {
67
67
  }
68
68
  return attested;
69
69
  };
70
+ // @implements A-SPEC-251.4 — whether the install this process loaded changed under it, and the heartbeat that lets the
71
+ // hooks compare builds. Both fail open: a server that cannot read its own package root starts and answers as before.
72
+ const { makeStalenessProbe, readInstallIdentity, writeMcpHeartbeat } = require('./server-staleness');
73
+ const pkgRoot = require('node:path').resolve(__dirname, '..', '..', '..');
74
+ const loadedIdentity = readInstallIdentity(pkgRoot) ?? { version: 'unknown', buildId: 'unknown' };
75
+ const serverStartedAt = new Date().toISOString();
76
+ const serverStaleness = makeStalenessProbe(pkgRoot, loadedIdentity, { startedAt: serverStartedAt });
77
+ // @implements A-SPEC-779.7 — this instance stamps the requests it files, so this session (and only it) withdraws them.
78
+ const serverInstanceId = `${process.pid}:${serverStartedAt}`;
79
+ require('../governance/approval-queue').setRequesterServer(serverInstanceId);
80
+ const beat = (root) => {
81
+ try {
82
+ const client = (() => { try {
83
+ return server.getClientVersion()?.name ?? 'unknown';
84
+ }
85
+ catch {
86
+ return 'unknown';
87
+ } })();
88
+ writeMcpHeartbeat(root, { client, pid: process.pid, version: loadedIdentity.version, buildId: loadedIdentity.buildId, packageRoot: pkgRoot, startedAt: serverStartedAt }, Date.now());
89
+ }
90
+ catch { /* information only */ }
91
+ };
70
92
  const handlers = (0, handlers_1.makeHandlers)(store, {
71
93
  harnessAttestation,
72
94
  elicit,
73
95
  elicitationAvailable: () => (0, approval_adapters_1.supportsFormElicitation)(server.getClientCapabilities()),
74
- observeInvocation: root => stampSession(root),
96
+ observeInvocation: root => { stampSession(root); beat(root); },
97
+ serverStaleness,
98
+ serverInstance: () => serverInstanceId,
75
99
  clientName: () => { try {
76
100
  return server.getClientVersion()?.name ?? 'unknown';
77
101
  }
@@ -147,8 +171,8 @@ const fullProfile = process.env.HOLMES_MCP_PROFILE === 'full';
147
171
  // clients can marshal complex (array/object) arguments; fall back to a
148
172
  // permissive stub only if a handler somehow lacks a schema (tool-schemas.test.ts
149
173
  // pins full 1:1 coverage, so the fallback should never fire in practice).
150
- const TOOLS = Object.keys(handlers)
151
- .filter((name) => fullProfile || !tool_schemas_1.HOOK_ENFORCED_TOOLS.has(name))
174
+ const wire = (0, tool_schemas_1.wireDispatch)(handlers, fullProfile); // @implements A-SPEC-792.25, A-SPEC-792.26
175
+ const TOOLS = wire.names
152
176
  .map((name) => {
153
177
  const def = tool_schemas_1.TOOL_SCHEMAS[name];
154
178
  return def
@@ -167,7 +191,8 @@ server.setRequestHandler(types_js_1.CallToolRequestSchema, async (req) => {
167
191
  // the prototype chain to a truthy non-handler and crash the new validation path (round-2 probe) —
168
192
  // pre-enforcement it silently "succeeded" by invoking Object. Both are wrong; unknown tool is true.
169
193
  const own = (o, k) => Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined;
170
- const fn = own(handlers, req.params.name);
194
+ // @implements A-SPEC-792.25 — the same set ListTools serves: a hidden tool is an unknown tool on the wire
195
+ const fn = wire.handlerFor(req.params.name);
171
196
  const def = own(tool_schemas_1.TOOL_SCHEMAS, req.params.name);
172
197
  const args = req.params.arguments ?? {};
173
198
  const check = fn && def ? (0, validate_args_1.validateArgs)(req.params.name, def.inputSchema, args) : { ok: true };
@@ -27,7 +27,7 @@ const spec_id_2 = require("../spec/spec-id");
27
27
  * - base > maxBase+1(leap) → 거부, 다음 가용 번호를 문면과 필드에 댄다.
28
28
  */
29
29
  /** The id's number SPACE. @implements A-SPEC-571.1 — ADR keeps its own sequence so a decision
30
- * (jarvis's ADR-0001) neither blocks nor is blocked by the functional chain's max. Everything
30
+ * (a consumer workspace's ADR-0001) neither blocks nor is blocked by the functional chain's max. Everything
31
31
  * else shares one space, exactly as before. */
32
32
  function idSpaceOf(id) {
33
33
  return /^ADR-/.test(id.trim()) ? 'ADR' : 'functional';
@@ -17,4 +17,17 @@ export interface ToolSchema {
17
17
  };
18
18
  }
19
19
  export declare const HOOK_ENFORCED_TOOLS: Set<string>;
20
+ /**
21
+ * @implements A-SPEC-792.25 — the one set the wire serves: ListTools advertises it and CallTool dispatches it, so a
22
+ * hidden tool is an unknown tool on the wire (risk_check answered there while ListTools hid it, F1-e.0d).
23
+ */
24
+ export declare function isWireTool(name: string, fullProfile: boolean): boolean;
25
+ /**
26
+ * @implements A-SPEC-792.26 — the wire's one tool set: ListTools serves `names` and CallTool resolves through
27
+ * `handlerFor`, an exact own-property match within that set, so a hidden tool or a respelling of one is unknown to both.
28
+ */
29
+ export declare function wireDispatch<T>(handlers: Record<string, T>, fullProfile: boolean): {
30
+ names: string[];
31
+ handlerFor(name: string): T | undefined;
32
+ };
20
33
  export declare const TOOL_SCHEMAS: Record<string, ToolSchema>;
@@ -1,6 +1,8 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.TOOL_SCHEMAS = exports.HOOK_ENFORCED_TOOLS = void 0;
4
+ exports.isWireTool = isWireTool;
5
+ exports.wireDispatch = wireDispatch;
4
6
  // @implements 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
5
7
  // @implements A-SPEC-495 — the maintenance_analyze description carries the semantic-evidence
6
8
  // consumer contract (sem-verify / semCos / semanticAlternates) beside the anti-prediction warning.
@@ -37,6 +39,22 @@ const ROOT_ANY = str('Absolute path to the project root. Version control is opti
37
39
  // at module scope, so anything importing it for this constant attaches to stdio. This module holds
38
40
  // the rest of the tool metadata and has no import side effects.
39
41
  exports.HOOK_ENFORCED_TOOLS = new Set(['phase_check', 'risk_check', 'rtm_check', 'spec_validate']);
42
+ /**
43
+ * @implements A-SPEC-792.25 — the one set the wire serves: ListTools advertises it and CallTool dispatches it, so a
44
+ * hidden tool is an unknown tool on the wire (risk_check answered there while ListTools hid it, F1-e.0d).
45
+ */
46
+ function isWireTool(name, fullProfile) {
47
+ return fullProfile || !exports.HOOK_ENFORCED_TOOLS.has(name);
48
+ }
49
+ /**
50
+ * @implements A-SPEC-792.26 — the wire's one tool set: ListTools serves `names` and CallTool resolves through
51
+ * `handlerFor`, an exact own-property match within that set, so a hidden tool or a respelling of one is unknown to both.
52
+ */
53
+ function wireDispatch(handlers, fullProfile) {
54
+ const names = Object.keys(handlers).filter((name) => isWireTool(name, fullProfile));
55
+ const set = new Set(names);
56
+ return { names, handlerFor: (name) => (set.has(name) && Object.prototype.hasOwnProperty.call(handlers, name) ? handlers[name] : undefined) };
57
+ }
40
58
  exports.TOOL_SCHEMAS = {
41
59
  approval_commit: {
42
60
  description: 'Complete a server-issued, one-use in-session approval continuation. This sensitive annotation asks the host to show its native tool confirmation; the server records arrival only as a host-gated continuation, never proof of a human response. Send the unmodified approvalIntent returned by the original refused action, then retry that original action. The server verifies challenge, kind, target, subject digest, workspace, session run and expiry; this tool never reads HOLMES_APPROVAL or writes configuration.',
@@ -170,6 +188,15 @@ exports.TOOL_SCHEMAS = {
170
188
  properties: {
171
189
  id: str('Id of the spec to retire.'),
172
190
  reason: str('Why it is being retired. Omitted from the document when blank; not required when the spec already carries superseded_by.'),
191
+ // @implements A-SPEC-222.4
192
+ supersededBy: str('On an ALREADY-outdated spec with no superseded_by: record this approved spec of the same kind as its successor (records spec-superseded), so an anchor can move to it. Refused, writing nothing, for a draft, another kind, or a spec that already names a different successor.'),
193
+ // @implements A-SPEC-222.5
194
+ directive: str('With supersededBy on a SEALED spec under an active full autonomy profile: the supervisor directive this retirement follows (a section title or message id). It is recorded; when every machine condition holds (sealed same-kind successor; an A-SPEC anchored nowhere or a T-SPEC whose successor is tested; no approved dependent outside the chain; not graded for a person; the successor covers what it covered) the spec is retired without an approval. Otherwise the refusal is today\'s, with autonomousRefused naming the failed condition.'),
195
+ also: {
196
+ type: 'array',
197
+ description: 'Further { id, supersededBy } pairs retired in the same autonomous act (a chain, e.g. the T-SPEC over the retired A-SPEC).',
198
+ items: { type: 'object', properties: { id: str('Id of the spec to retire.'), supersededBy: str('Its sealed successor.') }, required: ['id', 'supersededBy'] },
199
+ },
173
200
  root: str('Optional when the server is bound to a file store — the ledger location is derived from the store itself; if supplied it must resolve to the SAME project.'),
174
201
  },
175
202
  required: ['id'],
@@ -225,7 +252,7 @@ exports.TOOL_SCHEMAS = {
225
252
  },
226
253
  // @implements A-SPEC-718.4
227
254
  approval_ask: {
228
- description: "Ask the person to decide ONE pending approval request in this session's approval form — the id a refusal named (`[승인 대기 req-…]`), from the approval inbox or this machine's refusal log. The person chooses approve / deny / question; the answer is recorded exactly as the operator's grant, deny or question is recorded (actor `elicitation:<client>`), so after `granted` retry the refused act once. Returns { ok, id, kind, decision: granted|denied|held|undecided, nextAction }. Nothing is recorded without the person's answer: silence leaves the request pending. A request a run awaits is asked here too, from the interactive session (the run resumes on the grant). Refuses, recording nothing, from a run's own server, when the session cannot show a form (HOLMES_ELICIT=off, a server no harness launched, a client without forms), and for a shell/config/code-write request on a client not yet measured to wait for a person (only claude-code today).",
255
+ description: "Ask the person to decide ONE pending approval request in this session's approval form — the id a refusal named (`[승인 대기 req-…]`), from the approval inbox or this machine's refusal log. The person chooses approve / deny / question; the answer is recorded exactly as the operator's grant, deny or question is recorded (under the session's elicitation channel actor), so after `granted` retry the refused act once. Returns { ok, id, kind, decision: granted|denied|held|undecided, nextAction }. Nothing is recorded without the person's answer: silence leaves the request pending. A request a run awaits is asked here too, from the interactive session (the run resumes on the grant). Refuses, recording nothing, from a run's own server, when the session cannot show a form (HOLMES_ELICIT=off, a server no harness launched, a client without forms), and for a shell/config/code-write request on a client not yet measured to wait for a person (only claude-code today).",
229
256
  inputSchema: {
230
257
  type: 'object',
231
258
  properties: {
@@ -235,9 +262,22 @@ exports.TOOL_SCHEMAS = {
235
262
  required: ['id'],
236
263
  },
237
264
  },
265
+ // @implements A-SPEC-779.7
266
+ approval_withdraw: {
267
+ description: "Withdraw ONE pending approval request this session's MCP server filed, when the act it was filed for is no longer wanted (the slice was abandoned, a spec was replaced). Recorded as `withdrawn` — never granted, never denied — and gone from the operator's inbox, so nobody approves a request you gave up. Returns { ok, id, decision: withdrawn } or { ok: false, reason }. Refuses a request another session (or a hook, the CLI, a run) filed; a run withdraws its own with `approve --withdraw`. A reason is required: it is what the operator reads in place of a decision.",
268
+ inputSchema: {
269
+ type: 'object',
270
+ properties: {
271
+ id: str('The request id, e.g. req-0123456789ab.'),
272
+ reason: str('Why the request is no longer wanted.'),
273
+ root: str('Optional when the server is bound to a file store; if supplied it must resolve to the SAME project.'),
274
+ },
275
+ required: ['id', 'reason'],
276
+ },
277
+ },
238
278
  // @implements A-SPEC-102.9
239
279
  review_verdict: {
240
- description: "Ask the person for an independent review verdict on base..head in this session's approval form. approve records pass, deny records fail with the person's reason as the finding; the verdict is recorded as the person's (reviewer.person true, channel elicitation:<client>, independent true), so it satisfies the review gate without a separate terminal. Returns { ok, decision: pass|fail|undecided, independent? }. Silence, a question and an automatic decline record nothing. Refuses, recording nothing, inside a run, when the session cannot show a form, and on a client not yet measured to wait for a person (only claude-code today).",
280
+ description: "Ask the person for an independent review verdict on base..head in this session's approval form. approve records pass, deny records fail with the person's reason as the finding; the verdict is recorded as the person's (reviewer.person true, the elicitation channel, independent true), so it satisfies the review gate without a separate terminal. Returns { ok, decision: pass|fail|undecided, independent? }. Silence, a question and an automatic decline record nothing. Refuses, recording nothing, inside a run, when the session cannot show a form, and on a client not yet measured to wait for a person (only claude-code today).",
241
281
  inputSchema: {
242
282
  type: 'object',
243
283
  properties: {
@@ -0,0 +1,19 @@
1
+ /** `--target` when given, else `cwd`; the `.ax` project it belongs to, or the path itself when it belongs to none.
2
+ * @implements A-SPEC-102.31 (W7) — a `--target` that does not exist is returned resolved, never thrown: the act reports
3
+ * it as before, and the catalog of a root that cannot be resolved refuses the guarded acts. */
4
+ export declare function actRoot(flags: Record<string, string | boolean | undefined>, cwd?: string): string;
5
+ /** The search for projects under an autonomy scope: its depth and the directories it may read. */
6
+ export declare const SCOPE_SEARCH_LIMITS: {
7
+ readonly maxDepth: 16;
8
+ readonly maxDirs: 10000;
9
+ };
10
+ /**
11
+ * Every `.ax` project under `scope` (the scope's own included). autonomy full covers the whole subtree, so each project
12
+ * there is judged by its additions (A-SPEC-102.30, medium 2). Links are not followed, and `.git`, `node_modules` and
13
+ * `.ax` are not entered. A search past either limit, or a directory it cannot read, throws: the union could not be
14
+ * known, and the act is refused.
15
+ */
16
+ export declare function projectsUnder(scope: string, limits?: {
17
+ maxDepth: number;
18
+ maxDirs: number;
19
+ }): string[];
@@ -0,0 +1,100 @@
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.SCOPE_SEARCH_LIMITS = void 0;
37
+ exports.actRoot = actRoot;
38
+ exports.projectsUnder = projectsUnder;
39
+ // @implements A-SPEC-102.30, A-SPEC-102.31
40
+ /**
41
+ * The project an operator act works on, decided once. approve and lock recover act on the working directory when no
42
+ * `--target` is given (their usage says so); the guard was handed no root there, so `approve --grant` from inside a
43
+ * project judged without the project's additions while the queue it wrote was that project's (A and B, reproduced).
44
+ * The queue and the guard now take this one value.
45
+ */
46
+ const fs = __importStar(require("node:fs"));
47
+ const path = __importStar(require("node:path"));
48
+ const root_1 = require("./root");
49
+ /** `--target` when given, else `cwd`; the `.ax` project it belongs to, or the path itself when it belongs to none.
50
+ * @implements A-SPEC-102.31 (W7) — a `--target` that does not exist is returned resolved, never thrown: the act reports
51
+ * it as before, and the catalog of a root that cannot be resolved refuses the guarded acts. */
52
+ function actRoot(flags, cwd = process.cwd()) {
53
+ const dir = path.resolve(cwd, typeof flags.target === 'string' ? flags.target : '.');
54
+ try {
55
+ return (0, root_1.resolveProjectRoot)(dir, { includeGit: false }).root; // the `.ax` project, or the path itself, canonical
56
+ }
57
+ catch {
58
+ return dir;
59
+ }
60
+ }
61
+ /** The search for projects under an autonomy scope: its depth and the directories it may read. */
62
+ exports.SCOPE_SEARCH_LIMITS = { maxDepth: 16, maxDirs: 10_000 };
63
+ const NOT_ENTERED = new Set(['.git', 'node_modules', '.ax']);
64
+ /**
65
+ * Every `.ax` project under `scope` (the scope's own included). autonomy full covers the whole subtree, so each project
66
+ * there is judged by its additions (A-SPEC-102.30, medium 2). Links are not followed, and `.git`, `node_modules` and
67
+ * `.ax` are not entered. A search past either limit, or a directory it cannot read, throws: the union could not be
68
+ * known, and the act is refused.
69
+ */
70
+ function projectsUnder(scope, limits = exports.SCOPE_SEARCH_LIMITS) {
71
+ const found = [];
72
+ let read = 0;
73
+ const stack = [[path.resolve(scope), 0]];
74
+ while (stack.length > 0) {
75
+ const [dir, depth] = stack.pop();
76
+ if (++read > limits.maxDirs)
77
+ throw new Error(`more than ${limits.maxDirs} directories under ${scope}`);
78
+ let entries;
79
+ try {
80
+ entries = fs.readdirSync(dir, { withFileTypes: true });
81
+ }
82
+ catch (e) {
83
+ throw new Error(`${dir} cannot be read (${e.code ?? 'error'})`);
84
+ }
85
+ // @implements A-SPEC-102.31 — resolveProjectRoot's rule (a `.ax` directory, a link to one, the file system's case
86
+ // rule); the name compare missed `.AX` and a linked `.ax`. The search itself follows no link and enters no `.ax`
87
+ if ((0, root_1.isProjectDir)(dir))
88
+ found.push(dir);
89
+ for (const e of entries) {
90
+ if (!e.isDirectory())
91
+ continue;
92
+ if (NOT_ENTERED.has(e.name.toLowerCase()))
93
+ continue;
94
+ if (depth + 1 > limits.maxDepth)
95
+ throw new Error(`a search depth of ${limits.maxDepth} is passed under ${scope}`);
96
+ stack.push([path.join(dir, e.name), depth + 1]);
97
+ }
98
+ }
99
+ return found;
100
+ }
@@ -40,7 +40,7 @@ exports.isBaselineTrusted = isBaselineTrusted;
40
40
  exports.readBaseline = readBaseline;
41
41
  exports.shouldRecordBaseline = shouldRecordBaseline;
42
42
  exports.listBaselines = listBaselines;
43
- // @implements A-SPEC-128
43
+ // @implements A-SPEC-128, A-SPEC-222.10
44
44
  const fs = __importStar(require("node:fs"));
45
45
  const path = __importStar(require("node:path"));
46
46
  const node_crypto_1 = require("node:crypto");
@@ -129,8 +129,9 @@ function isBaselineTrusted(root, label, ledgerFile) {
129
129
  // so scanning only the legacy file would fail to find an anchor this very process just wrote.
130
130
  let events;
131
131
  try {
132
- const { FileLedgerStore } = require('../governance/ledger-store');
133
- events = new FileLedgerStore(path.dirname(ledgerFile)).loadAll();
132
+ // @implements A-SPEC-222.10 — H-C: a trusted anchor only (it narrows the test scope)
133
+ const { TrustedLedgerStore } = require('../governance/recorded-pairs');
134
+ events = new TrustedLedgerStore(path.dirname(ledgerFile)).loadAll();
134
135
  }
135
136
  catch {
136
137
  return false;