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.
Files changed (27) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +219 -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 +8 -5
  27. package/scripts/canonical-store-report.mjs +84 -0
@@ -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();
@@ -0,0 +1,67 @@
1
+ /**
2
+ * `src/services/observability/repair-cycle-metric.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS — the measured defect that forced the metric to
5
+ * change.
6
+ *
7
+ * The repair-cycle counter that used to live in `aggregation-helpers.ts`
8
+ * counted every slice-transition event whose `detail.artifactRole === 'qa'`.
9
+ * That is not a repair-cycle count: it counts QA's OWN internal state
10
+ * transitions, and it counts every transition TWICE because
11
+ * `peaks request transition` emits one event without `detail.from` and a
12
+ * second one with it. Measured over this repo's own recorded history
13
+ * (10 session dirs, 108 slices, 1102 slice-transition events) the old
14
+ * counter put 82 of the 108 slices at or over the cap of 3, while exactly
15
+ * ONE slice ever really reworked — and it reworked FIVE times.
16
+ * The other 81 alarms were a measurement artifact, not rework.
17
+ *
18
+ * So the metric is VERSIONED. Version 1 is the qa-event count — it is kept,
19
+ * under the name `legacyQaEventCount`, so the old number and the new number
20
+ * can be read side by side instead of being compared by accident. Version 2
21
+ * is the repair-cycle count computed here.
22
+ *
23
+ * THE v2 DEFINITION. A repair cycle = the slice's artifact RETURNS to an RD
24
+ * work state (`draft` | `spec-locked` | `implemented`) after it had entered a
25
+ * QA phase (`running` | `verdict-issued`). The state vocabulary is the one
26
+ * `ALLOWED_STATES_PER_ROLE` declares in
27
+ * `src/services/artifacts/request-artifact-state-helpers.ts`: `qa-handoff`
28
+ * is an RD state, so the normal closing hops `verdict-issued → qa-handoff` and
29
+ * `qa-handoff → handed-off` are the happy path, not rework.
30
+ *
31
+ * This is NOT the same measurement as
32
+ * `src/services/artifacts/repair-cycle-service.ts`, which counts the
33
+ * `QA return-to-rd cycle N` notes inside a request artifact. That one is the
34
+ * artifact contract's own record; this one is reconstructed from the
35
+ * observability event stream. The two are reported separately and are never
36
+ * merged.
37
+ */
38
+ import { type RepairCycleReport } from './aggregation-types.js';
39
+ import type { ObservabilityEvent } from './observability-service.js';
40
+ /**
41
+ * Version 1 was never versioned — it silently counted qa-role events.
42
+ * Version 2 is the repair-cycle count. A consumer that reads
43
+ * `metricVersion` can therefore tell which convention produced the numbers
44
+ * printed next to it.
45
+ */
46
+ export declare const REPAIR_CYCLE_METRIC_VERSION = 2;
47
+ /** What the v2 number counts, in one sentence, for every consumer that prints it. */
48
+ export declare const REPAIR_CYCLE_METRIC_DEFINITION: string;
49
+ /** What the v1 number counts, and why it must never be read as a repair-cycle count. */
50
+ export declare const LEGACY_QA_EVENT_COUNT_NOTE: string;
51
+ /** The three numbers one slice carries. */
52
+ export type SliceRepairMetrics = {
53
+ /** v2: how many times the slice came back to an RD work state after a QA phase. */
54
+ repairCycles: number;
55
+ /** v2: how many QA phases the slice entered. */
56
+ qaRounds: number;
57
+ /** v1: how many qa-role slice-transition events the slice emitted. */
58
+ legacyQaEventCount: number;
59
+ };
60
+ /** The three numbers, per slice, over the whole event stream. */
61
+ export declare function computeSliceRepairMetrics(events: readonly ObservabilityEvent[]): Map<string, SliceRepairMetrics>;
62
+ /**
63
+ * The repair-cycle report. `capHitCount` is computed from the v2 metric; the
64
+ * v1 count rides along under its own name so the two conventions can be
65
+ * compared rather than confused.
66
+ */
67
+ export declare function buildRepairCycleReport(events: readonly ObservabilityEvent[]): RepairCycleReport;
@@ -0,0 +1,223 @@
1
+ /**
2
+ * `src/services/observability/repair-cycle-metric.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS — the measured defect that forced the metric to
5
+ * change.
6
+ *
7
+ * The repair-cycle counter that used to live in `aggregation-helpers.ts`
8
+ * counted every slice-transition event whose `detail.artifactRole === 'qa'`.
9
+ * That is not a repair-cycle count: it counts QA's OWN internal state
10
+ * transitions, and it counts every transition TWICE because
11
+ * `peaks request transition` emits one event without `detail.from` and a
12
+ * second one with it. Measured over this repo's own recorded history
13
+ * (10 session dirs, 108 slices, 1102 slice-transition events) the old
14
+ * counter put 82 of the 108 slices at or over the cap of 3, while exactly
15
+ * ONE slice ever really reworked — and it reworked FIVE times.
16
+ * The other 81 alarms were a measurement artifact, not rework.
17
+ *
18
+ * So the metric is VERSIONED. Version 1 is the qa-event count — it is kept,
19
+ * under the name `legacyQaEventCount`, so the old number and the new number
20
+ * can be read side by side instead of being compared by accident. Version 2
21
+ * is the repair-cycle count computed here.
22
+ *
23
+ * THE v2 DEFINITION. A repair cycle = the slice's artifact RETURNS to an RD
24
+ * work state (`draft` | `spec-locked` | `implemented`) after it had entered a
25
+ * QA phase (`running` | `verdict-issued`). The state vocabulary is the one
26
+ * `ALLOWED_STATES_PER_ROLE` declares in
27
+ * `src/services/artifacts/request-artifact-state-helpers.ts`: `qa-handoff`
28
+ * is an RD state, so the normal closing hops `verdict-issued → qa-handoff` and
29
+ * `qa-handoff → handed-off` are the happy path, not rework.
30
+ *
31
+ * This is NOT the same measurement as
32
+ * `src/services/artifacts/repair-cycle-service.ts`, which counts the
33
+ * `QA return-to-rd cycle N` notes inside a request artifact. That one is the
34
+ * artifact contract's own record; this one is reconstructed from the
35
+ * observability event stream. The two are reported separately and are never
36
+ * merged.
37
+ */
38
+ import { artifactRole, isSliceTransition, transitionTo } from './aggregation-helpers.js';
39
+ import { REPAIR_CYCLE_CAP } from './aggregation-types.js';
40
+ /**
41
+ * Version 1 was never versioned — it silently counted qa-role events.
42
+ * Version 2 is the repair-cycle count. A consumer that reads
43
+ * `metricVersion` can therefore tell which convention produced the numbers
44
+ * printed next to it.
45
+ */
46
+ export const REPAIR_CYCLE_METRIC_VERSION = 2;
47
+ /** What the v2 number counts, in one sentence, for every consumer that prints it. */
48
+ export const REPAIR_CYCLE_METRIC_DEFINITION = 'A repair cycle = the slice returns to an RD work state (draft | spec-locked | implemented) ' +
49
+ 'after it had entered a QA phase (running | verdict-issued). One rework excursion counts once.';
50
+ /** What the v1 number counts, and why it must never be read as a repair-cycle count. */
51
+ export const LEGACY_QA_EVENT_COUNT_NOTE = 'Counts slice-transition events whose detail.artifactRole === "qa" — QA\'s own internal state ' +
52
+ 'transitions, NOT repair loops. Kept so the v1 and v2 numbers can be compared side by side.';
53
+ /**
54
+ * RD work states. A return to one of these after a QA phase is rework; a
55
+ * return to `qa-handoff` / `handed-off` is a forward or terminal hop.
56
+ */
57
+ const RD_WORK_STATES = new Set(['draft', 'spec-locked', 'implemented']);
58
+ /**
59
+ * QA work states — the `qa` role's `ALLOWED_STATES_PER_ROLE` entries minus
60
+ * `draft` (the initial state) and `blocked` (a terminal failure). Entering
61
+ * one of them opens a QA phase.
62
+ */
63
+ const QA_WORK_STATES = new Set(['running', 'verdict-issued']);
64
+ function eventTs(event) {
65
+ return typeof event.ts === 'string' ? event.ts : '';
66
+ }
67
+ /**
68
+ * The de-duplicated transition sequence of every slice.
69
+ *
70
+ * `detail.from` is never read: it is present on only 55% of the recorded
71
+ * events and contradicts the event order on 395 of those, so a metric that
72
+ * trusts it reads a field that does not mean what its name says. The
73
+ * sequence is rebuilt from `detail.to` + `detail.artifactRole` only.
74
+ */
75
+ function sliceSteps(events) {
76
+ const bySlice = new Map();
77
+ for (const event of events) {
78
+ if (!isSliceTransition(event))
79
+ continue;
80
+ const bucket = bySlice.get(event.sliceRid);
81
+ if (bucket === undefined)
82
+ bySlice.set(event.sliceRid, [event]);
83
+ else
84
+ bucket.push(event);
85
+ }
86
+ const steps = new Map();
87
+ for (const [rid, bucket] of bySlice) {
88
+ const ordered = [...bucket].sort((a, b) => eventTs(a).localeCompare(eventTs(b)));
89
+ const collapsed = [];
90
+ for (const event of ordered) {
91
+ const to = transitionTo(event);
92
+ if (to === null)
93
+ continue;
94
+ const role = artifactRole(event);
95
+ const last = collapsed[collapsed.length - 1];
96
+ // The same transition is emitted twice — once without `detail.from` and
97
+ // once with it. Both carry the same `to` and the same role, so the
98
+ // second one is dropped and the pair counts once.
99
+ if (last !== undefined && last.to === to && last.role === role)
100
+ continue;
101
+ collapsed.push({ to, role });
102
+ }
103
+ steps.set(rid, collapsed);
104
+ }
105
+ return steps;
106
+ }
107
+ /**
108
+ * Score one de-duplicated sequence.
109
+ *
110
+ * `qaPhaseOpen` is the "a rework is pending" latch: it is set when the slice
111
+ * enters QA work and cleared when the slice returns to an RD work state (one
112
+ * cycle, counted once) or leaves for a forward / terminal hop. `qaExcursionOpen`
113
+ * separates "a new QA phase" from "the same phase seen twice".
114
+ */
115
+ function scoreSteps(steps) {
116
+ let repairCycles = 0;
117
+ let qaRounds = 0;
118
+ let qaPhaseOpen = false;
119
+ let qaExcursionOpen = false;
120
+ for (const step of steps) {
121
+ const isQaWork = QA_WORK_STATES.has(step.to) && step.role === 'qa';
122
+ const isRdWork = RD_WORK_STATES.has(step.to) && step.role === 'rd';
123
+ if (isQaWork) {
124
+ if (!qaExcursionOpen) {
125
+ qaRounds += 1;
126
+ qaExcursionOpen = true;
127
+ }
128
+ qaPhaseOpen = true;
129
+ continue;
130
+ }
131
+ qaExcursionOpen = false;
132
+ if (isRdWork) {
133
+ if (qaPhaseOpen) {
134
+ repairCycles += 1;
135
+ qaPhaseOpen = false;
136
+ }
137
+ continue;
138
+ }
139
+ // A forward / terminal hop (`qa-handoff`, `handed-off`, `blocked`, ...):
140
+ // the QA phase is over and no rework is pending.
141
+ qaPhaseOpen = false;
142
+ }
143
+ return { repairCycles, qaRounds };
144
+ }
145
+ /** The v1 count: every qa-role slice-transition event, duplicates included. */
146
+ function legacyQaEventCounts(events) {
147
+ const counts = new Map();
148
+ for (const event of events) {
149
+ if (!isSliceTransition(event))
150
+ continue;
151
+ if (artifactRole(event) !== 'qa')
152
+ continue;
153
+ counts.set(event.sliceRid, (counts.get(event.sliceRid) ?? 0) + 1);
154
+ }
155
+ return counts;
156
+ }
157
+ /** The three numbers, per slice, over the whole event stream. */
158
+ export function computeSliceRepairMetrics(events) {
159
+ const steps = sliceSteps(events);
160
+ const legacy = legacyQaEventCounts(events);
161
+ const metrics = new Map();
162
+ for (const [rid, slice] of steps) {
163
+ const scored = scoreSteps(slice);
164
+ metrics.set(rid, {
165
+ repairCycles: scored.repairCycles,
166
+ qaRounds: scored.qaRounds,
167
+ legacyQaEventCount: legacy.get(rid) ?? 0
168
+ });
169
+ }
170
+ return metrics;
171
+ }
172
+ /**
173
+ * The repair-cycle report. `capHitCount` is computed from the v2 metric; the
174
+ * v1 count rides along under its own name so the two conventions can be
175
+ * compared rather than confused.
176
+ */
177
+ export function buildRepairCycleReport(events) {
178
+ const metrics = computeSliceRepairMetrics(events);
179
+ const rids = Array.from(metrics.keys()).sort((a, b) => a.localeCompare(b));
180
+ const perSlice = rids.map((rid) => ({
181
+ sliceRid: rid,
182
+ cycleCount: metrics.get(rid)?.repairCycles ?? 0
183
+ }));
184
+ const legacyPerSlice = rids.map((rid) => ({
185
+ sliceRid: rid,
186
+ eventCount: metrics.get(rid)?.legacyQaEventCount ?? 0
187
+ }));
188
+ const qaRoundPerSlice = rids.map((rid) => ({
189
+ sliceRid: rid,
190
+ roundCount: metrics.get(rid)?.qaRounds ?? 0
191
+ }));
192
+ const totalCycles = perSlice.reduce((sum, row) => sum + row.cycleCount, 0);
193
+ const capHitCount = perSlice.filter((row) => row.cycleCount >= REPAIR_CYCLE_CAP).length;
194
+ const legacyTotal = legacyPerSlice.reduce((sum, row) => sum + row.eventCount, 0);
195
+ const legacyCapHitCount = legacyPerSlice.filter((row) => row.eventCount >= REPAIR_CYCLE_CAP).length;
196
+ const qaRounds = {
197
+ metric: 'qa-rounds',
198
+ total: qaRoundPerSlice.reduce((sum, row) => sum + row.roundCount, 0),
199
+ peak: qaRoundPerSlice.reduce((peak, row) => Math.max(peak, row.roundCount), 0),
200
+ perSlice: qaRoundPerSlice
201
+ };
202
+ const legacyQaEventCount = {
203
+ metric: 'qa-role-transition-event-count',
204
+ metricVersion: 1,
205
+ note: LEGACY_QA_EVENT_COUNT_NOTE,
206
+ total: legacyTotal,
207
+ peak: legacyPerSlice.reduce((peak, row) => Math.max(peak, row.eventCount), 0),
208
+ capHitCount: legacyCapHitCount,
209
+ perSlice: legacyPerSlice
210
+ };
211
+ return {
212
+ metric: 'repair-cycles',
213
+ metricVersion: REPAIR_CYCLE_METRIC_VERSION,
214
+ definition: REPAIR_CYCLE_METRIC_DEFINITION,
215
+ totalCycles,
216
+ cap: REPAIR_CYCLE_CAP,
217
+ capHit: capHitCount > 0,
218
+ capHitCount,
219
+ perSlice,
220
+ qaRounds,
221
+ legacyQaEventCount
222
+ };
223
+ }
@@ -12,7 +12,7 @@
12
12
  * - Repair-cycle table: sliceRid | cycleCount
