peaks-loop 4.1.20 → 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 +89 -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 +7 -5
|
@@ -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,94 @@
|
|
|
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
|
+
|
|
3
92
|
## 4.1.20 — 2026-10-25(从 4.1.18 起装不上的根包,修好了)
|
|
4
93
|
|
|
5
94
|
**版本级别**:候选 **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 = [];
|
|
@@ -34,15 +34,55 @@ export type FanoutBreakdown = {
|
|
|
34
34
|
total: number;
|
|
35
35
|
perRole: Record<ObservabilitySubagentRole, number>;
|
|
36
36
|
};
|
|
37
|
+
/**
|
|
38
|
+
* The v1 convention, kept alive under a name that says what it is. It counts
|
|
39
|
+
* slice-transition events whose `detail.artifactRole === 'qa'` — QA's own
|
|
40
|
+
* internal state transitions, doubled by the duplicate emission, and NOT a
|
|
41
|
+
* repair-cycle count. It exists so the v1 and v2 numbers can be compared side
|
|
42
|
+
* by side instead of being compared by accident.
|
|
43
|
+
*/
|
|
44
|
+
export type LegacyQaEventCount = {
|
|
45
|
+
metric: 'qa-role-transition-event-count';
|
|
46
|
+
metricVersion: 1;
|
|
47
|
+
note: string;
|
|
48
|
+
total: number;
|
|
49
|
+
peak: number;
|
|
50
|
+
capHitCount: number;
|
|
51
|
+
perSlice: Array<{
|
|
52
|
+
sliceRid: string;
|
|
53
|
+
eventCount: number;
|
|
54
|
+
}>;
|
|
55
|
+
};
|
|
56
|
+
/**
|
|
57
|
+
* QA phases, reported separately from repair cycles: `qa-handoff →
|
|
58
|
+
* verdict-issued → qa-handoff` is a QA round, not an RD rework.
|
|
59
|
+
*/
|
|
60
|
+
export type QaRoundSummary = {
|
|
61
|
+
metric: 'qa-rounds';
|
|
62
|
+
total: number;
|
|
63
|
+
peak: number;
|
|
64
|
+
perSlice: Array<{
|
|
65
|
+
sliceRid: string;
|
|
66
|
+
roundCount: number;
|
|
67
|
+
}>;
|
|
68
|
+
};
|
|
37
69
|
export type RepairCycleReport = {
|
|
70
|
+
metric: 'repair-cycles';
|
|
71
|
+
/** Which convention produced the numbers below. */
|
|
72
|
+
metricVersion: number;
|
|
73
|
+
/** What the metric counts, in one sentence. */
|
|
74
|
+
definition: string;
|
|
38
75
|
totalCycles: number;
|
|
39
76
|
cap: number;
|
|
40
77
|
capHit: boolean;
|
|
78
|
+
/** Slices at or over the cap — computed from the v2 metric. */
|
|
41
79
|
capHitCount: number;
|
|
42
80
|
perSlice: Array<{
|
|
43
81
|
sliceRid: string;
|
|
44
82
|
cycleCount: number;
|
|
45
83
|
}>;
|
|
84
|
+
qaRounds: QaRoundSummary;
|
|
85
|
+
legacyQaEventCount: LegacyQaEventCount;
|
|
46
86
|
};
|
|
47
87
|
export declare const TERMINAL_HAPPY_STATES: ReadonlySet<string>;
|
|
48
88
|
export declare const TERMINAL_FAIL_STATES: ReadonlySet<string>;
|
|
@@ -16,8 +16,9 @@
|
|
|
16
16
|
import { type ObservabilityEvent } from './observability-service.js';
|
|
17
17
|
import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
|
|
18
18
|
export { REPAIR_CYCLE_CAP } from './aggregation-types.js';
|
|
19
|
+
export { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
|
|
19
20
|
export { readAllSessionEvents, readSessionEvents } from './aggregation-helpers.js';
|
|
20
|
-
export type { DashboardMetrics, FanoutBreakdown, Period, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation-types.js';
|
|
21
|
+
export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation-types.js';
|
|
21
22
|
export declare function aggregateStatus(events: readonly ObservabilityEvent[]): StatusAggregate;
|
|
22
23
|
export declare function aggregateSlices(events: readonly ObservabilityEvent[]): SliceRollup[];
|
|
23
24
|
export declare function aggregateFanout(events: readonly ObservabilityEvent[]): FanoutBreakdown;
|
|
@@ -14,16 +14,19 @@
|
|
|
14
14
|
* builds the read-side surface so Slice C is purely additive.
|
|
15
15
|
*/
|
|
16
16
|
import { readObservabilityEvents } from './observability-service.js';
|
|
17
|
-
import {
|
|
18
|
-
import {
|
|
17
|
+
import { TERMINAL_FAIL_STATES, TERMINAL_HAPPY_STATES, ZERO_FANOUT } from './aggregation-types.js';
|
|
18
|
+
import { durationMsBetween, isSliceTransition, transitionTo } from './aggregation-helpers.js';
|
|
19
|
+
import { buildRepairCycleReport, computeSliceRepairMetrics } from './repair-cycle-metric.js';
|
|
19
20
|
// The result shapes and their data (terminal states, repair-loop cap, zeroed
|
|
20
|
-
// fan-out row) live in `aggregation-types.ts`; the event-detail readers
|
|
21
|
-
//
|
|
22
|
-
//
|
|
23
|
-
//
|
|
24
|
-
//
|
|
25
|
-
//
|
|
21
|
+
// fan-out row) live in `aggregation-types.ts`; the event-detail readers and
|
|
22
|
+
// the event-source helpers live in `aggregation-helpers.ts` (wave-3 file-size
|
|
23
|
+
// cap split; declarations moved verbatim). The repair-cycle METRIC lives in
|
|
24
|
+
// `repair-cycle-metric.ts` — version 2 of it, with the version-1 count kept
|
|
25
|
+
// beside it under its own name. Every PUBLIC name is re-exported below so
|
|
26
|
+
// importers keep resolving it from `aggregation.js` unchanged; the
|
|
27
|
+
// module-private readers are imported for use here and not re-exported.
|
|
26
28
|
export { REPAIR_CYCLE_CAP } from './aggregation-types.js';
|
|
29
|
+
export { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
|
|
27
30
|
export { readAllSessionEvents, readSessionEvents } from './aggregation-helpers.js';
|
|
28
31
|
// ----- per-slice rollup (shared by status + slices queries) -----
|
|
29
32
|
function rollupSlices(events) {
|
|
@@ -69,10 +72,10 @@ function rollupSlices(events) {
|
|
|
69
72
|
// ----- public aggregations -----
|
|
70
73
|
export function aggregateStatus(events) {
|
|
71
74
|
const bySlice = rollupSlices(events);
|
|
72
|
-
const
|
|
75
|
+
const metrics = computeSliceRepairMetrics(events);
|
|
73
76
|
let repairCyclePeak = 0;
|
|
74
77
|
for (const rollup of bySlice.values()) {
|
|
75
|
-
const cycles =
|
|
78
|
+
const cycles = metrics.get(rollup.sliceRid)?.repairCycles ?? 0;
|
|
76
79
|
rollup.repairCycleCount = cycles;
|
|
77
80
|
if (cycles > repairCyclePeak)
|
|
78
81
|
repairCyclePeak = cycles;
|
|
@@ -91,9 +94,9 @@ export function aggregateStatus(events) {
|
|
|
91
94
|
}
|
|
92
95
|
export function aggregateSlices(events) {
|
|
93
96
|
const bySlice = rollupSlices(events);
|
|
94
|
-
const
|
|
97
|
+
const metrics = computeSliceRepairMetrics(events);
|
|
95
98
|
for (const rollup of bySlice.values()) {
|
|
96
|
-
rollup.repairCycleCount =
|
|
99
|
+
rollup.repairCycleCount = metrics.get(rollup.sliceRid)?.repairCycles ?? 0;
|
|
97
100
|
}
|
|
98
101
|
return Array.from(bySlice.values()).sort((a, b) => a.sliceRid.localeCompare(b.sliceRid));
|
|
99
102
|
}
|
|
@@ -111,19 +114,7 @@ export function aggregateFanout(events) {
|
|
|
111
114
|
return { total, perRole };
|
|
112
115
|
}
|
|
113
116
|
export function aggregateRepairCycles(events) {
|
|
114
|
-
|
|
115
|
-
const perSlice = Array.from(cyclesBySlice.entries())
|
|
116
|
-
.map(([sliceRid, cycleCount]) => ({ sliceRid, cycleCount }))
|
|
117
|
-
.sort((a, b) => a.sliceRid.localeCompare(b.sliceRid));
|
|
118
|
-
const totalCycles = perSlice.reduce((sum, row) => sum + row.cycleCount, 0);
|
|
119
|
-
const capHitCount = perSlice.filter((row) => row.cycleCount >= REPAIR_CYCLE_CAP).length;
|
|
120
|
-
return {
|
|
121
|
-
totalCycles,
|
|
122
|
-
cap: REPAIR_CYCLE_CAP,
|
|
123
|
-
capHit: capHitCount > 0,
|
|
124
|
-
capHitCount,
|
|
125
|
-
perSlice
|
|
126
|
-
};
|
|
117
|
+
return buildRepairCycleReport(events);
|
|
127
118
|
}
|
|
128
119
|
export function periodStartIso(period, now = () => new Date()) {
|
|
129
120
|
const d = now();
|