@holmes-lab/holmes-kit 0.39.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 (298) hide show
  1. package/CHANGELOG.md +344 -6
  2. package/README.md +54 -41
  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 +49 -13
  47. package/dist/holmes/cli/approve.js +249 -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 +34 -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 +202 -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.js +1 -1
  69. package/dist/holmes/cli/release-docs.js +1 -1
  70. package/dist/holmes/cli/run-exec.d.ts +141 -0
  71. package/dist/holmes/cli/run-exec.js +1435 -0
  72. package/dist/holmes/cli/run-provision.d.ts +3 -1
  73. package/dist/holmes/cli/run-provision.js +255 -44
  74. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  75. package/dist/holmes/cli/run-wiring.js +270 -0
  76. package/dist/holmes/cli/run.d.ts +21 -0
  77. package/dist/holmes/cli/run.js +341 -92
  78. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  79. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  80. package/dist/holmes/cli/screen-safe.js +18 -756
  81. package/dist/holmes/config/config.d.ts +2 -0
  82. package/dist/holmes/config/config.js +5 -2
  83. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  84. package/dist/holmes/cpg/import-resolver.js +1 -1
  85. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  86. package/dist/holmes/governance/approval-decisions.js +29 -0
  87. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  88. package/dist/holmes/governance/approval-grants.js +612 -33
  89. package/dist/holmes/governance/approval-queue.d.ts +26 -0
  90. package/dist/holmes/governance/approval-queue.js +109 -11
  91. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  92. package/dist/holmes/governance/approval-spend.js +191 -0
  93. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  94. package/dist/holmes/governance/autonomous-shell.js +332 -0
  95. package/dist/holmes/governance/autonomy.d.ts +5 -0
  96. package/dist/holmes/governance/autonomy.js +16 -11
  97. package/dist/holmes/governance/constitution.d.ts +5 -0
  98. package/dist/holmes/governance/constitution.js +32 -12
  99. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  100. package/dist/holmes/governance/full-autonomy.js +103 -7
  101. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  102. package/dist/holmes/governance/harness-catalog.js +348 -0
  103. package/dist/holmes/governance/human-channel.d.ts +38 -0
  104. package/dist/holmes/governance/human-channel.js +49 -0
  105. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  106. package/dist/holmes/governance/install-manifest.js +160 -0
  107. package/dist/holmes/governance/ledger-rechain.js +2 -0
  108. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  109. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  110. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  111. package/dist/holmes/governance/ledger-store.js +186 -8
  112. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  113. package/dist/holmes/governance/provenance-chain.js +19 -4
  114. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  115. package/dist/holmes/governance/provenance-ledger.js +53 -18
  116. package/dist/holmes/governance/push-gate-runner.js +11 -7
  117. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  118. package/dist/holmes/governance/recorded-pairs.js +522 -0
  119. package/dist/holmes/governance/replica-id.d.ts +1 -1
  120. package/dist/holmes/governance/replica-id.js +1 -1
  121. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  122. package/dist/holmes/governance/spec-seam.js +587 -0
  123. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  124. package/dist/holmes/governance/spend-kinds.js +18 -0
  125. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  126. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  127. package/dist/holmes/guardrail/impact-gate.d.ts +1 -0
  128. package/dist/holmes/guardrail/impact-gate.js +1 -1
  129. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  130. package/dist/holmes/guardrail/line-continuation.js +39 -0
  131. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  132. package/dist/holmes/guardrail/operator-person.js +57 -11
  133. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  134. package/dist/holmes/guardrail/refusal-codes.js +64 -10
  135. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  136. package/dist/holmes/guardrail/risk-classifier.js +228 -16
  137. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  138. package/dist/holmes/guardrail/risk-gate.js +7 -34
  139. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  140. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  141. package/dist/holmes/guardrail/run-refusals.js +24 -8
  142. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  143. package/dist/holmes/guardrail/run-stages.js +25 -5
  144. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  145. package/dist/holmes/guardrail/shell-words.js +24 -3
  146. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  147. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  148. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  149. package/dist/holmes/guardrail/write-target.js +26 -5
  150. package/dist/holmes/hooks/pre-tool-use.d.ts +105 -1
  151. package/dist/holmes/hooks/pre-tool-use.js +1134 -167
  152. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  153. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  154. package/dist/holmes/hooks/stop.d.ts +23 -0
  155. package/dist/holmes/hooks/stop.js +86 -33
  156. package/dist/holmes/mcp/approval-adapters.js +3 -1
  157. package/dist/holmes/mcp/approval-commit.js +3 -2
  158. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  159. package/dist/holmes/mcp/approval-policy.js +3 -1
  160. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  161. package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
  162. package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
  163. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  164. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  165. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  166. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  167. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  168. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  169. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  170. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  171. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  172. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  173. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  174. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  175. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  176. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  177. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  178. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  179. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  180. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  181. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  182. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  183. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  184. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  185. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  186. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  187. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  188. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  189. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  190. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  191. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  192. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  193. package/dist/holmes/mcp/handlers/test-execution.d.ts +1 -1
  194. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  195. package/dist/holmes/mcp/handlers.d.ts +89 -79
  196. package/dist/holmes/mcp/handlers.js +69 -22
  197. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  198. package/dist/holmes/mcp/harness-attestation.js +325 -53
  199. package/dist/holmes/mcp/maintenance-analyze.d.ts +1 -1
  200. package/dist/holmes/mcp/maintenance-analyze.js +9 -9
  201. package/dist/holmes/mcp/maintenance-evidence.js +31 -2
  202. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  203. package/dist/holmes/mcp/server-staleness.js +1 -1
  204. package/dist/holmes/mcp/server.js +9 -8
  205. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  206. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  207. package/dist/holmes/mcp/tool-schemas.js +29 -2
  208. package/dist/holmes/project/act-root.d.ts +19 -0
  209. package/dist/holmes/project/act-root.js +100 -0
  210. package/dist/holmes/project/baseline.js +4 -3
  211. package/dist/holmes/project/bounded-group.d.ts +47 -0
  212. package/dist/holmes/project/bounded-group.js +140 -0
  213. package/dist/holmes/project/bounded-io.d.ts +50 -2
  214. package/dist/holmes/project/bounded-io.js +138 -6
  215. package/dist/holmes/project/change-source.js +2 -2
  216. package/dist/holmes/project/instance-id.d.ts +10 -0
  217. package/dist/holmes/project/instance-id.js +233 -0
  218. package/dist/holmes/project/machine-identity.d.ts +25 -0
  219. package/dist/holmes/project/machine-identity.js +133 -0
  220. package/dist/holmes/project/owned-lock.d.ts +84 -0
  221. package/dist/holmes/project/owned-lock.js +263 -0
  222. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  223. package/dist/holmes/project/plain-lock-fs.js +126 -0
  224. package/dist/holmes/project/request-lock.d.ts +85 -0
  225. package/dist/holmes/project/request-lock.js +459 -0
  226. package/dist/holmes/project/root.d.ts +12 -4
  227. package/dist/holmes/project/root.js +26 -7
  228. package/dist/holmes/project/run-records.d.ts +19 -0
  229. package/dist/holmes/project/run-records.js +94 -12
  230. package/dist/holmes/project/screen-text.d.ts +94 -0
  231. package/dist/holmes/project/screen-text.js +763 -0
  232. package/dist/holmes/project/spend-lock.d.ts +82 -0
  233. package/dist/holmes/project/spend-lock.js +413 -0
  234. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  235. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  236. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  237. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  238. package/dist/holmes/review/confidence-calibration.js +1 -1
  239. package/dist/holmes/review/content-verify.js +1 -1
  240. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  241. package/dist/holmes/review/hop-ablation.js +5 -5
  242. package/dist/holmes/review/point-in-time-replay.js +12 -3
  243. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  244. package/dist/holmes/review/rank-diagnosis.js +1 -1
  245. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  246. package/dist/holmes/review/replay-corpus.js +25 -9
  247. package/dist/holmes/review/requirement-triage.js +2 -2
  248. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  249. package/dist/holmes/review/semantic-arm.js +3 -3
  250. package/dist/holmes/review/test-outcomes.js +3 -1
  251. package/dist/holmes/review/test-runner.d.ts +11 -0
  252. package/dist/holmes/review/test-runner.js +31 -10
  253. package/dist/holmes/review/test-selection-breadth.js +2 -2
  254. package/dist/holmes/review/verdicts.d.ts +105 -8
  255. package/dist/holmes/review/verdicts.js +640 -36
  256. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  257. package/dist/holmes/rtm/anchor-census.js +151 -0
  258. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  259. package/dist/holmes/rtm/anchor-ids.js +45 -2
  260. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  261. package/dist/holmes/rtm/comment-ranges.js +104 -0
  262. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  263. package/dist/holmes/rtm/counted-tests.js +63 -0
  264. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  265. package/dist/holmes/rtm/known-defects.js +1 -1
  266. package/dist/holmes/rtm/localize.js +1 -1
  267. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  268. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  269. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  270. package/dist/holmes/rtm/test-scope.js +166 -5
  271. package/dist/holmes/rtm/trace-gaps.js +1 -1
  272. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  273. package/dist/holmes/runtime/dispatch.js +12 -1
  274. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  275. package/dist/holmes/semantic/cloud-usage.js +1 -1
  276. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  277. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  278. package/dist/holmes/spec/approval-blockers.js +1 -1
  279. package/dist/holmes/spec/entity-store.d.ts +6 -1
  280. package/dist/holmes/spec/entity-store.js +16 -2
  281. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  282. package/dist/holmes/spec/entity-transaction.js +87 -170
  283. package/dist/holmes/spec/spec-store.d.ts +12 -6
  284. package/dist/holmes/spec/spec-store.js +4 -2
  285. package/dist/holmes/spec/spec-types.js +1 -1
  286. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  287. package/dist/holmes/spec/succession-guard.js +187 -0
  288. package/dist/holmes/spec/succession.d.ts +70 -0
  289. package/dist/holmes/spec/succession.js +171 -0
  290. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  291. package/docs/install-guide.md +9 -3
  292. package/docs/language-support.md +78 -0
  293. package/package.json +4 -3
  294. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  295. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  296. package/playbooks/publish/PLAYBOOK.md +45 -33
  297. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  298. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -40,18 +40,23 @@ exports.normalizeCommandPaths = normalizeCommandPaths;
