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
@@ -5,7 +5,7 @@ import { printResult } from '../cli-helpers.js';
5
5
  import { detectIdeFromContext, pluckObject, pluckString } from '../../services/ide/hook-translator.js';
6
6
  import { DISPATCH_PROVENANCE_ENV } from '../../services/worktree/dispatch-provenance.js';
7
7
  import { getAdapter } from '../../services/ide/ide-registry.js';
8
- import { emitBlock, emitDecision, emitHint } from '../../services/hooks/output.js';
8
+ import { emitBlock, emitDecision, emitHint, buildAllowDocument } from '../../services/hooks/output.js';
9
9
  /**
10
10
  * Parse the raw stdin payload, failing open to `null` on malformed JSON.
11
11
  */
@@ -135,13 +135,22 @@ export function handleWorktreeGate(io, options, toolKind, payload) {
135
135
  return false;
136
136
  }
137
137
  /**
138
- * Not a guarded surface — allow. Emit minimal JSON on stdout so Claude Code's PreToolUse hook
139
- * validator accepts the response. Empty stdout is rejected with "Hook JSON output validation
140
- * failed — Invalid input" in Claude Code 2.x; `{}` is the canonical no-op marker.
138
+ * Not a guarded surface — allow.
139
+ *
140
+ * In `--json` mode the stdout document is the CLI envelope with the Claude
141
+ * Code allow decision MERGED into it, so stdout stays ONE JSON document: the
142
+ * host parses it once and reads the decision out of `hookSpecificOutput`,
143
+ * while a downstream consumer still reads `JSON.parse(stdout).data.decision`.
144
+ *
145
+ * The envelope's own `data.decision` stays `allow` — it is nested under
146
+ * `data`, a key the host does not own, so the host reads no root `decision`
147
+ * at all. (The root `decision` key IS one the host owns, and it accepts only
148
+ * "approve" | "block" — a root `decision` of anything else is what produced
149
+ * the user's per-call "Invalid option" error.)
141
150
  */
