@skill-harness/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mojo Manyana
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapters/types.d.ts

@@ -0,0 +1,29 @@
+export type RunMode = "red" | "green" | "force";
+/** A provider+model pair, e.g. { provider: "fireworks", model: "accounts/.../deepseek-v4-pro" }. */
+export interface ModelRef {
+    provider: string;
+    model: string;
+}
+/** Parse a `provider:model` token (model may contain further colons/slashes). */
+export declare function parseModelRef(token: string): ModelRef;
+/** Stable, filesystem-safe slug for a model ref (used in run-dir names). */
+export declare function modelSlug(ref: ModelRef): string;
+export interface RunReq {
+    skillDir: string;
+    model: ModelRef;
+    mode: RunMode;
+    turns: string[];
+    cwd: string;
+}
+/** A judge request: single prompt, no skills, no session. */
+export interface JudgeReq {
+    model: ModelRef;
+    prompt: string;
+    cwd: string;
+}
+export interface HarnessAdapter {
+    name: string;
+    available(): Promise<boolean>;
+    run(req: RunReq): Promise<string>;
+    judge(req: JudgeReq): Promise<string>;
+}

package/dist/adapters/types.js

@@ -0,0 +1,18 @@
+/** Parse a `provider:model` token (model may contain further colons/slashes). */
+export function parseModelRef(token) {
+    const i = token.indexOf(":");
+    if (i < 0) {
+        throw new Error(`model must be \`provider:model\` (got \`${token}\`)`);
+    }
+    const provider = token.slice(0, i).trim();
+    const model = token.slice(i + 1).trim();
+    if (!provider || !model) {
+        throw new Error(`model must be \`provider:model\` (got \`${token}\`)`);
+    }
+    return { provider, model };
+}
+/** Stable, filesystem-safe slug for a model ref (used in run-dir names). */
+export function modelSlug(ref) {
+    return `${ref.provider}-${ref.model}`.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+//# sourceMappingURL=types.js.map

package/dist/discover.d.ts

@@ -0,0 +1,14 @@
+export interface DiscoveredSkill {
+    name: string;
+    dir: string;
+    hasSpec: boolean;
+    specPath: string;
+}
+/**
+ * Scan a skills root. A "skill" is any immediate subdirectory containing a
+ * SKILL.md. It is testable iff `<skill>/tests/specification.yaml` exists.
+ * Returns skills sorted by name (testable or not).
+ */
+export declare function discover(root: string): DiscoveredSkill[];
+/** Resolve a single skill by name; throws a helpful error if absent or specless. */
+export declare function resolveSkill(root: string, name: string): DiscoveredSkill;

package/dist/discover.js

@@ -0,0 +1,35 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Scan a skills root. A "skill" is any immediate subdirectory containing a
+ * SKILL.md. It is testable iff `<skill>/tests/specification.yaml` exists.
+ * Returns skills sorted by name (testable or not).
+ */
+export function discover(root) {
+    if (!existsSync(root) || !statSync(root).isDirectory()) {
+        throw new Error(`skills root is not a directory: ${root}`);
+    }
+    const skills = [];
+    for (const name of readdirSync(root)) {
+        if (name.startsWith("."))
+            continue;
+        const dir = join(root, name);
+        if (!statSync(dir).isDirectory())
+            continue;
+        if (!existsSync(join(dir, "SKILL.md")))
+            continue;
+        const specPath = join(dir, "tests", "specification.yaml");
+        skills.push({ name, dir, hasSpec: existsSync(specPath), specPath });
+    }
+    skills.sort((a, b) => a.name.localeCompare(b.name));
+    return skills;
+}
+/** Resolve a single skill by name; throws a helpful error if absent or specless. */
+export function resolveSkill(root, name) {
+    const skill = discover(root).find((s) => s.name === name);
+    if (!skill) {
+        throw new Error(`no skill \`${name}\` under ${root}`);
+    }
+    return skill;
+}
+//# sourceMappingURL=discover.js.map

package/dist/grade.d.ts

@@ -0,0 +1,44 @@
+import type { Scenario } from "./spec.js";
+import type { HarnessAdapter, ModelRef } from "./adapters/types.js";
+import type { Verdict } from "./score.js";
+export interface JudgePromptInput {
+    skill: string;
+    persona: string;
+    scenario: Scenario;
+    transcript: string;
+}
+/** Build the LLM-judge prompt for one transcript (ported from the old grade.sh). */
+export declare function buildJudgePrompt(input: JudgePromptInput): string;
+export interface ParsedVerdict {
+    verdict: Verdict;
+    reason: string;
+}
+/** Parse a judge's raw output into a verdict + reason. Unparseable → ERROR. */
+export declare function parseVerdict(out: string): ParsedVerdict;
+/**
+ * Judge-≠-subject de-confound guard. True when the judge resembles the model
+ * under test: same provider AND one model id contains the other (same family).
+ * opus-judging-opus inflated scores before — never let the judge sit in the model set.
+ */
+export declare function judgeResemblesSubject(judge: ModelRef, subject: ModelRef): boolean;
+export interface GradeResult extends ParsedVerdict {
+    raw: string;
+    /** Judge misfire: the overall verdict disagrees with AND(per-item grades). Recorded, never auto-passed; blocks SHIP until re-judged or overridden. */
+    suspect: boolean;
+}
+/**
+ * Judge-misfire detector: parse the judge's per-checklist-item grades and assert
+ * the overall verdict equals AND(items). A mismatch in EITHER direction — verdict
+ * PASS with a FAILed item (false-pass), or verdict FAIL with every item PASSing
+ * (the observed ~2% false-fail class) — is a misfire. Fail-open: if no item lines
+ * parse, or the verdict is ERROR, return false (never block a run on a parse miss).
+ */
+export declare function detectMisfire(raw: string, verdict: Verdict): boolean;
+/** Drive the judge for one transcript and parse the result. */
+export declare function gradeTranscript(adapter: HarnessAdapter, judge: ModelRef, prompt: string, cwd: string): Promise<GradeResult>;
+/**
+ * Grade a transcript in a fresh, isolated, throwaway workspace — never the
+ * subject's scenario dir — so the judge can't ingest repo context the subject
+ * left behind (matters for CLI judges that read cwd, e.g. claude-code).
+ */
+export declare function judgeInWorkspace(adapter: HarnessAdapter, judge: ModelRef, prompt: string, specDir: string): Promise<GradeResult>;

package/dist/grade.js

@@ -0,0 +1,89 @@
+import { createWorkspace } from "./workspace.js";
+/** Build the LLM-judge prompt for one transcript (ported from the old grade.sh). */
+export function buildJudgePrompt(input) {
+    const { skill, persona, scenario, transcript } = input;
+    const numbered = scenario.checklist.map((c, i) => `${i + 1}. ${c}`).join("\n");
+    return `You are grading ONE response from an AI assistant using a "${skill}" skill — ${persona} Judge it ONLY against the checklist below — do not add requirements beyond it.
+
+CHECKLIST (every numbered item must hold for a PASS):
+${numbered}
+
+TRANSCRIPT (the assistant is the model under test):
+${transcript}
+
+Grade each checklist item PASS or FAIL with a <=12-word justification quoting the transcript. Be skeptical: if an item is not clearly satisfied, mark it FAIL. Then output exactly these two lines:
+VERDICT: PASS      (only if EVERY item passed)   — or —   VERDICT: FAIL
+REASON: <15 words or fewer>`;
+}
+const VERDICT_RE = /VERDICT\**\s*:?\s*\**\s*(PASS|FAIL)/i;
+const REASON_RE = /REASON\**\s*:?\s*\**\s*(.*)$/im;
+/** Parse a judge's raw output into a verdict + reason. Unparseable → ERROR. */
+export function parseVerdict(out) {
+    const vm = out.match(VERDICT_RE);
+    if (!vm) {
+        return { verdict: "ERROR", reason: "judge produced no parseable verdict" };
+    }
+    const verdict = vm[1].toUpperCase();
+    const rm = out.match(REASON_RE);
+    const reason = rm ? rm[1].trim() : "";
+    return { verdict, reason };
+}
+/**
+ * Judge-≠-subject de-confound guard. True when the judge resembles the model
+ * under test: same provider AND one model id contains the other (same family).
+ * opus-judging-opus inflated scores before — never let the judge sit in the model set.
+ */
+export function judgeResemblesSubject(judge, subject) {
+    if (judge.provider !== subject.provider)
+        return false;
+    const a = judge.model;
+    const b = subject.model;
+    return a === b || a.includes(b) || b.includes(a);
+}
+const ITEM_RE = /^\s*\d+[.)]\s*\**\s*(PASS|FAIL)\b/gim;
+/**
+ * Judge-misfire detector: parse the judge's per-checklist-item grades and assert
+ * the overall verdict equals AND(items). A mismatch in EITHER direction — verdict
+ * PASS with a FAILed item (false-pass), or verdict FAIL with every item PASSing
+ * (the observed ~2% false-fail class) — is a misfire. Fail-open: if no item lines
+ * parse, or the verdict is ERROR, return false (never block a run on a parse miss).
+ */
+export function detectMisfire(raw, verdict) {
+    if (verdict === "ERROR")
+        return false;
+    const items = [...raw.matchAll(ITEM_RE)].map((m) => m[1].toUpperCase() === "PASS");
+    if (items.length === 0)
+        return false; // fail-open
+    const andItems = items.every((ok) => ok);
+    const verdictBool = verdict === "PASS";
+    return verdictBool !== andItems;
+}
+/** Drive the judge for one transcript and parse the result. */
+export async function gradeTranscript(adapter, judge, prompt, cwd) {
+    const raw = await adapter.judge({ model: judge, prompt, cwd });
+    const parsed = parseVerdict(raw);
+    // On a parse failure, surface what the judge actually emitted (e.g. a provider
+    // error) rather than a generic message — otherwise the cause is invisible.
+    if (parsed.verdict === "ERROR") {
+        const snippet = raw.trim().replace(/\s+/g, " ").slice(0, 160);
+        if (snippet)
+            parsed.reason = `judge unparseable: ${snippet}`;
+    }
+    const suspect = detectMisfire(raw, parsed.verdict);
+    return { ...parsed, raw, suspect };
+}
+/**
+ * Grade a transcript in a fresh, isolated, throwaway workspace — never the
+ * subject's scenario dir — so the judge can't ingest repo context the subject
+ * left behind (matters for CLI judges that read cwd, e.g. claude-code).
+ */
+export async function judgeInWorkspace(adapter, judge, prompt, specDir) {
+    const ws = createWorkspace("none", { specDir });
+    try {
+        return await gradeTranscript(adapter, judge, prompt, ws.cwd);
+    }
+    finally {
+        ws.cleanup();
+    }
+}
+//# sourceMappingURL=grade.js.map

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./spec.js";
+export * from "./discover.js";
+export * from "./run.js";
+export * from "./grade.js";
+export * from "./score.js";
+export * from "./results.js";
+export * from "./journal.js";
+export * from "./scheduler.js";
+export * from "./reps.js";
+export * from "./regrade.js";
+export * from "./workspace.js";
+export * from "./seeded.js";
+export * from "./report.js";
+export * from "./trends.js";
+export * from "./lint.js";
+export * from "./adapters/types.js";
+export * from "./util/exec.js";

