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,234 @@
1
+ /**
2
+ * `src/services/observability/report-formatter-near-miss.ts`
3
+ *
4
+ * The near-miss section of the markdown report.
5
+ *
6
+ * WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
7
+ * 300-line cap, and this section does not fit beside the rest of it. The
8
+ * split follows the precedent in this directory: the hotspot section lives
9
+ * in `report-formatter-hotspots.ts` for the same reason.
10
+ *
11
+ * WHY THE RATE NEVER APPEARS ALONE. The report is what leaves the terminal
12
+ * — it gets pasted into a PR description — so a number in it has to be read
13
+ * the way it was measured. The near-miss rate is measured over the reason
14
+ * classes the scope had events for, and a scope can hold events for ONE of
15
+ * the three classes: the `gate` emitter postdates every session in this
16
+ * repository's recorded history, so two of the three classes have no events
17
+ * at all there.
18
+ *
19
+ * A rate printed on its own is therefore ambiguous between "there were no
20
+ * near-misses" and "the classes that could have shown a near-miss were never
21
+ * observed" — and the second reading is an ABSENCE read as a RESULT, which
22
+ * is the exact failure this whole programme exists to close. So the rate line
23
+ * carries its coverage with it: how many of the reason classes the rate was
24
+ * measured over, and that the rest is an absence of data rather than a
25
+ * result. A reader who sees ONLY the rate line still cannot draw the wrong
26
+ * conclusion.
27
+ *
28
+ * WHY THE COVERAGE IS A TABLE. Each class's rate divides by the slices THAT
29
+ * CLASS REACHED, not by every passing slice, so the class's own population
30
+ * has to travel with its number. The table says, per class: whether the class
31
+ * was observable at all, how many events it had, how many slices it reached,
32
+ * how many it flagged, and the rate it supports — or `not measured`, which is
33
+ * what a class with no events gets instead of a zero. It also says how many
34
+ * slices said NOTHING about the class: those slices could not be judged on it,
35
+ * and they are the ones a skipped check would hide in.
36
+ *
37
+ * WHY THE FLAGGED SLICES ARE LISTED. The count has to have a referent: a
38
+ * reader who is told that one slice passed with a check unsatisfied has to
39
+ * be able to see WHICH slice and WHICH check.
40
+ */
41
+ /** How many decimals the rate's fraction is rounded to. */
42
+ const RATE_DECIMALS = 3;
43
+ /** How many decimals the rate's percentage is rounded to. */
44
+ const PERCENT_DECIMALS = 1;
45
+ /** The rate as a fraction and as a percentage — the two readings of one number. */
46
+ function formatRate(rate) {
47
+ const fraction = Number(rate.toFixed(RATE_DECIMALS));
48
+ const percent = Number((rate * 100).toFixed(PERCENT_DECIMALS));
49
+ return `${fraction} (${percent}%)`;
50
+ }
51
+ /** A rate as a percentage alone — the coverage table's cell. */
52
+ function formatPercent(rate) {
53
+ return `${Number((rate * 100).toFixed(PERCENT_DECIMALS))}%`;
54
+ }
55
+ /**
56
+ * The line that states the rate AND what the rate was measured over.
57
+ *
58
+ * The qualifier is on the rate's own line, not on a line further down, so a
59
+ * reader who reads nothing else still cannot take a zero for a finding.
60
+ */
61
+ function rateLine(nearMiss) {
62
+ const observableCount = nearMiss.coverage.filter((item) => item.observable).length;
63
+ const unobservedCount = nearMiss.unobservedClasses.length;
64
+ const coverage = unobservedCount === 0
65
+ ? `measured over all ${nearMiss.coverage.length} reason classes, every one of which was ` +
66
+ 'OBSERVABLE in this scope'
67
+ : `measured over the ${observableCount} of ${nearMiss.coverage.length} reason classes that ` +
68
+ `were OBSERVABLE in this scope; the other ${unobservedCount} class(es) had no events to ` +
69
+ 'observe, so their share of the rate is an absence of data, not a result';
70
+ return (`- **rate**: ${formatRate(nearMiss.nearMissRate)} — ` +
71
+ `${nearMiss.nearMissSliceCount} of ${nearMiss.passedSliceCount} passed slice(s) were ` +
72
+ `near-misses. The rate is ${coverage}.`);
73
+ }
74
+ /** The line that states the denominator and the definition it counts by. */
75
+ function denominatorLine(nearMiss) {
76
+ const denominator = nearMiss.denominator;
77
+ return `- **denominator**: ${denominator.sliceCount} slice(s) — ${denominator.definition}`;
78
+ }
79
+ /**
80
+ * The line that reconciles the denominator with the status summary's count.
81
+ *
82
+ * "Passed" has two definitions in this repository and they do not count the
83
+ * same slices, so the difference is stated rather than smoothed over.
84
+ */
85
+ function statusLine(nearMiss) {
86
+ const denominator = nearMiss.denominator;
87
+ if (denominator.difference === null) {
88
+ return (`- **status summary's success count**: ${denominator.statusSuccessCount} — the two ` +
89
+ '"passed" definitions agree over this scope.');
90
+ }
91
+ return (`- **status summary's success count**: ${denominator.statusSuccessCount} — the two ` +
92
+ '"passed" definitions do NOT count the same slices; the gap is stated below.');
93
+ }
94
+ /**
95
+ * The lines that say which gates the stream did not decide.
96
+ *
97
+ * The count covers TWO kinds, and the wording names both: a gate whose
98
+ * LIVENESS the stream did not decide (no usable phase), and a gate whose
99
+ * VERDICT the stream did not decide (an outcome or a gate id this build does
100
+ * not know). A count that said only "liveness" would misdescribe the two of
101
+ * the three kinds it carries.
102
+ */
103
+ function undeterminedLines(nearMiss) {
104
+ const lines = [
105
+ `- **undetermined**: ${nearMiss.undetermined.length} gate(s) whose liveness or verdict the ` +
106
+ 'recorded stream did not decide.'
107
+ ];
108
+ for (const item of nearMiss.undetermined) {
109
+ lines.push(` - \`${item.sliceRid}\` / \`${item.gateId}\` — ${item.reason}`);
110
+ }
111
+ return lines;
112
+ }
113
+ /**
114
+ * The lines that say which slices could not be MEASURED at all.
115
+ *
116
+ * A slice whose `verdict-issued` attempt records a prereq verdict this build
117
+ * cannot read is neither a pass nor a non-pass, so it is in neither the
118
+ * numerator nor the denominator. It is listed here because a slice that
119
+ * vanishes from the accounting reads as "no passing slices" — an absence read
120
+ * as a result.
121
+ */
122
+ function unmeasuredLines(nearMiss) {
123
+ const lines = [
124
+ `- **unmeasured**: ${nearMiss.unmeasured.length} slice(s) whose pass verdict could not be READ, ` +
125
+ 'so they are in neither the numerator nor the denominator.'
126
+ ];
127
+ for (const item of nearMiss.unmeasured) {
128
+ lines.push(` - \`${item.sliceRid}\` — ${item.reason}`);
129
+ }
130
+ return lines;
131
+ }
132
+ /** The coverage table: what each reason class could and could not be observed for. */
133
+ function coverageTable(coverage) {
134
+ const lines = [];
135
+ lines.push('### Coverage');
136
+ lines.push('');
137
+ lines.push("Each class's rate is over the slices that class REACHED — a class that saw five slices " +
138
+ 'out of a hundred reports one in five, not one in a hundred. A class with no events was ' +
139
+ 'NOT observed, so it has no rate. The slices that recorded NOTHING about the class could ' +
140
+ 'not be judged on it at all, so their count is stated beside the rate, as is the count of ' +
141
+ 'the slices whose verdict could not be READ at all — they are in neither the numerator ' +
142
+ 'nor the denominator.');
143
+ lines.push('');
144
+ lines.push('| reason class | observable | events | slices observed | slices with no events | ' +
145
+ 'slices unreadable | slices flagged | rate |');
146
+ lines.push('|---|---|---|---|---|---|---|---|');
147
+ for (const item of coverage) {
148
+ lines.push(`| ${item.reason} | ${item.observable ? 'yes' : 'no'} | ${item.scopeEventCount} | ` +
149
+ `${item.observedSliceCount} | ${item.unobservedSliceCount} | ${item.unreadableSliceCount} | ` +
150
+ `${item.nearMissSliceCount} | ` +
151
+ `${item.rate === null ? 'not measured' : formatPercent(item.rate)} |`);
152
+ }
153
+ lines.push('');
154
+ return lines.join('\n');
155
+ }
156
+ /** The line that names the classes the rate does not measure. */
157
+ function unobservedLine(nearMiss) {
158
+ const unobserved = nearMiss.unobservedClasses;
159
+ if (unobserved.length === 0) {
160
+ return '- **unobserved classes**: none — every reason class had events to observe in this scope.';
161
+ }
162
+ const names = unobserved.map((reason) => `\`${reason}\``).join(', ');
163
+ return (`- **unobserved classes**: ${names} — these classes had NO events in this scope, so the ` +
164
+ 'rate above does not measure them. A zero over an unobserved class is an absence of data, ' +
165
+ 'not a result.');
166
+ }
167
+ /**
168
+ * The table of the slices the metric flagged, so the count has a referent.
169
+ *
170
+ * WHY EACH KEY CARRIES ITS STATE AT THE PASS MOMENT. "The check was
171
+ * unsatisfied" covers two materially different findings, and a reader has to
172
+ * be able to tell them apart:
173
+ *
174
+ * - `refused` — the check WAS running at the pass moment and said no. The
175
+ * gate was live, it fired, and the slice passed anyway.
176
+ * - `unattempted` — the check had NOT been run at the pass moment. The
177
+ * role that owns it had not yet attempted its transition.
178
+ *
179
+ * On this repository's recorded history one of the twelve findings is the
180
+ * first and eleven are the second — and the second is the more alarming of
181
+ * the two, because it means the pass was declared before the owning role had
182
+ * even tried. A table that said only "unsatisfied" would hide which of the
183
+ * two a reader is looking at.
184
+ */
185
+ function flaggedSlices(nearMiss) {
186
+ const lines = [];
187
+ lines.push('### Flagged slices');
188
+ lines.push('');
189
+ if (nearMiss.records.length === 0) {
190
+ lines.push('_No slice passed with a required check still unsatisfied._');
191
+ lines.push('');
192
+ return lines.join('\n');
193
+ }
194
+ lines.push('| slice | reasons | passed at | unsatisfied checks |');
195
+ lines.push('|---|---|---|---|');
196
+ for (const record of nearMiss.records) {
197
+ const checks = record.unsatisfiedKeys.length === 0
198
+ ? '—'
199
+ : record.unsatisfiedKeys.map((entry) => `${entry.key} (${entry.state})`).join(', ');
200
+ lines.push(`| ${record.sliceRid} | ${record.reasons.join(', ')} | ${record.passMoment.ts} | ${checks} |`);
201
+ }
202
+ lines.push('');
203
+ lines.push('_`refused` — the check was running at the pass moment and said no. ' +
204
+ '`unattempted` — the check had not been run at the pass moment at all, so the owning ' +
205
+ 'role had not yet attempted its transition._');
206
+ lines.push('');
207
+ return lines.join('\n');
208
+ }
209
+ /**
210
+ * The markdown for the near-miss section, including its heading.
211
+ *
212
+ * The section is rendered ONLY when the caller supplies the measurement, so a
213
+ * caller that does not compute it gets exactly the report it got before.
214
+ */
215
+ export function markdownNearMissSection(nearMiss) {
216
+ const lines = [];
217
+ lines.push('## Near-misses');
218
+ lines.push('');
219
+ lines.push(rateLine(nearMiss));
220
+ lines.push(denominatorLine(nearMiss));
221
+ lines.push(statusLine(nearMiss));
222
+ lines.push(...undeterminedLines(nearMiss));
223
+ lines.push(...unmeasuredLines(nearMiss));
224
+ if (nearMiss.denominator.difference !== null) {
225
+ lines.push('');
226
+ lines.push(nearMiss.denominator.difference.note);
227
+ }
228
+ lines.push('');
229
+ lines.push(coverageTable(nearMiss.coverage));
230
+ lines.push(unobservedLine(nearMiss));
231
+ lines.push('');
232
+ lines.push(flaggedSlices(nearMiss));
233
+ return lines.join('\n');
234
+ }
@@ -6,13 +6,20 @@
6
6
  * entries. The CLI subcommand `peaks observability report` wires
