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
@@ -23,11 +23,17 @@
23
23
  * it can be unit-tested in isolation and so the on-disk file matches
24
24
  * the in-memory template byte-for-byte.
25
25
  *
26
- * Four `Bash` matchers are emitted: the Step 0.8 mechanical gate, the SOP
27
- * gate-enforce handler, and the two layer-B feedback hooks. No
28
- * `Write|Edit|MultiEdit` entry is emitted: that matcher's gate is
29
- * `peaks code-gate --json`, installed into the committed
30
- * `.claude/settings.json` by `peaks hooks install`.
26
+ * TWO `Bash` matchers are emitted: the Step 0.8 mechanical gate and the SOP
27
+ * gate-enforce handler. No `Write|Edit|MultiEdit` entry is emitted: that
28
+ * matcher's gate is `peaks code-gate`, installed into the committed
29
+ * `.claude/settings.json` by `peaks hooks install`. TEMPLATE_VERSION 1.10.0
30
+ * removed the two layer-B feedback hooks this file used to emit: they are this
31
+ * repository's OWN development hooks, and this file is written into a
32
+ * CONSUMER project, where `${CLAUDE_PROJECT_DIR}` is that project's root, no
33
+ * `src/**` is ever shipped, and the command therefore points at nothing. They
34
+ * are registered in this repository's tracked `.claude/settings.json` instead;
35
+ * `isRetiredTemplateEntry` in `claude-settings-template-merge.ts` is what makes
36
+ * an install that already has them converge.
31
37
  *
32
38
  * The previous `Bash` matcher (which whitelisted a fixed `peaks
33
39
  * <subcommand>` prefix) was removed in TEMPLATE_VERSION 1.2.0. The
@@ -116,8 +122,22 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
116
122
  * promotion they carry was true only locally. See
117
123
  * `buildFeedbackHookHandler` for why the pin is `bash` and not the
118
124
  * `powershell` its three siblings take.
125
+ * 1.10.0 — REMOVED those two entries again, and retired them so every install
126
+ * that already carries them converges. 1.9.0's INTENT was right — a
127
+ * fresh clone should carry the registration, not just the scripts —
128
+ * but this file is the wrong mechanism for it. This template is
129
+ * written into a CONSUMER project's `.claude/settings.local.json`,
130
+ * where `${CLAUDE_PROJECT_DIR}` is the consumer's root, `src/**` is
131
+ * not in the npm `files` list, and nothing copies it, so the two
132
+ * entries were a command that could never resolve in every
133
+ * downstream project; and this repository, whose `settings.local.json`
134
+ * is gitignored, got no tracked copy either. The scripts STAY here —
135
+ * they are this repository's own development hooks — and the
136
+ * registration moved to the tracked `.claude/settings.json`.
137
+ * `isRetiredTemplateEntry` carries the retirement, because declaring
138
+ * less cannot retire an entry on its own.
119
139
  */
120
- export const TEMPLATE_VERSION = '1.9.0';
140
+ export const TEMPLATE_VERSION = '1.10.0';
121
141
  /**
122
142
  * TEMPLATE_VERSION 1.4.0 — the SOP gate-enforce handler, read from the same
123
143
  * canonical hook spec `peaks hooks install` uses. Deriving it here (rather
@@ -141,12 +161,13 @@ function buildGateEnforceHandler() {
141
161
  * forcing gate is a core feature that PreToolUse hooks can short-
142
162
  * circuit but that the `permissions` block cannot.
143
163
  *
144
- * As of TEMPLATE_VERSION 1.9.0 the template emits four `Bash` matchers: the
145
- * two above, plus one per layer-B feedback hook (`FEEDBACK_HOOK_SCRIPTS`). The
146
- * `Write|Edit|MultiEdit` fact-forcing bypass is no longer a hook: it is the
147
- * `env` exemption above, and that matcher's gate (`peaks code-gate --json`) is
148
- * installed into the committed `.claude/settings.json` by `peaks hooks
149
- * install`.
164
+ * As of TEMPLATE_VERSION 1.10.0 the template emits exactly TWO `Bash` matchers:
165
+ * the two below. (1.9.0 added one entry per layer-B feedback hook on top of
166
+ * them, which made four; 1.10.0 removed and retired those — see
167
+ * `isRetiredTemplateEntry`.) The `Write|Edit|MultiEdit` fact-forcing bypass is
168
+ * no longer a hook: it is the `env` exemption above, and that matcher's gate
169
+ * (`peaks code-gate`) is installed into the committed `.claude/settings.json`
170
+ * by `peaks hooks install`.
150
171
  */
151
172
  export function buildClaudeSettingsLocalJson() {
152
173
  return {
@@ -182,15 +203,7 @@ export function buildClaudeSettingsLocalJson() {
182
203
  // group and the gate would run twice per Bash call.
183
204
  matcher: 'Bash',
184
205
  hooks: [buildGateEnforceHandler()]
185
- },
186
- ...FEEDBACK_HOOK_SCRIPTS.map((script) => ({
187
- // TEMPLATE_VERSION 1.9.0 — the layer-B feedback hooks, one matcher
188
- // group each, for the same reason the entry above has its own: a
189
- // group is peaks-managed only when EVERY handler in it carries a
190
- // peaks sentinel, and none of these handlers does.
191
- matcher: 'Bash',
192
- hooks: [buildFeedbackHookHandler(script)]
193
- }))
206
+ }
194
207
  ]
