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.
- package/.claude-plugin/marketplace.json +12 -2
- package/CHANGELOG.md +184 -0
- package/dist/cli/commands/code-auto-compact-command.js +19 -1
- package/dist/cli/commands/code-gate-step-08-command.js +103 -105
- package/dist/cli/commands/code-gate-step-08-remedy.d.ts +10 -2
- package/dist/cli/commands/code-gate-step-08-remedy.js +11 -3
- package/dist/cli/commands/gate-commands-enforce.d.ts +23 -8
- package/dist/cli/commands/gate-commands-enforce.js +27 -12
- package/dist/cli/commands/observability-commands-hotspots.d.ts +54 -0
- package/dist/cli/commands/observability-commands-hotspots.js +222 -0
- package/dist/cli/commands/observability-commands-near-miss.d.ts +28 -0
- package/dist/cli/commands/observability-commands-near-miss.js +105 -0
- package/dist/cli/commands/observability-commands-queries.d.ts +61 -18
- package/dist/cli/commands/observability-commands-queries.js +88 -47
- package/dist/cli/commands/observability-commands-session-row.d.ts +48 -0
- package/dist/cli/commands/observability-commands-session-row.js +201 -0
- package/dist/cli/commands/observability-commands.js +81 -20
- package/dist/services/artifacts/artifact-prerequisites.d.ts +3 -0
- package/dist/services/artifacts/artifact-prerequisites.js +1 -1
- package/dist/services/artifacts/prerequisite-path-census.d.ts +47 -0
- package/dist/services/artifacts/prerequisite-path-census.js +100 -0
- package/dist/services/artifacts/prerequisite-path-resolver.js +32 -2
- package/dist/services/artifacts/prerequisite-transition-event.js +13 -1
- package/dist/services/artifacts/rd-gate-event.d.ts +106 -0
- package/dist/services/artifacts/rd-gate-event.js +211 -0
- package/dist/services/artifacts/rd-transition-gates.d.ts +6 -0
- package/dist/services/artifacts/rd-transition-gates.js +65 -24
- package/dist/services/hooks/output.d.ts +67 -1
- package/dist/services/hooks/output.js +74 -1
- package/dist/services/observability/aggregation-types.d.ts +21 -0
- package/dist/services/observability/aggregation.d.ts +12 -2
- package/dist/services/observability/aggregation.js +28 -3
- package/dist/services/observability/compliance-judge.d.ts +77 -0
- package/dist/services/observability/compliance-judge.js +143 -0
- package/dist/services/observability/compliance-spec.d.ts +96 -0
- package/dist/services/observability/compliance-spec.js +29 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.d.ts +37 -0
- package/dist/services/observability/compliance-specs/peaks-race-code.spec.js +66 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.d.ts +50 -0
- package/dist/services/observability/compliance-specs/peaks-rd.spec.js +111 -0
- package/dist/services/observability/hotspot-attribution-summary.d.ts +84 -0
- package/dist/services/observability/hotspot-attribution-summary.js +74 -0
- package/dist/services/observability/hotspot-rows.d.ts +47 -0
- package/dist/services/observability/hotspot-rows.js +89 -0
- package/dist/services/observability/hotspot-shared.d.ts +207 -0
- package/dist/services/observability/hotspot-shared.js +127 -0
- package/dist/services/observability/hotspot-sources.d.ts +55 -0
- package/dist/services/observability/hotspot-sources.js +142 -0
- package/dist/services/observability/hotspots.d.ts +47 -0
- package/dist/services/observability/hotspots.js +47 -0
- package/dist/services/observability/near-miss-attempts.d.ts +175 -0
- package/dist/services/observability/near-miss-attempts.js +223 -0
- package/dist/services/observability/near-miss-coverage.d.ts +109 -0
- package/dist/services/observability/near-miss-coverage.js +108 -0
- package/dist/services/observability/near-miss-denominator.d.ts +81 -0
- package/dist/services/observability/near-miss-denominator.js +75 -0
- package/dist/services/observability/near-miss-difference.d.ts +98 -0
- package/dist/services/observability/near-miss-difference.js +135 -0
- package/dist/services/observability/near-miss-facts.d.ts +165 -0
- package/dist/services/observability/near-miss-facts.js +101 -0
- package/dist/services/observability/near-miss-gate-events.d.ts +75 -0
- package/dist/services/observability/near-miss-gate-events.js +106 -0
- package/dist/services/observability/near-miss-gates.d.ts +108 -0
- package/dist/services/observability/near-miss-gates.js +135 -0
- package/dist/services/observability/near-miss-records.d.ts +93 -0
- package/dist/services/observability/near-miss-records.js +87 -0
- package/dist/services/observability/near-miss.d.ts +148 -0
- package/dist/services/observability/near-miss.js +203 -0
- package/dist/services/observability/observability-schema.d.ts +17 -2
- package/dist/services/observability/observability-schema.js +21 -1
- package/dist/services/observability/owner-skill-map.d.ts +92 -0
- package/dist/services/observability/owner-skill-map.js +164 -0
- package/dist/services/observability/repair-cycle-metric.js +6 -3
- package/dist/services/observability/report-formatter-hotspots.d.ts +32 -0
- package/dist/services/observability/report-formatter-hotspots.js +76 -0
- package/dist/services/observability/report-formatter-near-miss.d.ts +48 -0
- package/dist/services/observability/report-formatter-near-miss.js +234 -0
- package/dist/services/observability/report-formatter.d.ts +49 -3
- package/dist/services/observability/report-formatter.js +55 -14
- package/dist/services/observability/retro-attribution.d.ts +129 -0
- package/dist/services/observability/retro-attribution.js +134 -0
- package/dist/services/observability/session-metric-rows.d.ts +153 -0
- package/dist/services/observability/session-metric-rows.js +184 -0
- package/dist/services/skills/presence-role.js +9 -2
- package/dist/services/standards/loop-engineering-readiness-lint.d.ts +15 -1
- package/dist/services/standards/loop-engineering-readiness-lint.js +27 -9
- package/dist/shared/incrementing-number.d.ts +57 -0
- package/dist/shared/incrementing-number.js +13 -0
- package/dist/skills/peaks-maker/index.js +43 -30
- package/output-styles/peaks-skill-swarm.md +2 -2
- package/package.json +5 -5
- package/scripts/install-skills-bundles.mjs +6 -1
- package/scripts/install-skills.mjs +10 -1
- package/skills/bee/peaks-perf-audit/SKILL.md +1 -1
- package/skills/bee/peaks-prd/SKILL.md +1 -1
- package/skills/bee/peaks-qa/SKILL.md +1 -1
- package/skills/bee/peaks-rd/SKILL.md +1 -1
- package/skills/bee/peaks-reviewer/SKILL.md +1 -1
- package/skills/bee/peaks-sc/SKILL.md +1 -1
- package/skills/bee/peaks-security-audit/SKILL.md +1 -1
- package/skills/bee/peaks-txt/SKILL.md +1 -1
- package/skills/bee/peaks-ui/SKILL.md +1 -1
- package/skills/peaks-audit/SKILL.md +1 -1
- package/skills/peaks-code/SKILL.md +1 -1
- package/skills/peaks-content/SKILL.md +1 -1
- package/skills/peaks-doctor/SKILL.md +1 -1
- package/skills/peaks-final-review/SKILL.md +1 -1
- package/skills/peaks-ide/SKILL.md +1 -1
- package/skills/peaks-issue-fix-orchestrator/SKILL.md +1 -1
- package/skills/peaks-maker/SKILL.md +125 -0
- package/skills/peaks-mut/SKILL.md +297 -0
- package/skills/peaks-race-code/SKILL.md +1 -1
- package/skills/peaks-resume/SKILL.md +1 -1
- package/skills/peaks-slice-decompose/SKILL.md +1 -1
- package/skills/peaks-solo/SKILL.md +1 -1
- package/skills/peaks-sop/SKILL.md +1 -1
- package/skills/peaks-status/SKILL.md +1 -1
- 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
|
-
|
|
184
|
-
|
|
185
|
-
|
|
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 (
|
|
218
|
+
if (text.includes(ref)) {
|
|
201
219
|
return;
|
|
202
220
|
}
|
|
203
221
|
}
|