peaks-loop 4.1.20 → 4.1.22

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 (32) hide show
  1. package/.claude-plugin/marketplace.json +3 -6
  2. package/CHANGELOG.md +198 -0
  3. package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
  4. package/dist/cli/commands/mut-commands-helpers.js +44 -26
  5. package/dist/cli/commands/observability-commands-baseline.d.ts +26 -0
  6. package/dist/cli/commands/observability-commands-baseline.js +74 -0
  7. package/dist/cli/commands/observability-commands-queries.d.ts +5 -0
  8. package/dist/cli/commands/observability-commands-queries.js +8 -1
  9. package/dist/cli/commands/observability-commands.d.ts +7 -1
  10. package/dist/cli/commands/observability-commands.js +19 -3
  11. package/dist/services/artifacts/repair-cycle-service.d.ts +23 -0
  12. package/dist/services/artifacts/repair-cycle-service.js +23 -0
  13. package/dist/services/distribution/json-layout.d.ts +20 -0
  14. package/dist/services/distribution/json-layout.js +195 -0
  15. package/dist/services/distribution/plugin-manifest.d.ts +31 -2
  16. package/dist/services/distribution/plugin-manifest.js +40 -4
  17. package/dist/services/observability/aggregation-helpers.d.ts +12 -8
  18. package/dist/services/observability/aggregation-helpers.js +12 -25
  19. package/dist/services/observability/aggregation-types.d.ts +40 -0
  20. package/dist/services/observability/aggregation.d.ts +2 -1
  21. package/dist/services/observability/aggregation.js +16 -25
  22. package/dist/services/observability/repair-cycle-metric.d.ts +67 -0
  23. package/dist/services/observability/repair-cycle-metric.js +223 -0
  24. package/dist/services/observability/report-formatter.d.ts +1 -1
  25. package/dist/services/observability/report-formatter.js +16 -4
  26. package/dist/services/observability/results-baseline-artifact.d.ts +29 -0
  27. package/dist/services/observability/results-baseline-artifact.js +80 -0
  28. package/dist/services/observability/results-baseline-rows.d.ts +33 -0
  29. package/dist/services/observability/results-baseline-rows.js +127 -0
  30. package/dist/services/observability/results-baseline.d.ts +115 -0
  31. package/dist/services/observability/results-baseline.js +101 -0
  32. package/package.json +7 -5