package/dist/index.js

@@ -0,0 +1,18 @@
+export * from "./spec.js";
+export * from "./discover.js";
+export * from "./run.js";
+export * from "./grade.js";
+export * from "./score.js";
+export * from "./results.js";
+export * from "./journal.js";
+export * from "./scheduler.js";
+export * from "./reps.js";
+export * from "./regrade.js";
+export * from "./workspace.js";
+export * from "./seeded.js";
+export * from "./report.js";
+export * from "./trends.js";
+export * from "./lint.js";
+export * from "./adapters/types.js";
+export * from "./util/exec.js";
+//# sourceMappingURL=index.js.map

package/dist/journal.d.ts

@@ -0,0 +1,76 @@
+import type { Verdict } from "./score.js";
+/**
+ * Machine-facing event stream for one run: one JSON object per line in
+ * <runDir>/journal.jsonl. UI, trends, and debugging read ONLY this (never
+ * scrape terminal output). `turn` events arrive with per-turn streaming (M4+).
+ *
+ * A re-grade (`skill-harness grade`) appends a second wave of judge-verdict
+ * events and a new score event to the same journal — for a single-rep run
+ * (or a re-grade of one), consumers take the LAST score event and the LAST
+ * judge-verdict per scenario id.
+ *
+ * That "last per id" rule does NOT apply to a `--reps N>1` run: it emits N
+ * `judge-verdict`/`misfire-flag` events per scenario id, one per rep
+ * (identified by the `rep` field), and no aggregate event. These per-rep
+ * events are not an aggregate — results.yaml holds the authoritative
+ * aggregated verdict/pass-rate for the scenario; taking the last per id
+ * would yield an arbitrary rep's verdict, not the aggregated one.
+ */
+export type JournalEvent = {
+    event: "run-started";
+    ts: string;
+    skill: string;
+    harness: string;
+    model: string;
+    judge: {
+        provider: string;
+        model: string;
+    };
+    mode: string;
+    label: string | null;
+} | {
+    event: "scenario-started";
+    ts: string;
+    id: string;
+    title: string;
+} | {
+    event: "gate-result";
+    ts: string;
+    id: string;
+    ok: boolean;
+    detail: string;
+    rep?: number;
+} | {
+    event: "judge-verdict";
+    ts: string;
+    id: string;
+    verdict: Verdict;
+    reason: string;
+    suspect: boolean;
+    rep?: number;
+} | {
+    event: "misfire-flag";
+    ts: string;
+    id: string;
+    reason: string;
+    rep?: number;
+} | {
+    event: "score";
+    ts: string;
+    passed: number;
+    total: number;
+    pct: number;
+    letter: string;
+    ship: boolean;
+    note: string;
+} | {
+    event: "override";
+    ts: string;
+    id: string;
+    override: Verdict | null;
+    note: string;
+};
+export declare function journalPath(runDir: string): string;
+export declare function appendJournal(runDir: string, e: JournalEvent): void;
+/** Read all events; missing file → []. Corrupt lines are skipped, never fatal. */
+export declare function readJournal(runDir: string): JournalEvent[];

