ultra11y 5.3.3 → 5.4.0

package/src/adjudicate.ts

@@ -10,7 +10,7 @@
 // C/NA, no ungroundable NC, no reasonless manual, full coverage of the residual set. The
 // decisions are the AGENT's, statically, gated — not a deferral to a human.
 import { mkdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import type { AuditResult, Automatability, Finding, Lang, PackCriterionAdjudication, ResidualRisk, Severity, Status } from "./types.js";
 import { SCHEMA_VERSION } from "./types.js";
 import { discover } from "./discover.js";
@@ -20,7 +20,7 @@ import { type Doc, type El, elementsByTag, attr, textContent, ancestors, snippet
 import { parseInlineStyle } from "./color.js";
 import { ADJUDICATION } from "./adjudication-data.js";
 import { scTitle, getSC, hasSC, techniquesFor, allSC, guidelineTitle } from "./wcag.js";
-import { groundItems, type GroundingSummary } from "./grounding.js";
+import { groundFinding, type GroundingSummary } from "./grounding.js";
 import {
   type StandardId,
   CORE,
@@ -331,7 +331,13 @@ function docsForAudit(audit: AuditResult, cwd?: string): Doc[] {
   const docs: Doc[] = [];
   for (const f of files) {
     try {
-      docs.push(parseSource(readText(cwd ? join(cwd, f) : f), f));
+      // `resolve`, not `join`: a cwd resolves RELATIVE paths and must leave an absolute one
+      // alone. `join("/repo", "/tmp/x/page.html")` produced `/repo/tmp/x/page.html`, which is
+      // unreadable — and the catch below swallows it, so every criterion silently arrived with
+      // ZERO evidence. The gate then refused each C verdict for "no evidence harvested",
+      // blaming the adjudicator for a path bug. Grounding has always used `resolve` for the
+      // same reason; these two must agree, since one harvests the anchors the other checks.
+      docs.push(parseSource(readText(cwd ? resolve(cwd, f) : f), f));
     } catch {
       /* unreadable — skip, mirrors runAudit */
     }
@@ -413,6 +419,13 @@ export interface ApplyAdjudicationResult {
   issues: string[];
   applied: number;
   stillManual: number;
+  /** Criteria whose verdict was REFUSED by the gate and therefore not applied. They stay
+   *  « to assess », each carrying the refusal as its residual reason. Always 0 in strict mode,
+   *  where a single refusal discards the whole fold. */
+  rejected: number;
+  /** The ids behind `rejected`, in file order — so a caller can name them without re-parsing
+   *  `issues` (one criterion can raise several). */
+  rejectedCriteria: string[];
   grounding: GroundingSummary;
 }
 
@@ -504,11 +517,51 @@ function normativeRefResolves(ref: string | undefined, standard: StandardId, ite
   return itemCriterionId === undefined || critId === itemCriterionId;
 }
 
-/** Fold an adjudication file back into the audit. FAIL-CLOSED (see module header). Returns
- *  a NEW AuditResult with the decided statuses, agent findings, recomputed conformancePct,
- *  a shrunk residual set, and the `adjudicated` marker. */
-export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opts: { cwd?: string } = {}): ApplyAdjudicationResult {
+/** Fold an adjudication file back into the audit. Returns a NEW AuditResult with the decided
+ *  statuses, agent findings, recomputed conformancePct, a shrunk residual set, and the
+ *  `adjudicated` marker.
+ *
+ *  FAIL-CLOSED PER VERDICT, which is not the same thing as fail-closed per FILE. Every check
+ *  below is unchanged and no refused verdict is ever applied — but a refusal now costs its own
+ *  criterion and nothing else. The all-or-nothing fold was measured to be worse than useless:
+ *  a CI run that filled 95 of 96 verdicts correctly had all 96 discarded, so the audit paid a
+ *  full adjudication and published « to assess » across the board. Since the point of the gate
+ *  is to keep an unproven verdict out of the report — not to punish the ones that proved
+ *  themselves — a refused criterion simply stays « to assess », carrying the refusal as its
+ *  residual reason so the next run knows what to fix.
+ *
+ *  `strict: true` restores the old file-level behaviour for a caller that genuinely wants
+ *  all-or-nothing (a conformance deliverable signed off in one pass). */
+export function applyAdjudication(
+  audit: AuditResult,
+  adj: AdjudicationFile,
+  opts: {
+    cwd?: string;
+    strict?: boolean;
+    /** Criteria the caller KNOWS this adjudication does not cover, each with the reason to
+     *  record. A ledger replay supplies them (« stale », « never adjudicated ») so an absence
+     *  it fully expected is not reported as a coverage violation — while the criterion still
+     *  stays to assess, carrying that reason instead of a blank cell. */
+    residualReasons?: Record<string, string>;
+  } = {},
+): ApplyAdjudicationResult {
   const issues: string[] = [];
+  const expected = opts.residualReasons ?? {};
+  // Per-criterion attribution. The gate used to collect one flat list, which is why it could
+  // only ever reject the whole file: an issue did not know which verdict it condemned.
+  const itemIssues = new Map<string, string[]>();
+  // Criteria that will NOT fold and must keep `manual` with a reason — the refused ones plus
+  // the ones the caller declared uncovered.
+  const notFolded = new Set<string>();
+  const blame = (criteriaId: string, issue: string) => {
+    issues.push(issue);
+    notFolded.add(criteriaId);
+    const list = itemIssues.get(criteriaId);
+    if (list) list.push(issue);
+    else itemIssues.set(criteriaId, [issue]);
+  };
+  /** An open criterion this adjudication deliberately does not carry. Not a gate violation. */
+  const uncovered = (criteriaId: string) => notFolded.add(criteriaId);
   // Spelling first, decisions second: "na" is NA, and rejecting the run over the case of a
   // verdict taught the caller nothing about accessibility. Everything below stays fail-closed.
   canonicalizeAdjudication(adj);
@@ -523,12 +576,16 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
     for (const pc of derivePackResults(audit, adj.standard)) {
       if (pc.status !== "manual") continue;
       open.add(pc.id);
-      if (!byId.has(pc.id)) issues.push(`criterion ${pc.id}: missing from the adjudication (coverage gap)`);
+      if (byId.has(pc.id)) continue;
+      if (Object.hasOwn(expected, pc.id)) uncovered(pc.id);
+      else blame(pc.id, `criterion ${pc.id}: missing from the adjudication (coverage gap)`);
     }
   } else {
     for (const r of audit.residualRisks) {
       open.add(r.criteriaId);
-      if (!byId.has(r.criteriaId)) issues.push(`criterion ${r.criteriaId}: missing from the adjudication (coverage gap)`);
+      if (byId.has(r.criteriaId)) continue;
+      if (Object.hasOwn(expected, r.criteriaId)) uncovered(r.criteriaId);
+      else blame(r.criteriaId, `criterion ${r.criteriaId}: missing from the adjudication (coverage gap)`);
     }
   }
 
@@ -539,18 +596,25 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
   // citation, no normativeRef. Adjudication may only ever decide what the engine left open.
   for (const it of adj.items) {
     if (!open.has(it.criteriaId)) {
-      issues.push(`criterion ${it.criteriaId}: not open for adjudication — the engine already decided it, or it is not part of ${adj.standard}`);
+      blame(it.criteriaId, `criterion ${it.criteriaId}: not open for adjudication — the engine already decided it, or it is not part of ${adj.standard}`);
     }
   }
 
-  // Per-item fail-closed validation.
-  const groundInputs: { file: string; line: number; selector?: string; snippet?: string }[] = [];
+  // Per-item fail-closed validation. Grounding inputs are collected PER ITEM (not into one
+  // flat list) for the same reason as `blame`: a failed citation has to condemn its own
+  // criterion and no other.
+  const groundInputs = new Map<string, { file: string; line: number; selector?: string; snippet?: string }[]>();
+  const toGround = (criteriaId: string, g: { file: string; line: number; selector?: string; snippet?: string }) => {
+    const list = groundInputs.get(criteriaId);
+    if (list) list.push(g);
+    else groundInputs.set(criteriaId, [g]);
+  };
   for (const it of adj.items) {
     const v = it.verdict;
     if (v === null) {
-      issues.push(`criterion ${it.criteriaId}: unadjudicated (verdict is null)`);
+      blame(it.criteriaId, `criterion ${it.criteriaId}: unadjudicated (verdict is null)`);
     } else if (v === "C" || v === "NA") {
-      if (!it.justification || !it.justification.trim()) issues.push(`criterion ${it.criteriaId}: a ${v} verdict requires a justification`);
+      if (!it.justification || !it.justification.trim()) blame(it.criteriaId, `criterion ${it.criteriaId}: a ${v} verdict requires a justification`);
       // A clearing verdict is gated exactly like an accusing one. Before this, the only
       // check was "the justification is a non-empty string", so `"x"` cleared a criterion —
       // and a model answering C to everything published a conformance nobody had assessed.
@@ -561,12 +625,14 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
         // concerned"); `C` is not — it must stay `manual` and be ruled on against the
         // criterion's own tests, from a rendered capture or by hand.
         if (v === "C") {
-          issues.push(
+          blame(
+            it.criteriaId,
             `criterion ${it.criteriaId}: a C verdict needs evidence to cite, and none was harvested for this criterion — record "manual" (reason "undecidable"), or "NA" if nothing in scope is concerned`,
           );
         }
       } else if (cites.length === 0) {
-        issues.push(
+        blame(
+          it.criteriaId,
           `criterion ${it.criteriaId}: a ${v} verdict must cite at least one of the ${it.evidence.length} evidence item(s) it was shown (citations: [{file, line, …}])`,
         );
       } else {
@@ -576,50 +642,75 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
         const anchors = new Set(it.evidence.map((e) => `${e.file}:${e.line}`));
         for (const c of cites) {
           if (!anchors.has(`${c.file}:${c.line}`)) {
-            issues.push(`criterion ${it.criteriaId}: citation ${c.file}:${c.line} is not among this criterion's harvested evidence (fabricated?)`);
+            blame(it.criteriaId, `criterion ${it.criteriaId}: citation ${c.file}:${c.line} is not among this criterion's harvested evidence (fabricated?)`);
           }
-          groundInputs.push({ file: c.file, line: c.line, selector: c.selector, snippet: c.snippet });
+          toGround(it.criteriaId, { file: c.file, line: c.line, selector: c.selector, snippet: c.snippet });
         }
       }
     } else if (v === "NC") {
-      if (!it.findings || it.findings.length === 0) issues.push(`criterion ${it.criteriaId}: an NC verdict requires at least one groundable finding`);
+      if (!it.findings || it.findings.length === 0) blame(it.criteriaId, `criterion ${it.criteriaId}: an NC verdict requires at least one groundable finding`);
       for (const f of it.findings ?? []) {
         // FAIL-CLOSED: every NC finding must cite a precise, resolvable test of the active
         // standard. A good practice with no normative test is a recommendation, not an NC.
         if (!f.normativeRef || !f.normativeRef.trim()) {
-          issues.push(`criterion ${it.criteriaId}: an NC finding requires a normativeRef citing the failed test of the active standard`);
+          blame(it.criteriaId, `criterion ${it.criteriaId}: an NC finding requires a normativeRef citing the failed test of the active standard`);
         } else if (!normativeRefResolves(f.normativeRef, adj.standard, isCore(adj.standard) ? undefined : it.criteriaId)) {
-          issues.push(
+          blame(
+            it.criteriaId,
             isCore(adj.standard)
               ? `criterion ${it.criteriaId}: normativeRef "${f.normativeRef}" does not resolve to a test of ${adj.standard} (fabricated?)`
               : `criterion ${it.criteriaId}: normativeRef "${f.normativeRef}" is not a test of ${adj.standard} ${it.criteriaId} — cite one of its own tests (e.g. "${it.criteriaId}.1"); a WCAG id looks alike but denotes an unrelated test`,
           );
         }
-        groundInputs.push({ file: f.file, line: f.line, selector: f.selector, snippet: f.snippet });
+        toGround(it.criteriaId, { file: f.file, line: f.line, selector: f.selector, snippet: f.snippet });
       }
     } else if (v === "manual") {
       if (!it.reason || !MANUAL_REASONS.has(it.reason))
-        issues.push(`criterion ${it.criteriaId}: a manual verdict requires reason ∈ {${MANUAL_REASON_VALUES.join(", ")}}`);
+        blame(it.criteriaId, `criterion ${it.criteriaId}: a manual verdict requires reason ∈ {${MANUAL_REASON_VALUES.join(", ")}}`);
     } else {
       // Name the vocabulary in the rejection. The caller is usually a model that has just
       // spent a whole worklist filling this file; "unknown verdict" alone told it nothing
       // about how to be right on the retry.
-      issues.push(`criterion ${it.criteriaId}: unknown verdict "${String(v)}" — expected one of ${VERDICTS.join(" | ")}`);
+      blame(it.criteriaId, `criterion ${it.criteriaId}: unknown verdict "${String(v)}" — expected one of ${VERDICTS.join(" | ")}`);
     }
     // Recommendations are independent of the verdict (a C criterion may still carry a good
     // practice) and are grounded exactly like an NC finding — no normativeRef required, as
     // a recommendation has no normative test by definition.
-    for (const rec of it.recommendations ?? []) groundInputs.push({ file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
+    for (const rec of it.recommendations ?? []) toGround(it.criteriaId, { file: rec.file, line: rec.line, selector: rec.selector, snippet: rec.snippet });
   }
 
   // Content-level grounding of every agent NC finding, every C/NA citation, and every
-  // recommendation — the same check, whichever direction the verdict points.
-  const grounding = groundItems(groundInputs, { cwd: opts.cwd });
-  for (const gi of grounding.issues) issues.push(gi);
+  // recommendation — the same check, whichever direction the verdict points. Walked per
+  // criterion so a failure is attributable; the aggregate summary is identical to what the
+  // flat `groundItems` produced.
+  const grounding: GroundingSummary = { grounded: 0, moved: 0, failed: 0, issues: [] };
+  for (const [criteriaId, inputs] of groundInputs) {
+    for (const input of inputs) {
+      const r = groundFinding(input, { cwd: opts.cwd });
+      if (r.ok) {
+        grounding.grounded++;
+        if (r.moved) grounding.moved++;
+      } else {
+        grounding.failed++;
+        if (r.issue) {
+          grounding.issues.push(r.issue);
+          blame(criteriaId, r.issue);
+        }
+      }
+    }
+  }
 
-  if (issues.length) {
-    return { ok: false, audit, issues, applied: 0, stillManual: 0, grounding };
+  // STRICT: the historical file-level fold. One refusal, nothing lands.
+  if (opts.strict && issues.length) {
+    return { ok: false, audit, issues, applied: 0, stillManual: 0, rejected: 0, rejectedCriteria: [], grounding };
   }
+  // PARTIAL: a refused criterion is dropped, the rest folds. `rejectedCriteria` keeps file
+  // order and de-duplicates, since one criterion can raise several issues. It counts only the
+  // criteria the gate REFUSED — an uncovered one the caller already declared is not a refusal.
+  const rejectedCriteria = adj.items.map((it) => it.criteriaId).filter((id) => itemIssues.has(id));
+  for (const id of itemIssues.keys()) if (!rejectedCriteria.includes(id)) rejectedCriteria.push(id);
+  const rejectedSet = notFolded;
+  const rejectedWhy = (id: string) => expected[id] ?? residualRejectedReason(itemIssues.get(id)?.[0] ?? "refused by the gate");
 
   // Apply: clone the audit, update the decided criteria + append agent findings.
   const next: AuditResult = structuredClone(audit);
@@ -636,6 +727,20 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
   if (packMode) {
     const decided: PackCriterionAdjudication[] = [];
     for (const it of adj.items) {
+      // A refused verdict does not land. It is recorded as still-`manual` carrying the
+      // refusal, so the page grid and the report say WHY this criterion is still to assess
+      // instead of leaving a blank cell.
+      if (rejectedSet.has(it.criteriaId)) {
+        if (!open.has(it.criteriaId)) continue; // surplus item: not ours to record at all
+        decided.push({
+          id: it.criteriaId,
+          status: "manual",
+          reason: "undecidable",
+          justification: rejectedWhy(it.criteriaId),
+          findings: [],
+        });
+        continue;
+      }
       if (it.verdict === "manual") {
         stillManual++;
         decided.push({
@@ -660,17 +765,25 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
         decidedBy: "agent",
       });
     }
+    // An OPEN criterion the file never mentioned — a coverage gap, or one the caller declared
+    // uncovered — also has to say why it is still to assess; the loop above only walks the
+    // items that exist.
+    for (const id of notFolded) {
+      if (byId.has(id) || !open.has(id)) continue;
+      decided.push({ id, status: "manual", reason: "undecidable", justification: rejectedWhy(id), findings: [] });
+    }
     next.packAdjudication = { standard: adj.standard, criteria: decided };
     // The agent's findings still join the flat list so grounding, `check` and the reports can
     // resolve them — but they never touch a WCAG criterion's status.
     next.findings = [...next.findings, ...newFindings];
-    next.adjudicated = { date: adj.auditDate, applied, stillManual };
-    return { ok: true, audit: next, issues, applied, stillManual, grounding };
+    next.adjudicated = { date: adj.auditDate, applied, stillManual, ...(rejectedCriteria.length ? { rejected: rejectedCriteria.length } : {}) };
+    return { ok: issues.length === 0, audit: next, issues, applied, stillManual, rejected: rejectedCriteria.length, rejectedCriteria, grounding };
   }
 
   for (const it of adj.items) {
     const c = critById.get(it.criteriaId);
     if (!c) continue; // an item for a non-residual criterion — ignore (coverage already gated)
+    if (rejectedSet.has(it.criteriaId)) continue; // refused: the criterion keeps its `manual` status
     if (it.verdict === "manual") {
       c.status = "manual";
       c.decidedBy = "agent";
@@ -696,7 +809,7 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
   // gets its recommendations, and an NC item's reset `c.findings` keeps them appended last.
   for (const it of adj.items) {
     const c = critById.get(it.criteriaId);
-    if (!c) continue;
+    if (!c || rejectedSet.has(it.criteriaId)) continue;
     for (const rec of it.recommendations ?? []) {
       const f = agentFinding(it.criteriaId, rec, true);
       c.findings.push(f);
@@ -705,11 +818,16 @@ export function applyAdjudication(audit: AuditResult, adj: AdjudicationFile, opt
   }
 
   next.findings = [...next.findings, ...newFindings];
-  // Residual set now holds only the still-manual criteria.
-  next.residualRisks = next.residualRisks.filter((r) => byId.get(r.criteriaId)?.verdict === "manual");
+  // Residual set now holds every criterion still to assess: the ones ruled `manual` by the
+  // adjudication, AND the ones whose verdict the gate refused. A refused criterion keeps its
+  // place in the residual set with the refusal as its reason — dropping it would report it as
+  // decided, and blanking the reason is exactly the empty cell this release is removing.
+  next.residualRisks = next.residualRisks
+    .filter((r) => byId.get(r.criteriaId)?.verdict === "manual" || rejectedSet.has(r.criteriaId))
+    .map((r) => (rejectedSet.has(r.criteriaId) ? { ...r, reason: rejectedWhy(r.criteriaId) } : r));
   recomputeTallies(next);
-  next.adjudicated = { date: adj.auditDate, applied, stillManual };
-  return { ok: true, audit: next, issues: [], applied, stillManual, grounding };
+  next.adjudicated = { date: adj.auditDate, applied, stillManual, ...(rejectedCriteria.length ? { rejected: rejectedCriteria.length } : {}) };
+  return { ok: issues.length === 0, audit: next, issues, applied, stillManual, rejected: rejectedCriteria.length, rejectedCriteria, grounding };
 }
 
 function agentFinding(criteriaId: string, f: AgentFinding, advisory = false): Finding {
@@ -750,6 +868,10 @@ function recomputeTallies(a: AuditResult): void {
 
 const residualScanReason = () => "Rendering criterion — decide on the rendered DOM (`scan`).";
 const residualUndecidableReason = () => "Left as an explicit residual risk (not decidable from the available evidence).";
+/** Why a criterion is still to assess after a PARTIAL fold: its verdict was refused. Carries
+ *  the first refusal verbatim, so the reader (and the next adjudication pass) sees the actual
+ *  contract violation rather than a bare « to assess ». */
+const residualRejectedReason = (why: string) => `Adjudication refused by the gate — ${why.replace(/^criterion \S+: /, "")}. Re-adjudicate this criterion.`;
 
 // ---- worklist file rendering ----
 const T = {
@@ -909,11 +1031,18 @@ function plainTest(s: string): string {
   return s.replace(/\[([^\]]+)\]\(#[^)]*\)/g, "$1");
 }
 
-export function formatAdjudication(items: AdjudicationItem[], lang: Lang = "en", standard: StandardId = CORE): string {
+/** `preamble: false` renders the criterion sections ALONE.
+ *
+ *  The preamble names the file to write into and the command to fold with, which is right for
+ *  the one combined document and wrong for a per-criterion brief: repeated 96 times it is 96
+ *  copies of instructions that contradict a CI adjudicator's toolset (it has no shell) and
+ *  point at the wrong file. The briefs carry evidence and protocol; the instructions live once,
+ *  in the worklist's `contract` field and the dispatch contract. */
+export function formatAdjudication(items: AdjudicationItem[], lang: Lang = "en", standard: StandardId = CORE, opts: { preamble?: boolean } = {}): string {
   const s = T[lang];
   const pack = isCore(standard) ? undefined : loadPack(standard);
-  const out: string[] = [s.title, "", s.intro, "", ...s.verdicts, "", s.rule, "", s.then, ""];
-  if (pack) out.push(`> ${s.packIntro(pack.name)}`, "");
+  const out: string[] = opts.preamble === false ? [] : [s.title, "", s.intro, "", ...s.verdicts, "", s.rule, "", s.then, ""];
+  if (pack && opts.preamble !== false) out.push(`> ${s.packIntro(pack.name)}`, "");
   for (const it of items) {
     out.push(`## ${pack ? `${pack.name} ` : ""}${it.criteriaId}${it.title ? ` — ${it.title}` : ""}  _(${it.automatability})_`);
     out.push("", `> ${s.evidence} (${it.evidence.length}${it.evidenceTruncated ? ` / ${it.evidenceTruncated.total}` : ""}):`, "");
@@ -970,6 +1099,10 @@ export function formatAdjudication(items: AdjudicationItem[], lang: Lang = "en",
 export interface WriteAdjudicationResult {
   todoPath: string;
   mdPath: string;
+  /** The verdicts-only file, for an adjudicator that cannot edit half a megabyte of JSON. */
+  verdictsPath: string;
+  /** One small Markdown brief per criterion, for one that cannot read it either. */
+  itemsDir: string;
   count: number;
 }
 
@@ -992,5 +1125,60 @@ export function writeAdjudication(
   };
   writeFileSync(todoPath, JSON.stringify(file, null, 2) + "\n");
   writeFileSync(mdPath, formatAdjudication(items, opts.lang ?? "en", opts.standard));
-  return { todoPath, mdPath, count: items.length };
+
+  // THE SPLIT SURFACE, for an adjudicator that cannot shell out.
+  //
+  // The two documents above are sized for a session with a shell: 96 RGAA criteria carrying
+  // 30 evidence anchors each come to ~540 KB of JSON and ~470 KB of Markdown, and the runbook
+  // tells the reader to edit the JSON in place and then run the engine to fold it. That is
+  // fine locally. In CI the adjudicator is handed Read/Grep/Glob/Edit/Write and nothing else,
+  // and against those tools the same instructions are impossible: reading either document
+  // swamps the context, editing 96 verdicts inside half a megabyte of JSON is 96 exact-match
+  // edits, and every prescribed `node …` command is denied. Measured on a real run: 17
+  // permission denials, 75 of 424 turns used, and a todo file that came back untouched — so
+  // the fail-closed fold correctly discarded all 96 and every criterion stayed "to assess".
+  //
+  // So the same worklist is also written as one small file to WRITE and one small file per
+  // criterion to READ. Additive on purpose: the two documents above keep their exact shape and
+  // every existing caller, gate and test is untouched.
+  const verdictsPath = join(outDir, "ADJUDICATE.verdicts.json");
+  writeFileSync(verdictsPath, JSON.stringify({ ...file, items: slimAdjudicationItems(items) }, null, 2) + "\n");
+  const itemsDir = join(outDir, "adjudicate");
+  mkdirSync(itemsDir, { recursive: true });
+  for (const it of items) {
+    writeFileSync(join(itemsDir, `${it.criteriaId}.md`), formatAdjudication([it], opts.lang ?? "en", opts.standard, { preamble: false }));
+  }
+  return { todoPath, mdPath, verdictsPath, itemsDir, count: items.length };
+}
+
+/** The worklist with the evidence stripped: what an adjudicator has to WRITE, without the
+ *  bulk it only has to READ. Every field the fold requires — verdict, justification, reason,
+ *  findings, citations, recommendations — is kept, so a filled slim file carries a complete
+ *  decision. The evidence comes back at fold time via `hydrateAdjudication`. */
+export function slimAdjudicationItems(items: AdjudicationItem[]): AdjudicationItem[] {
+  return items.map((it) => {
+    const { evidence: _evidence, evidenceTruncated: _truncated, ...rest } = it;
+    return { ...rest, evidence: [] } as AdjudicationItem;
+  });
+}
+
+/** Put the evidence back on a slim adjudication, re-derived from the audit it was built from.
+ *
+ *  Safe because the worklist is a pure function of the audit: same audit, same harvesters, same
+ *  anchors. This is what lets `verify --apply` accept a verdicts-only file WITHOUT relaxing a
+ *  single check — the citation gate still matches each cited anchor against this criterion's
+ *  own harvested evidence, exactly as it does for an inline worklist.
+ *
+ *  An item the re-derivation does not know is left alone: it is a surplus verdict, and the
+ *  coverage check in `applyAdjudication` is what must reject it. */
+export function hydrateAdjudication(adj: AdjudicationFile, audit: AuditResult, opts: { cwd?: string } = {}): void {
+  const needs = adj.items.filter((it) => !it.evidence || it.evidence.length === 0);
+  if (!needs.length) return;
+  const derived = new Map(buildAdjudicationWorklist(audit, { ...opts, standard: adj.standard }).map((it) => [it.criteriaId, it]));
+  for (const it of needs) {
+    const full = derived.get(it.criteriaId);
+    if (!full) continue;
+    it.evidence = full.evidence;
+    if (full.evidenceTruncated) it.evidenceTruncated = full.evidenceTruncated;
+  }
 }