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,53 @@
1
+ import { type RequestType } from './artifact-prerequisites.js';
2
+ import { type RequestTypeSource } from './request-artifact-metadata.js';
3
+ /**
4
+ * The block, or `''` when this role has nothing gated to say under this type.
5
+ * The empty string is the whole byte-identity contract: callers concatenate it,
6
+ * and a role with no gated artifacts must add zero bytes to the prompt.
7
+ */
8
+ export declare function buildArtifactContractBlock(input: {
9
+ role: string;
10
+ requestType: RequestType;
11
+ requestTypeSource: RequestTypeSource;
12
+ requestId: string;
13
+ }): string;
14
+ /**
15
+ * Append the block unless the text already carries one.
16
+ *
17
+ * Idempotent for the same reason `ensureKarpathyBlock` is: a caller prompt can
18
+ * already hold a copy — a re-dispatch, or a resume from a stored prompt — and
19
+ * two sections can DISAGREE (the type may have been declared between the two
20
+ * runs), so a reader cannot tell which contract is authoritative. The presence
21
+ * test is the block's own heading, which nothing else emits.
22
+ *
23
+ * An empty block adds zero bytes even when the text already carries one, so an
24
+ * unaffected dispatch stays byte-identical.
25
+ */
26
+ export declare function ensureArtifactContractBlock(text: string, block: string): string;
27
+ export type ArtifactTypeReading = {
28
+ requestType: RequestType;
29
+ requestTypeSource: RequestTypeSource;
30
+ };
31
+ /**
32
+ * The type recorded for `requestId`, read through the same reader the rest of
33
+ * the CLI uses. Every request artifact of the id is a candidate because the
34
+ * dispatched role's own file frequently does not exist yet at dispatch time —
35
+ * a dated snapshot over the dispatch records of the 2026-10-12 session (77 of
36
+ * them at the time of writing, a count the session is still growing): 18 had any
37
+ * request artifact for the id on disk before the dispatch and 10 had one that
38
+ * declared a type — while a sibling role may have recorded the type already. A
39
+ * `default` result is a real answer — nothing declared it.
40
+ */
41
+ export declare function readArtifactType(input: {
42
+ projectRoot: string;
43
+ sessionId: string;
44
+ requestId: string;
45
+ role: string;
46
+ }): Promise<ArtifactTypeReading>;
47
+ /** The composed block for a dispatch, reading the type from disk first. */
48
+ export declare function readArtifactContractBlock(input: {
49
+ projectRoot: string;
50
+ sessionId: string;
51
+ requestId: string;
52
+ role: string;
53
+ }): Promise<string>;
@@ -0,0 +1,231 @@
1
+ // The artifact contract block a dispatched sub-agent receives: for its own role
2
+ // and the request's type, every artifact the prerequisite gate will demand and
3
+ // the literal body markers each one must carry.
4
+ //
5
+ // Generated from the table the gate reads (`getPrerequisitesFor`), never from a
6
+ // second hand-written list: the markers are matched as case-insensitive
7
+ // substrings of the artifact body, so a list kept in prose drifts the moment a
8
+ // marker changes and the gate then refuses a producer it never told.
9
+ import { DEFAULT_REQUEST_TYPE, getPrerequisitesFor } from './artifact-prerequisites.js';
10
+ import { ALLOWED_STATES_PER_ROLE } from './request-artifact-state-helpers.js';
11
+ import { extractMetadata } from './request-artifact-metadata.js';
12
+ import { REQUEST_ID_PATTERN, showRequestArtifact } from './request-artifact-service.js';
13
+ import { isUnsafePathInput } from '../../shared/path-safety.js';
14
+ /** Roles whose request artifact may carry a `- type:` line, in search order. */
15
+ const TYPE_SOURCE_ROLES = ['rd', 'prd', 'qa', 'ui', 'sc'];
16
+ /** True for the five roles the state table is keyed on. */
17
+ function isRequestArtifactRole(role) {
18
+ return Object.prototype.hasOwnProperty.call(ALLOWED_STATES_PER_ROLE, role);
19
+ }
20
+ /**
21
+ * The prerequisite's path with the request id substituted for its `<rid>`.
22
+ *
23
+ * Deliberately NOT exported. A test that called this would no longer be
24
+ * independent of the renderer it checks, and that independence is the whole
25
+ * value of the pinning case.
26
+ */
27
+ function resolveContractPath(prerequisite, requestId) {
28
+ return prerequisite.relativePath.replace('<rid>', requestId);
29
+ }
30
+ function quoteAll(markers) {
31
+ return markers.map((marker) => `\`${marker}\``).join(', ');
32
+ }
33
+ /**
34
+ * The marker fields, in the order the block renders them. A table rather than a
35
+ * chain of `if`s: the three fields are independent and uniform, so listing them
36
+ * keeps the renderer's complexity flat as the vocabulary grows.
37
+ */
38
+ const MARKER_CLAUSES = [
39
+ { markers: (candidate) => candidate.mustContain, label: 'must contain' },
40
+ { markers: (candidate) => candidate.mustContainAny, label: 'must contain at least one of' },
41
+ {
42
+ markers: (candidate) => candidate.headingMustContain,
43
+ label: 'must appear as markdown headings'
44
+ }
45
+ ];
46
+ /**
47
+ * One line's worth of "what this file must carry", or the explicit statement
48
+ * that there is nothing to carry. `mustContainAny` is rendered as an
49
+ * alternative set rather than as three requirements — the gate passes on one.
50
+ */
51
+ function describePrerequisite(prerequisite) {
52
+ const clauses = MARKER_CLAUSES.flatMap(({ markers, label }) => {
53
+ const list = markers(prerequisite) ?? [];
54
+ return list.length === 0 ? [] : [`${label}: ${quoteAll(list)}`];
55
+ });
56
+ if (prerequisite.backCompat === true) {
57
+ const until = prerequisite.backCompatUntil ?? 'the window closes';
58
+ clauses.push(`a missing file only warns until ${until}`);
59
+ }
60
+ return clauses.length === 0 ? 'the file must exist; it has no body markers' : clauses.join('; ');
61
+ }
62
+ /**
63
+ * The command that reaches a state, spelled with every option
64
+ * `src/cli/commands/request-transition-command.ts` registers as MANDATORY.
65
+ * `--project` is one of them, and an earlier revision of this line omitted it —
66
+ * the prompt therefore handed the producer a command the CLI refuses for a
67
+ * missing option, which is this block's own defect class turned on itself. The
68
+ * pinning test now compares the emitted options against the command's own
69
+ * `mandatory` set, so a newly required flag fails the suite rather than reaching
70
+ * a prompt. `.` because a dispatched sub-agent's working directory is the
71
+ * project root.
72
+ */
73
+ function transitionCommand(role, state, requestId) {
74
+ return `peaks request transition ${requestId} --role ${role} --state ${state} --project .`;
75
+ }
76
+ function renderStateRow(role, state, prerequisites, requestId) {
77
+ const lines = prerequisites.map((entry) => `- \`${resolveContractPath(entry, requestId)}\` — ${describePrerequisite(entry)}`);
78
+ const reached = transitionCommand(role, state, requestId);
79
+ return {
80
+ state,
81
+ text: `\nAt \`${role}:${state}\` (reached with \`${reached}\`):\n${lines.join('\n')}\n`
82
+ };
83
+ }
84
+ /**
85
+ * One row per state of `role` that demands at least one artifact under
86
+ * `requestType`. A state with an empty row (`rd:implemented` for a feature, for
87
+ * instance) is left out rather than rendered as "nothing required" — the block
88
+ * is a list of obligations, and a state with none is not an obligation.
89
+ */
90
+ function stateRows(role, requestType, requestId) {
91
+ if (!isRequestArtifactRole(role))
92
+ return [];
93
+ const rows = [];
94
+ for (const state of ALLOWED_STATES_PER_ROLE[role]) {
95
+ const prerequisites = getPrerequisitesFor(role, state, requestType);
96
+ if (prerequisites.length === 0)
97
+ continue;
98
+ rows.push(renderStateRow(role, state, prerequisites, requestId));
99
+ }
100
+ return rows;
101
+ }
102
+ const BODY_RULE = 'The gate matches each marker below as a case-insensitive substring of the artifact body, and a ' +
103
+ 'heading marker must be a real markdown heading. Content under a different spelling is refused, ' +
104
+ 'so write the marker literally. Paths are relative to `.peaks/_runtime/<session-id>/`.';
105
+ /**
106
+ * The scope bound, always true of the block regardless of what the gate does:
107
+ * it says what the rows ARE (necessary) and not what they are not (sufficient).
108
+ */
109
+ const SCOPE_BASE = 'This block is generated from the prerequisite table alone, so the rows below are necessary and are ' +
110
+ 'not a complete contract.';
111
+ /**
112
+ * The body-lint gate, named in EVERY non-empty block because it runs for every role
113
+ * and every type: the transition OUT of `draft` lints the artifact and refuses on
114
+ * any placeholder the template still carries. The block said nothing about it, so a
115
+ * producer that satisfied every row below still met a refusal the carrier had never
116
+ * mentioned — the same defect as a row whose marker the producer was not shown.
117
+ */
118
+ const SCOPE_LINT = ' Separately from the rows above: leaving `draft` runs the body lint over this artifact, and it ' +
119
+ 'refuses on a placeholder the template still carries — an unfilled `<...>` token or a `- ...` stub.';
120
+ /**
121
+ * The addendum for a state the gate really does guard with more than the table.
122
+ * Measured on a probe project and again on this slice's own rid: an artifact set
123
+ * satisfying every `rd:qa-handoff` row was still refused once, on a declaration
124
+ * outside the table. The earlier wording said a gate "may also check something
125
+ * the table does not carry", which under-claims a systematic gap at exactly the
126
+ * state this block guides a producer to.
127
+ *
128
+ * The declaration is named because naming it is the whole fix: the refusal used to
129
+ * report the artifact as absent when the artifact was there and only its
130
+ * declaration was unmet, so a producer that read this far-first ended one refusal
131
+ * later than it needed to.
132
+ * NO PRODUCER IS NAMED: the same declaration is required of whichever security
133
+ * artifact the rows above demand — a `config` slice's is `rd/security-review-<rid>.md`
134
+ * — and more than one in-repo producer writes a valid one.
135
+ */
136
+ const SCOPE_HANDOFF = ' At `rd:qa-handoff` the gate also runs checks that are not rows of this table, so satisfying every ' +
137
+ 'row below does not by itself open that transition. One is the judged declaration: the security ' +
138
+ 'artifact the rows above name must also carry a `## Judged content` block, and a body written ' +
139
+ 'without one satisfies the row and is still refused.';
140
+ const ARTIFACT_CONTRACT_HEADING = '## Artifact contract (generated from the prerequisite table)';
141
+ /**
142
+ * The block, or `''` when this role has nothing gated to say under this type.
143
+ * The empty string is the whole byte-identity contract: callers concatenate it,
144
+ * and a role with no gated artifacts must add zero bytes to the prompt.
145
+ */
146
+ export function buildArtifactContractBlock(input) {
147
+ const rows = stateRows(input.role, input.requestType, input.requestId);
148
+ if (rows.length === 0)
149
+ return '';
150
+ const typeLine = input.requestTypeSource === 'declared'
151
+ ? `request type \`${input.requestType}\` (recorded by a \`- type:\` line)`
152
+ : `request type \`${input.requestType}\` — the DEFAULT, not a recorded choice: this request ` +
153
+ 'records no `- type:` line, so the gate applies the default table. If the work is really a ' +
154
+ 'different type, the demand set below is the wrong one';
155
+ // Conditional on the ROWS, not on a hand-written type list: whichever types
156
+ // render an `rd:qa-handoff` row are exactly the ones the extra checks run for.
157
+ const guardedHandoff = input.role === 'rd' && rows.some((row) => row.state === 'qa-handoff');
158
+ return (`\n${ARTIFACT_CONTRACT_HEADING}\n` +
159
+ `Role \`${input.role}\`, ${typeLine}.\n` +
160
+ `${BODY_RULE}\n` +
161
+ `${SCOPE_BASE}${guardedHandoff ? SCOPE_HANDOFF : ''}${SCOPE_LINT}\n` +
162
+ rows.map((row) => row.text).join('') +
163
+ '\n');
164
+ }
165
+ /**
166
+ * Append the block unless the text already carries one.
167
+ *
168
+ * Idempotent for the same reason `ensureKarpathyBlock` is: a caller prompt can
169
+ * already hold a copy — a re-dispatch, or a resume from a stored prompt — and
170
+ * two sections can DISAGREE (the type may have been declared between the two
171
+ * runs), so a reader cannot tell which contract is authoritative. The presence
172
+ * test is the block's own heading, which nothing else emits.
173
+ *
174
+ * An empty block adds zero bytes even when the text already carries one, so an
175
+ * unaffected dispatch stays byte-identical.
176
+ */
177
+ export function ensureArtifactContractBlock(text, block) {
178
+ if (block.length === 0 || text.includes(ARTIFACT_CONTRACT_HEADING))
179
+ return text;
180
+ return `${text}${block}`;
181
+ }
182
+ /**
183
+ * The type recorded for `requestId`, read through the same reader the rest of
184
+ * the CLI uses. Every request artifact of the id is a candidate because the
185
+ * dispatched role's own file frequently does not exist yet at dispatch time —
186
+ * a dated snapshot over the dispatch records of the 2026-10-12 session (77 of
187
+ * them at the time of writing, a count the session is still growing): 18 had any
188
+ * request artifact for the id on disk before the dispatch and 10 had one that
189
+ * declared a type — while a sibling role may have recorded the type already. A
190
+ * `default` result is a real answer — nothing declared it.
191
+ */
192
+ export async function readArtifactType(input) {
193
+ const fallback = {
194
+ requestType: DEFAULT_REQUEST_TYPE,
195
+ requestTypeSource: 'default'
196
+ };
197
+ if (isUnsafePathInput(input.sessionId) || !REQUEST_ID_PATTERN.test(input.requestId)) {
198
+ return fallback;
199
+ }
200
+ const candidates = [];
201
+ for (const candidate of [input.role, ...TYPE_SOURCE_ROLES]) {
202
+ if (isRequestArtifactRole(candidate) && !candidates.includes(candidate)) {
203
+ candidates.push(candidate);
204
+ }
205
+ }
206
+ for (const role of candidates) {
207
+ const found = await showRequestArtifact({
208
+ projectRoot: input.projectRoot,
209
+ sessionId: input.sessionId,
210
+ role,
211
+ requestId: input.requestId
212
+ });
213
+ if (found === null)
214
+ continue;
215
+ const metadata = extractMetadata(found.content);
216
+ if (metadata.requestTypeSource === 'declared') {
217
+ return { requestType: metadata.requestType, requestTypeSource: 'declared' };
218
+ }
219
+ }
220
+ return fallback;
221
+ }
222
+ /** The composed block for a dispatch, reading the type from disk first. */
223
+ export async function readArtifactContractBlock(input) {
224
+ const reading = await readArtifactType(input);
225
+ return buildArtifactContractBlock({
226
+ role: input.role,
227
+ requestId: input.requestId,
228
+ requestType: reading.requestType,
229
+ requestTypeSource: reading.requestTypeSource
230
+ });
231
+ }
@@ -55,6 +55,10 @@ export type ArtifactPrerequisite = {
55
55
  * the last of those, so the oldest tier still has to resolve.
56
56
  */
57
57
  legacyRelativePaths?: ReadonlyArray<string>;
58
+ /** Back-compat window — a missing file warns instead of failing; see `prerequisite-checks.ts`. */
59
+ backCompat?: boolean;
60
+ /** The release that CLOSES that window (e.g. `v2.14.0`); the warning code's suffix. */
61
+ backCompatUntil?: string;
58
62
  };
