@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
@@ -27,7 +27,7 @@ export declare const REFRESH_SUPERSEDE_POLL_MS = 15000;
27
27
  export declare function lowerOwnPriority(setPriority?: (priority: number) => void): boolean;
28
28
  /**
29
29
  * @implements A-SPEC-719.2 — a superseded worker ends within one poll instead of finishing its phase. Measured
30
- * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
30
+ * 2026-10-15: nine superseded consumer-workspace workers kept embedding for 2–4 h because the lease was asked only between phases.
31
31
  */
32
32
  export declare function armSupersedeWatch(root: string, generation: string, opts: {
33
33
  intervalMs: number;
@@ -129,7 +129,7 @@ function lowerOwnPriority(setPriority = (p) => os.setPriority(p)) {
129
129
  }
130
130
  /**
131
131
  * @implements A-SPEC-719.2 — a superseded worker ends within one poll instead of finishing its phase. Measured
132
- * 2026-10-15: nine superseded jarvis workers kept embedding for 2–4 h because the lease was asked only between phases.
132
+ * 2026-10-15: nine superseded consumer-workspace workers kept embedding for 2–4 h because the lease was asked only between phases.
133
133
  */
134
134
  function armSupersedeWatch(root, generation, opts) {
135
135
  // @implements A-SPEC-719.4 — by default only a readable newer lease or a removed workspace ends the worker:
@@ -2,6 +2,14 @@ import { PendingRequest } from '../governance/approval-queue';
2
2
  /** @implements A-SPEC-769.11 — the stage line prints from 9 s: the 18–29 s range of the 2026-10-15 incident stays visible. */
3
3
  export declare const STOP_TIMING_REPORT_MS = 9000;
4
4
  export declare const STOP_NOTICES: Set<string>;
5
+ /**
6
+ * @implements A-SPEC-734 (round 17) — the changed paths of THIS project, relative to its root, as git names them
7
+ * (`-z`: no quoting, so a name holding `"`, ` -> `, a newline or — with quotepath on — a non-ASCII character is read
8
+ * as itself; each was read as another path and skipped). Limited to the project (`-- .`) and made relative to it:
9
+ * porcelain paths are from the REPOSITORY root, and a monorepo package's ART-1/5/8 returned nothing while a root
10
+ * `src/a.ts` change was read from the package's own file (measured). A rename or copy names its destination.
11
+ */
12
+ export declare function workTreePaths(root: string): string[] | null;
5
13
  import { Spec } from '../spec/spec-parser';
6
14
  import type { TestOutcome } from '../review/test-runner';
7
15
  import { type KnownDefectJudgement } from '../rtm/known-defects';
@@ -48,6 +56,11 @@ export interface StopEvidence {
48
56
  launcher?: string;
49
57
  /** A-SPEC id -> number of real test cases (`it(`/`test(`) found in test files anchored to it. */
50
58
  testCasesByAspec?: Record<string, number>;
59
+ /** @implements A-SPEC-750.2 — A-SPEC id -> the anchored files that counted zero, and why (ART-4's detail). */
60
+ zeroCountCauses?: Record<string, Array<{
61
+ file: string;
62
+ reason: string;
63
+ }>>;
51
64
  /**
52
65
  * @implements A-SPEC-660
53
66
  * `@known-defect` markers found in the workspace's test files, judged against the clock by the
@@ -150,6 +163,16 @@ export interface StopEvidence {
150
163
  * catches it already existed inside `rechainLedger` and ran from the CLI only.
151
164
  */
152
165
  rolledBackLedgers?: string[];
166
+ /**
167
+ * @implements A-SPEC-792.13 — spec-store changes in the index or in new commits that no granted staging act recorded
168
+ * (spec-seam.ts): staging judged by its result, whatever form the shell act took.
169
+ */
170
+ unexplainedSpecChanges?: Array<{
171
+ where: 'index' | 'commit' | 'scan';
172
+ path?: string;
173
+ commit?: string;
174
+ detail?: string;
175
+ }>;
153
176
  /**
154
177
  * @implements A-SPEC-534.4
155
178
  * ART-8 RED-first evidence. `changedAspecs` are the A-SPECs whose source is dirty this turn;
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.MAX_CONSECUTIVE_BLOCKS = exports.STOP_NOTICES = exports.STOP_TIMING_REPORT_MS = void 0;
37
+ exports.workTreePaths = workTreePaths;
37
38
  exports.collectKnownDefects = collectKnownDefects;
38
39
  exports.collectSemanticCoverage = collectSemanticCoverage;
39
40
  exports.collectAnalysisCurrency = collectAnalysisCurrency;
@@ -65,7 +66,7 @@ exports.collectForbiddenEdgeJudgement = collectForbiddenEdgeJudgement;
65
66
  exports.stopSharedScan = stopSharedScan;
66
67
  exports.scanCodeCycles = scanCodeCycles;
67
68
  exports.writeGuardCount = writeGuardCount;
68
- // @implements A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7, A-SPEC-774.21, A-SPEC-778.1, A-SPEC-476.1, A-SPEC-792.1, A-SPEC-102.10
69
+ // @implements A-SPEC-734, A-SPEC-772.1, A-SPEC-770.3, A-SPEC-770.7, A-SPEC-774.21, A-SPEC-778.1, A-SPEC-476.1, A-SPEC-792.1, A-SPEC-102.10, A-SPEC-102.12, A-SPEC-222.10, A-SPEC-222.12, A-SPEC-222.13
69
70
  // @implements A-SPEC-769.9, A-SPEC-769.10, A-SPEC-769.11
70
71
  const fs = __importStar(require("node:fs"));
71
72
  // @implements A-SPEC-549.3 — evaluateStop's messages are English here; the Hangul-absence guard
@@ -134,7 +135,8 @@ function workTreePaths(root) {
134
135
  // whole-repository status of a 200k-file monorepo cost 20–25× the package's (measured); `underGitPrefix` still folds.
135
136
  const limit = prefix !== '' && /^[\x20-\x7e]+$/.test(prefix) ? ['--', `:(top,icase,literal)${prefix}`] : [];
136
137
  const raw = (0, node_child_process_1.execFileSync)('git', ['status', '--porcelain', '-z', '-uall', '--ignore-submodules=all', ...limit], { maxBuffer: bounded_io_1.GIT_MAX_BUFFER,
137
- cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: (0, root_1.cleanSubprocessEnv)(), timeout: bounded_io_1.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
138
+ // @implements A-SPEC-792.36 — the shared git environment: no fsmonitor hook or other switchable program runs
139
+ cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], env: (0, bounded_io_1.gitEnv)((0, root_1.cleanSubprocessEnv)()), timeout: bounded_io_1.GIT_TIMEOUT_MS, killSignal: 'SIGKILL',
138
140
  });
139
141
  out = [];
140
142
  const entries = raw.split('\0');
@@ -457,19 +459,22 @@ function runReviewGate(root, env, cwd, sessionId) {
457
459
  if (!mode.id)
458
460
  return cannot('the run has no id');
459
461
  const { listRuns, mainCheckoutOf } = require('../project/run-records');
462
+ // A-SPEC-102.32 — non-strict: a forged pointer finds no run record and an unreadable one throws; both block, named
460
463
  const rec = listRuns(mainCheckoutOf(root)).find((r) => r.run_id === mode.id);
461
464
  if (!rec)
462
465
  return cannot(`no run record for ${mode.id}`);
463
- if (typeof rec.base !== 'string' || rec.base === '')
466
+ // @implements A-SPEC-102.12 — from the task's review base when the run declared one.
467
+ const { reviewBaseOf, reviewPolicyOf } = require('../guardrail/run-stages');
468
+ const reviewBase = reviewBaseOf(rec);
469
+ if (reviewBase === null)
464
470
  return cannot('run record carries no base');
465
471
  const { gateRange, resolveRange } = require('../review/verdicts');
466
- const range = resolveRange(rec.worktree, rec.base, 'HEAD');
472
+ const range = resolveRange(rec.worktree, reviewBase, 'HEAD');
467
473
  if ('error' in range)
468
- return cannot(`the range ${rec.base}..HEAD does not resolve (${range.error})`, rec.base);
474
+ return cannot(`the range ${reviewBase}..HEAD does not resolve (${range.error})`, reviewBase);
469
475
  if (range.head === range.base)
470
476
  return undefined;
471
477
  // @implements A-SPEC-102.10 — a strict run is judged strictly at Stop too.
472
- const { reviewPolicyOf } = require('../guardrail/run-stages');
473
478
  const g = gateRange(rec.worktree, range.base, range.head, { strict: reviewPolicyOf(rec).strict });
474
479
  return g.ok ? undefined : { base: range.base, head: range.head, reasons: g.reasons };
475
480
  }
@@ -665,27 +670,24 @@ function unrecordedApprovals(root) {
665
670
  // a wave of false accusations.
666
671
  const recorded = new Set();
667
672
  const dir = path.join(root, '.ax', 'ledger');
668
- let files;
673
+ if (!fs.existsSync(dir))
674
+ return undefined;
675
+ // @implements A-SPEC-222.12 — N3: the approving acts come from trusted spec-approved rows only (a chainless line in a
676
+ // `junk.jsonl` hid a hand-approved spec); a row that names the id anywhere still records it, as before, so approvals
677
+ // named inside another approval's row (78 legacy ones here) stay recorded
678
+ let rows;
669
679
  try {
670
- files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
680
+ const { TrustedLedgerStore } = require('../governance/recorded-pairs');
681
+ rows = new TrustedLedgerStore(dir).loadAll();
671
682
  }
672
683
  catch {
673
684
  return undefined;
674
685
  }
675
- for (const f of files) {
676
- let text;
677
- try {
678
- text = fs.readFileSync(path.join(dir, f), 'utf8');
679
- }
680
- catch {
686
+ for (const e of rows) {
687
+ if (e.kind !== 'spec-approved')
681
688
  continue;
682
- }
683
- for (const line of text.split('\n')) {
684
- if (!line.includes('"spec-approved"'))
685
- continue;
686
- for (const m of line.matchAll(/\b(?:REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC)-[0-9.]+/g))
687
- recorded.add(m[0]);
688
- }
689
+ for (const m of JSON.stringify(e).matchAll(/\b(?:REQ|H-SPEC|A-SPEC|C-SPEC|T-SPEC)-[0-9.]+/g))
690
+ recorded.add(m[0]);
689
691
  }
690
692
  return approvedIds.filter((id) => !recorded.has(id));
691
693
  }
@@ -721,15 +723,23 @@ function rolledBackLedgers(root) {
721
723
  .filter((e) => e !== null);
722
724
  const { mainlineIsPrefix } = require('../governance/ledger-rechain');
723
725
  const out = [];
726
+ // @implements A-SPEC-222.12 (M1) — every tracked chain's HEAD blob in one read, shared with the trusted-events port
727
+ // (one git child per commit, not one per replica); a file HEAD does not hold is new, not rolled back
728
+ const { committedLedgerTexts } = require('../governance/recorded-pairs');
729
+ let heads;
730
+ // @implements A-SPEC-222.13 — a HEAD that could not be read is not "nothing committed": every tracked chain is
731
+ // reported (fail-closed), never skipped
732
+ try {
733
+ heads = committedLedgerTexts(root, tracked);
734
+ }
735
+ catch {
736
+ exports.STOP_NOTICES.add('the ledger rollback check (ART-2) could not read HEAD — every tracked chain is reported until it can');
737
+ return tracked;
738
+ }
724
739
  for (const rel of tracked) {
725
- let committed;
726
- // Round 17: `HEAD:./` — `ls-files` names paths from the project, `HEAD:` from the repository root (measured).
727
- try {
728
- committed = git(['show', `HEAD:./${rel}`]);
729
- }
730
- catch {
740
+ const committed = heads.get(rel);
741
+ if (committed === null || committed === undefined)
731
742
  continue;
732
- } // no HEAD, or newly added
733
743
  let working;
734
744
  try {
735
745
  working = readRegularText(path.join(root, rel));
@@ -820,7 +830,7 @@ function evaluateStop(specs, evidence) {
820
830
  // @implements A-SPEC-534.4 — ART-8 evidence rides through to the constitution, which emits a
821
831
  // BLOCKING ART-8 violation only in `strict` mode. `track`/`off` produce none here.
822
832
  const violations = (0, constitution_1.verifyConstitution)({
823
- specs, testCasesByAspec: evidence?.testCasesByAspec, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
833
+ specs, testCasesByAspec: evidence?.testCasesByAspec, zeroCountCauses: evidence?.zeroCountCauses, executedByAspec: evidence?.executedByAspec, findings: evidence?.findings,
824
834
  redFirstMode: evidence?.redFirstMode, changedAspecs: evidence?.changedAspecs, outcomesByAspec: evidence?.outcomesByAspec,
825
835
  cycles: evidence?.cycles,
826
836
  // @implements A-SPEC-660 — only the expired and unreadable markers are the constitution's business.
@@ -957,6 +967,23 @@ function evaluateStop(specs, evidence) {
957
967
  problems.push(`[ART-2] ${detail}`);
958
968
  structured.push({ article: 'ART-2', detail });
959
969
  }
970
+ // @implements A-SPEC-792.13 — a spec change reached the index or a commit without a person's grant
971
+ // @implements A-SPEC-222.15 (item 5) — a scan finding is its own reason, with no unstage or reset advice: the seam
972
+ // could not judge, so nothing is known to undo (the advice told a retry or a false refusal to move the branch back)
973
+ const seamAll = evidence?.unexplainedSpecChanges ?? [];
974
+ for (const u of seamAll.filter((x) => x.where === 'scan')) {
975
+ const detail = `the spec seam could not judge the spec store: ${u.detail ?? 'the scan could not finish'}`;
976
+ problems.push(`[ART-5] ${detail}`);
977
+ structured.push({ article: 'ART-5', detail });
978
+ }
979
+ const seam = seamAll.filter((x) => x.where !== 'scan');
980
+ if (seam.length > 0) {
981
+ const named = seam.slice(0, 5).map((u) => u.where === 'index' ? `staged ${u.path}` : `commit ${(u.commit ?? '').slice(0, 12)} changes ${u.path}`).join('; ');
982
+ const detail = `spec-store changes entered the index or a commit with no granted staging act (${named}${seam.length > 5 ? `; ${seam.length - 5} more` : ''}) — `
983
+ + 'unstage them (git restore --staged -- <paths>), move a branch back past the commit (git reset --soft <commit>^), or stage them again with the plain git add the gate files for approval_ask';
984
+ problems.push(`[ART-5] ${detail}`);
985
+ structured.push({ article: 'ART-5', detail });
986
+ }
960
987
  if (problems.length === 0)
961
988
  return { block: false, ...(tracked ? { tracked } : {}) };
962
989
  // @implements A-SPEC-134 — the distinct articles feed the constitution-debt state on a cap-yield.
@@ -967,7 +994,8 @@ function evaluateStop(specs, evidence) {
967
994
  .concat(evidence?.anchorStrict && (evidence?.unapprovedChangedAnchors ?? []).length > 0 ? ['ART-1'] : [])
968
995
  .concat(evidence?.reviewGate ? ['ART-7'] : [])
969
996
  .concat((evidence?.unrecordedApprovals ?? []).length > 0 ? ['ART-5'] : [])
970
- .concat((evidence?.rolledBackLedgers ?? []).length > 0 ? ['ART-2'] : []))];
997
+ .concat((evidence?.rolledBackLedgers ?? []).length > 0 ? ['ART-2'] : [])
998
+ .concat((evidence?.unexplainedSpecChanges ?? []).length > 0 ? ['ART-5'] : []))];
971
999
  return {
972
1000
  block: true,
973
1001
  articles,
@@ -1509,6 +1537,7 @@ if (require.main === module) {
1509
1537
  // fail-open); a SUCCESSFUL scan that finds nothing yields `{}` and DOES enforce — all evidence
1510
1538
  // vanishing while approved T-SPECs exist is a genuine violation state, not a hiccup.
1511
1539
  let testCasesByAspec;
1540
+ const zeroCountCauses = {};
1512
1541
  try {
1513
1542
  testCasesByAspec = {};
1514
1543
  const testRoot = stopProjectRoot();
@@ -1523,12 +1552,19 @@ if (require.main === module) {
1523
1552
  // every non-JS suite counts zero and ART-4 reports "no tests" for a project that has them.
1524
1553
  // Round 17: read from the project root, not the process directory (a Stop run from `src/` raised a false
1525
1554
  // ART-4 — measured).
1555
+ let reason = null;
1526
1556
  try {
1527
- n = (0, test_scope_1.countTestCases)(fs.readFileSync(abs, 'utf8'), file);
1557
+ const d = (0, test_scope_1.testCountDetail)(fs.readFileSync(abs, 'utf8'), file);
1558
+ n = d.cases;
1559
+ if (n === 0)
1560
+ reason = (0, test_scope_1.zeroCountReason)(d); // @implements A-SPEC-750.2, A-SPEC-750.4
1528
1561
  }
1529
1562
  catch { /* unreadable file: skip */ }
1530
1563
  for (const id of ids)
1531
1564
  testCasesByAspec[id] = (testCasesByAspec[id] ?? 0) + n;
1565
+ if (reason !== null)
1566
+ for (const id of ids)
1567
+ (zeroCountCauses[id] ??= []).push({ file, reason });
1532
1568
  }
1533
1569
  }
1534
1570
  catch {
@@ -1560,7 +1596,8 @@ if (require.main === module) {
1560
1596
  changedAspecs = changedAnchoredAspecs(stopProjectRoot());
1561
1597
  // @implements A-SPEC-645 — a renumbered A-SPEC keeps its red-first evidence: records are
1562
1598
  // grouped under the display id the entity carries now, per the ledger's rename records.
1563
- const { FileLedgerStore: LedgerForAliases } = require('../governance/ledger-store');
1599
+ // @implements A-SPEC-222.10 — H-C: trusted renames only (a forged one would lend another spec's red evidence)
1600
+ const { TrustedLedgerStore: LedgerForAliases } = require('../governance/recorded-pairs');
1564
1601
  const canonical = (0, display_id_aliases_1.displayIdCanonicalizer)(new LedgerForAliases(path.join(stopProjectRoot(), '.ax', 'ledger')).loadAll());
1565
1602
  outcomesByAspec = (0, test_outcomes_1.groupOutcomesByAspec)((0, test_outcomes_1.readOutcomes)(stopProjectRoot()), head, canonical);
1566
1603
  }
@@ -1678,6 +1715,22 @@ if (require.main === module) {
1678
1715
  const unrecorded = unrecordedApprovals(stopProjectRoot());
1679
1716
  // @implements A-SPEC-455
1680
1717
  const rolledBack = rolledBackLedgers(stopProjectRoot());
1718
+ // @implements A-SPEC-792.13 — the spec seam; a clean one advances to the tips now
1719
+ let unexplainedSpecs = [];
1720
+ try {
1721
+ const seamMod = require('../governance/spec-seam');
1722
+ unexplainedSpecs = seamMod.unexplainedSpecChanges(stopProjectRoot(), specsDir);
1723
+ // advancing is best effort: a seam left behind only re-checks what was already explained
1724
+ if (unexplainedSpecs.length === 0) {
1725
+ try {
1726
+ seamMod.advanceSpecSeam(stopProjectRoot(), specsDir);
1727
+ }
1728
+ catch { /* kept */ }
1729
+ }
1730
+ }
1731
+ catch (e) {
1732
+ unexplainedSpecs = [{ where: 'scan', detail: `the spec seam failed (${String(e.message ?? e).slice(0, 120)})` }];
1733
+ }
1681
1734
  clock.mark('ledgers');
1682
1735
  // @implements A-SPEC-564.2 — the Claude usage enrichment: numbers out of transcript_path into
1683
1736
  // the session-context ledger, once per session. Capability-declared: Codex/AGY pass no
@@ -1791,7 +1844,7 @@ if (require.main === module) {
1791
1844
  pendingRequests = require('../governance/approval-queue').readQueue(stopProjectRoot()).pending;
1792
1845
  }
1793
1846
  catch { /* text only */ }
1794
- let out = evaluateStop(specs, { pendingRequests, testCasesByAspec, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, ...(unapprovedAnchors ? { unapprovedChangedAnchors: unapprovedAnchors, anchorStrict } : {}), ...(reviewGate ? { reviewGate } : {}), unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}), ...(cycles ? { cycles } : {}) });
1847
+ let out = evaluateStop(specs, { pendingRequests, testCasesByAspec, zeroCountCauses, provenance, executedByAspec, findings, findingsUnreadable, unanchoredChangedSources: unanchored, ...(unapprovedAnchors ? { unapprovedChangedAnchors: unapprovedAnchors, anchorStrict } : {}), ...(reviewGate ? { reviewGate } : {}), unrecordedApprovals: unrecorded, rolledBackLedgers: rolledBack, unexplainedSpecChanges: unexplainedSpecs, redFirstMode, changedAspecs, outcomesByAspec, ...(knownDefects ? { knownDefects } : {}), ...(ci ? { ci } : {}), ...(dist ? { dist } : {}), ...(analysis ? { analysis } : {}), ...(semantic ? { semantic } : {}), ...(forbiddenEdges ? { forbiddenEdges } : {}), ...(cycles ? { cycles } : {}) });
1795
1848
  // @implements A-SPEC-534.4 — track mode records ART-8 findings without blocking: surface them so
1796
1849
  // the operator observes RED-first gaps before an owner promotes the posture to strict.
1797
1850
  // @implements A-SPEC-559.2 — spec-evolution trigger (observe-first, NEVER blocks): a dirty
@@ -2,7 +2,9 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.supportsFormElicitation = supportsFormElicitation;
4
4
  exports.selectApprovalAdapter = selectApprovalAdapter;
5
- const HOST_GATED_HARNESSES = new Set(['claude', 'codex', 'antigravity']);
5
+ // @implements A-SPEC-792.25 — formGate admits only an attested claude harness (A-SPEC-792.23/24), so codex and
6
+ // antigravity can never reach this choice; listing them only suggested a route that does not exist
7
+ const HOST_GATED_HARNESSES = new Set(['claude']);
6
8
  const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
7
9
  /** A generic or URL-only elicitation declaration cannot receive an MCP form. */
8
10
  function supportsFormElicitation(capabilities) {
@@ -37,6 +37,7 @@ exports.ApprovalContinuationStore = void 0;
37
37
  // @implements A-SPEC-718, A-SPEC-732
38
38
  const crypto = __importStar(require("node:crypto"));
39
39
  const approval_intent_1 = require("./approval-intent");
40
+ const human_channel_1 = require("../governance/human-channel");
40
41
  /**
41
42
  * Memory-only continuations deliberately die with the MCP session. A rejected or malformed
42
43
  * commit never burns a valid pending intent; only an exact, live host-gated commit can be consumed
@@ -82,7 +83,7 @@ class ApprovalContinuationStore {
82
83
  return undefined;
83
84
  this.committed.delete(candidate.id);
84
85
  return {
85
- actor: `host-gated:${committed.harness}`,
86
+ actor: (0, human_channel_1.humanChannelActor)('host-gated', committed.harness), // @implements A-SPEC-792.25
86
87
  token: crypto.randomUUID(),
87
88
  rationale: `host-gated in-session approval for ${committed.kind} ${committed.target}`,
88
89
  };
@@ -97,7 +98,7 @@ class ApprovalContinuationStore {
97
98
  continue;
98
99
  this.committed.delete(intent.id);
99
100
  return {
100
- actor: `host-gated:${intent.harness}`,
101
+ actor: (0, human_channel_1.humanChannelActor)('host-gated', intent.harness), // @implements A-SPEC-792.25
101
102
  token: crypto.randomUUID(),
102
103
  rationale: `host-gated in-session approval for ${intent.kind} ${intent.target}`,
103
104
  };
@@ -1,7 +1,8 @@
1
1
  import { ApprovalPresentationResult } from './approval-intent';
2
+ import { HumanChannelActor } from '../governance/human-channel';
2
3
  export type ApprovalPolicyDecision = {
3
4
  kind: 'approved';
4
- actor: string;
5
+ actor: HumanChannelActor;
5
6
  reason?: string;
6
7
  } | {
7
8
  kind: 'hold';
@@ -1,6 +1,7 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.resolveApprovalPresentation = resolveApprovalPresentation;
4
+ const human_channel_1 = require("../governance/human-channel");
4
5
  /**
5
6
  * The sole response transition table; timeout is never a synonym for cancel or deny.
6
7
  * A-SPEC-718.1: it is not a synonym for approve either — an unanswered prompt is held in every mode.
@@ -8,7 +9,8 @@ exports.resolveApprovalPresentation = resolveApprovalPresentation;
8
9
  function resolveApprovalPresentation(result, options) {
9
10
  const harness = options.harness.trim() || 'unknown';
10
11
  switch (result.kind) {
11
- case 'approve': return { kind: 'approved', actor: `elicitation:${harness}`, ...(result.reason ? { reason: result.reason } : {}) };
12
+ // @implements A-SPEC-792.25 — minted in one place, from the harness the caller attested
13
+ case 'approve': return { kind: 'approved', actor: (0, human_channel_1.humanChannelActor)('elicitation', harness), ...(result.reason ? { reason: result.reason } : {}) };
12
14
  case 'timeout': return { kind: 'hold', reason: 'approval prompt timed out' };
13
15
  case 'deny': return { kind: 'hold', reason: result.reason ? `denied: ${result.reason}` : 'denied' };
14
16
  case 'question': return { kind: 'hold', reason: `question: ${result.reason}` };
@@ -107,7 +107,7 @@ export declare function createAdoptionHandlers(context: AdoptionContext): {
107
107
  reason: string;
108
108
  findings?: unknown[];
109
109
  }[];
110
- reason?: undefined;
110
+ readonly reason?: undefined;
111
111
  availableClusters?: undefined;
112
112
  }>;
113
113
  /**
@@ -6,7 +6,10 @@ export interface ApprovalAskContext {
6
6
  attestation: () => {
7
7
  attested: boolean;
8
8
  reason?: string;
9
+ harness?: string;
9
10
  };
11
+ /** @implements A-SPEC-792.22 — the one form gate (makeRawHandlers): a refusal reason, or null when a form may be shown. */
12
+ formGate: () => string | null;
10
13
  env: () => NodeJS.ProcessEnv;
11
14
  /** @implements A-SPEC-779.7 — this server's instance id, the requester key approval_withdraw checks. */
12
15
  serverInstance?: () => string | undefined;
@@ -2,7 +2,7 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.FORM_WAITS_FOR_PERSON = void 0;
4
4
  exports.createApprovalAskHandlers = createApprovalAskHandlers;
5
- // @implements A-SPEC-718.4, A-SPEC-792.1, A-SPEC-779.7
5
+ // @implements A-SPEC-718.4, A-SPEC-792.1, A-SPEC-779.7, A-SPEC-245.9, A-SPEC-794.31, A-SPEC-794.33,A-SPEC-794.32
6
6
  /**
7
7
  * approval_ask — the person decides a pending request in the session's approval form, so no approval needs a typed
8
8
  * command (owner audit 2026-10-20). Since A-SPEC-779.4 neither the agent's shell nor the session's `!` can run
@@ -15,11 +15,12 @@ exports.createApprovalAskHandlers = createApprovalAskHandlers;
15
15
  const elicit_approval_1 = require("../elicit-approval");
16
16
  const approval_queue_1 = require("../../governance/approval-queue");
17
17
  const approve_1 = require("../../cli/approve");
18
- const screen_safe_1 = require("../../cli/screen-safe");
18
+ const screen_text_1 = require("../../project/screen-text"); // A-SPEC-794.5: from the project layer, as governance does
19
+ const human_channel_1 = require("../../governance/human-channel");
19
20
  /** Clients whose form waits for the person in every mode measured (claude-code: forms expired unanswered, 2026-10-19). */
20
21
  exports.FORM_WAITS_FOR_PERSON = new Set(['claude-code']);
21
22
  /** The one line the form shows for a request's field: the screen-safe flattening the approval screens use. */
22
- const oneLine = (s, max) => (0, screen_safe_1.flattenField)(s, max);
23
+ const oneLine = (s, max) => (0, screen_text_1.flattenField)(s, max);
23
24
  /** interpretElicitResult's reasons: a client's automatic decline is not a person's denial, and a question holds. */
24
25
  const AUTOMATIC_DECLINE = 'the session client declined the approval form';
25
26
  const QUESTION = '질문: ';
@@ -40,8 +41,11 @@ function createApprovalAskHandlers(context) {
40
41
  return refuse('a run\'s own server does not ask; the session that started the run asks the person');
41
42
  }
42
43
  const request = (0, approval_queue_1.grantableRequests)(root).find((p) => p.id === id);
44
+ // @implements A-SPEC-794.31, A-SPEC-794.32 — when no request is found, a development-build one is named in words,
45
+ // and no form is shown; a decidable request is never refused for it (the answer of a lookup that failed)
46
+ // A-SPEC-794.33 — on the exact id only: approval_ask names a request by its whole id (B-2)
43
47
  if (!request)
44
- return { ok: false, id, reason: `no pending request ${oneLine(id, 40)} in the approval inbox or this machine's refusal log` };
48
+ return { ok: false, id, reason: (0, approval_queue_1.devFiledRefusal)((0, approval_queue_1.readQueue)(root), id, true) ?? `no pending request ${oneLine(id, 40)} in the approval inbox or this machine's refusal log` };
45
49
  const client = context.clientName();
46
50
  const attestation = context.attestation();
47
51
  if ((0, elicit_approval_1.elicitationDisabled)(context.env()))
@@ -50,6 +54,10 @@ function createApprovalAskHandlers(context) {
50
54
  return refuse(`this session cannot show an approval form (${attestation.reason ?? 'not launched by a harness'})`);
51
55
  if (!context.elicit)
52
56
  return refuse('this session cannot show an approval form (the client did not advertise forms)');
57
+ // @implements A-SPEC-792.22 — every kind passes the one gate first; ELICITABLE_KINDS skipped it for any client
58
+ const gated = context.formGate();
59
+ if (gated !== null)
60
+ return refuse(gated);
53
61
  if (!elicit_approval_1.ELICITABLE_KINDS.has(request.kind) && !exports.FORM_WAITS_FOR_PERSON.has(client)) {
54
62
  return refuse(`a ${request.kind} approval in the form is not yet measured for ${client} (it might answer forms by itself)`);
55
63
  }
@@ -59,7 +67,7 @@ function createApprovalAskHandlers(context) {
59
67
  target: oneLine(request.target, 400),
60
68
  summary: `${id}${title} — ${oneLine(request.why, 120)}`,
61
69
  });
62
- const actor = `elicitation:${client}`;
70
+ const actor = (0, human_channel_1.humanChannelActor)('elicitation', attestation.harness ?? 'unattested'); // @implements A-SPEC-792.25
63
71
  const base = { ok: true, id, kind: request.kind };
64
72
  if (outcome.kind !== 'answered') {
65
73
  return { ...base, decision: 'undecided', nextAction: 'Nobody answered the form; the request is still pending. Ask again when the person is there.' };
@@ -69,7 +77,9 @@ function createApprovalAskHandlers(context) {
69
77
  const r = (0, approve_1.grantRequest)(root, id, { actor, rationale: reason ?? `approved in the session form (${client})` });
70
78
  if (!r.ok)
71
79
  return { ok: false, id, reason: r.reason };
72
- return { ...base, decision: 'granted', nextAction: 'Retry the refused act once; the grant covers it.' };
80
+ // @implements A-SPEC-245.9 (1b-6) — the result says the grant is single use and when it ends
81
+ const validity = (0, approve_1.grantValidityText)(r.expires);
82
+ return { ...base, decision: 'granted', validity, nextAction: `Retry the refused act once; the grant covers it (${validity}).` };
73
83
  }
74
84
  if (typeof reason === 'string' && reason.startsWith(AUTOMATIC_DECLINE)) {
75
85
  return { ...base, decision: 'undecided', nextAction: `The client declined the form without a person. ${fallback}` };
@@ -96,8 +106,9 @@ function createApprovalAskHandlers(context) {
96
106
  const reason = typeof a.reason === 'string' ? a.reason : '';
97
107
  const server = context.serverInstance?.();
98
108
  const r = (0, approve_1.withdrawRequest)(root, id, reason, { env: context.env(), cwd: root, ...(server ? { server } : {}) });
109
+ // A-SPEC-794.31, A-SPEC-794.32 — the answer of a withdrawal that found nothing
99
110
  if (!r.ok)
100
- return { ok: false, id, reason: r.reason };
111
+ return { ok: false, id, reason: (0, approval_queue_1.devFiledRefusal)((0, approval_queue_1.readQueue)(root), id, true) ?? r.reason }; // A-SPEC-794.33 — exact id (B-2)
101
112
  return { ok: true, id, decision: 'withdrawn', nextAction: 'The request is closed; the operator will not see it. Do not retry the act it was filed for.' };
102
113
  },
103
114
  };
@@ -69,7 +69,7 @@ export declare function createEntityIntegrationHandlers(context: {
69
69
  target?: undefined;
70
70
  executable?: undefined;
71
71
  code?: undefined;
72
- reason?: undefined;
72
+ readonly reason?: undefined;
73
73
  } | {
74
74
  ok: boolean;
75
75
  plan: import("../../spec/entity-integration-transaction").EntityIntegrationRecoveryInspection;
@@ -77,7 +77,7 @@ export declare function createEntityIntegrationHandlers(context: {
77
77
  executable: boolean;
78
78
  obligations?: undefined;
79
79
  code?: undefined;
80
- reason?: undefined;
80
+ readonly reason?: undefined;
81
81
  } | {
82
82
  blockers: string[];
83
83
  target?: string | undefined;
@@ -87,7 +87,7 @@ export declare function createEntityIntegrationHandlers(context: {
87
87
  executable: boolean;
88
88
  obligations?: undefined;
89
89
  code?: undefined;
90
- reason?: undefined;
90
+ readonly reason?: undefined;
91
91
  } | {
92
92
  ok: boolean;
93
93
  code: string;
@@ -45,6 +45,7 @@ const entity_integration_transaction_1 = require("../../spec/entity-integration-
45
45
  const approval_grants_1 = require("../../governance/approval-grants");
46
46
  const approval_queue_1 = require("../../governance/approval-queue");
47
47
  const ledger_store_1 = require("../../governance/ledger-store");
48
+ const recorded_pairs_1 = require("../../governance/recorded-pairs"); // A-SPEC-222.10 H-C: audit bindings from trusted rows
48
49
  const provenance_chain_1 = require("../../governance/provenance-chain");
49
50
  const spec_parser_1 = require("../../spec/spec-parser");
50
51
  const spec_digest_1 = require("../../spec/spec-digest");
@@ -183,11 +184,15 @@ function createEntityIntegrationHandlers(context) {
183
184
  };
184
185
  requireAuthority();
185
186
  const audit = (operation, outcome) => {
186
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
187
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
187
188
  if (!ledger.verifyAll().ok)
188
189
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Abandonment audit cannot extend an invalid ledger.');
189
190
  const ref = 'entity-operation:' + operation.operationId;
190
- if (ledger.loadAll().some(event => event.kind === 'entity-integration-abandoned' && event.inputs?.includes(ref)))
191
+ // A-SPEC-222.10 H-C: an untrusted abandonment row is a conflict, never "already recorded"
192
+ const abandoned = ledger.loadAllRaw().filter(event => event.kind === 'entity-integration-abandoned' && event.inputs?.includes(ref));
193
+ if (ledger.untrusted(abandoned).length > 0)
194
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Abandonment audit record is not a trusted ledger row.' + ledger.untrustedReason(abandoned)); // A-SPEC-222.12 L1
195
+ if (abandoned.length > 0)
191
196
  return;
192
197
  ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-integration-abandoned', summary: 'Abandoned Git entity integration ' + operation.operationId,
193
198
  inputs: [ref, (0, entity_integration_transaction_1.entityIntegrationTarget)(operation), 'workspace:' + operation.workspaceId, 'store:' + operation.storeId, recovery.journalVersion, target,
@@ -215,10 +220,11 @@ function createEntityIntegrationHandlers(context) {
215
220
  env = undefined;
216
221
  }
217
222
  const grants = new Set(), authorities = new Set(), usedGrantRefs = new Set();
223
+ const spentHere = []; // A-SPEC-245.15 (item 2): the grants this act spent still authorize its later steps
218
224
  const grantRef = (approval) => 'grant-use:' + (0, entity_transaction_1.entityContentVersion)(JSON.stringify({ actor: approval.actor, token: approval.token, nonce: approval.nonce, scope: approval.scope, expires: approval.expires }));
219
225
  const requireAuthority = (specId) => {
220
226
  const action = { kind: specId ? 'spec-approve' : 'config-write', target: specId ?? target };
221
- const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString());
227
+ const resolved = (0, approval_grants_1.resolveApproval)(bound.root, env, action, new Date().toISOString(), spentHere);
222
228
  if (!resolved)
223
229
  throw new entity_store_1.EntityStoreError(specId ? 'spec-approval-required' : 'approval-required', 'Current authority is required for this integration.' + (0, approval_queue_1.queueHint)(bound.root, { ...action, why: 'Integrate the exact Git inputs while preserving entity identity and official seal transitions.' }));
224
230
  if (resolved.source === 'grant' && resolved.approval.nonce)
@@ -234,7 +240,11 @@ function createEntityIntegrationHandlers(context) {
234
240
  if (!ledger.verifyAll().ok)
235
241
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration cannot rely on an invalid ledger.');
236
242
  const binding = bindingFor(operation), refs = new Set();
237
- for (const event of ledger.loadAll().filter(event => event.kind === 'entity-integration-grant-used' && event.inputs?.includes(binding[0]))) {
243
+ // A-SPEC-222.10 H-C: a forged prior use would leave a real grant unspent, so an untrusted usage row is a conflict
244
+ const rows = ledger.loadAllRaw().filter(event => event.kind === 'entity-integration-grant-used' && event.inputs?.includes(binding[0]));
245
+ if (ledger.untrusted(rows).length > 0)
246
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Grant usage record is not a trusted ledger row.' + ledger.untrustedReason(rows)); // A-SPEC-222.12 L1
247
+ for (const event of rows) {
238
248
  const usages = (event.inputs ?? []).filter(ref => ref.startsWith('grant-use:'));
239
249
  if (binding.some(ref => !event.inputs?.includes(ref)) || usages.length === 0 || usages.some(ref => !/^grant-use:sha256:[0-9a-f]{64}$/.test(ref) || refs.has(ref)))
240
250
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration grant usage has conflicting bindings.');
@@ -244,21 +254,28 @@ function createEntityIntegrationHandlers(context) {
244
254
  return refs;
245
255
  };
246
256
  const recordGrantUse = (operation) => {
247
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
257
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
248
258
  const prior = priorGrantUses(ledger, operation), additional = [...usedGrantRefs].filter(ref => !prior.has(ref));
249
259
  for (const ref of prior)
250
260
  usedGrantRefs.add(ref);
251
261
  if (!additional.length)
252
262
  return;
263
+ // @implements A-SPEC-245.9 (1b-1) — the grants are spent once across replicas in the transaction's
264
+ // beforePublish, the op id in rationale; a recovery finds the reservation below and does not spend again
265
+ const spending = (0, approval_grants_1.readGrants)(bound.root).grants.filter(g => additional.includes(grantRef(g)));
266
+ (0, approval_grants_1.spendGrantApprovals)(bound.root, spending, 'entity-integration ' + operation.operationId, 'entity-operation:' + operation.operationId);
267
+ spentHere.push(...spending);
253
268
  ledger.append({ ts: new Date().toISOString(), actor: authority.approval.actor, kind: 'entity-integration-grant-used', summary: 'Recorded grant usage for integration ' + operation.operationId,
254
269
  inputs: [...bindingFor(operation), target, ...additional, ...authorities], rationale: authority.approval.rationale, authorization: (0, provenance_chain_1.authorizationRef)(authority.approval.actor, authority.approval.token) });
255
270
  };
256
271
  const audit = (operation, verifyOnly = false, renumbered = []) => {
257
- const authority = requireAuthority(), ledger = new ledger_store_1.FileLedgerStore(path.join(bound.root, '.ax/ledger'));
272
+ const authority = requireAuthority(), ledger = new recorded_pairs_1.TrustedLedgerStore(path.join(bound.root, '.ax/ledger'));
258
273
  const binding = bindingFor(operation);
259
274
  for (const ref of priorGrantUses(ledger, operation))
260
275
  usedGrantRefs.add(ref);
261
- const events = ledger.loadAll(), existing = events.filter(event => event.kind === 'entity-integrated' && event.inputs?.includes(binding[0]));
276
+ const events = ledger.loadAllRaw(), existing = events.filter(event => event.kind === 'entity-integrated' && event.inputs?.includes(binding[0]));
277
+ if (ledger.untrusted(existing).length > 0)
278
+ throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration completion audit record is not a trusted ledger row.' + ledger.untrustedReason(existing)); // A-SPEC-222.12 L1
262
279
  if (existing.length) {
263
280
  if (existing.length !== 1 || binding.some(ref => !existing[0].inputs?.includes(ref)))
264
281
  throw new entity_store_1.EntityStoreError('audit-conflict', 'Integration completion audit has conflicting bindings.');
@@ -296,11 +313,10 @@ function createEntityIntegrationHandlers(context) {
296
313
  requireAuthority();
297
314
  const result = recovery ? await (0, entity_integration_transaction_1.recoverEntityIntegration)(bound.root, recovery, requireAuthority, audit, recordGrantUse)
298
315
  : await (0, entity_integration_transaction_1.applyEntityIntegration)(bound.root, plan, requireAuthority, audit, recordGrantUse);
299
- for (const grant of (0, approval_grants_1.readGrants)(bound.root).grants)
316
+ for (const grant of (0, approval_grants_1.readGrantFiles)(bound.root).grants)
300
317
  if (grant.nonce && usedGrantRefs.has(grantRef(grant)))
301
- grants.add(grant.nonce);
302
- for (const nonce of grants)
303
- (0, approval_grants_1.consumeGrantFile)(bound.root, nonce);
318
+ grants.add(grant.nonce); // A-SPEC-245.15: spent ones too
319
+ (0, approval_grants_1.spendGrants)(bound.root, grants); // A-SPEC-245.2 — acted under the entity-store lock
304
320
  return result;
305
321
  }
306
322
  if (a.operation !== undefined && a.operation !== 'plan')
@@ -314,6 +330,8 @@ function createEntityIntegrationHandlers(context) {
314
330
  catch (error) {
315
331
  if (error instanceof entity_store_1.EntityStoreError)
316
332
  return { ok: false, code: error.code, reason: error.message };
333
+ if (error instanceof approval_grants_1.GrantSpendRefusal)
334
+ return { ok: false, code: 'grant-spend-refused', reason: 'Nothing was integrated: ' + error.message };
317
335
  throw error;
318
336
  }
319
337
  },