peaks-loop 4.1.4 → 4.1.6

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 (294) hide show
  1. package/.claude-plugin/marketplace.json +7 -2
  2. package/CHANGELOG.md +148 -0
  3. package/README-en.md +47 -183
  4. package/README.md +24 -188
  5. package/dist/cli/cli-helpers.d.ts +20 -0
  6. package/dist/cli/cli-helpers.js +34 -0
  7. package/dist/cli/commands/_register.js +2 -0
  8. package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
  9. package/dist/cli/commands/best-practice-scan-command.js +35 -20
  10. package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
  11. package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
  12. package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
  13. package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
  14. package/dist/cli/commands/code-commands.d.ts +6 -4
  15. package/dist/cli/commands/code-commands.js +6 -4
  16. package/dist/cli/commands/code-gate-command.d.ts +5 -5
  17. package/dist/cli/commands/code-gate-command.js +49 -9
  18. package/dist/cli/commands/code-mode-gate-plan-command.d.ts +1 -1
  19. package/dist/cli/commands/code-mode-gate-plan-command.js +2 -2
  20. package/dist/cli/commands/core/memory-extract-command.js +10 -5
  21. package/dist/cli/commands/dispatch-cli-invocation-check.d.ts +108 -0
  22. package/dist/cli/commands/dispatch-cli-invocation-check.js +87 -0
  23. package/dist/cli/commands/dispatch-cli-invocation-scan.d.ts +66 -0
  24. package/dist/cli/commands/dispatch-cli-invocation-scan.js +162 -0
  25. package/dist/cli/commands/dispatch-command-spec.js +1 -1
  26. package/dist/cli/commands/dispatch-commands.js +12 -5
  27. package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
  28. package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
  29. package/dist/cli/commands/dispatch-preflight.js +46 -0
  30. package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
  31. package/dist/cli/commands/dispatch-prompt-composition.d.ts +7 -1
  32. package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
  33. package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
  34. package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
  35. package/dist/cli/commands/doc-commands.js +1 -1
  36. package/dist/cli/commands/feedback-commands-helpers.js +1 -1
  37. package/dist/cli/commands/final-review-prepare-command.js +22 -1
  38. package/dist/cli/commands/gate-commands-enforce.js +3 -3
  39. package/dist/cli/commands/hook-handle.js +41 -20
  40. package/dist/cli/commands/lint-commands.js +3 -1
  41. package/dist/cli/commands/loop-eval-capture-index.js +2 -4
  42. package/dist/cli/commands/openspec-command-shared.js +2 -2
  43. package/dist/cli/commands/perf-audit-commands.js +15 -5
  44. package/dist/cli/commands/project-commands.js +9 -6
  45. package/dist/cli/commands/race-commands.d.ts +15 -0
  46. package/dist/cli/commands/race-commands.js +65 -0
  47. package/dist/cli/commands/race-pilot-gate-record-command.d.ts +3 -0
  48. package/dist/cli/commands/race-pilot-gate-record-command.js +81 -0
  49. package/dist/cli/commands/request-command-options.d.ts +8 -0
  50. package/dist/cli/commands/request-commands.js +2 -0
  51. package/dist/cli/commands/request-init-command.js +67 -12
  52. package/dist/cli/commands/{vm-status-command.d.ts → request-retag-command.d.ts} +1 -1
  53. package/dist/cli/commands/request-retag-command.js +50 -0
  54. package/dist/cli/commands/request-show-command.d.ts +8 -0
  55. package/dist/cli/commands/request-show-command.js +14 -1
  56. package/dist/cli/commands/request-transition-command.js +12 -4
  57. package/dist/cli/commands/request-transition-failures.d.ts +14 -0
  58. package/dist/cli/commands/request-transition-failures.js +76 -7
  59. package/dist/cli/commands/request-transition-preflight.js +1 -1
  60. package/dist/cli/commands/scan-scope-commands.js +2 -2
  61. package/dist/cli/commands/security-audit-commands.js +26 -6
  62. package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
  63. package/dist/cli/commands/verdict-aggregate-command.js +2 -1
  64. package/dist/cli/commands/workflow-gate-commands.js +4 -4
  65. package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
  66. package/dist/cli/program.js +0 -2
  67. package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
  68. package/dist/services/artifacts/artifact-contract-block.js +231 -0
  69. package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
  70. package/dist/services/artifacts/artifact-prerequisites.js +65 -135
  71. package/dist/services/artifacts/artifact-templates.d.ts +1 -1
  72. package/dist/services/artifacts/artifact-templates.js +17 -10
  73. package/dist/services/artifacts/prerequisite-checks.d.ts +87 -0
  74. package/dist/services/artifacts/prerequisite-checks.js +198 -0
  75. package/dist/services/artifacts/prerequisite-transition-event.d.ts +20 -0
  76. package/dist/services/artifacts/prerequisite-transition-event.js +27 -0
  77. package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
  78. package/dist/services/artifacts/rd-transition-gates.js +71 -0
  79. package/dist/services/artifacts/request-artifact-metadata.d.ts +31 -0
  80. package/dist/services/artifacts/request-artifact-metadata.js +44 -0
  81. package/dist/services/artifacts/request-artifact-service.d.ts +5 -0
  82. package/dist/services/artifacts/request-artifact-service.js +43 -69
  83. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +21 -1
  84. package/dist/services/artifacts/request-artifact-state-helpers.js +34 -8
  85. package/dist/services/artifacts/request-retag-service.d.ts +68 -0
  86. package/dist/services/artifacts/request-retag-service.js +125 -0
  87. package/dist/services/artifacts/request-state-order.d.ts +38 -0
  88. package/dist/services/artifacts/request-state-order.js +99 -0
  89. package/dist/services/artifacts/request-type-demand.d.ts +44 -0
  90. package/dist/services/artifacts/request-type-demand.js +71 -0
  91. package/dist/services/audit/audit-goal-service.d.ts +7 -0
  92. package/dist/services/audit/enforcers/active-skill-resolver.d.ts +18 -0
  93. package/dist/services/audit/enforcers/active-skill-resolver.js +48 -1
  94. package/dist/services/audit/enforcers/code-ban.d.ts +11 -2
  95. package/dist/services/audit/enforcers/code-ban.js +21 -1
  96. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.d.ts +17 -0
  97. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.js +24 -7
  98. package/dist/services/audit-independent/handoff-missing-refusal.d.ts +26 -0
  99. package/dist/services/audit-independent/handoff-missing-refusal.js +109 -0
  100. package/dist/services/audit-independent/handoff-readers.d.ts +37 -0
  101. package/dist/services/audit-independent/handoff-readers.js +81 -0
  102. package/dist/services/audit-independent/index.d.ts +6 -1
  103. package/dist/services/audit-independent/index.js +6 -1
  104. package/dist/services/audit-independent/judged-declaration-build.d.ts +48 -0
  105. package/dist/services/audit-independent/judged-declaration-build.js +73 -0
  106. package/dist/services/audit-independent/judged-declaration-check.d.ts +80 -0
  107. package/dist/services/audit-independent/judged-declaration-check.js +216 -0
  108. package/dist/services/audit-independent/judged-declaration.d.ts +94 -0
  109. package/dist/services/audit-independent/judged-declaration.js +218 -0
  110. package/dist/services/audit-independent/perf-audit-service.js +12 -14
  111. package/dist/services/audit-independent/security-audit-artifact.d.ts +28 -0
  112. package/dist/services/audit-independent/security-audit-artifact.js +90 -0
  113. package/dist/services/audit-independent/security-audit-service.d.ts +6 -53
  114. package/dist/services/audit-independent/security-audit-service.js +34 -178
  115. package/dist/services/capability-guard-runner/contracts/J05.js +60 -14
  116. package/dist/services/codegraph/codegraph-index-integrity.js +2 -0
  117. package/dist/services/context/build-dispatch-system-prompt.d.ts +8 -12
  118. package/dist/services/context/build-dispatch-system-prompt.js +18 -18
  119. package/dist/services/context/collector.js +5 -1
  120. package/dist/services/context/post-compact-reinjection.js +1 -1
  121. package/dist/services/dispatch/active-dispatch-index.d.ts +36 -0
  122. package/dist/services/dispatch/active-dispatch-index.js +118 -0
  123. package/dist/services/dispatch/batch-counter.js +1 -2
  124. package/dist/services/dispatch/dispatch-record-writer.d.ts +29 -16
  125. package/dist/services/dispatch/dispatch-record-writer.js +58 -100
  126. package/dist/services/dispatch/dispatch-sub-agent.js +1 -1
  127. package/dist/services/dispatch/karpathy-block.d.ts +55 -0
  128. package/dist/services/dispatch/karpathy-block.js +101 -0
  129. package/dist/services/dispatch/ledger-reaper.d.ts +80 -0
  130. package/dist/services/dispatch/ledger-reaper.js +131 -0
  131. package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
  132. package/dist/services/dispatch/test-tool-detection.js +12 -1
  133. package/dist/services/evidence/evidence-generator.js +23 -12
  134. package/dist/services/feedback/feedback-promotion-service.d.ts +8 -11
  135. package/dist/services/feedback/feedback-promotion-service.js +30 -35
  136. package/dist/services/feedback/promotion-artifact-json-evidence.d.ts +18 -0
  137. package/dist/services/feedback/promotion-artifact-missing.d.ts +22 -0
  138. package/dist/services/feedback/promotion-artifact-missing.js +63 -0
  139. package/dist/services/final-review/final-review-contract.d.ts +95 -4
  140. package/dist/services/final-review/final-review-contract.js +64 -0
  141. package/dist/services/final-review/final-review-delivery.d.ts +13 -0
  142. package/dist/services/final-review/final-review-delivery.js +26 -12
  143. package/dist/services/final-review/final-review-evidence-collect.js +8 -53
  144. package/dist/services/final-review/final-review-evidence-records.d.ts +21 -0
  145. package/dist/services/final-review/final-review-evidence-records.js +67 -0
  146. package/dist/services/final-review/final-review-evidence-sources.d.ts +22 -0
  147. package/dist/services/final-review/final-review-evidence-sources.js +28 -4
  148. package/dist/services/final-review/final-review-prompt.js +19 -6
  149. package/dist/services/final-review/final-review-runner.js +5 -0
  150. package/dist/services/final-review/final-review-service.d.ts +2 -2
  151. package/dist/services/final-review/index.d.ts +1 -1
  152. package/dist/services/final-review/pre-post-diff.d.ts +2 -75
  153. package/dist/services/final-review/pre-post-diff.js +60 -59
  154. package/dist/services/hooks/pre-tool-code-gate.d.ts +7 -1
  155. package/dist/services/hooks/pre-tool-code-gate.js +21 -2
  156. package/dist/services/hooks/worktree-authorization-gate.js +6 -31
  157. package/dist/services/hooks/worktree-refusal-messages.d.ts +74 -0
  158. package/dist/services/hooks/worktree-refusal-messages.js +102 -0
  159. package/dist/services/lint/eslint-runner-support.d.ts +1 -1
  160. package/dist/services/lint/eslint-runner-support.js +2 -1
  161. package/dist/services/lint/eslint-runner-types.d.ts +8 -0
  162. package/dist/services/lint/eslint-runner.js +17 -4
  163. package/dist/services/llm/anthropic-runner.js +24 -7
  164. package/dist/services/loop/loop-observability.d.ts +39 -0
  165. package/dist/services/loop/loop-observability.js +55 -0
  166. package/dist/services/loop/monotonic-guard.js +6 -9
  167. package/dist/services/loop/monotonic-runner.js +8 -7
  168. package/dist/services/loop/run-driver.js +18 -22
  169. package/dist/services/memory/project-memory-service/index/kind-dispatch.js +14 -1
  170. package/dist/services/memory/project-memory-service/index/project-memory-plan-exec.js +13 -2
  171. package/dist/services/memory/project-memory-service/index.d.ts +2 -2
  172. package/dist/services/memory/project-memory-service/index.js +1 -1
  173. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.d.ts +36 -0
  174. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.js +48 -2
  175. package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts +23 -1
  176. package/dist/services/memory/project-memory-service/parsers/markdown-pure.js +37 -0
  177. package/dist/services/memory/project-memory-service/types.d.ts +32 -0
  178. package/dist/services/observability/observability-service.d.ts +7 -0
  179. package/dist/services/observability/observability-service.js +2 -1
  180. package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
  181. package/dist/services/openspec/coverage-evidence-reader.js +8 -8
  182. package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
  183. package/dist/services/openspec/openspec-archive-service.js +6 -6
  184. package/dist/services/prd/gate-evidence-derivation.d.ts +4 -3
  185. package/dist/services/prd/gate-evidence-derivation.js +4 -3
  186. package/dist/services/qa/bdd-test-style-verifier.js +22 -8
  187. package/dist/services/race/gate2-evaluator.d.ts +58 -0
  188. package/dist/services/race/gate2-evaluator.js +111 -0
  189. package/dist/services/race/gate2-policy.d.ts +17 -0
  190. package/dist/services/race/gate2-policy.js +31 -0
  191. package/dist/services/race/lane-phase.d.ts +19 -0
  192. package/dist/services/race/lane-phase.js +113 -0
  193. package/dist/services/race/pilot-gate-store.d.ts +67 -0
  194. package/dist/services/race/pilot-gate-store.js +227 -0
  195. package/dist/services/scan/file-size-baseline.d.ts +33 -0
  196. package/dist/services/scan/file-size-baseline.js +173 -0
  197. package/dist/services/scan/file-size-scan.d.ts +35 -3
  198. package/dist/services/scan/file-size-scan.js +63 -42
  199. package/dist/services/scan/type-corroboration.d.ts +32 -0
  200. package/dist/services/scan/type-corroboration.js +51 -0
  201. package/dist/services/scan/type-sanity-service.d.ts +14 -0
  202. package/dist/services/scan/type-sanity-service.js +23 -22
  203. package/dist/services/security/safe-settings-path.d.ts +5 -0
  204. package/dist/services/security/safe-settings-path.js +64 -8
  205. package/dist/services/skill/resume-detector.js +11 -11
  206. package/dist/services/skills/hooks-codegate-superpowers.d.ts +5 -6
  207. package/dist/services/skills/hooks-codegate-superpowers.js +7 -8
  208. package/dist/services/skills/hooks-settings-service.d.ts +1 -1
  209. package/dist/services/skills/hooks-settings-service.js +1 -1
  210. package/dist/services/skills/presence-lease-order.d.ts +13 -0
  211. package/dist/services/skills/presence-lease-order.js +24 -0
  212. package/dist/services/skills/skill-conformance-service.js +1 -0
  213. package/dist/services/skills/skill-statusline-service.js +4 -7
  214. package/dist/services/slice/slice-check-service.js +8 -8
  215. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +24 -8
  216. package/dist/services/workflow/pipeline-verify-gate-support.js +34 -39
  217. package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
  218. package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
  219. package/dist/services/workflow/pipeline-verify-service.js +27 -28
  220. package/dist/services/workflow/request-type-resolution.d.ts +99 -0
  221. package/dist/services/workflow/request-type-resolution.js +130 -0
  222. package/dist/services/workflow/workflow-skip-service.d.ts +1 -20
  223. package/dist/services/workflow/workflow-skip-service.js +22 -25
  224. package/dist/services/workflow/workflow-state-store.d.ts +9 -0
  225. package/dist/services/workflow/workflow-state-store.js +26 -1
  226. package/dist/services/workspace/claude-settings-retirements.d.ts +54 -0
  227. package/dist/services/workspace/claude-settings-retirements.js +112 -0
  228. package/dist/services/workspace/claude-settings-template-merge.d.ts +35 -15
  229. package/dist/services/workspace/claude-settings-template-merge.js +33 -53
  230. package/dist/services/workspace/claude-settings-template.d.ts +62 -12
  231. package/dist/services/workspace/claude-settings-template.js +58 -58
  232. package/dist/services/workspace/migrate-1-4-1-service.js +3 -0
  233. package/dist/services/workspace/reconcile-service.js +0 -1
  234. package/dist/shared/incrementing-number.d.ts +33 -2
  235. package/dist/shared/incrementing-number.js +72 -3
  236. package/package.json +5 -7
  237. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  238. package/skills/bee/peaks-prd/SKILL.md +4 -3
  239. package/skills/bee/peaks-qa/SKILL.md +1 -1
  240. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  241. package/skills/bee/peaks-qa/references/qa-transition-gates.md +1 -1
  242. package/skills/bee/peaks-rd/SKILL.md +2 -2
  243. package/skills/bee/peaks-rd/references/rd-fanout-contracts.md +1 -1
  244. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +8 -4
  245. package/skills/bee/peaks-rd/references/rd-transition-gates.md +3 -3
  246. package/skills/bee/peaks-rd/references/v2-12-fanout-collapse.md +2 -2
  247. package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md +1 -1
  248. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  249. package/skills/bee/peaks-sc/SKILL.md +1 -1
  250. package/skills/bee/peaks-security-audit/SKILL.md +10 -2
  251. package/skills/bee/peaks-txt/SKILL.md +4 -3
  252. package/skills/bee/peaks-ui/SKILL.md +3 -3
  253. package/skills/peaks-audit/SKILL.md +29 -1
  254. package/skills/peaks-code/SKILL.md +37 -17
  255. package/skills/peaks-code/references/fast-lane-norm.md +42 -0
  256. package/skills/peaks-code/references/fast-mode.md +3 -2
  257. package/skills/peaks-code/references/local-artifact-workspace.md +3 -3
  258. package/skills/peaks-code/references/micro-cycle.md +3 -3
  259. package/skills/peaks-code/references/resume-detection.md +1 -1
  260. package/skills/peaks-code/references/runbook.md +12 -6
  261. package/skills/peaks-code/references/step-11-memory-sediment.md +4 -0
  262. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  263. package/skills/peaks-code/references/swarm-dispatch-contract.md +40 -16
  264. package/skills/peaks-code/references/workflow-gates-and-types.md +6 -6
  265. package/skills/peaks-code/references/worktree-governance.md +4 -4
  266. package/skills/peaks-content/SKILL.md +1 -1
  267. package/skills/peaks-doctor/SKILL.md +1 -1
  268. package/skills/peaks-final-review/SKILL.md +31 -11
  269. package/skills/peaks-ide/SKILL.md +1 -1
  270. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  271. package/skills/peaks-race-code/SKILL.md +185 -0
  272. package/skills/peaks-resume/SKILL.md +1 -1
  273. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  274. package/skills/peaks-solo/SKILL.md +1 -1
  275. package/skills/peaks-sop/SKILL.md +1 -1
  276. package/skills/peaks-status/SKILL.md +1 -1
  277. package/skills/peaks-test/SKILL.md +7 -4
  278. package/dist/cli/commands/vm-command-shared.d.ts +0 -23
  279. package/dist/cli/commands/vm-command-shared.js +0 -23
  280. package/dist/cli/commands/vm-commands.d.ts +0 -3
  281. package/dist/cli/commands/vm-commands.js +0 -45
  282. package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
  283. package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
  284. package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
  285. package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
  286. package/dist/cli/commands/vm-release-command.d.ts +0 -5
  287. package/dist/cli/commands/vm-release-command.js +0 -101
  288. package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
  289. package/dist/cli/commands/vm-spawn-command.js +0 -177
  290. package/dist/cli/commands/vm-status-command.js +0 -50
  291. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.d.ts +0 -23
  292. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.js +0 -64
  293. package/dist/services/vm/vm-lease.d.ts +0 -40
  294. package/dist/services/vm/vm-lease.js +0 -160
