peaks-loop 4.1.22 → 4.1.24

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 (118) hide show
  1. package/.claude-plugin/marketplace.json +12 -2
  2. package/CHANGELOG.md +184 -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 +23 -8
  8. package/dist/cli/commands/gate-commands-enforce.js +27 -12
  9. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  10. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  11. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  12. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  13. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  14. package/dist/cli/commands/observability-commands-queries.js +88 -47
  15. package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
  16. package/dist/cli/commands/observability-commands-session-row.js +201 -0
  17. package/dist/cli/commands/observability-commands.js +81 -20
  18. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  19. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  20. package/dist/services/artifacts/prerequisite-path-census.d.ts +47 -0
  21. package/dist/services/artifacts/prerequisite-path-census.js +100 -0
  22. package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
  23. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  24. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  25. package/dist/services/artifacts/rd-gate-event.js +211 -0
  26. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  27. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  28. package/dist/services/hooks/output.d.ts +67 -1
  29. package/dist/services/hooks/output.js +74 -1
  30. package/dist/services/observability/aggregation-types.d.ts +21 -0
  31. package/dist/services/observability/aggregation.d.ts +12 -2
  32. package/dist/services/observability/aggregation.js +28 -3
  33. package/dist/services/observability/compliance-judge.d.ts +77 -0
  34. package/dist/services/observability/compliance-judge.js +143 -0
  35. package/dist/services/observability/compliance-spec.d.ts +96 -0
  36. package/dist/services/observability/compliance-spec.js +29 -0
  37. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  38. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  39. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  40. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  41. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  42. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  43. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  44. package/dist/services/observability/hotspot-rows.js +89 -0
  45. package/dist/services/observability/hotspot-shared.d.ts +207 -0
  46. package/dist/services/observability/hotspot-shared.js +127 -0
  47. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  48. package/dist/services/observability/hotspot-sources.js +142 -0
  49. package/dist/services/observability/hotspots.d.ts +47 -0
  50. package/dist/services/observability/hotspots.js +47 -0
  51. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  52. package/dist/services/observability/near-miss-attempts.js +223 -0
  53. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  54. package/dist/services/observability/near-miss-coverage.js +108 -0
  55. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  56. package/dist/services/observability/near-miss-denominator.js +75 -0
  57. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  58. package/dist/services/observability/near-miss-difference.js +135 -0
  59. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  60. package/dist/services/observability/near-miss-facts.js +101 -0
  61. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  62. package/dist/services/observability/near-miss-gate-events.js +106 -0
  63. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  64. package/dist/services/observability/near-miss-gates.js +135 -0
  65. package/dist/services/observability/near-miss-records.d.ts +93 -0
  66. package/dist/services/observability/near-miss-records.js +87 -0
  67. package/dist/services/observability/near-miss.d.ts +148 -0
  68. package/dist/services/observability/near-miss.js +203 -0
  69. package/dist/services/observability/observability-schema.d.ts +17 -2
  70. package/dist/services/observability/observability-schema.js +21 -1
  71. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  72. package/dist/services/observability/owner-skill-map.js +164 -0
  73. package/dist/services/observability/repair-cycle-metric.js +6 -3
  74. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  75. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  76. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  77. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  78. package/dist/services/observability/report-formatter.d.ts +49 -3
  79. package/dist/services/observability/report-formatter.js +55 -14
  80. package/dist/services/observability/retro-attribution.d.ts +129 -0
  81. package/dist/services/observability/retro-attribution.js +134 -0
  82. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  83. package/dist/services/observability/session-metric-rows.js +184 -0
  84. package/dist/services/skills/presence-role.js +9 -2
  85. package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
  86. package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
  87. package/dist/shared/incrementing-number.d.ts +57 -0
  88. package/dist/shared/incrementing-number.js +13 -0
  89. package/dist/skills/peaks-maker/index.js +43 -30
  90. package/output-styles/peaks-skill-swarm.md +2 -2
  91. package/package.json +5 -5
  92. package/scripts/install-skills-bundles.mjs +6 -1
  93. package/scripts/install-skills.mjs +10 -1
  94. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  95. package/skills/bee/peaks-prd/SKILL.md +1 -1
  96. package/skills/bee/peaks-qa/SKILL.md +1 -1
  97. package/skills/bee/peaks-rd/SKILL.md +1 -1
  98. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  99. package/skills/bee/peaks-sc/SKILL.md +1 -1
  100. package/skills/bee/peaks-security-audit/SKILL.md +1 -1
  101. package/skills/bee/peaks-txt/SKILL.md +1 -1
  102. package/skills/bee/peaks-ui/SKILL.md +1 -1
  103. package/skills/peaks-audit/SKILL.md +1 -1
  104. package/skills/peaks-code/SKILL.md +1 -1
  105. package/skills/peaks-content/SKILL.md +1 -1
  106. package/skills/peaks-doctor/SKILL.md +1 -1
  107. package/skills/peaks-final-review/SKILL.md +1 -1
  108. package/skills/peaks-ide/SKILL.md +1 -1
  109. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  110. package/skills/peaks-maker/SKILL.md +125 -0
  111. package/skills/peaks-mut/SKILL.md +297 -0
  112. package/skills/peaks-race-code/SKILL.md +1 -1
  113. package/skills/peaks-resume/SKILL.md +1 -1
  114. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  115. package/skills/peaks-solo/SKILL.md +1 -1
  116. package/skills/peaks-sop/SKILL.md +1 -1
  117. package/skills/peaks-status/SKILL.md +1 -1
  118. package/skills/peaks-test/SKILL.md +1 -1
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.22"
4
+ "version": "4.1.24"
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.22",
10
+ "version": "4.1.24",
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,189 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.24 — 2026-10-29(同一个 id,几个读法)
4
+
5
+ **版本级别**:**patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何门禁的阈值或放行条件;
6
+ **没有**动事件 schema 的版本号(`schemaVersion` 仍是 `z.literal(1)`);**没有**改发布流程。
7
+
8
+ **一句话:这一版修的是一个贯穿全仓库的缺陷形状 —— 同一个标识符有几个读者,每个读者各有自己的读法。**
9
+ 请求 id 有两种拼写(`004-<rid>` 与 `<rid>`),仓库早就写下了规则(`NUMBERED_PREFIX_RE`,18 处调用点遵守),
10
+ 但**产物路径解析器**和**观测层**没有:前者找不到磁盘上真实存在的证据,后者把同一个 slice 数成两个、并因此冤枉了一个
11
+ 做对了的 slice。规则本身没有错,是两个读者漏了读它。
12
+
13
+ ### 1. 头号数字:近失率里的两个假指控被撤销
14
+
15
+ 4.1.23 发布的近失率是 **12.8% = 12 / 94**。按今天的记录历史重算,**修复前**读数是 **14 / 95** ——
16
+ 其中两条是**假指控**:它们是同一个请求 id 的另一种拼写,而那个 slice 的另一次尝试其实**成功了**。
17
+
18
+ | | 修复前 | 修复后 |
19
+ |---|---|---|
20
+ | 近失 | **14** | **12** |
21
+ | 通过 | 95 | 95(随后随新 slice 增长到 97) |
22
+ | 双拼写记录的 slice | 4 | 4 —— **无一落在 12 条里** |
23
+ | `refused` / `unattempted` 拆分 | — | **1 / 11**,与真实发现一致 |
24
+
25
+ **分母是活的。** 本次会话期间兄弟 slice 不断记录成功,所以会话结束时读数是 12 / 97,而不是 12 / 95。
26
+ **要看的是分子**:它从 14 落到 12,掉掉的那两个是错误分类,不是被掩盖的近失。
27
+
28
+ `sliceIdentity(rid)` 现在和 `NUMBERED_PREFIX_RE`、`getNextNumber`、`requestIdFromFileName` **同处一个模块**——
29
+ 一个请求 id 的读写两侧从此不可能各自漂移。五个读者按逻辑 id 归并:近失、汇总、修复周期、差异计数、
30
+ 以及热点层的 `canonicalArtifact`。
31
+
32
+ ### 2. 合规率第一次有了读者
33
+
34
+ 4.1.23 如实记录了「**遵守率有裁判,没有读者**」—— `writeSessionMetricRow` / `readSessionMetricRow` 只有测试在调用。
35
+ 这一版补上了读者:`peaks observability session-row` 写出并打印本会话的追踪指标行,含近失率与合规率。
36
+ **输入未被观测时,比率是 `null` 并附原因,绝不是 0** —— 一个被判定的 0 仍然是 0。
37
+
38
+ ### 3. `peaks-mut` 与 `peaks-maker` 现在真的随包分发
39
+
40
+ 4.1.23 也如实记录了「`peaks-mut` 的分发缺口」:它的 `SKILL.md` 在 `src/skills/`,**不在 npm tarball 里**,
41
+ 所以**装好的 peaks-loop 上 `mut/` 产物没有产出者**。这一版把两个技能移进根 `skills/` 树,并让包带上它们:
42
+
43
+ | | |
44
+ |---|---|
45
+ | tarball 文件数 | 2955 → **2959**(2957 是在那个 commit 时刻量的;随后一次完整构建把 `dist/skills/peaks-maker/{index.js,index.d.ts}` 补进了 dist,所以**以 `npm pack` 对最终 tarball 的读数为准**) |
46
+ | `skills/peaks-mut/SKILL.md`、`skills/peaks-maker/SKILL.md` | **在包里** |
47
+ | `src/skills/` 下的文件 | **0** |
48
+ | 安装器自己的枚举 | **25 个候选**,全部落在根 `skills/` 树内 |
49
+ | 卫生块计数 | 23 → **25**,25 份字节相同 |
50
+
51
+ **单元测试绿色不是这个证据。** 上一次检查时,绿色的套件就坐在一个两个技能都不在的包旁边 —— 所以这次的证据是
52
+ `npm pack` 自己的文件清单,和安装器自己的枚举函数。
53
+
54
+ ### 4. 每次 Bash 都报的那个钩子错误:根因
55
+
56
+ 症状是每次 Bash 调用都有一行 `Hook JSON output validation failed — decision: Invalid option:
57
+ expected one of "approve"|"block"`。**报错点名了字段,没有点名钩子。**
58
+
59
+ | 读者 | 修复前 | 修复后 |
60
+ |---|---|---|
61
+ | `code gate-step-08` | 根级 `"decision": null`,且 JSON 后面跟一行 `next:` 散文 —— **两处违规** | 一个 JSON 文档,决策留在 `data` 下,散文走 stderr |
62
+ | `code auto-compact` | 根级 `"decision": "below-threshold"` + 尾随散文 | 同上 |
63
+ | `gate enforce --json` | 信封(根级无 `decision`)—— 本来就通过 | 不变 |
64
+
65
+ **机制在打印机,不在载荷。** `printResult` 在 `asJson` 为假时把 `result.data` **摊到根上**打印,
66
+ 于是为信封 `data` 构造的 `decision` 落到了宿主拥有的那个根级键上。装好的钩子命令不带 `--json`,正好走这条路。
67
+
68
+ `gate-step-08` 的阻断路径**语义不变**:`emitBlock` + `permissionDecision: "deny"` + exit 2,两个钩子都验过。
69
+ 三处重复的封包构造并成 `printAllow` / `printBlock` / `denyData` —— 重复正是这个 bug 出现三遍的原因,
70
+ 合并后该文件落在**基线以下**(263 行,上限 300,基线 291)而不是超限。
71
+
72
+ ### 5. 另外六处,同一个形状
73
+
74
+ - **产物路径解析器**认得了 kind-first 编号族(`security-002-<rid>.md`),此前只认得 `002-<rid>.md`。
75
+ 在一个删掉所有裸名副本的会话树上实测:**3/11 → 10/11**。近似名仍被拒绝(`security-backup-<rid>.md`、
76
+ 另一个 rid 的同类文件)。
77
+ - **readiness lint 读技能自己的正文。** 手工维护、字节相同的卫生块,其续行以 `run \`peaks code …\`` 开头,
78
+ 被「用户不该手打 CLI」的规则误判 —— 而那正是明确叫 LLM 自己跑、并禁止甩给用户的那一句。
79
+ 25 份 SKILL.md **全部**被咬中,而集成测试只对**一份**断言,且那恰好是唯一没插卫生块的。
80
+ 现在剥离 `<!-- peaks:loop-hygiene -->` 配对区间后再检查,且**未闭合标记时一个字节都不剥**(fail-closed)。
81
+ 全量实测:`cli-verb-bypass` **29 → 4**,`missing-guideline-reference` 20 → 20,通过的技能 **0 → 1**。
82
+ 剥离只移除了假阳性,没有移动别的。
83
+ - **安全评审归 `peaks-security-audit`**:归属表的「前缀面」与「键面」曾对 `rd/security-review-*` 各说各话,
84
+ 一个文件因此有两个主人。
85
+ - **oracle 覆盖到会分歧的路径**:独立的第二读法此前只覆盖两侧本来就一致的路径,所以它骂不出声。现在扫过每条迁移的
86
+ 候选集(138 条迁移 / 13 个候选路径 / 13 一致),并对唯一仍分歧的 `rd/security-review.md` 写了**可失效**的 pin
87
+ —— 从活表计算,那条路径一旦成为候选就会红。
88
+ - **运行时守卫按工作目录解析**:`.peaks/_runtime` 是工作目录概念,它此前按模块位置解析。
89
+
90
+ ### 6. 这一版**没有**交付的东西(如实记录)
91
+
92
+ - **`gate enforce` 仍然对几乎每个 Bash 调用发 `permissionDecision: "allow"`。** 按 Claude Code 的钩子契约,
93
+ 那是一次真实授权 —— 它批准调用并**跳过你的权限确认**(显式 deny 规则仍优先)。已决定移除,**不在本版**。
94
+ - **20 个 shipped SKILL.md 仍缺 `.peaks/standards/loop-engineering-guidelines.md` 引用**,另外 4 个仍被
95
+ `peaks capabilities` 那行咬中。已记入 backlog §23.17,作为独立切片。
96
+ - **变异覆盖不完整。** 会话级的 `mut/mut-report.json` 是另一个切片的报告;在本机 `peaks mut run` 两次
97
+ `MUT_FAILED / EPERM`(Stryker 的 Windows 沙箱去拷贝一个已死会话留下的 Unix 符号链接)。断言有效性那一半跑了
98
+ (30 条断言,0 条弱),「测试能否抓到真变异」那一半是**各切片手工植入变异**验证的,不是门自动覆盖的。
99
+ - **第三方评审全部是 SKIP。** 本机没有配置 reviewer provider(`configured: false`,0 个),
100
+ 所以单模型的自证盲区**没有被缓解**。
101
+ - **三个新测试文件的 BDD 契约是补上的,不是天然满足的。** 推送门拒了 31 处违规;**没有**给全新文件加基线行
102
+ —— 那会把缺陷变成许可。同时记下一条诊断代价:检测器**每个调用只返回第一个失败**且先查描述再查正文,
103
+ 所以描述格式错会遮住缺三元组,「改名即可」的判断是错的。
104
+
105
+ ## 4.1.23 — 2026-10-28(让"技能/门禁到底做了什么"变成可查的数字)
106
+
107
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何门禁的语义、
108
+ 阈值或放行条件;**没有**动事件 schema 的版本号(`schemaVersion` 仍是 `z.literal(1)`);**没有**碰发布流程。
109
+
110
+ **一句话:这一版给 peaks-loop 自己装上了眼睛 —— prereq 事件不再只记"缺了几个"而记"缺的是哪些、归谁",
111
+ 门禁层第一次发出自己的判定(pass / block / bypass)并带上当时的声明类型,查询能一次读到全部历史,
112
+ 而 `peaks observability near-miss` 第一次能回答"我们过去的『通过』,有多少是靠跳过检查换来的"。**
113
+
114
+ ### 1. 头号数字(在本仓库自己的记录历史上实测)
115
+
116
+ | | |
117
+ |---|---|
118
+ | 近失率 | **12.8% = 12 / 94** |
119
+ | 分母 | 94 个**记录了成功的 `verdict-issued` 尝试**的 slice(状态汇总的 `successCount` 是 103,两者对账写进了输出:`94 + 17 − 8 = 103`) |
120
+ | 12 的两种形状 | **11 个「拥有它的角色还没尝试迁移,就宣布通过了」+ 1 个「检查在拒绝时仍然放行」** —— 两种不同的缺陷,不同的修法 |
121
+ | 覆盖率 | **3 个原因类里只有 1 个可观测**(`prereq-skipped` 536 事件 / 94 slice / 12 次近失);`gate-never-evaluated` 与 `tool-blocked` **零事件、`rate: null`** |
122
+
123
+ **这个 12.8% 必须连着覆盖率一起引用。** 两类没数据的原因被写进了每一个界面:CLI 的 `unobservedClasses`
124
+ 与逐类 warning、markdown 报告**比率所在的那一行**、以及 spec §2.4.1 的记录表。"未观测"与"观测到 0"
125
+ 在输出里是不同的东西 —— 这正是本计划要消灭的那类混淆。
126
+
127
+ **另一件同样重要的事:113 次 prereq 拒绝里,每一次都被补齐后重试通过。** 没有一个是靠跳过检查换来的通过。
128
+ 门禁一直在正常工作,只是以前没有人记录它拒绝过什么。
129
+
130
+ ### 2. 证据层(不改任何判定,只让判定可见)
131
+
132
+ | 之前 | 之后 |
133
+ |---|---|
134
+ | prereq 事件只记 `missingCount: 3` | 记**清单**:每项带路径、`absent`/`body`、以及**归属技能** |
135
+ | 门禁层**完全不发事件** | 每个判定发一条 `gate` 事件:`gateId` / `phase` / `declaredType` / `outcome`(`pass`\|`block`\|`bypass`)/ `violationKind` / `reason` |
136
+ | 归属只按 `rd/` 前缀整体归给 `peaks-rd` | 更具体的前缀优先 —— `rd/third-party-review-<rid>.md` 现在归 **`peaks-reviewer`** |
137
+ | 汇总把卡在 `qa-handoff` 的 slice 既不算成功也不算失败(**8 个 slice 从账上蒸发**) | 三个桶**划分**全集:`success + fail + stalled === total` |
138
+ | `peaks observability report` 在有 1533 条事件的仓库上打印 `total events 0` | 五个命令都支持 `--all-sessions`;**作用域为空时,输出会告诉你数据在别处**(几个 session、多少条、用哪个开关) |
139
+ | 报告里"近失"只能靠人脑拼 | 报告开头就是"近失"节,含比率、分母及其定义、逐类覆盖率、被标记的 slice 与每键的状态(`refused` / `unattempted`) |
140
+
141
+ ### 3. 两个新增测量
142
+
143
+ - **`peaks observability near-miss`** —— 上面那个 12.8%,连同它的覆盖率和分母对账一起输出。
144
+ - **`peaks observability hotspots`** —— 哪个 artifact 被技能反复漏掉。计数被**拆成两组**:
145
+ `observedOmissions`(**确实**观测到缺失)与 `candidateMentions`(v1 历史事件只存计数不存清单,归属是**推出来的**)。
146
+ 只有 `confidence: 'exact'` 才算"确实缺失";`inferred` 是"与整个候选集不矛盾",`ambiguous` 是"是其中之一,说不准"。
147
+ 拆组是为了让 `count: 91` 永远不会被读成"缺了 91 次"。
148
+
149
+ ### 4. 顺带做的两件事
150
+
151
+ - **遵守率(试点)** —— `peaks-rd` 与 `peaks-race-code` 各有一份**可判定的**合规规范,
152
+ `judgeCompliance` 是**纯函数**(文件是否存在由调用方给),判定靠 artifact 契约,**不靠 LLM 猜**。
153
+ - **category 审计** —— 观测 schema 声明的每个 category 现在都写明了它的发射位置、触发条件、
154
+ 在记录历史里是否触发过,以及结论(① 条件触发 / ② 需要接线 / ③ 可删)。11 个里有 7 个从未触发,
155
+ 包括 `gate` —— 因为这个仓库所有 session 都早于它。
156
+
157
+ ### 5. 这一版**没有**交付的东西(如实记录)
158
+
159
+ - **遵守率有裁判,没有读者。** `writeSessionMetricRow` / `readSessionMetricRow` 目前**只有测试在调用** ——
160
+ 这一版交付的是**测量机器**,不是合规率的上线。plan 的完成定义里那一项**没有勾**。
161
+ - **`peaks-mut` 的分发缺口。** 它的 `SKILL.md` 在 `src/skills/peaks-mut/`,**不在 npm tarball 的 2935 个文件里**
162
+ (`package.json` 的 `files` 白名单只有 `skills/**`)。所以**装好的 peaks-loop 上,`mut/` 产物没有产出者** ——
163
+ 而 `mut/mut-report.json` 是 feature/bugfix/refactor 的 `rd -> qa-handoff` 硬性前置,**那个安装会永远过不了这道门禁**。
164
+ 已记录,需要单独一片修。
165
+ - **两个提交的主题与其内容不完全相符** —— `44c0b9b6`("the finding says whether the check was refusing or
166
+ unattempted")实际带了 21 个文件、三个关注点,其中 210 行是热点榜的测试基建;`1005fe00`(`docs(...)`)
167
+ 加了 39 行行为测试。两者都是并发提交事故的残留。**内容是对的**,已如实记录;**没有重写历史**。
168
+ - **没有为 `.peaks/_runtime/` 根目录的残留文件加守卫** —— 仓库有仓库根的守卫,没有 runtime 根的。
169
+
170
+ ### 6. 顺带修掉的两个"缺失被读成结果"
171
+
172
+ 评审复现了它们:
173
+
174
+ - `detail.outcome = 'PASS'`(松散 `z.record` 照收)曾让一次**干净通过**被判成 **近失率 100%**。
175
+ 现在 outcome 与 gate id 的词表**只有一份**,从 `rd-gate-event.ts` 导出;读不懂的 outcome 进 `undetermined`,
176
+ 而不是"没被评估"。
177
+ - `detail.prereqOk` 是字符串而非布尔时,那个 slice 曾**从分母里消失**("没有通过的 slice",而不是
178
+ "N 个通过的 slice 我们测不了")。现在它落进一个**新的 `unmeasured` 桶** —— 既不算通过、也不算没通过,
179
+ 而是被**显式标出**:报告的 `report.unmeasured` 逐条列出并写明记录到的值(例如 `the string "true"`),
180
+ 分母侧有 `unmeasuredSliceCount` 与一句"本分母排除了什么"���定义,覆盖率表多一列
181
+ `slices unreadable`,CLI 另有一条 stderr 警告。**读到的判定不可信时,它必须出现在某个地方** ——
182
+ 消失就是"缺失被读成结果"。
183
+
184
+ ---
185
+
186
+
3
187
  ## 4.1.22 — 2026-10-25(把"只测了两个子命令"的漏测补上,把"不是缺陷"的两条说准)
4
188
 
5
189
  **版本级别**:候选 **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,25 @@ 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
+ * In `--json` mode the stdout document is the CLI envelope with the Claude
59
+ * Code allow decision MERGED into it, so stdout stays ONE JSON document: the
60
+ * host parses it once and reads the decision out of `hookSpecificOutput`,
61
+ * while a downstream consumer still reads `JSON.parse(stdout).data.decision`.
62
+ *
63
+ * The envelope's own `data.decision` stays `allow` — it is nested under
64
+ * `data`, a key the host does not own, so the host reads no root `decision`
65
+ * at all. (The root `decision` key IS one the host owns, and it accepts only
66
+ * "approve" | "block" — a root `decision` of anything else is what produced
67
+ * the user's per-call "Invalid option" error.)
59
68
  */
60
69
  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. */
70
+ /**
71
+ * Worktree gate allowed and this is not a Bash surface — allow without running
72
+ * the SOP gate. Same one-document shape as the skipped path (see
73
+ * {@link emitAllowSkipped} for why the decision is merged into the envelope).
74
+ */
62
75
  export declare function emitAllowWorktree(io: ProgramIO, options: GateEnforceCliOptions): void;
63
76
  /**
64
77
  * writes the Claude Code permissionDecision:"deny" JSON to stdout (the hook's decision signal),
@@ -70,10 +83,12 @@ export declare function emitSopDeny(io: ProgramIO, options: GateEnforceCliOption
70
83
  /** Surface any SOP-gate warnings as hints before the allow decision is emitted. */
71
84
  export declare function emitSopWarnings(io: ProgramIO, decision: SopAllow): void;
72
85
  /**
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).
86
+ * SOP gate allowed the command.
87
+ *
88
+ * `--json` mode emits the canonical envelope on stdout (the documented
89
+ * contract for downstream tooling) with the Claude Code allow decision merged
90
+ * into it, so stdout stays ONE JSON document the host can parse — see
91
+ * {@link emitAllowSkipped} for the shape and the reason.
77
92
  */
78
93
  export declare function emitSopAllow(io: ProgramIO, options: GateEnforceCliOptions, decision: SopAllow): void;
79
94
  export {};