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
@@ -5,6 +5,12 @@
5
5
  // Hoisted verbatim from final-review-service.ts (C wave 7 file-size
6
6
  // split); the service module re-exports all three so no importer's path
7
7
  // or symbol changed.
8
+ //
9
+ // It also carries the pre/post-diff producer's contract with its consumers:
10
+ // where its artifact lands, what its conclusion line says, the shapes it
11
+ // returns and the reader for that conclusion line. Moved here by the file-size
12
+ // split that took `pre-post-diff.ts` back under the cap; `pre-post-diff.ts`
13
+ // re-exports every name, so no importer's path or symbol changed either.
8
14
  export class IncompleteFinalReviewError extends Error {
9
15
  code = 'INCOMPLETE_FINAL_REVIEW';
10
16
  constructor(message) {
@@ -12,3 +18,61 @@ export class IncompleteFinalReviewError extends Error {
12
18
  this.name = 'IncompleteFinalReviewError';
13
19
  }
14
20
  }
21
+ /* ------------------------------------------------------------------ *
22
+ * The pre/post-diff producer's contract, in full: its artifact, the
23
+ * conclusion that artifact opens with, the shapes it returns, and the
24
+ * reader for that conclusion. Hoisted verbatim from pre-post-diff.ts
25
+ * (file-size split); pre-post-diff.ts re-exports every name.
26
+ * ------------------------------------------------------------------ */
27
+ /** Path segments (under `.peaks/_runtime/<sessionId>/`) the artifact lands at. */
28
+ export const API_DIFF_ARTIFACT_SEGMENTS = ['final-review', 'api-diff.txt'];
29
+ /**
30
+ * The literal that opens the artifact's conclusion line.
31
+ *
32
+ * Exported because the consumer must be able to test for the CONCLUSION, not
33
+ * for a byte count (F-BLOCK-1BYTE): one byte of `api-diff.txt` satisfied
34
+ * "status: found" while conveying nothing, and the delivery gate it fed then let
35
+ * a `pass` stand on a comparison nobody saw. The producer writes the line this
36
+ * marker opens and `final-review-service.ts` requires it in the delivered
37
+ * bytes, so the two cannot drift apart into the same hole again.
38
+ */
39
+ export const PRE_POST_DIFF_VERDICT_MARKER = 'VERDICT: ';
40
+ /**
41
+ * The three conclusions the artifact may open with, exported as the same
42
+ * literals the verdict writer interpolates.
43
+ *
44
+ * They are constants because reading the conclusion is now part of the
45
+ * consumer's job (F2): the pre/post-diff source is the one source whose
46
+ * conclusion had a machine-readable form all along, and the envelope threw it
47
+ * away — a delivered `STRUCTURAL DRIFT DETECTED` produced `allPass: true` with
48
+ * an empty `needsAttention`. A consumer that must classify the conclusion may
49
+ * only do so against the producer's own literals, never against a re-typed
50
+ * copy of them.
51
+ */
52
+ export const PRE_POST_DIFF_NO_DRIFT = 'NO STRUCTURAL DRIFT';
53
+ export const PRE_POST_DIFF_ADDITIONS_ONLY = 'ADDITIONS ONLY';
54
+ export const PRE_POST_DIFF_DRIFT_DETECTED = 'STRUCTURAL DRIFT DETECTED';
55
+ /**
56
+ * Classify the delivered conclusion. Pure and total: a caller passes the bytes
57
+ * it received (possibly a head slice) and gets back what the artifact says.
58
+ *
59
+ * Only the FIRST `VERDICT:` line is read. The artifact's header promises the
60
+ * verdict "is repeated nowhere" and that it is the file's conclusion, so a
61
+ * later line cannot be the answer, and reading further would let a document's
62
+ * prose masquerade as its conclusion.
63
+ */
64
+ export function classifyPrePostDiffVerdict(content) {
65
+ const line = content
66
+ .split(/\r?\n/)
67
+ .find((candidate) => candidate.startsWith(PRE_POST_DIFF_VERDICT_MARKER));
68
+ if (line === undefined)
69
+ return 'indeterminate';
70
+ const conclusion = line.slice(PRE_POST_DIFF_VERDICT_MARKER.length);
71
+ if (conclusion.startsWith(PRE_POST_DIFF_DRIFT_DETECTED))
72
+ return 'drift-detected';
73
+ if (conclusion.startsWith(PRE_POST_DIFF_ADDITIONS_ONLY))
74
+ return 'additions-only';
75
+ if (conclusion.startsWith(PRE_POST_DIFF_NO_DRIFT))
76
+ return 'no-drift';
77
+ return 'indeterminate';
78
+ }
@@ -6,10 +6,23 @@ import type { DimensionEvidence, DimensionKind } from './final-review-types.js';
6
6
  */
7
7
  export interface UndeliverableDimensionEvidence {
8
8
  readonly dimension: DimensionKind;
9
+ /**
10
+ * Did the reviewer receive a bounded EXCERPT of at least one of these sources?
11
+ *
12
+ * Measured 2026-10-13 on the all-oversized set this report was written for
13
+ * (`qa-test-report` 19,256 B, `qa/test-cases` 42,335 B, `prd-handoff` 28,414 B
14
+ * against a 10,240 cap): the allocator inlined 30,720 bytes — a cap-sized head
15
+ * of each — into the prompt. So "no source can ever be delivered" was true
16
+ * only of WHOLE delivery, and the report read as if the reviewer had been
17
+ * shown nothing. This flag is which of those two facts it is.
18
+ */
19
+ readonly excerptDelivered: boolean;
9
20
  readonly sources: readonly {
10
21
  readonly key: string;
11
22
  readonly relativePath: string;
12
23
  readonly totalBytes: number;
24
+ /** Bytes of this source inlined as an excerpt (0 when none was inlined). */
25
+ readonly excerptBytes: number;
13
26
  }[];
14
27
  }
15
28
  /**
@@ -8,13 +8,15 @@
8
8
  import { isDelivered } from './final-review-service.js';
9
9
  import { MAX_EVIDENCE_BYTES_PER_FILE, REQUIRED_DIMENSIONS } from './final-review-evidence-budget.js';
10
10
  /**
11
- * Can this source EVER be delivered, whatever the budget?
11
+ * Can this source EVER be delivered WHOLE, whatever the budget?
12
12
  *
13
- * `whole` is the only rule with a structural ceiling. Its test is
14
- * `includedBytes === totalBytes`, and the allocator can only ever inline
13
+ * The whole qualifier is the fact: an over-cap source IS delivered, as a
14
+ * bounded excerpt (see `CollectedEvidence.excerpt`). What it can never be is
15
+ * delivered WHOLE, and `whole` is the only rule with a structural ceiling. Its
16
+ * test is `includedBytes === totalBytes`, and the allocator can only ever inline
15
17
  * `min(bytes, MAX_EVIDENCE_BYTES_PER_FILE)` — so a `whole`-rule source LARGER
16
- * than the per-file cap can never be delivered: not on this run, not on any
17
- * run, not with any budget, because the budget is not what cuts it. Raising
18
+ * than the per-file cap is never whole: not on this run, not on any run, not
19
+ * with any budget, because the budget is not what cuts it. Raising
18
20
  * `MAX_EVIDENCE_BYTES_TOTAL` changes nothing either, since the per-file cap is
19
21
  * derived from it and the reservation spends all of it.
20
22
  *
@@ -74,13 +76,16 @@ export function undeliverableDimensions(collected) {
74
76
  continue;
75
77
  if (!onDisk.every(isStructurallyUndeliverable))
76
78
  continue;
79
+ const sources = onDisk.map((item) => ({
80
+ key: item.source.key,
81
+ relativePath: item.relativePath,
82
+ totalBytes: item.totalBytes,
83
+ excerptBytes: item.excerpt ? item.includedBytes : 0
84
+ }));
77
85
  report.push({
78
86
  dimension,
79
- sources: onDisk.map((item) => ({
80
- key: item.source.key,
81
- relativePath: item.relativePath,
82
- totalBytes: item.totalBytes
83
- }))
87
+ excerptDelivered: sources.some((item) => item.excerptBytes > 0),
88
+ sources
84
89
  });
85
90
  }
86
91
  return report;
@@ -108,11 +113,20 @@ export function enforceDeliveryReachability(dimensions, report) {
108
113
  // The ENVELOPE is not byte-capped, so it names the path as well as the
109
114
  // size: the path is what a human has to act on to fix it.
110
115
  const detail = entry.sources
111
- .map((item) => `${item.key} at ${item.relativePath} (${String(item.totalBytes)} bytes)`)
116
+ .map((item) => `${item.key} at ${item.relativePath} (${String(item.totalBytes)} bytes, ${item.excerptBytes > 0
117
+ ? `${String(item.excerptBytes)} inlined as an excerpt, ${String(item.totalBytes - item.excerptBytes)} withheld`
118
+ : 'none inlined'})`)
112
119
  .join(', ');
120
+ // The consequence is measured, not assumed. Saying "no evidence can ever
121
+ // reach the reviewer" while a cap-sized head of every one of these sources
122
+ // sits in the prompt is a claim stronger than the code — the defect class
123
+ // this module keeps closing.
124
+ const consequence = entry.excerptDelivered
125
+ ? 'a bounded EXCERPT of each was inlined, so the reviewer HAS partial evidence for this dimension — but no source for it can be delivered WHOLE, and a head of a file is not the document: the conclusion may be in the part that was cut'
126
+ : 'none of them was inlined, so no evidence for this dimension reached the reviewer at all';
113
127
  const marker = `[delivery-reachability: ${dimension.verdict === 'pass'
114
128
  ? 'verdict downgraded from "pass" to "inconclusive"'
115
- : `gate ran; verdict "${dimension.verdict}" is already non-"pass" and is left unchanged`} — EVERY source on disk that supports "${dimension.dimension}" (${detail}) is larger than the per-file delivery cap of ${String(MAX_EVIDENCE_BYTES_PER_FILE)} bytes, and a source is inlined WHOLE or not at all, so no evidence for this dimension can ever reach the reviewer. The dimension is red by byte arithmetic, not by the reviewer's judgement, and it is listed in needsAttention for that reason.]`;
129
+ : `gate ran; verdict "${dimension.verdict}" is already non-"pass" and is left unchanged`} — EVERY source on disk that supports "${dimension.dimension}" (${detail}) is larger than the per-file delivery cap of ${String(MAX_EVIDENCE_BYTES_PER_FILE)} bytes, and a source is inlined WHOLE or not at all; ${consequence}. The dimension is red by byte arithmetic, not by the reviewer's judgement, and it is listed in needsAttention for that reason.]`;
116
130
  const annotated = {
117
131
  ...dimension,
118
132
  summary: `${dimension.summary} ${marker}`
@@ -4,9 +4,15 @@
4
4
  // budget allocator, hoisted from final-review-service.ts (C wave 7).
5
5
  // evidenceSourcesFor stays in the service module (guard C pins it there)
6
6
  // and is imported from it — a one-directional edge.
7
+ //
8
+ // The `CollectedEvidence` record builders moved to
9
+ // final-review-evidence-records.ts on 2026-10-13, when this file reached 298 of
10
+ // its 300-line cap. What stays here is the read phase, the floor reservation,
11
+ // the allocator and the two byte helpers — collect → records, one way.
7
12
  import { readFileSync } from 'node:fs';
8
13
  import { join } from 'node:path';
9
14
  import { GATE_SOURCE_FOR_DIMENSION } from './final-review-evidence-sources.js';
15
+ import { blankEvidence, foundEvidence, omittedEvidence, readFailureEvidence } from './final-review-evidence-records.js';
10
16
  import { MAX_EVIDENCE_BYTES_TOTAL, REQUIRED_DIMENSIONS, assertFloorReservationAffordable, sourceUnit } from './final-review-evidence-budget.js';
11
17
  import { evidenceSourcesFor } from './final-review-service.js';
12
18
  /**
@@ -27,7 +33,8 @@ export function readEvidence(projectRoot, sessionId, rid, prePostDiffAvailable)
27
33
  // copy would silently swap the evidence this run reports.
28
34
  const attempts = [
29
35
  source.segments,
30
- ...(source.legacySegments !== undefined ? [source.legacySegments] : [])
36
+ ...(source.legacySegments !== undefined ? [source.legacySegments] : []),
37
+ ...(source.olderSegments ?? [])
31
38
  ];
32
39
  // The path reported when nothing resolved stays the CANONICAL one, so the
33
40
  // operator is sent to where the artifact belongs, not to its old home.
@@ -120,63 +127,11 @@ function floorHolders(candidates) {
120
127
  });
121
128
  return holders;
122
129
  }
123
- function readFailureEvidence(base, candidate) {
124
- // `read` is never `'ok'` here (it is set exactly when the read failed),
125
- // and `'ok'` is not a status — the branch is what says which of the two
126
- // failure facts this is.
127
- const status = candidate.read === 'unreadable' ? 'unreadable' : 'missing';
128
- return {
129
- ...base,
130
- status,
131
- totalBytes: 0,
132
- includedBytes: 0,
133
- content: '',
134
- reason: candidate.read === 'missing'
135
- ? candidate.error
136
- : `the file exists but could not be read (${candidate.error})`
137
- };
138
- }
139
- function blankEvidence(base, raw) {
140
- return {
141
- ...base,
142
- status: 'empty',
143
- totalBytes: raw.byteLength,
144
- includedBytes: 0,
145
- content: '',
146
- reason: `file exists but contains no reviewable content (${raw.byteLength} bytes)`
147
- };
148
- }
149
- function omittedEvidence(base, raw, ctx) {
150
- const { allowance, budgetLeft, candidates, holders, pending, reservedElsewhere, unit, index } = ctx;
151
- const waiting = [...pending]
152
- .filter((holder) => holder !== index)
153
- .map((holder) => `${holders.get(holder)} (source ${candidates[holder]?.source.key ?? '?'})`);
154
- return {
155
- ...base,
156
- status: 'omitted',
157
- totalBytes: raw.byteLength,
158
- includedBytes: 0,
159
- content: '',
160
- reason: reservedElsewhere > 0
161
- ? `${reservedElsewhere} bytes of the budget are reserved for dimension(s) ${waiting.join(', ')} — their only remaining evidence comes later in the source order; this source is inlined WHOLE or not at all and needs ${unit} bytes, while ${budgetLeft} were left (${allowance} after the reservation)`
162
- : `total evidence budget (${MAX_EVIDENCE_BYTES_TOTAL} bytes) is exhausted — this source is inlined WHOLE or not at all and needs ${unit} bytes, ${budgetLeft} were left`
163
- };
164
- }
165
130
  function reservedForPending(pending, units, index) {
166
131
  return [...pending]
167
132
  .filter((holder) => holder !== index)
168
133
  .reduce((sum, holder) => sum + (units[holder] ?? 0), 0);
169
134
  }
170
- function foundEvidence(base, raw, unit, content) {
171
- return {
172
- ...base,
173
- status: 'found',
174
- totalBytes: raw.byteLength,
175
- includedBytes: unit,
176
- content,
177
- reason: ''
178
- };
179
- }
180
135
  export function collectEvidence(projectRoot, sessionId, rid, prePostDiffAvailable) {
181
136
  assertFloorReservationAffordable();
182
137
  const candidates = readEvidence(projectRoot, sessionId, rid, prePostDiffAvailable);
@@ -0,0 +1,21 @@
1
+ import type { CollectedEvidence, EvidenceCandidate, EvidenceSource } from './final-review-evidence-sources.js';
2
+ import type { DimensionKind } from './final-review-types.js';
3
+ export interface EvidenceBase {
4
+ readonly source: EvidenceSource;
5
+ readonly relativePath: string;
6
+ readonly absolutePath: string;
7
+ }
8
+ export declare function readFailureEvidence(base: EvidenceBase, candidate: EvidenceCandidate): CollectedEvidence;
9
+ export declare function blankEvidence(base: EvidenceBase, raw: Buffer): CollectedEvidence;
10
+ export interface OmissionContext {
11
+ readonly budgetLeft: number;
12
+ readonly allowance: number;
13
+ readonly holders: ReadonlyMap<number, DimensionKind>;
14
+ readonly pending: Set<number>;
15
+ readonly reservedElsewhere: number;
16
+ readonly unit: number;
17
+ readonly candidates: readonly EvidenceCandidate[];
18
+ readonly index: number;
19
+ }
20
+ export declare function omittedEvidence(base: EvidenceBase, raw: Buffer, ctx: OmissionContext): CollectedEvidence;
21
+ export declare function foundEvidence(base: EvidenceBase, raw: Buffer, unit: number, content: string): CollectedEvidence;
@@ -0,0 +1,67 @@
1
+ // src/services/final-review/final-review-evidence-records.ts
2
+ //
3
+ // The `CollectedEvidence` record builders — one per way a source can turn out:
4
+ // read failure (missing vs unreadable), blank, omitted, and found (whole or as
5
+ // an over-cap EXCERPT). Hoisted out of final-review-evidence-collect.ts, which
6
+ // the slice of 2026-10-13 left at 298 of its 300-line cap; the bodies are
7
+ // byte-for-byte what that module held. The allocator and the read phase stay
8
+ // there, so the one-directional edge is collect → records.
9
+ import { MAX_EVIDENCE_BYTES_TOTAL } from './final-review-evidence-budget.js';
10
+ export function readFailureEvidence(base, candidate) {
11
+ // `read` is never `'ok'` here (it is set exactly when the read failed),
12
+ // and `'ok'` is not a status — the branch is what says which of the two
13
+ // failure facts this is.
14
+ const status = candidate.read === 'unreadable' ? 'unreadable' : 'missing';
15
+ return {
16
+ ...base,
17
+ status,
18
+ totalBytes: 0,
19
+ includedBytes: 0,
20
+ excerpt: false,
21
+ content: '',
22
+ reason: candidate.read === 'missing'
23
+ ? candidate.error
24
+ : `the file exists but could not be read (${candidate.error})`
25
+ };
26
+ }
27
+ export function blankEvidence(base, raw) {
28
+ return {
29
+ ...base,
30
+ status: 'empty',
31
+ totalBytes: raw.byteLength,
32
+ includedBytes: 0,
33
+ excerpt: false,
34
+ content: '',
35
+ reason: `file exists but contains no reviewable content (${raw.byteLength} bytes)`
36
+ };
37
+ }
38
+ export function omittedEvidence(base, raw, ctx) {
39
+ const { allowance, budgetLeft, candidates, holders, pending, reservedElsewhere, unit, index } = ctx;
40
+ const waiting = [...pending]
41
+ .filter((holder) => holder !== index)
42
+ .map((holder) => `${holders.get(holder)} (source ${candidates[holder]?.source.key ?? '?'})`);
43
+ return {
44
+ ...base,
45
+ status: 'omitted',
46
+ totalBytes: raw.byteLength,
47
+ includedBytes: 0,
48
+ excerpt: false,
49
+ content: '',
50
+ reason: reservedElsewhere > 0
51
+ ? `${reservedElsewhere} bytes of the budget are reserved for dimension(s) ${waiting.join(', ')} — their only remaining evidence comes later in the source order; this source is inlined WHOLE or not at all and needs ${unit} bytes, while ${budgetLeft} were left (${allowance} after the reservation)`
52
+ : `total evidence budget (${MAX_EVIDENCE_BYTES_TOTAL} bytes) is exhausted — this source is inlined WHOLE or not at all and needs ${unit} bytes, ${budgetLeft} were left`
53
+ };
54
+ }
55
+ export function foundEvidence(base, raw, unit, content) {
56
+ return {
57
+ ...base,
58
+ status: 'found',
59
+ totalBytes: raw.byteLength,
60
+ includedBytes: unit,
61
+ // `unit` is `sourceUnit(candidate)` = `min(file bytes, cap)`, so this is
62
+ // exactly "the FILE is bigger than the cap" — never a budget-cut fragment.
63
+ excerpt: unit < raw.byteLength,
64
+ content,
65
+ reason: ''
66
+ };
67
+ }
@@ -37,6 +37,15 @@ export interface EvidenceSource {
37
37
  * it (`enforceScopeContractDelivery` returns early on `missing`).
38
38
  */
39
39
  readonly legacySegments?: readonly string[];
40
+ /**
41
+ * Further older locations, tried **in declared order** after
42
+ * `legacySegments`. Needed because one artifact has THREE tiers on disk
43
+ * (`audit/security-<rid>.md` → `rd/security-review-<rid>.md` →
44
+ * `rd/security-review.md`). Mirrors `legacyRelativePaths` on
45
+ * `ArtifactPrerequisite` in `src/services/artifacts/artifact-prerequisites.ts`,
46
+ * which splits its older tiers the same way for the same reason.
47
+ */
48
+ readonly olderSegments?: readonly (readonly string[])[];
40
49
  /** Dimensions this source can supply evidence for. */
41
50
  readonly supports: readonly DimensionKind[];
42
51
  /** What DELIVERED means for this source. See `isDelivered()` — every source
@@ -104,6 +113,19 @@ export interface CollectedEvidence {
104
113
  readonly totalBytes: number;
105
114
  /** Bytes actually inlined into the prompt. */
106
115
  readonly includedBytes: number;
116
+ /**
117
+ * The allocator's EXCERPT outcome: the FILE is larger than the per-file cap,
118
+ * so only its head was inlined. Measured 2026-10-13 on an all-oversized set
119
+ * (19,256 / 42,335 / 28,414 bytes against a 10,240 cap): the prompt carried a
120
+ * cap-sized head of each, 30,720 bytes, while the delivery report said "no
121
+ * source CAN be delivered". The excerpt was in the prompt; the statement that
122
+ * it was not is the claim-stronger-than-the-code defect.
123
+ *
124
+ * It is NOT delivery under the `whole` rule — `isDelivered` still answers
125
+ * `false` for it, because the conclusion may be in the part that was cut, so
126
+ * it may not back a `pass`. What it must not do is go unnamed.
127
+ */
128
+ readonly excerpt: boolean;
107
129
  readonly content: string;
108
130
  /** Why this source carries no evidence (non-`found` statuses only). */
109
131
  readonly reason: string;
@@ -93,7 +93,12 @@ function baseEvidenceSourcesA(rid) {
93
93
  {
94
94
  key: 'rd-code-review',
95
95
  label: 'RD code review',
96
- segments: ['rd', 'code-review.md'],
96
+ // The request id is part of the filename so two slices in one session do
97
+ // not collide (the same reason as CODE_REVIEW in
98
+ // `src/services/artifacts/artifact-prerequisites.ts`); the bare name is
99
+ // the older tier and is the legacy fallback.
100
+ segments: ['rd', `code-review-${rid}.md`],
101
+ legacySegments: ['rd', 'code-review.md'],
97
102
  supports: ['no-new-bugs'],
98
103
  delivery: { kind: 'whole' }
99
104
  }
@@ -103,8 +108,21 @@ function baseEvidenceSourcesB(rid) {
103
108
  return [
104
109
  {
105
110
  key: 'rd-security-review',
106
- label: 'RD security review',
107
- segments: ['rd', 'security-review.md'],
111
+ // The label names what the bytes ARE. The canonical path carries the
112
+ // independent `peaks-security-audit` envelope, so "RD security review"
113
+ // would now misname the producer — but the legacy tier really is the
114
+ // RD-authored review, so the parenthetical must cover both.
115
+ label: 'Security review (independent audit, or legacy RD review)',
116
+ // Mirrors AUDIT_SECURITY **and** SECURITY_REVIEW in
117
+ // `src/services/artifacts/artifact-prerequisites.ts`: the scoped
118
+ // `audit/security-${rid}.md` is canonical, the scoped
119
+ // `rd/security-review-${rid}.md` is the `config` row's own requirement
120
+ // (it was ridless, so a second config slice in a session overwrote the
121
+ // first's review), and the bare `rd/security-review.md` — the v2.11.x RD
122
+ // slot the independent audit skill replaced — is the oldest tier.
123
+ segments: ['audit', `security-${rid}.md`],
124
+ legacySegments: ['rd', `security-review-${rid}.md`],
125
+ olderSegments: [['rd', 'security-review.md']],
108
126
  supports: ['no-new-bugs'],
109
127
  delivery: { kind: 'whole' }
110
128
  },
@@ -118,7 +136,13 @@ function baseEvidenceSourcesB(rid) {
118
136
  {
119
137
  key: 'rd-bug-analysis',
120
138
  label: 'RD bug analysis (original problem statement)',
121
- segments: ['rd', 'bug-analysis.md'],
139
+ // Mirrors BUG_ANALYSIS in `src/services/artifacts/artifact-prerequisites.ts`:
140
+ // the scoped name is canonical and the bare name is the pre-scoping tier.
141
+ // A segment matcher fails by NOT matching, so the positive direction is
142
+ // asserted — by the bug-analysis scoping suite under
143
+ // tests/unit/services/artifacts/, which names its own file in its header.
144
+ segments: ['rd', `bug-analysis-${rid}.md`],
145
+ legacySegments: ['rd', 'bug-analysis.md'],
122
146
  supports: ['problem-resolution'],
123
147
  delivery: { kind: 'whole' }
124
148
  },
@@ -13,8 +13,13 @@ export function renderEvidenceSection(collected) {
13
13
  const heading = `### [${index + 1}] ${item.source.key} — ${item.source.label}`;
14
14
  const supports = `SUPPORTS: ${item.source.supports.join(', ')}`;
15
15
  if (item.status === 'found') {
16
- const status = item.includedBytes < item.totalBytes
17
- ? `FOUND at ${item.relativePath} — TRUNCATED, showing the first ${item.includedBytes} of ${item.totalBytes} bytes`
16
+ // An over-cap source IS delivered — as a bounded excerpt. The block says
17
+ // so in as many words, with the byte count and the withheld fraction, so
18
+ // a reviewer cannot read a head of a file as the whole file and a human
19
+ // reading the transcript can see the evidence was partial.
20
+ const withheld = item.totalBytes - item.includedBytes;
21
+ const status = item.excerpt
22
+ ? `FOUND at ${item.relativePath} — TRUNCATED EXCERPT (a HEAD, not the whole file): showing the first ${item.includedBytes} of ${item.totalBytes} bytes, ${withheld} bytes (${((withheld / item.totalBytes) * 100).toFixed(1)}%) withheld.`
18
23
  : `FOUND at ${item.relativePath} — ${item.totalBytes} bytes`;
19
24
  return `${heading}\n${supports}\nSTATUS: ${status}\n<<<EVIDENCE\n${item.content}\n>>>EVIDENCE`;
20
25
  }
@@ -97,16 +102,24 @@ export function renderDeliveryReachabilityStatus(report) {
97
102
  // Kept to one line per source and one line per dimension: this block rides
98
103
  // inside the same byte-capped prompt as the evidence it describes, and the
99
104
  // evidence blocks above already carry each source's path and status.
105
+ // Two measured states, not one assertion. An over-cap source IS delivered as
106
+ // a bounded excerpt (see the evidence blocks above); saying "no deliverable
107
+ // source" about a block the reviewer is reading is the claim-stronger-than-
108
+ // the-code defect, so the bullet names which of the two it is.
100
109
  const lines = report.map((entry) => {
101
110
  const sources = entry.sources
102
- .map((item) => `${item.key} (${String(item.totalBytes)} bytes)`)
111
+ .map((item) => item.excerptBytes > 0
112
+ ? `${item.key} (${String(item.totalBytes)} bytes; ${String(item.excerptBytes)} inlined, ${String(item.totalBytes - item.excerptBytes)} withheld)`
113
+ : `${item.key} (${String(item.totalBytes)} bytes; none inlined)`)
103
114
  .join(', ');
104
- return ` - ${entry.dimension}: NO deliverable source. ${sources} exceeds the per-file cap of ${String(MAX_EVIDENCE_BYTES_PER_FILE)} bytes, and a source is inlined WHOLE or not at all.`;
115
+ return entry.excerptDelivered
116
+ ? ` - ${entry.dimension}: EXCERPT ONLY — ${sources}. The reviewer received a bounded EXCERPT of each and NOT the documents.`
117
+ : ` - ${entry.dimension}: NO deliverable source — ${sources}. None was inlined, so no evidence for this dimension reached the reviewer.`;
105
118
  });
106
119
  return [
107
120
  '## Evidence delivery reachability (structural)',
108
- `The allocator inlines at most ${String(MAX_EVIDENCE_BYTES_PER_FILE)} bytes of any one source, WHOLE or not at all, and a source delivered under the "whole" rule is delivered only when the reviewer received ALL of it. For the dimension(s) below, every source on disk that supports it is larger than that cap, so no source CAN be delivered — not on this run and not on any run, whatever the budget.`,
121
+ `The allocator inlines at most ${String(MAX_EVIDENCE_BYTES_PER_FILE)} bytes of any one source, WHOLE or not at all, and a source delivered under the "whole" rule is delivered only when the reviewer received ALL of it. For the dimension(s) below, every source on disk that supports it is larger than the per-file cap of ${String(MAX_EVIDENCE_BYTES_PER_FILE)} bytes, so not one of them can ever be delivered WHOLE — not on this run and not on any run, whatever the budget.`,
109
122
  ...lines,
110
- 'Report each of them as "inconclusive" with confidence "low" and name this reason in its summary. Do NOT report "pass": the service re-checks it, and a "pass" here is downgraded. This is a STRUCTURAL impossibility, not a judgement you are being asked to make — say so rather than reporting an unexplained "inconclusive".'
123
+ 'Report each as "inconclusive", confidence "low", naming this reason in its summary, and do NOT report "pass": the service re-checks it and downgrades one — a head of a file is not the document, and the conclusion may be in the part that was cut.'
111
124
  ].join('\n');
112
125
  }
@@ -154,5 +154,10 @@ export async function prepareFinalReview(rid, opts) {
154
154
  const { allPass, needsAttention } = summarizeVerdicts(dimensions, output, [
155
155
  ...(gated.mustAttend ? ['existing-functionality-intact'] : [])
156
156
  ]);
157
+ // The one model call this review made, reported to the caller at the point
158
+ // the review is COMPLETE: one completed `prepareFinalReview` call ⇒ one
159
+ // `token-usage` event, emitted by the caller because that is where the session
160
+ // binding lives.
161
+ opts.onLlmTokens?.(response.tokens);
157
162
  return { ...output, dimensions, allPass, needsAttention };
158
163
  }
@@ -1,8 +1,8 @@
1
1
  import { type PrePostDiffResult } from './pre-post-diff.js';
2
2
  import { type CollectedEvidence, type EvidenceSource } from './final-review-evidence-sources.js';
3
- import { IncompleteFinalReviewError, type LlmRunner, type PrepareFinalReviewOptions } from './final-review-contract.js';
3
+ import { IncompleteFinalReviewError, type LlmRunner, type LlmTokenUsage, type PrepareFinalReviewOptions } from './final-review-contract.js';
4
4
  import type { DimensionEvidence, DimensionKind } from './final-review-types.js';
5
- export { IncompleteFinalReviewError, type LlmRunner, type PrepareFinalReviewOptions };
5
+ export { IncompleteFinalReviewError, type LlmRunner, type LlmTokenUsage, type PrepareFinalReviewOptions };
6
6
  /**
7
7
  * The on-disk sources, in allocation order.
8
8
  *
@@ -1,3 +1,3 @@
1
- export { prepareFinalReview, type PrepareFinalReviewOptions, type LlmRunner, IncompleteFinalReviewError, MAX_EVIDENCE_BYTES_PER_FILE, MAX_EVIDENCE_BYTES_TOTAL, assertFloorReservationAffordable, undeliverableDimensions, type UndeliverableDimensionEvidence } from './final-review-service.js';
1
+ export { prepareFinalReview, type PrepareFinalReviewOptions, type LlmRunner, type LlmTokenUsage, IncompleteFinalReviewError, MAX_EVIDENCE_BYTES_PER_FILE, MAX_EVIDENCE_BYTES_TOTAL, assertFloorReservationAffordable, undeliverableDimensions, type UndeliverableDimensionEvidence } from './final-review-service.js';
2
2
  export { classifyPrePostDiffVerdict, type PrePostDiffConclusion } from './pre-post-diff.js';
3
3
  export type { DimensionKind, DimensionVerdict, EvidenceKind, DimensionConfidence, EvidenceItem, DimensionEvidence, FinalReviewOutput } from './final-review-types.js';
@@ -43,86 +43,12 @@
43
43
  * indistinguishable from a clean comparison. Conclusion-first makes "the
44
44
  * reviewer got the answer" a property of the bytes received.
45
45
  */
46
- /** Path segments (under `.peaks/_runtime/<sessionId>/`) the artifact lands at. */
47
- export declare const API_DIFF_ARTIFACT_SEGMENTS: readonly ["final-review", "api-diff.txt"];
48
- /**
49
- * The literal that opens the artifact's conclusion line.
50
- *
51
- * Exported because the consumer must be able to test for the CONCLUSION, not
52
- * for a byte count (F-BLOCK-1BYTE): one byte of `api-diff.txt` satisfied
53
- * "status: found" while conveying nothing, and the delivery gate it fed then let
54
- * a `pass` stand on a comparison nobody saw. The producer writes the line this
55
- * marker opens and `final-review-service.ts` requires it in the delivered
56
- * bytes, so the two cannot drift apart into the same hole again.
57
- */
58
- export declare const PRE_POST_DIFF_VERDICT_MARKER = "VERDICT: ";
59
- /**
60
- * The three conclusions the artifact may open with, exported as the same
61
- * literals the writer interpolates below.
62
- *
63
- * They are constants because reading the conclusion is now part of the
64
- * consumer's job (F2): the pre/post-diff source is the one source whose
65
- * conclusion had a machine-readable form all along, and the envelope threw it
66
- * away — a delivered `STRUCTURAL DRIFT DETECTED` produced `allPass: true` with
67
- * an empty `needsAttention`. A consumer that must classify the conclusion may
68
- * only do so against the producer's own literals, never against a re-typed
69
- * copy of them.
70
- */
71
- export declare const PRE_POST_DIFF_NO_DRIFT = "NO STRUCTURAL DRIFT";
72
- export declare const PRE_POST_DIFF_ADDITIONS_ONLY = "ADDITIONS ONLY";
73
- export declare const PRE_POST_DIFF_DRIFT_DETECTED = "STRUCTURAL DRIFT DETECTED";
74
- /**
75
- * What the artifact's conclusion LINE says, read from the bytes a consumer
76
- * actually received.
77
- *
78
- * `indeterminate` is not "nothing to report": it is "the line is there (or is
79
- * not) and this consumer cannot classify it", which for a drift DETECTOR is a
80
- * fact a human has to see — see `enforceStructuralDriftAttention`.
81
- */
82
- export type PrePostDiffConclusion = 'no-drift' | 'additions-only' | 'drift-detected' | 'indeterminate';
83
- /**
84
- * Classify the delivered conclusion. Pure and total: a caller passes the bytes
85
- * it received (possibly a head slice) and gets back what the artifact says.
86
- *
87
- * Only the FIRST `VERDICT:` line is read. The artifact's header promises the
88
- * verdict "is repeated nowhere" and that it is the file's conclusion, so a
89
- * later line cannot be the answer, and reading further would let a document's
90
- * prose masquerade as its conclusion.
91
- */
92
- export declare function classifyPrePostDiffVerdict(content: string): PrePostDiffConclusion;
46
+ import { type PrePostDiffResult, type ProducePrePostDiffOptions } from './final-review-contract.js';
93
47
  /** Test-file globs — the single definition both the file count and the case
94
48
  * count use, so the two can never disagree about what a "test file" is. */
95
49
  export declare const TEST_FILE_GLOBS: readonly ["*.test.ts", "*.test.tsx", "*.spec.ts", "*.spec.tsx"];
96
50
  /** Source globs for the public-API surface. */
97
51
  export declare const API_SOURCE_GLOBS: readonly ["*.ts", "*.tsx"];
98
- export interface PrePostDiffComputed {
99
- readonly status: 'computed';
100
- readonly summary: string;
101
- readonly relativePath: string;
102
- readonly absolutePath: string;
103
- readonly content: string;
104
- }
105
- export interface PrePostDiffUnavailable {
106
- readonly status: 'unavailable';
107
- /** Why no baseline exists, in the operator's terms. */
108
- readonly reason: string;
109
- /**
110
- * `true` when the project root IS a git work tree — i.e. a baseline was
111
- * expected to be computable and was not. That distinction shapes the REASON
112
- * the operator is given (a tooling failure to fix, versus a project that has
113
- * no baseline to offer), and the service refuses a `pass` on this dimension
114
- * either way: "not a git repository" is the CAUSE of the missing evidence,
115
- * never a licence to trust the claim the evidence was supposed to support.
116
- */
117
- readonly inGitWorkTree: boolean;
118
- }
119
- export type PrePostDiffResult = PrePostDiffComputed | PrePostDiffUnavailable;
120
- export interface ProducePrePostDiffOptions {
121
- readonly projectRoot: string;
122
- readonly sessionId: string;
123
- /** Explicit base ref. Unset ⇒ merge-base with the upstream default branch. */
124
- readonly baseRef?: string;
125
- }
126
52
  /**
127
53
  * The exported NAMES bound by one source line. Approximate by design: the
128
54
  * column-0 anchor is what keeps it to top-level declarations, and
@@ -135,3 +61,4 @@ export declare function extractExportedNames(line: string): readonly string[];
135
61
  * must report a dimension it could not assess.
136
62
  */
137
63
  export declare function producePrePostDiff(opts: ProducePrePostDiffOptions): PrePostDiffResult;
64
+ export { API_DIFF_ARTIFACT_SEGMENTS, PRE_POST_DIFF_VERDICT_MARKER, PRE_POST_DIFF_NO_DRIFT, PRE_POST_DIFF_ADDITIONS_ONLY, PRE_POST_DIFF_DRIFT_DETECTED, classifyPrePostDiffVerdict, type PrePostDiffConclusion, type PrePostDiffComputed, type PrePostDiffUnavailable, type PrePostDiffResult, type ProducePrePostDiffOptions } from './final-review-contract.js';