7
7
  * the file read + aggregation + format pipeline.
8
8
  *
9
- * - Header: scope, period, generated-at timestamp
10
- * - Slice table: rid | transitions | finalState | durationMs | success
9
+ * - Header: scope, period, generated-at timestamp, and any warning the
10
+ * scope or the period raised — the warning travels IN the body, because
11
+ * the body is what gets pasted and the stderr line is what gets lost
12
+ * - Near-miss section: rate | denominator | coverage | flagged slices
13
+ * - Slice table: rid | transitions | final state | duration | outcome
14
+ * - Hotspots table: artifact | owner | mode | confidence | count
11
15
  * - Fanout table: role | count
12
16
  * - Repair-cycle table: sliceRid | cycleCount
13
- * - Top-N slowest slices: same as slice table, sorted by durationMs desc
17
+ * - Top-N slowest slices: rid | duration | transitions | final state,
18
+ * sorted by duration desc
14
19
  */
15
20
  import { type FanoutBreakdown, type Period, type RepairCycleReport, type SliceRollup, type StatusAggregate } from './aggregation.js';
21
+ import type { HotspotRow } from './hotspot-shared.js';
22
+ import type { NearMissReport } from './near-miss.js';
16
23
  export type ReportInput = {
17
24
  scope: 'session' | 'all-sessions';
18
25
  scopeId: string;
@@ -22,6 +29,45 @@ export type ReportInput = {
22
29
  slices: SliceRollup[];
23
30
  fanout: FanoutBreakdown;
24
31
  repairCycles: RepairCycleReport;
32
+ /**
33
+ * The warnings the scope or the period raised, rendered in the header.
34
+ *
35
+ * They are the reader's answer to "why is this table empty?" — a report
36
+ * scoped to one session, or narrowed to a period that holds no events,
37
+ * would otherwise show an empty table with no explanation. Printed to
38
+ * stderr they are lost the moment the report is pasted somewhere else, so
39
+ * the body carries them.
40
+ */
41
+ warnings?: readonly string[];
42
+ /**
43
+ * The near-miss measurement, rendered when it is supplied.
44
+ *
45
+ * It is OPTIONAL, and absent means the section is not rendered at all — a
46
+ * caller that does not compute the measurement gets exactly the report it
47
+ * got before the section existed.
48
+ *
49
+ * THE SECTION NEVER PRINTS A BARE RATE. A rate over a reason class the
50
+ * scope had no events for is an absence of data, not a result, so the
51
+ * section carries the per-class coverage beside the number: which classes
52
+ * were observable, which were not, and that the unobserved ones are not
53
+ * measured. The section lives in `report-formatter-near-miss.ts` — this
54
+ * file was near its cap — and the reasoning is explained there.
55
+ */
56
+ nearMiss?: NearMissReport;
57
+ /**
58
+ * The hotspot ranking, rendered when it is supplied.
59
+ *
60
+ * It is OPTIONAL, and absent means the section is not rendered at all — a
61
+ * caller that does not compute the ranking gets exactly the report it got
62
+ * before the ranking existed.
63
+ *
64
+ * THE SHAPE IS SET HERE, THE WIRING IS TASK 7's. The count column is
65
+ * named for what it counts — "times observed missing" and "candidate
66
+ * mentions" — so a reader cannot take a candidate mention for a missing
67
+ * artifact. The CLI command that supplies the ranking is Task 7's to
68
+ * wire; this file states the contract it will fill.
69
+ */
70
+ hotspots?: readonly HotspotRow[];
25
71
  };
26
72
  declare function pad(value: string | number, width: number): string;
27
73
  declare function formatDurationMs(ms: number | null): string;
@@ -6,13 +6,20 @@
6
6
  * entries. The CLI subcommand `peaks observability report` wires
7
7
  * the file read + aggregation + format pipeline.
8
8
  *
9
- * - Header: scope, period, generated-at timestamp
10
- * - Slice table: rid | transitions | finalState | durationMs | success
9
+ * - Header: scope, period, generated-at timestamp, and any warning the
10
+ * scope or the period raised — the warning travels IN the body, because
11
+ * the body is what gets pasted and the stderr line is what gets lost
12
+ * - Near-miss section: rate | denominator | coverage | flagged slices
13
+ * - Slice table: rid | transitions | final state | duration | outcome
14
+ * - Hotspots table: artifact | owner | mode | confidence | count
11
15
  * - Fanout table: role | count
12
16
  * - Repair-cycle table: sliceRid | cycleCount
13
- * - Top-N slowest slices: same as slice table, sorted by durationMs desc
17
+ * - Top-N slowest slices: rid | duration | transitions | final state,
18
+ * sorted by duration desc
14
19
  */
15
- import { REPAIR_CYCLE_METRIC_VERSION } from './aggregation.js';
20
+ import { REPAIR_CYCLE_METRIC_VERSION, sliceOutcome } from './aggregation.js';
21
+ import { markdownHotspotTables } from './report-formatter-hotspots.js';
22
+ import { markdownNearMissSection } from './report-formatter-near-miss.js';
16
23
  const SLOWEST_TOP_N = 5;
17
24
  function pad(value, width) {
18
25
  const str = String(value);
@@ -35,6 +42,12 @@ function markdownHeader(input) {
35
42
  lines.push(`- **period**: ${input.period}`);
36
43
  lines.push(`- **generated at**: ${input.generatedAt}`);
37
44
  lines.push(`- **scope marker**: from v2.11.1 install date (no backfill per PRD Q5)`);
45
+ const warnings = input.warnings ?? [];
46
+ if (warnings.length > 0) {
47
+ lines.push('');
48
+ for (const warning of warnings)
49
+ lines.push(`> **warning**: ${warning}`);
50
+ }
38
51
  lines.push('');
39
52
  return lines.join('\n');
40
53
  }
@@ -48,11 +61,26 @@ function markdownStatusSummary(status) {
48
61
  lines.push(`| total slices | ${status.totalSlices} |`);
49
62
  lines.push(`| success count | ${status.successCount} |`);
50
63
  lines.push(`| fail count | ${status.failCount} |`);
64
+ lines.push(`| stalled count | ${status.stalledCount} |`);
51
65
  lines.push(`| repair-cycle peak (v${REPAIR_CYCLE_METRIC_VERSION} metric) | ${status.repairCyclePeak} |`);
52
66
  lines.push(`| fanout cost total | ${status.fanoutCostTotal} |`);
53
67
  lines.push('');
54
68
  return lines.join('\n');
55
69
  }
70
+ /**
71
+ * The marker each outcome is drawn with in the slice table.
72
+ *
73
+ * A stalled slice is NOT a failure: it advanced partway and stopped, and
74
+ * drawing it `✗` is what put the "8 failures" into a report whose own summary
75
+ * counted 0 — the two halves of one report disagreeing about the same slices.
76
+ * `…` says "did not finish" and leaves the failure marker for the slices that
77
+ * really were blocked.
78
+ */
79
+ const OUTCOME_MARKERS = {
80
+ success: '✓',
81
+ failed: '✗',
82
+ stalled: '…'
83
+ };
56
84
  function markdownSliceTable(slices) {
57
85
  const lines = [];
58
86
  lines.push('## Slices');
@@ -62,14 +90,22 @@ function markdownSliceTable(slices) {
62
90
  lines.push('');
63
91
  return lines.join('\n');
64
92
  }
65
- lines.push('| rid | transitions | final state | duration | success |');
93
+ lines.push('| rid | transitions | final state | duration | outcome |');
66
94
  lines.push('|---|---|---|---|---|');
67
95
  for (const slice of slices) {
68
- lines.push(`| ${slice.sliceRid} | ${slice.transitions} | ${slice.finalState ?? '—'} | ${formatDurationMs(slice.durationMs)} | ${slice.success ? '✓' : '✗'} |`);
96
+ lines.push(`| ${slice.sliceRid} | ${slice.transitions} | ${slice.finalState ?? '—'} | ${formatDurationMs(slice.durationMs)} | ${OUTCOME_MARKERS[sliceOutcome(slice)]} |`);
69
97
  }
70
98
  lines.push('');
99
+ lines.push('_✓ succeeded · ✗ failed · … did not finish (stalled)_');
100
+ lines.push('');
71
101
  return lines.join('\n');
72
102
  }
103
+ /**
104
+ * The hotspot section: the rows, split by what their count actually counts.
105
+ *
106
+ * The section lives in `report-formatter-hotspots.ts` — this file was near
107
+ * its cap — and the split of the tables is explained there.
108
+ */
73
109
  function markdownFanoutTable(fanout) {
74
110
  const lines = [];
75
111
  lines.push('## Fanout');
@@ -148,14 +184,19 @@ function markdownSlowestSlices(slices) {
148
184
  * layer reads events, calls aggregations, and passes the result here.
149
185
  */
150
186
  export function renderObservabilityReport(input) {
151
- const sections = [
152
- markdownHeader(input),
153
- markdownStatusSummary(input.status),
154
- markdownSliceTable(input.slices),
155
- markdownFanoutTable(input.fanout),
156
- markdownRepairCycleTable(input.repairCycles),
157
- markdownSlowestSlices(input.slices)
158
- ];
187
+ const sections = [markdownHeader(input), markdownStatusSummary(input.status)];
188
+ // The near-miss section is rendered ONLY when the measurement is supplied,
189
+ // so a caller that does not compute it gets exactly the report it got
190
+ // before. It sits between the summary and the slice table: the summary
191
+ // says what the slices did, the near-misses say what was skipped.
192
+ if (input.nearMiss !== undefined)
193
+ sections.push(markdownNearMissSection(input.nearMiss));
194
+ sections.push(markdownSliceTable(input.slices));
195
+ // The hotspot section is rendered ONLY when the ranking is supplied, so a
196
+ // caller that does not compute it gets exactly the report it got before.
197
+ if (input.hotspots !== undefined)
198
+ sections.push(markdownHotspotTables(input.hotspots));
199
+ sections.push(markdownFanoutTable(input.fanout), markdownRepairCycleTable(input.repairCycles), markdownSlowestSlices(input.slices));
159
200
  return sections.join('\n').trimEnd() + '\n';
160
201
  }
161
202
  export const REPORT_FORMAT_CONSTANTS = {
@@ -0,0 +1,129 @@
1
+ /**
2
+ * `src/services/observability/retro-attribution.ts`
3
+ *
4
+ * Retro-attribution: name the artifacts behind the historical failures that
5
+ * recorded only a COUNT.
6
+ *
7
+ * WHY THIS EXISTS. Every slice-transition event carries `detail.missingCount`.
8
+ * The v1 events in this repository's own event log were written before the
9
+ * emitter kept the missing-artifact LIST, so the list they name is not in the
10
+ * record, and no amount of reading the record will produce it.
11
+ *
12
+ * WHAT CAN BE DERIVED INSTEAD. The prerequisite table is a pure function of
13
+ * three values — the artifact role, the target state and the request type —
14
+ * and a v1 event carries the first two. Re-deriving the table for that
15
+ * transition yields the CANDIDATE set: the artifacts the missing entries could
16
+ * be. The recorded count then says how many artifacts were missing in total,
17
+ * which is what decides whether the candidates can be narrowed.
18
+ *
19
+ * WHY THE CONFIDENCE IS CAPPED AT `inferred`. The derivation runs over
20
+ * TODAY's prerequisite table, and the table is version-controlled code that
21
+ * changes between two recorded events. A retro-attribution is therefore a
22
+ * reconstruction, not a measurement, so `exact` — which means "observed when
23
+ * it happened" — is never returned here. Only a forward event that stored the
24
+ * missing list as it was observed can carry it.
25
+ *
26
+ * WHY A COUNT MAY EXCEED THE TABLE. The recorded count is not the table's row
27
+ * count: the missing list is also fed by the judged-declaration refusals (the
28
+ * security artifact's own location) and by the handoff capsule's gate-evidence
29
+ * declaration (a key naming a file that is not on disk). Neither of those two
30
+ * sources is derivable from what a v1 event stores, so a count larger than
31
+ * the table's list yields `ambiguous` with the table's entries as the
32
+ * candidates. The candidate set is never widened with a guess, and the
33
+ * confidence never rises to cover the gap.
34
+ */
35
+ import { type RequestType } from '../artifacts/artifact-prerequisites.js';
36
+ import type { RequestArtifactRole } from '../artifacts/artifact-templates.js';
37
+ import type { RequestTypeSource } from '../artifacts/request-artifact-metadata.js';
38
+ import type { RequestArtifactState } from '../artifacts/request-artifact-state-helpers.js';
39
+ /**
40
+ * How far an attribution can be trusted.
41
+ *
42
+ * - `exact` — the missing list was measured when the event was recorded.
43
+ * Only a forward event carries it; the retro-attribution never does.
44
+ * - `inferred` — the recorded count is CONSISTENT WITH the whole candidate
45
+ * list being the missing set. It is not proof, and it must not be read as
46
+ * proof: the missing list has three sources (the prereq table, the
47
+ * judged-declaration refusals, the gate-evidence declaration), so a count
48
+ * equal to the table's length can match by coincidence while the missing
49
+ * entries came from the other two. `inferred` says "the count does not
50
+ * contradict this set", never "these artifacts were proven missing".
51
+ * - `ambiguous` — the count cannot single out any subset, so the candidate
52
+ * set stays the whole prereq list. An EMPTY candidate set means "nothing
53
+ * derivable" — distinguishable from "ambiguous among N" by
54
+ * `candidates.length === 0`, and it is the shape a transition the table
55
+ * holds nothing for produces.
56
+ */
57
+ export type AttributionConfidence = 'exact' | 'inferred' | 'ambiguous';
58
+ /**
59
+ * One attribution: how far it can be trusted, and the artifacts it can name.
60
+ *
61
+ * The candidates are a CANDIDATE list: the prereq paths of the transition,
62
+ * each paired with the skill that owns it. They name the artifacts the missing
63
+ * entries could be — not the artifacts that were proven missing, which only a
64
+ * forward event records. `ownerSkill` is `null` when no skill owns the path —
65
+ * a stated absence, not a missing field.
66
+ *
67
+ * `typeSource` says where the type that produced these candidates came from.
68
+ * The CANDIDATES are the same either way — the effective type is the type the
69
+ * prerequisite table was indexed by — but a reader asking "how many of these
70
+ * attributions rested on a type nobody wrote down?" cannot answer it unless
71
+ * the source travels with the attribution.
72
+ */
73
+ export type RetroAttribution = {
74
+ readonly confidence: AttributionConfidence;
75
+ readonly candidates: ReadonlyArray<{
76
+ path: string;
77
+ ownerSkill: string | null;
78
+ }>;
79
+ /** Whether the type that produced these candidates was DECLARED or defaulted. */
80
+ readonly typeSource: RequestTypeSource;
81
+ };
82
+ /** The inputs one historical failure carries, all of them derivable. */
83
+ export type RetroAttributionInput = {
84
+ /** The role of the artifact that was moving — the event's `detail.artifactRole`. */
85
+ readonly artifactRole: RequestArtifactRole;
86
+ /** The state it was moving to — the event's `detail.to`. */
87
+ readonly newState: RequestArtifactState;
88
+ /** The request's EFFECTIVE type — read from the artifact, or the default. */
89
+ readonly requestType: RequestType;
90
+ /** Where that type came from: declared on the `- type:` line, or defaulted. */
91
+ readonly typeSource: RequestTypeSource;
92
+ /** How many artifacts the event recorded as missing. */
93
+ readonly missingCount: number;
94
+ };
95
+ /**
96
+ * Attribute one historical failure to the artifacts that could have been
97
+ * missing.
98
+ *
99
+ * The rules, in the order they apply:
100
+ *
101
+ * - a transition the table demands nothing for → `ambiguous`, no candidate;
102
+ * - a count that cannot be read → `ambiguous`, the whole list as candidates;
103
+ * - a count of zero → `ambiguous`, no candidate (the record says nothing
104
+ * was missing, so naming a candidate would contradict it);
105
+ * - a count equal to the list's length → `inferred`, the whole list;
106
+ * - any other count → `ambiguous`, the whole list as candidates.
107
+ *
108
+ * WHAT `inferred` CLAIMS AT THE THIRD RULE. The count matches the table's
109
+ * length, so the count is CONSISTENT WITH the whole list being the missing
110
+ * set — and it is not proof of that. The missing list has three sources (the
111
+ * prereq table, the judged-declaration refusals, the gate-evidence
112
+ * declaration), and a count equal to the table's length can match by
113
+ * coincidence while the missing entries came from the other two, leaving a
114
+ * table entry intact. The same holds for a one-entry list and a count of one:
115
+ * the single missing entry may have come from source two or three. So the
116
+ * label says "the count does not contradict this set", and never "these
117
+ * artifacts were proven missing".
118
+ *
119
+ * The last rule covers a count of one against a list of several, a count
120
+ * between zero and the list's length, and a count ABOVE the list's length —
121
+ * the last because the missing list has two further sources the table does
122
+ * not describe, and neither of them is derivable from a v1 event.
123
+ *
124
+ * This function never returns `exact`. That confidence belongs to a forward
125
+ * event, which recorded the missing list as it was observed; this one
126
+ * reconstructs a candidate set from today's table and can therefore only
127
+ * claim `inferred` or `ambiguous`.
128
+ */
129
+ export declare function attributeV1Failure(opts: RetroAttributionInput): RetroAttribution;