@@ -0,0 +1,131 @@
1
+ /**
2
+ * The active-dispatches ledger reaper: the bound that stops the index growing
3
+ * with the session, and the decision about which rows it may act on.
4
+ *
5
+ * Split out of `./active-dispatch-index.ts` (that module owns the index FORMAT —
6
+ * register, unregister, read; this one owns the POLICY). Why a reaper exists at
7
+ * all: nothing ever finalized a dispatch. Measured 2026-10-12 across four
8
+ * sessions, `queued`/total was 39/39, 2/2, 9/9, 23/23 — not one record in any
9
+ * session had been finalized, and a recovery verb built for the purpose
10
+ * (`peaks sub-agent finalize --all-stale`) did not help, because building a verb
11
+ * does not make anyone call it. So the bound is applied by the tooling, at the
12
+ * one moment the index can grow: the next dispatch write.
13
+ */
14
+ import { assertSafeDispatchRecordPath } from '../security/safe-settings-path.js';
15
+ import { readActiveDispatchIndex, unregisterActiveDispatch } from './active-dispatch-index.js';
16
+ const MINUTES_PER_HOUR = 60;
17
+ const MS_PER_MINUTE = 60_000;
18
+ /** The bound, in hours. Named so the constant below states a policy, not a `6`. */
19
+ const LEDGER_REAP_BOUND_HOURS = 6;
20
+ /**
21
+ * How long a row may sit in the index still `queued` before the next dispatch
22
+ * write reaps it.
23
+ *
24
+ * Six hours, from the ledger's own data rather than a round number: the ACTIVE
25
+ * session's index spans 8.6 hours and holds 18 entries, all `queued`; the
26
+ * largest gap between two dispatches in it is 4h19m. The bound must clear the
27
+ * longest dispatch a session can legitimately still be running, and 6h is above
28
+ * every dispatch interval this ledger records while staying two orders of
29
+ * magnitude tighter than the 30-day `DISPATCH_RECORD_TTL_DAYS` file GC.
30
+ *
31
+ * Only a row whose RECORD is still `queued` is reaped. The residual risk is
32
+ * recorded rather than hidden: a sub-agent still running when the session
33
+ * dispatches again after a longer-than-six-hour gap has its bookkeeping cleared
34
+ * early. Its work is unaffected; its later finalize call finds nothing `queued`
35
+ * and reports that.
36
+ *
37
+ * One thing the reap inherits rather than causes, recorded because it is
38
+ * invisible otherwise: `markCompleted` also attempts a graph `envelope-received`
39
+ * transition, and the reaped records are graph-bound. That transition is inert —
40
+ * measured 2026-10-13, 54/54 nodes in `.peaks/_runtime/<sessionId>/graphs/` are
41
+ * still `prepared` — so the reap changes no graph state. Documented, not fixed.
42
+ */
43
+ export const LEDGER_REAP_BOUND_MS = LEDGER_REAP_BOUND_HOURS * MINUTES_PER_HOUR * MS_PER_MINUTE;
44
+ /**
45
+ * Sentinel for a row that names nothing this module may act on: a path outside
46
+ * the ledger (the guard refuses it) or a record file that is absent. Distinct
47
+ * from `unreadable`, which is a real status meaning "a record I may not
48
+ * rewrite" — the two must not be collapsed, because the first is a row to drop
49
+ * and the second is a row to keep.
50
+ */
51
+ const UNUSABLE_ROW = 'unusable-row';
52
+ /**
53
+ * The record's status. The path guard runs HERE, before the record is read,
54
+ * because the row names a path this function goes on to write to; a refused
55
+ * path returns {@link UNUSABLE_ROW} rather than a status, so a refused row is
56
+ * never read and never mistaken for a readable one.
57
+ */
58
+ function readStatusGuarded(input, recordPath) {
59
+ try {
60
+ assertSafeDispatchRecordPath(recordPath, input.projectRoot);
61
+ }
62
+ catch {
63
+ return UNUSABLE_ROW;
64
+ }
65
+ return input.readStatus(recordPath) ?? UNUSABLE_ROW;
66
+ }
67
+ /** Decide one row, from the row and the record it names. */
68
+ function decideRow(input, recordPath, entry, cutoffMs) {
69
+ if (entry.status !== 'queued')
70
+ return 'keep';
71
+ const createdAtMs = Date.parse(entry.createdAt);
72
+ if (!Number.isFinite(createdAtMs) || createdAtMs >= cutoffMs)
73
+ return 'keep';
74
+ const recordStatus = readStatusGuarded(input, recordPath);
75
+ if (recordStatus === 'queued')
76
+ return 'reap';
77
+ if (recordStatus === UNUSABLE_ROW)
78
+ return 'drop';
79
+ return 'keep';
80
+ }
81
+ /** Remove a row from the index without touching the record it named. */
82
+ function dropRow(input, recordPath) {
83
+ unregisterActiveDispatch({
84
+ projectRoot: input.projectRoot,
85
+ sessionId: input.sessionId,
86
+ recordPath,
87
+ status: 'no-execution'
88
+ });
89
+ }
90
+ /**
91
+ * Finalize every index row whose RECORD is still `queued` past the bound, and
92
+ * drop it from the index. Called at the start of `writeInitialDispatchRecord`,
93
+ * i.e. at the next dispatch write — the exact moment the index would grow.
94
+ *
95
+ * A row is dropped without finalizing when it names no usable record: a path
96
+ * outside `.peaks/_sub_agents/`, or a file that is absent. A row pointing at no
97
+ * record is stale by definition.
98
+ *
99
+ * The row is only a hint. The RECORD decides: `running` / `finalizing` is a live
100
+ * dispatch and is left alone however old it is, and a record the writer already
101
+ * terminated is left to that writer. Only a record still `queued` — never
102
+ * started AND never finalized — is reaped. (This is the distinction that
103
+ * matters: `no-execution` is terminal for the heartbeat pollers, so reaping a
104
+ * live record would stop a watcher waiting on it.)
105
+ */
106
+ export function reapStaleQueuedEntries(input) {
107
+ const now = input.now ?? (() => new Date());
108
+ const boundMs = input.boundMs ?? LEDGER_REAP_BOUND_MS;
109
+ const cutoffMs = now().getTime() - boundMs;
110
+ const index = readActiveDispatchIndex(input.projectRoot, input.sessionId);
111
+ const reaped = [];
112
+ for (const [recordPath, entry] of Object.entries(index)) {
113
+ const decision = decideRow(input, recordPath, entry, cutoffMs);
114
+ if (decision === 'keep')
115
+ continue;
116
+ reaped.push(recordPath);
117
+ if (decision === 'drop') {
118
+ dropRow(input, recordPath);
119
+ continue;
120
+ }
121
+ try {
122
+ input.finalize(recordPath);
123
+ }
124
+ catch {
125
+ // The reader said `queued` and the writer could not turn it terminal;
126
+ // drop the row so it cannot accumulate.
127
+ dropRow(input, recordPath);
128
+ }
129
+ }
130
+ return { reaped };
131
+ }
@@ -36,11 +36,20 @@
36
36
  * examples. No role split remains, so every role receives a byte-identical
