peaks-loop 4.1.22 → 4.1.24

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 (118) hide show
  1. package/.claude-plugin/marketplace.json +12 -2
  2. package/CHANGELOG.md +184 -0
  3. package/dist/cli/commands/code-auto-compact-command.js +19 -1
  4. package/dist/cli/commands/code-gate-step-08-command.js +103 -105
  5. package/dist/cli/commands/code-gate-step-08-remedy.d.ts +10 -2
  6. package/dist/cli/commands/code-gate-step-08-remedy.js +11 -3
  7. package/dist/cli/commands/gate-commands-enforce.d.ts +23 -8
  8. package/dist/cli/commands/gate-commands-enforce.js +27 -12
  9. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  10. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  11. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  12. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  13. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  14. package/dist/cli/commands/observability-commands-queries.js +88 -47
  15. package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
  16. package/dist/cli/commands/observability-commands-session-row.js +201 -0
  17. package/dist/cli/commands/observability-commands.js +81 -20
  18. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  19. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  20. package/dist/services/artifacts/prerequisite-path-census.d.ts +47 -0
  21. package/dist/services/artifacts/prerequisite-path-census.js +100 -0
  22. package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
  23. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  24. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  25. package/dist/services/artifacts/rd-gate-event.js +211 -0
  26. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  27. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  28. package/dist/services/hooks/output.d.ts +67 -1
  29. package/dist/services/hooks/output.js +74 -1
  30. package/dist/services/observability/aggregation-types.d.ts +21 -0
  31. package/dist/services/observability/aggregation.d.ts +12 -2
  32. package/dist/services/observability/aggregation.js +28 -3
  33. package/dist/services/observability/compliance-judge.d.ts +77 -0
  34. package/dist/services/observability/compliance-judge.js +143 -0
  35. package/dist/services/observability/compliance-spec.d.ts +96 -0
  36. package/dist/services/observability/compliance-spec.js +29 -0
  37. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  38. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  39. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  40. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  41. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  42. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  43. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  44. package/dist/services/observability/hotspot-rows.js +89 -0
  45. package/dist/services/observability/hotspot-shared.d.ts +207 -0
  46. package/dist/services/observability/hotspot-shared.js +127 -0
  47. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  48. package/dist/services/observability/hotspot-sources.js +142 -0
  49. package/dist/services/observability/hotspots.d.ts +47 -0
  50. package/dist/services/observability/hotspots.js +47 -0
  51. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  52. package/dist/services/observability/near-miss-attempts.js +223 -0
  53. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  54. package/dist/services/observability/near-miss-coverage.js +108 -0
  55. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  56. package/dist/services/observability/near-miss-denominator.js +75 -0
  57. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  58. package/dist/services/observability/near-miss-difference.js +135 -0
  59. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  60. package/dist/services/observability/near-miss-facts.js +101 -0
  61. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  62. package/dist/services/observability/near-miss-gate-events.js +106 -0
  63. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  64. package/dist/services/observability/near-miss-gates.js +135 -0
  65. package/dist/services/observability/near-miss-records.d.ts +93 -0
  66. package/dist/services/observability/near-miss-records.js +87 -0
  67. package/dist/services/observability/near-miss.d.ts +148 -0
  68. package/dist/services/observability/near-miss.js +203 -0
  69. package/dist/services/observability/observability-schema.d.ts +17 -2
  70. package/dist/services/observability/observability-schema.js +21 -1
  71. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  72. package/dist/services/observability/owner-skill-map.js +164 -0
  73. package/dist/services/observability/repair-cycle-metric.js +6 -3
  74. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  75. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  76. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  77. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  78. package/dist/services/observability/report-formatter.d.ts +49 -3
  79. package/dist/services/observability/report-formatter.js +55 -14
  80. package/dist/services/observability/retro-attribution.d.ts +129 -0
  81. package/dist/services/observability/retro-attribution.js +134 -0
  82. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  83. package/dist/services/observability/session-metric-rows.js +184 -0
  84. package/dist/services/skills/presence-role.js +9 -2
  85. package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
  86. package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
  87. package/dist/shared/incrementing-number.d.ts +57 -0
  88. package/dist/shared/incrementing-number.js +13 -0
  89. package/dist/skills/peaks-maker/index.js +43 -30
  90. package/output-styles/peaks-skill-swarm.md +2 -2
  91. package/package.json +5 -5
  92. package/scripts/install-skills-bundles.mjs +6 -1
  93. package/scripts/install-skills.mjs +10 -1
  94. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  95. package/skills/bee/peaks-prd/SKILL.md +1 -1
  96. package/skills/bee/peaks-qa/SKILL.md +1 -1
  97. package/skills/bee/peaks-rd/SKILL.md +1 -1
  98. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  99. package/skills/bee/peaks-sc/SKILL.md +1 -1
  100. package/skills/bee/peaks-security-audit/SKILL.md +1 -1
  101. package/skills/bee/peaks-txt/SKILL.md +1 -1
  102. package/skills/bee/peaks-ui/SKILL.md +1 -1
  103. package/skills/peaks-audit/SKILL.md +1 -1
  104. package/skills/peaks-code/SKILL.md +1 -1
  105. package/skills/peaks-content/SKILL.md +1 -1
  106. package/skills/peaks-doctor/SKILL.md +1 -1
  107. package/skills/peaks-final-review/SKILL.md +1 -1
  108. package/skills/peaks-ide/SKILL.md +1 -1
  109. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  110. package/skills/peaks-maker/SKILL.md +125 -0
  111. package/skills/peaks-mut/SKILL.md +297 -0
  112. package/skills/peaks-race-code/SKILL.md +1 -1
  113. package/skills/peaks-resume/SKILL.md +1 -1
  114. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  115. package/skills/peaks-solo/SKILL.md +1 -1
  116. package/skills/peaks-sop/SKILL.md +1 -1
  117. package/skills/peaks-status/SKILL.md +1 -1
  118. package/skills/peaks-test/SKILL.md +1 -1
