peaks-loop 4.1.21 → 4.1.23

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 (78) hide show
  1. package/.claude-plugin/marketplace.json +3 -6
  2. package/CHANGELOG.md +191 -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-hotspots.d.ts +54 -0
  6. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  7. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  8. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  9. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  10. package/dist/cli/commands/observability-commands-queries.js +88 -47
  11. package/dist/cli/commands/observability-commands.js +79 -20
  12. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  13. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  14. package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
  15. package/dist/services/artifacts/prerequisite-path-census.js +79 -0
  16. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  17. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  18. package/dist/services/artifacts/rd-gate-event.js +211 -0
  19. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  20. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  21. package/dist/services/distribution/json-layout.d.ts +20 -0
  22. package/dist/services/distribution/json-layout.js +195 -0
  23. package/dist/services/distribution/plugin-manifest.d.ts +31 -2
  24. package/dist/services/distribution/plugin-manifest.js +40 -4
  25. package/dist/services/observability/aggregation-types.d.ts +21 -0
  26. package/dist/services/observability/aggregation.d.ts +12 -2
  27. package/dist/services/observability/aggregation.js +26 -2
  28. package/dist/services/observability/compliance-judge.d.ts +77 -0
  29. package/dist/services/observability/compliance-judge.js +143 -0
  30. package/dist/services/observability/compliance-spec.d.ts +96 -0
  31. package/dist/services/observability/compliance-spec.js +29 -0
  32. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  33. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  34. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  35. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  36. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  37. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  38. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  39. package/dist/services/observability/hotspot-rows.js +89 -0
  40. package/dist/services/observability/hotspot-shared.d.ts +212 -0
  41. package/dist/services/observability/hotspot-shared.js +122 -0
  42. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  43. package/dist/services/observability/hotspot-sources.js +142 -0
  44. package/dist/services/observability/hotspots.d.ts +47 -0
  45. package/dist/services/observability/hotspots.js +47 -0
  46. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  47. package/dist/services/observability/near-miss-attempts.js +223 -0
  48. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  49. package/dist/services/observability/near-miss-coverage.js +108 -0
  50. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  51. package/dist/services/observability/near-miss-denominator.js +75 -0
  52. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  53. package/dist/services/observability/near-miss-difference.js +132 -0
  54. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  55. package/dist/services/observability/near-miss-facts.js +101 -0
  56. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  57. package/dist/services/observability/near-miss-gate-events.js +106 -0
  58. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  59. package/dist/services/observability/near-miss-gates.js +135 -0
  60. package/dist/services/observability/near-miss-records.d.ts +93 -0
  61. package/dist/services/observability/near-miss-records.js +87 -0
  62. package/dist/services/observability/near-miss.d.ts +148 -0
  63. package/dist/services/observability/near-miss.js +196 -0
  64. package/dist/services/observability/observability-schema.d.ts +17 -2
  65. package/dist/services/observability/observability-schema.js +21 -1
  66. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  67. package/dist/services/observability/owner-skill-map.js +144 -0
  68. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  69. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  70. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  71. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  72. package/dist/services/observability/report-formatter.d.ts +49 -3
  73. package/dist/services/observability/report-formatter.js +55 -14
  74. package/dist/services/observability/retro-attribution.d.ts +129 -0
  75. package/dist/services/observability/retro-attribution.js +134 -0
  76. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  77. package/dist/services/observability/session-metric-rows.js +184 -0
  78. package/package.json +5 -5
@@ -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
  }
@@ -16,6 +16,16 @@ export type StatusAggregate = {
16
16
  totalSlices: number;
17
17
  successCount: number;
18
18
  failCount: number;
19
+ /**
20
+ * Slices that reached a state which is neither a success terminal state nor
21
+ * a terminal failure — the ones stuck mid-flight, e.g. at `qa-handoff`.
22
+ *
23
+ * The three outcome counts partition the slice set, so
24
+ * `successCount + failCount + stalledCount === totalSlices` holds for every
25
+ * event set. A slice whose transitions recorded no final state at all also
26
+ * lands here: it reached no terminal outcome either.
27
+ */
28
+ readonly stalledCount: number;
19
29
  repairCyclePeak: number;
20
30
  fanoutCostTotal: number;
21
31
  };
