peaks-loop 4.1.23 → 4.1.25

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 (66) hide show
  1. package/.claude-plugin/marketplace.json +12 -2
  2. package/CHANGELOG.md +188 -0
  3. package/dist/cli/commands/code-auto-compact-command.js +19 -1
  4. package/dist/cli/commands/code-gate-step-08-command.js +103 -105
  5. package/dist/cli/commands/code-gate-step-08-remedy.d.ts +10 -2
  6. package/dist/cli/commands/code-gate-step-08-remedy.js +11 -3
  7. package/dist/cli/commands/gate-commands-enforce.d.ts +14 -8
  8. package/dist/cli/commands/gate-commands-enforce.js +31 -24
  9. package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
  10. package/dist/cli/commands/observability-commands-session-row.js +201 -0
  11. package/dist/cli/commands/observability-commands.js +2 -0
  12. package/dist/services/artifacts/prerequisite-path-census.d.ts +8 -3
  13. package/dist/services/artifacts/prerequisite-path-census.js +30 -9
  14. package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
  15. package/dist/services/hooks/output.d.ts +35 -1
  16. package/dist/services/hooks/output.js +39 -1
  17. package/dist/services/observability/aggregation.js +2 -1
  18. package/dist/services/observability/hotspot-shared.d.ts +7 -12
  19. package/dist/services/observability/hotspot-shared.js +18 -13
  20. package/dist/services/observability/near-miss-difference.js +4 -1
  21. package/dist/services/observability/near-miss.js +9 -2
  22. package/dist/services/observability/owner-skill-map.js +23 -3
  23. package/dist/services/observability/repair-cycle-metric.js +6 -3
  24. package/dist/services/skills/presence-role.js +9 -2
  25. package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
  26. package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
  27. package/dist/shared/incrementing-number.d.ts +57 -0
  28. package/dist/shared/incrementing-number.js +13 -0
  29. package/dist/skills/peaks-maker/index.js +43 -30
  30. package/output-styles/peaks-skill-swarm.md +2 -2
  31. package/package.json +7 -6
  32. package/scripts/install-skills-bundles.mjs +6 -1
  33. package/scripts/install-skills.mjs +10 -1
  34. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  35. package/skills/bee/peaks-prd/SKILL.md +1 -1
  36. package/skills/bee/peaks-qa/SKILL.md +1 -1
  37. package/skills/bee/peaks-rd/SKILL.md +1 -1
  38. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  39. package/skills/bee/peaks-sc/SKILL.md +1 -1
  40. package/skills/bee/peaks-security-audit/SKILL.md +1 -1
  41. package/skills/bee/peaks-txt/SKILL.md +1 -1
  42. package/skills/bee/peaks-ui/SKILL.md +1 -1
  43. package/skills/peaks-audit/SKILL.md +1 -1
  44. package/skills/peaks-code/SKILL.md +1 -1
  45. package/skills/peaks-content/SKILL.md +1 -1
  46. package/skills/peaks-doctor/SKILL.md +1 -1
  47. package/skills/peaks-final-review/SKILL.md +1 -1
  48. package/skills/peaks-ide/SKILL.md +1 -1
  49. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  50. package/skills/peaks-maker/SKILL.md +125 -0
  51. package/skills/peaks-mut/SKILL.md +297 -0
  52. package/skills/peaks-race-code/SKILL.md +1 -1
  53. package/skills/peaks-resume/SKILL.md +1 -1
  54. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  55. package/skills/peaks-solo/SKILL.md +1 -1
  56. package/skills/peaks-sop/SKILL.md +1 -1
  57. package/skills/peaks-status/SKILL.md +1 -1
  58. package/skills/peaks-test/SKILL.md +1 -1
  59. package/skills/bee/peaks-prd/test-prompts.json +0 -12
  60. package/skills/bee/peaks-qa/test-prompts.json +0 -12
  61. package/skills/bee/peaks-rd/test-prompts.json +0 -12
  62. package/skills/bee/peaks-txt/test-prompts.json +0 -12
  63. package/skills/bee/peaks-ui/test-prompts.json +0 -12
  64. package/skills/peaks-code/test-prompts.json +0 -12
  65. package/skills/peaks-doctor/test_prompts.json +0 -17
  66. package/skills/peaks-sop/test-prompts.json +0 -17
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.23"
4
+ "version": "4.1.25"
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.23",
10
+ "version": "4.1.25",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
@@ -102,6 +102,16 @@
102
102
  "path": "./skills/peaks-issue-fix-orchestrator",
103
103
  "description": "End-to-end orchestrator that surveys open issues in a target repo, classifies them by difficulty, mines reference merged-PRs, fixes each issue with real commits (with Repository + AI-modified declaration), writes normalized PR description files, and emits a one-line submit script. Use when the user wants to drive a \"fix N open issues and prepare PRs\" run on an upstream repo (any language; primarily Python + TypeScript). Reuses Loop Engineering primitives: 4-layer asset model, Darwin ratchet, karpathy-engineered red lines, Human-NL-Choice-Only. Triggers on `/peaks-issue-fix-orchestrator`, \"fix 30 issues\", \"dogfood on <repo>\", \"open-issue sweep on <repo>\"."
104
104
  },
