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
@@ -3,7 +3,7 @@ name: peaks-code
3
3
  description: Code-domain loop engineering orchestrator for the Peaks-Loop skill family. Use when the user asks Peaks-Loop to handle a code-repo workflow end-to-end (端到端/全流程/需求开发), especially from a product document (PRD/飞书文档/Feishu doc) through implementation and validation. Coordinates peaks-prd, peaks-rd, peaks-qa, peaks-ui, peaks-sc, and peaks-txt while preserving user confirmation gates. Triggers on `/peaks-code`, "peaks code", "全流程开发", "端到端迭代". General primitives (peaks-resume / peaks-status / peaks-test) are sibling skills, not children.
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
 
@@ -168,7 +168,7 @@ Pins the boundary between `peaks-code` and the **superpowers** skill family (`br
168
168
  - **L2 — hook + lifecycle gate** (`peaks hooks install` → `peaks gate enforce` → `evaluateWorktreeAuth`; 5 deny codes `REQUIRED / EXPIRED / REQUEST_MISMATCH / CONSUMED / FILE_INVALID`).
169
169
  - **L3 — IDE `permissions.deny`** (Claude Code refuses Skill BEFORE LLM sees it; strongest layer).
170
170
 
171
- Sub-agents MUST NOT use raw `git worktree add`. The only authorized path is `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>` (fall back to L2 hook gate + manual `peaks worktree auth grant` until rid-L2-extended ships). Sub-agents MUST write artifacts under `.peaks/_runtime/<sessionId>/<role>/requests/` in MAIN (`--project .`), not in a worktree. See `references/worktree-governance.md`.
171
+ Sub-agents MUST NOT use raw `git worktree add`. The only authorized path is `peaks worktree spawn --rid <rid> --role <role> --purpose <text>` (fall back to L2 hook gate + manual `peaks worktree auth grant` until rid-L2-extended ships). Sub-agents MUST write artifacts under `.peaks/_runtime/<sessionId>/<role>/requests/` in MAIN (`--project .`), not in a worktree. See `references/worktree-governance.md`.
172
172
 
173
173
  ## Peaks-Loop Startup sequence (MANDATORY — execute in order)
174
174
 
@@ -232,6 +232,7 @@ See also: references/session-overload-signal-index.md for the 7-signal lookup ta
232
232
  | **D-002** | 2.5 | `peaks session title --session-id <sid> ...` rejected with `error: unknown option '--session-id'` (this is the bare `<sid>` anti-pattern) | sid is positional: `peaks session title <sessionId> "<title>" --json` | §Step 2.5a |
233
233
  | **D-003** | 0.8 | `JOB_SHAPE_NOT_DECIDED` exception expected but never thrown | Current behavior is `peaks job status` reports `done: 0` passively — treat as recoverable miss, not hard error | §Step 0.8 third paragraph |
234
234
  | **D-010** | 11c | `peaks memory extract` returns `extractedCount: 0` despite `<!-- peaks-memory:start -->` existing | Block requires YAML frontmatter (`title:` + `kind:` + `---`) + closing `<!-- peaks-memory:end -->`. A marker without those fields, and a marker that is not the exact literal (e.g. with a `kind=…` written inside it), produce no writes and are both named in the envelope's `warnings[]` — read it before concluding there was no block | §Step 11c + 11d |
235
+ | **D-011** | 11c | `extractedCount` ≥ 1 but `.peaks/memory/` gains fewer files than `plannedWrites` lists, with `warnings: []` | A third outcome, separate from D-010: the block parsed and was planned, and the **write** was skipped because the store already held its target name (`writtenFiles` shorter than `plannedWrites`). Since 2026-10-13 the envelope names each skipped block and closes with `Wrote N of M planned memories; K skipped because the target file already exists`. Re-read `warnings[]` before reporting the step complete — a re-run of the same handoff is the ordinary way to hit this, and it is not a failure | §Step 11c + 11d |
235
236
 
236
237
  > **Sediment lesson (master record):** `.peaks/memory/peaks-code-runbook-4-0-0-beta-6-skill-md-cli-d-001-d-002-d-003-d-010.md`
237
238
 
@@ -314,6 +315,8 @@ Write DAG → `.peaks/_runtime/<sessionId>/sc/slice-dag.json`, run `peaks sub-ag
314
315
 
315
316
  After `peaks-rd` finishes, Code MUST auto-route to `peaks-qa` without waiting for confirmation. Cap: 3 cycles; on 3rd failure emit blocked TXT handoff. Full 5-step procedure at `references/micro-cycle.md`.
316
317
 
318
+ > **Fast-mode exception.** Under `peaks code plan --fast` this loop is off — `repairLoop: !opts.fast` in `buildCodePlan`. Without this line the `MUST` above contradicts fast mode, which is reachable only through `references/fast-mode.md`; what a fast lane must still satisfy, and when a task is not a fast-lane task at all, is in **`references/fast-lane-norm.md`** (the single source).
319
+
317
320
  ## Default runbook
318
321
 
319
322
  The end-to-end CLI sequence for `full-auto` lives in `references/runbook.md`. `assisted`/`strict` pause at `[CONFIRM]`; `full-auto`/`24h` auto-proceed. At a `[CONFIRM]` gate the CLI never prompts: the transition throws `CONFIRMATION_REQUIRED`, so Code asks the user via `AskUserQuestion` and, on approval, re-runs the same command with `--confirm`. Never expect or ask for a terminal `y/N` prompt.
@@ -0,0 +1,42 @@
1
+ # Fast-lane norm — the single source
2
+
3
+ > **advisory**: nothing enforces the rules stated here. They are a judgement
4
+ > list, not a gate, and no lane enforces its own rules either — each lane only
5
+ > *states* its obligations: peaks-code's fast mode its step switches
6
+ > (`peaks code plan --fast`), peaks-race-code its completion proofs, which that
7
+ > skill itself calls self-reported and checked by nothing. So "stated here" does
8
+ > not mean "enforced somewhere".
9
+ >
10
+ > **The document itself is pinned by a test.** That is a different claim, and
11
+ > the next paragraph says exactly what the test checks and what it does not.
12
+
13
+ Two fast lanes share these two statements.
14
+ `tests/unit/standards/fast-lane-norm-single-source.test.ts` walks every markdown file under skills/, asserting the gate sentence appears once and the risk-list heading appears once. That is the whole guard — a copy of the risk list **under a different heading** is not caught, which is why this paragraph names the mechanism instead of promising more. The design record under `docs/` quotes the gate too, because a design doc has to name what it specifies; that is documentation drift, not lane drift. Two places that cannot be word-for-word identical should not have been split in the first place.
15
+
16
+ ## 1. The acceptance gate
17
+
18
+ `test pass + tsc pass + lint pass` = GO.
19
+
20
+ A single QA round, **no** repair loop. peaks-code's fast mode turns the repair
21
+ loop off; peaks-race-code has no separate QA window to loop with.
22
+
23
+ ## 2. When a task is not a fast-lane task
24
+
25
+ Any one hit means the task does not belong in a fast lane. **Each row is
26
+ annotated with how mechanical it actually is** — only row 6 is machine-checkable,
27
+ and the rest are judgement calls, which is worth knowing before treating this
28
+ list as if it decided anything on its own.
29
+
30
+ | # | Risk surface | Machine-checkable? |
31
+ |---|---|---|
32
+ | 1 | authn / authz / credentials / secrets handling paths | no — judgement |
33
+ | 2 | database schema or migrations | partly — the path can be matched (`migrations/` and the like) |
34
+ | 3 | public API surface (exported signatures change) | partly — codegraph / export-surface diffs help |
35
+ | 4 | concurrency / transaction semantics | no — judgement |
36
+ | 5 | dependency upgrades carrying API changes | partly — the `package.json` diff is mechanical, the API-change call is not |
37
+ | 6 | change size past a threshold | **yes — but no threshold exists yet** (spec U2), so this row is unactionable rather than decided. A lane has to set one before it can act on it |
38
+ | 7 | behaviour that cannot be believed from "run the tests once" | no — judgement |
39
+
40
+ **This list does not say what happens on a hit.** That belongs to each lane:
41
+ peaks-code's answer is the full workflow, and peaks-race-code's answer is
42
+ one-way escalation to peaks-code.
@@ -1,7 +1,7 @@
1
1
  # Code fast mode (slice 2 — round-trip ≤ 30s)
2
2
 
3
3
  For hot-fix / small-bug slices where the full 5-step workflow is overkill,
4
- use **fast mode**: `peaks code plan --fast <change-id>`. Fast mode skips
4
+ use **fast mode**: `peaks code plan --fast <session-id>`. Fast mode skips
5
5
  three steps that dominate cold-start cost:
6
6
 
7
7
  | Step | Default | Fast |
@@ -13,7 +13,8 @@ three steps that dominate cold-start cost:
13
13
 
14
14
  ## Acceptance gate
15
15
 
16
- `test pass + tsc pass + lint pass` = GO. Single QA round, NO repair loop.
16
+ The gate, and the list of tasks that do not belong in a fast lane at all, live
17
+ in `fast-lane-norm.md` — the single source, shared with the other fast lane.
17
18
  Use fast mode only when the user explicitly opts in (default stays
18
19
  conservative).
19
20
 
@@ -52,12 +52,12 @@ Files written into these directories during the workflow (not pre-created — th
52
52
 
53
53
  - `rd/project-scan.md` (Code step 0.6)
54
54
  - `rd/tech-doc.md` (feature/refactor planning; required by `rd → implemented` gate)
55
- - `rd/bug-analysis.md` (bugfix planning; required by `rd → implemented` gate for `--type bugfix`)
56
- - `rd/code-review-<rid>.md`, `audit/security-<rid>.md` (required by `rd → qa-handoff` gate for feature/bugfix/refactor; the `config` type instead requires the ridless `rd/security-review.md`)
55
+ - `rd/bug-analysis-<rid>.md` (bugfix planning; required by `rd → implemented` gate for `--type bugfix`)
56
+ - `rd/code-review-<rid>.md`, `audit/security-<rid>.md` (required by `rd → qa-handoff` gate for feature/bugfix/refactor; the `config` type instead requires `rd/security-review-<rid>.md`)
57
57
  - `rd/mock-plan.md` (frontend-only mode)
58
58
  - `ui/design-draft.md` (UI step)
59
59
  - `system/existing-system.md` (Code step 0.7; legacy projects only)
60
- - `qa/test-cases/<rid>.md`, `qa/test-reports/<rid>.md`, `qa/security-findings.md`, `qa/performance-findings.md` (gated per `--type`)
60
+ - `qa/test-cases/<rid>.md`, `qa/test-reports/<rid>.md` (gated per `--type`); `qa/security-findings.md` / `qa/performance-findings.md` are **not** required by any `--type` since the v2.11.0 D1/D4 trim — peaks-rd's audit fan-out owns that evidence, so existing ones are kept for auditability and ignored by the gate
61
61
 
62
62
  ## Root pollution prohibition (CRITICAL)
63
63
 
@@ -164,9 +164,9 @@ verdict=return-to-rd → RD 修 (new slice 内部走 micro-cycle)
164
164
 
165
165
  > **CLI gate enforcement**: `peaks request transition` now refuses to move RD/QA to gated states when required artifacts are missing. The required files depend on `--type` chosen at `peaks request init` (default `feature`):
166
166
  >
167
- > - `feature` / `refactor`: full gates (tech-doc, code-review, security-review, test-cases, test-report, security-findings, performance-findings)
168
- > - `bugfix`: lighter planning (`bug-analysis.md` instead of `tech-doc.md`); still requires code-review + security-review + regression test-cases + security-findings; performance-findings optional unless the bug is performance-related
169
- > - `config`: only security-review (RD) and security-findings (QA)
167
+ > - `feature` / `refactor`: full gates (tech-doc, code-review, security-review, test-cases, test-report)
168
+ > - `bugfix`: lighter planning (`bug-analysis-<rid>.md` instead of `tech-doc.md`); still requires code-review + security-review + regression test-cases
169
+ > - `config`: `rd/security-review-<rid>.md` (RD) only — the one type whose RD evidence is the security review rather than `audit/security-<rid>.md`
170
170
  > - `docs` / `chore`: no gates
171
171
  >
172
172
  > When PRD lands, classify the request type before running `peaks request init` for every role — pass `--type <type>` so the artifact records it and downstream transitions enforce the right gates. Misclassifying a feature as `docs` to skip gates is a workflow violation. If a transition fails with `code: PREREQUISITES_MISSING`, the response lists every missing path — produce them, then re-transition. For one-off exceptions, the escape hatch `--allow-incomplete --reason "<text>"` records the bypass in the artifact transition note.
@@ -44,7 +44,7 @@ done
44
44
 
45
45
  | Missing file | Resume at |
46
46
  |---|---|
47
- | `rd/tech-doc.md` (for `feature`/`refactor`) or `rd/bug-analysis.md` (for `bugfix`) | Step 3b (RD planning) |
47
+ | `rd/tech-doc.md` (for `feature`/`refactor`) or `rd/bug-analysis-<rid>.md` (for `bugfix`) | Step 3b (RD planning) |
48
48
  | `rd/code-review-<rid>.md` or `audit/security-<rid>.md` | Step 5 (RD review fan-out) |
49
49
  | `audit/perf-<rid>.md` (for `feature`/`refactor`) | Step 5 (perf baseline) |
50
50
  | `qa/test-cases/<rid>.md` | Step 6 (QA test-case generation) |
@@ -136,7 +136,7 @@ peaks sub-agent dispatch --from-dag .peaks/_runtime/<sid>/sc/slice-dag.json --ba
136
136
  peaks skill presence:set peaks-code --project <repo> --mode <mode> --gate swarm-converged
137
137
  ls .peaks/_runtime/<sid>/prd/requests/<rid>.md # PRD artefact must exist (Gate B hard)
138
138
  # feature / refactor → ls .peaks/_runtime/<sid>/rd/tech-doc.md
139
- # bugfix → ls .peaks/_runtime/<sid>/rd/bug-analysis.md
139
+ # bugfix → ls .peaks/_runtime/<sid>/rd/bug-analysis-<rid>.md
140
140
  ls .peaks/_runtime/<sid>/qa/test-cases/<rid>.md # QA test-cases (skipped for docs|chore)
141
141
  # ui (only when in plan):
142
142
  ls .peaks/_runtime/<sid>/ui/design-draft.md 2>&1 # non-blocking (Gate B info)
@@ -146,16 +146,21 @@ ls .peaks/_runtime/<sid>/ui/design-draft.md 2>&1 # non-blocking (G
146
146
 
147
147
  # 4. Peaks-Loop RD planning artifact (the file required by the prerequisite gate)
148
148
  # feature / refactor → write .peaks/_runtime/<id>/rd/tech-doc.md
149
- # bugfix → write .peaks/_runtime/<id>/rd/bug-analysis.md
149
+ # bugfix → write .peaks/_runtime/<id>/rd/bug-analysis-<rid>.md
150
150
  # config → no planning artifact required at this state
151
151
  # docs / chore → no planning artifact required
152
+ # The RD state machine is a SEQUENCE (draft → spec-locked → implemented →
153
+ # qa-handoff → handed-off) and the CLI refuses a forward jump, so lock the
154
+ # plan first, then declare it implemented. Backward moves (the QA
155
+ # return-to-rd repair re-enters spec-locked) are always legal.
156
+ peaks request transition <rid> --role rd --state spec-locked --project <repo> --json
152
157
  peaks request transition <rid> --role rd --state implemented --project <repo> --json
153
158
 
154
159
  # 5. Peaks-Loop Code review + security review BEFORE qa-handoff transition.
155
160
  # Produce the evidence files the CLI gate enforces:
156
161
  # - .peaks/_runtime/<id>/rd/code-review-<rid>.md (CRITICAL/HIGH findings + fixes; required for feature/bugfix/refactor)
157
- # - .peaks/_runtime/<id>/audit/security-<rid>.md (required for feature/bugfix/refactor; the ridless rd/security-review.md is the config-type requirement)
158
- # The pre-rid names remain accepted back-compat tiers, but writing one re-opens the two-slices-one-session collision (slice 2026-09-14-audit-artifact-rid-scoping).
162
+ # - .peaks/_runtime/<id>/audit/security-<rid>.md (required for feature/bugfix/refactor; the config type instead requires rd/security-review-<rid>.md)
163
+ # The pre-rid names remain accepted back-compat tiers, but writing one re-opens the two-slices-one-session collision (slices 2026-09-14-audit-artifact-rid-scoping and 2026-10-14-backlog-9-37-prereq-collisions).
159
164
  # Then transition. If --type is docs/chore the gate is empty and the transition is unguarded.
160
165
  peaks request transition <rid> --role rd --state qa-handoff --project <repo> --json
161
166
 
@@ -164,8 +169,9 @@ peaks request transition <rid> --role rd --state qa-handoff --project <repo> --j
164
169
  # Before qa:running → .peaks/_runtime/<id>/qa/test-cases/<rid>.md
165
170
  peaks request transition <rid> --role qa --state running --project <repo> --json
166
171
  # Before qa:verdict-issued → .peaks/_runtime/<id>/qa/test-reports/<rid>.md
167
- # + .peaks/_runtime/<id>/qa/security-findings.md
168
- # + .peaks/_runtime/<id>/qa/performance-findings.md (feature/refactor only)
172
+ # (no qa/security-findings.md or qa/performance-findings.md: no qa:verdict-issued
173
+ # table holds them since the v2.11.0 D1/D4 trim — peaks-rd's audit fan-out owns
174
+ # that evidence; see skills/bee/peaks-qa/references/qa-transition-gates.md).
169
175
  peaks request transition <rid> --role qa --state verdict-issued --project <repo> --json
170
176
  # → Peaks-Loop Gate D check. Assisted/Strict: [CONFIRM]
171
177
  # → AskUserQuestion; on approval re-run the transition with --confirm
@@ -43,6 +43,10 @@ peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt
43
43
 
44
44
  > **CLI reality check (D-010 sediment, 2026-07-09; warnings added 2026-09-17):** The `<!-- peaks-memory:start -->` block must be followed immediately by a **YAML frontmatter** (`title: ...`, `kind: lesson | decision | convention`) and a `---` separator. Each block must close with `<!-- peaks-memory:end -->`. A marker whose body lacks those fields produces no `plannedWrites`, so `extractedCount` stays 0 — and the CLI now says why: the rejected block is named, with the failed precondition, in the envelope's `warnings[]`. The same channel catches a marker that is not the exact literal (e.g. a `kind=…` written inside it), which `warnings` reports as "… is not the exact marker …". Read `warnings` before treating `extractedCount: 0` as "there was no block" — but note the warning reports the loss, it does not recover it: fix the marker and re-run.
45
45
 
46
+ > **Second outcome, measured 2026-10-12 and reported since 2026-10-13 (D-011).** A block can be found, parsed and listed in `plannedWrites`, and still never reach the disk: the write is skipped when `.peaks/memory/` already holds a file with that block's target name (the step is idempotent by design — a re-run of the same handoff must not abort on `EEXIST`). Before this was reported, that outcome produced `extractedCount: 5`, `plannedWrites.length: 5`, `warnings: []` and **4** files — a skipped write and a completed one were indistinguishable in the envelope. The envelope now names each skipped block and closes with `Wrote N of M planned memories; K skipped because the target file already exists`. So: compare `writtenFiles` against `plannedWrites` **before** reporting the sediment complete, and treat `writtenFiles` shorter than `plannedWrites` with `warnings: []` as the report being wrong rather than as a clean run.
47
+
48
+ > **Also measured, and it is a NAME rule rather than a warning rule.** A block titled only in a non-Latin script used to resolve to one shared filename for every such title, so the second one collided with the first and was skipped without a word. The name now derives from the title itself, which is why two CJK-titled blocks reach two files. A title with no letter or digit in any script still gets a derived name of its own rather than a shared one.
49
+
46
50
  ### 11d — Gate C (zero-write outcome)
47
51
 
48
52
  If `extractedCount === 0` after 11c, fire AskUserQuestion:
@@ -410,7 +410,7 @@ The role's required artefact paths (also see peaks-ui/rd/qa SKILL.md and `swarm-
410
410
  | Role | Writes | Reads (PRD-side) |
411
411
  |---|---|---|
412
412
  | `ui` | `.peaks/_runtime/<sessionId>/ui/design-draft.md`, `.peaks/_runtime/<sessionId>/ui/requests/<rid>.md` | PRD body, project-scan, archetype |
413
- | `rd-planning` | `.peaks/_runtime/<sessionId>/rd/tech-doc.md` (feature/refactor) or `.peaks/_runtime/<sessionId>/rd/bug-analysis.md` (bugfix) | PRD body, project-scan, existing-system, codegraph |
413
+ | `rd-planning` | `.peaks/_runtime/<sessionId>/rd/tech-doc.md` (feature/refactor) or `.peaks/_runtime/<sessionId>/rd/bug-analysis-<rid>.md` (bugfix) | PRD body, project-scan, existing-system, codegraph |
414
414
  | `qa-test-cases` | `.peaks/_runtime/<sessionId>/qa/test-cases/<rid>.md` | PRD body, RD planning artefact, project-scan, codegraph |
415
415
 
416
416
  **Code launches all sub-agents in the swarm plan in a single message (multiple `peaks sub-agent dispatch` calls in parallel, each followed by execution of the returned toolCall)** — this is what gives real concurrency. Do not sequentialize them. The CLI returns N toolCall descriptors; the LLM fires all N in the same message; the IDE dispatches them concurrently; Code then waits for all to return, runs `ls` checks against the paths above (Peaks-Loop Gate B), and only then advances to RD implementation.
@@ -94,7 +94,21 @@ You are running peaks-rd's planning step. Produce the planning artefact, not cod
94
94
  Code is written in a later sub-agent or inline run.
95
95
 
96
96
  Steps:
97
- 1. peaks request init --role rd --id <rid> --project <repo> --apply --type <type> --json
97
+ 1. peaks request init --role rd --id <rid> --session-id <sid> --project <repo> --apply --type <type> --json
98
+ `--session-id` is REQUIRED and has NO fallback: `request init` never reads
99
+ `.peaks/_runtime/session.json`, even when that file exists and holds the right
100
+ id and a sibling command resolves it — `peaks skill presence` does. Omit it and
101
+ the command exits 1 with `SESSION_ID_REQUIRED`; `--project` is required too.
102
+ (Measured 2026-10-13. Before that date this step omitted the flag, so the
103
+ command as written could not run.)
104
+ 1a. Backfill the artifact step 1 just created. It is a SKELETON, and creating it is
105
+ not producing it: measured, the `--role rd` template is 55 lines carrying 6
106
+ `<placeholder>` tokens (`<path>`, `<openspec change id>`, `<change-id>` twice,
107
+ `<percent>` twice). Replace every one with real content. The transition gate
108
+ lints the carrier, so a leftover placeholder makes
109
+ `peaks request transition --role rd --state implemented` return
110
+ `LINT_GATE_FAILED: 6 lint error(s)` — the whole count, on placeholder lines
111
+ alone. Nothing else in this prompt tells you the artifact needs filling.
98
112
  2. peaks request show <rid> --role prd --project <repo> --json
99
113
  3. peaks request show <rid> --role ui --project <repo> --json (if ui in plan)
100
114
  4. Read <project-scan-path>. If absent and Code did not pre-create it, create it
@@ -103,7 +117,7 @@ Steps:
103
117
  5. Read <existing-system-path> if archetype is legacy-*.
104
118
  6. Write the type-appropriate planning artefact:
105
119
  - feature | refactor → .peaks/_runtime/<sid>/rd/tech-doc.md
106
- - bugfix → .peaks/_runtime/<sid>/rd/bug-analysis.md
120
+ - bugfix → .peaks/_runtime/<sid>/rd/bug-analysis-<rid>.md
107
121
  - config | docs | chore → no planning artefact required. Return skipped.
108
122
  7. Return:
109
123
  {
@@ -124,12 +138,22 @@ You are running peaks-qa's planning step. Produce test cases, do NOT execute the
124
138
  The execution step runs after RD implementation in a separate sub-agent.
125
139
 
126
140
  Steps:
127
- 1. peaks request init --role qa --id <rid> --project <repo> --apply --type <type> --json
141
+ 1. peaks request init --role qa --id <rid> --session-id <sid> --project <repo> --apply --type <type> --json
142
+ `--session-id` is REQUIRED with no fallback — see §3.3 step 1 for the measured
143
+ reason. Omitting it exits 1 with `SESSION_ID_REQUIRED`.
144
+ 1a. Backfill the artifact step 1 just created. Measured: the `--role qa` template is
145
+ 53 lines carrying 2 `<id>` placeholders, and the transition gate lints the
146
+ carrier — a leftover placeholder is a `LINT_GATE_FAILED`, not a warning. See
147
+ §3.3 step 1a.
128
148
  2. peaks request show <rid> --role prd --project <repo> --json
129
149
  3. peaks request show <rid> --role rd --project <repo> --json
130
150
  4. Read <project-scan-path>.
131
151
  5. Write .peaks/_runtime/<sid>/qa/test-cases/<rid>.md with test cases linked to PRD
132
152
  acceptance items (use **Acceptance:** A1, A2 style).
153
+ The file MUST contain the literal line `## Test cases`. The prerequisite gate
154
+ matches that exact substring — a correct document under a differently-spelled
155
+ heading (`## Test Cases`, `## Test plan`) is refused as if it were missing, and
156
+ the refusal does not say which spelling it wanted. Write the heading first.
133
157
  6. Return:
134
158
  {
135
159
  "role": "qa-test-cases",
@@ -206,12 +230,12 @@ Sub-agent presence in this list = Code launched a Task for it. Absence = the rol
206
230
 
207
231
  > Body of `### Mode-driven fan-out shape`.
208
232
 
209
- | Mode | How the swarm plan is decided | What Code does |
210
- |---|---|---|
211
- | `full-auto` | Compute plan from signals above, no question to user | Auto-launch all sub-agents in the plan in parallel |
212
- | `24h` | Same as `full-auto` | Same as `full-auto` (long-run profile; the fan-out shape is identical, only the auto-compact cadence differs) |
213
- | `assisted` | `AskUserQuestion` with three options: (a) Full — UI + RD(planning) + QA(test-cases); (b) Backend-only — RD(planning) + QA(test-cases); (c) Sequential — run RD first, then QA, skip UI | Use the user's choice as the plan |
214
- | `strict` | Same as `assisted` (the question is informational; strict still enforces confirmation gates later) | Same as `assisted` |
233
+ | Mode | How the swarm plan is decided | What Code does |
234
+ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
235
+ | `full-auto` | Compute plan from signals above, no question to user | Auto-launch all sub-agents in the plan in parallel |
236
+ | `24h` | Same as `full-auto` | Same as `full-auto` (long-run profile; the fan-out shape is identical, only the auto-compact cadence differs) |
237
+ | `assisted` | `AskUserQuestion` with three options: (a) Full — UI + RD(planning) + QA(test-cases); (b) Backend-only — RD(planning) + QA(test-cases); (c) Sequential — run RD first, then QA, skip UI | Use the user's choice as the plan |
238
+ | `strict` | Same as `assisted` (the question is informational; strict still enforces confirmation gates later) | Same as `assisted` |
215
239
 
216
240
  In all modes, **the plan must be written to `sc/swarm-plan.json` before any Task call.** Code updates `.peaks/.active-skill.json` to `gate=swarm-fan-out` at this point.
217
241
 
@@ -219,12 +243,12 @@ In all modes, **the plan must be written to `sc/swarm-plan.json` before any Task
219
243
 
220
244
  > Body of `### Degradation when swarm roles fail or are absent`.
221
245
 
222
- | Condition | Code action | TXT handoff note |
223
- |---|---|---|
224
- | UI sub-agent returns blocked/error | RD continues with PRD visual descriptions | `ui-design-missing` |
225
- | RD planning sub-agent returns blocked/error | RD continues with PRD-derived planning | `tech-doc-missing` |
226
- | QA test-cases sub-agent returns blocked/error | RD continues; QA backfills test cases before verdict | `qa-test-cases-missing` |
227
- | Two or more of the above | Fall back to sequential: `peaks request transition rd → spec-locked` then inline RD run, then QA | `swarm-degraded-to-sequential` |
228
- | All three fail | Pause workflow; surface to user; request confirmation to continue | `swarm-aborted` |
246
+ | Condition | Code action | TXT handoff note |
247
+ | --------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------ |
248
+ | UI sub-agent returns blocked/error | RD continues with PRD visual descriptions | `ui-design-missing` |
249
+ | RD planning sub-agent returns blocked/error | RD continues with PRD-derived planning | `tech-doc-missing` |
250
+ | QA test-cases sub-agent returns blocked/error | RD continues; QA backfills test cases before verdict | `qa-test-cases-missing` |
251
+ | Two or more of the above | Fall back to sequential: `peaks request transition rd → spec-locked` then inline RD run, then QA | `swarm-degraded-to-sequential` |
252
+ | All three fail | Pause workflow; surface to user; request confirmation to continue | `swarm-aborted` |
229
253
 
230
254
  Skipping the entire swarm (when `--type` is `config|docs|chore`) is not a degradation — record `swarm-skipped: type=<type>` and proceed.
@@ -37,7 +37,7 @@ When Peaks-Loop Code coordinates development in a code repository, keep this ord
37
37
  - Assisted/Strict: pause with `AskUserQuestion` for explicit user confirmation before proceeding;
38
38
  3. **Peaks-Loop Swarm parallel phase** — after PRD confirmed, launch UI, RD(planning), QA(test-cases) simultaneously:
39
39
  3a. UI design draft and visual direction (MANDATORY when request is frontend/user-visible; skipped for `--type docs|chore|config` or pure-backend requests);
40
- 3b. RD planning artifact — `rd/tech-doc.md` for feature/refactor, `rd/bug-analysis.md` for bugfix, skipped for docs/chore/config;
40
+ 3b. RD planning artifact — `rd/tech-doc.md` for feature/refactor, `rd/bug-analysis-<rid>.md` for bugfix, skipped for docs/chore/config;
41
41
  3c. QA test-case generation (skipped for docs/chore — no acceptance surface to validate);
42
42
  4. **Peaks-Loop RD implementation** — consumes the type-appropriate inputs: project-scan + standards + (if UI involved) UI design-draft + RD planning artifact + QA test-cases. Includes unit tests for new/changed behavior (TDD) unless `--type` is docs/chore;
43
43
  5. **Peaks-Loop Code review + security review** — CRITICAL/HIGH issues fixed before progression; marked-blocked issues only allow a blocked handoff;
@@ -83,7 +83,7 @@ ls .peaks/_runtime/<sessionId>/prd/requests/<rid>.md
83
83
 
84
84
  # Type-specific RD planning artifact:
85
85
  # feature / refactor → ls .peaks/_runtime/<sessionId>/rd/tech-doc.md
86
- # bugfix → ls .peaks/_runtime/<sessionId>/rd/bug-analysis.md
86
+ # bugfix → ls .peaks/_runtime/<sessionId>/rd/bug-analysis-<rid>.md
87
87
  # config / docs / chore → (no RD planning artifact required)
88
88
 
89
89
  # QA test-cases (skipped for docs/chore):
@@ -105,8 +105,8 @@ The CLI gate (`peaks request transition --state qa-handoff`) is the authoritativ
105
105
  | Request type | Required RD evidence (under `.peaks/_runtime/<sessionId>/`) |
106
106
  |---|---|
107
107
  | `feature` / `refactor` | `rd/tech-doc.md` + `rd/code-review-<rid>.md` + `audit/security-<rid>.md` + `audit/perf-<rid>.md` + `qa/test-cases/<rid>.md` (qa/test-cases pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004) |
108
- | `bugfix` | `rd/bug-analysis.md` + `rd/code-review-<rid>.md` + `audit/security-<rid>.md` + `audit/perf-<rid>.md` + `qa/test-cases/<rid>.md` (the perf artifact is always required; a bug with no perf surface satisfies it with the `N/A — no perf surface` stub) |
109
- | `config` | `rd/security-review.md` (this one is genuinely ridless — `SECURITY_REVIEW.relativePath` carries no `<rid>`) |
108
+ | `bugfix` | `rd/bug-analysis-<rid>.md` + `rd/code-review-<rid>.md` + `audit/security-<rid>.md` + `audit/perf-<rid>.md` + `qa/test-cases/<rid>.md` (the perf artifact is always required; a bug with no perf surface satisfies it with the `N/A — no perf surface` stub) |
109
+ | `config` | `rd/security-review-<rid>.md` (`SECURITY_REVIEW.relativePath` carries the `<rid>` since slice `2026-10-14-backlog-9-37-prereq-collisions`; the bare `rd/security-review.md` stays readable as the legacy tier) |
110
110
  | `docs` / `chore` | (no extra evidence required) |
111
111
 
112
112
  > The four rid-scoped names above are the gate's **primary** tier (slice `2026-09-14-audit-artifact-rid-scoping`): two slices in one session share `rd/` and `audit/`, so a ridless write silently destroyed the earlier slice's evidence. The pre-rid names (`rd/code-review.md`, `audit/security.md`, `audit/perf.md`, `rd/security-review.md`, `rd/perf-baseline.md`) remain accepted as **back-compat tiers** — they keep old sessions passing, but a new slice must write the rid-scoped name or it reopens the collision.
@@ -120,9 +120,9 @@ ls .peaks/_runtime/<sessionId>/rd/requests/<rid>.md
120
120
  # Type-specific RD evidence (must match the type recorded in the artifact body)
121
121
  # feature / refactor → ls rd/tech-doc.md rd/code-review-<rid>.md audit/security-<rid>.md audit/perf-<rid>.md qa/test-cases/<rid>.md
122
122
  # (qa/test-cases/<rid>.md pre-drafted by the 4th sub-agent in peaks-rd's parallel fan-out — slice 004)
123
- # bugfix → ls rd/bug-analysis.md rd/code-review-<rid>.md audit/security-<rid>.md audit/perf-<rid>.md qa/test-cases/<rid>.md
123
+ # bugfix → ls rd/bug-analysis-<rid>.md rd/code-review-<rid>.md audit/security-<rid>.md audit/perf-<rid>.md qa/test-cases/<rid>.md
124
124
  # (the perf artifact is always required; use the "N/A — no perf surface" stub when there is no perf surface)
125
- # config → ls rd/security-review.md
125
+ # config → ls rd/security-review-<rid>.md
126
126
  # docs / chore → (no extra evidence required)
127
127
  # Missing any required file → DO NOT attempt the qa-handoff transition; CLI will reject with PREREQUISITES_MISSING.
128
128
  ```
@@ -29,7 +29,7 @@ The explicit `MUST NOT` block lives in:
29
29
  - `peaks sub-agent dispatch` CLI prompt template
30
30
 
31
31
  Each prompt template carries the block:
32
- > MUST NOT follow the superpowers chain (`brainstorming` → `writing-plans` → `subagent-driven-development` → `using-git-worktrees`) for worktree decisions. The chain is reference material, not a workflow. For worktree operations, use `peaks worktree spawn --rid <id> --ttl <duration> --purpose <text>` (or, until that ships, fall back to L2 hook gate + manual `peaks worktree auth grant`).
32
+ > MUST NOT follow the superpowers chain (`brainstorming` → `writing-plans` → `subagent-driven-development` → `using-git-worktrees`) for worktree decisions. The chain is reference material, not a workflow. For worktree operations, use `peaks worktree spawn --rid <rid> --role <role> --purpose <text>` (or, until that ships, fall back to L2 hook gate + manual `peaks worktree auth grant`).
33
33
 
34
34
  L1 is the weakest layer because the LLM is the decision-maker and may forget the block under load. L3 exists to catch L1 failures.
35
35
 
@@ -40,9 +40,9 @@ L1 is the weakest layer because the LLM is the decision-maker and may forget the
40
40
  ```bash
41
41
  # User authorizes a worktree operation
42
42
  peaks worktree auth grant \
43
- --rid rid-2026-07-29-worktree-spawn \
43
+ --operation git-worktree \
44
44
  --reason "RD sub-agent for worktree spawn slice" \
45
- --ttl 5m
45
+ --request-id rid-2026-07-29-worktree-spawn
46
46
  # Output: grant token, single-use by default
47
47
  ```
48
48
 
@@ -79,7 +79,7 @@ Sediment: `.peaks/memory/2026-07-29-worktree-layer3-deny.md`.
79
79
 
80
80
  Every sub-agent dispatched by peaks-rd / peaks-qa / peaks-ui / peaks-sc / peaks-txt MUST:
81
81
 
82
- 1. **Use `peaks worktree spawn --rid <rid> --ttl <duration> --purpose <text>`** for any worktree operation. Raw `git worktree add` is forbidden.
82
+ 1. **Use `peaks worktree spawn --rid <rid> --role <role> --purpose <text>`** for any worktree operation. Raw `git worktree add` is forbidden.
83
83
  2. **Treat the superpowers chain as reference material only.** It MAY inform PRD / RD planning but MUST NOT drive tool selection.
84
84
  3. **Write artifacts under `.peaks/_runtime/<sessionId>/<role>/requests/` in the MAIN checkout.** Dispatch with `--project .` (the main workdir), NOT `--project .claude/worktrees/...`. Worktrees are ephemeral; main is durable.
85
85
 
@@ -3,7 +3,7 @@ name: peaks-content
3
3
  description: Non-code orchestrator for content workflows (draft / edit / publish / archive). Use when a user wants to drive an end-to-end content-production loop (blog post, newsletter, marketing copy, social thread, doc page) where the LLM must coordinate draft / edit / tone / publish / archive stages with explicit gates between them, and where the user only wants to speak natural language and pick options. NOT for free-form chatting; NOT for code review. Reuses the peaks-loop Loop Engineering primitives (Loop Engineering Asset, Bee Asset, Workflow Trace, Evolution Evaluation) but does NOT import peaks-code internals. Triggers on `/peaks-content`, "peaks content", "content workflow", "publish this to <channel>", "edit the draft", "archive the previous version".
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
 
@@ -4,7 +4,7 @@ description: Orchestrate peaks-loop's L3 doctor (peaks audit + peaks doctor + pe
4
4
  visibility: internal
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
 
@@ -3,7 +3,7 @@ name: peaks-final-review
3
3
  description: Final-review skill for Peaks. Use when a workflow needs to assemble 4-dimension business-review evidence (functional-completeness, problem-resolution, no-new-bugs, existing-functionality-intact) for human acceptance at the end of an autonomous slice. Triggers on "/peaks-final-review", "prepare final review", "4-dim review", or peaks-code end-of-workflow handoff.
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
 
@@ -69,7 +69,7 @@ interface PrepareFinalReviewOptions {
69
69
  }
70
70
  ```
71
71
 
72
- The service is the **gate primitive** that closes the 10% human / 90% LLM loop. It reads the approved audit-goal JSON from `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`, **collects real evidence from disk** (`qa/test-reports`, `qa/test-cases`, `qa/security-findings`, `qa/performance-findings`, `rd/{tech-doc,bug-analysis,code-review,security-review}.md`, `prd/handoff.md`), inlines it into the 4-dim review prompt under byte bounds, calls an injected `LlmRunner` exactly once, parses the response, and validates that all four required dimensions are present. It throws `IncompleteFinalReviewError` on malformed JSON or missing dimensions — callers MUST treat that as a gate failure (return to human for re-prompting) and never let autonomous work proceed on a partial review.
72
+ The service is the **gate primitive** that closes the 10% human / 90% LLM loop. It reads the approved audit-goal JSON from `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`, **collects real evidence from disk** (`qa/test-reports`, `qa/test-cases`, `qa/security-findings`, `qa/performance-findings`, `rd/{tech-doc,bug-analysis-<rid>,code-review-<rid>,security-review}.md`, `prd/handoff.md`), inlines it into the 4-dim review prompt under byte bounds, calls an injected `LlmRunner` exactly once, parses the response, and validates that all four required dimensions are present. It throws `IncompleteFinalReviewError` on malformed JSON or missing dimensions — callers MUST treat that as a gate failure (return to human for re-prompting) and never let autonomous work proceed on a partial review.
73
73
 
74
74
  > **Evidence-backed verdicts (added 2026-09-12).** The service previously sent the model only `successCriteria` and no evidence at all, so it could not honestly grade anything — a real run returned 4/4 `inconclusive`, and a model willing to confabulate could have returned `pass`. Verdicts are now gated **structurally**, not by prompt wording: any `pass` whose supporting sources were all missing/empty is rewritten to `inconclusive` + `confidence: low` (`fail` is never softened), and `allPass` is derived from the gated verdicts so it can only narrow. Every non-`found` evidence source renders an explicit `STATUS: MISSING (<why>)` in the prompt, so the model always knows what it does not know.
75
75
 
@@ -97,18 +97,38 @@ If any precondition is missing, **STOP** and route back to the responsible skill
97
97
  > **the rid is positional**. Use the CLI.
98
98
 
99
99
  ```bash
100
- peaks prepare-final-review <rid> [--session-id <sid>] [--project <path>] [--llm-provider <name>] [--json]
100
+ peaks prepare-final-review <rid> --session-id <sid> [--project <path>] [--llm-provider <name>] [--json]
101
101
  ```
102
102
 
103
103
  - `<rid>` is **positional** (not `--rid`). It resolves to `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`.
104
- - `--session-id` defaults to the active workspace binding when omitted.
105
- - **`--llm-provider` defaults to `stub`, and `stub` is the only provider that works today.**
106
- `stub` runs no real review — it returns a scaffold envelope so CI can prove the route is reachable.
107
- Verified 2026-09-12: passing a real provider (`--llm-provider anthropic`) returns
108
- `status: not-applicable` / `serviceWired: false` / `providerBinding: unknown` and tells you to re-run
109
- with `stub`; the CLI's own nextAction calls real-provider binding "a follow-up slice". So there is
110
- currently **no reachable path to a real 4-dim review** — confirming the route works is all `stub`
111
- can do.
104
+ - **`--session-id` is REQUIRED.** It is not inferred from the active binding: the CLI validates it and
105
+ refuses an empty value.
106
+ > **⚠️ 2026-10-12 correction.** This line read *"`--session-id` defaults to the active workspace
107
+ > binding when omitted"* and the usage line above showed it as optional. **Both were false** —
108
+ > omitting it fails with `MISSING_REQUIRED_FLAG` (`final-review-prepare-command.ts:84` returns that
109
+ > code — **not `MISSING_REQUIRED_OPTION`, which is what the handoff §2.14 recorded and what an
110
+ > earlier version of this line repeated**; the wrong identifier had been copied between documents
111
+ > without anyone reading the code. `final-review-commands.ts:51` declares the option as required, so
112
+ > it is not inferred from the binding.) The validator also rejects `..`, `/` and `\` in the value.
113
+ > segment and rejects an empty string). Recorded as a doc-behind-code drift in
114
+ > `.peaks/docs/backlog.md` §7.14; fixed here.
115
+ - **`--llm-provider` defaults to `stub`.** `stub` runs no real review — it returns a
116
+ `status: scaffold-only` / `providerBinding: stub` envelope so the route's reachability can be proven
117
+ without spending a model call.
118
+ - **A real provider is reachable.** `--llm-provider anthropic` returns `status: review-complete` with
119
+ `providerBinding: anthropic-messages-api`.
120
+ > **⚠️ 2026-10-12 correction.** This block previously asserted the opposite — *"`stub` is the only
121
+ > provider that works today"*, plus a "verified 2026-09-12" measurement of
122
+ > `status: not-applicable` / `serviceWired: false` / `providerBinding: unknown`, concluding there was
123
+ > **no reachable path to a real 4-dim review**. **That is no longer true and was measured false twice
124
+ > on 2026-10-12** (once per slice), on both a `feature` and a `bugfix` rid.
125
+ >
126
+ > What the old note was really describing is a *different* problem, and it is worth keeping: a real
127
+ > review's four dimensions can still come back `inconclusive` — but because of **evidence delivery**,
128
+ > not the provider. The assembler inlines a source **whole or not at all** against a per-file cap, so
129
+ > a thorough artifact (a 42 KB test-case file, a 28 KB PRD handoff) is truncated and the dimension
130
+ > cannot be judged. **Writing more evidence can therefore make a dimension less judgeable.** See
131
+ > `.peaks/_runtime/2026-10-12-session-74bd69/sc/rollout-findings.md` §S-7.
112
132
  - `--json` is required for machine consumption (peaks-code, peaks-txt, downstream CI).
113
133
 
114
134
  Calling the service directly (`prepareFinalReview(rid, { projectRoot, sessionId, llmRunner })`) remains
@@ -4,7 +4,7 @@ description: Orchestrate peaks-loop's IDE-aware behavior (hooks + statusline + h
4
4
  visibility: internal
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
 
@@ -3,7 +3,7 @@ name: peaks-issue-fix-orchestrator
3
3
  description: 'End-to-end orchestrator that surveys open issues in a target repo, classifies them by difficulty, mines reference merged-PRs, fixes each issue with real commits (with Repository + AI-modified declaration), writes normalized PR description files, and emits a one-line submit script. Use when the user wants to drive a "fix N open issues and prepare PRs" run on an upstream repo (any language; primarily Python + TypeScript). Reuses Loop Engineering primitives: 4-layer asset model, Darwin ratchet, karpathy-engineered red lines, Human-NL-Choice-Only. Triggers on `/peaks-issue-fix-orchestrator`, "fix 30 issues", "dogfood on <repo>", "open-issue sweep on <repo>".'
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