59
63
  export type PrerequisiteCheckResult = {
60
64
  ok: boolean;
@@ -63,15 +67,19 @@ export type PrerequisiteCheckResult = {
63
67
  description: string;
64
68
  }>;
65
69
  /**
66
- * path that is currently missing but is in a 1-minor-release
67
- * back-compat window. The transition gate does not throw on
68
- * `missing`-only (so legacy callers keep working) but surfaces the
69
- * warning to the operator so they can plan the v2.14.0 hard cut.
70
+ * Missing files inside a back-compat window (see
71
+ * `ArtifactPrerequisite.backCompat`). NOT a failure — the gate does not throw
72
+ * on these, so legacy callers keep working. They ARE reported:
73
+ * `transitionRequestArtifact` copies the list onto its success result and
74
+ * `peaks request transition` prints each one as an envelope warning, so a
75
+ * soft-passed prerequisite is not read as a passed one. `code` is derived per
76
+ * prerequisite (`prerequisite-checks.ts`), so it names which artifact.
70
77
  */
71
78
  warnings: Array<{
72
79
  path: string;
73
80
  code: string;
74
81
  message: string;
82
+ expiredWindow?: string;
75
83
  }>;
76
84
  };
77
85
  export type CheckPrerequisitesOptions = {
@@ -85,20 +93,20 @@ export type CheckPrerequisitesOptions = {
85
93
  role: RequestArtifactRole;
86
94
  newState: RequestArtifactState;
87
95
  requestId: string;
88
- requestType?: RequestType;
96
+ /**
97
+ * Required, with no default. The `?? DEFAULT_REQUEST_TYPE` that used to sit in
98
+ * `getPrerequisitesFor`'s signature let a caller silently select the `feature`
99
+ * table by omitting an argument; a caller that wants the default now has to
100
+ * write it, and the one place that legitimately substitutes it is the artifact
101
+ * reader (`request-artifact-metadata.ts`), which labels the substitution.
102
+ */
103
+ requestType: RequestType;
104
+ /**
105
+ * False for a caller that is not a state move — the retag command's impact
106
+ * probe reads the table without transitioning anything, and the event stream
107
+ * is read as a record of transitions.
108
+ */
109
+ emitEvents?: boolean;
89
110
  };
90
- export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType?: RequestType): ReadonlyArray<ArtifactPrerequisite>;
91
- /**
92
- * The contract's BODY checks for one prerequisite, applied to `body`. Returns
93
- * one human-readable message per failed check, empty when the body satisfies
94
- * the contract.
95
- *
96
- * Exported because this contract has a SECOND enforcer: `peaks workflow
97
- * verify-pipeline` probes the same table for the paths it checks
98
- * (`pipeline-verify-gate-support.ts`), and a resolver that probed only
99
- * `existsSync` passed files this function rejects — a guard laxer than the
100
- * contract it claims to read. Both callers now share this one implementation,
101
- * so the checker cannot drift from the table again.
102
- */
103
- export declare function prerequisiteBodyViolations(prerequisite: ArtifactPrerequisite, body: string): string[];
111
+ export declare function getPrerequisitesFor(role: RequestArtifactRole, newState: RequestArtifactState, requestType: RequestType): ReadonlyArray<ArtifactPrerequisite>;
104
112
  export declare function checkPrerequisites(options: CheckPrerequisitesOptions): Promise<PrerequisiteCheckResult>;