195
208
  }
196
209
  };
@@ -224,44 +237,31 @@ function buildBashGateStep08Handler() {
224
237
  };
225
238
  }
226
239
  /**
227
- * TEMPLATE_VERSION 1.9.0 — the two rules promoted to layer B by hand first: the
228
- * scripts shipped in `src/services/hooks/`, but the registration existed only in
229
- * the generated copy on the machine that wrote it. Emitting it here is what makes
230
- * the promotion a property of the repository rather than of that machine — the
231
- * layer-B feedback gate reads THIS template's `hooks` block, so a fresh clone had
232
- * the enforcement and nothing registering it.
233
- *
234
- * The filenames are the contract: the layer-B check looks for a hook command that
235
- * INVOKES A FILE NAMED AFTER THE RULE, so the command has to carry the script's
236
- * name and cannot be a `peaks` verb that dispatches to it.
237
- */
238
- const FEEDBACK_HOOK_SCRIPTS = [
239
- 'pre-tool-peaks-current-directory-scope.sh',
240
- 'pre-tool-piping-a-test-run-reports-the-pipes-exit-code.sh'
241
- ];
242
- /** The shell these two handlers are pinned to. See `buildFeedbackHookHandler`. */
243
- const FEEDBACK_HOOK_SHELL = 'bash';
244
- /**
245
- * The handler for one feedback hook, pinned to `shell: 'bash'`.
240
+ * TEMPLATE_VERSION 1.9.0 emitted the two layer-B feedback hooks from here; 1.10.0
241
+ * removed and RETIRED them. See `claude-settings-retirements.ts` for the retirement
242
+ * itself and for why declaring less cannot carry one. What is worth keeping here:
246
243
  *
247
- * THE PIN IS THE DECISION, and it is deliberately not the `powershell` its three
248
- * siblings take. Measured on this host, both shapes run the script and both print
249
- * its refusal to stderr — but they do not report the same exit code:
244
+ * - WHERE THEY LIVE NOW. `pre-tool-peaks-current-directory-scope.sh` and
245
+ * `pre-tool-piping-a-test-run-reports-the-pipes-exit-code.sh` are this
246
+ * repository's OWN development hooks, so their registration is in this
247
+ * repository's tracked `.claude/settings.json` — where `${CLAUDE_PROJECT_DIR}`
248
+ * really is the root that contains `src/`.
249
+ * - THE SHELL PIN THEY STILL CARRY, and why it is not the `powershell` their CLI
250
+ * siblings take. Measured on this host, both shapes run the script and both
251
+ * print its refusal to stderr — but not the same exit code:
250
252
  *
251
- * bash "<script>" exit 2 (the script's own code)
252
- * powershell "<script>" exit 1 (flattened by the shell)
253
+ * bash "<script>" exit 2 (the script's own code)
254
+ * powershell "<script>" exit 1 (flattened by the shell)
253
255
  *
254
- * Under the Claude Code hook protocol only exit 2 blocks; any other non-zero exit
255
- * is a NON-BLOCKING ERROR and the tool call goes ahead. So pinning `powershell`
256
- * here would not be a cosmetic difference on a blocking hook — it would turn the
257
- * refusal into a log line and let the command through, which is the failure these
258
- * two entries exist to prevent. `shell` accepts `bash` and `powershell` only, and
259
- * `bash` is also the interpreter this command already names.
256
+ * Under the Claude Code hook protocol only exit 2 blocks; any other non-zero
257
+ * exit is a NON-BLOCKING ERROR and the tool call goes ahead. So `powershell`
258
+ * would turn the refusal into a log line and let the command through — the
259
+ * failure these entries exist to prevent. `shell` accepts `bash` and
260
+ * `powershell` only, and `bash` is also the interpreter the command names.
261
+ * - WHAT THEY REFUSE. `peaks-current-directory-scope` refuses global-state
262
+ * mutations (`npm i -g`, writes under `~/.claude`) unless the user explicitly
263
+ * authorises them; `piping-a-test-run-reports-the-pipes-exit-code` refuses a
264
+ * test run piped into a pager, because the exit code read afterwards is the
265
+ * pager's, not the runner's. `tests/unit/hooks/feedback-promoted-pretool-hooks.test.ts`
266
+ * drives both, with a plant for each.
260
267
  */
261
- function buildFeedbackHookHandler(script) {
262
- return {
263
- type: 'command',
264
- command: `bash "\${CLAUDE_PROJECT_DIR}/src/services/hooks/${script}"`,
265
- shell: FEEDBACK_HOOK_SHELL
266
- };
267
- }
@@ -20,6 +20,9 @@
20
20
  */
21
21
  import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync } from 'node:fs';
22
22
  import { join } from 'node:path';
