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,148 @@
1
+ /**
2
+ * `src/services/observability/near-miss.ts`
3
+ *
4
+ * The near-miss rate: of the slices that were declared PASSING, how many
5
+ * passed anyway after a required check was still unsatisfied?
6
+ *
7
+ * WHY THIS EXISTS. The premise of the whole programme is that "the QA verdict
8
+ * says pass" is a metric that is blind: it cannot see a pass that was bought
9
+ * by skipping a check. This module is the number that can see it. The spec
10
+ * (§2.3 S2.3) names it the headline output of the project, and the review
11
+ * focus of Task 5 is the distinction between "gate skipped and never
12
+ * evaluated" and "gate evaluated and passed" — the latter is normal flow, and
13
+ * misreading it as the former would inflate the metric past meaning.
14
+ *
15
+ * THE REFERENCE MOMENT IS THE SUCCESSFUL PASS. The question this metric asks
16
+ * is "at the moment the slice was declared passing, had the required check
17
+ * been satisfied?" — so the reference is the PASS, not the first
18
+ * `verdict-issued` event and not the last attempt at a key. A `verdict-issued`
19
+ * attempt whose prereq check FAILED is not a pass at all; it is a refused
20
+ * transition recorded under the same `to` state. The pass moment is therefore
21
+ * the first `verdict-issued` attempt whose prereq check SUCCEEDED.
22
+ *
23
+ * A slice with no pass moment was never declared passing, so it is in
24
+ * neither the numerator nor the denominator: there is no pass to have been
25
+ * bought by skipping a check. The EXCEPTION is a slice whose pass moment
26
+ * exists but could not be READ — a `verdict-issued` attempt whose prereq
27
+ * verdict is recorded in a shape this build cannot read. Whether such a slice
28
+ * passed is unknown, so it is reported as UNMEASURED rather than dropped: a
29
+ * slice that vanishes from the accounting reads as "no passing slices", which
30
+ * is an absence read as a result.
31
+ *
32
+ * THE LIVE SET IS A UNION OVER THE SLICE'S WHOLE HISTORY. A gate is "live"
33
+ * for a transition when it WOULD have run had the transition not been
34
+ * bypassed — `liveGateIds(phase, judged)` answers that. But the live set of
35
+ * the FINAL transition is not the question: the size ratchet is live only at
36
+ * `implemented`, so a slice bypassed there and later advanced to `qa-handoff`
37
+ * has an EMPTY live set at its final transition, and a reader who looked only
38
+ * there would see nothing wrong. The union over every gate event the slice
39
+ * ever produced is what catches it.
40
+ *
41
+ * A `bypass` event is the PRIMARY evidence of a near-miss but the rule does
42
+ * not DEPEND on it: a live gate with NO verdict of its own is a near-miss too,
43
+ * because a gate that was skipped and recorded nothing must not vanish from
44
+ * the metric. The converse is what keeps the number honest: a live gate that
45
+ * got a `pass` OR a `block` WAS evaluated, and neither is a near-miss.
46
+ *
47
+ * WHAT THE RULE CANNOT SEE. The live set is the union over the slice's gate
48
+ * EVENTS, so a gate is only ever found unevaluated when a sibling gate event
49
+ * establishes that it was live. A phase at which NO gate event was emitted
50
+ * contributes nothing — the gates live there are not in the live set at all —
51
+ * so that shape is NOT observable for this class, and the coverage output
52
+ * carries the count of slices that produced no gate event.
53
+ *
54
+ * WHY THE DECLARED TYPE IS READ FROM THE EVENT AND NOT FROM THE ARTIFACT.
55
+ * `peaks request retag` rewrites the `- type:` line with no state guard, so
56
+ * the artifact on disk carries the CURRENT type, not the type the transition
57
+ * ran under. The gate event carries the type the transition judged, so the
58
+ * live set is reproduced from the event stream alone.
59
+ *
60
+ * WHY A MISSING DECLARED TYPE FALLS BACK TO THE STREAM. Older gate events
61
+ * (written before the type was carried) exist on this branch without the
62
+ * field. A `claim-table` event at the same phase in the same slice proves
63
+ * the slice was tooling-only at that phase — the claim table only runs for
64
+ * tooling-only slices — and its absence proves it was not. When even that
65
+ * leaves the liveness undetermined (no usable phase), the gate is reported in
66
+ * the `undetermined` list rather than being silently counted or silently
67
+ * dropped: a reader must be able to see that something was not decidable.
68
+ *
69
+ * WHY THE TOOL-BLOCKED BRANCH IS EMPTY. The `tool-trace` category does not
70
+ * exist in the schema yet — the tool-trace stream is a later slice. The
71
+ * branch in `near-miss-facts.ts` is written so that the moment the category
72
+ * lands, the reason starts firing with no change to this file's contract;
73
+ * until then it finds nothing, because there is nothing to find.
74
+ *
75
+ * WHY THE REPORT CARRIES ITS COVERAGE. A rate over a class that had no
76
+ * events to observe is not a rate — it is an absence read as a result, which
77
+ * is the exact failure this programme exists to close. The report therefore
78
+ * says, per class, whether the class was observable at all, and the CLI
79
+ * warns when one was not.
80
+ *
81
+ * WHY THE REPORT CARRIES ITS DENOMINATOR. "Passed" has two definitions here
82
+ * and they do not count the same slices, so the report states the one it
83
+ * uses and reconciles it with the status summary's.
84
+ *
85
+ * WHY THE READERS LIVE NEXT DOOR. `near-miss-facts.ts` holds the event-shape
86
+ * readers this metric is computed from, and `near-miss-records.ts` holds the
87
+ * shape of a finding; this file holds the METRIC and nothing else — the same
88
+ * split `aggregation.ts` and `aggregation-helpers.ts` make in this directory.
89
+ */
90
+ import type { ObservabilityEvent } from './observability-service.js';
91
+ import { type NearMissUndetermined, type NearMissReason } from './near-miss-facts.js';
92
+ import { type NearMissRecord, type NearMissUnmeasured } from './near-miss-records.js';
93
+ import { type NearMissClassCoverage } from './near-miss-coverage.js';
94
+ import { type NearMissDenominator } from './near-miss-denominator.js';
95
+ import type { RequestTypeReading } from './hotspot-shared.js';
96
+ export type { NearMissEvidence, NearMissUndetermined, NearMissReason, UnsatisfiedKey, UnsatisfiedKeyState } from './near-miss-facts.js';
97
+ export type { NearMissClassCoverage } from './near-miss-coverage.js';
98
+ export type { NearMissDenominator } from './near-miss-denominator.js';
99
+ export type { NearMissRecord, NearMissUnmeasured } from './near-miss-records.js';
100
+ /** The near-miss metric over a set of events. */
101
+ export type NearMissReport = {
102
+ /** Near-miss slices over passing slices; 0 when there are no passing slices. */
103
+ readonly nearMissRate: number;
104
+ readonly passedSliceCount: number;
105
+ readonly nearMissSliceCount: number;
106
+ readonly records: readonly NearMissRecord[];
107
+ /** Gates whose liveness or verdict the stream did not decide. */
108
+ readonly undetermined: readonly NearMissUndetermined[];
109
+ /**
110
+ * The slices whose PASS verdict could not be READ.
111
+ *
112
+ * Whether such a slice passed is unknown, so it is in neither the
113
+ * numerator nor the denominator — and it is listed here rather than
114
+ * dropped, because a slice that vanishes from the accounting reads as "no
115
+ * passing slices", which is an absence read as a result.
116
+ */
117
+ readonly unmeasured: readonly NearMissUnmeasured[];
118
+ /**
119
+ * What each reason class could and could not be observed for.
120
+ *
121
+ * A class with `observable: false` had NO events of its kind in the scope,
122
+ * so its share of the rate is an absence of data — not a result. A consumer
123
+ * that reads `nearMissRate` alone can still be misled, so this travels in
124
+ * the same envelope.
125
+ */
126
+ readonly coverage: readonly NearMissClassCoverage[];
127
+ /**
128
+ * The reason classes this scope had NO events to observe.
129
+ *
130
+ * The aggregate `nearMissRate` does NOT cover these classes, so a zero
131
+ * over them is an absence of data rather than a result. The per-class
132
+ * `coverage` entry says the same thing with the numbers behind it.
133
+ */
134
+ readonly unobservedClasses: readonly NearMissReason[];
135
+ /**
136
+ * The denominator the rate divides by, and how it relates to the status
137
+ * summary's success count.
138
+ */
139
+ readonly denominator: NearMissDenominator;
140
+ };
141
+ /**
142
+ * The near-miss metric over a set of events.
143
+ *
144
+ * The rate divides the near-miss slices by the PASSING slices — the slices
145
+ * that recorded a successful verdict attempt — and is 0 when there are none,
146
+ * so an empty scope reads as "no rate" rather than as a division by zero.
147
+ */
148
+ export declare function computeNearMiss(events: readonly ObservabilityEvent[], requestTypes?: ReadonlyMap<string, RequestTypeReading>): NearMissReport;
@@ -0,0 +1,196 @@
1
+ /**
2
+ * `src/services/observability/near-miss.ts`
3
+ *
4
+ * The near-miss rate: of the slices that were declared PASSING, how many
5
+ * passed anyway after a required check was still unsatisfied?
6
+ *
7
+ * WHY THIS EXISTS. The premise of the whole programme is that "the QA verdict
8
+ * says pass" is a metric that is blind: it cannot see a pass that was bought
9
+ * by skipping a check. This module is the number that can see it. The spec
10
+ * (§2.3 S2.3) names it the headline output of the project, and the review
11
+ * focus of Task 5 is the distinction between "gate skipped and never
12
+ * evaluated" and "gate evaluated and passed" — the latter is normal flow, and
13
+ * misreading it as the former would inflate the metric past meaning.
14
+ *
15
+ * THE REFERENCE MOMENT IS THE SUCCESSFUL PASS. The question this metric asks
16
+ * is "at the moment the slice was declared passing, had the required check
17
+ * been satisfied?" — so the reference is the PASS, not the first
18
+ * `verdict-issued` event and not the last attempt at a key. A `verdict-issued`
19
+ * attempt whose prereq check FAILED is not a pass at all; it is a refused
20
+ * transition recorded under the same `to` state. The pass moment is therefore
21
+ * the first `verdict-issued` attempt whose prereq check SUCCEEDED.
22
+ *
23
+ * A slice with no pass moment was never declared passing, so it is in
24
+ * neither the numerator nor the denominator: there is no pass to have been
25
+ * bought by skipping a check. The EXCEPTION is a slice whose pass moment
26
+ * exists but could not be READ — a `verdict-issued` attempt whose prereq
27
+ * verdict is recorded in a shape this build cannot read. Whether such a slice
28
+ * passed is unknown, so it is reported as UNMEASURED rather than dropped: a
29
+ * slice that vanishes from the accounting reads as "no passing slices", which
30
+ * is an absence read as a result.
31
+ *
32
+ * THE LIVE SET IS A UNION OVER THE SLICE'S WHOLE HISTORY. A gate is "live"
33
+ * for a transition when it WOULD have run had the transition not been
34
+ * bypassed — `liveGateIds(phase, judged)` answers that. But the live set of
35
+ * the FINAL transition is not the question: the size ratchet is live only at
36
+ * `implemented`, so a slice bypassed there and later advanced to `qa-handoff`
37
+ * has an EMPTY live set at its final transition, and a reader who looked only
38
+ * there would see nothing wrong. The union over every gate event the slice
39
+ * ever produced is what catches it.
40
+ *
41
+ * A `bypass` event is the PRIMARY evidence of a near-miss but the rule does
42
+ * not DEPEND on it: a live gate with NO verdict of its own is a near-miss too,
43
+ * because a gate that was skipped and recorded nothing must not vanish from
44
+ * the metric. The converse is what keeps the number honest: a live gate that
45
+ * got a `pass` OR a `block` WAS evaluated, and neither is a near-miss.
46
+ *
47
+ * WHAT THE RULE CANNOT SEE. The live set is the union over the slice's gate
48
+ * EVENTS, so a gate is only ever found unevaluated when a sibling gate event
49
+ * establishes that it was live. A phase at which NO gate event was emitted
50
+ * contributes nothing — the gates live there are not in the live set at all —
51
+ * so that shape is NOT observable for this class, and the coverage output
52
+ * carries the count of slices that produced no gate event.
53
+ *
54
+ * WHY THE DECLARED TYPE IS READ FROM THE EVENT AND NOT FROM THE ARTIFACT.
55
+ * `peaks request retag` rewrites the `- type:` line with no state guard, so
56
+ * the artifact on disk carries the CURRENT type, not the type the transition
57
+ * ran under. The gate event carries the type the transition judged, so the
58
+ * live set is reproduced from the event stream alone.
59
+ *
60
+ * WHY A MISSING DECLARED TYPE FALLS BACK TO THE STREAM. Older gate events
61
+ * (written before the type was carried) exist on this branch without the
62
+ * field. A `claim-table` event at the same phase in the same slice proves
63
+ * the slice was tooling-only at that phase — the claim table only runs for
64
+ * tooling-only slices — and its absence proves it was not. When even that
65
+ * leaves the liveness undetermined (no usable phase), the gate is reported in
66
+ * the `undetermined` list rather than being silently counted or silently
67
+ * dropped: a reader must be able to see that something was not decidable.
68
+ *
69
+ * WHY THE TOOL-BLOCKED BRANCH IS EMPTY. The `tool-trace` category does not
70
+ * exist in the schema yet — the tool-trace stream is a later slice. The
71
+ * branch in `near-miss-facts.ts` is written so that the moment the category
72
+ * lands, the reason starts firing with no change to this file's contract;
73
+ * until then it finds nothing, because there is nothing to find.
74
+ *
75
+ * WHY THE REPORT CARRIES ITS COVERAGE. A rate over a class that had no
76
+ * events to observe is not a rate — it is an absence read as a result, which
77
+ * is the exact failure this programme exists to close. The report therefore
78
+ * says, per class, whether the class was observable at all, and the CLI
79
+ * warns when one was not.
80
+ *
81
+ * WHY THE REPORT CARRIES ITS DENOMINATOR. "Passed" has two definitions here
82
+ * and they do not count the same slices, so the report states the one it
83
+ * uses and reconciles it with the status summary's.
84
+ *
85
+ * WHY THE READERS LIVE NEXT DOOR. `near-miss-facts.ts` holds the event-shape
86
+ * readers this metric is computed from, and `near-miss-records.ts` holds the
87
+ * shape of a finding; this file holds the METRIC and nothing else — the same
88
+ * split `aggregation.ts` and `aggregation-helpers.ts` make in this directory.
89
+ */
90
+ import { sliceFacts } from './near-miss-facts.js';
91
+ import { evidenceFor, reasonsFor, unmeasuredReason } from './near-miss-records.js';
92
+ import { computeCoverage, unobservableReasons } from './near-miss-coverage.js';
93
+ import { describeDenominator } from './near-miss-denominator.js';
94
+ /**
95
+ * The events of one slice, grouped by the slice they belong to.
96
+ *
97
+ * An event with no slice rid belongs to no slice, so it is not in any of the
98
+ * populations — it is not a slice's evidence of anything.
99
+ */
100
+ function groupBySlice(events) {
101
+ const bySlice = new Map();
102
+ for (const event of events) {
103
+ const sliceRid = event.sliceRid;
104
+ if (sliceRid === undefined)
105
+ continue;
106
+ const bucket = bySlice.get(sliceRid);
107
+ if (bucket === undefined)
108
+ bySlice.set(sliceRid, [event]);
109
+ else
110
+ bucket.push(event);
111
+ }
112
+ return bySlice;
113
+ }
114
+ /**
115
+ * The walk over the slices: what passed, what was flagged, and what could
116
+ * not be measured at all.
117
+ */
118
+ function walkSlices(bySlice) {
119
+ const records = [];
120
+ const undetermined = [];
121
+ const unmeasured = [];
122
+ const passingFacts = [];
123
+ const unmeasuredFacts = [];
124
+ const reasonsBySlice = new Map();
125
+ let passedSliceCount = 0;
126
+ for (const [sliceRid, sliceEvents] of bySlice) {
127
+ const fact = sliceFacts(sliceRid, sliceEvents);
128
+ const unreadable = fact.unreadableVerdict;
129
+ if (unreadable !== null) {
130
+ // The verdict was RECORDED and could not be READ, so whether the slice
131
+ // passed is unknown. It is in neither the numerator nor the denominator,
132
+ // and it is reported rather than dropped.
133
+ unmeasured.push({
134
+ sliceRid,
135
+ sessionId: unreadable.sessionId,
136
+ ts: unreadable.ts,
137
+ reason: unmeasuredReason(unreadable, fact.passMoment !== null)
138
+ });
139
+ unmeasuredFacts.push(fact);
140
+ continue;
141
+ }
142
+ // A slice with no pass moment was never declared passing.
143
+ if (fact.passMoment === null)
144
+ continue;
145
+ passedSliceCount += 1;
146
+ passingFacts.push(fact);
147
+ const { reasons, neverEvaluated } = reasonsFor(fact);
148
+ undetermined.push(...fact.undetermined);
149
+ if (reasons.length === 0)
150
+ continue;
151
+ const gateEvents = sliceEvents.filter((event) => event.category === 'gate');
152
+ reasonsBySlice.set(sliceRid, reasons);
153
+ records.push({
154
+ sliceRid,
155
+ reasons,
156
+ passMoment: { ts: fact.passMoment.ts },
157
+ unsatisfiedKeys: fact.passMoment.unsatisfiedKeys,
158
+ evidence: evidenceFor(neverEvaluated, gateEvents, fact.passMoment)
159
+ });
160
+ }
161
+ return {
162
+ records,
163
+ undetermined,
164
+ unmeasured,
165
+ passingFacts,
166
+ unmeasuredFacts,
167
+ reasonsBySlice,
168
+ passedSliceCount
169
+ };
170
+ }
171
+ /**
172
+ * The near-miss metric over a set of events.
173
+ *
174
+ * The rate divides the near-miss slices by the PASSING slices — the slices
175
+ * that recorded a successful verdict attempt — and is 0 when there are none,
176
+ * so an empty scope reads as "no rate" rather than as a division by zero.
177
+ */
178
+ export function computeNearMiss(events, requestTypes = new Map()) {
179
+ const walk = walkSlices(groupBySlice(events));
180
+ const { records, undetermined, unmeasured, passingFacts, unmeasuredFacts, reasonsBySlice } = walk;
181
+ const passedSliceCount = walk.passedSliceCount;
182
+ const nearMissSliceCount = records.length;
183
+ const nearMissRate = passedSliceCount === 0 ? 0 : nearMissSliceCount / passedSliceCount;
184
+ const coverage = computeCoverage({ events, passingFacts, reasonsBySlice, unmeasuredFacts });
185
+ return {
186
+ nearMissRate,
187
+ passedSliceCount,
188
+ nearMissSliceCount,
189
+ records,
190
+ undetermined,
191
+ unmeasured,
192
+ coverage,
193
+ unobservedClasses: unobservableReasons(coverage),
194
+ denominator: describeDenominator(events, passedSliceCount, requestTypes, unmeasured.length)
195
+ };
196
+ }
@@ -15,7 +15,21 @@
15
15
  */
