toolroll 0.5.0

package/dist/proof.js

@@ -0,0 +1,1140 @@
+/**
+ * The build's own claim, adjudicated against evidence the plane captured
+ * itself (`docs/PRIORITIES.md` Priority 2). Modelled line-for-line on the
+ * scout's report (`scout-report.ts`): fail closed, every problem reported at
+ * once, stable reasons, byte caps, control-character rejection on every
+ * string.
+ *
+ * The proof is a distinct deliverable from the terminal handoff every
+ * attempt writes (including `failed` ones, whose lists are deliberately
+ * compacted prose) — only a `completed` attempt owes one, and the plane
+ * judges it. A missing or malformed proof never fails the attempt or
+ * touches the commit; it only keeps the verdict off "verified".
+ *
+ * `adjudicate` is pure and does no I/O: every fact it reasons over — whether
+ * the proof artifact exists, whether the handoff and terminal diff exist,
+ * what the sealed diff-stat says, whether a screenshot's bytes actually are
+ * a PNG or JPEG, whether an approved verification command ran and what it
+ * returned — is gathered by the caller (`builder.ts`) and handed in as data,
+ * so the review itself stays testable without a filesystem or a database.
+ */
+import { hasForbiddenControls } from "./decision.js";
+import { EVIDENCE_KINDS } from "./scope.js";
+/** Shared by preflight and final adjudication; presentation text is never a rubric. */
+function criterionContractProblems(approved, answer) {
+    if (answer === undefined)
+        return [{ kind: "missing", message: `the proof does not answer approved criterion "${approved.id}"` }];
+    const problems = [];
+    if (answer.statement.trim() !== approved.statement.trim()) {
+        problems.push({ kind: "statement", message: `criterion "${approved.id}" was signed as "${approved.statement}" and the proof restates it as "${answer.statement}"` });
+    }
+    for (const kind of approved.evidence) {
+        if (!answer.evidence.some(ref => ref.kind === kind)) {
+            problems.push({ kind: "evidence", message: `criterion "${approved.id}" requires ${kind} evidence, which the proof does not reference` });
+        }
+    }
+    return problems;
+}
+/** Only submission defects. A truthful not-met answer is not malformed. */
+export function proofSubmissionProblems(proof, rubric) {
+    const answers = new Map(proof.criteria.map(one => [one.id, one]));
+    const problems = rubric.flatMap(one => criterionContractProblems(one, answers.get(one.id)).map(problem => problem.message));
+    const checks = new Set(proof.checks.map(one => one.command));
+    const changed = new Set(proof.changed);
+    const shots = new Set(proof.screenshots.map(one => one.path));
+    for (const criterion of proof.criteria) {
+        if (criterion.verdict === "pending-verification" && !rubric.some(one => one.id === criterion.id && one.evidence.includes("check"))) {
+            problems.push(`criterion ${criterion.id} can wait for the final check only when its signed requirements include check evidence`);
+        }
+        for (const evidence of criterion.evidence) {
+            const resolves = evidence.kind === "check" ? checks.has(evidence.ref)
+                : evidence.kind === "changed-path" ? changed.has(evidence.ref)
+                    : evidence.kind === "screenshot" ? shots.has(evidence.ref) : true;
+            if (!resolves)
+                problems.push(`criterion ${criterion.id} names a ${evidence.kind} ref that resolves to nothing — ${JSON.stringify(evidence.ref)}`);
+        }
+    }
+    problems.push(...failedMetChecks(proof).map(failedCheckWords));
+    return problems;
+}
+/** Caps are BYTES of UTF-8, matching the scout report's rule: a payload is
+ * the same size whatever script it is written in. */
+export const PROOF_LIMITS = {
+    payload: 64 * 1024,
+    criteria: 12,
+    criterionId: 40,
+    criterionStatement: 300,
+    criterionHow: 500,
+    evidencePerCriterion: 4,
+    evidenceRef: 300,
+    checks: 12,
+    checkCommand: 300,
+    checkSummary: 300,
+    changed: 64,
+    changedPath: 300,
+    caveats: 8,
+    caveat: 300,
+    screenshots: 8,
+    screenshotPath: 300,
+    screenshotCaption: 300,
+};
+function refuse(reason, message) {
+    return { ok: false, problems: [{ reason, message }] };
+}
+function describe(value) {
+    if (value === undefined)
+        return "nothing";
+    if (value === null)
+        return "null";
+    if (typeof value === "string")
+        return `a ${value.length}-char string`;
+    return `a ${Array.isArray(value) ? "array" : typeof value}`;
+}
+function prose(value, field, cap, problems) {
+    if (value === undefined || value === null || (typeof value === "string" && value.trim() === "")) {
+        problems.push({ reason: `missing-${field}`, message: `${field} is required` });
+        return null;
+    }
+    if (typeof value !== "string") {
+        problems.push({ reason: `bad-${field}`, message: `${field} must be a string (got ${describe(value)})` });
+        return null;
+    }
+    if (Buffer.byteLength(value, "utf8") > cap) {
+        problems.push({ reason: `${field}-too-long`, message: `${field} is over ${cap} bytes` });
+        return null;
+    }
+    if (hasForbiddenControls(value)) {
+        problems.push({ reason: `${field}-controls`, message: `${field} carries control characters that could become terminal escapes` });
+        return null;
+    }
+    return value;
+}
+/** A repository-relative path: no leading slash, no drive letter, no `.`/`..`
+ * segment, no backslash, no control character. The same shape
+ * `readVerifiedArtifact` enforces on an evidence key, applied here to a
+ * path an agent claims rather than one the machine already wrote. */
+function relativePath(value, field, cap, problems) {
+    const raw = prose(value, field, cap, problems);
+    if (raw === null)
+        return null;
+    const segments = raw.split("/");
+    const wellFormed = !raw.startsWith("/") &&
+        segments.every(segment => segment.length > 0 && segment !== "." && segment !== ".." && !segment.includes("\\"));
+    if (!wellFormed) {
+        problems.push({ reason: `${field}-not-relative`, message: `${field} must be a normalized repository-relative path (got ${describe(value)})` });
+        return null;
+    }
+    return raw;
+}
+/** `evidence` is optional on a criterion (absent → `[]`, exactly like every
+ * other list here) — the mandatory PRESENCE of an answer for a SIGNED
+ * criterion is `adjudicate`'s concern, not the parser's; this only proves
+ * the shape of what is there. */
+function parseEvidenceRefs(value, field, problems) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        problems.push({ reason: `bad-${field}`, message: `${field} must be an array (got ${describe(value)})` });
+        return null;
+    }
+    if (value.length > PROOF_LIMITS.evidencePerCriterion) {
+        problems.push({ reason: `${field}-too-many`, message: `${field} lists ${value.length} — cap is ${PROOF_LIMITS.evidencePerCriterion}` });
+        return null;
+    }
+    const refs = [];
+    let bad = false;
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            problems.push({ reason: `${field}[${index}]-shape`, message: `${field}[${index}] must be an object` });
+            bad = true;
+            continue;
+        }
+        const one = entry;
+        const kind = one["kind"];
+        if (typeof kind !== "string" || !EVIDENCE_KINDS.includes(kind)) {
+            problems.push({
+                reason: `${field}[${index}]-bad-kind`,
+                message: `${field}[${index}].kind must draw from ${EVIDENCE_KINDS.join(", ")} (got ${describe(kind)})`,
+            });
+            bad = true;
+            continue;
+        }
+        const ref = prose(one["ref"], `${field}[${index}].ref`, PROOF_LIMITS.evidenceRef, problems);
+        if (ref === null) {
+            bad = true;
+            continue;
+        }
+        refs.push({ kind: kind, ref });
+    }
+    return bad ? null : refs;
+}
+function parseCriteria(value, problems) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        problems.push({ reason: "bad-criteria", message: `criteria must be an array (got ${describe(value)})` });
+        return [];
+    }
+    if (value.length > PROOF_LIMITS.criteria) {
+        problems.push({ reason: "criteria-too-many", message: `criteria lists ${value.length} — cap is ${PROOF_LIMITS.criteria}` });
+        return [];
+    }
+    const criteria = [];
+    const seen = new Set();
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            problems.push({ reason: `criteria[${index}]-shape`, message: `criteria[${index}] must be an object` });
+            continue;
+        }
+        const one = entry;
+        const id = prose(one["id"], `criteria[${index}].id`, PROOF_LIMITS.criterionId, problems);
+        if (id !== null && seen.has(id)) {
+            problems.push({ reason: `criteria[${index}]-duplicate-id`, message: `criterion id "${id}" appears twice` });
+        }
+        else if (id !== null) {
+            seen.add(id);
+        }
+        const statement = prose(one["statement"], `criteria[${index}].statement`, PROOF_LIMITS.criterionStatement, problems);
+        const how = prose(one["how"], `criteria[${index}].how`, PROOF_LIMITS.criterionHow, problems);
+        const verdict = one["verdict"];
+        if (verdict !== "met" && verdict !== "not-met" && verdict !== "not-checked" && verdict !== "pending-verification") {
+            problems.push({
+                reason: `criteria[${index}]-bad-verdict`,
+                message: `criteria[${index}].verdict must be "met", "not-met", "not-checked", or "pending-verification" (got ${describe(verdict)})`,
+            });
+            continue;
+        }
+        const evidence = parseEvidenceRefs(one["evidence"], `criteria[${index}].evidence`, problems);
+        if (id === null || statement === null || how === null || evidence === null)
+            continue;
+        criteria.push({ id, statement, how, verdict, evidence });
+    }
+    return criteria;
+}
+function parseChecks(value, problems) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        problems.push({ reason: "bad-checks", message: `checks must be an array (got ${describe(value)})` });
+        return [];
+    }
+    if (value.length > PROOF_LIMITS.checks) {
+        problems.push({ reason: "checks-too-many", message: `checks lists ${value.length} — cap is ${PROOF_LIMITS.checks}` });
+        return [];
+    }
+    const checks = [];
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            problems.push({ reason: `checks[${index}]-shape`, message: `checks[${index}] must be an object` });
+            continue;
+        }
+        const one = entry;
+        const command = prose(one["command"], `checks[${index}].command`, PROOF_LIMITS.checkCommand, problems);
+        const summary = prose(one["summary"], `checks[${index}].summary`, PROOF_LIMITS.checkSummary, problems);
+        const exitCode = one["exitCode"];
+        if (typeof exitCode !== "number" || !Number.isInteger(exitCode) || exitCode < 0 || exitCode > 255) {
+            problems.push({
+                reason: `checks[${index}]-bad-exit-code`,
+                message: `checks[${index}].exitCode must be an integer 0-255 (got ${describe(exitCode)})`,
+            });
+            continue;
+        }
+        if (command === null || summary === null)
+            continue;
+        checks.push({ command, summary, exitCode });
+    }
+    return checks;
+}
+function parseStringList(value, field, cap, itemCap, problems) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        problems.push({ reason: `bad-${field}`, message: `${field} must be an array (got ${describe(value)})` });
+        return [];
+    }
+    if (value.length > cap) {
+        problems.push({ reason: `${field}-too-many`, message: `${field} lists ${value.length} — cap is ${cap}` });
+        return [];
+    }
+    const out = [];
+    for (const [index, entry] of value.entries()) {
+        const item = prose(entry, `${field}[${index}]`, itemCap, problems);
+        if (item !== null)
+            out.push(item);
+    }
+    return out;
+}
+function parseScreenshots(value, problems) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value)) {
+        problems.push({ reason: "bad-screenshots", message: `screenshots must be an array (got ${describe(value)})` });
+        return [];
+    }
+    if (value.length > PROOF_LIMITS.screenshots) {
+        problems.push({ reason: "screenshots-too-many", message: `screenshots lists ${value.length} — cap is ${PROOF_LIMITS.screenshots}` });
+        return [];
+    }
+    const screenshots = [];
+    const seen = new Set();
+    for (const [index, entry] of value.entries()) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            problems.push({ reason: `screenshots[${index}]-shape`, message: `screenshots[${index}] must be an object` });
+            continue;
+        }
+        const one = entry;
+        const path = relativePath(one["path"], `screenshots[${index}].path`, PROOF_LIMITS.screenshotPath, problems);
+        const caption = prose(one["caption"], `screenshots[${index}].caption`, PROOF_LIMITS.screenshotCaption, problems);
+        if (path !== null && seen.has(path)) {
+            problems.push({ reason: `screenshots[${index}]-duplicate-path`, message: `screenshot path "${path}" appears twice` });
+            continue;
+        }
+        if (path === null || caption === null)
+            continue;
+        seen.add(path);
+        screenshots.push({ path, caption });
+    }
+    return screenshots;
+}
+export function parseProof(raw) {
+    if (Buffer.byteLength(raw, "utf8") > PROOF_LIMITS.payload) {
+        return refuse("too-large", `the payload is over ${PROOF_LIMITS.payload} bytes`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        return refuse("not-json", `the payload is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return refuse("not-an-object", "the payload must be one JSON object");
+    }
+    const body = parsed;
+    const problems = [];
+    if (body["version"] !== 1) {
+        problems.push({ reason: "bad-version", message: `version must be 1 (got ${describe(body["version"])})` });
+    }
+    const criteria = parseCriteria(body["criteria"], problems);
+    const checks = parseChecks(body["checks"], problems);
+    const changed = parseStringList(body["changed"], "changed", PROOF_LIMITS.changed, PROOF_LIMITS.changedPath, problems);
+    const caveats = parseStringList(body["caveats"], "caveats", PROOF_LIMITS.caveats, PROOF_LIMITS.caveat, problems);
+    const screenshots = parseScreenshots(body["screenshots"], problems);
+    if (problems.length > 0)
+        return { ok: false, problems };
+    return {
+        ok: true,
+        proof: { version: 1, criteria, checks, changed, caveats, screenshots },
+    };
+}
+/** Re-serialize the validated shape, never the agent's raw bytes (the
+ * scout report's rule, `scout.ts`): what is stored and later hash-verified
+ * is exactly what this parser admitted, key order and all. */
+export function serializeProof(proof) {
+    return JSON.stringify(proof, null, 2);
+}
+function caveatNames(caveat, id) {
+    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[^\\p{L}\\p{N}_-])${escaped}(?![\\p{L}\\p{N}_-])`, "u").test(caveat);
+}
+/** Every (caveat, criterion) pair where the caveat names a criterion the
+ * proof marks `met` — the proof contradicts itself and cannot verify. In
+ * caveat order, then criterion order; `[]` for a proof at peace with its
+ * own caveats. */
+export function blockingCaveats(proof) {
+    const met = proof.criteria.filter(one => one.verdict === "met" || one.verdict === "pending-verification");
+    const out = [];
+    proof.caveats.forEach((caveat, index) => {
+        for (const criterion of met)
+            if (caveatNames(caveat, criterion.id))
+                out.push({ caveat, index, criterionId: criterion.id });
+    });
+    return out;
+}
+/**
+ * Every check a criterion marked `met` cites that the proof's own `checks`
+ * list says exited nonzero (proof preflight closure): a met criterion
+ * resting on a failing command is not evidence, it is a contradiction the
+ * adjudicator fails the row for. A not-met or not-checked criterion may
+ * cite a failed check honestly — it is reporting, not claiming — so only
+ * `met` and `pending-verification` count here: pending asserts the agent's
+ * own checks already passed. A ref that resolves to no check is a different
+ * problem (an unresolved ref), not this one. In criterion order, then
+ * evidence order.
+ */
+export function failedMetChecks(proof) {
+    const checksByCommand = new Map(proof.checks.map(c => [c.command, c]));
+    const out = [];
+    for (const criterion of proof.criteria) {
+        if (criterion.verdict !== "met" && criterion.verdict !== "pending-verification")
+            continue;
+        for (const evidence of criterion.evidence) {
+            if (evidence.kind !== "check")
+                continue;
+            const check = checksByCommand.get(evidence.ref);
+            if (check !== undefined && check.exitCode !== 0)
+                out.push({ criterionId: criterion.id, ref: evidence.ref, exitCode: check.exitCode });
+        }
+    }
+    return out;
+}
+/** The one actionable fact a failed check citation is reported as — the
+ * adjudicator's matrix detail and the agent's exit preflight say exactly
+ * this, so what the preflight refuses is what the plane would have said. */
+export function failedCheckWords(one) {
+    return `criterion "${one.criterionId}"'s check "${one.ref}" exited ${one.exitCode}`;
+}
+/** The leading tag list of a caveat — `c1: …`, `c1, c4: …`, `(c2) …` — as
+ * the tokens it names before its first colon or after its parentheses.
+ * A caveat with no such prefix has no tags; its attribution rests on any
+ * known id appearing as a standalone token anywhere in it. */
+function leadingTags(caveat) {
+    const separator = String.raw `(?:\s*[,/&+]\s*(?:and\s+)?|\s+and\s+)`;
+    const prefixed = new RegExp(String.raw `^\s*\(?\s*([\p{L}\p{N}_-]+(?:${separator}[\p{L}\p{N}_-]+)*)\s*\)?\s*:`, "u").exec(caveat);
+    if (prefixed === null)
+        return [];
+    return prefixed[1].split(new RegExp(separator, "u")).map(one => one.trim()).filter(one => one !== "");
+}
+export function caveatAttributionProblems(proof, signedIds = []) {
+    const own = new Set(proof.criteria.map(one => one.id));
+    const known = new Set(signedIds.length > 0 ? signedIds : [...own]);
+    const out = [];
+    proof.caveats.forEach((caveat, index) => {
+        const named = [...known].filter(id => caveatNames(caveat, id));
+        const tags = leadingTags(caveat);
+        const unknown = tags.filter(tag => !known.has(tag));
+        const answered = signedIds.length > 0 ? unknown.filter(tag => own.has(tag)) : [];
+        if (unknown.length > 0)
+            out.push({ caveat, index, kind: "unknown", tags: unknown, ...(answered.length > 0 ? { answered } : {}) });
+        else if (named.length === 0)
+            out.push({ caveat, index, kind: "unassigned", tags: [] });
+    });
+    return out;
+}
+/** The words one attribution problem refuses in — shared by the plane's
+ * adjudication and the agent's exit preflight so both say the same thing. */
+export function caveatAttributionWords(problem) {
+    if (problem.kind !== "unknown") {
+        return `caveat ${problem.index + 1} names no criterion — every caveat is an exception to exactly one signed criterion, named by its exact id (an unrelated idea belongs in the handoff's follow-ups): ${problem.caveat}`;
+    }
+    const quoted = problem.tags.map(tag => `"${tag}"`).join(", ");
+    const answered = problem.answered ?? [];
+    return answered.length > 0 && answered.length === problem.tags.length
+        ? `caveat ${problem.index + 1} names ${quoted}, a criterion the proof authored for itself that nobody signed — a proof-only id is no signed authority; every caveat names a signed criterion's exact id: ${problem.caveat}`
+        : `caveat ${problem.index + 1} names ${quoted}, which is no signed or answered criterion — every caveat names an exact criterion id: ${problem.caveat}`;
+}
+/** v39: the floor a criterion's screenshot evidence must clear — "real,
+ * not placeholder-sized" in exact numbers (scope: "meaningful byte size
+ * and at least 320 by 200 dimensions"). */
+export const SCREENSHOT_EVIDENCE_MIN_BYTES = 1024;
+export const SCREENSHOT_EVIDENCE_MIN_WIDTH = 320;
+export const SCREENSHOT_EVIDENCE_MIN_HEIGHT = 200;
+export function changedListProblems(changed, stat) {
+    if (stat === null || !stat.captured || stat.truncated)
+        return { problems: [], recoverable: false, sealed: null };
+    const claimed = new Set(changed);
+    const problems = [];
+    let unexplained = false;
+    for (const path of changed) {
+        if (stat.paths.has(path))
+            continue;
+        const destination = stat.renames?.get(path);
+        if (destination !== undefined && stat.paths.has(destination)) {
+            problems.push(`changed lists ${JSON.stringify(path)}, the old name of a move the sealed diff records once as ${JSON.stringify(destination)} — list the destination only`);
+        }
+        else {
+            unexplained = true;
+            problems.push(`changed lists ${JSON.stringify(path)}, which the sealed diff does not contain`);
+        }
+    }
+    for (const path of stat.paths) {
+        if (!claimed.has(path))
+            problems.push(`changed omits ${JSON.stringify(path)}, which the sealed diff contains`);
+    }
+    const sealed = [...stat.paths].sort();
+    return { problems, recoverable: problems.length > 0 && !unexplained, sealed };
+}
+/** What a receipt-only correction may never touch: the exact criterion
+ * id/verdict pairs the agent submitted (comment 397, run 1648). A
+ * correction restates a signed statement or repairs an evidence reference
+ * against the exact rubric; it cannot move an answer (not-met or
+ * not-checked becoming pending-verification, or any other change of
+ * word), drop a criterion — an extra negative answer is a finding, not a
+ * formatting defect — or add one. One line per frozen pair broken. */
+export function frozenCriterionProblems(submitted, corrected) {
+    const problems = [];
+    const after = new Map(corrected.criteria.map(one => [one.id, one.verdict]));
+    for (const prior of submitted.criteria) {
+        const verdict = after.get(prior.id);
+        if (verdict === undefined) {
+            problems.push(`criterion ${prior.id} (${prior.verdict}) was dropped; every submitted criterion and its verdict are frozen by a receipt-only correction`);
+        }
+        else if (verdict !== prior.verdict) {
+            problems.push(`criterion ${prior.id} was submitted as ${prior.verdict}; a receipt-only correction cannot change it to ${verdict}`);
+        }
+    }
+    const before = new Set(submitted.criteria.map(one => one.id));
+    for (const one of corrected.criteria) {
+        if (!before.has(one.id))
+            problems.push(`criterion ${one.id} was added; a receipt-only correction answers exactly the submitted criteria`);
+    }
+    return problems;
+}
+/** Whether two readings of the sealed diff-stat state the same facts:
+ * the same capture standing, the same paths and the same rename
+ * provenance. Settlement reads the stat once before the receipt
+ * correction and re-reads it after that correction and after the final
+ * gate; a reading that differs is never adjudicated from the cached one. */
+export function sameDiffStatFacts(a, b) {
+    if (a === null || b === null)
+        return a === b;
+    const restate = (one) => JSON.stringify({
+        captured: one.captured,
+        truncated: one.truncated,
+        paths: [...one.paths].sort(),
+        renames: [...(one.renames ?? [])].sort(),
+    });
+    return restate(a) === restate(b);
+}
+export const GOAL_ASSESSMENT_PENDING = "The saved evidence is awaiting independent goal assessment.";
+/** Legacy folds could only lower a verdict. Direct assessment also records an
+ * ordinary wait between green machine checks and the goal judgement. */
+export function reviewConflict(matrix, machine, verdict) {
+    return matrix.some(row => row.assessment !== undefined) ? matrix.some(row => row.review?.judgement === "contradicts")
+        : machine !== null && machine !== verdict;
+}
+/** Human sign-off is owed, with no other recorded evidence failure. This is
+ * presentation only; it never changes a verdict or grants acceptance. */
+export function manualReviewOnly(proof) {
+    return proof?.verdict === "short" && (proof.matrix === undefined || (proof.matrix.some(row => row.state === "manual-review")
+        && proof.matrix.every(row => row.state === "pass" || row.state === "manual-review")))
+        && proof.reasons.length > 0
+        && proof.reasons.every(reason => /^criterion "[^"]+" requires manual-review evidence — an operator must accept it before this can verify$/.test(reason));
+}
+/** Set equality, exactly — the "must equal the complete sealed git diff
+ * exactly" rule (v39) needs both directions, unlike the legacy subset
+ * check. */
+function setEquals(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const one of a)
+        if (!b.has(one))
+            return false;
+    return true;
+}
+/**
+ * The criterion-to-evidence matrix, computed once and shared by every
+ * surface (v39) — best-effort from whatever is available: `proof` is null
+ * when no proof parsed at all, in which case every approved criterion is
+ * simply unanswered. `[]` whenever no rubric was signed, so a
+ * grandfathered run renders no matrix at all rather than a wall of
+ * "missing" rows nobody signed up for.
+ */
+function criterionMatrix(approvedCriteria, proof, diffStat, screenshots) {
+    if (approvedCriteria.length === 0)
+        return [];
+    const answers = new Map((proof?.criteria ?? []).map(c => [c.id, c]));
+    const screenshotsByPath = new Map(screenshots.map(s => [s.path, s]));
+    const checksByCommand = new Map((proof?.checks ?? []).map(c => [c.command, c]));
+    const changedSet = new Set(proof?.changed ?? []);
+    // null = cannot know either way (diff unavailable or truncated) — never
+    // treated as agreement, per "an unavailable or truncated diff cannot verify".
+    const diffExact = diffStat !== null && diffStat.captured && !diffStat.truncated ? setEquals(changedSet, diffStat.paths) : null;
+    return approvedCriteria.map((approved) => {
+        const base = { id: approved.id, statement: approved.statement, requiredEvidence: approved.evidence, review: null };
+        const answer = answers.get(approved.id);
+        const contract = criterionContractProblems(approved, answer);
+        if (answer === undefined) {
+            return { ...base, state: "missing", detail: contract.map(one => one.message), answered: [] };
+        }
+        if (answer.statement.trim() !== approved.statement.trim()) {
+            return {
+                ...base,
+                state: "failed",
+                detail: contract.filter(one => one.kind === "statement").map(one => one.message),
+                answered: answer.evidence,
+            };
+        }
+        const detail = [];
+        let anyMissing = false;
+        let anyFailed = false;
+        let anyManual = false;
+        // Only adjudicate's trusted successful final check resolves this state.
+        // Until then the shared row must not misleadingly read as passed.
+        if (answer.verdict === "pending-verification") {
+            anyMissing = true;
+            detail.push(`criterion "${approved.id}" is waiting for the final check`);
+        }
+        // The proof's own caveats outrank its verdict word: a criterion marked
+        // `met` that a caveat names is not met by the proof's own admission.
+        for (const blocking of proof === null ? [] : blockingCaveats(proof)) {
+            if (blocking.criterionId !== approved.id)
+                continue;
+            anyFailed = true;
+            detail.push(`criterion "${approved.id}" is marked met, but caveat ${blocking.index + 1} admits an exception to it: ${blocking.caveat}`);
+        }
+        for (const kind of approved.evidence) {
+            const ref = answer.evidence.find(e => e.kind === kind);
+            if (ref === undefined) {
+                anyMissing = true;
+                detail.push(...contract.filter(one => one.kind === "evidence" && one.message.includes(`requires ${kind} evidence`)).map(one => one.message));
+                continue;
+            }
+            if (kind === "manual-review") {
+                anyManual = true;
+                detail.push(`criterion "${approved.id}" requires manual-review evidence — an operator must accept it before this can verify`);
+                continue;
+            }
+            if (kind === "check") {
+                const check = checksByCommand.get(ref.ref);
+                if (check === undefined) {
+                    anyFailed = true;
+                    detail.push(`criterion "${approved.id}"'s check evidence "${ref.ref}" does not match any reported check`);
+                }
+                else if (check.exitCode !== 0) {
+                    anyFailed = true;
+                    detail.push(failedCheckWords({ criterionId: approved.id, ref: ref.ref, exitCode: check.exitCode }));
+                }
+                continue;
+            }
+            if (kind === "screenshot") {
+                const shot = screenshotsByPath.get(ref.ref);
+                if (shot === undefined || !shot.ok) {
+                    anyFailed = true;
+                    detail.push(`criterion "${approved.id}"'s screenshot evidence "${ref.ref}" could not be verified${shot?.problem ? `: ${shot.problem}` : ""}`);
+                }
+                else if ((shot.bytes ?? 0) < SCREENSHOT_EVIDENCE_MIN_BYTES ||
+                    shot.dims == null ||
+                    shot.dims.width < SCREENSHOT_EVIDENCE_MIN_WIDTH ||
+                    shot.dims.height < SCREENSHOT_EVIDENCE_MIN_HEIGHT) {
+                    anyFailed = true;
+                    detail.push(`criterion "${approved.id}"'s screenshot "${ref.ref}" is missing or placeholder-sized (needs a real PNG or JPEG of at least ${SCREENSHOT_EVIDENCE_MIN_BYTES} bytes and ${SCREENSHOT_EVIDENCE_MIN_WIDTH}x${SCREENSHOT_EVIDENCE_MIN_HEIGHT})`);
+                }
+                continue;
+            }
+            // changed-path
+            if (!changedSet.has(ref.ref)) {
+                anyFailed = true;
+                detail.push(`criterion "${approved.id}"'s changed-path evidence "${ref.ref}" is not among the proof's claimed changed paths`);
+            }
+            else if (diffExact !== true) {
+                anyFailed = true;
+                detail.push(diffExact === null
+                    ? `criterion "${approved.id}"'s changed-path evidence cannot verify — the sealed diff is unavailable or truncated`
+                    : `criterion "${approved.id}"'s changed-path evidence cannot verify — the proof's changed paths do not exactly match the sealed diff`);
+            }
+        }
+        const state = anyMissing ? "missing" : anyFailed ? "failed" : anyManual ? "manual-review" : "pass";
+        return { ...base, state, detail, answered: answer.evidence };
+    });
+}
+/** Evidence readiness only. The signed criteria are copied from the scope,
+ * never restated by the builder; an independent assessment must settle them. */
+function assessCapturedEvidence(input) {
+    const completeDiff = input.diffStat !== null && input.diffStat.captured && !input.diffStat.truncated;
+    const check = input.verifyCommand;
+    const checked = check.configured && check.ran && check.exitCode === 0;
+    let machineVerdict = checked ? "verified" : "attested";
+    const problems = [];
+    if (!input.handoffPresent)
+        problems.push("the terminal handoff is missing");
+    if (!input.terminalDiffPresent || input.terminalDiffCaptureStatus !== "ok")
+        problems.push("the machine-captured diff is missing or failed to capture");
+    if (!completeDiff)
+        problems.push("the sealed diff is unavailable or truncated; the exact candidate cannot be assessed");
+    if (check.configured && !check.ran)
+        problems.push(verificationFailureWords(check.failure));
+    if (problems.length > 0)
+        machineVerdict = "short";
+    if (check.configured && check.ran && check.exitCode !== 0) {
+        machineVerdict = "refuted";
+        problems.push(`the repository's approved verification command exited ${check.exitCode}`);
+    }
+    const matrix = (input.approvedCriteria ?? []).map((criterion) => {
+        const detail = [];
+        const answered = [];
+        let missing = false, failed = false, manual = false;
+        for (const kind of criterion.evidence) {
+            if (kind === "check") {
+                if (checked)
+                    answered.push({ kind, ref: input.verificationCommand ?? "approved project check" });
+                else {
+                    failed ||= check.configured && check.ran && check.exitCode !== 0;
+                    missing ||= !check.configured || !check.ran;
+                    detail.push(`criterion "${criterion.id}" needs a passing approved project check`);
+                }
+            }
+            else if (kind === "changed-path") {
+                if (completeDiff) {
+                    for (const path of input.diffStat.paths)
+                        answered.push({ kind, ref: path });
+                }
+                else {
+                    missing = true;
+                    detail.push(`criterion "${criterion.id}" needs the complete saved source inventory`);
+                }
+            }
+            else if (kind === "screenshot") {
+                // Screenshots must have been explicitly captured and validated, never
+                // guessed from arbitrary files or inferred from a passing test.
+                const shots = input.screenshots.filter(shot => shot.ok && (shot.bytes ?? 0) >= SCREENSHOT_EVIDENCE_MIN_BYTES &&
+                    shot.dims != null && shot.dims.width >= SCREENSHOT_EVIDENCE_MIN_WIDTH && shot.dims.height >= SCREENSHOT_EVIDENCE_MIN_HEIGHT);
+                if (shots.length === 0) {
+                    missing = true;
+                    detail.push(`criterion "${criterion.id}" needs a captured screenshot of the required behavior`);
+                }
+                else
+                    for (const shot of shots)
+                        answered.push({ kind, ref: shot.path });
+            }
+            else {
+                manual = true;
+                detail.push(`criterion "${criterion.id}" requires manual-review evidence — an operator must accept it before this can verify`);
+            }
+        }
+        const evidenceState = failed ? "failed" : missing ? "missing" : manual ? "manual-review" : "pass";
+        const coverage = input.reviewContext?.find(one => one.id === criterion.id);
+        return {
+            id: criterion.id, statement: criterion.statement, requiredEvidence: criterion.evidence,
+            assessment: { evidenceState, detail }, state: evidenceState === "pass" ? "missing" : evidenceState,
+            detail: [...detail, `criterion "${criterion.id}" awaits independent goal assessment`], answered, review: null,
+            ...(coverage === undefined ? {} : { coverage: { state: coverage.state, inherited: coverage.inherited, items: [...coverage.items], gaps: [...coverage.gaps], priorSupport: coverage.priorSupport } }),
+        };
+    });
+    return { machineVerdict, verdict: machineVerdict === "refuted" ? "refuted" : "short", matrix,
+        reasons: problems.length > 0 ? problems : [GOAL_ASSESSMENT_PENDING] };
+}
+/** Only direct assessments can settle a pending goal. Machine failures and
+ * required evidence remain authoritative; this never upgrades a legacy proof. */
+function foldGoalAssessment(base, judgements) {
+    const byId = new Map(judgements.map(one => [one.id, one]));
+    const matrix = base.matrix.map((row) => {
+        const evidence = row.assessment;
+        const judgement = byId.get(row.id);
+        const review = judgement === undefined ? row.review : { judgement: judgement.judgement, note: judgement.note, author: judgement.author };
+        const contradicted = review?.judgement === "contradicts";
+        const upheld = review?.judgement === "upholds";
+        return { ...row, review,
+            state: contradicted ? "failed" : evidence.evidenceState === "pass" ? upheld ? "pass" : "missing" : evidence.evidenceState,
+            detail: [...evidence.detail, ...(upheld ? [] : [review === null
+                        ? `criterion "${row.id}" awaits independent goal assessment`
+                        : `${review.author} ${contradicted ? "contradicts" : "needs more evidence for"} criterion "${row.id}": ${review.note}`])],
+        };
+    });
+    const machineReady = base.machineVerdict === "verified" || base.machineVerdict === "attested";
+    const contradicted = matrix.some(row => row.review?.judgement === "contradicts");
+    const passed = machineReady && matrix.every(row => row.state === "pass" && row.review?.judgement === "upholds");
+    const verdict = base.machineVerdict === "refuted" || contradicted ? "refuted" : passed ? base.machineVerdict : "short";
+    return { ...base, verdict, matrix, reasons: passed ? ["The saved evidence and independent assessment satisfy the approved goal."]
+            : [...(!machineReady ? base.reasons : []), ...matrix.flatMap(row => row.detail)] };
+}
+function verificationFailureWords(failure) {
+    return (() => {
+        switch (failure) {
+            case "dependency-missing":
+                return "the approved verification command could not start because a required project executable was unavailable and no approved recovery was enabled";
+            case "setup-stale":
+                return "automatic recovery stopped because the project setup or check changed";
+            case "setup-failed":
+                return "the approved setup command failed during automatic recovery";
+            case "tracked-files-changed":
+                return "automatic recovery stopped because tracked files no longer matched the built result";
+            case "setup-changed-files":
+                return "automatic recovery stopped because the setup command changed tracked files after the build";
+            case "checkout-moved":
+                return "automatic recovery stopped because the checkout moved away from the built commit";
+            case "cleanliness-unavailable":
+                return "automatic recovery stopped because Toolroll could not confirm that the built checkout was unchanged";
+            case "dependency-still-missing":
+                return "the required project executable was still unavailable after replaying the approved setup command";
+            case "retry-spawn-failed":
+                return "the retried verification command could not be started after automatic recovery";
+            case "retry-timed-out":
+                return "the retried verification command timed out after automatic recovery";
+            case "custody-lost":
+                return "automatic recovery stopped because this worker no longer owned the build";
+            case "timed-out":
+                return "the approved verification command timed out before checks finished";
+            case "spawn-failed":
+            default:
+                return "the approved verification command could not be run";
+        }
+    })();
+}
+/**
+ * Ordered rules; the first that fires wins. Every reason is a sentence the
+ * surfaces print verbatim — this function is the only place that decides
+ * wording, so the task page, run page, board, CLI, and chat cards cannot
+ * drift from each other (Priority 2, the "one surface, six places" rule).
+ *
+ * v39: `input.approvedCriteria` empty runs the rules below byte for byte —
+ * the grandfathering promise. Non-empty inserts the rubric rules AFTER the
+ * diff-stat and verify-command rules and BEFORE the legacy unmet check,
+ * exactly as approved in the v2 plan: a proof that alters a signed
+ * criterion's statement is REFUTED (the same severity as any other
+ * altered term); an unanswered criterion, an evidence reference that does
+ * not resolve, or a criterion capped at manual-review is SHORT (a gap, or
+ * a review a machine cannot finish, never a lie). The legacy self-declared
+ * `verdict` field still runs afterward and can only downgrade further,
+ * never upgrade past what the evidence proved.
+ *
+ * The changed[] vs. sealed-diff exactness check (review finding, post-v39)
+ * runs GLOBALLY, ahead of the rubric rules and independent of whether any
+ * criterion cites changed-path evidence at all — a rubric with none of
+ * those must not let an untruthful or incomplete changed[] through
+ * unchecked. An unavailable or truncated diff-stat cannot prove either
+ * direction, so it can only ever produce SHORT, never REFUTED.
+ */
+/** An optional screenshot inventory carries no builder-authored completion
+ * claims. The existing bounded parser still validates every supplied field. */
+export function artifactManifestOnly(proof) {
+    return proof.criteria.length === 0 && proof.checks.length === 0 && proof.changed.length === 0 && proof.caveats.length === 0;
+}
+export function adjudicate(input) {
+    const approvedCriteria = input.approvedCriteria ?? [];
+    if (input.directAssessment && approvedCriteria.length > 0 && (!input.proofArtifactPresent ||
+        (input.proofParse?.ok && artifactManifestOnly(input.proofParse.proof))))
+        return assessCapturedEvidence(input);
+    const coverageById = new Map((input.reviewContext ?? []).map(one => [one.id, one]));
+    const matrixOf = (proof) => criterionMatrix(approvedCriteria, proof, input.diffStat, input.screenshots).map(row => {
+        if (input.reviewContext === undefined)
+            return row;
+        const found = coverageById.get(row.id);
+        // A criterion the inventory never covered is a gap the surfaces
+        // must show, never a silent "judged from the patch".
+        const coverage = found === undefined
+            ? { state: "gap", inherited: false, items: [], gaps: ["the sealed review context carries no coverage entry for this criterion"], priorSupport: "none" }
+            : { state: found.state, inherited: found.inherited, items: [...found.items], gaps: [...found.gaps], priorSupport: found.priorSupport };
+        return { ...row, coverage };
+    });
+    if (!input.proofArtifactPresent) {
+        return { verdict: "short", reasons: ["no proof was written"], matrix: matrixOf(null) };
+    }
+    if (input.proofParse === null || !input.proofParse.ok) {
+        const detail = input.proofParse !== null && !input.proofParse.ok
+            ? input.proofParse.problems.map(p => p.message).join("; ")
+            : "the proof could not be read";
+        return { verdict: "short", reasons: [`the proof is malformed: ${detail}`], matrix: matrixOf(null) };
+    }
+    const submitted = input.proofParse.proof;
+    const finalCheckPassed = input.verifyCommand.configured && input.verifyCommand.ran && input.verifyCommand.exitCode === 0;
+    const pendingContractValid = proofSubmissionProblems(submitted, approvedCriteria).length === 0;
+    // Resolve only an explicit conditional claim, against THIS run's machine
+    // facts. Never infer intent from prose, modify the sealed receipt, or turn
+    // a genuine not-met/not-checked answer into success. All evidence, caveat,
+    // manual-review and artifact checks below still apply to the resolved copy.
+    const proof = {
+        ...submitted,
+        criteria: submitted.criteria.map(one => one.verdict === "pending-verification" && finalCheckPassed && pendingContractValid &&
+            approvedCriteria.some(approved => approved.id === one.id && approved.evidence.includes("check") && approved.statement.trim() === one.statement.trim())
+            ? { ...one, verdict: "met" } : one),
+    };
+    const matrix = matrixOf(proof);
+    if (!input.handoffPresent) {
+        return { verdict: "short", reasons: ["the terminal handoff is missing"], matrix };
+    }
+    if (!input.terminalDiffPresent || input.terminalDiffCaptureStatus === "failed") {
+        return { verdict: "short", reasons: ["the machine-captured diff is missing or failed to capture"], matrix };
+    }
+    // The claimed changed[] must equal the COMPLETE sealed diff exactly —
+    // globally, whether or not any signed criterion cites changed-path
+    // evidence at all (a rubric with none of those would otherwise let an
+    // untruthful or incomplete changed[] through unchecked). An unavailable
+    // or truncated stat cannot prove either direction, so it cannot verify:
+    // short, never refuted — "we could not check" is not "the claim is
+    // false" (the same ruling the verify-command facts make below).
+    if (input.diffStat === null || !input.diffStat.captured || input.diffStat.truncated) {
+        return {
+            verdict: "short",
+            reasons: ["the sealed diff is unavailable or truncated; the claimed changed paths cannot be verified against it"],
+            matrix,
+        };
+    }
+    {
+        const diffPaths = input.diffStat.paths;
+        const claimed = new Set(proof.changed);
+        const overclaimed = proof.changed.filter(path => !diffPaths.has(path));
+        if (overclaimed.length > 0) {
+            return {
+                verdict: "refuted",
+                reasons: [`claimed changed path${overclaimed.length > 1 ? "s" : ""} not in the sealed diff: ${overclaimed.join(", ")}`],
+                matrix,
+            };
+        }
+        const underclaimed = [...diffPaths].filter(path => !claimed.has(path));
+        if (underclaimed.length > 0) {
+            return {
+                verdict: "short",
+                reasons: [`the sealed diff touched path${underclaimed.length > 1 ? "s" : ""} the proof never claimed as changed: ${underclaimed.join(", ")}`],
+                matrix,
+            };
+        }
+    }
+    // Altering a signed requirement is an integrity contradiction, not an
+    // evidence gap. It outranks an environment failure: an unavailable check
+    // must never downgrade changed authority from refuted to short.
+    if (approvedCriteria.length > 0) {
+        const restated = matrix.filter(row => row.detail.some(d => d.includes("was signed as")));
+        if (restated.length > 0) {
+            return { verdict: "refuted", reasons: restated.flatMap(row => row.detail), matrix };
+        }
+    }
+    // A proof whose caveat admits an exception to a criterion it marks met
+    // contradicts itself (atomic authority closure): the verdict must agree
+    // with the caveats, and a self-disagreeing proof is conflicting
+    // evidence — refuted, never verified, whether or not a rubric was
+    // signed. It ranks with the altered-statement rule above: an
+    // environment failure must never soften a contradiction to short.
+    {
+        const blocking = blockingCaveats(proof);
+        if (blocking.length > 0) {
+            return {
+                verdict: "refuted",
+                reasons: blocking.map(one => `criterion "${one.criterionId}" is marked met, but caveat ${one.index + 1} admits an exception to it: ${one.caveat}`),
+                matrix,
+            };
+        }
+        // EVERY caveat is attributed (final authority closure): one that names
+        // no known criterion, or a tag nobody signed, is an exception the
+        // verdict cannot be reconciled with — the proof's own words do not
+        // say which criterion they qualify, and the plane refutes rather than
+        // guesses. Known ids are the signed rubric's alone when one was
+        // signed (a proof-authored extra id is no authority); the proof's own
+        // only when nothing was signed.
+        const unattributed = caveatAttributionProblems(proof, approvedCriteria.map(one => one.id));
+        if (unattributed.length > 0) {
+            return { verdict: "refuted", reasons: unattributed.map(caveatAttributionWords), matrix };
+        }
+    }
+    // A command that could not exercise the product is missing evidence, not
+    // contradictory evidence. This precedes criterion-state checks so the
+    // actionable environment cause is never buried under a generic gap.
+    if (input.verifyCommand.configured && !input.verifyCommand.ran) {
+        const reason = verificationFailureWords(input.verifyCommand.failure);
+        return { verdict: "short", reasons: [reason], matrix };
+    }
+    if (input.verifyCommand.configured && input.verifyCommand.ran && input.verifyCommand.exitCode !== 0) {
+        return {
+            verdict: "refuted",
+            reasons: [
+                input.verifyCommand.setupReplayed === true
+                    ? `the repository's approved verification command exited ${input.verifyCommand.exitCode} after the approved setup command was replayed`
+                    : `the repository's approved verification command exited ${input.verifyCommand.exitCode}`,
+            ],
+            matrix,
+        };
+    }
+    if (approvedCriteria.length > 0) {
+        // manual-review folds in here too (v39 review finding): a row that
+        // needs a human's eyes is never machine-verifiable, so it must never
+        // reach "verified" or "attested" on its own — it stays "short" until
+        // an operator explicitly accepts the proof (the same act that already
+        // lets a short/refuted run read as done).
+        const unresolved = matrix.filter(row => row.state === "missing" || row.state === "failed" || row.state === "manual-review");
+        if (unresolved.length > 0) {
+            return { verdict: "short", reasons: unresolved.flatMap(row => row.detail), matrix };
+        }
+    }
+    const unmet = proof.criteria.filter(c => c.verdict !== "met");
+    if (unmet.length > 0) {
+        return {
+            verdict: "short",
+            reasons: unmet.map(c => `criterion "${c.statement}" is ${c.verdict === "not-met" ? "not met" : c.verdict === "pending-verification" ? "waiting for the final check" : "not checked"}`),
+            matrix,
+        };
+    }
+    const badScreenshots = input.screenshots.filter(s => !s.ok);
+    if (badScreenshots.length > 0) {
+        return {
+            verdict: "short",
+            reasons: badScreenshots.map(s => `claimed screenshot "${s.path}" could not be verified${s.problem ? `: ${s.problem}` : ""}`),
+            matrix,
+        };
+    }
+    if (input.verifyCommand.configured && input.verifyCommand.ran && input.verifyCommand.exitCode === 0) {
+        return {
+            verdict: "verified",
+            reasons: [
+                input.verifyCommand.setupReplayed === true
+                    ? "the approved verification command passed after the approved setup command ran"
+                    : "the approved verification command passed",
+            ],
+            matrix,
+        };
+    }
+    return { verdict: "attested", reasons: ["the proof agrees with the sealed diff; no verification command is configured to re-run"], matrix };
+}
+/**
+ * Folds an independent reviewer's per-criterion judgements into an ALREADY
+ * ADJUDICATED result (v40, evidence-review-v1) — pure, and never re-derives
+ * verdict facts that were not persisted (verify-command outcome, screenshot
+ * bytes): it folds over the STORED result, it does not re-run `adjudicate`.
+ *
+ * Three rules, and they are the whole contract:
+ *  - `contradicts` -> refuted. A second reader saying a signed term is not
+ *    met is the same severity as a proof that altered the term: the
+ *    matching row becomes `failed`, with the reviewer's note as an
+ *    attributed `detail` line.
+ *  - `cannot-tell` changes nothing. Recorded and rendered, never moves the
+ *    verdict — "we could not check" is not "the claim is false" (the same
+ *    maxim `adjudicate` already lives by for an unavailable diff or a
+ *    failed verify-command attempt).
+ *  - `upholds` never upgrades. A `short` (or `attested`) run stays exactly
+ *    what it was — this is the law that stops a second model laundering a
+ *    bad proof, and the reason `foldReview` can only LOWER a verdict, never
+ *    raise one.
+ *
+ * A judgement naming a criterion absent from `base.matrix` is ignored —
+ * `parseReview` already refuses a payload naming an unsigned id, so this is
+ * belt and suspenders, never a live path.
+ */
+export function foldReview(base, judgements) {
+    if (judgements.length === 0)
+        return base;
+    if (base.matrix.length > 0 && base.matrix.every(row => row.assessment !== undefined)) {
+        return foldGoalAssessment(base, judgements);
+    }
+    const byId = new Map(judgements.map(j => [j.id, j]));
+    let anyContradiction = false;
+    const matrix = base.matrix.map((row) => {
+        const judgement = byId.get(row.id);
+        if (judgement === undefined)
+            return row;
+        const review = { judgement: judgement.judgement, note: judgement.note, author: judgement.author };
+        if (judgement.judgement !== "contradicts")
+            return { ...row, review };
+        anyContradiction = true;
+        return {
+            ...row,
+            state: "failed",
+            detail: [...row.detail, `${judgement.author} contradicts criterion "${row.id}": ${judgement.note}`],
+            review,
+        };
+    });
+    if (!anyContradiction)
+        return { ...base, matrix };
+    const contradictions = matrix.filter(row => row.review?.judgement === "contradicts");
+    return {
+        verdict: "refuted",
+        reasons: [...base.reasons, ...contradictions.flatMap(row => (row.review === null ? [] : [`${row.review.author} contradicts criterion "${row.id}": ${row.review.note}`]))],
+        matrix,
+    };
+}
+export function semanticCoverage(matrix, policy) {
+    const judged = (word) => matrix.filter(row => row.review?.judgement === word).map(row => row.id);
+    const upheld = judged("upholds");
+    const contradicted = judged("contradicts");
+    const uncertain = judged("cannot-tell");
+    const unreviewed = matrix.filter(row => row.review === null).map(row => row.id);
+    // Every named gap is listed, including one on a row the patch still
+    // judges: what could not be sealed is said, whatever else was.
+    const contextGaps = matrix.flatMap(row => (row.coverage !== undefined && row.coverage.gaps.length > 0 ? [{ id: row.id, gaps: [...row.coverage.gaps] }] : []));
+    const reviewed = matrix.length - unreviewed.length;
+    return {
+        policy,
+        required: policy === "strict" || matrix.some(row => row.assessment !== undefined),
+        total: matrix.length,
+        upheld,
+        contradicted,
+        uncertain,
+        unreviewed,
+        contextGaps,
+        satisfied: matrix.length === 0 || reviewed === 0 ? null : upheld.length === matrix.length,
+    };
+}
+/** The coverage in plain words — one line every surface prints the same
+ * way. `[]` for a run with no rubric: nothing to cover. */
+export function coverageWords(coverage) {
+    if (coverage.total === 0)
+        return [];
+    const lines = [];
+    // No review has folded: nothing is waited for (model review is retired),
+    // so only sealed context gaps are worth a line.
+    if (coverage.satisfied === null) {
+        for (const gap of coverage.contextGaps)
+            lines.push(`context gap ${gap.id}: ${gap.gaps.join("; ")}`);
+        return lines;
+    }
+    const standing = coverage.satisfied === null
+        ? coverage.required ? "required under strict quality — no independent review has settled yet" : "independent review is optional under default quality — none has settled"
+        : coverage.satisfied
+            ? coverage.required ? "required under strict quality — satisfied" : "optional under default quality — every criterion upheld"
+            : coverage.required
+                ? `required under strict quality — NOT satisfied (${[...(coverage.uncertain.length > 0 ? [`cannot-tell never counts: ${coverage.uncertain.join(", ")}`] : []), ...(coverage.contradicted.length > 0 ? [`contradicted: ${coverage.contradicted.join(", ")}`] : []), ...(coverage.unreviewed.length > 0 ? [`unreviewed: ${coverage.unreviewed.join(", ")}`] : [])].join("; ")})`
+                : `optional under default quality — ${coverage.upheld.length}/${coverage.total} upheld${coverage.uncertain.length > 0 ? `, cannot-tell: ${coverage.uncertain.join(", ")}` : ""}${coverage.contradicted.length > 0 ? `, contradicted: ${coverage.contradicted.join(", ")}` : ""}`;
+    lines.push(`semantic coverage: ${coverage.upheld.length}/${coverage.total} upheld by an independent reviewer — ${coverage.policy === "default" && coverage.required ? standing.replaceAll("under strict quality", "for goal assessment") : standing}`);
+    for (const gap of coverage.contextGaps)
+        lines.push(`context gap ${gap.id}: ${gap.gaps.join("; ")}`);
+    return lines;
+}
+/** The pass fraction of a criterion matrix — the one number every list
+ * surface (board, chat) needs, shared so "N/M criteria" is computed in
+ * exactly one place (v40 closes the two hand-rolled copies). */
+export function passFraction(matrix) {
+    return { passed: matrix.filter(row => row.state === "pass").length, total: matrix.length };
+}
+/** The matrix in plain lines, for a text surface (the CLI, `brief`) — the
+ * same shared vocabulary `criterionMatrixHtml` renders in the console, so
+ * the words never drift between the two (Priority 2's rule, extended). */
+export function matrixWords(matrix) {
+    if (matrix.length === 0)
+        return [];
+    const lines = ["  acceptance matrix"];
+    for (const row of matrix) {
+        lines.push(`    [${row.state}] ${row.id}: ${row.statement} (requires: ${row.requiredEvidence.join(", ")})`);
+        if (row.answered.length > 0) {
+            lines.push(`      answered: ${row.answered.map(a => `${a.kind}: ${a.ref}`).join("; ")}`);
+        }
+        for (const detail of row.detail)
+            lines.push(`      ${detail}`);
+        if (row.review !== null) {
+            lines.push(`      review (${row.review.author}): ${row.review.judgement} — ${row.review.note}`);
+        }
+        if (row.coverage !== undefined) {
+            lines.push(`      context: ${coverageStateWords(row.coverage)}`);
+        }
+    }
+    return lines;
+}
+/** One criterion's context standing in words — shared by the CLI matrix
+ * and the console badge title so the two never drift. */
+export function coverageStateWords(coverage) {
+    const prior = coverage.priorSupport === "eligible" ? "; an earlier review of the source may be weighed as context (never as this run's verdict)" : coverage.priorSupport === "invalid" ? "; the earlier source review no longer supports it" : "";
+    switch (coverage.state) {
+        case "patch":
+            return `judged from this run's own patch${coverage.gaps.length > 0 ? ` (${coverage.gaps.join("; ")})` : ""}${prior}`;
+        case "context":
+            return `inherited — sealed context ${coverage.items.join(", ")}${prior}`;
+        case "gap":
+            return `GAP — inherited context is missing: ${coverage.gaps.join("; ")}${coverage.items.length > 0 ? ` (partial: ${coverage.items.join(", ")})` : ""}${prior}`;
+    }
+}
+/** Plain words for a verdict, shared by every surface (the `summary.ts`
+ * pattern) so the task page, run page, board, CLI, and chat cannot say
+ * three different things about the same run. */
+export function verdictWords(verdict, reasons) {
+    const detail = reasons.length > 0 ? reasons.join("; ") : "";
+    switch (verdict) {
+        case "verified":
+            return { word: "complete — verified", detail };
+        case "attested":
+            return { word: "complete — evidence attested", detail };
+        case "short":
+            return { word: "missing evidence", detail };
+        case "refuted":
+            return { word: "conflicting evidence", detail };
+    }
+}
+/** The `data-dispatch-status` token a page's CSS and tests key off. */
+export function dispatchStatusToken(verdict) {
+    switch (verdict) {
+        case "verified":
+            return "complete-verified";
+        case "attested":
+            return "complete-with-evidence";
+        case "short":
+            return "needs-verification";
+        case "refuted":
+            return "proof-refuted";
+    }
+}