peaks-loop 4.1.21 → 4.1.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/.claude-plugin/marketplace.json +3 -6
  2. package/CHANGELOG.md +191 -0
  3. package/dist/cli/commands/mut-commands-helpers.d.ts +6 -6
  4. package/dist/cli/commands/mut-commands-helpers.js +44 -26
  5. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  6. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  7. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  8. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  9. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  10. package/dist/cli/commands/observability-commands-queries.js +88 -47
  11. package/dist/cli/commands/observability-commands.js +79 -20
  12. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  13. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  14. package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
  15. package/dist/services/artifacts/prerequisite-path-census.js +79 -0
  16. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  17. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  18. package/dist/services/artifacts/rd-gate-event.js +211 -0
  19. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  20. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  21. package/dist/services/distribution/json-layout.d.ts +20 -0
  22. package/dist/services/distribution/json-layout.js +195 -0
  23. package/dist/services/distribution/plugin-manifest.d.ts +31 -2
  24. package/dist/services/distribution/plugin-manifest.js +40 -4
  25. package/dist/services/observability/aggregation-types.d.ts +21 -0
  26. package/dist/services/observability/aggregation.d.ts +12 -2
  27. package/dist/services/observability/aggregation.js +26 -2
  28. package/dist/services/observability/compliance-judge.d.ts +77 -0
  29. package/dist/services/observability/compliance-judge.js +143 -0
  30. package/dist/services/observability/compliance-spec.d.ts +96 -0
  31. package/dist/services/observability/compliance-spec.js +29 -0
  32. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  33. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  34. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  35. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  36. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  37. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  38. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  39. package/dist/services/observability/hotspot-rows.js +89 -0
  40. package/dist/services/observability/hotspot-shared.d.ts +212 -0
  41. package/dist/services/observability/hotspot-shared.js +122 -0
  42. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  43. package/dist/services/observability/hotspot-sources.js +142 -0
  44. package/dist/services/observability/hotspots.d.ts +47 -0
  45. package/dist/services/observability/hotspots.js +47 -0
  46. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  47. package/dist/services/observability/near-miss-attempts.js +223 -0
  48. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  49. package/dist/services/observability/near-miss-coverage.js +108 -0
  50. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  51. package/dist/services/observability/near-miss-denominator.js +75 -0
  52. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  53. package/dist/services/observability/near-miss-difference.js +132 -0
  54. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  55. package/dist/services/observability/near-miss-facts.js +101 -0
  56. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  57. package/dist/services/observability/near-miss-gate-events.js +106 -0
  58. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  59. package/dist/services/observability/near-miss-gates.js +135 -0
  60. package/dist/services/observability/near-miss-records.d.ts +93 -0
  61. package/dist/services/observability/near-miss-records.js +87 -0
  62. package/dist/services/observability/near-miss.d.ts +148 -0
  63. package/dist/services/observability/near-miss.js +196 -0
  64. package/dist/services/observability/observability-schema.d.ts +17 -2
  65. package/dist/services/observability/observability-schema.js +21 -1
  66. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  67. package/dist/services/observability/owner-skill-map.js +144 -0
  68. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  69. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  70. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  71. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  72. package/dist/services/observability/report-formatter.d.ts +49 -3
  73. package/dist/services/observability/report-formatter.js +55 -14
  74. package/dist/services/observability/retro-attribution.d.ts +129 -0
  75. package/dist/services/observability/retro-attribution.js +134 -0
  76. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  77. package/dist/services/observability/session-metric-rows.js +184 -0
  78. package/package.json +5 -5
@@ -0,0 +1,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;
@@ -15,6 +15,10 @@
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
  */
19
23
  import { fail, ok } from 'peaks-loop-shared/result';
20
24
  import { findProjectRoot } from '../../services/config/config-safety.js';
@@ -27,28 +31,84 @@ export function resolveProjectRoot(optionProject) {
27
31
  ? resolveCanonicalProjectRoot(optionProject)
28
32
  : (findProjectRoot(process.cwd()) ?? process.cwd());
29
33
  }