package/dist/journal.js

@@ -0,0 +1,32 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+export function journalPath(runDir) {
+    return join(runDir, "journal.jsonl");
+}
+export function appendJournal(runDir, e) {
+    mkdirSync(runDir, { recursive: true });
+    appendFileSync(journalPath(runDir), JSON.stringify(e) + "\n", "utf8");
+}
+/** Read all events; missing file → []. Corrupt lines are skipped, never fatal. */
+export function readJournal(runDir) {
+    const p = journalPath(runDir);
+    if (!existsSync(p))
+        return [];
+    const events = [];
+    for (const line of readFileSync(p, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const ev = JSON.parse(line);
+            if (ev && typeof ev === "object" && typeof ev.event === "string") {
+                events.push(ev);
+            }
+            // else: valid JSON but not a journal event — skip
+        }
+        catch {
+            /* tolerate a torn/corrupt line */
+        }
+    }
+    return events;
+}
+//# sourceMappingURL=journal.js.map

package/dist/lint.d.ts

@@ -0,0 +1,14 @@
+export type LintCode = "spec" | "ship_bar" | "critical" | "fixture" | "consistency" | "lint-error";
+export interface LintFinding {
+    readonly skill: string;
+    readonly scenario?: string;
+    readonly code: LintCode;
+    readonly message: string;
+}
+/**
+ * Validate one skill's spec + fixtures statically (and results-consistency when
+ * committed results exist — see the consistency block). Never throws: a bad spec
+ * becomes a single `code:"spec"` finding. Returns ALL findings so the CLI can
+ * report every problem across every skill.
+ */
+export declare function lintSkill(skillDir: string): LintFinding[];

