peaks-loop 4.1.17 → 4.1.19

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 (205) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +269 -0
  3. package/README-en.md +6 -0
  4. package/README.md +5 -0
  5. package/contracts/test-style-contract.md +14 -5
  6. package/dist/cli/commands/audit-red-lines-runners.js +6 -1
  7. package/dist/cli/commands/best-practice-scan-collision.d.ts +42 -0
  8. package/dist/cli/commands/best-practice-scan-collision.js +115 -0
  9. package/dist/cli/commands/best-practice-scan-command.d.ts +5 -0
  10. package/dist/cli/commands/best-practice-scan-command.js +9 -18
  11. package/dist/cli/commands/best-practice-scan-helpers.d.ts +12 -6
  12. package/dist/cli/commands/best-practice-scan-helpers.js +37 -17
  13. package/dist/cli/commands/code-auto-compact-command.js +71 -40
  14. package/dist/cli/commands/code-auto-compact-deferral.d.ts +34 -0
  15. package/dist/cli/commands/code-auto-compact-deferral.js +59 -0
  16. package/dist/cli/commands/code-gate-command.d.ts +4 -4
  17. package/dist/cli/commands/code-gate-command.js +4 -4
  18. package/dist/cli/commands/core/skill-generated-config-notice.d.ts +5 -0
  19. package/dist/cli/commands/core/skill-generated-config-notice.js +42 -8
  20. package/dist/cli/commands/core/skill-presence-commands.js +42 -74
  21. package/dist/cli/commands/core/skill-presence-set-command.d.ts +11 -0
  22. package/dist/cli/commands/core/skill-presence-set-command.js +175 -0
  23. package/dist/cli/commands/core/skill-registry-commands.js +32 -0
  24. package/dist/cli/commands/core/skill-store-report.d.ts +8 -0
  25. package/dist/cli/commands/core/skill-store-report.js +79 -0
  26. package/dist/cli/commands/core/standards-init-command.js +44 -8
  27. package/dist/cli/commands/core/standards-migrate-command.js +5 -4
  28. package/dist/cli/commands/dispatch-dag-runners.d.ts +1 -0
  29. package/dist/cli/commands/dispatch-dag-runners.js +11 -1
  30. package/dist/cli/commands/dispatch-detached-branch.js +19 -1
  31. package/dist/cli/commands/dispatch-prompt-composition.js +7 -2
  32. package/dist/cli/commands/dispatch-scratch-path-block.d.ts +73 -0
  33. package/dist/cli/commands/dispatch-scratch-path-block.js +131 -0
  34. package/dist/cli/commands/hooks-commands.js +36 -7
  35. package/dist/cli/commands/hooks-uninstall-command.js +5 -5
  36. package/dist/cli/commands/mut-commands-helpers.d.ts +72 -5
  37. package/dist/cli/commands/mut-commands-helpers.js +197 -4
  38. package/dist/cli/commands/mut-commands.d.ts +9 -1
  39. package/dist/cli/commands/mut-commands.js +82 -154
  40. package/dist/cli/commands/preferences-commands.js +27 -2
  41. package/dist/cli/commands/scan-scope-helpers.js +2 -2
  42. package/dist/services/24h-mode/auto-engage.d.ts +11 -3
  43. package/dist/services/24h-mode/auto-engage.js +14 -6
  44. package/dist/services/artifacts/artifact-templates.js +10 -0
  45. package/dist/services/artifacts/backcompat-acceptance.d.ts +8 -1
  46. package/dist/services/artifacts/backcompat-acceptance.js +8 -7
  47. package/dist/services/artifacts/rd-transition-gates.d.ts +32 -5
  48. package/dist/services/artifacts/rd-transition-gates.js +96 -19
  49. package/dist/services/artifacts/request-artifact-service.js +6 -6
  50. package/dist/services/audit/enforcers/lint-output-style.js +14 -2
  51. package/dist/services/audit/enforcers/root-scratch-artifacts.d.ts +46 -0
  52. package/dist/services/audit/enforcers/root-scratch-artifacts.js +97 -0
  53. package/dist/services/audit/static-service.js +4 -4
  54. package/dist/services/code/auto-compact-history.d.ts +6 -1
  55. package/dist/services/code/auto-compact-history.js +6 -1
  56. package/dist/services/code/auto-compact-modes.d.ts +60 -14
  57. package/dist/services/code/auto-compact-modes.js +75 -20
  58. package/dist/services/code/auto-compact-orchestrator.js +7 -5
  59. package/dist/services/code/auto-compact-profile.d.ts +23 -0
  60. package/dist/services/code/auto-compact-profile.js +51 -0
  61. package/dist/services/code/auto-compact-run-types.d.ts +8 -4
  62. package/dist/services/compact-history/compact-history-service.d.ts +6 -1
  63. package/dist/services/compact-history/compact-history-service.js +5 -1
  64. package/dist/services/context/auto-compact-types.d.ts +7 -5
  65. package/dist/services/dispatch/dispatch-ledger-reader.d.ts +13 -0
  66. package/dist/services/dispatch/dispatch-ledger-reader.js +164 -0
  67. package/dist/services/doctor/doctor-service/checks/canonical-store-version.d.ts +57 -0
  68. package/dist/services/doctor/doctor-service/checks/canonical-store-version.js +190 -0
  69. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.d.ts +37 -0
  70. package/dist/services/doctor/doctor-service/checks/l3-runtime-root-census.js +100 -0
  71. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.d.ts +11 -3
  72. package/dist/services/doctor/doctor-service/checks/skill-reference-parity.js +48 -29
  73. package/dist/services/doctor/doctor-service/plugin-registry.js +4 -0
  74. package/dist/services/doctor/doctor-service/types.d.ts +12 -0
  75. package/dist/services/hooks/hook-payload-cwd.d.ts +11 -4
  76. package/dist/services/hooks/hook-payload-cwd.js +11 -4
  77. package/dist/services/hooks/pre-tool-code-gate.d.ts +4 -4
  78. package/dist/services/hooks/pre-tool-code-gate.js +4 -4
  79. package/dist/services/hooks/presence-marker-detector.d.ts +3 -0
  80. package/dist/services/hooks/presence-marker-detector.js +21 -19
  81. package/dist/services/ide/adapters/claude-code-adapter.js +6 -8
  82. package/dist/services/ide/adapters/codex-adapter.js +23 -7
  83. package/dist/services/ide/adapters/cursor-adapter.js +23 -7
  84. package/dist/services/mode/mode-status-service.d.ts +26 -27
  85. package/dist/services/mode/mode-status-service.js +36 -60
  86. package/dist/services/preferences/preferences-types.d.ts +30 -0
  87. package/dist/services/preferences/preferences-types.js +13 -0
  88. package/dist/services/scan/acceptance-coverage-service.d.ts +14 -11
  89. package/dist/services/scan/acceptance-coverage-service.js +157 -52
  90. package/dist/services/scan/rid-change-claims.d.ts +15 -0
  91. package/dist/services/scan/rid-change-claims.js +116 -0
  92. package/dist/services/session/getSessionDir.d.ts +13 -0
  93. package/dist/services/session/getSessionDir.js +7 -1
  94. package/dist/services/skills/hooks-settings-types.d.ts +17 -21
  95. package/dist/services/skills/presence-caller-id.d.ts +51 -0
  96. package/dist/services/skills/presence-caller-id.js +43 -0
  97. package/dist/services/skills/presence-gate.d.ts +65 -0
  98. package/dist/services/skills/presence-gate.js +113 -0
  99. package/dist/services/skills/presence-lease-resolver.d.ts +63 -0
  100. package/dist/services/skills/presence-lease-resolver.js +114 -0
  101. package/dist/services/skills/presence-lease-selection.d.ts +91 -0
  102. package/dist/services/skills/presence-lease-selection.js +135 -0
  103. package/dist/services/skills/presence-lease-service.d.ts +3 -11
  104. package/dist/services/skills/presence-lease-service.js +34 -87
  105. package/dist/services/skills/presence-lease-store.d.ts +33 -0
  106. package/dist/services/skills/presence-lease-store.js +94 -0
  107. package/dist/services/skills/presence-lease-types.d.ts +31 -0
  108. package/dist/services/skills/presence-lease-types.js +27 -0
  109. package/dist/services/skills/presence-role.d.ts +35 -0
  110. package/dist/services/skills/presence-role.js +72 -0
  111. package/dist/services/skills/skill-presence-service.d.ts +39 -9
  112. package/dist/services/skills/skill-presence-service.js +143 -174
  113. package/dist/services/skills/skill-presence-write.d.ts +60 -0
  114. package/dist/services/skills/skill-presence-write.js +74 -0
  115. package/dist/services/skills/skill-statusline-service.js +7 -7
  116. package/dist/services/skills/sync-service-support.d.ts +27 -0
  117. package/dist/services/skills/sync-service.js +1 -0
  118. package/dist/services/standards/ide-aware-standards-service.d.ts +35 -23
  119. package/dist/services/standards/ide-aware-standards-service.js +45 -20
  120. package/dist/services/standards/migrate-claude-rules-service.d.ts +6 -0
  121. package/dist/services/standards/migrate-claude-rules-service.js +18 -0
  122. package/dist/services/standards/migrate-service.d.ts +1 -1
  123. package/dist/services/standards/migrate-service.js +27 -7
  124. package/dist/services/standards/project-scripts.d.ts +25 -0
  125. package/dist/services/standards/project-scripts.js +116 -0
  126. package/dist/services/standards/project-standards-service.d.ts +23 -15
  127. package/dist/services/standards/project-standards-service.js +176 -243
  128. package/dist/services/standards/standards-constitution.d.ts +89 -0
  129. package/dist/services/standards/standards-constitution.js +199 -0
  130. package/dist/services/standards/standards-files.d.ts +37 -0
  131. package/dist/services/standards/standards-files.js +138 -0
  132. package/dist/services/standards/standards-pointer.d.ts +73 -0
  133. package/dist/services/standards/standards-pointer.js +98 -0
  134. package/dist/services/standards/standards-render-agents.d.ts +34 -0
  135. package/dist/services/standards/standards-render-agents.js +149 -0
  136. package/dist/services/standards/standards-render-common.d.ts +38 -1
  137. package/dist/services/standards/standards-render-common.js +44 -7
  138. package/dist/services/standards/standards-render.d.ts +1 -3
  139. package/dist/services/standards/standards-render.js +6 -87
  140. package/dist/services/workflow/workflow-graph-ensure.d.ts +77 -0
  141. package/dist/services/workflow/workflow-graph-ensure.js +97 -0
  142. package/dist/services/workflow/workflow-inflight-probe.d.ts +68 -31
  143. package/dist/services/workflow/workflow-inflight-probe.js +163 -75
  144. package/dist/services/workflow/workflow-presence-lifecycle.js +21 -6
  145. package/dist/services/workspace/generated-artifacts-content.d.ts +46 -0
  146. package/dist/services/workspace/generated-artifacts-content.js +167 -0
  147. package/dist/services/workspace/generated-artifacts-stamp.d.ts +36 -13
  148. package/dist/services/workspace/generated-artifacts-stamp.js +37 -15
  149. package/dist/services/workspace/runtime-layout.d.ts +64 -0
  150. package/dist/services/workspace/runtime-layout.js +62 -0
  151. package/output-styles/peaks-skill-swarm.md +18 -2
  152. package/package.json +10 -9
  153. package/schemas/doctor-report.schema.json +1 -1
  154. package/scripts/canonical-store-fs.mjs +112 -0
  155. package/scripts/canonical-store-link.mjs +13 -22
  156. package/scripts/canonical-store-marker.mjs +241 -0
  157. package/scripts/canonical-store.mjs +119 -141
  158. package/scripts/install-skills-bundles.mjs +56 -13
  159. package/scripts/install-skills-fs.mjs +73 -0
  160. package/scripts/install-skills-output-styles.mjs +8 -2
  161. package/scripts/install-skills-report.mjs +19 -0
  162. package/scripts/install-skills.mjs +9 -0
  163. package/skills/bee/peaks-perf-audit/SKILL.md +3 -1
  164. package/skills/bee/peaks-prd/SKILL.md +5 -3
  165. package/skills/bee/peaks-qa/SKILL.md +4 -2
  166. package/skills/bee/peaks-qa/references/qa-skill-presence.md +1 -1
  167. package/skills/bee/peaks-qa/references/qa-standards-preflight.md +3 -1
  168. package/skills/bee/peaks-qa/references/qa-sub-agent-dispatch.md +2 -2
  169. package/skills/bee/peaks-rd/SKILL.md +4 -2
  170. package/skills/bee/peaks-rd/references/artifact-and-standards-output.md +1 -1
  171. package/skills/bee/peaks-rd/references/rd-runbook.md +11 -2
  172. package/skills/bee/peaks-rd/references/rd-standards-preflight.md +3 -1
  173. package/skills/bee/peaks-rd/references/rd-sub-agent-dispatch.md +24 -5
  174. package/skills/bee/peaks-rd/references/rd-transition-gates.md +49 -5
  175. package/skills/bee/peaks-rd/references/skill-presence-and-title.md +1 -1
  176. package/skills/bee/peaks-reviewer/SKILL.md +3 -1
  177. package/skills/bee/peaks-sc/SKILL.md +4 -2
  178. package/skills/bee/peaks-security-audit/SKILL.md +3 -1
  179. package/skills/bee/peaks-txt/SKILL.md +5 -3
  180. package/skills/bee/peaks-ui/SKILL.md +6 -4
  181. package/skills/peaks-audit/SKILL.md +3 -1
  182. package/skills/peaks-code/SKILL.md +4 -2
  183. package/skills/peaks-code/references/a2a-artifact-mapping.md +3 -3
  184. package/skills/peaks-code/references/completion-handoff.md +1 -1
  185. package/skills/peaks-code/references/local-artifact-workspace.md +10 -11
  186. package/skills/peaks-code/references/micro-cycle.md +2 -2
  187. package/skills/peaks-code/references/mode-selection-with-stale-presence.md +3 -3
  188. package/skills/peaks-code/references/runbook.md +4 -4
  189. package/skills/peaks-code/references/skill-presence-and-title.md +4 -2
  190. package/skills/peaks-code/references/standards-preflight.md +7 -6
  191. package/skills/peaks-code/references/sub-agent-dispatch.md +1 -1
  192. package/skills/peaks-code/references/swarm-dispatch-contract.md +5 -5
  193. package/skills/peaks-code/references/workflow-gates-and-types.md +37 -11
  194. package/skills/peaks-content/SKILL.md +3 -1
  195. package/skills/peaks-doctor/SKILL.md +3 -1
  196. package/skills/peaks-final-review/SKILL.md +3 -1
  197. package/skills/peaks-ide/SKILL.md +3 -1
  198. package/skills/peaks-issue-fix-orchestrator/SKILL.md +5 -3
  199. package/skills/peaks-race-code/SKILL.md +9 -4
  200. package/skills/peaks-resume/SKILL.md +3 -1
  201. package/skills/peaks-slice-decompose/SKILL.md +3 -1
  202. package/skills/peaks-solo/SKILL.md +3 -1
  203. package/skills/peaks-sop/SKILL.md +4 -2
  204. package/skills/peaks-status/SKILL.md +3 -1
  205. package/skills/peaks-test/SKILL.md +3 -1
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.17"
4
+ "version": "4.1.19"
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.17",
10
+ "version": "4.1.19",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
package/CHANGELOG.md CHANGED
@@ -1,5 +1,274 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.19 — 2026-10-24(`peaks mut` 在真实用户机器上**真的能跑**)
4
+
5
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
6
+ 没有改 fail-open 策略、没有动 auto-compact 三档阈值,peaks-code 的 11 步工序与 Gate A–G **一字不改**;
7
+ 改的是 `peaks mut` 这一条线上的**依赖位置、作用域与文档**(§1–§5),以及**版本号本身**(§6)。
8
+
9
+ 这一批做的是**同一件事**:让 `peaks mut` 从"消费者装上就崩"走到"消费者装上就能跑"。
10
+
11
+ 崩的原因**不是代码写错了**,是**依赖放错了地方**:变异测试引擎只挂在根包的 `devDependencies` 上,
12
+ 而真正 import 它的是 `peaks-loop-mut` —— 一个**要被发布出去**的包。消费者装到的是 registry 上的
13
+ `peaks-loop-mut@0.1.72`,它的 dependencies 只有 `{zod, ecc-universal}`,**不带 stryker**,
14
+ 于是 `Cannot find package '@stryker-mutator/core'`。
15
+
16
+ 这一批把它修好,并且补上三件一直缺的东西:**项目作用域正确**(改谁就只改谁)、
17
+ **文档说真话**(文档里每句话都对得上代码)、**过期接受退休**(一条理由已经不成立的"豁免"从名单里划掉)。
18
+
19
+ **消费者要多付一点下载体积:约 2.66 MB。** 这件事写在 §1,不藏着。
20
+
21
+ ### 1. 变异引擎落到生产依赖(以及它到底值不值这 2.66 MB)
22
+
23
+ - 现在 `@stryker-mutator/core`(Stryker 的变异引擎)与 `@stryker-mutator/vitest-runner` 是
24
+ `peaks-loop-mut` 的**生产依赖**(`dependencies`,不是 `devDependencies`),两者同为 **9.6.1**。
25
+ - **消费者视角 —— `@stryker-mutator/vitest-runner` 是干什么的**:它是把 Stryker 的变异引擎接到
26
+ vitest 上的**适配器**。没有它,Stryker 只能退回"跑一条命令看退出码"的粗粒度跑手,
27
+ **算不出逐 mutant 的 kill rate** —— 而 `peaks mut` 卖的**正是这个数字**。所以它不是可选项。
28
+ - **代价**:安装会多出 stryker 引擎闭包 **9 个包 / 约 2.66 MB**。
29
+ - **vitest 那部分不会自动来**:vitest-runner 声明的 peer 是 `vitest >=2.0.0`,而 pnpm 的 peer 自动安装
30
+ **只在 peer 缺失时**发生。vitest / vite 家族共 **11 个包 / 约 5.30 MB**,**只有在你的机器上
31
+ 还没有 vitest 时**才会被自动装上 —— 而要跑 `peaks mut` 的项目**必然已经有 vitest**。
32
+ - 说人话:**你装 peaks-loop 多下载了约 2.7 MB**。参照:`peaks-loop-mut` 现有的生产依赖树是
33
+ **344 个包 / 156.6 MB**(大头是 `sql.js` 23.0 MB、`typescript` 22.5 MB、`ecc-universal` 18.6 MB,
34
+ **与本次改动无关**),2.66 MB 相对可忽略。(这一段的 MB 一律是**二进制 MB**:三个大头由同一份实测
35
+ 脚本以 `/1024/1024` 从按 `KB` 记的实测字节换算,与上面 2.66 / 5.30 / 156.6 同一口径。)
36
+ - **为什么这一节必须配一次版本号**:发布脚本**先发子包、后发根包**,并且**跳过 registry 上已存在的同版本**。
37
+ `peaks-loop-mut@0.1.72` 已经在 registry 上,它不带 `dist/version.js` 所以不会被判 stale ——
38
+ 版本不动,**这个改动到不了任何用户**。
39
+
40
+ ### 2. core / vitest-runner 的大版本互斥修好了;那个**从来没激活过**的 checker 被移除
41
+
42
+ - 此前:vitest-runner 9.6.1 声明的 peer 要求 core **9.6.1**,而根包 `devDependencies` 里 core 停在
43
+ **^8.7.1** ⇒ 每次安装都有一条 unmet peer。
44
+ - 现在:core 与 vitest-runner 同为 **9.6.1**,**全量重解析零 unmet peer**。
45
+ - `@stryker-mutator/typescript-checker` **已移除**:**移除之前**全仓只有 **5 处**提到它 —— 根清单的
46
+ `devDependencies` 一行、锁文件里的 importer 条目 / package 条目 / peer 快照条目三条,以及
47
+ `.peaks/docs/lint-rule-divergences.md` 里的一句散文记录。**这 5 处没有一处是插件**:
48
+ `stryker.conf.js` 的 `plugins` 里**从来就没有它**(移除前的版本也没有),它**从来没有被激活过**。
49
+ 而它声明的 peer 是 core `~8.7.0`,与 9.6.1 **互斥**,于是每次安装都报一条 unsatisfied binding。
50
+ 移除后那条警告消失。这一版发出去的树里,它**只剩两处**被提到:那一句散文记录,和本节的这一句。
51
+ - 锁文件的改动**有闭包证明**,不是"看着像":把两份锁文件的 stryker 传递闭包逐键比对,结论是
52
+ **每一处改动都在闭包内**(**PASS**)。checker 移除那一轮单独是 **26 删 / 0 增 / 1 改**,
53
+ 删掉的正是 checker 的子树;028 这一轮合起来,importer 只动了 `.` 与 `packages/peaks-loop-mut`。
54
+
55
+ ### 3. `peaks mut` 的项目作用域与程序化配置(改谁就只改谁)
56
+
57
+ - 此前:`--project` 被**忽略** —— Stryker 读配置、解析 `mutate` / `testFiles` 模式都按 `process.cwd()` 来,
58
+ `--test-files` 根本没传到 Stryker;项目根的 `stryker.conf.js` 是**必须**的。
59
+ - 现在:作用域由 `--project` 决定,配置由 CLI **程序化**构建;项目根的 `stryker.conf.js`
60
+ 降级为**可选的向后兼容兜底**(项目自己写的 `mutate` 仍然优先于 CLI 的默认值)。
61
+ - **实测(真实夹具,在仓库之外:没有 `node_modules`、没有 `stryker.conf.js`)**:
62
+ `mutantsTotal 4 / killed 2 / survived 2 / killRate 0.5`;
63
+ 从**另一个工作目录**发起时,被改的是夹具里的文件,调用者 cwd 里的诱饵文件**没被改**
64
+ (`decoyUnchanged = true`)。**stdout 恰好 1 行**,可解析。
65
+ - 失败现在有**具名错误码**,不再是 `UNHANDLED_ERROR`:
66
+ `MUT_MUTATE_PATTERN_REQUIRED`、`MUT_NO_MUTANTS`、`MUT_TOOLCHAIN_UNAVAILABLE`。
67
+ - 测试:纯配置构建器 **13 passed**、CLI 标志解析 **5 passed**、集成 **2 个文件 / 5 个测试全绿**。
68
+ - 报告 schema 的源文件**逐字节未改**
69
+ (sha256 `bc675a8521601c8edb2cd217ccbe9972fe6ed2040b79701e3870cd1f3db60d1d` 前后相同)。
70
+
71
+ ### 4. 文档与脚本说真话(每一句都对得上代码)
72
+
73
+ - `peaks-mut` 技能文档:**18 处校正 + 3 处收紧**(逐条"原句 → 现句"在切片载体里)。
74
+ - 守卫测试对着**真实的 commander 命令对象**比对,不是对着手抄的标志清单 ⇒ 标志改名/增删都会红。
75
+ 当前 **12/12 绿**;红复现实测 **1 failed / 11 passed,退出码 1**。
76
+ - 仓库自己的 `stryker.conf.js` 此前指向 **4 个没有任何测试 import 的文件** ⇒ dogfood 运行必然
77
+ `killRate 0`、退出码 1(**不是配置写错了,是那几个文件根本没有测试**)。现在 4 个 mutate 目标
78
+ **每一个都有测试 import**。
79
+ - 根脚本 `mut:run` / `mut:scan` 现在带的参数**就是解析器认的参数**(之前那两个脚本各缺必需参数)。
80
+
81
+ ### 5. `mut/mut-report.json` 的过期接受条目退休
82
+
83
+ - 此前:种子名单里有一条针对 `mut/mut-report.json` 的"过期可接受"豁免,它给的理由**两半都是假的**
84
+ ("没有生产者"、"peaks tact read 不是注册命令")。现在 `peaks mut run` **真的**产出报告,
85
+ `peaks tact read` **真的**是注册命令 —— 理由不成立了,条目就该退休。
86
+ - 退休范围**只有那一条接受条目**:那行 `backCompat` / `backCompatUntil` 的**窗口本身一字未改**
87
+ (窗口仍在,缺的报告仍是软通过);另一条接受**保留**。
88
+ - 真实报告(`mut/mut-report.json`):`mutantsTotal 21 / killed 20 / survived 1`、
89
+ `killRate 0.9523809523809523`、`totalAssertions 29`、`weakAssertions 0`、`weakRate 0`、
90
+ `thresholds.passed true`。
91
+ - 阈值**一个都没改**(`mutationKillRateMin 0.80` / `weakAssertionRateMax 0.05`),
92
+ 受影响的 **7 个测试文件 / 93 个测试全绿**。
93
+
94
+ ### 6. 版本号与发布含义
95
+
96
+ - 根包 `peaks-loop` **4.1.18 → 4.1.19**。`packages/` 下**实际只有 4 个**可发布 workspace 包
97
+ (发现规则是扫 `packages/` 的直接子目录、且要求其中有 `package.json`),
98
+ 由正路脚本**锁步升**(子包规则 = patch 位 +1,major/minor 不变):
99
+
100
+ | 包 | 改前 | 改后 |
101
+ | ----------------------------- | ------- | ---------- |
102
+ | `peaks-loop`(根) | 4.1.18 | **4.1.19** |
103
+ | `peaks-loop-mut` | 0.1.72 | **0.1.73** |
104
+ | `peaks-loop-shared` | 0.0.107 | 0.0.108 |
105
+ | `peaks-loop-shared-channel` | 0.0.75 | 0.0.76 |
106
+ | `peaks-loop-internal-runtime` | 0.0.58 | 0.0.59 |
107
+
108
+ - 两个**受版本控制**的版本戳同步为 4.1.19:`packages/peaks-loop-shared/src/version.ts` 的 `CLI_VERSION`
109
+ 与 `packages/peaks-loop-internal-runtime/src/index.ts` 的 `RUNTIME_VERSION`。
110
+ - **版本字段一个都没手改**:全部由 `scripts/bump-version.mjs --to 4.1.19` 与 `scripts/sync-version.mjs`
111
+ 产生。逐字段比对证明:**5 个 manifest 各自只有 `version` 一个键变了**。
112
+ - **维护者要做的**(本次**没有**做):合并后 `git tag v4.1.19` + push,由发布流程发包。
113
+ **本次不打 tag、不发布、不提交。**
114
+ - 为什么**必须**动版本号(再说一次,因为它就是本节存在的理由):发布脚本**先发子包、后发根包**,
115
+ 并且**跳过 registry 上已存在的同版本**;线上根包 pin 的是 `peaks-loop-mut: 0.1.72`,
116
+ 而 registry 上的 0.1.72 **不带 stryker** ⇒ 版本不动,§1 的依赖**到不了用户**。
117
+
118
+ ### 7. 验证
119
+
120
+ - `node scripts/verify-version-parity.mjs runtime-src` 退出 **0**(源码层,不需 build)。
121
+ - 源码 CLI `node node_modules/tsx/dist/cli.mjs src/cli/index.ts --version` 打印 **4.1.19**。
122
+ - `pnpm install --frozen-lockfile` 退出 **0**,而且**锁文件一个字都没改** ——
123
+ workspace 包在锁文件里是 `link:` 引用(**不记版本号**),所以版本号变动**不需要**动锁文件。
124
+ - 依赖守卫测试 `tests/unit/release/mut-runtime-dependency.test.ts` **13 passed (13)**。
125
+ - `tsc -p tsconfig.json --noEmit` 退出 **0**;`prettier --check` 对本次改动的清单文件退出 **0**;
126
+ `eslint --config config/eslint/.peaks-rules.cjs --no-ignore` 对两个版本戳文件 **0 findings**。
127
+ - 逐字段比对:**5 个 manifest 各自只有 `version` 一个键变了**。
128
+
129
+ ## 4.1.18 — 2026-10-23(下游机器的技能商店会说谎了;门禁不再对自己的沉默撒谎)
130
+
131
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
132
+ 既有 CLI 参数、门禁的六个硬阻断族成员、fail-open 策略、auto-compact 三档阈值、
133
+ peaks-code 的 11 步工序与 Gate A–G **一字不改**。
134
+
135
+ 本次修的是同一条线上的**七个洞**,它们是**同一类**:**一个表面说自己做了、其实没做的事**。
136
+ 下游 macOS 机器报告"`~/.peaks/skills/peaks-code` 在,但 `~/.claude/skills/peaks-code` 软链后面的内容没有完整更新" ——
137
+ 查到最后,**发布包是好的**(4.1.16 / 4.1.17 的 tarball 里 49 个 reference 文件一个不少),
138
+ 坏的是**商店那一侧**,而且坏的方式是:**没有任何地方记录版本号**,所以"冻结在 4.1.15"和"是当前的"
139
+ **长得一模一样**。
140
+
141
+ **下游那台机器要做的:装上这个版本,跑 `peaks skill sync`。** 这次切片要的是一条**命令**,
142
+ 不是一个诊断。
143
+
144
+ ### 1. 商店的陈旧必须**可检测**,也必须**可修复**
145
+
146
+ - 此前:`~/.peaks/skills/<name>.peaks-managed` 这个 sidecar **只记了来源路径**,不记版本。
147
+ 归属靠"sidecar 在不在"判定,刷新靠**逐字节比对**。没有版本 ⇒ 陈旧**不可知** ——
148
+ 安装器不知道、`peaks doctor` 不知道、用户不知道。
149
+ - 现在:sidecar 记**两个事实** —— 来源路径 **和** 产出这份副本的**包版本**(一行 JSON)。
150
+ **旧格式仍然读得动**:只有路径的老 sidecar 解析成"是我们的,但版本未知",而**版本未知即陈旧**
151
+ (当前来源才是权威)—— 一个会在旧格式上抛错的读取器会**弄坏每一个已存在的安装**。
152
+ - 陈旧现在**按版本**判定,不只按字节。所以**记录的路径已经失效**(npm 全局前缀换了)但版本落后时,
153
+ 照样刷新;而路径失效、版本却对得上时,**不重拷**,只**订正 marker** ——
154
+ 一条指向已经不存在的路径的 marker,本身就是一条陈旧的事实。
155
+ - **用户自己写的那份仍然受保护**:**没有 marker** 的商店条目**永远不会被覆盖**。
156
+ - **doctor 检查** `skills:store-version:store` 比的是**商店记录的版本 ↔ 已安装包的版本**,
157
+ **永远只出一行**:落后=红并给出补救命令 `peaks skill sync`;当前=绿并**同时写出两个版本**;
158
+ 没有商店=绿且只是"无可比较"(没有商店的机器不是坏机器);读不出来=红、severity `warning`。
159
+ **它只读,不写。**
160
+ - **修复命令**是 `peaks skill sync`。它对 legacy、v2、以及**路径已经失效**的 marker **一律能修**。
161
+
162
+ ### 2. 为什么已有的那条检查看不见它(这一条比修复本身更值得记)
163
+
164
+ `skills:reference-parity` 检查的名字里就写着下游那个形状,它比对的是**商店 ↔ IDE 树**。
165
+ 但那台机器上 `~/.claude/skills/peaks-code` 是**指向商店的软链** —— 两棵树**是同一棵树**,
166
+ 永远"一致"。**一份冻结在旧版本的商店是完全自洽的**,所以 parity 检查永远沉默。
167
+ **store↔IDE 的一致性看不见 store↔package 的陈旧** —— 这是两个不同的轴,此前只有一个。
168
+ 新加的那条检查在**另一个轴**上,它**不是** parity 检查的替代品。
169
+
170
+ ### 3. 同样这一类:门禁说的和门禁做的不一致
171
+
172
+ - **`peaks hooks install --help`** 描述了一个命令**早就不做**的效果:`--no-progress`
173
+ 说自己会"跳过 progress-start 那个 PreToolUse 条目",而**父命令自己的描述**说那个条目
174
+ **早已不再安装**(slice #014)。这个参数被穿了四层、最终进到一个**下划线开头、根本没被读**的参数里。
175
+ 它的帮助文本还**没提**全局安装会往用户全局的 `~/.claude/skills/peaks-code/hooks/` 里拷两个脚本 ——
176
+ 下游那台机器正是跑过这条命令的机器。
177
+ - **`build-integrity`**:零个带 `.ts` 源码的包,会打出和"核对了二十个包"**一模一样**的
178
+ `build-integrity: OK`。空集是**合法的**,所以**退出码仍然是 0**;变的是**那句话**,而且它
179
+ **刻意不含那个全清字符串** —— `build-integrity: OK (nothing to check)` 仍然**包含**
180
+ `build-integrity: OK`,而那正是这条切片要防的"读平了"。
181
+ - **提交门**:本次之前,同一个切片里有**三个**文件**带着未格式化**的状态进了 commit,
182
+ 而**提交时跑的每一个门都是绿的**;是**推送门**把它们拦下来的。原因是
183
+ `lint-staged` 把 `tests/**` 当作"在 lint scope 之外"**直接丢掉了**。
184
+ 现在提交门多了一条**宽格式腿**:scope 之外但在宽 glob 之内的**已暂存**文件不干净就**拒**,
185
+ 并**点名文件与确切的修法**。
186
+ **宽检查的基线集合是空的**(债在 2026-10-17 收干净了),所以这条规则字面上就是
187
+ "**不许有未格式化的文件**",**不需要逐文件的基线行** —— 它和提交门那条**逐文件棘轮**
188
+ 是**两种**机制,owner 2026-10-03 的 lint scope 决定**没有被重开**,eslint 腿**也没有被放宽**。
189
+ - **叶子代理的临时目录**不再依赖 cwd:派发提示里现在**机器注入**一块绝对路径的说明 ——
190
+ 和 Karpathy 那一块**同一个机制**("一个忙起来会忘掉的义务不是执行器")。
191
+ 路径是 `<projectRoot>/.peaks/_runtime/<sid>/<role>/scratch/`,且用**正斜杠** ——
192
+ 因为反斜杠对 POSIX shell 是转义字符,`> D:\repo\x.log` 在那里写的是 `D:repox.log`,
193
+ **就落在 cwd 里**。**那正是这个泄漏本身,被"修"出来时的形状。**
194
+ - **auto-compact 的延后**此前**在生产里从来没有触发过**:探针被喂了空的图(`graphs: []`),
195
+ 即使有图也**不可能**满足 —— 它要的是 `status === 'running'` **且**带心跳的节点,
196
+ 而图的三处写入方**从不**产出这两样。现在延后读**派发账本**(owner 2026-10-22 裁定:
197
+ 账本是唯一真相源),"在飞"= **未终态且新鲜**,新鲜度复用既有的 30 分钟阈值(**没有重复一个常量**)。
198
+ **六种"不知道"全部延后**:账本读不出、记录读不出、状态不认识、新鲜度解析不出、
199
+ 记录版本不认识、记录越出账本。
200
+ - **`.sh` 兄弟实现**(Code-Gate 的那份)现在是 **Node 命令的薄壳**:找 CLI(`PATH` 上的 `peaks`,
201
+ 否则安装器写在旁边的包根指针),`exec` 过去,子进程继承 stdin —— 载荷**原样**抵达,薄壳**不读**它。
202
+ - **`peaks skill sync --dry-run`** 以前**会建目录**,还会报"装了 184 个符号链接"——而它一个链接都没建。
203
+ 现在 dry run **什么都不写**,报 0。
204
+
205
+ ### 4. 被有意接受的取舍(写在这里以免看起来像疏漏)
206
+
207
+ - **兄弟实现的 fallback 路径**(**没有 CLI 可达**的那种情形)**仍然是第二份实现**,仍然带着 bash 规则,
208
+ 仍然和命令在 **336 行矩阵里的 130 行**上分歧:**116 行误拒**(fallback 自己的拒绝)与
209
+ **14 行偏放行**(全是同一种形状:项目内的**绝对路径** —— fallback 没有 payload 自己拼写下的项目根,
210
+ **无法相对化**)。那 14 行**既有的、未变的**,而且**薄壳委派时它不存在**。
211
+ **更便宜也更诚实的修法没有被采纳**(把 fallback 变成**一律拒绝**就能关掉那 14 行、
212
+ 让"一份实现"字面为真),代价是**在一台没有 Node CLI 的机器上拒绝一切编辑**。
213
+ **这是 owner 的取舍,留着。**
214
+ - **doctor 的一条检查"干净时不说一声"这件事没有在本版修**。`compareSkillReferenceParity`
215
+ 在完全一致时返回 `[]` —— 没有"干净"这一行,所以报告**分不清**"跑了、没发现问题"和"根本没跑"。
216
+ 本机实测:`peaks doctor --json` 出了 **88 条检查,没有一条**带 `skills:` 前缀。
217
+ 改**所有**检查的报告形状是另一件事(另一个决定、另一条切片),**不在本次**;
218
+ 本次新增的商店版本检查**干净时会出一行**。
219
+ - **`--no-progress` 没有被删掉**:它是已发布的 CLI 表面,删是破坏性变更。
220
+ 这次只把它的帮助文本**改成它实际的样子**,并用一条测试把这个事实**钉住**
221
+ (`resolveHookEntries` 两种参数返回**同一组**条目 —— 将来谁给它加上效果,那条测试会红)。
222
+ - **auto-compact 延后的"不知道就延后"是**没有时间上限**的**(+6 个月仍然如此),
223
+ 只有红线或 6 小时回收器能解开它;**三档阈值一个数字没动**,变的是**延后真的会触发**。
224
+ - **本版找到了 `diff-proj-*` 那些残留的来源,而它不是一段签进来的测试**:`diff-proj` 这个字符串在
225
+ `src/`、`scripts/`、`tests/`、`.husky/` 里**一处都没有**,那些 fixture 的 `link` 是一个指向
226
+ MSYS 风格 `/d/projects/peaks-loop/...` 的 POSIX 软链 ⇒ 是**上一轮会话里一条临时 bash 命令**,
227
+ 从仓库根按 **cwd 相对**路径写进去的。**这恰恰是本切片要治的那个习惯本身** —— 比任何测试都更有
228
+ 力地说明"规则必须机器注入"。
229
+ 那一类才是主题;找到那一个测试是另一条请求。
230
+
231
+ ### 5. 验证
232
+
233
+ - **每个切片的 QA 判决**:技能商店的版本可检测性 `pass-with-notes`;D-1(宽格式腿)
234
+ `pass-with-notes`;§2.18(nothing-to-check)`pass`;§2.31(scratch 路径块)`pass-with-notes`;
235
+ D-3(hook 帮助文本)`pass-with-notes`;§20(ledger 延后)`pass-with-notes`;
236
+ §19.1(薄壳)`pass-with-notes`,**外加一条被点名的 finding**。
237
+ - **每一条天花板都没有涨**:eslint 1696/1700、错误 560/561、prettier 0、tsc 0、
238
+ 注释死引用 0、叙述行 22/22、文件尺寸 77/77 与 21935/21935、静默告警 44/44 与 60/60。
239
+ - **商店那条**:owner 的形状被**原样重建并修好** —— legacy marker + 旧字节 + 删掉的
240
+ `references/fast-lane-norm.md` ⇒ `peaks doctor` **点名了它**("2 of 23 … peaks-code (no version recorded)")
241
+ ⇒ `peaks skill sync` ⇒ 文件回来了、`SKILL.md` 是当前的、marker 变成 v2(记着当时的包版本 4.1.17)。
242
+ **用户自己写的那一份 survived**(没有 marker 的条目**没有被覆盖**,也**没有被塞进 sidecar**,
243
+ 并且被报成"没有动它")。doctor 检查**永远只出一行**,**没有继承** parity 检查"干净时不出声"的形状。
244
+ 该切片动过的文件里 **0** 个失败。
245
+ - **§20 的延后现在真的会在生产里触发**(对着真 CLI 端到端量过):ledger 1 分钟 ⇒
246
+ `"decision": "in-flight-batch"`;31 分钟 ⇒ 照常压缩;没有 ledger ⇒ 照常压缩;
247
+ **读不出来的 ledger ⇒ 也延后**(安全方向);红线 0.96 仍然压过一切。
248
+ reader 热态成本 **2.03 ms**(5 条记录的会话上)。
249
+ - **§19.1 的差分**:**薄壳委派与 Node 命令 0 行分歧**(一份实现,结构上不可能分歧)。
250
+ **fallback 与命令的分歧**:**336 行矩阵里的 130 行**(116 误拒 + 14 偏放行);
251
+ QA 另在 **448 行**上重新导出 **15** 行偏放行 —— **同一种形状**,**既有**,**没有一行是回归**。
252
+ **仍然开着的一条残留,而且被直接量过**:`file_path = <root>/src/x.ts` ⇒ **Node 命令 deny**
253
+ (`data.action = deny`)、**fallback allow**(exit 0)—— fallback 没有 payload 自己拼写下的项目根,
254
+ **无法相对化一个绝对路径**。**既有残留**,且**只在 fallback 路径上**。记在 backlog §19.2 与安全审计里,
255
+ **没有当作已修**。
256
+ - **§19.1 的 QA 找到一条 finding,并且它推翻了刚刚重发的安全审计里的一句话**:fallback 的 payload
257
+ 扫描当时是 `grep -oE '"cwd":…' | head -n1`,扫的是**整个** payload,所以一个**嵌套**的 `cwd` 键会
258
+ 抢到首次匹配 —— 此时 fallback **不拒绝**,按 `$PWD` 读,于是**放行**了 Node 命令**拒绝**的文件。
259
+ 这与文件自己的注释和审计摘要里的断言**矛盾**(那句断言说 fallback 现在"拒绝而不是猜")。
260
+ **洞是既有的、只在 Mode 2 上、且可达性很窄**(Claude Code 的 Edit/Write/MultiEdit 的 `input`
261
+ 里没有 `cwd`)。**本次修掉了**:扫描换成一段**带深度感知**(认识字符串和花括号)的 `awk`,
262
+ 读**顶层**的 `tool_name`/`tool`/`cwd` 与 `tool_input`/`input` 里的
263
+ `file_path`/`path`/`notebook_path`;**读不懂的 payload(括号不平衡、值里带换行)一律拒绝**。
264
+ **编排器直接对着当前代码量过**:Node 命令拒,fallback 现在也拒。**审计因此又重发了一次** ——
265
+ **审计不是最后一句话**。
266
+ - **BDD 测试风格契约**(本仓库有检查器,但**没有 CI 门**):本次动过的测试文件里 **21 个**不合规,
267
+ 拆开是 **11 个在 HEAD 上就已经不合规**(本次**没有引入**那份债,记在 backlog §21.9 里
268
+ 作为另一条更大的改动)**和 12 个本次新增的**,那 12 个本次全部改到合规。
269
+ - **lint scope 的影子(`scripts/` + `tests/`)**的文件数从 818 涨到 842 —— 按 owner 2026-10-03 的决定,
270
+ **影子目录是豁免的**,所以这条**不是** finding。
271
+
3
272
  ## 4.1.17 — 2026-10-22(相对路径按它**在哪个目录**判,不按它**怎么拼写**判)
4
273
 
5
274
  **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次是**纯修复**:
package/README-en.md CHANGED
@@ -80,6 +80,12 @@ Other slash commands you'll reach for:
80
80
 
81
81
  No CLI to memorize. No manifest to hand-author. No second terminal to open. **Send the slash, the rest is on it.**
82
82
 
83
+ > **How much more does this download?** This version ships the mutation-testing engine
84
+ > (`@stryker-mutator/core` + `@stryker-mutator/vitest-runner`) as a **runtime dependency**, so the install
85
+ > pulls the stryker engine closure — **about 2.66 MB (9 packages)** more. The vitest family's 5.30 MB is only
86
+ > auto-installed **if your machine does not have vitest yet**, and any project that runs `peaks mut` already
87
+ > has vitest. **In one line: installing peaks-loop downloads about 2.7 MB more.**
88
+
83
89
  ---
84
90
 
85
91
  ## Where files land after install
package/README.md CHANGED
@@ -75,6 +75,11 @@ npm i -g peaks-loop
75
75
 
76
76
  不需要记 CLI、不需要写 manifest、不需要切到第二个终端。**斜杠命令一发,后面的活它替你跑完。**
77
77
 
78
+ > **装这个包会多下载多少?** 这一版把变异测试引擎(`@stryker-mutator/core` +
79
+ > `@stryker-mutator/vitest-runner`)作为**运行时依赖**带上了 —— 消费者的安装会多出 stryker 引擎闭包
80
+ > **约 2.66 MB(9 个包)**。vitest 家族那 5.30 MB **只在你的机器上还没有 vitest 时**才会被自动装上,
81
+ > 而要跑 `peaks mut` 的项目**必然已经有 vitest**。**一句话:你装 peaks-loop 多下载了约 2.7 MB。**
82
+
78
83
  ---
79
84
 
80
85
  ## 装上以后,文件放在哪
@@ -28,11 +28,20 @@ MUST follow the given-when-then shape.
28
28
 
29
29
  ### 1.1 Description (the `it()` / `test()` string-literal)
30
30
 
31
- - **Form**: `when X, should Y` — state the precondition in the `when`
32
- clause and the observable outcome in the `should` clause.
33
- - **Required word**: must include at least one of `when` or `should`.
34
- (`when` alone is the precondition; `should` alone is the outcome;
35
- the natural-language form combines both.)
31
+ - **Preferred form (idiomatic — a preference, NOT a requirement)**:
32
+ `when X, should Y` — state the precondition in the `when` clause and the
33
+ observable outcome in the `should` clause. New tests SHOULD read this way,
34
+ because it names the precondition and the outcome in one sentence. Writing
35
+ only `when`, or only `should`, is ALLOWED; writing both is RECOMMENDED, never
36
+ required.
37
+ - **Enforced rule (the only rule a checker enforces)**: the description MUST
38
+ include at least one of `when` or `should`. This is exactly what the
39
+ verifier runs: `hasWhenOrShould` in
40
+ `src/services/qa/bdd-test-style-contract.ts` matches
41
+ `/(\bwhen\b|\bshould\b)/i`, and a description that contains neither fails
42
+ with the reason code `description-no-should-when`. A description carrying
43
+ only `when`, or only `should`, PASSES this rule — the checker never asks for
44
+ both.
36
45
  - **Anti-pattern**: do NOT use legacy `// arrange:` / `// act:` /
37
46
  `// assert:` markers anywhere in the test body.
38
47
 
@@ -7,6 +7,7 @@
7
7
  */
8
8
  import { fail, ok } from 'peaks-loop-shared/result';
9
9
  import { runRedLinesAudit } from '../../services/audit/red-lines-service.js';
10
+ import { withRootScratchFindings } from '../../services/audit/enforcers/root-scratch-artifacts.js';
10
11
  import { getErrorMessage, printResult } from '../cli-helpers.js';
11
12
  import { PROJECT_PATH_HINT, SCANNER_HINT, validateProjectRoot } from './audit-command-shared.js';
12
13
  import { emptyRedLineAudit } from './audit-refusal-data.js';
@@ -33,7 +34,11 @@ export function runRedLines(options, io) {
33
34
  }
34
35
  try {
35
36
  const result = runRedLinesAudit({ projectRoot: validation.projectRoot });
36
- const envelope = ok('audit.red-lines', result.audit, result.warnings.map((w) => `${w.file}: ${w.message}`), redLinesNextActions(result.audit));
37
+ // The root scratch sweep rides in this envelope: a capture at the project
38
+ // root is the shape that reaches a commit, because a tracked file leaves
39
+ // `git status` clean and no other gate reads it.
40
+ const audit = withRootScratchFindings(result.audit, validation.projectRoot);
41
+ const envelope = ok('audit.red-lines', audit, result.warnings.map((w) => `${w.file}: ${w.message}`), redLinesNextActions(audit));
37
42
  printResult(io, envelope, options.json);
38
43
  }
39
44
  catch (error) {
@@ -0,0 +1,42 @@
1
+ import { type ProgramIO } from '../cli-helpers.js';
2
+ export declare function bestPracticeDir(projectRoot: string): string;
3
+ /** `<project>/best-practice/<date>-<slug>.md`. The slug is lossy by design:
4
+ * every character outside `[A-Za-z0-9_-]` collapses to `-` and the result is
5
+ * truncated to 32, so no intent can introduce a path separator. */
6
+ export declare function scanArtifactPath(projectRoot: string, slugSource: string): string;
7
+ export declare function intentIdLine(intent: string): string;
8
+ /** The intent the artifact at `path` was written for, or null when it records
9
+ * none (an artifact written before this marker existed) or cannot be read.
10
+ *
11
+ * Only the FIRST line is read, and the marker is always written first, so a
12
+ * caller-supplied intent cannot forge a match by putting a marker of its own
13
+ * into the text it carries. */
14
+ export declare function readArtifactIntentId(path: string): string | null;
15
+ /**
16
+ * The collision §12.3 recorded: the artifact path keys on `(date, slug)` and
17
+ * the slug is capped at 32 characters, so two intents that agree in their
18
+ * first 32 slug characters land on one file and the second silently overwrote
19
+ * the first one's recommendation.
20
+ *
21
+ * The same intent again is NOT a collision — it is the same scan re-running,
22
+ * and it overwrites as it always did. An artifact this command cannot
23
+ * attribute is treated as another intent's: the refusal is unconditional,
24
+ * because an artifact that cannot be named cannot be cleared.
25
+ */
26
+ export type SlugCollision = {
27
+ readonly project: string;
28
+ readonly intent: string;
29
+ readonly language: string;
30
+ readonly artifactPath: string;
31
+ readonly existingIntent: string | null;
32
+ };
33
+ /** The collision a scan would cause, or null when it would cause none. */
34
+ export declare function detectSlugCollision(project: string, intent: string, language: string): SlugCollision | null;
35
+ export declare const SLUG_COLLISION_MESSAGE: string;
36
+ /**
37
+ * Refuse a scan whose artifact path is already owned by another intent.
38
+ *
39
+ * Nothing is rendered: the refusal is the whole answer, exactly as the
40
+ * synthetic and no-fragments refusals are.
41
+ */
42
+ export declare function emitSlugCollisionRefusal(io: ProgramIO, asJson: boolean, collision: SlugCollision): void;
@@ -0,0 +1,115 @@
1
+ /**
2
+ *
3
+ * The best-practice-scan artifact path, the record of which intent owns it,
4
+ * and the refusal that replaced a silent overwrite (§12.3).
5
+ *
6
+ * The path keys on `(date, slug)` and the slug is capped at 32 characters, so
7
+ * two different intents can land on one file. Before this, the second scan
8
+ * silently overwrote the first one's recommendation and both exited 0 — one
9
+ * scan's result was lost, with no error and no warning.
10
+ *
11
+ * The behaviour implemented here is ONE: the second scan REFUSES, naming the
12
+ * collision. The path scheme itself is unchanged, so a scan that collides with
13
+ * nothing still writes exactly where it wrote before.
14
+ *
15
+ * To tell "the same intent again" from "a different intent that landed on the
16
+ * same path", every artifact this command writes starts with an intent-id
17
+ * marker: the exact intent, JSON-encoded, on the first line. The marker is
18
+ * always written FIRST, so a caller-supplied intent cannot forge a match by
19
+ * putting a marker of its own into the text it carries.
20
+ */
21
+ import { closeSync, existsSync, openSync, readSync } from 'node:fs';
22
+ import { join } from 'node:path';
23
+ import { fail } from 'peaks-loop-shared/result';
24
+ import { printResult } from '../cli-helpers.js';
25
+ export function bestPracticeDir(projectRoot) {
26
+ return join(projectRoot, 'best-practice');
27
+ }
28
+ /** `YYYY-MM-DD` is 10 characters, and the slug is capped at 32 so the filename
29
+ * stays a filename. Both are part of the pinned artifact path. */
30
+ const ISO_DATE_LENGTH = 10;
31
+ const SLUG_MAX_LENGTH = 32;
32
+ /** `<project>/best-practice/<date>-<slug>.md`. The slug is lossy by design:
33
+ * every character outside `[A-Za-z0-9_-]` collapses to `-` and the result is
34
+ * truncated to 32, so no intent can introduce a path separator. */
35
+ export function scanArtifactPath(projectRoot, slugSource) {
36
+ const dateStr = new Date().toISOString().slice(0, ISO_DATE_LENGTH);
37
+ const slug = slugSource.replace(/[^a-zA-Z0-9_-]+/g, '-').slice(0, SLUG_MAX_LENGTH) || 'intent';
38
+ return join(bestPracticeDir(projectRoot), `${dateStr}-${slug}.md`);
39
+ }
40
+ /** The first line of every artifact this command writes: the exact intent,
41
+ * JSON-encoded. It is what tells "the same intent again" from "a different
42
+ * intent that landed on the same path". */
43
+ const INTENT_ID_PREFIX = '<!-- peaks-intent-id: ';
44
+ const INTENT_ID_SUFFIX = ' -->';
45
+ /** An intent longer than this cannot be read back; such an artifact is unattributable. */
46
+ const INTENT_ID_READ_LIMIT = 65_536;
47
+ export function intentIdLine(intent) {
48
+ return `${INTENT_ID_PREFIX}${JSON.stringify(intent)}${INTENT_ID_SUFFIX}`;
49
+ }
50
+ /** The intent the artifact at `path` was written for, or null when it records
51
+ * none (an artifact written before this marker existed) or cannot be read.
52
+ *
53
+ * Only the FIRST line is read, and the marker is always written first, so a
54
+ * caller-supplied intent cannot forge a match by putting a marker of its own
55
+ * into the text it carries. */
56
+ export function readArtifactIntentId(path) {
57
+ const fd = openSync(path, 'r');
58
+ try {
59
+ const buffer = Buffer.alloc(INTENT_ID_READ_LIMIT);
60
+ const read = readSync(fd, buffer, 0, INTENT_ID_READ_LIMIT, 0);
61
+ const firstLine = buffer.subarray(0, read).toString('utf8').split('\n')[0] ?? '';
62
+ if (!firstLine.startsWith(INTENT_ID_PREFIX) || !firstLine.endsWith(INTENT_ID_SUFFIX)) {
63
+ return null;
64
+ }
65
+ const encoded = firstLine.slice(INTENT_ID_PREFIX.length, firstLine.length - INTENT_ID_SUFFIX.length);
66
+ let decoded;
67
+ try {
68
+ decoded = JSON.parse(encoded);
69
+ }
70
+ catch {
71
+ // A marker that cannot be parsed is a marker that cannot be trusted:
72
+ // `decoded` stays null, so the caller gets "no usable marker" and the
73
+ // refusal stays fail-closed.
74
+ decoded = null;
75
+ }
76
+ return typeof decoded === 'string' ? decoded : null;
77
+ }
78
+ finally {
79
+ closeSync(fd);
80
+ }
81
+ }
82
+ /** The collision a scan would cause, or null when it would cause none. */
83
+ export function detectSlugCollision(project, intent, language) {
84
+ const primary = scanArtifactPath(project, intent);
85
+ if (!existsSync(primary))
86
+ return null;
87
+ const existingIntent = readArtifactIntentId(primary);
88
+ if (existingIntent === intent)
89
+ return null;
90
+ return { project, intent, language, artifactPath: primary, existingIntent };
91
+ }
92
+ export const SLUG_COLLISION_MESSAGE = 'best-practice-scan: SLUG COLLISION — this scan would overwrite an artifact that ' +
93
+ 'belongs to another intent, so nothing was written and nothing was overwritten. The ' +
94
+ 'artifact path keys on (date, slug) and the slug is capped at 32 characters, so two ' +
95
+ 'intents that agree in their first 32 slug characters land on one file.';
96
+ /**
97
+ * Refuse a scan whose artifact path is already owned by another intent.
98
+ *
99
+ * Nothing is rendered: the refusal is the whole answer, exactly as the
100
+ * synthetic and no-fragments refusals are.
101
+ */
102
+ export function emitSlugCollisionRefusal(io, asJson, collision) {
103
+ printResult(io, fail('best-practice.scan', 'BEST_PRACTICE_SCAN_SLUG_COLLISION', SLUG_COLLISION_MESSAGE, {
104
+ project: collision.project,
105
+ intent: collision.intent,
106
+ language: collision.language,
107
+ artifactPath: collision.artifactPath,
108
+ existingIntent: collision.existingIntent,
109
+ collision: true,
110
+ step25: 'skipped-slug-collision'
111
+ }, [
112
+ 'Reword the intent so its first 32 slug characters differ, or delete the artifact that already owns the path',
113
+ `Existing artifact: ${collision.artifactPath}`
114
+ ]), asJson);
115
+ }
@@ -29,6 +29,11 @@
29
29
  * (`BEST_PRACTICE_SCAN_NO_FRAGMENTS` — see `emitNoFragmentsRefusal`, which is
30
30
  * the guard against a `★` recommendation built from zero fragments).
31
31
  *
32
+ * Collision refusal: the artifact path keys on `(date, slug)` with the slug
33
+ * capped at 32 characters, so two intents that agree in their first 32 slug
34
+ * characters land on one file. The second scan refuses
35
+ * (`BEST_PRACTICE_SCAN_SLUG_COLLISION`) rather than overwrite the first.
36
+ *
32
37
  * Catch-gate (spec §7): the command emits a 3-line prompt asking the
33
38
  * user to ack / pick alt / reject + reason. The gate is read from
34
39
  * stdin via `PEAKS_BEST_PRACTICE_STDIN` (test seam) or the real stdin
@@ -3,24 +3,9 @@ import { fail, ok } from 'peaks-loop-shared/result';
3
3
  import { detectLanguage } from '../../services/best-practice/language-detector.js';
4
4
  import { scanBestPractice } from '../../services/best-practice/scan-orchestrator.js';
5
5
  import { findForbiddenTokens, formatOutputTable } from '../../services/best-practice/output-formatter.js';
6
- import { CATCH_GATE_PROMPT, emitNoFragmentsRefusal, INTENT_REQUIRED_MESSAGE, renderSyntheticRefusal, scanArtifactPath, SYNTHETIC_SOURCE_MESSAGE, writeRefusal, writeRenderedArtifact } from './best-practice-scan-helpers.js';
6
+ import { CATCH_GATE_PROMPT, emitNoFragmentsRefusal, INTENT_REQUIRED_MESSAGE, readUserInput, renderSyntheticRefusal, SYNTHETIC_SOURCE_MESSAGE, writeRefusal, writeRenderedArtifact } from './best-practice-scan-helpers.js';
7
+ import { detectSlugCollision, emitSlugCollisionRefusal, scanArtifactPath } from './best-practice-scan-collision.js';
7
8
  import { readLookupResultsOrFail } from './best-practice-scan-lookup-results.js';
8
- async function readUserInput() {
9
- const override = process.env.PEAKS_BEST_PRACTICE_STDIN;
10
- if (override !== undefined)
11
- return override;
12
- if (process.stdin.isTTY)
13
- return '';
14
- return new Promise((resolveStdin) => {
15
- let data = '';
16
- process.stdin.setEncoding('utf8');
17
- process.stdin.on('data', (chunk) => {
18
- data += chunk;
19
- });
20
- process.stdin.on('end', () => resolveStdin(data.trim()));
21
- process.stdin.on('error', () => resolveStdin(data.trim()));
22
- });
23
- }
24
9
  export function parseCatchGateReply(raw, recommended) {
25
10
  const trimmed = raw.trim();
26
11
  if (trimmed.length === 0) {
@@ -117,6 +102,12 @@ export function registerBestPracticeScanCommand(program, io) {
117
102
  process.exitCode = 1;
118
103
  return;
119
104
  }
105
+ const collision = detectSlugCollision(opts.project, intent, language);
106
+ if (collision !== null) {
107
+ emitSlugCollisionRefusal(io, opts.json === true, collision);
108
+ process.exitCode = 1;
109
+ return;
110
+ }
120
111
  const recommendation = scan.results.length > 0 ? 'A' : 'B';
121
112
  const reasoning = `基于调用方提供的 ${scan.fragments.length} 个 ${scan.source} 文档片段` +
122
113
  `(URL 由调用方构造,Context7 响应不含 URL);` +
@@ -150,7 +141,7 @@ export function registerBestPracticeScanCommand(program, io) {
150
141
  commitFlag: opts.commit === true,
151
142
  forbiddenHits
152
143
  };
153
- writeRenderedArtifact(artifactPath, table, payload);
144
+ writeRenderedArtifact(artifactPath, table, payload, intent);
154
145
  printResult(io, ok('best-practice.scan', payload, forbiddenHits.length > 0 ? [`forbidden tokens present: ${forbiddenHits.join(', ')}`] : [], [`Artifact written to ${artifactPath}`, `catch-gate outcome: ${outcome.kind}`]), opts.json === true);
155
146
  }
156
147
  catch (err) {
@@ -2,11 +2,14 @@ import { type ProgramIO } from '../cli-helpers.js';
2
2
  export declare const CATCH_GATE_PROMPT: string;
3
3
  export declare const INTENT_REQUIRED_MESSAGE: string;
4
4
  export declare const SYNTHETIC_SOURCE_MESSAGE: string;
5
- export declare function bestPracticeDir(projectRoot: string): string;
6
- /** `<project>/best-practice/<date>-<slug>.md`. The slug is lossy by design:
7
- * every character outside `[A-Za-z0-9_-]` collapses to `-` and the result is
8
- * truncated to 32, so no intent can introduce a path separator. */
9
- export declare function scanArtifactPath(projectRoot: string, slugSource: string): string;
5
+ /**
6
+ * The catch-gate reply: the `PEAKS_BEST_PRACTICE_STDIN` seam in tests, the
7
+ * real stdin in production.
8
+ *
9
+ * Moved here from the command file: that file had three lines of headroom
10
+ * under the 300-line cap, and the collision check needed more than that.
11
+ */
12
+ export declare function readUserInput(): Promise<string>;
10
13
  /** Refusal body for a synthetic scan. It is written to the artifact path so
11
14
  * the skip survives the fire-and-forget caller (`best-practice-auto-trigger`
12
15
  * spawns with `stdio: 'ignore'`, so stdout never reaches anyone). */
@@ -39,8 +42,11 @@ export declare function writeRefusal(projectRoot: string, intent: string, refusa
39
42
  * payload is proved to serialise *before* anything is written: a payload the
40
43
  * printer cannot render must not leave behind an artifact claiming a scan that
41
44
  * never reported.
45
+ *
46
+ * The first line is the intent-id marker, so a later scan can tell which
47
+ * intent owns this artifact.
42
48
  */
43
- export declare function writeRenderedArtifact(artifactPath: string, table: string, payload: unknown): void;
49
+ export declare function writeRenderedArtifact(artifactPath: string, table: string, payload: unknown, intent: string): void;
44
50
  export declare const NO_FRAGMENTS_MESSAGE: string;
45
51
  /**
46
52
  * Refuse a scan that resolved against real lookups and still found nothing.