@@ -1,13 +1,13 @@
1
1
  {
2
2
  "metadata": {
3
3
  "pluginRoot": ".",
4
- "version": "4.1.20"
4
+ "version": "4.1.22"
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.20",
10
+ "version": "4.1.22",
11
11
  "author": {
12
12
  "name": "SquabbyZ"
13
13
  },
@@ -61,10 +61,7 @@
61
61
  "mcpServers": {
62
62
  "peaks": {
63
63
  "command": "peaks",
64
- "args": [
65
- "mcp",
66
- "serve"
67
- ]
64
+ "args": ["mcp", "serve"]
68
65
  }
69
66
  },
70
67
  "skills": [
package/CHANGELOG.md CHANGED
@@ -1,5 +1,203 @@
1
1
  # Changelog
2
2
 
3
+ ## 4.1.22 — 2026-10-25(把"只测了两个子命令"的漏测补上,把"不是缺陷"的两条说准)
4
+
5
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改任何运行时语义、
6
+ **没有**动 mutation 阈值、**没有**碰发布流程;三个代码切片各自只加守卫、**零清单改动**,本切片只做
7
+ **版本锁步 + 生成清单重生成 + 这段 CHANGELOG**。
8
+
9
+ **一句话:`peaks mut` 指向一个**不存在**的 `--test-files` 时,`mut mutants` 过去会**静默回退**到默认发现,
10
+ 为一个从未存在过的文件报出**满分 kill rate**(exit 0)—— 而最初的记录只测了 `run` 与 `asserts`、**漏了
11
+ `mutants`**;这一版三个子命令统一 **exit 1 + 具名码 `MUT_TEST_FILE_NOT_FOUND`**。**
12
+
13
+ ### 1. 缺陷:`peaks mut` 缺失 `--test-files` 路径时的静默回退(三个子命令这一版统一堵上)
14
+
15
+ 同一夹具、同一台机器上的**前后两侧实测**(改前取自 `HEAD` 的隔离树,改后取自本仓库的工作树):
16
+
17
+ | 子命令 | 改前 | 改后 |
18
+ |---|---|---|
19
+ | `mut mutants` | **exit 0、写出了报告、killRate 1、mutantsTotal 2** | **exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告** |
20
+ | `mut run` | exit 1 `MUT_FAILED`(裸 ENOENT + 机器绝对路径) | exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告 |
21
+ | `mut asserts` | exit 1 `UNHANDLED_ERROR`(裸 ENOENT + 机器绝对路径) | exit 1 `MUT_TEST_FILE_NOT_FOUND`,无报告 |
22
+
23
+ **"静默回退"不是推测,是可比对的 digest。** 改前 `mut mutants` + 缺失文件写出的报告,digest 与
24
+ `mut mutants` + **一个能用的 glob** 写出的报告**完全相同**(两者都是 `339e74cc…`)—— 缺失的路径被
25
+ Stryker 的文件匹配丢掉,vitest runner 跑了项目自己的默认发现,然后为一个**从未存在过的文件**报出了满分。
26
+ 改后同一个 glob 仍然 exit 0、digest 仍是 `339e74cc…`(能用的 glob 保持能用),而缺失文件一律 exit 1。
27
+
28
+ 改后三个子命令的消息**逐字节相同**,且**只给相对 `--project` 的路径**,并附近邻候选:
29
+
30
+ ```
31
+ Test file not found: tests/does-not-exist.test.ts
32
+ Near-miss candidates:
33
+ - tests/add.test.ts
34
+ ```
35
+
36
+ **快乐路径没变**:有效测试文件下 `mut run` 的报告 digest 改前改后**都是 `96595ff6…`**(`killRate` 1、
37
+ `mutantsTotal` 2)。守卫 `tests/unit/cli/mut-test-file-not-found.test.ts` **15 个用例全绿**。
38
+
39
+ **这一段要更正的是一条"不可复现"的判断。** 最初的记录写的是"缺失 `--test-files` 路径静默回退默认发现、
40
+ 可能报出完美 kill rate"**不可复现** —— 那条判断**只测了 `run` 与 `asserts`**,**漏了 `mutants`**;在
41
+ `mutants` 上它**确实复现**(exit 0 + 满分 kill rate)。本批的三个子命令现在统一成同一个具名码。
42
+
43
+ ### 2. 生成的插件清单:`prettier --check` 从 exit 1 变成 exit 0(本次 bump 没有把形状缺陷带回来)
44
+
45
+ 清单是**受版本控制的生成产物**(`npm run plugin:manifest`),渲染器过去把**每个**数组都展开,
46
+ 所以清单**不是** prettier-clean 的。实测(用仓库自己的 prettier 与仓库自己的 prettier 配置):
47
+
48
+ | | 改前(`HEAD` 的渲染) | 改后(本切片 bump 之后的渲染) |
49
+ |---|---|---|
50
+ | `prettier --check` | **exit 1(不是 prettier-clean)** | **exit 0** |
51
+ | 行数(按换行计数) | 200 | **197** |
52
+ | 行数(按 `split("\n").length`) | 201 | **198** |
53
+
54
+ 唯一的变化是 `"args": ["mcp", "serve"]`(4 行 → 1 行)。改前的清单经 prettier 规范化后的输出,
55
+ sha256 是 `849e6168…`,与**本切片 bump 之前**工作树里那份清单(切片 B 的渲染,版本 4.1.21)
56
+ **逐字节相同** —— 说明新的渲染器产出的正是 prettier 自己的形状。本切片 bump 之后的清单
57
+ sha256 是 `fd087f50…`,同样 prettier-clean。
58
+
59
+ **依赖集不变**:根 manifest 的 `dependencies`(12 项)与 `devDependencies`(19 项)与 bump 前**逐字段相同**
60
+ (本切片实测:五个 manifest 各自只有 `version` 一个键变了);`prettier` 仍在 `devDependencies`、
61
+ **不在** `dependencies`(实测 `prettier in dependencies: false`),发布包的运行时依赖集没有变化。
62
+
63
+ **版本戳在两处**:`metadata.version` 与 `plugins[0].version` 都读 `4.1.22`;连跑两次生成**逐字节相同**
64
+ (sha256 `fd087f50…`)。
65
+
66
+ ### 3. 包入口不变量(只加守卫,**零清单改动**)
67
+
68
+ 根包声明 **1** 个入口(`bin.peaks → ./bin/peaks.js`),`peaks-loop-mut` 声明 **2** 个
69
+ (`exports["."].types`、`exports["."].default`)。守卫 `tests/unit/release/package-entry-points-guard.test.ts`
70
+ **9 passed | 1 skipped**(构建产物在 → 磁盘检查**跑起来**:2 checked、0 skipped)。守卫钉住三条不变量:
71
+ 声明的入口必须落在该包自己的 `files` 白名单里;`main` 与 `exports["."].default` 若同时声明必须一致;
72
+ 根包**不得**把副作用型 CLI 模块声明成库入口。
73
+
74
+ ### 4. 两条必须说准的事(一条"不是缺陷",一条"更正旧判断")
75
+
76
+ **(1)"包缺 `main`"不是缺陷 —— 它不是这次修的东西。** `peaks-loop-mut` 的主入口**已经**由 `exports["."]` 表达
77
+ (`exports["."].default → ./dist/index.js`)。实测(本机 Node v24.12.0):
78
+
79
+ - 一个同时声明 `main` 与 `exports` 的包,被 import 时加载的是 **`exports`** 那个目标(输出 `LOADED:EXPORTS`)
80
+ —— Node 解析 `exports` 优先于 `main`,`main` 被忽略;
81
+ - **`require()` 一个纯 ESM 包在 Node v24.12.0 上是成功的**(实测 `REQUIRE_OK`;`ERR_REQUIRE_ESM`
82
+ 只对 Node < 22.12 成立)。所以诚实的理由是**"冗余且会误导"**,而**不是**"无法 require";
83
+ - 根包则**绝不能**加 `main`/`exports`:`dist/cli/index.js` 在**模块顶层**就
84
+ `program.parseAsync(process.argv)`(`src/cli/index.ts:61`),实测**import 它就会把 CLI 跑起来**
85
+ —— 导入过程中就打出了 CLI 的帮助横幅。
86
+
87
+ **(2)"静默回退不可复现"这条旧判断本身不成立 —— 这一版是真的堵上了。** 它在 `mut mutants` 上**确实复现**
88
+ (exit 0 + 满分 kill rate),缺的只是那次测量里的**第三个子命令**。所以这里不是"没有缺陷",而是
89
+ "缺陷是真的、这一版三个子命令统一堵上了"。
90
+
91
+ ### 5. 版本号本身
92
+
93
+ | 包 | 从 | 到 |
94
+ |---|---|---|
95
+ | `peaks-loop` | 4.1.21 | **4.1.22** |
96
+ | `peaks-loop-shared` | 0.0.110 | 0.0.111 |
97
+ | `peaks-loop-mut` | 0.1.75 | 0.1.76 |
98
+ | `peaks-loop-shared-channel` | 0.0.78 | 0.0.79 |
99
+ | `peaks-loop-internal-runtime` | 0.0.61 | 0.0.62 |
100
+
101
+ 版本号由 `scripts/bump-version.mjs` 产生(不是手打的):根 `4.1.21 → 4.1.22`,四个 workspace 包在同一次
102
+ lockstep 里各 +1,五个 manifest **各自只有 `version` 一个键变了**;`scripts/sync-version.mjs` 把
103
+ `CLI_VERSION` 与 `RUNTIME_VERSION` 写成 `4.1.22`,`node scripts/verify-version-parity.mjs runtime-src`
104
+ **exit 0**。
105
+
106
+ **发布顺序(发版前必须知道)**:`pnpm pack` 会把根包 `workspace:*` 依赖改写成**精确 semver pin**,
107
+ 所以 `peaks-loop@4.1.22` 打包后的 manifest 依赖的是 `peaks-loop-mut@0.1.76`、
108
+ `peaks-loop-shared@0.0.111`、`peaks-loop-shared-channel@0.0.79`、`peaks-loop-internal-runtime@0.0.62`
109
+ (实测:从 tarball 里读出的 `package/package.json`)。这四个版本**在 registry 上都不存在**(实测 `E404`),
110
+ 所以**这四个包必须先发布**,`peaks-loop@4.1.22` 才能被消费者装上;在它们发布之前,根包是不可安装的。
111
+
112
+ ## 4.1.21 — 2026-10-25(把"返工循环"数对,把"没测过"说出来)
113
+
114
+ **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改 fail-open 策略、
115
+ 没有动 auto-compact 三档阈值,peaks-code 的 11 步工序与 Gate A–G **一字不改**;改的是**一个度量的口径**、
116
+ **两个门禁的诚实性**、**CI 的一个咨询性作业**、**一个算错单位的守卫**,以及**版本号本身**。
117
+
118
+ **一句话:`peaks observability` 之前把 QA 自己的内部迁移当成了"返工循环"数出来,于是 108 个切片里有 82 个
119
+ "超了帽"。这一版把它数对了 —— 真正超帽的只有 1 个。**
120
+
121
+ ### 1. 缺陷:返工循环数的是 QA 的内部迁移
122
+
123
+ 旧口径数的是每一条 `detail.artifactRole === 'qa'` 的 slice-transition 事件。那是 QA 阶段内部的迁移,
124
+ 和"RD 被打回去重做"没有关系。四个**各自独立**的缺陷叠在一起:
125
+
126
+ | # | 缺陷 | 实测 |
127
+ |---|---|---|
128
+ | 1 | 数的是 QA 内部迁移 | 与返工无关 |
129
+ | 2 | 一次迁移发**两条**事件 | 约 8ms 间隔,其中一条没有 `detail.from` |
130
+ | 3 | `detail.from` 不可信 | 仅 606/1102 存在,其中 **395 条与事件顺序矛盾** ⇒ 绝不读它 |
131
+ | 4 | `qa-handoff` 是 **RD 的状态** | 正常收尾 `verdict-issued→qa-handoff→handed-off` 是**快乐路径**,不是返工 |
132
+
133
+ **实测对比**(10 个会话目录、108 个切片、1102 条事件):
134
+
135
+ | 口径 | ≥cap(3) 的切片 | 分布 | 峰值 |
136
+ |---|---|---|---|
137
+ | 旧(QA 事件计数) | **82 / 108** | `0:11 1:1 2:14 3:2 4:50 5:12 6:5 7:2 8:7 9:1 11:2 24:1` | **24** |
138
+ | 新(返工循环) | **1 / 108** | `0:93 1:13 2:1 5:1` | **5** |
139
+
140
+ 唯一真正超帽的那一个,序列是真的:`implemented→qa-handoff→running→verdict-issued→implemented→…`,五轮。
141
+
142
+ ### 2. 度量版本化:v2 与 v1 并列,不让新旧数被静默对比
143
+
144
+ - `metricVersion: 2`;旧计数保留在 `legacyQaEventCount` 下,`capHitCount` 用 v2。
145
+ - 返工循环的判定:QA 阶段后回到 RD **工作态**(`draft|spec-locked|implemented`)才算;一次返工只计一次;
146
+ 重复发射折叠;**绝不读 `detail.from`**;纯 QA 往返单列为 QA rounds,不混进返工。
147
+
148
+ ### 3. 新命令与可复算的基线产物
149
+
150
+ - `peaks observability repair-cycles --all-sessions --json`
151
+ - `peaks observability baseline [--write|--check]` → `.peaks/observability/results-baseline.json`
152
+
153
+ 基线行只用**率与峰值**;人口描述被单独隔离并注明"不得作为门禁",产物里写明 `ciEnforceable: false`
154
+ 及其原因(观测数据在 gitignored 的会话空间里,CI 拿不到,硬接只会造一条假门禁)。
155
+
156
+ ### 4. 没测过的门禁,必须说"没测过"
157
+
158
+ Phase A benchmark 门禁从二态改成**三态**:
159
+
160
+ | 状态 | 退出码 | `passesGate` |
161
+ |---|---|---|
162
+ | `measured-and-passed` | 0 | `true` |
163
+ | `measured-and-failed` | 1 | `false` |
164
+ | `not-measured` | **3** | **`null`** |
165
+ | runner 报错 | 2 | — |
166
+
167
+ 旧的 `passesGate: false` 既可能是"测了没过",也可能是"根本没测",读者分不出来,而根因恰恰是**零次测量**。
168
+ 现在未决绝不等同于通过。runner 也拒绝把 `--out` 指向记忆库(exit 2)—— 它以前每次运行都会往
169
+ `.peaks/memory/` 里写一份 `_TBD_` 存根,覆盖掉平台预留给人类真实测量的那个文件。
170
+
171
+ ### 5. 一个算错单位的守卫
172
+
173
+ `peaks-loop-internal-runtime` 的 resource-budget 守卫里,`process.cpuUsage()` 返回**微秒**,
174
+ 而旧式算法 `/1e6 × 100` 得到的是**厘秒**。于是 `maxCpuPct: 5` 实际约束的是 **50 毫秒** CPU,不是 5%。
175
+ 现在 `cpuPct` 是**占单核百分比**,另出 `cpuCentiseconds` 字段,字段名与 `Sample` 形状保持不变。
176
+
177
+ ### 6. CI 增加一个咨询性作业
178
+
179
+ `changed-tests-subset`:**只在 PR、只在 ubuntu**、`continue-on-error: true`(咨询性,不挡合并)、
180
+ `fetch-depth: 0` + 显式 merge-base、`PEAKS_VITEST_MAX_WORKERS: 4`、`timeout-minutes: 60`。
181
+ 权威门禁仍是全量 `test` 作业。
182
+
183
+ ### 7. 这次发版带走了什么
184
+
185
+ `v4.1.20..HEAD` 的 44 个改动文件里,**13 个真正进入已发布产物**(12 个经 `src/**→dist/**`,
186
+ 1 个是 `peaks-loop-internal-runtime`);`dist/` 占 tarball 2889 条目中的 2670(92.4%)。
187
+ 发版影响面按**输入集**算:展开 `package.json#files` 白名单得直发集,再补上 `src/**→dist/**` 与
188
+ `packages/**→内部包` 的间接集,最后排除发布元数据。
189
+
190
+ ### 8. 版本号本身
191
+
192
+ | 包 | 从 | 到 |
193
+ |---|---|---|
194
+ | `peaks-loop` | 4.1.20 | **4.1.21** |
195
+ | `peaks-loop-shared` | 0.0.109 | 0.0.110 |
196
+ | `peaks-loop-mut` | 0.1.74 | 0.1.75 |
197
+ | `peaks-loop-shared-channel` | 0.0.77 | 0.0.78 |
198
+ | `peaks-loop-internal-runtime` | 0.0.60 | 0.0.61 |
199
+
200
+
3
201
  ## 4.1.20 — 2026-10-25(从 4.1.18 起装不上的根包,修好了)
4
202
 
5
203
  **版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
@@ -13,7 +13,8 @@
13
13
  * toolchain must surface a MACHINE-READABLE error code (for example
14
14
  * `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
15
15
  * non-zero exit code — never `UNHANDLED_ERROR` with a bare
16
- * "Cannot find package".
16
+ * "Cannot find package". The same rule now covers a missing `--test-files`
17
+ * path (`MUT_TEST_FILE_NOT_FOUND`).
17
18
  */
18
19
  import { Command } from 'commander';
19
20
  import { type AssertionsReport, type MutationReport, type StrykerInvoker } from 'peaks-loop-mut';
@@ -75,16 +76,15 @@ export declare function mutErrorCode(err: unknown): string;
75
76
  /** The human-readable half of the envelope. */
76
77
  export declare function mutErrorMessage(err: unknown): string;
77
78
  /**
78
- * Emit the failure envelope on stderr and set a non-zero exit code.
79
- * stdout stays reserved for the `--json` payload (R6), so the envelope
80
- * goes to stderr exactly like every other peaks CLI error.
79
+ * Emit the failure envelope on stderr and set a non-zero exit code. Its
80
+ * `data` field carries the machine-readable detail — where an ABSOLUTE path
81
+ * belongs; stdout stays reserved for the `--json` payload (R6).
81
82
  */
82
83
  export declare function emitMutError(io: ProgramIO, err: unknown): void;
83
84
  /**
84
85
  * `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
85
86
  * report). One-axis: --session-id required.
86
- */
87
- export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
87
+ */ export declare function buildMutRunCommand(invokeStryker: StrykerInvoker, io: ProgramIO): Command;
88
88
  /**
89
89
  * `peaks mut mutants` — Stryker only; writes a stub-assertions
90
90
  * mut-report.json. One-axis: --session-id required.
@@ -13,10 +13,11 @@
13
13
  * toolchain must surface a MACHINE-READABLE error code (for example
14
14
  * `MUT_TOOLCHAIN_UNAVAILABLE`) plus an actionable message and a
15
15
  * non-zero exit code — never `UNHANDLED_ERROR` with a bare
16
- * "Cannot find package".
16
+ * "Cannot find package". The same rule now covers a missing `--test-files`
17
+ * path (`MUT_TEST_FILE_NOT_FOUND`).
17
18
  */
18
19
  import { Command } from 'commander';
19
- import { buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
20
+ import { assertTestFilesUsable, buildMutReport, runMutation, scanAssertions } from 'peaks-loop-mut';
20
21
  import { printErrorEnvelope } from '../cli-helpers.js';
21
22
  /**
22
23
  * Fallback code for a mutation failure that carries no named code of its
@@ -98,18 +99,27 @@ export function mutErrorMessage(err) {
98
99
  return err instanceof Error ? err.message : String(err);
99
100
  }
100
101
  /**
101
- * Emit the failure envelope on stderr and set a non-zero exit code.
102
- * stdout stays reserved for the `--json` payload (R6), so the envelope
103
- * goes to stderr exactly like every other peaks CLI error.
102
+ * Emit the failure envelope on stderr and set a non-zero exit code. Its
103
+ * `data` field carries the machine-readable detail — where an ABSOLUTE path
104
+ * belongs; stdout stays reserved for the `--json` payload (R6).
104
105
  */
105
106
  export function emitMutError(io, err) {
106
- printErrorEnvelope(io, 'mut', mutErrorCode(err), mutErrorMessage(err), {}, []);
107
+ const details = err?.details;
108
+ const data = details && typeof details === 'object' ? details : {};
109
+ printErrorEnvelope(io, 'mut', mutErrorCode(err), mutErrorMessage(err), data, []);
110
+ }
111
+ /**
112
+ * Validate `--test-files` BEFORE any Stryker run, scan or report write: a
113
+ * missing path must fail with the named code, never reach the mutation
114
+ * engine. A PATTERN is accepted here — Stryker expands patterns.
115
+ */
116
+ function assertMutTestFiles(a) {
117
+ assertTestFilesUsable({ project: a.project, testFiles: a.testFiles, allowPatterns: true });
107
118
  }
108
119
  /**
109
120
  * `peaks mut run` — the full mut pipeline (Stryker + assertion scan +
110
121
  * report). One-axis: --session-id required.
111
- */
112
- export function buildMutRunCommand(invokeStryker, io) {
122
+ */ export function buildMutRunCommand(invokeStryker, io) {
113
123
  return new Command('run')
114
124
  .description('Run the full mut pipeline (Stryker + assertion scan + report). One-axis: --session-id required.')
115
125
  .requiredOption('--project <path>', 'project root')
@@ -121,6 +131,7 @@ export function buildMutRunCommand(invokeStryker, io) {
121
131
  .option('--json', 'machine-readable output', false)
122
132
  .action(async (a) => {
123
133
  try {
134
+ assertMutTestFiles(a);
124
135
  const { mutation } = await runMutation({
125
136
  project: a.project,
126
137
  testFiles: a.testFiles,
@@ -172,6 +183,7 @@ export function buildMutMutantsCommand(invokeStryker, io) {
172
183
  .option('--json', 'machine-readable output', false)
173
184
  .action(async (a) => {
174
185
  try {
186
+ assertMutTestFiles(a);
175
187
  const { mutation } = await runMutation({
176
188
  project: a.project,
177
189
  testFiles: a.testFiles,
@@ -213,24 +225,30 @@ export function buildMutAssertsCommand(io) {
213
225
  .requiredOption('--out <path>', 'output path for mut-report.json')
214
226
  .option('--json', 'machine-readable output', false)
215
227
  .action(async (a) => {
216
- const assertions = await scanAssertions({
217
- project: a.project,
218
- testFiles: a.testFiles
219
- });
220
- const report = await buildMutReport({
221
- inputSig: a.inputSig,
222
- out: a.out,
223
- mutation: emptyMutation(),
224
- assertions
225
- });
226
- emitSummary(io, a.json, {
227
- ok: true,
228
- sha256: report.sha256,
229
- passed: report.thresholds.passed,
230
- path: a.out
231
- });
232
- if (!report.thresholds.passed) {
233
- process.exitCode = 1;
228
+ try {
229
+ assertMutTestFiles(a);
230
+ const assertions = await scanAssertions({
231
+ project: a.project,
232
+ testFiles: a.testFiles
233
+ });
234
+ const report = await buildMutReport({
235
+ inputSig: a.inputSig,
236
+ out: a.out,
237
+ mutation: emptyMutation(),
238
+ assertions
239
+ });
240
+ emitSummary(io, a.json, {
241
+ ok: true,
242
+ sha256: report.sha256,
243
+ passed: report.thresholds.passed,
244
+ path: a.out
245
+ });
246
+ if (!report.thresholds.passed) {
247
+ process.exitCode = 1;
248
+ }
249
+ }
250
+ catch (err) {
251
+ emitMutError(io, err);
234
252
  }
235
253
  });
236
254
  }
@@ -0,0 +1,26 @@
1
+ /**
2
+ * `src/cli/commands/observability-commands-baseline.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS. `peaks observability baseline` is the ONE
5
+ * observability command that writes: `--write` regenerates the tracked
6
+ * results-layer baseline at `.peaks/observability/results-baseline.json`. It
7
+ * lives in its own module because the sibling query module is at the
8
+ * file-size cap, and because a writing command wants its own readable
9
+ * surface rather than being folded into a read-only one.
10
+ *
11
+ * The tracked artifact is NOT CI-enforceable — its source data is gitignored
12
+ * session state — so `--check` never reports a false pass: a missing tracked
13
+ * artifact and a machine with no session data are both failures, because in
14
+ * both cases nothing was compared.
15
+ */
16
+ import { type ProgramIO } from '../cli-helpers.js';
17
+ /**
18
+ * `peaks observability baseline` — print / write / check the tracked
19
+ * results-layer baseline.
20
+ */
21
+ export declare function runBaseline(io: ProgramIO, options: {
22
+ project?: string;
23
+ json?: boolean;
24
+ write?: boolean;
25
+ check?: boolean;
26
+ }): void;
@@ -0,0 +1,74 @@
1
+ /**
2
+ * `src/cli/commands/observability-commands-baseline.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS. `peaks observability baseline` is the ONE
5
+ * observability command that writes: `--write` regenerates the tracked
6
+ * results-layer baseline at `.peaks/observability/results-baseline.json`. It
7
+ * lives in its own module because the sibling query module is at the
8
+ * file-size cap, and because a writing command wants its own readable
9
+ * surface rather than being folded into a read-only one.
10
+ *
11
+ * The tracked artifact is NOT CI-enforceable — its source data is gitignored
12
+ * session state — so `--check` never reports a false pass: a missing tracked
13
+ * artifact and a machine with no session data are both failures, because in
14
+ * both cases nothing was compared.
15
+ */
16
+ import { fail, ok } from 'peaks-loop-shared/result';
17
+ import { RESULTS_BASELINE_RELATIVE_PATH, computeResultsBaseline } from '../../services/observability/results-baseline.js';
18
+ import { compareResultsBaseline, readTrackedResultsBaseline, writeResultsBaseline } from '../../services/observability/results-baseline-artifact.js';
19
+ import { getErrorMessage, printResult } from '../cli-helpers.js';
20
+ import { resolveProjectRoot } from './observability-commands-queries.js';
21
+ /**
22
+ * The `--check` verdict. It NEVER reports a false pass: a missing tracked
23
+ * artifact and a machine with no session data are both failures, because in
24
+ * both cases there is nothing to compare and nothing was verified.
25
+ */
26
+ function baselineCheckResult(projectRoot, baseline) {
27
+ const tracked = readTrackedResultsBaseline(projectRoot);
28
+ if (tracked === null) {
29
+ return fail('observability.baseline', 'RESULTS_BASELINE_MISSING', `No tracked results baseline at ${RESULTS_BASELINE_RELATIVE_PATH} — there is nothing to compare against.`, { mode: 'check', trackedPath: RESULTS_BASELINE_RELATIVE_PATH, drifts: [], baseline }, ['Run `peaks observability baseline --write` to create the tracked artifact.']);
30
+ }
31
+ if (baseline.population.sliceCount === 0) {
32
+ return fail('observability.baseline', 'RESULTS_BASELINE_NO_SESSION_DATA', 'No observability session data found in this project, so the baseline could not be compared. ' +
33
+ 'This is NOT a pass: the source data lives in gitignored session state that a CI runner does not have.', { mode: 'check', trackedPath: RESULTS_BASELINE_RELATIVE_PATH, drifts: [], baseline }, ['Run this check on a machine that has recorded session data.']);
34
+ }
35
+ const drifts = compareResultsBaseline(baseline, tracked);
36
+ if (drifts.length > 0) {
37
+ return fail('observability.baseline', 'RESULTS_BASELINE_DRIFT', `${drifts.length} baseline row(s) drifted past the documented tolerance.`, { mode: 'check', trackedPath: RESULTS_BASELINE_RELATIVE_PATH, drifts, baseline }, [
38
+ 'Review the drift, then regenerate with `peaks observability baseline --write` if it is intended.'
39
+ ]);
40
+ }
41
+ return ok('observability.baseline', { mode: 'check', trackedPath: RESULTS_BASELINE_RELATIVE_PATH, drifts, baseline }, []);
42
+ }
43
+ /**
44
+ * `peaks observability baseline` — print / write / check the tracked
45
+ * results-layer baseline.
46
+ */
47
+ export function runBaseline(io, options) {
48
+ const projectRoot = resolveProjectRoot(options.project);
49
+ try {
50
+ const baseline = computeResultsBaseline(projectRoot);
51
+ if (options.write === true) {
52
+ const path = writeResultsBaseline(projectRoot, baseline);
53
+ printResult(io, ok('observability.baseline', { mode: 'write', path, baseline }, []), options.json);
54
+ return;
55
+ }
56
+ if (options.check === true) {
57
+ const result = baselineCheckResult(projectRoot, baseline);
58
+ printResult(io, result, options.json);
59
+ if (!result.ok)
60
+ process.exitCode = 1;
61
+ return;
62
+ }
63
+ const warnings = baseline.population.sliceCount === 0
64
+ ? [
65
+ 'No observability session data found — the computed baseline is empty and is NOT a meaningful measurement.'
66
+ ]
67
+ : [];
68
+ printResult(io, ok('observability.baseline', { mode: 'print', baseline }, warnings), options.json);
69
+ }
70
+ catch (error) {
71
+ printResult(io, fail('observability.baseline', 'OBSERVABILITY_BASELINE_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
72
+ process.exitCode = 1;
73
+ }
74
+ }
@@ -11,6 +11,10 @@
11
11
  * `runReport` stayed behind on purpose: it carries a
12
12
  * `max-lines-per-function` finding, and a NEW module in this campaign must be
13
13
  * clean outright — hoisting it would move a finding into a brand-new file.
14
+ *
15
+ * LATER ADDITION — `peaks observability repair-cycles` also grew an
16
+ * `--all-sessions` scope, so the whole recorded history of a project can be
17
+ * measured from the command itself.
14
18
  */
15
19
  import { type ProgramIO } from '../cli-helpers.js';
16
20
  export declare function resolveProjectRoot(optionProject: string | undefined): string;
@@ -34,4 +38,5 @@ export declare function runRepairCycles(io: ProgramIO, options: {
34
38
  project?: string;
35
39
  session?: string;
36
40
  json?: boolean;
41
+ allSessions?: boolean;
37
42
  }): void;
@@ -11,6 +11,10 @@
11
11
  * `runReport` stayed behind on purpose: it carries a
12
12
  * `max-lines-per-function` finding, and a NEW module in this campaign must be
13
13
  * clean outright — hoisting it would move a finding into a brand-new file.
14
+ *
15
+ * LATER ADDITION — `peaks observability repair-cycles` also grew an
16
+ * `--all-sessions` scope, so the whole recorded history of a project can be
17
+ * measured from the command itself.
14
18
  */
15
19
  import { fail, ok } from 'peaks-loop-shared/result';
16
20
  import { findProjectRoot } from '../../services/config/config-safety.js';
@@ -95,7 +99,10 @@ export function runFanout(io, options) {
95
99
  }
96
100
  export function runRepairCycles(io, options) {
97
101
  const projectRoot = resolveProjectRoot(options.project);
98
- const sessionId = resolveSessionId(options.session, projectRoot);
102
+ // `--all-sessions` is the escape from the canonical-session binding: the
103
+ // recorded history (every session in the project) is the population the
104
+ // results baseline and the metric comparison are measured over.
105
+ const sessionId = options.allSessions === true ? undefined : resolveSessionId(options.session, projectRoot);
99
106
  try {
100
107
  const events = sessionId !== undefined
101
108
  ? readSessionEvents(projectRoot, sessionId)
@@ -4,12 +4,18 @@
4
4
  *
5
5
  * markdown report formatter is implemented.
6
6
  *
7
- * Read-only — never writes. Reads the JSONL metrics files emitted
7
+ * Read-only over the JSONL metrics files emitted
8
8
  * by the `peaks request transition` hook (Slice A) plus the future
9
9
  * Slice C hook sites (dispatch / checkpoint / mode-gate / context
10
10
  * / post-compact). The aggregations tolerate zero events gracefully
11
11
  * so each subcommand returns a meaningful empty result on a fresh
12
12
  * tree.
13
+ *
14
+ * ONE EXCEPTION TO THE READ-ONLY RULE: `peaks observability baseline
15
+ * --write` regenerates the tracked results-layer baseline at
16
+ * `.peaks/observability/results-baseline.json`. It is the only command
17
+ * here that writes, and it exists because the results layer needs a
18
+ * baseline that can be regenerated and compared on demand.
13
19
  */
14
20
  import type { Command } from 'commander';
15
21
  import { type ProgramIO } from '../cli-helpers.js';
@@ -4,12 +4,18 @@
4
4
  *
5
5
  * markdown report formatter is implemented.
6
6
  *
7
- * Read-only — never writes. Reads the JSONL metrics files emitted
7
+ * Read-only over the JSONL metrics files emitted
8
8
  * by the `peaks request transition` hook (Slice A) plus the future
9
9
  * Slice C hook sites (dispatch / checkpoint / mode-gate / context
10
10
  * / post-compact). The aggregations tolerate zero events gracefully
11
11
  * so each subcommand returns a meaningful empty result on a fresh
12
12
  * tree.
13
+ *
14
+ * ONE EXCEPTION TO THE READ-ONLY RULE: `peaks observability baseline
15
+ * --write` regenerates the tracked results-layer baseline at
16
+ * `.peaks/observability/results-baseline.json`. It is the only command
17
+ * here that writes, and it exists because the results layer needs a
18
+ * baseline that can be regenerated and compared on demand.
13
19
  */
14
20
  import { fail, ok } from 'peaks-loop-shared/result';
15
21
  import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
@@ -22,6 +28,7 @@ import { renderObservabilityReport } from '../../services/observability/report-f
22
28
  // `runReport` — the one function here carrying a finding — stayed behind, so no
23
29
  // finding moved into the new module.
24
30
  import { resolveProjectRoot, resolveSessionId, runFanout, runRepairCycles, runSlices, runStatus } from './observability-commands-queries.js';
31
+ import { runBaseline } from './observability-commands-baseline.js';
25
32
  const VALID_PERIODS = ['day', 'week', 'month'];
26
33
  function runReport(io, options) {
27
34
  const projectRoot = resolveProjectRoot(options.project);
@@ -93,11 +100,20 @@ export function registerObservabilityCommands(program, io) {
93
100
  });
94
101
  addJsonOption(observability
95
102
  .command('repair-cycles')
96
- .description('RD → QA repair-cycle count per slice. Cap = 3 (peaks-code repair-loop contract); capHit flag is set when any slice hits the cap.')
103
+ .description('RD → QA repair-cycle count per slice (metric version 2: a repair cycle is a return to an RD work state after a QA phase). Cap = 3 (peaks-code repair-loop contract); capHit flag is set when any slice hits the cap. The version-1 qa-role event count is reported beside it as legacyQaEventCount — it is NOT a repair-cycle count.')
97
104
  .option('--project <path>', 'target project root (defaults to git root or cwd)')
98
- .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action((options) => {
105
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
106
+ .option('--all-sessions', 'measure the whole recorded history of the project instead of the canonical session binding')).action((options) => {
99
107
  runRepairCycles(io, options);
100
108
  });
109
+ addJsonOption(observability
110
+ .command('baseline')
111
+ .description('Results-layer baseline over the whole recorded history. Prints the computed baseline; --write regenerates the tracked artifact at .peaks/observability/results-baseline.json; --check compares the computed baseline with the tracked one and reports drift. The tracked artifact is NOT CI-enforceable: its source data is gitignored session state.')
112
+ .option('--project <path>', 'target project root (defaults to git root or cwd)')
113
+ .option('--write', 'regenerate the tracked results baseline artifact')
114
+ .option('--check', 'compare the computed baseline against the tracked artifact and report drift')).action((options) => {
115
+ runBaseline(io, options);
116
+ });
101
117
  observability
102
118
  .command('report')
103
119
  .description('Render a markdown summary suitable for paste into PR descriptions or .peaks/PROJECT.md timeline entries. Default period = day; --json emits an envelope wrapping the markdown body. Output sections: header + status summary + slice table + fanout table + repair-cycle table + top-N slowest slices.')
@@ -1,3 +1,26 @@
1
+ /**
2
+ * `src/services/artifacts/repair-cycle-service.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS. It counts the RD/QA repair cycles recorded in a
5
+ * request artifact's OWN transition notes (`QA return-to-rd cycle N`). That
6
+ * note is the artifact contract's authoritative record of a repair loop, so
7
+ * this is the number the repair gate reads.
8
+ *
9
+ * CROSS-REFERENCE — THERE IS A SECOND, DIFFERENT REPAIR-CYCLE COUNT, and the
10
+ * two must never be merged or compared:
11
+ *
12
+ * - THIS module counts the artifact's own `QA return-to-rd cycle N` notes.
13
+ * - `src/services/observability/repair-cycle-metric.ts` counts repair
14
+ * cycles RECONSTRUCTED from the observability event stream: a return to
15
+ * an RD work state (`draft` | `spec-locked` | `implemented`) after the
16
+ * slice had entered a QA phase (`running` | `verdict-issued`).
17
+ *
18
+ * They disagree on purpose: the note is written by whoever routes the repair
19
+ * and may be missing, while the event stream is reconstructed after the fact
20
+ * from the transitions that actually happened. `peaks observability
21
+ * repair-cycles` reports the reconstructed one, versioned, with the
22
+ * version-1 qa-event count kept beside it under its own name.
23
+ */
1
24
  export type RepairCycleEntry = {
2
25
  cycle: number;
3
26
  timestamp: string;
@@ -1,3 +1,26 @@
1
+ /**
2
+ * `src/services/artifacts/repair-cycle-service.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS. It counts the RD/QA repair cycles recorded in a
5
+ * request artifact's OWN transition notes (`QA return-to-rd cycle N`). That
6
+ * note is the artifact contract's authoritative record of a repair loop, so
7
+ * this is the number the repair gate reads.
8
+ *
9
+ * CROSS-REFERENCE — THERE IS A SECOND, DIFFERENT REPAIR-CYCLE COUNT, and the
10
+ * two must never be merged or compared:
11
+ *
12
+ * - THIS module counts the artifact's own `QA return-to-rd cycle N` notes.
13
+ * - `src/services/observability/repair-cycle-metric.ts` counts repair
14
+ * cycles RECONSTRUCTED from the observability event stream: a return to
15
+ * an RD work state (`draft` | `spec-locked` | `implemented`) after the
16
+ * slice had entered a QA phase (`running` | `verdict-issued`).
17
+ *
18
+ * They disagree on purpose: the note is written by whoever routes the repair
19
+ * and may be missing, while the event stream is reconstructed after the fact
20
+ * from the transitions that actually happened. `peaks observability
21
+ * repair-cycles` reports the reconstructed one, versioned, with the
22
+ * version-1 qa-event count kept beside it under its own name.
23
+ */
1
24
  import { showRequestArtifact } from './request-artifact-service.js';
2
25
  const DEFAULT_MAX_CYCLES = 3;
3
26
  // Matches transition notes Code writes during repair routing.