@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
@@ -38,8 +38,9 @@ exports.applyStageGate = applyStageGate;
38
38
  exports.applyRoleStage = applyRoleStage;
39
39
  exports.currentStage = currentStage;
40
40
  exports.reviewPolicyOf = reviewPolicyOf;
41
+ exports.reviewBaseOf = reviewBaseOf;
41
42
  exports.transitionRun = transitionRun;
42
- // @implements A-SPEC-781, A-SPEC-781.1, A-SPEC-774.19, A-SPEC-781.2, A-SPEC-102.10
43
+ // @implements A-SPEC-781, A-SPEC-781.1, A-SPEC-774.19, A-SPEC-781.2, A-SPEC-102.10, A-SPEC-102.12, A-SPEC-102.14
43
44
  /**
44
45
  * @implements A-SPEC-781 — a run's SDLC stage is recorded state. Only the holder of the run's stop key (the
45
46
  * orchestrator; the session inside the run never sees it) moves it, along the edges the project's machine declares,
@@ -70,6 +71,8 @@ function applyStageGate(out, ctx) {
70
71
  const mode = (0, run_mode_1.runMode)(ctx.env, ctx.projectRoot, ctx.cwd, ctx.sessionId);
71
72
  if (!mode.run || !mode.id)
72
73
  return out;
74
+ // A-SPEC-102.32 — non-strict: a forged pointer makes the worktree its own main, where no run record is, so the stage
75
+ // gate is off for the run (the Limits); a pointer that cannot be opened throws to the hook
73
76
  const main = (0, run_records_1.mainCheckoutOf)(ctx.projectRoot);
74
77
  if (!(0, run_records_1.listRuns)(main).some((r) => r.run_id === mode.id))
75
78
  return out;
@@ -86,6 +89,7 @@ function applyStageGate(out, ctx) {
86
89
  if (action && denied.has(action)) {
87
90
  return {
88
91
  permissionDecision: 'deny',
92
+ refusal: 'stage.refused', // A-SPEC-245.24
89
93
  permissionDecisionReason: `[Holmes-Kit] the run is in stage ${stage}, where ${action} is not allowed (${rel}) — the orchestrator moves the run with holmes-kit run transition`,
90
94
  };
91
95
  }
@@ -105,6 +109,8 @@ function applyRoleStage(out, ctx) {
105
109
  const mode = (0, run_mode_1.runMode)(ctx.env, ctx.projectRoot, ctx.cwd, ctx.sessionId);
106
110
  if (!mode.run || !mode.id)
107
111
  return out;
112
+ // A-SPEC-102.32 — non-strict: as applyStageGate's, a forged pointer turns the role stage off; one that cannot be opened
113
+ // throws to the hook
108
114
  const main = (0, run_records_1.mainCheckoutOf)(ctx.projectRoot);
109
115
  if (!(0, run_records_1.listRuns)(main).some((r) => r.run_id === mode.id))
110
116
  return out;
@@ -119,7 +125,7 @@ function applyRoleStage(out, ctx) {
119
125
  const rel = path.relative(ctx.projectRoot, path.isAbsolute(t) ? t : path.resolve(base, t)).replace(/\\/g, '/');
120
126
  const issue = (0, role_policy_1.roleCheck)((0, phase_1.classifyAction)(rel, undefined, opts) ?? 'WRITE_OTHER', identity, policy, { run: true, stage });
121
127
  if (issue)
122
- return { permissionDecision: 'deny', permissionDecisionReason: issue };
128
+ return { permissionDecision: 'deny', refusal: 'role.refused', permissionDecisionReason: issue }; // A-SPEC-245.24
123
129
  }
124
130
  return out;
125
131
  }
@@ -140,6 +146,17 @@ function reviewPolicyOf(rec) {
140
146
  const rounds = typeof r?.rounds === 'number' && Number.isInteger(r.rounds) && r.rounds >= 1 && r.rounds <= 20 ? r.rounds : undefined;
141
147
  return { ...(rounds !== undefined ? { rounds } : {}), strict: r?.strict === true };
142
148
  }
149
+ /**
150
+ * @implements A-SPEC-102.12 — the base every review gate of the run judges from: the task's review base declared at
151
+ * start, otherwise the run's own start HEAD; null when neither is recorded.
152
+ */
153
+ function reviewBaseOf(rec) {
154
+ const r = rec;
155
+ const declared = r?.review?.base;
156
+ if (typeof declared === 'string' && /^[0-9a-f]{40,64}$/.test(declared))
157
+ return declared;
158
+ return typeof r?.base === 'string' && r.base !== '' ? r.base : null;
159
+ }
143
160
  function transitionRun(main, runId, to, opts) {
144
161
  const rec = (0, run_records_1.listRuns)(main).find((r) => r.run_id === runId);
145
162
  if (!rec)
@@ -156,9 +173,10 @@ function transitionRun(main, runId, to, opts) {
156
173
  return { ok: false, reason: `${from} → ${to} is not an allowed transition (from ${from}: ${(machine.transitions[from] ?? []).join(', ') || 'none'})` };
157
174
  }
158
175
  if (machine.reviewed.includes(to)) {
159
- if (typeof rec.base !== 'string' || rec.base === '')
176
+ const reviewBase = reviewBaseOf(rec);
177
+ if (reviewBase === null)
160
178
  return { ok: false, reason: `${to} needs a review of the run's range, and the run recorded no base at start` };
161
- const range = (0, verdicts_1.resolveRange)(rec.worktree, rec.base, 'HEAD');
179
+ const range = (0, verdicts_1.resolveRange)(rec.worktree, reviewBase, 'HEAD');
162
180
  if ('error' in range)
163
181
  return { ok: false, reason: range.error };
164
182
  // @implements A-SPEC-102.10 — the run's recorded policy: strict review, and a cap on failing rounds.
@@ -166,7 +184,9 @@ function transitionRun(main, runId, to, opts) {
166
184
  const g = (0, verdicts_1.gateRange)(rec.worktree, range.base, range.head, { strict: policy.strict });
167
185
  if (!g.ok) {
168
186
  const capRounds = policy.rounds ?? null;
169
- const failed = capRounds !== null ? (0, verdicts_1.failingRounds)(main, rec.base) : [];
187
+ // @implements A-SPEC-102.14 — counted over the run's own lineage, under any recorded base.
188
+ // @implements A-SPEC-102.18 — and what the run amended or rewrote away (its record carries its authorship).
189
+ const failed = capRounds !== null ? (0, verdicts_1.failingRounds)(main, range.base, range.head, rec.worktree, { ...rec, run_id: runId }) : [];
170
190
  if (capRounds !== null && failed.length >= capRounds) {
171
191
  const findings = (failed[failed.length - 1].findings ?? []).slice(0, 50).map((f) => String(f).slice(0, 300));
172
192
  (0, run_refusals_1.appendRunEvent)(main, runId, {
@@ -9,7 +9,7 @@ exports.judgeScope = judgeScope;
9
9
  /**
10
10
  * The de-amplified scope judgment — PURE (no fs, no git; the hook gathers, this decides).
11
11
  *
12
- * Field basis (2026-08-23, jarvis): one test-class addition to an ALREADY-ANCHORED file cost
12
+ * Field basis (2026-08-23, a consumer workspace): one test-class addition to an ALREADY-ANCHORED file cost
13
13
  * >=3 human interventions, because the old model re-checked Files-to-Touch on every edit of an
14
14
  * anchored file (double registration: the anchor said "this file belongs to X" and FtT had to
15
15
  * say it again), while its matcher quietly widened every FILE token to the file's whole parent
@@ -250,6 +250,15 @@ const mentionsWiringUncached = (text) => {
250
250
  if ([...(0, write_target_1.wiringFileNames)(), ...write_target_1.WIRING_DIR_NAMES].some((n) => re.test(n)))
251
251
  return true;
252
252
  }
253
+ // @implements A-SPEC-792.41 — a zsh group inside a word (`.m(c)p.json`, `.(mcp|x).json`) is a glob too; the split above
254
+ // cut the word at its parentheses, so the name never appeared whole.
255
+ for (const tok of t.split(/[\s;&<>'"`=]+/)) {
256
+ if (!/[^\s(|]\(|\)[^\s)|]/.test(tok) || tok.length > 256)
257
+ continue;
258
+ const re = (0, write_target_1.globPatternRe)(tok.split('/').pop() ?? tok, true);
259
+ if ([...(0, write_target_1.wiringFileNames)(), ...write_target_1.WIRING_DIR_NAMES].some((n) => re.test(n)))
260
+ return true;
261
+ }
253
262
  return false;
254
263
  };
255
264
  const CALL_ROLES = new Map([
@@ -382,6 +391,15 @@ function harnessWiringActOf(root, base, segmentText, fullText, env = process.env
382
391
  // A word made unknowable by `$(…)` or a variable is still refused when its last component is a
383
392
  // wiring file name (`rm "$(git rev-parse --show-toplevel)/.agents/hooks.json"`, round 4).
384
393
  const unknownByName = (w, dirs) => (w.text === '' ? null : byName(w, dirs));
394
+ // @implements A-SPEC-792.41 — a glob whose place is unknowable: its last component matched against the wiring names.
395
+ const globByName = (w) => {
396
+ const last = (0, linear_match_1.trimTrailing)(w.text, '/\\').split(/[/\\]/).pop()?.toLowerCase() ?? '';
397
+ if (last.length > 256)
398
+ return `${w.text.slice(-80)} (a glob too long to judge)`;
399
+ const re = (0, write_target_1.globPatternRe)(last, true);
400
+ const hit = [...(0, write_target_1.wiringFileNames)(), ...write_target_1.WIRING_DIR_NAMES].find((n) => re.test(n));
401
+ return hit === undefined ? null : `${w.text.length > 120 ? `…${w.text.slice(-80)}` : w.text} (a glob that can name ${hit})`;
402
+ };
385
403
  // @implements A-SPEC-728 (rule 47) — a path that passed is not judged again within one judgement of a command (a loop judges
386
404
  // its body once per word: 16 loops over 80 tar members at six directories took 10.6 s — measured), and one command judges at
387
405
  // most PATHS_JUDGED_MAX distinct paths: past that it is refused as too large to judge, so the bound never makes a pass.
@@ -413,9 +431,12 @@ function harnessWiringActOf(root, base, segmentText, fullText, env = process.env
413
431
  del: (w, recursive) => once(recursive ? 'R' : 'D', w, () => !w.known ? unknownByName(w, recursive) : w.text === '' ? null
414
432
  : w.text.length > MAX_PATH ? byName(w, recursive)
415
433
  : b !== null || absolute(w.text) ? (0, write_target_1.wiringDeletionKindOf)(root, b, w.text, env, home, recursive) : byName(w, recursive)),
416
- wr: (w) => once('W', w, () => !w.known ? (w.glob ? null : unknownByName(w, false)) : w.text === '' || w.glob ? null
417
- : w.text.length > MAX_PATH ? byName(w, false)
418
- : b !== null || absolute(w.text) ? (0, write_target_1.wiringWriteKindOf)(root, b ?? root, w.text, env, home) : byName(w, false)),
434
+ // @implements A-SPEC-792.41 — a glob target is judged as a deletion's glob is: the shell expands it onto whatever
435
+ // exists, so `tee ~/.cl*ude/settings.json` wrote the user's settings (measured in bash and zsh). It returned null.
436
+ wr: (w) => once('W', w, () => !w.known ? (w.glob ? globByName(w) : unknownByName(w, false)) : w.text === '' ? null
437
+ : w.glob ? (w.text.length <= MAX_PATH && (b !== null || absolute(w.text)) ? (0, write_target_1.wiringDeletionKindOf)(root, b, w.text, env, home, true) : globByName(w))
438
+ : w.text.length > MAX_PATH ? byName(w, false)
439
+ : b !== null || absolute(w.text) ? (0, write_target_1.wiringWriteKindOf)(root, b ?? root, w.text, env, home) : byName(w, false)),
419
440
  };
420
441
  };
421
442
  const { judgeable, del, wr } = at(base);
@@ -0,0 +1,40 @@
1
+ /**
2
+ * The text the rule reads. Data goes only when the whole command was read with certainty and nothing in it runs text;
3
+ * otherwise `whole`: no splitter can be trusted on text not read with certainty, so all of it is judged, comments and
4
+ * bodies included, with `$'…'` made plain.
5
+ */
6
+ export declare function commandText(raw: string): {
7
+ text: string;
8
+ whole: boolean;
9
+ };
10
+ /**
11
+ * A-SPEC-794.54 — `commandText` for a reader that has no bound of its own: past the length bound, or when the reader
12
+ * overflows, the whole text as written, comments and bodies included.
13
+ */
14
+ export declare function readableText(raw: string): string;
15
+ export declare const KEYWORD: RegExp;
16
+ /** True when `cwd` is the project's store or inside it, judged against the project root (never a parent's name). */
17
+ export declare function cwdInStore(cwd: string | null | undefined, root: string | null | undefined): boolean;
18
+ /**
19
+ * What the rule judges. `whole`: no path analysis ran, so every clause reaches the rule and the command need not build any
20
+ * path. A-SPEC-794.42 — what the text holds differs: not read with certainty, as written with `$'…'` made plain; past the
21
+ * length bound or after an overflow, the raw text; past the stage bound, comments and bodies are gone. A-SPEC-794.45 — past
22
+ * the nesting bound an inner program counts as building a path, so a command with nothing removed goes on with
23
+ * `whole: false`; with a comment or a body beside its `eval` the data rule comes first and it is `whole: true`.
24
+ */
25
+ export interface StoreBuilt {
26
+ text: string;
27
+ whole: boolean;
28
+ }
29
+ /**
30
+ * The text the not-a-read rule judges when a store path is built while the command runs, or null when none is: the
31
+ * pipelines such a path can reach, followed through the names that carry it. `pipelines` is the classifier's splitter,
32
+ * which keeps a pipeline whole (null when a quote is left open: the command is then one pipeline).
33
+ */
34
+ export declare function storePathBuiltJudgement(command: string, cwd: string | null | undefined, root: string | null | undefined, pipelines: (cmd: string) => string[] | null): StoreBuilt | null;
35
+ /** The text alone: what the predicate's own cases read. */
36
+ export declare const storePathBuiltText: (command: string, cwd: string | null | undefined, root: string | null | undefined, pipelines: (cmd: string) => string[] | null) => string | null;
37
+ /** The refusal: what was judged, and the next act. */
38
+ export declare const STORE_BUILT_REASON = "shell command can write a .ax governance path it builds while it runs, and is not recognisably read-only \u2014 write with literal paths (a protected .ax path asks for an approval), or read with one read command and literal paths";
39
+ /** A-SPEC-794.40 — the command need not build anything: nothing here says it does, and the way through comes first. */
40
+ export declare const STORE_WHOLE_REASON = "shell command names .ax or runs inside it, and could not be read with certainty (a construct or a here-document this gate does not read, text that may run, or a very long command), so it was judged whole and is not recognisably read-only \u2014 remove the .ax mention, or split the command into separate calls, and it is judged again; a write to a protected .ax path with literal paths asks for an approval";