productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/evalChecks.js

@@ -0,0 +1,295 @@
+// Deterministic eval checks (foo-eval-system-v0 R-002). Every check that can
+// be code is code — no judge spend where a regex suffices. Carried posture from
+// the research-format gate: only unambiguous misses hard-fail ("fail");
+// ambiguous findings surface as advisory ("warn") with reasons, and strict mode
+// promotes them.
+// A quantity the one-number rule counts: plain numbers, money, percents,
+// multipliers, and unit-suffixed figures. A number inside a word (v2, utf8)
+// is not a quantity.
+const QUANTITY = /(?<![\w.$])\$?\d[\d,]*(?:\.\d+)?(?:\s?%|x|k|M|B|bn)?(?![\w.])/g;
+// Markers that make a quantity accounted-for under the sourcing lint: a
+// markdown link in the same sentence, an estimate flag, or the "our rule"
+// label the seed roast introduced.
+const SOURCE_MARKERS = [
+    /\[[^\]]+\]\([^)]+\)/, // markdown link
+    /(?<![\w-])(?:estimate[ds]?|est\.)(?![\w-])/i,
+    /(?<![\w-])our rule(?![\w-])/i,
+];
+function stripInlineCode(line) {
+    return line.replace(/`[^`]*`/g, (span) => " ".repeat(span.length));
+}
+function proseLines(text) {
+    const output = [];
+    let inFence = false;
+    for (const [index, raw] of text.split(/\r?\n/).entries()) {
+        if (/^\s*(`{3,}|~{3,})/.test(raw)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        output.push({ line: index + 1, text: stripInlineCode(raw) });
+    }
+    return output;
+}
+function sentences(text) {
+    return text
+        .split(/(?<=[.!?])\s+/)
+        .map((sentence) => sentence.trim())
+        .filter((sentence) => sentence.length > 0);
+}
+function quantities(sentence) {
+    return [...sentence.matchAll(QUANTITY)].map((match) => match[0]);
+}
+function numberValue(params, key, fallback) {
+    const value = params[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+const oneNumberRule = (lines, params, findings) => {
+    const max = numberValue(params, "maxPerSentence", 2);
+    for (const { line, text } of lines) {
+        for (const sentence of sentences(text)) {
+            const found = quantities(sentence);
+            if (found.length > max) {
+                findings.push({
+                    check: "one-number-rule",
+                    line,
+                    phrase: found.join(", "),
+                    message: `Sentence carries ${found.length} quantities; the limit is ${max}. Split the sentence or move figures to a table.`,
+                    severity: "fail",
+                });
+            }
+        }
+    }
+};
+const lengthLimit = (lines, params, findings) => {
+    const maxWords = numberValue(params, "maxWords", 1000);
+    const words = lines.reduce((count, { text }) => count + text.split(/\s+/).filter((word) => word.length > 0).length, 0);
+    if (words > maxWords) {
+        findings.push({
+            check: "length-limit",
+            line: lines.at(-1)?.line ?? 1,
+            phrase: `${words} words`,
+            message: `The artifact runs ${words} words against a limit of ${maxWords}. Cut before polishing.`,
+            severity: "fail",
+        });
+    }
+};
+const numberSourcing = (lines, _params, findings) => {
+    for (const { line, text } of lines) {
+        for (const sentence of sentences(text)) {
+            const found = quantities(sentence);
+            if (found.length === 0)
+                continue;
+            const sourced = SOURCE_MARKERS.some((marker) => marker.test(sentence));
+            if (!sourced) {
+                // Advisory, not a hard fail: a bare number can be legitimately
+                // self-evident (a date, a version); the reader rules, strict promotes.
+                findings.push({
+                    check: "number-sourcing",
+                    line,
+                    phrase: found[0],
+                    message: "A quantity with no source link, estimate flag, or “our rule” label in its sentence. Source it, flag it, or own it.",
+                    severity: "warn",
+                });
+            }
+        }
+    }
+};
+const flagConservation = (lines, params, findings) => {
+    // Guarded substance the improve loop must not trade away (R-005): counts of
+    // these markers may grow, never shrink, relative to the recorded baseline.
+    const baselines = [
+        { key: "minCitations", pattern: /\[[^\]]+\]\([^)]+\)/g, label: "citations" },
+        { key: "minEstimateFlags", pattern: /(?<![\w-])(?:estimate[ds]?|est\.)(?![\w-])/gi, label: "estimate flags" },
+        { key: "minOurRuleLabels", pattern: /(?<![\w-])our rule(?![\w-])/gi, label: "“our rule” labels" },
+    ];
+    const text = lines.map(({ text: value }) => value).join("\n");
+    for (const { key, pattern, label } of baselines) {
+        const floor = numberValue(params ?? {}, key, 0);
+        if (floor <= 0)
+            continue;
+        const count = [...text.matchAll(pattern)].length;
+        if (count < floor) {
+            findings.push({
+                check: "flag-conservation",
+                line: 1,
+                phrase: `${count} ${label}`,
+                message: `The artifact carries ${count} ${label}; the recorded baseline is ${floor}. A higher score bought by cutting guarded substance is refused.`,
+                severity: "fail",
+            });
+        }
+    }
+};
+// ── Agent-relay update-notice checks (seed 2, foo-eval-system-v0) ───────────
+//
+// The update-notice relay (src/updateNotice.ts) addresses the coding agent
+// that ran foo and rides stderr; under --json it is suppressed entirely. The
+// observed failures these checks pin (agent-relay-update-notice-v0 R-004):
+// the notice reaching a payload an agent parses, and a structured payload
+// carrying relay addressing vocabulary. The signature markers are the
+// renderer's own stable strings — the address prefix and the head — chosen
+// because updateNotice never renders them inside code spans (only the
+// `foo update` span is backticked, which stripInlineCode blanks).
+const RELAY_SIGNATURE = [
+    "[foo → the human you're working for]",
+    "A newer productfoo is available",
+];
+// Corpus capture format for two-channel runs: the packet's evals/README.md
+// documents it. Checks that read a channel refuse to guess on other shapes.
+const STDOUT_DELIMITER = "--- stdout ---";
+const STDERR_DELIMITER = "--- stderr ---";
+function channelLines(lines) {
+    let current = null;
+    const channels = { stdout: [], stderr: [] };
+    for (const entry of lines) {
+        if (entry.text.trim() === STDOUT_DELIMITER) {
+            current = "stdout";
+            continue;
+        }
+        if (entry.text.trim() === STDERR_DELIMITER) {
+            current = "stderr";
+            continue;
+        }
+        if (current === "stdout")
+            channels.stdout.push(entry);
+        else if (current === "stderr")
+            channels.stderr.push(entry);
+    }
+    // No delimiters seen at all: not an artifact this check can read.
+    return current === null ? null : channels;
+}
+// One finding per line even when both signature markers hit — the phrase
+// carries every marker that matched.
+function relaySignatureFindings(check, lines, message, findings) {
+    for (const { line, text } of lines) {
+        const hits = RELAY_SIGNATURE.filter((marker) => text.includes(marker));
+        if (hits.length === 0)
+            continue;
+        findings.push({ check, line, phrase: hits.join(", "), message, severity: "fail" });
+    }
+}
+function noCaptureSections(check, findings) {
+    findings.push({
+        check,
+        line: 1,
+        phrase: STDOUT_DELIMITER,
+        message: `The artifact carries no ${STDOUT_DELIMITER} / ${STDERR_DELIMITER} capture sections; this check reads a two-channel run capture (packet evals/README.md documents the format).`,
+        severity: "warn",
+    });
+}
+// Relay addressing vocabulary as JSON keys, matched on PARSED keys so token
+// boundaries are exact: a value or key named "protocol" does not carry the
+// key "to", and "history" does not carry "to" as a substring.
+const RELAY_FORBIDDEN_KEYS = [
+    /^to$/i,
+    /^(?:relay|chat|webhook)(?:[-_](?:target|url|endpoint|channel|thread|id))?$/i,
+    /^spawn(?:[-_]agents?)?$/i,
+];
+function forbiddenRelayKey(key) {
+    return RELAY_FORBIDDEN_KEYS.some((pattern) => pattern.test(key));
+}
+function walkRelayKeys(node, path, lines, findings) {
+    if (Array.isArray(node)) {
+        node.forEach((item, index) => walkRelayKeys(item, `${path}[${index}]`, lines, findings));
+        return;
+    }
+    if (node === null || typeof node !== "object")
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        if (forbiddenRelayKey(key)) {
+            findings.push({
+                check: "relay-json-exclusion",
+                line: lines.find(({ text }) => text.includes(`"${key}"`))?.line ?? 1,
+                phrase: `"${key}"`,
+                message: `Structured payload carries relay addressing key "${key}"${path ? ` at ${path}` : ""}. The --json payload speaks data, never relay addressing.`,
+                severity: "fail",
+            });
+        }
+        walkRelayKeys(value, path ? `${path}.${key}` : key, lines, findings);
+    }
+}
+const relayJsonExclusion = (lines, _params, findings) => {
+    // 1. The relay line itself, rendered or quoted, anywhere in the payload.
+    relaySignatureFindings("relay-json-exclusion", lines, "The update-notice relay line reaches a payload an agent parses as data. The notice rides stderr only — never stdout, never --json.", findings);
+    // 2. Addressing vocabulary as JSON keys — parseable payloads only, so the
+    //    key match is structural, not a substring guess.
+    let payload;
+    try {
+        payload = JSON.parse(lines.map(({ text }) => text).join("\n"));
+    }
+    catch {
+        payload = undefined;
+    }
+    if (payload !== undefined) {
+        walkRelayKeys(payload, "", lines, findings);
+        return;
+    }
+    // Unparseable: a corrupted payload leaves the relay-line scan above as the
+    // evidence; an artifact with no JSON at all is the wrong target and the
+    // check says so instead of reading as covered.
+    const hasStructure = lines.some(({ text }) => text.includes("{"));
+    findings.push({
+        check: "relay-json-exclusion",
+        line: 1,
+        phrase: hasStructure ? "unparseable JSON" : "no JSON payload",
+        message: hasStructure
+            ? "The artifact is not valid JSON, so key-level relay addressing cannot be measured. If this is a corrupted payload, the relay-line scan above carries the evidence."
+            : "The artifact carries no JSON payload; this check targets the --json output surface and cannot see anything here.",
+        severity: "warn",
+    });
+};
+const relayStdoutClean = (lines, _params, findings) => {
+    const channels = channelLines(lines);
+    if (!channels) {
+        noCaptureSections("relay-stdout-clean", findings);
+        return;
+    }
+    relaySignatureFindings("relay-stdout-clean", channels.stdout, "The update-notice relay line reached stdout — the machine-readable channel an agent parses. The relay rides stderr only.", findings);
+};
+const relayHeadlessSilent = (lines, _params, findings) => {
+    const channels = channelLines(lines);
+    if (!channels) {
+        noCaptureSections("relay-headless-silent", findings);
+        return;
+    }
+    const message = "A headless run carried the update-notice relay line. With no agent present, the relay has no addressee — silence is the contract.";
+    relaySignatureFindings("relay-headless-silent", channels.stdout, message, findings);
+    relaySignatureFindings("relay-headless-silent", channels.stderr, message, findings);
+};
+const REGISTRY = {
+    "one-number-rule": oneNumberRule,
+    "length-limit": lengthLimit,
+    "number-sourcing": numberSourcing,
+    "flag-conservation": flagConservation,
+    "relay-json-exclusion": relayJsonExclusion,
+    "relay-stdout-clean": relayStdoutClean,
+    "relay-headless-silent": relayHeadlessSilent,
+};
+export const DETERMINISTIC_CHECK_IDS = Object.freeze(Object.keys(REGISTRY));
+/** Run the requested deterministic checks over an artifact's markdown. */
+export function runDeterministicChecks(artifactText, checks, options = {}) {
+    const findings = [];
+    const lines = proseLines(artifactText);
+    for (const { id, params } of checks) {
+        const check = REGISTRY[id];
+        if (!check) {
+            // Refuse unknown input rather than guess — an eval that silently
+            // no-ops reads as "covered" when it is not.
+            findings.push({
+                check: id,
+                line: 1,
+                phrase: id,
+                message: `Unknown deterministic check. Known checks: ${DETERMINISTIC_CHECK_IDS.join(", ")}.`,
+                severity: "fail",
+            });
+            continue;
+        }
+        check(lines, params ?? {}, findings);
+    }
+    if (options.strict) {
+        for (const finding of findings)
+            finding.severity = "fail";
+    }
+    return { ok: findings.every((finding) => finding.severity !== "fail"), findings };
+}

