peaks-loop 4.1.19 → 4.1.21
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.
- package/.claude-plugin/marketplace.json +2 -2
- package/CHANGELOG.md +219 -0
- package/dist/cli/commands/observability-commands-baseline.d.ts +26 -0
- package/dist/cli/commands/observability-commands-baseline.js +74 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +5 -0
- package/dist/cli/commands/observability-commands-queries.js +8 -1
- package/dist/cli/commands/observability-commands.d.ts +7 -1
- package/dist/cli/commands/observability-commands.js +19 -3
- package/dist/services/artifacts/repair-cycle-service.d.ts +23 -0
- package/dist/services/artifacts/repair-cycle-service.js +23 -0
- package/dist/services/observability/aggregation-helpers.d.ts +12 -8
- package/dist/services/observability/aggregation-helpers.js +12 -25
- package/dist/services/observability/aggregation-types.d.ts +40 -0
- package/dist/services/observability/aggregation.d.ts +2 -1
- package/dist/services/observability/aggregation.js +16 -25
- package/dist/services/observability/repair-cycle-metric.d.ts +67 -0
- package/dist/services/observability/repair-cycle-metric.js +223 -0
- package/dist/services/observability/report-formatter.d.ts +1 -1
- package/dist/services/observability/report-formatter.js +16 -4
- package/dist/services/observability/results-baseline-artifact.d.ts +29 -0
- package/dist/services/observability/results-baseline-artifact.js +80 -0
- package/dist/services/observability/results-baseline-rows.d.ts +33 -0
- package/dist/services/observability/results-baseline-rows.js +127 -0
- package/dist/services/observability/results-baseline.d.ts +115 -0
- package/dist/services/observability/results-baseline.js +101 -0
- package/package.json +8 -5
- package/scripts/canonical-store-report.mjs +84 -0
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"metadata": {
|
|
3
3
|
"pluginRoot": ".",
|
|
4
|
-
"version": "4.1.
|
|
4
|
+
"version": "4.1.21"
|
|
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.
|
|
10
|
+
"version": "4.1.21",
|
|
11
11
|
"author": {
|
|
12
12
|
"name": "SquabbyZ"
|
|
13
13
|
},
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,224 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 4.1.21 — 2026-10-25(把"返工循环"数对,把"没测过"说出来)
|
|
4
|
+
|
|
5
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**改 fail-open 策略、
|
|
6
|
+
没有动 auto-compact 三档阈值,peaks-code 的 11 步工序与 Gate A–G **一字不改**;改的是**一个度量的口径**、
|
|
7
|
+
**两个门禁的诚实性**、**CI 的一个咨询性作业**、**一个算错单位的守卫**,以及**版本号本身**。
|
|
8
|
+
|
|
9
|
+
**一句话:`peaks observability` 之前把 QA 自己的内部迁移当成了"返工循环"数出来,于是 108 个切片里有 82 个
|
|
10
|
+
"超了帽"。这一版把它数对了 —— 真正超帽的只有 1 个。**
|
|
11
|
+
|
|
12
|
+
### 1. 缺陷:返工循环数的是 QA 的内部迁移
|
|
13
|
+
|
|
14
|
+
旧口径数的是每一条 `detail.artifactRole === 'qa'` 的 slice-transition 事件。那是 QA 阶段内部的迁移,
|
|
15
|
+
和"RD 被打回去重做"没有关系。四个**各自独立**的缺陷叠在一起:
|
|
16
|
+
|
|
17
|
+
| # | 缺陷 | 实测 |
|
|
18
|
+
|---|---|---|
|
|
19
|
+
| 1 | 数的是 QA 内部迁移 | 与返工无关 |
|
|
20
|
+
| 2 | 一次迁移发**两条**事件 | 约 8ms 间隔,其中一条没有 `detail.from` |
|
|
21
|
+
| 3 | `detail.from` 不可信 | 仅 606/1102 存在,其中 **395 条与事件顺序矛盾** ⇒ 绝不读它 |
|
|
22
|
+
| 4 | `qa-handoff` 是 **RD 的状态** | 正常收尾 `verdict-issued→qa-handoff→handed-off` 是**快乐路径**,不是返工 |
|
|
23
|
+
|
|
24
|
+
**实测对比**(10 个会话目录、108 个切片、1102 条事件):
|
|
25
|
+
|
|
26
|
+
| 口径 | ≥cap(3) 的切片 | 分布 | 峰值 |
|
|
27
|
+
|---|---|---|---|
|
|
28
|
+
| 旧(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** |
|
|
29
|
+
| 新(返工循环) | **1 / 108** | `0:93 1:13 2:1 5:1` | **5** |
|
|
30
|
+
|
|
31
|
+
唯一真正超帽的那一个,序列是真的:`implemented→qa-handoff→running→verdict-issued→implemented→…`,五轮。
|
|
32
|
+
|
|
33
|
+
### 2. 度量版本化:v2 与 v1 并列,不让新旧数被静默对比
|
|
34
|
+
|
|
35
|
+
- `metricVersion: 2`;旧计数保留在 `legacyQaEventCount` 下,`capHitCount` 用 v2。
|
|
36
|
+
- 返工循环的判定:QA 阶段后回到 RD **工作态**(`draft|spec-locked|implemented`)才算;一次返工只计一次;
|
|
37
|
+
重复发射折叠;**绝不读 `detail.from`**;纯 QA 往返单列为 QA rounds,不混进返工。
|
|
38
|
+
|
|
39
|
+
### 3. 新命令与可复算的基线产物
|
|
40
|
+
|
|
41
|
+
- `peaks observability repair-cycles --all-sessions --json`
|
|
42
|
+
- `peaks observability baseline [--write|--check]` → `.peaks/observability/results-baseline.json`
|
|
43
|
+
|
|
44
|
+
基线行只用**率与峰值**;人口描述被单独隔离并注明"不得作为门禁",产物里写明 `ciEnforceable: false`
|
|
45
|
+
及其原因(观测数据在 gitignored 的会话空间里,CI 拿不到,硬接只会造一条假门禁)。
|
|
46
|
+
|
|
47
|
+
### 4. 没测过的门禁,必须说"没测过"
|
|
48
|
+
|
|
49
|
+
Phase A benchmark 门禁从二态改成**三态**:
|
|
50
|
+
|
|
51
|
+
| 状态 | 退出码 | `passesGate` |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| `measured-and-passed` | 0 | `true` |
|
|
54
|
+
| `measured-and-failed` | 1 | `false` |
|
|
55
|
+
| `not-measured` | **3** | **`null`** |
|
|
56
|
+
| runner 报错 | 2 | — |
|
|
57
|
+
|
|
58
|
+
旧的 `passesGate: false` 既可能是"测了没过",也可能是"根本没测",读者分不出来,而根因恰恰是**零次测量**。
|
|
59
|
+
现在未决绝不等同于通过。runner 也拒绝把 `--out` 指向记忆库(exit 2)—— 它以前每次运行都会往
|
|
60
|
+
`.peaks/memory/` 里写一份 `_TBD_` 存根,覆盖掉平台预留给人类真实测量的那个文件。
|
|
61
|
+
|
|
62
|
+
### 5. 一个算错单位的守卫
|
|
63
|
+
|
|
64
|
+
`peaks-loop-internal-runtime` 的 resource-budget 守卫里,`process.cpuUsage()` 返回**微秒**,
|
|
65
|
+
而旧式算法 `/1e6 × 100` 得到的是**厘秒**。于是 `maxCpuPct: 5` 实际约束的是 **50 毫秒** CPU,不是 5%。
|
|
66
|
+
现在 `cpuPct` 是**占单核百分比**,另出 `cpuCentiseconds` 字段,字段名与 `Sample` 形状保持不变。
|
|
67
|
+
|
|
68
|
+
### 6. CI 增加一个咨询性作业
|
|
69
|
+
|
|
70
|
+
`changed-tests-subset`:**只在 PR、只在 ubuntu**、`continue-on-error: true`(咨询性,不挡合并)、
|
|
71
|
+
`fetch-depth: 0` + 显式 merge-base、`PEAKS_VITEST_MAX_WORKERS: 4`、`timeout-minutes: 60`。
|
|
72
|
+
权威门禁仍是全量 `test` 作业。
|
|
73
|
+
|
|
74
|
+
### 7. 这次发版带走了什么
|
|
75
|
+
|
|
76
|
+
`v4.1.20..HEAD` 的 44 个改动文件里,**13 个真正进入已发布产物**(12 个经 `src/**→dist/**`,
|
|
77
|
+
1 个是 `peaks-loop-internal-runtime`);`dist/` 占 tarball 2889 条目中的 2670(92.4%)。
|
|
78
|
+
发版影响面按**输入集**算:展开 `package.json#files` 白名单得直发集,再补上 `src/**→dist/**` 与
|
|
79
|
+
`packages/**→内部包` 的间接集,最后排除发布元数据。
|
|
80
|
+
|
|
81
|
+
### 8. 版本号本身
|
|
82
|
+
|
|
83
|
+
| 包 | 从 | 到 |
|
|
84
|
+
|---|---|---|
|
|
85
|
+
| `peaks-loop` | 4.1.20 | **4.1.21** |
|
|
86
|
+
| `peaks-loop-shared` | 0.0.109 | 0.0.110 |
|
|
87
|
+
| `peaks-loop-mut` | 0.1.74 | 0.1.75 |
|
|
88
|
+
| `peaks-loop-shared-channel` | 0.0.77 | 0.0.78 |
|
|
89
|
+
| `peaks-loop-internal-runtime` | 0.0.60 | 0.0.61 |
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
## 4.1.20 — 2026-10-25(从 4.1.18 起装不上的根包,修好了)
|
|
93
|
+
|
|
94
|
+
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
|
|
95
|
+
没有改 fail-open 策略、没有动 auto-compact 三档阈值,peaks-code 的 11 步工序与 Gate A–G **一字不改**;
|
|
96
|
+
改的是**根包自己的打包白名单**(§1–§2)、**消费者能看到的说法**(§3–§4)与**版本号本身**(§5)。
|
|
97
|
+
|
|
98
|
+
**一句话:`npm i -g peaks-loop` 从 4.1.18 起就是装不上的。这一版把它修好了。**
|
|
99
|
+
|
|
100
|
+
### 1. 缺陷:白名单少了一行,于是整个安装死在 postinstall
|
|
101
|
+
|
|
102
|
+
根包的 `package.json#files` 是**白名单** —— 只有被它点名的文件才会进 tarball。
|
|
103
|
+
`scripts/install-skills-bundles.mjs`(**在包里**)import 了 `./canonical-store-report.mjs`,
|
|
104
|
+
而后者**不在白名单里**,于是 npm 发出去的是**一个没有同伙的 import 方**。
|
|
105
|
+
|
|
106
|
+
Node 的 ESM 加载器在跑任何代码之前就要把整张模块图解析完,所以这不是"少了个功能",
|
|
107
|
+
是**图连不上**,安装死在 `postinstall`,CLI 根本轮不到上场:
|
|
108
|
+
|
|
109
|
+
```
|
|
110
|
+
npm error Error [ERR_MODULE_NOT_FOUND]: Cannot find module
|
|
111
|
+
'.../node_modules/peaks-loop/scripts/canonical-store-report.mjs'
|
|
112
|
+
imported from .../node_modules/peaks-loop/scripts/install-skills-bundles.mjs
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
**根因提交**是 `12c71e55`("fix(gates): a surface must not say what the code does not do")。
|
|
116
|
+
那一个提交在 `scripts/` 下**新增了 3 个** canonical-store 脚本(`canonical-store-fs.mjs`、
|
|
117
|
+
`canonical-store-marker.mjs`、`canonical-store-report.mjs`),给 importer 接上了其中的**第三个**,
|
|
118
|
+
而白名单**只加了那 3 个里的 2 个** —— 漏掉的正是 `-report`。该提交落在 `v4.1.17` 与 `v4.1.18`
|
|
119
|
+
之间(`git merge-base --is-ancestor` 实测:在 `v4.1.18`/`v4.1.19` 之内,在 `v4.1.16`/`v4.1.17` 之外)。
|
|
120
|
+
|
|
121
|
+
### 2. 实测证据(每个数字都来自本次实测)
|
|
122
|
+
|
|
123
|
+
**两个互相独立的方法**,同一个结论:
|
|
124
|
+
|
|
125
|
+
| 方法 | 4.1.17 | 4.1.18 | 4.1.19 |
|
|
126
|
+
|---|---|---|---|
|
|
127
|
+
| **真实 `npm install`**(隔离 prefix + 隔离 HOME) | **exit 0**,`added 127 packages in 10s` | **exit 1**,`ERR_MODULE_NOT_FOUND` | **exit 1**,`ERR_MODULE_NOT_FOUND` |
|
|
128
|
+
| **静态解析已发布 tarball**(`scripts/*.mjs` 数 / 本地相对 import 数 / **未命中**的目标数) | 16 / 24 / **0** | 18 / 27 / **1** | 18 / 27 / **1** |
|
|
129
|
+
|
|
130
|
+
那个"**1**"在 4.1.18 与 4.1.19 里是**同一个**目标:`install-skills-bundles.mjs -> ./canonical-store-report.mjs`。
|
|
131
|
+
**4.1.19 tarball 里所有已发布脚本的本地相对 import 全被枚举过一遍,未命中的只有这一个** ——
|
|
132
|
+
其余没进包的 `scripts/*.mjs` 都是本就不该进包的 dev / build / 测试脚本。
|
|
133
|
+
|
|
134
|
+
**不是 4.1.19 那一批引入的**:`v4.1.18` 与 `v4.1.19` 之间,`package.json#files` 的脚本条目
|
|
135
|
+
**增 0 减 0**,importer 的 blob 哈希**完全相同**(`05e80b3da11df0fee5f870fa3285a0fe153d0ff3`)。
|
|
136
|
+
4.1.19 是**继承**了这个缺陷,不是**造成**了它。
|
|
137
|
+
|
|
138
|
+
**修好之后的实测**(不只是"打包内容看着对",是**真的装得上、跑得起来**):
|
|
139
|
+
|
|
140
|
+
- 把修好的树 `pnpm pack` 出来的 tarball 里,`scripts/*.mjs` 共 **19** 个,
|
|
141
|
+
`scripts/canonical-store-report.mjs` **在包里**,已发布脚本的本地相对 import **未命中 0 个**。
|
|
142
|
+
- **真实安装**:把那个 tarball 装进一个隔离的 prefix(`HOME`、`PEAKS_CLAUDE_SKILLS_DIR`、
|
|
143
|
+
`PEAKS_CLAUDE_AGENTS_DIR` 全部指到临时目录),`npm install` **退出 0**
|
|
144
|
+
(`added 293 packages in 40s`),**没有** `ERR_MODULE_NOT_FOUND`,postinstall 跑完。
|
|
145
|
+
- **装完就能用**:装好的包里 `peaks --version` 打出 **4.1.20**(退出 0),
|
|
146
|
+
`peaks mut --help` 打出完整命令树(退出 0)。
|
|
147
|
+
- 说明一句方法上的诚实:这 4 个 workspace 子包在本次版本里是**新版本号**,registry 上**还没有**
|
|
148
|
+
(实测 `npm view peaks-loop-mut@0.1.74` → **404**),所以端到端安装里这 4 个内部依赖是用
|
|
149
|
+
**本树自己打出来的 tarball**(`file:` spec)解析的,其余依赖全部走 registry。
|
|
150
|
+
这正是发布流程"先发子包、后发根包"之后的拓扑;**打包白名单这件事本身**由上面的 tarball
|
|
151
|
+
内容测量直接回答。
|
|
152
|
+
|
|
153
|
+
### 3. 修法:一行白名单 + 一个防回归守卫
|
|
154
|
+
|
|
155
|
+
**修法就是一行** —— 根 `package.json#files` 里加一条 `"scripts/canonical-store-report.mjs",`,
|
|
156
|
+
`files` 的其余部分**一字未动**。白名单**没有**被放宽成整个 `scripts/`:那些 dev / build / 测试
|
|
157
|
+
脚本是**故意**不进包的,放宽会把它们一起发出去。
|
|
158
|
+
|
|
159
|
+
**现在有了防回归守卫**:`tests/unit/release/packaging-shipped-scripts-import-guard.test.ts`
|
|
160
|
+
(**13** 个用例)。它**静态**地读根 manifest 的白名单,取出 `scripts/*.mjs` 条目作为**已发布脚本集**,
|
|
161
|
+
解析每个已发布脚本的本地相对 import,断言**每个被 import 的目标也在已发布集里**。
|
|
162
|
+
**不联网、不查 registry、不做真实 `npm install`**。
|
|
163
|
+
|
|
164
|
+
它守的是"**已发布脚本之间的**本地相对 import",**不会**要求 dev / build / 测试脚本进包。
|
|
165
|
+
而且它被证明**真的会红**:临时把那一行从 `files` 里去掉 → 守卫 **exit 1**(`4 failed | 9 passed (13)`);
|
|
166
|
+
逐字节还原(sha256 比对一致)→ 再跑 → **exit 0**(`13 passed (13)`)。**只看到绿不算验证过。**
|
|
167
|
+
|
|
168
|
+
守卫在修好的树上的数字:**已发布脚本条目 19 个**,**检查的本地相对 import 27 个**,**未命中 0 个**。
|
|
169
|
+
|
|
170
|
+
### 4. 顺手拆掉的一颗雷:`main` 指向了不在白名单里的文件
|
|
171
|
+
|
|
172
|
+
工作树里根 `package.json` 带着 4 处**与本次缺陷无关**的改动(`repository.url`、`bin.peaks`,
|
|
173
|
+
以及新增的 `main`、`directories`)。其中 **`main: "stryker.conf.js"`** 是一颗雷:
|
|
174
|
+
`stryker.conf.js` **不在 `files` 白名单里**,所以它**不会**进 tarball ——
|
|
175
|
+
而 `main` 正是消费者 `import 'peaks-loop'` 解析到的入口。
|
|
176
|
+
留着它,就等于**修好一个"装得上"的包,再塞一个"装上了但主入口用不了"的坑**。
|
|
177
|
+
这 4 处已全部**还原成 `HEAD` 的原值**(`main` 与 `directories` 直接删掉)。
|
|
178
|
+
|
|
179
|
+
**成因是查出来的,不是猜的**:`npm pkg fix` 会把 `repository.url` 归一化成 `git+https://` 形式、
|
|
180
|
+
把 `bin` 的 `./` 前缀去掉;`npm pkg set` 会写入 `main` 与 `directories`。
|
|
181
|
+
而**本次用的版本锁步脚本不会**(实测:跑一次 `scripts/bump-version.mjs`,这 4 个字段
|
|
182
|
+
**0 个**被改动)。
|
|
183
|
+
|
|
184
|
+
### 5. 版本号与发布含义
|
|
185
|
+
|
|
186
|
+
- 根包 `peaks-loop` **4.1.19 → 4.1.20**。`packages/` 下**实际只有 4 个**可发布 workspace 包,
|
|
187
|
+
由正路脚本**锁步升**(子包规则 = patch 位 +1,major/minor 不变):
|
|
188
|
+
|
|
189
|
+
| 包 | 改前 | 改后 |
|
|
190
|
+
| ----------------------------- | ------- | ---------- |
|
|
191
|
+
| `peaks-loop`(根) | 4.1.19 | **4.1.20** |
|
|
192
|
+
| `peaks-loop-mut` | 0.1.73 | **0.1.74** |
|
|
193
|
+
| `peaks-loop-shared` | 0.0.108 | 0.0.109 |
|
|
194
|
+
| `peaks-loop-shared-channel` | 0.0.76 | 0.0.77 |
|
|
195
|
+
| `peaks-loop-internal-runtime` | 0.0.59 | 0.0.60 |
|
|
196
|
+
|
|
197
|
+
- 两个**受版本控制**的版本戳同步为 4.1.20:`packages/peaks-loop-shared/src/version.ts` 的 `CLI_VERSION`
|
|
198
|
+
与 `packages/peaks-loop-internal-runtime/src/index.ts` 的 `RUNTIME_VERSION`。
|
|
199
|
+
- **版本字段一个都没手改**:全部由 `scripts/bump-version.mjs --to 4.1.20` 与 `scripts/sync-version.mjs`
|
|
200
|
+
产生。逐字段比对证明:**5 个 manifest 各自只有 `version` 一个键变了**;根 manifest 相对 `HEAD`
|
|
201
|
+
只多两处 —— `version` 与 `files` 里的那一行。
|
|
202
|
+
- **维护者要做的**(本次**没有**做):合并后 `git tag v4.1.20` + push,由发布流程发包。
|
|
203
|
+
**本次不打 tag、不发布、不提交。**
|
|
204
|
+
|
|
205
|
+
### 6. 验证
|
|
206
|
+
|
|
207
|
+
- `node scripts/verify-version-parity.mjs runtime-src` 退出 **0**(`RUNTIME_VERSION=4.1.20`)。
|
|
208
|
+
- `pnpm install --frozen-lockfile` 退出 **0**,而且**锁文件一个字都没改** ——
|
|
209
|
+
sha256 前后同为 `7f60e065a8df3a63d7b03a2fc8f91db9628362387997fc77655c8c75ef46cc72`,
|
|
210
|
+
`git diff pnpm-lock.yaml` 为**空**。workspace 包在锁文件里是 `link:` 引用(**不记版本号**),
|
|
211
|
+
所以版本号变动**不需要**动锁文件。
|
|
212
|
+
- 逐字段比对:**5 个 manifest 各自只有 `version` 一个键变了**。
|
|
213
|
+
- 新守卫 `tests/unit/release/packaging-shipaged-scripts-import-guard.test.ts`:
|
|
214
|
+
**13 passed (13)**;去掉那一行白名单则 **4 failed | 9 passed (13)**,逐字节还原后回到全绿。
|
|
215
|
+
- **端到端**:修好的树 `pnpm pack` → 隔离 prefix 里 `npm install` **退出 0**
|
|
216
|
+
(`added 293 packages in 40s`)、**无** `ERR_MODULE_NOT_FOUND`;装好的包里
|
|
217
|
+
`peaks --version` 打出 **4.1.20**,`peaks mut --help` 退出 **0**。
|
|
218
|
+
- `.claude-plugin/marketplace.json` 由 `npm run plugin:manifest` 重生成,**跑两次逐字节相同**。
|
|
219
|
+
- `tsc -p tsconfig.json --noEmit` 退出 **0**;`prettier --check` 对本次改动的清单文件退出 **0**;
|
|
220
|
+
`eslint --config config/eslint/.peaks-rules.cjs --no-ignore` 对本次改动的文件 **0 findings**。
|
|
221
|
+
|
|
3
222
|
## 4.1.19 — 2026-10-24(`peaks mut` 在真实用户机器上**真的能跑**)
|
|
4
223
|
|
|
5
224
|
**版本级别**:候选 **patch**(沿用常设规则"默认版本新增采用最小的版本位")。本次**没有**新增门禁族、
|
|
@@ -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
|
-
|
|
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
|
|
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
|
|
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)')
|
|
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.
|
|
@@ -2,13 +2,18 @@
|
|
|
2
2
|
* `src/services/observability/aggregation-helpers.ts`
|
|
3
3
|
*
|
|
4
4
|
* The event-detail readers the aggregations in `aggregation.ts` are built on
|
|
5
|
-
* (category test, `detail` field extraction, timestamp difference)
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
5
|
+
* (category test, `detail` field extraction, timestamp difference) and the
|
|
6
|
+
* two event-source helpers the CLI calls. Moved verbatim (wave 3, file-size
|
|
7
|
+
* cap campaign) so the aggregation module stays under the 300 raw-line cap.
|
|
8
|
+
* The first four were module-private before the move and are NOT re-exported
|
|
9
|
+
* from `aggregation.ts`; the two event-source helpers were public and are
|
|
10
|
+
* re-exported there, so that module's public surface is unchanged.
|
|
11
|
+
*
|
|
12
|
+
* The per-slice repair-cycle count that used to live here moved to
|
|
13
|
+
* `repair-cycle-metric.ts`: the version-1 counter this file carried counted
|
|
14
|
+
* QA's own state transitions, not repair loops, and the corrected metric
|
|
15
|
+
* needs its own module to keep the version marker and the legacy count
|
|
16
|
+
* together.
|
|
12
17
|
*/
|
|
13
18
|
import { type ObservabilityEvent } from './observability-service.js';
|
|
14
19
|
export declare function isSliceTransition(event: ObservabilityEvent): event is ObservabilityEvent & {
|
|
@@ -17,6 +22,5 @@ export declare function isSliceTransition(event: ObservabilityEvent): event is O
|
|
|
17
22
|
export declare function artifactRole(event: ObservabilityEvent): string;
|
|
18
23
|
export declare function transitionTo(event: ObservabilityEvent): string | null;
|
|
19
24
|
export declare function durationMsBetween(firstTs: string, lastTs: string): number;
|
|
20
|
-
export declare function computeRepairCyclesBySlice(events: readonly ObservabilityEvent[]): Map<string, number>;
|
|
21
25
|
export declare function readAllSessionEvents(projectRoot: string): ObservabilityEvent[];
|
|
22
26
|
export declare function readSessionEvents(projectRoot: string, sessionId: string): ObservabilityEvent[];
|
|
@@ -2,13 +2,18 @@
|
|
|
2
2
|
* `src/services/observability/aggregation-helpers.ts`
|
|
3
3
|
*
|
|
4
4
|
* The event-detail readers the aggregations in `aggregation.ts` are built on
|
|
5
|
-
* (category test, `detail` field extraction, timestamp difference)
|
|
6
|
-
*
|
|
7
|
-
*
|
|
8
|
-
*
|
|
9
|
-
*
|
|
10
|
-
*
|
|
11
|
-
*
|
|
5
|
+
* (category test, `detail` field extraction, timestamp difference) and the
|
|
6
|
+
* two event-source helpers the CLI calls. Moved verbatim (wave 3, file-size
|
|
7
|
+
* cap campaign) so the aggregation module stays under the 300 raw-line cap.
|
|
8
|
+
* The first four were module-private before the move and are NOT re-exported
|
|
9
|
+
* from `aggregation.ts`; the two event-source helpers were public and are
|
|
10
|
+
* re-exported there, so that module's public surface is unchanged.
|
|
11
|
+
*
|
|
12
|
+
* The per-slice repair-cycle count that used to live here moved to
|
|
13
|
+
* `repair-cycle-metric.ts`: the version-1 counter this file carried counted
|
|
14
|
+
* QA's own state transitions, not repair loops, and the corrected metric
|
|
15
|
+
* needs its own module to keep the version marker and the legacy count
|
|
16
|
+
* together.
|
|
12
17
|
*/
|
|
13
18
|
import { readObservabilityEvents } from './observability-service.js';
|
|
14
19
|
import { listSessionDirsWithMetrics } from './jsonl-store.js';
|
|
@@ -31,24 +36,6 @@ export function durationMsBetween(firstTs, lastTs) {
|
|
|
31
36
|
}
|
|
32
37
|
return Math.max(0, b - a);
|
|
33
38
|
}
|
|
34
|
-
export function computeRepairCyclesBySlice(events) {
|
|
35
|
-
// Repair cycle = each rd → qa transition within one slice (proxy for the
|
|
36
|
-
// RD→QA→RD loop). For each slice we count qa transitions that follow an
|
|
37
|
-
// rd transition. Multiple qa transitions on the same slice are capped by
|
|
38
|
-
// REPAIR_CYCLE_CAP at the report level — the per-slice count here is the
|
|
39
|
-
// raw observation count.
|
|
40
|
-
const cyclesBySlice = new Map();
|
|
41
|
-
for (const event of events) {
|
|
42
|
-
if (!isSliceTransition(event))
|
|
43
|
-
continue;
|
|
44
|
-
const rid = event.sliceRid;
|
|
45
|
-
const role = artifactRole(event);
|
|
46
|
-
if (role === 'qa') {
|
|
47
|
-
cyclesBySlice.set(rid, (cyclesBySlice.get(rid) ?? 0) + 1);
|
|
48
|
-
}
|
|
49
|
-
}
|
|
50
|
-
return cyclesBySlice;
|
|
51
|
-
}
|
|
52
39
|
export function readAllSessionEvents(projectRoot) {
|
|
53
40
|
const sessions = listSessionDirsWithMetrics(projectRoot);
|
|
54
41
|
const all = [];
|