@skill-harness/core 0.3.1 → 0.4.0

package/dist/regate.js

@@ -0,0 +1,195 @@
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseVerdict, detectMisfire } from "./grade.js";
+import { evaluateNeedleGates, hasNeedleGates } from "./seeded.js";
+import { judgeOneRep } from "./regrade.js";
+import { readResults, writeResults, transcriptPath, judgeRawPath, repIndexOf, findDiffFiles, effectiveThreshold, } from "./results.js";
+import { outcomesToResult } from "./reps.js";
+import { appendJournal } from "./journal.js";
+import { gatesDigest, GATES_PREFIX } from "./sources.js";
+/** Marker in a saved transcript that a needle gate reported a failure. */
+const GATE_FAILED_RE = /: (MISSING|PRESENT)$/m;
+const TRAILER = "=== SEEDED GATES ===";
+const DIFF_HEADER = "=== STAGED DIFF ===";
+/**
+ * Rebuild a transcript with a fresh gates trailer, preserving the model's turns and
+ * the embedded diff exactly.
+ *
+ * The trailer is harness-generated annotation appended *after* the model's output, so
+ * regenerating it corrects our own note rather than falsifying a transcript. The old
+ * file is still kept beside the new one (`.pre-regate.txt`) so the audit trail never
+ * depends on the reader accepting that distinction.
+ */
+function rewriteTranscript(path, gateLines) {
+    const original = readFileSync(path, "utf8");
+    const trailerAt = original.indexOf(TRAILER);
+    if (trailerAt === -1)
+        return; // no trailer to correct (non-seeded shape); leave it alone
+    const diffAt = original.indexOf(DIFF_HEADER);
+    const head = original.slice(0, trailerAt);
+    const tail = diffAt === -1 ? "" : original.slice(diffAt);
+    renameSync(path, path.replace(/\.txt$/, ".pre-regate.txt"));
+    writeFileSync(path, `${head}${TRAILER}\n${gateLines.join("\n")}\n\n${tail}`, "utf8");
+}
+/** Recover a rep's judge verdict from its saved judge-raw artifact — free, and exact. */
+function verdictFromSavedJudgement(runDir, id, rep) {
+    const path = judgeRawPath(runDir, id, "green", rep);
+    if (!existsSync(path))
+        return null;
+    const raw = readFileSync(path, "utf8");
+    const parsed = parseVerdict(raw);
+    return { verdict: parsed.verdict, reason: parsed.reason, suspect: detectMisfire(raw, parsed.verdict) };
+}
+/**
+ * Re-evaluate needle gates against a run's **saved staged diffs** and re-decide the
+ * verdicts they determined — without re-running the model.
+ *
+ * `diff_contains` / `diff_excludes` are pure functions of the diff, and since
+ * `f6a5f6c` every seeded rep persists its diff as a run artifact. So the defect class
+ * "the gate was wrong, the behavior wasn't" — hit three times in the reference corpus
+ * (a context needle, a baseline-satisfied needle, a filename needle) — no longer costs
+ * a re-run. Measured on the C2 needle fix: **9 judge calls instead of 81
+ * rep-executions across three models.**
+ *
+ * Per rep, exactly one of four things happens:
+ *
+ * | old gate | new gate | outcome | cost |
+ * |---|---|---|---|
+ * | fail | fail | FAIL, with the corrected reason | free |
+ * | pass | fail | FAIL — the gate is objective and it says no | free |
+ * | pass | pass | the rep's saved judgement, re-parsed from its judge-raw artifact | free |
+ * | fail | pass | judged now: the judge never saw this rep, because the gate blocked it | 1 judge call |
+ *
+ * That third row is what keeps this cheap without guessing: a rep the judge already
+ * saw has its verdict on disk, so regate re-reads it rather than re-asking.
+ *
+ * **Limits, deliberately hard failures rather than partial work:** `assert.vitest` and
+ * `assert.post_test` need the workspace and cannot be re-evaluated from any artifact,
+ * so a scenario carrying either is not regatable. Diffs and judge-raw files are
+ * gitignored, so this works for whoever holds the run dirs — the repo owner, or CI that
+ * just ran — which is exactly the situation it is needed in.
+ */
+export async function regateRun(opts) {
+    const now = opts.now ?? (() => new Date().toISOString());
+    const prev = readResults(opts.runDir);
+    const specById = new Map(opts.spec.scenarios.map((s) => [s.id, s]));
+    // Why a scenario cannot be regated, collected rather than thrown one at a time: a
+    // mixed spec (needles here, vitest there) should regate what it can, and only a run
+    // with nothing regatable is an error worth refusing.
+    const blocked = [];
+    const targets = [];
+    for (const rec of prev.scenarios) {
+        const s = specById.get(rec.id);
+        if (!s || !hasNeedleGates(s))
+            continue; // nothing for regate to re-decide
+        if (s.assert?.vitest || s.assert?.post_test) {
+            blocked.push(`${s.id}: declares ${s.assert.vitest ? "assert.vitest" : "assert.post_test"}, which needs the workspace — ` +
+                `no saved artifact can stand in for it, so this scenario needs a re-run`);
+            continue;
+        }
+        if (findDiffFiles(opts.runDir, s.id, "green").length === 0) {
+            blocked.push(`${s.id}: no staged-diff artifact on disk (\`.diff.txt\` is gitignored — regate needs the run dir that produced it)`);
+            continue;
+        }
+        targets.push(s);
+    }
+    if (targets.length === 0) {
+        throw new Error(`nothing to regate in ${opts.runDir}` +
+            (blocked.length > 0 ? `:\n  ${blocked.join("\n  ")}` : " — no scenario declares diff_contains/diff_excludes"));
+    }
+    const changes = [];
+    let judgeCalls = 0;
+    const scenarios = [];
+    for (const rec of prev.scenarios) {
+        const scenario = targets.find((s) => s.id === rec.id);
+        if (!scenario) {
+            scenarios.push(rec); // untouched: not regatable, or no gates
+            continue;
+        }
+        const diffFiles = findDiffFiles(opts.runDir, scenario.id, "green");
+        const outcomes = [];
+        // Per scenario, not run-wide: with several regated scenarios, a global counter
+        // would report every change as "re-judged" because some other scenario was.
+        let judgedHere = 0;
+        let gateFailedHere = false;
+        for (const file of diffFiles) {
+            const rep = repIndexOf(file) ?? undefined;
+            const diff = readFileSync(join(opts.runDir, file), "utf8");
+            const gate = evaluateNeedleGates(scenario, diff);
+            const tPath = transcriptPath(opts.runDir, scenario.id, "green", rep);
+            const before = existsSync(tPath) ? readFileSync(tPath, "utf8") : "";
+            const oldGateFailed = GATE_FAILED_RE.test(before.slice(before.indexOf(TRAILER)));
+            // The trailer is regenerated whatever the outcome: leaving a stale
+            // `MISSING` note beside a corrected verdict would misinform the next reader
+            // (and the next judge, which reads this transcript).
+            if (existsSync(tPath))
+                rewriteTranscript(tPath, gate.lines);
+            if (gate.failure) {
+                gateFailedHere = true;
+                outcomes.push({ verdict: "FAIL", reason: gate.failure, suspect: false });
+                continue;
+            }
+            if (!oldGateFailed) {
+                // The judge already saw this rep. Its verdict is on disk — re-read it rather
+                // than paying to ask the same question again.
+                const saved = verdictFromSavedJudgement(opts.runDir, scenario.id, rep);
+                outcomes.push(saved ?? { verdict: rec.judge_verdict, reason: rec.judge_reason, suspect: rec.suspect });
+                continue;
+            }
+            // The gate blocked this rep before, so no judgement of it exists anywhere.
+            const transcript = readFileSync(tPath, "utf8");
+            outcomes.push(await judgeOneRep({
+                runDir: opts.runDir, spec: opts.spec, scenario, transcript,
+                adapter: opts.adapter, judge: opts.judge, specDir: opts.specDir,
+                mode: "green", rep, now,
+            }));
+            judgeCalls++;
+            judgedHere++;
+        }
+        const threshold = effectiveThreshold(rec, scenario);
+        const next = outcomesToResult(scenario.id, outcomes, outcomes.length, threshold);
+        // Overrides and their notes survive: a regate re-decides the gate, and an author
+        // override is a statement about the judge, not about the needle.
+        scenarios.push({ ...next, override: rec.override, note: rec.note });
+        const to = next.judge_verdict;
+        if (to !== rec.judge_verdict) {
+            changes.push({
+                id: scenario.id, from: rec.judge_verdict, to,
+                gate: gateFailedHere ? "fail" : "pass",
+                judged: judgedHere > 0,
+            });
+        }
+    }
+    const ctx = prev.mode === "green" && !prev.partial
+        ? { shipBar: opts.spec.ship_bar, critical: opts.spec.critical }
+        : null;
+    const results = writeResults(opts.runDir, {
+        skill: prev.skill, harness: prev.harness, model: prev.model,
+        judge: { provider: opts.judge.provider, model: opts.judge.model },
+        timestamp: prev.timestamp, label: prev.label, mode: prev.mode, partial: prev.partial,
+        // Only the `gates:` keys of the scenarios actually re-evaluated. Stimulus, rubric
+        // and policy were not re-decided here, so their hashes stay exactly as recorded.
+        source_hashes: refreshGateHashes(prev.source_hashes, targets),
+        scenarios,
+    }, ctx);
+    appendJournal(opts.runDir, {
+        event: "regate", ts: now(),
+        scenarios: targets.map((s) => s.id),
+        changed: changes.map((c) => `${c.id}: ${c.from}->${c.to} (gate ${c.gate}${c.judged ? ", re-judged" : ""})`),
+        judge_calls: judgeCalls,
+        ...(blocked.length > 0 ? { skipped: blocked } : {}),
+    });
+    return { results, changes, judgeCalls };
+}
+function refreshGateHashes(recorded, regated) {
+    if (!recorded)
+        return undefined;
+    const next = { ...recorded };
+    for (const s of regated) {
+        const digest = gatesDigest(s);
+        if (digest !== null && GATES_PREFIX + s.id in next)
+            next[GATES_PREFIX + s.id] = digest;
+    }
+    return next;
+}
+//# sourceMappingURL=regate.js.map