package/dist-public/src/evalCompile.d.ts

@@ -0,0 +1,56 @@
+import { type CalibrationReport } from "./evalCalibration.js";
+import { type EvalChecksResult } from "./evalChecks.js";
+import { type JudgeTransport } from "./evalJudge.js";
+import type { EvalRecord } from "./evalRecord.js";
+export type CompiledJudge = {
+    id: string;
+    /** The criterion the judge scores, verbatim from the record. */
+    criterion: string;
+    /** The judge model pinned by the record — calibration is keyed to it. */
+    model: string;
+};
+export type CompiledSuite = {
+    /** Deterministic records, run natively. */
+    deterministic: EvalRecord[];
+    judges: EvalRecord[];
+    /** The judge plan: what will be asked, of which model. */
+    judgePlan: CompiledJudge[];
+    /** Approved-only is the rule (R-004); what was skipped stays visible. */
+    skippedUnapproved: string[];
+};
+export type JudgeOutcome = {
+    id: string;
+    verdict: "pass" | "fail" | "error";
+    /** True until the judge's calibration report exists and holds (D-007). */
+    advisory: boolean;
+    /** Why the judge is (or is not) allowed to gate. */
+    gating_reason: string;
+    /** The order-swap check disagreed with itself on this artifact. */
+    flipped?: boolean;
+    /** Verdict from the required confirmation; absent if the first call errored. */
+    swapped?: "pass" | "fail" | "error";
+    reason?: string;
+};
+export type SuiteRunResult = {
+    /** True means no gating check failed, not that any gating check passed. Read status. */
+    ok: boolean;
+    /** Coverage: zero approved checks is not_run; only uncalibrated judges is advisory_only. */
+    status: "passed" | "failed" | "not_run" | "advisory_only";
+    deterministic: EvalChecksResult;
+    judges: JudgeOutcome[];
+    skippedUnapproved: string[];
+};
+/** Plan an approved suite: split kinds and render each judge's ask. */
+export declare function compileSuite(records: EvalRecord[]): CompiledSuite;
+/**
+ * Run a compiled suite over an artifact. Deterministic checks gate; judge
+ * verdicts gate only when calibrated — uncalibrated judges are advisory-only
+ * and can never fail the run (R-003/D-007).
+ */
+export declare function runSuite(compiled: CompiledSuite, artifactText: string, options?: {
+    strict?: boolean;
+    /** Resolve a judge record's calibration reference to its report. */
+    calibration?: (record: EvalRecord) => CalibrationReport | undefined;
+    /** Injected for tests; defaults to the real model call. */
+    transport?: JudgeTransport;
+}): Promise<SuiteRunResult>;

