peaks-loop 4.1.20 → 4.1.22

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/.claude-plugin/marketplace.json +3 -6
  2. package/CHANGELOG.md +198 -0
  3. package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
  4. package/dist/cli/commands/mut-commands-helpers.js +44 -26
  5. package/dist/cli/commands/observability-commands-baseline.d.ts +26 -0
  6. package/dist/cli/commands/observability-commands-baseline.js +74 -0
  7. package/dist/cli/commands/observability-commands-queries.d.ts +5 -0
  8. package/dist/cli/commands/observability-commands-queries.js +8 -1
  9. package/dist/cli/commands/observability-commands.d.ts +7 -1
  10. package/dist/cli/commands/observability-commands.js +19 -3
  11. package/dist/services/artifacts/repair-cycle-service.d.ts +23 -0
  12. package/dist/services/artifacts/repair-cycle-service.js +23 -0
  13. package/dist/services/distribution/json-layout.d.ts +20 -0
  14. package/dist/services/distribution/json-layout.js +195 -0
  15. package/dist/services/distribution/plugin-manifest.d.ts +31 -2
  16. package/dist/services/distribution/plugin-manifest.js +40 -4
  17. package/dist/services/observability/aggregation-helpers.d.ts +12 -8
  18. package/dist/services/observability/aggregation-helpers.js +12 -25
  19. package/dist/services/observability/aggregation-types.d.ts +40 -0
  20. package/dist/services/observability/aggregation.d.ts +2 -1
  21. package/dist/services/observability/aggregation.js +16 -25
  22. package/dist/services/observability/repair-cycle-metric.d.ts +67 -0
  23. package/dist/services/observability/repair-cycle-metric.js +223 -0
  24. package/dist/services/observability/report-formatter.d.ts +1 -1
  25. package/dist/services/observability/report-formatter.js +16 -4
  26. package/dist/services/observability/results-baseline-artifact.d.ts +29 -0
  27. package/dist/services/observability/results-baseline-artifact.js +80 -0
  28. package/dist/services/observability/results-baseline-rows.d.ts +33 -0
  29. package/dist/services/observability/results-baseline-rows.js +127 -0
  30. package/dist/services/observability/results-baseline.d.ts +115 -0
  31. package/dist/services/observability/results-baseline.js +101 -0
  32. package/package.json +7 -5
