peaks-loop 4.1.4 → 4.1.5

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 (240) hide show
  1. package/.claude-plugin/marketplace.json +7 -2
  2. package/CHANGELOG.md +112 -0
  3. package/README-en.md +1 -1
  4. package/README.md +1 -1
  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/code-commands.d.ts +6 -4
  9. package/dist/cli/commands/code-commands.js +6 -4
  10. package/dist/cli/commands/code-gate-command.d.ts +5 -5
  11. package/dist/cli/commands/code-gate-command.js +49 -9
  12. package/dist/cli/commands/code-mode-gate-plan-command.d.ts +1 -1
  13. package/dist/cli/commands/code-mode-gate-plan-command.js +2 -2
  14. package/dist/cli/commands/core/memory-extract-command.js +10 -5
  15. package/dist/cli/commands/dispatch-cli-invocation-check.d.ts +108 -0
  16. package/dist/cli/commands/dispatch-cli-invocation-check.js +87 -0
  17. package/dist/cli/commands/dispatch-cli-invocation-scan.d.ts +66 -0
  18. package/dist/cli/commands/dispatch-cli-invocation-scan.js +162 -0
  19. package/dist/cli/commands/dispatch-commands.js +12 -5
  20. package/dist/cli/commands/dispatch-preflight.js +46 -0
  21. package/dist/cli/commands/dispatch-prompt-composition.d.ts +6 -0
  22. package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
  23. package/dist/cli/commands/doc-commands.js +1 -1
  24. package/dist/cli/commands/feedback-commands-helpers.js +1 -1
  25. package/dist/cli/commands/final-review-prepare-command.js +22 -1
  26. package/dist/cli/commands/gate-commands-enforce.js +3 -3
  27. package/dist/cli/commands/hook-handle.js +41 -20
  28. package/dist/cli/commands/lint-commands.js +3 -1
  29. package/dist/cli/commands/loop-eval-capture-index.js +2 -4
  30. package/dist/cli/commands/perf-audit-commands.js +15 -5
  31. package/dist/cli/commands/project-commands.js +9 -6
  32. package/dist/cli/commands/race-commands.d.ts +15 -0
  33. package/dist/cli/commands/race-commands.js +65 -0
  34. package/dist/cli/commands/race-pilot-gate-record-command.d.ts +3 -0
  35. package/dist/cli/commands/race-pilot-gate-record-command.js +81 -0
  36. package/dist/cli/commands/request-command-options.d.ts +8 -0
  37. package/dist/cli/commands/request-commands.js +2 -0
  38. package/dist/cli/commands/request-init-command.js +67 -12
  39. package/dist/cli/commands/request-retag-command.d.ts +3 -0
  40. package/dist/cli/commands/request-retag-command.js +50 -0
  41. package/dist/cli/commands/request-show-command.d.ts +8 -0
  42. package/dist/cli/commands/request-show-command.js +14 -1
  43. package/dist/cli/commands/request-transition-command.js +12 -4
  44. package/dist/cli/commands/request-transition-failures.d.ts +14 -0
  45. package/dist/cli/commands/request-transition-failures.js +45 -3
  46. package/dist/cli/commands/scan-scope-commands.js +2 -2
  47. package/dist/cli/commands/security-audit-commands.js +26 -6
  48. package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
  49. package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
  50. package/dist/services/artifacts/artifact-contract-block.js +212 -0
  51. package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
  52. package/dist/services/artifacts/artifact-prerequisites.js +63 -133
  53. package/dist/services/artifacts/artifact-templates.d.ts +1 -1
  54. package/dist/services/artifacts/artifact-templates.js +17 -10
  55. package/dist/services/artifacts/prerequisite-checks.d.ts +87 -0
  56. package/dist/services/artifacts/prerequisite-checks.js +198 -0
  57. package/dist/services/artifacts/prerequisite-transition-event.d.ts +20 -0
  58. package/dist/services/artifacts/prerequisite-transition-event.js +27 -0
  59. package/dist/services/artifacts/request-artifact-metadata.d.ts +31 -0
  60. package/dist/services/artifacts/request-artifact-metadata.js +44 -0
  61. package/dist/services/artifacts/request-artifact-service.d.ts +5 -0
  62. package/dist/services/artifacts/request-artifact-service.js +23 -51
  63. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +12 -0
  64. package/dist/services/artifacts/request-artifact-state-helpers.js +28 -4
  65. package/dist/services/artifacts/request-retag-service.d.ts +68 -0
  66. package/dist/services/artifacts/request-retag-service.js +125 -0
  67. package/dist/services/artifacts/request-state-order.d.ts +38 -0
  68. package/dist/services/artifacts/request-state-order.js +99 -0
  69. package/dist/services/artifacts/request-type-demand.d.ts +44 -0
  70. package/dist/services/artifacts/request-type-demand.js +71 -0
  71. package/dist/services/audit/audit-goal-service.d.ts +7 -0
  72. package/dist/services/audit/enforcers/active-skill-resolver.d.ts +18 -0
  73. package/dist/services/audit/enforcers/active-skill-resolver.js +48 -1
  74. package/dist/services/audit/enforcers/code-ban.d.ts +11 -2
  75. package/dist/services/audit/enforcers/code-ban.js +21 -1
  76. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.d.ts +17 -0
  77. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.js +24 -7
  78. package/dist/services/audit-independent/handoff-missing-refusal.d.ts +26 -0
  79. package/dist/services/audit-independent/handoff-missing-refusal.js +109 -0
  80. package/dist/services/audit-independent/handoff-readers.d.ts +37 -0
  81. package/dist/services/audit-independent/handoff-readers.js +81 -0
  82. package/dist/services/audit-independent/index.d.ts +6 -1
  83. package/dist/services/audit-independent/index.js +6 -1
  84. package/dist/services/audit-independent/judged-declaration-build.d.ts +48 -0
  85. package/dist/services/audit-independent/judged-declaration-build.js +73 -0
  86. package/dist/services/audit-independent/judged-declaration-check.d.ts +79 -0
  87. package/dist/services/audit-independent/judged-declaration-check.js +155 -0
  88. package/dist/services/audit-independent/judged-declaration.d.ts +94 -0
  89. package/dist/services/audit-independent/judged-declaration.js +218 -0
  90. package/dist/services/audit-independent/perf-audit-service.js +12 -14
  91. package/dist/services/audit-independent/security-audit-artifact.d.ts +28 -0
  92. package/dist/services/audit-independent/security-audit-artifact.js +90 -0
  93. package/dist/services/audit-independent/security-audit-service.d.ts +6 -53
  94. package/dist/services/audit-independent/security-audit-service.js +34 -178
  95. package/dist/services/capability-guard-runner/contracts/J05.js +60 -14
  96. package/dist/services/codegraph/codegraph-index-integrity.js +2 -0
  97. package/dist/services/context/build-dispatch-system-prompt.d.ts +3 -3
  98. package/dist/services/context/build-dispatch-system-prompt.js +7 -7
  99. package/dist/services/context/collector.js +5 -1
  100. package/dist/services/dispatch/active-dispatch-index.d.ts +36 -0
  101. package/dist/services/dispatch/active-dispatch-index.js +118 -0
  102. package/dist/services/dispatch/batch-counter.js +1 -2
  103. package/dist/services/dispatch/dispatch-record-writer.d.ts +29 -16
  104. package/dist/services/dispatch/dispatch-record-writer.js +58 -100
  105. package/dist/services/dispatch/dispatch-sub-agent.js +1 -1
  106. package/dist/services/dispatch/karpathy-block.d.ts +55 -0
  107. package/dist/services/dispatch/karpathy-block.js +101 -0
  108. package/dist/services/dispatch/ledger-reaper.d.ts +80 -0
  109. package/dist/services/dispatch/ledger-reaper.js +131 -0
  110. package/dist/services/evidence/evidence-generator.js +15 -8
  111. package/dist/services/feedback/feedback-promotion-service.d.ts +8 -11
  112. package/dist/services/feedback/feedback-promotion-service.js +30 -35
  113. package/dist/services/feedback/promotion-artifact-json-evidence.d.ts +18 -0
  114. package/dist/services/feedback/promotion-artifact-missing.d.ts +22 -0
  115. package/dist/services/feedback/promotion-artifact-missing.js +63 -0
  116. package/dist/services/final-review/final-review-contract.d.ts +95 -4
  117. package/dist/services/final-review/final-review-contract.js +64 -0
  118. package/dist/services/final-review/final-review-delivery.d.ts +13 -0
  119. package/dist/services/final-review/final-review-delivery.js +26 -12
  120. package/dist/services/final-review/final-review-evidence-collect.js +8 -53
  121. package/dist/services/final-review/final-review-evidence-records.d.ts +21 -0
  122. package/dist/services/final-review/final-review-evidence-records.js +67 -0
  123. package/dist/services/final-review/final-review-evidence-sources.d.ts +22 -0
  124. package/dist/services/final-review/final-review-evidence-sources.js +28 -4
  125. package/dist/services/final-review/final-review-prompt.js +19 -6
  126. package/dist/services/final-review/final-review-runner.js +5 -0
  127. package/dist/services/final-review/final-review-service.d.ts +2 -2
  128. package/dist/services/final-review/index.d.ts +1 -1
  129. package/dist/services/final-review/pre-post-diff.d.ts +2 -75
  130. package/dist/services/final-review/pre-post-diff.js +60 -59
  131. package/dist/services/hooks/pre-tool-code-gate.d.ts +7 -1
  132. package/dist/services/hooks/pre-tool-code-gate.js +21 -2
  133. package/dist/services/hooks/worktree-authorization-gate.js +6 -31
  134. package/dist/services/hooks/worktree-refusal-messages.d.ts +74 -0
  135. package/dist/services/hooks/worktree-refusal-messages.js +102 -0
  136. package/dist/services/lint/eslint-runner-support.d.ts +1 -1
  137. package/dist/services/lint/eslint-runner-support.js +2 -1
  138. package/dist/services/lint/eslint-runner-types.d.ts +8 -0
  139. package/dist/services/lint/eslint-runner.js +17 -4
  140. package/dist/services/llm/anthropic-runner.js +24 -7
  141. package/dist/services/loop/loop-observability.d.ts +39 -0
  142. package/dist/services/loop/loop-observability.js +55 -0
  143. package/dist/services/loop/monotonic-guard.js +6 -9
  144. package/dist/services/loop/monotonic-runner.js +8 -7
  145. package/dist/services/loop/run-driver.js +18 -22
  146. package/dist/services/memory/project-memory-service/index/kind-dispatch.js +14 -1
  147. package/dist/services/memory/project-memory-service/index/project-memory-plan-exec.js +13 -2
  148. package/dist/services/memory/project-memory-service/index.d.ts +2 -2
  149. package/dist/services/memory/project-memory-service/index.js +1 -1
  150. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.d.ts +36 -0
  151. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.js +48 -2
  152. package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts +23 -1
  153. package/dist/services/memory/project-memory-service/parsers/markdown-pure.js +37 -0
  154. package/dist/services/memory/project-memory-service/types.d.ts +32 -0
  155. package/dist/services/observability/observability-service.d.ts +7 -0
  156. package/dist/services/observability/observability-service.js +2 -1
  157. package/dist/services/prd/gate-evidence-derivation.d.ts +4 -3
  158. package/dist/services/prd/gate-evidence-derivation.js +4 -3
  159. package/dist/services/qa/bdd-test-style-verifier.js +22 -8
  160. package/dist/services/race/gate2-evaluator.d.ts +58 -0
  161. package/dist/services/race/gate2-evaluator.js +111 -0
  162. package/dist/services/race/gate2-policy.d.ts +17 -0
  163. package/dist/services/race/gate2-policy.js +31 -0
  164. package/dist/services/race/lane-phase.d.ts +19 -0
  165. package/dist/services/race/lane-phase.js +113 -0
  166. package/dist/services/race/pilot-gate-store.d.ts +67 -0
  167. package/dist/services/race/pilot-gate-store.js +227 -0
  168. package/dist/services/scan/file-size-baseline.d.ts +26 -0
  169. package/dist/services/scan/file-size-baseline.js +150 -0
  170. package/dist/services/scan/file-size-scan.d.ts +42 -3
  171. package/dist/services/scan/file-size-scan.js +58 -42
  172. package/dist/services/scan/type-sanity-service.js +13 -3
  173. package/dist/services/skill/resume-detector.js +3 -3
  174. package/dist/services/skills/hooks-codegate-superpowers.d.ts +5 -6
  175. package/dist/services/skills/hooks-codegate-superpowers.js +7 -8
  176. package/dist/services/skills/hooks-settings-service.d.ts +1 -1
  177. package/dist/services/skills/hooks-settings-service.js +1 -1
  178. package/dist/services/skills/presence-lease-order.d.ts +13 -0
  179. package/dist/services/skills/presence-lease-order.js +24 -0
  180. package/dist/services/skills/skill-conformance-service.js +1 -0
  181. package/dist/services/skills/skill-statusline-service.js +4 -7
  182. package/dist/services/slice/slice-check-service.js +8 -8
  183. package/dist/services/workflow/pipeline-verify-gate-support.js +2 -1
  184. package/dist/services/workflow/pipeline-verify-service.js +1 -1
  185. package/dist/services/workflow/workflow-skip-service.d.ts +0 -20
  186. package/dist/services/workflow/workflow-skip-service.js +3 -4
  187. package/dist/services/workspace/claude-settings-retirements.d.ts +54 -0
  188. package/dist/services/workspace/claude-settings-retirements.js +112 -0
  189. package/dist/services/workspace/claude-settings-template-merge.d.ts +35 -15
  190. package/dist/services/workspace/claude-settings-template-merge.js +33 -53
  191. package/dist/services/workspace/claude-settings-template.d.ts +62 -12
  192. package/dist/services/workspace/claude-settings-template.js +58 -58
  193. package/dist/services/workspace/migrate-1-4-1-service.js +3 -0
  194. package/dist/services/workspace/reconcile-service.js +0 -1
  195. package/dist/shared/incrementing-number.d.ts +10 -0
  196. package/dist/shared/incrementing-number.js +27 -0
  197. package/package.json +5 -5
  198. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  199. package/skills/bee/peaks-prd/SKILL.md +1 -1
  200. package/skills/bee/peaks-qa/SKILL.md +1 -1
  201. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  202. package/skills/bee/peaks-qa/references/qa-transition-gates.md +1 -1
  203. package/skills/bee/peaks-rd/SKILL.md +2 -2
  204. package/skills/bee/peaks-rd/references/rd-fanout-contracts.md +1 -1
  205. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +8 -4
  206. package/skills/bee/peaks-rd/references/rd-transition-gates.md +3 -3
  207. package/skills/bee/peaks-rd/references/v2-12-fanout-collapse.md +2 -2
  208. package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md +1 -1
  209. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  210. package/skills/bee/peaks-sc/SKILL.md +1 -1
  211. package/skills/bee/peaks-security-audit/SKILL.md +10 -2
  212. package/skills/bee/peaks-txt/SKILL.md +4 -3
  213. package/skills/bee/peaks-ui/SKILL.md +3 -3
  214. package/skills/peaks-audit/SKILL.md +29 -1
  215. package/skills/peaks-code/SKILL.md +5 -2
  216. package/skills/peaks-code/references/fast-lane-norm.md +42 -0
  217. package/skills/peaks-code/references/fast-mode.md +3 -2
  218. package/skills/peaks-code/references/local-artifact-workspace.md +3 -3
  219. package/skills/peaks-code/references/micro-cycle.md +3 -3
  220. package/skills/peaks-code/references/resume-detection.md +1 -1
  221. package/skills/peaks-code/references/runbook.md +12 -6
  222. package/skills/peaks-code/references/step-11-memory-sediment.md +4 -0
  223. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  224. package/skills/peaks-code/references/swarm-dispatch-contract.md +40 -16
  225. package/skills/peaks-code/references/workflow-gates-and-types.md +6 -6
  226. package/skills/peaks-code/references/worktree-governance.md +4 -4
  227. package/skills/peaks-content/SKILL.md +1 -1
  228. package/skills/peaks-doctor/SKILL.md +1 -1
  229. package/skills/peaks-final-review/SKILL.md +31 -11
  230. package/skills/peaks-ide/SKILL.md +1 -1
  231. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  232. package/skills/peaks-race-code/SKILL.md +185 -0
  233. package/skills/peaks-resume/SKILL.md +1 -1
  234. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  235. package/skills/peaks-solo/SKILL.md +1 -1
  236. package/skills/peaks-sop/SKILL.md +1 -1
  237. package/skills/peaks-status/SKILL.md +1 -1
  238. package/skills/peaks-test/SKILL.md +7 -4
  239. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.d.ts +0 -23
  240. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.js +0 -64
