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
@@ -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);
@@ -0,0 +1,48 @@
1
+ /**
2
+ * `src/cli/commands/observability-commands-session-row.ts`
3
+ *
4
+ * `peaks observability session-row` — the production caller of the per-session
5
+ * metric row, and the reader of the compliance rate.
6
+ *
7
+ * WHY IT IS ON DEMAND. The row and the judge had no caller outside their own
8
+ * tests, so neither was reachable. This command is the caller: it reads the
9
+ * scoped session, judges every slice it recorded against the peaks-rd spec,
10
+ * writes the tracked row, and prints the rates it was built from. No session-end
11
+ * hook exists to attach to, so the row is written when the command is asked for.
12
+ *
13
+ * WHY THE RATE IS NULL WHEN NOTHING WAS JUDGED. A compliance rate is the share of
14
+ * declared steps that ran. A session with no judged slice has no such share: 0
15
+ * would read as "judged, and nothing ran", which nothing observed. So the rate
16
+ * is null and the reason says why, the same coverage rule the near-miss rate uses.
17
+ *
18
+ * WHY THE SPEC IS PEAKS-RD ONLY. The fast-lane spec's steps describe a lane that
19
+ * writes no RD artifacts, so judging an RD slice against it would report a rate
20
+ * that measures the wrong skill. Each reading names its spec, so a second spec
21
+ * can be added later without changing the shape.
22
+ */
23
+ import type { Command } from 'commander';
24
+ import { type SessionComplianceReading } from '../../services/observability/session-metric-rows.js';
25
+ import { type ProgramIO } from '../cli-helpers.js';
26
+ import { type ObservabilityQueryOptions } from './observability-commands-queries.js';
27
+ /** The compliance rate of a session, or the reason it was not observed. */
28
+ export type ComplianceSummary = {
29
+ /** The unweighted mean of the judged slices' rates, or null when none was judged. */
30
+ readonly complianceRate: number | null;
31
+ /**
32
+ * Why the rate is null, or why it covers fewer slices than the session
33
+ * recorded. Null when the rate covers every slice the session recorded.
34
+ */
35
+ readonly complianceReason: string | null;
36
+ readonly judgedSliceCount: number;
37
+ /** The recorded slices that could not be judged, and why. */
38
+ readonly rejectedSliceCount: number;
39
+ };
40
+ /** Summarise the readings. An empty set is unobserved, never a zero rate. */
41
+ export declare function summarizeCompliance(readings: readonly SessionComplianceReading[], rejectedSliceCount?: number): ComplianceSummary;
42
+ /**
43
+ * `peaks observability session-row` — write the session's tracked row and print
44
+ * its near-miss and compliance rates.
45
+ */
46
+ export declare function runSessionRow(io: ProgramIO, options: ObservabilityQueryOptions): Promise<void>;
47
+ /** Register `peaks observability session-row` under the observability command. */
48
+ export declare function registerSessionRowCommand(observability: Command, io: ProgramIO): void;
@@ -0,0 +1,201 @@
1
+ /**
2
+ * `src/cli/commands/observability-commands-session-row.ts`
3
+ *
4
+ * `peaks observability session-row` — the production caller of the per-session
5
+ * metric row, and the reader of the compliance rate.
6
+ *
7
+ * WHY IT IS ON DEMAND. The row and the judge had no caller outside their own
8
+ * tests, so neither was reachable. This command is the caller: it reads the
9
+ * scoped session, judges every slice it recorded against the peaks-rd spec,
10
+ * writes the tracked row, and prints the rates it was built from. No session-end
11
+ * hook exists to attach to, so the row is written when the command is asked for.
12
+ *
13
+ * WHY THE RATE IS NULL WHEN NOTHING WAS JUDGED. A compliance rate is the share of
14
+ * declared steps that ran. A session with no judged slice has no such share: 0
15
+ * would read as "judged, and nothing ran", which nothing observed. So the rate
16
+ * is null and the reason says why, the same coverage rule the near-miss rate uses.
17
+ *
18
+ * WHY THE SPEC IS PEAKS-RD ONLY. The fast-lane spec's steps describe a lane that
19
+ * writes no RD artifacts, so judging an RD slice against it would report a rate
20
+ * that measures the wrong skill. Each reading names its spec, so a second spec
21
+ * can be added later without changing the shape.
22
+ */
23
+ import { fail, ok } from 'peaks-loop-shared/result';
24
+ import { PEAKS_RD_SPEC } from '../../services/observability/compliance-specs/peaks-rd.spec.js';
25
+ import { buildSessionMetricRow, judgeSessionCompliance, readSkillsBlobSha, sessionMetricRowPath, writeSessionMetricRow } from '../../services/observability/session-metric-rows.js';
26
+ import { isSinglePathSegment } from '../../services/session/getSessionDir.js';
27
+ import { NUMBERED_PREFIX_RE } from '../../shared/incrementing-number.js';
28
+ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
29
+ import { hotspotRequestTypes } from './observability-commands-hotspots.js';
30
+ import { readScopedEvents, resolveProjectRoot, scopeOf, scopeWarnings } from './observability-commands-queries.js';
31
+ /** Summarise the readings. An empty set is unobserved, never a zero rate. */
32
+ export function summarizeCompliance(readings, rejectedSliceCount = 0) {
33
+ const rejectedNote = rejectedSliceCount === 0
34
+ ? null
35
+ : `${rejectedSliceCount} recorded slice id(s) could NOT be judged, because they are ` +
36
+ 'not a single safe path segment — an unobserved slice, not a failed one';
37
+ if (readings.length === 0) {
38
+ // The two reasons are different facts, and the recorded one wins when both
39
+ // hold: a session whose slices were all REJECTED did record slices, so
40
+ // saying "no slice was recorded" would deny the event stream's own content.
41
+ return {
42
+ complianceRate: null,
43
+ complianceReason: rejectedNote ??
44
+ 'no slice was recorded in this session, so no slice was judged and no compliance ' +
45
+ 'rate was observed — an absence of data, not a result',
46
+ judgedSliceCount: 0,
47
+ rejectedSliceCount
48
+ };
49
+ }
50
+ const total = readings.reduce((sum, reading) => sum + reading.complianceRate, 0);
51
+ return {
52
+ complianceRate: total / readings.length,
53
+ complianceReason: rejectedNote,
54
+ judgedSliceCount: readings.length,
55
+ rejectedSliceCount
56
+ };
57
+ }
58
+ /**
59
+ * The distinct slices the session's events name, split by whether they can be
60
+ * judged, together with the spelling each slice is judged under.
61
+ *
62
+ * WHY A SLICE ID IS CHECKED BEFORE IT BECOMES A PATH. The slice id comes from
63
+ * the event stream, and the judge substitutes it into the spec's declared
64
+ * artifact paths before probing the filesystem. A slice id carrying `..` would
65
+ * therefore move the probe OUTSIDE the session directory, and an artifact
66
+ * planted elsewhere would be credited as a step that ran inside the session.
67
+ * The event stream is a file on disk, so its contents are input like any other:
68
+ * the check belongs here, at the boundary where the id becomes a path.
69
+ *
70
+ * The predicate is the repository's own `isSinglePathSegment`, the same one the
71
+ * session id is held to. A legal slice id is a single segment, so nothing a
72
+ * real slice id carries is refused.
73
+ *
74
+ * WHY THE SLICES ARE KEYED ON THE LOGICAL ID AND NOT ON THE RAW STRING. A
75
+ * slice's id arrives in TWO spellings, from two different producers: the
76
+ * request writer stamps `NNN-` on the artifact FILENAME, while the transition
77
+ * CLI is handed the UN-NUMBERED rid — and the event stream carries both. Keyed
78
+ * on the raw string, ONE slice was judged twice, under two spellings that
79
+ * resolve DIFFERENTLY: the resolver finds the artifacts under the numbered
80
+ * spelling and misses most of them under the bare one, so the same slice was
81
+ * counted once at its real rate and once at a rate its artifacts do not
82
+ * support. The rate's denominator was then the count of SPELLINGS rather than
83
+ * the count of slices, so it was not the mean the slice's contract names.
84
+ *
85
+ * The repository's own rule says which spelling is the slice's identity:
86
+ * `NUMBERED_PREFIX_RE` — the family `buildNumberedFilename` writes and
87
+ * `requestIdFromFileName` strips. Stripping it leaves the LOGICAL slice id,
88
+ * and that is what the sets are keyed on.
89
+ *
90
+ * WHY THE NUMBERED SPELLING IS THE ONE JUDGED. The artifacts on disk carry
91
+ * that number — `rd/requests/002-<rid>.md` and `prd/handoff-002-<rid>.md`
92
+ * alike — so the numbered spelling is the one the resolver can actually find
93
+ * them under. A slice the stream named only in its bare spelling is judged
94
+ * under that spelling, because it is the only one it has.
95
+ *
96
+ * WHY THE SAFETY CHECK RUNS BEFORE THE NORMALISATION. The check is on the RAW
97
+ * id, so a hostile multi-segment id is refused rather than normalised into
98
+ * something that looks safe: stripping a leading `NNN-` can only ever REMOVE
99
+ * characters from an id that is already a single safe segment, and can never
100
+ * turn one segment into two or into a traversal.
101
+ */
102
+ function partitionSliceRids(events) {
103
+ const judged = new Map();
104
+ const rejected = new Set();
105
+ for (const event of events) {
106
+ if (event.sliceRid === undefined)
107
+ continue;
108
+ const rid = event.sliceRid;
109
+ if (!isSinglePathSegment(rid)) {
110
+ rejected.add(rid);
111
+ continue;
112
+ }
113
+ const numbered = NUMBERED_PREFIX_RE.test(rid);
114
+ const logical = rid.replace(NUMBERED_PREFIX_RE, '');
115
+ const existing = judged.get(logical);
116
+ if (existing === undefined)
117
+ judged.set(logical, { rid, numbered });
118
+ // A numbered spelling resolves artifacts the bare spelling cannot find, so
119
+ // it wins; two spellings of the same family are the same slice either way.
120
+ else if (numbered && !existing.numbered)
121
+ judged.set(logical, { rid, numbered });
122
+ }
123
+ return { judged: [...judged.values()].map((entry) => entry.rid), rejected: [...rejected] };
124
+ }
125
+ /** Judge every slice the session recorded against the peaks-rd spec. */
126
+ async function judgeSessionSlices(projectRoot, sessionId, sliceRids) {
127
+ const readings = [];
128
+ for (const sliceRid of sliceRids) {
129
+ readings.push(await judgeSessionCompliance({ projectRoot, sessionId, spec: PEAKS_RD_SPEC, sliceRid }));
130
+ }
131
+ return readings;
132
+ }
133
+ /** The warnings the envelope carries: the scope, the spec, and any unobserved rate. */
134
+ function sessionRowWarnings(projectRoot, sessionId, eventCount, compliance) {
135
+ const warnings = [
136
+ ...scopeWarnings(projectRoot, sessionId, eventCount),
137
+ `compliance is judged against the \`${PEAKS_RD_SPEC.id}\` spec only.`
138
+ ];
139
+ if (compliance.complianceReason !== null)
140
+ warnings.push(compliance.complianceReason);
141
+ return warnings;
142
+ }
143
+ /** The envelope's data: the near-miss rate, the compliance rate, and the row's location. */
144
+ function sessionRowData(projectRoot, sessionId, row, compliance) {
145
+ // The near-miss rate is null when no slice passed: the row stores 0 there,
146
+ // and the command must not present that 0 as a measured rate.
147
+ const nearMissRate = row.passedSliceCount === 0 ? null : row.nearMissRate;
148
+ return {
149
+ scope: scopeOf(sessionId),
150
+ rowPath: sessionMetricRowPath(projectRoot, sessionId),
151
+ nearMissRate,
152
+ nearMissReason: nearMissRate === null
153
+ ? 'no slice passed in this session, so the near-miss rate was not observed'
154
+ : null,
155
+ passedSliceCount: row.passedSliceCount,
156
+ nearMissSliceCount: row.nearMissSliceCount,
157
+ ...compliance,
158
+ specIds: [PEAKS_RD_SPEC.id]
159
+ };
160
+ }
161
+ /**
162
+ * `peaks observability session-row` — write the session's tracked row and print
163
+ * its near-miss and compliance rates.
164
+ */
165
+ export async function runSessionRow(io, options) {
166
+ const projectRoot = resolveProjectRoot(options.project);
167
+ try {
168
+ const { sessionId, events } = readScopedEvents(projectRoot, options);
169
+ if (sessionId === undefined) {
170
+ throw new Error('a session row belongs to one session: pass --session <sessionId>, or run without --all-sessions');
171
+ }
172
+ const { requestTypes } = hotspotRequestTypes(projectRoot, events);
173
+ const { judged, rejected } = partitionSliceRids(events);
174
+ const readings = await judgeSessionSlices(projectRoot, sessionId, judged);
175
+ const skillsBlobSha = readSkillsBlobSha(projectRoot);
176
+ const row = buildSessionMetricRow({
177
+ sessionId,
178
+ events,
179
+ requestTypes,
180
+ compliance: readings,
181
+ ...(skillsBlobSha === undefined ? {} : { skillsBlobSha })
182
+ });
183
+ writeSessionMetricRow(projectRoot, row);
184
+ const compliance = summarizeCompliance(readings, rejected.length);
185
+ printResult(io, ok('observability.session-row', sessionRowData(projectRoot, sessionId, row, compliance), sessionRowWarnings(projectRoot, sessionId, events.length, compliance)), options.json);
186
+ }
187
+ catch (error) {
188
+ printResult(io, fail('observability.session-row', 'OBSERVABILITY_SESSION_ROW_FAILED', getErrorMessage(error), { projectRoot }, []), options.json);
189
+ process.exitCode = 1;
190
+ }
191
+ }
192
+ /** Register `peaks observability session-row` under the observability command. */
193
+ export function registerSessionRowCommand(observability, io) {
194
+ addJsonOption(observability
195
+ .command('session-row')
196
+ .description("Write the tracked per-session metric row (.peaks/observability/sessions/<sessionId>.json) and print its rates. The near-miss rate is null, with a reason, when no slice passed; the compliance rate is the mean share of the peaks-rd spec's required steps that ran across the session's slices, and is null, with a reason, when no slice was recorded.")
197
+ .option('--project <path>', 'target project root (defaults to git root or cwd)')
198
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')).action(async (options) => {
199
+ await runSessionRow(io, options);
200
+ });
201
+ }
@@ -19,53 +19,108 @@
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 { registerSessionRowCommand } from './observability-commands-session-row.js';
36
+ import { hotspotRequestTypes, registerHotspotsCommand } from './observability-commands-hotspots.js';
32
37
  const VALID_PERIODS = ['day', 'week', 'month'];
38
+ /** The `--all-sessions` help text, ONE string for every command that carries it. */
39
+ const ALL_SESSIONS_DESCRIPTION = 'measure the whole recorded history of the project instead of the canonical session binding';
40
+ /**
41
+ * The warning a report carries when its PERIOD emptied the result.
42
+ *
43
+ * The scope and the period are two different axes: `--all-sessions` widens
44
+ * WHICH sessions are read, `--period` narrows WHICH DAYS of them count. A
45
+ * reader who scoped correctly and still saw an empty table was narrowed by
46
+ * the period, so the warning says the scope holds events and names the
47
+ * period window that reaches the most of them.
48
+ */
49
+ function periodWarnings(scopedEvents, period, now) {
50
+ if (scopedEvents.length === 0)
51
+ return [];
52
+ if (filterByPeriod(scopedEvents, period, now).length > 0)
53
+ return [];
54
+ let reaching;
55
+ let reachingCount = 0;
56
+ for (const candidate of VALID_PERIODS) {
57
+ const count = filterByPeriod(scopedEvents, candidate, now).length;
58
+ if (count > 0 && count >= reachingCount) {
59
+ reaching = candidate;
60
+ reachingCount = count;
61
+ }
62
+ }
63
+ if (reaching === undefined) {
64
+ return [
65
+ `No observability events fall inside the \`${period}\` period, and the scope's ` +
66
+ `${scopedEvents.length} event(s) are older than every period window — ` +
67
+ 'no `--period` value reaches them.'
68
+ ];
69
+ }
70
+ return [
71
+ `No observability events fall inside the \`${period}\` period, though the scope holds ` +
72
+ `${scopedEvents.length} event(s) — use \`--period ${reaching}\` to read them.`
73
+ ];
74
+ }
33
75
  function runReport(io, options) {
34
76
  const projectRoot = resolveProjectRoot(options.project);
35
- const sessionId = resolveSessionId(options.session, projectRoot);
36
77
  const period = options.period !== undefined && VALID_PERIODS.includes(options.period)
37
78
  ? options.period
38
79
  : 'day';
39
80
  try {
40
- const allEvents = sessionId !== undefined
41
- ? readSessionEvents(projectRoot, sessionId)
42
- : readAllSessionEvents(projectRoot);
43
- const periodStart = periodStartIso(period);
44
- const events = filterByPeriod(allEvents, period);
81
+ const { sessionId, events: allEvents } = readScopedEvents(projectRoot, options);
82
+ // ONE clock for the whole report: the window the events are filtered by
83
+ // and the window the warning names must be the same one.
84
+ const at = new Date();
85
+ const now = () => new Date(at);
86
+ const periodStart = periodStartIso(period, now);
87
+ const events = filterByPeriod(allEvents, period, now);
88
+ // The two measurements the report leads with. The request types are
89
+ // resolved through the hotspots command's own lookup, so the ranking in
90
+ // the report and the ranking the `hotspots` command prints cannot drift.
91
+ const { requestTypes } = hotspotRequestTypes(projectRoot, events);
92
+ const warnings = [
93
+ ...scopeWarnings(projectRoot, sessionId, allEvents.length),
94
+ ...periodWarnings(allEvents, period, now)
95
+ ];
45
96
  const markdown = renderObservabilityReport({
46
97
  scope: sessionId !== undefined ? 'session' : 'all-sessions',
47
98
  scopeId: sessionId ?? 'all',
48
99
  period,
49
- generatedAt: new Date().toISOString(),
100
+ generatedAt: at.toISOString(),
50
101
  status: aggregateStatus(events),
51
102
  slices: aggregateSlices(events),
52
103
  fanout: aggregateFanout(events),
53
- repairCycles: aggregateRepairCycles(events)
104
+ repairCycles: aggregateRepairCycles(events),
105
+ nearMiss: computeNearMiss(events, requestTypes),
106
+ hotspots: aggregateHotspots(events, requestTypes),
107
+ warnings
54
108
  });
55
109
  if (options.json === true) {
56
110
  // --json on report: emit a metadata envelope so callers can
57
111
  // machine-parse the markdown body without losing the envelope
58
112
  // contract.
59
113
  printResult(io, ok('observability.report', {
60
- scope: sessionId !== undefined ? { sessionId } : { allSessions: true },
114
+ scope: scopeOf(sessionId),
61
115
  period,
62
116
  periodStart,
63
117
  totalEventsScanned: allEvents.length,
64
118
  totalEventsInPeriod: events.length,
65
119
  markdown
66
- }, []), true);
120
+ }, warnings), true);
67
121
  return;
68
122
  }
123
+ // The warnings are IN the markdown header: the body is what gets pasted.
69
124
  io.stdout(markdown);
70
125
  }
71
126
  catch (error) {
@@ -79,23 +134,26 @@ export function registerObservabilityCommands(program, io) {
79
134
  .description('Read-only slice topology observability queries (v2.11.1). Reads JSONL metrics from .peaks/_runtime/<sessionId>/metrics/slices.jsonl.');
80
135
  addJsonOption(observability
81
136
  .command('status')
82
- .description('Aggregate metrics for the active session (or all sessions with --project + omitted --session). Includes totalEvents / totalSlices / successCount / failCount / repairCyclePeak / fanoutCostTotal.')
137
+ .description('Aggregate metrics for the active session (or all sessions with --project + omitted --session). Includes totalEvents / totalSlices / successCount / failCount / stalledCount / repairCyclePeak / fanoutCostTotal.')
83
138
  .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) => {
139
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
140
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
85
141
  runStatus(io, options);
86
142
  });
87
143
  addJsonOption(observability
88
144
  .command('slices')
89
145
  .description('List all slices for the scope. Per slice: rid, transition count, first/last ts, durationMs, finalState, fanoutCount, repairCycleCount, success.')
90
146
  .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) => {
147
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
148
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
92
149
  runSlices(io, options);
93
150
  });
94
151
  addJsonOption(observability
95
152
  .command('fanout')
96
153
  .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
154
  .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) => {
155
+ .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
156
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
99
157
  runFanout(io, options);
100
158
  });
101
159
  addJsonOption(observability
@@ -103,7 +161,7 @@ export function registerObservabilityCommands(program, io) {
103
161
  .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
162
  .option('--project <path>', 'target project root (defaults to git root or cwd)')
105
163
  .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) => {
164
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
107
165
  runRepairCycles(io, options);
108
166
  });
109
167
  addJsonOption(observability
@@ -114,13 +172,16 @@ export function registerObservabilityCommands(program, io) {
114
172
  .option('--check', 'compare the computed baseline against the tracked artifact and report drift')).action((options) => {
115
173
  runBaseline(io, options);
116
174
  });
117
- observability
175
+ addJsonOption(observability
118
176
  .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.')
177
+ .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
178
  .option('--project <path>', 'target project root (defaults to git root or cwd)')
121
179
  .option('--session <sessionId>', 'scope to one session (defaults to the canonical session binding)')
122
180
  .option('--period <period>', 'one of: day | week | month (defaults to day)', 'day')
123
- .action((options) => {
181
+ .option('--all-sessions', ALL_SESSIONS_DESCRIPTION)).action((options) => {
124
182
  runReport(io, options);
125
183
  });
184
+ registerNearMissCommand(observability, io);
185
+ registerSessionRowCommand(observability, io);
186
+ registerHotspotsCommand(observability, io);
126
187
  }
@@ -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,