40
40
  exports.verbWordRe = verbWordRe;
41
41
  exports.plainShellText = plainShellText;
42
42
  exports.splitShellClauses = splitShellClauses;
43
+ exports.splitUnquoted = splitUnquoted;
43
44
  exports.shellTextOnlyReads = shellTextOnlyReads;
44
45
  exports.stripCommitMessages = stripCommitMessages;
45
46
  exports.classifyReversibility = classifyReversibility;
47
+ exports.gitConfigExecWrite = gitConfigExecWrite;
46
48
  exports.classifyArchitectureReversal = classifyArchitectureReversal;
47
49
  exports.classifySecret = classifySecret;
48
50
  exports.classifyBlastRadius = classifyBlastRadius;
49
51
  exports.assessRisk = assessRisk;
50
- // @implements A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4, A-SPEC-773.5
52
+ exports.outwardActsOf = outwardActsOf;
53
+ // @implements A-SPEC-794.54, A-SPEC-794.52, A-SPEC-794.51, A-SPEC-794.50, A-SPEC-794.49, A-SPEC-794.45, A-SPEC-794.42, A-SPEC-794.40, A-SPEC-794.37, A-SPEC-794.35, A-SPEC-794.34, A-SPEC-794.33, A-SPEC-125.1, A-SPEC-773, A-SPEC-773.1, A-SPEC-773.2, A-SPEC-627,A-SPEC-728,A-SPEC-737, A-SPEC-747, A-SPEC-753, A-SPEC-747.1, A-SPEC-226.1, A-SPEC-226.2, A-SPEC-747.3, A-SPEC-226.3, A-SPEC-747.9, A-SPEC-728.3, A-SPEC-773.4, A-SPEC-773.5, A-SPEC-222.12
51
54
  const fs = __importStar(require("node:fs"));
52
55
  const path = __importStar(require("node:path"));
53
56
  const shell_argument_roles_1 = require("./shell-argument-roles");
54
57
  const write_target_1 = require("./write-target");
58
+ const line_continuation_1 = require("./line-continuation");
59
+ const unresolved_write_1 = require("./unresolved-write");
55
60
  const risk_types_1 = require("./risk-types");
56
61
  const linear_match_1 = require("./linear-match");
57
62
  const write_target_2 = require("./write-target");
