peaks-loop 4.1.22 → 4.1.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/.claude-plugin/marketplace.json +12 -2
  2. package/CHANGELOG.md +184 -0
  3. package/dist/cli/commands/code-auto-compact-command.js +19 -1
  4. package/dist/cli/commands/code-gate-step-08-command.js +103 -105
  5. package/dist/cli/commands/code-gate-step-08-remedy.d.ts +10 -2
  6. package/dist/cli/commands/code-gate-step-08-remedy.js +11 -3
  7. package/dist/cli/commands/gate-commands-enforce.d.ts +23 -8
  8. package/dist/cli/commands/gate-commands-enforce.js +27 -12
  9. package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
  10. package/dist/cli/commands/observability-commands-hotspots.js +222 -0
  11. package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
  12. package/dist/cli/commands/observability-commands-near-miss.js +105 -0
  13. package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
  14. package/dist/cli/commands/observability-commands-queries.js +88 -47
  15. package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
  16. package/dist/cli/commands/observability-commands-session-row.js +201 -0
  17. package/dist/cli/commands/observability-commands.js +81 -20
  18. package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
  19. package/dist/services/artifacts/artifact-prerequisites.js +1 -1
  20. package/dist/services/artifacts/prerequisite-path-census.d.ts +47 -0
  21. package/dist/services/artifacts/prerequisite-path-census.js +100 -0
  22. package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
  23. package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
  24. package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
  25. package/dist/services/artifacts/rd-gate-event.js +211 -0
  26. package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
  27. package/dist/services/artifacts/rd-transition-gates.js +65 -24
  28. package/dist/services/hooks/output.d.ts +67 -1
  29. package/dist/services/hooks/output.js +74 -1
  30. package/dist/services/observability/aggregation-types.d.ts +21 -0
  31. package/dist/services/observability/aggregation.d.ts +12 -2
  32. package/dist/services/observability/aggregation.js +28 -3
  33. package/dist/services/observability/compliance-judge.d.ts +77 -0
  34. package/dist/services/observability/compliance-judge.js +143 -0
  35. package/dist/services/observability/compliance-spec.d.ts +96 -0
  36. package/dist/services/observability/compliance-spec.js +29 -0
  37. package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
  38. package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
  39. package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
  40. package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
  41. package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
  42. package/dist/services/observability/hotspot-attribution-summary.js +74 -0
  43. package/dist/services/observability/hotspot-rows.d.ts +47 -0
  44. package/dist/services/observability/hotspot-rows.js +89 -0
  45. package/dist/services/observability/hotspot-shared.d.ts +207 -0
  46. package/dist/services/observability/hotspot-shared.js +127 -0
  47. package/dist/services/observability/hotspot-sources.d.ts +55 -0
  48. package/dist/services/observability/hotspot-sources.js +142 -0
  49. package/dist/services/observability/hotspots.d.ts +47 -0
  50. package/dist/services/observability/hotspots.js +47 -0
  51. package/dist/services/observability/near-miss-attempts.d.ts +175 -0
  52. package/dist/services/observability/near-miss-attempts.js +223 -0
  53. package/dist/services/observability/near-miss-coverage.d.ts +109 -0
  54. package/dist/services/observability/near-miss-coverage.js +108 -0
  55. package/dist/services/observability/near-miss-denominator.d.ts +81 -0
  56. package/dist/services/observability/near-miss-denominator.js +75 -0
  57. package/dist/services/observability/near-miss-difference.d.ts +98 -0
  58. package/dist/services/observability/near-miss-difference.js +135 -0
  59. package/dist/services/observability/near-miss-facts.d.ts +165 -0
  60. package/dist/services/observability/near-miss-facts.js +101 -0
  61. package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
  62. package/dist/services/observability/near-miss-gate-events.js +106 -0
  63. package/dist/services/observability/near-miss-gates.d.ts +108 -0
  64. package/dist/services/observability/near-miss-gates.js +135 -0
  65. package/dist/services/observability/near-miss-records.d.ts +93 -0
  66. package/dist/services/observability/near-miss-records.js +87 -0
  67. package/dist/services/observability/near-miss.d.ts +148 -0
  68. package/dist/services/observability/near-miss.js +203 -0
  69. package/dist/services/observability/observability-schema.d.ts +17 -2
  70. package/dist/services/observability/observability-schema.js +21 -1
  71. package/dist/services/observability/owner-skill-map.d.ts +92 -0
  72. package/dist/services/observability/owner-skill-map.js +164 -0
  73. package/dist/services/observability/repair-cycle-metric.js +6 -3
  74. package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
  75. package/dist/services/observability/report-formatter-hotspots.js +76 -0
  76. package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
  77. package/dist/services/observability/report-formatter-near-miss.js +234 -0
  78. package/dist/services/observability/report-formatter.d.ts +49 -3
  79. package/dist/services/observability/report-formatter.js +55 -14
  80. package/dist/services/observability/retro-attribution.d.ts +129 -0
  81. package/dist/services/observability/retro-attribution.js +134 -0
  82. package/dist/services/observability/session-metric-rows.d.ts +153 -0
  83. package/dist/services/observability/session-metric-rows.js +184 -0
  84. package/dist/services/skills/presence-role.js +9 -2
  85. package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
  86. package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
  87. package/dist/shared/incrementing-number.d.ts +57 -0
  88. package/dist/shared/incrementing-number.js +13 -0
  89. package/dist/skills/peaks-maker/index.js +43 -30
  90. package/output-styles/peaks-skill-swarm.md +2 -2
  91. package/package.json +5 -5
  92. package/scripts/install-skills-bundles.mjs +6 -1
  93. package/scripts/install-skills.mjs +10 -1
  94. package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
  95. package/skills/bee/peaks-prd/SKILL.md +1 -1
  96. package/skills/bee/peaks-qa/SKILL.md +1 -1
  97. package/skills/bee/peaks-rd/SKILL.md +1 -1
  98. package/skills/bee/peaks-reviewer/SKILL.md +1 -1
  99. package/skills/bee/peaks-sc/SKILL.md +1 -1
  100. package/skills/bee/peaks-security-audit/SKILL.md +1 -1
  101. package/skills/bee/peaks-txt/SKILL.md +1 -1
  102. package/skills/bee/peaks-ui/SKILL.md +1 -1
  103. package/skills/peaks-audit/SKILL.md +1 -1
  104. package/skills/peaks-code/SKILL.md +1 -1
  105. package/skills/peaks-content/SKILL.md +1 -1
  106. package/skills/peaks-doctor/SKILL.md +1 -1
  107. package/skills/peaks-final-review/SKILL.md +1 -1
  108. package/skills/peaks-ide/SKILL.md +1 -1
  109. package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
  110. package/skills/peaks-maker/SKILL.md +125 -0
  111. package/skills/peaks-mut/SKILL.md +297 -0
  112. package/skills/peaks-race-code/SKILL.md +1 -1
  113. package/skills/peaks-resume/SKILL.md +1 -1
  114. package/skills/peaks-slice-decompose/SKILL.md +1 -1
  115. package/skills/peaks-solo/SKILL.md +1 -1
  116. package/skills/peaks-sop/SKILL.md +1 -1
  117. package/skills/peaks-status/SKILL.md +1 -1
  118. package/skills/peaks-test/SKILL.md +1 -1