37
37
  * block.
38
38
  */
39
- export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nRead `package.json#scripts.test` for the project's framework and use the project-local runner \u2014 do NOT invoke `npx <runner>`. If unsure, run `peaks test --json` first. Only as a last resort, ask the user before assuming a runner. `peaks test <file>` already resolves the local binary for you (Windows-aware).\n\n## Test Scope (mandatory)\n\nAny test command MUST be **scoped** to a single file or pattern; a bare `./node_modules/.bin/vitest run` is **refused** unless you prefix the explicit opt-in token `PEAKS_FULL_TEST=1` (CI / release verification only, never routine slice verification).\n\nRepo-defined `test` / `test:*` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).";
39
+ export declare const TEST_TOOL_DETECTION_BLOCK = "## Test Tool Detection (mandatory)\n\nRead `package.json#scripts.test` for the project's framework and use the project-local runner \u2014 do NOT invoke `npx <runner>`. If unsure, run `peaks test --json` first. Only as a last resort, ask the user before assuming a runner. `peaks test <file>` already resolves the local binary for you (Windows-aware).\n\n## Test Scope (mandatory)\n\nAny test command MUST be **scoped** to a single file or pattern \u2014 a bare `./node_modules/.bin/vitest run` is **not permitted** without the explicit opt-in token `PEAKS_FULL_TEST=1` (CI / release verification only, never routine slice verification). Nothing inspects the command you run: this is a rule you follow, not a gate that fires.\n\nA suite whose subject is the tree, not one file, is in scope for every slice, whatever the slice changed \u2014 it can go red for a change outside its own subtree. This repo's tier is `tests/unit/standards`, `tests/unit/lint` and the root of `tests/unit/` (`tests/unit/*.test.ts`): add all three to a slice's run, once per slice rather than per reviewer pass.\n\nRepo-defined `test` / `test:*` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).";
40
40
  /**
41
41
  * Pure helper that returns the block. Exists as a function (not just an
42
42
  * exported constant) so future variants can take a runtime parameter
43
43
  * (e.g. projectRoot for context) without churning every call site.
44
+ *
45
+ * The whole-tree tier (2026-10-16) names `tests/unit/standards`, `tests/unit/lint`
46
+ * and the root of `tests/unit/` (`tests/unit/*.test.ts`). A file-scoped run cannot
47
+ * cover a suite whose subject is the tree: the push gate's area rule turns
48
+ * `src/<area>` into `tests/unit/<area>`, and no guard directory has an area of its
49
+ * own to be reached through. That gap is a HAND-run's alone — the classifier's
50
+ * `subset()` unions the whole tier into every subset verdict, so the gate reaches
51
+ * the tier on every diff it runs at all. The one diff it does NOT run is gate data
52
+ * alone whose content did not move: that verdict selects 0 tests, root tier included.
44
53
  */