@@ -1598,8 +1603,10 @@ function stripCommitMessages(cmd) {
1598
1603
  *
1599
1604
  * @implements A-SPEC-226
1600
1605
  */
1601
- function shellWritesProtectedAx(ncmd) {
1602
- if (!namesProtectedAx(ncmd))
1606
+ function shellWritesProtectedAx(ncmd, storeReachable = false) {
1607
+ // @implements A-SPEC-794.34 — `storeReachable`: the text is the pipelines a store path built at run time reaches
1608
+ // (A-SPEC-794.35), so it is judged whole without the "names a protected child" precondition
1609
+ if (!storeReachable && !namesProtectedAx(ncmd))
1603
1610
  return false;
1604
1611
  // @implements A-SPEC-227 — the ledger exemption is cancelled here, not inside the restore check,
1605
1612
  // because it is a property of the TARGET rather than of the command shape.
@@ -1625,7 +1632,7 @@ function shellWritesProtectedAx(ncmd) {
1625
1632
  });
1626
1633
  };
1627
1634
  const pipelines = independentPipelines(ncmd);
1628
- return pipelines === null ? writes(ncmd) : pipelines.filter((p) => namesProtectedAx(p)).some(writes);
1635
+ return pipelines === null || storeReachable ? writes(ncmd) : pipelines.filter((p) => namesProtectedAx(p)).some(writes);
1629
1636
  }
