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
@@ -0,0 +1,198 @@
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 { basename, extname } from 'node:path';
15
+ import { CLI_VERSION } from 'peaks-loop-shared/version';
16
+ /** Stands in for a `backCompatUntil` nobody declared. ONE token for BOTH sites
17
+ * — the warning code and the message — so the two cannot disagree, and
18
+ * token-shaped like the version it stands in for. No live prerequisite omits
19
+ * the field, so this is unreachable today; the honest placeholder beats
20
+ * asserting a release nobody set. */
21
+ const UNDECLARED_WINDOW = 'a-future-release';
22
+ /**
23
+ * The warning `code` for a prerequisite whose file is missing inside its
24
+ * back-compat window, derived from the prerequisite itself: the artifact's own
25
+ * filename stem plus the release that closes the window.
26
+ *
27
+ * The stem is what makes the code name WHICH artifact is missing — the branch
28
+ * this replaced emitted the literal `mut-report-missing-deprecated-in-v2.14.0`
29
+ * for EVERY `backCompat` prerequisite, so the `rd/third-party-review.md`
30
+ * warning carried the same code as the `mut/mut-report.json` one and a
31
+ * consumer filtering on it matched both. `backCompatUntil` keeps the
32
+ * deprecation semantics legible and is per-prerequisite, because the two live
33
+ * windows close in different releases (v2.14.0 and v2.15.0).
34
+ *
35
+ * The stem is taken verbatim: both prerequisites that carry `backCompat` name
36
+ * a fixed path, so no character is rewritten.
37
+ *
38
+ * TWO KNOWN LIMITS OF THE STEM, stated so neither is read as a guarantee:
39
+ * - a `<rid>`-templated soft prerequisite keeps the placeholder, producing
40
+ * the LITERAL `<rid>-missing-deprecated-in-…` — the same code for every
41
+ * request. The code is therefore not per-slice filterable. No live
42
+ * prerequisite carries `backCompat` with a `<rid>` path, so nothing
43
+ * filters on one today; the placeholder is the honest thing to print, and
44
+ * making it per-slice would mean resolving the rid into a code a consumer
45
+ * would have to know to match.
46
+ * - the stem comes from the FILENAME only, so two prerequisites sharing a
47
+ * stem collide (`x.md` and `x.json` both yield `x-…`). Measured 0 live
48
+ * collisions, and the pair that exists (`mut/mut-report.json` vs
49
+ * `rd/third-party-review.md`) differs by stem as well as by directory.
50
+ */
51
+ export function backCompatWarningCode(prerequisite) {
52
+ const stem = basename(prerequisite.relativePath, extname(prerequisite.relativePath));
53
+ return `${stem}-missing-deprecated-in-${prerequisite.backCompatUntil ?? UNDECLARED_WINDOW}`;
54
+ }
55
+ /** How many segments a release string is compared by: `MAJOR.MINOR.PATCH`. Named
56
+ * because the count is a policy (what a release string means here), not a loop
57
+ * detail, and both the parse and the compare read it. */
58
+ const RELEASE_SEGMENTS = 3;
59
+ /**
60
+ * The declared window's `MAJOR.MINOR.PATCH`, as three numbers, from a release
61
+ * string. Only the leading triple is read: a prerelease suffix (`-beta.11`)
62
+ * compares as its release triple, and a segment that is missing or not a number
63
+ * reads as 0. Both limits are stated rather than guarded, because every
64
+ * declaration in the table is a plain `vX.Y.Z`.
65
+ */
66
+ function releaseTriple(version) {
67
+ const segments = (version.replace(/^v/i, '').split('-')[0] ?? '').split('.');
68
+ const triple = [];
69
+ for (let index = 0; index < RELEASE_SEGMENTS; index += 1) {
70
+ const parsed = Number.parseInt(segments[index] ?? '', 10);
71
+ triple.push(Number.isNaN(parsed) ? 0 : parsed);
72
+ }
73
+ return triple;
74
+ }
75
+ /** Negative when `a` predates `b`, positive when it follows, 0 when their
76
+ * release triples are equal. */
77
+ function compareReleaseVersions(a, b) {
78
+ const left = releaseTriple(a);
79
+ const right = releaseTriple(b);
80
+ for (let index = 0; index < RELEASE_SEGMENTS; index += 1) {
81
+ const difference = (left[index] ?? 0) - (right[index] ?? 0);
82
+ if (difference !== 0)
83
+ return difference < 0 ? -1 : 1;
84
+ }
85
+ return 0;
86
+ }
87
+ /**
88
+ * The certificate for a soft pass whose window has closed, or `null` while the
89
+ * window is still open. It names BOTH releases, so a reader sees the comparison
90
+ * rather than a verdict — the release the table declared, and the build it was
91
+ * compared against.
92
+ *
93
+ * A window closing AT the running release counts as closed: the declared release
94
+ * is the one that removes the soft pass, so on that release there is none left.
95
+ *
96
+ * `installedVersion` is a parameter rather than a closed-over constant so a test
97
+ * can drive both sides of the boundary without depending on the release this
98
+ * repository happens to be building; the default is the version this build ships.
99
+ */
100
+ function expiredWindowClause(prerequisite, installedVersion) {
101
+ const until = prerequisite.backCompatUntil;
102
+ if (until === undefined)
103
+ return null;
104
+ if (compareReleaseVersions(installedVersion, until) < 0)
105
+ return null;
106
+ return `${until} (installed ${installedVersion})`;
107
+ }
108
+ /**
109
+ * The soft-pass warning for a missing `prerequisite`, or `null` when a missing
110
+ * file is a HARD failure and belongs in `missing` instead.
111
+ *
112
+ * The `null` is the whole decision, and it is the caller's only input to it. The
113
+ * invariant the two destinations have, stated exactly:
114
+ * - `warnings` does NOT feed `ok` — a soft pass is reported, never enforced,
115
+ * which is why this can be a warning at all;
116
+ * - `missing` IS what decides `ok` (`ok = missing.length === 0`), so choosing
117
+ * the `missing` branch is choosing to fail the gate. That is the point of
118
+ * the `null`, and the acceptance evidence for this change depends on it.
119
+ *
120
+ * `expiredWindow` is set only when the declared window has closed, so its
121
+ * PRESENCE is the verdict and `path` / `code` / `message` stay byte-identical for
122
+ * the consumers that already read them.
123
+ */
124
+ export function missingPrerequisiteWarning(prerequisite, relativePath, installedVersion = CLI_VERSION) {
125
+ if (prerequisite.backCompat !== true)
126
+ return null;
127
+ const until = prerequisite.backCompatUntil ?? UNDECLARED_WINDOW;
128
+ const expiredWindow = expiredWindowClause(prerequisite, installedVersion);
129
+ return {
130
+ path: relativePath,
131
+ code: backCompatWarningCode(prerequisite),
132
+ message: `${prerequisite.description} — file missing; soft-blocked under the back-compat window. ${until} hard-fail.`,
133
+ ...(expiredWindow === null ? {} : { expiredWindow })
134
+ };
135
+ }
136
+ /**
137
+ * The contract's BODY checks for one prerequisite, applied to `body`. Returns
138
+ * one human-readable message per failed check, empty when the body satisfies
139
+ * the contract.
140
+ *
141
+ * Exported because this contract has a SECOND enforcer: `peaks workflow
142
+ * verify-pipeline` probes the same table for the paths it checks
143
+ * (`pipeline-verify-gate-support.ts`), and a resolver that probed only
144
+ * `existsSync` passed files this function rejects — a guard laxer than the
145
+ * contract it claims to read. Both callers now share this one implementation,
146
+ * so the checker cannot drift from the table again.
147
+ */
148
+ export function prerequisiteBodyViolations(prerequisite, body) {
149
+ const violations = [];
150
+ const lowered = body.toLowerCase();
151
+ if (prerequisite.mustContain && prerequisite.mustContain.length > 0) {
152
+ const missingMarkers = prerequisite.mustContain.filter((marker) => !lowered.includes(marker.toLowerCase()));
153
+ if (missingMarkers.length > 0) {
154
+ violations.push(`${prerequisite.description} — missing section(s): ${missingMarkers.join(', ')}`);
155
+ }
156
+ }
157
+ if (prerequisite.headingMustContain && prerequisite.headingMustContain.length > 0) {
158
+ // Slice 2.6.1.F: a line beginning with `#`, `##`, or `###` followed by
159
+ // the marker (case-insensitive). Fenced code blocks are NOT excluded
160
+ // here — a "heading" inside a code fence is rare and, when present,
161
+ // should still be reported as missing to keep the contract strict.
162
+ const headingLines = body
163
+ .split('\n')
164
+ .map((line) => line.trim())
165
+ .filter((line) => /^#{1,3}\s+/.test(line));
166
+ const loweredHeadings = headingLines.map((h) => h.toLowerCase());
167
+ const missingHeadings = prerequisite.headingMustContain.filter((marker) => !loweredHeadings.some((h) => h.includes(marker.toLowerCase())));
168
+ if (missingHeadings.length > 0) {
169
+ violations.push(`${prerequisite.description} — missing heading(s): ${missingHeadings.join(', ')}`);
170
+ }
171
+ }
172
+ if (prerequisite.mustContainAny && prerequisite.mustContainAny.length > 0) {
173
+ const hitAny = prerequisite.mustContainAny.some((marker) => lowered.includes(marker.toLowerCase()));
174
+ if (!hitAny) {
175
+ violations.push(`${prerequisite.description} — none of the escape-hatch markers present: ${prerequisite.mustContainAny.join(', ')}`);
176
+ }
177
+ }
178
+ return violations;
179
+ }
180
+ /** True when `prerequisite` declares any body check at all. Private on purpose:
181
+ * its ONE caller is `bodyViolationsIfDeclared` below. */
182
+ function hasBodyChecks(prerequisite) {
183
+ return ((prerequisite.mustContain?.length ?? 0) > 0 ||
184
+ (prerequisite.headingMustContain?.length ?? 0) > 0 ||
185
+ (prerequisite.mustContainAny?.length ?? 0) > 0);
186
+ }
187
+ /**
188
+ * The body violations for `prerequisite`, or `[]` when it declares no body
189
+ * contract — and in that case `read` is NEVER called, so a prerequisite with
190
+ * nothing to check never has its file opened (unchanged behaviour: the guard has
191
+ * always been a guard on the READ, which is why it takes the read as a thunk
192
+ * rather than the body).
193
+ */
194
+ export async function bodyViolationsIfDeclared(prerequisite, read) {
195
+ if (!hasBodyChecks(prerequisite))
196
+ return [];
197
+ return prerequisiteBodyViolations(prerequisite, await read());
198
+ }
@@ -0,0 +1,20 @@
1
+ import type { PrerequisiteCheckResult } from './artifact-prerequisites.js';
2
+ import type { RequestArtifactRole } from './artifact-templates.js';
3
+ import type { RequestArtifactState } from './request-artifact-state-helpers.js';
4
+ /**
5
+ * Slice C of v2.11.1 — observability hook #7/7. Fire-and-forget per PRD Q4. The
6
+ * synchronous emit never throws and never blocks the prereq check's return
7
+ * value.
8
+ *
9
+ * Split out when `checkPrerequisites` gained the `emitEvents: false` opt-out:
10
+ * the emit and the decision to skip it are one story, and the caller is over its
11
+ * file-size cap. Body moved verbatim.
12
+ */
13
+ export declare function emitPrereqTransitionEvent(opts: {
14
+ projectRoot: string;
15
+ sessionId: string;
16
+ role: RequestArtifactRole;
17
+ newState: RequestArtifactState;
18
+ requestId: string;
19
+ result: PrerequisiteCheckResult;
20
+ }): void;
@@ -0,0 +1,27 @@
1
+ import { emitObservabilityEvent } from '../observability/observability-service.js';
2
+ /**
3
+ * Slice C of v2.11.1 — observability hook #7/7. Fire-and-forget per PRD Q4. The
4
+ * synchronous emit never throws and never blocks the prereq check's return
5
+ * value.
6
+ *
7
+ * Split out when `checkPrerequisites` gained the `emitEvents: false` opt-out:
8
+ * the emit and the decision to skip it are one story, and the caller is over its
9
+ * file-size cap. Body moved verbatim.
10
+ */
11
+ export function emitPrereqTransitionEvent(opts) {
12
+ if (opts.sessionId === undefined)
13
+ return;
14
+ emitObservabilityEvent({
15
+ schemaVersion: 1,
16
+ ts: new Date().toISOString(),
17
+ sessionId: opts.sessionId,
18
+ category: 'slice-transition',
19
+ sliceRid: opts.requestId,
20
+ detail: {
21
+ artifactRole: opts.role,
22
+ to: opts.newState,
23
+ prereqOk: opts.result.ok,
24
+ missingCount: opts.result.missing.length
25
+ }
26
+ }, { projectRoot: opts.projectRoot });
27
+ }
@@ -0,0 +1,31 @@
1
+ import { type RequestType } from './artifact-prerequisites.js';
2
+ /**
3
+ * Where a request artifact's effective type came from.
4
+ *
5
+ * `default` means the body carried no usable `- type:` line, so
6
+ * `DEFAULT_REQUEST_TYPE` was substituted. Nothing else in the repository tells
7
+ * that apart from a deliberate `- type: feature`, and the substitution has a
8
+ * price: measured 2026-10-13 through `getPrerequisitesFor`, the `feature` row at
9
+ * `rd:qa-handoff` demands 9 artifacts, `bugfix` 10, `docs` and `chore` none. The
10
+ * locked PRD handoff for this slice states 10 for `feature`; 9 is what the
11
+ * function returns.
12
+ *
13
+ * `peaks request init` writes a type line only when `--type` was passed, so the
14
+ * absence of the line survives creation instead of being stamped over with the
15
+ * default at the moment the distinction is first knowable.
16
+ */
17
+ export type RequestTypeSource = 'declared' | 'default';
18
+ export type ArtifactMetadata = {
19
+ state: string;
20
+ requestType: RequestType;
21
+ requestTypeSource: RequestTypeSource;
22
+ createdAt?: string;
23
+ sessionId?: string;
24
+ };
25
+ /**
26
+ * Read the fields of a request artifact body. Moved verbatim out of
27
+ * `request-artifact-service.ts` when the type's provenance was added; the only
28
+ * behaviour change is `requestTypeSource`, which records whether a usable
29
+ * `- type:` line was actually present.
30
+ */
31
+ export declare function extractMetadata(markdown: string): ArtifactMetadata;
@@ -0,0 +1,44 @@
1
+ import { DEFAULT_REQUEST_TYPE, isRequestType } from './artifact-prerequisites.js';
2
+ import { readArtifactState } from './request-artifact-state-helpers.js';
3
+ /**
4
+ * Read the fields of a request artifact body. Moved verbatim out of
5
+ * `request-artifact-service.ts` when the type's provenance was added; the only
6
+ * behaviour change is `requestTypeSource`, which records whether a usable
7
+ * `- type:` line was actually present.
8
+ */
9
+ export function extractMetadata(markdown) {
10
+ const state = readArtifactState(markdown) ?? 'unknown';
11
+ let createdAt;
12
+ let requestType = DEFAULT_REQUEST_TYPE;
13
+ let requestTypeSource = 'default';
14
+ let sessionId;
15
+ for (const rawLine of markdown.split(/\r?\n/)) {
16
+ const line = rawLine.trim();
17
+ const createdMatch = /^-\s*created:\s*(.+?)\s*$/.exec(line);
18
+ if (createdMatch !== null && createdMatch[1] !== undefined) {
19
+ createdAt = createdMatch[1];
20
+ continue;
21
+ }
22
+ const typeMatch = /^-\s*type:\s*(.+?)\s*$/.exec(line);
23
+ if (typeMatch !== null && typeMatch[1] !== undefined) {
24
+ const candidate = typeMatch[1];
25
+ if (isRequestType(candidate)) {
26
+ requestType = candidate;
27
+ requestTypeSource = 'declared';
28
+ }
29
+ // Placeholder values (e.g. "feature | bug | refactor | clarification") fall back to default.
30
+ continue;
31
+ }
32
+ const sessionMatch = /^-\s*session:\s*(.+?)\s*$/.exec(line);
33
+ if (sessionMatch !== null && sessionMatch[1] !== undefined) {
34
+ sessionId = sessionMatch[1];
35
+ continue;
36
+ }
37
+ }
38
+ const base = { state, requestType, requestTypeSource };
39
+ if (createdAt !== undefined)
40
+ base.createdAt = createdAt;
41
+ if (sessionId !== undefined)
42
+ base.sessionId = sessionId;
43
+ return base;
44
+ }
@@ -1,4 +1,5 @@
1
1
  import { DEFAULT_REQUEST_TYPE, isRequestType, VALID_REQUEST_TYPES, type PrerequisiteCheckResult, type RequestType } from './artifact-prerequisites.js';
2
+ import { type RequestTypeSource } from './request-artifact-metadata.js';
2
3
  export { VALID_REQUEST_TYPES, DEFAULT_REQUEST_TYPE, isRequestType, type RequestType };
3
4
  import { type RequestArtifactRole } from './artifact-templates.js';
4
5
  export type { RequestArtifactRole } from './artifact-templates.js';
@@ -74,6 +75,8 @@ export type RequestArtifactSummary = {
74
75
  path: string;
75
76
  state: string;
76
77
  requestType: RequestType;
78
+ /** Whether `requestType` was recorded in the body or substituted. See `RequestTypeSource`. */
79
+ requestTypeSource: RequestTypeSource;
77
80
  createdAt?: string;
78
81
  };
79
82
  export type ListRequestArtifactsOptions = {
@@ -112,6 +115,8 @@ export type TransitionRequestArtifactResult = RequestArtifactSummary & {
112
115
  previousState: string;
113
116
  content: string;
114
117
  bypassedPrerequisites?: PrerequisiteCheckResult;
118
+ /** Soft-passed prerequisites on a SUCCESSFUL transition (set only when non-empty). Never affects `ok`. */
119
+ prerequisiteWarnings?: PrerequisiteCheckResult['warnings'];
115
120
  };
116
121
  import { type RequestArtifactState } from './request-artifact-state-helpers.js';
117
122
  export { allowedStatesForRole, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
@@ -8,7 +8,8 @@ import { ensureSession, getSessionIdCanonical } from '../session/session-manager
8
8
  // gone; request-artifact callers pass `options.sessionId` explicitly
9
9
  // or accept the requestId as the default. Path-safety helpers now
10
10
  // live at `shared/path-safety.ts` if this module ever needs them.
11
- import { getNextNumber, buildNumberedFilename, slugifyDescription } from '../../shared/incrementing-number.js';
11
+ import { getNextNumber, buildNumberedFilename, requestIdFromFileName, slugifyDescription } from '../../shared/incrementing-number.js';
12
+ import { extractMetadata } from './request-artifact-metadata.js';
12
13
  import { lintRequestArtifact } from './artifact-lint-service.js';
13
14
  import { isUnsafePathInput } from '../../shared/path-safety.js';
14
15
  import { guardRuntimeSegment, runtimeRoot } from '../../shared/runtime-root.js';
@@ -74,7 +75,6 @@ export async function createRequestArtifact(options) {
74
75
  if (!REQUEST_ID_PATTERN.test(options.requestId)) {
75
76
  throw new Error(`Invalid request id: ${options.requestId} (expected letters, digits, dots, underscores, or dashes)`);
76
77
  }
77
- const requestType = options.requestType ?? DEFAULT_REQUEST_TYPE;
78
78
  const clock = options.clock ?? defaultClock;
79
79
  const timestamp = clock();
80
80
  // Use provided session ID or get/create current session. The session
@@ -144,7 +144,10 @@ export async function createRequestArtifact(options) {
144
144
  const number = getNextNumber(requestsDir);
145
145
  const filename = buildNumberedFilename(number, options.requestId);
146
146
  const path = join(requestsDir, filename);
147
- const content = renderTemplate(options.role, options.requestId, sessionId, sessionSlug, timestamp, requestType);
147
+ const content = renderTemplate(options.role, options.requestId, sessionId, sessionSlug, timestamp,
148
+ // `null`, not the default: an untyped request records no type, so the
149
+ // reader's substitution stays visible as a substitution.
150
+ options.requestType ?? null);
148
151
  if (options.apply !== true) {
149
152
  // session-axis dir (`.peaks/_runtime/<sid>/`). Pre-resolved here
150
153
  // so dry-run output reports the canonical scope location.
@@ -183,47 +186,12 @@ export async function createRequestArtifact(options) {
183
186
  ...(options.callerId !== undefined ? { callerId: options.callerId } : {})
184
187
  };
185
188
  }
186
- function extractMetadata(markdown) {
187
- const state = readArtifactState(markdown) ?? 'unknown';
188
- let createdAt;
189
- let requestType = DEFAULT_REQUEST_TYPE;
190
- let sessionId;
191
- for (const rawLine of markdown.split(/\r?\n/)) {
192
- const line = rawLine.trim();
193
- const createdMatch = /^-\s*created:\s*(.+?)\s*$/.exec(line);
194
- if (createdMatch !== null && createdMatch[1] !== undefined) {
195
- createdAt = createdMatch[1];
196
- continue;
197
- }
198
- const typeMatch = /^-\s*type:\s*(.+?)\s*$/.exec(line);
199
- if (typeMatch !== null && typeMatch[1] !== undefined) {
200
- const candidate = typeMatch[1];
201
- if (isRequestType(candidate)) {
202
- requestType = candidate;
203
- }
204
- // Placeholder values (e.g. "feature | bug | refactor | clarification") fall back to default.
205
- continue;
206
- }
207
- const sessionMatch = /^-\s*session:\s*(.+?)\s*$/.exec(line);
208
- if (sessionMatch !== null && sessionMatch[1] !== undefined) {
209
- sessionId = sessionMatch[1];
210
- continue;
211
- }
212
- }
213
- const base = { state, requestType };
214
- if (createdAt !== undefined)
215
- base.createdAt = createdAt;
216
- if (sessionId !== undefined)
217
- base.sessionId = sessionId;
218
- return base;
219
- }
220
189
  async function readSummary(dir, role, fileName, sessionId) {
221
190
  const path = join(dir, fileName);
222
191
  const body = await readFile(path, 'utf8');
223
- const { state, createdAt, requestType, sessionId: bodySessionId } = extractMetadata(body);
224
- // Strip numbered prefix (e.g., "001-requestId.md" -> "requestId")
225
- // Only strip 3-digit zero-padded prefixes (our incrementing number format)
226
- const requestId = fileName.replace(/^0\d{2}-/, '').replace(/\.md$/, '');
192
+ const { state, createdAt, requestType, requestTypeSource, sessionId: bodySessionId } = extractMetadata(body);
193
+ // The id, stripped by the rule that writes the prefix (see `buildNumberedFilename`).
194
+ const requestId = requestIdFromFileName(fileName) ?? fileName.replace(/\.md$/, '');
227
195
  // Repair R5: this used to take the *scope* path fragment (`_runtime/<sid>`)
228
196
  // and re-join it onto the project root, then strip the prefix back off to
229
197
  // recover the bare session id. The round-trip was the escape's carrier — an
@@ -237,6 +205,7 @@ async function readSummary(dir, role, fileName, sessionId) {
237
205
  path,
238
206
  state,
239
207
  requestType,
208
+ requestTypeSource,
240
209
  writerSessionId: bodySessionId ?? sessionId
241
210
  };
242
211
  if (createdAt !== undefined) {
@@ -364,7 +333,8 @@ async function readRequestArtifact(dir, role, found, sessionId) {
364
333
  // the sibling `request-artifact-state-helpers.ts` module — see
365
334
  // v2.18.3 file-split for the rationale. Function signatures and
366
335
  // behaviour are unchanged (verbatim move).
367
- import { ALLOWED_STATES_PER_ROLE, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, readArtifactState, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
336
+ import { ALLOWED_STATES_PER_ROLE, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
337
+ import { assertLegalStateStep } from './request-state-order.js';
368
338
  export { allowedStatesForRole, FileSizeViolationError, LintGateError, PrerequisitesNotSatisfiedError, TypeSanityViolationError, updateStatusBlock } from './request-artifact-state-helpers.js';
369
339
  export async function transitionRequestArtifact(options) {
370
340
  if (!VALID_ROLES.has(options.role)) {
@@ -397,6 +367,8 @@ export async function transitionRequestArtifact(options) {
397
367
  confirmed: options.confirmed,
398
368
  forceConfirm: options.forceConfirm
399
369
  });
370
+ // A forward jump past an intermediate state is refused (request-state-order.ts).
371
+ assertLegalStateStep(options.role, existing.state, options.newState, options.allowIncomplete === true);
400
372
  const prerequisiteResult = await checkPrerequisites({
401
373
  projectRoot: options.projectRoot,
402
374
  sessionId: existing.sessionId,
@@ -408,9 +380,6 @@ export async function transitionRequestArtifact(options) {
408
380
  if (!prerequisiteResult.ok && options.allowIncomplete !== true) {
409
381
  throw new PrerequisitesNotSatisfiedError(options.role, options.newState, existing.sessionId, prerequisiteResult.missing, prerequisiteResult.warnings);
410
382
  }
411
- // (Removed in v2.11.0 Group A: the tech-doc-presence + tech-doc-mandatory-
412
- // sections gates. The rd → spec-locked transition now relies on the
413
- // immutable peaks-prd handoff (sha256-frontmatter) for the same intent;
414
383
  // Type sanity check for PRD handoff
415
384
  if (options.typeSanityCheck !== undefined &&
416
385
  options.role === 'prd' &&
@@ -438,7 +407,7 @@ export async function transitionRequestArtifact(options) {
438
407
  }
439
408
  }
440
409
  }
441
- // File size gate: when RD declares implemented, scan for oversized files (karpathy-skills "Simplicity First")
410
+ // File-size ratchet: refuse only a file this change made worse (Simplicity First).
442
411
  if (options.role === 'rd' &&
443
412
  options.newState === 'implemented' &&
444
413
  options.allowIncomplete !== true) {
@@ -458,11 +427,8 @@ export async function transitionRequestArtifact(options) {
458
427
  const reasonForNote = combinedReason.length > 0 ? combinedReason : undefined;
459
428
  const { updated, previousState } = updateStatusBlock(existing.content, options.newState, timestamp, reasonForNote);
460
429
  await writeFile(existing.path, updated, 'utf8');
461
- // Slice v2.11.1 — observability hook #1/7. Fire-and-forget emit per
462
- // PRD Q4 (full-auto must never fail-loud on observability). The
463
- // synchronous `emitObservabilityEvent` returns `{written: false}` on
464
- // any error path; we deliberately ignore the result so the
465
- // transition contract remains unchanged.
430
+ // Fire-and-forget: the synchronous emit returns `{written: false}` on any
431
+ // error path and we ignore it, so observability never fails the transition.
466
432
  emitObservabilityEvent({
467
433
  schemaVersion: 1,
468
434
  ts: timestamp,
@@ -483,6 +449,7 @@ export async function transitionRequestArtifact(options) {
483
449
  path: existing.path,
484
450
  state: options.newState,
485
451
  requestType: existing.requestType,
452
+ requestTypeSource: existing.requestTypeSource,
486
453
  previousState,
487
454
  content: updated
488
455
  };
@@ -492,5 +459,10 @@ export async function transitionRequestArtifact(options) {
492
459
  if (!prerequisiteResult.ok && options.allowIncomplete === true) {
493
460
  result.bypassedPrerequisites = prerequisiteResult;
494
461
  }
462
+ // Soft-passed prerequisites travel on the SUCCESS path too, not only inside
463
+ // the throw above — otherwise `ok: true` drops what it soft-passed.
464
+ if (prerequisiteResult.warnings.length > 0) {
465
+ result.prerequisiteWarnings = prerequisiteResult.warnings;
466
+ }
495
467
  return result;
496
468
  }
@@ -34,15 +34,27 @@ export declare class TypeSanityViolationError extends Error {
34
34
  }
35
35
  export declare class FileSizeViolationError extends Error {
36
36
  readonly code = "FILE_SIZE_VIOLATION";
37
+ /** `previousLines` is the file's size at the scan's base ref, or `null` when
38
+ * the change CREATED it over the cap. Carried so the message can name the
39
+ * growth — a refusal that does not say how much worse the file got reads as
40
+ * an absolute cap breach, which is the reading this gate no longer makes.
41
+ *
42
+ * The `violations` array also drives the sentence naming the AGGREGATE
43
+ * ratchet row this gate is easily confused with. This gate is PER FILE; that
44
+ * row is a sum over the census. In a working tree the two can disagree with
45
+ * neither being wrong, and the message says so rather than leaving a reader
46
+ * to conclude that one of them is broken. */
37
47
  readonly violations: Array<{
38
48
  file: string;
39
49
  lines: number;
40
50
  cap: number;
51
+ previousLines: number | null;
41
52
  }>;
42
53
  constructor(violations: Array<{
43
54
  file: string;
44
55
  lines: number;
45
56
  cap: number;
57
+ previousLines: number | null;
46
58
  }>);
47
59
  }
48
60
  export interface ArtifactStateLocation {
@@ -62,12 +62,36 @@ export class TypeSanityViolationError extends Error {
62
62
  }
63
63
  export class FileSizeViolationError extends Error {
64
64
  code = 'FILE_SIZE_VIOLATION';
65
+ /** `previousLines` is the file's size at the scan's base ref, or `null` when
66
+ * the change CREATED it over the cap. Carried so the message can name the
67
+ * growth — a refusal that does not say how much worse the file got reads as
68
+ * an absolute cap breach, which is the reading this gate no longer makes.
69
+ *
70
+ * The `violations` array also drives the sentence naming the AGGREGATE
71
+ * ratchet row this gate is easily confused with. This gate is PER FILE; that
72
+ * row is a sum over the census. In a working tree the two can disagree with
73
+ * neither being wrong, and the message says so rather than leaving a reader
74
+ * to conclude that one of them is broken. */
65
75
  violations;
66
76
  constructor(violations) {
67
- const summary = violations.map((v) => `${v.file} (${v.lines} lines, cap ${v.cap})`).join(', ');
68
- super(`File size violation: ${violations.length} file(s) exceed their file-size cap: ${summary}. ` +
69
- 'Split into smaller modules, or consider reusing existing components / existing API data ' +
70
- '(karpathy-guidelines §2 Simplicity First), or use --allow-incomplete to bypass.');
77
+ const summary = violations
78
+ .map((v) => v.previousLines === null
79
+ ? `${v.file} (${v.lines} lines, cap ${v.cap}, created over the cap)`
80
+ : `${v.file} (${v.lines} lines, cap ${v.cap}, grew +${v.lines - v.previousLines} from ${v.previousLines})`)
81
+ .join(', ');
82
+ super(`File size regression: ${violations.length} changed file(s) grew past (or were created over) their file-size cap: ${summary}. ` +
83
+ 'This is the PER-FILE rule: each changed file is judged against its own size at the base ref. ' +
84
+ 'It is a different measurement from the aggregate ratchet row `file-size excess lines` ' +
85
+ '(fileSizeExcessLines), which sums the whole census — so `node .husky/peaks-gate.mjs repo` ' +
86
+ 'can print that row green at this same moment (it prints a ✓ for a held row), and ' +
87
+ '`node .husky/peaks-gate-baseline.mjs` can report "monotonicity: every ceiling held": one ' +
88
+ 'file growing a few lines sits inside an aggregate fall and never reaches that row. Neither ' +
89
+ 'reading is wrong and neither takes priority over the other; they measure different things, ' +
90
+ 'and both must hold. ' +
91
+ 'A file already over its cap at the base ref is accepted unless this change enlarges it; ' +
92
+ 'a rename is measured against the size it had before the move. Split into smaller modules, ' +
93
+ 'or consider reusing existing components / existing API data (karpathy-guidelines §2 ' +
94
+ 'Simplicity First), or use --allow-incomplete to bypass.');
71
95
  this.name = 'FileSizeViolationError';
72
96
  this.violations = violations;
73
97
  }
@@ -0,0 +1,68 @@
1
+ import type { RequestType } from './artifact-prerequisites.js';
2
+ import { type RequestTypeSource } from './request-artifact-metadata.js';
3
+ import { type RequestArtifactRole } from './request-artifact-service.js';
4
+ export type RequestTypeChange = {
5
+ readonly from: RequestType;
6
+ readonly fromSource: RequestTypeSource;
7
+ readonly to: RequestType;
8
+ };
9
+ export type RetagImpact = {
10
+ /** Paths the new type demands and the old one did not. */
11
+ readonly added: ReadonlyArray<string>;
12
+ /** Paths the old type demanded and the new one does not. */
13
+ readonly removed: ReadonlyArray<string>;
14
+ /** Everything the new type's table demands that is not on disk, added or not. */
15
+ readonly missing: ReadonlyArray<string>;
16
+ };
17
+ export type RetagRequestArtifactOptions = {
18
+ projectRoot: string;
19
+ role: RequestArtifactRole;
20
+ requestId: string;
21
+ requestType: RequestType;
22
+ /**
23
+ * Required. Omitting it made `showRequestArtifact` resolve the first session
24
+ * holding a matching rid, so a WRITE verb could mutate an artifact nobody
25
+ * named. A write has to say which one.
26
+ */
27
+ sessionId: string;
28
+ clock?: () => string;
29
+ };
30
+ export type RetagRequestArtifactResult = {
31
+ role: RequestArtifactRole;
32
+ requestId: string;
33
+ sessionId: string;
34
+ path: string;
35
+ change: RequestTypeChange;
36
+ impact: RetagImpact;
37
+ /** The durable line appended to the artifact body; see `appendRetagNote`. */
38
+ note: string;
39
+ content: string;
40
+ };
41
+ /**
42
+ * Rewrite the artifact's type, changing the line the READER would take.
43
+ * `extractMetadata` scans every top-level `- type:` line and keeps the last
44
+ * usable one, so the writer targets the last line regardless of validity: if the
45
+ * last is a placeholder and an earlier one is real, the rewrite lands on the
46
+ * placeholder, which then becomes the usable one — the same line the reader
47
+ * picks up either way. With no such line at all (the shape a hand-written
48
+ * carrier has) one is inserted into the metadata block.
49
+ *
50
+ * The one other change it makes: lines are split on `\r?\n` and rejoined with
51
+ * `\n`, so a CRLF body comes back LF-terminated. Reproduced by an independent
52
+ * reviewer; named rather than implied.
53
+ */
54
+ export declare function setRequestTypeInBody(markdown: string, requestType: RequestType): string;
55
+ /**
56
+ * The durable record of a retag, appended rather than rewritten so a later retag
57
+ * — or a transition's own `- transition note` — leaves every earlier one intact.
58
+ *
59
+ * It exists because the type line itself is overwritten and the difference it
60
+ * makes is not cosmetic: retagging down (`feature` → `chore`) stops nine
61
+ * artifacts being demanded. Without a line like this the only visible trace of
62
+ * that would be the envelope of the run that did it, and the artifact tree lives
63
+ * under a gitignored directory. Same idiom as `updateStatusBlock`'s note.
64
+ */
65
+ export declare function appendRetagNote(markdown: string, change: RequestTypeChange, timestamp: string): string;
66
+ export declare function retagRequestArtifact(options: RetagRequestArtifactOptions): Promise<RetagRequestArtifactResult | null>;
67
+ /** The envelope lines a retag reports, so the change is not silent. */
68
+ export declare function describeRetag(result: RetagRequestArtifactResult): string[];