ultra11y 5.3.4 → 5.4.0

package/src/cli.ts

@@ -50,6 +50,7 @@ import {
   hydrateAdjudication,
   type AdjudicationFile,
 } from "./adjudicate.js";
+import { entriesFrom, isLedger, ledgerPath, mergeLedger, readLedger, replayLedger, type VerdictLedger, writeLedger } from "./ledger.js";
 import { BATCH_SIZE, apiKeyFromEnv, applyRawVerdicts, judgeAll, modelFromEnv } from "./llm.js";
 import { runScan, runScanMany, runCrawlScan, runSampleScan, mergeDynamic, mergeSnapshotAudit, cleanDynamic, dockerAvailable } from "./scan.js";
 import { runScanLocal, runScanManyLocal, runCrawlScanLocal, runSampleScanLocal, localAvailable } from "./scan-local.js";
@@ -375,6 +376,13 @@ Options:
   --generate         criteria: emit the bundled references/criteria.md (WCAG 2.2 AA)
   --apply <file>     verify: reduce a filled verdicts file to a pass/fail gate
                      (requires --report — coverage is re-derived from the report, uncapped)
+                     Also accepts an ADJUDICATION (--in <audit.json>), or a VERDICT LEDGER,
+                     which it REPLAYS onto the audit with no model in the loop
+  --ledger <file>    verify --apply / judge --apply: record the verdicts the fold ACCEPTED,
+                     so a later run replays them for free (default:
+                     .ultra11y/verdicts/<standard>.json). Replay re-derives the evidence
+                     and re-runs the same gate; a verdict whose evidence changed is
+                     dropped as stale and its criterion says so
   --max-verify <n>   verify: cap the worklist size; 0 = no cap           (default: 40)
   --verdicts <file>  check --semantic: the adjudicated verdicts artifact
                      (default: VERIFY.todo.json next to the report)
@@ -437,6 +445,10 @@ Options:
   --apply            judge: fold the verdicts straight into the audit, through the SAME
                      fail-closed gate an agent's verdicts pass (no unjustified C/NA, no
                      ungroundable NC, no unadjudicated criterion)
+  --strict           verify --apply / judge --apply: all-or-nothing fold — one refused
+                     verdict discards the whole adjudication. The default folds PER
+                     VERDICT: a refusal costs its own criterion, which stays to assess
+                     carrying the refusal, and every verdict that proved itself lands
   --semantic         verify: fold the support-check into one pass
                      check: engage the semantic gate — requires an adjudicated verdicts
                      artifact (fails closed when absent) and re-grounds every passing