1630
1637
  /**
1631
1638
  * @implements A-SPEC-226.3 — A-SPEC-226 reads the path a command names, so `git add -A`, `git add .ax` and `git commit -a`
@@ -1726,23 +1733,103 @@ function stageClauseOf(words) {
1726
1733
  return { mode: update && !all ? 'tracked' : 'all', pathspecs, unknownBase };
1727
1734
  return update ? { mode: 'tracked', pathspecs, unknownBase } : null;
1728
1735
  }
1736
+ /** @implements A-SPEC-792.13 — the runners whose git the clause words do not show. */
1737
+ const OPAQUE_GIT_RUNNER = /^(?:sh|bash|zsh|dash|ksh|python|python3|node|perl|ruby|osascript|find|xargs|eval)$/;
1738
+ /**
1739
+ * @implements A-SPEC-792.13 — the clause as git sees it: `env` (its assignments and options), `command`, `builtin`,
1740
+ * `exec`, `nohup`, `nice` and `time` taken off the front, and an absolute path to git read as `git`.
1741
+ */
1742
+ function unwrapGitWords(words) {
1743
+ let w = words;
1744
+ for (let guard = 0; guard < 16 && w.length > 0; guard++) {
1745
+ const first = w[0];
1746
+ if (first === 'env') {
1747
+ let i = 1;
1748
+ let split = null;
1749
+ while (i < w.length && (/^[A-Za-z_]\w*=/.test(w[i]) || w[i].startsWith('-'))) {
1750
+ // @implements A-SPEC-792.15 — -S and --split-string carry the command itself: read it as words
1751
+ const o = w[i];
1752
+ if (o === '-S' || o === '--split-string') {
1753
+ split = w[i + 1] ?? '';
1754
+ i += 2;
1755
+ break;
1756
+ }
1757
+ if (/^-S./.test(o)) {
1758
+ split = o.slice(2);
1759
+ i += 1;
1760
+ break;
1761
+ }
1762
+ if (o.startsWith('--split-string=')) {
1763
+ split = o.slice('--split-string='.length);
1764
+ i += 1;
1765
+ break;
1766
+ }
1767
+ i += /^(?:-u|--unset|-C|--chdir)$/.test(o) ? 2 : 1;
1768
+ }
1769
+ w = split === null ? w.slice(i) : [...split.split(/\s+/).filter(Boolean), ...w.slice(i)];
1770
+ }
1771
+ else if (/^(?:command|builtin|exec|nohup)$/.test(first)) {
1772
+ w = w.slice(w[1] === '-p' || w[1] === '--' ? 2 : 1);
1773
+ }
1774
+ else if (first === 'nice') {
1775
+ w = w.slice(w[1] === '-n' ? 3 : /^-\d+$/.test(w[1] ?? '') ? 2 : 1);
1776
+ }
1777
+ else if (first === 'time') {
1778
+ w = w.slice(w[1] === '-p' ? 2 : 1);
1779
+ }
1780
+ else
1781
+ break;
1782
+ }
1783
+ return w.length > 0 && w[0].includes('/') && path.posix.basename(w[0].replace(/\\/g, '/')) === 'git' ? ['git', ...w.slice(1)] : w;
1784
+ }
1729
1785
  function stagingReachesSpecs(cmd, action) {
1730
1786
  const signal = action.stagedStore;
1731
- if (signal === undefined || !/\bgit\b/.test(cmd))
1787
+ if (signal === undefined)
1788
+ return false;
1789
+ return stagingReaches(cmd, action, signal.specsDir, (mode) => 'unanswered' in signal || signal.tracked || (mode === 'all' && signal.untracked));
1790
+ }
1791
+ /**
1792
+ * @implements A-SPEC-222.12 (N1) — the same act for another replica's ledger file: `git add -A`, `git add .` or
1793
+ * `git commit -a` that reaches one stages what the trusted-events port counts once it is committed
1794
+ */
1795
+ function stagingReachesForeignLedger(cmd, action) {
1796
+ const signal = action.stagedStore;
1797
+ if (signal === undefined || signal.ledgerDir === undefined)
1798
+ return false;
1799
+ const ledgerDir = signal.ledgerDir;
1800
+ const foreign = 'unanswered' in signal ? null : signal.foreignLedger;
1801
+ if (!('unanswered' in signal) && foreign === undefined)
1802
+ return false;
1803
+ return stagingReaches(cmd, action, ledgerDir, (mode) => foreign === null || foreign.tracked || (mode === 'all' && foreign.untracked));
1804
+ }
1805
+ function stagingReaches(cmd, action, protectedDir, changed) {
1806
+ if (!/\bgit\b/.test(cmd))
1732
1807
  return false;
1733
1808
  const fold = (p) => { const s = (0, linear_match_1.trimTrailing)(path.posix.normalize(p.replace(/\\/g, '/')), '/'); return process.platform === 'win32' ? s.toLowerCase() : s; };
1734
1809
  const inside = (t, r) => t === r || t.startsWith(r + '/');
1735
- const specs = fold(signal.specsDir);
1810
+ const specs = fold(protectedDir);
1736
1811
  const root = action.projectRoot ? fold(action.projectRoot) : null;
1737
1812
  const base0 = action.cwd ?? action.projectRoot;
1738
- const changed = (mode) => 'unanswered' in signal || signal.tracked || (mode === 'all' && signal.untracked);
1739
1813
  let movedBase = false;
1740
1814
  for (const clause of splitShellClauses(stripCommitMessages(cmd))) {
1741
- const words = clauseWords(clause);
1815
+ const words = unwrapGitWords(clauseWords(clause));
1742
1816
  if (/^(?:cd|pushd|popd)$/.test(words[0] ?? '')) {
1743
1817
  movedBase = true;
1744
1818
  continue;
1745
1819
  }
1820
+ // @implements A-SPEC-792.13 — an alias is a staging verb the text does not show; git behind a shell, an
1821
+ // interpreter, find -exec or xargs is not parsed here: either reaches the store when it has changes
1822
+ if (words[0] === 'git' && words.some((w) => /^alias\./i.test(w) || /^-calias\./i.test(w))) {
1823
+ if (changed('all'))
1824
+ return true;
1825
+ continue;
1826
+ }
1827
+ if (OPAQUE_GIT_RUNNER.test(words[0] ?? '') && /\bgit\b/.test(clause) && /\b(?:add|stage|commit)\b|alias\./i.test(clause)
1828
+ && (!/^(?:sh|bash|zsh|dash|ksh)$/.test(words[0]) || words.includes('-c')) && (words[0] !== 'find' || words.some((w) => /^-exec(?:dir)?$/.test(w)))) {
1829
+ if (changed('all'))
1830
+ return true;
1831
+ continue;
1832
+ }
1746
1833
  const st = stageClauseOf(words);
1747
1834
  if (st === null || !changed(st.mode))
1748
1835
  continue;
@@ -1753,7 +1840,8 @@ function stagingReachesSpecs(cmd, action) {
1753
1840
  continue;
1754
1841
  }
1755
1842
  for (const p of st.pathspecs) {
1756
- if (base === null || /[*?[$`~]/.test(p) || p.startsWith(':'))
1843
+ // @implements A-SPEC-792.38 — `{` too: the shell expands `.ax/{specs,}` before git sees it (allowed in production)
1844
+ if (base === null || /[*?[{$`~]/.test(p) || p.startsWith(':'))
1757
1845
  return true;
1758
1846
  const abs = fold(path.posix.resolve(base, p.replace(/\\/g, '/')));
1759
1847
  if (inside(specs, abs) || inside(abs, specs))
@@ -1796,13 +1884,20 @@ function independentPipelines(ncmd) {
1796
1884
  * words, an `eval`/`-c` program's escaped words): `r''m -rf /usr/local`, `r\m -rf .git`, `g''it reset --hard` were allowed
1797
1885
  * while their plain forms were denied (measured). The stricter verdict stands.
1798
1886
  */
1887
+ function storeBuiltFrom(action) {
1888
+ const roles = (0, shell_argument_roles_1.shellArgumentRoles)(action.command ?? '', action.cwd ?? action.projectRoot ?? null);
1889
+ return (0, unresolved_write_1.storePathBuiltJudgement)(stripCommitMessages(roles.governanceText), action.cwd, action.projectRoot, (c) => splitUnquoted(c, false));
1890
+ }
1799
1891
  function classifyReversibility(action) {
1800
1892
  const raw = action.command ?? '';
1801
1893
  const joined = raw === '' ? raw : (0, write_target_2.joinShellText)(raw);
1894
+ // @implements A-SPEC-794.37 — the data in a command is judged from the command as written, once: the joined text has no
1895
+ // quoted here-document delimiter left to tell its body from code (B-H1)
1896
+ const built = action.kind === 'shell' ? storeBuiltFrom(action) : null;
1802
1897
  if (joined === raw)
1803
- return withAxCwdNote(classifyReversibilityAsWritten(action), action);
1804
- const a = classifyReversibilityAsWritten(action);
1805
- const b = classifyReversibilityAsWritten({ ...action, command: joined });
1898
+ return withAxCwdNote(classifyReversibilityAsWritten(action, built), action);
1899
+ const a = classifyReversibilityAsWritten(action, built);
1900
+ const b = classifyReversibilityAsWritten({ ...action, command: joined }, built);
1806
1901
  return withAxCwdNote((0, risk_types_1.maxLevel)(a.level, b.level) === a.level ? a : b, action);
1807
1902
  }
1808
1903
  /**
@@ -1816,14 +1911,66 @@ function withAxCwdNote(verdict, action) {
1816
1911
  const rel = path.relative(path.join(action.projectRoot, '.ax'), action.cwd);
1817
1912
  if (rel.startsWith('..') || path.isAbsolute(rel))
1818
1913
  return verdict;
1819
- const i = verdict.reasons.findIndex((r) => /protected \.ax governance path/.test(r));
1914
+ // @implements A-SPEC-794.42 — the built-path reasons too: leaving the mention out cannot help inside the store
1915
+ const i = verdict.reasons.findIndex((r) => /protected \.ax governance path/.test(r) || r === unresolved_write_1.STORE_BUILT_REASON || r === unresolved_write_1.STORE_WHOLE_REASON);
1820
1916
  if (i < 0)
1821
1917
  return verdict;
1822
1918
  const where = path.relative(action.projectRoot, action.cwd);
1823
- const note = `; this shell's working directory (${where}) is inside .ax, so every command run there is judged over .ax: run \`cd ${action.projectRoot}\` on its own first, then the command`;
1919
+ const note = `; this shell's working directory (${where}) is inside .ax, so every command run there is judged over .ax: run \`cd ${/\s/.test(action.projectRoot) ? `'${action.projectRoot}'` : action.projectRoot}\` on its own first, then the command`; // A-SPEC-794.45
1824
1920
  return { ...verdict, reasons: verdict.reasons.map((r, j) => (j === i ? r + note : r)) };
1825
1921
  }
1826
- function classifyReversibilityAsWritten(action) {
1922
+ /**
1923
+ * @implements A-SPEC-792.34 — the git configuration keys that name a program git runs (filters, fsmonitor, hooks path,
1924
+ * ssh, pager, diff and merge drivers, aliases, includes, credential helpers, editors); git keys are case-insensitive.
1925
+ */
1926
+ // @implements A-SPEC-792.39 — `hook.<name>.command` (config-based hooks) is not switched off by core.hooksPath.
1927
+ const GIT_EXEC_KEY_RE = /^(?:filter\..+|hook\..+|core\.(?:fsmonitor|hookspath|sshcommand|pager|attributesfile|editor|askpass|gitproxy)|diff\.external|diff\..+\.(?:textconv|command)|merge\..+\.driver|alias\..+|include\.path|includeif\..+|credential\.helper|credential\..+\.helper|gpg\.program|gpg\..+\.program|sequence\.editor|uploadpack\.packobjectshook)$/;
1928
+ const GIT_CONFIG_READ = new Set(['--get', '--get-all', '--get-regexp', '--get-urlmatch', '--list', '-l', '--get-color', '--get-colorbool']);
1929
+ const GIT_CONFIG_WRITE = new Set(['--unset', '--unset-all', '--add', '--replace-all', '--rename-section', '--remove-section']);
1930
+ const GIT_CONFIG_VALUED = new Set(['-f', '--file', '--blob', '--type', '--default', '--comment']);
1931
+ /**
1932
+ * The execution-surface key a `git config` in this command writes, `'--edit'` for an edit, or null. Every segment is
1933
+ * read; leading git options (`-C <dir>`, `-c <k=v>`, `--git-dir=…`) are skipped; `git config set|unset|edit` count too.
1934
+ */
1935
+ function gitConfigExecWrite(command) {
1936
+ for (const seg of command.split(/&&|\|\||[;|\n]/)) {
1937
+ const w = seg.trim().split(/\s+/).map((x) => x.replace(/^['"]|['"]$/g, '')).filter(Boolean);
1938
+ const g = w.findIndex((x) => x === 'git' || /[\\/]git$/.test(x));
1939
+ if (g < 0)
1940
+ continue;
1941
+ let i = g + 1;
1942
+ while (i < w.length && w[i].startsWith('-'))
1943
+ i += (w[i] === '-C' || w[i] === '-c') ? 2 : 1;
1944
+ if (w[i] !== 'config')
1945
+ continue;
1946
+ let rest = w.slice(i + 1);
1947
+ if (rest.some((x) => x === '--edit' || x === '-e') || rest[0] === 'edit')
1948
+ return '--edit';
1949
+ let write = rest.some((x) => GIT_CONFIG_WRITE.has(x));
1950
+ if (rest[0] === 'set' || rest[0] === 'unset') {
1951
+ write = true;
1952
+ rest = rest.slice(1);
1953
+ }
1954
+ if (!write && rest.some((x) => GIT_CONFIG_READ.has(x)))
1955
+ continue;
1956
+ const plain = [];
1957
+ for (let j = 0; j < rest.length; j++) {
1958
+ if (GIT_CONFIG_VALUED.has(rest[j])) {
1959
+ j++;
1960
+ continue;
1961
+ }
1962
+ if (!rest[j].startsWith('-'))
1963
+ plain.push(rest[j]);
1964
+ }
1965
+ const key = plain[0];
1966
+ if (key === undefined || !GIT_EXEC_KEY_RE.test(key.toLowerCase()))
1967
+ continue;
1968
+ if (write || plain.length >= 2)
1969
+ return key;
1970
+ }
1971
+ return null;
1972
+ }
1973
+ function classifyReversibilityAsWritten(action, built) {
1827
1974
  const axis = 'reversibility';
1828
1975
  const cmd = action.command ?? '';
1829
1976
  // Command-based hard-hitl checks run regardless of `kind` — a dangerous shell command
@@ -1835,6 +1982,10 @@ function classifyReversibilityAsWritten(action) {
1835
1982
  if (GIT_TOKEN_RE.test(cmd) && RESET_TOKEN_RE.test(cmd) && HARD_FLAG_RE.test(cmd)) {
1836
1983
  return { axis, level: 'hard-hitl', reasons: ['git reset --hard discards uncommitted work irreversibly'] };
1837
1984
  }
1985
+ const execKey = gitConfigExecWrite(cmd);
1986
+ if (execKey !== null) {
1987
+ return { axis, level: 'hard-hitl', reasons: [`git config changes what git runs (${execKey}) — a program inside Holmes's own git judgments`] };
1988
+ }
1838
1989
  // Removal targeting a protected .ax governance path is UNCONDITIONALLY hard-hitl —
1839
1990
  // `.ax/specs`/`.ax/decisions` deletion is non-bypassable per H-SPEC-125, independent
1840
1991
  // of `tracked` (the shell form of the delete-kind protected-path rule).
@@ -1882,7 +2033,8 @@ function classifyReversibilityAsWritten(action) {
1882
2033
  level: 'hard-hitl',
1883
2034
  // @implements A-SPEC-773.4 — name the reads the gate already admits (G0 round 1: 5 of 6 runs filed an approval
1884
2035
  // request for a read loop it could not judge, while one read command with a glob passes).
1885
- reasons: ['shell command over a protected .ax governance path is not recognisably read-only; to read, use one read command with literal paths or a glob — `cat .ax/specs/*/<ID>.md | head`, `grep -n <word> .ax/specs/…`, `sed -n 1,80p <file>` — or the Read tool; loops, xargs and sh -c are not judged as reads'],
2036
+ // @implements A-SPEC-794.40 — a loop of reads over literal paths passes, so it is not named as refused; a cd is
2037
+ reasons: ['shell command over a protected .ax governance path is not recognisably read-only; to read, use one read command with literal paths or a glob, without cd — `cat .ax/specs/*/<ID>.md | head`, `grep -n <word> .ax/specs/…`, `sed -n 1,80p <file>` — or the Read tool; xargs and sh -c are not judged as reads; a command that only mentions the path, in a message or a body, passes once the mention is left out'], // A-SPEC-794.42
1886
2038
  };
1887
2039
  }
1888
2040
  // @implements A-SPEC-226.3 — the same act without the spelling.
@@ -1893,6 +2045,26 @@ function classifyReversibilityAsWritten(action) {
1893
2045
  reasons: ['staging command reaches changed files in the protected .ax spec store without naming it (the same act as staging them by name)'],
1894
2046
  };
1895
2047
  }
2048
+ // @implements A-SPEC-222.12 (N1)
2049
+ if (stagingReachesForeignLedger(cmd, action)) {
2050
+ return {
2051
+ axis,
2052
+ level: 'hard-hitl',
2053
+ reasons: ['staging command reaches another replica\'s ledger file in .ax/ledger without naming it — once committed, its rows are trusted, so a person stages another replica\'s ledger'],
2054
+ };
2055
+ }
2056
+ // @implements A-SPEC-794.34 — a store path built while the command runs is judged by the not-a-read rule above as if it
2057
+ // named a protected path. It runs after the rules above, so a command one of them refuses keeps that rule's reason.
2058
+ // @implements A-SPEC-794.35 — only the pipelines that path reaches are judged, normalised as the whole command is
2059
+ if (built !== null) {
2060
+ const judged = [...new Set([
2061
+ scopeForClassification(normalizeCommandPaths(built.text)),
2062
+ scopeForClassification(normalizeCommandPaths(built.text, false)),
2063
+ ...(action.projectRoot ? [scopeForClassification(normalizeCommandPaths(segmentFlattened(built.text, action.projectRoot, action.cwd ?? action.projectRoot), false))] : []),
2064
+ ])].join('\n');
2065
+ if (shellWritesProtectedAx(judged, true))
2066
+ return { axis, level: 'hard-hitl', reasons: [built.whole ? unresolved_write_1.STORE_WHOLE_REASON : unresolved_write_1.STORE_BUILT_REASON] }; // A-SPEC-794.40
2067
+ }
1896
2068
  // A destructive recursive `rm` — either `-rf` on a non-safe target, or a recursive delete of
1897
2069
  // a catastrophic root (/, ~, $HOME, ., .., glob) even WITHOUT `-f` — is whole-tree destruction,
1898
2070
  // unconditionally hard-hitl regardless of `tracked`. The single-file `tracked===true` auto
@@ -2023,3 +2195,43 @@ function assessRisk(action, cfg) {
2023
2195
  const reasons = verdicts.filter((v) => v.level !== 'auto').flatMap((v) => v.reasons);
2024
2196
  return { level, verdicts, reasons };
2025
2197
  }
2198
+ /** The options before a subcommand that take the next word as their value. */
2199
+ const OPTION_TAKES_VALUE = {
2200
+ git: new Set(['-C', '-c', '--git-dir', '--work-tree', '--namespace']),
2201
+ npm: new Set(['--prefix', '-w', '--workspace', '--tag', '--registry']),
2202
+ };
2203
+ /** The options after the subcommand under which nothing leaves the machine. */
2204
+ const NO_OUTWARD_EFFECT = {
2205
+ git: new Set(['--help', '-h', '--dry-run', '-n']),
2206
+ npm: new Set(['--help', '-h', '--dry-run']),
2207
+ };
2208
+ /**
2209
+ * @implements A-SPEC-794.49, A-SPEC-794.50 — the outward acts a clause of this command runs, read with the readers above.
2210
+ * A comment or a here-document body is no clause, a control or grouping word is not the command, and a form with no
2211
+ * outward effect is no act. A runner's inner program, a substitution and a package script are not read.
2212
+ */
2213
+ function outwardActsOf(command) {
2214
+ const acts = new Set();
2215
+ // A-SPEC-794.51, A-SPEC-794.52 — a line continuation vanishes in the shell, so it vanishes here, before any reader sees it
2216
+ // A-SPEC-794.54 — a command the comment and body reader cannot finish is read whole
2217
+ for (const clause of splitShellClauses((0, line_continuation_1.joinLineContinuations)((0, unresolved_write_1.readableText)(command)))) {
2218
+ let words = clauseWords(clause).map((w) => w.replace(/^\(+|\)+$/g, '')).filter(Boolean);
2219
+ while (words.length > 0 && (unresolved_write_1.KEYWORD.test(words[0]) || /^[A-Za-z_]\w*=/.test(words[0])))
2220
+ words = words.slice(1);
2221
+ words = unwrapGitWords(words);
2222
+ const tool = words[0];
2223
+ if (tool !== 'git' && tool !== 'npm')
2224
+ continue;
2225
+ let i = 1;
2226
+ while ((words[i] ?? '').startsWith('-'))
2227
+ i += OPTION_TAKES_VALUE[tool].has(words[i]) ? 2 : 1;
2228
+ if (words[i] !== (tool === 'git' ? 'push' : 'publish'))
2229
+ continue;
2230
+ const rest = words.slice(i + 1);
2231
+ const end = rest.indexOf('--');
2232
+ if (rest.slice(0, end < 0 ? rest.length : end).some((w) => NO_OUTWARD_EFFECT[tool].has(w)))
2233
+ continue;
2234
+ acts.add(tool === 'git' ? 'push' : 'publish');
2235
+ }
2236
+ return [...acts];
2237
+ }
@@ -1,7 +1,8 @@
1
1
  import { RiskAssessment, RiskLevel } from './risk-types';
2
+ import { type LedgerActor } from '../governance/human-channel';
2
3
  export type Enforcement = 'block' | 'warn' | 'off';
3
4
  export interface Approval {
4
- actor: string;
5
+ actor: LedgerActor;
5
6
  token: string;
6
7
  rationale: string;
7
8
  /**
@@ -50,13 +51,6 @@ export declare function approvalCovers(a: Approval | undefined, action: {
50
51
  kind: string;
51
52
  target: string;
52
53
  }, now: string): boolean;
53
- /**
54
- * @implements A-SPEC-133
55
- * Has this single-use nonce already been spent? Sync-reads the append-only provenance chain for a
56
- * `nonce-consumed` entry carrying the nonce. A missing/unreadable ledger means nothing was consumed
57
- * yet — false, never a throw (the gate must not crash on a fresh project).
58
- */
59
- export declare function isNonceConsumed(nonce: string, ledgerFile: string): boolean;
60
54
  /**
61
55
  * Graduated response for a bare risk level, with no notion of approval.
62
56
  * Pure: no I/O, no clock, no randomness.
@@ -2,9 +2,9 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.isValidApproval = isValidApproval;
4
4
  exports.approvalCovers = approvalCovers;
5
- exports.isNonceConsumed = isNonceConsumed;
6
5
  exports.gradedResponse = gradedResponse;
7
6
  exports.riskGate = riskGate;
7
+ const human_channel_1 = require("../governance/human-channel");
8
8
  /** All of actor/token/rationale must be present and non-empty (whitespace-only counts as empty). */
9
9
  function isValidApproval(a) {
10
10
  if (a == null)
@@ -13,7 +13,10 @@ function isValidApproval(a) {
13
13
  // return false, NEVER throw — the gate is handed unvalidated external JSON (MCP
14
14
  // call / CLI flag / config), and a crash here would be a DoS on the safety
15
15
  // mechanism (or a fail-open if a caller wraps it in try/catch). Guard the type.
16
- return [a.actor, a.token, a.rationale].every((s) => typeof s === 'string' && s.trim().length > 0);
16
+ // @implements A-SPEC-792.26 — a minted person-channel actor is a String object, well-formed by construction
17
+ return (0, human_channel_1.isMinted)(a.actor) || [a.actor].every((s) => typeof s === 'string' && s.trim().length > 0)
18
+ ? [a.token, a.rationale].every((s) => typeof s === 'string' && s.trim().length > 0)
19
+ : false;
17
20
  }
18
21
  /**
19
22
  * @implements A-SPEC-133
@@ -88,38 +91,8 @@ function patternMatches(pattern, target) {
88
91
  const re = new RegExp('^' + p.split('*').map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$');
89
92
  return re.test(target);
90
93
  }
91
- /**
92
- * @implements A-SPEC-133
93
- * Has this single-use nonce already been spent? Sync-reads the append-only provenance chain for a
94
- * `nonce-consumed` entry carrying the nonce. A missing/unreadable ledger means nothing was consumed
95
- * yet — false, never a throw (the gate must not crash on a fresh project).
96
- */
97
- function isNonceConsumed(nonce, ledgerFile) {
98
- if (!nonce)
99
- return false;
100
- let text;
101
- try {
102
- // Local require to keep this module free of a load-time fs dependency for its pure consumers.
103
- const fs = require('node:fs');
104
- if (!fs.existsSync(ledgerFile))
105
- return false;
106
- text = fs.readFileSync(ledgerFile, 'utf8');
107
- }
108
- catch {
109
- return false;
110
- }
111
- for (const line of text.split('\n')) {
112
- if (!line.trim())
113
- continue;
114
- try {
115
- const evt = JSON.parse(line);
116
- if (evt.kind === 'nonce-consumed' && Array.isArray(evt.inputs) && evt.inputs.includes(nonce))
117
- return true;
118
- }
119
- catch { /* skip unparseable line */ }
120
- }
121
- return false;
122
- }
94
+ // @implements A-SPEC-794.4 — the single-file nonce reader that stood here had no production caller and matched only the
95
+ // raw nonce in one chain; every spend is judged by the ledger store's isNonceConsumed, across chains and fingerprints.
123
96
  /**
124
97
  * Graduated response for a bare risk level, with no notion of approval.
125
98
  * Pure: no I/O, no clock, no randomness.
@@ -50,13 +50,23 @@ export interface RiskAction {
50
50
  */
51
51
  stagedStore?: StagedStoreSignal;
52
52
  }
53
+ /**
54
+ * @implements A-SPEC-222.12 (N1) — `foreignLedger`: changes to another replica's ledger file (any `provenance*.jsonl` but
55
+ * this writer's own) under `ledgerDir`, which a staging act puts within the trusted-events port's reach once committed.
56
+ */
53
57
  export type StagedStoreSignal = {
54
58
  specsDir: string;
55
59
  tracked: boolean;
56
60
  untracked: boolean;
61
+ ledgerDir?: string;
62
+ foreignLedger?: {
63
+ tracked: boolean;
64
+ untracked: boolean;
65
+ };
57
66
  } | {
58
67
  specsDir: string;
59
68
  unanswered: true;
69
+ ledgerDir?: string;
60
70
  };
61
71
  export interface RiskThresholds {
62
72
  blastRadiusConfirm?: number;
@@ -95,7 +95,7 @@ function applyPlanScope(out, ctx) {
95
95
  if (targets.length === 0)
96
96
  return out;
97
97
  const refusal = planScopeRefusal(ctx, targets);
98
- return refusal ? { permissionDecision: 'deny', permissionDecisionReason: refusal } : out;
98
+ return refusal ? { permissionDecision: 'deny', refusal: 'scope.outside', permissionDecisionReason: refusal } : out; // A-SPEC-245.24
99
99
  }
100
100
  /**
101
101
  * @implements A-SPEC-774.23 — the plan-scope judgement for any writer (file tools, apply_patch, the shell): null when
@@ -108,6 +108,8 @@ function planScopeRefusal(ctx, targets) {
108
108
  const mode = (0, run_mode_1.runMode)(ctx.env, ctx.projectRoot, ctx.cwd, ctx.sessionId);
109
109
  if (!mode.run || !mode.id)
110
110
  return null;
111
+ // A-SPEC-102.32 — non-strict: a forged pointer finds no run record, so the run reads as unscoped and the plan scope is
112
+ // off; a pointer that cannot be opened throws to the hook
111
113
  const rec = (0, run_records_1.listRuns)((0, run_records_1.mainCheckoutOf)(ctx.projectRoot)).find((r) => r.run_id === mode.id);
112
114
  if (!rec || rec.scope === undefined)
113
115
  return null; // an unscoped run
@@ -45,7 +45,7 @@ exports.applyRunRefusalStop = applyRunRefusalStop;
45
45
  exports.recordRunStopBlock = recordRunStopBlock;
46
46
  exports.runState = runState;
47
47
  exports.grantGuard = grantGuard;
48
- // @implements A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781, A-SPEC-780.1, A-SPEC-774.20, A-SPEC-781.2, A-SPEC-770.12, A-SPEC-778.1, A-SPEC-779.2, A-SPEC-792.1, A-SPEC-102.10
48
+ // @implements A-SPEC-778, A-SPEC-779, A-SPEC-780, A-SPEC-781, A-SPEC-780.1, A-SPEC-774.20, A-SPEC-781.2, A-SPEC-770.12, A-SPEC-778.1, A-SPEC-779.2, A-SPEC-792.1, A-SPEC-102.10, A-SPEC-794.30
49
49
  /**
50
50
  * @implements A-SPEC-778 — a refusal loop in a run ends in a stop the orchestrator can read, not in a used-up budget.
51
51
  * Every PreToolUse refusal of a run is appended to `<main>/.ax/state/run-refusals/<run>.jsonl` (a protected path the
@@ -219,13 +219,16 @@ function applyRunRefusalStop(out, ctx) {
219
219
  const cfg = (0, config_1.loadConfig)(ctx.projectRoot).run;
220
220
  const limit = cfg.refusalRepeatLimit;
221
221
  const now = ctx.now ? ctx.now() : new Date();
222
+ // A-SPEC-102.32 — non-strict: a forged pointer counts the refusals in the worktree's own log, apart from the run's; a
223
+ // pointer that cannot be opened throws to the hook
222
224
  const file = runRefusalsFile((0, run_records_1.mainCheckoutOf)(ctx.projectRoot), mode.id ?? 'unidentified-run');
223
225
  const events = readRunRefusals(file);
224
226
  if (events === 'unreadable') {
225
- return { permissionDecision: 'deny', permissionDecisionReason: `[Holmes-Kit] this run stopped: its refusal log cannot be read (${file}) — ${END}` };
227
+ return { permissionDecision: 'deny', refusal: 'run.stopped', permissionDecisionReason: `[Holmes-Kit] this run stopped: its refusal log cannot be read (${file}) — ${END}` };
226
228
  }
227
229
  // @implements A-SPEC-780 — compared with what run start pinned; logged once, then the stop below holds.
228
230
  if (mode.id && !events.some((e) => e.event === 'install_changed')) {
231
+ // A-SPEC-102.32 — non-strict: a forged pointer finds no pin in the worktree, so a changed install is not stopped
229
232
  const pinned = pinnedInstall((0, run_records_1.mainCheckoutOf)(ctx.projectRoot), mode.id);
230
233
  const current = ctx.ownInstall ?? ownInstall();
231
234
  if (pinned && installDiffers(pinned, current)) {
@@ -236,7 +239,7 @@ function applyRunRefusalStop(out, ctx) {
236
239
  }
237
240
  const stop = stoppedBy(events, limit);
238
241
  if (stop)
239
- return { permissionDecision: 'deny', permissionDecisionReason: stopReason(stop, limit, cfg.approvalWaitMinutes) };
242
+ return { permissionDecision: 'deny', refusal: 'run.stopped', permissionDecisionReason: stopReason(stop, limit, cfg.approvalWaitMinutes) }; // A-SPEC-245.24
240
243
  // @implements A-SPEC-779 — an open wait: resolved by a decision, expired by the clock, or still waiting.
241
244
  const wait = openWait(events);
242
245
  if (wait && wait.request) {
@@ -247,11 +250,12 @@ function applyRunRefusalStop(out, ctx) {
247
250
  }
248
251
  else if (now.getTime() - Date.parse(wait.ts) > cfg.approvalWaitMinutes * 60_000) {
249
252
  append(file, { ts: now.toISOString(), event: 'approval_expired', request: wait.request });
250
- return { permissionDecision: 'deny', permissionDecisionReason: stopReason({ code: 'approval.expired', count: 1, expired: wait.request }, limit, cfg.approvalWaitMinutes) };
253
+ return { permissionDecision: 'deny', refusal: 'run.stopped', permissionDecisionReason: stopReason({ code: 'approval.expired', count: 1, expired: wait.request }, limit, cfg.approvalWaitMinutes) };
251
254
  }
252
255
  else {
253
256
  return {
254
257
  permissionDecision: 'deny',
258
+ refusal: 'run.awaiting-approval', // A-SPEC-245.24
255
259
  permissionDecisionReason: `[Holmes-Kit] this run is awaiting approval ${wait.request} (${wait.code ?? 'approval'}) since ${wait.ts} — `
256
260
  // @implements A-SPEC-792.1 — the interactive session's form (A-SPEC-779.5), never a command to type.
257
261
  + `the person decides it in the interactive session's approval form (approval_ask with id "${wait.request}", workspace ${queueRoot}); `
@@ -262,19 +266,28 @@ function applyRunRefusalStop(out, ctx) {
262
266
  if (out.permissionDecision !== 'deny')
263
267
  return out;
264
268
  const reason = out.permissionDecisionReason ?? '';
265
- const rc = (0, refusal_codes_1.refusalCode)(reason);
269
+ // @implements A-SPEC-245.24 (item 5) — the deny site's own code, so a path or name in the reason cannot pick the code
270
+ // the log and the stop count use
271
+ // A-SPEC-245.26 (4a) — a present but unset code is unclassified, as hookOutputFor writes it
272
+ const rc = (0, refusal_codes_1.refusalFor)(reason, 'refusal' in out ? (typeof out.refusal === 'string' ? out.refusal : '') : undefined);
266
273
  if (!append(file, { ts: now.toISOString(), event: 'refusal', code: rc.code, class: rc.class, tool: ctx.tool }))
267
274
  return out;
268
275
  let next = reason;
269
- const request = REQUEST_RE.exec(reason)?.[1];
276
+ let code = rc.code;
277
+ // @implements A-SPEC-245.25 (item 5a) — the request the gate filed, carried in the verdict; an approval-wait bracket
278
+ // quoted inside the reason can be the agent's own text, so it starts no wait
279
+ const request = typeof out.request === 'string' && /^req-[0-9a-f]{12}$/.test(out.request) ? out.request : undefined;
270
280
  if (request && rc.class === 'needs_hitl'
271
281
  && append(file, { ts: now.toISOString(), event: 'awaiting_approval', request, code: rc.code, queue_root: ctx.projectRoot })) {
272
282
  next += `\n[Holmes-Kit] this run now awaits approval ${request}: until the person decides it in the interactive session's approval form, every tool call of this run is refused`;
283
+ code = 'run.awaiting-approval'; // A-SPEC-245.24 (item 5) — the line the run path appended names the code
273
284
  }
274
285
  const count = events.filter((e) => e.event === 'refusal' && e.code === rc.code).length + 1;
275
- if (count >= limit)
286
+ if (count >= limit) {
276
287
  next += `\n[Holmes-Kit] this run is now stopped: refusal ${rc.code} repeated ${count} times (limit ${limit}) — ${END}`;
277
- return next === reason ? out : { ...out, permissionDecisionReason: next };
288
+ code = 'run.stopped';
289
+ }
290
+ return next === reason ? out : { ...out, permissionDecisionReason: next, refusal: code };
278
291
  }
279
292
  /**
280
293
  * @implements A-SPEC-778.1 — the Stop hook's record of a blocked turn in a run. Every block appends `stop_blocked`; the
@@ -286,6 +299,7 @@ function recordRunStopBlock(ctx, articles, yielded) {
286
299
  const mode = (0, run_mode_1.runMode)(ctx.env, ctx.projectRoot, ctx.cwd, ctx.sessionId);
287
300
  if (!mode.run)
288
301
  return null;
302
+ // A-SPEC-102.32 — non-strict: a forged pointer logs the stall in the worktree's own log; a throw is caught (no line)
289
303
  const file = runRefusalsFile((0, run_records_1.mainCheckoutOf)(ctx.projectRoot), mode.id ?? 'unidentified-run');
290
304
  const ts = (ctx.now ? ctx.now() : new Date()).toISOString();
291
305
  if (!append(file, { ts, event: 'stop_blocked', articles: [...articles] }))
@@ -332,6 +346,8 @@ function grantGuard(root, id, opts) {
332
346
  }
333
347
  if (opts.interactive)
334
348
  return null;
349
+ // A-SPEC-102.32 — non-strict: a forged pointer reads the worktree's run logs, where no run awaits the request, so this
350
+ // guard does not refuse for a run; a pointer that cannot be opened throws to the grant
335
351
  const dir = (0, exports.runRefusalsDir)((0, run_records_1.mainCheckoutOf)(root));
336
352
  // @implements A-SPEC-779.1 — a log that cannot be read cannot say no run awaits the request: refuse, naming it.
337
353
  const unknown = (what) => `cannot tell whether a run awaits ${id}: the run logs cannot be read (${what}) — the person decides it in an interactive session's approval form`;
@@ -33,6 +33,11 @@ export declare function reviewPolicyOf(rec: unknown): {
33
33
  rounds?: number;
34
34
  strict: boolean;
35
35
  };
36
+ /**
37
+ * @implements A-SPEC-102.12 — the base every review gate of the run judges from: the task's review base declared at
38
+ * start, otherwise the run's own start HEAD; null when neither is recorded.
39
+ */
40
+ export declare function reviewBaseOf(rec: unknown): string | null;
36
41
  export declare function transitionRun(main: string, runId: string, to: string, opts: {
37
42
  key: string;
38
43
  why?: string;