package/dist-public/src/evalCompile.js

@@ -0,0 +1,58 @@
+import { judgeMayGate } from "./evalCalibration.js";
+import { runDeterministicChecks } from "./evalChecks.js";
+import { callJudgeWithSwap } from "./evalJudge.js";
+/** Plan an approved suite: split kinds and render each judge's ask. */
+export function compileSuite(records) {
+    const approved = records.filter((record) => record.approved);
+    const skippedUnapproved = records
+        .filter((record) => !record.approved)
+        .map((record) => record.id);
+    const deterministic = approved.filter((record) => record.kind === "deterministic");
+    const judges = approved.filter((record) => record.kind === "judge");
+    return {
+        deterministic,
+        judges,
+        judgePlan: judges.map((record) => ({
+            id: record.id,
+            criterion: record.judge.prompt,
+            model: record.judge.model,
+        })),
+        skippedUnapproved,
+    };
+}
+/**
+ * Run a compiled suite over an artifact. Deterministic checks gate; judge
+ * verdicts gate only when calibrated — uncalibrated judges are advisory-only
+ * and can never fail the run (R-003/D-007).
+ */
+export async function runSuite(compiled, artifactText, options = {}) {
+    const deterministic = runDeterministicChecks(artifactText, compiled.deterministic.map((record) => ({
+        id: record.check.id,
+        params: record.check.params,
+    })), options);
+    const judges = [];
+    for (const record of compiled.judges) {
+        const gate = judgeMayGate(record.judge, record.judge?.calibration ? options.calibration?.(record) : undefined);
+        const call = await callJudgeWithSwap({ prompt: record.judge.prompt, model: record.judge.model, artifact: artifactText }, options.transport);
+        judges.push({
+            id: record.id,
+            verdict: call.verdict,
+            advisory: !gate.allowed,
+            gating_reason: gate.reason,
+            flipped: call.flipped,
+            swapped: call.swapped,
+            reason: call.error ?? call.note,
+        });
+    }
+    const gatingJudgeFailed = judges.some((judge) => !judge.advisory && judge.verdict !== "pass");
+    const ran = compiled.deterministic.length + judges.length;
+    const gating = compiled.deterministic.length + judges.filter(judge => !judge.advisory).length;
+    const ok = ran > 0 && deterministic.ok && !gatingJudgeFailed;
+    return {
+        ok,
+        status: ran === 0 ? "not_run" : gating === 0 ? "advisory_only" : ok ? "passed" : "failed",
+        deterministic,
+        judges,
+        skippedUnapproved: compiled.skippedUnapproved,
+    };
+}