@@ -515,6 +527,10 @@ const VALUE_FLAGS = new Set([
   "dedup",
   "only",
   "standard",
+  // `verify --apply` / `judge --apply`: where to RECORD the verdicts the fold accepted, so a
+  // later run can replay them without a model (src/ledger.ts). A path; empty falls back to the
+  // standard's default location under .ultra11y/verdicts/.
+  "ledger",
   "baseline",
   "fail-on",
   "split",
@@ -599,6 +615,9 @@ const BOOLEAN_FLAGS = new Set([
   "generate",
   "semantic",
   "manual",
+  // `verify --apply` / `judge --apply`: restore the all-or-nothing fold, where one refused
+  // verdict discards the whole adjudication. The default is per-verdict.
+  "strict",
   "no-technical",
   "override",
   "local",
@@ -2493,10 +2512,14 @@ function cmdVerify(p: ParsedArgs): number {
       return 2;
     }
     // Dispatch on shape: an OBJECT with kind:"adjudication" is a manual-criteria adjudication
-    // (src/adjudicate.ts); a plain ARRAY is the classic NC-verdicts worklist.
+    // (src/adjudicate.ts); kind:"verdict-ledger" is a stored one being REPLAYED (src/ledger.ts,
+    // no model in the loop); a plain ARRAY is the classic NC-verdicts worklist.
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed) && (parsed as { kind?: string }).kind === "adjudication") {
       return applyAdjudicationFile(p, parsed as AdjudicationFile, lang);
     }
+    if (isLedger(parsed)) {
+      return replayLedgerFile(p, parsed, lang);
+    }
     if (!Array.isArray(parsed)) {
       console.error("ultra11y verify: --apply must be a JSON array of verdicts, or an adjudication object.");
       return 2;
@@ -2624,6 +2647,109 @@ function cmdVerify(p: ParsedArgs): number {
   return 0;
 }
 
+/** Where to record the verdicts a fold accepted. `--ledger <path>` names a file; `--ledger`
+ *  bare takes the standard's default location. Absent ⇒ nothing is recorded, so a caller who
+ *  never asked for a ledger never gets a surprise file in their tree. */
+function ledgerTarget(p: ParsedArgs, standard: StandardId): string | undefined {
+  const flag = p.flags.ledger;
+  if (flag === undefined || flag === false) return undefined;
+  return typeof flag === "string" && flag ? flag : ledgerPath(standard);
+}
+
+/** `verify --apply <ledger.json> --in <audit.json> --out <dir>` — REPLAY stored verdicts onto
+ *  a fresh audit, with no model in the loop.
+ *
+ *  This is the parity mechanism: the same `applyAdjudication` gate runs, on evidence re-derived
+ *  from the audit in front of it, so a stored verdict has to prove itself again exactly as it
+ *  did the day it was recorded. A verdict whose evidence has since changed is dropped as stale
+ *  and its criterion returns to « to assess », saying so. */
+function replayLedgerFile(p: ParsedArgs, ledger: VerdictLedger, lang: Lang): number {
+  const inFlag = p.flags.in;
+  if (typeof inFlag !== "string" || !inFlag) {
+    console.error(
+      lang === "fr"
+        ? "ultra11y verify : --apply <registre> exige --in <audit.json> (l'audit à mettre à jour)."
+        : "ultra11y verify: --apply <ledger> requires --in <audit.json> (the audit to update).",
+    );
+    return 2;
+  }
+  let audit: AuditResult;
+  try {
+    audit = JSON.parse(readText(inFlag)) as AuditResult;
+  } catch {
+    console.error(`ultra11y verify: --in file not found or not valid JSON: ${inFlag}.`);
+    return 2;
+  }
+  const cwd = typeof p.flags.cwd === "string" ? (p.flags.cwd as string) : undefined;
+  const standard = resolveStandard(p.flags.standard) ?? ledger.standard;
+  const rp = replayLedger(audit, ledger, { cwd, standard });
+  const r = applyAdjudication(audit, rp.adj, { cwd, strict: p.flags.strict === true, residualReasons: rp.residualReasons });
+
+  if (!r.ok && (p.flags.strict === true || r.applied + r.stillManual === 0)) {
+    if (p.flags.json) console.log(JSON.stringify({ ...r, replay: rp }, null, 2));
+    else {
+      console.error(lang === "fr" ? `✗ Registre rejeté (${r.issues.length} problème(s)) :` : `✗ Ledger rejected (${r.issues.length} issue(s)):`);
+      for (const i of r.issues) console.error(`  ✗ ${i}`);
+    }
+    return 1;
+  }
+  const out = typeof p.flags.out === "string" ? (p.flags.out as string) : ".";
+  mkdirSync(out, { recursive: true });
+  const auditPath = join(out, "audit-latest.json");
+  writeFileSync(auditPath, `${JSON.stringify(r.audit, null, 2)}\n`);
+
+  if (p.flags.json)
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          auditPath,
+          applied: r.applied,
+          stillManual: r.stillManual,
+          rejected: r.rejected,
+          rejectedCriteria: r.rejectedCriteria,
+          replayed: rp.fresh.length,
+          stale: rp.stale,
+          obsolete: rp.obsolete,
+          missing: rp.missing,
+          issues: r.issues,
+          conformancePct: r.audit.conformancePct,
+          grounding: r.grounding,
+        },
+        null,
+        2,
+      ),
+    );
+  else {
+    console.log(
+      lang === "fr"
+        ? `✓ ${r.applied} verdict(s) rejoué(s) depuis le registre, ${r.stillManual} laissé(s) en résiduel${r.rejected ? `, ${r.rejected} refusé(s)` : ""} → ${auditPath}`
+        : `✓ ${r.applied} verdict(s) replayed from the ledger, ${r.stillManual} left residual${r.rejected ? `, ${r.rejected} refused` : ""} → ${auditPath}`,
+    );
+    // Named, never merely counted: these are exactly the criteria a refresh pass has to
+    // adjudicate, and a silent count is what let a half-covered grid read as complete.
+    if (rp.stale.length)
+      console.error(
+        lang === "fr"
+          ? `⚠ ${rp.stale.length} verdict(s) périmé(s) (l'évidence a changé) : ${rp.stale.join(", ")}`
+          : `⚠ ${rp.stale.length} stale verdict(s) (the evidence changed): ${rp.stale.join(", ")}`,
+      );
+    if (rp.missing.length)
+      console.error(
+        lang === "fr"
+          ? `⚠ ${rp.missing.length} critère(s) absent(s) du registre : ${rp.missing.join(", ")}`
+          : `⚠ ${rp.missing.length} criterion(ia) absent from the ledger: ${rp.missing.join(", ")}`,
+      );
+    if (rp.obsolete.length)
+      console.error(
+        lang === "fr"
+          ? `ℹ ${rp.obsolete.length} entrée(s) obsolète(s) (le moteur les décide désormais) : ${rp.obsolete.join(", ")}`
+          : `ℹ ${rp.obsolete.length} obsolete entry(ies) (the engine now decides them): ${rp.obsolete.join(", ")}`,
+      );
+  }
+  return 0;
+}
+
 /** `verify --apply <adjudication.json> --in <audit.json> --out <dir>` — fold an AI
  *  adjudication of the manual criteria back into the audit, fail-closed, then rewrite the
  *  audit JSON so `report`/`prd` re-render with the adjudicated statuses. */
@@ -2648,9 +2774,15 @@ function applyAdjudicationFile(p: ParsedArgs, adj: AdjudicationFile, lang: Lang)
   // they were made against. Put it back from the audit before folding: the worklist is a pure
   // function of the audit, so this reconstructs the very anchors the citation gate checks
   // against — the fold below is the same fold, with the same refusals.
