@holmes-lab/holmes-kit 0.39.0 → 0.40.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (325) hide show
  1. package/CHANGELOG.md +578 -6
  2. package/README.md +120 -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 +226 -442
  65. package/dist/holmes/cli/init.js +33 -0
  66. package/dist/holmes/cli/interactive-prompt.d.ts +39 -2
  67. package/dist/holmes/cli/interactive-prompt.js +98 -16
  68. package/dist/holmes/cli/lock-recover.d.ts +5 -0
  69. package/dist/holmes/cli/lock-recover.js +126 -0
  70. package/dist/holmes/cli/mcp-processes.js +1 -1
  71. package/dist/holmes/cli/release-docs.js +1 -1
  72. package/dist/holmes/cli/run-exec.d.ts +141 -0
  73. package/dist/holmes/cli/run-exec.js +1435 -0
  74. package/dist/holmes/cli/run-provision.d.ts +3 -1
  75. package/dist/holmes/cli/run-provision.js +255 -44
  76. package/dist/holmes/cli/run-wiring.d.ts +69 -0
  77. package/dist/holmes/cli/run-wiring.js +270 -0
  78. package/dist/holmes/cli/run.d.ts +21 -0
  79. package/dist/holmes/cli/run.js +341 -92
  80. package/dist/holmes/cli/runtime-binding-approval.js +32 -19
  81. package/dist/holmes/cli/screen-safe.d.ts +3 -92
  82. package/dist/holmes/cli/screen-safe.js +18 -756
  83. package/dist/holmes/config/config.d.ts +19 -0
  84. package/dist/holmes/config/config.js +18 -3
  85. package/dist/holmes/cpg/foundation/language-matrix.js +2 -2
  86. package/dist/holmes/cpg/import-resolver.js +1 -1
  87. package/dist/holmes/governance/approval-decisions.d.ts +47 -0
  88. package/dist/holmes/governance/approval-decisions.js +29 -0
  89. package/dist/holmes/governance/approval-grants.d.ts +220 -1
  90. package/dist/holmes/governance/approval-grants.js +612 -33
  91. package/dist/holmes/governance/approval-queue.d.ts +26 -0
  92. package/dist/holmes/governance/approval-queue.js +109 -11
  93. package/dist/holmes/governance/approval-spend.d.ts +95 -0
  94. package/dist/holmes/governance/approval-spend.js +191 -0
  95. package/dist/holmes/governance/autonomous-shell.d.ts +61 -0
  96. package/dist/holmes/governance/autonomous-shell.js +332 -0
  97. package/dist/holmes/governance/autonomy.d.ts +12 -0
  98. package/dist/holmes/governance/autonomy.js +51 -15
  99. package/dist/holmes/governance/constitution.d.ts +5 -0
  100. package/dist/holmes/governance/constitution.js +32 -12
  101. package/dist/holmes/governance/full-autonomy.d.ts +10 -0
  102. package/dist/holmes/governance/full-autonomy.js +103 -7
  103. package/dist/holmes/governance/harness-catalog.d.ts +103 -0
  104. package/dist/holmes/governance/harness-catalog.js +348 -0
  105. package/dist/holmes/governance/human-channel.d.ts +38 -0
  106. package/dist/holmes/governance/human-channel.js +49 -0
  107. package/dist/holmes/governance/install-manifest.d.ts +22 -0
  108. package/dist/holmes/governance/install-manifest.js +160 -0
  109. package/dist/holmes/governance/ledger-rechain.js +2 -0
  110. package/dist/holmes/governance/ledger-store.conformance.d.ts +7 -1
  111. package/dist/holmes/governance/ledger-store.conformance.js +66 -0
  112. package/dist/holmes/governance/ledger-store.d.ts +88 -11
  113. package/dist/holmes/governance/ledger-store.js +186 -8
  114. package/dist/holmes/governance/provenance-chain.d.ts +16 -4
  115. package/dist/holmes/governance/provenance-chain.js +19 -4
  116. package/dist/holmes/governance/provenance-ledger.d.ts +6 -3
  117. package/dist/holmes/governance/provenance-ledger.js +53 -18
  118. package/dist/holmes/governance/push-gate-runner.d.ts +2 -0
  119. package/dist/holmes/governance/push-gate-runner.js +50 -9
  120. package/dist/holmes/governance/push-gate.d.ts +13 -2
  121. package/dist/holmes/governance/push-gate.js +106 -14
  122. package/dist/holmes/governance/recorded-pairs.d.ts +96 -0
  123. package/dist/holmes/governance/recorded-pairs.js +522 -0
  124. package/dist/holmes/governance/replica-id.d.ts +1 -1
  125. package/dist/holmes/governance/replica-id.js +1 -1
  126. package/dist/holmes/governance/spec-seam.d.ts +59 -0
  127. package/dist/holmes/governance/spec-seam.js +587 -0
  128. package/dist/holmes/governance/spend-kinds.d.ts +16 -0
  129. package/dist/holmes/governance/spend-kinds.js +18 -0
  130. package/dist/holmes/guardrail/advisory-line.d.ts +102 -0
  131. package/dist/holmes/guardrail/advisory-line.js +718 -0
  132. package/dist/holmes/guardrail/decision-ledger.d.ts +2 -1
  133. package/dist/holmes/guardrail/decision-ledger.js +2 -1
  134. package/dist/holmes/guardrail/impact-gate.d.ts +7 -0
  135. package/dist/holmes/guardrail/impact-gate.js +33 -6
  136. package/dist/holmes/guardrail/line-continuation.d.ts +8 -0
  137. package/dist/holmes/guardrail/line-continuation.js +39 -0
  138. package/dist/holmes/guardrail/operator-person.d.ts +28 -4
  139. package/dist/holmes/guardrail/operator-person.js +57 -11
  140. package/dist/holmes/guardrail/refusal-codes.d.ts +8 -3
  141. package/dist/holmes/guardrail/refusal-codes.js +64 -10
  142. package/dist/holmes/guardrail/risk-classifier.d.ts +15 -9
  143. package/dist/holmes/guardrail/risk-classifier.js +228 -16
  144. package/dist/holmes/guardrail/risk-gate.d.ts +2 -8
  145. package/dist/holmes/guardrail/risk-gate.js +7 -34
  146. package/dist/holmes/guardrail/risk-types.d.ts +10 -0
  147. package/dist/holmes/guardrail/run-plan-scope.js +3 -1
  148. package/dist/holmes/guardrail/run-refusals.js +24 -8
  149. package/dist/holmes/guardrail/run-stages.d.ts +5 -0
  150. package/dist/holmes/guardrail/run-stages.js +25 -5
  151. package/dist/holmes/guardrail/scope-judgment.js +1 -1
  152. package/dist/holmes/guardrail/shell-words.js +24 -3
  153. package/dist/holmes/guardrail/unresolved-write.d.ts +40 -0
  154. package/dist/holmes/guardrail/unresolved-write.js +556 -0
  155. package/dist/holmes/guardrail/write-target.d.ts +3 -0
  156. package/dist/holmes/guardrail/write-target.js +26 -5
  157. package/dist/holmes/hooks/pre-tool-use.d.ts +116 -1
  158. package/dist/holmes/hooks/pre-tool-use.js +1176 -170
  159. package/dist/holmes/hooks/rtm-refresh-child.d.ts +1 -1
  160. package/dist/holmes/hooks/rtm-refresh-child.js +1 -1
  161. package/dist/holmes/hooks/session-start.js +17 -1
  162. package/dist/holmes/hooks/stop.d.ts +23 -0
  163. package/dist/holmes/hooks/stop.js +86 -33
  164. package/dist/holmes/mcp/approval-adapters.js +3 -1
  165. package/dist/holmes/mcp/approval-commit.js +3 -2
  166. package/dist/holmes/mcp/approval-policy.d.ts +2 -1
  167. package/dist/holmes/mcp/approval-policy.js +3 -1
  168. package/dist/holmes/mcp/handlers/adoption.d.ts +1 -1
  169. package/dist/holmes/mcp/handlers/approval-ask.d.ts +3 -0
  170. package/dist/holmes/mcp/handlers/approval-ask.js +18 -7
  171. package/dist/holmes/mcp/handlers/entity-integration.d.ts +3 -3
  172. package/dist/holmes/mcp/handlers/entity-integration.js +29 -11
  173. package/dist/holmes/mcp/handlers/entity-renumber.d.ts +4 -4
  174. package/dist/holmes/mcp/handlers/entity-renumber.js +29 -11
  175. package/dist/holmes/mcp/handlers/entity-store.d.ts +2 -2
  176. package/dist/holmes/mcp/handlers/entity-store.js +133 -59
  177. package/dist/holmes/mcp/handlers/maintenance-analysis.d.ts +13 -0
  178. package/dist/holmes/mcp/handlers/maintenance-analysis.js +59 -2
  179. package/dist/holmes/mcp/handlers/operator-inspection.d.ts +9 -5
  180. package/dist/holmes/mcp/handlers/operator-inspection.js +79 -16
  181. package/dist/holmes/mcp/handlers/phase-queries.d.ts +1 -1
  182. package/dist/holmes/mcp/handlers/requirement-triage.d.ts +4 -4
  183. package/dist/holmes/mcp/handlers/review-evidence.d.ts +2 -2
  184. package/dist/holmes/mcp/handlers/review-evidence.js +35 -11
  185. package/dist/holmes/mcp/handlers/review-queries.d.ts +5 -0
  186. package/dist/holmes/mcp/handlers/review-queries.js +8 -1
  187. package/dist/holmes/mcp/handlers/review-verdict.d.ts +3 -0
  188. package/dist/holmes/mcp/handlers/review-verdict.js +10 -3
  189. package/dist/holmes/mcp/handlers/risk-assessment.d.ts +7 -2
  190. package/dist/holmes/mcp/handlers/risk-assessment.js +34 -12
  191. package/dist/holmes/mcp/handlers/runtime-binding-tool.d.ts +2 -2
  192. package/dist/holmes/mcp/handlers/slice-orchestration.d.ts +6 -1
  193. package/dist/holmes/mcp/handlers/slice-orchestration.js +14 -1
  194. package/dist/holmes/mcp/handlers/spec-approval.d.ts +15 -3
  195. package/dist/holmes/mcp/handlers/spec-approval.js +32 -5
  196. package/dist/holmes/mcp/handlers/spec-authoring.d.ts +2 -2
  197. package/dist/holmes/mcp/handlers/spec-authoring.js +19 -2
  198. package/dist/holmes/mcp/handlers/spec-lifecycle.d.ts +11 -38
  199. package/dist/holmes/mcp/handlers/spec-lifecycle.js +441 -94
  200. package/dist/holmes/mcp/handlers/spec-queries.d.ts +2 -2
  201. package/dist/holmes/mcp/handlers/taint-screening.d.ts +1 -1
  202. package/dist/holmes/mcp/handlers/taint-screening.js +2 -2
  203. package/dist/holmes/mcp/handlers/test-execution.d.ts +471 -4
  204. package/dist/holmes/mcp/handlers/test-execution.js +199 -21
  205. package/dist/holmes/mcp/handlers/workspace-queries.d.ts +2 -2
  206. package/dist/holmes/mcp/handlers.d.ts +557 -82
  207. package/dist/holmes/mcp/handlers.js +74 -23
  208. package/dist/holmes/mcp/harness-attestation.d.ts +78 -5
  209. package/dist/holmes/mcp/harness-attestation.js +325 -53
  210. package/dist/holmes/mcp/maintenance-analyze.d.ts +6 -1
  211. package/dist/holmes/mcp/maintenance-analyze.js +13 -11
  212. package/dist/holmes/mcp/maintenance-evidence.d.ts +9 -0
  213. package/dist/holmes/mcp/maintenance-evidence.js +35 -3
  214. package/dist/holmes/mcp/requirement-triage-evidence.js +22 -13
  215. package/dist/holmes/mcp/server-staleness.js +1 -1
  216. package/dist/holmes/mcp/server.js +9 -8
  217. package/dist/holmes/mcp/spec-id-guard.js +1 -1
  218. package/dist/holmes/mcp/tool-schemas.d.ts +13 -0
  219. package/dist/holmes/mcp/tool-schemas.js +42 -9
  220. package/dist/holmes/project/act-root.d.ts +19 -0
  221. package/dist/holmes/project/act-root.js +100 -0
  222. package/dist/holmes/project/baseline.d.ts +15 -2
  223. package/dist/holmes/project/baseline.js +14 -8
  224. package/dist/holmes/project/bounded-group.d.ts +47 -0
  225. package/dist/holmes/project/bounded-group.js +140 -0
  226. package/dist/holmes/project/bounded-io.d.ts +51 -2
  227. package/dist/holmes/project/bounded-io.js +140 -6
  228. package/dist/holmes/project/change-source.d.ts +4 -0
  229. package/dist/holmes/project/change-source.js +14 -6
  230. package/dist/holmes/project/instance-id.d.ts +10 -0
  231. package/dist/holmes/project/instance-id.js +233 -0
  232. package/dist/holmes/project/machine-identity.d.ts +25 -0
  233. package/dist/holmes/project/machine-identity.js +133 -0
  234. package/dist/holmes/project/owned-lock.d.ts +84 -0
  235. package/dist/holmes/project/owned-lock.js +263 -0
  236. package/dist/holmes/project/plain-lock-fs.d.ts +2 -0
  237. package/dist/holmes/project/plain-lock-fs.js +126 -0
  238. package/dist/holmes/project/request-lock.d.ts +85 -0
  239. package/dist/holmes/project/request-lock.js +459 -0
  240. package/dist/holmes/project/root.d.ts +12 -4
  241. package/dist/holmes/project/root.js +29 -8
  242. package/dist/holmes/project/run-records.d.ts +19 -0
  243. package/dist/holmes/project/run-records.js +94 -12
  244. package/dist/holmes/project/screen-text.d.ts +94 -0
  245. package/dist/holmes/project/screen-text.js +763 -0
  246. package/dist/holmes/project/spend-lock.d.ts +82 -0
  247. package/dist/holmes/project/spend-lock.js +413 -0
  248. package/dist/holmes/refresh/freshness-coordinator.d.ts +1 -1
  249. package/dist/holmes/refresh/freshness-coordinator.js +1 -1
  250. package/dist/holmes/review/condition-hunk-replay.js +4 -2
  251. package/dist/holmes/review/confidence-calibration.d.ts +1 -1
  252. package/dist/holmes/review/confidence-calibration.js +1 -1
  253. package/dist/holmes/review/content-verify.js +1 -1
  254. package/dist/holmes/review/evidence-mode.d.ts +21 -0
  255. package/dist/holmes/review/evidence-mode.js +33 -0
  256. package/dist/holmes/review/head-worktree.d.ts +55 -0
  257. package/dist/holmes/review/head-worktree.js +329 -0
  258. package/dist/holmes/review/hop-ablation.d.ts +4 -4
  259. package/dist/holmes/review/hop-ablation.js +5 -5
  260. package/dist/holmes/review/mrp.js +13 -3
  261. package/dist/holmes/review/point-in-time-replay.js +12 -3
  262. package/dist/holmes/review/rank-diagnosis.d.ts +2 -2
  263. package/dist/holmes/review/rank-diagnosis.js +1 -1
  264. package/dist/holmes/review/replay-corpus.d.ts +10 -4
  265. package/dist/holmes/review/replay-corpus.js +25 -9
  266. package/dist/holmes/review/requirement-triage.js +2 -2
  267. package/dist/holmes/review/run-provenance.d.ts +45 -0
  268. package/dist/holmes/review/run-provenance.js +314 -0
  269. package/dist/holmes/review/semantic-arm.d.ts +3 -3
  270. package/dist/holmes/review/semantic-arm.js +3 -3
  271. package/dist/holmes/review/test-evidence.d.ts +174 -0
  272. package/dist/holmes/review/test-evidence.js +330 -2
  273. package/dist/holmes/review/test-outcomes.js +3 -1
  274. package/dist/holmes/review/test-reports.d.ts +94 -0
  275. package/dist/holmes/review/test-reports.js +382 -0
  276. package/dist/holmes/review/test-runner.d.ts +180 -58
  277. package/dist/holmes/review/test-runner.js +560 -324
  278. package/dist/holmes/review/test-selection-breadth.js +2 -2
  279. package/dist/holmes/review/test-units.d.ts +159 -0
  280. package/dist/holmes/review/test-units.js +814 -0
  281. package/dist/holmes/review/verdicts.d.ts +105 -8
  282. package/dist/holmes/review/verdicts.js +640 -36
  283. package/dist/holmes/rtm/anchor-census.d.ts +9 -0
  284. package/dist/holmes/rtm/anchor-census.js +151 -0
  285. package/dist/holmes/rtm/anchor-ids.d.ts +25 -1
  286. package/dist/holmes/rtm/anchor-ids.js +45 -2
  287. package/dist/holmes/rtm/comment-ranges.d.ts +2 -0
  288. package/dist/holmes/rtm/comment-ranges.js +104 -0
  289. package/dist/holmes/rtm/counted-tests.d.ts +1 -0
  290. package/dist/holmes/rtm/counted-tests.js +63 -0
  291. package/dist/holmes/rtm/impact-advisory.d.ts +1 -1
  292. package/dist/holmes/rtm/known-defects.js +1 -1
  293. package/dist/holmes/rtm/localize.js +1 -1
  294. package/dist/holmes/rtm/taint-benchmark.d.ts +1 -1
  295. package/dist/holmes/rtm/taint-vocabulary.d.ts +1 -1
  296. package/dist/holmes/rtm/test-scope.d.ts +31 -0
  297. package/dist/holmes/rtm/test-scope.js +166 -5
  298. package/dist/holmes/rtm/trace-gaps.js +1 -1
  299. package/dist/holmes/runtime/dispatch.d.ts +10 -0
  300. package/dist/holmes/runtime/dispatch.js +12 -1
  301. package/dist/holmes/semantic/cloud-usage.d.ts +1 -1
  302. package/dist/holmes/semantic/cloud-usage.js +1 -1
  303. package/dist/holmes/semantic/unreadable-paths.d.ts +1 -1
  304. package/dist/holmes/semantic/unreadable-paths.js +1 -1
  305. package/dist/holmes/spec/approval-blockers.js +1 -1
  306. package/dist/holmes/spec/entity-store.d.ts +6 -1
  307. package/dist/holmes/spec/entity-store.js +16 -2
  308. package/dist/holmes/spec/entity-transaction.d.ts +7 -2
  309. package/dist/holmes/spec/entity-transaction.js +87 -170
  310. package/dist/holmes/spec/spec-store.d.ts +12 -6
  311. package/dist/holmes/spec/spec-store.js +4 -2
  312. package/dist/holmes/spec/spec-types.js +1 -1
  313. package/dist/holmes/spec/succession-guard.d.ts +56 -0
  314. package/dist/holmes/spec/succession-guard.js +187 -0
  315. package/dist/holmes/spec/succession.d.ts +70 -0
  316. package/dist/holmes/spec/succession.js +171 -0
  317. package/dist/holmes/spec/transition-policy.d.ts +2 -2
  318. package/docs/install-guide.md +9 -3
  319. package/docs/language-support.md +78 -0
  320. package/package.json +4 -3
  321. package/playbooks/author-slice/PLAYBOOK.md +1 -1
  322. package/playbooks/promote-slice/PLAYBOOK.md +5 -1
  323. package/playbooks/publish/PLAYBOOK.md +47 -34
  324. package/dist/holmes/review/manual-baseline.d.ts +0 -209
  325. package/dist/holmes/review/manual-baseline.js +0 -2847
