peaks-loop 4.1.4 → 4.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (294) hide show
  1. package/.claude-plugin/marketplace.json +7 -2
  2. package/CHANGELOG.md +148 -0
  3. package/README-en.md +47 -183
  4. package/README.md +24 -188
  5. package/dist/cli/cli-helpers.d.ts +20 -0
  6. package/dist/cli/cli-helpers.js +34 -0
  7. package/dist/cli/commands/_register.js +2 -0
  8. package/dist/cli/commands/best-practice-scan-command.d.ts +11 -6
  9. package/dist/cli/commands/best-practice-scan-command.js +35 -20
  10. package/dist/cli/commands/best-practice-scan-helpers.d.ts +47 -0
  11. package/dist/cli/commands/best-practice-scan-helpers.js +88 -5
  12. package/dist/cli/commands/best-practice-scan-lookup-results.d.ts +13 -0
  13. package/dist/cli/commands/best-practice-scan-lookup-results.js +237 -0
  14. package/dist/cli/commands/code-commands.d.ts +6 -4
  15. package/dist/cli/commands/code-commands.js +6 -4
  16. package/dist/cli/commands/code-gate-command.d.ts +5 -5
  17. package/dist/cli/commands/code-gate-command.js +49 -9
  18. package/dist/cli/commands/code-mode-gate-plan-command.d.ts +1 -1
  19. package/dist/cli/commands/code-mode-gate-plan-command.js +2 -2
  20. package/dist/cli/commands/core/memory-extract-command.js +10 -5
  21. package/dist/cli/commands/dispatch-cli-invocation-check.d.ts +108 -0
  22. package/dist/cli/commands/dispatch-cli-invocation-check.js +87 -0
  23. package/dist/cli/commands/dispatch-cli-invocation-scan.d.ts +66 -0
  24. package/dist/cli/commands/dispatch-cli-invocation-scan.js +162 -0
  25. package/dist/cli/commands/dispatch-command-spec.js +1 -1
  26. package/dist/cli/commands/dispatch-commands.js +12 -5
  27. package/dist/cli/commands/dispatch-isolation-lease.d.ts +1 -1
  28. package/dist/cli/commands/dispatch-isolation-lease.js +6 -53
  29. package/dist/cli/commands/dispatch-preflight.js +46 -0
  30. package/dist/cli/commands/dispatch-prompt-blocks.d.ts +1 -1
  31. package/dist/cli/commands/dispatch-prompt-composition.d.ts +7 -1
  32. package/dist/cli/commands/dispatch-prompt-composition.js +29 -7
  33. package/dist/cli/commands/dispatch-record-write.d.ts +1 -1
  34. package/dist/cli/commands/dispatch-tool-call.d.ts +1 -1
  35. package/dist/cli/commands/doc-commands.js +1 -1
  36. package/dist/cli/commands/feedback-commands-helpers.js +1 -1
  37. package/dist/cli/commands/final-review-prepare-command.js +22 -1
  38. package/dist/cli/commands/gate-commands-enforce.js +3 -3
  39. package/dist/cli/commands/hook-handle.js +41 -20
  40. package/dist/cli/commands/lint-commands.js +3 -1
  41. package/dist/cli/commands/loop-eval-capture-index.js +2 -4
  42. package/dist/cli/commands/openspec-command-shared.js +2 -2
  43. package/dist/cli/commands/perf-audit-commands.js +15 -5
  44. package/dist/cli/commands/project-commands.js +9 -6
  45. package/dist/cli/commands/race-commands.d.ts +15 -0
  46. package/dist/cli/commands/race-commands.js +65 -0
  47. package/dist/cli/commands/race-pilot-gate-record-command.d.ts +3 -0
  48. package/dist/cli/commands/race-pilot-gate-record-command.js +81 -0
  49. package/dist/cli/commands/request-command-options.d.ts +8 -0
  50. package/dist/cli/commands/request-commands.js +2 -0
  51. package/dist/cli/commands/request-init-command.js +67 -12
  52. package/dist/cli/commands/{vm-status-command.d.ts → request-retag-command.d.ts} +1 -1
  53. package/dist/cli/commands/request-retag-command.js +50 -0
  54. package/dist/cli/commands/request-show-command.d.ts +8 -0
  55. package/dist/cli/commands/request-show-command.js +14 -1
  56. package/dist/cli/commands/request-transition-command.js +12 -4
  57. package/dist/cli/commands/request-transition-failures.d.ts +14 -0
  58. package/dist/cli/commands/request-transition-failures.js +76 -7
  59. package/dist/cli/commands/request-transition-preflight.js +1 -1
  60. package/dist/cli/commands/scan-scope-commands.js +2 -2
  61. package/dist/cli/commands/security-audit-commands.js +26 -6
  62. package/dist/cli/commands/slice-decompose-artifacts.js +2 -1
  63. package/dist/cli/commands/verdict-aggregate-command.js +2 -1
  64. package/dist/cli/commands/workflow-gate-commands.js +4 -4
  65. package/dist/cli/commands/worktree-lease-gc-command.js +1 -1
  66. package/dist/cli/program.js +0 -2
  67. package/dist/services/artifacts/artifact-contract-block.d.ts +53 -0
  68. package/dist/services/artifacts/artifact-contract-block.js +231 -0
  69. package/dist/services/artifacts/artifact-prerequisites.d.ts +27 -19
  70. package/dist/services/artifacts/artifact-prerequisites.js +65 -135
  71. package/dist/services/artifacts/artifact-templates.d.ts +1 -1
  72. package/dist/services/artifacts/artifact-templates.js +17 -10
  73. package/dist/services/artifacts/prerequisite-checks.d.ts +87 -0
  74. package/dist/services/artifacts/prerequisite-checks.js +198 -0
  75. package/dist/services/artifacts/prerequisite-transition-event.d.ts +20 -0
  76. package/dist/services/artifacts/prerequisite-transition-event.js +27 -0
  77. package/dist/services/artifacts/rd-transition-gates.d.ts +33 -0
  78. package/dist/services/artifacts/rd-transition-gates.js +71 -0
  79. package/dist/services/artifacts/request-artifact-metadata.d.ts +31 -0
  80. package/dist/services/artifacts/request-artifact-metadata.js +44 -0
  81. package/dist/services/artifacts/request-artifact-service.d.ts +5 -0
  82. package/dist/services/artifacts/request-artifact-service.js +43 -69
  83. package/dist/services/artifacts/request-artifact-state-helpers.d.ts +21 -1
  84. package/dist/services/artifacts/request-artifact-state-helpers.js +34 -8
  85. package/dist/services/artifacts/request-retag-service.d.ts +68 -0
  86. package/dist/services/artifacts/request-retag-service.js +125 -0
  87. package/dist/services/artifacts/request-state-order.d.ts +38 -0
  88. package/dist/services/artifacts/request-state-order.js +99 -0
  89. package/dist/services/artifacts/request-type-demand.d.ts +44 -0
  90. package/dist/services/artifacts/request-type-demand.js +71 -0
  91. package/dist/services/audit/audit-goal-service.d.ts +7 -0
  92. package/dist/services/audit/enforcers/active-skill-resolver.d.ts +18 -0
  93. package/dist/services/audit/enforcers/active-skill-resolver.js +48 -1
  94. package/dist/services/audit/enforcers/code-ban.d.ts +11 -2
  95. package/dist/services/audit/enforcers/code-ban.js +21 -1
  96. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.d.ts +17 -0
  97. package/dist/services/audit/red-line-catalog-p2-a-bee-runtime.js +24 -7
  98. package/dist/services/audit-independent/handoff-missing-refusal.d.ts +26 -0
  99. package/dist/services/audit-independent/handoff-missing-refusal.js +109 -0
  100. package/dist/services/audit-independent/handoff-readers.d.ts +37 -0
  101. package/dist/services/audit-independent/handoff-readers.js +81 -0
  102. package/dist/services/audit-independent/index.d.ts +6 -1
  103. package/dist/services/audit-independent/index.js +6 -1
  104. package/dist/services/audit-independent/judged-declaration-build.d.ts +48 -0
  105. package/dist/services/audit-independent/judged-declaration-build.js +73 -0
  106. package/dist/services/audit-independent/judged-declaration-check.d.ts +80 -0
  107. package/dist/services/audit-independent/judged-declaration-check.js +216 -0
  108. package/dist/services/audit-independent/judged-declaration.d.ts +94 -0
  109. package/dist/services/audit-independent/judged-declaration.js +218 -0
  110. package/dist/services/audit-independent/perf-audit-service.js +12 -14
  111. package/dist/services/audit-independent/security-audit-artifact.d.ts +28 -0
  112. package/dist/services/audit-independent/security-audit-artifact.js +90 -0
  113. package/dist/services/audit-independent/security-audit-service.d.ts +6 -53
  114. package/dist/services/audit-independent/security-audit-service.js +34 -178
  115. package/dist/services/capability-guard-runner/contracts/J05.js +60 -14
  116. package/dist/services/codegraph/codegraph-index-integrity.js +2 -0
  117. package/dist/services/context/build-dispatch-system-prompt.d.ts +8 -12
  118. package/dist/services/context/build-dispatch-system-prompt.js +18 -18
  119. package/dist/services/context/collector.js +5 -1
  120. package/dist/services/context/post-compact-reinjection.js +1 -1
  121. package/dist/services/dispatch/active-dispatch-index.d.ts +36 -0
  122. package/dist/services/dispatch/active-dispatch-index.js +118 -0
  123. package/dist/services/dispatch/batch-counter.js +1 -2
  124. package/dist/services/dispatch/dispatch-record-writer.d.ts +29 -16
  125. package/dist/services/dispatch/dispatch-record-writer.js +58 -100
  126. package/dist/services/dispatch/dispatch-sub-agent.js +1 -1
  127. package/dist/services/dispatch/karpathy-block.d.ts +55 -0
  128. package/dist/services/dispatch/karpathy-block.js +101 -0
  129. package/dist/services/dispatch/ledger-reaper.d.ts +80 -0
  130. package/dist/services/dispatch/ledger-reaper.js +131 -0
  131. package/dist/services/dispatch/test-tool-detection.d.ts +17 -1
  132. package/dist/services/dispatch/test-tool-detection.js +12 -1
  133. package/dist/services/evidence/evidence-generator.js +23 -12
  134. package/dist/services/feedback/feedback-promotion-service.d.ts +8 -11
  135. package/dist/services/feedback/feedback-promotion-service.js +30 -35
  136. package/dist/services/feedback/promotion-artifact-json-evidence.d.ts +18 -0
  137. package/dist/services/feedback/promotion-artifact-missing.d.ts +22 -0
  138. package/dist/services/feedback/promotion-artifact-missing.js +63 -0
  139. package/dist/services/final-review/final-review-contract.d.ts +95 -4
  140. package/dist/services/final-review/final-review-contract.js +64 -0
  141. package/dist/services/final-review/final-review-delivery.d.ts +13 -0
  142. package/dist/services/final-review/final-review-delivery.js +26 -12
  143. package/dist/services/final-review/final-review-evidence-collect.js +8 -53
  144. package/dist/services/final-review/final-review-evidence-records.d.ts +21 -0
  145. package/dist/services/final-review/final-review-evidence-records.js +67 -0
  146. package/dist/services/final-review/final-review-evidence-sources.d.ts +22 -0
  147. package/dist/services/final-review/final-review-evidence-sources.js +28 -4
  148. package/dist/services/final-review/final-review-prompt.js +19 -6
  149. package/dist/services/final-review/final-review-runner.js +5 -0
  150. package/dist/services/final-review/final-review-service.d.ts +2 -2
  151. package/dist/services/final-review/index.d.ts +1 -1
  152. package/dist/services/final-review/pre-post-diff.d.ts +2 -75
  153. package/dist/services/final-review/pre-post-diff.js +60 -59
  154. package/dist/services/hooks/pre-tool-code-gate.d.ts +7 -1
  155. package/dist/services/hooks/pre-tool-code-gate.js +21 -2
  156. package/dist/services/hooks/worktree-authorization-gate.js +6 -31
  157. package/dist/services/hooks/worktree-refusal-messages.d.ts +74 -0
  158. package/dist/services/hooks/worktree-refusal-messages.js +102 -0
  159. package/dist/services/lint/eslint-runner-support.d.ts +1 -1
  160. package/dist/services/lint/eslint-runner-support.js +2 -1
  161. package/dist/services/lint/eslint-runner-types.d.ts +8 -0
  162. package/dist/services/lint/eslint-runner.js +17 -4
  163. package/dist/services/llm/anthropic-runner.js +24 -7
  164. package/dist/services/loop/loop-observability.d.ts +39 -0
  165. package/dist/services/loop/loop-observability.js +55 -0
  166. package/dist/services/loop/monotonic-guard.js +6 -9
  167. package/dist/services/loop/monotonic-runner.js +8 -7
  168. package/dist/services/loop/run-driver.js +18 -22
  169. package/dist/services/memory/project-memory-service/index/kind-dispatch.js +14 -1
  170. package/dist/services/memory/project-memory-service/index/project-memory-plan-exec.js +13 -2
  171. package/dist/services/memory/project-memory-service/index.d.ts +2 -2
  172. package/dist/services/memory/project-memory-service/index.js +1 -1
  173. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.d.ts +36 -0
  174. package/dist/services/memory/project-memory-service/parsers/frontmatter-parse.js +48 -2
  175. package/dist/services/memory/project-memory-service/parsers/markdown-pure.d.ts +23 -1
  176. package/dist/services/memory/project-memory-service/parsers/markdown-pure.js +37 -0
  177. package/dist/services/memory/project-memory-service/types.d.ts +32 -0
  178. package/dist/services/observability/observability-service.d.ts +7 -0
  179. package/dist/services/observability/observability-service.js +2 -1
  180. package/dist/services/openspec/coverage-evidence-reader.d.ts +9 -9
  181. package/dist/services/openspec/coverage-evidence-reader.js +8 -8
  182. package/dist/services/openspec/openspec-archive-service.d.ts +1 -1
  183. package/dist/services/openspec/openspec-archive-service.js +6 -6
  184. package/dist/services/prd/gate-evidence-derivation.d.ts +4 -3
  185. package/dist/services/prd/gate-evidence-derivation.js +4 -3
  186. package/dist/services/qa/bdd-test-style-verifier.js +22 -8
  187. package/dist/services/race/gate2-evaluator.d.ts +58 -0
  188. package/dist/services/race/gate2-evaluator.js +111 -0
  189. package/dist/services/race/gate2-policy.d.ts +17 -0
  190. package/dist/services/race/gate2-policy.js +31 -0
  191. package/dist/services/race/lane-phase.d.ts +19 -0
  192. package/dist/services/race/lane-phase.js +113 -0
  193. package/dist/services/race/pilot-gate-store.d.ts +67 -0
  194. package/dist/services/race/pilot-gate-store.js +227 -0
  195. package/dist/services/scan/file-size-baseline.d.ts +33 -0
  196. package/dist/services/scan/file-size-baseline.js +173 -0
  197. package/dist/services/scan/file-size-scan.d.ts +35 -3
  198. package/dist/services/scan/file-size-scan.js +63 -42
  199. package/dist/services/scan/type-corroboration.d.ts +32 -0
  200. package/dist/services/scan/type-corroboration.js +51 -0
  201. package/dist/services/scan/type-sanity-service.d.ts +14 -0
  202. package/dist/services/scan/type-sanity-service.js +23 -22
  203. package/dist/services/security/safe-settings-path.d.ts +5 -0
  204. package/dist/services/security/safe-settings-path.js +64 -8
  205. package/dist/services/skill/resume-detector.js +11 -11
  206. package/dist/services/skills/hooks-codegate-superpowers.d.ts +5 -6
  207. package/dist/services/skills/hooks-codegate-superpowers.js +7 -8
  208. package/dist/services/skills/hooks-settings-service.d.ts +1 -1
  209. package/dist/services/skills/hooks-settings-service.js +1 -1
  210. package/dist/services/skills/presence-lease-order.d.ts +13 -0
  211. package/dist/services/skills/presence-lease-order.js +24 -0
  212. package/dist/services/skills/skill-conformance-service.js +1 -0
  213. package/dist/services/skills/skill-statusline-service.js +4 -7
  214. package/dist/services/slice/slice-check-service.js +8 -8
  215. package/dist/services/workflow/pipeline-verify-gate-support.d.ts +24 -8
  216. package/dist/services/workflow/pipeline-verify-gate-support.js +34 -39
  217. package/dist/services/workflow/pipeline-verify-qa-phase.d.ts +102 -0
  218. package/dist/services/workflow/pipeline-verify-qa-phase.js +176 -0
  219. package/dist/services/workflow/pipeline-verify-service.js +27 -28
  220. package/dist/services/workflow/request-type-resolution.d.ts +99 -0
  221. package/dist/services/workflow/request-type-resolution.js +130 -0
  222. package/dist/services/workflow/workflow-skip-service.d.ts +1 -20
  223. package/dist/services/workflow/workflow-skip-service.js +22 -25
  224. package/dist/services/workflow/workflow-state-store.d.ts +9 -0
  225. package/dist/services/workflow/workflow-state-store.js +26 -1
  226. package/dist/services/workspace/claude-settings-retirements.d.ts +54 -0
  227. package/dist/services/workspace/claude-settings-retirements.js +112 -0
  228. package/dist/services/workspace/claude-settings-template-merge.d.ts +35 -15
  229. package/dist/services/workspace/claude-settings-template-merge.js +33 -53
  230. package/dist/services/workspace/claude-settings-template.d.ts +62 -12
  231. package/dist/services/workspace/claude-settings-template.js +58 -58
  232. package/dist/services/workspace/migrate-1-4-1-service.js +3 -0
  233. package/dist/services/workspace/reconcile-service.js +0 -1
  234. package/dist/shared/incrementing-number.d.ts +33 -2
  235. package/dist/shared/incrementing-number.js +72 -3
  236. package/package.json +5 -7
  237. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  238. package/skills/bee/peaks-prd/SKILL.md +4 -3
  239. package/skills/bee/peaks-qa/SKILL.md +1 -1
  240. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  241. package/skills/bee/peaks-qa/references/qa-transition-gates.md +1 -1
  242. package/skills/bee/peaks-rd/SKILL.md +2 -2
  243. package/skills/bee/peaks-rd/references/rd-fanout-contracts.md +1 -1
  244. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +8 -4
  245. package/skills/bee/peaks-rd/references/rd-transition-gates.md +3 -3
  246. package/skills/bee/peaks-rd/references/v2-12-fanout-collapse.md +2 -2
  247. package/skills/bee/peaks-rd/references/writing-handoff-frontmatter.md +1 -1
  248. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  249. package/skills/bee/peaks-sc/SKILL.md +1 -1
  250. package/skills/bee/peaks-security-audit/SKILL.md +10 -2
  251. package/skills/bee/peaks-txt/SKILL.md +4 -3
  252. package/skills/bee/peaks-ui/SKILL.md +3 -3
  253. package/skills/peaks-audit/SKILL.md +29 -1
  254. package/skills/peaks-code/SKILL.md +37 -17
  255. package/skills/peaks-code/references/fast-lane-norm.md +42 -0
  256. package/skills/peaks-code/references/fast-mode.md +3 -2
  257. package/skills/peaks-code/references/local-artifact-workspace.md +3 -3
  258. package/skills/peaks-code/references/micro-cycle.md +3 -3
  259. package/skills/peaks-code/references/resume-detection.md +1 -1
  260. package/skills/peaks-code/references/runbook.md +12 -6
  261. package/skills/peaks-code/references/step-11-memory-sediment.md +4 -0
  262. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  263. package/skills/peaks-code/references/swarm-dispatch-contract.md +40 -16
  264. package/skills/peaks-code/references/workflow-gates-and-types.md +6 -6
  265. package/skills/peaks-code/references/worktree-governance.md +4 -4
  266. package/skills/peaks-content/SKILL.md +1 -1
  267. package/skills/peaks-doctor/SKILL.md +1 -1
  268. package/skills/peaks-final-review/SKILL.md +31 -11
  269. package/skills/peaks-ide/SKILL.md +1 -1
  270. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  271. package/skills/peaks-race-code/SKILL.md +185 -0
  272. package/skills/peaks-resume/SKILL.md +1 -1
  273. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  274. package/skills/peaks-solo/SKILL.md +1 -1
  275. package/skills/peaks-sop/SKILL.md +1 -1
  276. package/skills/peaks-status/SKILL.md +1 -1
  277. package/skills/peaks-test/SKILL.md +7 -4
  278. package/dist/cli/commands/vm-command-shared.d.ts +0 -23
  279. package/dist/cli/commands/vm-command-shared.js +0 -23
  280. package/dist/cli/commands/vm-commands.d.ts +0 -3
  281. package/dist/cli/commands/vm-commands.js +0 -45
  282. package/dist/cli/commands/vm-hypervisor-probe.d.ts +0 -27
  283. package/dist/cli/commands/vm-hypervisor-probe.js +0 -78
  284. package/dist/cli/commands/vm-hypervisor-runtime.d.ts +0 -15
  285. package/dist/cli/commands/vm-hypervisor-runtime.js +0 -64
  286. package/dist/cli/commands/vm-release-command.d.ts +0 -5
  287. package/dist/cli/commands/vm-release-command.js +0 -101
  288. package/dist/cli/commands/vm-spawn-command.d.ts +0 -5
  289. package/dist/cli/commands/vm-spawn-command.js +0 -177
  290. package/dist/cli/commands/vm-status-command.js +0 -50
  291. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.d.ts +0 -23
  292. package/dist/services/audit/enforcers/lint-peaks-skill-runtime.js +0 -64
  293. package/dist/services/vm/vm-lease.d.ts +0 -40
  294. package/dist/services/vm/vm-lease.js +0 -160
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.4"
4
+ "version": "4.1.6"
5
5
  },