@@ -0,0 +1,134 @@
1
+ /**
2
+ * `src/services/observability/retro-attribution.ts`
3
+ *
4
+ * Retro-attribution: name the artifacts behind the historical failures that
5
+ * recorded only a COUNT.
6
+ *
7
+ * WHY THIS EXISTS. Every slice-transition event carries `detail.missingCount`.
8
+ * The v1 events in this repository's own event log were written before the
9
+ * emitter kept the missing-artifact LIST, so the list they name is not in the
10
+ * record, and no amount of reading the record will produce it.
11
+ *
12
+ * WHAT CAN BE DERIVED INSTEAD. The prerequisite table is a pure function of
13
+ * three values — the artifact role, the target state and the request type —
14
+ * and a v1 event carries the first two. Re-deriving the table for that
15
+ * transition yields the CANDIDATE set: the artifacts the missing entries could
16
+ * be. The recorded count then says how many artifacts were missing in total,
17
+ * which is what decides whether the candidates can be narrowed.
18
+ *
19
+ * WHY THE CONFIDENCE IS CAPPED AT `inferred`. The derivation runs over
20
+ * TODAY's prerequisite table, and the table is version-controlled code that
21
+ * changes between two recorded events. A retro-attribution is therefore a
22
+ * reconstruction, not a measurement, so `exact` — which means "observed when
23
+ * it happened" — is never returned here. Only a forward event that stored the
24
+ * missing list as it was observed can carry it.
25
+ *
26
+ * WHY A COUNT MAY EXCEED THE TABLE. The recorded count is not the table's row
27
+ * count: the missing list is also fed by the judged-declaration refusals (the
28
+ * security artifact's own location) and by the handoff capsule's gate-evidence
29
+ * declaration (a key naming a file that is not on disk). Neither of those two
30
+ * sources is derivable from what a v1 event stores, so a count larger than
31
+ * the table's list yields `ambiguous` with the table's entries as the
32
+ * candidates. The candidate set is never widened with a guess, and the
33
+ * confidence never rises to cover the gap.
34
+ */
35
+ import { getPrerequisitesFor, isRequestType } from '../artifacts/artifact-prerequisites.js';
36
+ import { ownerSkillForPath } from './owner-skill-map.js';
37
+ /**
38
+ * The prereq list for one transition, or an empty list when the request type
39
+ * is not one the table knows.
40
+ *
41
+ * The table is indexed by request type, and an event's type arrives from a
42
+ * file this module does not own — so an unknown type must answer an empty
43
+ * list rather than raise inside a read path.
44
+ *
45
+ * The published parameter is a `RequestType`, so this arm is reachable only
46
+ * from a caller that ignores the signature.
47
+ */
48
+ function prerequisitesFor(role, newState, requestType) {
49
+ if (!isRequestType(requestType))
50
+ return [];
51
+ return getPrerequisitesFor(role, newState, requestType);
52
+ }
53
+ /**
54
+ * The recorded count, or `null` when it cannot be read as a count.
55
+ *
56
+ * A count that is missing, negative or not a number says nothing about how
57
+ * many artifacts were missing, so the candidate set cannot be narrowed by it.
58
+ *
59
+ * The published parameter is a `number`, so this arm is reachable only from a
60
+ * caller that ignores the signature.
61
+ */
62
+ function readableCount(value) {
63
+ if (typeof value !== 'number')
64
+ return null;
65
+ if (!Number.isFinite(value))
66
+ return null;
67
+ if (value < 0)
68
+ return null;
69
+ return value;
70
+ }
71
+ /**
72
+ * The candidate list of one transition, in the table's own order.
73
+ *
74
+ * The path is the table's `relativePath` TEMPLATE, with the `<rid>`
75
+ * placeholder still in it: the transition that produced the event is not
76
+ * available here, so the template is the most specific path that can be
77
+ * named. The owner lookup is a prefix match, so the placeholder does not
78
+ * affect it.
79
+ */
80
+ function candidatesFor(prereqs) {
81
+ return prereqs.map((prereq) => ({
82
+ path: prereq.relativePath,
83
+ ownerSkill: ownerSkillForPath(prereq.relativePath)
84
+ }));
85
+ }
86
+ /**
87
+ * Attribute one historical failure to the artifacts that could have been
88
+ * missing.
89
+ *
90
+ * The rules, in the order they apply:
91
+ *
92
+ * - a transition the table demands nothing for → `ambiguous`, no candidate;
93
+ * - a count that cannot be read → `ambiguous`, the whole list as candidates;
94
+ * - a count of zero → `ambiguous`, no candidate (the record says nothing
95
+ * was missing, so naming a candidate would contradict it);
96
+ * - a count equal to the list's length → `inferred`, the whole list;
97
+ * - any other count → `ambiguous`, the whole list as candidates.
98
+ *
99
+ * WHAT `inferred` CLAIMS AT THE THIRD RULE. The count matches the table's
100
+ * length, so the count is CONSISTENT WITH the whole list being the missing
101
+ * set — and it is not proof of that. The missing list has three sources (the
102
+ * prereq table, the judged-declaration refusals, the gate-evidence
103
+ * declaration), and a count equal to the table's length can match by
104
+ * coincidence while the missing entries came from the other two, leaving a
105
+ * table entry intact. The same holds for a one-entry list and a count of one:
106
+ * the single missing entry may have come from source two or three. So the
107
+ * label says "the count does not contradict this set", and never "these
108
+ * artifacts were proven missing".
109
+ *
110
+ * The last rule covers a count of one against a list of several, a count
111
+ * between zero and the list's length, and a count ABOVE the list's length —
112
+ * the last because the missing list has two further sources the table does
113
+ * not describe, and neither of them is derivable from a v1 event.
114
+ *
115
+ * This function never returns `exact`. That confidence belongs to a forward
116
+ * event, which recorded the missing list as it was observed; this one
117
+ * reconstructs a candidate set from today's table and can therefore only
118
+ * claim `inferred` or `ambiguous`.
119
+ */
120
+ export function attributeV1Failure(opts) {
121
+ const prereqs = prerequisitesFor(opts.artifactRole, opts.newState, opts.requestType);
122
+ const typeSource = opts.typeSource;
123
+ if (prereqs.length === 0)
124
+ return { confidence: 'ambiguous', candidates: [], typeSource };
125
+ const candidates = candidatesFor(prereqs);
126
+ const count = readableCount(opts.missingCount);
127
+ if (count === null)
128
+ return { confidence: 'ambiguous', candidates, typeSource };
129
+ if (count === 0)
130
+ return { confidence: 'ambiguous', candidates: [], typeSource };
131
+ if (count === prereqs.length)
132
+ return { confidence: 'inferred', candidates, typeSource };
133
+ return { confidence: 'ambiguous', candidates, typeSource };
134
+ }
@@ -0,0 +1,153 @@
1
+ /**
2
+ * `src/services/observability/session-metric-rows.ts`
3
+ *
4
+ * WHY THIS FILE EXISTS. The raw event stream lives in gitignored session
5
+ * state, so a CI runner and a fresh clone have nothing to compare against.
6
+ * The per-session row is the TRACKED artifact that makes the numbers
7
+ * comparable across machines and across time: one JSON file per session,
8
+ * holding that session's aggregate numbers.
9
+ *
10
+ * WHAT THE ROW CARRIES, AND WHAT IT REFUSES TO CARRY. Counts and rates, and
11
+ * nothing else: no event, no free-text reason, no tool input or output. The
12
+ * event stream's `reason` field holds paths and code fragments, and a
13
+ * tracked file is the one place in this program where such text would
14
+ * outlive the session that produced it.
15
+ *
16
+ * WHY THE COMPLIANCE READING IS COMPUTED HERE. The compliance judge asks
17
+ * whether an artifact exists, and the paths it asks about carry an
18
+ * UNRESOLVED `<rid>` placeholder: the judge hands the declared path through
19
+ * verbatim, and the CALLER substitutes the request id. A caller that probes
20
+ * the raw string asks the filesystem about a path that contains the literal
21
+ * `<rid>`, every step misses, and the rate reads 0 without a single error.
22
+ * The substitution is therefore not left to the caller of this module: the
23
+ * reading is produced here, through the repository's own path resolver.
24
+ *
25
+ * WHY THE ROW IS PUBLISHED THROUGH THE SHARED ATOMIC WRITER. A tracked file
26
+ * that a later run reads must never be observed half-written, so the row is
27
+ * written to a temporary file in the same directory and renamed over the
28
+ * target — the same guarantee the lease store gives.
29
+ */
30
+ import type { ComplianceSpec } from './compliance-spec.js';
31
+ import type { HotspotRequestTypes } from './hotspot-shared.js';
32
+ import type { RequestType } from '../artifacts/artifact-prerequisites.js';
33
+ import type { ObservabilityEvent } from './observability-service.js';
34
+ /** Where a session's tracked row lives, relative to the project root. */
35
+ export declare const SESSION_METRIC_ROWS_RELATIVE_PATH = ".peaks/observability/sessions/<sessionId>.json";
36
+ /** The row's schema version. */
37
+ export declare const SESSION_METRIC_ROW_SCHEMA_VERSION = 1;
38
+ /** One slice's compliance reading, inside a session row. */
39
+ export type SessionComplianceReading = {
40
+ /** The spec that was judged. */
41
+ readonly specId: string;
42
+ /** The slice the spec was judged against. */
43
+ readonly sliceRid: string;
44
+ /** The share of the spec's REQUIRED steps that ran. */
45
+ readonly complianceRate: number;
46
+ };
47
+ /** The tracked per-session aggregate row. */
48
+ export type SessionMetricRow = {
49
+ readonly schemaVersion: 1;
50
+ readonly sessionId: string;
51
+ readonly generatedAt: string;
52
+ readonly nearMissRate: number;
53
+ readonly passedSliceCount: number;
54
+ readonly nearMissSliceCount: number;
55
+ readonly hotspotCount: number;
56
+ /**
57
+ * The request types whose passes were never GATED.
58
+ *
59
+ * The cause of the gap between the two "passed" definitions: a type whose
60
+ * prerequisite table has no `qa:verdict-issued` row has no check to verify
61
+ * that transition against, so the check emits nothing and the pass is never
62
+ * gated — not gated-and-unrecorded. The row carries the cause, because the
63
+ * row is what outlives the session: a reader holding only the tracked file
64
+ * could otherwise hunt for an emitter bug that does not exist.
65
+ */
66
+ readonly typesWithoutVerdictPrerequisite: readonly RequestType[];
67
+ readonly compliance: readonly SessionComplianceReading[];
68
+ readonly skillsBlobSha?: string;
69
+ };
70
+ /**
71
+ * Judge one slice against one compliance spec, in this session's directory.
72
+ *
73
+ * THE SUBSTITUTION HAPPENS HERE, NOT AT THE CALL SITE. The declared paths
74
+ * carry the `<rid>` placeholder, and the request id is put in before the
75
+ * filesystem is asked — through the repository's own path resolver, which
76
+ * also honours the numbered filename prefix the request writer stamps on.
77
+ *
78
+ * The rate is the share of the spec's REQUIRED steps that ran. A spec that
79
+ * declares no required step demonstrates no compliance and reads 0, which is
80
+ * the judge's own rule and is not restated here.
81
+ */
82
+ export declare function judgeSessionCompliance(opts: {
83
+ readonly projectRoot: string;
84
+ readonly sessionId: string;
85
+ readonly spec: ComplianceSpec;
86
+ readonly sliceRid: string;
87
+ }): Promise<SessionComplianceReading>;
88
+ /**
89
+ * Build a session's row from its events.
90
+ *
91
+ * The row carries the metrics a later run compares: the near-miss rate with
92
+ * the two counts behind it, the size of the hotspot ranking, and the
93
+ * compliance readings the caller judged. It carries no event and no prose.
94
+ *
95
+ * WHY THE REQUEST TYPES ARE AN INPUT AND NOT LOOKED UP HERE. The types live
96
+ * in the request artifacts, and the repository has ONE reader for them — the
97
+ * CLI's `hotspotRequestTypes`. A second lookup inside this module would be a
98
+ * second copy of a reader that drifts, and a drifted copy attributes
99
+ * historical failures against the wrong prerequisite list. So the caller
100
+ * supplies the map, and this module passes it to both the near-miss metric
101
+ * and the hotspot aggregation.
102
+ *
103
+ * WITHOUT THEM THE ROW MISREPORTS TWICE. The near-miss denominator would
104
+ * name "the prereq verdict was never recorded" instead of the cause — the
105
+ * types whose passes were never gated at all — and the hotspot ranking would
106
+ * hold no retro-attributed row, so the count would read as "no hotspot" on a
107
+ * history that has some.
108
+ */
109
+ export declare function buildSessionMetricRow(opts: {
110
+ readonly sessionId: string;
111
+ readonly events: readonly ObservabilityEvent[];
112
+ readonly requestTypes?: HotspotRequestTypes;
113
+ readonly skillsBlobSha?: string;
114
+ readonly compliance?: readonly SessionComplianceReading[];
115
+ }): SessionMetricRow;
116
+ /**
117
+ * The absolute path of a session's tracked row.
118
+ *
119
+ * The row lives OUTSIDE the session directory, so it cannot route through
120
+ * the session-dir resolver; the SAME predicate is used, so the two cannot
121
+ * disagree about what a legal session id is.
122
+ *
123
+ * WHY NOT THE SESSION-DIR RESOLVER. The row is tracked ON PURPOSE — the
124
+ * underscore convention makes a non-underscore `.peaks/` segment git-tracked
125
+ * source of truth, and `.peaks/_runtime/<sid>/` is gitignored. The row is
126
+ * the artifact a CI runner or a fresh clone compares a session against, so
127
+ * putting it in the runtime tree would make it untrackable and the row
128
+ * pointless. The session id here names a FILE inside a tracked directory, not
129
+ * a session runtime directory.
130
+ *
131
+ * `SESSION_METRIC_ROWS_RELATIVE_PATH` is the same path written relatively;
132
+ * a test pins the two together, so they cannot drift.
133
+ */
134
+ export declare function sessionMetricRowPath(projectRoot: string, sessionId: string): string;
135
+ /** Publish a session's row. The write is atomic: a reader sees it whole. */
136
+ export declare function writeSessionMetricRow(projectRoot: string, row: SessionMetricRow): void;
137
+ /**
138
+ * The tracked row for a session, or null when the project has none.
139
+ *
140
+ * A row this build cannot read is an ERROR, not an absence: a file that is
141
+ * there and unreadable is a different fact from a file that is not there,
142
+ * and reading it as "no row" would hide a version this build does not know.
143
+ */
144
+ export declare function readSessionMetricRow(projectRoot: string, sessionId: string): SessionMetricRow | null;
145
+ /**
146
+ * The git object id of the `skills/` tree, or undefined when there is none.
147
+ *
148
+ * The id is the skills version a session ran against, so a later run can
149
+ * tell whether two sessions measured the same skills. A directory that is
150
+ * not a git repository — or one with no committed `skills/` tree — has no
151
+ * version to report, and "no version" is an answer the caller can read.
152
+ */
153
+ export declare function readSkillsBlobSha(projectRoot: string): string | undefined;
@@ -0,0 +1,184 @@
1
+ /**
2
+ * `src/services/observability/session-metric-rows.ts`
3
+ *
4
+ * WHY THIS FILE EXISTS. The raw event stream lives in gitignored session
5
+ * state, so a CI runner and a fresh clone have nothing to compare against.
6
+ * The per-session row is the TRACKED artifact that makes the numbers
7
+ * comparable across machines and across time: one JSON file per session,
8
+ * holding that session's aggregate numbers.
9
+ *
10
+ * WHAT THE ROW CARRIES, AND WHAT IT REFUSES TO CARRY. Counts and rates, and
11
+ * nothing else: no event, no free-text reason, no tool input or output. The
12
+ * event stream's `reason` field holds paths and code fragments, and a
13
+ * tracked file is the one place in this program where such text would
14
+ * outlive the session that produced it.
15
+ *
16
+ * WHY THE COMPLIANCE READING IS COMPUTED HERE. The compliance judge asks
17
+ * whether an artifact exists, and the paths it asks about carry an
18
+ * UNRESOLVED `<rid>` placeholder: the judge hands the declared path through
19
+ * verbatim, and the CALLER substitutes the request id. A caller that probes
20
+ * the raw string asks the filesystem about a path that contains the literal
21
+ * `<rid>`, every step misses, and the rate reads 0 without a single error.
22
+ * The substitution is therefore not left to the caller of this module: the
23
+ * reading is produced here, through the repository's own path resolver.
24
+ *
25
+ * WHY THE ROW IS PUBLISHED THROUGH THE SHARED ATOMIC WRITER. A tracked file
26
+ * that a later run reads must never be observed half-written, so the row is
27
+ * written to a temporary file in the same directory and renamed over the
28
+ * target — the same guarantee the lease store gives.
29
+ */
30
+ import { execFileSync } from 'node:child_process';
31
+ import { existsSync, readFileSync } from 'node:fs';
32
+ import { join } from 'node:path';
33
+ import { resolvePrerequisiteAbsolutePathWithFallback, sessionRootsFor } from '../artifacts/prerequisite-path-resolver.js';
34
+ import { atomicWriteJson } from '../ide/shared/atomic-json.js';
35
+ import { isSinglePathSegment } from '../session/getSessionDir.js';
36
+ import { judgeCompliance } from './compliance-judge.js';
37
+ import { aggregateHotspots } from './hotspots.js';
38
+ import { computeNearMiss } from './near-miss.js';
39
+ /** Where a session's tracked row lives, relative to the project root. */
40
+ export const SESSION_METRIC_ROWS_RELATIVE_PATH = '.peaks/observability/sessions/<sessionId>.json';
41
+ /** The row's schema version. */
42
+ export const SESSION_METRIC_ROW_SCHEMA_VERSION = 1;
43
+ /** The shape of a git object id. */
44
+ const GIT_OBJECT_ID_RE = /^[0-9a-f]{40}$/;
45
+ /**
46
+ * Judge one slice against one compliance spec, in this session's directory.
47
+ *
48
+ * THE SUBSTITUTION HAPPENS HERE, NOT AT THE CALL SITE. The declared paths
49
+ * carry the `<rid>` placeholder, and the request id is put in before the
50
+ * filesystem is asked — through the repository's own path resolver, which
51
+ * also honours the numbered filename prefix the request writer stamps on.
52
+ *
53
+ * The rate is the share of the spec's REQUIRED steps that ran. A spec that
54
+ * declares no required step demonstrates no compliance and reads 0, which is
55
+ * the judge's own rule and is not restated here.
56
+ */
57
+ export async function judgeSessionCompliance(opts) {
58
+ assertSinglePathSegment(opts.sessionId);
59
+ const roots = sessionRootsFor(opts.projectRoot, opts.sessionId);
60
+ const present = new Set();
61
+ for (const step of opts.spec.steps) {
62
+ const resolved = await resolvePrerequisiteAbsolutePathWithFallback(roots.canonical, roots.legacy, { relativePath: step.verify.artifactExists, description: step.description }, opts.sliceRid);
63
+ if (resolved !== null)
64
+ present.add(step.verify.artifactExists);
65
+ }
66
+ const judged = judgeCompliance(opts.spec, (artifactPath) => present.has(artifactPath));
67
+ return {
68
+ specId: judged.specId,
69
+ sliceRid: opts.sliceRid,
70
+ complianceRate: judged.complianceRate
71
+ };
72
+ }
73
+ /**
74
+ * Build a session's row from its events.
75
+ *
76
+ * The row carries the metrics a later run compares: the near-miss rate with
77
+ * the two counts behind it, the size of the hotspot ranking, and the
78
+ * compliance readings the caller judged. It carries no event and no prose.
79
+ *
80
+ * WHY THE REQUEST TYPES ARE AN INPUT AND NOT LOOKED UP HERE. The types live
81
+ * in the request artifacts, and the repository has ONE reader for them — the
82
+ * CLI's `hotspotRequestTypes`. A second lookup inside this module would be a
83
+ * second copy of a reader that drifts, and a drifted copy attributes
84
+ * historical failures against the wrong prerequisite list. So the caller
85
+ * supplies the map, and this module passes it to both the near-miss metric
86
+ * and the hotspot aggregation.
87
+ *
88
+ * WITHOUT THEM THE ROW MISREPORTS TWICE. The near-miss denominator would
89
+ * name "the prereq verdict was never recorded" instead of the cause — the
90
+ * types whose passes were never gated at all — and the hotspot ranking would
91
+ * hold no retro-attributed row, so the count would read as "no hotspot" on a
92
+ * history that has some.
93
+ */
94
+ export function buildSessionMetricRow(opts) {
95
+ const requestTypes = opts.requestTypes ?? new Map();
96
+ const nearMiss = computeNearMiss(opts.events, requestTypes);
97
+ const hotspots = aggregateHotspots(opts.events, requestTypes);
98
+ return {
99
+ schemaVersion: SESSION_METRIC_ROW_SCHEMA_VERSION,
100
+ sessionId: opts.sessionId,
101
+ generatedAt: new Date().toISOString(),
102
+ nearMissRate: nearMiss.nearMissRate,
103
+ passedSliceCount: nearMiss.passedSliceCount,
104
+ nearMissSliceCount: nearMiss.nearMissSliceCount,
105
+ hotspotCount: hotspots.length,
106
+ typesWithoutVerdictPrerequisite: nearMiss.denominator.difference?.typesWithoutVerdictPrerequisite ?? [],
107
+ compliance: opts.compliance ?? [],
108
+ ...(opts.skillsBlobSha === undefined ? {} : { skillsBlobSha: opts.skillsBlobSha })
109
+ };
110
+ }
111
+ /**
112
+ * The absolute path of a session's tracked row.
113
+ *
114
+ * The row lives OUTSIDE the session directory, so it cannot route through
115
+ * the session-dir resolver; the SAME predicate is used, so the two cannot
116
+ * disagree about what a legal session id is.
117
+ *
118
+ * WHY NOT THE SESSION-DIR RESOLVER. The row is tracked ON PURPOSE — the
119
+ * underscore convention makes a non-underscore `.peaks/` segment git-tracked
120
+ * source of truth, and `.peaks/_runtime/<sid>/` is gitignored. The row is
121
+ * the artifact a CI runner or a fresh clone compares a session against, so
122
+ * putting it in the runtime tree would make it untrackable and the row
123
+ * pointless. The session id here names a FILE inside a tracked directory, not
124
+ * a session runtime directory.
125
+ *
126
+ * `SESSION_METRIC_ROWS_RELATIVE_PATH` is the same path written relatively;
127
+ * a test pins the two together, so they cannot drift.
128
+ */
129
+ export function sessionMetricRowPath(projectRoot, sessionId) {
130
+ assertSinglePathSegment(sessionId);
131
+ return join(projectRoot, '.peaks', 'observability', 'sessions', `${sessionId}.json`);
132
+ }
133
+ /** Publish a session's row. The write is atomic: a reader sees it whole. */
134
+ export function writeSessionMetricRow(projectRoot, row) {
135
+ atomicWriteJson(sessionMetricRowPath(projectRoot, row.sessionId), row);
136
+ }
137
+ /**
138
+ * The tracked row for a session, or null when the project has none.
139
+ *
140
+ * A row this build cannot read is an ERROR, not an absence: a file that is
141
+ * there and unreadable is a different fact from a file that is not there,
142
+ * and reading it as "no row" would hide a version this build does not know.
143
+ */
144
+ export function readSessionMetricRow(projectRoot, sessionId) {
145
+ const path = sessionMetricRowPath(projectRoot, sessionId);
146
+ if (!existsSync(path))
147
+ return null;
148
+ const row = JSON.parse(readFileSync(path, 'utf8'));
149
+ const version = row.schemaVersion;
150
+ if (version !== SESSION_METRIC_ROW_SCHEMA_VERSION) {
151
+ throw new Error(`session metric row ${path} declares schema version ${String(version)}, ` +
152
+ 'which this build does not read');
153
+ }
154
+ return row;
155
+ }
156
+ /**
157
+ * The git object id of the `skills/` tree, or undefined when there is none.
158
+ *
159
+ * The id is the skills version a session ran against, so a later run can
160
+ * tell whether two sessions measured the same skills. A directory that is
161
+ * not a git repository — or one with no committed `skills/` tree — has no
162
+ * version to report, and "no version" is an answer the caller can read.
163
+ */
164
+ export function readSkillsBlobSha(projectRoot) {
165
+ let sha = '';
166
+ try {
167
+ sha = execFileSync('git', ['rev-parse', 'HEAD:skills'], {
168
+ cwd: projectRoot,
169
+ encoding: 'utf8',
170
+ stdio: ['ignore', 'pipe', 'ignore'],
171
+ windowsHide: true
172
+ }).trim();
173
+ }
174
+ catch {
175
+ sha = '';
176
+ }
177
+ return GIT_OBJECT_ID_RE.test(sha) ? sha : undefined;
178
+ }
179
+ /** Refuse a session id that is not a single path segment. */
180
+ function assertSinglePathSegment(sessionId) {
181
+ if (!isSinglePathSegment(sessionId)) {
182
+ throw new Error(`Invalid session id: ${sessionId} (must be a single path segment)`);
183
+ }
184
+ }
@@ -32,7 +32,11 @@ export const ORCHESTRATOR_ROLE_SKILLS = [
32
32
  // accepted here, before any PRD or RD skill may run. Nothing dispatches it.
33
33
  'peaks-audit',
34
34
  // The fast lane — a user-facing entry the user picks instead of the full workflow.
35
- 'peaks-race-code'
35
+ 'peaks-race-code',
36
+ // The always-loaded entry that writes the skill pool and the local SkillHub:
37
+ // the user reaches it by describing what they want, and it is never
38
+ // dispatched by another skill.
39
+ 'peaks-maker'
36
40
  ];