142
151
  export function emitAllowSkipped(io, options) {
143
152
  if (options.json === true) {
144
- printResult(io, ok('gate.enforce', { decision: 'allow', skipped: true }), true);
153
+ printResult(io, buildAllowDocument(ok('gate.enforce', { decision: 'allow', skipped: true })), true);
145
154
  }
146
155
  else {
147
156
  emitDecision(io, {});
@@ -159,10 +168,14 @@ function emitWorktreeDeny(io, options, wtDecision) {
159
168
  emitHint(io, JSON.stringify(ok('gate.enforce', { decision: 'deny', layer: 'worktree-auth', ...wtDecision })));
160
169
  }
161
170
  }
162
- /** Worktree gate allowed and this is not a Bash surface — allow without running the SOP gate. */
171
+ /**
172
+ * Worktree gate allowed and this is not a Bash surface — allow without running
173
+ * the SOP gate. Same one-document shape as the skipped path (see
174
+ * {@link emitAllowSkipped} for why the decision is merged into the envelope).
175
+ */
163
176
  export function emitAllowWorktree(io, options) {
164
177
  if (options.json === true) {
165
- printResult(io, ok('gate.enforce', { decision: 'allow', layer: 'worktree-auth' }), true);
178
+ printResult(io, buildAllowDocument(ok('gate.enforce', { decision: 'allow', layer: 'worktree-auth' })), true);
166
179
  }
167
180
  else {
168
181
  emitDecision(io, {});
@@ -189,14 +202,16 @@ export function emitSopWarnings(io, decision) {
189
202
  }
190
203
  }
191
204
  /**
192
- * SOP gate allowed the command. --json mode emits the canonical envelope on stdout (the documented
193
- * contract for downstream tooling). The hook decision (allow/deny) is still signalled via
194
- * emitHint here was wrong — emitHint writes to stderr, but the AC5 contract expects the JSON
195
- * envelope on stdout. Switch to printResult(asJson=true).
205
+ * SOP gate allowed the command.
206
+ *
207
+ * `--json` mode emits the canonical envelope on stdout (the documented
208
+ * contract for downstream tooling) with the Claude Code allow decision merged
209
+ * into it, so stdout stays ONE JSON document the host can parse — see
210
+ * {@link emitAllowSkipped} for the shape and the reason.
196
211
  */
197
212
  export function emitSopAllow(io, options, decision) {
198
213
  if (options.json === true) {
199
- printResult(io, ok('gate.enforce', decision), true);
214
+ printResult(io, buildAllowDocument(ok('gate.enforce', decision)), true);
200
215
  }
201
216
  else {
202
217
  // allow: emit minimal JSON on stdout so Claude Code's PreToolUse hook
@@ -0,0 +1,54 @@
1
+ /**
2
+ * `src/cli/commands/observability-commands-hotspots.ts`
3
+ *
4
+ * `peaks observability hotspots` — which artifact does a skill keep failing
5
+ * to deliver, and who owns it.
6
+ *
7
+ * WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
8
+ * That file is at its file-size cap and a later task needs room in it too,
9
+ * so each subcommand's registration lives in its own module and the parent
10
+ * gains one import and one call. The precedent is the sibling split of
11
+ * `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
12
+ *
13
+ * WHY THE REQUEST TYPES ARE RESOLVED HERE. The retro-attribution re-derives
14
+ * a transition's prerequisite list, and the table is indexed by request type —
15
+ * a fact that lives in the request artifact, not in the event stream. The
16
+ * events carry the slice; the request artifact carries the type. So this
17
+ * layer reads the request artifacts and hands the types to the ranking.
18
+ *
19
+ * WHY THE READER IS THE CANONICAL ONE. The `- type:` line is parsed by the
20
+ * repository's own metadata reader, so a value this command accepts is a
21
+ * value the rest of the pipeline accepts. A type line this command does not
22
+ * understand is left unresolved, and its slice contributes no retro-attributed
23
+ * row — reported as a warning, never as a silent omission.
24
+ */
25
+ import type { Command } from 'commander';
26
+ import { type RequestTypeReading } from '../../services/observability/hotspot-shared.js';
27
+ import type { ObservabilityEvent } from '../../services/observability/observability-service.js';
28
+ import { type ProgramIO } from '../cli-helpers.js';
29
+ import { type ObservabilityQueryOptions } from './observability-commands-queries.js';
30
+ /**
31
+ * The request types of the slices in the scope, keyed by slice rid.
32
+ *
33
+ * The retro-attribution re-derives a transition's prerequisite list from the
34
+ * request type, and the type lives in the request artifact rather than in the
35
+ * event stream — so a caller that wants the HISTORICAL rows has to resolve
36
+ * the types itself. Without them the ranking holds only the forward events,
37
+ * and on a history that predates the forward emitter it holds NOTHING, which
38
+ * would read as "no hotspot" rather than as "no history".
39
+ *
40
+ * ONE IMPLEMENTATION, TWO CALLERS. The `hotspots` command and the `report`
41
+ * command both need the types, and a second copy of the lookup is a copy that
42
+ * drifts — so both go through this function.
43
+ */
44
+ export declare function hotspotRequestTypes(projectRoot: string, events: readonly ObservabilityEvent[]): {
45
+ readonly requestTypes: Map<string, RequestTypeReading>;
46
+ readonly unreadable: number;
47
+ readonly defaulted: number;
48
+ };
49
+ /**
50
+ * `peaks observability hotspots` — print the hotspot ranking.
51
+ */
52
+ export declare function runHotspots(io: ProgramIO, options: ObservabilityQueryOptions): void;
53
+ /** Register `peaks observability hotspots` under the observability command. */
54
+ export declare function registerHotspotsCommand(observability: Command, io: ProgramIO): void;
@@ -0,0 +1,222 @@
1
+ /**
2
+ * `src/cli/commands/observability-commands-hotspots.ts`
3
+ *
4
+ * `peaks observability hotspots` — which artifact does a skill keep failing
5
+ * to deliver, and who owns it.
6
+ *
7
+ * WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
8
+ * That file is at its file-size cap and a later task needs room in it too,
9
+ * so each subcommand's registration lives in its own module and the parent
10
+ * gains one import and one call. The precedent is the sibling split of
11
+ * `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
12
+ *
13
+ * WHY THE REQUEST TYPES ARE RESOLVED HERE. The retro-attribution re-derives
14
+ * a transition's prerequisite list, and the table is indexed by request type —
15
+ * a fact that lives in the request artifact, not in the event stream. The
16
+ * events carry the slice; the request artifact carries the type. So this
17
+ * layer reads the request artifacts and hands the types to the ranking.
18
+ *
19
+ * WHY THE READER IS THE CANONICAL ONE. The `- type:` line is parsed by the
20
+ * repository's own metadata reader, so a value this command accepts is a
21
+ * value the rest of the pipeline accepts. A type line this command does not
22
+ * understand is left unresolved, and its slice contributes no retro-attributed
23
+ * row — reported as a warning, never as a silent omission.
24
+ */
25
+ import { readFileSync, readdirSync } from 'node:fs';
26
+ import { join } from 'node:path';
27
+ import { fail, ok } from 'peaks-loop-shared/result';
28
+ import { isRequestType } from '../../services/artifacts/artifact-prerequisites.js';
29
+ import { extractMetadata } from '../../services/artifacts/request-artifact-metadata.js';
30
+ import { guardRuntimeSegment, runtimeRoot } from '../../shared/runtime-root.js';
31
+ import { slugifyDescription } from '../../shared/incrementing-number.js';
32
+ import { aggregateHotspots } from '../../services/observability/hotspots.js';
33
+ import { summarizeAttribution } from '../../services/observability/hotspot-attribution-summary.js';
34
+ import { groupHotspotsByMeaning } from '../../services/observability/hotspot-shared.js';
35
+ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
36
+ import { readScopedEvents, resolveProjectRoot, scopeOf, scopeWarnings } from './observability-commands-queries.js';
37
+ /** The request artifact roles a request type can be read from. */
38
+ const REQUEST_ROLES = ['prd', 'ui', 'rd', 'qa', 'sc'];
39
+ /**
40
+ * The request type of every request artifact under the project, AND where each
41
+ * type came from.
42
+ *
43
+ * The map is keyed by the request's SLUG — the same form the artifact's
44
+ * filename carries — because that is the only spelling shared by the file
45
+ * on disk and the request id in the event stream.
46
+ *
47
+ * WHY THE SOURCE RIDES ALONG WITH THE TYPE. An artifact that declares no
48
+ * usable `- type:` line still has an EFFECTIVE type — the system's default —
49
+ * and that is the type the prerequisite table was indexed by when the
50
+ * transition ran, so the attribution must use it. But the effective type and
51
+ * the fact that NOBODY WROTE IT DOWN are two different facts, and a reader
52
+ * asking "how many of these attributions rested on a type nobody wrote
53
+ * down?" cannot answer it if the reader throws the second fact away.
54
+ *
55
+ * THE TWO BUCKETS ARE NOT THE SAME BUCKET. `unreadable` counts artifacts
56
+ * that could not be READ — their type is unknown, so their slice contributes
57
+ * no retro-attributed row at all. `defaulted` counts artifacts that read
58
+ * fine but carry no usable type line: their slice DOES contribute a row,
59
+ * attributed against the default. Conflating them would report a type nobody
60
+ * wrote down as a type nobody could supply.
61
+ *
62
+ * WHY A DECLARED READING WINS OVER A DEFAULTED ONE FOR THE SAME SLUG. A
63
+ * request's artifact is written once per role, and one role's copy may carry
64
+ * a type line while another's does not. The declared line is the stronger
65
+ * fact — it is what a human wrote — so it is the one that names the type.
66
+ */
67
+ function readRequestTypes(projectRoot) {
68
+ const bySlug = new Map();
69
+ const counts = { unreadable: 0, defaulted: 0 };
70
+ const runtime = runtimeRoot(projectRoot);
71
+ let sessions;
72
+ try {
73
+ sessions = readdirSync(runtime.dir(), { withFileTypes: true })
74
+ .filter((entry) => entry.isDirectory())
75
+ .map((entry) => entry.name);
76
+ }
77
+ catch {
78
+ return { bySlug, unreadable: counts.unreadable, defaulted: counts.defaulted };
79
+ }
80
+ for (const session of sessions) {
81
+ for (const role of REQUEST_ROLES) {
82
+ const dir = join(runtime.join(guardRuntimeSegment(session, 'session id'), guardRuntimeSegment(role, 'role'), guardRuntimeSegment('requests', 'leaf')));
83
+ let files;
84
+ try {
85
+ files = readdirSync(dir).filter((name) => name.endsWith('.md'));
86
+ }
87
+ catch {
88
+ continue;
89
+ }
90
+ for (const file of files) {
91
+ readOneRequestArtifact(dir, file, bySlug, counts);
92
+ }
93
+ }
94
+ }
95
+ return { bySlug, unreadable: counts.unreadable, defaulted: counts.defaulted };
96
+ }
97
+ /**
98
+ * Read ONE request artifact and fold it into the slug map.
99
+ *
100
+ * WHY IT IS ITS OWN FUNCTION. The reader walks every artifact of every
101
+ * session and role, and the three facts it collects — the reading, the
102
+ * unreadable count, the no-type-line count — are counted as it goes. Folding
103
+ * one artifact's handling into its own function keeps each step readable and
104
+ * keeps the reader's size under the cap.
105
+ *
106
+ * THE COUNTING RULES. An artifact that cannot be READ is `unreadable` — its
107
+ * slice's type is unknown, so nothing can be attributed to it. An artifact
108
+ * that reads but whose type line is unusable is `defaulted` — its slice still
109
+ * gets the default type, and the attribution is real but its provenance is
110
+ * not. The two are different facts and they do not share a bucket.
111
+ */
112
+ function readOneRequestArtifact(dir, file, bySlug, counts) {
113
+ let markdown;
114
+ try {
115
+ markdown = readFileSync(join(dir, file), 'utf8');
116
+ }
117
+ catch {
118
+ counts.unreadable += 1;
119
+ return;
120
+ }
121
+ const { requestType, requestTypeSource } = extractMetadata(markdown);
122
+ if (!isRequestType(requestType)) {
123
+ counts.unreadable += 1;
124
+ return;
125
+ }
126
+ if (requestTypeSource === 'default')
127
+ counts.defaulted += 1;
128
+ const slug = file.replace(/^\d{3}-/, '').replace(/\.md$/, '');
129
+ const existing = bySlug.get(slug);
130
+ if (existing === undefined || existing.source === 'default') {
131
+ bySlug.set(slug, { requestType, source: requestTypeSource });
132
+ }
133
+ }
134
+ /**
135
+ * The request types of the slices in the scope, keyed by slice rid.
136
+ *
137
+ * The retro-attribution re-derives a transition's prerequisite list from the
138
+ * request type, and the type lives in the request artifact rather than in the
139
+ * event stream — so a caller that wants the HISTORICAL rows has to resolve
140
+ * the types itself. Without them the ranking holds only the forward events,
141
+ * and on a history that predates the forward emitter it holds NOTHING, which
142
+ * would read as "no hotspot" rather than as "no history".
143
+ *
144
+ * ONE IMPLEMENTATION, TWO CALLERS. The `hotspots` command and the `report`
145
+ * command both need the types, and a second copy of the lookup is a copy that
146
+ * drifts — so both go through this function.
147
+ */
148
+ export function hotspotRequestTypes(projectRoot, events) {
149
+ const { bySlug, unreadable, defaulted } = readRequestTypes(projectRoot);
150
+ const requestTypes = new Map();
151
+ for (const event of events) {
152
+ const rid = event.sliceRid;
153
+ if (rid === undefined)
154
+ continue;
155
+ const reading = bySlug.get(slugifyDescription(rid));
156
+ if (reading !== undefined && !requestTypes.has(rid))
157
+ requestTypes.set(rid, reading);
158
+ }
159
+ return { requestTypes, unreadable, defaulted };
160
+ }
161
+ /**
162
+ * What the reader found while it read the request artifacts, said plainly.
163
+ *
164
+ * WHY THE TWO FACTS ARE TWO WARNINGS. An artifact that could not be READ
165
+ * leaves its slice with no type at all, so nothing is attributed to it — that
166
+ * is a GAP. An artifact that read fine but carried no usable type line leaves
167
+ * its slice with the DEFAULT type, so an attribution IS produced, and only its
168
+ * PROVENANCE is weak. One warning per fact, so a reader can tell which
169
+ * happened without reading the code.
170
+ */
171
+ function requestTypeWarnings(unreadable, defaulted) {
172
+ const warnings = [];
173
+ if (unreadable > 0) {
174
+ warnings.push(`${unreadable} request artifact(s) could not be read, so the slices they belong to have ` +
175
+ 'no known request type and contribute no retro-attributed row.');
176
+ }
177
+ if (defaulted > 0) {
178
+ warnings.push(`${defaulted} request artifact(s) carry no usable \`- type:\` line, so their slices are ` +
179
+ 'attributed against the DEFAULT request type — a type nobody wrote down. The ' +
180
+ 'attribution is real; its provenance is not.');
181
+ }
182
+ return warnings;
183
+ }
184
+ /**
185
+ * `peaks observability hotspots` — print the hotspot ranking.
186
+ */
187
+ export function runHotspots(io, options) {
188
+ const projectRoot = resolveProjectRoot(options.project);
189
+ try {
190
+ const { sessionId, events } = readScopedEvents(projectRoot, options);
191
+ const { requestTypes, unreadable, defaulted } = hotspotRequestTypes(projectRoot, events);
192
+ const hotspots = aggregateHotspots(events, requestTypes);
193
+ const attribution = summarizeAttribution(events, requestTypes, {
194
+ unreadable,
195
+ withoutTypeLine: defaulted
196
+ });
197
+ const warnings = [
198
+ ...scopeWarnings(projectRoot, sessionId, events.length),
199
+ ...requestTypeWarnings(unreadable, defaulted)
200
+ ];
201
+ printResult(io, ok('observability.hotspots', {
202
+ scope: scopeOf(sessionId),
203
+ hotspots: groupHotspotsByMeaning(hotspots),
204
+ attribution
205
+ }, warnings), options.json);
206
+ }
207
+ catch (error) {
208
+ printResult(io, fail('observability.hotspots', 'OBSERVABILITY_HOTSPOTS_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
209
+ process.exitCode = 1;
210
+ }
211
+ }
212
+ /** Register `peaks observability hotspots` under the observability command. */
213
+ export function registerHotspotsCommand(observability, io) {
214
+ addJsonOption(observability
215
+ .command('hotspots')
216
+ .description('Hotspot ranking: which artifact a skill keeps failing to deliver, and who owns it. The rows are split by what their count COUNTS, so the group a row is in says what its number means: `observedOmissions` are MEASURED (the artifact was seen missing that many times) and `candidateMentions` are CANDIDATES recovered from a historical count (one real failure counts toward EVERY candidate it could not narrow, so those numbers are an upper bound, NOT a count of failures). Each row also carries its owner, artifact, mode and confidence; the confidence values are unchanged.')
217
+ .option('--project <path>', 'target project root (defaults to git root or cwd)')
218
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
219
+ .option('--all-sessions', 'measure the whole recorded history of the project instead of the canonical session binding')).action((options) => {
220
+ runHotspots(io, options);
221
+ });
222
+ }
@@ -0,0 +1,28 @@
1
+ /**
2
+ * `src/cli/commands/observability-commands-near-miss.ts`
3
+ *
4
+ * `peaks observability near-miss` — the headline number of the whole
5
+ * programme: of the slices that passed, how many passed anyway after a gate
6
+ * that was live never got evaluated?
7
+ *
8
+ * WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
9
+ * That file is at its file-size cap and a later task needs room in it too,
10
+ * so each subcommand's registration lives in its own module and the parent
11
+ * gains one import and one call. The precedent is the sibling split of
12
+ * `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
13
+ *
14
+ * WHY THE SCOPE BEHAVES LIKE THE OTHER QUERIES. The scope resolution, the
15
+ * `--all-sessions` escape and the empty-scope warning are the shared ones in
16
+ * `observability-commands-queries.ts`, so this command measures the same
17
+ * population its siblings report and says so the same way when it is empty.
18
+ */
19
+ import type { Command } from 'commander';
20
+ import { type ProgramIO } from '../cli-helpers.js';
21
+ import { type ObservabilityQueryOptions } from './observability-commands-queries.js';
22
+ /**
23
+ * `peaks observability near-miss` — print the near-miss rate and the list of
24
+ * slices it came from.
25
+ */
26
+ export declare function runNearMiss(io: ProgramIO, options: ObservabilityQueryOptions): void;
27
+ /** Register `peaks observability near-miss` under the observability command. */
28
+ export declare function registerNearMissCommand(observability: Command, io: ProgramIO): void;
@@ -0,0 +1,105 @@
1
+ /**
2
+ * `src/cli/commands/observability-commands-near-miss.ts`
3
+ *
4
+ * `peaks observability near-miss` — the headline number of the whole
5
+ * programme: of the slices that passed, how many passed anyway after a gate
6
+ * that was live never got evaluated?
7
+ *
8
+ * WHY THE REGISTRATION LIVES HERE AND NOT IN `observability-commands.ts`.
9
+ * That file is at its file-size cap and a later task needs room in it too,
10
+ * so each subcommand's registration lives in its own module and the parent
11
+ * gains one import and one call. The precedent is the sibling split of
12
+ * `observability-commands-queries.ts` and `observability-commands-baseline.ts`.
13
+ *
14
+ * WHY THE SCOPE BEHAVES LIKE THE OTHER QUERIES. The scope resolution, the
15
+ * `--all-sessions` escape and the empty-scope warning are the shared ones in
16
+ * `observability-commands-queries.ts`, so this command measures the same
17
+ * population its siblings report and says so the same way when it is empty.
18
+ */
19
+ import { fail, ok } from 'peaks-loop-shared/result';
20
+ import { computeNearMiss } from '../../services/observability/near-miss.js';
21
+ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
22
+ import { hotspotRequestTypes } from './observability-commands-hotspots.js';
23
+ import { readScopedEvents, resolveProjectRoot, scopeOf, scopeWarnings } from './observability-commands-queries.js';
24
+ /**
25
+ * The warning that says a reason class had no events to observe.
26
+ *
27
+ * A class with no events cannot produce a finding, so its share of the rate
28
+ * is an ABSENCE OF DATA. Saying nothing would let a reader take the rate for
29
+ * "no near-misses" when the truth is "this class was never looked at" — the
30
+ * exact misreading the metric exists to prevent.
31
+ */
32
+ function coverageWarnings(coverage) {
33
+ return coverage
34
+ .filter((item) => !item.observable)
35
+ .map((item) => `The \`${item.reason}\` class had NO events to observe in this scope ` +
36
+ `(${item.scopeEventCount} event(s)), so its share of the near-miss rate is an ` +
37
+ 'absence of data, not a result — the rate does not measure that class.');
38
+ }
39
+ /**
40
+ * The warning that says the denominator differs from the status summary's.
41
+ *
42
+ * "Passed" has two definitions in this repository and they do not count the
43
+ * same slices. A reader who sees one number and assumes it is the other's
44
+ * would be wrong, so the difference is stated rather than smoothed over.
45
+ */
46
+ function denominatorWarnings(denominator) {
47
+ if (denominator.difference === null)
48
+ return [];
49
+ return [denominator.difference.note];
50
+ }
51
+ /**
52
+ * The warning that says a slice could not be measured at all.
53
+ *
54
+ * A slice whose `verdict-issued` attempt records a prereq verdict this build
55
+ * cannot read is in neither the numerator nor the denominator, so a reader who
56
+ * adds up the slices finds one missing. Saying nothing would let them infer
57
+ * it was never there.
58
+ */
59
+ function unmeasuredWarnings(unmeasured) {
60
+ if (unmeasured.length === 0)
61
+ return [];
62
+ return [
63
+ `${unmeasured.length} slice(s) recorded a \`verdict-issued\` attempt whose prereq verdict this ` +
64
+ 'build cannot read, so whether they passed is unknown — they are in neither the numerator ' +
65
+ `nor the denominator: ${unmeasured.map((item) => `\`${item.sliceRid}\``).join(', ')}`
66
+ ];
67
+ }
68
+ /**
69
+ * `peaks observability near-miss` — print the near-miss rate and the list of
70
+ * slices it came from.
71
+ */
72
+ export function runNearMiss(io, options) {
73
+ const projectRoot = resolveProjectRoot(options.project);
74
+ try {
75
+ const { sessionId, events } = readScopedEvents(projectRoot, options);
76
+ // The request types let the denominator NAME the cause of the gap between
77
+ // the two "passed" definitions: the slices that reached a verdict with no
78
+ // recorded prereq verdict are the ones whose type has no
79
+ // `qa:verdict-issued` prerequisite row at all.
80
+ const { requestTypes } = hotspotRequestTypes(projectRoot, events);
81
+ const report = computeNearMiss(events, requestTypes);
82
+ const warnings = [
83
+ ...scopeWarnings(projectRoot, sessionId, events.length),
84
+ ...coverageWarnings(report.coverage),
85
+ ...denominatorWarnings(report.denominator),
86
+ ...unmeasuredWarnings(report.unmeasured)
87
+ ];
88
+ printResult(io, ok('observability.near-miss', { scope: scopeOf(sessionId), ...report }, warnings), options.json);
89
+ }
90
+ catch (error) {
91
+ printResult(io, fail('observability.near-miss', 'OBSERVABILITY_NEAR_MISS_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
92
+ process.exitCode = 1;
93
+ }
94
+ }
95
+ /** Register `peaks observability near-miss` under the observability command. */
96
+ export function registerNearMissCommand(observability, io) {
97
+ addJsonOption(observability
98
+ .command('near-miss')
99
+ .description('Near-miss rate: of the slices that were DECLARED PASSING (a `verdict-issued` attempt whose prereq check succeeded), how many passed anyway after a required check was still unsatisfied at that moment, or after a live gate never got evaluated? The `denominator` field states the definition and size of the population the rate divides by, and reconciles it with the status summary\'s success count — the two "passed" definitions do not count the same slices, and the difference is reported rather than smoothed over. The `coverage` field says, per reason class, whether that class had any events to observe: a class with none was not measured, so its share of the rate is an absence of data rather than a result.')
100
+ .option('--project <path>', 'target project root (defaults to git root or cwd)')
101
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
102
+ .option('--all-sessions', 'measure the whole recorded history of the project instead of the canonical session binding')).action((options) => {
103
+ runNearMiss(io, options);
104
+ });
105
+ }
@@ -15,28 +15,71 @@
15
15
  * LATER ADDITION — `peaks observability repair-cycles` also grew an
16
16
  * `--all-sessions` scope, so the whole recorded history of a project can be
17
17
  * measured from the command itself.
18
+ *
19
+ * TASK 4 — the same `--all-sessions` scope now reaches `status` / `slices` /
20
+ * `fanout` / `report`, and every scoped query says so when its scope holds no
21
+ * events while OTHER sessions hold some.
18
22
  */
23
+ import { readAllSessionEvents } from '../../services/observability/aggregation.js';
19
24
  import { type ProgramIO } from '../cli-helpers.js';
20
25
  export declare function resolveProjectRoot(optionProject: string | undefined): string;
21
- export declare function resolveSessionId(optionSession: string | undefined, projectRoot: string): string | undefined;
22
- export declare function runStatus(io: ProgramIO, options: {
23
- project?: string;
24
- session?: string;
25
- json?: boolean;
26
- }): void;
27
- export declare function runSlices(io: ProgramIO, options: {
28
- project?: string;
29
- session?: string;
30
- json?: boolean;
31
- }): void;
32
- export declare function runFanout(io: ProgramIO, options: {
33
- project?: string;
34
- session?: string;
35
- json?: boolean;
36
- }): void;
37
- export declare function runRepairCycles(io: ProgramIO, options: {
26
+ /**
27
+ * The options every read-only observability query accepts.
28
+ *
29
+ * `allSessions` widens the scope from the canonical session binding to the
30
+ * WHOLE recorded history of the project — the same flag, and the same
31
+ * meaning, that `repair-cycles` already carries.
32
+ */
33
+ export type ObservabilityQueryOptions = {
38
34
  project?: string;
39
35
  session?: string;
40
36
  json?: boolean;
41
37
  allSessions?: boolean;
42
- }): void;
38
+ };
39
+ /**
40
+ * The session a query reads, or `undefined` for EVERY session.
41
+ *
42
+ * `allSessions` short-circuits the resolution: the whole recorded history is
43
+ * read instead of the canonical session binding, and an explicit `--session`
44
+ * does not narrow it back. That is the precedence `repair-cycles
45
+ * --all-sessions` already has.
46
+ */
47
+ export declare function resolveSessionId(optionSession: string | undefined, projectRoot: string, allSessions: boolean): string | undefined;
48
+ /**
49
+ * The warnings a scoped query carries.
50
+ *
51
+ * A scoped query that reads zero events reads exactly like a project that
52
+ * recorded nothing, and the reader concludes the second — the events that ARE
53
+ * there stay invisible. So when the scope is empty while OTHER sessions hold
54
+ * events, the warning says how many sessions hold them, how many events in
55
+ * total, and names the flag that reaches them.
56
+ *
57
+ * Empty otherwise: either the scope holds events, or the scope already
58
+ * covers every session.
59
+ */
60
+ export declare function scopeWarnings(projectRoot: string, scopedSessionId: string | undefined, scopedEventCount: number): string[];
61
+ /** What a scoped query reads: the session it was scoped to, and its events. */
62
+ export type ScopedRead = {
63
+ readonly sessionId: string | undefined;
64
+ readonly events: ReturnType<typeof readAllSessionEvents>;
65
+ };
66
+ /**
67
+ * The events a scoped query answers for: the one session the scope names, or
68
+ * every session the project recorded.
69
+ */
70
+ export declare function readScopedEvents(projectRoot: string, options: ObservabilityQueryOptions): ScopedRead;
71
+ /**
72
+ * The scope a query answered for: one session, or every session.
73
+ *
74
+ * ONE spelling of that shape, exported because the report command answers
75
+ * with it too: a scope written two ways is a scope that can drift.
76
+ */
77
+ export declare function scopeOf(sessionId: string | undefined): {
78
+ sessionId: string;
79
+ } | {
80
+ allSessions: true;
81
+ };
82
+ export declare function runStatus(io: ProgramIO, options: ObservabilityQueryOptions): void;
83
+ export declare function runSlices(io: ProgramIO, options: ObservabilityQueryOptions): void;
84
+ export declare function runFanout(io: ProgramIO, options: ObservabilityQueryOptions): void;
85
+ export declare function runRepairCycles(io: ProgramIO, options: ObservabilityQueryOptions): void;