@@ -0,0 +1,70 @@
1
+ /**
2
+ * Whether Y may stand in for a retired X — the one judgment the code gate's anchor move, spec_retire's after-the-fact
3
+ * superseded_by and its autonomous retirement share (AU1-b.1, review of 2026-10-25 15:45, F3).
4
+ */
5
+ import { Spec } from './spec-parser';
6
+ /** Y sealed now: approved, and its digest is its approved_digest. */
7
+ export declare function sealHolds(y: Spec): boolean;
8
+ /**
9
+ * @implements A-SPEC-222.9 — H3: a spec as it was sealed, whatever its status now (status and superseded_by are not in
10
+ * the digest), so a retired X is judged by the body that was approved; an edit after the seal, or no seal, is no basis.
11
+ */
12
+ export declare function sealedBody(x: Spec, approved?: ApprovedSeal): boolean;
13
+ /** A-SPEC-222.10 — whether a trusted `spec-approved` event recorded this `[id, digest]`. */
14
+ export type ApprovedSeal = (id: string, digest: string) => boolean;
15
+ /**
16
+ * Y belongs to X's line: a shared parent, or Y names X in depends_on — or names X in `replaces` while the two share a
17
+ * REQ ancestor (A-SPEC-222.8 N6: `replaces` alone is a declaration anyone can write).
18
+ */
19
+ export declare function sharesLineage(x: Spec, y: Spec, specs?: Spec[]): boolean;
20
+ /** @implements A-SPEC-222.8 — N2: a successor counts only as a ledger event recorded it. */
21
+ export type RecordedPair = (x: string, y: string) => boolean;
22
+ export declare function recordedPairs(events: ReadonlyArray<{
23
+ kind?: string;
24
+ inputs?: unknown;
25
+ }>): RecordedPair;
26
+ /**
27
+ * @implements A-SPEC-222.7 — the A-SPEC of Y that covers X's dependency `d`: `d` itself, its successor in this act's
28
+ * chain, or its recorded superseded_by when that successor qualifies (H2b: a record is trusted only when it does;
29
+ * A-SPEC-222.8: and only when the ledger recorded it).
30
+ * @implements A-SPEC-222.9 — a retired `d` is followed only while it holds its seal (H3). Every decision passes the
31
+ * record through SuccessionJudge (L11: an absent one trusted any written successor); only the constitution's pure exit
32
+ * hint, which reads no ledger and decides nothing, calls without one.
33
+ */
34
+ export declare function coveringAspec(d: string, y: Spec, specs: Spec[], mapped?: Map<string, string>, recorded?: RecordedPair, approved?: ApprovedSeal): string | null;
35
+ /**
36
+ * @implements A-SPEC-222.7 — null when the T-SPEC Y may replace the T-SPEC X, else why not: Y sealed, and EVERY A-SPEC X
37
+ * depends on (H1: the gate reads them all) covered by Y with counted tests.
38
+ */
39
+ export declare function tspecSuccessionRefusal(x: Spec, y: Spec | null | undefined, yId: string, specs: Spec[], counted: (aspec: string) => number, mapped?: Map<string, string>, recorded?: RecordedPair, approved?: ApprovedSeal): string | null;
40
+ /**
41
+ * Null when Y qualifies as the successor of the A-SPEC X, else why not: Y is an A-SPEC id, sealed, of X's kind, of X's
42
+ * lineage, its Files to Touch name every entry of X's, and (A-SPEC-222.8 N5) reach nowhere X's range does not — each
43
+ * entry of Y is an entry of X or a path one of X's entries matches (a directory, a new file or a glob goes to a person).
44
+ */
45
+ export declare function successorRefusal(x: Spec, y: Spec | null | undefined, yId: string, specs?: Spec[]): string | null;
46
+ /**
47
+ * @implements A-SPEC-222.9 — SD1 finding 4: the one judgment of who may stand in for a retired X, for the code gate,
48
+ * `spec_retire`'s after-the-fact record and its autonomous retirement. It takes the specs, the ledger's record (from
49
+ * the trusted-events port) and a test counter, never the store or the ledger, and its A and T judgments read the record
50
+ * the same way. X is judged as it was sealed (H3).
51
+ */
52
+ export declare class SuccessionJudge {
53
+ private readonly deps;
54
+ /** @implements A-SPEC-222.10 — `approved` is required: a seal counts only as a trusted spec-approved event recorded it (H-B). */
55
+ constructor(deps: {
56
+ specs: Spec[];
57
+ recorded: RecordedPair;
58
+ approved: ApprovedSeal;
59
+ counted: (aspec: string) => number;
60
+ });
61
+ private unsealed;
62
+ /** Null when the sealed A-SPEC Y may succeed the A-SPEC X. */
63
+ aspec(x: Spec, yId: string): string | null;
64
+ /** Null when the sealed T-SPEC Y may succeed the T-SPEC X: every A-SPEC X covers is covered by Y with counted tests. */
65
+ tspec(x: Spec, yId: string, mapped?: Map<string, string>): string | null;
66
+ /** The A-SPEC of Y that covers X's dependency `d`, or null. */
67
+ covering(d: string, y: Spec, mapped?: Map<string, string>): string | null;
68
+ /** The record, for a caller that must ask whether a pair was recorded at all. */
69
+ recorded(x: string, y: string): boolean;
70
+ }
@@ -0,0 +1,171 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SuccessionJudge = void 0;
4
+ exports.sealHolds = sealHolds;
5
+ exports.sealedBody = sealedBody;
6
+ exports.sharesLineage = sharesLineage;
7
+ exports.recordedPairs = recordedPairs;
8
+ exports.coveringAspec = coveringAspec;
9
+ exports.tspecSuccessionRefusal = tspecSuccessionRefusal;
10
+ exports.successorRefusal = successorRefusal;
11
+ const spec_digest_1 = require("./spec-digest");
12
+ const scope_judgment_1 = require("../guardrail/scope-judgment");
13
+ const A_SPEC_ID = /^A-SPEC-\d{3,}(?:\.\d+)?$/;
14
+ /** Y sealed now: approved, and its digest is its approved_digest. */
15
+ function sealHolds(y) {
16
+ const d = y.frontmatter.approved_digest;
17
+ return y.status === 'approved' && typeof d === 'string' && (0, spec_digest_1.specDigest)(y) === d;
18
+ }
19
+ /**
20
+ * @implements A-SPEC-222.9 — H3: a spec as it was sealed, whatever its status now (status and superseded_by are not in
21
+ * the digest), so a retired X is judged by the body that was approved; an edit after the seal, or no seal, is no basis.
22
+ */
23
+ function sealedBody(x, approved) {
24
+ const d = x.frontmatter.approved_digest;
25
+ // @implements A-SPEC-222.10 — H-B: the digest carries no id and the file is writable, so the seal counts only as a
26
+ // trusted spec-approved event recorded it for this id
27
+ return typeof d === 'string' && (0, spec_digest_1.specDigest)(x) === d && (approved === undefined || approved(x.id, d));
28
+ }
29
+ /** @implements A-SPEC-222.8 — the REQs a spec descends from, through depends_on. */
30
+ function reqAncestors(s, specs) {
31
+ const out = new Set();
32
+ const seen = new Set();
33
+ const walk = (id) => {
34
+ if (seen.has(id))
35
+ return;
36
+ seen.add(id);
37
+ if (id.startsWith('REQ-')) {
38
+ out.add(id);
39
+ return;
40
+ }
41
+ for (const d of specs.find((x) => x.id === id)?.dependsOn ?? [])
42
+ walk(d);
43
+ };
44
+ for (const d of s.dependsOn)
45
+ walk(d);
46
+ return out;
47
+ }
48
+ /**
49
+ * Y belongs to X's line: a shared parent, or Y names X in depends_on — or names X in `replaces` while the two share a
50
+ * REQ ancestor (A-SPEC-222.8 N6: `replaces` alone is a declaration anyone can write).
51
+ */
52
+ function sharesLineage(x, y, specs = []) {
53
+ if (x.dependsOn.some((d) => y.dependsOn.includes(d)) || y.dependsOn.includes(x.id))
54
+ return true;
55
+ const replaces = y.frontmatter.replaces;
56
+ const named = (Array.isArray(replaces) ? replaces.map(String) : typeof replaces === 'string' ? [replaces] : []).map((s) => s.trim());
57
+ if (!named.includes(x.id))
58
+ return false;
59
+ const xr = reqAncestors(x, specs);
60
+ return [...reqAncestors(y, specs)].some((r) => xr.has(r));
61
+ }
62
+ function recordedPairs(events) {
63
+ const pairs = new Set();
64
+ for (const e of events) {
65
+ if (e.kind !== 'spec-superseded' && e.kind !== 'spec-retired')
66
+ continue;
67
+ const inputs = Array.isArray(e.inputs) ? e.inputs.map(String) : [];
68
+ const y = inputs.find((i) => i.startsWith('superseded-by:'));
69
+ if (inputs[0] && y)
70
+ pairs.add(`${inputs[0]}\u0000${y.slice('superseded-by:'.length)}`);
71
+ }
72
+ return (x, y) => pairs.has(`${x}\u0000${y}`);
73
+ }
74
+ /**
75
+ * @implements A-SPEC-222.7 — the A-SPEC of Y that covers X's dependency `d`: `d` itself, its successor in this act's
76
+ * chain, or its recorded superseded_by when that successor qualifies (H2b: a record is trusted only when it does;
77
+ * A-SPEC-222.8: and only when the ledger recorded it).
78
+ * @implements A-SPEC-222.9 — a retired `d` is followed only while it holds its seal (H3). Every decision passes the
79
+ * record through SuccessionJudge (L11: an absent one trusted any written successor); only the constitution's pure exit
80
+ * hint, which reads no ledger and decides nothing, calls without one.
81
+ */
82
+ function coveringAspec(d, y, specs, mapped, recorded, approved) {
83
+ if (y.dependsOn.includes(d))
84
+ return d;
85
+ const m = mapped?.get(d);
86
+ if (m && y.dependsOn.includes(m))
87
+ return m;
88
+ const ds = specs.find((s) => s.id === d);
89
+ const via = String(ds?.frontmatter?.superseded_by ?? '').trim();
90
+ if (ds && ds.status === 'outdated' && via && y.dependsOn.includes(via) && (!recorded || recorded(d, via)) && sealedBody(ds, approved)
91
+ && successorRefusal(ds, specs.find((s) => s.id === via), via, specs) === null)
92
+ return via;
93
+ return null;
94
+ }
95
+ /**
96
+ * @implements A-SPEC-222.7 — null when the T-SPEC Y may replace the T-SPEC X, else why not: Y sealed, and EVERY A-SPEC X
97
+ * depends on (H1: the gate reads them all) covered by Y with counted tests.
98
+ */
99
+ function tspecSuccessionRefusal(x, y, yId, specs, counted, mapped, recorded, approved) {
100
+ if (yId === x.id)
101
+ return `${x.id} cannot succeed itself`;
102
+ if (!y || y.type !== 'T-SPEC' || !sealHolds(y))
103
+ return `${yId} is not a sealed T-SPEC`;
104
+ for (const d of x.dependsOn.filter((id) => id.startsWith('A-SPEC-'))) {
105
+ const c = coveringAspec(d, y, specs, mapped, recorded, approved);
106
+ if (c === null)
107
+ return `${y.id} does not cover ${d} (retiring ${x.id} would open its gate)`;
108
+ if (counted(c) === 0)
109
+ return `${c} has no counted test case`;
110
+ }
111
+ return null;
112
+ }
113
+ /**
114
+ * Null when Y qualifies as the successor of the A-SPEC X, else why not: Y is an A-SPEC id, sealed, of X's kind, of X's
115
+ * lineage, its Files to Touch name every entry of X's, and (A-SPEC-222.8 N5) reach nowhere X's range does not — each
116
+ * entry of Y is an entry of X or a path one of X's entries matches (a directory, a new file or a glob goes to a person).
117
+ */
118
+ function successorRefusal(x, y, yId, specs = []) {
119
+ if (yId === x.id)
120
+ return `${x.id} cannot succeed itself`; // @implements A-SPEC-222.7 (M1)
121
+ if (x.type === 'A-SPEC' && !A_SPEC_ID.test(yId))
122
+ return `${yId} is not an A-SPEC id`;
123
+ if (!y || y.type !== x.type || !sealHolds(y))
124
+ return `${yId} is not a sealed ${x.type}`;
125
+ if (!sharesLineage(x, y, specs))
126
+ return `${y.id} is not of ${x.id}'s lineage (no shared parent, it does not depend on ${x.id}, and no replaces within one REQ)`;
127
+ if (x.type === 'A-SPEC') {
128
+ const xFiles = (0, scope_judgment_1.fttPathTokens)(x.sections['Files to Touch'] ?? '');
129
+ const yFiles = (0, scope_judgment_1.fttPathTokens)(y.sections['Files to Touch'] ?? '');
130
+ const dropped = xFiles.filter((f) => !yFiles.includes(f));
131
+ if (dropped.length > 0)
132
+ return `${y.id}'s Files to Touch drop ${dropped.join(', ')}`;
133
+ const beyond = yFiles.filter((f) => !xFiles.includes(f) && (/[*?[]/.test(f) || !xFiles.some((t) => (0, scope_judgment_1.matchesFtt)(t, f))));
134
+ if (beyond.length > 0)
135
+ return `${y.id}'s Files to Touch reach beyond ${x.id}'s range (${beyond.join(', ')})`;
136
+ }
137
+ return null;
138
+ }
139
+ /**
140
+ * @implements A-SPEC-222.9 — SD1 finding 4: the one judgment of who may stand in for a retired X, for the code gate,
141
+ * `spec_retire`'s after-the-fact record and its autonomous retirement. It takes the specs, the ledger's record (from
142
+ * the trusted-events port) and a test counter, never the store or the ledger, and its A and T judgments read the record
143
+ * the same way. X is judged as it was sealed (H3).
144
+ */
145
+ class SuccessionJudge {
146
+ deps;
147
+ /** @implements A-SPEC-222.10 — `approved` is required: a seal counts only as a trusted spec-approved event recorded it (H-B). */
148
+ constructor(deps) {
149
+ this.deps = deps;
150
+ }
151
+ unsealed(x) {
152
+ return sealedBody(x, this.deps.approved) ? null
153
+ : `${x.id} does not hold its seal (never sealed, edited after it, or no trusted spec-approved event records it), so it is no basis for a successor`;
154
+ }
155
+ /** Null when the sealed A-SPEC Y may succeed the A-SPEC X. */
156
+ aspec(x, yId) {
157
+ return this.unsealed(x) ?? successorRefusal(x, this.deps.specs.find((s) => s.id === yId), yId, this.deps.specs);
158
+ }
159
+ /** Null when the sealed T-SPEC Y may succeed the T-SPEC X: every A-SPEC X covers is covered by Y with counted tests. */
160
+ tspec(x, yId, mapped) {
161
+ return this.unsealed(x)
162
+ ?? tspecSuccessionRefusal(x, this.deps.specs.find((s) => s.id === yId), yId, this.deps.specs, this.deps.counted, mapped, this.deps.recorded, this.deps.approved);
163
+ }
164
+ /** The A-SPEC of Y that covers X's dependency `d`, or null. */
165
+ covering(d, y, mapped) {
166
+ return coveringAspec(d, y, this.deps.specs, mapped, this.deps.recorded, this.deps.approved);
167
+ }
168
+ /** The record, for a caller that must ask whether a pair was recorded at all. */
169
+ recorded(x, y) { return this.deps.recorded(x, y); }
170
+ }
171
+ exports.SuccessionJudge = SuccessionJudge;
@@ -9,7 +9,7 @@ export declare function prepareLifecycleSpec(spec: Spec, all: Spec[], operation:
9
9
  ok: true;
10
10
  candidate: Spec;
11
11
  dependents: Spec[];
12
- reason?: undefined;
12
+ readonly reason?: undefined;
13
13
  };
14
14
  /** Act-time policy only: callers own authority, version checks, persistence and audit. */
15
15
  export declare function prepareApprovedSpec(spec: Spec, specs: Spec[], resolver: (specs: Spec[]) => (id: string) => Spec | null, readFile: (relative: string) => string | null, opts?: {
@@ -29,6 +29,6 @@ export declare function prepareApprovedSpec(spec: Spec, specs: Spec[], resolver:
29
29
  candidate: Spec;
30
30
  digest: string;
31
31
  parentDigests: Record<string, string>;
32
- reason?: undefined;
32
+ readonly reason?: undefined;
33
33
  findings?: undefined;
34
34
  };
@@ -5,6 +5,9 @@ This guide exists because of a measured failure, not a hypothetical one: an adop
5
5
  time, because their npm global prefix pointed inside `C:\Program Files\nodejs`. The local install
6
6
  worked on the first try. Find your row, run its one command.
7
7
 
8
+ > What you install: a hook that prevents accidents. Its resistance to forgery has not been verified, and it is
9
+ > not a security boundary against the same user's agent shell (the CHANGELOG's Known limitations).
10
+
8
11
  ## Which situation are you in?
9
12
 
10
13
  | Situation | Privileges needed | Command |
@@ -258,9 +261,9 @@ claiming that a local configuration proves a live session loaded it.
258
261
 
259
262
  | Idea | Why not |
260
263
  |---|---|
261
- | A `postinstall` script that prints guidance | Under npm 12 it would be blocked like any other install script, and it forfeits this package's property of running no install scripts of its own |
264
+ | A `postinstall` script that prints guidance | Under npm 12 it would be blocked like any other install script. This package's one `postinstall` prepares the local semantic model and does nothing else |
262
265
  | Approving the tree-sitter grammars in `allowScripts` | Measured unnecessary — they load from shipped prebuilds — and every extra approval is code that runs at install time |
263
- | Recommending `npx @holmes-lab/holmes-kit init` with no install | `init` writes wiring with absolute paths; under bare `npx` those point into the npx cache and break when it is pruned |
266
+ | Recommending `npx @holmes-lab/holmes-kit init` with no install | Run from the temporary npx cache, `init` wires an npx pin instead of an absolute path, and npx then runs npm in every workspace the harness opens. npm reads that workspace's `.npmrc` and `node_modules`, which can put other code in the gate server's place (measured 2026-09-25) |
264
267
  | Fixing your npm prefix from inside the package | A package rewriting your npm configuration is exactly the supply-chain behaviour this guide warns about |
265
268
  ## ARM Linux needs Node 20 or 22
266
269
 
@@ -288,7 +291,10 @@ holmes-kit semantic-setup
288
291
  ```
289
292
 
290
293
  `HOLMES_SKIP_MODEL_INSTALL=1` explicitly refuses automatic preparation. It is the only automatic
291
- opt-out and never prevents an explicit `semantic-setup` or `semantic-check`. The Node lifecycle
294
+ opt-out and never prevents an explicit `semantic-setup` or `semantic-check`. `holmes-kit init`
295
+ starts the same automatic preparation (not under `--dry-run` or `--remove`), so set it for an
296
+ offline or CI `init` as well; without it a download that fails is reported and `init` still
297
+ completes. The Node lifecycle
292
298
  implementation is shared by the three harnesses. Windows PowerShell-bootstrap default-preparation
293
299
  behavior is retained for separate consumer validation; do not treat this document as evidence that
294
300
  that bootstrap path has completed the same acceptance run.
@@ -0,0 +1,78 @@
1
+ <!-- GENERATED by renderLanguageSupport() (A-SPEC-510.6). Do not edit by hand:
2
+ every cell is derived from the module that owns the capability, and a test pins this
3
+ file byte-identical to the render. Regenerate: `node scripts/render-language-support.js`. -->
4
+ # Language support matrix
5
+
6
+ Legend: ● full · ◐ partial · ○ none
7
+
8
+ | Layer | TypeScript / JavaScript | Python | C# | Java | Go | Rust | C++ |
9
+ |---|---|---|---|---|---|---|---|
10
+ | **relations** | ● | ● | ● | ● | ● | ● | ● |
11
+ | **ast** | ● | ● | ● | ● | ● | ● | ● |
12
+ | **cfg** | ● | ● | ● | ● | ● | ● | ● |
13
+ | **ddg** | ● | ● | ● | ● | ● | ● | ● |
14
+ | **cdg** | ● | ● | ● | ● | ● | ● | ● |
15
+ | **runner** | ● | ● | ● | ● | ● | ● | ○ |
16
+ | **taint** | ● | ● | ● | ● | ● | ● | ● |
17
+
18
+ ## What each layer means
19
+
20
+ - **relations** — L0 — symbols and relations that actually become RTM graph edges
21
+ - **ast** — L1 — lossless-span AST, persisted (tree-sitter wasm substrate)
22
+ - **cfg** — L2 — control-flow graph with dominator / post-dominator trees
23
+ - **ddg** — L3 — data dependence (reaching definitions, REACHING_DEF edges)
24
+ - **cdg** — L3 — control dependence (CDG edges); PDG = DDG ∪ CDG
25
+ - **runner** — test_run — executes this language's suites for ART-4 execution evidence
26
+ - **taint** — taint_scan — data-flow walk for source→sink analysis
27
+
28
+ ## Per-cell basis
29
+
30
+ - `relations` / TypeScript / JavaScript: **full** — graph edges: calls, imports, inherits
31
+ - `relations` / Python: **full** — graph edges: calls, imports, inherits
32
+ - `relations` / C#: **full** — graph edges: calls, imports, inherits
33
+ - `relations` / Java: **full** — graph edges: calls, imports, inherits
34
+ - `relations` / Go: **full** — graph edges: calls, imports, inherits
35
+ - `relations` / Rust: **full** — graph edges: calls, imports, inherits
36
+ - `relations` / C++: **full** — graph edges: calls, imports, inherits
37
+ - `ast` / TypeScript / JavaScript: **full** — vendored tree-sitter grammar (L1 AST persisted)
38
+ - `ast` / Python: **full** — vendored tree-sitter grammar (L1 AST persisted)
39
+ - `ast` / C#: **full** — vendored tree-sitter grammar (L1 AST persisted)
40
+ - `ast` / Java: **full** — vendored tree-sitter grammar (L1 AST persisted)
41
+ - `ast` / Go: **full** — vendored tree-sitter grammar (L1 AST persisted)
42
+ - `ast` / Rust: **full** — vendored tree-sitter grammar (L1 AST persisted)
43
+ - `ast` / C++: **full** — vendored tree-sitter grammar (L1 AST persisted) — limit: template/macro-heavy real files can refuse at L1 (measured 25-34% on three corpora); layers above speak only for what parses
44
+ - `cfg` / TypeScript / JavaScript: **full** — control flow + dominators, statement granularity
45
+ - `cfg` / Python: **full** — control flow + dominators, statement granularity
46
+ - `cfg` / C#: **full** — control flow + dominators, statement granularity
47
+ - `cfg` / Java: **full** — control flow + dominators, statement granularity
48
+ - `cfg` / Go: **full** — control flow + dominators, statement granularity
49
+ - `cfg` / Rust: **full** — control flow + dominators, statement granularity
50
+ - `cfg` / C++: **full** — control flow + dominators, statement granularity
51
+ - `ddg` / TypeScript / JavaScript: **full** — reaching definitions (REACHING_DEF), statement granularity
52
+ - `ddg` / Python: **full** — reaching definitions (REACHING_DEF), statement granularity
53
+ - `ddg` / C#: **full** — reaching definitions (REACHING_DEF), statement granularity
54
+ - `ddg` / Java: **full** — reaching definitions (REACHING_DEF), statement granularity
55
+ - `ddg` / Go: **full** — reaching definitions (REACHING_DEF), statement granularity
56
+ - `ddg` / Rust: **full** — reaching definitions (REACHING_DEF), statement granularity
57
+ - `ddg` / C++: **full** — reaching definitions (REACHING_DEF), statement granularity
58
+ - `cdg` / TypeScript / JavaScript: **full** — control dependence (CDG), statement granularity
59
+ - `cdg` / Python: **full** — control dependence (CDG), statement granularity
60
+ - `cdg` / C#: **full** — control dependence (CDG), statement granularity
61
+ - `cdg` / Java: **full** — control dependence (CDG), statement granularity
62
+ - `cdg` / Go: **full** — control dependence (CDG), statement granularity
63
+ - `cdg` / Rust: **full** — control dependence (CDG), statement granularity
64
+ - `cdg` / C++: **full** — control dependence (CDG), statement granularity
65
+ - `runner` / TypeScript / JavaScript: **full** — test runner adapter: jest
66
+ - `runner` / Python: **full** — test runner adapter: pytest
67
+ - `runner` / C#: **full** — test runner adapter: dotnet
68
+ - `runner` / Java: **full** — test runner adapter: java
69
+ - `runner` / Go: **full** — test runner adapter: go
70
+ - `runner` / Rust: **full** — test runner adapter: rust
71
+ - `runner` / C++: **none** — no test-runner adapter — execution evidence unavailable
72
+ - `taint` / TypeScript / JavaScript: **full** — taint_scan { dataFlow: true } analyses this language (vocabulary + CFG/DDG)
73
+ - `taint` / Python: **full** — taint_scan { dataFlow: true } analyses this language (vocabulary + CFG/DDG)
74
+ - `taint` / C#: **full** — taint_scan { dataFlow: true } analyses this language (vocabulary + CFG/DDG)
75
+ - `taint` / Java: **full** — taint_scan { dataFlow: true } analyses this language (vocabulary + CFG/DDG)
76
+ - `taint` / Go: **full** — taint_scan { dataFlow: true } analyses this language (vocabulary + CFG/DDG)
77
+ - `taint` / Rust: **full** — taint_scan { dataFlow: true } analyses this language (vocabulary + CFG/DDG)
78
+ - `taint` / C++: **full** — taint_scan { dataFlow: true } analyses this language (vocabulary + CFG/DDG)
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
- "//": "@implements A-SPEC-209",
2
+ "//": "@implements A-SPEC-209, A-SPEC-794.58",
3
3
  "name": "@holmes-lab/holmes-kit",
4
- "version": "0.39.0",
4
+ "version": "0.40.1",
5
5
  "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
6
6
  "main": "dist/holmes/mcp/server.js",
7
7
  "types": "dist/holmes/mcp/server.d.ts",
@@ -16,6 +16,7 @@
16
16
  "playbooks/",
17
17
  "scripts/install.ps1",
18
18
  "docs/install-guide.md",
19
+ "docs/language-support.md",
19
20
  "CHANGELOG.md"
20
21
  ],
21
22
  "engines": {
@@ -92,7 +93,7 @@
92
93
  "type": "git",
93
94
  "url": "git+https://github.com/holmes-kit/holmes-kit.git"
94
95
  },
95
- "homepage": "https://github.com/holmes-kit/holmes-kit#readme",
96
+ "homepage": "https://holmes-lab.web.app",
96
97
  "bugs": {
97
98
  "url": "https://github.com/holmes-kit/holmes-kit/issues"
98
99
  },
@@ -84,7 +84,7 @@ Criteria · Non-Functional · Assumptions · Open Questions.** 필수 필드: `r
84
84
 
85
85
  **관측을 신설하거나 좌표를 바꾸는 슬라이스**(계측·원장·카운터·지표·이벤트 기록)는 `## Non-Functional`에
86
86
  `- [observability] <무엇을 기록하고 어디서 어떤 키로 읽는가>` 의무를 적는다. 기록 쪽만 검증한 테스트는
87
- 읽는 쪽이 보는 좌표에 없는 기록을 잡지 못한다 — jarvis 실사고(2026-09-08): `kind`가 고정돼 조회가
87
+ 읽는 쪽이 보는 좌표에 없는 기록을 잡지 못한다 — 소비 작업공간의 실사고(2026-09-08): `kind`가 고정돼 조회가
88
88
  구조적으로 0이었고, 그 0 위에서 설계 결정이 두 번 내려졌다. 이 의무는 T-SPEC의 `[observability]`
89
89
  케이스와 대응되어야 하며, 대응이 없으면 `review_scope`·`maintenance_analyze`가 `obligationGaps`로
90
90
  **보고**한다 — 차단이 아니라 보고다(`obligationGapsFor`; 태그 어휘는 열려 있어 새 필드가 필요 없다).
@@ -13,7 +13,11 @@ description: >-
13
13
  계산 → `status: approved` + `approved_digest` + 부모 봉인 스냅샷 기록 → 원장 append를 한 번에.
14
14
  손으로 `status:`만 바꾸는 것으로는 부족하다: 봉인 없이 approved가 된 스펙은 `unsealed-approval`로
15
15
  검증에 걸리고, 봉인 후 본문을 고치면 `post-approval-edit`으로, 부모가 움직이면 `stale-parent`로
16
- 걸린다(REQ-132). `spec_approve`는 사람의 승인을 요구한다(fail-closed) — 요청 인자로는 대체되지 않는다.
16
+ 걸린다(REQ-132). `spec_approve`는 기본으로 사람의 승인을 요구한다(fail-closed) — 요청 인자로는 대체되지 않는다.
17
+ 예외가 둘 있다: 자율 승인이 켜진 프로젝트에서는 저위험 스펙이 바로 봉인되고, full 프로필이 덮는 작업공간에서는
18
+ 사람에게 가던 봉인이 바로 봉인된다(행위자 `full-autonomy:`, REQ-792). 다만 세 부류는 바로 거부되고 거부문이 고칠
19
+ 길을 말한다: triage를 거치지 않은 REQ, 선언하지 않았거나 알 수 없는 등급, 그리고 `--no-architecture`로 발급된 프로필의
20
+ 아키텍처 문서. 사람이 봐야 할 봉인이면 프로필을 먼저 좁힌다.
17
21
  사람은 세션의 승인 창에서 답한다. 거부가 `[승인 대기 req-…]`를 지목했다면 `approval_ask`에 그 id를 넘겨
18
22
  창을 띄운다(0.37.0). 창이 없는 세션에서는 같은 작업공간의 Claude Code 세션 승인 창에서 결정한다 —
19
23
  명령을 입력하라고 사람에게 넘기지 않는다(0.38.0, REQ-792).
@@ -2,26 +2,29 @@
2
2
  name: holmes-publish
3
3
  description: >-
4
4
  Use when asked to publish holmes-kit to NPM registry or run release workflow governed by
5
- "HOLMES_APPROVAL", "hard-hitl", or "A-SPEC-133" — the repository owner authorizes an
6
- irreversible / high-risk release Human-In-The-Loop, while a low-risk release may self-publish
7
- under autonomous mode.
5
+ "HOLMES_APPROVAL", "hard-hitl", or "A-SPEC-133" — the repository owner authorizes the release
6
+ Human-In-The-Loop; the release risk rules are a procedure, and nothing runs them for the agent.
8
7
  ---
9
8
 
10
- # holmes-publish — NPM 배포 및 릴리스 자율/HITL 절차
9
+ # holmes-publish — NPM 배포 및 릴리스 HITL 절차
11
10
 
12
11
  이 플레이북은 `@holmes-lab/holmes-kit` 를 NPM Registry에 안전하게 배포하는 **규정 절차**를 정의합니다.
13
- npm publish 는 **비가역·외부노출**이라 기본은 HITL(사람 승인)이지만, **저위험 릴리스**(문서·테스트·양성
14
- 내부 변경의 patch/minor)는 **자율 모드에서 자율 처리**할 수 있고, **비가역/high-risk**(게이트·보안·아키텍처
15
- 변경, major 범프, 상위 스펙)는 반드시 **오너의 대역외 HITL 승인**을 거칩니다. 판정은 결정론적 분류기
16
- `releaseAutonomy`(A-SPEC-555.1, `governance/autonomy.ts`)가 담당합니다.
12
+ npm publish 는 **비가역·외부노출**이라 **게시는 오너가 정합니다**(HITL): 오너가 직접 게시하거나, full 프로필이면 `--allow-publish` 로 허용합니다. **저위험 릴리스**(문서·테스트·양성
13
+ 내부 변경의 patch/minor)와 **비가역/high-risk**(게이트·보안·아키텍처 변경, major 범프, 상위 스펙)를 가르는 규칙은
14
+ `releaseAutonomy`(A-SPEC-555.1, `governance/autonomy.ts`)에 있지만, 이 함수를 부르는 명령은 없고 어떤 게이트도 그
15
+ 결과를 읽지 않습니다. 규칙은 오너에게 보고할 위험 분류로 씁니다.
17
16
 
18
17
  ---
19
18
 
20
19
  ## 배포 절차 (Release Workflow)
21
20
 
22
21
  ### 1단계: 사전 품질 감사 (Pre-flight Quality Audit)
22
+ 0. 버전, `CHANGELOG.md`의 `[X.Y.Z]` 항목, README 항목을 **먼저 커밋한다.** `verify-release`는 dirty 트리를
23
+ 거부하고, 시험 영수증은 같은 HEAD만 받는다. 개발 트리에 추적되지 않은 파일이 있으면 릴리스 커밋의 깨끗한
24
+ worktree에서 진행한다.
23
25
  1. `npm run typecheck` (타입 오류 0건)
24
- 2. 전체 스위트 green — `mcp__holmes-kit__test_run`(HEAD~1..HEAD) 또는 `npx jest`. 부하가 높으면 대시보드
26
+ 2. 전체 스위트 green — `mcp__holmes-kit__test_run({root, full: true})`. 범위 실행(`HEAD~1..HEAD`)과 `npx jest`는
27
+ push 증빙을 남기지 않는다(A-SPEC-128.2, 128.4). 부하가 높으면 대시보드
25
28
  canary(A-SPEC-435)가 타임아웃할 수 있으니 부하를 낮춘 뒤 재실행한다(코드가 아니라 부하 문제).
26
29
  3. `npm run build` (`dist/` 최신 + `.build-id`).
27
30
 
@@ -31,7 +34,7 @@ npm publish 는 **비가역·외부노출**이라 기본은 HITL(사람 승인)
31
34
  ---
32
35
 
33
36
  ### 2단계: 패키지 타르볼 시뮬레이션 및 검수 (Tarball Inspection)
34
- - `npm publish --dry-run`
37
+ - `npm pack --dry-run --ignore-scripts` (`npm`의 dry-run 표시가 시험으로 상속돼 판정이 틀어지므로 게시 명령의 dry-run으로 보지 않는다)
35
38
  - 타르볼 구성 검수: `package.json`(명칭·버전), `bin/`, `dist/`, `playbooks/`, `CHANGELOG.md`, `README.md`.
36
39
 
37
40
  ---
@@ -97,20 +100,23 @@ README 의 추적 배지(`.ax/badges/traced.svg`)와 그 아래 측정 문구는
97
100
 
98
101
  ---
99
102
 
100
- ### 3단계: 릴리스 자율 판정 (Release Autonomy) — auto 또는 HITL
101
- `releaseAutonomy(specsSinceTag, versionBump, process.env, root, now)` 로 이번 릴리스를 분류한다
102
- (`versionBumpKind(현재버전, 대상버전)` 으로 범프 종류 산출):
103
- - **`'auto'`** (자율 ON + 모든 스펙 auto 등급 + patch/minor): 사람 없이 4단계로 진행하되, 원장에 배포
104
- 근거를 남긴다(무엇을·왜·어느 버전). 저위험 릴리스의 자율 처리.
103
+ ### 3단계: 릴리스 위험 분류 (Release Autonomy 규칙) — 보고용
104
+ `releaseAutonomy(specsSinceTag, versionBump, process.env, root, now)` 의 규칙으로 이번 릴리스를 분류한다
105
+ (`versionBumpKind(현재버전, 대상버전)` 으로 범프 종류 산출). 이 함수를 부르는 명령은 없고 게시 검사도 이 판정을 읽지
106
+ 않는다. 분류를 확인하지 못했으면 `'hitl'` 로 본다:
107
+ - **`'auto'`** (자율 ON + 모든 스펙 auto 등급 + patch/minor): 규칙상 저위험이다. 보고에 그렇게 적는다.
105
108
  - **`'hitl'`** (자율 OFF · major 범프 · 게이트/보안/아키텍처 스펙 · 상위 REQ/H/C · 비가역 breaking_change):
106
- **오너에게 배포 요약을 보고하고 명시적 대역외 승인**을 받은 뒤에만 진행한다. AI Agent 는 독단적으로
107
- `npm publish` 하지 않는다. 승인은 채팅의 명시적 확인 또는 `HOLMES_APPROVAL` 로 전달된다.
109
+ 규칙상 고위험이다. 보고에 어느 스펙 때문인지 적는다.
110
+
111
+ 어느 쪽이든 **오너에게 배포 요약을 보고하고 명시적 대역외 승인**을 받은 뒤에만 진행한다. AI Agent 는 독단적으로
112
+ `npm publish` 하지 않는다. 오너가 채팅에서 명시적으로 확인하거나 직접 게시한다. full 프로필에서는 `--allow-publish`
113
+ 없는 게시를 게이트가 읽는 형태에서 hook이 거부한다. 프로필 밖에서는 hook이 판정하지 않으니 이 확인은 절차다.
108
114
 
109
115
  **[HITL 보고 양식]**: 패키지 `@holmes-lab/holmes-kit` · 대상 `vX.Y.Z`(범프: major/minor/patch) ·
110
116
  테스트 PASS · 타르볼 N개/XXX kB · 분류 사유(어느 스펙이 hitl 인지).
111
117
 
112
118
  > [!CAUTION]
113
- > hitl 판정에서 오너 승인이 없으면 즉시 중단. 자율(auto) 판정이라도 2.5단계 문서 게이트를 통과해야 한다.
119
+ > 오너 승인이 없으면 즉시 중단. `'auto'` 분류라도 2.5단계 문서 게이트를 통과해야 한다.
114
120
 
115
121
  ---
116
122
 
@@ -119,26 +125,27 @@ README 의 추적 배지(`.ax/badges/traced.svg`)와 그 아래 측정 문구는
119
125
  npm publish --access public
120
126
  ```
121
127
  - 2FA / Web OTP 가 필요하면 인증 URL 을 사용자에게 제공하고 대기.
122
- - verify-release 가 전체 `npm test` 를 돌려 플레이크할 수 있으므로, 1단계를 이미 green 으로 통과했다면
123
- `npm publish --ignore-scripts` + 수동 무결성 확인(트리 클린·build-id==HEAD·CHANGELOG 항목)로 우회할 수 있다.
128
+ - `prepublishOnly` 의 `verify-release` 는 트리 클린, 24시간 안의 같은 HEAD release test-lane 영수증, 문서 정합,
129
+ build-id==HEAD, CHANGELOG 항목을 본다. 영수증은 `npm run build` 뒤 `node scripts/verify-release.js --record-release-test-lane`
130
+ 으로 남긴다. 이 검사를 건너뛰고 게시하지 않는다. 시험이 흔들리면 원인을 찾고 다시 돌린다.
124
131
 
125
132
  ---
126
133
 
127
134
  ### 5단계: 배포 후 검증 및 Git 태깅 (Post-Release Verification)
128
135
  1. NPM 반영 확인: `npm view @holmes-lab/holmes-kit version` (레지스트리 read-cache 지연 시 레지스트리 JSON 직접 조회).
129
- 2. 커밋 및 태그:
136
+ 2. 태그. 릴리스 커밋은 1단계에서 이미 있다. 게시한 커밋에 건다:
130
137
  ```bash
131
- git add package.json CHANGELOG.md README.md
132
- git commit -m "chore: release vX.Y.Z"
133
- git tag -a vX.Y.Z -m "vX.Y.Z Release"
138
+ git tag -a vX.Y.Z <릴리스 커밋> -m "vX.Y.Z Release"
139
+ git push origin vX.Y.Z
134
140
  ```
141
+ full 프로필에 push 플래그가 없으면 이 push는 hook이 거부한다. 오너에게 부탁한다.
135
142
 
136
143
  ---
137
144
 
138
145
  ### 6단계: 외부 문서 표면 (External Docs Reach) — 발행이 닿는 곳까지 정직하게
139
146
 
140
147
  npm 만 갱신하고 끝나면, 사람들이 실제로 읽는 문서는 낡은 채로 남는다. **사고 이력 1**: 이 저장소에는
141
- GitHub 리모트가 없어(origin 이 로컬 gitea) 0.16.0·0.17.0·0.18.0 **세 릴리스 동안** GitHub README 가
148
+ GitHub 리모트가 없어(origin 이 로컬 저장소 서버) 0.16.0·0.17.0·0.18.0 **세 릴리스 동안** GitHub README 가
142
149
  한 번도 갱신되지 않았고, `package.json` 의 `homepage` 가 바로 그 문서를 가리킨다. **사고 이력 2
143
150
  (2026-10-11 측정)**: 아래 4a 가 0.35.13 에 쓰인 뒤에도 GitHub 의 `.ax/badges/traced.svg` 는 **v0.27.0
144
151
  (2026-09-20) 의 숫자 그대로**였고, GitHub README 는 v0.35.10 에서 멈춰 0.35.11–0.35.16 **여섯 릴리스**가
@@ -152,16 +159,22 @@ GitHub 리모트가 없어(origin 이 로컬 gitea) 0.16.0·0.17.0·0.18.0 **세
152
159
  > `README: 원격 sha <전> → <후>, 재조회 일치 yes/no` · `badge: 원격 sha <전> → <후>, 재조회 일치 yes/no` ·
153
160
  > `SKIP 사유: <없음 | 정확한 사유>`. "동기화했다"는 문장은 이 세 줄이 아니다.
154
161
 
155
- 가장 짧은 실행 경로(두 파일을 같은 방식으로; `<owner>/<repo>` 는 1 에서 파생한 값):
162
+ 가장 짧은 실행 경로(두 파일을 하나씩, 경로를 글자 그대로; `<owner>/<repo>` 는 1 에서 파생한 값, `<sha>` 는
163
+ 바로 앞 명령이 출력한 값). 반복문으로 묶지 않는다: 셸 변수로 `.ax` 경로를 만드는 명령은 hook이 모든 프로필에서
164
+ 거부한다. 배지 내용은 저장소 밖 임시 파일로 옮긴 뒤 `-F content=@파일`로 읽게 한다(HEAD 게이트 판정으로 쟀다,
165
+ GitHub에는 보내지 않았다). 명령이 거부되면 이 단계는 오너가 터미널에서 같은 명령으로 한다.
156
166
 
157
167
  ```bash
158
- for f in README.md .ax/badges/traced.svg; do
159
- before=$(gh api "repos/<owner>/<repo>/contents/$f" --jq .sha)
160
- gh api --method PUT "repos/<owner>/<repo>/contents/$f" \
161
- -f message="docs: sync $f with vX.Y.Z" -f sha="$before" \
162
- -f content="$(base64 < "$f" | tr -d '\n')" --jq .content.sha
163
- gh api "repos/<owner>/<repo>/contents/$f" --jq .content | tr -d '\n' | base64 -d | cmp - "$f" && echo "$f: 재조회 일치"
164
- done
168
+ gh api "repos/<owner>/<repo>/contents/README.md" --jq .sha
169
+ gh api --method PUT "repos/<owner>/<repo>/contents/README.md" -f message="docs: sync README.md with vX.Y.Z" \
170
+ -f sha="<sha>" -f content="$(base64 < README.md | tr -d '\n')" --jq .content.sha
171
+ gh api "repos/<owner>/<repo>/contents/README.md" --jq .content | tr -d '\n' | base64 -d | cmp - README.md && echo "README.md: 재조회 일치"
172
+
173
+ gh api "repos/<owner>/<repo>/contents/.ax/badges/traced.svg" --jq .sha
174
+ base64 < .ax/badges/traced.svg | tr -d '\n' > /tmp/traced.svg.b64
175
+ gh api --method PUT "repos/<owner>/<repo>/contents/.ax/badges/traced.svg" -f message="docs: sync traced.svg with vX.Y.Z" \
176
+ -f sha="<sha>" -F content=@/tmp/traced.svg.b64 --jq .content.sha
177
+ gh api "repos/<owner>/<repo>/contents/.ax/badges/traced.svg" --jq .content | tr -d '\n' | base64 -d | cmp - .ax/badges/traced.svg && echo "traced.svg: 재조회 일치"
165
178
  ```
166
179
 
167
180
  1. **대상 파생 (하드코딩 금지)**: `package.json` 의 `repository` 에서 `<owner>/<repo>` 를 얻는다
@@ -173,7 +186,7 @@ done
173
186
  3. **동기화**: 로컬 `README.md` 를 `gh api --method PUT` 으로 올린다(`sha` 는 2 에서 읽은 값).
174
187
  4. **재조회 검증**: 다시 읽어 로컬과 일치하는지 확인한다. **쓴 것과 남은 것은 다를 수 있다** —
175
188
  검증 없는 "갱신했다"는 주장이지 사실이 아니다.
176
- 4a. **추적 배지도 같은 표면이다 — README 와 한 쌍으로, 같은 루프 안에서**: 로컬에 `.ax/badges/traced.svg` 가
189
+ 4a. **추적 배지도 같은 표면이다 — README 와 한 쌍으로, README 바로 뒤에서**: 로컬에 `.ax/badges/traced.svg` 가
177
190
  있으면 README 와 **같은 대상 `<owner>/<repo>`** 의 같은 경로를 2~4 와 똑같이 다룬다 — 원격을 먼저 읽어
178
191
  차이를 보고하고, 올리고, **배지도 다시 읽어** 로컬과 일치하는지 확인한다. README 만 올리면 원격 README 는
179
192
  새 숫자를 말하고 그림은 옛 숫자를 보여 준다(사고 이력 2: 그림이 **스물한 릴리스** 전 숫자였다). 배지