6
6
  "plugins": [
7
7
  {
8
8
  "name": "peaks-loop",
9
9
  "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
10
- "version": "4.1.4",
10
+ "version": "4.1.6",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
@@ -123,6 +123,11 @@
123
123
  "description": "QA and verification role for Peaks-Loop (LLM-only internal role; not user-invocable.\nTriggered by peaks-code via `peaks sub-agent dispatch --role qa`.)\nUse when a workflow needs unit-test coverage evidence, regression matrices,\nbaseline reports, validation reports, acceptance checks, or refactor verification gates.",
124
124
  "userInvocable": false
125
125
  },
126
+ {
127
+ "name": "peaks-race-code",
128
+ "path": "./skills/peaks-race-code",
129
+ "description": "Fast lane for code work — this window edits source directly, with no sub-agents and no paperwork. Use it when a code task is small enough that opening a second context window is the whole cost, i.e. trivial and everyday small features and bug fixes whose diff you can hold in your head. Not for a task that touches one of the risk surfaces the fast-lane norm names (`../peaks-code/references/fast-lane-norm.md`), and not for work that needs a durable audit trail — those belong to peaks-code; read the norm before you decide. Triggers on \"/peaks-race-code\", \"peaks race\", \"race this\", \"fast lane\", \"直接改,别走全流程\"."
130
+ },
126
131
  {
127
132
  "name": "peaks-rd",
128
133
  "path": "./skills/bee/peaks-rd",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,153 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.6 — 2026-10-18(三类闸规则收紧:配置路径的 reader、skip 允许列表、声明类型;两个 refactor 切片被自己新增的规则抓住)
4
+
5
+ **版本级别**: 未发布区间 `v4.1.5..HEAD` 共 **38 个 commit**(**2 feat / 11 fix / 3 refactor / 7 chore / 8 docs / 4 test+style**)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。**本版含两处用户可见的行为收紧**,按 4.1.5 的先例明写:声明为 `docs`/`chore`/`config` 的请求不能再携带产品源码;`config` 不再能通过 skip 记录跳过它的 QA 阶段。
6
+
7
+ ### 1. 声明类型第一次被改动内容佐证(`f7de7828`)
8
+
9
+ 前置表由 rid 的**声明类型**选择,而没有任何东西检查类型与 diff 是否一致——一个标成 `chore` 的请求可以改运行时代码并通过提交闸。现在 `docs`/`chore`/`config` 的请求若触及 `src/**` 或 `packages/<name>/src/**`,会在 `rd:implemented`、`rd:qa-handoff` 和 `rd:handed-off` 被拒绝;工具链路径(`scripts/`、`tests/`、`.husky/`、配置、lockfile)不受影响。规则与 file-size 棘轮**共用一次 git 枚举**(`-z` + `--relative`),非 ASCII 路径不能借 C-quote 逃过 `src/` 判定。**原建议"把 `checkTypeSanity` 接到提交腿"被测量否决**:它对 `chore` 只与纯 lockfile 一致,会拒掉本仓库自己的基础设施切片;提交腿也没有 rid↔commit 绑定。
10
+
11
+ **这个切片被它自己的规则抓住了**:它声明 `chore` 却改 `src/`,于是重定向为 `refactor`,走完 handoff / code review / security / perf / QA 的完整证据链,而不是给自己开豁免。perf 在 `qa-handoff`/`handed-off` 记了一个 `block`(+2 次 git spawn,约 126 ms 一次性),为关闭"`implemented` 之后再加 `src/` 变更"的窗口而**显式豁免并记录**。
12
+
13
+ ### 2. skip 允许列表从 QA-free 类型派生(`98614528`)
14
+
15
+ `SKIPPABLE_TYPES` 此前是手写列表 `['docs','config','chore']`,而 `typeRequiresQaPhase('config')` 为 **true**——一条本地 skip 记录可以跳过 config 本来要求的 `SECURITY_REVIEW` 与 `TEST_REPORT`。现在 `QA_FREE_TYPES = VALID_REQUEST_TYPES.filter(t => !typeRequiresQaPhase(t))`,允许列表就是它(今天 `docs` + `chore`),`config` 退出。读路径还拒绝写入侧不可能产生的记录:空 reason、空/未 trim/含控制字符的 gate 名(C0/DEL/C1)、控制字符字段;坏记录读成 `null`,闸照常执行。署名行改成 **"record says applied by …"**——它是自述,不是证明。
16
+
17
+ ### 3. 配置路径的 reader 不再在复合 diff 里消失(`43f3cc51`)
18
+
19
+ 分类器只看映射决定网:一个不映射到任何测试的路径既不触发全量回退,也不扩大子集。`.gitignore + src/` 因此会跳过读根 `.gitignore` 的 `tests/unit/workspace/top-level-change-id-guard.test.ts`——用线上分类器扫全部 2246 个非空提交,**9 个提交就是这个复合形状**。落地的是一条**声明映射**(`.gitignore`、`pnpm-workspace.yaml`)+ `/^\.gitattributes$/` 全量触发器(它没有根 reader,记下的映射指向的测试只把键写在注释里)。arm 要求一行非注释代码同时命名键、带读/join 调用、绑定 `REPO_ROOT`、且不带写调用;红控包括注释-only、临时根读取、写操作和缺失的 reader。
20
+
21
+ ### 4. 两个"把崩溃/竞态读成通过"的修复(`988c6197`、`1cba9312`)
22
+
23
+ - **format 棘轮把 prettier 崩溃读成干净树**:`typeof '' === 'string'` 让 exit 1 + 空 stdout 返回 `''`,腿打印 `0 unformatted file(s)` + held。现在只有 prettier **确实列出**了文件才返回列表。
24
+ - **树扫描器在文件消失时杀死整个测试文件**:`ENOENT` 发生在枚举与读取之间,而扫描在模块作用域运行,失败是 `(0 tests)`。现在只容忍 `ENOENT`,并报告 `listed/read/vanished`,缺口可见而不是被吞掉。
25
+
26
+ ### 5. 其余已落地
27
+
28
+ - **A–F sweep 的闸改进**:`.github/` 与 `.husky/` 成为全量触发器(`af8f8053`);`GATE_GUARD_SUITES` 的根层按规则并入每个子集(`27a85b7f`);`src/` 的每一段都映射到 `tests/unit/<area>`,130 个孤儿测试降到 6 个且逐个记录(`7fa29669`);类型表决定 QA 相位(`d62eda51`)。
29
+ - **CI 与门禁**:覆盖率地板成为 CI 可执行的棘轮(`87b76fa3`);coverage 地板测量它记录的人口(`b1c5c89e`);一个要求 100% 且无人调用的门被移除(`888fb3e9`)。
30
+ - **CLI**:`peaks scan best-practice` 可以真正查阅文档(`195f573b`);VM isolation 表面(从未运行)被移除(`0172d89f`);路径守卫判断目录本身而不是调用者的拼写(`82c6f384`)。
31
+
32
+ ### 已知残余(记录,不粉饰)
33
+
34
+ - ③c 的反向不可发现性(未在映射中的 reader)、tooling 路径的误标、skip 记录 provenance 不可验证。
35
+ - 13 个 A–F 的 RD 工件停在 `implemented`——**grandfathered**;现在回溯关闭会触发 ③c。
36
+ - ③c 的 perf `block` 已显式豁免;③b 的安全/文档 LOW 已记录。
37
+ - 4 个 workspace 包随根版本各 +1 patch(internal-runtime 0.0.46、mut 0.1.60、shared 0.0.95、shared-channel 0.0.63),`CLI_VERSION` 与 `RUNTIME_VERSION` 由 `scripts/sync-version.mjs` 同步。
38
+
39
+ ## 4.1.5 — 2026-10-14 (快车道从设计走到落地并带来一个新命令族;代码门与提交禁令第一次真的会拒绝;提交边界补齐三道门;派发提示第一次被自己的 CLI 校验;artifact 按 rid 落盘,两条切片停止互相覆写)
40
+
41
+ **版本级别**: 未发布区间 `v4.1.4..HEAD` 共 **125 个 commit**(**13 feat / 37 fix / 2 refactor / 5 chore / 3 test / 3 style** / 其余 62 docs+memory)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。
42
+
43
+ **此处必须如实记一笔,与 4.1.3 面对 `peaks mcp` 时是同一情形**:本版**确实新增了命令族**——`peaks race`(`pilot-status` 只读判定与 `pilot-gate record` 唯一写入者两个动词,`src/cli/commands/race-commands.ts`)与 `request retag`(`src/cli/commands/request-retag-command.ts`)。按严格语义化版本,新增用户可见命令应当取 **minor**。取 patch 是常设规则的默认,不是"没有新增命令"。4 个 workspace 包各 +1 patch(internal-runtime 0.0.44→**0.0.45**、mut 0.1.58→**0.1.59**、shared 0.0.93→**0.0.94**、shared-channel 0.0.61→**0.0.62**),`CLI_VERSION` 与 `RUNTIME_VERSION` 由 `scripts/sync-version.mjs` 同步。
44
+
45
+ ### 1. 快车道:从一份设计到一条真能开门的路径
46
+
47
+ `peaks-race-code` 是本版的核心新能力。它的设计先被写死、再被对抗性评审推翻重写过一次(`9da13bc0` 的设计记录、`304e4e2e` 评审后的重写、`8d3f2896` 拆成四个 slice),落地时 `9bad2be1` 把它交付为 `peaks-code` 的**兄弟**而不是模式——它去掉的正是让 peaks-code 开独立上下文窗口的那条红线:在这个车道里,编排的窗口同时就是改源码的窗口。技能树因此从 22 走到 **23**(14 个顶层 + 9 个 bee 级,`tests/unit/ide/` 的三条计数断言随之更新)。门槛只有一个事实:为会话解析出的 driver 读到 `peaks-race-code`,而这个事实是**自报的**,文档自己也这么说。
48
+
49
+ **但代码门此前在这条路径上是死的,这是本版最该被读到的一段。** `401b44f7` 之前 `peaks code-gate` 按 `tool` / `input` 读工具调用,而真实的 PreToolUse 投递的是 `tool_name` / `tool_input`;工具名到达时是 `undefined`,而 `decideGateAction` 的第一个判断放行任何不叫 Edit / Write / MultiEdit 的名字——**在读路径之前**,于是它对每一次调用都返回 allow。修法在命令层归一化顶层载荷,接受两种拼写(与既有 shell sibling `pre-tool-code-gate.sh` 一致),`GateInput` 与 `decideGateAction` 不动。
50
+
51
+ **这是一次会到达每一个既有安装的行为变更,故明写**:注册了 code-gate 条目的仓库会从"这门从不拒绝"变成"按路径族拒绝"——对 `src/`、`tests/unit/`、`tests/integration/`、`config/`、`bin/`、`scripts/` 的直接 Edit / Write / MultiEdit 会被 `PEAKS_CODE_PROHIBITED_DIRECT_EDIT` 拒绝,除非解析出的 driver 是快车道。用户没有理由预期这件事,因为这条条目**从未拒绝过一次调用**,它的第一次拒绝会是一次普通的 `src/**` 编辑。
52
+
53
+ 放行必须精确。`adff480b` 只认**精确匹配** `peaks-race-code`,无前缀匹配也不做大小写折叠,于是一个未来的 `peaks-race-<something>` 兄弟不会继承源码编辑权——顺带把这条钉死的是 `938b92a1`:唯一的负例 `peaks-code` 在 `startsWith('peaks-race')`、大小写折叠、`trim`/`contains` 三种放宽下**全都仍然通过**,所以四条新负例各对一种放宽。`f5612cde` 从 hook payload 读 caller identity(`caller_id`,回退 `session_id`),把 lease 查询**限定在该 caller**,再交给 `decideGateAction` 的第三个参数。
54
+
55
+ **提交禁令(AI 署名红线)有三处只存在于代码里的事实。** 它只有一个调用点,且只在 `peaks hook handle` 下运行——即 trae / cursor / codex;Claude Code、hermes 与 openclaw 拿到的是 `gate enforce`,其中**不含**禁令。它此前能被任意字符串解除:`79b20add` 证实任何带 `session_id: "anything"` 的载荷都会让一个本该被拒的提交通过,因为判别说的是"载荷里有没有非空字符串"而不是"那个字符串有没有指到一个 lease";`a8f94c89` 证实什么都没解析出来时,`if (skill !== null)` 会让整条禁令跳过自己。`023235e2` 补上最后一块:`callerId` 过滤器一直有效,但**没有任何生产调用点传它**,于是"谁在驱动"由 `readdirSync` 第一个产出回答——一个没有 peaks 技能的会话的 `git commit` 会被另一个窗口的 peaks-code lease 禁掉。而 `0c08be62` 让 driver 解析器与 statusline 读者对同一份 lease 集合给出同一答案(按 `lastHeartbeat` 再按 `startedAt` 的共享 comparator);此前它取 `readdirSync` 的第一个,在 Windows 上就是文件名顺序。
56
+
57
+ ### 2. gate 2 从"没有阈值"变成有策略的判定;车道相位搬进一个有语法的载体
58
+
59
+ `peaks-race-code` 的 pilot 信任门原先有四个可数量、零个阈值,于是"pilot 清关了吗"无法可复现地回答。`21304696` 补上 `src/services/race/gate2-policy.ts`、`gate2-evaluator.ts`、`pilot-gate-store.ts` 与两个动词:`peaks race pilot-status`(只读判定,fail 时 exit 1)与 `peaks race pilot-gate record`(唯一写入者,幂等 upsert)。策略 `race-gate2-policy-v1` 有七条阈值,其中 `taskCount >= 10` 取 rule-of-three(十次干净跑把失败率上界锁在约 26%);安全臂计入**全部**记录(含 escalated)而 `taskCount` 只计 landed,这条不对称是刻意的。覆盖面是**推导出来的**,永不自报:`filesChanged × HARD_BLOCKED_PATH_FAMILIES`(从 `src/services/hooks/pre-tool-code-gate.ts` import),或安全臂谓词。判定永远从策略常量重算,**从不**读 `.peaks/race/pilot-gate.json` 自己的 policy 块——否则削弱那个块就能洗白这道门。用五条真实的 2026-10-11 trace 播种,得到 `insufficient-evidence` 与两个缺口:**task 4 < 10、session 1 < 2**(core 3 与 safetyArm 1 达标)。
60
+
61
+ **车道相位从 markdown 搬进一个有语法的载体。** 相位此前是 `skills/peaks-audit/SKILL.md` 里的一句话加一个 HTML 注释标记;markdown 是自由文本,于是每一条"必须长得像 X"的守卫都能被一个人类仍读作相位声明的拼写变体绕开——**五轮修复产生了五种逃逸**(一行两个 token、一行两个 `phase=`、多一个空格、少一个空格、tab、NBSP、大写、缺前缀),没有一轮是最后一轮,而守卫已到 500 行帽的 495 行。`3b95e00a` 把它搬到 `.peaks/race/lane-phase.json`(`{ "phase": "name-only" }`),`src/services/race/lane-phase.ts` 是唯一读者:严格的 Zod 对象、恰好两个值的 enum、以及一个带标签的结果(ok / missing / invalid),**missing 拒绝而不是取默认**。**第一版没有做到这件事,记录如此**:JSON 的键可以用 unicode 转义书写,而 `JSON.parse` 会把转义解析回键名 `phase`,于是一个首条声明被转义的文件返回 ok 并采用**第二个**值——原始文本读者看到的是一个相位,守卫解析出的是另一个,而一条非法的首条声明被静默丢弃。修法是拒绝任何反斜杠。QA 对八条验收判据全部 PASS,含 80+ 条对抗输入(键与值里的 unicode 转义、任何位置的重复键、三个位置的 BOM、NUL、孤立代理、CRLF、NEL、一个 4 MB 的填充对象、载体路径上放目录与符号链接,以及为数组 / 字符串 / 数字 / null 的 root)。
62
+
63
+ `76830652` 把车道问题放到**每一次 peaks 工作流的入口**:一个以"端到端做这个"表述的诉求直达 peaks-code,所以住在 dispatcher 里的问题永远不会被问到。问题落在 peaks-audit 的契约处(任何 peaks-* 工作流的第一步),每个请求问一次;快车道是 pre-pilot,所以在 pilot 清关前它**只在用户点名时**可达。
64
+
65
+ ### 3. 提交边界上新增的三道门
66
+
67
+ CI 结构性地看不到这三样东西:artifact 住在 `.peaks/_runtime/`,那是 gitignored,所以**本地提交是它们唯一可见的边界**。
68
+
69
+ **artifact 契约在提交处被强制执行(`4a5d74b4`)。** 本仓此前对同一份工作有三种做法,按"artifact 的 state 值对该 role 是否合法"衡量:完整状态机(2026-09-10)、混合——33 条规范 state 行加 6 条手写、CLI 会拒绝的名字(2026-10-09)、以及完全没有(2026-10-11,零条 state 行)。**绕过的形式是模仿,不是拒绝。** 检查器早就存在(`peaks workflow verify-pipeline` 在 2026-10-11 那次会话上正确报 `complete:false / gateC:fail`),**只是没有任何东西运行它**。新增 `.husky/peaks-gate-pipeline.mjs`(pre-commit 腿)与 `.husky/pipeline/contract-verdict.mjs`(纯判定路径:无 fs、无 spawn、无时钟)。豁免是 `PEAKS_SKIP_PIPELINE_VERIFY=1` 且**大声**:它逐条列出跳过的 rid、说明读过的范围、并声明环境变量在 git 历史里不留痕——不像 `--allow-incomplete`,它的理由留在 artifact 里。**跑不起来的检查器一律拒绝**:一条崩溃的检查器不是"没有违规"。rid 枚举改按 **artifact** 键控而不是按 `rid-` 前缀,两个方向的错误在真实会话上量过:2026-10-11 是 8→4,2026-10-10 是 0→18。文件里也写明它**不是**完全强制:这条腿放行 `MUT_REPORT`,而它的 artifact 在这个构建里没有生产者。
70
+
71
+ **这条腿会验证一个有工作的会话,而不是它被绑定到的那个(`f9091db3`)。** 此前它解析 ACTIVE 会话并枚举该会话的 rid 载体;当 active 会话是新的、而工作属于另一个会话时,枚举为空,这条腿便以"no rid to verify … Nothing was refused"放行——那句话是真的,而检查从未运行。实测:job backlog-9x-drain 的最后一条切片从会话 `…-3cb9bc` 提交,而它全部六个 rid 载体住在 `…-2f9323` 下。**显然的修法(绑定会话为空而兄弟非空时拒绝)被量过后否决**:11 个会话目录里 6 个零 rid 载体,其中三个是当天建立的,拒绝会挡住那六个会话的每一次 docs / chore / memory 提交。落地的形状是验证**正确**的那个会话,而不是拒绝。`15def424` 收掉它留下的三条:平局判定从 `>=` 改成 `carrier mtime → session id` 的全序 `better()`(QA 把三个兄弟的所有六种排列都跑过,修复后收敛到**一个**目标,HEAD 下有**三个**);不可读的兄弟从静默丢弃改为**被点名**(审计者量到:40 棵指向这条路径的树里,HEAD 在 15 棵上打印 "0 NOT verified" 而确实丢了一个会话);注释里那串"87 + 47 + 19 + 18 + 14 rids"被删掉——它们是 request **文件**计数,真实枚举是 6 个载体会话上的 65 个 rid。
72
+
73
+ **staged 与 worktree 的分歧被抓住(`23d5de3d`)。** `git commit` 交付的是 INDEX,而本仓每一个测试、门和评审读的都是 WORKING TREE。两者分歧时"被验证的字节"和"被提交的字节"不是同一份,而没有东西说出来——一个会话里真实触发过两次:一轮修复编辑了受tracked 文件却没重新 `git add`,于是 STAGED 侧是修复前的弱守卫(22 例 / 16004 B)而 worktree 是 28 / 24168 B。比较**经过 git 的 filter**:staged 侧是 index blob,worktree 侧是 `git hash-object`。第一版直接比原始字节,在 `core.autocrlf=true`(本仓如此)下会把 git 判定为同步的文件拒绝,而且打印出的补救(`git add`)是可证明的空操作——**这是提交门唯一绝不能有的结局:它教人用 `--no-verify`**。不可比较的路径(gitlink、符号链接、未合并、不可读)一律拒绝。
74
+
75
+ **提交路径开始量 staged 文件尺寸(`8caa1901`)。** 在此之前 `node .husky/peaks-gate.mjs staged <over-cap file>` 对任何文件都打印 `NOTHING WAS COMPARED (staged) … every one of them is OUTSIDE the lint scope` 并 **exit 0**——337 行的测试文件和 600 行的一样,而 `peaks scan file-size` 与 transition 路径会拒绝同一个文件并给出 delta。新腿挂在门的 `all` scope 上而不是 lint-scoped 的 `files` 上,因为 `tests/**` 在 LINT scope 之外、却在 file-size 政策之内——挂在 `files` 上的腿会漏掉缺陷正是在其上被量到的那个文件;它跑在 empty-change-set 分支**之前**,因为那个分支正是本缺陷的签名。`scripts/lint/file-size-delta.ts` 调用 `scanFileSize`,与 `peaks scan file-size` 用的是**同一个**实现,新模块自己不含任何阈值、也没有"长大了"这个概念。**只有增长被拒绝**:已经超帽但没长大的文件保持绿,创建是另一个分支。
76
+
77
+ ### 4. 既有的几条判据被改成会失败
78
+
79
+ **尺寸判定按 delta 而不是绝对值(`435445dd`)。** `rd -> implemented` 的尺寸门扫描 `getChangedFiles` 并拒绝**任何**超帽的改动文件,而基线把 `fileSizeOverCap` **78** 当作可接受量棘轮着——同一个机制一边容忍 78 个超帽文件,一边不许任何切片碰其中一个。连续复现两次;第二次一个 767 行的文件因为改了 **2 行描述**被拒,两次会话都退回了 `--allow-incomplete`——那正是 artifact 契约存在来让它多余的旁路。状态机也开始强制它自己描述的顺序:`rd: draft -> handed-off` 此前能通过,而 `implemented` 与 `qa-handoff` 都被拒,于是一条切片可以越过每一道中间门宣称自己已交付。
80
+
81
+ **软通过的前提被真的报出来(`3059ac27`)。** 门为每一个缺失文件的 backCompat 前提构造一个 `warnings` 数组且不动 `missing`,于是 `ok` 保持 true——而调用方只在它自己的 `throw` 里读 `prerequisiteResult.warnings`。那个词在文件里只出现一次,就在那一行,所以成功路径上这个数组被构造、填满、一帧之后丢弃:一个软通过了两条前提的 transition 因此报 `warnings: []`,读者会断定每一条前提都通过了。实测:`data.prerequisiteWarnings: undefined` 与 `envelope.warnings: []` 变成了 **2 和 2**。顺带修掉一处"不会失败的门"——警告码是硬编码的字面量、指着 mut-report,却为**每一条** backCompat 前提发出,于是 third-party-review 前提被报在 mut-report 的码下面,而任何按那个码过滤 MUT_REPORT 问题的东西都会一并匹配到它。
82
+
83
+ **eslint 的行改成说出它们容忍什么(`d3684dbc`)。** `eslintFindings` 是一个**计数**的上界,而计数的上界意味着没有任何单条 finding 能迫使行动:ESM `require()` 家族的 16 个 error 级站点一直被报出来,却落在一个 1727 的计数里——约等于零。行现在是"包含 + 按量不增长",建立在 census 既有的 per-file map 上:1270 个文件里 478 个容忍 finding、792 个为零,artifact 精确复现 ceiling(**行之和 = 1727 findings / 573 errors**)。**提交路径调用同一条规则**,于是新实例在贡献者遇到它的地方**按名字**变红:
84
+
85
+ ```
86
+ count form: eslint findings (derived) 1 (ceiling 1) -> green, silent
87
+ table form: src/tidy.ts went from 0 to 1 lint finding(s) (+1) -> exit 1
88
+ ```
89
+
90
+ 一条关键情形也成立:对受容忍文件的**无关改动**在提交路径上保持绿——因为会拦住无辜提交的门正是教人用 `--no-verify` 的那一扇。这个切片交了六条 finding,最该记的一条是它自己赖以成立的理由**是假的,且来自编排者**:声称 eslint-disable 注释点名的 `no-var-requires` "在 ESLint v8 里不存在",实测 `@typescript-eslint/eslint-plugin` **8.66.0 定义了它**(`deprecatedSince` 8.0.0,`replacedBy` `no-require-imports`),而一条被弃用的规则**仍然会报**。真缺陷是"被抑制的规则"和"在报的规则"**不匹配**——一个更有意思的失败,被那个更弱的故事挤掉了。
91
+
92
+ **把每一个 `require()` 扫出源码,并防止它回来(`c3fe88b7`)。** 本仓每个 `package.json` 都声明 `"type": "module"`,所以 `require` 在运行时不存在。十六处分布在十四个文件里:十五处躲在函数体里当"惰性" require,只在各自的冷路径上抛;一处(`scripts/fix-dispatcher.js`)在顶层,让那个文件无法加载。**没有任何东西能在模式上失败,这正是它累积起来的原因**:tsc 接受 ESM 文件里的 require;没有测试走过那些路径;四处带着 `eslint-disable-next-line @typescript-eslint/no-var-requires`——一条**没有启用**的规则,而真正的拼写 `no-require-imports` 本来就在那些站点上报错,于是这些指令什么都没抑制。实测 before → after:`peaks loop run` 在干净会话上 `RUN_FAILED "require is not defined"` → exit 0 `RUN_OK`;`peaks security-audit run` 不带 `globalThis` shim 从 exit 1、只留一个 `.tmp` → exit 0、`.md` 落盘。新守卫 `tests/unit/standards/no-esm-require-mixing.test.ts` 目标为零、无 allowlist,其判别性对照是一个被转换文件**逐字的前修内容**——一条不可能失败的对照不是对照。
93
+
94
+ **一个名字可以给一行做键,不能判定一行(`e8e916e6`)。** 同一缺陷类的三个活实例,每一个都由测量而非检视确立:`pilot-gate-store` 拒绝任何不以 `rid-` 开头的 rid,而 `.peaks/_runtime/*/rd/requests/` 下 97 个不同 id 里有 **58 个**没有前缀——守卫在拒绝本仓实际铸造的多数 id;`type-sanity-service` 用 `/\b(?:tests?|…)\b/` 判断"这是不是测试文件",而词边界可以被 `-` 满足,于是 `src/services/test-cache/test-cache-service.ts` 被判成测试(在 `git ls-files` 上重测:3064 条 tracked 路径,**恰好 29 条判定改变**,全部单向——18 条变 `source`、11 条变 `unknown`);`context/collector` 把 `relative(root, full)`——在 win32 上以 `\` 分隔——喂给一个测试 `/__tests__/` 的分类器,于是那个分支在它被写成的平台上**永远不可能匹配**,而规范化的值就在四行之上已经算好了。
95
+
96
+ ### 5. 派发:提示词第一次被自己的 CLI 校验
97
+
98
+ 编排者手写一份共享 brief 交给一个 campaign 里的每个子代理,**没有任何东西校验它**,而它在一次会话里三次携带关于本仓 CLI 自身的假陈述:一个错 flag、一条范围错误的必需项、一条挂在错 artifact 上的必需项。三条都是子代理读 artifact 时发现的,**没有一条是门发现的**——这是工作流里唯一没有测试读过的 artifact。
99
+
100
+ `9894eab0` 加了检查器:从提示里抽出 `peaks …` 调用,对**注册的命令树**解析,报出被解析出的命令或它的祖先没有声明的 flag。解析来自 CLI 自己,永不来自一份名单。它**警告而不拒绝**,决定的数字是真实语料上的假阳性计数:本会话 **147 条派发记录、1772 次调用、176 条未声明 flag**,其中**恰好一条**是假阳性——一份正确的 brief 在一个记录该缺陷的表格里**引用了**那条错误命令。`--rid` 是整个语料里唯一的未声明 flag:147 次出现在被注入的一行上,29 次出现在手写的一行上——**第二组是真的,这正是本片的意义**。审查者给的二次输入关闭了一个真缺陷:一次每匹配都走到文末的扫描在 `composeDispatchPrompt` 里对一份 3.5 MB 提示耗时 **109.9 s**,按 run 上限定界后同一输入是 **98.6 ms**。
101
+
102
+ `f9ecb6fd` 把被注入的那一行修对:`L1_WORKTREE_GOVERNANCE_BLOCK` 里的两条 worktree 命令**都跑不起来**——`peaks worktree auth grant --rid … --reason … --ttl <5m>` 三处都错(没有 `--rid` 这个 flag,它是可选的 `--request-id`;必需的 `--operation` 被省略;`--ttl` 的单位是毫秒,`<5m>` 不是合法值形式),逐一逐字运行两者都答 `error: required option … not specified`。修完的守卫是重点:第一版只查 flag 是否存在、必需项是否出现、拼写是否声明过——评审证明它**看不见它刚刚移除的缺陷**:把 `--ttl 5m` 重新加回全部五个表面,它 8/8 全绿,而 CLI 接受那一行并写下一份 **5 毫秒** TTL 的 grant。它现在是逐次出现的形状走查,把每个选项对回注册声明,断言块里点名的字面值是声明 enum 的成员,并把未被消费的 token 当作游离操作数。
103
+
104
+ `b7056cdb` 让生产者知道它将被按什么评判:前提表靠字面量字符串判定 artifact 是否存在,而派发提示从不点名它们——于是做了工作的生产者被一个它从未被展示过的谓词拒绝,唯一出路是事后编辑别人的证据。实测:四个有真实内容、判定正确、证据可量的 artifact 因四条违规被拒,**每一条都是缺失的字面标题而非缺失的事实**。块从表里**生成**,永不从表里**转录**:改表会移动这个块,移除 surfacing 会让套件点名那个缺失的标记而变红。
105
+
106
+ ### 6. artifact 按 rid 落盘,两条切片停止互相覆写
107
+
108
+ 一个会话里两条同类型切片写同一个路径,第二条覆写第一条,**而两条 transition 都通过**——第二条切片被另一份 diff 的审查判定,artifact 和门里都没有任何东西说出来。本版把三类 artifact 改成按 rid:
109
+
110
+ - `BUG_ANALYSIS`(`6a394084`):`rd/bug-analysis.md` → 带 `<rid>` 占位符,`legacyRelativePath` 兜底,磁盘上已有的会话继续解析;`AUDIT_SECURITY` / `AUDIT_PERF` / `KARPATHY_REVIEW` 早已是这个形状。磁盘上实测:三个会话 95 份 request artifact 里,**每个会话恰好一份** `bug-analysis.md`。后果是**观察到的而不是推断的**:一个在修显然是 bugfix 的 RD 报称自己选了 `refactor`,因为那个文件"已经装着另一条切片的分析"——而声明一个自己不是的类型会选中**另一张**前提表,于是结构性碰撞转化为一条静默更轻的门。把表项回退,13 个用例里 9 个变红。
111
+ - `SECURITY_REVIEW`(`47863518`):`rd/security-review.md` 是同一碰撞里**硬且静默**的那个实例,它不声明 `mustContain`。七处读者分布于五个服务,八份 `skills/**` 文档一并跟过来。两轮 QA 修复各有产出:第一轮证伪了一条证据表断言(`workflow-gates-and-types.md:109` 不在 diff 里却仍然断言那个性质),第二轮证伪了清扫自己的完备性断言——模式以 artifact **名字**和 token "rid" 为键,而真正要紧的 `v2-12-fanout-collapse.md:12/:15` 把 `audit/security.md` 与 `audit/perf.md` 当作当前的写目标呈现,其中 `rid` 出现 **0 次**。所以第二轮不再清扫,而是落地 `tests/unit/services/artifacts/legacy-path-doc-contract.test.ts`:从前提表**推导**被降级的词干(七个名字,没有喂给扫描的字面名单),它的红跑取在真实的修复前文本上,1 failed / 15 passed,恰好点名那三处。
112
+ - `final-review` 消费的 rid 作用域证据路径(`ebb07c61`):门接受的 artifact 路径**其消费者从不读**——`peaks prepare-final-review` 从 `rd/code-review.md`、`rd/security-review.md` 拼装证据,而 transition 门与写侧统一在 `rd/code-review-<rid>.md` 与 `audit/security-<rid>.md`;写对了 rid 作用域路径的切片,其 no-new-bugs 维度仍然回到 `inconclusive`,评审报 `rd-code-review` ENOENT。
113
+
114
+ `0da35578` 把一条**写了却没人读**的声明变成会被读:`backCompatUntil` 落在两行前提上(`mut/mut-report.json` 在 v2.14.0、`rd/third-party-review.md` 在 v2.15.0)而没有任何东西读它,安装版本是 4.1.4,于是两个窗口都过期了约二十个 minor release,没有任何用户可见的输出把它们与按时的窗口区分开。软通过警告现在带一个附加的 `expiredWindow` 字段,拒绝打印机与成功打印机都渲染它。实测一次真实的 `rd -> qa-handoff`:两条软通过分别报 `v2.15.0 (installed 4.1.4)` 与 `v2.14.0 (installed 4.1.4)`,各带一句 "past expiry"。**它只观察**:一条 OPEN 窗口和一条**早于**窗口的构建都渲染不出这个从句,缺失前提仍然给 `ok: true`,`path`/`code`/`message` 逐字节不变。
115
+
116
+ `21016bbf` 让一条切片**声明它判定了什么**,而检查读那份声明(backlog 9.9 的第四次尝试):三次尝试都被建起来又撤回,因为此前没有机器可读的"这条切片动了什么",每个机制只能去**推断**,而每一种推断在本仓日常生成的输入上都是错的——从 git 状态推断会让干净树上的审计永久空转,从散文 `## Red-line scope` 解析会拒掉 15 份真实请求里的 14 份。现在 `security-audit run --judged <paths...>` 记录每条路径的内容哈希,`rd:qa-handoff` 重新哈希它们并拒绝,点名 artifact 与第一条移动的路径。
117
+
118
+ ### 7. 其余修复
119
+
120
+ - **`peaks workspace init` 把本仓自己的开发 hook 注册进下游项目(`09f8d043`)。** 模板用 `bash "${CLAUDE_PROJECT_DIR}/src/services/hooks/<script>.sh"` 展开两条 hook,而 `${CLAUDE_PROJECT_DIR}` 解析到**消费者**的项目根,脚本在本仓的 `src/` 里,`package.json#files` 也不发 `src/**`——于是每个下游项目都拿到两条无法解析的 Bash PreToolUse 条目。修法是 `TEMPLATE_VERSION` 1.9.0 → **1.10.0** 并把这些条目注册进本仓**被 tracked** 的 `.claude/settings.json`,fresh clone 才真的能拿到它们。这次搬迁又打断第二条门:反馈提升检查的 layer B 只读 `peaks workspace init` **生成**的那份快照,快照刷新后两条真的被提升的规则会被报成未提升——一个假阴性,因为强制**搬了家而不是消失了**。
121
+ - **仪表盘数了三类计数,而没有任何东西发出它们(`e6bcc39e`)。** `peaks dashboard summary` 报 `cycleCount` / `tokenCount` / `monotonicTriggerCount`,而它们的唯一生产者是三个**没有调用点**的 helper——三个计数按构造为零。实测 `{"cycleCount":0,"tokenCount":0,"dispatchCount":3,"compactCount":0,"monotonicTriggerCount":0}`:`dispatchCount` 非零,另外三个结构性地死。这类计数此前通过的验收是 `AC-F1: PASS - observability-service.ts exports 4 new emit helpers`——它测的是**导出**而不是**发出**,于是每个类别都未接线地发了出去。
122
+ - **`peaks memory extract` 报了一个它没有写下的数字(`97bb5e5c`)。** 一个 5 块的 capsule 给出 `extractedCount: 5`、`plannedWrites: 5`、`warnings: []` 而磁盘上只有**四个**文件:一个纯 CJK 标题被 slugify 成空,回退到通用的 `project-memory.md`,与一条已 tracked 的条目碰撞,于是那次写入被静默跳过。第一版修复**本身是一次回归**,由评审发现:派生名用十六进制、每字节两个字符,一个长标题产生 287 字符的文件名、ENOENT,并让**整个批次**中止。
123
+ - **`peaks request retag`,以及"默认类型"不再无声(`97bb5e5c`)。** 一个 hand-written artifact 的 request type 此前静默地就是默认的 `feature`——`rd:qa-handoff` 要求最多的那个类型。它现在在 `request show` 里同时以字段和警告的形式可读为 `declared` 或 `default`;`--type` 缺席时 `init` 不写 type 行,于是默认值永不被盖在那个区分之上;`retag` 负责改它,并且**往 artifact 里追加自己的注记**——那个唯一能改门禁适用表的操作不再不可见。`getPrerequisitesFor` 的默认值被删除,它的第三个参数现在是必需的。
124
+ - **四条只有散文在强制的义务有了执行者(`fae227a1`),每一条都先在野外被量到失败。** 强制的 Karpathy 块此前没有执行者,而 2026-10-12 的四份 RD 提示**全都不含它**(派发路径现在自己追加:一份已经带了它的草稿 14029 → 12055 字节,正好是 2 字节分隔符加 1758 字节的块);派发账本的回收器没有调用者(每个会话的每条记录都是 `queued`,39/39、2/2、9/9、23/23——终结动词在数字是 13 时写就,到 73 时已无人调用);一个看不见文件的扫描会报绿(`peaks-gate.mjs repo` 走 `git ls-files`,所以 `3b95e00a` 加进一个没有基线行的模块后门从那次提交起就是红的);审计拒绝点名了错误的路障(两个 CLI 都以 `handoff-missing` 拒绝而不说信封**已经通过**校验,于是四个独立审查者每人做完全部工作却无法落地)。
125
+ - **`peaks code lint` 的 `execution-failed` 不再把四件事说成一件(`adf63e1e`)**:不可构建的参数表、失败的 spawn、被杀的子进程、无法解析的 linter 输出,共用一个状态码且一个都不点名,而 hint 无论实际发生了什么都说 "restore the ESLint toolchain"——一个工具链好好的操作员被指去重建它。现在 `reason` 从 runner 带进消息,每个条件一个。
126
+ - **CI 的 capability 基线门现在说出**哪个**探针失败了(`adb3c67c`)。** 4.1.4 的发布在 `gate-capability-baseline` 上失败,CI 只给一行 `verdict=drifted degraded=false failing=[J03]`——J03 有六个探针,六个条件压缩成一个词。细节其实一直都在:`capability-audit-service/runner.ts` 从写下那天起就把失败契约的 `diff.reason` 放进 `dimensions[].evidence[].summary`,而工作流的内联脚本只读 `journeyId` 就把它丢了。测试**不读**工作流,而是**执行**它。
127
+ - **工具在说假话的那些散文(`48861a11`、`e84ef33e`、`cdbef65d`、`c0554c7a`、`f3a3c969`、`17183c8c`、`e4030eb1`)。** 一整族 fix 都在改**散文而不是代码**,因为代码是对的而承诺超了:`skills/peaks-race-code/SKILL.md` 引用了一份 `docs/` 下的设计记录,而 `docs/` 不在 `package.json#files` 里、安装器只拷贝技能目录,所以那条引用对每个消费者都是死的(引用守卫按仓根解析,对"是否会被发布"是盲的);快车道规范说"没有第二份拷贝能通过套件",而测试只查一个文件、两条陈述里的一条——**一条强于代码的断言,写在正是为阻止它而存在的规范里**;一趟以 `vitest … | head` 为模式、走全文匹配的 hook 拒绝了一条搜索模式为 `vitest` 的 `grep`,而本仓**自己规定**的命令 `timeout 300 pnpm vitest run 2>&1 | tail -100`(就写在 "If the exit code is 0, tests passed" 旁边)反而因为 `timeout` 起头而不受保护——被改的是文档,不是匹配器。
128
+
129
+ ### 8. 记录与记忆(62 docs + 3 test + 3 style + 2 chore)
130
+
131
+ 绝大多数 docs commit 是 backlog 与 memory 的沉淀,但它们记录的是本版反复撞上的同一类缺陷:**标题是一个断言,而没有东西检查它。** 实测:§9 的四条决定项**都已由用户裁定**,其中三条**已经实现**(9.1 在 `3b95e00a`、9.2 的裁定在 `3059ac27`、9.3 的两半在 `435445dd`、9.4 的前一半在 `d3684dbc`),而**每一条的标题都还写着 "needs the user's decision"**——信任标题的读者会重新实现已完成的工作(`80b14172`)。同一族里还有:一个以名字为键的清扫看不见由**位置**定义的类(真正要紧的文件里搜索键出现 **0 次**);一条被复制到四个载体里的错误理由(`9.4` 的 `no-var-requires` 故事,见 §4)在任何地方都不可校验,而其中一份是 sha256 锁定的、根本改不了。
132
+
133
+ `3 test` 与 `3 style` 里最该记的是**格式棘轮**:`b9b5ca69` 把 `node .husky/format-check-ratchet.mjs` 挪进 pre-push 并**放在最前**——理由不止是开销,而是该腿失败时的补救是 `pnpm format`,它会重写 tracked 源码,从而让另外两条腿作废。这正是一周 drift 一次浮出的地方:`2e8c8b6a` 面对的是**累积在主分支上的 61 个 commit**、两个未格式化文件落在允许集之外。两文件被判为**空白改动**的方式不是 `git diff -w`(prettier 在这里做的是**行重排**,`--ignore-whitespace` 无法规范化一个换行),而是把空白全部剥掉后与 HEAD **逐字节相同**(12309 字符 / sha256 `8759576b…`,9655 字符 / sha256 `ceccf1f1…`,修复前后一致)。`f50210ef` 把允许集从 12 个名字收缩到 **11** 个——**只减不增,这是这份棘轮唯一安全的方向**。
134
+
135
+ ### 9. 未验证(记录而非隐瞒)
136
+
137
+ - **快车道的 pilot 门判 `insufficient-evidence`,不是 pass**:五条真实 trace 给出两个缺口(task 4 < 10、session 1 < 2),所以快车道在 pilot 清关前**只在用户点名它时**可达。
138
+ - **第 3 节的三道门在 CI 上不可测**:artifact 住在 gitignored 的 `.peaks/_runtime/` 下,而这三条腿的存在理由正是"本地提交是它们唯一可见的边界"。
139
+ - **提交禁令(AI 署名红线)只在 trae / cursor / codex 上运行**。Claude Code、hermes、openclaw 拿到的是 `gate enforce`,其中不含禁令——所以这条红线在**这三个 harness 上仍然只有检测、没有执行**。
140
+ - **快车道完成的证明是自报的**,而强制的规范住在 `skills/peaks-code/references/fast-lane-norm.md`,在**任何车道里都没有执行者**;`src/services/hooks/` 下的 shell sibling 由一个全局作用域的安装拷贝、且**没有接线到任何东西**。
141
+ - **eslint 行表的键是名字,而名字不是身份**:一个文件被**重命名**到一个受容忍的名字上会洗白它的 findings,且无需任何重生成——旧路径离开被量过的 map、总量下降,那是一个被允许的方向。在 header 里连同探针一起写明,**未修**(身份追踪是另一次改动)。
142
+ - **`21016bbf` 的完备性不被强制**:一份声明是"关于它点名的路径"的断言,永远不是"那就是全部"(实测:磁盘上十个文件、声明一个,绿)。而该片还记录了一次代价——实现者为了追 `prettierUnformatted` ceiling 把一次 `prettier --write` 从自己拥有的文件扩大到两整棵树,重排了 65 个无关 fixture 和 6 个随包发布的模板;它们全部被回退。
143
+ - **尺寸 gate 的 subprocess 开销未优**:K 个超帽**改动**文件要 2+2K 次 git spawn,每次约 58 ms,已知的修法是单次 `cat-file --batch`——**未实现**,因为两个调用点都是每切片的人手命令,付 0.3–0.8 s。
144
+ - **本版记录的 ceiling 只降不升**,全部由受认可的生成器产出,nothing rose:
145
+
146
+ ```
147
+ eslintFindings 1760 -> 1722 fileSizeOverCap 78 -> 77
148
+ eslintErrors 590 -> 572 fileSizeExcessLines 22502 -> 22117
149
+ ```
150
+
3
151
  ## 4.1.4 — 2026-10-10 (修掉推送门上的一个假绿;`src/cli/commands` 清空超帽;两条"BLOCKING 却拦不住任何东西"的步骤;以及一项被推迟的边界)
4
152
 
5
153
  **版本级别**: 未发布区间 `v4.1.3..HEAD` 共 **17 个 commit**(1 feat / 5 fix / 6 refactor / 2 test / 其余 docs+memory)。取 **patch**,依维护者 2026-07-22 的常设规则"默认版本新增采用最小的版本位"。4 个 workspace 包各 +1 patch(internal-runtime 0.0.43→0.0.44、mut 0.1.57→0.1.58、shared 0.0.92→0.0.93、shared-channel 0.0.60→0.0.61),`CLI_VERSION` 与 `RUNTIME_VERSION` 由 `scripts/sync-version.mjs` 同步。**本版不新增命令族**,所以 4.1.3 那条"新增命令应取 minor"的注记不适用。
package/README-en.md CHANGED
@@ -9,7 +9,6 @@
9
9
  [![ci](https://img.shields.io/github/actions/workflow/status/SquabbyZ/peaks-loop/ci.yml?style=for-the-badge&logo=githubactions&logoColor=white&label=ci)](https://github.com/SquabbyZ/peaks-loop/actions/workflows/ci.yml)
10
10
  [![license](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](./LICENSE)
11
11
  [![node](https://img.shields.io/badge/node-%E2%89%A520-339933?style=for-the-badge&logo=node.js&logoColor=white)](https://www.npmjs.com/package/peaks-loop)
12
- [![tests](https://img.shields.io/badge/tests-285%2B%20cases%20%C3%97%204%20pkgs-22c55e?style=for-the-badge&logo=vitest&logoColor=white)](#status)
13
12
  [![stars](https://img.shields.io/github/stars/SquabbyZ/peaks-loop?style=for-the-badge&logo=github&github=github&logoColor=white)](https://github.com/SquabbyZ/peaks-loop/stargazers)
14
13
 
15
14
  **English** · [简体中文](./README.md)
@@ -24,22 +23,13 @@
24
23
 
25
24
  ## What it is
26
25
 
27
- peaks-loop is a **Loop Engineering crystallization system**, not a workflow tool — what sediments from the runs you do is **not** a procedure, it's a set of **Loop Engineering** method assets that are karpathy-engineered at the rule level and darwin-verified at the change level.
26
+ peaks-loop is an orchestration layer that sits on the AI coding tool you already use (**Claude Code** / **Z Code**). You send one slash command in the chat box and it runs the whole chain for you: split the work → run it gate by gate → **stop at the gate that breaks**.
28
27
 
29
- | Asset layer | Role | One-liner |
30
- | --- | --- | --- |
31
- | **Loop Engineering Asset** | Method system, first-class | Answers "why this loop exists, when it fires, what counts as success, how it improves" |
32
- | **Bee Asset** | Executable body, first-class | The runnable body of a Loop Engineering Asset — every bee in the swarm |
33
- | **Workflow Trace** | Evidence, **NOT** the durable product | Immutable per-run record; feeds crystallization + evaluation, not the user-facing asset |
34
- | **Evolution Evaluation** | Anti-drift gate, mandatory | Every improvement needs an independent-context scorer + a regression skeptic; keep only if it passes, otherwise revert |
35
-
36
- - **Engineering principles = karpathy-style · Verify every improvement = darwin-style** — both are required, not optional. Drop karpathy and your principles are never written down; drop darwin and your changes are never verified. They are co-equal layers, not sequential steps.
37
- - `/peaks-code` is the **code-domain** long-task Loop Engineering orchestrator, not a general orchestrator; non-code lanes (`peaks-content` / `peaks-doctor` / `peaks-issue-fix-orchestrator` / `peaks-sop`) ship as independent `peaks-*` bees, **not** as subclasses of `peaks-code`.
38
- - Twice-clean runs sediment into your local tactic pool (bee); broken runs come back for you to redefine. Your few bees grow with your taste.
28
+ There are only two things you ever do: **say a sentence**, or **pick one option**.
39
29
 
40
- <p align="center">
41
- <img src="./assets/readme/architecture.svg" alt="peaks-loop four asset layers, seven gates, one engineering spine" width="92%"/>
42
- </p>
30
+ - **It is not a new AI CLI.** It does not grab your shell, your prompt, or your IDE, and it does not replace any native entry point inside them.
31
+ - **You memorize no CLI, hand-author no manifest, hand-fill no form.** All CLI verbs are hidden from you and open to the LLM; it runs the commands, you just talk.
32
+ - **It does not decide for you.** Decisions that touch your assets come back to you as a choice; everything else it runs on its own.
43
33
 
44
34
  ---
45
35
 
@@ -60,11 +50,15 @@ npm i -g peaks-loop
60
50
  >
61
51
  > If you suspect the skills did not land, **no CLI command reports that state today**
62
52
  > (`peaks skill search` queries the in-package skill pool, which says nothing about your IDE directory), so
63
- > look at the directory itself: `ls ~/.claude/skills | grep '^peaks-' | head` (or the IDE dir you actually
64
- > use). Empty means the CLI installed but the skills did not — the gap is recorded in
65
- > `.peaks/docs/backlog.md` §2.52a.
53
+ > look at the directory itself:
54
+ >
55
+ > ```bash
56
+ > ls ~/.claude/skills | grep '^peaks-' | head # or the IDE dir you actually use
57
+ > ```
58
+ >
59
+ > Empty means the CLI installed but the skills did not. The gap is recorded in `.peaks/docs/backlog.md` §2.52a.
66
60
 
67
- Then, in the **Claude Code** or **Z Code** chat you already use, send an **explicit slash command** (the leading slash is what triggers peaks-loop — a plain sentence won't always route here):
61
+ Then, in the **Claude Code** or **Z Code** chat you already use, send an **explicit slash command** (the leading slash is what triggers peaks-loop):
68
62
 
69
63
  ```
70
64
  /peaks-code walk me through this codebase
@@ -80,7 +74,6 @@ Other slash commands you'll reach for:
80
74
  /peaks-issue-fix-orchestrator fix the next 30 open issues upstream
81
75
  /peaks-sop author the team's release SOP
82
76
  /peaks-solo I'll do this again — sediment it as a local tactic
83
- /peaks-solo run it like last time
84
77
  ```
85
78
 
86
79
  <sub>📦 Adapters for other AI coding tools are coming — contributions welcome → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).</sub>
@@ -89,13 +82,33 @@ No CLI to memorize. No manifest to hand-author. No second terminal to open. **Se
89
82
 
90
83
  ---
91
84
 
92
- ## What it does for you
85
+ ## Where files land after install
93
86
 
94
- Code, content, project health, issue sweeps, custom workflows — **4.x ships five first-class domains**, each with its own orchestrator. Same discipline on every lane: "gate fails = stop, run the next gate".
87
+ After `npm i -g`, the three asset classes (**skills / agents / output-styles**) are stored **once**, under
88
+ `~/.peaks/{skills,agents,output-styles}` in your own home directory. Every entry in each IDE directory
89
+ (`~/.claude/…`, `~/.trae/…`, and so on) is **a link to it** — directories via junction, individual `.md` files
90
+ via symlink. So upgrading `peaks-loop` leaves the link targets unchanged and needs no rebuild.
95
91
 
96
- <p align="center">
97
- <img src="./assets/readme/command-palette.svg" alt="peaks-loop 13 slash commands — command palette" width="92%"/>
98
- </p>
92
+ Two things that affect you directly:
93
+
94
+ - **Managed entries are overwritten on upgrade.** An entry peaks-loop installed (say
95
+ `~/.claude/agents/karpathy-reviewer.md`) sits next to a `.peaks-managed` sidecar that marks ownership, and its
96
+ contents are updated on upgrade. **To keep your own version instead, delete that sidecar** — an entry without
97
+ the marker is always treated as yours, and is **never replaced and never deleted**.
98
+ - **On some Windows hosts they degrade to real copies.** Without Developer Mode and without administrator
99
+ rights, **file** symlinks cannot be created (the junctions used for directories are unaffected), so the
100
+ installer writes real copies and says so on stderr: `installed as REAL COPIES because this host refused a symlink`.
101
+ The contents still follow the upgrade.
102
+
103
+ The true-source root can be redirected with the `PEAKS_HOME` environment variable. The full model, what happens
104
+ when you upgrade from 4.1.1, and how to verify and roll back →
105
+ [`.peaks/docs/canonical-store.md`](./.peaks/docs/canonical-store.md).
106
+
107
+ ---
108
+
109
+ ## What it does for you
110
+
111
+ Code, content, project health, issue sweeps, custom workflows — **every domain has its own orchestrator**, and each one runs under the same discipline: "gate fails = stop". All you do is pick a command and send it:
99
112
 
100
113
  | Domain | Send this slash command | It will… |
101
114
  | --- | --- | --- |
@@ -121,112 +134,25 @@ Every lane opens with **one slash command**.
121
134
  ## Why people pick it
122
135
 
123
136
  - **Natural language is the interface.** No CLI to learn, no commands to memorize. **Use an explicit slash command (e.g. `/peaks-code xxx`)** to route to the right orchestrator; everything after the slash is plain language. The LLM runs the commands on your behalf.
124
- - **Gates that actually block, not decorate.** 285+ test cases across 4 packages, all green by default; QA gate, review sign-off — all on. **Audit fails = stop. QA fails = stop.**
125
- - **Run-once flows become local tactics (bees).** Sedimented loop engineering lands in your local `~/.peaks/` pool — twice-clean runs auto-promote to standing tactics, broken runs come back for you to redefine. **Next time, just say "run that one" and the whole playbook slots back in.** Your few tactics grow with your taste.
126
- - **Sits on top of what you already run.** Not a new AI CLI to learn — it rides on **Claude Code** and **Z Code**. No shell grab, no prompt grab, no IDE grab. Other tools: adapters in progress, contributions welcome.
137
+ - **Gates that actually block, not decorate.** Code audit, security scan, QA gate, review sign-off — all on by default. **Audit fails = stop. QA fails = stop.**
138
+ - **Run-once flows become local tactics (bees).** What sediments lands in your local `~/.peaks/` pool — twice-clean runs auto-promote, broken runs come back for you to redefine. **Next time, just say "run that one" and the whole playbook slots back in.** Your few tactics grow with your taste.
139
+ - **Sits on top of what you already run.** Not a new AI CLI to learn — it rides on **Claude Code** and **Z Code**. No shell grab, no prompt grab, no IDE grab. Other tools: adapters in progress.
127
140
  - **You decide, it executes.** Decisions that touch your assets are yours; everything else it runs on its own. **Zero learning cost. One minute to first task.**
128
141
 
129
142
  ---
130
143
 
131
- ## What gates ship by default
132
-
133
- | Gate | Default | What it catches |
134
- | --- | --- | --- |
135
- | Unit + integration tests | ✅ on | regressions at the code level |
136
- | Code audit (lint / prose / type) | ✅ on | drift in style and intent |
137
- | Security scan | ✅ on | secrets, SSRF, injection, dangerous IO |
138
- | QA review | ✅ on | task-level gate — fails loud, stops clean |
139
- | Review sign-off | ✅ on | nothing ships without eyes on it |
140
- | Anti-drift evaluation (Evolution Evaluation) | ✅ on | every improvement needs an independent scorer + a regression skeptic, otherwise revert |
141
-
142
- **All gates on by default. You only speak to turn one off.**
143
-
144
- ---
145
-
146
- ## Status · shipping 4.0.17
147
-
148
- <p align="center">
149
- <img src="./assets/readme/pulse.svg" alt="peaks-loop live metrics — 4 tiles + sparkline + pipeline progress" width="92%"/>
150
- </p>
151
-
152
- <p align="center">
153
- <img src="./assets/readme/trace-stream.svg" alt="peaks-loop live diff & log stream — code diff + scrolling log + 7-gate chain" width="92%"/>
154
- </p>
155
-
156
- | | |
157
- | --- | --- |
158
- | **Latest** | [![npm](https://img.shields.io/npm/v/peaks-loop?style=for-the-badge&logo=npm&logoColor=white&color=cb3837)](https://www.npmjs.com/package/peaks-loop) — 4.1.4 (2026-10-10) |
159
- | **Domains** | Code (`peaks-code`) · Content (`peaks-content`) · Project health (`peaks-doctor`) · Issue sweep (`peaks-issue-fix-orchestrator`) · Custom SOP (`peaks-sop`) · Cross-domain primitives (`peaks-solo` dispatcher · `peaks-resume` · `peaks-status` · `peaks-test` · `peaks-slice-decompose`) |
160
- | **Sediment pool** | `~/.peaks/` local pool · twice-clean runs auto-promote to a bee · broken runs come back for you to redefine · the bee grows with your taste |
161
- | **Test suite** | 285+ cases · 4 packages (peaks-loop / peaks-loop-mut / peaks-loop-shared-channel / peaks-loop-shared) · **0 timeouts** · 14 BDD caller-binding edge cases |
162
- | **IDE adapters** | ✅ Claude Code · ✅ Z Code · 🚧 Codex / Cursor / Trae / Tongyi Lingma / Hermes / OpenClaw / Qoder (adapters in progress — contributions welcome) |
163
- | **Runtime** | Node ≥ 20 |
164
- | **License** | MIT |
165
-
166
- ### What 4.0.17 actually shipped (2026-08-07)
144
+ ## Strongly recommended · compose these three
167
145
 
168
- | Epic | Solved | Verified by |
169
- | --- | --- | --- |
170
- | **Vitest worker cap (root-cause fix)** | 17 timeouts blocked the full suite; the root cause was `pool: 'forks' + fileParallelism: true` with no `maxWorkers` cap. On a 16-core box, ~15 fork workers + 2 files spawning real `node` processes = 8.8× oversubscription. `testTimeout` measures wall clock, so descheduled tests burned 30s doing nothing. Fix: `maxWorkers = floor(cpus/2)` + `PEAKS_VITEST_MAX_WORKERS` env override + 6-case drift-guard test. **17 timeouts → 0, wall 383.67s → 360.40s, 3/3 AC-1 runs all 0 timeouts.** | commit `ace1a03d` + guard test `tests/unit/vitest-concurrency-guard.test.ts` |
171
- | **PRD-002b ESLint strictification (`no-magic-numbers`)** | Slice 2 dropped 917 → 192 violations (−725). 20 source files extracted 140+ inline magic numbers into named `const`s. `no-magic-numbers` config got `ignore: [-1, 0, 1, 2, 100, 1000]` + `ignoreArrayIndexes / ignoreDefaultValues`. 7 BDD tests, 31/31 lint tests PASS. Severity stayed `warn` (D5 no-touch-stockcode). | commits `d5ef17c1` + `0c3187c4` + 7 BDD tests |
172
- | **Statusline `--now` injection + 24-spawn amortization** | Slice 1 root cause: the test wrote `updatedAt = new Date().toISOString()` (just-NOW) and expected the lifecycle to be "within 10s window", but under full-suite concurrency the spawned subprocess is descheduled and only executes several seconds later — the completed-expiry window ages out → C1 baseline fallback → `expected '' to contain '[████████]'`. Fix: add `--now <ms>` CLI option; test pins `TEST_NOW_MS` shared by both CLI and lifecycle. **Slice 7** went further: replaced 24 real `node dist/cli/index.js` spawns with a single `beforeAll` IPC server (JSON over stdio). Wall 216s → 29s (7.5× speedup), 24/24 PASS. | commit `3d6e4bc9` (slice 1 inside) + `44c42424` (slice 7) |
173
- | **Complexity refactor (slice 3 A+B+C+D + slice 4 bundle-reader rewrite)** | Slice 3 four-stage refactor dropped 357 → 330 complexity violations (target ≤90, this wave covers the high cohort): spec-service parser → table-dispatch, slice-decompose → FSM, project-context `detectComponentLibrary` → 11-dispatch table. **Slice 4** = bundle-reader full rewrite, 5 violations → 1, public API preserved verbatim. | commits `72ef798c` + `31160051` + `1ac6e56d` + `923be824` + `0603754d` + `6b27eb94` |
174
- | **Type-narrowing + max-lines pilot (slice 5+6)** | Slice 5 closed 670 violations: 667 phantom `no-explicit-any` config swap (broken ruleId fix, same pattern as the no-duplicate-imports 4.0.16 fix) + 3 real narrowings (`catch (error: any)` → `unknown` + `instanceof Error`). Slice 6 split 4 over-length functions in `dispatch-record-writer.ts`, 4 → 0 in target file. Both slices prove the rules are essentially exhausted — true count is an order of magnitude smaller than the sediment claimed. | commits `fbb43e9e` + `3d6e4bc9` (inside) |
175
- | **Mac auto-compact ESM anti-fake-green: 5/5 verified** | Slice 8 audit-only: 5 defenses (`readClaudeTranscriptFallback` / `readClaudeStatuslinePercent` / `presence-marker-detector` / `post-compact-detector` / `step-08-gate`) all in place, ESM `require()` 0 hits, legacy silent-catch blocks already explicit re-throw `ReferenceError` / `SyntaxError`. | sediment `.peaks/memory/2026-08-07-mac-esm-defense-audit.md` |
176
- | **Caller-binding coverage extension (slice 9)** | 14 BDD tests covering 5 gap categories: multi-tenant isolation / post-rotation recovery / TTL freshness / rotation hygiene / primary-wins contract. `tests/unit/session/*` grew from 51 → 65 tests. | commit `823be8c4` + new file `tests/unit/session/caller-binding-slice-9-edge-cases.test.ts` |
177
- | **Pre-publish gates all green** | `gate-cli-version` ALIGNED (root 4.0.17 == shared CLI_VERSION 4.0.17), `build-integrity: OK`, 0 `Co-Authored-By` trailers. | per `peaks-loop-publishing-critical-hard-rules` recipe |
178
-
179
- ---
180
-
181
- ## Strongly recommended · compose these four
182
-
183
- > **Zero learning cost.** That's the biggest reason to use them together — not just that the effect is excellent, but that **all four projects speak the same interface: natural language + a choice.** You say one sentence; the LLM runs the commands, applies the gates, and follows the playbook.
184
-
185
- <p align="center">
186
- <img src="./assets/readme/footer.svg" alt="peaks-loop recommended stack" width="92%"/>
187
- </p>
146
+ > **Zero learning cost.** The biggest reason to use them together is that all three speak the same interface — "natural language + one choice". You say one sentence; the LLM runs the commands, applies the gates, and follows the playbook, with nothing for you to memorize.
188
147
 
189
148
  | Role | Project | One-liner |
190
149
  | --- | --- | --- |
191
- | **Sediment + gates** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← you are here | loop-engineering crystallization system; install → PRD/RD/QA/UI/SC/TXT as one chain + sediment |
150
+ | **Sediment + gates** | [**peaks-loop**](https://github.com/SquabbyZ/peaks-loop) ← you are here | install → PRD/RD/QA/UI/SC/TXT as one chain + sediment |
192
151
  | **Tactical handbook** | [affaan-m/ECC](https://github.com/affaan-m/ECC) | the best tactics, skills, and SOPs you can put on top of Claude Code |
193
152
  | **Process & discipline** | [obra/superpowers](https://github.com/obra/superpowers) | brainstorming / TDD / debugging / code-review as flow disciplines, every one with a hard exit |
194
153
 
195
154
  **One sentence to use them all**: clone the two repos above, install peaks-loop, hand the rest to your LLM — it pulls what it needs, holds the gates, lands the tactics, sediments the flow.
196
155
 
197
- ### Tribute
198
-
199
- peaks-loop's two engineering spines come straight from these projects:
200
-
201
- - [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) — "engineer every rule" is etched into our method layer.
202
- - [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill) — "verify every improvement" is etched into our anti-drift gate.
203
-
204
- ---
205
-
206
- ## For developers · 24h mode and batch tooling
207
-
208
- > **For peaks-loop project maintainers and "24h mode" users** — end-users, skip this section and head straight to FAQ.
209
-
210
- If your workflow reaches **24h mode** (`peaks session 24h-mode` → `24H_ACTIVE`), **batch closure passes**, or anything that needs to spawn many `peaks request transition` (or similar) calls from a parent LLM context, **install Python 3.10+ first**:
211
-
212
- ```bash
213
- # macOS / Linux
214
- brew install python@3.12 # or: pyenv install 3.12
215
-
216
- # Windows
217
- winget install Python.Python.3.12
218
- ```
219
-
220
- **Why not Node.js?peaks-loop itself is Node/pnpm, isn't it?** — peaks-loop's *own* hard dep stays Node.js, **unchanged**. The reason Python wins for *batch-utility scripting* is the `subprocess` layer: Python's `subprocess.run(capture_output=True, env=...)` is significantly less painful than Node's `child_process.spawn` on Windows + UTF-8 + cross-platform (one line of `LANG` / `LC_ALL` / `PYTHONIOENCODING` env in the child fixes it; Node's `child_process` needs separate `windowsHide` + `console.log` encoding tricks). And the code is shorter.
221
-
222
- **Rules** (sedimented at `.peaks/memory/2026-08-01-24h-mode-59-rid-closure-pass.md`):
223
-
224
- 1. **Detect-then-pick**: probe `python3 --version` (or `py -3` on Windows) first; use Python if available; else fall back to `node`; else surface the missing-runtime error — do not silently degrade.
225
- 2. **Path**: place the script at **`.peaks/_tools/<name>.py`** (or `.mjs`). Do **not** place under `bin/` — that directory is reserved for peaks-loop's own source-shipped scripts and pollution from temporary helpers is a maintenance hazard. The `_`-prefixed `.peaks/_tools/` mirrors `.peaks/_runtime/`, `.peaks/_sub_agents/`, `.peaks/_dogfood/` and is gitignored.
226
- 3. **Delete when the work is done.** Temporary scripts are not deliverables; leaving them around invites the "what is this?" question.
227
-
228
- This section is **not for ordinary end-users** — `npm i -g peaks-loop` + a slash command is all you need. Python is for the layer of people who want to write their own batch utilities.
229
-
230
156
  ---
231
157
 
232
158
  ## FAQ
@@ -234,14 +160,7 @@ This section is **not for ordinary end-users** — `npm i -g peaks-loop` + a sla
234
160
  <details>
235
161
  <summary><b>How does it relate to Claude Code / Z Code?</b></summary>
236
162
 
237
- It **sits on top of** them, not in place of. peaks-loop doesn't grab your shell, your prompt, or your IDE. It runs as a first-class adapter on Claude Code and Z Code. **Adapters for other tools are in progress — contributions welcome** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).
238
-
239
- </details>
240
-
241
- <details>
242
- <summary><b>Do I need to learn CLI commands?</b></summary>
243
-
244
- No. You speak or pick; the LLM runs the commands. **All CLI verbs are hidden from you, open to the LLM.**
163
+ It **sits on top of** them, not in place of. It doesn't grab your shell, your prompt, or your IDE — you keep using them as usual. **Adapters for other AI coding tools are in progress — contributions welcome** → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues).
245
164
 
246
165
  </details>
247
166
 
@@ -262,78 +181,23 @@ It changes, but **the gates hold**. Audit fails = nothing ships. QA fails = noth
262
181
  <details>
263
182
  <summary><b>What's new in 4.x vs 3.x?</b></summary>
264
183
 
265
- **The biggest shift: from "code-only tool" to multi-domain orchestration system.** 4.x no longer just writes code — it ships four new domain orchestrators: `peaks-content` (content production), `peaks-doctor` (project health), `peaks-issue-fix-orchestrator` (batch issue fix), `peaks-sop` (custom SOPs). On top of that, `peaks-solo` auto-routes to the right domain from plain language. Plus 9 IDE adapters, crystallization-system renaming, post-run crystallization. Full list → [`CHANGELOG.md`](./CHANGELOG.md).
184
+ **From a code-only tool to multi-domain orchestration:** it ships four new domain chains — `peaks-content` (content production), `peaks-doctor` (project health), `peaks-issue-fix-orchestrator` (batch issue fix), `peaks-sop` (custom SOPs) — plus `peaks-solo`, a dispatcher that routes from plain language to the right domain. Full list → [`CHANGELOG.md`](./CHANGELOG.md).
266
185
 
267
186
  </details>
268
187
 
269
188
  ---
270
189
 
271
- ## Full skill index
272
-
273
- 13 user skills · every entry point lives in `skills/<name>/SKILL.md`:
274
-
275
- <p align="center">
276
- <img src="./assets/readme/skill-index.svg" alt="peaks-loop 13 user skills — full index with category badges" width="92%"/>
277
- </p>
278
-
279
- ---
280
-
281
- ## Ship summary (4.x · 19 rids)
282
-
283
- `009 · 010 · 011 · 014 · 015 · 016 · 017 · 020b · 024 · 025 · 026 · 027 · 028 · 029 · 030 · 031 · 032 · 033 · 034` — CLI surface collapse (73 → 5 byte-identical), Trusted Publishing + OIDC, 24h-mode, context spillover, DAG wave + barrier, dashboard aggregation, test-rebuild epic, karpathy-cost self-review, compact visibility, retire-auto-compact-hook, and more.
284
-
285
- <p align="center">
286
- <img src="./assets/readme/ship-summary.svg" alt="peaks-loop 4.x 19-rid ship timeline with category chips" width="92%"/>
287
- </p>
288
-
289
- ---
290
-
291
- ## Downstream consumer notes
292
-
293
- If you maintain a project that depends on `peaks-loop` (or that runs `npm install peaks-loop` as part of CI / contributor onboarding), three behaviors are worth pinning in your head:
294
-
295
- - **`codegraph` is a transitive dependency.** `peaks-loop` pins `@colbymchenry/codegraph@1.6.2` in its `dependencies`, so `npm install` / `pnpm install` will pull it automatically. The CLI command group `peaks codegraph …` (status / init / index / query / files / context / affected) is shipped inside `dist/services/codegraph/`. No extra install step required.
296
- - **`.codegraph/` directory ownership is shared.** Tools like aider, cody, and similar agents also create a top-level `.codegraph/`. `peaks codegraph init` will refuse to overwrite a foreign schema and exits with code 73 + a `CODEGRAPH_INIT_CONFLICT` envelope. If your project already has a `.codegraph/` from another tool, move / rename it (or remove it if you no longer need it) before running `peaks codegraph init`.
297
- - **Session binding lives under `.peaks/_runtime/<sessionId>/`.** Codegraph orchestration context (and other per-session evidence) is written there by RD / QA slices. Add `.peaks/_runtime/` to your project's `.gitignore` to avoid committing local session state. A missing / unbound session produces a graceful skip-with-warning, never a crash.
298
- - **Doctor fallback for yarn-pnp / pnpm-strict.** `peaks doctor` falls back to a filesystem walk when `require.resolve('@colbymchenry/codegraph/package.json')` throws, so downstream installs under strict resolution modes still get a green check (or a `severity: 'warning'` if the version drifted from the pinned `1.6.2`).
299
- - **Tarball size / verify.** Each release ships the codegraph service under `dist/services/codegraph/`. Per-release verification lives at `scripts/verify-codegraph-tarball.mjs` (run `node scripts/verify-codegraph-tarball.mjs` locally before tagging a release). Exit 0 means the whitelist is intact; exit 1 means the tarball is missing the codegraph service files.
300
-
301
- Install snippet (typical consumer):
302
-
303
- ```bash
304
- # Add peaks-loop to your project
305
- npm install peaks-loop
306
-
307
- # Bootstrap codegraph for the first time (refuses if .codegraph/ already
308
- # exists with a non-peaks-loop schema; exit code 73 + envelope)
309
- npx peaks codegraph init --project .
310
-
311
- # Verify the doctor is green for downstream resolution modes
312
- npx peaks doctor --project .
313
- ```
314
-
315
- Three common pitfalls:
316
-
317
- 1. **`peaks codegraph init` exits 73** — your project has a pre-existing `.codegraph/` from another tool. Move it out of the way (or remove it), then re-run.
318
- 2. **`peaks doctor` warns about codegraph version drift** — your lockfile resolved a different `@colbymchenry/codegraph` version than the pinned `1.6.2`. Pin to `1.6.2` in your lockfile; the warning does not flip the doctor exit code.
319
- 3. **Session-bound artifacts under `.peaks/_runtime/` are noisy in `git status`** — add the path to your project's `.gitignore`. The `peaks-loop` repo already does this; consumers should mirror the rule.
320
-
321
- ---
322
-
323
190
  ## Links
324
191
 
325
192
  - All skills → [`skills/`](./skills/)
326
193
  - Changelog → [`CHANGELOG.md`](./CHANGELOG.md)
327
194
  - Questions → [GitHub Issues](https://github.com/SquabbyZ/peaks-loop/issues)
328
- - Tribute: [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) · [alchaincyf/darwin-skill](https://github.com/alchaincyf/darwin-skill)
329
195
  - Recommended combo: [affaan-m/ECC](https://github.com/affaan-m/ECC) · [obra/superpowers](https://github.com/obra/superpowers)
330
196
 
331
197
  ---
332
198
 
333
- ---
334
-
335
199
  <div align="center">
336
200
 
337
201
  MIT License · Made by [SquabbyZ](https://github.com/SquabbyZ) · English · [简体中文](./README.md)
338
202
 
339
- </div>
203
+ </div>