@skill-harness/core 0.4.0 → 0.6.0

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/dist/sources.js CHANGED
@@ -390,6 +390,48 @@ export function remedyForKey(key) {
390
390
  }
391
391
  return "re-run"; // stimulus:, SKILL.md, fixture:, agent files, post_test contents
392
392
  }
393
+ /** The skill-text key. Skill-wide: it belongs to every scenario at once. */
394
+ export const SKILL_KEY = "SKILL.md";
395
+ /**
396
+ * Every recorded key whose drift could change THIS scenario's verdict — excluding the
397
+ * two skill-wide ones (`SKILL.md`, `rubric:__persona`), which callers handle
398
+ * separately because they move every scenario at once.
399
+ *
400
+ * Written for run-over-run comparison (see stability.ts): "did these two runs ask this
401
+ * scenario the same question, judged by the same rubric?" is answerable from the
402
+ * recorded hashes, and only if you know which keys belong to the scenario. Derived
403
+ * from the spec rather than from the key strings, because the path-shaped keys
404
+ * (`system_prompt_file`, `post_test`) carry no scenario id at all.
405
+ *
406
+ * `policy:<id>` is deliberately NOT here. Its `reps`/`pass_threshold` half is already
407
+ * compared as an *aggregation* shape (1 draw vs a majority of 3 is the comparison a
408
+ * hash cannot express), and its `critical` half changes whether a verdict can block a
409
+ * ship, never what the verdict is. Including it would report a critical-set edit as
410
+ * "these runs measured different things", which is false.
411
+ *
412
+ * Both key generations are returned: 0.4.0+ runs carry the split facet keys, older
413
+ * ones the combined `scenario:<id>`. A caller comparing two runs must not treat a
414
+ * combined digest and a split one as comparable — they hash different byte layouts —
415
+ * so it compares only keys BOTH runs recorded, and treats "no shared key" as
416
+ * unverifiable rather than unchanged.
417
+ */
418
+ export function scenarioSourceKeys(s) {
419
+ const keys = [
420
+ STIMULUS_PREFIX + s.id,
421
+ RUBRIC_PREFIX + s.id,
422
+ SCENARIO_PREFIX + s.id, // legacy combined (pre-0.4.0 runs)
423
+ ];
424
+ if (gatesDigest(s) !== null)
425
+ keys.push(GATES_PREFIX + s.id);
426
+ if (s.systemPromptFile)
427
+ keys.push(s.systemPromptFile); // the agent file IS the stimulus
428
+ if (s.assert?.post_test)
429
+ keys.push(s.assert.post_test); // its contents are the gate
430
+ const fx = effectiveFixture(s);
431
+ if (fx)
432
+ keys.push(FIXTURE_PREFIX + fx);
433
+ return keys;
434
+ }
393
435
  /** The scenario id a key belongs to, for per-scenario lint findings. Undefined for skill-wide keys. */