13
13
  * - Top-N slowest slices: same as slice table, sorted by durationMs desc
14
14
  */
15
- import type { FanoutBreakdown, Period, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation.js';
15
+ import { type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation.js';
16
16
  export type ReportInput = {
17
17
  scope: 'session' | 'all-sessions';
18
18
  scopeId: string;
@@ -12,6 +12,7 @@
12
12
  * - Repair-cycle table: sliceRid | cycleCount
13
13
  * - Top-N slowest slices: same as slice table, sorted by durationMs desc
14
14
  */
15
+ import { REPAIR_CYCLE_METRIC_VERSION } from './aggregation.js';
15
16
  const SLOWEST_TOP_N = 5;
16
17
  function pad(value, width) {
17
18
  const str = String(value);
@@ -47,7 +48,7 @@ function markdownStatusSummary(status) {
47
48
  lines.push(`| total slices | ${status.totalSlices} |`);
48
49
  lines.push(`| success count | ${status.successCount} |`);
49
50
  lines.push(`| fail count | ${status.failCount} |`);
50
- lines.push(`| repair-cycle peak | ${status.repairCyclePeak} |`);
51
+ lines.push(`| repair-cycle peak (v${REPAIR_CYCLE_METRIC_VERSION} metric) | ${status.repairCyclePeak} |`);
51
52
  lines.push(`| fanout cost total | ${status.fanoutCostTotal} |`);
52
53
  lines.push('');
53
54
  return lines.join('\n');
@@ -93,20 +94,31 @@ function markdownRepairCycleTable(repairCycles) {
93
94
  const lines = [];
94
95
  lines.push('## Repair cycles');
95
96
  lines.push('');
97
+ // The version marker and the definition travel with the numbers: a reader
98
+ // must not be able to see a v2 cap-hit count next to a v1 count without the
99
+ // report saying that the two are different measurements.
100
+ lines.push(`- **metric**: \`${repairCycles.metric}\` (version ${repairCycles.metricVersion})`);
101
+ lines.push(`- **definition**: ${repairCycles.definition}`);
102
+ lines.push('');
96
103
  if (repairCycles.perSlice.length === 0) {
97
- lines.push('_No repair cycles recorded for this period._');
104
+ lines.push('_No slice transitions recorded for this period._');
98
105
  lines.push('');
99
106
  return lines.join('\n');
100
107
  }
101
- lines.push('| slice rid | cycle count |');
108
+ lines.push('| slice rid | repair cycles |');
102
109
  lines.push('|---|---|');
103
110
  for (const row of repairCycles.perSlice) {
104
111
  lines.push(`| ${row.sliceRid} | ${row.cycleCount} |`);
105
112
  }
106
113
  lines.push('');
114
+ lines.push(`- **total repair cycles (v${repairCycles.metricVersion})**: ${repairCycles.totalCycles}`);
107
115
  lines.push(`- **cap**: ${repairCycles.cap}`);
108
116
  lines.push(`- **cap hit**: ${repairCycles.capHit ? 'yes' : 'no'}`);
109
- lines.push(`- **slices at cap**: ${repairCycles.capHitCount}`);
117
+ lines.push(`- **slices at cap (v${repairCycles.metricVersion})**: ${repairCycles.capHitCount}`);
118
+ lines.push(`- **QA rounds (a separate metric — a QA phase, NOT a repair cycle)**: total ${repairCycles.qaRounds.total}, peak ${repairCycles.qaRounds.peak}`);
119
+ const legacy = repairCycles.legacyQaEventCount;
120
+ lines.push(`- **legacy v${legacy.metricVersion} \`${legacy.metric}\` (NOT a repair-cycle count)**: total ${legacy.total}, peak ${legacy.peak}, slices at cap ${legacy.capHitCount}`);
121
+ lines.push(`- **legacy note**: ${legacy.note}`);
110
122
  lines.push('');
111
123
  return lines.join('\n');
112
124
  }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * `src/services/observability/results-baseline-artifact.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS — the tracked artifact and the comparison against it
5
+ * are separated from the computation, so the question "what does the baseline
6
+ * say?" and the question "what does the machine measure right now?" can be
7
+ * answered by different modules.
8
+ *
9
+ * The tracked artifact lives at `.peaks/observability/results-baseline.json`.
10
+ * It is NOT CI-enforceable: its source data is gitignored session state
11
+ * (`.peaks/_runtime/<sessionId>/metrics/slices.jsonl`), so a CI runner has
12
+ * nothing to compare against. This module never wires the artifact into a
13
+ * gate; it only reads it, writes it, and reports drift against it.
14
+ */
15
+ import { type BaselineDrift, type BaselineRowKind, type BaselineTolerance, type ResultsBaseline } from './results-baseline.js';
16
+ /** Absolute path of the tracked artifact for a project root. */
17
+ export declare function resultsBaselinePath(projectRoot: string): string;
18
+ /** The tracked artifact, or null when this project has none yet. */
19
+ export declare function readTrackedResultsBaseline(projectRoot: string): ResultsBaseline | null;
20
+ /** Regenerate the tracked artifact and return the path it was written to. */
21
+ export declare function writeResultsBaseline(projectRoot: string, baseline: ResultsBaseline): string;
22
+ /** The tolerance that applies to a row kind, read from the tracked artifact. */
23
+ export declare function toleranceFor(tolerance: BaselineTolerance, kind: BaselineRowKind): number;
24
+ /**
25
+ * Compare a freshly computed baseline with the tracked one. A missing row or
26
+ * a metric-version mismatch is drift; so is a value that moved further than
27
+ * the tolerance its kind allows.
28
+ */
29
+ export declare function compareResultsBaseline(computed: ResultsBaseline, tracked: ResultsBaseline): BaselineDrift[];
@@ -0,0 +1,80 @@
1
+ /**
2
+ * `src/services/observability/results-baseline-artifact.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS — the tracked artifact and the comparison against it
5
+ * are separated from the computation, so the question "what does the baseline
6
+ * say?" and the question "what does the machine measure right now?" can be
7
+ * answered by different modules.
8
+ *
9
+ * The tracked artifact lives at `.peaks/observability/results-baseline.json`.
10
+ * It is NOT CI-enforceable: its source data is gitignored session state
11
+ * (`.peaks/_runtime/<sessionId>/metrics/slices.jsonl`), so a CI runner has
12
+ * nothing to compare against. This module never wires the artifact into a
13
+ * gate; it only reads it, writes it, and reports drift against it.
14
+ */
15
+ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
16
+ import { dirname, join } from 'node:path';
17
+ /** Absolute path of the tracked artifact for a project root. */
18
+ export function resultsBaselinePath(projectRoot) {
19
+ return join(projectRoot, '.peaks', 'observability', 'results-baseline.json');
20
+ }
21
+ /** The tracked artifact, or null when this project has none yet. */
22
+ export function readTrackedResultsBaseline(projectRoot) {
23
+ const path = resultsBaselinePath(projectRoot);
24
+ if (!existsSync(path))
25
+ return null;
26
+ return JSON.parse(readFileSync(path, 'utf8'));
27
+ }
28
+ /** Regenerate the tracked artifact and return the path it was written to. */
29
+ export function writeResultsBaseline(projectRoot, baseline) {
30
+ const path = resultsBaselinePath(projectRoot);
31
+ mkdirSync(dirname(path), { recursive: true });
32
+ writeFileSync(path, `${JSON.stringify(baseline, null, 2)}\n`, 'utf8');
33
+ return path;
34
+ }
35
+ /** The tolerance that applies to a row kind, read from the tracked artifact. */
36
+ export function toleranceFor(tolerance, kind) {
37
+ return tolerance[kind];
38
+ }
39
+ /**
40
+ * Compare a freshly computed baseline with the tracked one. A missing row or
41
+ * a metric-version mismatch is drift; so is a value that moved further than
42
+ * the tolerance its kind allows.
43
+ */
44
+ export function compareResultsBaseline(computed, tracked) {
45
+ const drifts = [];
46
+ if (computed.metricVersion !== tracked.metricVersion) {
47
+ drifts.push({
48
+ rowId: 'metric-version',
49
+ kind: 'metric-version-mismatch',
50
+ tracked: tracked.metricVersion,
51
+ computed: computed.metricVersion,
52
+ tolerance: null
53
+ });
54
+ }
55
+ const trackedRows = new Map(tracked.baselineRows.map((row) => [row.id, row]));
56
+ for (const row of computed.baselineRows) {
57
+ const prior = trackedRows.get(row.id);
58
+ if (prior === undefined) {
59
+ drifts.push({
60
+ rowId: row.id,
61
+ kind: 'row-missing',
62
+ tracked: null,
63
+ computed: row.value,
64
+ tolerance: null
65
+ });
66
+ continue;
67
+ }
68
+ const tolerance = toleranceFor(tracked.tolerance, row.kind);
69
+ if (Math.abs(row.value - prior.value) > tolerance) {
70
+ drifts.push({
71
+ rowId: row.id,
72
+ kind: 'value-drift',
73
+ tracked: prior.value,
74
+ computed: row.value,
75
+ tolerance
76
+ });
77
+ }
78
+ }
79
+ return drifts;
80
+ }
@@ -0,0 +1,33 @@
1
+ /**
2
+ * `src/services/observability/results-baseline-rows.ts`
3
+ *
4
+ * WHY THIS MODULE EXISTS. The published rows and the old-vs-new metric
5
+ * comparison are the two parts of the results baseline that decide what a
6
+ * reader is shown, and both are big enough to push the computation module
7
+ * over the repository's 300 raw-line file-size cap.
8
+ *
9
+ * THE RULE THE ROWS OBEY. Every published row is a RATE or a PEAK. A raw
10
+ * count that grows with the number of slices ever recorded is a population
11
+ * descriptor, not a baseline row — those live in their own block of the
12
+ * artifact, and a reader must never mistake one for the other.
13
+ *
14
+ * THE RULE THE COMPARISON OBEY. Version 1 of the repair-cycle metric counted
15
+ * qa-role slice-transition events — QA's own internal state transitions,
16
+ * doubled by the duplicate emission — and was never a repair-cycle count.
17
+ * Version 2 counts repair cycles. The two are recorded side by side so the
18
+ * historical numbers are read as a DIFFERENT MEASUREMENT, not as a
19
+ * regression.
20
+ */
21
+ import type { RepairCycleReport, StatusAggregate } from './aggregation-types.js';
22
+ import type { BaselineRow, ResultsBaseline } from './results-baseline.js';
23
+ /**
24
+ * The published rows. Every one of them is a RATE or a PEAK: a raw count that
25
+ * grows with the number of slices ever recorded is a population descriptor,
26
+ * not a baseline row.
27
+ */
28
+ export declare function baselineRows(status: StatusAggregate, cycles: RepairCycleReport, slices: number): BaselineRow[];
29
+ /**
30
+ * The old-vs-new comparison, recorded so a reader sees that the historical
31
+ * numbers were a DIFFERENT MEASUREMENT and not a regression.
32
+ */
33
+ export declare function metricComparison(cycles: RepairCycleReport, slices: number): ResultsBaseline['metricComparison'];