ultra11y 5.3.4 → 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 = {

package/src/audit.ts

@@ -12,6 +12,7 @@ import { attachSignals, isSnapshotDom, snapshotPageId } from "./snapshot.js";
 import { attr, elementsByTag, type Doc, type CaptureProvenance } from "./parse/html.js";
 import { CAPTURES_DIR, computeCaptureCoverage, enrichCaptureOrigins, isUnderDir, readCaptureDir, capturesForSources } from "./capture.js";
 import { isFullDocument } from "./rules/rule.js";
+import { renderedTestedScs } from "./rules/rendered.js";
 import { runRules } from "./rules/registry.js";
 import { runCrossRules } from "./rules/cross-registry.js";
 import { listPacks } from "./standards/registry.js";
@@ -64,12 +65,141 @@ const APPLICABLE: Record<string, (d: Doc) => boolean> = {
   "3.1.1": (d) => isFullDocument(d), // Language of Page — html-lang-missing / lang-invalid
 };
 
-function residualReason(automatability: string): string {
+// ---- SUBJECT MATTER: what makes a NON-static criterion applicable at all -----------------
+//
+// A judgment or rendering criterion used to have exactly two outcomes: `NC` when a rule fired,
+// `manual` otherwise. So a repository containing no audio and no video still reported all five
+// time-based-media criteria as « to assess » — and under RGAA, whose theme 4 projects from
+// them, that is 13 criteria a reader has to work through to discover there was never anything
+// to look at. Measured on a real 300-file audit: 96 of 106 criteria « to assess », whole themes
+// among them applicable to nothing in scope.
+//
+// « Not applicable » is a real, normative verdict, and the engine can prove it for a criterion
+// whose SUBJECT MATTER is a thing you can look for in the source. So: no media element in the
+// whole scope ⇒ the media criteria are NA, with a justification naming the observation.
+//
+// Three rules keep this honest, because a wrong NA is far worse than an honest « to assess » —
+// it is a non-conformity hidden inside a report someone signs:
+//
+//   1. OVER-INCLUSION IS THE SAFE DIRECTION. A predicate answers "could this criterion
+//      possibly apply here?", so it must say YES on anything ambiguous. `<object>`/`<embed>`/
+//      `<iframe>` are usually not media, and they are all listed anyway: their presence merely
+//      keeps a criterion open, which costs nothing but a line in the worklist.
+//   2. APPLICABILITY IS OR-FOLDED ACROSS THE WHOLE SCOPE (see `foldDoc`). One document with a
+//      `<video>` keeps the media criteria open for the entire audit. NA means "nothing,
+//      anywhere in what was audited" — never "nothing in this file".
+//   3. THE VERDICT IS SCOPE-BOUND AND SAYS SO. The justification states what was searched and
+//      not found, so it is falsifiable by a reader. A scope that cannot see rendered output
+//      (an opaque component library) is already flagged on the audit itself, and `check`'s
+//      unjustified-NA gate still applies.
+const SUBJECT_MATTER: Record<string, (d: Doc) => boolean> = {
+  // ---- Time-based media (WCAG 1.2.x → RGAA theme 4) ----
+  // Captions, transcripts, audio description and sign language all presuppose a media element.
+  // `track` counts on its own: a stray <track> means media is being assembled somewhere.
+  "1.2.1": hasMedia,
+  "1.2.2": hasMedia,
+  "1.2.3": hasMedia,
+  "1.2.4": hasMedia,
+  "1.2.5": hasMedia,
+  // ---- Motion actuation (WCAG 2.5.4) ----
+  // Applicable only where device motion drives the interface, which is a source-visible API.
+  "2.5.4": hasMotionApi,
+  // ---- Forms (WCAG 3.3.x) ----
+  // Error identification, labels and instructions, error suggestion, error prevention,
+  // redundant entry and accessible authentication all presuppose user input. 3.3.4 and 3.3.8
+  // are narrower still (legal/financial transactions, authentication), so "any form control"
+  // is the deliberately over-inclusive predicate for them.
+  "3.3.1": hasFormControl,
+  "3.3.2": hasFormControl,
+  "3.3.3": hasFormControl,
+  "3.3.4": hasFormControl,
+  "3.3.7": hasFormControl,
+  "3.3.8": hasFormControl,
+  // Identify Input Purpose — about autocomplete on fields collecting user data.
+  "1.3.5": hasFormControl,
+};
+
+/** Media, and everything that could be carrying media. Over-inclusive on purpose (rule 1). */
+function hasMedia(d: Doc): boolean {
+  return has(d, "audio", "video", "track", "source", "object", "embed", "iframe", "marquee", "canvas");
+}
+
+/** Device-motion input: the only thing WCAG 2.5.4 is about. */
+function hasMotionApi(d: Doc): boolean {
+  return /\b(?:devicemotion|deviceorientation|DeviceMotionEvent|DeviceOrientationEvent|Accelerometer|Gyroscope|requestPermission)\b/i.test(d.source);
+}
+
+/** Any control that takes user input, native or delegated. Over-inclusive on purpose. */
+function hasFormControl(d: Doc): boolean {
+  if (has(d, "input", "select", "textarea", "form", "fieldset", "output", "datalist")) return true;
+  // A custom widget standing in for a field, and a submit control that implies one.
+  return d.elements.some((e) => {
+    const role = (e.attribs.role ?? "").toLowerCase();
+    if (role && /^(textbox|combobox|listbox|checkbox|radio|radiogroup|slider|spinbutton|searchbox|switch|form)$/.test(role)) return true;
+    return e.attribs.contenteditable !== undefined;
+  });
+}
+
+// ---- WHY a criterion is still to assess, and WHERE its evidence would come from -----------
+//
+// One generic sentence per tier used to answer for all 52 undecided criteria: "needs a rendered
+// DOM (contrast, focus visibility, zoom/reflow, target size)" was printed against 1.4.5 (images
+// of text) as readily as against 1.4.3 (contrast), naming four measurements of which at most
+// one was the criterion's. A reader could not tell what was missing, and neither could the next
+// run — so « to assess » read as a shrug rather than as an instruction.
+//
+// Each entry names the measurement that decides the criterion and the command that produces it.
+// Absent ⇒ the tier default below, which is still true, just unspecific.
+const RESIDUAL_TRAIL: Record<string, string> = {
+  // Rendering criteria the SNAPSHOT tier decides offline, from computed styles + stylesheets.
+  "1.3.4":
+    "Decided on a page's own stylesheets (an orientation media query that rotates the document) — record a snapshot with `scan --sample` (or an E2E capture), then re-audit.",
+  "1.4.1": "Decided on computed colours (a link distinguished by colour alone) — record a snapshot with `scan --sample`, then re-audit.",
+  "1.4.3":
+    "Decided on computed text/background colours, with a screenshot fallback where the backdrop is an image — record a snapshot with `scan --sample`, then re-audit.",
+  "1.4.11": "Decided on computed colours of UI components and graphics — record a snapshot with `scan --sample`, then re-audit.",
+  "2.4.7":
+    "Decided on the page's own stylesheets (a `:focus` rule that removes the indicator without restoring one), or by the live focus probe — record a snapshot with `scan --sample`, then re-audit.",
+  // Rendering criteria that need a LIVE browser: they are measured by acting on the page.
+  "1.4.4": "Needs a live browser: the page is re-measured at 200% zoom — `scan <url> --runtime local --merge <audit.json>`.",
+  "1.4.10": "Needs a live browser: the page is re-measured in a 320px viewport (reflow) — `scan <url> --merge <audit.json>`.",
+  "1.4.12": "Needs a live browser: text spacing overrides are injected and the layout re-measured — `scan <url> --runtime local --merge <audit.json>`.",
+  "1.4.13":
+    "Needs a live browser: hover/focus-triggered content is opened and probed for dismiss/hover/persist — `scan <url> --runtime local --merge <audit.json>`.",
+  // axe's own `target-size` rule can FAIL this on a live page, but no tier certifies it, so a
+  // clean scan leaves it open rather than conforming. Say both halves.
+  "2.5.8":
+    "A live scan can fail this (axe `target-size`) but never certify it — `scan <url> --runtime local --merge <audit.json>`, then adjudicate what is left.",
+  "4.1.3":
+    "Needs a live browser WITH interaction: a status message is triggered and the live region observed — `scan <url> --runtime local --merge <audit.json>` (interactions are on by default).",
+  // Rendering criteria no automated tier measures — say so, rather than pointing at `scan` and
+  // letting the reader discover it changes nothing.
+  "1.4.5":
+    "No automated tier decides this: whether text is presented as an image is a reading of each image's content. Adjudicate it (`verify --manual`) against the images the audit lists.",
+  "2.1.2": "No automated tier decides this: escaping a keyboard trap has to be attempted by hand, on each focusable region.",
+  "2.3.1": "No automated tier decides this: flashing has to be observed over time on the rendered page.",
+  "2.4.11": "No automated tier decides this: whether a focused element stays unobscured depends on the sticky headers and overlays in play on each screen.",
+};
+
+function residualReason(automatability: string, sc?: string): string {
+  const trail = sc ? RESIDUAL_TRAIL[sc] : undefined;
+  if (trail) return trail;
   return automatability === "needs-rendering"
     ? "Needs a rendered DOM (contrast, focus visibility, zoom/reflow, target size) — decide via `scan`."
     : "Judgement criterion — adjudicated by the agent from source/context (`verify --manual`, gated).";
 }
 
+/** Why a non-static criterion is NA — the observation, so a reader can falsify it. Scope-bound
+ *  by construction (`n` files audited), which is exactly the claim being made. */
+function subjectMatterReason(sc: string, files: number): string {
+  const scope = `nothing in the ${files} file(s) audited is concerned`;
+  if (sc.startsWith("1.2."))
+    return `No time-based media in scope: ${scope} — no <audio>, <video>, <track>, <object>, <embed>, <iframe> or <canvas> element was found.`;
+  if (sc === "2.5.4") return `No motion actuation in scope: ${scope} — no device-motion or device-orientation API is used.`;
+  if (sc === "1.3.5" || sc.startsWith("3.3.")) return `No user input in scope: ${scope} — no form control (native, ARIA or contenteditable) was found.`;
+  return `No element in scope is concerned by this success criterion (${scope}).`;
+}
+
 // Streaming accumulator: parse → run rules → fold → DISCARD each Doc, so the
 // engine never holds a whole repo in memory. The only cross-document state is
 // (a) the flat findings list (bounded by finding count, not source size) and
@@ -87,6 +217,10 @@ interface Accum {
   sfcExts: Set<string>; // which SFC extensions were seen
   captures: { file: string; provenance: CaptureProvenance }[]; // rendered capture files audited
   langCounts: Map<string, number>; // <html lang> primary subtags seen, for repo-language detection
+  // Success criteria the RENDERED tier measured, from the snapshots ingested in this run
+  // (src/rules/rendered.ts renderedTestedScs). Stamped onto scope.scan.testedScs so the
+  // partial-audit banner names what is genuinely missing instead of every rendering criterion.
+  renderedScs: Set<string>;
 }
 
 // Precompute the static success criteria + their applicability predicates once.
@@ -94,6 +228,13 @@ const STATIC_PREDS: ReadonlyArray<readonly [string, (d: Doc) => boolean]> = allS
   .filter((c) => c.automatability === "static")
   .map((c) => [c.sc, APPLICABLE[c.sc] ?? isFullDocument] as const);
 
+// The same fold, for the non-static criteria whose subject matter is source-visible. Kept as a
+// separate list so the `static` contract above ("clean ⇒ C") is untouched: a criterion here can
+// only ever gain `NA`, never `C`.
+const SUBJECT_PREDS: ReadonlyArray<readonly [string, (d: Doc) => boolean]> = allSC()
+  .filter((c) => c.automatability !== "static" && SUBJECT_MATTER[c.sc] !== undefined)
+  .map((c) => [c.sc, SUBJECT_MATTER[c.sc]!] as const);
+
 function newAccum(): Accum {
   return {
     byCriterion: new Map(),
@@ -107,6 +248,7 @@ function newAccum(): Accum {
     sfcExts: new Set(),
     captures: [],
     langCounts: new Map(),
+    renderedScs: new Set(),
   };
 }
 
@@ -166,6 +308,14 @@ export function foldDoc(acc: Accum, doc: Doc, graph?: DepGraph): void {
   for (const [id, pred] of STATIC_PREDS) {
     if (!acc.applicable.get(id) && pred(doc)) acc.applicable.set(id, true);
   }
+  // OR-folded across the whole scope: one document carrying the subject matter keeps the
+  // criterion open for the entire audit (see SUBJECT_MATTER, rule 2).
+  for (const [id, pred] of SUBJECT_PREDS) {
+    if (!acc.applicable.get(id) && pred(doc)) acc.applicable.set(id, true);
+  }
+  // A page snapshot just let the rendered tier MEASURE some criteria, offline and with no
+  // browser. Record which, so the report stops claiming they were never tested.
+  if (doc.signals) for (const sc of renderedTestedScs(doc.signals)) acc.renderedScs.add(sc);
   if (doc.opaqueComponents?.length) {
     for (const lib of doc.opaqueComponents) acc.opaqueLibs.add(lib);
     acc.opaqueFiles++;
@@ -215,11 +365,17 @@ function finalize(acc: Accum, inputs: string[], extra: FinalizeExtra = {}): Audi
     } else if (normativeFs.length > 0) {
       // a rule on a needs-rendering / judgment SC raised a DEFINITE failure
       status = "NC";
+    } else if (SUBJECT_MATTER[c.sc] !== undefined && !(acc.applicable.get(c.sc) ?? false)) {
+      // The criterion's SUBJECT MATTER is absent from the entire scope, so there is nothing to
+      // judge and nothing to render — « not applicable » is the accurate verdict, not « to
+      // assess ». Never a `C`: this says the criterion does not apply, never that it is met.
+      status = "NA";
+      justification = subjectMatterReason(c.sc, acc.fileCount);
     } else {
       // engine can't decide — leave it for the agent to adjudicate (`verify --manual`,
       // gated) or the `scan` tier (rendering criteria); never a silent conforming.
       status = "manual";
-      residualRisks.push({ criteriaId: c.sc, reason: residualReason(c.automatability), automatability: c.automatability });
+      residualRisks.push({ criteriaId: c.sc, reason: residualReason(c.automatability, c.sc), automatability: c.automatability });
     }
     criteria.push({ id: c.sc, guideline: c.guideline, status, findings: fs, ...(justification ? { justification } : {}) });
   }
@@ -262,6 +418,11 @@ function finalize(acc: Accum, inputs: string[], extra: FinalizeExtra = {}): Audi
           }
         : {}),
       ...(acc.langCounts.size ? { langs: [...acc.langCounts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])).map(([lang]) => lang) } : {}),
+      // Coverage the RENDERED tier earned from the snapshots this run ingested. Same field the
+      // live-browser merge stamps (`mergeDynamic`), because it is the same claim: these criteria
+      // were measured. Omitted when no snapshot carried usable signals, so a source-only audit
+      // is byte-for-byte unchanged and still says the rendering criteria are untested.
+      ...(acc.renderedScs.size ? { scan: { testedScs: [...acc.renderedScs].sort() } } : {}),
       // The pages this run genuinely read. Written UNCONDITIONALLY — `[]` is the whole point,
       // because "this audit read no page" is exactly the claim a source-only run needs to make,
       // and an omit-when-empty field would say nothing precisely then. See scope.pagesAudited.