package/dist-public/src/evalImprove.d.ts

@@ -0,0 +1,60 @@
+import type { SuiteRunResult } from "./evalCompile.js";
+/** R-005's agreed budget. A loop without one is the B4 boundary. */
+export declare const IMPROVE_MAX_ROUNDS = 3;
+/**
+ * The substance a round may never trade for a better score. Each guard is a
+ * countable property of the artifact, because "did it keep the counter-case"
+ * has to be decidable without asking a judge — a judge is exactly the thing
+ * that might be gamed here.
+ */
+export type ConservationGuard = {
+    id: "citations" | "estimate-flags" | "counter-case";
+    label: string;
+    /** How many instances the artifact carries. Never allowed to fall. */
+    count: (artifact: string) => number;
+};
+export declare const CONSERVATION_GUARDS: readonly ConservationGuard[];
+export type ConservationBreach = {
+    guard: ConservationGuard["id"];
+    label: string;
+    before: number;
+    after: number;
+};
+/**
+ * Compare a proposed revision against the artifact it replaces. A guard breaks
+ * when its count falls; holding steady or rising is fine, because the loop is
+ * guarding against removal, not against editing.
+ */
+export declare function conservationBreaches(before: string, after: string): ConservationBreach[];
+export type ImproveStop = "all-checks-pass" | "evaluation-error" | "not-run" | "no-change" | "budget-spent" | "conservation-refused";
+export type ImproveRound = {
+    round: number;
+    /** Gating failures after this round: deterministic misses plus calibrated judge fails. */
+    failing: string[];
+    /** Judge verdicts that were reported but could not gate. */
+    advisory: string[];
+    /** Present when the round's revision was refused. */
+    refused?: ConservationBreach[];
+};
+export type ImproveResult = {
+    rounds: ImproveRound[];
+    stop: ImproveStop;
+    /** The artifact the loop landed on — the last accepted revision. */
+    artifact: string;
+};
+/** Produce the next revision. Returns null when it has nothing further to try. */
+export type ImproveReviser = (artifact: string, failing: string[], round: number) => Promise<string | null>;
+/** Score an artifact. Injected so the loop is testable without a model call. */
+export type ImproveScorer = (artifact: string) => Promise<SuiteRunResult>;
+/**
+ * Run the loop.
+ *
+ * A calibrated judge that would stop the loop is asked twice: a single
+ * stochastic flip should not end a run, so the failure stands only if it
+ * repeats (R-005). Deterministic checks are never re-asked — they do not flip.
+ */
+export declare function runImproveLoop(artifact: string, score: ImproveScorer, revise: ImproveReviser, options?: {
+    maxRounds?: number;
+}): Promise<ImproveResult>;
+/** Where it landed and why it stopped — printed every run, human surfaces only. */
+export declare function renderImproveLanding(result: ImproveResult, glyphsOn: boolean): string;