394
436
  export function scenarioIdForKey(key, scenarios) {
395
437
  if (key === PERSONA_KEY)
@@ -0,0 +1,144 @@
1
+ import { type Spec } from "./spec.js";
2
+ import { type ScoredRunGroup } from "./trends.js";
3
+ import type { Verdict } from "./score.js";
4
+ /**
5
+ * Run-over-run verdict stability, per scenario, derived on read from committed
6
+ * history. No new measurement, nothing persisted.
7
+ *
8
+ * ## Why this exists
9
+ *
10
+ * Measured in the reference corpus (`plan`, deepseek, two consecutive full force runs,
11
+ * 2026-08-05 → 2026-08-06): **A5 went 3/3 PASS to 0/3 FAIL and D1 went 1/3 to 3/3, each
12
+ * run internally `flakiness 0.00`.** Two unanimous runs, opposite verdicts.
13
+ *
14
+ * `flakiness` is a within-run number: it measures how much the reps of ONE run
15
+ * disagreed. A scenario sitting on a behavioural boundary can be unanimous inside every
16
+ * run and still land on a different side each time — and then `flakiness 0.00` reads as
17
+ * confidence when it is the opposite. Nothing in a single `results.yaml` can see this,
18
+ * because the evidence is spread across files.
19
+ *
20
+ * ## What makes a flip a *stability* signal
21
+ *
22
+ * A verdict that changes because the scenario changed is not instability, it is an
23
+ * edit — and reporting edits as instability would make this feature noise. So a pair of
24
+ * adjacent runs is only compared when all of the following hold, and each rejection is
25
+ * reported with its reason rather than silently dropped:
26
+ *
27
+ * | gate | rejected as | why |
28
+ * |---|---|---|
29
+ * | both verdicts conclusive | `inconclusive` | an ERROR or unresolved misfire says nothing about behaviour |
30
+ * | same reps + pass threshold | `aggregation` | 1 draw vs a majority of 3 is not the same measurement (as in lift.ts) |
31
+ * | the scenario's own recorded sources identical | `sources` | different question, or different rubric |
32
+ * | those sources comparable at all | `unverified` | one run predates `source_hashes`, or the two use different key generations |
33
+ *
34
+ * **`SKILL.md` is deliberately NOT one of those gates.** In the measured case the skill
35
+ * text HAD changed — an edit aimed at a different scenario — while A5's own stimulus and
36
+ * rubric were byte-identical. Excluding that pair would have hidden the exact finding
37
+ * this feature was asked to surface. Such a flip is reported with `skillChanged`, and
38
+ * the note says what it means: either a side effect of that edit or a boundary cell.
39
+ * Which of the two it is cannot be told from the record, and pretending otherwise would
40
+ * be a guess dressed as a fact.
41
+ *
42
+ * Modes are never mixed (`collectScoredRuns` groups per mode), because placement moves
43
+ * verdicts on identical text — a green run and a force run are two deployments.
44
+ */
45
+ /** One run's contribution to a scenario's history. */
46
+ export interface StabilityPoint {
47
+ timestamp: string;
48
+ label: string | null;
49
+ /** Override-aware, matching what the scorecard claims (an override IS the author's verdict). */
50
+ verdict: Verdict;
51
+ overridden: boolean;
52
+ /** True for an `--only` run: real evidence about this scenario, but not a full run. */
53
+ partial: boolean;
54
+ reps: number;
55
+ /**
56
+ * Every rep in this run agreed AND there was more than one rep. A single rep is not
57
+ * unanimous, it is one draw — the distinction the headline finding turns on.
58
+ */
59
+ unanimous: boolean;
60
+ }
61
+ /** Why a pair of adjacent runs could, or could not, be compared. */
62
+ export type PairStatus = "compared" | "inconclusive" | "aggregation" | "sources" | "unverified";
63
+ export interface StabilityPair {
64
+ from: StabilityPoint;
65
+ to: StabilityPoint;
66
+ status: PairStatus;
67
+ /** The verdict changed. Only meaningful when `status === "compared"`. */
68
+ flipped: boolean;
69
+ /** The skill text differed between these two runs (not a rejection — see the module doc). */
70
+ skillChanged: boolean;
71
+ /** Human labels of the scenario's own sources that differed (`status === "sources"`). */
72
+ changedSources: string[];
73
+ /** A flip where BOTH runs were internally unanimous — invisible to within-run flakiness. */
74
+ unanimousFlip: boolean;
75
+ }
76
+ export type StabilityState = "stable" | "boundary" | "unmeasured";
77
+ export interface ScenarioStability {
78
+ id: string;
79
+ title: string;
80
+ critical: boolean;
81
+ tag: string;
82
+ mode: string;
83
+ model: string;
84
+ /** The window, chronologically ascending (oldest first). */
85
+ points: StabilityPoint[];
86
+ /** Adjacent pairs within the window, oldest first. */
87
+ pairs: StabilityPair[];
88
+ compared: number;
89
+ flips: number;
90
+ /** Of `flips`, how many happened across a SKILL.md edit. */
91
+ flipsAcrossSkillEdit: number;
92
+ /** Of `flips`, how many were between two internally-unanimous runs. */
93
+ unanimousFlips: number;
94
+ /**
95
+ * `flips / compared`, or null when nothing was comparable. 0 = never flipped in the
96
+ * window; 1 = flipped at every opportunity.
97
+ *
98
+ * Same polarity as `flakiness` (0 is the quiet end) on purpose, and named for the
99
+ * thing being counted rather than for its absence: `stability: 0.0` would have to
100
+ * mean "perfectly stable", which reads exactly backwards next to `flaky 0.00`.
101
+ */
102
+ volatility: number | null;
103
+ state: StabilityState;
104
+ }
105
+ export interface StabilityOptions {
106
+ /** How many of the most recent scored runs to look at. Default 5. */
107
+ window?: number;
108
+ }
109
+ /** Derive stability for every scenario × tag × mode from an already-read history. */
110
+ export declare function stabilityFrom(groups: ScoredRunGroup[], spec: Spec, opts?: StabilityOptions): ScenarioStability[];
111
+ /**
112
+ * Read `<skillDir>/tests/results/` and derive run-over-run stability per scenario ×
113
+ * model tag × delivery mode. Free and offline: it reads committed results.yaml files
114
+ * and computes; it never runs a model, a judge, or a harness.
115
+ *
116
+ * Deliberately derived on read rather than stored in results.yaml, for the reason lift
117
+ * is: stability is a fact about a SET of runs, so a copy inside one run's file would be
118
+ * wrong the moment the next run lands — the stale-scorecard failure `source_hashes`
119
+ * exists to prevent. It also means this works retroactively on history recorded by
120
+ * every earlier version.
121
+ */
122
+ export declare function collectStability(skillDir: string, opts?: StabilityOptions): ScenarioStability[];
123
+ /** Scenarios that flipped at least once — the cells a single run reads as too certain. */
124
+ export declare function boundaryCells(all: ScenarioStability[]): ScenarioStability[];
125
+ /**
126
+ * The window as one readable string: `PASS!→FAIL!` or `FAIL⋯PASS→PASS!`.
127
+ *
128
+ * `→` is a step this comparison counted; `⋯` is a step it rejected (an edit, a
129
+ * different aggregation, unverifiable hashes); `!` marks a run whose reps were
130
+ * internally unanimous. The two arrows have to differ, or a path reading `FAIL→PASS`
131
+ * would sit next to "held its verdict" and look like a contradiction — the window shows
132
+ * every run, but only some of the steps between them are evidence.
133
+ */
134
+ export declare const PATH_LEGEND = "\u2192 comparable step \u00B7 \u22EF step not comparable \u00B7 ! that run's reps were unanimous";
135
+ export declare function verdictPath(s: ScenarioStability): string;
136
+ /**
137
+ * The one-line human statement. This string is the feature: a number nobody can read
138
+ * ("volatility 1.00") would leave the reader exactly where a single run left them.
139
+ *
140
+ * Every branch says what the record supports and no more — which of "the edit did it"
141
+ * and "the cell is bimodal" is true cannot be told from committed results, so the
142
+ * across-an-edit wording names both.
143
+ */
144
+ export declare function stabilityNote(s: ScenarioStability): string;
@@ -0,0 +1,232 @@
1
+ import { join } from "node:path";
2
+ import { loadSpec } from "./spec.js";
3
+ import { effectiveVerdicts } from "./results.js";
4
+ import { collectScoredRuns } from "./trends.js";
5
+ import { describeSourceKey, scenarioSourceKeys, PERSONA_KEY, SKILL_KEY } from "./sources.js";
6
+ const DEFAULT_WINDOW = 5;
7
+ /** A verdict that carries evidence about the task rather than about the harness or judge. */
8
+ function conclusive(v) {
9
+ // Same rule lift.ts applies, for the same reason: ERROR is a harness failure and an
10
+ // unresolved misfire is a judge failure. Counting either as a side of a flip would
11
+ // report infrastructure noise as behavioural instability.
12
+ return !v.suspect && v.verdict !== "ERROR" && v.verdict !== "JUDGE-AMBIGUOUS";
13
+ }
14
+ function pointFor(r, s, verdict) {
15
+ const reps = s.reps ?? 1;
16
+ return {
17
+ timestamp: r.timestamp,
18
+ label: r.label,
19
+ verdict,
20
+ overridden: s.override != null,
21
+ partial: Boolean(r.partial),
22
+ reps,
23
+ unanimous: reps > 1 && s.flakiness === 0,
24
+ };
25
+ }
26
+ /** reps + threshold, normalised the way lift.ts normalises it (a lone rep has no threshold). */
27
+ function shapeOf(s) {
28
+ const reps = s.reps ?? 1;
29
+ return JSON.stringify([reps, reps > 1 ? s.pass_threshold ?? null : null]);
30
+ }
31
+ /**
32
+ * Compare the recorded hashes of one scenario's own sources across two runs.
33
+ *
34
+ * Only keys BOTH runs recorded are compared: a key one side never hashed cannot be
35
+ * shown to be unchanged. `shared === 0` means unverifiable (a pre-`source_hashes` run,
36
+ * or a split-key run against a legacy combined-key one), which is reported as
37
+ * `unverified` rather than assumed identical — the whole value of this feature is that
38
+ * it does not claim more than the record supports.
39
+ */
40
+ function compareSources(a, b, keys) {
41
+ if (!a || !b)
42
+ return { shared: 0, changed: [] };
43
+ let shared = 0;
44
+ const changed = [];
45
+ for (const key of keys) {
46
+ const va = a[key];
47
+ const vb = b[key];
48
+ if (va === undefined || vb === undefined)
49
+ continue;
50
+ shared++;
51
+ if (va !== vb)
52
+ changed.push(describeSourceKey(key));
53
+ }
54
+ return { shared, changed };
55
+ }
56
+ /** Derive one scenario's stability within one tag × mode group. */
57
+ function stabilityForScenario(group, scenario, window) {
58
+ // The window is over runs that HOLD this scenario: an `--only` run elsewhere in the
59
+ // history must not consume a slot and shrink the comparison to nothing.
60
+ const relevant = group.runs.filter((r) => r.scenarios.some((s) => s.id === scenario.id));
61
+ const kept = relevant.slice(-window);
62
+ // Skill-wide rubric: the persona moves every verdict in the skill, so it belongs with
63
+ // the scenario's own sources rather than with the SKILL.md caveat.
64
+ const keys = [...scenarioSourceKeys(scenario), PERSONA_KEY];
65
+ const points = [];
66
+ const raw = [];
67
+ for (const r of kept) {
68
+ const i = r.scenarios.findIndex((s) => s.id === scenario.id);
69
+ const s = r.scenarios[i];
70
+ const eff = effectiveVerdicts(r.scenarios)[i];
71
+ points.push(pointFor(r, s, eff.verdict));
72
+ raw.push({ r, s, ok: conclusive(eff) });
73
+ }
74
+ const pairs = [];
75
+ for (let i = 1; i < raw.length; i++) {
76
+ const prev = raw[i - 1];
77
+ const cur = raw[i];
78
+ const from = points[i - 1];
79
+ const to = points[i];
80
+ const skillChanged = prev.r.source_hashes?.[SKILL_KEY] !== undefined &&
81
+ cur.r.source_hashes?.[SKILL_KEY] !== undefined &&
82
+ prev.r.source_hashes[SKILL_KEY] !== cur.r.source_hashes[SKILL_KEY];
83
+ const base = { from, to, flipped: false, skillChanged, changedSources: [], unanimousFlip: false };
84
+ if (!prev.ok || !cur.ok) {
85
+ pairs.push({ ...base, status: "inconclusive" });
86
+ continue;
87
+ }
88
+ if (shapeOf(prev.s) !== shapeOf(cur.s)) {
89
+ pairs.push({ ...base, status: "aggregation" });
90
+ continue;
91
+ }
92
+ const src = compareSources(prev.r.source_hashes, cur.r.source_hashes, keys);
93
+ if (src.shared === 0) {
94
+ pairs.push({ ...base, status: "unverified" });
95
+ continue;
96
+ }
97
+ if (src.changed.length > 0) {
98
+ pairs.push({ ...base, status: "sources", changedSources: src.changed });
99
+ continue;
100
+ }
101
+ const flipped = from.verdict !== to.verdict;
102
+ pairs.push({
103
+ ...base,
104
+ status: "compared",
105
+ flipped,
106
+ unanimousFlip: flipped && from.unanimous && to.unanimous,
107
+ });
108
+ }
109
+ const compared = pairs.filter((p) => p.status === "compared").length;
110
+ const flipped = pairs.filter((p) => p.status === "compared" && p.flipped);
111
+ return {
112
+ id: scenario.id,
113
+ title: scenario.title,
114
+ critical: scenario.critical,
115
+ tag: group.tag,
116
+ mode: group.mode,
117
+ model: group.model,
118
+ points,
119
+ pairs,
120
+ compared,
121
+ flips: flipped.length,
122
+ flipsAcrossSkillEdit: flipped.filter((p) => p.skillChanged).length,
123
+ unanimousFlips: flipped.filter((p) => p.unanimousFlip).length,
124
+ volatility: compared === 0 ? null : flipped.length / compared,
125
+ // "unmeasured" is a third state on purpose: a scenario with one run, or with no
126
+ // comparable pair, has NOT been shown to be stable. Collapsing it into "stable"
127
+ // would turn absence of evidence into evidence — the same conflation lift.ts
128
+ // refuses when it reports "no red baseline" instead of a zero.
129
+ state: compared === 0 ? "unmeasured" : flipped.length > 0 ? "boundary" : "stable",
130
+ };
131
+ }
132
+ /** Derive stability for every scenario × tag × mode from an already-read history. */
133
+ export function stabilityFrom(groups, spec, opts = {}) {
134
+ const window = Math.max(2, opts.window ?? DEFAULT_WINDOW); // a window of 1 has no pair to compare
135
+ const out = [];
136
+ for (const group of groups) {
137
+ for (const scenario of spec.scenarios) {
138
+ out.push(stabilityForScenario(group, scenario, window));
139
+ }
140
+ }
141
+ return out;
142
+ }
143
+ /**
144
+ * Read `<skillDir>/tests/results/` and derive run-over-run stability per scenario ×
145
+ * model tag × delivery mode. Free and offline: it reads committed results.yaml files
146
+ * and computes; it never runs a model, a judge, or a harness.
147
+ *
148
+ * Deliberately derived on read rather than stored in results.yaml, for the reason lift
149
+ * is: stability is a fact about a SET of runs, so a copy inside one run's file would be
150
+ * wrong the moment the next run lands — the stale-scorecard failure `source_hashes`
151
+ * exists to prevent. It also means this works retroactively on history recorded by
152
+ * every earlier version.
153
+ */
154
+ export function collectStability(skillDir, opts = {}) {
155
+ const spec = loadSpec(join(skillDir, "tests", "specification.yaml"));
156
+ return stabilityFrom(collectScoredRuns(skillDir), spec, opts);
157
+ }
158
+ /** Scenarios that flipped at least once — the cells a single run reads as too certain. */
159
+ export function boundaryCells(all) {
160
+ return all.filter((s) => s.state === "boundary");
161
+ }
162
+ /**
163
+ * The window as one readable string: `PASS!→FAIL!` or `FAIL⋯PASS→PASS!`.
164
+ *
165
+ * `→` is a step this comparison counted; `⋯` is a step it rejected (an edit, a
166
+ * different aggregation, unverifiable hashes); `!` marks a run whose reps were
167
+ * internally unanimous. The two arrows have to differ, or a path reading `FAIL→PASS`
168
+ * would sit next to "held its verdict" and look like a contradiction — the window shows
169
+ * every run, but only some of the steps between them are evidence.
170
+ */
171
+ export const PATH_LEGEND = "→ comparable step · ⋯ step not comparable · ! that run's reps were unanimous";
172
+ export function verdictPath(s) {
173
+ const label = (p) => `${p.verdict}${p.unanimous ? "!" : ""}${p.overridden ? "(override)" : ""}`;
174
+ let out = s.points.length > 0 ? label(s.points[0]) : "";
175
+ s.pairs.forEach((pair, i) => {
176
+ out += `${pair.status === "compared" ? "→" : "⋯"}${label(s.points[i + 1])}`;
177
+ });
178
+ return out;
179
+ }
180
+ /**
181
+ * The one-line human statement. This string is the feature: a number nobody can read
182
+ * ("volatility 1.00") would leave the reader exactly where a single run left them.
183
+ *
184
+ * Every branch says what the record supports and no more — which of "the edit did it"
185
+ * and "the cell is bimodal" is true cannot be told from committed results, so the
186
+ * across-an-edit wording names both.
187
+ */
188
+ export function stabilityNote(s) {
189
+ if (s.state === "boundary") {
190
+ const parts = [
191
+ `${s.id} flipped its verdict in ${s.flips} of ${s.compared} comparable run-to-run step(s) (${verdictPath(s)})`,
192
+ ];
193
+ if (s.unanimousFlips > 0) {
194
+ parts.push(`${s.unanimousFlips === s.flips ? "each flip was" : `${s.unanimousFlips} flip(s) were`} between runs that were` +
195
+ ` INTERNALLY UNANIMOUS (flakiness 0.00) — within-run reps cannot see this`);
196
+ }
197
+ if (s.flipsAcrossSkillEdit === s.flips && s.flips > 0) {
198
+ parts.push(`SKILL.md changed across ${s.flips === 1 ? "that step" : "those steps"}, while this scenario's own stimulus` +
199
+ ` and rubric did not — so it is either a side effect of that edit or a boundary cell, and the record cannot say which`);
200
+ }
201
+ else if (s.flipsAcrossSkillEdit > 0) {
202
+ parts.push(`${s.flipsAcrossSkillEdit} of them across a SKILL.md edit`);
203
+ }
204
+ else {
205
+ parts.push(`on unchanged skill text — treat a single run of this cell as one draw, not a measurement`);
206
+ }
207
+ return parts.join("; ");
208
+ }
209
+ if (s.state === "stable") {
210
+ // "across N comparable step(s)", not "across N runs": the window can hold runs whose
211
+ // steps were rejected, and claiming those as agreement would overstate the evidence.
212
+ return `${s.id} held its verdict across ${s.compared} comparable run-to-run step(s) (${verdictPath(s)})`;
213
+ }
214
+ const why = new Map();
215
+ for (const p of s.pairs)
216
+ if (p.status !== "compared")
217
+ why.set(p.status, (why.get(p.status) ?? 0) + 1);
218
+ const reasons = [...why.entries()].map(([status, n]) => `${n} ${REJECTION[status]}`);
219
+ const changed = [...new Set(s.pairs.flatMap((p) => p.changedSources))];
220
+ const detail = changed.length > 0 ? ` (${changed.join(", ")} changed — an edit, not a flip)` : "";
221
+ return s.points.length < 2
222
+ ? `${s.id} has ${s.points.length} run in this mode — no run-over-run comparison exists yet`
223
+ : `${s.id} has no comparable run-to-run step: ${reasons.join(", ")}${detail}`;
224
+ }
225
+ const REJECTION = {
226
+ compared: "compared",
227
+ inconclusive: "step(s) with an ERROR or unresolved misfire",
228
+ aggregation: "step(s) aggregated differently (reps or pass threshold)",
229
+ sources: "step(s) where the scenario's own sources changed",
230
+ unverified: "step(s) whose recorded hashes cannot be compared",
231
+ };
232
+ //# sourceMappingURL=stability.js.map
package/dist/trends.d.ts CHANGED
@@ -14,6 +14,17 @@ export interface TrendRun {
14
14
  export interface TrendModel {
15
15
  model: string;
16
16
  tag: string;
17
+ /**
18
+ * The delivery mode every run in this series shares (`green` or `force`).
19
+ *
20
+ * A series is per tag AND per mode, never pooled: the two modes are different
21
+ * deliveries of the same text, and placement moves verdicts in both directions at
22
+ * once (measured on identical skill text: `build` A1 0/3 → 3/3 with force, `plan`
23
+ * C2 3/3 → 0/3). A sparkline that ran green then force would draw that epoch
24
+ * change as skill progress — or regression — which is the one thing a trend line
25
+ * must not invent.
26
+ */
27
+ mode: string;
17
28
  runs: TrendRun[];
18
29
  truncated: boolean;
19
30
  skipped: number;
@@ -27,6 +38,34 @@ export interface TrendData {
27
38
  }[];
28
39
  models: TrendModel[];
29
40
  }
41
+ /** One model tag's scored run history in ONE delivery mode, chronologically ascending. */
42
+ export interface ScoredRunGroup {
43
+ tag: string;
44
+ mode: string;
45
+ model: string;
46
+ runs: ResultsFile[];
47
+ /** Runs in this tag whose results.yaml could not be parsed (per tag, not per mode). */
48
+ skipped: number;
49
+ }
50
+ /**
51
+ * Walk `<skillDir>/tests/results/` and group every SCORED run by model tag × delivery
52
+ * mode, chronologically (timestamp-slug dir names sort correctly).
53
+ *
54
+ * The single history reader: `collectTrends` renders it, `collectStability` derives
55
+ * run-over-run flips from it. Two walkers over the same tree is how "which runs count"
56
+ * drifts — the mistake that had force runs excluded from scoring in seven places at
57
+ * once (see SCORED_MODES).
58
+ *
59
+ * Red runs are excluded: a baseline has no grade, and pairing it with anything would
60
+ * compare a skill-off run to a skill-on one. Green and force are never pooled into one
61
+ * group — placement moves verdicts, so a green run and a force run of the same scenario
62
+ * are two measurements, not two samples.
63
+ *
64
+ * A run whose `results.yaml` fails to parse (e.g. an interrupted non-atomic write) is
65
+ * logged via `console.warn`, skipped, and counted in `skipped` — never thrown, because
66
+ * one torn file must not take down a whole read-only view.
67
+ */
68
+ export declare function collectScoredRuns(skillDir: string): ScoredRunGroup[];
30
69
  /**
31
70
  * Per model-tag, read the full run history (not just the latest) from
32
71
  * <skillDir>/tests/results/, chronologically (timestamp-slug dir names sort
@@ -35,15 +74,18 @@ export interface TrendData {
35
74
  * rule: an override resolves a misfire) + reps flakiness. Read-only; no
36
75
  * absolute paths in the result.
37
76
  *
38
- * Only scored (mode === "green") runs are included in the history — a
39
- * red/force run has no real grade (`effective_grade` is a "not scored"
40
- * placeholder; see run.ts) and would otherwise plot as a misleading 0% dip in
41
- * the sparkline/grid. Non-green runs are deliberately excluded, which is
42
- * distinct from `skipped`: a run's mode can only be known after reading its
43
- * results.yaml, so every candidate run-dir in the tag is read (not just the
44
- * most recent `limit`) before filtering to green and applying the `limit`
45
- * window — trends is a bounded, on-demand, local view, so this extra read
46
- * cost is acceptable. If a tag has zero green runs, it's omitted entirely.
77
+ * Only scored runs are included in the history — a red baseline has no real grade
78
+ * (`effective_grade` is a "not scored" placeholder; see run.ts) and would otherwise
79
+ * plot as a misleading 0% dip in the sparkline/grid. Red runs are deliberately
80
+ * excluded, which is distinct from `skipped`: a run's mode can only be known after
81
+ * reading its results.yaml, so every candidate run-dir in the tag is read (not just
82
+ * the most recent `limit`) before filtering and applying the `limit` window
83
+ * trends is a bounded, on-demand, local view, so this extra read cost is
84
+ * acceptable.
85
+ *
86
+ * Green and force runs both count, but never in the same series: a tag with both
87
+ * yields one TrendModel per mode (see `TrendModel.mode`), each with its own
88
+ * `limit` window. A tag with no scored run at all is omitted entirely.
47
89
  *
48
90
  * A run whose `results.yaml` fails to parse (e.g. an interrupted non-atomic
49
91
  * write) is logged via `console.warn` and skipped — never surfaced or thrown —