package/dist/regrade.d.ts

@@ -2,6 +2,19 @@ import type { Spec, Scenario } from "./spec.js";
 import type { HarnessAdapter, ModelRef } from "./adapters/types.js";
 import { type ScenarioResult, type ResultsFile } from "./results.js";
 import { type RepOutcome } from "./reps.js";
+/**
+ * Carry a run's recorded hashes forward, refreshing only the `rubric:` keys this
+ * re-grade actually judged under (plus the persona, which applies to all of them).
+ *
+ * Everything else is preserved deliberately: the transcripts were produced by the old
+ * stimulus, so a stimulus hash must stay stale until someone re-runs. `--suspect-only`
+ * is why this takes an id list rather than refreshing every rubric key — a re-grade
+ * that touched two scenarios must not certify the rubric of the twelve it skipped.
+ *
+ * No hashes recorded (a pre-`source_hashes` run) stays that way: inventing hashes for
+ * a run that never recorded any would claim a coverage it does not have.
+ */
+export declare function refreshRubricHashes(recorded: Record<string, string> | undefined, spec: Spec, judgedIds: string[]): Record<string, string> | undefined;
 export interface RegradeOptions {
     runDir: string;
     spec: Spec;

package/dist/regrade.js

@@ -4,6 +4,35 @@ import { buildJudgePrompt, judgeInWorkspace } from "./grade.js";
 import { findTranscriptFiles, judgeRawPath, repIndexOf, readResults, writeResults, effectiveThreshold, } from "./results.js";
 import { outcomesToResult } from "./reps.js";
 import { appendJournal } from "./journal.js";
+import { rubricDigest, personaDigest, RUBRIC_PREFIX, PERSONA_KEY } from "./sources.js";
+/**
+ * Carry a run's recorded hashes forward, refreshing only the `rubric:` keys this
+ * re-grade actually judged under (plus the persona, which applies to all of them).
+ *
+ * Everything else is preserved deliberately: the transcripts were produced by the old
+ * stimulus, so a stimulus hash must stay stale until someone re-runs. `--suspect-only`
+ * is why this takes an id list rather than refreshing every rubric key — a re-grade
+ * that touched two scenarios must not certify the rubric of the twelve it skipped.
+ *
+ * No hashes recorded (a pre-`source_hashes` run) stays that way: inventing hashes for
+ * a run that never recorded any would claim a coverage it does not have.
+ */
+export function refreshRubricHashes(recorded, spec, judgedIds) {
+    if (!recorded)
+        return undefined;
+    const next = { ...recorded };
+    const specById = new Map(spec.scenarios.map((s) => [s.id, s]));
+    for (const id of judgedIds) {
+        const s = specById.get(id);
+        // Only refresh a key the run already carried: adding one for a scenario whose
+        // rubric was never hashed would fabricate coverage.
+        if (s && RUBRIC_PREFIX + id in next)
+            next[RUBRIC_PREFIX + id] = rubricDigest(s);
+    }
+    if (PERSONA_KEY in next)
+        next[PERSONA_KEY] = personaDigest(spec.judge_persona);
+    return next;
+}
 /** Judge one saved transcript: writes the judge-raw artifact, emits a `judge-verdict` journal event (plus `misfire-flag` when the verdict is suspect), and returns the outcome. */
 export async function judgeOneRep(opts) {
     const { runDir, spec, scenario, transcript, adapter, judge, specDir, mode, rep, now } = opts;
@@ -112,9 +141,14 @@ export async function regradeRun(opts) {
         label: prev?.label ?? null,
         mode,
         // A re-grade judges the SAVED transcripts, which were produced by the OLD text —
-        // the recorded hashes stay, keeping an honestly-stale run honestly stale.
+        // the recorded **stimulus** hashes stay, keeping an honestly-stale run honestly
+        // stale. The rubric hashes are a different matter: this re-grade applied the
+        // CURRENT checklist and persona to those transcripts, so "the verdicts reflect
+        // today's rubric" is now a true statement about the record, and the hashes should
+        // say so. Doctrine narrowed 0.4.0, from "recorded hashes stay" to "recorded
+        // *stimulus* hashes stay" — see refreshRubricHashes.
         partial: prev?.partial,
-        source_hashes: prev?.source_hashes,
+        source_hashes: refreshRubricHashes(prev?.source_hashes, spec, targets),
         scenarios: scenarioResults,
     }, ctx);
     const g = results.effective_grade;

package/dist/rescore.js

@@ -2,6 +2,27 @@ import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { readResults, writeResults } from "./results.js";
 import { appendJournal } from "./journal.js";
+import { policyDigest, POLICY_PREFIX } from "./sources.js";
+/**
+ * Refresh the `policy:` keys a run recorded, since a rescore has just re-applied the
+ * current policy to every rep it holds.
+ *
+ * Unlike a re-grade, this needs no id list: `rescoreRun` walks every recorded
+ * scenario, and the ones it carries verbatim (single-rep, ERROR, JUDGE-AMBIGUOUS) are
+ * carried *because the current threshold cannot change their verdict* — they are
+ * scored under today's policy too. Only keys the run already carried are touched, so
+ * this never fabricates coverage.
+ */
+function refreshPolicyHashes(recorded, spec) {
+    if (!recorded)
+        return undefined;
+    const next = { ...recorded };
+    for (const s of spec.scenarios) {
+        if (POLICY_PREFIX + s.id in next)
+            next[POLICY_PREFIX + s.id] = policyDigest(s);
+    }
+    return next;
+}
 /**
  * Re-score a run against the CURRENT spec's pass thresholds — no model calls, no judge
  * calls. Reps are the raw measurement (`passes` of `clean`); a threshold is *policy*.
@@ -46,7 +67,13 @@ export function rescoreRun(opts) {
     const results = writeResults(opts.runDir, {
         skill: prev.skill, harness: prev.harness, model: prev.model, judge: prev.judge,
         timestamp: prev.timestamp, label: prev.label, mode: prev.mode,
-        partial: prev.partial, source_hashes: prev.source_hashes, scenarios,
+        partial: prev.partial,
+        // A rescore re-applies the CURRENT policy (thresholds, critical set) to the
+        // recorded reps, so `policy:` drift is genuinely resolved by having run this —
+        // that is what makes `rescore` the honest remedy lint names for it. Stimulus,
+        // rubric and gate hashes are untouched: none of them was re-evaluated here.
+        source_hashes: refreshPolicyHashes(prev.source_hashes, opts.spec),
+        scenarios,
     }, ctx);
     appendJournal(opts.runDir, {
         event: "rescore", ts: now(),

package/dist/results.d.ts

@@ -25,6 +25,16 @@ export interface GradeSummary {
 }
 export interface ResultsFile {
     schema: 2;
+    /**
+     * The harness version that wrote this file — provenance for the numbers in it.
+     *
+     * Optional because runs recorded before the field existed do not have one, and
+     * inventing a version for them would fabricate provenance. Not part of `schema`:
+     * 0.2.1 → 0.3.0 kept `schema: 2` while changing what a verdict means, which is
+     * exactly the drift `schema` cannot express. Written by `finalizeResults`, so no
+     * writer can forget it.
+     */
+    harness_version?: string;
     skill: string;
     harness: string;
     model: string;

package/dist/results.js

@@ -3,6 +3,7 @@ import { join, relative, sep } from "node:path";
 import yaml from "js-yaml";
 import { modelSlug } from "./adapters/types.js";
 import { score } from "./score.js";
+import { HARNESS_VERSION } from "./version.js";
 /** The pass-threshold a re-grade uses: the run's persisted value, else the spec's per-scenario value, else 0.5. */
 export function effectiveThreshold(prevScenario, scenario) {
     return prevScenario?.pass_threshold ?? scenario.passThreshold ?? 0.5;
@@ -51,6 +52,10 @@ export function finalizeResults(draft, ctx) {
     }
     return {
         schema: 2,
+        // Stamped here, the single place every writer passes through, so `run`,
+        // `grade`, `rescore` and the review UI's override save all record which tool
+        // produced the record they leave behind.
+        harness_version: HARNESS_VERSION,
         skill: draft.skill,
         harness: draft.harness,
         model: draft.model,

package/dist/run.js

@@ -73,7 +73,7 @@ export async function runSkillModel(opts) {
         ...(partial ? { partial: true } : {}),
         // Only the scenarios this run actually measured: a --only run must not claim
         // coverage of scenarios it skipped.
-        source_hashes: sourceHashes({ skillDir, specDir: dirname(opts.specPath), scenarios }),
+        source_hashes: sourceHashes({ skillDir, specDir: dirname(opts.specPath), scenarios, judgePersona: spec.judge_persona }),
         scenarios: scenarioResults,
     }, ctx);
     if (ctx) {

package/dist/seeded.d.ts

@@ -58,6 +58,24 @@ export interface SeededOutcome {
  * guessing from prefixes.
  */
 export declare function changedLines(diff: string): string;
+/** Whether a scenario declares any needle gate at all. */
+export declare function hasNeedleGates(scenario: Scenario): boolean;
+/**
+ * Evaluate `diff_contains` / `diff_excludes` against a staged diff: the trailer lines
+ * to report, and the first failure (null when every needle is satisfied).
+ *
+ * A **pure function of the diff**, which is what makes `regate` possible — the saved
+ * `.diff.txt` artifact holds everything these gates need, so correcting a needle never
+ * requires re-running the model. Shared with `regate` deliberately: two copies of this
+ * loop would let a regated verdict disagree with what a fresh run would have produced,
+ * which is the same drift the fixture-marker check refuses between lint and runtime.
+ *
+ * Both gates read the CHANGED lines only, never context — see `changedLines`.
+ */
+export declare function evaluateNeedleGates(scenario: Scenario, diff: string): {
+    lines: string[];
+    failure: string | null;
+};
 /**
  * Cut a diff to a byte budget on a line boundary, appending an explicit marker
  * naming how much was dropped.

package/dist/seeded.js

@@ -56,6 +56,42 @@ export function changedLines(diff) {
     }
     return out.join("\n");
 }
+/** Whether a scenario declares any needle gate at all. */
+export function hasNeedleGates(scenario) {
+    return (scenario.assert?.diff_contains?.length ?? 0) > 0 || (scenario.assert?.diff_excludes?.length ?? 0) > 0;
+}
+/**
+ * Evaluate `diff_contains` / `diff_excludes` against a staged diff: the trailer lines
+ * to report, and the first failure (null when every needle is satisfied).
+ *
+ * A **pure function of the diff**, which is what makes `regate` possible — the saved
+ * `.diff.txt` artifact holds everything these gates need, so correcting a needle never
+ * requires re-running the model. Shared with `regate` deliberately: two copies of this
+ * loop would let a regated verdict disagree with what a fresh run would have produced,
+ * which is the same drift the fixture-marker check refuses between lint and runtime.
+ *
+ * Both gates read the CHANGED lines only, never context — see `changedLines`.
+ */
+export function evaluateNeedleGates(scenario, diff) {
+    const changed = changedLines(diff);
+    const lines = [];
+    let failure = null;
+    for (const needle of scenario.assert?.diff_contains ?? []) {
+        const ok = changed.includes(needle);
+        lines.push(`  diff_contains ${JSON.stringify(needle)}: ${ok ? "OK" : "MISSING"}`);
+        if (!ok && !failure)
+            failure = `staged diff missing ${JSON.stringify(needle)}`;
+    }
+    // Scope discipline, stated as a fact about the diff rather than inferred from
+    // whether the model remembered to say "I left lastIndex alone".
+    for (const needle of scenario.assert?.diff_excludes ?? []) {
+        const ok = !changed.includes(needle);
+        lines.push(`  diff_excludes ${JSON.stringify(needle)}: ${ok ? "OK" : "PRESENT"}`);
+        if (!ok && !failure)
+            failure = `staged diff touches forbidden ${JSON.stringify(needle)}`;
+    }
+    return { lines, failure };
+}
 /**
  * Byte cap on the diff copy embedded in the judged transcript. The judge prompt
  * is a single request, so an unbounded diff (a fixture-wide refactor, a
@@ -167,21 +203,10 @@ export async function runSeeded(scenario, opts) {
     // either token. Every published A4 result recorded that as an objective pass.
     // Read against changed lines it means what the checklist means: the model
     // returned a Result.
-    const changed = changedLines(diff);
-    for (const needle of scenario.assert?.diff_contains ?? []) {
-        const ok = changed.includes(needle);
-        parts.push(`  diff_contains ${JSON.stringify(needle)}: ${ok ? "OK" : "MISSING"}`);
-        if (!ok && !gateFailure)
-            gateFailure = `staged diff missing ${JSON.stringify(needle)}`;
-    }
-    // Scope discipline, stated as a fact about the diff rather than inferred from
-    // whether the model remembered to say "I left lastIndex alone".
-    for (const needle of scenario.assert?.diff_excludes ?? []) {
-        const ok = !changed.includes(needle);
-        parts.push(`  diff_excludes ${JSON.stringify(needle)}: ${ok ? "OK" : "PRESENT"}`);
-        if (!ok && !gateFailure)
-            gateFailure = `staged diff touches forbidden ${JSON.stringify(needle)}`;
-    }
+    const needles = evaluateNeedleGates(scenario, diff);
+    parts.push(...needles.lines);
+    if (needles.failure && !gateFailure)
+        gateFailure = needles.failure;
     if (scenario.assert?.vitest) {
         const v = await runVitest([], repo);
         // code === null means exec SIGKILLed it at the timeout. That is infrastructure,

package/dist/sources.d.ts

@@ -37,8 +37,44 @@ import type { Scenario } from "./spec.js";
  * reindenting the YAML or reordering scenarios is correctly a no-op, while
  * changing a single checklist word is correctly a change.
  */
+/**
+ * The pre-0.4.0 combined key: one digest over a scenario's stimulus, rubric, policy
+ * and gates together. Still read (runs recorded with it must keep comparing), never
+ * written. See `scenarioDigest`.
+ */
 export declare const SCENARIO_PREFIX = "scenario:";
 export declare const FIXTURE_PREFIX = "fixture:";
+/**
+ * The split: three (four, with gates) digests per scenario, each mapped to the
+ * cheapest tool that can honestly restore freshness.
+ *
+ * | key | contents | drift means | remedy |
+ * |---|---|---|---|
+ * | `stimulus:<id>` | mode, turns, workspace, remote, agent-file path, fixture path, `assert.vitest`, `post_test` path | the transcripts answer a different question | `run` (model + judge) |
+ * | `rubric:<id>` | title, checklist | transcripts fine, verdicts wrong | `grade` (judge only) |
+ * | `policy:<id>` | critical, reps, pass_threshold | only the scoring moved | `rescore` (free) |
+ * | `gates:<id>` | `diff_contains`, `diff_excludes` | needle wrong, behavior fine | `regate` (free; judges only flipped reps) |
+ * | `rubric:__persona` | spec-level `judge_persona` | every verdict in the skill | `grade` per model |
+ *
+ * Why this matters more than it looks: with one key, lint had exactly one remedy for
+ * any drift — "re-run" — so **correcting a rubric cost model spend**. Measured on the
+ * reference corpus, two parked branches (one needle, one checklist rewrite) demanded
+ * 135 rep-executions to restore freshness while producing zero new information about
+ * the models. A gate that charges that much to fix a known-bad rubric is pressure to
+ * leave the rubric in place, which inverts the point of having a gate.
+ *
+ * The strictness is unchanged: every edit still marks something stale. Only the price
+ * of getting back to fresh changed.
+ */
+export declare const STIMULUS_PREFIX = "stimulus:";
+export declare const RUBRIC_PREFIX = "rubric:";
+export declare const POLICY_PREFIX = "policy:";
+export declare const GATES_PREFIX = "gates:";
+/**
+ * The spec-level rubric key. `__persona` cannot collide with a scenario id: ids are
+ * validated as `[A-Za-z][A-Za-z0-9_-]*`, so none can begin with an underscore.
+ */
+export declare const PERSONA_KEY = "rubric:__persona";
 /**
  * Recorded in place of a hash when a source existed but could not be read.
  *
@@ -65,14 +101,24 @@ export declare function fileSha256(path: string): string | null;
  * normalised so a Linux-recorded hash still matches on Windows.
  */
 export declare function dirSha256(dir: string): string | null;
+export declare function stimulusDigest(s: Scenario): string;
+export declare function rubricDigest(s: Scenario): string;
+export declare function policyDigest(s: Scenario): string;
+/** Null when the scenario declares no needle gates — no key is recorded for it. */
+export declare function gatesDigest(s: Scenario): string | null;
+/** The spec-level judge persona, which is rubric for every scenario at once. */
+export declare function personaDigest(persona: string): string;
 /**
- * A scenario's semantic digest: everything that changes what the scenario
- * measures, and nothing that doesn't.
+ * The pre-0.4.0 combined digest: everything about a scenario in one hash.
+ *
+ * **Read-only now** — `sourceHashes` writes the four split keys instead. Kept because
+ * `lint` must still compare runs that recorded `scenario:<id>`, and those runs are
+ * every scorecard published before 0.4.0. Deleting it would turn "no findings" into
+ * "no comparison" for the entire existing corpus, silently.
  *
- * Built from the parsed scenario rather than its YAML text, so formatting is
- * irrelevant. `critical` is included because it changes whether the scenario can
- * block a ship; `title` is included because it is what a reader of the scorecard
- * believes was tested.
+ * Its bytes must therefore never change again: this is a stored-hash format, not an
+ * implementation detail. The facet digests take new fields; this one is frozen at the
+ * 0.3.x field set, which is why it does not go through `facets()`.
  */
 export declare function scenarioDigest(s: Scenario): string;
 /**
@@ -89,6 +135,13 @@ export interface SourceContext {
     skillDir: string;
     specDir: string;
     scenarios: Scenario[];
+    /**
+     * The spec's `judge_persona`. Required rather than optional: an optional field that
+     * silently disables the `rubric:__persona` comparison is the blind-spot shape this
+     * module exists to prevent, and making it required lets the compiler find every
+     * caller instead of leaving one quietly un-checked.
+     */
+    judgePersona: string;
 }
 /**
  * Hash every source this run measures: SKILL.md, each distinct
@@ -111,5 +164,13 @@ export declare function sourceHashes(ctx: SourceContext): Record<string, string>
 export declare function currentHashFor(key: string, ctx: SourceContext): string | null | undefined;
 /** Human label for a recorded key, used in lint messages. */
 export declare function describeSourceKey(key: string): string;
+/**
+ * The cheapest command that honestly restores freshness for this key kind.
+ *
+ * This string is the feature. Before the split, lint's only remedy was "re-run", so a
+ * one-word checklist fix cost a full model pass — pressure to leave a known-bad rubric
+ * in place. Naming the actual remedy is what converts that into a free command.
+ */
+export declare function remedyForKey(key: string): string;
 /** The scenario id a key belongs to, for per-scenario lint findings. Undefined for skill-wide keys. */
 export declare function scenarioIdForKey(key: string, scenarios: Scenario[]): string | undefined;