@@ -1,8 +1,9 @@
1
1
  import { join, dirname, basename } from 'node:path';
2
2
  import { readFile, readdir } from 'node:fs/promises';
3
3
  import { pathExists } from 'peaks-loop-shared/fs';
4
- import { emitObservabilityEvent } from '../observability/observability-service.js';
4
+ import { emitPrereqTransitionEvent } from './prerequisite-transition-event.js';
5
5
  import { isUnsafePathInput } from '../../shared/path-safety.js';
6
+ import { bodyViolationsIfDeclared, missingPrerequisiteWarning } from './prerequisite-checks.js';
6
7
  export const VALID_REQUEST_TYPES = [
7
8
  'feature',
8
9
  'bugfix',
@@ -15,41 +16,28 @@ export const DEFAULT_REQUEST_TYPE = 'feature';
15
16
  export function isRequestType(value) {
16
17
  return VALID_REQUEST_TYPES.includes(value);
17
18
  }
18
- // Shared prerequisite fragments
19
- // (Removed in v2.11.0 Group A: TECH_DOC prerequisite. The per-session
20
- // rd/tech-doc.md is replaced by the immutable peaks-prd handoff at
21
- // prd/handoff.md. Group B will introduce a PRD_HANDOFF prerequisite
22
- // once the handoff service lands. For Group A scope, `rd:implemented`
23
- // and `rd:qa-handoff` rely on the evidence files (code-review,
24
- // security-review, perf-baseline, karpathy-review, unit tests) only.)
19
+ // Shared prerequisite fragments.
25
20
  const BUG_ANALYSIS = {
26
- relativePath: 'rd/bug-analysis.md',
27
- description: 'Bug root-cause analysis (reproduction, affected paths, fix approach, regression test plan)',
21
+ relativePath: 'rd/bug-analysis-<rid>.md',
22
+ // The bare path below is still accepted, so an older session keeps passing.
23
+ legacyRelativePath: 'rd/bug-analysis.md',
24
+ description: 'Bug root-cause analysis (reproduction, affected paths, fix approach, regression test plan). The rid is part of the filename so two bugfix slices in one session do not collide; the bare location is accepted during the back-compat window via legacyRelativePath.',
28
25
  mustContain: ['## Root cause', '## Fix approach']
29
26
  };
30
- // filename (`code-review-<rid>.md`). A fixed per-session path cannot hold
31
- // two slices' evidence at once — the second slice's write silently
32
- // destroyed the first slice's on 2026-09-13, and the gate stayed green
33
- // because it only checks that *some* file is there, not whose it is.
34
- // The bare path stays accepted (see `legacyRelativePath`) so sessions
35
- // written before this change — and any writer still emitting it — keep
36
- // passing.
37
27
  const CODE_REVIEW = {
28
+ // The bare path below is still accepted, so an older session keeps passing.
38
29
  relativePath: 'rd/code-review-<rid>.md',
39
30
  legacyRelativePath: 'rd/code-review.md',
40
31
  description: 'Code review evidence (CRITICAL/HIGH must be fixed before handoff)',
41
32
  mustContain: ['## Findings', 'CRITICAL']
42
33
  };
43
34
  const SECURITY_REVIEW = {
44
- relativePath: 'rd/security-review.md',
45
- description: 'Security review evidence for the changed surface'
35
+ relativePath: 'rd/security-review-<rid>.md',
36
+ // The bare path is the legacy tier, so a session already on disk keeps passing.
37
+ legacyRelativePath: 'rd/security-review.md',
38
+ description: 'Security review evidence for the changed surface. The rid is part of the filename so two config slices in one session do not collide; the bare location is the legacy tier. The body is never read, so a collision here was silent.'
46
39
  };
47
- // Gate B9 — RD-side perf baseline (peaks-rd SKILL "Parallel review fan-out").
48
- // The file must exist; the body must either carry a Results table marker
49
- // (per peaks-rd SKILL "Mandatory perf-baseline output") or the explicit
50
- // "N/A — no perf surface" escape hatch. A slice without a perf surface
51
- // still has to write the stub; an RD that omits perf-baseline entirely is
52
- // blocked here, matching peaks-rd's BLOCKING Gate B9 claim.
40
+ // Gate B9 — RD-side perf baseline: the body carries a Results table or "N/A — no perf surface".
53
41
  const PERF_BASELINE = {
54
42
  relativePath: 'rd/perf-baseline.md',
55
43
  description: 'RD-side perf baseline (peaks-rd Gate B9) — must include a Results table with measurements OR the literal "N/A — no perf surface" escape hatch in the Notes section. QA Gate A4 diffs against this file.',
@@ -105,28 +93,31 @@ const AUDIT_PERF = {
105
93
  // rd-side CLI hard gate (blocks `rd → qa-handoff`), while qa-side
106
94
  // consumption remains soft.
107
95
  //
108
- // `backCompat: true` is set, a MISSING file downgrades to a warning
109
- // (`mut-report-missing-deprecated-in-v2.14.0`) instead of a hard
110
- // failure. The hard-fail behavior for `passed: false` is preserved
96
+ // `backCompat: true` is set, a MISSING file downgrades to a warning instead
97
+ // of a hard failure. The hard-fail behavior for `passed: false` is preserved
111
98
  // (the body still has to carry `"passed": true` when present).
112
99
  // v2.14.0 will remove `backCompat` and re-elevate missing → throw.
100
+ // The warning's code is derived from this prerequisite
101
+ // (`backCompatWarningCode` → `mut-report-missing-deprecated-in-v2.14.0`)
102
+ // rather than hardcoded in the shared branch, so a consumer filtering on the
103
+ // code cannot match a different artifact's warning.
113
104
  //
114
- // repo's own producer/reader constant is `mutReportPath()` in
115
- // `packages/peaks-loop-mut/src/services/mut/report-loader.ts`, which names
116
- // `mut/mut-report.json`, and `peaks mut run`'s `--out` is supplied by the
117
- // caller. A `<rid>`-templated requirement here would be a name no producer
118
- // in the repo can write — a gate that exists only in prose, sitting behind
119
- // `backCompat: true` so it gates nothing at all. If mut ever gains a
105
+ // The repo's producer/reader constant is `mutReportPath()` in
106
+ // `packages/peaks-loop-mut/src/services/mut/report-loader.ts`, naming
107
+ // `mut/mut-report.json`; `peaks mut run`'s `--out` is caller-supplied. A
108
+ // `<rid>`-templated requirement here would name no file a producer can write —
109
+ // a gate living only in prose, behind `backCompat: true`, gating nothing.
120
110
  const MUT_REPORT = {
121
111
  relativePath: 'mut/mut-report.json',
122
- description: 'peaks-mut mutation + weak-assertion report (Plan 2, v2.12.0+). v2.13.1: required at rd:qa-handoff for feature / bugfix / refactor slices. v2.13.2: back-compat window — missing file downgrades to a warning (1-minor-release); passed:false still throws. The body must carry `"passed": true` when present; failed runs are blocked at this gate. CONFIG / DOCS / CHORE slices retain the legacy "no acceptance surface" exemption.',
112
+ description: 'peaks-mut mutation + weak-assertion report (Plan 2, v2.12.0+). v2.13.1: the artifact contract requires this at rd:qa-handoff for feature / bugfix / refactor slices — `peaks workflow verify-pipeline` is what checks that, and it reads this table rather than the transition. v2.13.2: back-compat window — missing file downgrades to a warning (1-minor-release); passed:false still throws. The body must carry `"passed": true` when present; failed runs are blocked at this gate. CONFIG / DOCS / CHORE slices retain the legacy "no acceptance surface" exemption.',
123
113
  // Substring check on the JSON property name only — strictness (kill
124
114
  // rate ≥ 0.8 etc.) is enforced downstream by verdict-aggregator +
125
115
  // peaks-mut's evaluateThresholds. We require both the property name
126
116
  // and a literal `true` value to keep the gate as tight as possible
127
117
  // without depending on JSON parsing in the prereq resolver.
128
118
  mustContainAny: ['"passed": true', '"passed":true'],
129
- backCompat: true
119
+ backCompat: true,
120
+ backCompatUntil: 'v2.14.0'
130
121
  };
131
122
  // v2.12.0 Group B Tier 5 — gate that the peaks-prd handoff (the
132
123
  // immutable, per-slice handoff capsule at `prd/handoff-<rid>.md`
@@ -151,7 +142,7 @@ const AUDIT_REQUIRES_HANDOFF = {
151
142
  // sessions on disk that hold only `prd/handoff.md` keep passing. That tier
152
143
  // on, and every producer (`handoff-service.initHandoff`,
153
144
  legacyRelativePath: 'prd/handoff.md',
154
- description: 'PRD handoff capsule (v2.12.0+) — peaks-security-audit / peaks-perf-audit both read frontmatter from this file. Must exist before audit prereqs are evaluated at rd:qa-handoff. The rid is part of the filename so two slices in one session do not collide; the bare pre-rid-scoping location is accepted as the legacy tier.',
145
+ description: 'PRD handoff capsule (v2.12.0+) — peaks-security-audit / peaks-perf-audit both read frontmatter from this file. There is no dependency on the transition: the ARTIFACT CONTRACT is what binds every reader of this table, and `peaks workflow verify-pipeline` is what checks the contract on disk (`contractEvidencePaths()` reads this table; a state name does not). The `rd:qa-handoff` transition enforces this same table through `checkPrerequisites`, so a missing prerequisite blocks the state move and is reported without one — the table is checked the same way with or without a transition. The rid is part of the filename so two slices in one session do not collide; the bare pre-rid-scoping location is accepted as the legacy tier.',
155
146
  // Empty `mustContain` is fine — file existence is the contract.
156
147
  // The peaks-prd handoff service writes frontmatter with
157
148
  // `schemaVersion: 2` and a sha256 fingerprint; we pin a
@@ -197,7 +188,8 @@ const THIRD_PARTY_REVIEW = {
197
188
  relativePath: 'rd/third-party-review.md',
198
189
  description: 'v2.14.0 G4 third-party reviewer (peaks-reviewer skill) — must declare a `modelFamily` distinct from the karpathy-reviewer modelFamily (AC-4.4). Skipped when `~/.peaks/config.json` lacks `reviewer.providers` (>=2 entries); the prereq then resolves to a soft warning (`no-reviewer-config`) rather than a hard failure. The JSON sibling at `rd/third-party-review.json` carries the schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 ships as a soft-warning prereq (1-minor-release back-compat window); v2.15.0 will hard-fail when the file is absent AND `reviewer.providers` is configured.',
199
190
  mustContain: ['third-party-review', 'modelFamily'],
200
- backCompat: true
191
+ backCompat: true,
192
+ backCompatUntil: 'v2.15.0'
201
193
  };
202
194
  const TEST_CASES = {
203
195
  relativePath: 'qa/test-cases/<rid>.md',
@@ -257,13 +249,10 @@ const QA_INITIATED = {
257
249
  relativePath: 'qa/.initiated',
258
250
  description: 'QA skill must be invoked before RD handoff (run peaks request init --role qa)'
259
251
  };
260
- // v2.11.0 D1/D4 trim (Group C Tier 6): peaks-qa no longer requires
261
- // qa/security-findings.md or qa/performance-findings.md at qa:verdict-issued.
262
- // Those are owned by peaks-rd's audit fan-out (rd/security-review.md and
263
- // rd/perf-baseline.md). QA references them by path from the test-report body
264
- // (see qa-transition-gates.md Gates A3/A4). SECURITY_FINDINGS /
265
- // PERFORMANCE_FINDINGS constants are kept for back-compat and a 1-minor-
266
- // release deprecation window but are NOT in any qa:verdict-issued table.
252
+ // v2.11.0 D1/D4 trim (Group C Tier 6): no qa:verdict-issued table holds
253
+ // qa/security-findings.md or qa/performance-findings.md — peaks-rd's audit
254
+ // fan-out owns that evidence. Both constants below are kept for back-compat
255
+ // only: `evidence-generator.ts` writes the scoped names, not these.
267
256
  //
268
257
  // v2.12.0 Group B Tier 5: at rd:qa-handoff, the v2.11.x security-review +
269
258
  // perf-baseline slots are replaced by `AUDIT_SECURITY` + `AUDIT_PERF` (the
@@ -303,8 +292,7 @@ const FEATURE_TABLE = {
303
292
  // v2.11.0 D1/D4: SECURITY_FINDINGS dropped from qa:verdict-issued (peaks-rd owns it).
304
293
  // v2.12.0 Group B Tier 5: security-review + perf-baseline → AUDIT_SECURITY +
305
294
  // AUDIT_PERF (with legacy shims for 1-minor-release back-compat).
306
- // v2.13.1 Group A: add MUT_REPORT (same rd-side hard block rationale as
307
- // FEATURE_TABLE).
295
+ // v2.13.1 Group A: add MUT_REPORT (same rd-side hard block rationale as FEATURE_TABLE).
308
296
  const BUGFIX_TABLE = {
309
297
  'prd:handed-off': [PRD_CONTENT],
310
298
  'rd:implemented': [BUG_ANALYSIS],
@@ -345,7 +333,7 @@ const PREREQUISITES_BY_TYPE = {
345
333
  config: CONFIG_TABLE,
346
334
  chore: MINIMAL_TABLE
347
335
  };
348
- export function getPrerequisitesFor(role, newState, requestType = DEFAULT_REQUEST_TYPE) {
336
+ export function getPrerequisitesFor(role, newState, requestType) {
349
337
  const table = PREREQUISITES_BY_TYPE[requestType];
350
338
  return table[`${role}:${newState}`] ?? [];
351
339
  }
@@ -383,57 +371,6 @@ async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, reques
383
371
  const match = entries.find((name) => /^\d+-/.test(name) && name.endsWith(targetSuffix));
384
372
  return match ? join(dir, match) : null;
385
373
  }
386
- /**
387
- * The contract's BODY checks for one prerequisite, applied to `body`. Returns
388
- * one human-readable message per failed check, empty when the body satisfies
389
- * the contract.
390
- *
391
- * Exported because this contract has a SECOND enforcer: `peaks workflow
392
- * verify-pipeline` probes the same table for the paths it checks
393
- * (`pipeline-verify-gate-support.ts`), and a resolver that probed only
394
- * `existsSync` passed files this function rejects — a guard laxer than the
395
- * contract it claims to read. Both callers now share this one implementation,
396
- * so the checker cannot drift from the table again.
397
- */
398
- export function prerequisiteBodyViolations(prerequisite, body) {
399
- const violations = [];
400
- const lowered = body.toLowerCase();
401
- if (prerequisite.mustContain && prerequisite.mustContain.length > 0) {
402
- const missingMarkers = prerequisite.mustContain.filter((marker) => !lowered.includes(marker.toLowerCase()));
403
- if (missingMarkers.length > 0) {
404
- violations.push(`${prerequisite.description} — missing section(s): ${missingMarkers.join(', ')}`);
405
- }
406
- }
407
- if (prerequisite.headingMustContain && prerequisite.headingMustContain.length > 0) {
408
- // Slice 2.6.1.F: a line beginning with `#`, `##`, or `###` followed by
409
- // the marker (case-insensitive). Fenced code blocks are NOT excluded
410
- // here — a "heading" inside a code fence is rare and, when present,
411
- // should still be reported as missing to keep the contract strict.
412
- const headingLines = body
413
- .split('\n')
414
- .map((line) => line.trim())
415
- .filter((line) => /^#{1,3}\s+/.test(line));
416
- const loweredHeadings = headingLines.map((h) => h.toLowerCase());
417
- const missingHeadings = prerequisite.headingMustContain.filter((marker) => !loweredHeadings.some((h) => h.includes(marker.toLowerCase())));
418
- if (missingHeadings.length > 0) {
419
- violations.push(`${prerequisite.description} — missing heading(s): ${missingHeadings.join(', ')}`);
420
- }
421
- }
422
- if (prerequisite.mustContainAny && prerequisite.mustContainAny.length > 0) {
423
- const hitAny = prerequisite.mustContainAny.some((marker) => lowered.includes(marker.toLowerCase()));
424
- if (!hitAny) {
425
- violations.push(`${prerequisite.description} — none of the escape-hatch markers present: ${prerequisite.mustContainAny.join(', ')}`);
426
- }
427
- }
428
- return violations;
429
- }
430
- /** True when `prerequisite` declares any body check at all. Guards the read so
431
- * a prereq with no body contract is never opened (unchanged behaviour). */
432
- function hasBodyChecks(prerequisite) {
433
- return ((prerequisite.mustContain?.length ?? 0) > 0 ||
434
- (prerequisite.headingMustContain?.length ?? 0) > 0 ||
435
- (prerequisite.mustContainAny?.length ?? 0) > 0);
436
- }
437
374
  export async function checkPrerequisites(options) {
438
375
  const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
439
376
  if (requirements.length === 0) {
@@ -466,25 +403,21 @@ export async function checkPrerequisites(options) {
466
403
  const relative = resolvePrerequisitePath(prerequisite, options.requestId);
467
404
  const absolute = await resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, options.requestId);
468
405
  if (absolute === null) {
469
- // file downgrades to a warning, NOT a hard failure. v2.14.0
470
- // will remove this branch and re-elevate missing → throw.
471
- const backCompat = prerequisite.backCompat === true;
472
- if (backCompat) {
473
- warnings.push({
474
- path: relative,
475
- code: 'mut-report-missing-deprecated-in-v2.14.0',
476
- message: `${prerequisite.description} — file missing; soft-blocked under v2.13.2 1-minor back-compat window. v2.14.0 hard-fail.`
477
- });
406
+ // A `backCompat` prerequisite downgrades a missing file to a warning, NOT
407
+ // a hard failure; v2.14.0/v2.15.0 re-elevate it. The decision and the
408
+ // code that names the artifact live in `prerequisite-checks.ts`.
409
+ const softWarning = missingPrerequisiteWarning(prerequisite, relative);
410
+ if (softWarning !== null) {
411
+ warnings.push(softWarning);
478
412
  continue;
479
413
  }
480
414
  missing.push({ path: relative, description: prerequisite.description });
481
415
  continue;
482
416
  }
483
- if (hasBodyChecks(prerequisite)) {
484
- const body = await readFile(absolute, 'utf8');
485
- for (const description of prerequisiteBodyViolations(prerequisite, body)) {
486
- missing.push({ path: relative, description });
487
- }
417
+ // Read handed over as a thunk: the no-body-contract guard lives with the check.
418
+ const bodyViolations = await bodyViolationsIfDeclared(prerequisite, () => readFile(absolute, 'utf8'));
419
+ for (const description of bodyViolations) {
420
+ missing.push({ path: relative, description });
488
421
  }
489
422
  }
490
423
  // own `gateEvidence` DECLARATION must be true — every path it names must
@@ -519,8 +452,25 @@ export async function checkPrerequisites(options) {
519
452
  });
520
453
  missing.push(...declaredEvidence.missing);
521
454
  warnings.push(...declaredEvidence.warnings);
455
+ // The security audit artifact declares the paths it judged; the check
456
+ // re-hashes them, so a repair after the audit is refused by name. An
457
+ // artifact with no declaration is refused here, not waved through — a
458
+ // deleted section is the shed this arm exists to close.
459
+ const { verifyJudgedDeclaration } = await import('../audit-independent/judged-declaration-check.js');
460
+ for (const refusal of verifyJudgedDeclaration({
461
+ projectRoot: options.projectRoot,
462
+ sessionId: options.sessionId,
463
+ requestId: options.requestId
464
+ }).refusals) {
465
+ missing.push({
466
+ path: refusal.artifact,
467
+ description: `Judged declaration ${refusal.code} at ${refusal.path}`
468
+ });
469
+ }
522
470
  }
523
471
  const result = { ok: missing.length === 0, missing, warnings };
472
+ if (options.emitEvents === false)
473
+ return result;
524
474
  emitPrereqTransitionEvent({
525
475
  projectRoot: options.projectRoot,
526
476
  sessionId: options.sessionId ?? '',
@@ -531,26 +481,6 @@ export async function checkPrerequisites(options) {
531
481
  });
532
482
  return result;
533
483
  }
534
- // Slice C of v2.11.1 — observability hook #7/7. Fire-and-forget per
535
- // PRD Q4. The synchronous emit never throws and never blocks the
536
- // prereq check return value.
537
- function emitPrereqTransitionEvent(opts) {
538
- if (opts.sessionId === undefined)
539
- return;
540
- emitObservabilityEvent({
541
- schemaVersion: 1,
542
- ts: new Date().toISOString(),
543
- sessionId: opts.sessionId,
544
- category: 'slice-transition',
545
- sliceRid: opts.requestId,
546
- detail: {
547
- artifactRole: opts.role,
548
- to: opts.newState,
549
- prereqOk: opts.result.ok,
550
- missingCount: opts.result.missing.length
551
- }
552
- }, { projectRoot: opts.projectRoot });
553
- }
554
484
  /**
555
485
  * Resolve a prerequisite to an on-disk path, with a 2-tier fallback
556
486
  * dirs are no longer created):
@@ -26,4 +26,4 @@ export declare function formatHandoffPath(sessionId: string, role: string, reque
26
26
  export declare function formatCommitBoundaryPath(sessionId: string, requestId: string): string;
27
27
  /** Canonical path for the txt skill-usage lessons log under a session scope. */
28
28
  export declare function formatSkillUsageLessonsPath(sessionId: string): string;
29
- export declare function renderTemplate(role: RequestArtifactRole, requestId: string, sessionId: string, changeSlug: string, timestamp: string, requestType: RequestType): string;
29
+ export declare function renderTemplate(role: RequestArtifactRole, requestId: string, sessionId: string, changeSlug: string, timestamp: string, requestType: RequestType | null): string;
@@ -25,12 +25,23 @@ export function formatCommitBoundaryPath(sessionId, requestId) {
25
25
  export function formatSkillUsageLessonsPath(sessionId) {
26
26
  return `.peaks/_runtime/${sessionId}/txt/skill-usage-lessons.md`;
27
27
  }
28
+ /**
29
+ * The artifact's own record of its type, or nothing when nobody chose one.
30
+ *
31
+ * `null` means `--type` was not passed. Emitting the default here would stamp a
32
+ * chosen-looking `- type: feature` onto every untyped request at the one moment
33
+ * the distinction is still knowable, and `extractMetadata` would then report
34
+ * every such request as declared. The absent line IS the record; the reader
35
+ * substitutes the default and labels it.
36
+ */
37
+ function renderTypeLine(requestType) {
38
+ return requestType === null ? '' : `- type: ${requestType}\n`;
39
+ }
28
40
  function renderPrdTemplate(requestId, _sessionId, sessionId, timestamp, requestType) {
29
41
  return (`# PRD Request ${requestId}
30
42
 
31
43
  - session: ${sessionId}
32
- - type: ${requestType}
33
- - source: <ticket, message URL, or "verbal" with a short sanitized quote>
44
+ ${renderTypeLine(requestType)}- source: <ticket, message URL, or "verbal" with a short sanitized quote>
34
45
  - raw input (sanitized): <one-paragraph restatement of what the user actually asked for>
35
46
 
36
47
  ` +
@@ -53,8 +64,7 @@ function renderUiTemplate(requestId, _sessionId, sessionId, timestamp, requestTy
53
64
 
54
65
  - session: ${sessionId}
55
66
  - linked-prd: ${formatHandoffPath(sessionId, 'prd', requestId)}
56
- - type: ${requestType}
57
- - scope: full new surface | iteration on existing surface | regression fix | visual refresh
67
+ ${renderTypeLine(requestType)}- scope: full new surface | iteration on existing surface | regression fix | visual refresh
58
68
  - design direction: editorial | bento | Swiss | luxury | retro-futurist | glass | product-system | other-explicit-name
59
69
 
60
70
  ` +
@@ -77,8 +87,7 @@ function renderRdTemplate(requestId, _sessionId, sessionId, timestamp, requestTy
77
87
  - session: ${sessionId}
78
88
  - linked-prd: ${formatHandoffPath(sessionId, 'prd', requestId)}
79
89
  - linked-ui: ${formatHandoffPath(sessionId, 'ui', requestId)} (when UI involved)
80
- - type: ${requestType}
81
-
90
+ ${renderTypeLine(requestType)}
82
91
  ` +
83
92
  RD_TEMPLATE_BODY +
84
93
  `## Handoff
@@ -100,8 +109,7 @@ function renderQaTemplate(requestId, _sessionId, sessionId, timestamp, requestTy
100
109
  - linked-prd: ${formatHandoffPath(sessionId, 'prd', requestId)}
101
110
  - linked-rd: ${formatHandoffPath(sessionId, 'rd', requestId)}
102
111
  - linked-ui: ${formatHandoffPath(sessionId, 'ui', requestId)} (when UI involved)
103
- - type: ${requestType}
104
-
112
+ ${renderTypeLine(requestType)}
105
113
  ` +
106
114
  QA_TEMPLATE_BODY +
107
115
  `## Status
@@ -119,8 +127,7 @@ function renderScTemplate(requestId, _sessionId, sessionId, timestamp, requestTy
119
127
  - linked-rd: ${formatHandoffPath(sessionId, 'rd', requestId)}
120
128
  - linked-qa: ${formatHandoffPath(sessionId, 'qa', requestId)}
121
129
  - linked-ui: ${formatHandoffPath(sessionId, 'ui', requestId)} (when UI involved)
122
- - type: ${requestType}
123
-
130
+ ${renderTypeLine(requestType)}
124
131
  ` +
125
132
  SC_TEMPLATE_BODY +
126
133
  `- artifact workspace path: .peaks/_runtime/${sessionId}/
@@ -0,0 +1,87 @@
1
+ /**
2
+ * How ONE prerequisite is judged: its body markers, and the soft-pass
3
+ * downgrade a missing file gets inside a back-compat window.
4
+ *
5
+ * WHY THIS IS A SIBLING AND NOT THREE MORE LINES IN THE TABLE.
6
+ * `artifact-prerequisites.ts` is over the 300-line file-size cap and
7
+ * `fileSizeExcessLines` is a ratchet that may only go DOWN
8
+ * (`.husky/peaks-gate-baseline-monotonic.mjs` — "Split the file; do not raise
9
+ * the ceiling"). The soft-pass branch this module was split out for must ADD
10
+ * lines to that file, so the body check its two enforcers share lives here,
11
+ * where the census counts no debt. `prerequisiteBodyViolations` moved verbatim;
12
+ * only its location changed.
13
+ */
14
+ import type { ArtifactPrerequisite } from './artifact-prerequisites.js';
15
+ /**
16
+ * The warning `code` for a prerequisite whose file is missing inside its
17
+ * back-compat window, derived from the prerequisite itself: the artifact's own
18
+ * filename stem plus the release that closes the window.
19
+ *
20
+ * The stem is what makes the code name WHICH artifact is missing — the branch
21
+ * this replaced emitted the literal `mut-report-missing-deprecated-in-v2.14.0`
22
+ * for EVERY `backCompat` prerequisite, so the `rd/third-party-review.md`
23
+ * warning carried the same code as the `mut/mut-report.json` one and a
24
+ * consumer filtering on it matched both. `backCompatUntil` keeps the
25
+ * deprecation semantics legible and is per-prerequisite, because the two live
26
+ * windows close in different releases (v2.14.0 and v2.15.0).
27
+ *
28
+ * The stem is taken verbatim: both prerequisites that carry `backCompat` name
29
+ * a fixed path, so no character is rewritten.
30
+ *
31
+ * TWO KNOWN LIMITS OF THE STEM, stated so neither is read as a guarantee:
32
+ * - a `<rid>`-templated soft prerequisite keeps the placeholder, producing
33
+ * the LITERAL `<rid>-missing-deprecated-in-…` — the same code for every
34
+ * request. The code is therefore not per-slice filterable. No live
35
+ * prerequisite carries `backCompat` with a `<rid>` path, so nothing
36
+ * filters on one today; the placeholder is the honest thing to print, and
37
+ * making it per-slice would mean resolving the rid into a code a consumer
38
+ * would have to know to match.
39
+ * - the stem comes from the FILENAME only, so two prerequisites sharing a
40
+ * stem collide (`x.md` and `x.json` both yield `x-…`). Measured 0 live
41
+ * collisions, and the pair that exists (`mut/mut-report.json` vs
42
+ * `rd/third-party-review.md`) differs by stem as well as by directory.
43
+ */
44
+ export declare function backCompatWarningCode(prerequisite: ArtifactPrerequisite): string;
45
+ /**
46
+ * The soft-pass warning for a missing `prerequisite`, or `null` when a missing
47
+ * file is a HARD failure and belongs in `missing` instead.
48
+ *
49
+ * The `null` is the whole decision, and it is the caller's only input to it. The
50
+ * invariant the two destinations have, stated exactly:
51
+ * - `warnings` does NOT feed `ok` — a soft pass is reported, never enforced,
52
+ * which is why this can be a warning at all;
53
+ * - `missing` IS what decides `ok` (`ok = missing.length === 0`), so choosing
54
+ * the `missing` branch is choosing to fail the gate. That is the point of
55
+ * the `null`, and the acceptance evidence for this change depends on it.
56
+ *
57
+ * `expiredWindow` is set only when the declared window has closed, so its
58
+ * PRESENCE is the verdict and `path` / `code` / `message` stay byte-identical for
59
+ * the consumers that already read them.
60
+ */
61
+ export declare function missingPrerequisiteWarning(prerequisite: ArtifactPrerequisite, relativePath: string, installedVersion?: string): {
62
+ path: string;
63
+ code: string;
64
+ message: string;
65
+ expiredWindow?: string;
66
+ } | null;
67
+ /**
68
+ * The contract's BODY checks for one prerequisite, applied to `body`. Returns
69
+ * one human-readable message per failed check, empty when the body satisfies
70
+ * the contract.
71
+ *
72
+ * Exported because this contract has a SECOND enforcer: `peaks workflow
73
+ * verify-pipeline` probes the same table for the paths it checks
74
+ * (`pipeline-verify-gate-support.ts`), and a resolver that probed only
75
+ * `existsSync` passed files this function rejects — a guard laxer than the
76
+ * contract it claims to read. Both callers now share this one implementation,
77
+ * so the checker cannot drift from the table again.
78
+ */
79
+ export declare function prerequisiteBodyViolations(prerequisite: ArtifactPrerequisite, body: string): string[];
80
+ /**
81
+ * The body violations for `prerequisite`, or `[]` when it declares no body
82
+ * contract — and in that case `read` is NEVER called, so a prerequisite with
83
+ * nothing to check never has its file opened (unchanged behaviour: the guard has
84
+ * always been a guard on the READ, which is why it takes the read as a thunk
85
+ * rather than the body).
86
+ */
87
+ export declare function bodyViolationsIfDeclared(prerequisite: ArtifactPrerequisite, read: () => Promise<string>): Promise<string[]>;