-  hydrateAdjudication(adj, audit, { cwd: typeof p.flags.cwd === "string" ? (p.flags.cwd as string) : undefined });
-  const r = applyAdjudication(audit, adj);
-  if (!r.ok) {
+  const cwd = typeof p.flags.cwd === "string" ? (p.flags.cwd as string) : undefined;
+  hydrateAdjudication(adj, audit, { cwd });
+  const strict = p.flags.strict === true;
+  const r = applyAdjudication(audit, adj, { cwd, strict });
+  // STRICT: one refusal discards the file, nothing is persisted — the historical contract.
+  // PARTIAL (default): the refusals are reported, the criteria they condemn stay to assess,
+  // and everything that proved itself is kept. Only a fold that landed NOTHING is an error;
+  // otherwise a single bad verdict would again cost the whole run.
+  if (!r.ok && (strict || r.applied + r.stillManual === 0)) {
     if (p.flags.json) console.log(JSON.stringify(r, null, 2));
     else {
       console.error(lang === "fr" ? `✗ Adjudication rejetée (${r.issues.length} problème(s)) :` : `✗ Adjudication rejected (${r.issues.length} issue(s)):`);
@@ -2658,11 +2790,35 @@ function applyAdjudicationFile(p: ParsedArgs, adj: AdjudicationFile, lang: Lang)
     }
     return 1;
   }
+  if (r.rejected > 0 && !p.flags.json) {
+    console.error(
+      lang === "fr"
+        ? `⚠ ${r.rejected} critère(s) refusé(s) par la porte — ils restent à évaluer, avec le motif du refus :`
+        : `⚠ ${r.rejected} criterion(ia) refused by the gate — they stay to assess, carrying the refusal:`,
+    );
+    for (const i of r.issues) console.error(`  ✗ ${i}`);
+  }
   // Persist the updated audit so report/prd re-render with the adjudicated statuses.
   const out = typeof p.flags.out === "string" ? (p.flags.out as string) : ".";
   mkdirSync(out, { recursive: true });
   const auditPath = join(out, "audit-latest.json");
   writeFileSync(auditPath, JSON.stringify(r.audit, null, 2) + "\n");
+  // Record what landed, so the next run does not have to pay a model to learn it again. Only
+  // the ACCEPTED verdicts go in: a refused one in the ledger would be laundered back on the
+  // next replay, which is the whole thing the gate exists to prevent.
+  const ledgerOut = ledgerTarget(p, adj.standard);
+  if (ledgerOut) {
+    const refused = new Set(r.rejectedCriteria);
+    const accepted = new Set(adj.items.map((it) => it.criteriaId).filter((id) => !refused.has(id)));
+    const fresh = entriesFrom(adj, accepted, r.audit.date);
+    writeLedger(ledgerOut, mergeLedger(readLedger(ledgerOut), adj.standard, fresh));
+    if (!p.flags.json)
+      console.log(
+        lang === "fr"
+          ? `✓ ${fresh.length} verdict(s) enregistré(s) au registre → ${ledgerOut}`
+          : `✓ ${fresh.length} verdict(s) recorded in the ledger → ${ledgerOut}`,
+      );
+  }
   // Carry the numbers the fold produced. The failure payload has always described its own
   // outcome (`issues`); the success one described only the mechanics, so a caller that gates
   // on the adjudicated result — a CI step, an orchestrator's tool node — had to re-read and
@@ -2675,6 +2831,9 @@ function applyAdjudicationFile(p: ParsedArgs, adj: AdjudicationFile, lang: Lang)
           auditPath,
           applied: r.applied,
           stillManual: r.stillManual,
+          rejected: r.rejected,
+          rejectedCriteria: r.rejectedCriteria,
+          issues: r.issues,
           conformancePct: r.audit.conformancePct,
           findings: r.audit.findings.length,
           grounding: r.grounding,
@@ -2686,8 +2845,8 @@ function applyAdjudicationFile(p: ParsedArgs, adj: AdjudicationFile, lang: Lang)
   else
     console.log(
       lang === "fr"
-        ? `✓ ${r.applied} critère(s) adjugé(s), ${r.stillManual} laissé(s) en résiduel → ${auditPath}`
-        : `✓ ${r.applied} criterion(ia) adjudicated, ${r.stillManual} left residual → ${auditPath}`,
+        ? `✓ ${r.applied} critère(s) adjugé(s), ${r.stillManual} laissé(s) en résiduel${r.rejected ? `, ${r.rejected} refusé(s)` : ""} → ${auditPath}`
+        : `✓ ${r.applied} criterion(ia) adjudicated, ${r.stillManual} left residual${r.rejected ? `, ${r.rejected} refused` : ""} → ${auditPath}`,
     );
   return 0;
 }
@@ -2746,16 +2905,18 @@ async function cmdJudge(p: ParsedArgs): Promise<number> {
   }
   const max = typeof p.flags.max === "string" ? Number(p.flags.max) : undefined;
   const truncated = max !== undefined && Number.isFinite(max) && max > 0 && items.length > max;