package/dist/lint.js

@@ -0,0 +1,137 @@
+import { existsSync, statSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import yaml from "js-yaml";
+import { loadSpec, SpecError } from "./spec.js";
+import { readResults, finalizeResults, findTranscriptFiles, resultsPath } from "./results.js";
+/** True if `p` exists and is a directory. Never throws (TOCTOU-safe: a race or dangling
+ * symlink between the check and the stat is treated as "not a directory", not an error). */
+function isDir(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validate one skill's spec + fixtures statically (and results-consistency when
+ * committed results exist — see the consistency block). Never throws: a bad spec
+ * becomes a single `code:"spec"` finding. Returns ALL findings so the CLI can
+ * report every problem across every skill.
+ */
+export function lintSkill(skillDir) {
+    const specPath = join(skillDir, "tests", "specification.yaml");
+    const findings = [];
+    let spec;
+    try {
+        spec = loadSpec(specPath);
+    }
+    catch (e) {
+        const message = e instanceof SpecError ? e.message : e instanceof Error ? e.message : String(e);
+        return [{ skill: basename(skillDir), code: "spec", message }];
+    }
+    const skill = spec.skill;
+    // ship_bar sanity
+    if (spec.ship_bar.total < 1) {
+        findings.push({ skill, code: "ship_bar", message: "ship_bar.total must be >= 1" });
+    }
+    if (spec.ship_bar.min_pass < 1) {
+        findings.push({ skill, code: "ship_bar", message: "ship_bar.min_pass must be >= 1" });
+    }
+    if (spec.ship_bar.min_pass > spec.ship_bar.total) {
+        findings.push({ skill, code: "ship_bar", message: `ship_bar.min_pass (${spec.ship_bar.min_pass}) > total (${spec.ship_bar.total})` });
+    }
+    if (spec.ship_bar.total > spec.scenarios.length) {
+        findings.push({ skill, code: "ship_bar", message: `ship_bar.total (${spec.ship_bar.total}) > scenario count (${spec.scenarios.length})` });
+    }
+    // critical ids exist
+    const ids = new Set(spec.scenarios.map((s) => s.id));
+    for (const cid of spec.critical) {
+        if (!ids.has(cid))
+            findings.push({ skill, code: "critical", message: `critical id \`${cid}\` is not a scenario` });
+    }
+    // fixture paths exist — check the EFFECTIVE workspace fixture (what the runtime actually
+    // copies: run.ts uses scenario.workspace, not the raw scenario.fixture — an inline scenario
+    // with env.workspace: fixture:PATH sets workspace.fixture but NOT scenario.fixture). Resolve
+    // relative to the spec's dir, matching workspace.ts resolve(specDir, fixture) where specDir = <skillDir>/tests.
+    const specDir = dirname(specPath);
+    for (const s of spec.scenarios) {
+        const fx = typeof s.workspace === "object" && s.workspace !== null ? s.workspace.fixture : undefined;
+        if (fx) {
+            const abs = isAbsolute(fx) ? fx : resolve(specDir, fx);
+            if (!isDir(abs)) {
+                findings.push({ skill, scenario: s.id, code: "fixture", message: `fixture not found: ${fx}` });
+            }
+        }
+    }
+    // results-consistency — only for committed results.yaml (skipped silently otherwise).
+    // Each run dir gets ONE try: schema-1 is intentionally skipped (continue, no finding —
+    // migrateResults carries a schema-1 grade verbatim, so recomputing it would false-flag).
+    // Anything else that goes wrong (unparseable YAML, or a schema-2 file that's missing/
+    // malformed fields — e.g. `scenarios: null`) is caught and surfaces as a `consistency`
+    // finding instead of throwing (lintSkill never throws) or being silently dropped (a
+    // broken committed artifact must fail the gate, not pass it).
+    const resultsRoot = join(skillDir, "tests", "results");
+    for (const runDir of enumerateRunDirs(resultsRoot)) {
+        try {
+            const raw = yaml.load(readFileSync(resultsPath(runDir), "utf8"));
+            if (raw?.schema !== 2)
+                continue; // schema-1 intentionally skipped — no finding
+            const r = readResults(runDir);
+            const ctx = r.mode === "green" ? { shipBar: spec.ship_bar, critical: spec.critical } : null;
+            const recomputed = finalizeResults({ skill: r.skill, harness: r.harness, model: r.model, judge: r.judge, timestamp: r.timestamp, label: r.label, mode: r.mode, scenarios: r.scenarios }, ctx).effective_grade;
+            if (JSON.stringify(recomputed) !== JSON.stringify(r.effective_grade)) {
+                findings.push({ skill, code: "consistency", message: `results.yaml effective_grade is stale in ${runDir} (recompute differs)` });
+            }
+            for (const s of r.scenarios) {
+                if (s.override != null) {
+                    if (!s.note || !s.note.trim())
+                        findings.push({ skill, scenario: s.id, code: "consistency", message: `override on ${s.id} has no note (${runDir})` });
+                    if (findTranscriptFiles(runDir, s.id, r.mode).length === 0)
+                        findings.push({ skill, scenario: s.id, code: "consistency", message: `override on ${s.id} has no preserved transcript (${runDir})` });
+                }
+            }
+        }
+        catch (e) {
+            findings.push({ skill, code: "consistency", message: `results.yaml unreadable or malformed in ${runDir}: ${e instanceof Error ? e.message : String(e)}` });
+        }
+    }
+    return findings;
+}
+/**
+ * All committed run dirs under a skill's tests/results (<tag>/<timestamp>/results.yaml).
+ * Empty if none. Never throws: unreadable/dangling entries (e.g. a broken symlink, or a
+ * TOCTOU removal between readdir and statSync) are skipped rather than propagated, so a
+ * single bad entry can't abort lintSkill's "never throws" contract.
+ */
+function enumerateRunDirs(resultsRoot) {
+    if (!existsSync(resultsRoot))
+        return [];
+    const out = [];
+    let tags;
+    try {
+        tags = readdirSync(resultsRoot);
+    }
+    catch {
+        return out;
+    }
+    for (const tag of tags) {
+        const tagDir = join(resultsRoot, tag);
+        if (!isDir(tagDir))
+            continue;
+        let timestamps;
+        try {
+            timestamps = readdirSync(tagDir);
+        }
+        catch {
+            continue;
+        }
+        for (const ts of timestamps) {
+            const runDir = join(tagDir, ts);
+            if (isDir(runDir) && existsSync(join(runDir, "results.yaml")))
+                out.push(runDir);
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=lint.js.map

package/dist/regrade.d.ts

@@ -0,0 +1,54 @@
+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";
+export interface RegradeOptions {
+    runDir: string;
+    spec: Spec;
+    scenario: Scenario;
+    adapter: HarnessAdapter;
+    judge: ModelRef;
+    specDir: string;
+    threshold: number;
+    now?: () => string;
+}
+/** 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 declare function judgeOneRep(opts: {
+    runDir: string;
+    spec: Spec;
+    scenario: Scenario;
+    transcript: string;
+    adapter: HarnessAdapter;
+    judge: ModelRef;
+    specDir: string;
+    mode: string;
+    rep: number | undefined;
+    now: () => string;
+}): Promise<RepOutcome>;
+/**
+ * Re-judge a scenario's saved GREEN transcript(s) with `judge` — no harness
+ * re-run. Rewrites the judge-raw artifact per rep, emits per-rep judge-verdict
+ * (+ misfire-flag) journal events, and returns the aggregated ScenarioResult
+ * (override/note empty; the caller merges any prior override + persists).
+ */
+export declare function regradeScenario(opts: RegradeOptions): Promise<ScenarioResult>;
+export interface RegradeRunOptions {
+    runDir: string;
+    spec: Spec;
+    adapter: HarnessAdapter;
+    judge: ModelRef;
+    specDir: string;
+    now?: () => string;
+}
+/**
+ * Re-judge every green-transcript scenario in a run dir with `judge` — no
+ * harness re-run. Targets are the run's RECORDED scenarios (falling back to
+ * the spec for a run with no prior results.yaml), so re-grading rewrites the
+ * whole results.yaml consistently with what the run actually recorded. Each
+ * target must still exist in the spec (for its checklist) AND have a green
+ * transcript on disk; anything missing fails fast before spending any judge
+ * calls. Preserves each prior scenario's override/note, rewrites
+ * results.yaml, emits the `score` journal event, and returns the new
+ * ResultsFile. Shared by `cmdGrade` and the pi-extension's `judge` command.
+ */
+export declare function regradeRun(opts: RegradeRunOptions): Promise<ResultsFile>;