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.
Files changed (26) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +89 -0
  3. package/dist/cli/commands/observability-commands-baseline.d.ts +26 -0
  4. package/dist/cli/commands/observability-commands-baseline.js +74 -0
  5. package/dist/cli/commands/observability-commands-queries.d.ts +5 -0
  6. package/dist/cli/commands/observability-commands-queries.js +8 -1
  7. package/dist/cli/commands/observability-commands.d.ts +7 -1
  8. package/dist/cli/commands/observability-commands.js +19 -3
  9. package/dist/services/artifacts/repair-cycle-service.d.ts +23 -0
  10. package/dist/services/artifacts/repair-cycle-service.js +23 -0
  11. package/dist/services/observability/aggregation-helpers.d.ts +12 -8
  12. package/dist/services/observability/aggregation-helpers.js +12 -25
  13. package/dist/services/observability/aggregation-types.d.ts +40 -0
  14. package/dist/services/observability/aggregation.d.ts +2 -1
  15. package/dist/services/observability/aggregation.js +16 -25
  16. package/dist/services/observability/repair-cycle-metric.d.ts +67 -0
  17. package/dist/services/observability/repair-cycle-metric.js +223 -0
  18. package/dist/services/observability/report-formatter.d.ts +1 -1
  19. package/dist/services/observability/report-formatter.js +16 -4
  20. package/dist/services/observability/results-baseline-artifact.d.ts +29 -0
  21. package/dist/services/observability/results-baseline-artifact.js +80 -0
  22. package/dist/services/observability/results-baseline-rows.d.ts +33 -0
  23. package/dist/services/observability/results-baseline-rows.js +127 -0
  24. package/dist/services/observability/results-baseline.d.ts +115 -0
  25. package/dist/services/observability/results-baseline.js +101 -0
  26. 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.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.20",
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
- 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.
@@ -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), the
6
- * per-slice repair-cycle count, and the two event-source helpers the CLI
7
- * calls. Moved verbatim (wave 3, file-size cap campaign) so the aggregation
8
- * module stays under the 300 raw-line cap. The first four were module-private
9
- * before the move and are NOT re-exported from `aggregation.ts`; the two
10
- * event-source helpers were public and are re-exported there, so that
11
- * module's public surface is unchanged.
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), the
6
- * per-slice repair-cycle count, and the two event-source helpers the CLI
7
- * calls. Moved verbatim (wave 3, file-size cap campaign) so the aggregation
8
- * module stays under the 300 raw-line cap. The first four were module-private
9
- * before the move and are NOT re-exported from `aggregation.ts`; the two
10
- * event-source helpers were public and are re-exported there, so that
11
- * module's public surface is unchanged.
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 { REPAIR_CYCLE_CAP, TERMINAL_FAIL_STATES, TERMINAL_HAPPY_STATES, ZERO_FANOUT } from './aggregation-types.js';
18
- import { computeRepairCyclesBySlice, durationMsBetween, isSliceTransition, transitionTo } from './aggregation-helpers.js';
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, the
21
- // per-slice cycle count and the event-source helpers live in
22
- // `aggregation-helpers.ts` (wave-3 file-size cap split; declarations moved
23
- // verbatim). Every PUBLIC name is re-exported below so importers keep
24
- // resolving it from `aggregation.js` unchanged; the module-private readers are
25
- // imported for use here and not re-exported.
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 cyclesBySlice = computeRepairCyclesBySlice(events);
75
+ const metrics = computeSliceRepairMetrics(events);
73
76
  let repairCyclePeak = 0;
74
77
  for (const rollup of bySlice.values()) {
75
- const cycles = cyclesBySlice.get(rollup.sliceRid) ?? 0;
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 cyclesBySlice = computeRepairCyclesBySlice(events);
97
+ const metrics = computeSliceRepairMetrics(events);
95
98
  for (const rollup of bySlice.values()) {
96
- rollup.repairCycleCount = cyclesBySlice.get(rollup.sliceRid) ?? 0;
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
- const cyclesBySlice = computeRepairCyclesBySlice(events);
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();