16
16
  import { z } from 'zod';
17
17
  export declare const OBSERVABILITY_SCHEMA_VERSION: 1;
18
- export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"];
18
+ /**
19
+ * The event vocabulary every observability record is drawn from.
20
+ *
21
+ * EVERY CATEGORY MUST BE ABLE TO NAME ITS TRIGGER. A category that cannot say
22
+ * what makes it fire is a promise the schema makes and the program does not
23
+ * keep. The audit that records, for every category, where it is emitted, what
24
+ * triggers it and whether it has ever fired, lives at
25
+ * `.peaks/docs/observability-category-audit.md`; a category added to this list
26
+ * joins that table in the same change that declares it.
27
+ *
28
+ * THE ORDER IS THE ON-DISK ORDER, and the list is APPENDED, never reordered:
29
+ * a reader that stores a category by its index must never watch its meaning
30
+ * change under it.
31
+ */
32
+ export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease", "gate"];
19
33
  export type ObservabilityCategory = (typeof OBSERVABILITY_CATEGORIES)[number];
20
34
  export declare const OBSERVABILITY_SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
21
35
  export type ObservabilitySubagentRole = (typeof OBSERVABILITY_SUBAGENT_ROLES)[number];
@@ -24,6 +38,7 @@ export declare const ObservabilityEventSchema: z.ZodObject<{
24
38
  ts: z.ZodString;
25
39
  sessionId: z.ZodString;
26
40
  category: z.ZodEnum<{
41
+ gate: "gate";
27
42
  "slice-transition": "slice-transition";
28
43
  dispatch: "dispatch";
29
44
  checkpoint: "checkpoint";
@@ -66,6 +81,6 @@ export type EmitResult = {
66
81
  };
67
82
  export declare const OBSERVABILITY_CONSTANTS: {
68
83
  readonly SCHEMA_VERSION: 1;
69
- readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"];
84
+ readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease", "gate"];
70
85
  readonly SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
71
86
  };
@@ -15,6 +15,20 @@
15
15
  */
16
16
  import { z } from 'zod';
17
17
  export const OBSERVABILITY_SCHEMA_VERSION = 1;
18
+ /**
19
+ * The event vocabulary every observability record is drawn from.
20
+ *
21
+ * EVERY CATEGORY MUST BE ABLE TO NAME ITS TRIGGER. A category that cannot say
22
+ * what makes it fire is a promise the schema makes and the program does not
23
+ * keep. The audit that records, for every category, where it is emitted, what
24
+ * triggers it and whether it has ever fired, lives at
25
+ * `.peaks/docs/observability-category-audit.md`; a category added to this list
26
+ * joins that table in the same change that declares it.
27
+ *
28
+ * THE ORDER IS THE ON-DISK ORDER, and the list is APPENDED, never reordered:
29
+ * a reader that stores a category by its index must never watch its meaning
30
+ * change under it.
31
+ */
18
32
  export const OBSERVABILITY_CATEGORIES = [
19
33
  'slice-transition',
20
34
  'dispatch',
@@ -30,7 +44,13 @@ export const OBSERVABILITY_CATEGORIES = [
30
44
  // 3.A). Read by `peaks lease metrics`. The `detail.kind` field
31
45
  // discriminates spawn / renew / release / gc / autoRelease /
32
46
  // autoRelease-failed / autoRelease-skipped.
33
- 'lease'
47
+ 'lease',
48
+ // The RD transition gates' verdicts. One event per gate DECISION, so a
49
+ // reader can ask which gate was never evaluated: `detail.gateId` names it
50
+ // ('file-size-ratchet' / 'declared-type-corroboration' / 'claim-table'),
51
+ // `detail.outcome` says what it decided ('pass' / 'block' / 'bypass').
52
+ // APPENDED, so no existing category's index shifts.
53
+ 'gate'
34
54
  ];
35
55
  // v2.12.0 fan-out collapse: `security-reviewer` (in-process RD slot)
36
56
  // moved out to the standalone `peaks-security-audit` skill; the matching
@@ -0,0 +1,92 @@
1
+ /**
2
+ * `src/services/observability/owner-skill-map.ts`
3
+ *
4
+ * The path → owning-skill lookup. An artifact path says WHAT is missing;
5
+ * this table says WHO was supposed to produce it, so a reader of the
6
+ * observability stream can name the skill that failed to deliver rather
7
+ * than only counting the failure.
8
+ *
9
+ * WHY A TABLE AND NOT A RULE. The artifact directories are not derivable
10
+ * from the path shape: `audit/security-<rid>.md` and `audit/perf-<rid>.md`
11
+ * live under the same directory and belong to two different skills, and a
12
+ * rule that said "anything under `audit/` is an audit artifact" would name
13
+ * neither. The table states the ownership explicitly, and the more specific
14
+ * prefix wins when two could match.
15
+ *
16
+ * WHY THERE IS NO `audit/` CATCH-ALL. A directory-level entry for `audit/`
17
+ * would attribute both audit artifacts to one skill, which is the
18
+ * ambiguity this table exists to remove. The audit entries are the
19
+ * specific ones instead — one per artifact, and one per location that
20
+ * artifact is written at.
21
+ *
22
+ * WHY THE LOOKUP ANSWERS `null`. A path has no owner that this table can
23
+ * name, and a guessed owner is worse than none: it would put a skill's name
24
+ * on an artifact that skill never produces. The paths that are genuinely
25
+ * ownerless are listed in `UNOWNED_PATH_ENTRIES` with the reason, so that
26
+ * "no owner" is always a stated fact and never a gap.
27
+ *
28
+ * TWO KINDS OF ROW. A row is a PREFIX claim by default — the path starts
29
+ * with it — and an EXACT claim when it says so. The exact rows exist for
30
+ * the bare, file-shaped legacy locations: a prefix claim on a file name
31
+ * would also claim every file whose name merely starts with it, and an
32
+ * artifact that was never produced must not be attributed to the skill
33
+ * that owns a different file with a similar name.
34
+ *
35
+ * THE `gateEvidence.*` ROWS ARE DECLARATION KEYS, NOT PATHS. The handoff
36
+ * capsule declares the evidence Gate C will check, and a declared key that
37
+ * names a file that is not on disk reaches the missing list under the key's
38
+ * own name. The owner of a key is the skill that produces the evidence the
39
+ * key names — the same question the artifact rows answer, asked of a
40
+ * declaration instead of a file.
41
+ */
42
+ /** One row of the map: a path prefix and the skill that owns what it names. */
43
+ export type OwnerSkillEntry = {
44
+ readonly prefix: string;
45
+ readonly skill: string;
46
+ /**
47
+ * True when `prefix` names ONE file rather than a directory of files: the
48
+ * match is the whole path, not its start.
49
+ */
50
+ readonly exact?: boolean;
51
+ };
52
+ /**
53
+ * The map, in declaration order. The LOOKUP sorts by prefix length, so this
54
+ * order is documentation, not the resolution order.
55
+ */
56
+ export declare const OWNER_SKILL_ENTRIES: readonly OwnerSkillEntry[];
57
+ /**
58
+ * A shape of path that has no owning skill, and the reason it has none.
59
+ *
60
+ * The list exists so that "no owner" is a STATED fact. A path that reaches
61
+ * the missing list and is neither in the map nor here is a hole, and the
62
+ * census test is what turns that hole into a red test.
63
+ */
64
+ export type UnownedPathEntry = {
65
+ /** The path prefix that identifies the shape. */
66
+ readonly prefix: string;
67
+ /** Why no skill owns a path of this shape. */
68
+ readonly reason: string;
69
+ };
70
+ /**
71
+ * The paths that have no owner, and why.
72
+ *
73
+ * `gateEvidence(<status>)` is a handoff capsule whose declaration cannot be
74
+ * read. It is not an artifact: no skill produces a broken capsule, so there
75
+ * is no owner to name — the defect belongs to whoever wrote the capsule, and
76
+ * the gate reports it as a body failure on the capsule itself.
77
+ */
78
+ export declare const UNOWNED_PATH_ENTRIES: readonly UnownedPathEntry[];
79
+ /**
80
+ * The skill that owns the artifact at `path`, or `null` when no row claims
81
+ * it.
82
+ *
83
+ * Total over every input: a value that is not a string answers `null` rather
84
+ * than raising, because this runs inside the observability emit, whose
85
+ * contract is that it never throws and never changes the caller's decision.
86
+ */
87
+ export declare function ownerSkillForPath(path: string): string | null;
88
+ /**
89
+ * The reason the path at `path` has no owning skill, or `null` when the
90
+ * path is not one of the known ownerless shapes.
91
+ */
92
+ export declare function unownedPathReason(path: string): string | null;
@@ -0,0 +1,144 @@
1
+ /**
2
+ * `src/services/observability/owner-skill-map.ts`
3
+ *
4
+ * The path → owning-skill lookup. An artifact path says WHAT is missing;
5
+ * this table says WHO was supposed to produce it, so a reader of the
6
+ * observability stream can name the skill that failed to deliver rather
7
+ * than only counting the failure.
8
+ *
9
+ * WHY A TABLE AND NOT A RULE. The artifact directories are not derivable
10
+ * from the path shape: `audit/security-<rid>.md` and `audit/perf-<rid>.md`
11
+ * live under the same directory and belong to two different skills, and a
12
+ * rule that said "anything under `audit/` is an audit artifact" would name
13
+ * neither. The table states the ownership explicitly, and the more specific
14
+ * prefix wins when two could match.
15
+ *
16
+ * WHY THERE IS NO `audit/` CATCH-ALL. A directory-level entry for `audit/`
17
+ * would attribute both audit artifacts to one skill, which is the
18
+ * ambiguity this table exists to remove. The audit entries are the
19
+ * specific ones instead — one per artifact, and one per location that
20
+ * artifact is written at.
21
+ *
22
+ * WHY THE LOOKUP ANSWERS `null`. A path has no owner that this table can
23
+ * name, and a guessed owner is worse than none: it would put a skill's name
24
+ * on an artifact that skill never produces. The paths that are genuinely
25
+ * ownerless are listed in `UNOWNED_PATH_ENTRIES` with the reason, so that
26
+ * "no owner" is always a stated fact and never a gap.
27
+ *
28
+ * TWO KINDS OF ROW. A row is a PREFIX claim by default — the path starts
29
+ * with it — and an EXACT claim when it says so. The exact rows exist for
30
+ * the bare, file-shaped legacy locations: a prefix claim on a file name
31
+ * would also claim every file whose name merely starts with it, and an
32
+ * artifact that was never produced must not be attributed to the skill
33
+ * that owns a different file with a similar name.
34
+ *
35
+ * THE `gateEvidence.*` ROWS ARE DECLARATION KEYS, NOT PATHS. The handoff
36
+ * capsule declares the evidence Gate C will check, and a declared key that
37
+ * names a file that is not on disk reaches the missing list under the key's
38
+ * own name. The owner of a key is the skill that produces the evidence the
39
+ * key names — the same question the artifact rows answer, asked of a
40
+ * declaration instead of a file.
41
+ */
42
+ /**
43
+ * The map, in declaration order. The LOOKUP sorts by prefix length, so this
44
+ * order is documentation, not the resolution order.
45
+ */
46
+ export const OWNER_SKILL_ENTRIES = [
47
+ { prefix: 'gateEvidence.codeReview', skill: 'peaks-rd' },
48
+ { prefix: 'gateEvidence.perfBaseline', skill: 'peaks-perf-audit' },
49
+ { prefix: 'gateEvidence.prdHandoff', skill: 'peaks-prd' },
50
+ // The project scan is Gate A's artifact, and Gate A belongs to the
51
+ // orchestrator: `skills/peaks-code/SKILL.md` carries it as the MANDATORY
52
+ // "Pre-RD project scan checklist", and
53
+ // `skills/peaks-code/references/project-scan-checklist.md` opens with
54
+ // "Before handing off to `peaks-rd`, scan the project and record findings
55
+ // to `.peaks/project-scan/project-scan.md`". The declared path is that
56
+ // file, so the skill that writes it is the one that owns the key.
57
+ { prefix: 'gateEvidence.projectScan', skill: 'peaks-code' },
58
+ // The security review evidence. For the fanout types the key declares
59
+ // `audit/security-<rid>.md`, which the independent security audit writes;
60
+ // for the `config` type it declares the config-specific
61
+ // `rd/security-review-<rid>.md`, which is an RD artifact. One key, one
62
+ // answer — the row names the skill that owns the security review as a
63
+ // concept, which is the audit skill for every type that reaches it.
64
+ { prefix: 'gateEvidence.securityReview', skill: 'peaks-security-audit' },
65
+ { prefix: 'audit/security-', skill: 'peaks-security-audit' },
66
+ // The bare security audit location — the one that predates the request id
67
+ // in the filename. It is a live tier, not a guess: the judged-declaration
68
+ // check resolves the audit artifact through `securityArtifactTiers`, and
69
+ // that list's second entry is this file — so a session holding it puts that
70
+ // path into the missing list, and a row that did not claim it would leave
71
+ // that missing artifact with no owner. EXACT, because the row claims this
72
+ // one file and not every file whose name begins with it.
73
+ { prefix: 'audit/security.md', skill: 'peaks-security-audit', exact: true },
74
+ { prefix: 'audit/perf-', skill: 'peaks-perf-audit' },
75
+ // The bare perf audit location — the sibling of the security one above,
76
+ // and the same story: the resolver probes it as a legacy tier.
77
+ { prefix: 'audit/perf.md', skill: 'peaks-perf-audit', exact: true },
78
+ { prefix: 'prd/', skill: 'peaks-prd' },
79
+ { prefix: 'ui/', skill: 'peaks-ui' },
80
+ { prefix: 'rd/', skill: 'peaks-rd' },
81
+ // The third-party review is the REVIEWER's artifact, not RD's: the prereq
82
+ // that demands it names the skill that writes it ("v2.14.0 G4 third-party
83
+ // reviewer (peaks-reviewer skill)"). The `rd/` row above is a DIRECTORY
84
+ // claim, so without this row it over-claimed this file and named the wrong
85
+ // skill to fix.
86
+ { prefix: 'rd/third-party-review-', skill: 'peaks-reviewer' },
87
+ { prefix: 'qa/', skill: 'peaks-qa' },
88
+ { prefix: 'sc/', skill: 'peaks-sc' },
89
+ { prefix: 'mut/', skill: 'peaks-mut' }
90
+ ];
91
+ /**
92
+ * The same rows, most specific prefix first. A longer prefix is a narrower
93
+ * claim, so it is tried first — that is what keeps `audit/security.md` ahead
94
+ * of `audit/security-`, and both ahead of a shorter prefix that would also
95
+ * match them.
96
+ */
97
+ const ENTRIES_BY_SPECIFICITY = [...OWNER_SKILL_ENTRIES].sort((a, b) => b.prefix.length - a.prefix.length);
98
+ /**
99
+ * The paths that have no owner, and why.
100
+ *
101
+ * `gateEvidence(<status>)` is a handoff capsule whose declaration cannot be
102
+ * read. It is not an artifact: no skill produces a broken capsule, so there
103
+ * is no owner to name — the defect belongs to whoever wrote the capsule, and
104
+ * the gate reports it as a body failure on the capsule itself.
105
+ */
106
+ export const UNOWNED_PATH_ENTRIES = [
107
+ {
108
+ prefix: 'gateEvidence(',
109
+ reason: 'a handoff capsule whose gateEvidence declaration cannot be read is not an artifact ' +
110
+ 'any skill produces — the defect belongs to whoever wrote the capsule, so there is ' +
111
+ 'no owning skill to name'
112
+ }
113
+ ];
114
+ /**
115
+ * The skill that owns the artifact at `path`, or `null` when no row claims
116
+ * it.
117
+ *
118
+ * Total over every input: a value that is not a string answers `null` rather
119
+ * than raising, because this runs inside the observability emit, whose
120
+ * contract is that it never throws and never changes the caller's decision.
121
+ */
122
+ export function ownerSkillForPath(path) {
123
+ if (typeof path !== 'string')
124
+ return null;
125
+ for (const entry of ENTRIES_BY_SPECIFICITY) {
126
+ const claimed = entry.exact === true ? path === entry.prefix : path.startsWith(entry.prefix);
127
+ if (claimed)
128
+ return entry.skill;
129
+ }
130
+ return null;
131
+ }
132
+ /**
133
+ * The reason the path at `path` has no owning skill, or `null` when the
134
+ * path is not one of the known ownerless shapes.
135
+ */
136
+ export function unownedPathReason(path) {
137
+ if (typeof path !== 'string')
138
+ return null;
139
+ for (const entry of UNOWNED_PATH_ENTRIES) {
140
+ if (path.startsWith(entry.prefix))
141
+ return entry.reason;
142
+ }
143
+ return null;
144
+ }