@@ -0,0 +1,20 @@
1
+ /** The two knobs of prettier's JSON layout a render can depend on. */
2
+ export interface JsonLayoutOptions {
3
+ /** prettier's `printWidth` — the column budget one printed line may use. */
4
+ readonly printWidth: number;
5
+ /** prettier's `tabWidth` — how many spaces one indentation level is. */
6
+ readonly tabWidth: number;
7
+ }
8
+ /**
9
+ * prettier's own defaults, used when the repository's config says nothing about a
10
+ * knob. They are prettier's, not this repository's: the config file is the one
11
+ * source of truth for the numbers, and a second copy of them here would be a
12
+ * second decision.
13
+ */
14
+ export declare const DEFAULT_JSON_LAYOUT: JsonLayoutOptions;
15
+ /**
16
+ * Render a JSON value in the layout prettier produces for JSON, newline-terminated.
17
+ *
18
+ * The output is a prettier FIXED POINT: formatting it again returns it unchanged.
19
+ */
20
+ export declare function renderJsonDocument(value: unknown, options?: JsonLayoutOptions): string;
@@ -0,0 +1,195 @@
1
+ // src/services/distribution/json-layout.ts
2
+ //
3
+ // WHY THIS FILE EXISTS. `.claude-plugin/marketplace.json` is a GENERATED artifact
4
+ // and it SHIPS (the root `package.json#files` allowlist names `.claude-plugin/**`),
5
+ // so its bytes are a published surface. The renderer used to emit it with
6
+ // `JSON.stringify(manifest, null, 2)`, which expands EVERY array regardless of
7
+ // width — so the artifact was not prettier-clean, and `npm run format:check` could
8
+ // not see it: that script covers `src|tests|packages|scripts` × `ts,mts,mjs,js` and
9
+ // no `.json` at all. Nothing asserted the property until a guard did.
10
+ //
11
+ // THE RULE IS PRETTIER'S, AND IT IS REPLICATED HERE WITHOUT PRETTIER. `prettier`
12
+ // is a devDependency. The root `package.json#files` allowlist also names
13
+ // `dist/**/*.js`, so `dist/services/distribution/plugin-manifest.js` — and this
14
+ // module beside it — SHIP to consumers. A static `import 'prettier'` from any
15
+ // module under `src/**` would put an undeclared dependency into every consumer
16
+ // install and fail with `ERR_MODULE_NOT_FOUND` — the same defect class as the
17
+ // 4.1.18→4.1.20 packaging break. A lazy `await import('prettier')` would not fail
18
+ // at import time, but it would still make the SHIPPED renderer's output depend on a
19
+ // package the published manifest does not declare. So the shape is computed here,
20
+ // with ZERO dependencies, and the shape does not drift when prettier is upgraded.
21
+ //
22
+ // THE TWO RULES, AS PRETTIER APPLIES THEM TO JSON.
23
+ //
24
+ // 1. OBJECTS. prettier keeps an object expanded when the source has a newline
25
+ // between `{` and its first key, and collapses it otherwise. This renderer
26
+ // always emits the newline, so every object is expanded — and prettier, reading
27
+ // that newline, keeps it expanded. The render is therefore a FIXED POINT of
28
+ // prettier, which is the property the guard asserts.
29
+ //
30
+ // 2. ARRAYS. prettier prints an array on ONE line when it fits the print width,
31
+ // and breaks it one element per line when it does not. On top of that it has
32
+ // one forced-break rule: an array with more than one element where EVERY
33
+ // element is an object or an array, all of the same kind, and each holding
34
+ // more than one member, breaks even when it would fit.
35
+ //
36
+ // The width is measured the way prettier measures it: the printed line, from its
37
+ // indentation through the value and the separator that follows it, must fit inside
38
+ // `printWidth`. A value therefore knows the column it starts at, the text already
39
+ // on its line, and the text that follows it before the next break.
40
+ //
41
+ // MEASURED, NOT ASSUMED. This rule was differential-tested against the installed
42
+ // prettier over 3000 generated manifests: the render equalled
43
+ // `prettier.format(JSON.stringify(value, null, 2))` in 3000 of 3000 cases, and
44
+ // `prettier.format(render(value)) === render(value)` in 3000 of 3000. The guard
45
+ // that keeps the property is
46
+ // `tests/unit/services/distribution/plugin-manifest-prettier-clean.test.ts`.
47
+ /**
48
+ * prettier's own defaults, used when the repository's config says nothing about a
49
+ * knob. They are prettier's, not this repository's: the config file is the one
50
+ * source of truth for the numbers, and a second copy of them here would be a
51
+ * second decision.
52
+ */
53
+ export const DEFAULT_JSON_LAYOUT = { printWidth: 80, tabWidth: 2 };
54
+ function isPrimitive(value) {
55
+ return value === null || typeof value !== 'object';
56
+ }
57
+ function isJsonArray(value) {
58
+ return Array.isArray(value);
59
+ }
60
+ function isJsonObject(value) {
61
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
62
+ }
63
+ /** One JSON literal. `undefined` is not a JSON value, so it reads as `null`. */
64
+ function literal(value) {
65
+ return JSON.stringify(value) ?? 'null';
66
+ }
67
+ /**
68
+ * prettier's forced-break rule for arrays. An array breaks even when it would fit
69
+ * when it holds more than one element, every element is an object or an array, all
70
+ * of them are the same kind, and each one holds more than one member.
71
+ */
72
+ function forcesBreak(elements) {
73
+ if (elements.length <= 1)
74
+ return false;
75
+ return elements.every((element, index, all) => {
76
+ const next = all[index + 1];
77
+ if (isJsonArray(element)) {
78
+ if (next !== undefined && !isJsonArray(next))
79
+ return false;
80
+ return element.length > 1;
81
+ }
82
+ if (isJsonObject(element)) {
83
+ if (next !== undefined && !isJsonObject(next))
84
+ return false;
85
+ return Object.keys(element).length > 1;
86
+ }
87
+ return false;
88
+ });
89
+ }
90
+ /**
91
+ * A non-empty object anywhere below this value forces every enclosing array to
92
+ * break: this renderer always expands an object, and an expanded member breaks the
93
+ * group that holds it.
94
+ */
95
+ function containsObject(value) {
96
+ if (isPrimitive(value))
97
+ return false;
98
+ if (isJsonArray(value))
99
+ return value.some(containsObject);
100
+ if (isJsonObject(value))
101
+ return Object.keys(value).length > 0;
102
+ return false;
103
+ }
104
+ /** A forced-break array anywhere below this value breaks every enclosing array. */
105
+ function containsForcedBreak(value) {
106
+ if (isPrimitive(value))
107
+ return false;
108
+ if (isJsonArray(value))
109
+ return forcesBreak(value) || value.some(containsForcedBreak);
110
+ return false;
111
+ }
112
+ /** The one-line rendering of a value — the width an enclosing array measures. */
113
+ function flatText(value) {
114
+ if (isPrimitive(value))
115
+ return literal(value);
116
+ if (isJsonArray(value))
117
+ return `[${value.map(flatText).join(', ')}]`;
118
+ if (!isJsonObject(value))
119
+ return 'null';
120
+ const keys = Object.keys(value);
121
+ if (keys.length === 0)
122
+ return '{}';
123
+ const members = keys.map((key) => `${JSON.stringify(key)}: ${flatText(value[key])}`);
124
+ return `{ ${members.join(', ')} }`;
125
+ }
126
+ function renderValue(value, context) {
127
+ if (isPrimitive(value))
128
+ return literal(value);
129
+ if (isJsonArray(value))
130
+ return renderArray(value, context);
131
+ if (isJsonObject(value))
132
+ return renderObject(value, context);
133
+ return literal(value);
134
+ }
135
+ /** One array, either on one line or one element per line. */
136
+ function renderArray(elements, context) {
137
+ if (elements.length === 0)
138
+ return '[]';
139
+ const flat = `[${elements.map(flatText).join(', ')}]`;
140
+ const fits = context.indent + context.prefixWidth + flat.length + context.suffixWidth <=
141
+ context.options.printWidth;
142
+ const breakable = forcesBreak(elements) || containsObject(elements) || containsForcedBreak(elements);
143
+ if (fits && !breakable)
144
+ return flat;
145
+ const inner = context.indent + context.options.tabWidth;
146
+ const pad = ' '.repeat(inner);
147
+ const body = elements
148
+ .map((element, index) => {
149
+ const child = {
150
+ options: context.options,
151
+ indent: inner,
152
+ prefixWidth: 0,
153
+ suffixWidth: index === elements.length - 1 ? 0 : 1
154
+ };
155
+ return pad + renderValue(element, child);
156
+ })
157
+ .join(',\n');
158
+ return `[\n${body}\n${' '.repeat(context.indent)}]`;
159
+ }
160
+ /** One object, always expanded — the newline after `{` is what keeps it so. */
161
+ function renderObject(value, context) {
162
+ const keys = Object.keys(value);
163
+ if (keys.length === 0)
164
+ return '{}';
165
+ const inner = context.indent + context.options.tabWidth;
166
+ const pad = ' '.repeat(inner);
167
+ const body = keys
168
+ .map((key, index) => {
169
+ const keyText = JSON.stringify(key);
170
+ const child = {
171
+ options: context.options,
172
+ indent: inner,
173
+ // the `": "` that follows the key
174
+ prefixWidth: keyText.length + 2,
175
+ suffixWidth: index === keys.length - 1 ? 0 : 1
176
+ };
177
+ return `${pad}${keyText}: ${renderValue(value[key], child)}`;
178
+ })
179
+ .join(',\n');
180
+ return `{\n${body}\n${' '.repeat(context.indent)}}`;
181
+ }
182
+ /**
183
+ * Render a JSON value in the layout prettier produces for JSON, newline-terminated.
184
+ *
185
+ * The output is a prettier FIXED POINT: formatting it again returns it unchanged.
186
+ */
187
+ export function renderJsonDocument(value, options = DEFAULT_JSON_LAYOUT) {
188
+ const text = renderValue(value, {
189
+ options,
190
+ indent: 0,
191
+ prefixWidth: 0,
192
+ suffixWidth: 0
193
+ });
194
+ return `${text}\n`;
195
+ }
@@ -1,4 +1,5 @@
1
1
  import { type SkillMetadata } from '../skills/skill-registry.js';