@@ -30,6 +40,17 @@ export type SliceRollup = {
30
40
  repairCycleCount: number;
31
41
  success: boolean;
32
42
  };
43
+ /**
44
+ * How one slice ended.
45
+ *
46
+ * The three outcomes PARTITION the slice set: a slice that reached a
47
+ * terminal success state, a slice that reached a terminal failure state, and
48
+ * a slice that reached NEITHER — it advanced partway and stopped (at
49
+ * `qa-handoff`, typically). `stalled` is not a failure: the work was never
50
+ * concluded, and the counts must say so rather than drop the slice from the
51
+ * accounting.
52
+ */
53
+ export type SliceOutcome = 'success' | 'failed' | 'stalled';
33
54
  export type FanoutBreakdown = {
34
55
  total: number;
35
56
  perRole: Record<ObservabilitySubagentRole, number>;
@@ -14,11 +14,21 @@
14
14
  * builds the read-side surface so Slice C is purely additive.
15
15
  */
16
16
  import { type ObservabilityEvent } from './observability-service.js';
17
- import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
17
+ import { type DashboardMetrics, type FanoutBreakdown, type Period, type RepairCycleReport, type SliceOutcome, type SliceRollup, type StatusAggregate } from './aggregation-types.js';
18
18
  export { REPAIR_CYCLE_CAP } from './aggregation-types.js';
19
19
  export { REPAIR_CYCLE_METRIC_VERSION } from './repair-cycle-metric.js';
20
20
  export { readAllSessionEvents, readSessionEvents } from './aggregation-helpers.js';
21
- export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceRollup, StatusAggregate } from './aggregation-types.js';
21
+ export type { DashboardMetrics, FanoutBreakdown, LegacyQaEventCount, Period, QaRoundSummary, RepairCycleReport, SliceOutcome, SliceRollup, StatusAggregate } from './aggregation-types.js';
22
+ /**
23
+ * How one slice ended, from its rollup.
24
+ *
25
+ * ONE spelling of the three outcomes, shared by the status counts and by the
26
+ * report's slice table: a slice that reached a terminal success state, a slice
27
+ * that reached a terminal failure state, and a slice that reached NEITHER — it
28
+ * advanced partway and stopped (at `qa-handoff`, typically). The last is not a
29
+ * failure, so it is not counted as one and is not drawn as one.
30
+ */
31
+ export declare function sliceOutcome(rollup: SliceRollup): SliceOutcome;
22
32
  export declare function aggregateStatus(events: readonly ObservabilityEvent[]): StatusAggregate;
23
33
  export declare function aggregateSlices(events: readonly ObservabilityEvent[]): SliceRollup[];
24
34
  export declare function aggregateFanout(events: readonly ObservabilityEvent[]): FanoutBreakdown;
@@ -70,6 +70,22 @@ function rollupSlices(events) {
70
70
  return bySlice;
71
71
  }
72
72
  // ----- public aggregations -----
73
+ /**
74
+ * How one slice ended, from its rollup.
75
+ *
76
+ * ONE spelling of the three outcomes, shared by the status counts and by the
77
+ * report's slice table: a slice that reached a terminal success state, a slice
78
+ * that reached a terminal failure state, and a slice that reached NEITHER — it
79
+ * advanced partway and stopped (at `qa-handoff`, typically). The last is not a
80
+ * failure, so it is not counted as one and is not drawn as one.
81
+ */
82
+ export function sliceOutcome(rollup) {
83
+ if (rollup.success)
84
+ return 'success';
85
+ if (rollup.finalState !== null && TERMINAL_FAIL_STATES.has(rollup.finalState))
86
+ return 'failed';
87
+ return 'stalled';
88
+ }
73
89
  export function aggregateStatus(events) {
74
90
  const bySlice = rollupSlices(events);
75
91
  const metrics = computeSliceRepairMetrics(events);
@@ -80,14 +96,22 @@ export function aggregateStatus(events) {
80
96
  if (cycles > repairCyclePeak)
81
97
  repairCyclePeak = cycles;
82
98
  }
83
- const successCount = Array.from(bySlice.values()).filter((r) => r.success).length;
84
- const failCount = Array.from(bySlice.values()).filter((r) => r.finalState !== null && TERMINAL_FAIL_STATES.has(r.finalState)).length;
99
+ // The three outcome buckets come from the ONE outcome spelling above, so
100
+ // they partition the slice set: every slice lands in exactly one bucket and
101
+ // `successCount + failCount + stalledCount === totalSlices` holds for every
102
+ // event set. Before the third bucket existed, a slice stuck at `qa-handoff`
103
+ // was in NEITHER the success nor the fail count and the summary reported
104
+ // fewer outcomes than the slice table showed rows.
105
+ const successCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'success').length;
106
+ const failCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'failed').length;
107
+ const stalledCount = Array.from(bySlice.values()).filter((r) => sliceOutcome(r) === 'stalled').length;
85
108
  const fanoutCostTotal = events.filter((e) => e.category === 'dispatch').length;