105
+ {
106
+ "name": "peaks-maker",
107
+ "path": "./skills/peaks-maker",
108
+ "description": "Sediment and SkillHub author. Use when the user describes — in natural language — intent to (a) capture a workflow as a reusable skill, (b) refine or clone an existing bee, (c) export / import a skill bundle, (d) retain a release for the local SkillHub, or (e) dispose a previous release. Intent-based, never keyword-based: \"调一下\", \"改改\", \"下次复用\" all map to the same concrete `peaks skill sediment …` verb. User never types CLI; peaks-maker runs it on the user's behalf."
109
+ },
110
+ {
111
+ "name": "peaks-mut",
112
+ "path": "./skills/peaks-mut",
113
+ "description": "Mutation testing + assertion validity scan for Peaks. Use when a workflow needs to catch test fake-green (coverage looks fine but tests do not actually exercise behavior). Runs Stryker mutants and a 5-pattern weak-assertion AST scan, then emits a hashable MUT.sig report that chains to TACT.sig."
114
+ },
105
115
  {
106
116
  "name": "peaks-perf-audit",
107
117
  "path": "./skills/bee/peaks-perf-audit",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,193 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.25 — 2026-10-29(授权与发布物)
4
+
5
+ **版本级别**:**patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何门禁的阈值或放行条件;
6
+ **没有**动事件 schema 的版本号(`schemaVersion` 仍是 `z.literal(1)`);**没有**改发布流程本身。
7
+
8
+ **一句话:这一版做两件事 —— 把一个每次 Bash 调用都在静默替你授权的钩子收回来,以及让**真正发布出去的包**不再夹带开发夹具。**
9
+ 两件都是「机制声称的和实际做的不是一回事」:前者声称「只是放行」,实际是**授予权限**;后者声称「已排除」,实际**在发布的那条路径上没排除**。
10
+
11
+ ### 1. 钩子不再替你授权
12
+
13
+ `peaks gate enforce --project "${CLAUDE_PROJECT_DIR}" --json` 是装在 `PreToolUse:Bash` 上的钩子,它此前在**每一次**调用上输出:
14
+
15
+ ```json
16
+ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow" }
17
+ ```
18
+
19
+ 按 Claude Code 的钩子契约,`permissionDecision` 不是「允许」,是**真实授权**:宿主批准该调用并**跳过你自己的权限确认**(你显式 deny 的规则仍然优先)。
20
+ 实测它在**每一条非空命令、且没有被任何门拦下的** Bash 调用上触发 —— 而那条 catch 是 fail-open 的,SOP 注册表读不出来时同样放行+授权。
21
+
22
+ **而这个授权从来就不需要。** 最初的报错是
23
+
24
+ ```
25
+ Hook JSON output validation failed — decision: Invalid option: expected one of "approve"|"block"
26
+ ```
27
+
28
+ 根因是**根级** `decision` 键;门自己的判定早就挪进 `data`(宿主不读那个键)。宿主读不到根级 `decision` 时,
29
+ **一个不带 `hookSpecificOutput` 的文档它就满意** —— 另外两个兄弟钩子(`gate-step-08`、`auto-compact`)一直如此,在真实会话里逐次运行、零宿主校验错误。
30
+
31
+ 于是三条允许路径(`emitAllowSkipped` / `emitAllowWorktree` / `emitSopAllow`)改为输出普通 CLI 信封,**不带 `hookSpecificOutput`**。
32
+ `buildAllowDocument` 与 `HOOK_ALLOW_DECISION` 被**删除**而不是留着不用 —— 一个只为发授权而存在的助手留在原地,就是下一切片的事故。
33
+ `data.decision` 仍是 `"allow"`:CLI 自己给下游工具的 `--json` 契约没有变。
34
+
35
+ **拒绝路径一字未动**:`emitBlock` 仍写 `permissionDecision: "deny"` + exit 2,而且拒绝**是因为判定而拒绝**(对照:同一 payload 给了授权后 exit 0 放行)。
36
+
37
+ 代码是**降**的:三条允许路径共用一个 helper(`gate-commands-enforce.ts` 292 → 277、`output.ts` 204 → 164)。
38
+
39
+ ### 2. 发布物不再夹带开发夹具
40
+
41
+ 4.1.24 的 tarball 里带着 **8 个 `test-prompts.json`**,其中一个内嵌一位开发者的本地路径与内部流程细节。
42
+ **QA 是从 registry 把 tarball 拉下来 grep 出来的** —— 这是实测暴露,不是推断。
43
+
44
+ | 打包器 | 修复前 | 修复后 |
45
+ |---|---|---|
46
+ | `npm pack --ignore-scripts` | 2959 文件 / **1** 个夹具 | 2958 / **0** |
47
+ | `pnpm pack`(**发布用的那个**) | 2966 文件 / **8** 个夹具 | 2958 / **0** |
48
+
49
+ **机制是 packlist 的版本差异。** `package.json#files` 写的是 `"skills/**"` 再用 `!skills/**/test-prompts.json` 减去。
50
+ npm 11 自己的 packlist 认这条 negation;**pnpm 10.11.0 内置的 npm-packlist 5.1.3 里,include 胜过 negation** ——
51
+ 而 `scripts/release-pack.mjs` 用 pnpm 打包,所以这条规则**只在真正要紧的地方失效**。
52
+ 而 negation **本来也盖不住第八个**:`skills/peaks-doctor/test_prompts.json` 是**下划线**命名,它在**每一种**清单里都发货。
53
+
54
+ 修法是**正面点名该发什么**,而不是让两个打包器对 negation 的解释一致:`"skills/**/!(*test[-_]prompts*).*"`,
55
+ 外加 `"!skills/**/test_prompts.json"`。原有的 negation **保留** —— QA 实测 `!skills/**/.DS_Store` 在 pnpm 下是**承重的**(npm 靠 `.npmignore`/`.gitignore` 也会丢它)。
56
+
57
+ **修完之后两个打包器产出字节一致的清单**,与 4.1.24 逐文件对比:**只少那 8 个夹具、零新增、零误删**;
58
+ `git ls-files skills/` 减去那 8 个,恰好等于 tarball 里的 `skills/`。
59
+
60
+ ### 3. tarball 第一次有了验收测试
61
+
62
+ 新测试断言的是**产物**而不是清单:它用**两个**打包器**真打** tarball 并读出条目,断言三件事 ——
63
+ 任一 tarball 不含夹具;**每个受跟踪的非夹具 `skills/` 文件仍在**(防止排除吃掉别的);两个打包器**一致**。
64
+
65
+ **断言 `package.json` 里的字符串正是让这个缺陷溜过去的那种形状**:清单可以写着正确的话,而 tarball 仍然带着文件。
66
+ **只有 tarball 能谈论 tarball。** 而且**缺一个打包器算失败、不算跳过**(把 `tar` 从 `PATH` 拿掉 → `spawnSync tar ENOENT`,exit 1)——
67
+ 一个因为什么都没跑而报「通过」的守卫,比没有守卫更糟。
68
+
69
+ ### 4. 一条关于「数数」的教训
70
+
71
+ 这个缺陷藏了这么久,是因为一个数把它盖住了:**「7」**。
72
+ 两份清单做差集得到 7 —— 但**第八个在两边都有,差集永远看不见两边都有的文件**。
73
+ 这和「门只对一份样本断言」是同一种盲区,只不过那次是别人做的,这次是我自己做的差集。
74
+
75
+ ### 5. 这一版**没有**交付的东西(如实记录)
76
+
77
+ - **4.1.24 已经带着那 8 个夹具发上去了,npm 上的 tarball 不可变,撤不回。** 这一版能做的是「此后不再发」。
78
+ - **包含规则要求文件名带点**:将来一个**无扩展名**的 `skills/**` 文件会被**静默丢掉,且没有任何测试会红**(守卫断言的是受跟踪文件在位,而未跟踪的文件不在它的集合里)。已记入 backlog §23.20。
79
+ - `*test[-_]prompts*` 会连坐任何**含有**该记号的文件名(例如将来的 `test-prompts-extra.json`)。今天为 0。
80
+ - **变异覆盖不完整**:会话级的 `mut/mut-report.json` 是另一个切片的报告;本机 `peaks mut run` 两次 `MUT_FAILED / EPERM`(Stryker 的 Windows 沙箱去拷贝一个已死会话留下的 Unix 符号链接)。断言有效性那一半跑了(30 条断言,0 条弱),「测试能否抓到真变异」那一半是各切片**手工植入变异**验证的,不是门自动覆盖的。
81
+ - **第三方评审全部是 SKIP**:本机没有配置 reviewer provider(`configured: false`,0 个),单模型的自证盲区**没有被缓解**。
82
+ - **发布工具链在 Windows 上有一个同类缺陷,这一版没修。** `scripts/_release-shared.mjs` 的 `resolveNpmInvocation()`
83
+ 探三个候选、找不到就**大声拒绝**;而 `resolvePnpmInvocation()` 只探一个、找不到就**静默退回裸名 `pnpm`** ——
84
+ 而 `pnpm pack` 正是产出**发布 tarball** 的命令。corepack 管理的 pnpm(CI 的形态)没有那个文件,
85
+ 所以在 Windows 上会退到 `pnpm.cmd` → ENOENT,失败形态是「发布根本没发生」而不是报错。
86
+ **CI 在 `ubuntu-latest` 上发布,所以 4.1.25 不受影响**;受影响的是**在 Windows 上发布的维护者**。
87
+ 已记入 backlog §23.22。
88
+
89
+ ## 4.1.24 — 2026-10-29(同一个 id,几个读法)
90
+
91
+ **版本级别**:**patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何门禁的阈值或放行条件;
92
+ **没有**动事件 schema 的版本号(`schemaVersion` 仍是 `z.literal(1)`);**没有**改发布流程。
93
+
94
+ **一句话:这一版修的是一个贯穿全仓库的缺陷形状 —— 同一个标识符有几个读者,每个读者各有自己的读法。**
95
+ 请求 id 有两种拼写(`004-<rid>` 与 `<rid>`),仓库早就写下了规则(`NUMBERED_PREFIX_RE`,18 处调用点遵守),
96
+ 但**产物路径解析器**和**观测层**没有:前者找不到磁盘上真实存在的证据,后者把同一个 slice 数成两个、并因此冤枉了一个
97
+ 做对了的 slice。规则本身没有错,是两个读者漏了读它。
98
+
99
+ ### 1. 头号数字:近失率里的两个假指控被撤销
100
+
101
+ 4.1.23 发布的近失率是 **12.8% = 12 / 94**。按今天的记录历史重算,**修复前**读数是 **14 / 95** ——
102
+ 其中两条是**假指控**:它们是同一个请求 id 的另一种拼写,而那个 slice 的另一次尝试其实**成功了**。
103
+
104
+ | | 修复前 | 修复后 |
105
+ |---|---|---|
106
+ | 近失 | **14** | **12** |
107
+ | 通过 | 95 | 95(随后随新 slice 增长到 97) |
108
+ | 双拼写记录的 slice | 4 | 4 —— **无一落在 12 条里** |
109
+ | `refused` / `unattempted` 拆分 | — | **1 / 11**,与真实发现一致 |
110
+
111
+ **分母是活的。** 本次会话期间兄弟 slice 不断记录成功,所以会话结束时读数是 12 / 97,而不是 12 / 95。
112
+ **要看的是分子**:它从 14 落到 12,掉掉的那两个是错误分类,不是被掩盖的近失。
113
+
114
+ `sliceIdentity(rid)` 现在和 `NUMBERED_PREFIX_RE`、`getNextNumber`、`requestIdFromFileName` **同处一个模块**——
115
+ 一个请求 id 的读写两侧从此不可能各自漂移。五个读者按逻辑 id 归并:近失、汇总、修复周期、差异计数、
116
+ 以及热点层的 `canonicalArtifact`。
117
+
118
+ ### 2. 合规率第一次有了读者
119
+
120
+ 4.1.23 如实记录了「**遵守率有裁判,没有读者**」—— `writeSessionMetricRow` / `readSessionMetricRow` 只有测试在调用。
121
+ 这一版补上了读者:`peaks observability session-row` 写出并打印本会话的追踪指标行,含近失率与合规率。
122
+ **输入未被观测时,比率是 `null` 并附原因,绝不是 0** —— 一个被判定的 0 仍然是 0。
123
+
124
+ ### 3. `peaks-mut` 与 `peaks-maker` 现在真的随包分发
125
+
126
+ 4.1.23 也如实记录了「`peaks-mut` 的分发缺口」:它的 `SKILL.md` 在 `src/skills/`,**不在 npm tarball 里**,
127
+ 所以**装好的 peaks-loop 上 `mut/` 产物没有产出者**。这一版把两个技能移进根 `skills/` 树,并让包带上它们:
128
+
129
+ | | |
130
+ |---|---|
131
+ | tarball 文件数 | 2955 → **2966** —— 以**实际发布的 tarball** 为准(`npm pack peaks-loop@4.1.24` 后 `tar -tzf` 数出 2966)。本地 `npm pack --dry-run` 读的是 2959,两次构建差 7 个文件,**原因未查明**;本行此前写的 2955 / 2957 / 2959 都是不同时刻的读数,都不等于发布物。**同一个包在不同构建机上文件数不同,本身是个待查的问题。** |
132
+ | `skills/peaks-mut/SKILL.md`、`skills/peaks-maker/SKILL.md` | **在包里** |
133
+ | `src/skills/` 下的文件 | **0** |
134
+ | 安装器自己的枚举 | **25 个候选**,全部落在根 `skills/` 树内 |
135
+ | 卫生块计数 | 23 → **25**,25 份字节相同 |
136
+
137
+ **单元测试绿色不是这个证据。** 上一次检查时,绿色的套件就坐在一个两个技能都不在的包旁边 —— 所以这次的证据是
138
+ `npm pack` 自己的文件清单,和安装器自己的枚举函数。
139
+
140
+ ### 4. 每次 Bash 都报的那个钩子错误:根因
141
+
142
+ 症状是每次 Bash 调用都有一行 `Hook JSON output validation failed — decision: Invalid option:
143
+ expected one of "approve"|"block"`。**报错点名了字段,没有点名钩子。**
144
+
145
+ | 读者 | 修复前 | 修复后 |
146
+ |---|---|---|
147
+ | `code gate-step-08` | 根级 `"decision": null`,且 JSON 后面跟一行 `next:` 散文 —— **两处违规** | 一个 JSON 文档,决策留在 `data` 下,散文走 stderr |
148
+ | `code auto-compact` | 根级 `"decision": "below-threshold"` + 尾随散文 | 同上 |
149
+ | `gate enforce --json` | 信封(根级无 `decision`)—— 本来就通过 | 不变 |
150
+
151
+ **机制在打印机,不在载荷。** `printResult` 在 `asJson` 为假时把 `result.data` **摊到根上**打印,
152
+ 于是为信封 `data` 构造的 `decision` 落到了宿主拥有的那个根级键上。装好的钩子命令不带 `--json`,正好走这条路。
153
+
154
+ `gate-step-08` 的阻断路径**语义不变**:`emitBlock` + `permissionDecision: "deny"` + exit 2,两个钩子都验过。
155
+ 三处重复的封包构造并成 `printAllow` / `printBlock` / `denyData` —— 重复正是这个 bug 出现三遍的原因,
156
+ 合并后该文件落在**基线以下**(263 行,上限 300,基线 291)而不是超限。
157
+
158
+ ### 5. 另外六处,同一个形状
159
+
160
+ - **产物路径解析器**认得了 kind-first 编号族(`security-002-<rid>.md`),此前只认得 `002-<rid>.md`。
161
+ 在一个删掉所有裸名副本的会话树上实测:**3/11 → 10/11**。近似名仍被拒绝(`security-backup-<rid>.md`、
162
+ 另一个 rid 的同类文件)。
163
+ - **readiness lint 读技能自己的正文。** 手工维护、字节相同的卫生块,其续行以 `run \`peaks code …\`` 开头,
164
+ 被「用户不该手打 CLI」的规则误判 —— 而那正是明确叫 LLM 自己跑、并禁止甩给用户的那一句。
165
+ 25 份 SKILL.md **全部**被咬中,而集成测试只对**一份**断言,且那恰好是唯一没插卫生块的。
166
+ 现在剥离 `<!-- peaks:loop-hygiene -->` 配对区间后再检查,且**未闭合标记时一个字节都不剥**(fail-closed)。
167
+ 全量实测:`cli-verb-bypass` **29 → 4**,`missing-guideline-reference` 20 → 20,通过的技能 **0 → 1**。
168
+ 剥离只移除了假阳性,没有移动别的。
169
+ - **安全评审归 `peaks-security-audit`**:归属表的「前缀面」与「键面」曾对 `rd/security-review-*` 各说各话,
170
+ 一个文件因此有两个主人。
171
+ - **oracle 覆盖到会分歧的路径**:独立的第二读法此前只覆盖两侧本来就一致的路径,所以它骂不出声。现在扫过每条迁移的
172
+ 候选集(138 条迁移 / 13 个候选路径 / 13 一致),并对唯一仍分歧的 `rd/security-review.md` 写了**可失效**的 pin
173
+ —— 从活表计算,那条路径一旦成为候选就会红。
174
+ - **运行时守卫按工作目录解析**:`.peaks/_runtime` 是工作目录概念,它此前按模块位置解析。
175
+
176
+ ### 6. 这一版**没有**交付的东西(如实记录)
177
+
178
+ - **`gate enforce` 仍然对几乎每个 Bash 调用发 `permissionDecision: "allow"`。** 按 Claude Code 的钩子契约,
179
+ 那是一次真实授权 —— 它批准调用并**跳过你的权限确认**(显式 deny 规则仍优先)。已决定移除,**不在本版**。
180
+ - **20 个 shipped SKILL.md 仍缺 `.peaks/standards/loop-engineering-guidelines.md` 引用**,另外 4 个仍被
181
+ `peaks capabilities` 那行咬中。已记入 backlog §23.17,作为独立切片。
182
+ - **变异覆盖不完整。** 会话级的 `mut/mut-report.json` 是另一个切片的报告;在本机 `peaks mut run` 两次
183
+ `MUT_FAILED / EPERM`(Stryker 的 Windows 沙箱去拷贝一个已死会话留下的 Unix 符号链接)。断言有效性那一半跑了
184
+ (30 条断言,0 条弱),「测试能否抓到真变异」那一半是**各切片手工植入变异**验证的,不是门自动覆盖的。
185
+ - **第三方评审全部是 SKIP。** 本机没有配置 reviewer provider(`configured: false`,0 个),
186
+ 所以单模型的自证盲区**没有被缓解**。
187
+ - **三个新测试文件的 BDD 契约是补上的,不是天然满足的。** 推送门拒了 31 处违规;**没有**给全新文件加基线行
188
+ —— 那会把缺陷变成许可。同时记下一条诊断代价:检测器**每个调用只返回第一个失败**且先查描述再查正文,
189
+ 所以描述格式错会遮住缺三元组,「改名即可」的判断是错的。
190
+
3
191
  ## 4.1.23 — 2026-10-28(让"技能/门禁到底做了什么"变成可查的数字)
4
192
 
5
193
  **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何门禁的语义、
@@ -6,6 +6,7 @@ import { resolveAutoCompactProfile } from '../../services/code/auto-compact-prof
6
6
  import { probeInFlightBatch } from '../../services/workflow/workflow-inflight-probe.js';
7
7
  import { readDispatchLedgerFacts } from '../../services/dispatch/dispatch-ledger-reader.js';
8
8
  import { readActiveSid } from './code-runtime-session.js';
9
+ import { emitResultDocument } from '../../services/hooks/output.js';
9
10
  import { buildAutoCompactEnvelope } from './code-auto-compact-envelope.js';
10
11
  import { describeDeferral, withDeferralDetail } from './code-auto-compact-deferral.js';
11
12
  const AUTO_COMPACT_DESCRIPTION = 'v2.13.0 AC-4: zero-human-intervention auto-compact. Probes current ' +
@@ -122,7 +123,24 @@ async function runAutoCompactAction(opts, io) {
122
123
  // `data` on success-path and `nextActions` on the error
123
124
  // path; surface both directly to the user.
124
125
  const envelope = buildAutoCompactEnvelope(result);
125
- printResult(io, withDeferralDetail(envelope, deferralDetail(result, capture.last)), opts.json);
126
+ const document = withDeferralDetail(envelope, deferralDetail(result, capture.last));
127
+ // The installed PreToolUse hook runs this command with NO `--json`, so an
128
+ // exit-0 run's stdout is the hook's document. printResult's default branch
129
+ // flattens `data` to the root and appends `next: ...` prose: the root then
130
+ // carried `decision: "below-threshold"` — a value outside the host's
131
+ // {approve, block} vocabulary at a key it owns — and the prose made stdout
132
+ // unparseable as one document. Both were reported as
133
+ // "Hook JSON output validation failed" on EVERY Bash call.
134
+ // `emitResultDocument` emits the SAME envelope `--json` already prints, so
135
+ // every exit-0 path here leaves exactly ONE JSON document on stdout and puts
136
+ // the advice on stderr. (Hint additions are additive: a consumer that reads
137
+ // `.data.decision` from stdout still reads `below-threshold`.)
138
+ if (exitOk) {
139
+ emitResultDocument(io, document);
140
+ }
141
+ else {
142
+ printResult(io, document, opts.json);
143
+ }
126
144
  if (!exitOk)
127
145
  process.exitCode = 1;
128
146
  }
@@ -3,14 +3,18 @@ import { fail, ok } from 'peaks-loop-shared/result';
3
3
  import { evaluateStep08, STEP_08_BACKUP_REGEX } from '../../services/code/step-08-gate.js';
4
4
  import { buildContextAuditHint } from '../../services/context/context-audit-hint.js';
5
5
  import { resolveOuterSessionId } from '../../services/session/binding-status-service.js';
6
+ import { emitBlock, emitHint, emitResultDocument } from '../../services/hooks/output.js';
6
7
  import { printGateStep08RemedyCommand, readHookCommand } from './code-gate-step-08-remedy.js';
7
8
  import { readActiveSid } from './code-runtime-session.js';
9
+ const GATE = 'code.gate-step-08';
10
+ const EXIT_2_NOTE = "This gate blocks with exit 2; a harness that reports it as non-blocking has overridden the hook's exit code.";
11
+ const DETECT_JOB_HINT = 'Run `peaks code detect-job --is-job true --rationale <text> --suggested-job-id <slug>` (or `--is-job false --rationale <text>`, whose id defaults to `single-task`) to record the Job-shape verdict.';
12
+ const BLOCK_MISSING = `BLOCKED: prompt looks Job-shaped but peaks code detect-job has not been called. ${DETECT_JOB_HINT} Then retry.`;
8
13
  export function registerCodeGateStep08Command(code, io) {
9
14
  // v3.1.2 Step 0.8 — Mechanical PreToolUse gate.
10
- // Wire-installed by `peaks workspace init` (extends the existing hook
11
- // installer). Exit code is the load-bearing contract:
12
- // exit 0 → allow (with structured stdout describing the decision)
13
- // exit 2 → block (stderr contains the BLOCKED: ... reason)
15
+ // Wire-installed by `peaks workspace init`. Exit code is the load-bearing
16
+ // contract: 0 → allow (with the envelope on stdout), 2 → block (with the
17
+ // host's deny document on stdout and the reason on stderr).
14
18
  addJsonOption(code
15
19
  .command('gate-step-08')
16
20
  .description('v3.1.2: PreToolUse gate for Step 0.8 — allow when job-shape.json exists; ' +
@@ -27,45 +31,108 @@ async function runGateStep08(opts, io) {
27
31
  try {
28
32
  const sessionId = opts.sessionId ?? readActiveSid(opts.project);
29
33
  if (sessionId === null) {
30
- // No session binding — treat as allow (single-rid mode). The
31
- // LLM has not yet anchored; we have nothing to gate against.
32
- printGateStep08NoSession(io, opts.json);
34
+ // No session binding — treat as allow (single-rid mode). The LLM has not
35
+ // yet anchored; we have nothing to gate against.
36
+ printAllow(io, { mode: 'no-session', decision: null, nextSlice: null }, [
37
+ 'No active session id; gate passes through (single-rid mode).'
38
+ ]);
33
39
  return;
34
40
  }
35
41
  const command = opts.prompt === undefined ? await readHookCommand() : undefined;
36
- const context = resolveGateStep08Context(opts, sessionId, command);
37
- const verdict = context.result.verdict;
38
- if (verdict.kind === 'allow-job') {
39
- printGateStep08AllowJob(verdict, context, io, opts.json);
40
- return;
41
- }
42
- if (verdict.kind === 'allow-single') {
43
- printGateStep08AllowSingle(context, io, opts.json);
44
- return;
45
- }
46
- if (verdict.kind === 'allow-remedy-command') {
47
- printGateStep08RemedyCommand(verdict, context.hintActions, io, opts.json);
48
- return;
49
- }
50
- if (verdict.kind === 'block-missing-decision') {
51
- // Block: the prompt matched the backup regex, so the LLM is treated as
52
- // having skipped `peaks code detect-job` on a Job-shaped request.
53
- // Exit code 2 is the load-bearing signal for the PreToolUse hook.
54
- printGateStep08Blocked(verdict, context, io, opts.json);
55
- return;
56
- }
57
- if (verdict.kind === 'block-no-decision-with-ledger') {
58
- printGateStep08BlockedWithLedger(verdict, context, io, opts.json);
59
- return;
60
- }
61
- // allow-no-decision-recorded — no decision and no ledger. This is a
62
- // normal non-Job session and the gate must let it through.
63
- printGateStep08Undecided(verdict, context, io, opts.json);
42
+ dispatchVerdict(resolveGateStep08Context(opts, sessionId, command), io, opts.json);
64
43
  }
65
44
  catch (err) {
66
45
  reportGateStep08Failure(io, err, opts.json);
67
46
  }
68
47
  }
48
+ /**
49
+ * Allow — ONE document (the `--json` envelope) on stdout, advice on stderr.
50
+ * `--json` no longer selects a second shape: two shapes for one command is what
51
+ * let the installed hook entry drift out of the host's contract.
52
+ */
53
+ function printAllow(io, data, actions) {
54
+ emitResultDocument(io, ok(GATE, { allow: true, ...data }, [], [...actions]));
55
+ }
56
+ /** The fields every Step 0.8 deny envelope carries. */
57
+ function denyData(extra) {
58
+ return { backupRegex: STEP_08_BACKUP_REGEX.toString(), exitCode: 2, ...extra };
59
+ }
60
+ /**
61
+ * Block — the half a fix must not weaken. Hook mode (no `--json`) emits the
62
+ * host's canonical deny document and exits 2; `--json` mode keeps the failure
63
+ * envelope on stdout (a committed integration test pins that shape). Both
64
+ * exit 2, which is the load-bearing block signal.
65
+ */
66
+ function printBlock(io, denied, hints, json) {
67
+ const envelope = fail(GATE, denied.code, denied.message, denied.data, [
68
+ DETECT_JOB_HINT,
69
+ 'Then re-run the Bash tool call.',
70
+ ...hints
71
+ ]);
72
+ if (json === true) {
73
+ io.stderr(`${denied.message}\n${EXIT_2_NOTE}\n`);
74
+ printResult(io, envelope, true);
75
+ }
76
+ else {
77
+ emitBlock(io, denied.message);
78
+ emitHint(io, EXIT_2_NOTE);
79
+ for (const action of envelope.nextActions)
80
+ emitHint(io, `- ${action}`);
81
+ }
82
+ process.exitCode = 2;
83
+ }
84
+ /** One branch per Step 0.8 verdict; every branch prints exactly one answer. */
85
+ function dispatchVerdict(context, io, json) {
86
+ const verdict = context.result.verdict;
87
+ if (verdict.kind === 'block-missing-decision' ||
88
+ verdict.kind === 'block-no-decision-with-ledger') {
89
+ printBlockedVerdict(verdict, context, io, json);
90
+ return;
91
+ }
92
+ printAllowedVerdict(verdict, context, io);
93
+ }
94
+ /** Block: the two refusal verdicts differ only in code, message and one field. */
95
+ function printBlockedVerdict(verdict, context, io, json) {
96
+ const missing = verdict.kind === 'block-missing-decision';
97
+ printBlock(io, {
98
+ code: missing ? 'STEP_08_BLOCKED' : 'STEP_08_BLOCKED_WITH_LEDGER',
99
+ message: missing ? BLOCK_MISSING : `BLOCKED: ${verdict.reason}`,
100
+ data: denyData(missing ? { promptSource: verdict.promptSource } : { ledgerJobIds: verdict.ledgerJobIds })
101
+ }, context.hintActions, json);
102
+ }
103
+ /** Allow: the job verdict, the single-rid pass-through, the remedy, the undecided case. */
104
+ function printAllowedVerdict(verdict, context, io) {
105
+ const hints = context.hintActions;
106
+ const nextLine = context.result.nextSliceLine;
107
+ switch (verdict.kind) {
108
+ case 'allow-job':
109
+ printAllow(io, {
110
+ mode: 'job',
111
+ decision: verdict.decision,
112
+ progress: verdict.progress,
113
+ nextSlice: nextLine
114
+ }, [...(nextLine !== null ? [nextLine] : []), ...hints]);
115
+ return;
116
+ case 'allow-single':
117
+ printAllow(io, { mode: 'single', decision: null, nextSlice: null }, [
118
+ 'job-shape.json says isJob=false; single-rid mode (gate allows).',
119
+ ...hints
120
+ ]);
121
+ return;
122
+ case 'allow-remedy-command':
123
+ printGateStep08RemedyCommand(verdict, hints, io);
124
+ return;
125
+ default:
126
+ // allow-no-decision-recorded — no decision and no ledger. This is a
127
+ // normal non-Job session and the gate must let it through.
128
+ printAllow(io, {
129
+ mode: 'undecided-no-regex-hit',
130
+ decision: null,
131
+ nextSlice: null,
132
+ promptSource: verdict.promptSource
133
+ }, [verdict.reason, ...hints]);
134
+ }
135
+ }
69
136
  function resolveGateStep08Context(opts, sessionId, command) {
70
137
  // hint. Runs ONLY when the window is ≥ 0.70 full, caches the audit
71
138
  // result for ≥ 5 min so the transcript is scanned at most once per
@@ -88,77 +155,8 @@ function resolveGateStep08Context(opts, sessionId, command) {
88
155
  const result = evaluateStep08(evalInput);
89
156
  return { result, hintActions };
90
157
  }
91
- function printGateStep08NoSession(io, json) {
92
- const envelope = ok('code.gate-step-08', {
93
- allow: true,
94
- mode: 'no-session',
95
- decision: null,
96
- nextSlice: null
97
- }, [], ['No active session id; gate passes through (single-rid mode).']);
98
- printResult(io, envelope, json);
99
- }
100
- function printGateStep08AllowJob(verdict, context, io, json) {
101
- const result = context.result;
102
- const envelope = ok('code.gate-step-08', {
103
- allow: true,
104
- mode: 'job',
105
- decision: verdict.decision,
106
- progress: verdict.progress,
107
- nextSlice: result.nextSliceLine
108
- }, [], [...(result.nextSliceLine !== null ? [result.nextSliceLine] : []), ...context.hintActions]);
109
- printResult(io, envelope, json);
110
- }
111
- function printGateStep08AllowSingle(context, io, json) {
112
- const envelope = ok('code.gate-step-08', {
113
- allow: true,
114
- mode: 'single',
115
- decision: null,
116
- nextSlice: null
117
- }, [], ['job-shape.json says isJob=false; single-rid mode (gate allows).', ...context.hintActions]);
118
- printResult(io, envelope, json);
119
- }
120
- function printGateStep08Blocked(verdict, context, io, json) {
121
- const blockMessage = 'BLOCKED: prompt looks Job-shaped but peaks code detect-job has not been called. Run `peaks code detect-job --is-job true --rationale <text> --suggested-job-id <slug>` (or `--is-job false --rationale <text>`, whose id defaults to `single-task`) to record your Job-shape verdict, then retry.';
122
- const envelope = fail('code.gate-step-08', 'STEP_08_BLOCKED', blockMessage, {
123
- promptSource: verdict.promptSource,
124
- backupRegex: STEP_08_BACKUP_REGEX.toString(),
125
- exitCode: 2
126
- }, [
127
- 'Run `peaks code detect-job --is-job true --rationale <text> --suggested-job-id <slug>` (or `--is-job false --rationale <text>`, whose id defaults to `single-task`) to record the Job-shape verdict.',
128
- 'Then re-run the Bash tool call.',
129
- ...context.hintActions
130
- ]);
131
- io.stderr(`${blockMessage}\nThis gate blocks with exit 2; a harness that reports it as non-blocking has overridden the hook's exit code.\n`);
132
- printResult(io, envelope, json);
133
- process.exitCode = 2;
134
- }
135
- function printGateStep08BlockedWithLedger(verdict, context, io, json) {
136
- const blockMessage = `BLOCKED: ${verdict.reason}`;
137
- const envelope = fail('code.gate-step-08', 'STEP_08_BLOCKED_WITH_LEDGER', blockMessage, {
138
- ledgerJobIds: verdict.ledgerJobIds,
139
- backupRegex: STEP_08_BACKUP_REGEX.toString(),
140
- exitCode: 2
141
- }, [
142
- 'Run `peaks code detect-job --is-job true --rationale <text> --suggested-job-id <slug>` (or `--is-job false --rationale <text>`, whose id defaults to `single-task`) to record the Job-shape verdict the Job ledger presumes.',
143
- 'Then re-run the Bash tool call.',
144
- ...context.hintActions
145
- ]);
146
- io.stderr(`${blockMessage}\nThis gate blocks with exit 2; a harness that reports it as non-blocking has overridden the hook's exit code.\n`);
147
- printResult(io, envelope, json);
148
- process.exitCode = 2;
149
- }
150
- function printGateStep08Undecided(verdict, context, io, json) {
151
- const envelope = ok('code.gate-step-08', {
152
- allow: true,
153
- mode: 'undecided-no-regex-hit',
154
- decision: null,
155
- nextSlice: null,
156
- promptSource: verdict.promptSource
157
- }, [], [verdict.reason, ...context.hintActions]);
158
- printResult(io, envelope, json);
159
- }
160
158
  function reportGateStep08Failure(io, err, json) {
161
- printResult(io, fail('code.gate-step-08', 'GATE_STEP_08_FAILED', getErrorMessage(err), null, [
159
+ printResult(io, fail(GATE, 'GATE_STEP_08_FAILED', getErrorMessage(err), null, [
162
160
  'Verify the project path and try again'
163
161
  ]), json);
164
162
  process.exitCode = 1;
@@ -6,12 +6,20 @@
6
6
  * This module reads the PreToolUse payload that names the command and prints
7
7
  * the named allow when that command is the remedy.
8
8
  */
9
- import { type ProgramIO } from '../cli-helpers.js';
9
+ import type { ProgramIO } from '../cli-helpers.js';
10
10
  import type { Step08Verdict } from '../../services/code/step-08-gate.js';
11
11
  type AllowRemedyCommandVerdict = Extract<Step08Verdict, {
12
12
  kind: 'allow-remedy-command';
13
13
  }>;
14
14
  /** The command the hook is gating, when the payload carries one. */
15
15
  export declare function readHookCommand(): Promise<string | undefined>;
16
- export declare function printGateStep08RemedyCommand(verdict: AllowRemedyCommandVerdict, hintActions: readonly string[], io: ProgramIO, json?: boolean): void;
16
+ /**
17
+ * Allow — ONE document on stdout, action lines on stderr.
18
+ *
19
+ * This arm answers the hook on every call that runs the remedy command, so its
20
+ * stdout is a hook document like every other allow arm of this gate; the
21
+ * `decision: null` payload stays NESTED under `data`, never at the root the
22
+ * host owns. See `code-gate-step-08-command.ts`'s header for the full reason.
23
+ */
24
+ export declare function printGateStep08RemedyCommand(verdict: AllowRemedyCommandVerdict, hintActions: readonly string[], io: ProgramIO): void;
17
25
  export {};
@@ -7,8 +7,8 @@
7
7
  * the named allow when that command is the remedy.
8
8
  */
9
9
  import { ok } from 'peaks-loop-shared/result';
10
- import { printResult } from '../cli-helpers.js';
11
10
  import { pluckObject, pluckString } from '../../services/ide/hook-translator.js';
11
+ import { emitResultDocument } from '../../services/hooks/output.js';
12
12
  const HOOK_STDIN_TIMEOUT_MS = 2_000;
13
13
  /**
14
14
  * Read the PreToolUse payload the Bash matcher pipes in. A TTY means a manual
@@ -65,12 +65,20 @@ function commandFromHookPayload(raw) {
65
65
  export async function readHookCommand() {
66
66
  return commandFromHookPayload(await readStdin());
67
67
  }
68
- export function printGateStep08RemedyCommand(verdict, hintActions, io, json) {
68
+ /**
69
+ * Allow — ONE document on stdout, action lines on stderr.
70
+ *
71
+ * This arm answers the hook on every call that runs the remedy command, so its
72
+ * stdout is a hook document like every other allow arm of this gate; the
73
+ * `decision: null` payload stays NESTED under `data`, never at the root the
74
+ * host owns. See `code-gate-step-08-command.ts`'s header for the full reason.
75
+ */
76
+ export function printGateStep08RemedyCommand(verdict, hintActions, io) {
69
77
  const envelope = ok('code.gate-step-08', {
70
78
  allow: true,
71
79
  mode: 'remedy-command',
72
80
  decision: null,
73
81
  nextSlice: null
74
82
  }, [], [verdict.reason, ...hintActions]);
75
- printResult(io, envelope, json);
83
+ emitResultDocument(io, envelope);
76
84
  }
@@ -53,12 +53,17 @@ export declare function handleWorktreeGate(io: ProgramIO, options: GateEnforceCl
53
53
  parsedStdin: unknown;
54
54
  }): boolean;
55
55
  /**
56
- * Not a guarded surface — allow. Emit minimal JSON on stdout so Claude Code's PreToolUse hook
57
- * validator accepts the response. Empty stdout is rejected with "Hook JSON output validation
58
- * failed — Invalid input" in Claude Code 2.x; `{}` is the canonical no-op marker.
56
+ * Not a guarded surface — allow.
57
+ *
58
+ * The stdout document is the CLI envelope a downstream consumer reads
59
+ * (`JSON.parse(stdout).data.decision`), carrying no permission grant.
59
60
  */
60
61
  export declare function emitAllowSkipped(io: ProgramIO, options: GateEnforceCliOptions): void;
61
- /** Worktree gate allowed and this is not a Bash surface — allow without running the SOP gate. */
62
+ /**
63
+ * Worktree gate allowed and this is not a Bash surface — allow without running
64
+ * the SOP gate. Same plain-envelope shape as the skipped path (see
65
+ * {@link emitAllowSkipped}).
66
+ */
62
67
  export declare function emitAllowWorktree(io: ProgramIO, options: GateEnforceCliOptions): void;
63
68
  /**
64
69
  * writes the Claude Code permissionDecision:"deny" JSON to stdout (the hook's decision signal),
@@ -70,10 +75,11 @@ export declare function emitSopDeny(io: ProgramIO, options: GateEnforceCliOption
70
75
  /** Surface any SOP-gate warnings as hints before the allow decision is emitted. */
71
76
  export declare function emitSopWarnings(io: ProgramIO, decision: SopAllow): void;
72
77
  /**
73
- * SOP gate allowed the command. --json mode emits the canonical envelope on stdout (the documented
74
- * contract for downstream tooling). The hook decision (allow/deny) is still signalled via
75
- * emitHint here was wrong — emitHint writes to stderr, but the AC5 contract expects the JSON
76
- * envelope on stdout. Switch to printResult(asJson=true).
78
+ * SOP gate allowed the command.
79
+ *
80
+ * `--json` mode emits the canonical envelope on stdout (the documented contract
81
+ * for downstream tooling): ONE JSON document, the gate's decision under `data`, and
82
+ * no permission grant — see {@link emitAllowSkipped} for the shape and the reason.
77
83
  */
78
84
  export declare function emitSopAllow(io: ProgramIO, options: GateEnforceCliOptions, decision: SopAllow): void;
79
85
  export {};