2
+ import { type JsonLayoutOptions } from './json-layout.js';
2
3
  /** Where the generator writes, relative to the package root. */
3
4
  export declare const PLUGIN_MANIFEST_RELATIVE_PATH = ".claude-plugin/marketplace.json";
4
5
  /**
@@ -20,6 +21,16 @@ interface PackageManifest {
20
21
  } | string;
21
22
  readonly license?: string;
22
23
  readonly keywords?: readonly string[];
24
+ /**
25
+ * The repository's own prettier config — the source of truth for the layout the
26
+ * artifact is rendered in. Read from the SAME package.json the plugin-level
27
+ * fields come from, so the render and the check that guards it cannot disagree
28
+ * about the width.
29
+ */
30
+ readonly prettier?: {
31
+ readonly printWidth?: number;
32
+ readonly tabWidth?: number;
33
+ };
23
34
  }
24
35
  /** One plugin entry's skill list item — the shape `peaks skill:visibility` reads. */
25
36
  interface PluginSkillEntry {
@@ -78,8 +89,26 @@ export declare function skillEntriesOf(skills: readonly SkillMetadata[]): readon
78
89
  * caller that must fail loudly on an unreadable SKILL.md can do so once.
79
90
  */
80
91
  export declare function generatePluginManifest(manifest: PackageManifest, skills: readonly SkillMetadata[]): GeneratedPluginManifest;
81
- /** Pretty JSON, newline-terminated — the same serialization contract as the whitelist. */
82
- export declare function serializePluginManifest(manifest: GeneratedPluginManifest): string;
92
+ /**
93
+ * The layout the repository's own prettier config asks for, read from the ROOT
94
+ * package.json. Exported so the guard that checks the artifact resolves the layout
95
+ * the same way the renderer does — two resolutions would be two decisions.
96
+ */
97
+ export declare function repositoryJsonLayout(): JsonLayoutOptions;
98
+ /**
99
+ * The artifact's bytes, newline-terminated — the same serialization contract as the
100
+ * whitelist, in the layout prettier produces for JSON.
101
+ *
102
+ * `JSON.stringify(manifest, null, 2)` used to do this, and it expanded EVERY array
103
+ * regardless of width, so the committed artifact was not prettier-clean. The shape
104
+ * is now computed by `json-layout.ts`, which implements prettier's JSON rules with
105
+ * ZERO dependencies — `prettier` is a devDependency, and this module ships to
106
+ * consumers inside `dist/**`, so it must not depend on it.
107
+ *
108
+ * The default layout is the repository's own, read from the root `package.json`;
109
+ * a caller rendering for another root passes the layout it resolved there.
110
+ */
111
+ export declare function serializePluginManifest(manifest: GeneratedPluginManifest, options?: JsonLayoutOptions): string;
83
112
  /** Absolute path of the committed artifact for a package root. */
84
113
  export declare function pluginManifestPath(root?: string): string;
85
114
  /**
@@ -28,6 +28,7 @@ import { readFileSync } from 'node:fs';
28
28
  import { dirname, join, relative } from 'node:path';
29
29
  import { repoRoot } from 'peaks-loop-shared/paths';
30
30
  import { loadSkillRegistry } from '../skills/skill-registry.js';
31
+ import { DEFAULT_JSON_LAYOUT, renderJsonDocument } from './json-layout.js';
31
32
  /** Where the generator writes, relative to the package root. */
32
33
  export const PLUGIN_MANIFEST_RELATIVE_PATH = '.claude-plugin/marketplace.json';
33
34
  /**
@@ -97,9 +98,43 @@ export function generatePluginManifest(manifest, skills) {
97
98
  ]
98
99
  };
99
100
  }
100
- /** Pretty JSON, newline-terminated — the same serialization contract as the whitelist. */
101
- export function serializePluginManifest(manifest) {
102
- return `${JSON.stringify(manifest, null, 2)}\n`;
101
+ /**
102
+ * The layout the repository's own prettier config asks for.
103
+ *
104
+ * The config file is the ONE source of truth for `printWidth`; a second copy of the
105
+ * number here would be a second decision, and the artifact would drift from the
106
+ * tool that checks it the first time either moved. Absent config falls back to
107
+ * prettier's own defaults.
108
+ */
109
+ function jsonLayoutOf(manifest) {
110
+ return {
111
+ printWidth: manifest.prettier?.printWidth ?? DEFAULT_JSON_LAYOUT.printWidth,
112
+ tabWidth: manifest.prettier?.tabWidth ?? DEFAULT_JSON_LAYOUT.tabWidth
113
+ };
114
+ }
115
+ /**
116
+ * The layout the repository's own prettier config asks for, read from the ROOT
117
+ * package.json. Exported so the guard that checks the artifact resolves the layout
118
+ * the same way the renderer does — two resolutions would be two decisions.
119
+ */
120
+ export function repositoryJsonLayout() {
121
+ return jsonLayoutOf(loadPackageManifest());
122
+ }
123
+ /**
124
+ * The artifact's bytes, newline-terminated — the same serialization contract as the
125
+ * whitelist, in the layout prettier produces for JSON.
126
+ *
127
+ * `JSON.stringify(manifest, null, 2)` used to do this, and it expanded EVERY array
128
+ * regardless of width, so the committed artifact was not prettier-clean. The shape
129
+ * is now computed by `json-layout.ts`, which implements prettier's JSON rules with
130
+ * ZERO dependencies — `prettier` is a devDependency, and this module ships to
131
+ * consumers inside `dist/**`, so it must not depend on it.
132
+ *
133
+ * The default layout is the repository's own, read from the root `package.json`;
134
+ * a caller rendering for another root passes the layout it resolved there.
135
+ */
136
+ export function serializePluginManifest(manifest, options = repositoryJsonLayout()) {
137
+ return renderJsonDocument(manifest, options);
103
138
  }
104
139
  /** Absolute path of the committed artifact for a package root. */
105
140
  export function pluginManifestPath(root = repoRoot) {
@@ -122,5 +157,6 @@ export async function renderPluginManifest(root = repoRoot) {
122
157
  const named = skills.failures.map((failure) => failure.skillPath).join(', ');
123
158
  throw new Error(`Refusing to render the plugin manifest: unreadable skill(s): ${named}`);
124
159
  }
125
- return serializePluginManifest(generatePluginManifest(loadPackageManifest(root), skills.skills));
160
+ const pkg = loadPackageManifest(root);
161
+ return serializePluginManifest(generatePluginManifest(pkg, skills.skills), jsonLayoutOf(pkg));
126
162
  }
@@ -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();
@@ -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;