45
54
  export declare function formatTestToolDetection(): string;
46
55
  /**
@@ -49,6 +58,13 @@ export declare function formatTestToolDetection(): string;
49
58
  * whether the command is allowed, refused, or requires the explicit
50
59
  * opt-in.
51
60
  *
61
+ * NO CALLER YET, stated so the next reader does not look for one: nothing
62
+ * under `src/`, `tests/` or `scripts/` imports this. The dispatch block
63
+ * states the scope as a rule the agent follows, and does not claim a run is
64
+ * refused — wiring this into the `peaks test` CLI or a hook is a separate
65
+ * change with its own blast radius, and it is the owner's call, not a
66
+ * consequence of the rule text.
67
+ *
52
68
  * - 'scoped' — the command names a file/pattern after `run`
53
69
  * - 'opt-in' — the user/LLM set PEAKS_FULL_TEST=1 to override
54
70
  * - 'refused' — bare `vitest run` with no path and no opt-in
@@ -42,13 +42,24 @@ Read \`package.json#scripts.test\` for the project's framework and use the proje
42
42
 
43
43
  ## Test Scope (mandatory)
44
44
 
45
- Any test command MUST be **scoped** to a single file or pattern; a bare \`./node_modules/.bin/vitest run\` is **refused** unless you prefix the explicit opt-in token \`PEAKS_FULL_TEST=1\` (CI / release verification only, never routine slice verification).
45
+ Any test command MUST be **scoped** to a single file or pattern — a bare \`./node_modules/.bin/vitest run\` is **not permitted** without the explicit opt-in token \`PEAKS_FULL_TEST=1\` (CI / release verification only, never routine slice verification). Nothing inspects the command you run: this is a rule you follow, not a gate that fires.
46
+
47
+ A suite whose subject is the tree, not one file, is in scope for every slice, whatever the slice changed — it can go red for a change outside its own subtree. This repo's tier is \`tests/unit/standards\`, \`tests/unit/lint\` and the root of \`tests/unit/\` (\`tests/unit/*.test.ts\`): add all three to a slice's run, once per slice rather than per reviewer pass.
46
48
 
47
49
  Repo-defined \`test\` / \`test:*\` scripts are the human/LLM direct path and are NOT gated by this scope rule (PB-5).`;
48
50
  /**
49
51
  * Pure helper that returns the block. Exists as a function (not just an
50
52
  * exported constant) so future variants can take a runtime parameter
51
53
  * (e.g. projectRoot for context) without churning every call site.
54
+ *
55
+ * The whole-tree tier (2026-10-16) names `tests/unit/standards`, `tests/unit/lint`
56
+ * and the root of `tests/unit/` (`tests/unit/*.test.ts`). A file-scoped run cannot
57
+ * cover a suite whose subject is the tree: the push gate's area rule turns
58
+ * `src/<area>` into `tests/unit/<area>`, and no guard directory has an area of its
59
+ * own to be reached through. That gap is a HAND-run's alone — the classifier's
60
+ * `subset()` unions the whole tier into every subset verdict, so the gate reaches
61
+ * the tier on every diff it runs at all. The one diff it does NOT run is gate data
62
+ * alone whose content did not move: that verdict selects 0 tests, root tier included.
52
63
  */