23
+ // Frozen: the filenames release 1.4.1 wrote, not the current contract. The
24
+ // entries name what this migration must FIND on an upgraded tree, so they stay
25
+ // bare even where a later release put the request id in the canonical name.
23
26
  export const PER_SESSION_ARTIFACT_TYPES = [
24
27
  'rd/tech-doc.md',
25
28
  'rd/code-review.md',
@@ -277,7 +277,6 @@ function readActiveSkillSessionId(projectRoot) {
277
277
  return null;
278
278
  try {
279
279
  // Sync read: tiny file, no I/O benefit from async
280
- const { readFileSync } = require('node:fs');
281
280
  const raw = readFileSync(pathToRead, 'utf8');
282
281
  const parsed = JSON.parse(raw);
283
282
  if (typeof parsed?.sessionId === 'string' && parsed.sessionId.length > 0) {
@@ -22,6 +22,16 @@ export declare function getNextNumber(dirPath: string): number;
22
22
  */
23
23
  export declare function slugifyDescription(description: string): string;
24
24
  export declare function buildNumberedFilename(number: number, description: string): string;
25
+ /**
26
+ * The id a markdown artifact's filename carries, or null when the name is not a
27
+ * markdown artifact at all. The READ side of `buildNumberedFilename`, in the same
28
+ * module, so writer and reader cannot drift apart from each other.
29
+ *
30
+ * The returned stem is not yet checked against the id pattern the artifact service
31
+ * owns; a caller that needs a legal request id applies that there rather than the
32
+ * pattern being imported here.
33
+ */
34
+ export declare function requestIdFromFileName(fileName: string): string | null;
25
35
  /**
26
36
  * Get the next numbered file path in a directory.
27
37
  * Combines getNextNumber() and buildNumberedFilename().
@@ -34,6 +34,19 @@ export function getNextNumber(dirPath) {
34
34
  * @param description - Human-readable description (converted to kebab-case slug)
35
35
  * @returns Formatted filename like "001-feature-name.md"
36
36
  */
37
+ /**
38
+ * The `<NNN>` prefix in a numbered filename is COSMETIC. `getNextNumber` reads
39
+ * the directory's highest prefix and adds one, and nothing claims a number in
40
+ * between — so two writers running at once can both read the same maximum and
41
+ * both stamp the same number. That is harmless only because the number is not
42
+ * an identity: what names an artifact is the slug (the request id), and every
43
+ * reader strips the prefix. Measured 2026-10-12: the sole consumers of the
44
+ * number are this module's writer path (`getNextNumber` -> `buildNumberedFilename`)
45
+ * and the read side (`requestIdFromFileName`, which discards it); the artifact
46
+ * service's duplicate check and lookup both key on the slug. Read that as a
47
+ * constraint: give the number a meaning and you must claim it atomically first,
48
+ * rather than assume this scan hands out unique values.
49
+ */
37
50
  // Windows supports up to 255 chars per filename component (and 260 for the
38
51
  // full path). Pre-#015 the slug was silently truncated to 50 chars, which
39
52
  // produced orphaned artefacts (the on-disk file no longer matched the
@@ -65,6 +78,20 @@ export function buildNumberedFilename(number, description) {
65
78
  const slug = slugifyDescription(description);
66
79
  return `${padded}-${slug}.md`;
67
80
  }
81
+ /**
82
+ * The id a markdown artifact's filename carries, or null when the name is not a
83
+ * markdown artifact at all. The READ side of `buildNumberedFilename`, in the same
84
+ * module, so writer and reader cannot drift apart from each other.
85
+ *
86
+ * The returned stem is not yet checked against the id pattern the artifact service
87
+ * owns; a caller that needs a legal request id applies that there rather than the
88
+ * pattern being imported here.
89
+ */
90
+ export function requestIdFromFileName(fileName) {
91
+ if (!fileName.endsWith('.md'))
92
+ return null;
93
+ return fileName.replace(/^0\d{2}-/, '').replace(/\.md$/, '');
94
+ }
68
95
  /**
69
96
  * Get the next numbered file path in a directory.
70
97
  * Combines getNextNumber() and buildNumberedFilename().
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "peaks-loop",
3
- "version": "4.1.4",
3
+ "version": "4.1.5",
4
4
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
5
5
  "author": "SquabbyZ",
6
6
  "keywords": [
@@ -129,10 +129,10 @@
129
129
  "picomatch": "4.0.4",
130
130
  "yaml": "^2.9.0",
131
131
  "zod": "^4.4.3",
132
- "peaks-loop-internal-runtime": "0.0.44",
133
- "peaks-loop-shared": "0.0.93",
134
- "peaks-loop-mut": "0.1.58",
135
- "peaks-loop-shared-channel": "0.0.61"
132
+ "peaks-loop-internal-runtime": "0.0.45",
133
+ "peaks-loop-shared-channel": "0.0.62",
134
+ "peaks-loop-mut": "0.1.59",
135
+ "peaks-loop-shared": "0.0.94"
136
136
  },
137
137
  "devDependencies": {
138
138
  "@changesets/cli": "2.31.1",
@@ -12,7 +12,7 @@ metadata:
12
12
  - schema: .peaks/project-scan/audit-output-schema.md
13
13
  ---
14
14
 
15
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
15
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
16
16
 
17
17
  ## Loop hygiene (every turn — MANDATORY)
18
18
 
@@ -8,7 +8,7 @@ description: |
8
8
  visibility: internal
9
9
  ---
10
10
 
11
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
11
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
12
12
 
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
@@ -8,7 +8,7 @@ description: |
8
8
  visibility: internal
9
9
  ---
10
10
 
11
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
11
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
12
12
 
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
@@ -13,8 +13,8 @@ This chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.m
13
13
 
14
14
  For worktree operations, use ONLY:
15
15
 
16
- - `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)
17
- - until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`
16
+ - `peaks worktree spawn --rid <rid> --role <role> --purpose <text>` (after rid-L2-extended ships)
17
+ - until then: `peaks worktree auth grant --operation <op> --reason <text>` (`<op>`, e.g. `git-worktree` | `agent-isolation-worktree`)
18
18
 
19
19
  The superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-qa's own QA artifacts (`.peaks/_runtime/<sessionId>/qa/<artifact>.md`) are authoritative.
20
20
 
@@ -2,7 +2,7 @@
2
2
 
3
3
  > Body of `### Transition verification gates`. You cannot declare a phase complete from memory. Each gate below is a `ls` or `grep` command you **MUST run** and whose output you **MUST see** before proceeding. If any file shows "No such file" or any command returns empty, the phase is incomplete.
4
4
 
5
- > **CLI enforcement (v2.11.0 D1/D4 trim)**: the gates below are enforced by `peaks request transition`. The CLI checks the same files before allowing the transition and fails with `code: PREREQUISITES_MISSING` if any are absent. Required files depend on the request type recorded at `peaks request init --type ...`. **As of v2.11.0:** peaks-qa does NOT own security-findings or performance-findings — those are produced by peaks-rd's audit fan-out as `rd/security-review.md` and `rd/perf-baseline.md` and are referenced from the QA test report rather than required as separate files.
5
+ > **CLI enforcement (v2.11.0 D1/D4 trim)**: the gates below are enforced by `peaks request transition`. The CLI checks the same files before allowing the transition and fails with `code: PREREQUISITES_MISSING` if any are absent. Required files depend on the request type recorded at `peaks request init --type ...`. **As of v2.11.0:** peaks-qa does NOT own security-findings or performance-findings — peaks-rd's audit fan-out produces that evidence as `audit/security-<rid>.md` and `audit/perf-<rid>.md` (the standalone skills in the paragraph below; the paths named here were `rd/security-review.md` / `rd/perf-baseline.md` until v2.12.0 and remain readable back-compat tiers), and the QA test report references it rather than requiring separate files.
6
6
 
7
7
  | Type | qa:running requires | qa:verdict-issued also requires |
8
8
  |---|---|---|
@@ -9,7 +9,7 @@ description: |
9
9
  visibility: internal
10
10
  ---
11
11
 
12
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
12
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
13
13
 
14
14
  ## Loop hygiene (every turn — MANDATORY)
15
15
 
@@ -85,7 +85,7 @@ For frontend / UI-affecting slices, RD's self-test uses the Playwright MCP heade
85
85
 
86
86
  When this skill is launched as a sub-agent via `peaks sub-agent dispatch <role>` (then the LLM executes the returned toolCall) from `peaks-code`, the following sections of THIS skill are **suspended** for the sub-agent run: Session id (use parent's), Skill presence, Workspace initialization, Mode selection, Statusline install.
87
87
 
88
- What the sub-agent MUST still do: read PRD via `peaks request show`, run standards preflight (dry-run only), write planning artefact (`rd/tech-doc.md` for feature/refactor; `rd/bug-analysis.md` for bugfix; skip for config/docs/chore), return compact JSON envelope.
88
+ What the sub-agent MUST still do: read PRD via `peaks request show`, run standards preflight (dry-run only), write planning artefact (`rd/tech-doc.md` for feature/refactor; `rd/bug-analysis-<rid>.md` for bugfix; skip for config/docs/chore), return compact JSON envelope.
89
89
 
90
90
  → see `references/rd-sub-agent-dispatch.md` for the full contract + hard prohibitions.
91
91
 
@@ -230,7 +230,7 @@ refusing — matching the prereq-side acceptance above.
230
230
  |---|---|
231
231
  | feature / refactor | `prd/handoff.md` (immutable) + `audit/security-<rid>.md` (peaks-security-audit) + `audit/perf-<rid>.md` (peaks-perf-audit) + `rd/code-review-<rid>.md` + `rd/karpathy-review-<rid>.md` + `qa/test-cases/<rid>.md` |
232
232
  | bugfix | `prd/handoff.md` (immutable) + `audit/security-<rid>.md` (peaks-security-audit) + `audit/perf-<rid>.md` (peaks-perf-audit, perf-shaped only) + `rd/code-review-<rid>.md` + `rd/karpathy-review-<rid>.md` + `qa/test-cases/<rid>.md` |
233
- | config | `rd/security-review.md` (genuinely ridless — `SECURITY_REVIEW.relativePath` carries no `<rid>`) |
233
+ | config | `rd/security-review-<rid>.md` (`SECURITY_REVIEW.relativePath` carries the `<rid>` since slice 9.37; the bare name stays readable as the legacy tier) |
234
234
  | docs / chore | (no extra evidence required) |
235
235
 
236
236
  Always required (in addition to the type-specific row):
@@ -13,8 +13,8 @@ This chain ends with `git worktree add` (superpowers:using-git-worktrees SKILL.m
13
13
 
14
14
  For worktree operations, use ONLY:
15
15
 
16
- - `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)
17
- - until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`
16
+ - `peaks worktree spawn --rid <rid> --role <role> --purpose <text>` (after rid-L2-extended ships)
17
+ - until then: `peaks worktree auth grant --operation <op> --reason <text>` (`<op>`, e.g. `git-worktree` | `agent-isolation-worktree`)
18
18
 
19
19
  The superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-rd's own PRD/RD artifacts (`.peaks/_runtime/<sessionId>/rd/requests/<rid>.md`) are authoritative.
20
20
 
@@ -70,7 +70,7 @@ What the sub-agent **MUST** still do, from this skill's contract:
70
70
  2. `peaks request show <rid> --role prd --project <repo> --json` (and `--role ui` if UI is in the swarm plan).
71
71
  3. Standards preflight (dry-run only; Code owns the apply step).
72
72
  4. Project-scan read; create `rd/project-scan.md` only if Code flagged it missing in the dispatch prompt.
73
- 5. Write the planning artefact: `rd/requests/<rid>.md` (feature/refactor, per the `artifact-per-request.md` contract) or `rd/bug-analysis.md` (bugfix). If `--type` is `config|docs|chore`, **no planning artefact is required** — return immediately with `{"role":"rd-planning","status":"skipped","reason":"type=<type>"}`.
73
+ 5. Write the planning artefact: `rd/requests/<rid>.md` (feature/refactor, per the `artifact-per-request.md` contract) or `rd/bug-analysis-<rid>.md` (bugfix). If `--type` is `config|docs|chore`, **no planning artefact is required** — return immediately with `{"role":"rd-planning","status":"skipped","reason":"type=<type>"}`.
74
74
 
75
75
  > **v2.11.0 change (Group A):** `rd/tech-doc.md` is removed. The per-slice planning record is the per-request artefact at `rd/requests/<rid>.md`; the slice's source-of-truth architecture is the immutable peaks-prd handoff at `prd/handoff.md` (verify handoff hash = `<dispatched value>` before reading).
76
76
  6. Return only a compact JSON envelope — Code will run the convergence gate (`ls` checks):
@@ -139,6 +139,8 @@ See the block constant at `src/services/dispatch/test-tool-detection.ts` for the
139
139
 
140
140
  When the dispatch primitive constructs the sub-agent prompt, the following context block MUST be appended to the sub-agent prompt verbatim. The block is the canonical injection source for any RD-spawned sub-agent (including 4-way fanout, including inline main-loop RD).
141
141
 
142
+ **The dispatch CLI now does this itself (2026-10-13).** `peaks sub-agent dispatch` runs `ensureKarpathyBlock` over the assembled prompt (`src/services/dispatch/karpathy-block.ts`, applied in `src/cli/commands/dispatch-prompt-composition.ts`), so the block reaches the child whether or not the caller remembers to append it. A caller that already appended it is not appended twice. The constant is the machine copy of the block below, and a unit test asserts the two are byte-equal, so neither can drift. What the obligation still covers is the path that does NOT go through this CLI: `--from-dag` (`src/services/code/dag-orchestrator.ts`) and `--mode detached` inject no Karpathy block, so a caller using either must append it itself.
143
+
142
144
  ```
143
145
  Karpathy-guidelines context (REQUIRED — read before any code action)
144
146
 
@@ -161,7 +163,9 @@ Touch only what you must. Clean up only your own mess. When editing existing cod
161
163
  Define success criteria. Loop until verified. "Add validation" → write tests for invalid inputs, then make them pass. "Fix the bug" → write a test that reproduces it, then make it pass. For multi-step tasks, state a brief plan with verify checkpoints. Strong success criteria let you loop independently. Weak criteria require constant clarification.
162
164
  ```
163
165
 
164
- Sub-agents MUST NOT silently drop this block. Nothing asserts its presence automatically — the unit test that did was deleted in `f17aa377`, so a dropped block fails silently. The canonical skill id for the full guidelines text is `andrej-karpathy-skills:karpathy-guidelines`.
166
+ Sub-agents MUST NOT silently drop this block. The canonical skill id for the full guidelines text is `andrej-karpathy-skills:karpathy-guidelines`.
167
+
168
+ Corrected 2026-10-13, kept visible rather than edited away: this paragraph used to read *"Nothing asserts its presence automatically — the unit test that did was deleted in `f17aa377`, so a dropped block fails silently."* That was true when written and it was the defect. The composer now injects the block and `tests/unit/services/dispatch/karpathy-block.test.ts` + `tests/unit/skills/karpathy-injection.test.ts` assert both the delivery and the byte-equality of this file's block with the constant, so a dropped block no longer fails silently on the CLI path. Measured 2026-10-12, before the executor existed: four RD dispatch prompts in one session carried zero occurrences of `Karpathy`.
165
169
 
166
170
  ## BDD Test Style Contract (effective rid-2026-08-05-bdd-test-style, v4.0.11+)
167
171
 
@@ -11,10 +11,10 @@ You cannot declare a phase complete from memory. Each gate below is a `ls` or `g
11
11
  > | Type | rd:implemented requires | rd:qa-handoff also requires |
12
12
  > |---|---|---|
13
13
  > | feature / refactor | `rd/tech-doc.md` | `rd/code-review-<rid>.md` + `audit/security-<rid>.md` + `audit/perf-<rid>.md` (filled Results table, or `N/A — no perf surface` in Notes) + **`qa/test-cases/<rid>.md`** (added in slice 004; pre-drafted by the 4th sub-agent in the parallel fan-out) |
14
- > | bugfix | `rd/bug-analysis.md` (lighter than tech-doc; root cause + fix + regression test plan) | `rd/code-review-<rid>.md` + `audit/security-<rid>.md` + **`qa/test-cases/<rid>.md`**; `audit/perf-<rid>.md` only when the bug is performance-shaped (matches the L449-452 "When this applies" criteria) |
15
- > | config | (none) | `rd/security-review.md` only — this one is genuinely ridless (`SECURITY_REVIEW.relativePath` carries no `<rid>`) |
14
+ > | bugfix | `rd/bug-analysis-<rid>.md` (lighter than tech-doc; root cause + fix + regression test plan) | `rd/code-review-<rid>.md` + `audit/security-<rid>.md` + **`qa/test-cases/<rid>.md`**; `audit/perf-<rid>.md` only when the bug is performance-shaped (matches the L449-452 "When this applies" criteria) |
15
+ > | config | (none) | `rd/security-review-<rid>.md` only — `SECURITY_REVIEW.relativePath` carries the `<rid>` since slice 9.37 |
16
16
  >
17
- > The `<rid>`-bearing names are the ones `peaks request transition` resolves first; the pre-rid names (`rd/code-review.md`, `rd/security-review.md`, `audit/security.md`, `audit/perf.md`) stay **readable** as back-compat tiers for sessions written before slice `2026-09-14-audit-artifact-rid-scoping` — read, never written. Exception: `rd/perf-baseline.md` is the RD-side Gate B9 baseline (a different artifact from `audit/perf-<rid>.md`) and is still both written by `peaks perf baseline --apply` and read as `AUDIT_PERF`'s oldest legacy tier.
17
+ > The `<rid>`-bearing names are the ones `peaks request transition` resolves first; the pre-rid names (`rd/bug-analysis.md`, `rd/code-review.md`, `rd/security-review.md`, `audit/security.md`, `audit/perf.md`) stay **readable** as back-compat tiers for sessions written before the rid was added to the filename — read, never written. Exception: `rd/perf-baseline.md` is the RD-side Gate B9 baseline (a different artifact from `audit/perf-<rid>.md`) and is still both written by `peaks perf baseline --apply` and read as `AUDIT_PERF`'s oldest legacy tier.
18
18
  > | docs / chore | (none) | (none) |
19
19
  >
20
20
  > The escape hatch `--allow-incomplete --reason "<text>"` still exists for one-off exceptions; the bypass is recorded in the artifact transition note.
@@ -9,10 +9,10 @@ into two new standalone audit skills.
9
9
  ## Removed sub-agent slots
10
10
 
11
11
  - `security-reviewer` — moved to standalone `peaks-security-audit` skill.
12
- Output: `.peaks/_runtime/<sessionId>/audit/security.md`.
12
+ Output: `.peaks/_runtime/<sessionId>/audit/security-<rid>.md`.
13
13
  Required RD-side prereq: `AUDIT_SECURITY`.
14
14
  - `perf-baseline-reviewer` — moved to standalone `peaks-perf-audit` skill.
15
- Output: `.peaks/_runtime/<sessionId>/audit/perf.md`.
15
+ Output: `.peaks/_runtime/<sessionId>/audit/perf-<rid>.md`.
16
16
  Required RD-side prereq: `AUDIT_PERF`.
17
17
 
18
18
  Both audit skills consume the immutable peaks-prd handoff
@@ -67,7 +67,7 @@ gateEvidence:
67
67
  - `nextActions[]` — verb-first; what peaks-qa should do next, in order.
68
68
  - `gateEvidence` — paths to the gate files peaks-qa will validate. **DERIVED, never hand-written**: the producer computes it from the request `type` (`src/services/prd/gate-evidence-derivation.ts`), and Gate C reads the same `rd:qa-handoff` row, so the block and the gate cannot disagree. It declares that row's evidence, plus `projectScan` (Gate A's artifact — declared only where Gate C runs, since a path nothing verifies should not be declared):
69
69
  - `feature` / `refactor` / `bugfix` → **5 keys**: `projectScan`, `prdHandoff`, `codeReview`, `securityReview`, `perfBaseline`
70
- - `config` → **2 keys**: `projectScan`, `securityReview`. `CONFIG_TABLE['rd:qa-handoff']` is the security review alone, so a config slice has **no** `prdHandoff`; and its security evidence is the genuinely ridless `rd/security-review.md`, not `audit/security-<rid>.md`.
70
+ - `config` → **2 keys**: `projectScan`, `securityReview`. `CONFIG_TABLE['rd:qa-handoff']` is the security review alone, so a config slice has **no** `prdHandoff`; and its security evidence is `rd/security-review-<rid>.md` (scoped by rid since slice 9.37), not `audit/security-<rid>.md`.
71
71
  - `docs` / `chore` → **no `gateEvidence` block at all**. Those types have no `rd:qa-handoff` row: there is no evidence to declare and nothing for Gate C to check, so the block is omitted rather than filled with an unverified statement. Such a capsule is byte-identical to a pre-B2 one.
72
72
  **The Gate C failure rule is scoped to the types above** — where that gate runs: a declared path that does not exist fails `peaks request transition --state qa-handoff` (`PREREQUISITES_MISSING`), naming the key. Two shapes are deliberately NOT failures: a capsule for a type with no `rd:qa-handoff` row (the check does not run), and an **empty** declaration (`gateEvidence: {}`) — a weak claim, not a false one, since the type's artifacts remain enforced by the table itself, so an empty map cannot open the gate. When the request type cannot be resolved at all, the block is omitted rather than half-declared.
73
73
  - `schemaVersion: 2` — pinned, and written PLAIN (no quotes). The constant is `HANDOFF_SCHEMA_VERSION` in `src/services/prd/handoff-frontmatter-shape.ts` and its value is the string `'2'`; the serializer emits it unquoted, because `AUDIT_REQUIRES_HANDOFF` matches the substring `schemaVersion: 2` and a quoted `'2'` would not contain it. `readHandoff` accepts `'2'` or the bare number `2` and nothing else — **`'2.0'` is not a valid value here**, and this document said it was until it was measured against the serializer. Bump only when the field set changes.
@@ -4,7 +4,7 @@ visibility: internal
4
4
  description: Third-party independent code-review skill for Peaks. Use as a parallel reviewer to karpathy-reviewer when a workflow needs an out-of-band (non-RD-model) review pass to mitigate single-LLM self-dogfood blind spots. Emits a schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 G4.
5
5
  ---
6
6
 
7
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
7
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
8
8
 
9
9
  ## Loop hygiene (every turn — MANDATORY)
10
10
 
@@ -8,7 +8,7 @@ description: |
8
8
  visibility: internal
9
9
  ---
10
10
 
11
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
11
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
12
12
 
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
@@ -12,7 +12,7 @@ metadata:
12
12
  - schema: .peaks/project-scan/audit-output-schema.md
13
13
  ---
14
14
 
15
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
15
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
16
16
 
17
17
  ## Loop hygiene (every turn — MANDATORY)
18
18
 
@@ -142,11 +142,19 @@ The service renders the envelope to markdown and writes to
142
142
 
143
143
  ```bash
144
144
  peaks security-audit run --rid <id> --sid <sid> --project <repo> \
145
+ --judged <path> [<path>...] \
145
146
  --envelope @<path-to-envelope.json>
146
147
  # or pipe the envelope via stdin
147
- peaks security-audit run --rid <id> --sid <sid> --project <repo> < envelope.json
148
+ peaks security-audit run --rid <id> --sid <sid> --project <repo> \
149
+ --judged <path> [<path>...] < envelope.json
148
150
  ```
149
151
 
152
+ `--judged` is **required**, and omitting it refuses the run with `declaration-missing` without
153
+ writing anything. Name the paths this audit actually judged: the CLI records each one's content
154
+ hash in the artifact, and `rd:qa-handoff` re-hashes them, so a declared path edited afterwards
155
+ refuses that transition. **Declare what you judged, not what you touched** — the check can tell
156
+ that a declared path moved, and it cannot tell that an undeclared one did.
157
+
150
158
  The artifact body has the required sections per `.peaks/project-scan/audit-output-schema.md`:
151
159
 
152
160
  - `## Summary` — 1-paragraph narrative
@@ -8,7 +8,7 @@ description: |
8
8
  visibility: internal
9
9
  ---
10
10
 
11
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
11
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
12
12
 
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
@@ -277,7 +277,8 @@ peaks capabilities --json
277
277
  # You MUST scan the handoff capsule for embedded memory blocks FIRST. If none
278
278
  # are present, the step is a no-op (the command succeeds with extractedCount=0
279
279
  # and writes nothing). If blocks are present, --apply writes them and the
280
- # index is regenerated.
280
+ # index is regenerated — except a block whose target name is already in the
281
+ # store, which is skipped and named in warnings[] (check it; see below).
281
282
  grep -c "peaks-memory:start" .peaks/_runtime/<sessionId>/txt/handoff.md || true # skill-side scan; do NOT add a new CLI
282
283
  peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json
283
284
  peaks skill presence:clear --project <repo> # handoff capsule complete, remove presence indicator
@@ -292,7 +293,7 @@ Every handoff capsule you emit **MUST** include the scan for stable facts. The m
292
293
  - Run `grep -c 'peaks-memory:start' .peaks/_runtime/<sessionId>/txt/handoff.md` after writing the capsule body.
293
294
  - If the count is 0 AND this session surfaced a stable project fact (an architectural decision, a stack constraint, a naming convention, a refactor approved by the user, an API pattern, a hard rule from RD/QA review), you MUST go back and embed at least one `<!-- peaks-memory:start -->` block before declaring TXT complete. Skipping the block is a workflow violation.
294
295
  - If the count is 0 AND no stable fact was surfaced (pure analysis, no code touched, all transient), it is acceptable to skip embedding — but you MUST still run `peaks memory extract --apply` so the artefact state stays consistent (the command will be a no-op write, that's fine).
295
- - If the count is ≥ 1, the `--apply` extract will write one markdown per block to `.peaks/memory/` and regenerate `index.json`. The user sees the durable persistence; that is the entire point of this step.
296
+ - If the count is ≥ 1, the `--apply` extract writes one markdown per block **whose target name the store does not already hold**, then regenerates `index.json`. A block whose name (the title, lowercased, with every run of non-letter/non-digit characters collapsed to `-`) already names a stored file is **skipped, not overwritten** — and the envelope says so: one `warnings[]` line per skipped block, plus a closing line giving both counts. So read `warnings[]` and compare `writtenFiles` with `plannedWrites` before reporting the sediment complete; `writtenFiles` shorter than `plannedWrites` with `warnings: []` is the case that used to be indistinguishable from success. The user sees the durable persistence; that is the entire point of this step.
296
297
 
297
298
  This rule is the skill-side half of the **Skill is primary, CLI is auxiliary** contract: the LLM is responsible for embedding blocks (skill prompt, no CLI can decide what is stable), and the CLI is responsible for atomic persistence (`peaks memory extract --apply`, single shot, structured JSON envelope).
298
299
 
@@ -8,7 +8,7 @@ description: |
8
8
  visibility: internal
9
9
  ---
10
10
 
11
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
11
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
12
12
 
13
13
  ## Loop hygiene (every turn — MANDATORY)
14
14
 
@@ -381,8 +381,8 @@ UI sub-agents follow the same G7 metadata-only + G8.6 share protocol. UI artifac
381
381
 
382
382
  For worktree operations, use ONLY:
383
383
 
384
- - `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (after rid-L2-extended ships)
385
- - until then: `peaks worktree auth grant --rid <id> --reason <text> --ttl <5m>`
384
+ - `peaks worktree spawn --rid <rid> --role <role> --purpose <text>` (after rid-L2-extended ships)
385
+ - until then: `peaks worktree auth grant --operation <op> --reason <text>` (`<op>`, e.g. `git-worktree` | `agent-isolation-worktree`)
386
386
 
387
387
  The superpowers skills remain available as REFERENCE material for brainstorming / planning techniques, but MUST NOT be used as a workflow. peaks-ui's own UI artifacts (`.peaks/_runtime/<sessionId>/ui/<artifact>.md`) are authoritative. Full design: `skills/peaks-code/references/worktree-governance.md`.
388
388
 
@@ -3,7 +3,7 @@ name: peaks-audit
3
3
  description: Gate autonomous LLM work on a 6-dimension audit + user-accepted goal. Use IMMEDIATELY after a need is expressed, BEFORE any PRD/RD/QA work starts.
4
4
  ---
5
5
 
6
- <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 22. -->
6
+ <!-- peaks:loop-hygiene — HAND-MAINTAINED block, NOT generated; byte-identical in every SKILL.md, enforced by tests/unit/skills/loop-hygiene-block.test.ts. Edit one, edit all 23. -->
7
7
 
8
8
  ## Loop hygiene (every turn — MANDATORY)
9
9
 
@@ -51,6 +51,34 @@ The `.peaks/` workspace is partitioned by a **single scope axis** (session-id, a
51
51
 
52
52
  **None.** `peaks-audit` is the entry point; no other peaks-* skill runs first. If the user hands you a raw need with no accepted goal, audit it before doing anything else.
53
53
 
54
+ ## Lane routing — ask once per request, at this entry
55
+
56
+ If every peaks-* workflow enters here, then this is where the lane question belongs: a need reaches `peaks-audit` before it reaches any other peaks-* skill, whichever words the user used to express it. The question — the full workflow (`peaks-code`) or the fast lane (`peaks-race-code`) — is answered by the user, and is never presumed by the LLM on their behalf.
57
+
58
+ | Situation | Behaviour |
59
+ |---|---|
60
+ | The user named no skill — just a need, in their own words | Ask once with `AskUserQuestion`. **No option is preselected.** |
61
+ | The user named a skill (`/peaks-code`, `/peaks-race-code`) | Ask once, with **the named lane preselected**: one Enter passes, and choosing the other lane stays available. |
62
+ | The question has already been answered for this request | Do not ask again. |
63
+ | This session is already locked to a lane | Do not ask again. |
64
+
65
+ **The phase rewrites the first two rows of that table, and nothing else.** Which of the two branches is in force is read from the tracked file `.peaks/race/lane-phase.json` and stated nowhere else in this file — what follows gives the rule for either value rather than asserting a value, so no sentence here can drift from it:
66
+
67
+ | `.peaks/race/lane-phase.json` says | Behaviour |
68
+ |---|---|
69
+ | `name-only` | **Do not ask.** An unnamed need runs the full workflow (`peaks-code`), and a named skill is respected without being questioned. The question would be **malformed rather than merely unhelpful** here: with the fast lane absent from its options it carries a single answer, and `AskUserQuestion` requires two to four — so do not re-add it to "be safe", as its absence is the design, not an oversight. |
70
+ | `offered-by-default` | The table above applies in full: ask even when a skill was named, with that one preselected, and the fast lane is one of the offered options. |
71
+
72
+ That file is **authoritative**, and it may hold exactly one key, `phase`, with exactly one of those two values: `src/services/race/lane-phase.ts` reads it and refuses anything else, and `tests/unit/skills/race-lane-phase-gate.test.ts` judges the value against the tracked evidence before this lane may be offered. Moving the phase means moving that one value, with the evidence behind it — and leaving it at `offered-by-default` while its evidence does not pass turns that guard red.
73
+
74
+ Clearing the pilot is a separate, explicit project decision — a real-task trial with no severe regression — and not something to read off a green test run. It is recorded by moving that value to `offered-by-default`; whatever the file names is what binds.
75
+
76
+ **There is no silent lane.** `peaks-race-code` starts only on the user's word: they named it, or they picked it when the question was asked. Never answer that question for them, and where it applies and they have not answered it, hold there rather than choosing a lane on their behalf.
77
+
78
+ **Mid-task, suggest; never re-ask.** When a closer look shows the task is heavier than it looked, say so in one sentence and let the user keep going — "this is past what the fast lane is for; want the full workflow instead?" A suggestion, not a popup and not a gate, and the user may ignore it.
79
+
80
+ What may take the fast lane at all is not decided here. The changes that do not belong in one, and what "done" means once one does, are stated once in `../peaks-code/references/fast-lane-norm.md`; read them there rather than from this file, and do not restate them here.
81
+
54
82
  ## Hard contract — invoke IMMEDIATELY
55
83
 
56
84
  When a workflow surfaces a human need (a sentence, a ticket summary, a voice note, a vague "I want X"), call `peaks-audit` BEFORE any other skill: