peaks-loop 4.1.22 → 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 (72) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CHANGELOG.md +82 -0
  3. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  4. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  5. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  6. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  7. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  8. package/dist/cli/commands/observability-commands-queries.js +88 -47
  9. package/dist/cli/commands/observability-commands.js +79 -20
  10. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  11. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  12. package/dist/services/artifacts/prerequisite-path-census.d.ts +42 -0
  13. package/dist/services/artifacts/prerequisite-path-census.js +79 -0
  14. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  15. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  16. package/dist/services/artifacts/rd-gate-event.js +211 -0
  17. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  18. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  19. package/dist/services/observability/aggregation-types.d.ts +21 -0
  20. package/dist/services/observability/aggregation.d.ts +12 -2
  21. package/dist/services/observability/aggregation.js +26 -2
  22. package/dist/services/observability/compliance-judge.d.ts +77 -0
  23. package/dist/services/observability/compliance-judge.js +143 -0
  24. package/dist/services/observability/compliance-spec.d.ts +96 -0
  25. package/dist/services/observability/compliance-spec.js +29 -0
  26. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  27. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  28. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  29. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  30. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  31. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  32. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  33. package/dist/services/observability/hotspot-rows.js +89 -0
  34. package/dist/services/observability/hotspot-shared.d.ts +212 -0
  35. package/dist/services/observability/hotspot-shared.js +122 -0
  36. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  37. package/dist/services/observability/hotspot-sources.js +142 -0
  38. package/dist/services/observability/hotspots.d.ts +47 -0
  39. package/dist/services/observability/hotspots.js +47 -0
  40. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  41. package/dist/services/observability/near-miss-attempts.js +223 -0
  42. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  43. package/dist/services/observability/near-miss-coverage.js +108 -0
  44. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  45. package/dist/services/observability/near-miss-denominator.js +75 -0
  46. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  47. package/dist/services/observability/near-miss-difference.js +132 -0
  48. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  49. package/dist/services/observability/near-miss-facts.js +101 -0
  50. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  51. package/dist/services/observability/near-miss-gate-events.js +106 -0
  52. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  53. package/dist/services/observability/near-miss-gates.js +135 -0
  54. package/dist/services/observability/near-miss-records.d.ts +93 -0
  55. package/dist/services/observability/near-miss-records.js +87 -0
  56. package/dist/services/observability/near-miss.d.ts +148 -0
  57. package/dist/services/observability/near-miss.js +196 -0
  58. package/dist/services/observability/observability-schema.d.ts +17 -2
  59. package/dist/services/observability/observability-schema.js +21 -1
  60. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  61. package/dist/services/observability/owner-skill-map.js +144 -0
  62. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  63. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  64. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  65. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  66. package/dist/services/observability/report-formatter.d.ts +49 -3
  67. package/dist/services/observability/report-formatter.js +55 -14
  68. package/dist/services/observability/retro-attribution.d.ts +129 -0
  69. package/dist/services/observability/retro-attribution.js +134 -0
  70. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  71. package/dist/services/observability/session-metric-rows.js +184 -0
  72. package/package.json +5 -5
@@ -15,7 +15,21 @@
15
15
  */
16
16
  import { z } from 'zod';
17
17
  export declare const OBSERVABILITY_SCHEMA_VERSION: 1;
18
- export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"];
18
+ /**
19
+ * The event vocabulary every observability record is drawn from.
20
+ *
21
+ * EVERY CATEGORY MUST BE ABLE TO NAME ITS TRIGGER. A category that cannot say
22
+ * what makes it fire is a promise the schema makes and the program does not
23
+ * keep. The audit that records, for every category, where it is emitted, what
24
+ * triggers it and whether it has ever fired, lives at
25
+ * `.peaks/docs/observability-category-audit.md`; a category added to this list
26
+ * joins that table in the same change that declares it.
27
+ *
28
+ * THE ORDER IS THE ON-DISK ORDER, and the list is APPENDED, never reordered:
29
+ * a reader that stores a category by its index must never watch its meaning
30
+ * change under it.
31
+ */
32
+ export declare const OBSERVABILITY_CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease", "gate"];
19
33
  export type ObservabilityCategory = (typeof OBSERVABILITY_CATEGORIES)[number];
20
34
  export declare const OBSERVABILITY_SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
21
35
  export type ObservabilitySubagentRole = (typeof OBSERVABILITY_SUBAGENT_ROLES)[number];
@@ -24,6 +38,7 @@ export declare const ObservabilityEventSchema: z.ZodObject<{
24
38
  ts: z.ZodString;
25
39
  sessionId: z.ZodString;
26
40
  category: z.ZodEnum<{
41
+ gate: "gate";
27
42
  "slice-transition": "slice-transition";
28
43
  dispatch: "dispatch";
29
44
  checkpoint: "checkpoint";
@@ -66,6 +81,6 @@ export type EmitResult = {
66
81
  };
67
82
  export declare const OBSERVABILITY_CONSTANTS: {
68
83
  readonly SCHEMA_VERSION: 1;
69
- readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"];
84
+ readonly CATEGORIES: readonly ["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease", "gate"];
70
85
  readonly SUBAGENT_ROLES: readonly ["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"];
71
86
  };
@@ -15,6 +15,20 @@
15
15
  */
16
16
  import { z } from 'zod';
17
17
  export const OBSERVABILITY_SCHEMA_VERSION = 1;
18
+ /**
19
+ * The event vocabulary every observability record is drawn from.
20
+ *
21
+ * EVERY CATEGORY MUST BE ABLE TO NAME ITS TRIGGER. A category that cannot say
22
+ * what makes it fire is a promise the schema makes and the program does not
23
+ * keep. The audit that records, for every category, where it is emitted, what
24
+ * triggers it and whether it has ever fired, lives at
25
+ * `.peaks/docs/observability-category-audit.md`; a category added to this list
26
+ * joins that table in the same change that declares it.
27
+ *
28
+ * THE ORDER IS THE ON-DISK ORDER, and the list is APPENDED, never reordered:
29
+ * a reader that stores a category by its index must never watch its meaning
30
+ * change under it.
31
+ */
18
32
  export const OBSERVABILITY_CATEGORIES = [
19
33
  'slice-transition',
20
34
  'dispatch',
@@ -30,7 +44,13 @@ export const OBSERVABILITY_CATEGORIES = [
30
44
  // 3.A). Read by `peaks lease metrics`. The `detail.kind` field
31
45
  // discriminates spawn / renew / release / gc / autoRelease /
32
46
  // autoRelease-failed / autoRelease-skipped.
33
- 'lease'
47
+ 'lease',
48
+ // The RD transition gates' verdicts. One event per gate DECISION, so a
49
+ // reader can ask which gate was never evaluated: `detail.gateId` names it
50
+ // ('file-size-ratchet' / 'declared-type-corroboration' / 'claim-table'),
51
+ // `detail.outcome` says what it decided ('pass' / 'block' / 'bypass').
52
+ // APPENDED, so no existing category's index shifts.
53
+ 'gate'
34
54
  ];
35
55
  // v2.12.0 fan-out collapse: `security-reviewer` (in-process RD slot)
36
56
  // moved out to the standalone `peaks-security-audit` skill; the matching
@@ -0,0 +1,92 @@
1
+ /**
2
+ * `src/services/observability/owner-skill-map.ts`
3
+ *
4
+ * The path → owning-skill lookup. An artifact path says WHAT is missing;
5
+ * this table says WHO was supposed to produce it, so a reader of the
6
+ * observability stream can name the skill that failed to deliver rather
7
+ * than only counting the failure.
8
+ *
9
+ * WHY A TABLE AND NOT A RULE. The artifact directories are not derivable
10
+ * from the path shape: `audit/security-<rid>.md` and `audit/perf-<rid>.md`
11
+ * live under the same directory and belong to two different skills, and a
12
+ * rule that said "anything under `audit/` is an audit artifact" would name
13
+ * neither. The table states the ownership explicitly, and the more specific
14
+ * prefix wins when two could match.
15
+ *
16
+ * WHY THERE IS NO `audit/` CATCH-ALL. A directory-level entry for `audit/`
17
+ * would attribute both audit artifacts to one skill, which is the
18
+ * ambiguity this table exists to remove. The audit entries are the
19
+ * specific ones instead — one per artifact, and one per location that
20
+ * artifact is written at.
21
+ *
22
+ * WHY THE LOOKUP ANSWERS `null`. A path has no owner that this table can
23
+ * name, and a guessed owner is worse than none: it would put a skill's name
24
+ * on an artifact that skill never produces. The paths that are genuinely
25
+ * ownerless are listed in `UNOWNED_PATH_ENTRIES` with the reason, so that
26
+ * "no owner" is always a stated fact and never a gap.
27
+ *
28
+ * TWO KINDS OF ROW. A row is a PREFIX claim by default — the path starts
29
+ * with it — and an EXACT claim when it says so. The exact rows exist for
30
+ * the bare, file-shaped legacy locations: a prefix claim on a file name
31
+ * would also claim every file whose name merely starts with it, and an
32
+ * artifact that was never produced must not be attributed to the skill
33
+ * that owns a different file with a similar name.
34
+ *
35
+ * THE `gateEvidence.*` ROWS ARE DECLARATION KEYS, NOT PATHS. The handoff
36
+ * capsule declares the evidence Gate C will check, and a declared key that
37
+ * names a file that is not on disk reaches the missing list under the key's
38
+ * own name. The owner of a key is the skill that produces the evidence the
39
+ * key names — the same question the artifact rows answer, asked of a
40
+ * declaration instead of a file.
41
+ */
42
+ /** One row of the map: a path prefix and the skill that owns what it names. */
43
+ export type OwnerSkillEntry = {
44
+ readonly prefix: string;
45
+ readonly skill: string;
46
+ /**
47
+ * True when `prefix` names ONE file rather than a directory of files: the
48
+ * match is the whole path, not its start.
49
+ */
50
+ readonly exact?: boolean;
51
+ };
52
+ /**
53
+ * The map, in declaration order. The LOOKUP sorts by prefix length, so this
54
+ * order is documentation, not the resolution order.
55
+ */
56
+ export declare const OWNER_SKILL_ENTRIES: readonly OwnerSkillEntry[];
57
+ /**
58
+ * A shape of path that has no owning skill, and the reason it has none.
59
+ *
60
+ * The list exists so that "no owner" is a STATED fact. A path that reaches
61
+ * the missing list and is neither in the map nor here is a hole, and the
62
+ * census test is what turns that hole into a red test.
63
+ */
64
+ export type UnownedPathEntry = {
65
+ /** The path prefix that identifies the shape. */
66
+ readonly prefix: string;
67
+ /** Why no skill owns a path of this shape. */
68
+ readonly reason: string;
69
+ };
70
+ /**
71
+ * The paths that have no owner, and why.
72
+ *
73
+ * `gateEvidence(<status>)` is a handoff capsule whose declaration cannot be
74
+ * read. It is not an artifact: no skill produces a broken capsule, so there
75
+ * is no owner to name — the defect belongs to whoever wrote the capsule, and
76
+ * the gate reports it as a body failure on the capsule itself.
77
+ */
78
+ export declare const UNOWNED_PATH_ENTRIES: readonly UnownedPathEntry[];
79
+ /**
80
+ * The skill that owns the artifact at `path`, or `null` when no row claims
81
+ * it.
82
+ *
83
+ * Total over every input: a value that is not a string answers `null` rather
84
+ * than raising, because this runs inside the observability emit, whose
85
+ * contract is that it never throws and never changes the caller's decision.
86
+ */
87
+ export declare function ownerSkillForPath(path: string): string | null;
88
+ /**
89
+ * The reason the path at `path` has no owning skill, or `null` when the
90
+ * path is not one of the known ownerless shapes.
91
+ */
92
+ export declare function unownedPathReason(path: string): string | null;
@@ -0,0 +1,144 @@
1
+ /**
2
+ * `src/services/observability/owner-skill-map.ts`
3
+ *
4
+ * The path → owning-skill lookup. An artifact path says WHAT is missing;
5
+ * this table says WHO was supposed to produce it, so a reader of the
6
+ * observability stream can name the skill that failed to deliver rather
7
+ * than only counting the failure.
8
+ *
9
+ * WHY A TABLE AND NOT A RULE. The artifact directories are not derivable
10
+ * from the path shape: `audit/security-<rid>.md` and `audit/perf-<rid>.md`
11
+ * live under the same directory and belong to two different skills, and a
12
+ * rule that said "anything under `audit/` is an audit artifact" would name
13
+ * neither. The table states the ownership explicitly, and the more specific
14
+ * prefix wins when two could match.
15
+ *
16
+ * WHY THERE IS NO `audit/` CATCH-ALL. A directory-level entry for `audit/`
17
+ * would attribute both audit artifacts to one skill, which is the
18
+ * ambiguity this table exists to remove. The audit entries are the
19
+ * specific ones instead — one per artifact, and one per location that
20
+ * artifact is written at.
21
+ *
22
+ * WHY THE LOOKUP ANSWERS `null`. A path has no owner that this table can
23
+ * name, and a guessed owner is worse than none: it would put a skill's name
24
+ * on an artifact that skill never produces. The paths that are genuinely
25
+ * ownerless are listed in `UNOWNED_PATH_ENTRIES` with the reason, so that
26
+ * "no owner" is always a stated fact and never a gap.
27
+ *
28
+ * TWO KINDS OF ROW. A row is a PREFIX claim by default — the path starts
29
+ * with it — and an EXACT claim when it says so. The exact rows exist for
30
+ * the bare, file-shaped legacy locations: a prefix claim on a file name
31
+ * would also claim every file whose name merely starts with it, and an
32
+ * artifact that was never produced must not be attributed to the skill
33
+ * that owns a different file with a similar name.
34
+ *
35
+ * THE `gateEvidence.*` ROWS ARE DECLARATION KEYS, NOT PATHS. The handoff
36
+ * capsule declares the evidence Gate C will check, and a declared key that
37
+ * names a file that is not on disk reaches the missing list under the key's
38
+ * own name. The owner of a key is the skill that produces the evidence the
39
+ * key names — the same question the artifact rows answer, asked of a
40
+ * declaration instead of a file.
41
+ */
42
+ /**
43
+ * The map, in declaration order. The LOOKUP sorts by prefix length, so this
44
+ * order is documentation, not the resolution order.
45
+ */
46
+ export const OWNER_SKILL_ENTRIES = [
47
+ { prefix: 'gateEvidence.codeReview', skill: 'peaks-rd' },
48
+ { prefix: 'gateEvidence.perfBaseline', skill: 'peaks-perf-audit' },
49
+ { prefix: 'gateEvidence.prdHandoff', skill: 'peaks-prd' },
50
+ // The project scan is Gate A's artifact, and Gate A belongs to the
51
+ // orchestrator: `skills/peaks-code/SKILL.md` carries it as the MANDATORY
52
+ // "Pre-RD project scan checklist", and
53
+ // `skills/peaks-code/references/project-scan-checklist.md` opens with
54
+ // "Before handing off to `peaks-rd`, scan the project and record findings
55
+ // to `.peaks/project-scan/project-scan.md`". The declared path is that
56
+ // file, so the skill that writes it is the one that owns the key.
57
+ { prefix: 'gateEvidence.projectScan', skill: 'peaks-code' },
58
+ // The security review evidence. For the fanout types the key declares
59
+ // `audit/security-<rid>.md`, which the independent security audit writes;
60
+ // for the `config` type it declares the config-specific
61
+ // `rd/security-review-<rid>.md`, which is an RD artifact. One key, one
62
+ // answer — the row names the skill that owns the security review as a
63
+ // concept, which is the audit skill for every type that reaches it.
64
+ { prefix: 'gateEvidence.securityReview', skill: 'peaks-security-audit' },
65
+ { prefix: 'audit/security-', skill: 'peaks-security-audit' },
66
+ // The bare security audit location — the one that predates the request id
67
+ // in the filename. It is a live tier, not a guess: the judged-declaration
68
+ // check resolves the audit artifact through `securityArtifactTiers`, and
69
+ // that list's second entry is this file — so a session holding it puts that
70
+ // path into the missing list, and a row that did not claim it would leave
71
+ // that missing artifact with no owner. EXACT, because the row claims this
72
+ // one file and not every file whose name begins with it.
73
+ { prefix: 'audit/security.md', skill: 'peaks-security-audit', exact: true },
74
+ { prefix: 'audit/perf-', skill: 'peaks-perf-audit' },
75
+ // The bare perf audit location — the sibling of the security one above,
76
+ // and the same story: the resolver probes it as a legacy tier.
77
+ { prefix: 'audit/perf.md', skill: 'peaks-perf-audit', exact: true },
78
+ { prefix: 'prd/', skill: 'peaks-prd' },
79
+ { prefix: 'ui/', skill: 'peaks-ui' },
80
+ { prefix: 'rd/', skill: 'peaks-rd' },
81
+ // The third-party review is the REVIEWER's artifact, not RD's: the prereq
82
+ // that demands it names the skill that writes it ("v2.14.0 G4 third-party
83
+ // reviewer (peaks-reviewer skill)"). The `rd/` row above is a DIRECTORY
84
+ // claim, so without this row it over-claimed this file and named the wrong
85
+ // skill to fix.
86
+ { prefix: 'rd/third-party-review-', skill: 'peaks-reviewer' },
87
+ { prefix: 'qa/', skill: 'peaks-qa' },
88
+ { prefix: 'sc/', skill: 'peaks-sc' },
89
+ { prefix: 'mut/', skill: 'peaks-mut' }
90
+ ];
91
+ /**
92
+ * The same rows, most specific prefix first. A longer prefix is a narrower
93
+ * claim, so it is tried first — that is what keeps `audit/security.md` ahead
94
+ * of `audit/security-`, and both ahead of a shorter prefix that would also
95
+ * match them.
96
+ */
97
+ const ENTRIES_BY_SPECIFICITY = [...OWNER_SKILL_ENTRIES].sort((a, b) => b.prefix.length - a.prefix.length);
98
+ /**
99
+ * The paths that have no owner, and why.
100
+ *
101
+ * `gateEvidence(<status>)` is a handoff capsule whose declaration cannot be
102
+ * read. It is not an artifact: no skill produces a broken capsule, so there
103
+ * is no owner to name — the defect belongs to whoever wrote the capsule, and
104
+ * the gate reports it as a body failure on the capsule itself.
105
+ */
106
+ export const UNOWNED_PATH_ENTRIES = [
107
+ {
108
+ prefix: 'gateEvidence(',
109
+ reason: 'a handoff capsule whose gateEvidence declaration cannot be read is not an artifact ' +
110
+ 'any skill produces — the defect belongs to whoever wrote the capsule, so there is ' +
111
+ 'no owning skill to name'
112
+ }
113
+ ];
114
+ /**
115
+ * The skill that owns the artifact at `path`, or `null` when no row claims
116
+ * it.
117
+ *
118
+ * Total over every input: a value that is not a string answers `null` rather
119
+ * than raising, because this runs inside the observability emit, whose
120
+ * contract is that it never throws and never changes the caller's decision.
121
+ */
122
+ export function ownerSkillForPath(path) {
123
+ if (typeof path !== 'string')
124
+ return null;
125
+ for (const entry of ENTRIES_BY_SPECIFICITY) {
126
+ const claimed = entry.exact === true ? path === entry.prefix : path.startsWith(entry.prefix);
127
+ if (claimed)
128
+ return entry.skill;
129
+ }
130
+ return null;
131
+ }
132
+ /**
133
+ * The reason the path at `path` has no owning skill, or `null` when the
134
+ * path is not one of the known ownerless shapes.
135
+ */
136
+ export function unownedPathReason(path) {
137
+ if (typeof path !== 'string')
138
+ return null;
139
+ for (const entry of UNOWNED_PATH_ENTRIES) {
140
+ if (path.startsWith(entry.prefix))
141
+ return entry.reason;
142
+ }
143
+ return null;
144
+ }
@@ -0,0 +1,32 @@
1
+ /**
2
+ * `src/services/observability/report-formatter-hotspots.ts`
3
+ *
4
+ * The hotspot section of the markdown report.
5
+ *
6
+ * WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
7
+ * 300-line cap, and the hotspot table does not fit beside the rest. The
8
+ * split follows the precedent in this directory: `aggregation.ts` keeps its
9
+ * readers in `aggregation-helpers.ts` for the same reason.
10
+ *
11
+ * WHY THE TABLES ARE SPLIT BY WHAT THE COUNT COUNTS. A hotspot row's count
12
+ * means DIFFERENT THINGS depending on how the row was known: an `exact` row
13
+ * counted the artifact being MISSING, and a reconstructed row counted the
14
+ * artifact being one of the CANDIDATES — one real failure contributes to
15
+ * every candidate the attribution could not narrow, so the number is candidate
16
+ * mentions, not failures. A single column cannot carry both meanings, so a
17
+ * reader of one column heading would have to know the rule to read the
18
+ * number under it.
19
+ *
20
+ * So there is ONE TABLE PER MEANING, and each column heading names what it
21
+ * counts: "times observed missing" and "candidate mentions". The confidence
22
+ * column stays as it is, so a reader can still see WHICH tier a row came
23
+ * from — the split makes the meaning visible without taking that away.
24
+ *
25
+ * WHY THE NOTE IS NOT THE WHOLE MECHANISM. The note says what the two
26
+ * meanings are; the column headings say which one a reader is looking at. A
27
+ * reader who skips the note still cannot take a candidate mention for a
28
+ * missing artifact.
29
+ */
30
+ import { type HotspotRow } from './hotspot-shared.js';
31
+ /** The markdown for the hotspot section, including its heading. */
32
+ export declare function markdownHotspotTables(hotspots: readonly HotspotRow[]): string;
@@ -0,0 +1,76 @@
1
+ /**
2
+ * `src/services/observability/report-formatter-hotspots.ts`
3
+ *
4
+ * The hotspot section of the markdown report.
5
+ *
6
+ * WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
7
+ * 300-line cap, and the hotspot table does not fit beside the rest. The
8
+ * split follows the precedent in this directory: `aggregation.ts` keeps its
9
+ * readers in `aggregation-helpers.ts` for the same reason.
10
+ *
11
+ * WHY THE TABLES ARE SPLIT BY WHAT THE COUNT COUNTS. A hotspot row's count
12
+ * means DIFFERENT THINGS depending on how the row was known: an `exact` row
13
+ * counted the artifact being MISSING, and a reconstructed row counted the
14
+ * artifact being one of the CANDIDATES — one real failure contributes to
15
+ * every candidate the attribution could not narrow, so the number is candidate
16
+ * mentions, not failures. A single column cannot carry both meanings, so a
17
+ * reader of one column heading would have to know the rule to read the
18
+ * number under it.
19
+ *
20
+ * So there is ONE TABLE PER MEANING, and each column heading names what it
21
+ * counts: "times observed missing" and "candidate mentions". The confidence
22
+ * column stays as it is, so a reader can still see WHICH tier a row came
23
+ * from — the split makes the meaning visible without taking that away.
24
+ *
25
+ * WHY THE NOTE IS NOT THE WHOLE MECHANISM. The note says what the two
26
+ * meanings are; the column headings say which one a reader is looking at. A
27
+ * reader who skips the note still cannot take a candidate mention for a
28
+ * missing artifact.
29
+ */
30
+ import { groupHotspotsByMeaning } from './hotspot-shared.js';
31
+ /** The markdown for the hotspot section, including its heading. */
32
+ export function markdownHotspotTables(hotspots) {
33
+ const lines = [];
34
+ lines.push('## Hotspots');
35
+ lines.push('');
36
+ if (hotspots.length === 0) {
37
+ lines.push('_No hotspot recorded for this period._');
38
+ lines.push('');
39
+ return lines.join('\n');
40
+ }
41
+ lines.push('_`exact` rows are MEASURED — the artifact was seen missing. `inferred`/`ambiguous` ' +
42
+ 'rows are CANDIDATES recovered from a historical count: one real failure counts toward ' +
43
+ 'EVERY candidate it could not narrow, so those counts are candidate mentions, not ' +
44
+ 'failures._');
45
+ lines.push('');
46
+ // The SAME split the CLI's JSON payload uses, so the two surfaces cannot
47
+ // disagree about which rows are measurements and which are candidates.
48
+ const groups = groupHotspotsByMeaning(hotspots);
49
+ table(lines, groups.observedOmissions, 'Measured missing artifacts', 'times observed missing');
50
+ table(lines, groups.candidateMentions, 'Candidate artifacts', 'candidate mentions');
51
+ return lines.join('\n');
52
+ }
53
+ /** One table of rows, under a heading that names what its count counts. */
54
+ function table(lines, rows, heading, column) {
55
+ lines.push(`### ${heading}`);
56
+ lines.push('');
57
+ if (rows.length === 0) {
58
+ lines.push('_None._');
59
+ lines.push('');
60
+ return;
61
+ }
62
+ lines.push(`| artifact | owner skill | mode | confidence | ${column} |`);
63
+ lines.push('|---|---|---|---|---|');
64
+ for (const row of rows) {
65
+ lines.push(`| ${row.artifact} | ${row.ownerSkill ?? '—'} | ${row.kind} | ${row.confidence} | ${row.count} |`);
66
+ }
67
+ lines.push('');
68
+ // A row with no owner says WHY below the table: "no skill owns this" is a
69
+ // stated fact with a reason, not a gap the reader has to guess at.
70
+ for (const row of rows) {
71
+ if (row.ownerReason === null)
72
+ continue;
73
+ lines.push(`_\`${row.artifact}\` has no owning skill: ${row.ownerReason}_`);
74
+ lines.push('');
75
+ }
76
+ }
@@ -0,0 +1,48 @@
1
+ /**
2
+ * `src/services/observability/report-formatter-near-miss.ts`
3
+ *
4
+ * The near-miss section of the markdown report.
5
+ *
6
+ * WHY IT IS ITS OWN MODULE. `report-formatter.ts` was already near its
7
+ * 300-line cap, and this section does not fit beside the rest of it. The
8
+ * split follows the precedent in this directory: the hotspot section lives
9
+ * in `report-formatter-hotspots.ts` for the same reason.
10
+ *
11
+ * WHY THE RATE NEVER APPEARS ALONE. The report is what leaves the terminal
12
+ * — it gets pasted into a PR description — so a number in it has to be read
13
+ * the way it was measured. The near-miss rate is measured over the reason
14
+ * classes the scope had events for, and a scope can hold events for ONE of
15
+ * the three classes: the `gate` emitter postdates every session in this
16
+ * repository's recorded history, so two of the three classes have no events
17
+ * at all there.
18
+ *
19
+ * A rate printed on its own is therefore ambiguous between "there were no
20
+ * near-misses" and "the classes that could have shown a near-miss were never
21
+ * observed" — and the second reading is an ABSENCE read as a RESULT, which
22
+ * is the exact failure this whole programme exists to close. So the rate line
23
+ * carries its coverage with it: how many of the reason classes the rate was
24
+ * measured over, and that the rest is an absence of data rather than a
25
+ * result. A reader who sees ONLY the rate line still cannot draw the wrong
26
+ * conclusion.
27
+ *
28
+ * WHY THE COVERAGE IS A TABLE. Each class's rate divides by the slices THAT
29
+ * CLASS REACHED, not by every passing slice, so the class's own population
30
+ * has to travel with its number. The table says, per class: whether the class
31
+ * was observable at all, how many events it had, how many slices it reached,
32
+ * how many it flagged, and the rate it supports — or `not measured`, which is
33
+ * what a class with no events gets instead of a zero. It also says how many
34
+ * slices said NOTHING about the class: those slices could not be judged on it,
35
+ * and they are the ones a skipped check would hide in.
36
+ *
37
+ * WHY THE FLAGGED SLICES ARE LISTED. The count has to have a referent: a
38
+ * reader who is told that one slice passed with a check unsatisfied has to
39
+ * be able to see WHICH slice and WHICH check.
40
+ */
41
+ import type { NearMissReport } from './near-miss.js';
42
+ /**
43
+ * The markdown for the near-miss section, including its heading.
44
+ *
45
+ * The section is rendered ONLY when the caller supplies the measurement, so a
46
+ * caller that does not compute it gets exactly the report it got before.
47
+ */
48
+ export declare function markdownNearMissSection(nearMiss: NearMissReport): string;