53
64
  export function formatTestToolDetection() {
54
65
  return TEST_TOOL_DETECTION_BLOCK;
@@ -34,6 +34,8 @@ import { handoffRelativePath, sha256OfBody } from '../prd/handoff-service.js';
34
34
  import { getSessionDir } from '../session/getSessionDir.js';
35
35
  import { REQUEST_ID_PATTERN } from '../artifacts/request-artifact-service.js';
36
36
  import { isUnsafePathInput } from '../../shared/path-safety.js';
37
+ import { requestIdFromFileName, slugifyDescription } from '../../shared/incrementing-number.js';
38
+ import { renderJudgedSection } from '../audit-independent/judged-declaration-build.js';
37
39
  import { buildCodeReview, buildKarpathyReview, buildPerfAudit, buildPerformanceFindings, buildQaRequest, buildSecurityFindings, buildSecurityReview, buildTechDoc, buildTestCases, buildTestReport, filesMd, lineCountsMd } from './evidence-body-builders.js';
38
40
  /** Comma/space tolerant `--files` splitter. */
39
41
  export function parseFiles(raw) {
@@ -104,19 +106,22 @@ ${lineCountsMd(lineCounts)}
104
106
  };
105
107
  return { content: `${serializeHandoffFrontmatter(frontmatter)}${body}`, hash: handoffHash };
106
108
  }
107
- /** Find the existing numbered QA request file for `rid`, else the default. */
109
+ /** Find the QA request file whose carried id is `rid`, else the default. */
108
110
  async function resolveQaRequestPath(qaDir, rid) {
109
- const suffix = `-${rid}.md`;
110
111
  try {
111
112
  const entries = await readdir(join(qaDir, 'requests'));
112
- const match = entries.find((name) => /^\d+-/.test(name) && name.endsWith(suffix));
113
+ // The operand is the SLUG, as it is at the two `request-artifact-service.ts`
114
+ // sites: the writer lowercases the rid into the filename, so comparing a
115
+ // carried id against the raw rid answers a different question about the same
116
+ // file and misses it whenever the rid carries a capital.
117
+ const match = entries.find((name) => requestIdFromFileName(name) === slugifyDescription(rid));
113
118
  if (match !== undefined)
114
119
  return join(qaDir, 'requests', match);
115
120
  }
116
121
  catch {
117
122
  // directory missing — fall through to the default numbered name
118
123
  }
119
- return join(qaDir, 'requests', `001-${rid}.md`);
124
+ return join(qaDir, 'requests', `001-${slugifyDescription(rid)}.md`);
120
125
  }
121
126
  export async function generateEvidence(options) {
122
127
  const { projectRoot, rid, title, files, lineCounts, sessionId } = options;
@@ -158,22 +163,28 @@ export async function generateEvidence(options) {
158
163
  requestId: rid
159
164
  });
160
165
  const handoff = buildHandoff(rid, sessionId, title, files, lineCounts, gateEvidence);
166
+ // This generator has no surface of its own to declare, so it declares the
167
+ // paths it was handed. Given none, the section is empty and the audit
168
+ // artifact is refused by the check — declaring nothing is the case the
169
+ // contract exists to refuse, not one to paper over here.
170
+ const judgedSection = renderJudgedSection(projectRoot, files);
161
171
  // Four of these twelve paths carry the rid because the `rd:qa-handoff` gate
162
172
  // requires `<rid>` in them: every slice in a session shares `rd/` and
163
173
  // `audit/`, so writing the ridless name silently destroyed the previous
164
174
  // slice's evidence on 2026-09-13 while the gate stayed green (slice