-  // `--max` bounds the spend; `--apply` folds the verdicts through a gate that REFUSES an
-  // incomplete adjudication. Together they can never succeed — so say so before spending
-  // anything, instead of billing a full run and failing on coverage at the end.
-  if (truncated && p.flags.apply === true) {
+  // `--max` bounds the spend. It used to be refused outright together with `--apply`, and
+  // rightly so: the fold was all-or-nothing, so a bounded adjudication could only ever fail on
+  // coverage — billing a full run to guarantee a failure. The fold is now per-verdict, so a
+  // bounded run lands what it covered and leaves the rest to assess, which is precisely what
+  // someone bounding spend is asking for. The pair is impossible only under `--strict`.
+  if (truncated && p.flags.apply === true && p.flags.strict === true) {
     console.error(
       lang === "fr"
-        ? `ultra11y judge : --max ${max} ne couvre que ${max} des ${items.length} critères, et --apply exige une adjudication COMPLÈTE (le gate refuse une couverture partielle).\n` +
-            "  Retirez --max pour tout adjuger, ou retirez --apply pour produire la worklist et l'appliquer plus tard."
-        : `ultra11y judge: --max ${max} covers only ${max} of ${items.length} criteria, and --apply requires a COMPLETE adjudication (the gate refuses partial coverage).\n` +
-            "  Drop --max to adjudicate everything, or drop --apply to produce the worklist and apply it later.",
+        ? `ultra11y judge : --max ${max} ne couvre que ${max} des ${items.length} critères, et --apply --strict exige une adjudication COMPLÈTE (le fold tout-ou-rien refuse une couverture partielle).\n` +
+            "  Retirez --strict pour appliquer ce qui est couvert, retirez --max pour tout adjuger, ou retirez --apply pour produire la worklist et l'appliquer plus tard."
+        : `ultra11y judge: --max ${max} covers only ${max} of ${items.length} criteria, and --apply --strict requires a COMPLETE adjudication (the all-or-nothing fold refuses partial coverage).\n` +
+            "  Drop --strict to apply what is covered, drop --max to adjudicate everything, or drop --apply to produce the worklist and apply it later.",
     );
     return 2;
   }
@@ -2811,20 +2972,45 @@ async function cmdJudge(p: ParsedArgs): Promise<number> {
   // --apply runs the SAME gate an agent's verdicts go through. A truncated run cannot pass
   // its coverage check, which is the correct outcome, not a bug.
   const adj = JSON.parse(readText(w.todoPath)) as AdjudicationFile;
-  const r = applyAdjudication(audit, adj);
-  if (!r.ok) {
+  const r = applyAdjudication(audit, adj, { strict: p.flags.strict === true });
+  // Same policy as `verify --apply`: a batch the model got wrong costs its own criteria, not
+  // the whole paid run. Only a fold that landed nothing at all is an error.
+  if (!r.ok && (p.flags.strict === true || r.applied + r.stillManual === 0)) {
     console.error(lang === "fr" ? `✗ Adjudication rejetée (${r.issues.length} problème(s)) :` : `✗ Adjudication rejected (${r.issues.length} issue(s)):`);
     for (const i of r.issues.slice(0, 40)) console.error(`  ✗ ${i}`);
     if (r.issues.length > 40) console.error(`  … +${r.issues.length - 40}`);
     return 1;
   }
+  if (r.rejected > 0) {
+    console.error(
+      lang === "fr"
+        ? `⚠ ${r.rejected} critère(s) refusé(s) par la porte — ils restent à évaluer, avec le motif du refus :`
+        : `⚠ ${r.rejected} criterion(ia) refused by the gate — they stay to assess, carrying the refusal:`,
+    );
+    for (const i of r.issues.slice(0, 40)) console.error(`  ✗ ${i}`);
+    if (r.issues.length > 40) console.error(`  … +${r.issues.length - 40}`);
+  }
   mkdirSync(out, { recursive: true });
   const auditPath = join(out, "audit-latest.json");
   writeFileSync(auditPath, `${JSON.stringify(r.audit, null, 2)}\n`);
+  // Same recording as `verify --apply`: what the model paid for, written down where the next
+  // run can replay it for free.
+  const ledgerOut = ledgerTarget(p, adj.standard);
+  if (ledgerOut) {
+    const refused = new Set(r.rejectedCriteria);
+    const accepted = new Set(adj.items.map((it) => it.criteriaId).filter((id) => !refused.has(id)));
+    const fresh = entriesFrom(adj, accepted, r.audit.date);
+    writeLedger(ledgerOut, mergeLedger(readLedger(ledgerOut), adj.standard, fresh));
+    console.log(
+      lang === "fr"
+        ? `✓ ${fresh.length} verdict(s) enregistré(s) au registre → ${ledgerOut}`
+        : `✓ ${fresh.length} verdict(s) recorded in the ledger → ${ledgerOut}`,
+    );
+  }
   console.log(
     lang === "fr"
-      ? `✓ ${r.applied} critère(s) adjugé(s), ${r.stillManual} laissé(s) en résiduel → ${auditPath}`
-      : `✓ ${r.applied} criterion(ia) adjudicated, ${r.stillManual} left residual → ${auditPath}`,
+      ? `✓ ${r.applied} critère(s) adjugé(s), ${r.stillManual} laissé(s) en résiduel${r.rejected ? `, ${r.rejected} refusé(s)` : ""} → ${auditPath}`
+      : `✓ ${r.applied} criterion(ia) adjudicated, ${r.stillManual} left residual${r.rejected ? `, ${r.rejected} refused` : ""} → ${auditPath}`,
   );
   return 0;
 }

package/src/ledger.ts

@@ -0,0 +1,250 @@
+// The VERDICT LEDGER — how a judgment criterion stays decided without paying a model again.
+//
+// The engine can decide only a handful of criteria outright; the rest are judgment calls that
+// an agent adjudicates from harvested evidence (src/adjudicate.ts). That worked in a session
+// and nowhere else: every other run — a CI job, a nightly report, a colleague's checkout —
+// started from zero and published « to assess », because a verdict lived only in the
+// `audit-latest.json` that one run produced.
+//
+// The ledger is that verdict, written down where it can be reviewed: a small file committed to
+// the audited repository, holding one entry per adjudicated criterion with its justification,
+// its citations and — the part that makes it trustworthy — a FINGERPRINT of the evidence it was
+// ruled against. Replaying it is not a cache lookup: each entry is rebuilt into an ordinary
+// adjudication and folded through `applyAdjudication`, so the same coverage checks, the same
+// citation matching and the same content-level re-grounding decide whether it still stands.
+// A verdict nobody can prove is refused in CI exactly as it would be in a session.
+//
+// Staleness is the reason the fingerprint exists. When the code under a criterion changes, the
+// evidence the agent read changes with it, the fingerprint stops matching, and the verdict is
+// dropped as STALE — the criterion returns to « to assess » saying so. The alternative, a
+// verdict that silently outlives the code it described, is the one failure mode a conformance
+// deliverable cannot afford.
+//
+// The fingerprint deliberately ignores LINE NUMBERS. Grounding already tolerates ±10 lines of
+// drift (a citation that moved is still the same citation), so hashing line numbers would
+// invalidate every verdict in a file the moment someone added a comment at the top — punishing
+// a formatting change like a semantic one. It hashes what the agent actually read: the file, the
+// selector and the normalised snippet.
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { type AdjudicationFile, type AdjudicationItem, type AgentFinding, buildAdjudicationWorklist, type Evidence } from "./adjudicate.js";
+import { CORE, type StandardId } from "./standards/index.js";
+import type { AuditResult } from "./types.js";
+import { SCHEMA_VERSION } from "./types.js";
+
+/** Where a ledger lives by default, relative to the audited repository root. Committed on
+ *  purpose: a verdict is a claim about this codebase, so it belongs in review alongside it. */
+export const LEDGER_DIR = ".ultra11y/verdicts";
+
+/** The default path for a standard's ledger. */
+export function ledgerPath(standard: StandardId, root = "."): string {
+  return join(root, LEDGER_DIR, `${standard}.json`);
+}
+
+export interface LedgerEntry {
+  criteriaId: string;
+  /** The verdict as folded — same vocabulary as an adjudication item. */
+  verdict: "C" | "NC" | "NA" | "manual";
+  justification?: string;
+  reason?: string | null;
+  citations?: Evidence[];
+  findings?: AgentFinding[];
+  recommendations?: AgentFinding[];
+  /** Fingerprint of the evidence this verdict was ruled against (see module header). */
+  evidenceFingerprint: string;
+  /** How many evidence items were harvested — carried for the reader, never trusted. */
+  evidenceCount: number;
+  /** ISO date the verdict was recorded. */
+  date: string;
+  /** Who ruled. Only ever "agent": the engine's own verdicts are recomputed every run and
+   *  have no business in a ledger. */
+  decidedBy: "agent";
+}
+
+export interface VerdictLedger {
+  tool: "ultra11y";
+  kind: "verdict-ledger";
+  schemaVersion: number;
+  standard: StandardId;
+  entries: LedgerEntry[];
+}
+
+const norm = (s: string) => s.replace(/\s+/g, " ").trim();
+
+/** The line-independent identity of one piece of evidence: what the agent actually read. */
+const anchorKey = (e: { file: string; selector?: string; snippet?: string }) => `${e.file}|${e.selector ?? ""}|${norm(e.snippet ?? "")}`;
+
+/** Fingerprint the evidence a criterion was ruled against. Order-independent (the harvester's
+ *  traversal order is not a property of the code) and line-independent (see module header). */
+export function evidenceFingerprint(evidence: Evidence[]): string {
+  const keys = evidence.map(anchorKey).sort();
+  return `sha256:${createHash("sha256")
+    .update(`${keys.length}\n${keys.join("\n")}`)
+    .digest("hex")
+    .slice(0, 32)}`;
+}
+
+/** Move a stored anchor onto TODAY's line for the same piece of evidence.
+ *
+ *  Necessary, not cosmetic. The fingerprint is deliberately line-independent, but the fold's
+ *  citation check is exact: a citation must match one of the criterion's harvested anchors by
+ *  `file:line`. Without re-anchoring, adding a comment at the top of a file shifted every line
+ *  and the gate refused every stored verdict in it as fabricated — punishing a reformatting
+ *  exactly like a rewrite, and making the ledger useless in practice.
+ *
+ *  This launders nothing: the fingerprint has already proved the evidence set is the same
+ *  content, so all that moves is the line number — the very drift `groundFinding` was written to
+ *  tolerate. An anchor with no counterpart in today's evidence is left untouched, and the fold
+ *  refuses it, which is the correct outcome. */
+function reanchor<T extends { file: string; line: number; selector?: string; snippet?: string }>(stored: T[] | undefined, today: Evidence[]): T[] | undefined {
+  if (!stored?.length) return stored;
+  const byKey = new Map(today.map((e) => [anchorKey(e), e]));
+  return stored.map((s) => {
+    const now = byKey.get(anchorKey(s));
+    return now && now.line !== s.line ? { ...s, line: now.line } : s;
+  });
+}
+
+export function emptyLedger(standard: StandardId = CORE): VerdictLedger {
+  return { tool: "ultra11y", kind: "verdict-ledger", schemaVersion: SCHEMA_VERSION, standard, entries: [] };
+}
+
+export function isLedger(v: unknown): v is VerdictLedger {
+  const o = v as VerdictLedger | null;
+  return !!o && typeof o === "object" && o.tool === "ultra11y" && o.kind === "verdict-ledger" && Array.isArray(o.entries);
+}
+
+export function readLedger(path: string): VerdictLedger | undefined {
+  if (!existsSync(path)) return undefined;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    return isLedger(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeLedger(path: string, ledger: VerdictLedger): void {
+  mkdirSync(dirname(path), { recursive: true });
+  // Entries id-sorted so the committed file has a stable diff — a ledger that reshuffles on
+  // every write is a ledger nobody reviews.
+  const sorted: VerdictLedger = { ...ledger, entries: [...ledger.entries].sort((a, b) => a.criteriaId.localeCompare(b.criteriaId, "en", { numeric: true })) };
+  writeFileSync(path, `${JSON.stringify(sorted, null, 2)}\n`);
+}
+
+/** Record the verdicts an adjudication just landed, as ledger entries.
+ *
+ *  `applied` names the criteria whose verdict the fold ACCEPTED — a refused one must never
+ *  reach the ledger, or the next replay would launder it back in. */
+export function entriesFrom(adj: AdjudicationFile, accepted: ReadonlySet<string>, date: string): LedgerEntry[] {
+  const out: LedgerEntry[] = [];
+  for (const it of adj.items) {
+    if (!accepted.has(it.criteriaId) || it.verdict === null) continue;
+    out.push({
+      criteriaId: it.criteriaId,
+      verdict: it.verdict,
+      ...(it.justification?.trim() ? { justification: it.justification.trim() } : {}),
+      ...(it.reason ? { reason: it.reason } : {}),
+      ...(it.citations?.length ? { citations: it.citations } : {}),
+      ...(it.findings?.length ? { findings: it.findings } : {}),
+      ...(it.recommendations?.length ? { recommendations: it.recommendations } : {}),
+      evidenceFingerprint: evidenceFingerprint(it.evidence),
+      evidenceCount: it.evidence.length,
+      date,
+      decidedBy: "agent",
+    });
+  }
+  return out;
+}
+
+/** Merge fresh entries over an existing ledger — same criterion, newest wins. A refresh pass
+ *  that only re-adjudicated part of the grid must not delete the rest. */
+export function mergeLedger(existing: VerdictLedger | undefined, standard: StandardId, fresh: LedgerEntry[]): VerdictLedger {
+  const base = existing && existing.standard === standard ? existing : emptyLedger(standard);
+  const byId = new Map(base.entries.map((e) => [e.criteriaId, e]));
+  for (const e of fresh) byId.set(e.criteriaId, e);
+  return { ...base, schemaVersion: SCHEMA_VERSION, standard, entries: [...byId.values()] };
+}
+
+export interface ReplayResult {
+  /** The ledger's still-valid verdicts, as an ordinary adjudication for `applyAdjudication`. */
+  adj: AdjudicationFile;
+  /** Criteria whose verdict still matches the evidence and will be folded. */
+  fresh: string[];
+  /** Criteria whose evidence changed since the verdict — dropped, with the reason to report. */
+  stale: string[];
+  /** Ledger entries for criteria the engine no longer leaves open (it decided them itself, or
+   *  they are not part of this standard). Dropped: the engine outranks a stored verdict. */
+  obsolete: string[];
+  /** Open criteria the ledger says nothing about — they stay to assess, and are what a refresh
+   *  pass has to adjudicate. */
+  missing: string[];
+  /** Per-criterion residual reasons for everything that did NOT fold, ready to hand to
+   *  `applyAdjudication`. */
+  residualReasons: Record<string, string>;
+}
+
+/** Rebuild a ledger into an adjudication for THIS audit, dropping what no longer holds.
+ *
+ *  The worklist is a pure function of the audit, so re-deriving it here reconstructs the very
+ *  evidence anchors the citation gate checks against — the fold that follows is the same fold,
+ *  with the same refusals. Nothing about a ledger entry is trusted except that it was written:
+ *  its fingerprint is recomputed, its criterion must still be open, and its citations are
+ *  re-grounded downstream. */
+export function replayLedger(audit: AuditResult, ledger: VerdictLedger, opts: { cwd?: string; standard?: StandardId } = {}): ReplayResult {
+  const standard = opts.standard ?? ledger.standard ?? CORE;
+  const worklist = buildAdjudicationWorklist(audit, { cwd: opts.cwd, standard });
+  const open = new Map(worklist.map((it) => [it.criteriaId, it]));
+  const byId = new Map(ledger.entries.map((e) => [e.criteriaId, e]));
+
+  const items: AdjudicationItem[] = [];
+  const fresh: string[] = [];
+  const stale: string[] = [];
+  const obsolete: string[] = [];
+  const missing: string[] = [];
+  const residualReasons: Record<string, string> = {};
+
+  for (const e of ledger.entries) if (!open.has(e.criteriaId)) obsolete.push(e.criteriaId);
+
+  for (const it of worklist) {
+    const e = byId.get(it.criteriaId);
+    if (!e) {
+      missing.push(it.criteriaId);
+      residualReasons[it.criteriaId] = "No verdict in the ledger — this criterion has never been adjudicated. Run an adjudication pass to record one.";
+      continue;
+    }
+    const now = evidenceFingerprint(it.evidence);
+    if (now !== e.evidenceFingerprint) {
+      stale.push(it.criteriaId);
+      residualReasons[it.criteriaId] =
+        `Ledger verdict is STALE — the evidence changed since it was recorded on ${e.date} (${e.evidenceCount} item(s) then, ${it.evidence.length} now). Re-adjudicate this criterion.`;
+      continue;
+    }
+    fresh.push(it.criteriaId);
+    // Rebuild the item on TODAY's harvested evidence, carrying only the decision from the
+    // ledger. The stored citations still have to be found among that evidence, which is what
+    // makes the replay a re-verification rather than a restore.
+    items.push({
+      ...it,
+      verdict: e.verdict,
+      justification: e.justification ?? "",
+      reason: e.reason ?? null,
+      findings: reanchor(e.findings, it.evidence) ?? [],
+      ...(e.citations ? { citations: reanchor(e.citations, it.evidence) ?? [] } : {}),
+      ...(e.recommendations ? { recommendations: reanchor(e.recommendations, it.evidence) ?? [] } : {}),
+      decidedBy: "agent",
+    });
+  }
+
+  return {
+    adj: { tool: "ultra11y", kind: "adjudication", schemaVersion: SCHEMA_VERSION, standard, auditDate: audit.date, items },
+    fresh,
+    stale,
+    obsolete,
+    missing,
+    residualReasons,
+  };
+}

package/src/orchestrate-templates.ts

@@ -197,7 +197,7 @@ For EACH of your criteria:
    - \`manual\` (still undecidable) — REQUIRES \`reason\`: \`needs-rendered-dom\` (only a rendered DOM can decide, e.g. computed contrast) or \`undecidable\` (the evidence cannot settle it either way).
 3. Never guess. A criterion you cannot decide from real evidence stays \`manual\` with a reason — that is a valid, honest verdict; the scan tier or a human picks it up.
 
-Return (structured output): \`{ "verdicts": [{ "criteriaId", "verdict", "justification", "citations", "reason", "findings" }] }\` — your ITEMS only, every field grounded in what you actually read, every NC finding carrying its \`normativeRef\`, and every C (plus every evidenced NA) carrying its \`citations\`. A verdict that clears a criterion without naming what it cleared is refused by the fold, and one refusal discards the WHOLE adjudication — including every other verdict you got right.
+Return (structured output): \`{ "verdicts": [{ "criteriaId", "verdict", "justification", "citations", "reason", "findings" }] }\` — your ITEMS only, every field grounded in what you actually read, every NC finding carrying its \`normativeRef\`, and every C (plus every evidenced NA) carrying its \`citations\`. A verdict that clears a criterion without naming what it cleared is refused by the fold; the refusal costs THAT criterion — which stays « to assess » carrying the reason — and leaves every other verdict standing. So never guess to fill a gap: an honest \`manual\` is worth more than a verdict the gate throws away.
 ${footer}`,
     refuter: `# Contract: refuter
 
@@ -243,7 +243,7 @@ ${status}
 ## The loop (play every role yourself, one item at a time)
 
 1. **Audit** (if not done): \`${engine} audit "<globs>" --graph --out ${runAbs}\` → \`${join(runAbs, "audit-latest.json")}\`.
-2. **Adjudicate the residual criteria** — \`${engine} verify --manual --in ${join(runAbs, "audit-latest.json")} --out ${runAbs}\` writes \`${join(runAbs, "ADJUDICATE.todo.json")}\`. For EVERY item, apply \`${join(runAbs, "orchestration", "agents", "adjudicator.md")}\` yourself (read the evidence, rule C/NC/NA/manual, fill the required justification/findings/reason IN the todo file). Then fold, fail-closed: \`${engine} verify --apply ${join(runAbs, "ADJUDICATE.todo.json")} --in ${join(runAbs, "audit-latest.json")} --out ${runAbs}\`.
+2. **Adjudicate the residual criteria** — \`${engine} verify --manual --in ${join(runAbs, "audit-latest.json")} --out ${runAbs}\` writes \`${join(runAbs, "ADJUDICATE.todo.json")}\`. For EVERY item, apply \`${join(runAbs, "orchestration", "agents", "adjudicator.md")}\` yourself (read the evidence, rule C/NC/NA/manual, fill the required justification/findings/reason IN the todo file). Then fold — gated per verdict, so a refusal costs its own criterion and no other: \`${engine} verify --apply ${join(runAbs, "ADJUDICATE.todo.json")} --in ${join(runAbs, "audit-latest.json")} --out ${runAbs}\`. Add \`--ledger .ultra11y/verdicts/<standard>.json\` to RECORD the verdicts that landed, so CI can replay them without a model; \`--strict\` restores the old all-or-nothing fold.
 3. **Report**: \`${engine} report --in ${join(runAbs, "audit-latest.json")} --out ${runAbs}\`.
 4. **Verify the report's claims** — \`${engine} verify --report <the report .md> --out ${runAbs}\` writes \`${join(runAbs, "VERIFY.todo.json")}\`. For EVERY entry, apply \`${join(runAbs, "orchestration", "agents", "refuter.md")}\` yourself (open file:line, verdict supported/partial/refuted/unsupported + note IN the todo file). Then: \`${engine} verify --apply ${join(runAbs, "VERIFY.todo.json")} --report <the report .md>\`.
 5. **Gate**: \`${engine} check --report <the report .md> --semantic\` must exit 0 before presenting anything.

package/src/report.ts

@@ -171,17 +171,35 @@ const L = {
   },
 } as const;
 
-// The needs-rendering criteria the scan tier decides, with the labels the partial-audit
-// banner names them by. Coverage comes from scope.scan.testedScs (stamped by mergeDynamic:
-// Docker measures 1.4.10 only; the local runtime adds zoom / spacing / focus / hover, and
-// live regions when interactions are on) — so the banner only ever names criteria that
-// genuinely lack a dynamic verdict, and drops only when every one of them is covered.
+// Every criterion an automated tier can CREDIT, with the labels the partial-audit banner names
+// them by. Two tiers contribute, and `scope.scan.testedScs` is the single coverage stamp for
+// both — so the banner only ever names criteria that genuinely lack a verdict, and disappears
+// once they are all covered:
+//
+//   - the SNAPSHOT tier (src/rules/rendered.ts), offline from a recorded page: 1.3.4, 1.4.1,
+//     1.4.3, 1.4.11, 2.4.7;
+//   - the LIVE-BROWSER tier (src/scan.ts Docker measures 1.4.10 only; src/scan-local.ts adds
+//     zoom / spacing / focus / hover, and live regions when interactions are on).
+//
+// This listed six, all from the live-browser tier, and that was wrong in both directions at
+// once: an audit that had ingested 35 snapshots and measured contrast and focus visibility from
+// them was still told the rendering criteria "were not tested", while the criteria those
+// snapshots really did decide were absent from the list and so could never be reported covered.
+//
+// The five needs-rendering criteria NO tier measures (1.4.5, 2.1.2, 2.3.1, 2.4.11, 2.5.8) are
+// deliberately NOT here: listing them would make the banner permanent and un-actionable, since
+// no run could ever clear it. They carry a per-criterion reason instead (src/audit.ts
+// RESIDUAL_TRAIL) saying that no automated tier decides them, and what does.
 const NEEDS_RENDERING: readonly { sc: string; label: Record<Lang, string> }[] = [
+  { sc: "1.3.4", label: { fr: "verrou d’orientation", en: "orientation lock" } },
+  { sc: "1.4.1", label: { fr: "information par la couleur", en: "use of colour" } },
+  { sc: "1.4.3", label: { fr: "contraste du texte", en: "text contrast" } },
   { sc: "1.4.4", label: { fr: "zoom 200 %", en: "200% zoom" } },
   { sc: "1.4.10", label: { fr: "reflow 320 px", en: "320px reflow" } },
+  { sc: "1.4.11", label: { fr: "contraste des composants", en: "non-text contrast" } },
   { sc: "1.4.12", label: { fr: "espacement du texte", en: "text spacing" } },
-  { sc: "2.4.7", label: { fr: "visibilité du focus", en: "focus visibility" } },
   { sc: "1.4.13", label: { fr: "contenu au survol", en: "content on hover" } },
+  { sc: "2.4.7", label: { fr: "visibilité du focus", en: "focus visibility" } },
   { sc: "4.1.3", label: { fr: "régions live", en: "live regions" } },
 ];