30
- export function resolveSessionId(optionSession, projectRoot) {
34
+ /**
35
+ * The session a query reads, or `undefined` for EVERY session.
36
+ *
37
+ * `allSessions` short-circuits the resolution: the whole recorded history is
38
+ * read instead of the canonical session binding, and an explicit `--session`
39
+ * does not narrow it back. That is the precedence `repair-cycles
40
+ * --all-sessions` already has.
41
+ */
42
+ export function resolveSessionId(optionSession, projectRoot, allSessions) {
43
+ if (allSessions)
44
+ return undefined;
31
45
  if (optionSession !== undefined)
32
46
  return optionSession;
33
47
  return getSessionIdCanonical(projectRoot) ?? undefined;
34
48
  }
49
+ /**
50
+ * The warnings a scoped query carries.
51
+ *
52
+ * A scoped query that reads zero events reads exactly like a project that
53
+ * recorded nothing, and the reader concludes the second — the events that ARE
54
+ * there stay invisible. So when the scope is empty while OTHER sessions hold
55
+ * events, the warning says how many sessions hold them, how many events in
56
+ * total, and names the flag that reaches them.
57
+ *
58
+ * Empty otherwise: either the scope holds events, or the scope already
59
+ * covers every session.
60
+ */
61
+ export function scopeWarnings(projectRoot, scopedSessionId, scopedEventCount) {
62
+ if (scopedSessionId === undefined)
63
+ return [];
64
+ if (scopedEventCount > 0)
65
+ return [];
66
+ const sessions = new Set();
67
+ let eventCount = 0;
68
+ for (const event of readAllSessionEvents(projectRoot)) {
69
+ if (event.sessionId === scopedSessionId)
70
+ continue;
71
+ sessions.add(event.sessionId);
72
+ eventCount += 1;
73
+ }
74
+ if (eventCount === 0)
75
+ return [];
76
+ return [
77
+ `No observability events in session \`${scopedSessionId}\`; ` +
78
+ `${sessions.size} other session(s) hold ${eventCount} event(s) in total — ` +
79
+ 'use `--all-sessions` to read them.'
80
+ ];
81
+ }
82
+ /**
83
+ * The events a scoped query answers for: the one session the scope names, or
84
+ * every session the project recorded.
85
+ */
86
+ export function readScopedEvents(projectRoot, options) {
87
+ const sessionId = resolveSessionId(options.session, projectRoot, options.allSessions === true);
88
+ const events = sessionId !== undefined
89
+ ? readSessionEvents(projectRoot, sessionId)
90
+ : readAllSessionEvents(projectRoot);
91
+ return { sessionId, events };
92
+ }
93
+ /**
94
+ * The scope a query answered for: one session, or every session.
95
+ *
96
+ * ONE spelling of that shape, exported because the report command answers
97
+ * with it too: a scope written two ways is a scope that can drift.
98
+ */
99
+ export function scopeOf(sessionId) {
100
+ return sessionId !== undefined ? { sessionId } : { allSessions: true };
101
+ }
35
102
  export function runStatus(io, options) {
36
103
  const projectRoot = resolveProjectRoot(options.project);
37
- const sessionId = resolveSessionId(options.session, projectRoot);
38
104
  try {
39
- const events = sessionId !== undefined
40
- ? readSessionEvents(projectRoot, sessionId)
41
- : readAllSessionEvents(projectRoot);
105
+ const { sessionId, events } = readScopedEvents(projectRoot, options);
42
106
  const status = aggregateStatus(events);
43
- const warnings = sessionId === undefined && status.totalEvents === 0
44
- ? [
45
- 'No observability events found in any session — emit a slice transition via `peaks request transition` to populate.'
46
- ]
47
- : [];
48
- printResult(io, ok('observability.status', {
49
- scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
50
- status
51
- }, warnings), options.json);
107
+ const warnings = scopeWarnings(projectRoot, sessionId, status.totalEvents);
108
+ if (sessionId === undefined && status.totalEvents === 0) {
109
+ warnings.push('No observability events found in any session — emit a slice transition via `peaks request transition` to populate.');
110
+ }
111
+ printResult(io, ok('observability.status', { scope: scopeOf(sessionId), status }, warnings), options.json);
52
112
  }
53
113
  catch (error) {
54
114
  printResult(io, fail('observability.status', 'OBSERVABILITY_STATUS_FAILED', getErrorMessage(error), { projectRoot }, ['Run `peaks observability slices` for per-slice detail']), options.json);
@@ -57,17 +117,11 @@ export function runStatus(io, options) {
57
117
  }
58
118
  export function runSlices(io, options) {
59
119
  const projectRoot = resolveProjectRoot(options.project);
60
- const sessionId = resolveSessionId(options.session, projectRoot);
61
120
  try {
62
- const events = sessionId !== undefined
63
- ? readSessionEvents(projectRoot, sessionId)
64
- : readAllSessionEvents(projectRoot);
121
+ const { sessionId, events } = readScopedEvents(projectRoot, options);
65
122
  const slices = aggregateSlices(events);
66
- printResult(io, ok('observability.slices', {
67
- scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
68
- total: slices.length,
69
- slices
70
- }, []), options.json);
123
+ const warnings = scopeWarnings(projectRoot, sessionId, events.length);
124
+ printResult(io, ok('observability.slices', { scope: scopeOf(sessionId), total: slices.length, slices }, warnings), options.json);
71
125
  }
72
126
  catch (error) {
73
127
  printResult(io, fail('observability.slices', 'OBSERVABILITY_SLICES_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
@@ -76,21 +130,14 @@ export function runSlices(io, options) {
76
130
  }
77
131
  export function runFanout(io, options) {
78
132
  const projectRoot = resolveProjectRoot(options.project);
79
- const sessionId = resolveSessionId(options.session, projectRoot);
80
133
  try {
81
- const events = sessionId !== undefined
82
- ? readSessionEvents(projectRoot, sessionId)
83
- : readAllSessionEvents(projectRoot);
134
+ const { sessionId, events } = readScopedEvents(projectRoot, options);
84
135
  const fanout = aggregateFanout(events);
85
- const warnings = fanout.total === 0
86
- ? [
87
- 'No dispatch events recorded yet — Slice C will wire `peaks sub-agent dispatch`; until then fanout is empty.'
88
- ]
89
- : [];
90
- printResult(io, ok('observability.fanout', {
91
- scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
92
- fanout
93
- }, warnings), options.json);
136
+ const warnings = scopeWarnings(projectRoot, sessionId, events.length);
137
+ if (fanout.total === 0) {
138
+ warnings.push('No dispatch events recorded in this scope — the fanout breakdown counts the dispatch events of the scope that was read.');
139
+ }
140
+ printResult(io, ok('observability.fanout', { scope: scopeOf(sessionId), fanout }, warnings), options.json);
94
141
  }
95
142
  catch (error) {
96
143
  printResult(io, fail('observability.fanout', 'OBSERVABILITY_FANOUT_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
@@ -99,19 +146,13 @@ export function runFanout(io, options) {
99
146
  }
100
147
  export function runRepairCycles(io, options) {
101
148
  const projectRoot = resolveProjectRoot(options.project);
102
- // `--all-sessions` is the escape from the canonical-session binding: the
103
- // recorded history (every session in the project) is the population the
104
- // results baseline and the metric comparison are measured over.
105
- const sessionId = options.allSessions === true ? undefined : resolveSessionId(options.session, projectRoot);
106
149
  try {
107
- const events = sessionId !== undefined
108
- ? readSessionEvents(projectRoot, sessionId)
109
- : readAllSessionEvents(projectRoot);
150
+ // `--all-sessions` is the escape from the canonical-session binding: the
151
+ // recorded history (every session in the project) is the population the
152
+ // results baseline and the metric comparison are measured over.
153
+ const { sessionId, events } = readScopedEvents(projectRoot, options);
110
154
  const cycles = aggregateRepairCycles(events);
111
- printResult(io, ok('observability.repair-cycles', {
112
- scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
113
- cycles
114
- }, []), options.json);
155
+ printResult(io, ok('observability.repair-cycles', { scope: scopeOf(sessionId), cycles }, scopeWarnings(projectRoot, sessionId, events.length)), options.json);
115
156
  }
116
157
  catch (error) {
117
158
  printResult(io, fail('observability.repair-cycles', 'OBSERVABILITY_REPAIR_CYCLES_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
@@ -19,53 +19,107 @@
19
19
  */
20
20
  import { fail, ok } from 'peaks-loop-shared/result';
21
21
  import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
22
- import { aggregateFanout, aggregateRepairCycles, aggregateSlices, aggregateStatus, filterByPeriod, periodStartIso, readAllSessionEvents, readSessionEvents } from '../../services/observability/aggregation.js';
22
+ import { aggregateFanout, aggregateRepairCycles, aggregateSlices, aggregateStatus, filterByPeriod, periodStartIso } from '../../services/observability/aggregation.js';
23
23
  import { renderObservabilityReport } from '../../services/observability/report-formatter.js';
24
+ import { computeNearMiss } from '../../services/observability/near-miss.js';
25
+ import { aggregateHotspots } from '../../services/observability/hotspots.js';
24
26
  // Slice `b1-filesplit-campaign` (wave 3B): the four read-only query runners
25
27
  // (`runStatus` / `runSlices` / `runFanout` / `runRepairCycles`) plus the two
26
28
  // scope resolvers they share moved VERBATIM to `./observability-commands-queries.ts`
27
29
  // so this file clears the 300 raw-line cap. What they do is unchanged;
28
30
  // `runReport` — the one function here carrying a finding — stayed behind, so no
29
31
  // finding moved into the new module.
30
- import { resolveProjectRoot, resolveSessionId, runFanout, runRepairCycles, runSlices, runStatus } from './observability-commands-queries.js';
32
+ import { readScopedEvents, resolveProjectRoot, runFanout, runRepairCycles, runSlices, runStatus, scopeOf, scopeWarnings } from './observability-commands-queries.js';
31
33
  import { runBaseline } from './observability-commands-baseline.js';
34
+ import { registerNearMissCommand } from './observability-commands-near-miss.js';
35
+ import { hotspotRequestTypes, registerHotspotsCommand } from './observability-commands-hotspots.js';
32
36
  const VALID_PERIODS = ['day', 'week', 'month'];
37
+ /** The `--all-sessions` help text, ONE string for every command that carries it. */
38
+ const ALL_SESSIONS_DESCRIPTION = 'measure the whole recorded history of the project instead of the canonical session binding';
39
+ /**
40
+ * The warning a report carries when its PERIOD emptied the result.
41
+ *
42
+ * The scope and the period are two different axes: `--all-sessions` widens
43
+ * WHICH sessions are read, `--period` narrows WHICH DAYS of them count. A
44
+ * reader who scoped correctly and still saw an empty table was narrowed by
45
+ * the period, so the warning says the scope holds events and names the
46
+ * period window that reaches the most of them.
47
+ */
48
+ function periodWarnings(scopedEvents, period, now) {
49
+ if (scopedEvents.length === 0)
50
+ return [];
51
+ if (filterByPeriod(scopedEvents, period, now).length > 0)
52
+ return [];
53
+ let reaching;
54
+ let reachingCount = 0;
55
+ for (const candidate of VALID_PERIODS) {
56
+ const count = filterByPeriod(scopedEvents, candidate, now).length;
57
+ if (count > 0 && count >= reachingCount) {
58
+ reaching = candidate;
59
+ reachingCount = count;
60
+ }
61
+ }
62
+ if (reaching === undefined) {
63
+ return [
64
+ `No observability events fall inside the \`${period}\` period, and the scope's ` +
65
+ `${scopedEvents.length} event(s) are older than every period window — ` +
66
+ 'no `--period` value reaches them.'
67
+ ];
68
+ }
69
+ return [
70
+ `No observability events fall inside the \`${period}\` period, though the scope holds ` +
71
+ `${scopedEvents.length} event(s) — use \`--period ${reaching}\` to read them.`
72
+ ];
73
+ }
33
74
  function runReport(io, options) {
34
75
  const projectRoot = resolveProjectRoot(options.project);
35
- const sessionId = resolveSessionId(options.session, projectRoot);
36
76
  const period = options.period !== undefined && VALID_PERIODS.includes(options.period)
37
77
  ? options.period
38
78
  : 'day';
39
79
  try {
40
- const allEvents = sessionId !== undefined
41
- ? readSessionEvents(projectRoot, sessionId)
42
- : readAllSessionEvents(projectRoot);
43
- const periodStart = periodStartIso(period);
44
- const events = filterByPeriod(allEvents, period);
80
+ const { sessionId, events: allEvents } = readScopedEvents(projectRoot, options);
81
+ // ONE clock for the whole report: the window the events are filtered by
82
+ // and the window the warning names must be the same one.
83
+ const at = new Date();
84
+ const now = () => new Date(at);
85
+ const periodStart = periodStartIso(period, now);
86
+ const events = filterByPeriod(allEvents, period, now);
87
+ // The two measurements the report leads with. The request types are
88
+ // resolved through the hotspots command's own lookup, so the ranking in
89
+ // the report and the ranking the `hotspots` command prints cannot drift.
90
+ const { requestTypes } = hotspotRequestTypes(projectRoot, events);
91
+ const warnings = [
92
+ ...scopeWarnings(projectRoot, sessionId, allEvents.length),
93
+ ...periodWarnings(allEvents, period, now)
94
+ ];
45
95
  const markdown = renderObservabilityReport({
46
96
  scope: sessionId !== undefined ? 'session' : 'all-sessions',
47
97
  scopeId: sessionId ?? 'all',
48
98
  period,
49
- generatedAt: new Date().toISOString(),
99
+ generatedAt: at.toISOString(),
50
100
  status: aggregateStatus(events),
51
101
  slices: aggregateSlices(events),
52
102
  fanout: aggregateFanout(events),
53
- repairCycles: aggregateRepairCycles(events)
103
+ repairCycles: aggregateRepairCycles(events),
104
+ nearMiss: computeNearMiss(events, requestTypes),
105
+ hotspots: aggregateHotspots(events, requestTypes),
106
+ warnings
54
107
  });
55
108
  if (options.json === true) {
56
109
  // --json on report: emit a metadata envelope so callers can
57
110
  // machine-parse the markdown body without losing the envelope
58
111
  // contract.
59
112
  printResult(io, ok('observability.report', {
60
- scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
113
+ scope: scopeOf(sessionId),
61
114
  period,
62
115
  periodStart,
63
116
  totalEventsScanned: allEvents.length,
64
117
  totalEventsInPeriod: events.length,
65
118
  markdown
66
- }, []), true);
119
+ }, warnings), true);
67
120
  return;
68
121
  }
122
+ // The warnings are IN the markdown header: the body is what gets pasted.
69
123
  io.stdout(markdown);
70
124
  }
71
125
  catch (error) {
@@ -79,23 +133,26 @@ export function registerObservabilityCommands(program, io) {
79
133
  .description('Read-only slice topology observability queries (v2.11.1). Reads JSONL metrics from .peaks/_runtime/<sessionId>/metrics/slices.jsonl.');
80
134
  addJsonOption(observability
81
135
  .command('status')
82
- .description('Aggregate metrics for the active session (or all sessions with --project + omitted --session). Includes totalEvents / totalSlices / successCount / failCount / repairCyclePeak / fanoutCostTotal.')
136
+ .description('Aggregate metrics for the active session (or all sessions with --project + omitted --session). Includes totalEvents / totalSlices / successCount / failCount / stalledCount / repairCyclePeak / fanoutCostTotal.')
83
137
  .option('--project <path>', 'target project root (defaults to git root or cwd)')
84
- .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action((options) => {
138
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
139
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
85
140
  runStatus(io, options);
86
141
  });
87
142
  addJsonOption(observability
88
143
  .command('slices')
89
144
  .description('List all slices for the scope. Per slice: rid, transition count, first/last ts, durationMs, finalState, fanoutCount, repairCycleCount, success.')
90
145
  .option('--project <path>', 'target project root (defaults to git root or cwd)')
91
- .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action((options) => {
146
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
147
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
92
148
  runSlices(io, options);
93
149
  });
94
150
  addJsonOption(observability
95
151
  .command('fanout')
96
152
  .description('Fanout cost breakdown by sub-agent role (rd / qa / code-reviewer / karpathy-reviewer / peaks-security-audit / peaks-perf-audit; v2.12.0 collapse — `security-reviewer` removed from the role enum). Returns 0 per role until Slice C wires the `peaks sub-agent dispatch` hook.')
97
153
  .option('--project <path>', 'target project root (defaults to git root or cwd)')
98
- .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action((options) => {
154
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
155
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
99
156
  runFanout(io, options);
100
157
  });
101
158
  addJsonOption(observability
@@ -103,7 +160,7 @@ export function registerObservabilityCommands(program, io) {
103
160
  .description('RD → QA repair-cycle count per slice (metric version 2: a repair cycle is a return to an RD work state after a QA phase). Cap = 3 (peaks-code repair-loop contract); capHit flag is set when any slice hits the cap. The version-1 qa-role event count is reported beside it as legacyQaEventCount — it is NOT a repair-cycle count.')
104
161
  .option('--project <path>', 'target project root (defaults to git root or cwd)')
105
162
  .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
106
- .option('--all-sessions', 'measure the whole recorded history of the project instead of the canonical session binding')).action((options) => {
163
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
107
164
  runRepairCycles(io, options);
108
165
  });
109
166
  addJsonOption(observability
@@ -114,13 +171,15 @@ export function registerObservabilityCommands(program, io) {
114
171
  .option('--check', 'compare the computed baseline against the tracked artifact and report drift')).action((options) => {
115
172
  runBaseline(io, options);
116
173
  });
117
- observability
174
+ addJsonOption(observability
118
175
  .command('report')
119
- .description('Render a markdown summary suitable for paste into PR descriptions or .peaks/PROJECT.md timeline entries. Default period = day; --json emits an envelope wrapping the markdown body. Output sections: header + status summary + slice table + fanout table + repair-cycle table + top-N slowest slices.')
176
+ .description('Render a markdown summary suitable for paste into PR descriptions or .peaks/PROJECT.md timeline entries. Default period = day; --json emits an envelope wrapping the markdown body. Output sections: header + status summary + near-miss section (rate, denominator, per-class coverage, unobserved classes) + slice table + hotspot tables + fanout table + repair-cycle table + top-N slowest slices.')
120
177
  .option('--project <path>', 'target project root (defaults to git root or cwd)')
121
178
  .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
122
179
  .option('--period <period>', 'one of: day | week | month (defaults to day)', 'day')
123
- .action((options) => {
180
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
124
181
  runReport(io, options);
125
182
  });
183
+ registerNearMissCommand(observability, io);
184
+ registerHotspotsCommand(observability, io);
126
185
  }
@@ -84,6 +84,9 @@ export type PrerequisiteCheckResult = {
84
84
  expiredWindow?: string;
85
85
  }>;
86
86
  };
87
+ type TransitionKey = `${RequestArtifactRole}:${RequestArtifactState}`;
88
+ type PrerequisiteTable = Partial<Record<TransitionKey, ReadonlyArray<ArtifactPrerequisite>>>;
89
+ export declare const PREREQUISITES_BY_TYPE: Record<RequestType, PrerequisiteTable>;
87
90
  export type CheckPrerequisitesOptions = {
88
91
  projectRoot: string;
89
92
  /**
@@ -327,7 +327,7 @@ const CONFIG_TABLE = {
327
327
  'rd:qa-handoff': [SECURITY_REVIEW],
328
328
  'qa:verdict-issued': [TEST_REPORT]
329
329
  };
330
- const PREREQUISITES_BY_TYPE = {
330
+ export const PREREQUISITES_BY_TYPE = {
331
331
  feature: FEATURE_TABLE,
332
332
  bugfix: BUGFIX_TABLE,
333
333
  refactor: REFACTOR_TABLE,
@@ -0,0 +1,42 @@
1
+ /**
2
+ * `src/services/artifacts/prerequisite-path-census.ts`
3
+ *
4
+ * Every path shape that can reach the prerequisite missing list, as one
5
+ * de-duplicated list.
6
+ *
7
+ * WHY THIS EXISTS. The owner-skill map has to cover the paths the gates
8
+ * actually demand, and the gates read ONE table. Reading that table through
9
+ * a census function means the coverage check and the gate can never
10
+ * disagree about which paths exist — a second hand-written list would drift
11
+ * from the table on the first table change.
12
+ *
13
+ * THE THREE SOURCES OF A MISSING PATH. `checkPrerequisites` builds its
14
+ * missing list from three places, and a census that reads only the first
15
+ * would leave the other two uncovered:
16
+ *
17
+ * 1. the table loop — the canonical `relativePath`, plus the legacy tiers
18
+ * (`legacyRelativePath` / `legacyRelativePaths`) the resolver probes
19
+ * before it calls a file absent;
20
+ * 2. the judged-declaration refusals — the security artifact's own
21
+ * location, which the resolver reports verbatim;
22
+ * 3. the handoff capsule's gate-evidence declaration — a key that names a
23
+ * file that is not on disk, reported under the KEY's name, and the
24
+ * unreadable-capsule shape beside it.
25
+ *
26
+ * The `<rid>` placeholder is left in place on the table paths: this is the
27
+ * table's own shape, and the owner lookup is a prefix match, so the
28
+ * placeholder is irrelevant to it.
29
+ *
30
+ * THE KEY SET IS READ, NOT COPIED. `GATE_EVIDENCE_KEYS` is the one
31
+ * definition of the gate-evidence vocabulary, and a second copy of it here
32
+ * would be the same drift hole this census exists to close. The failure
33
+ * statuses are held in a `Record` keyed by the reader's own status type, so
34
+ * a status added to that type fails the build here until this census
35
+ * accounts for it.
36
+ */
37
+ /**
38
+ * Every `relativePath` any request type demands, every legacy tier the
39
+ * resolver probes for one, and every gate-evidence shape a declaration can
40
+ * report — de-duplicated and sorted.
41
+ */
42
+ export declare function allPrerequisitePaths(): readonly string[];