@@ -0,0 +1,165 @@
1
+ /**
2
+ * `src/services/observability/near-miss-facts.ts`
3
+ *
4
+ * The event-stream readers the near-miss metric is computed from: what one
5
+ * slice's events say about the gates that were live, the gates that were
6
+ * evaluated, when the slice was declared PASSING, what its prerequisite
7
+ * attempts recorded, and what the slice could be OBSERVED for at all.
8
+ *
9
+ * WHY THIS IS A SEPARATE MODULE. The near-miss metric reads the observability
10
+ * stream the same way the slice aggregation does — the same event shapes, the
11
+ * same terminal-state vocabulary — and those readers are what this module
12
+ * holds, so `near-miss.ts` holds the METRIC and nothing else. The split
13
+ * follows the precedent in this directory: `aggregation.ts` reads the same
14
+ * stream and keeps its readers in `aggregation-helpers.ts` for the same
15
+ * reason.
16
+ *
17
+ * WHY THE READERS ARE CAREFUL ABOUT WHICH EVENT SAYS WHAT. The stream holds
18
+ * two shapes of `slice-transition` event and they mean different things:
19
+ *
20
+ * - the PREREQ shape (`{artifactRole, to, prereqOk, missingCount}`) is
21
+ * emitted by the prerequisite check itself, BEFORE the transition is
22
+ * allowed to proceed. A `prereqOk: false` on it records a REFUSAL: the
23
+ * gate did its job and the transition did not happen.
24
+ * - the TRANSITION shape (`{from, to, artifactRole}`) is emitted after the
25
+ * artifact was written, so it records an ARRIVAL at that state.
26
+ *
27
+ * A reader that treats the prereq shape's `to` as an arrival would count a
28
+ * blocked transition as a slice that got there. The attempts module reads the
29
+ * prereq shape, and the shape that carries no verdict at all is ignored.
30
+ *
31
+ * WHY THE GATE READERS LIVE NEXT DOOR TOO. A gate is identified by a gate id
32
+ * and a phase, and a prerequisite by a transition key — different
33
+ * vocabularies, so `near-miss-gates.ts` holds the gate side.
34
+ */
35
+ import { type NearMissUndetermined } from './near-miss-gates.js';
36
+ import { type PrereqAttempt, type UnreadableVerdict, type UnsatisfiedKeyState } from './near-miss-attempts.js';
37
+ import type { RdGateId } from '../artifacts/rd-gate-event.js';
38
+ import type { ObservabilityEvent } from './observability-service.js';
39
+ export { KNOWN_GATE_IDS, type NearMissUndetermined } from './near-miss-gates.js';
40
+ /** The event category a tool trace carries once that slice lands. */
41
+ export declare const TOOL_TRACE_CATEGORY = "tool-trace";
42
+ /** Why a slice counts as a near-miss. */
43
+ export type NearMissReason = 'gate-never-evaluated' | 'tool-blocked' | 'prereq-skipped';
44
+ /** A pointer at one raw event, so a reader can check a count against it. */
45
+ export type NearMissEvidence = {
46
+ readonly sessionId: string;
47
+ readonly ts: string;
48
+ /** The gate this event is about, when it is a gate decision. */
49
+ readonly gateId?: string;
50
+ /**
51
+ * The transition key a prereq refusal belongs to, when it is one.
52
+ *
53
+ * The key names WHICH check refused, so a reader can check the pairing: the
54
+ * same key is where a later success would have to appear for the refusal
55
+ * to have been answered.
56
+ */
57
+ readonly transitionKey?: string;
58
+ };
59
+ /**
60
+ * The state of one transition key AT THE PASS MOMENT.
61
+ *
62
+ * WHY THE STATE IS NOT ONE THING. "The check was unsatisfied" covers two
63
+ * materially different situations, and a reader has to be able to tell them
64
+ * apart:
65
+ *
66
+ * - `refused` — the check WAS run at the pass moment and said no. The gate
67
+ * was live, it fired, and the slice passed anyway.
68
+ * - `unattempted` — the check had NOT been run at the pass moment at all.
69
+ * The role that owns the check had not yet attempted its transition.
70
+ *
71
+ * On this repository's recorded history one of the twelve findings is
72
+ * `refused` and eleven are `unattempted` — and the second is the more alarming
73
+ * of the two, because it means the pass was declared before the owning role
74
+ * had even tried. Calling all twelve "still refusing" would send a reader
75
+ * hunting for a gate that was firing when it was not.
76
+ */
77
+ export type { UnsatisfiedKeyState } from './near-miss-attempts.js';
78
+ /** One transition key that was unsatisfied when the slice was declared passing. */
79
+ export type UnsatisfiedKey = {
80
+ /** The transition key: `artifactRole -> to`. */
81
+ readonly key: string;
82
+ /** The state of that key's check AT THE PASS MOMENT. */
83
+ readonly state: UnsatisfiedKeyState;
84
+ /** How many times the check refused, whenever it ran. */
85
+ readonly refusalCount: number;
86
+ };
87
+ /**
88
+ * The moment the slice was declared passing, and what was still unsatisfied
89
+ * at that moment.
90
+ */
91
+ export type PassMoment = {
92
+ /** The position of the successful verdict attempt in the slice's stream. */
93
+ readonly index: number;
94
+ /** The instant of the successful verdict attempt. */
95
+ readonly ts: string;
96
+ /**
97
+ * The transition keys whose check was still unsatisfied when the slice was
98
+ * declared passing, each with its state at that moment.
99
+ */
100
+ readonly unsatisfiedKeys: readonly UnsatisfiedKey[];
101
+ /** The failed attempts of those keys — the evidence for the finding. */
102
+ readonly failures: readonly PrereqAttempt[];
103
+ };
104
+ /** What one slice's events say about it. */
105
+ export type SliceFacts = {
106
+ readonly sliceRid: string;
107
+ /**
108
+ * The moment the slice was declared PASSING, or null when it never was.
109
+ *
110
+ * A slice with no pass moment is not in the metric's denominator: it was
111
+ * never declared passing, so there is no pass to have been bought by
112
+ * skipping a check.
113
+ */
114
+ readonly passMoment: PassMoment | null;
115
+ /** The gate ids that were live at some transition of this slice. */
116
+ readonly liveGates: ReadonlySet<RdGateId>;
117
+ /** The gate ids that got a `pass` or a `block` — i.e. WERE evaluated. */
118
+ readonly evaluatedGates: ReadonlySet<RdGateId>;
119
+ /**
120
+ * The gate ids whose VERDICT could not be read.
121
+ *
122
+ * A verdict this build cannot read is not an absent one: the event named an
123
+ * outcome or a gate id this build does not know. Those gates are not
124
+ * reported as never evaluated — they are reported as undetermined.
125
+ *
126
+ * The scope is settled over the WHOLE slice's gate events, not one event at
127
+ * a time: an event this build cannot attribute to a gate may have been the
128
+ * verdict of a gate that recorded nothing of its own, and of no other.
129
+ */
130
+ readonly unreadableGates: ReadonlySet<RdGateId>;
131
+ /** Whether a tool trace blocked on this slice. */
132
+ readonly toolBlocked: boolean;
133
+ /**
134
+ * The `verdict-issued` attempt whose prereq verdict could not be READ.
135
+ *
136
+ * A slice with one of these has no readable pass moment, and it is neither
137
+ * a pass nor a non-pass: whether it passed is unknown. It is reported as
138
+ * unmeasured rather than dropped, so it cannot read as "no passing slices".
139
+ */
140
+ readonly unreadableVerdict: UnreadableVerdict | null;
141
+ /** The gates whose liveness the stream did not decide. */
142
+ readonly undetermined: readonly NearMissUndetermined[];
143
+ /**
144
+ * What this slice could be OBSERVED for — the evidence each reason class
145
+ * needs, and whether this slice produced any.
146
+ *
147
+ * A slice that produced no gate event cannot be judged on the gate class at
148
+ * all: the live set is the union over the slice's gate events, so with none
149
+ * the union is empty. The same holds for a slice with no prereq attempt
150
+ * and a slice with no tool trace.
151
+ */
152
+ readonly observed: {
153
+ readonly gateEvents: number;
154
+ readonly prereqAttempts: number;
155
+ readonly toolTraces: number;
156
+ };
157
+ };
158
+ /**
159
+ * The facts one slice's events carry.
160
+ *
161
+ * The live set is the union over the slice's gate events of the gates that
162
+ * were live at each event's transition — the union is the whole point, so
163
+ * this walks every gate event rather than the last one.
164
+ */
165
+ export declare function sliceFacts(sliceRid: string, events: readonly ObservabilityEvent[]): SliceFacts;
@@ -0,0 +1,101 @@
1
+ /**
2
+ * `src/services/observability/near-miss-facts.ts`
3
+ *
4
+ * The event-stream readers the near-miss metric is computed from: what one
5
+ * slice's events say about the gates that were live, the gates that were
6
+ * evaluated, when the slice was declared PASSING, what its prerequisite
7
+ * attempts recorded, and what the slice could be OBSERVED for at all.
8
+ *
9
+ * WHY THIS IS A SEPARATE MODULE. The near-miss metric reads the observability
10
+ * stream the same way the slice aggregation does — the same event shapes, the
11
+ * same terminal-state vocabulary — and those readers are what this module
12
+ * holds, so `near-miss.ts` holds the METRIC and nothing else. The split
13
+ * follows the precedent in this directory: `aggregation.ts` reads the same
14
+ * stream and keeps its readers in `aggregation-helpers.ts` for the same
15
+ * reason.
16
+ *
17
+ * WHY THE READERS ARE CAREFUL ABOUT WHICH EVENT SAYS WHAT. The stream holds
18
+ * two shapes of `slice-transition` event and they mean different things:
19
+ *
20
+ * - the PREREQ shape (`{artifactRole, to, prereqOk, missingCount}`) is
21
+ * emitted by the prerequisite check itself, BEFORE the transition is
22
+ * allowed to proceed. A `prereqOk: false` on it records a REFUSAL: the
23
+ * gate did its job and the transition did not happen.
24
+ * - the TRANSITION shape (`{from, to, artifactRole}`) is emitted after the
25
+ * artifact was written, so it records an ARRIVAL at that state.
26
+ *
27
+ * A reader that treats the prereq shape's `to` as an arrival would count a
28
+ * blocked transition as a slice that got there. The attempts module reads the
29
+ * prereq shape, and the shape that carries no verdict at all is ignored.
30
+ *
31
+ * WHY THE GATE READERS LIVE NEXT DOOR TOO. A gate is identified by a gate id
32
+ * and a phase, and a prerequisite by a transition key — different
33
+ * vocabularies, so `near-miss-gates.ts` holds the gate side.
34
+ */
35
+ import { readGate, unreadableGateIds } from './near-miss-gates.js';
36
+ import { collectAttempts, failuresOf, passMomentOf, unreadableVerdictOf, unsatisfiedKeys } from './near-miss-attempts.js';
37
+ export { KNOWN_GATE_IDS } from './near-miss-gates.js';
38
+ /** The event category a tool trace carries once that slice lands. */
39
+ export const TOOL_TRACE_CATEGORY = 'tool-trace';
40
+ /** Fold one tool-trace event into the accumulator. */
41
+ function readToolTrace(acc, event) {
42
+ // The tool-trace category is not in the schema yet, so this branch finds
43
+ // nothing today. It is written now so that the reason starts firing the
44
+ // moment the category lands. The category is compared as a raw string
45
+ // because the schema's own union does not name it yet, and narrowing the
46
+ // comparison to that union would make this branch uncallable.
47
+ const detail = event.detail;
48
+ acc.toolTraces += 1;
49
+ if (detail.outcome === 'block')
50
+ acc.toolBlocked = true;
51
+ }
52
+ /**
53
+ * The facts one slice's events carry.
54
+ *
55
+ * The live set is the union over the slice's gate events of the gates that
56
+ * were live at each event's transition — the union is the whole point, so
57
+ * this walks every gate event rather than the last one.
58
+ */
59
+ export function sliceFacts(sliceRid, events) {
60
+ const gateEvents = events.filter((event) => event.category === 'gate');
61
+ const attempts = collectAttempts(events);
62
+ const gates = {
63
+ liveGates: new Set(),
64
+ evaluatedGates: new Set(),
65
+ namedGates: new Set(),
66
+ unattributedGates: new Set(),
67
+ unreadableGates: new Set(),
68
+ undetermined: []
69
+ };
70
+ const acc = { gates, toolBlocked: false, toolTraces: 0 };
71
+ for (const event of events) {
72
+ if (event.category === TOOL_TRACE_CATEGORY)
73
+ readToolTrace(acc, event);
74
+ else if (event.category === 'gate')
75
+ readGate(gates, event, sliceRid, gateEvents);
76
+ }
77
+ const moment = passMomentOf(attempts);
78
+ const unsatisfied = moment === null ? [] : unsatisfiedKeys(attempts, moment.index);
79
+ const failures = unsatisfied.flatMap((entry) => failuresOf(attempts, entry.key));
80
+ return {
81
+ sliceRid,
82
+ passMoment: moment === null
83
+ ? null
84
+ : { index: moment.index, ts: moment.ts, unsatisfiedKeys: unsatisfied, failures },
85
+ liveGates: gates.liveGates,
86
+ evaluatedGates: gates.evaluatedGates,
87
+ unreadableGates: unreadableGateIds(gates),
88
+ toolBlocked: acc.toolBlocked,
89
+ // The reference moment is the FIRST successful `verdict-issued` attempt,
90
+ // so an unreadable attempt only unsettles the slice's verdict when it
91
+ // comes at or before that moment. With no moment at all, any unreadable
92
+ // attempt leaves the question open.
93
+ unreadableVerdict: unreadableVerdictOf(events, moment?.index),
94
+ undetermined: gates.undetermined,
95
+ observed: {
96
+ gateEvents: gateEvents.length,
97
+ prereqAttempts: attempts.length,
98
+ toolTraces: acc.toolTraces
99
+ }
100
+ };
101
+ }
@@ -0,0 +1,75 @@
1
+ /**
2
+ * `src/services/observability/near-miss-gate-events.ts`
3
+ *
4
+ * The readers of ONE gate event: which gate it names, at which phase, with
5
+ * which outcome, and which gates were live at that phase.
6
+ *
7
+ * WHY THIS IS ITS OWN MODULE. A gate is identified by a gate id and a phase,
8
+ * a prerequisite by a transition key — different vocabularies, so the readers
9
+ * of one sit beside the readers of the other. What lives HERE is the reading
10
+ * of a single event; what lives in `near-miss-gates.ts` is the accumulation
11
+ * of many readings into the facts the metric reads.
12
+ *
13
+ * WHY THE LIVE SET IS REPRODUCED FROM THE EVENT AND NOT FROM THE ARTIFACT.
14
+ * `peaks request retag` rewrites the `- type:` line with no state guard, so
15
+ * the artifact on disk carries the CURRENT type, not the type the transition
16
+ * ran under. The gate event carries the type the transition judged, so the
17
+ * live set is reproduced from the event stream alone.
18
+ *
19
+ * WHY A MISSING DECLARED TYPE FALLS BACK TO THE STREAM. Older gate events
20
+ * (written before the type was carried) exist on this branch without the
21
+ * field. A `claim-table` event at the same phase in the same slice proves
22
+ * the slice was tooling-only at that phase — the claim table only runs for
23
+ * tooling-only slices — and its absence proves it was not. When even that
24
+ * leaves the liveness undetermined (no usable phase), the gate is reported
25
+ * rather than guessed at.
26
+ */
27
+ import { type RequestType } from '../artifacts/artifact-prerequisites.js';
28
+ import { type RdGateId } from '../artifacts/rd-gate-event.js';
29
+ import type { RdGatePhase } from '../artifacts/rd-transition-gates.js';
30
+ import type { ObservabilityEvent } from './observability-service.js';
31
+ /** The gate that only a tooling-only slice runs. */
32
+ export declare const CLAIM_TABLE_GATE: RdGateId;
33
+ /**
34
+ * The gate ids this metric knows how to judge.
35
+ *
36
+ * READ FROM THE CANONICAL LIST, not re-typed here: a second copy of the
37
+ * vocabulary is a list that rots, and it rots SILENTLY — a gate id added
38
+ * upstream would not be in the copy, so `gateIdOf` would answer null for it
39
+ * and a gate that PASSED would never be counted as evaluated, reading as
40
+ * "never evaluated" — a false near-miss.
41
+ */
42
+ export declare const KNOWN_GATE_IDS: readonly RdGateId[];
43
+ /** The gate id an event's own detail names, or null when it names none we know. */
44
+ export declare function gateIdOf(event: ObservabilityEvent): RdGateId | null;
45
+ /**
46
+ * The phase a gate event was recorded at, or null when it carries none.
47
+ *
48
+ * TYPED BY THE GATE LAYER'S OWN UNION, not by a second copy of it: the copy
49
+ * would be a list that rots, and it rots silently — a phase added upstream
50
+ * would not be in the copy, so a gate that PASSED at that phase would be read
51
+ * as carrying no usable phase, and the slice would be reported as
52
+ * undetermined instead of evaluated.
53
+ */
54
+ export declare function phaseOf(event: ObservabilityEvent): RdGatePhase | null;
55
+ /** The declared type a gate event carries, or null when it carries none usable. */
56
+ export declare function declaredTypeOf(event: ObservabilityEvent): RequestType | null;
57
+ /** The outcome a gate event carries. */
58
+ export declare function outcomeOf(event: ObservabilityEvent): string;
59
+ /**
60
+ * Whether the slice was tooling-only at a phase, judged from the stream.
61
+ *
62
+ * The claim table only runs for tooling-only slices, so a claim-table event
63
+ * at this phase in this slice proves the slice was tooling-only here, and its
64
+ * absence proves it was not. This is the fallback for gate events written
65
+ * before the declared type was carried.
66
+ */
67
+ export declare function toolingOnlyAtPhase(phase: RdGatePhase, gateEvents: readonly ObservabilityEvent[]): boolean;
68
+ /**
69
+ * The live gate set of one gate event's transition, or null when it cannot
70
+ * be reproduced.
71
+ *
72
+ * `null` means the liveness is undetermined — the event carries no usable
73
+ * phase — and the caller reports it rather than guessing.
74
+ */
75
+ export declare function liveGatesOf(event: ObservabilityEvent, gateEvents: readonly ObservabilityEvent[]): readonly RdGateId[] | null;
@@ -0,0 +1,106 @@
1
+ /**
2
+ * `src/services/observability/near-miss-gate-events.ts`
3
+ *
4
+ * The readers of ONE gate event: which gate it names, at which phase, with
5
+ * which outcome, and which gates were live at that phase.
6
+ *
7
+ * WHY THIS IS ITS OWN MODULE. A gate is identified by a gate id and a phase,
8
+ * a prerequisite by a transition key — different vocabularies, so the readers
9
+ * of one sit beside the readers of the other. What lives HERE is the reading
10
+ * of a single event; what lives in `near-miss-gates.ts` is the accumulation
11
+ * of many readings into the facts the metric reads.
12
+ *
13
+ * WHY THE LIVE SET IS REPRODUCED FROM THE EVENT AND NOT FROM THE ARTIFACT.
14
+ * `peaks request retag` rewrites the `- type:` line with no state guard, so
15
+ * the artifact on disk carries the CURRENT type, not the type the transition
16
+ * ran under. The gate event carries the type the transition judged, so the
17
+ * live set is reproduced from the event stream alone.
18
+ *
19
+ * WHY A MISSING DECLARED TYPE FALLS BACK TO THE STREAM. Older gate events
20
+ * (written before the type was carried) exist on this branch without the
21
+ * field. A `claim-table` event at the same phase in the same slice proves
22
+ * the slice was tooling-only at that phase — the claim table only runs for
23
+ * tooling-only slices — and its absence proves it was not. When even that
24
+ * leaves the liveness undetermined (no usable phase), the gate is reported
25
+ * rather than guessed at.
26
+ */
27
+ import { isRequestType } from '../artifacts/artifact-prerequisites.js';
28
+ import { liveGateIds, RD_GATE_IDS } from '../artifacts/rd-gate-event.js';
29
+ import { isToolingOnlyDeclaredType } from '../scan/type-corroboration.js';
30
+ /** The gate that only a tooling-only slice runs. */
31
+ export const CLAIM_TABLE_GATE = 'claim-table';
32
+ /**
33
+ * The gate ids this metric knows how to judge.
34
+ *
35
+ * READ FROM THE CANONICAL LIST, not re-typed here: a second copy of the
36
+ * vocabulary is a list that rots, and it rots SILENTLY — a gate id added
37
+ * upstream would not be in the copy, so `gateIdOf` would answer null for it
38
+ * and a gate that PASSED would never be counted as evaluated, reading as
39
+ * "never evaluated" — a false near-miss.
40
+ */
41
+ export const KNOWN_GATE_IDS = RD_GATE_IDS;
42
+ /** The gate id an event's own detail names, or null when it names none we know. */
43
+ export function gateIdOf(event) {
44
+ const detail = event.detail;
45
+ const gateId = detail.gateId;
46
+ if (typeof gateId !== 'string')
47
+ return null;
48
+ return KNOWN_GATE_IDS.find((known) => known === gateId) ?? null;
49
+ }
50
+ /**
51
+ * The phase a gate event was recorded at, or null when it carries none.
52
+ *
53
+ * TYPED BY THE GATE LAYER'S OWN UNION, not by a second copy of it: the copy
54
+ * would be a list that rots, and it rots silently — a phase added upstream
55
+ * would not be in the copy, so a gate that PASSED at that phase would be read
56
+ * as carrying no usable phase, and the slice would be reported as
57
+ * undetermined instead of evaluated.
58
+ */
59
+ export function phaseOf(event) {
60
+ const detail = event.detail;
61
+ const phase = detail.phase;
62
+ if (phase === 'implemented' || phase === 'qa-handoff' || phase === 'handed-off')
63
+ return phase;
64
+ return null;
65
+ }
66
+ /** The declared type a gate event carries, or null when it carries none usable. */
67
+ export function declaredTypeOf(event) {
68
+ const detail = event.detail;
69
+ const declaredType = detail.declaredType;
70
+ if (typeof declaredType !== 'string' || !isRequestType(declaredType))
71
+ return null;
72
+ return declaredType;
73
+ }
74
+ /** The outcome a gate event carries. */
75
+ export function outcomeOf(event) {
76
+ const detail = event.detail;
77
+ return typeof detail.outcome === 'string' ? detail.outcome : '';
78
+ }
79
+ /**
80
+ * Whether the slice was tooling-only at a phase, judged from the stream.
81
+ *
82
+ * The claim table only runs for tooling-only slices, so a claim-table event
83
+ * at this phase in this slice proves the slice was tooling-only here, and its
84
+ * absence proves it was not. This is the fallback for gate events written
85
+ * before the declared type was carried.
86
+ */
87
+ export function toolingOnlyAtPhase(phase, gateEvents) {
88
+ return gateEvents.some((event) => phaseOf(event) === phase && gateIdOf(event) === CLAIM_TABLE_GATE);
89
+ }
90
+ /**
91
+ * The live gate set of one gate event's transition, or null when it cannot
92
+ * be reproduced.
93
+ *
94
+ * `null` means the liveness is undetermined — the event carries no usable
95
+ * phase — and the caller reports it rather than guessing.
96
+ */
97
+ export function liveGatesOf(event, gateEvents) {
98
+ const phase = phaseOf(event);
99
+ if (phase === null)
100
+ return null;
101
+ const declaredType = declaredTypeOf(event);
102
+ const judged = declaredType === null
103
+ ? toolingOnlyAtPhase(phase, gateEvents)
104
+ : isToolingOnlyDeclaredType(declaredType);
105
+ return liveGateIds(phase, judged);
106
+ }
@@ -0,0 +1,108 @@
1
+ /**
2
+ * `src/services/observability/near-miss-gates.ts`
3
+ *
4
+ * The GATE facts the near-miss metric is computed from: which gates were
5
+ * live, which of them were evaluated, which of them recorded a verdict this
6
+ * build cannot read, and the liveness of the ones the stream did not decide.
7
+ *
8
+ * WHY THIS IS ITS OWN MODULE. The near-miss metric reads the gate side of
9
+ * the stream and the prerequisite side of the stream, and the two have
10
+ * different vocabularies: a gate is identified by a gate id and a phase, a
11
+ * prerequisite by a transition key. Keeping the readers of one beside the
12
+ * readers of the other is what lets the metric itself stay a metric. The
13
+ * readers of a single gate event live in `near-miss-gate-events.ts`; what
14
+ * lives here is the accumulation of many readings into the facts.
15
+ *
16
+ * WHY THE READERS OF ONE EVENT ARE BESIDE THE READERS OF MANY. The scope of
17
+ * an unreadable verdict depends on what the WHOLE slice's gate events say —
18
+ * an event this build cannot attribute may have been the verdict of a gate
19
+ * that recorded nothing of its own, and of no other. So the decision of what
20
+ * is unreadable cannot be made by one event alone, and the facts it reads
21
+ * have to be accumulated before it is answered.
22
+ */
23
+ import { type RdGateId } from '../artifacts/rd-gate-event.js';
24
+ import type { ObservabilityEvent } from './observability-service.js';
25
+ /** A gate whose liveness could not be decided from the event stream. */
26
+ export type NearMissUndetermined = {
27
+ readonly sliceRid: string;
28
+ readonly sessionId: string;
29
+ readonly ts: string;
30
+ readonly gateId: string;
31
+ /**
32
+ * WHAT could not be decided — the liveness of the gate, or its verdict.
33
+ *
34
+ * The two are different questions, and a count that says only "undetermined"
35
+ * cannot say which one it counted.
36
+ */
37
+ readonly kind: 'liveness' | 'verdict';
38
+ /** What left the question open. */
39
+ readonly reason: string;
40
+ };
41
+ /**
42
+ * The gate facts one slice's events carry, accumulated as the stream is walked.
43
+ *
44
+ * MUTABLE on purpose: this is the accumulator the reader folds events into,
45
+ * and the metric reads the finished set. The public surface exposes them
46
+ * read-only.
47
+ */
48
+ export type GateFacts = {
49
+ /** The gate ids that were live at some transition of this slice. */
50
+ readonly liveGates: Set<RdGateId>;
51
+ /** The gate ids that got a `pass` or a `block` — i.e. WERE evaluated. */
52
+ readonly evaluatedGates: Set<RdGateId>;
53
+ /**
54
+ * The gate ids some event NAMED, whatever verdict that event carried.
55
+ *
56
+ * A gate that has an event of its own carries its own verdict, and the
57
+ * verdict of one gate says nothing about another — that is what keeps an
58
+ * event about a gate this build does not know from masking a gate that
59
+ * was bypassed.
60
+ */
61
+ readonly namedGates: Set<RdGateId>;
62
+ /**
63
+ * The live gates an event naming a gate this build does not know MIGHT
64
+ * have been about.
65
+ *
66
+ * Such an event cannot be attributed to a gate, so it may be the verdict
67
+ * of any gate that was live at its phase and recorded no verdict of its
68
+ * own. The scope is settled by `unreadableGateIds`, once every event of
69
+ * the slice has been read.
70
+ */
71
+ readonly unattributedGates: Set<RdGateId>;
72
+ /**
73
+ * The gate ids whose own VERDICT could not be read.
74
+ *
75
+ * An unreadable verdict is not an absent one: a gate whose own event
76
+ * names an outcome this build does not know was not shown to have been
77
+ * skipped — it was shown to be unreadable. Those gates are excluded from
78
+ * the never-evaluated finding, and reported as undetermined instead.
79
+ */
80
+ readonly unreadableGates: Set<RdGateId>;
81
+ /** The gates whose liveness the stream did not decide. */
82
+ readonly undetermined: NearMissUndetermined[];
83
+ };
84
+ /**
85
+ * The gates whose verdict this build cannot read.
86
+ *
87
+ * An event that names a KNOWN gate and an outcome this build does not know
88
+ * leaves exactly that gate unreadable. An event that names a gate this build
89
+ * does not know leaves UNATTRIBUTED: it may have been the verdict of any gate
90
+ * that was live at its phase and recorded no verdict of its own — and of no
91
+ * other, because a gate that recorded a verdict of its own carries that
92
+ * verdict, and one gate's verdict says nothing about another's.
93
+ */
94
+ export declare function unreadableGateIds(facts: GateFacts): ReadonlySet<RdGateId>;
95
+ /**
96
+ * Fold one gate event into the gate facts.
97
+ *
98
+ * A VERDICT THIS BUILD CANNOT READ IS NOT A FINDING. The event schema keeps
99
+ * `detail` loose, so an event can carry an outcome this build does not know
100
+ * (`'PASS'`) or name a gate id this build does not know. Neither is a gate
101
+ * that was skipped: both are events whose verdict cannot be read. Reading them
102
+ * as "never evaluated" would report a slice that evaluated every gate as one
103
+ * that skipped one — a false near-miss at a rate of 100%.
104
+ */
105
+ export declare function readGate(facts: GateFacts, event: ObservabilityEvent, sliceRid: string, gateEvents: readonly ObservabilityEvent[]): void;
106
+ export { gateIdOf, liveGatesOf, phaseOf } from './near-miss-gate-events.js';
107
+ export { CLAIM_TABLE_GATE, KNOWN_GATE_IDS } from './near-miss-gate-events.js';
108
+ export { declaredTypeOf, outcomeOf, toolingOnlyAtPhase } from './near-miss-gate-events.js';