86
109
  return {
87
110
  totalEvents: events.length,
88
111
  totalSlices: bySlice.size,
89
112
  successCount,
90
113
  failCount,
114
+ stalledCount,
91
115
  repairCyclePeak,
92
116
  fanoutCostTotal
93
117
  };
@@ -0,0 +1,77 @@
1
+ /**
2
+ * `src/services/observability/compliance-judge.ts`
3
+ *
4
+ * The judge: given a compliance spec and a way to ask whether an artifact
5
+ * exists, report which declared steps actually ran.
6
+ *
7
+ * WHY A JUDGE AND NOT A SCOREBOARD. A pass rate says "the slice passed"; a
8
+ * compliance rate says "the checks the skill PROMISED ran". The difference is
9
+ * the point of the campaign: a slice can pass its gate while a step the skill
10
+ * declared never happened, and only the second reading sees that.
11
+ *
12
+ * THE JUDGE IS PURE. It never touches a filesystem: whether an artifact exists
13
+ * is asked through the `exists` callback the caller supplies. That is what
14
+ * makes one spec judgeable against a real workspace, a fixture, or a
15
+ * hypothetical — and it is why the rules below are statements about RULES
16
+ * rather than about a machine's state.
17
+ *
18
+ * THE DEMOTION RULE, AND WHY IT IS A FIXPOINT. A step that declares
19
+ * `afterStep: X` cannot be credited on the strength of its own artifact when X
20
+ * did not run: the audit that exists without the handoff it read is not
21
+ * evidence of an audit. Demoting one step can invalidate whatever depended on
22
+ * it, so the demotion is applied repeatedly until nothing changes — and since
23
+ * demotion only ever removes a pass, the loop terminates.
24
+ *
25
+ * STEP IDS MUST BE UNIQUE INSIDE A SPEC, AND THE JUDGE ENFORCES IT. The
26
+ * demotion looks a prerequisite up by id, so two steps sharing one id would be
27
+ * judged against each other — and each would overwrite the other's presence
28
+ * in the judge's bookkeeping, so both would report the same verdict. That is
29
+ * a silently wrong compliance number, which is the exact failure this
30
+ * campaign exists to prevent, so a spec that declares one id twice is
31
+ * REJECTED with an error naming the id rather than scored.
32
+ */
33
+ import type { ComplianceSpec } from './compliance-spec.js';
34
+ /** What the judge concluded about one declared step. */
35
+ export type StepResult = {
36
+ /** The step's id, so a reader can find it in the spec. */
37
+ readonly stepId: string;
38
+ /** Whether the step's artifact was there. */
39
+ readonly executed: boolean;
40
+ /**
41
+ * Why the step did not execute. Present exactly when `executed` is false;
42
+ * absent when it is true, because a passing step has nothing to explain.
43
+ */
44
+ readonly failureReason?: string;
45
+ };
46
+ /** The verdict for one spec. */
47
+ export type ComplianceResult = {
48
+ /** The spec's id. */
49
+ readonly specId: string;
50
+ /** One entry per declared step, in the order the spec declares them. */
51
+ readonly steps: readonly StepResult[];
52
+ /**
53
+ * The share of REQUIRED steps that executed. A spec that declares no
54
+ * required step demonstrates no compliance, so the rate is 0 rather than a
55
+ * vacuous 1: the reading that lets a spec declaring nothing read as
56
+ * perfect compliance is the one this metric exists to refuse.
57
+ */
58
+ readonly complianceRate: number;
59
+ };
60
+ /**
61
+ * Judge one spec.
62
+ *
63
+ * @param spec the declared steps to judge.
64
+ * @param exists asked whether a session-relative artifact path is present.
65
+ * THE PATH ARRIVES WITH ITS `<rid>` PLACEHOLDER UNRESOLVED. The judge hands
66
+ * the declared path through verbatim; the CALLER substitutes the request id
67
+ * before probing the filesystem. A caller that probes the raw string gets
68
+ * the literal `<rid>` as a path, every step misses, and the rate reads 0
69
+ * without a single error — so the substitution is the caller's job, and it
70
+ * is stated here because that is where the callback is declared.
71
+ *
72
+ * @throws Error when two steps of the spec share one id. The judge's
73
+ * bookkeeping is keyed by step id, so a repeated id would make two steps
74
+ * overwrite each other's presence and report the same verdict — a silently
75
+ * wrong compliance number. A malformed spec is refused rather than scored.
76
+ */
77
+ export declare function judgeCompliance(spec: ComplianceSpec, exists: (artifactPath: string) => boolean): ComplianceResult;
@@ -0,0 +1,143 @@
1
+ /**
2
+ * `src/services/observability/compliance-judge.ts`
3
+ *
4
+ * The judge: given a compliance spec and a way to ask whether an artifact
5
+ * exists, report which declared steps actually ran.
6
+ *
7
+ * WHY A JUDGE AND NOT A SCOREBOARD. A pass rate says "the slice passed"; a
8
+ * compliance rate says "the checks the skill PROMISED ran". The difference is
9
+ * the point of the campaign: a slice can pass its gate while a step the skill
10
+ * declared never happened, and only the second reading sees that.
11
+ *
12
+ * THE JUDGE IS PURE. It never touches a filesystem: whether an artifact exists
13
+ * is asked through the `exists` callback the caller supplies. That is what
14
+ * makes one spec judgeable against a real workspace, a fixture, or a
15
+ * hypothetical — and it is why the rules below are statements about RULES
16
+ * rather than about a machine's state.
17
+ *
18
+ * THE DEMOTION RULE, AND WHY IT IS A FIXPOINT. A step that declares
19
+ * `afterStep: X` cannot be credited on the strength of its own artifact when X
20
+ * did not run: the audit that exists without the handoff it read is not
21
+ * evidence of an audit. Demoting one step can invalidate whatever depended on
22
+ * it, so the demotion is applied repeatedly until nothing changes — and since
23
+ * demotion only ever removes a pass, the loop terminates.
24
+ *
25
+ * STEP IDS MUST BE UNIQUE INSIDE A SPEC, AND THE JUDGE ENFORCES IT. The
26
+ * demotion looks a prerequisite up by id, so two steps sharing one id would be
27
+ * judged against each other — and each would overwrite the other's presence
28
+ * in the judge's bookkeeping, so both would report the same verdict. That is
29
+ * a silently wrong compliance number, which is the exact failure this
30
+ * campaign exists to prevent, so a spec that declares one id twice is
31
+ * REJECTED with an error naming the id rather than scored.
32
+ */
33
+ /**
34
+ * Judge one spec.
35
+ *
36
+ * @param spec the declared steps to judge.
37
+ * @param exists asked whether a session-relative artifact path is present.
38
+ * THE PATH ARRIVES WITH ITS `<rid>` PLACEHOLDER UNRESOLVED. The judge hands
39
+ * the declared path through verbatim; the CALLER substitutes the request id
40
+ * before probing the filesystem. A caller that probes the raw string gets
41
+ * the literal `<rid>` as a path, every step misses, and the rate reads 0
42
+ * without a single error — so the substitution is the caller's job, and it
43
+ * is stated here because that is where the callback is declared.
44
+ *
45
+ * @throws Error when two steps of the spec share one id. The judge's
46
+ * bookkeeping is keyed by step id, so a repeated id would make two steps
47
+ * overwrite each other's presence and report the same verdict — a silently
48
+ * wrong compliance number. A malformed spec is refused rather than scored.
49
+ */
50
+ export function judgeCompliance(spec, exists) {
51
+ assertUniqueStepIds(spec);
52
+ const executed = new Map();
53
+ const reasons = new Map();
54
+ for (const step of spec.steps) {
55
+ const present = exists(step.verify.artifactExists);
56
+ executed.set(step.id, present);
57
+ if (!present) {
58
+ reasons.set(step.id, `missing artifact: ${step.verify.artifactExists}`);
59
+ }
60
+ }
61
+ demoteUnsatisfiedPrerequisites(spec, executed, reasons);
62
+ const steps = spec.steps.map((step) => {
63
+ const ran = executed.get(step.id) === true;
64
+ const reason = reasons.get(step.id);
65
+ if (ran || reason === undefined) {
66
+ return { stepId: step.id, executed: ran };
67
+ }
68
+ return { stepId: step.id, executed: ran, failureReason: reason };
69
+ });
70
+ const required = spec.steps.filter((step) => step.required);
71
+ const executedRequired = required.filter((step) => executed.get(step.id) === true).length;
72
+ const complianceRate = required.length === 0 ? 0 : executedRequired / required.length;
73
+ return { specId: spec.id, steps, complianceRate };
74
+ }
75
+ /**
76
+ * Refuse a spec that declares the same step id twice.
77
+ *
78
+ * THE REFUSAL IS THE POINT. The judge's bookkeeping is keyed by step id, so
79
+ * two steps sharing one id would overwrite each other's presence and then
80
+ * report the SAME verdict — one of them would be credited on the other's
81
+ * artifact, and the compliance rate would be wrong without anything saying so.
82
+ * A silently wrong compliance number is the exact failure this campaign
83
+ * exists to prevent, so the malformed spec is refused instead of scored.
84
+ */
85
+ function assertUniqueStepIds(spec) {
86
+ const seen = new Set();
87
+ for (const step of spec.steps) {
88
+ if (seen.has(step.id)) {
89
+ throw new Error(`compliance spec "${spec.id}" declares the step id "${step.id}" more than once; ` +
90
+ 'step ids must be unique so each result names exactly one step');
91
+ }
92
+ seen.add(step.id);
93
+ }
94
+ }
95
+ /**
96
+ * Demote every step whose prerequisite did not execute, until nothing changes.
97
+ *
98
+ * A step names its prerequisite by id, and the prerequisite may be declared
99
+ * LATER in the spec — which is why this is a fixpoint rather than a single
100
+ * pass in declaration order. A prerequisite the spec does not declare is
101
+ * unsatisfied by definition: a step cannot be credited on the strength of a
102
+ * prerequisite nobody can show.
103
+ *
104
+ * THE PREREQUISITE'S OWN `required` FLAG DOES NOT MATTER HERE. A step is
105
+ * demoted whenever its prerequisite did not execute, even when that
106
+ * prerequisite is optional: an optional step that did not run is not a
107
+ * failure, but the step that was supposed to come AFTER it cannot be credited
108
+ * on its own artifact alone either, because the thing it was ordered against
109
+ * is not there. This is the conservative reading, and it is the same rule
110
+ * that keeps a required step honest when its prerequisite is missing; it is
111
+ * pinned by a test so it cannot change silently.
112
+ */
113
+ function demoteUnsatisfiedPrerequisites(spec, executed, reasons) {
114
+ const declared = new Set(spec.steps.map((step) => step.id));
115
+ let changed = true;
116
+ while (changed) {
117
+ changed = false;
118
+ for (const step of spec.steps) {
119
+ const prerequisite = step.afterStep;
120
+ if (prerequisite === undefined)
121
+ continue;
122
+ if (executed.get(step.id) !== true)
123
+ continue;
124
+ if (prerequisite === step.id) {
125
+ executed.set(step.id, false);
126
+ reasons.set(step.id, `prerequisite step "${prerequisite}" is this step itself, so no order can be satisfied`);
127
+ changed = true;
128
+ continue;
129
+ }
130
+ if (!declared.has(prerequisite)) {
131
+ executed.set(step.id, false);
132
+ reasons.set(step.id, `prerequisite step "${prerequisite}" is not declared in this spec, so it cannot have run`);
133
+ changed = true;
134
+ continue;
135
+ }
136
+ if (executed.get(prerequisite) === true)
137
+ continue;
138
+ executed.set(step.id, false);
139
+ reasons.set(step.id, `prerequisite step "${prerequisite}" did not execute`);
140
+ changed = true;
141
+ }
142
+ }
143
+ }