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,142 @@
1
+ /**
2
+ * `src/services/observability/hotspot-sources.ts`
3
+ *
4
+ * The two readers the hotspot ranking is built from: a FORWARD event's
5
+ * measured missing list, and a HISTORICAL event's count-only failure.
6
+ *
7
+ * WHY THEY ARE HERE AND NOT IN THE RANKING. The ranking says what a row
8
+ * MEANS; this file says how each SOURCE of a row is turned into one. The
9
+ * two are kept apart so the difference between a measurement and a
10
+ * reconstruction is a difference of FILES, not of a branch buried in the
11
+ * middle of a sort.
12
+ *
13
+ * WHY A HISTORICAL EVENT CANNOT CARRY A MODE. A v1 event recorded only a
14
+ * COUNT — not which artifacts were missing, and not whether each was absent
15
+ * or short. So a reconstructed row names the failure SURFACE the
16
+ * prerequisite checks, and the row's confidence is what marks it as a
17
+ * reconstruction rather than a measurement.
18
+ */
19
+ import { getPrerequisitesFor } from '../artifacts/artifact-prerequisites.js';
20
+ import { ALLOWED_STATES_PER_ROLE } from '../artifacts/request-artifact-state-helpers.js';
21
+ import { attributeV1Failure } from './retro-attribution.js';
22
+ import { canonicalArtifact, count, ownerOf } from './hotspot-shared.js';
23
+ /**
24
+ * The artifact roles a transition can belong to.
25
+ *
26
+ * READ FROM THE CANONICAL TABLE, not from a list written here: a second
27
+ * copy of the state vocabulary is a list that rots, and a state missing from
28
+ * it silently drops every failure of that transition — which is how a whole
29
+ * class of failures stops being counted.
30
+ */
31
+ const TRANSITION_ROLES = Object.keys(ALLOWED_STATES_PER_ROLE);
32
+ /** The measured missing list of a forward event, or null when it has none. */
33
+ export function recordedMissing(event) {
34
+ const detail = event.detail;
35
+ if (!Array.isArray(detail.missing))
36
+ return null;
37
+ return detail.missing;
38
+ }
39
+ /**
40
+ * Whether the event is a HISTORICAL failure — a count-only one the
41
+ * retro-attribution can speak about.
42
+ *
43
+ * A forward event carries the missing list as it was measured, so it is not
44
+ * a reconstruction and never enters the retro-attribution.
45
+ */
46
+ export function isHistoricalFailure(event) {
47
+ if (recordedMissing(event) !== null)
48
+ return false;
49
+ return event.detail.prereqOk === false;
50
+ }
51
+ /**
52
+ * The failure mode a prerequisite's own check reports.
53
+ *
54
+ * A prerequisite with no body markers can only fail by the file being
55
+ * ABSENT; one WITH body markers is a file whose MARKERS may be short. The
56
+ * row therefore names the surface the prerequisite checks, which is what a
57
+ * count alone can support.
58
+ */
59
+ function failureSurface(path, role, state, type) {
60
+ const entry = getPrerequisitesFor(role, state, type).find((candidate) => candidate.relativePath === path);
61
+ if (entry === undefined)
62
+ return 'absent';
63
+ const demandsMarkers = (entry.mustContain?.length ?? 0) > 0 ||
64
+ (entry.mustContainAny?.length ?? 0) > 0 ||
65
+ (entry.headingMustContain?.length ?? 0) > 0;
66
+ return demandsMarkers ? 'body' : 'absent';
67
+ }
68
+ /** The rows a slice's forward (measured) missing list contributes. */
69
+ export function forwardRows(event, rid, into) {
70
+ const missing = recordedMissing(event);
71
+ if (missing === null)
72
+ return;
73
+ for (const entry of missing) {
74
+ if (typeof entry.path !== 'string')
75
+ continue;
76
+ const artifact = canonicalArtifact(entry.path, rid);
77
+ const kind = entry.kind === 'body' ? 'body' : 'absent';
78
+ // The owner is the ONE THE EVENT RECORDED, including a null: the event
79
+ // resolved it when it was written, and a path the owner map does not know
80
+ // is exactly the case that must stay visible. The map is only consulted
81
+ // for an entry that carries no owner field at all.
82
+ const ownerSkill = 'ownerSkill' in entry
83
+ ? typeof entry.ownerSkill === 'string'
84
+ ? entry.ownerSkill
85
+ : null
86
+ : ownerOf(artifact);
87
+ count(into, { ownerSkill, artifact, kind, confidence: 'exact', event, rid });
88
+ }
89
+ }
90
+ /**
91
+ * The attribution of one historical failure, or null when the event is not
92
+ * one the retro-attribution can speak about.
93
+ *
94
+ * ONE IMPLEMENTATION, TWO CALLERS. The rows and the attribution summary must
95
+ * agree about which failures were attributed — a copy of this gate would
96
+ * drift, and the drift would show up as two numbers that disagree.
97
+ */
98
+ export function attributeFailure(event, reading) {
99
+ if (reading === undefined)
100
+ return null;
101
+ const requestType = reading.requestType;
102
+ const detail = event.detail;
103
+ const role = typeof detail.artifactRole === 'string' ? detail.artifactRole : '';
104
+ const state = typeof detail.to === 'string' ? detail.to : '';
105
+ const missingCount = typeof detail.missingCount === 'number' ? detail.missingCount : 0;
106
+ if (!TRANSITION_ROLES.includes(role))
107
+ return null;
108
+ if (!ALLOWED_STATES_PER_ROLE[role].includes(state)) {
109
+ return null;
110
+ }
111
+ return {
112
+ attribution: attributeV1Failure({
113
+ artifactRole: role,
114
+ newState: state,
115
+ requestType,
116
+ typeSource: reading.source,
117
+ missingCount
118
+ }),
119
+ role,
120
+ state
121
+ };
122
+ }
123
+ /** The rows a slice's historical (count-only) failure contributes. */
124
+ export function retroRows(event, rid, reading, into) {
125
+ const resolved = attributeFailure(event, reading);
126
+ if (resolved === null)
127
+ return;
128
+ const { attribution, role, state } = resolved;
129
+ for (const candidate of attribution.candidates) {
130
+ const artifact = canonicalArtifact(candidate.path, rid);
131
+ const kind = failureSurface(candidate.path, role, state, reading?.requestType ?? 'feature');
132
+ const ownerSkill = candidate.ownerSkill ?? ownerOf(artifact);
133
+ count(into, {
134
+ ownerSkill,
135
+ artifact,
136
+ kind,
137
+ confidence: attribution.confidence,
138
+ event,
139
+ rid
140
+ });
141
+ }
142
+ }
@@ -0,0 +1,47 @@
1
+ /**
2
+ * `src/services/observability/hotspots.ts`
3
+ *
4
+ * The hotspot ranking: which artifact does a skill keep failing to deliver,
5
+ * and who owns it.
6
+ *
7
+ * WHY THIS EXISTS. The programme's premise is that the QA verdict says
8
+ * "pass" without saying WHICH check was skipped, so a reader cannot go and
9
+ * fix the skill that is actually failing. This ranking names the artifact and
10
+ * its owner, so the next step ("raise this to a hook") has a target.
11
+ *
12
+ * TWO SOURCES, AND THE CONFIDENCE COLUMN SAYS WHICH. A FORWARD event (v2)
13
+ * carries the missing list as it was MEASURED: the path, the mode and the
14
+ * owner are all facts, and the row's confidence is `exact`. A HISTORICAL
15
+ * event (v1) carries only a COUNT, so the artifact is a CANDIDATE recovered
16
+ * by the retro-attribution, and the row's confidence is `inferred` (the count
17
+ * matched the whole prerequisite list) or `ambiguous` (the count did not
18
+ * localise to one entry). The spec (§2.2 S2.2) puts all three tiers in one
19
+ * ranking and requires them to be LABELLED, because an `inferred` row says
20
+ * "this artifact was in the missing set", NOT "this artifact was proven
21
+ * missing". A reader who sorts by count must be able to see which rows are
22
+ * measurements and which are reconstructions.
23
+ *
24
+ * WHY THE ROW SAYS WHAT ITS COUNT COUNTS. The confidence label names HOW the
25
+ * row was known, but a reader sorting by `count` sees a NUMBER and reaches
26
+ * for the obvious meaning — how many times the artifact was missing. For a
27
+ * reconstructed row that meaning is wrong: one real failure contributes to
28
+ * every candidate the attribution could not narrow, so the count is CANDIDATE
29
+ * MENTIONS. The row therefore carries `countMeaning` beside the count, so the
30
+ * number cannot be read the wrong way without the reader having to know the
31
+ * rule.
32
+ *
33
+ * A ROW WITH NO OWNER IS STILL A ROW. An artifact whose directory the
34
+ * owner map does not know is a NEW artifact type, and a new artifact type is
35
+ * exactly what a reader needs to see — the gate is that it is COUNTED, not
36
+ * that it is attributed. Dropping it would hide a whole class of failures
37
+ * behind a mapping gap, which is the failure mode the owner map exists to
38
+ * prevent.
39
+ *
40
+ * WHY THE READERS LIVE NEXT DOOR. `hotspot-rows.ts` holds the reading of
41
+ * the event stream, so this file states what a row MEANS and what the
42
+ * ranking guarantees — the same split `aggregation.ts` and
43
+ * `aggregation-helpers.ts` make in this directory.
44
+ */
45
+ export { aggregateHotspots } from './hotspot-rows.js';
46
+ export { summarizeAttribution, type HotspotAttributionSummary, type RequestArtifactCounts } from './hotspot-attribution-summary.js';
47
+ export { canonicalArtifact, countMeaningOf, type HotspotConfidence, type HotspotEvidence, type HotspotRequestTypes, type HotspotRow, type RequestTypeReading } from './hotspot-shared.js';
@@ -0,0 +1,47 @@
1
+ /**
2
+ * `src/services/observability/hotspots.ts`
3
+ *
4
+ * The hotspot ranking: which artifact does a skill keep failing to deliver,
5
+ * and who owns it.
6
+ *
7
+ * WHY THIS EXISTS. The programme's premise is that the QA verdict says
8
+ * "pass" without saying WHICH check was skipped, so a reader cannot go and
9
+ * fix the skill that is actually failing. This ranking names the artifact and
10
+ * its owner, so the next step ("raise this to a hook") has a target.
11
+ *
12
+ * TWO SOURCES, AND THE CONFIDENCE COLUMN SAYS WHICH. A FORWARD event (v2)
13
+ * carries the missing list as it was MEASURED: the path, the mode and the
14
+ * owner are all facts, and the row's confidence is `exact`. A HISTORICAL
15
+ * event (v1) carries only a COUNT, so the artifact is a CANDIDATE recovered
16
+ * by the retro-attribution, and the row's confidence is `inferred` (the count
17
+ * matched the whole prerequisite list) or `ambiguous` (the count did not
18
+ * localise to one entry). The spec (§2.2 S2.2) puts all three tiers in one
19
+ * ranking and requires them to be LABELLED, because an `inferred` row says
20
+ * "this artifact was in the missing set", NOT "this artifact was proven
21
+ * missing". A reader who sorts by count must be able to see which rows are
22
+ * measurements and which are reconstructions.
23
+ *
24
+ * WHY THE ROW SAYS WHAT ITS COUNT COUNTS. The confidence label names HOW the
25
+ * row was known, but a reader sorting by `count` sees a NUMBER and reaches
26
+ * for the obvious meaning — how many times the artifact was missing. For a
27
+ * reconstructed row that meaning is wrong: one real failure contributes to
28
+ * every candidate the attribution could not narrow, so the count is CANDIDATE
29
+ * MENTIONS. The row therefore carries `countMeaning` beside the count, so the
30
+ * number cannot be read the wrong way without the reader having to know the
31
+ * rule.
32
+ *
33
+ * A ROW WITH NO OWNER IS STILL A ROW. An artifact whose directory the
34
+ * owner map does not know is a NEW artifact type, and a new artifact type is
35
+ * exactly what a reader needs to see — the gate is that it is COUNTED, not
36
+ * that it is attributed. Dropping it would hide a whole class of failures
37
+ * behind a mapping gap, which is the failure mode the owner map exists to
38
+ * prevent.
39
+ *
40
+ * WHY THE READERS LIVE NEXT DOOR. `hotspot-rows.ts` holds the reading of
41
+ * the event stream, so this file states what a row MEANS and what the
42
+ * ranking guarantees — the same split `aggregation.ts` and
43
+ * `aggregation-helpers.ts` make in this directory.
44
+ */
45
+ export { aggregateHotspots } from './hotspot-rows.js';
46
+ export { summarizeAttribution } from './hotspot-attribution-summary.js';
47
+ export { canonicalArtifact, countMeaningOf } from './hotspot-shared.js';
@@ -0,0 +1,175 @@
1
+ /**
2
+ * `src/services/observability/near-miss-attempts.ts`
3
+ *
4
+ * The prereq ATTEMPTS a slice's events record, the moment the slice was
5
+ * declared PASSING, and the keys whose check was still unsatisfied at that
6
+ * moment.
7
+ *
8
+ * WHY A SEPARATE MODULE. The near-miss metric needs to know, for one slice,
9
+ * when it was declared passing and which required checks had not been
10
+ * satisfied by then. That is a reading of the event stream, and it is the
11
+ * reading the `prereq-skipped` reason is built on — so it lives next door, and
12
+ * `near-miss.ts` holds the metric.
13
+ *
14
+ * WHY THE STREAM HOLDS TWO EVENTS PER ATTEMPT. A transition attempt produces
15
+ * TWO `slice-transition` events: the one the prereq check itself emits,
16
+ * carrying the verdict (`{artifactRole, to, prereqOk, missingCount}`), and the
17
+ * one the transition emits after the artifact is written, carrying the
18
+ * arrival (`{from, to, artifactRole}`) and NO verdict. Reading the second as
19
+ * an attempt would double-count every attempt and pair a failure with an
20
+ * unrelated transition, so the attempt IS the verdict event and the verdict
21
+ * -less one is ignored.
22
+ *
23
+ * WHY THE REFERENCE MOMENT IS THE SUCCESSFUL PASS. The question the near-miss
24
+ * literature asks is "at the moment the slice was declared passing, had the
25
+ * required check been satisfied?" — so the reference is the PASS, not the
26
+ * first `verdict-issued` event and not the last attempt at a key. A
27
+ * `verdict-issued` attempt whose prereq check FAILED is not a pass at all; it
28
+ * is a refused transition recorded under the same `to` state. The pass moment
29
+ * is therefore the first `verdict-issued` attempt whose prereq check
30
+ * SUCCEEDED, and a slice with no such attempt never passed — it is in
31
+ * neither the numerator nor the denominator.
32
+ *
33
+ * WHY A KEY IS "UNSATISFIED" RATHER THAN "FAILED". A check that refused and
34
+ * was then satisfied on a retry is a gate working as designed, and the
35
+ * earlier question ("was there ever a failure?") cannot tell the two apart.
36
+ * What the near-miss question asks is whether the key was satisfied WHEN THE
37
+ * SLICE PASSED — and a key whose only successful attempt comes after the pass
38
+ * moment was still unsatisfied at the moment the slice was declared passing.
39
+ *
40
+ * WHY THE KEY IS `artifactRole -> to`. A retry re-runs the SAME check: the
41
+ * same artifact role, moving to the same state. Pairing on the key is what
42
+ * says "this later success answered that earlier failure". Pairing on time
43
+ * alone would pair a failure with any later success, including one for a
44
+ * different transition.
45
+ */
46
+ import type { ObservabilityEvent } from './observability-service.js';
47
+ /** The state a QA verdict is issued at. */
48
+ export declare const VERDICT_STATE = "verdict-issued";
49
+ /** One prereq verdict the stream recorded for a transition attempt. */
50
+ export type PrereqAttempt = {
51
+ /** The position of the attempt in the slice's event stream. */
52
+ readonly index: number;
53
+ /** The transition key: `artifactRole -> to`. */
54
+ readonly key: string;
55
+ /** Whether the check passed. */
56
+ readonly passed: boolean;
57
+ readonly sessionId: string;
58
+ readonly ts: string;
59
+ };
60
+ /**
61
+ * The state of one transition key AT THE PASS MOMENT.
62
+ *
63
+ * WHY THE STATE IS NOT ONE THING. "The check was unsatisfied" covers two
64
+ * materially different situations, and a reader has to be able to tell them
65
+ * apart:
66
+ *
67
+ * - `refused` — the check WAS run at the pass moment and said no. The gate
68
+ * was live, it fired, and the slice passed anyway.
69
+ * - `unattempted` — the check had NOT been run at the pass moment at all.
70
+ * The role that owns the check had not yet attempted its transition.
71
+ *
72
+ * On this repository's recorded history one of the twelve findings is
73
+ * `refused` and eleven are `unattempted` — and the second is the more alarming
74
+ * of the two, because it means the pass was declared before the owning role
75
+ * had even tried. Calling all twelve "refusing" would send a reader hunting
76
+ * for a gate that was firing when it was not.
77
+ */
78
+ export type UnsatisfiedKeyState = 'refused' | 'unattempted';
79
+ /**
80
+ * The transition key an event belongs to, or null when it names no transition.
81
+ *
82
+ * The key is the pair that identifies the CHECK, not the attempt: a retry
83
+ * re-runs the same check, so the key is what pairs a failure with the
84
+ * success that later answered it.
85
+ */
86
+ export declare function attemptKey(event: ObservabilityEvent): string | null;
87
+ /**
88
+ * The prereq verdict an event carries, or null when it carries none.
89
+ *
90
+ * `null` is the verdict-LESS event: the transition itself, which says where
91
+ * the slice went but nothing about whether the check let it go.
92
+ */
93
+ export declare function prereqVerdictOf(event: ObservabilityEvent): boolean | null;
94
+ /**
95
+ * The `verdict-issued` attempt of a slice whose prereq verdict this build
96
+ * cannot READ, or null when there is none.
97
+ *
98
+ * WHY THIS IS NOT "NO VERDICT". The event schema keeps `detail` loose, so a
99
+ * record CAN carry a `prereqOk` that is not a boolean — the string `"true"`,
100
+ * a number, a null. The two cases are different facts: a record with no
101
+ * `prereqOk` at all is the verdict-LESS arrival event, while a record with a
102
+ * `prereqOk` this build cannot read is a verdict that was RECORDED and is
103
+ * UNREADABLE. Reading the second as the first makes the slice vanish: it has
104
+ * no pass moment, so it is in neither the numerator nor the denominator, and
105
+ * no coverage count mentions it.
106
+ *
107
+ * THE SCOPE IS THE VERDICT TRANSITION, because that is the attempt that
108
+ * decides whether the slice passed at all. A malformed verdict on another
109
+ * transition does not make the slice's pass unreadable.
110
+ *
111
+ * `beforeIndex` bounds the search to the attempts that come BEFORE the pass
112
+ * moment: the reference moment is the FIRST successful `verdict-issued`
113
+ * attempt, so an unreadable attempt after it cannot have decided the pass.
114
+ */
115
+ export declare function unreadableVerdictOf(events: readonly ObservabilityEvent[], beforeIndex?: number): UnreadableVerdict | null;
116
+ /** A prereq verdict the record carries in a shape this build cannot read. */
117
+ export type UnreadableVerdict = {
118
+ /** The transition key: `artifactRole -> to`. */
119
+ readonly key: string;
120
+ readonly sessionId: string;
121
+ readonly ts: string;
122
+ /** The value the record carried, spelled out so a reader can see it. */
123
+ readonly value: string;
124
+ };
125
+ /** The attempts a slice's events record, in stream order. */
126
+ export declare function collectAttempts(events: readonly ObservabilityEvent[]): readonly PrereqAttempt[];
127
+ /**
128
+ * The moment the slice was declared PASSING.
129
+ *
130
+ * The pass moment is the first `verdict-issued` attempt whose prereq check
131
+ * SUCCEEDED. A `verdict-issued` attempt whose check failed is a refused
132
+ * transition, not a pass, so it does not end the wait — the slice was still
133
+ * trying when it refused.
134
+ *
135
+ * The POSITION is returned alongside the timestamp because two events can
136
+ * share a millisecond, and the comparison this moment is used for — "was
137
+ * this key satisfied by then?" — is a question about order, which a
138
+ * timestamp cannot answer when the clock does not advance.
139
+ */
140
+ export declare function passMomentOf(attempts: readonly PrereqAttempt[]): {
141
+ readonly index: number;
142
+ readonly ts: string;
143
+ } | null;
144
+ /**
145
+ * The keys whose check was STILL UNSATISFIED when the slice was declared
146
+ * passing, each with its state at that moment.
147
+ *
148
+ * A key qualifies when it recorded at least one failed attempt AND had no
149
+ * successful attempt at or before the pass moment. The absence of a success
150
+ * is what shows it was still unsatisfied when the slice passed.
151
+ *
152
+ * THE STATE AT THE PASS MOMENT IS NOT ONE THING, and the difference is the
153
+ * finding:
154
+ *
155
+ * - `refused` — the check had run at the pass moment and said no. The gate
156
+ * was live, it fired, and the slice passed anyway.
157
+ * - `unattempted` — the check had NOT run at the pass moment. The owning
158
+ * role had not yet attempted its transition, and the slice was declared
159
+ * passing without it.
160
+ *
161
+ * On this repository's recorded history one of the twelve findings is
162
+ * `refused` and eleven are `unattempted`. Calling all twelve "refusing"
163
+ * would send a reader after a gate that was firing when it was not.
164
+ *
165
+ * The failure is not required to PRECEDE the pass moment: a key whose only
166
+ * failure came after the pass is still a key that was unsatisfied when the
167
+ * slice was declared passing, and that is the finding.
168
+ */
169
+ export declare function unsatisfiedKeys(attempts: readonly PrereqAttempt[], passIndex: number): readonly {
170
+ readonly key: string;
171
+ readonly state: UnsatisfiedKeyState;
172
+ readonly refusalCount: number;
173
+ }[];
174
+ /** The failed attempts of one unsatisfied key — the evidence for the finding. */
175
+ export declare function failuresOf(attempts: readonly PrereqAttempt[], key: string): readonly PrereqAttempt[];
@@ -0,0 +1,223 @@
1
+ /**
2
+ * `src/services/observability/near-miss-attempts.ts`
3
+ *
4
+ * The prereq ATTEMPTS a slice's events record, the moment the slice was
5
+ * declared PASSING, and the keys whose check was still unsatisfied at that
6
+ * moment.
7
+ *
8
+ * WHY A SEPARATE MODULE. The near-miss metric needs to know, for one slice,
9
+ * when it was declared passing and which required checks had not been
10
+ * satisfied by then. That is a reading of the event stream, and it is the
11
+ * reading the `prereq-skipped` reason is built on — so it lives next door, and
12
+ * `near-miss.ts` holds the metric.
13
+ *
14
+ * WHY THE STREAM HOLDS TWO EVENTS PER ATTEMPT. A transition attempt produces
15
+ * TWO `slice-transition` events: the one the prereq check itself emits,
16
+ * carrying the verdict (`{artifactRole, to, prereqOk, missingCount}`), and the
17
+ * one the transition emits after the artifact is written, carrying the
18
+ * arrival (`{from, to, artifactRole}`) and NO verdict. Reading the second as
19
+ * an attempt would double-count every attempt and pair a failure with an
20
+ * unrelated transition, so the attempt IS the verdict event and the verdict
21
+ * -less one is ignored.
22
+ *
23
+ * WHY THE REFERENCE MOMENT IS THE SUCCESSFUL PASS. The question the near-miss
24
+ * literature asks is "at the moment the slice was declared passing, had the
25
+ * required check been satisfied?" — so the reference is the PASS, not the
26
+ * first `verdict-issued` event and not the last attempt at a key. A
27
+ * `verdict-issued` attempt whose prereq check FAILED is not a pass at all; it
28
+ * is a refused transition recorded under the same `to` state. The pass moment
29
+ * is therefore the first `verdict-issued` attempt whose prereq check
30
+ * SUCCEEDED, and a slice with no such attempt never passed — it is in
31
+ * neither the numerator nor the denominator.
32
+ *
33
+ * WHY A KEY IS "UNSATISFIED" RATHER THAN "FAILED". A check that refused and
34
+ * was then satisfied on a retry is a gate working as designed, and the
35
+ * earlier question ("was there ever a failure?") cannot tell the two apart.
36
+ * What the near-miss question asks is whether the key was satisfied WHEN THE
37
+ * SLICE PASSED — and a key whose only successful attempt comes after the pass
38
+ * moment was still unsatisfied at the moment the slice was declared passing.
39
+ *
40
+ * WHY THE KEY IS `artifactRole -> to`. A retry re-runs the SAME check: the
41
+ * same artifact role, moving to the same state. Pairing on the key is what
42
+ * says "this later success answered that earlier failure". Pairing on time
43
+ * alone would pair a failure with any later success, including one for a
44
+ * different transition.
45
+ */
46
+ /** The state a QA verdict is issued at. */
47
+ export const VERDICT_STATE = 'verdict-issued';
48
+ /**
49
+ * The transition key an event belongs to, or null when it names no transition.
50
+ *
51
+ * The key is the pair that identifies the CHECK, not the attempt: a retry
52
+ * re-runs the same check, so the key is what pairs a failure with the
53
+ * success that later answered it.
54
+ */
55
+ export function attemptKey(event) {
56
+ const detail = event.detail;
57
+ const role = typeof detail.artifactRole === 'string' ? detail.artifactRole : null;
58
+ const to = typeof detail.to === 'string' ? detail.to : null;
59
+ if (role === null || to === null)
60
+ return null;
61
+ return `${role} -> ${to}`;
62
+ }
63
+ /**
64
+ * The prereq verdict an event carries, or null when it carries none.
65
+ *
66
+ * `null` is the verdict-LESS event: the transition itself, which says where
67
+ * the slice went but nothing about whether the check let it go.
68
+ */
69
+ export function prereqVerdictOf(event) {
70
+ const detail = event.detail;
71
+ return typeof detail.prereqOk === 'boolean' ? detail.prereqOk : null;
72
+ }
73
+ /**
74
+ * The `verdict-issued` attempt of a slice whose prereq verdict this build
75
+ * cannot READ, or null when there is none.
76
+ *
77
+ * WHY THIS IS NOT "NO VERDICT". The event schema keeps `detail` loose, so a
78
+ * record CAN carry a `prereqOk` that is not a boolean — the string `"true"`,
79
+ * a number, a null. The two cases are different facts: a record with no
80
+ * `prereqOk` at all is the verdict-LESS arrival event, while a record with a
81
+ * `prereqOk` this build cannot read is a verdict that was RECORDED and is
82
+ * UNREADABLE. Reading the second as the first makes the slice vanish: it has
83
+ * no pass moment, so it is in neither the numerator nor the denominator, and
84
+ * no coverage count mentions it.
85
+ *
86
+ * THE SCOPE IS THE VERDICT TRANSITION, because that is the attempt that
87
+ * decides whether the slice passed at all. A malformed verdict on another
88
+ * transition does not make the slice's pass unreadable.
89
+ *
90
+ * `beforeIndex` bounds the search to the attempts that come BEFORE the pass
91
+ * moment: the reference moment is the FIRST successful `verdict-issued`
92
+ * attempt, so an unreadable attempt after it cannot have decided the pass.
93
+ */
94
+ export function unreadableVerdictOf(events, beforeIndex) {
95
+ for (const [index, event] of events.entries()) {
96
+ if (beforeIndex !== undefined && index >= beforeIndex)
97
+ return null;
98
+ if (event.category !== 'slice-transition')
99
+ continue;
100
+ const detail = event.detail;
101
+ if (detail.to !== VERDICT_STATE)
102
+ continue;
103
+ if (!('prereqOk' in detail))
104
+ continue;
105
+ if (typeof detail.prereqOk === 'boolean')
106
+ continue;
107
+ return {
108
+ key: attemptKey(event) ?? `-> ${VERDICT_STATE}`,
109
+ sessionId: event.sessionId,
110
+ ts: event.ts,
111
+ value: describePrereqValue(detail.prereqOk)
112
+ };
113
+ }
114
+ return null;
115
+ }
116
+ /**
117
+ * How a prereq verdict that is not a boolean is described to a reader.
118
+ *
119
+ * The value is named, not summarised: a reader who is told "the verdict was
120
+ * unreadable" has to open the record to learn what it actually said, and
121
+ * `"true"` read as a boolean is exactly the reading this build must not make.
122
+ */
123
+ function describePrereqValue(value) {
124
+ if (value === null)
125
+ return 'null';
126
+ if (typeof value === 'string')
127
+ return `the string "${value}"`;
128
+ if (typeof value === 'number')
129
+ return `the number ${String(value)}`;
130
+ if (typeof value === 'boolean')
131
+ return `the boolean ${String(value)}`;
132
+ return `a ${typeof value}`;
133
+ }
134
+ /** The attempts a slice's events record, in stream order. */
135
+ export function collectAttempts(events) {
136
+ const attempts = [];
137
+ for (const [index, event] of events.entries()) {
138
+ if (event.category !== 'slice-transition')
139
+ continue;
140
+ const verdict = prereqVerdictOf(event);
141
+ if (verdict === null)
142
+ continue;
143
+ const key = attemptKey(event);
144
+ if (key === null)
145
+ continue;
146
+ attempts.push({ index, key, passed: verdict, sessionId: event.sessionId, ts: event.ts });
147
+ }
148
+ return attempts;
149
+ }
150
+ /**
151
+ * The moment the slice was declared PASSING.
152
+ *
153
+ * The pass moment is the first `verdict-issued` attempt whose prereq check
154
+ * SUCCEEDED. A `verdict-issued` attempt whose check failed is a refused
155
+ * transition, not a pass, so it does not end the wait — the slice was still
156
+ * trying when it refused.
157
+ *
158
+ * The POSITION is returned alongside the timestamp because two events can
159
+ * share a millisecond, and the comparison this moment is used for — "was
160
+ * this key satisfied by then?" — is a question about order, which a
161
+ * timestamp cannot answer when the clock does not advance.
162
+ */
163
+ export function passMomentOf(attempts) {
164
+ const pass = attempts.find((attempt) => attempt.key.endsWith(`-> ${VERDICT_STATE}`) && attempt.passed);
165
+ return pass === undefined ? null : { index: pass.index, ts: pass.ts };
166
+ }
167
+ /**
168
+ * The keys whose check was STILL UNSATISFIED when the slice was declared
169
+ * passing, each with its state at that moment.
170
+ *
171
+ * A key qualifies when it recorded at least one failed attempt AND had no
172
+ * successful attempt at or before the pass moment. The absence of a success
173
+ * is what shows it was still unsatisfied when the slice passed.
174
+ *
175
+ * THE STATE AT THE PASS MOMENT IS NOT ONE THING, and the difference is the
176
+ * finding:
177
+ *
178
+ * - `refused` — the check had run at the pass moment and said no. The gate
179
+ * was live, it fired, and the slice passed anyway.
180
+ * - `unattempted` — the check had NOT run at the pass moment. The owning
181
+ * role had not yet attempted its transition, and the slice was declared
182
+ * passing without it.
183
+ *
184
+ * On this repository's recorded history one of the twelve findings is
185
+ * `refused` and eleven are `unattempted`. Calling all twelve "refusing"
186
+ * would send a reader after a gate that was firing when it was not.
187
+ *
188
+ * The failure is not required to PRECEDE the pass moment: a key whose only
189
+ * failure came after the pass is still a key that was unsatisfied when the
190
+ * slice was declared passing, and that is the finding.
191
+ */
192
+ export function unsatisfiedKeys(attempts, passIndex) {
193
+ const keys = [];
194
+ const byKey = new Map();
195
+ for (const attempt of attempts) {
196
+ const bucket = byKey.get(attempt.key);
197
+ if (bucket === undefined)
198
+ byKey.set(attempt.key, [attempt]);
199
+ else
200
+ bucket.push(attempt);
201
+ }
202
+ for (const [key, bucket] of byKey) {
203
+ const refusals = bucket.filter((attempt) => !attempt.passed);
204
+ if (refusals.length === 0)
205
+ continue;
206
+ const satisfiedByPass = bucket.some((attempt) => attempt.passed && attempt.index <= passIndex);
207
+ if (satisfiedByPass)
208
+ continue;
209
+ // The state is read at the PASS MOMENT, not over the whole history: a
210
+ // check that refused only AFTER the pass had not run at all by then.
211
+ const refusedAtPass = refusals.some((attempt) => attempt.index <= passIndex);
212
+ keys.push({
213
+ key,
214
+ state: refusedAtPass ? 'refused' : 'unattempted',
215
+ refusalCount: refusals.length
216
+ });
217
+ }
218
+ return keys;
219
+ }
220
+ /** The failed attempts of one unsatisfied key — the evidence for the finding. */
221
+ export function failuresOf(attempts, key) {
222
+ return attempts.filter((attempt) => attempt.key === key && !attempt.passed);
223
+ }