165
175
  const writes = [
166
176
  [join(rdDir, `code-review-${rid}.md`), buildCodeReview(rid, title, files, lineCounts)],
167
- [join(auditDir, `security-${rid}.md`), buildSecurityReview(rid)],
177
+ [join(auditDir, `security-${rid}.md`), buildSecurityReview(rid) + judgedSection],
168
178
  // ...but the `config` type is the one whose `rd:qa-handoff` row is
169
- // `SECURITY_REVIEW` — the genuinely ridless `rd/security-review.md` — and
170
- // this generator is request-type-agnostic (no `--request-type`). So it
171
- // (`AUDIT_SECURITY`) and the bare one `config` resolves. Nothing is lost
172
- // by having both; a `config` slice has nothing else to fall back on, and
173
- // dropping this write made a `config` slice fail its own gate while the
174
- // generator reported success (repair round: measured `missing:
179
+ // `SECURITY_REVIEW`, and this generator is request-type-agnostic (no
180
+ // `--request-type`). So both this write (`AUDIT_SECURITY`) and the scoped
181
+ // one below are emitted, or a `config` slice fails its own gate while the
182
+ // generator reports success (measured then as `missing:
175
183
  // ['rd/security-review.md']` with the real generator and the real gate).
176
- [join(rdDir, 'security-review.md'), buildSecurityReview(rid)],
184
+ // The rid is now in that name too: the ridless one was overwritten by the
185
+ // second config slice in a session, and the prereq pins no body, so the
186
+ // first slice's review vanished without a single check reporting it.
187
+ [join(rdDir, `security-review-${rid}.md`), buildSecurityReview(rid)],
177
188
  [join(rdDir, `karpathy-review-${rid}.md`), buildKarpathyReview(rid, lineCounts)],
178
189
  // `rd/tech-doc.md` stays ridless on purpose: the TECH_DOC prereq was
179
190
  // sibling that anything reads.
@@ -24,8 +24,10 @@
24
24
  * The comment marker is the SOURCE OF TRUTH for human review; the sidecar is
25
25
  * the source of truth for the scanner. Neither is evidence on its own.
26
26
  */
27
- import { type PromotionArtifactCheck, type PromotionEvidence } from './promotion-artifact-evidence.js';
27
+ import { missingArtifacts } from './promotion-artifact-missing.js';
28
+ import type { PromotionArtifactCheck, PromotionEvidence } from './promotion-artifact-evidence.js';
28
29
  export type { PromotionArtifactCheck, PromotionEvidence };
30
+ export { missingArtifacts };
29
31
  export type PromotionLayer = 'A' | 'B' | 'C';
30
32
  export declare const PROMOTION_LAYERS: readonly PromotionLayer[];
31
33
  export type PromotionLayerDetail = {
@@ -52,9 +54,11 @@ export declare const PROMOTION_LAYER_DETAILS: readonly PromotionLayerDetail[];
52
54
  * decoration: `gate-enforce-service.enforceBashCommand` enumerates SOPs via
53
55
  * `readRegistry()`, so an unregistered manifest is off the enforcement path
54
56
  * no matter how valid it is.
55
- * - B (peaks-hooks PreToolUse): `.peaks/.claude-settings-template.json` must
56
- * register the rule inside its `hooks` block. The file always exists, so
57
- * existence proves nothing — the evidence is the registration inside it.
57
+ * - B (peaks-hooks PreToolUse): the `hooks` block of one of the two settings
58
+ * files in `LAYER_B_SETTINGS` — the `.peaks/.claude-settings-template.json`
59
+ * snapshot, or this repository's tracked `.claude/settings.json` — must
60
+ * register the rule. The file always exists, so existence proves nothing:
61
+ * the evidence is the registration inside it.
58
62
  * - C (mode-gate hardFloorCategory): `src/services/code/mode-gate.ts` must
59
63
  * register the rule in the hard-floor vocabulary, for the same reason. This
60
64
  * is the repo's existing convention: the one real layer-C promotion cites
@@ -78,13 +82,6 @@ export declare const PROMOTION_LAYER_DETAILS: readonly PromotionLayerDetail[];
78
82
  export declare function sopIdForFeedback(memoryName: string): string;
79
83
  /** The artifact(s) and the structural evidence each must carry for `layer` to mean anything. */
80
84
  export declare function promotionArtifactChecks(memoryName: string, layer: PromotionLayer): PromotionArtifactCheck[];
81
- /**
82
- * Which of `checks` are not satisfied under `projectRoot`. Empty means the
83
- * promotion is backed by its artifact. Never throws, and never permits: a file
84
- * that is absent, unreadable, or unparseable is a finding, not a warning —
85
- * "cannot read the evidence" must not read as "the evidence is good".
86
- */
87
- export declare function missingArtifacts(checks: readonly PromotionArtifactCheck[], projectRoot: string): string[];
88
85
  export type FeedbackMemory = {
89
86
  /** File basename (without `.md`). */
90
87
  name: string;
@@ -28,7 +28,8 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from
28
28
  import { dirname, join, resolve } from 'node:path';
29
29
  import { registerSop } from '../sop/sop-registry-service.js';
30
30
  import { projectRegistryPath, projectSopManifestPath } from '../sop/sop-paths.js';
31
- import { artifactEvidenceFailure } from './promotion-artifact-evidence.js';
31
+ import { missingArtifacts } from './promotion-artifact-missing.js';
32
+ export { missingArtifacts };
32
33
  /**
33
34
  * PRD-002b slice 2 — extract magic numbers used by the promotion
34
35
  * helper. `slice(0, 5)` was used as a heuristic on the user's body
@@ -47,7 +48,7 @@ export const PROMOTION_LAYER_DETAILS = [
47
48
  {
48
49
  layer: 'B',
49
50
  label: 'peaks-hooks PreToolUse',
50
- description: 'Append a matcher to .peaks/.claude-settings-template.json. Tool-call interception.'
51
+ description: 'Append a matcher to `.peaks/.claude-settings-template.json`, or to `.claude/settings.json` for a hook that ships with this repository. Tool-call interception.'
51
52
  },
52
53
  {
53
54
  layer: 'C',
@@ -72,9 +73,11 @@ export const PROMOTION_LAYER_DETAILS = [
72
73
  * decoration: `gate-enforce-service.enforceBashCommand` enumerates SOPs via
73
74
  * `readRegistry()`, so an unregistered manifest is off the enforcement path
74
75
  * no matter how valid it is.
75
- * - B (peaks-hooks PreToolUse): `.peaks/.claude-settings-template.json` must
76
- * register the rule inside its `hooks` block. The file always exists, so
77
- * existence proves nothing — the evidence is the registration inside it.
76
+ * - B (peaks-hooks PreToolUse): the `hooks` block of one of the two settings
77
+ * files in `LAYER_B_SETTINGS` — the `.peaks/.claude-settings-template.json`
78
+ * snapshot, or this repository's tracked `.claude/settings.json` — must
79
+ * register the rule. The file always exists, so existence proves nothing:
80
+ * the evidence is the registration inside it.
78
81
  * - C (mode-gate hardFloorCategory): `src/services/code/mode-gate.ts` must
79
82
  * register the rule in the hard-floor vocabulary, for the same reason. This
80
83
  * is the repo's existing convention: the one real layer-C promotion cites
@@ -110,7 +113,8 @@ export function promotionArtifactChecks(memoryName, layer) {
110
113
  if (layer === 'B') {
111
114
  return [
112
115
  {
113
- path: '.peaks/.claude-settings-template.json',
116
+ path: LAYER_B_SETTINGS[0],
117
+ alternatives: [LAYER_B_SETTINGS[1]],
114
118
  evidence: 'hook-registration',
115
119
  id: memoryName
116
120
  }
@@ -121,34 +125,25 @@ export function promotionArtifactChecks(memoryName, layer) {
121
125
  ];
122
126
  }
123
127
  /**
124
- * Which of `checks` are not satisfied under `projectRoot`. Empty means the
125
- * promotion is backed by its artifact. Never throws, and never permits: a file
126
- * that is absent, unreadable, or unparseable is a finding, not a warning —
127
- * "cannot read the evidence" must not read as "the evidence is good".
128
+ * The settings files a layer-B hook registration may legitimately live in.
129
+ *
130
+ * TWO locations, because there are two audiences and only one file each.
131
+ * `peaks workspace init` writes `.peaks/.claude-settings-template.json` in every
132
+ * project, consumer or not, so it is tried first. This repository's own
133
+ * development hooks are registered in the tracked `.claude/settings.json`
134
+ * instead — the template above is written into a CONSUMER tree, where
135
+ * `${CLAUDE_PROJECT_DIR}/src/**` names nothing, so a hook of ours cannot live
136
+ * there. Checking only the snapshot reports a rule that IS enforced as
137
+ * unpromoted; checking only the tracked file breaks every consumer.
138
+ *
139
+ * `.claude/settings.local.json` is deliberately NOT a third location: a rule
140
+ * backed only by that untracked file is the "true on one machine" state this
141
+ * artifact check exists to reject.
128
142
  */
129
- export function missingArtifacts(checks, projectRoot) {
130
- const missing = [];
131
- for (const check of checks) {
132
- const absolute = resolve(projectRoot, check.path);
133
- if (!existsSync(absolute)) {
134
- missing.push(`${check.path} (absent)`);
135
- continue;
136
- }
137
- let text;
138
- try {
139
- text = readFileSync(absolute, 'utf8');
140
- }
141
- catch {
142
- missing.push(`${check.path} (unreadable)`);
143
- continue;
144
- }
145
- const failure = artifactEvidenceFailure(check, text);
146
- if (failure !== null) {
147
- missing.push(`${check.path} (${failure})`);
148
- }
149
- }
150
- return missing;
151
- }
143
+ const LAYER_B_SETTINGS = [
144
+ '.peaks/.claude-settings-template.json',
145
+ '.claude/settings.json'
146
+ ];
152
147
  const COMMENT_MARKER_RE = /<!--\s*peaks-feedback-promoted:\s*layer=([ABC])\s*-->/;
153
148
  /**
154
149
  * declaration.
@@ -518,8 +513,8 @@ export function generatePromotionStub(opts) {
518
513
  }
519
514
  if (layer === 'B') {
520
515
  return {
521
- snippet: `{\n "matcher": "Bash",\n "hooks": [\n {\n "type": "command",\n "command": "node -e \\"process.exit(0)\\""\n }\n ]\n}\n<!-- Append the rule-specific matcher to .peaks/.claude-settings-template.json -->`,
522
- targetFiles: ['.peaks/.claude-settings-template.json']
516
+ snippet: `{\n "matcher": "Bash",\n "hooks": [\n {\n "type": "command",\n "command": "node -e \\"process.exit(0)\\""\n }\n ]\n}\n<!-- Append the rule-specific matcher to .peaks/.claude-settings-template.json, or to .claude/settings.json for a hook that ships with this repository -->`,
517
+ targetFiles: [...LAYER_B_SETTINGS]
523
518
  };
524
519
  }
525
520
  // layer === 'C'
@@ -18,6 +18,24 @@ export type PromotionEvidence =
18
18
  export type PromotionArtifactCheck = {
19
19
  /** Project-relative POSIX path whose CONTENT must carry the evidence. */
20
20
  path: string;
21
+ /**
22
+ * Other project-relative paths where the SAME evidence may legitimately live.
23
+ *
24
+ * The conjunction is across CHECKS — layer A needs its manifest AND its
25
+ * registry entry — so an alternative location cannot be expressed as another
26
+ * check: that would demand it too. It belongs here, where the sense is OR.
27
+ *
28
+ * Layer B is the reason the field exists. Its registration is written into
29
+ * whichever Claude settings file the project actually reads: a consumer gets
30
+ * the generated snapshot, while this repository registers its own development
31
+ * hooks in the tracked `.claude/settings.json` — the template that produces the
32
+ * snapshot is written into a consumer tree, where a command naming
33
+ * `${CLAUDE_PROJECT_DIR}/src/**` resolves to nothing.
34
+ *
35
+ * `artifactEvidenceFailure` reads `evidence` and `id` only, so the same check
36
+ * is tried against every candidate as it stands.
37
+ */
38
+ alternatives?: readonly string[];
21
39
  evidence: PromotionEvidence;
22
40
  /** The rule id the evidence must name (a SOP id for layer A, a memory name for B and C). */
23
41
  id: string;
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The reader half of the promotion-artifact concern: which of a layer's required
3
+ * artifacts are NOT present, under a given project root.
4
+ *
5
+ * Extracted from `./feedback-promotion-service.ts` for the file-size cap, the way
6
+ * `./promotion-artifact-evidence.ts` was extracted before it. That module builds
7
+ * the decision from a file's text; this one decides whether the file is there to
8
+ * read. The service re-exports `missingArtifacts` from its own path, so no
9
+ * importer changed.
10
+ */
11
+ import { type PromotionArtifactCheck } from './promotion-artifact-evidence.js';
12
+ /**
13
+ * Which of `checks` are not satisfied under `projectRoot`. Empty means the
14
+ * promotion is backed by its artifact. Never throws, and never permits: a file
15
+ * that is absent, unreadable, or unparseable is a finding, not a warning —
16
+ * "cannot read the evidence" must not read as "the evidence is good".
17
+ *
18
+ * A check is satisfied when `path` OR any of its `alternatives` carries the
19
+ * evidence; one that no candidate satisfies is reported ONCE, naming every
20
+ * location it looked in, so a reader is never told about half the search.
21
+ */
22
+ export declare function missingArtifacts(checks: readonly PromotionArtifactCheck[], projectRoot: string): string[];
@@ -0,0 +1,63 @@
1
+ /**
2
+ * The reader half of the promotion-artifact concern: which of a layer's required
3
+ * artifacts are NOT present, under a given project root.
4
+ *
5
+ * Extracted from `./feedback-promotion-service.ts` for the file-size cap, the way
6
+ * `./promotion-artifact-evidence.ts` was extracted before it. That module builds
7
+ * the decision from a file's text; this one decides whether the file is there to
8
+ * read. The service re-exports `missingArtifacts` from its own path, so no
9
+ * importer changed.
10
+ */
11
+ import { existsSync, readFileSync } from 'node:fs';
12
+ import { resolve } from 'node:path';
13
+ import { artifactEvidenceFailure } from './promotion-artifact-evidence.js';
14
+ /**
15
+ * Which of `checks` are not satisfied under `projectRoot`. Empty means the
16
+ * promotion is backed by its artifact. Never throws, and never permits: a file
17
+ * that is absent, unreadable, or unparseable is a finding, not a warning —
18
+ * "cannot read the evidence" must not read as "the evidence is good".
19
+ *
20
+ * A check is satisfied when `path` OR any of its `alternatives` carries the
21
+ * evidence; one that no candidate satisfies is reported ONCE, naming every
22
+ * location it looked in, so a reader is never told about half the search.
23
+ */
24
+ export function missingArtifacts(checks, projectRoot) {
25
+ const missing = [];
26
+ for (const check of checks) {
27
+ const failures = candidateFailures(check, projectRoot);
28
+ if (failures !== null)
29
+ missing.push(failures.join('; '));
30
+ }
31
+ return missing;
32
+ }
33
+ /**
34
+ * One `${path} (${reason})` per location that does NOT back `check`, or `null`
35
+ * when one of them does. `null` and `[]` are different answers, which is why the
36
+ * caller gets the distinction rather than an empty array.
37
+ *
38
+ * `check.alternatives` exists because a layer may legitimately keep its one
39
+ * artifact in more than one place; the conjunction is across CHECKS, so an
40
+ * alternative location cannot be spelled as another check without demanding it.
41
+ */
42
+ function candidateFailures(check, projectRoot) {
43
+ const failures = [];
44
+ for (const candidate of [check.path, ...(check.alternatives ?? [])]) {
45
+ const absolute = resolve(projectRoot, candidate);
46
+ if (!existsSync(absolute)) {
47
+ failures.push(`${candidate} (absent)`);
48
+ continue;
49
+ }
50
+ let text;
51
+ try {
52
+ text = readFileSync(absolute, 'utf8');
53
+ }
54
+ catch {
55
+ failures.push(`${candidate} (unreadable)`);
56
+ continue;
57
+ }
58
+ const failure = artifactEvidenceFailure(check, text);
59
+ if (failure !== null)
60
+ failures.push(`${candidate} (${failure})`);
61
+ }
62
+ return failures.length === 1 + (check.alternatives?.length ?? 0) ? failures : null;
63
+ }
@@ -1,12 +1,20 @@
1
+ /**
2
+ * A completed model call's token accounting: the two counts an observability
3
+ * reader sums, plus a tag saying whether the provider reported them or the
4
+ * runner estimated them. `source` is optional so a runner that always has
5
+ * provider numbers — or a test fake — need not state it.
6
+ */
7
+ export interface LlmTokenUsage {
8
+ readonly input: number;
9
+ readonly output: number;
10
+ readonly source?: 'provider' | 'estimated';
11
+ }
1
12
  export interface LlmRunner {
2
13
  call(systemPrompt: string, userPrompt: string, opts: {
3
14
  maxTokens: number;
4
15
  }): Promise<{
5
16
  output: string;
6
- tokens: {
7
- input: number;
8
- output: number;
9
- };
17
+ tokens: LlmTokenUsage;
10
18
  }>;
11
19
  }
12
20
  export interface PrepareFinalReviewOptions {
@@ -19,8 +27,91 @@ export interface PrepareFinalReviewOptions {
19
27
  * reports the dimension `unavailable` when it cannot.
20
28
  */
21
29
  readonly baseRef?: string;
30
+ /**
31
+ * Called once per COMPLETED review, with the model call's token accounting,
32
+ * immediately before this function returns. The `token-usage` emission
33
+ * belongs in the caller (the CLI holds the session binding and owns the
34
+ * emit), so the service reports the numbers instead of writing observability
35
+ * itself. Optional: a caller that has nowhere to put them simply omits it.
36
+ */
37
+ readonly onLlmTokens?: (tokens: LlmTokenUsage) => void;
22
38
  }
23
39
  export declare class IncompleteFinalReviewError extends Error {
24
40
  readonly code: "INCOMPLETE_FINAL_REVIEW";
25
41
  constructor(message: string);
26
42
  }
43
+ /** Path segments (under `.peaks/_runtime/<sessionId>/`) the artifact lands at. */
44
+ export declare const API_DIFF_ARTIFACT_SEGMENTS: readonly ["final-review", "api-diff.txt"];
45
+ /**
46
+ * The literal that opens the artifact's conclusion line.
47
+ *
48
+ * Exported because the consumer must be able to test for the CONCLUSION, not
49
+ * for a byte count (F-BLOCK-1BYTE): one byte of `api-diff.txt` satisfied
50
+ * "status: found" while conveying nothing, and the delivery gate it fed then let
51
+ * a `pass` stand on a comparison nobody saw. The producer writes the line this
52
+ * marker opens and `final-review-service.ts` requires it in the delivered
53
+ * bytes, so the two cannot drift apart into the same hole again.
54
+ */
55
+ export declare const PRE_POST_DIFF_VERDICT_MARKER = "VERDICT: ";
56
+ /**
57
+ * The three conclusions the artifact may open with, exported as the same
58
+ * literals the verdict writer interpolates.
59
+ *
60
+ * They are constants because reading the conclusion is now part of the
61
+ * consumer's job (F2): the pre/post-diff source is the one source whose
62
+ * conclusion had a machine-readable form all along, and the envelope threw it
63
+ * away — a delivered `STRUCTURAL DRIFT DETECTED` produced `allPass: true` with
64
+ * an empty `needsAttention`. A consumer that must classify the conclusion may
65
+ * only do so against the producer's own literals, never against a re-typed
66
+ * copy of them.
67
+ */
68
+ export declare const PRE_POST_DIFF_NO_DRIFT = "NO STRUCTURAL DRIFT";
69
+ export declare const PRE_POST_DIFF_ADDITIONS_ONLY = "ADDITIONS ONLY";
70
+ export declare const PRE_POST_DIFF_DRIFT_DETECTED = "STRUCTURAL DRIFT DETECTED";
71
+ /**
72
+ * What the artifact's conclusion LINE says, read from the bytes a consumer
73
+ * actually received.
74
+ *
75
+ * `indeterminate` is not "nothing to report": it is "the line is there (or is
76
+ * not) and this consumer cannot classify it", which for a drift DETECTOR is a
77
+ * fact a human has to see — see `enforceStructuralDriftAttention`.
78
+ */
79
+ export type PrePostDiffConclusion = 'no-drift' | 'additions-only' | 'drift-detected' | 'indeterminate';
80
+ /**
81
+ * Classify the delivered conclusion. Pure and total: a caller passes the bytes
82
+ * it received (possibly a head slice) and gets back what the artifact says.
83
+ *
84
+ * Only the FIRST `VERDICT:` line is read. The artifact's header promises the
85
+ * verdict "is repeated nowhere" and that it is the file's conclusion, so a
86
+ * later line cannot be the answer, and reading further would let a document's
87
+ * prose masquerade as its conclusion.
88
+ */
89
+ export declare function classifyPrePostDiffVerdict(content: string): PrePostDiffConclusion;
90
+ export interface PrePostDiffComputed {
91
+ readonly status: 'computed';
92
+ readonly summary: string;
93
+ readonly relativePath: string;
94
+ readonly absolutePath: string;
95
+ readonly content: string;
96
+ }
97
+ export interface PrePostDiffUnavailable {
98
+ readonly status: 'unavailable';
99
+ /** Why no baseline exists, in the operator's terms. */
100
+ readonly reason: string;
101
+ /**
102
+ * `true` when the project root IS a git work tree — i.e. a baseline was
103
+ * expected to be computable and was not. That distinction shapes the REASON
104
+ * the operator is given (a tooling failure to fix, versus a project that has
105
+ * no baseline to offer), and the service refuses a `pass` on this dimension
106
+ * either way: "not a git repository" is the CAUSE of the missing evidence,
107
+ * never a licence to trust the claim the evidence was supposed to support.
108
+ */
109
+ readonly inGitWorkTree: boolean;
110
+ }
111
+ export type PrePostDiffResult = PrePostDiffComputed | PrePostDiffUnavailable;
112
+ export interface ProducePrePostDiffOptions {
113
+ readonly projectRoot: string;
114
+ readonly sessionId: string;
115
+ /** Explicit base ref. Unset ⇒ merge-base with the upstream default branch. */
116
+ readonly baseRef?: string;
117
+ }