37
41
  /** The 1-level sub-roles an orchestrator dispatches. */
38
42
  export const BEE_ROLE_SKILLS = [
@@ -53,7 +57,10 @@ export const BEE_ROLE_SKILLS = [
53
57
  // One dimension audited, decoupled from the RD fan-out: one envelope,
54
58
  // written for the caller that asked for the audit.
55
59
  'peaks-perf-audit',
56
- 'peaks-security-audit'
60
+ 'peaks-security-audit',
61
+ // One stage of a larger flow: peaks-code and peaks-rd dispatch it after the
62
+ // TACT chain exists, and it writes one measurement report back.
63
+ 'peaks-mut'
57
64
  ];
58
65
  /** The two lists as ONE lookup, so a skill's tier is decided in one place. */
59
66
  const ROLE_TIERS = new Map([
@@ -8,7 +8,8 @@
8
8
  * { ok: false, findings: string[] }.
9
9
  *
10
10
  * The lint asserts three structural properties the spec binds every
11
- * Loop-Engineering-participating peaks-* skill to:
11
+ * Loop-Engineering-participating peaks-* skill to. All three see the skill's
12
+ * OWN text: the shared loop-hygiene insert is blanked first.
12
13
  *
13
14
  * 1. The skill references the shared guideline file
14
15
  * `.peaks/standards/loop-engineering-guidelines.md` (or its
@@ -49,6 +50,9 @@
49
50
  * that rule at the textual layer.
50
51
  */
51
52
  export type LintFinding = string;
53
+ /** Loop-hygiene block delimiters — a shared, non-per-skill insert; skip it. */
54
+ export declare const HYGIENE_BLOCK_OPEN_MARKER = "<!-- peaks:loop-hygiene";
55
+ export declare const HYGIENE_BLOCK_CLOSE_MARKER = "<!-- /peaks:loop-hygiene -->";
52
56
  export type ReadinessLintResult = {
53
57
  ok: true;
54
58
  findings: [];
@@ -101,9 +105,19 @@ export declare const JSON_HAND_AUTHORING_PHRASES: ReadonlyArray<string>;
101
105
  * verb targeting the user.
102
106
  */
103
107
  export declare const JSON_REFERENCE_ALLOWLIST: ReadonlyArray<string>;
108
+ /**
109
+ * Blank the shared loop-hygiene block so the readiness checks skip it: only text
110
+ * BETWEEN two paired markers goes. The region is blanked, not deleted, so a
111
+ * later finding keeps its ORIGINAL line number. A malformed region (one marker
112
+ * with no pair) strips nothing — a lint that one deleted line can switch off is
113
+ * worse than the false positive this exemption exists to fix.
114
+ */
115
+ export declare function stripHygieneBlock(text: string): string;
104
116
  /**
105
117
  * Lint a SKILL.md text for Loop Engineering readiness.
106
118
  *
119
+ * Checks run on {@link stripHygieneBlock}(input); see the helper for why.
120
+ *
107
121
  * @param skillMdText raw markdown text of a peaks-* SKILL.md
108
122
  * @returns a ReadinessLintResult
109
123
  */
@@ -8,7 +8,8 @@
8
8
  * { ok: false, findings: string[] }.
9
9
  *
10
10
  * The lint asserts three structural properties the spec binds every
11
- * Loop-Engineering-participating peaks-* skill to:
11
+ * Loop-Engineering-participating peaks-* skill to. All three see the skill's
12
+ * OWN text: the shared loop-hygiene insert is blanked first.
12
13
  *
13
14
  * 1. The skill references the shared guideline file
14
15
  * `.peaks/standards/loop-engineering-guidelines.md` (or its
@@ -48,6 +49,9 @@
48
49
  * This lint is what stops a future peaks-* skill from regressing
49
50
  * that rule at the textual layer.
50
51
  */
52
+ /** Loop-hygiene block delimiters — a shared, non-per-skill insert; skip it. */
53
+ export const HYGIENE_BLOCK_OPEN_MARKER = '<!-- peaks:loop-hygiene';
54
+ export const HYGIENE_BLOCK_CLOSE_MARKER = '<!-- /peaks:loop-hygiene -->';
51
55
  /**
52
56
  * The shared guideline file that every Loop-Engineering-participating
53
57
  * peaks-* skill must reference. Both the canonical path and the
@@ -166,9 +170,26 @@ export const JSON_REFERENCE_ALLOWLIST = [
166
170
  // ---------------------------------------------------------------------------
167
171
  // Pure function
168
172
  // ---------------------------------------------------------------------------
173
+ /**
174
+ * Blank the shared loop-hygiene block so the readiness checks skip it: only text
175
+ * BETWEEN two paired markers goes. The region is blanked, not deleted, so a
176
+ * later finding keeps its ORIGINAL line number. A malformed region (one marker
177
+ * with no pair) strips nothing — a lint that one deleted line can switch off is
178
+ * worse than the false positive this exemption exists to fix.
179
+ */
180
+ export function stripHygieneBlock(text) {
181
+ const start = text.indexOf(HYGIENE_BLOCK_OPEN_MARKER);
182
+ const closeAt = start === -1 ? -1 : text.indexOf(HYGIENE_BLOCK_CLOSE_MARKER, start);
183
+ if (start === -1 || closeAt === -1)
184
+ return text;
185
+ const end = closeAt + HYGIENE_BLOCK_CLOSE_MARKER.length;
186
+ return text.slice(0, start) + text.slice(start, end).replace(/[^\r\n]/g, '') + text.slice(end);
187
+ }
169
188
  /**
170
189
  * Lint a SKILL.md text for Loop Engineering readiness.
171
190
  *
191
+ * Checks run on {@link stripHygieneBlock}(input); see the helper for why.
192
+ *
172
193
  * @param skillMdText raw markdown text of a peaks-* SKILL.md
173
194
  * @returns a ReadinessLintResult
174
195
  */
@@ -180,9 +201,10 @@ export function lintSkillLoopEngineeringReadiness(skillMdText) {
180
201
  findings: ['skill-md-empty: SKILL.md text is empty or missing']
181
202
  };
182
203
  }
183
- checkGuidelineReference(skillMdText, findings);
184
- checkCliVerbBypass(skillMdText, findings);
185
- checkJsonHandAuthoring(skillMdText, findings);
204
+ const checkedText = stripHygieneBlock(skillMdText);
205
+ checkGuidelineReference(checkedText, findings);
206
+ checkCliVerbBypass(checkedText, findings);
207
+ checkJsonHandAuthoring(checkedText, findings);
186
208
  if (findings.length > 0) {
187
209
  return { ok: false, findings };
188
210
  }
@@ -192,12 +214,8 @@ export function lintSkillLoopEngineeringReadiness(skillMdText) {
192
214
  // Individual checks
193
215
  // ---------------------------------------------------------------------------
194
216
  function checkGuidelineReference(text, findings) {
195
- // Strip code fences before checking — references inside ``` blocks
196
- // are still valid references (the lint accepts them), but we strip
197
- // so the substring match is unambiguous.
198
- const stripped = text;
199
217
  for (const ref of LOOP_ENGINEERING_GUIDELINE_PATHS) {
200
- if (stripped.includes(ref)) {
218
+ if (text.includes(ref)) {
201
219
  return;
202
220
  }
203
221
  }