package/dist-public/src/evalImprove.js

@@ -0,0 +1,175 @@
+// foo-eval-system-v0 T-006 (R-005): the critique-and-improve loop, budgeted.
+//
+// The loop is roast → apply the roast's next prompt → re-score, and its danger
+// is obvious once named: a scoring loop optimises whatever it can measure, so
+// the cheapest way to raise a score is to delete the substance the score does
+// not look at. A round that scores better by cutting the counter-case, the
+// citations, or the estimate flags has not improved the artifact; it has eaten
+// it. Those cuts are refused here, by name, rather than celebrated.
+//
+// Everything else is budget and honesty: at most three rounds, early stop when
+// nothing is failing or nothing changed, uncalibrated judges never allowed to
+// stop or extend a round, and a landing report every run that says where it
+// stopped and why.
+import { withGlyph } from "./statusGlyphs.js";
+/** R-005's agreed budget. A loop without one is the B4 boundary. */
+export const IMPROVE_MAX_ROUNDS = 3;
+const CITATION = /\[[^\]\n]*·[^\]\n]*\]|\[\d+\]|\(https?:\/\/[^)\s]+\)/g;
+const ESTIMATE_FLAG = /(?<![\w-])(?:estimate|estimated|approx\.?|approximately|~\d|assumption|assumed)(?![\w-])/gi;
+const COUNTER_CASE = /(?<![\w-])(?:however|but |counter-case|on the other hand|the case against|dissent|objection|risk[s]? (?:i|we)['’]d flag)(?![\w-])/gi;
+export const CONSERVATION_GUARDS = [
+    { id: "citations", label: "citations", count: (text) => (text.match(CITATION) ?? []).length },
+    { id: "estimate-flags", label: "estimate flags", count: (text) => (text.match(ESTIMATE_FLAG) ?? []).length },
+    { id: "counter-case", label: "counter-case", count: (text) => (text.match(COUNTER_CASE) ?? []).length },
+];
+/**
+ * Compare a proposed revision against the artifact it replaces. A guard breaks
+ * when its count falls; holding steady or rising is fine, because the loop is
+ * guarding against removal, not against editing.
+ */
+export function conservationBreaches(before, after) {
+    const breaches = [];
+    for (const guard of CONSERVATION_GUARDS) {
+        const had = guard.count(before);
+        const has = guard.count(after);
+        if (has < had)
+            breaches.push({ guard: guard.id, label: guard.label, before: had, after: has });
+    }
+    return breaches;
+}
+function gatingFailures(result) {
+    const failures = [];
+    for (const finding of result.deterministic.findings) {
+        // Only unambiguous misses gate; advisory findings are reported, never fatal
+        // (R-002, carrying the research-format-gate posture).
+        if (finding.severity === "fail")
+            failures.push(`${finding.check}: ${finding.message}`);
+    }
+    for (const judge of result.judges) {
+        // An uncalibrated judge is reported and ignored. It may not stop the loop
+        // and it may not extend it — being wrong in either direction is expensive.
+        if (judge.advisory)
+            continue;
+        if (judge.verdict === "fail")
+            failures.push(`${judge.id}: ${judge.reason ?? "judge failed"}`);
+    }
+    return failures;
+}
+function advisoryNotes(result) {
+    return result.judges
+        .filter((judge) => judge.advisory && judge.verdict !== "pass")
+        .map((judge) => `${judge.id}: ${judge.verdict} (advisory — ${judge.gating_reason})`);
+}
+/** Missing checks or a failed calibrated judge cannot authorize improvement. */
+function unavailableEvaluation(result) {
+    if (result.status === "not_run")
+        return { stop: "not-run", reasons: ["No approved checks ran."] };
+    if (result.status === "advisory_only")
+        return { stop: "not-run", reasons: ["No gating checks ran — judge results are advisory only."] };
+    const errors = result.judges.filter(judge => !judge.advisory && judge.verdict === "error");
+    if (errors.length)
+        return {
+            stop: "evaluation-error",
+            reasons: errors.map(judge => `${judge.id}: ${judge.reason ?? "judge error"}`),
+        };
+    return undefined;
+}
+/**
+ * Run the loop.
+ *
+ * A calibrated judge that would stop the loop is asked twice: a single
+ * stochastic flip should not end a run, so the failure stands only if it
+ * repeats (R-005). Deterministic checks are never re-asked — they do not flip.
+ */
+export async function runImproveLoop(artifact, score, revise, options = {}) {
+    const budget = Math.max(1, Math.min(options.maxRounds ?? IMPROVE_MAX_ROUNDS, IMPROVE_MAX_ROUNDS));
+    const rounds = [];
+    let current = artifact;
+    for (let round = 1; round <= budget; round += 1) {
+        let result = await score(current);
+        const unavailable = unavailableEvaluation(result);
+        if (unavailable) {
+            rounds.push({ round, failing: unavailable.reasons, advisory: advisoryNotes(result) });
+            return { rounds, stop: unavailable.stop, artifact: current };
+        }
+        let failing = gatingFailures(result);
+        // Re-ask once before a judge verdict is allowed to end the run.
+        if (failing.length > 0 && result.judges.some((judge) => !judge.advisory && judge.verdict === "fail")) {
+            const second = await score(current);
+            const unavailable = unavailableEvaluation(second);
+            if (unavailable) {
+                rounds.push({ round, failing: unavailable.reasons, advisory: advisoryNotes(second) });
+                return { rounds, stop: unavailable.stop, artifact: current };
+            }
+            const stillFailing = gatingFailures(second);
+            if (stillFailing.length === 0) {
+                result = second;
+                failing = stillFailing;
+            }
+        }
+        if (failing.length === 0) {
+            rounds.push({ round, failing: [], advisory: advisoryNotes(result) });
+            return { rounds, stop: "all-checks-pass", artifact: current };
+        }
+        const proposed = await revise(current, failing, round);
+        if (proposed === null || proposed === current) {
+            rounds.push({ round, failing, advisory: advisoryNotes(result) });
+            return { rounds, stop: "no-change", artifact: current };
+        }
+        const breaches = conservationBreaches(current, proposed);
+        if (breaches.length > 0) {
+            // The round is refused, not scored. Accepting it and reporting the breach
+            // afterwards would still leave the cut substance in the landed artifact.
+            rounds.push({ round, failing, advisory: advisoryNotes(result), refused: breaches });
+            return { rounds, stop: "conservation-refused", artifact: current };
+        }
+        rounds.push({ round, failing, advisory: advisoryNotes(result) });
+        current = proposed;
+    }
+    return { rounds, stop: "budget-spent", artifact: current };
+}
+/** Where it landed and why it stopped — printed every run, human surfaces only. */
+export function renderImproveLanding(result, glyphsOn) {
+    const lines = [];
+    const last = result.rounds.at(-1);
+    switch (result.stop) {
+        case "all-checks-pass":
+            lines.push(withGlyph("proven", `improve loop — every gating check passes after ${result.rounds.length} round(s).`, glyphsOn));
+            break;
+        case "evaluation-error":
+            lines.push(withGlyph("blocked", "improve loop — evaluation failed to produce a verdict; the artifact was kept.", glyphsOn));
+            break;
+        case "not-run":
+            lines.push(withGlyph("needs_input", "improve loop — no gating checks ran; the artifact was kept.", glyphsOn));
+            break;
+        case "no-change":
+            lines.push(withGlyph("claimed", `improve loop — stopped at round ${result.rounds.length}: the round changed nothing.`, glyphsOn));
+            break;
+        case "budget-spent":
+            lines.push(withGlyph("needs_input", `improve loop — spent its ${result.rounds.length}-round budget with checks still failing.`, glyphsOn));
+            break;
+        case "conservation-refused":
+            lines.push(withGlyph("blocked", `improve loop — refused round ${result.rounds.length}: it raised the score by cutting guarded substance.`, glyphsOn));
+            break;
+    }
+    if (last?.refused) {
+        lines.push("");
+        for (const breach of last.refused) {
+            lines.push(`  ${breach.label}: ${breach.before} → ${breach.after} — a round may not trade this for a better score.`);
+        }
+    }
+    if (last && last.failing.length > 0 && result.stop !== "all-checks-pass") {
+        lines.push("");
+        lines.push("Still failing:");
+        for (const failure of last.failing)
+            lines.push(`  ${failure}`);
+    }
+    const advisory = last?.advisory ?? [];
+    if (advisory.length > 0) {
+        lines.push("");
+        lines.push("Advisory (reported, never counted):");
+        for (const note of advisory)
+            lines.push(`  ${note}`);
+    }
+    return lines.join("\n");
+}