ultra11y 5.8.0 → 5.9.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "ultra11y",
       "source": "./",
       "description": "Automatic accessibility review of the code under change before every commit, push and pull request, plus full WCAG 2.2 AA / RGAA audits and conformance deliverables on demand.",
-      "version": "5.8.0",
+      "version": "5.9.0",
       "author": { "name": "maxgfr" },
       "homepage": "https://github.com/maxgfr/ultra11y",
       "repository": "https://github.com/maxgfr/ultra11y",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "author": { "name": "maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "author": { "name": "maxgfr", "url": "https://github.com/maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.opencode/plugins/ultra11y.js

@@ -27,7 +27,7 @@ import { fileURLToPath } from "node:url";
 // Ownership marker: `ultra11y install --opencode` refuses to overwrite a plugin file that
 // does not carry it, so a user's own ultra11y.js is never clobbered.
 const ULTRA11Y_OPENCODE_PLUGIN = "ULTRA11Y_OPENCODE_PLUGIN";
-const ULTRA11Y_PLUGIN_VERSION = "5.8.0";
+const ULTRA11Y_PLUGIN_VERSION = "5.9.0";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "5.8.0",
+  "version": "5.9.0",
   "description": "Audit HTML/CSS/JSX against WCAG 2.2 AA and produce a dated compliance report, or author/review accessible markup (native-HTML-first). A skills.sh agent skill: an install-free static engine (bundled, no npm install) plus the agent's judgment, with check/verify gates against hallucinated non-conformities, and pluggable in-repo standards packs (RGAA France first; Section 508 & EN 301 549 next).",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.8.0";
+var VERSION = "5.9.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -57504,7 +57504,7 @@ function adjudicationContract() {
     verdicts: [...VERDICTS],
     manualReasons: [...MANUAL_REASON_VALUES],
     requires: {
-      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence); a criterion with no harvested evidence cannot be C at all",
+      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence, and about the same kind of element the harvest recorded there \u2014 copy the evidence's own `snippet` rather than retyping the element); a criterion with no harvested evidence cannot be C at all",
       NA: "a non-empty justification",
       NC: "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
       manual: `a reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`
@@ -57640,6 +57640,61 @@ function auditFiles(audit2, cwd) {
     return /* @__PURE__ */ new Set();
   }
 }
+function tagOf2(x) {
+  const fromSnippet = /<\s*([a-zA-Z][\w-]*)/.exec(x.snippet ?? "");
+  if (fromSnippet) return fromSnippet[1].toLowerCase();
+  const fromSelector = /^\s*([a-zA-Z][\w-]*)/.exec(x.selector ?? "");
+  return fromSelector ? fromSelector[1].toLowerCase() : void 0;
+}
+function contentTokens(markup) {
+  const out2 = /* @__PURE__ */ new Set();
+  const withoutTags = markup.replace(/<[^>]*>/g, " ");
+  for (const m of markup.matchAll(/=\s*"([^"]*)"|=\s*'([^']*)'/g)) {
+    for (const w of (m[1] ?? m[2] ?? "").split(/[\s/_-]+/)) if (w.length >= 3) out2.add(w.toLowerCase());
+  }
+  for (const w of withoutTags.split(/[\s/_-]+/)) if (w.length >= 3) out2.add(w.toLowerCase());
+  return out2;
+}
+function recognisablySame(cite, anchor) {
+  const ta = tagOf2(cite);
+  const tb = tagOf2(anchor);
+  if (ta !== void 0 && tb !== void 0 && ta !== tb) return false;
+  if (!cite.snippet || !anchor.snippet) return true;
+  const want = contentTokens(anchor.snippet);
+  if (!want.size) return true;
+  const got = contentTokens(cite.snippet);
+  if (!got.size) return true;
+  for (const w of got) if (want.has(w)) return true;
+  return false;
+}
+function overlap(cite, anchor) {
+  if (!cite.snippet || !anchor.snippet) return 0;
+  const want = contentTokens(anchor.snippet);
+  if (!want.size) return 0;
+  let n = 0;
+  for (const w of contentTokens(cite.snippet)) if (want.has(w)) n++;
+  return n;
+}
+function anchorFor(evidence, c2, drift) {
+  const reps = evidence.filter((e) => e.file === c2.file && Math.abs(e.line - c2.line) <= drift);
+  const best = (cands) => {
+    let top;
+    let score = -1;
+    for (const e of cands) {
+      const n = overlap(c2, e);
+      if (n > score) {
+        score = n;
+        top = e;
+      }
+    }
+    return top;
+  };
+  const rep = best(reps);
+  if (rep) return { at: rep, representative: true };
+  const siblings = evidence.filter((e) => cites0(e.alsoAt ?? [], c2, drift));
+  const sib = best(siblings);
+  return sib ? { at: sib, representative: false } : void 0;
+}
 function cites0(anchors, c2, drift) {
   for (const a of anchors) {
     const at = a.lastIndexOf(":");
@@ -57775,7 +57830,20 @@ function applyAdjudication(audit2, adj, opts = {}) {
           if (!cites0(anchors, c2, citationDrift) && !scopeFiles().has(c2.file)) {
             blame(it.criteriaId, `criterion ${it.criteriaId}: citation ${c2.file}:${c2.line} is not among this criterion's harvested evidence (fabricated?)`);
           }
-          toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: c2.selector, snippet: c2.snippet });
+          const anchor = anchorFor(it.evidence, c2, citationDrift);
+          if (anchor && !recognisablySame(c2, anchor.at)) {
+            blame(
+              it.criteriaId,
+              `criterion ${it.criteriaId}: citation ${c2.file}:${c2.line} does not describe the element harvested there (${anchor.at.snippet ? `\`${anchor.at.snippet.slice(0, 80)}\`` : `<${tagOf2(anchor.at)}>`}) \u2014 cite the element you actually read, copying its \`snippet\` from the brief`
+            );
+          }
+          if (anchor?.representative) {
+            toGround(it.criteriaId, { file: anchor.at.file, line: anchor.at.line, selector: anchor.at.selector ?? c2.selector, snippet: anchor.at.snippet });
+          } else if (anchor) {
+            toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: anchor.at.selector ?? c2.selector });
+          } else {
+            toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: c2.selector, snippet: c2.snippet });
+          }
         }
       }
     } else if (v === "NC") {
@@ -57941,6 +58009,7 @@ function recomputeTallies(a) {
 var residualScanReason = () => "Rendering criterion \u2014 decide on the rendered DOM (`scan`).";
 var residualUndecidableReason = () => "Left as an explicit residual risk (not decidable from the available evidence).";
 var residualRejectedReason = (why) => `Adjudication refused by the gate \u2014 ${why.replace(/^criterion \S+: /, "")}. Re-adjudicate this criterion.`;
+var SNIPPET_SHOWN = 200;
 var T2 = {
   fr: {
     title: "# Adjudication des crit\xE8res \xE0 \xE9valuer (ultra11y)",
@@ -57959,6 +58028,7 @@ var T2 = {
     pagesWord: "page(s)",
     on: "sur",
     alsoAt: "aussi en",
+    snippetLabel: "`snippet` \xE0 copier dans la citation",
     incomplete: "LECTURE INCOMPL\xC8TE \u2014 un \xAB C \xBB sera refus\xE9 sur ce crit\xE8re",
     none: "(aucune \xE9vidence automatique \u2014 d\xE9cidez depuis la source, ou laissez `manual` avec une raison)",
     questions: "\xC0 v\xE9rifier manuellement",
@@ -57988,6 +58058,7 @@ var T2 = {
     pagesWord: "page(s)",
     on: "on",
     alsoAt: "also at",
+    snippetLabel: "`snippet` to copy into the citation",
     incomplete: "INCOMPLETE READING \u2014 a C will be refused on this criterion",
     none: "(no automatic evidence \u2014 decide from source, or leave `manual` with a reason)",
     questions: "To verify manually",
@@ -58048,6 +58119,10 @@ function formatAdjudication(items, lang = "en", standard = CORE2, opts = {}) {
           e.alsoAt?.length ? `${s.alsoAt} ${e.alsoAt.slice(0, shown).join(", ")}${e.alsoAt.length > shown ? "\u2026" : ""}` : ""
         ].filter(Boolean).join(" ");
         out2.push(`- \`${e.file}:${e.line}\` (\`${e.selector}\`)${extra ? ` [${extra}]` : ""}${e.note ? ` \u2014 ${e.note}` : ""}`);
+        if (e.snippet?.trim()) {
+          const snip = e.snippet.trim().replace(/\s+/g, " ").slice(0, SNIPPET_SHOWN);
+          out2.push(`  - ${s.snippetLabel} : \`${snip}${e.snippet.trim().length > SNIPPET_SHOWN ? "\u2026" : ""}\``);
+        }
       }
       out2.push("");
     }
@@ -61319,6 +61394,8 @@ var S = {
     pagesDetailNote: "Un bloc par page portant au moins une non-conformit\xE9, et seulement ses crit\xE8res **non conformes** \u2014 la grille compl\xE8te (tous les crit\xE8res de chaque page, avec leurs tests et leurs captures) vit dans l'artefact.",
     pagesClamped: (n) => `_Le d\xE9tail de ${n} page(s) a \xE9t\xE9 retir\xE9 de ce commentaire pour tenir dans la limite de GitHub \u2014 l'artefact les porte toutes._`,
     scoreboardClamped: (n) => `_${n} page(s) retir\xE9e(s) du tableau pour tenir dans la limite de GitHub \u2014 l'artefact les porte toutes._`,
+    pageDefects: "D\xE9fauts",
+    pageMoreDefects: (n) => `_\u2026 et ${n} autre(s) d\xE9faut(s) distinct(s) sur cette page \u2014 voir la fiche de page dans l'artefact._`,
     noCriterionForFindings: (n) => `${n} constat(s) sur cette page ne rendent aucun crit\xE8re du r\xE9f\xE9rentiel non conforme : leur r\xE8gle sort du p\xE9rim\xE8tre d'application de chacun. Ils comptent dans les colonnes ci-dessus, et sont d\xE9taill\xE9s dans l'artefact.`
   },
   en: {
@@ -61364,6 +61441,8 @@ var S = {
     pagesDetailNote: "One block per page carrying at least one non-conformity, and only its **non-conforming** criteria \u2014 the full grid (every criterion of every page, with its tests and its screenshot) lives in the artifact.",
     pagesClamped: (n) => `_The detail of ${n} page(s) was dropped from this comment to fit GitHub's limit \u2014 the artifact carries them all._`,
     scoreboardClamped: (n) => `_${n} page(s) dropped from the table to fit GitHub's limit \u2014 the artifact carries them all._`,
+    pageDefects: "Defects",
+    pageMoreDefects: (n) => `_\u2026 and ${n} more distinct defect(s) on this page \u2014 see its sheet in the artifact._`,
     noCriterionForFindings: (n) => `${n} finding(s) on this page make no criterion of the standard non-conforming: their rule falls outside every criterion's applicability. They are counted in the columns above, and detailed in the artifact.`
   }
 };
@@ -61508,7 +61587,8 @@ function basisCaveats(result, derived, s, lang) {
   if (notAudited && derived.some((p) => p.basis === "not-audited")) out2.push(`> ${notAudited}`, "");
   return out2;
 }
-function pageBlock(result, page, standard, lang) {
+var PAGE_DEFECTS_SHOWN = 6;
+function pageBlock(result, page, standard, lang, baseDir) {
   const s = S[lang];
   const rows = pageCriterionRows(result, page, standard, lang);
   const nc = rows.filter((r) => r.status === "NC");
@@ -61534,6 +61614,19 @@ function pageBlock(result, page, standard, lang) {
   for (const r of nc) {
     out2.push(withTests ? `| ${cell(r.label)} | ${r.tests.map((t3) => `\`${t3}\``).join(" ")} |` : `| ${cell(r.label)} |`);
   }
+  const defects = groupFindings(
+    page.findings.filter((f) => !f.advisory),
+    standard,
+    lang,
+    baseDir
+  );
+  if (defects.length) {
+    out2.push("", `| ${s.severity} | ${s.where} | ${s.what} | ${s.occurrences} |`, "| --- | --- | --- | ---: |");
+    for (const g of defects.slice(0, PAGE_DEFECTS_SHOWN)) {
+      out2.push(`| ${ICON5[g.severity]} ${g.severity} | \`${cell(g.where)}\` (\`${cell(g.selectorHint)}\`) | ${cell(g.message)} | ${g.occurrences} |`);
+    }
+    if (defects.length > PAGE_DEFECTS_SHOWN) out2.push("", s.pageMoreDefects(defects.length - PAGE_DEFECTS_SHOWN));
+  }
   out2.push("", "</details>");
   return out2.join("\n");
 }
@@ -61541,6 +61634,7 @@ function pagesComment(result, opts = {}) {
   const standard = opts.standard ?? CORE2;
   const lang = opts.lang ?? "en";
   const s = S[lang];
+  const baseDir = opts.baseDir ?? process.cwd();
   const stdLabel = isCore(standard) ? "WCAG 2.2 AA" : loadPack(standard).name;
   const redirected = result.scope.redirected ?? [];
   const scope = pagesOf(result);
@@ -61563,7 +61657,7 @@ function pagesComment(result, opts = {}) {
   if (rate.agentRuled) head.push(`> ${agentMarkNote(lang)}`, "");
   const blocks = [...derived].sort(
     (a, b) => severityCount(b, "bloquant") - severityCount(a, "bloquant") || severityCount(b, "majeur") - severityCount(a, "majeur") || severityCount(b, "mineur") - severityCount(a, "mineur")
-  ).map((p) => pageBlock(result, p, standard, lang)).filter((b) => b !== void 0);
+  ).map((p) => pageBlock(result, p, standard, lang, baseDir)).filter((b) => b !== void 0);
   const assemble = (nBlocks2, nRows2) => {
     const body3 = [...scoreboardTable(result, derived.slice(0, nRows2), standard, s, lang), ""];
     if (nRows2 < derived.length) body3.push(s.scoreboardClamped(derived.length - nRows2), "");

package/skills/review-a11y/SKILL.md

@@ -5,7 +5,7 @@ when_to_use: "Invoke WITHOUT being asked whenever changed front-end code should
 allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs *), Read, Grep, Glob
 license: MIT
 metadata:
-  version: 5.8.0
+  version: 5.9.0
 ---
 
 # review-a11y — accessibility review of changed code

package/skills/review-a11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.8.0";
+var VERSION = "5.9.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -57504,7 +57504,7 @@ function adjudicationContract() {
     verdicts: [...VERDICTS],
     manualReasons: [...MANUAL_REASON_VALUES],
     requires: {
-      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence); a criterion with no harvested evidence cannot be C at all",
+      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence, and about the same kind of element the harvest recorded there \u2014 copy the evidence's own `snippet` rather than retyping the element); a criterion with no harvested evidence cannot be C at all",
       NA: "a non-empty justification",
       NC: "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
       manual: `a reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`
@@ -57640,6 +57640,61 @@ function auditFiles(audit2, cwd) {
     return /* @__PURE__ */ new Set();
   }
 }
+function tagOf2(x) {
+  const fromSnippet = /<\s*([a-zA-Z][\w-]*)/.exec(x.snippet ?? "");
+  if (fromSnippet) return fromSnippet[1].toLowerCase();
+  const fromSelector = /^\s*([a-zA-Z][\w-]*)/.exec(x.selector ?? "");
+  return fromSelector ? fromSelector[1].toLowerCase() : void 0;
+}
+function contentTokens(markup) {
+  const out2 = /* @__PURE__ */ new Set();
+  const withoutTags = markup.replace(/<[^>]*>/g, " ");
+  for (const m of markup.matchAll(/=\s*"([^"]*)"|=\s*'([^']*)'/g)) {
+    for (const w of (m[1] ?? m[2] ?? "").split(/[\s/_-]+/)) if (w.length >= 3) out2.add(w.toLowerCase());
+  }
+  for (const w of withoutTags.split(/[\s/_-]+/)) if (w.length >= 3) out2.add(w.toLowerCase());
+  return out2;
+}
+function recognisablySame(cite, anchor) {
+  const ta = tagOf2(cite);
+  const tb = tagOf2(anchor);
+  if (ta !== void 0 && tb !== void 0 && ta !== tb) return false;
+  if (!cite.snippet || !anchor.snippet) return true;
+  const want = contentTokens(anchor.snippet);
+  if (!want.size) return true;
+  const got = contentTokens(cite.snippet);
+  if (!got.size) return true;
+  for (const w of got) if (want.has(w)) return true;
+  return false;
+}
+function overlap(cite, anchor) {
+  if (!cite.snippet || !anchor.snippet) return 0;
+  const want = contentTokens(anchor.snippet);
+  if (!want.size) return 0;
+  let n = 0;
+  for (const w of contentTokens(cite.snippet)) if (want.has(w)) n++;
+  return n;
+}
+function anchorFor(evidence, c2, drift) {
+  const reps = evidence.filter((e) => e.file === c2.file && Math.abs(e.line - c2.line) <= drift);
+  const best = (cands) => {
+    let top;
+    let score = -1;
+    for (const e of cands) {
+      const n = overlap(c2, e);
+      if (n > score) {
+        score = n;
+        top = e;
+      }
+    }
+    return top;
+  };
+  const rep = best(reps);
+  if (rep) return { at: rep, representative: true };
+  const siblings = evidence.filter((e) => cites0(e.alsoAt ?? [], c2, drift));
+  const sib = best(siblings);
+  return sib ? { at: sib, representative: false } : void 0;
+}
 function cites0(anchors, c2, drift) {
   for (const a of anchors) {
     const at = a.lastIndexOf(":");
@@ -57775,7 +57830,20 @@ function applyAdjudication(audit2, adj, opts = {}) {
           if (!cites0(anchors, c2, citationDrift) && !scopeFiles().has(c2.file)) {
             blame(it.criteriaId, `criterion ${it.criteriaId}: citation ${c2.file}:${c2.line} is not among this criterion's harvested evidence (fabricated?)`);
           }
-          toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: c2.selector, snippet: c2.snippet });
+          const anchor = anchorFor(it.evidence, c2, citationDrift);
+          if (anchor && !recognisablySame(c2, anchor.at)) {
+            blame(
+              it.criteriaId,
+              `criterion ${it.criteriaId}: citation ${c2.file}:${c2.line} does not describe the element harvested there (${anchor.at.snippet ? `\`${anchor.at.snippet.slice(0, 80)}\`` : `<${tagOf2(anchor.at)}>`}) \u2014 cite the element you actually read, copying its \`snippet\` from the brief`
+            );
+          }
+          if (anchor?.representative) {
+            toGround(it.criteriaId, { file: anchor.at.file, line: anchor.at.line, selector: anchor.at.selector ?? c2.selector, snippet: anchor.at.snippet });
+          } else if (anchor) {
+            toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: anchor.at.selector ?? c2.selector });
+          } else {
+            toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: c2.selector, snippet: c2.snippet });
+          }
         }
       }
     } else if (v === "NC") {
@@ -57941,6 +58009,7 @@ function recomputeTallies(a) {
 var residualScanReason = () => "Rendering criterion \u2014 decide on the rendered DOM (`scan`).";
 var residualUndecidableReason = () => "Left as an explicit residual risk (not decidable from the available evidence).";
 var residualRejectedReason = (why) => `Adjudication refused by the gate \u2014 ${why.replace(/^criterion \S+: /, "")}. Re-adjudicate this criterion.`;
+var SNIPPET_SHOWN = 200;
 var T2 = {
   fr: {
     title: "# Adjudication des crit\xE8res \xE0 \xE9valuer (ultra11y)",
@@ -57959,6 +58028,7 @@ var T2 = {
     pagesWord: "page(s)",
     on: "sur",
     alsoAt: "aussi en",
+    snippetLabel: "`snippet` \xE0 copier dans la citation",
     incomplete: "LECTURE INCOMPL\xC8TE \u2014 un \xAB C \xBB sera refus\xE9 sur ce crit\xE8re",
     none: "(aucune \xE9vidence automatique \u2014 d\xE9cidez depuis la source, ou laissez `manual` avec une raison)",
     questions: "\xC0 v\xE9rifier manuellement",
@@ -57988,6 +58058,7 @@ var T2 = {
     pagesWord: "page(s)",
     on: "on",
     alsoAt: "also at",
+    snippetLabel: "`snippet` to copy into the citation",
     incomplete: "INCOMPLETE READING \u2014 a C will be refused on this criterion",
     none: "(no automatic evidence \u2014 decide from source, or leave `manual` with a reason)",
     questions: "To verify manually",
@@ -58048,6 +58119,10 @@ function formatAdjudication(items, lang = "en", standard = CORE2, opts = {}) {
           e.alsoAt?.length ? `${s.alsoAt} ${e.alsoAt.slice(0, shown).join(", ")}${e.alsoAt.length > shown ? "\u2026" : ""}` : ""
         ].filter(Boolean).join(" ");
         out2.push(`- \`${e.file}:${e.line}\` (\`${e.selector}\`)${extra ? ` [${extra}]` : ""}${e.note ? ` \u2014 ${e.note}` : ""}`);
+        if (e.snippet?.trim()) {
+          const snip = e.snippet.trim().replace(/\s+/g, " ").slice(0, SNIPPET_SHOWN);
+          out2.push(`  - ${s.snippetLabel} : \`${snip}${e.snippet.trim().length > SNIPPET_SHOWN ? "\u2026" : ""}\``);
+        }
       }
       out2.push("");
     }
@@ -61319,6 +61394,8 @@ var S = {
     pagesDetailNote: "Un bloc par page portant au moins une non-conformit\xE9, et seulement ses crit\xE8res **non conformes** \u2014 la grille compl\xE8te (tous les crit\xE8res de chaque page, avec leurs tests et leurs captures) vit dans l'artefact.",
     pagesClamped: (n) => `_Le d\xE9tail de ${n} page(s) a \xE9t\xE9 retir\xE9 de ce commentaire pour tenir dans la limite de GitHub \u2014 l'artefact les porte toutes._`,
     scoreboardClamped: (n) => `_${n} page(s) retir\xE9e(s) du tableau pour tenir dans la limite de GitHub \u2014 l'artefact les porte toutes._`,
+    pageDefects: "D\xE9fauts",
+    pageMoreDefects: (n) => `_\u2026 et ${n} autre(s) d\xE9faut(s) distinct(s) sur cette page \u2014 voir la fiche de page dans l'artefact._`,
     noCriterionForFindings: (n) => `${n} constat(s) sur cette page ne rendent aucun crit\xE8re du r\xE9f\xE9rentiel non conforme : leur r\xE8gle sort du p\xE9rim\xE8tre d'application de chacun. Ils comptent dans les colonnes ci-dessus, et sont d\xE9taill\xE9s dans l'artefact.`
   },
   en: {
@@ -61364,6 +61441,8 @@ var S = {
     pagesDetailNote: "One block per page carrying at least one non-conformity, and only its **non-conforming** criteria \u2014 the full grid (every criterion of every page, with its tests and its screenshot) lives in the artifact.",
     pagesClamped: (n) => `_The detail of ${n} page(s) was dropped from this comment to fit GitHub's limit \u2014 the artifact carries them all._`,
     scoreboardClamped: (n) => `_${n} page(s) dropped from the table to fit GitHub's limit \u2014 the artifact carries them all._`,
+    pageDefects: "Defects",
+    pageMoreDefects: (n) => `_\u2026 and ${n} more distinct defect(s) on this page \u2014 see its sheet in the artifact._`,
     noCriterionForFindings: (n) => `${n} finding(s) on this page make no criterion of the standard non-conforming: their rule falls outside every criterion's applicability. They are counted in the columns above, and detailed in the artifact.`
   }
 };
@@ -61508,7 +61587,8 @@ function basisCaveats(result, derived, s, lang) {
   if (notAudited && derived.some((p) => p.basis === "not-audited")) out2.push(`> ${notAudited}`, "");
   return out2;
 }
-function pageBlock(result, page, standard, lang) {
+var PAGE_DEFECTS_SHOWN = 6;
+function pageBlock(result, page, standard, lang, baseDir) {
   const s = S[lang];
   const rows = pageCriterionRows(result, page, standard, lang);
   const nc = rows.filter((r) => r.status === "NC");
@@ -61534,6 +61614,19 @@ function pageBlock(result, page, standard, lang) {
   for (const r of nc) {
     out2.push(withTests ? `| ${cell(r.label)} | ${r.tests.map((t3) => `\`${t3}\``).join(" ")} |` : `| ${cell(r.label)} |`);
   }
+  const defects = groupFindings(
+    page.findings.filter((f) => !f.advisory),
+    standard,
+    lang,
+    baseDir
+  );
+  if (defects.length) {
+    out2.push("", `| ${s.severity} | ${s.where} | ${s.what} | ${s.occurrences} |`, "| --- | --- | --- | ---: |");
+    for (const g of defects.slice(0, PAGE_DEFECTS_SHOWN)) {
+      out2.push(`| ${ICON5[g.severity]} ${g.severity} | \`${cell(g.where)}\` (\`${cell(g.selectorHint)}\`) | ${cell(g.message)} | ${g.occurrences} |`);
+    }
+    if (defects.length > PAGE_DEFECTS_SHOWN) out2.push("", s.pageMoreDefects(defects.length - PAGE_DEFECTS_SHOWN));
+  }
   out2.push("", "</details>");
   return out2.join("\n");
 }
@@ -61541,6 +61634,7 @@ function pagesComment(result, opts = {}) {
   const standard = opts.standard ?? CORE2;
   const lang = opts.lang ?? "en";
   const s = S[lang];
+  const baseDir = opts.baseDir ?? process.cwd();
   const stdLabel = isCore(standard) ? "WCAG 2.2 AA" : loadPack(standard).name;
   const redirected = result.scope.redirected ?? [];
   const scope = pagesOf(result);
@@ -61563,7 +61657,7 @@ function pagesComment(result, opts = {}) {
   if (rate.agentRuled) head.push(`> ${agentMarkNote(lang)}`, "");
   const blocks = [...derived].sort(
     (a, b) => severityCount(b, "bloquant") - severityCount(a, "bloquant") || severityCount(b, "majeur") - severityCount(a, "majeur") || severityCount(b, "mineur") - severityCount(a, "mineur")
-  ).map((p) => pageBlock(result, p, standard, lang)).filter((b) => b !== void 0);
+  ).map((p) => pageBlock(result, p, standard, lang, baseDir)).filter((b) => b !== void 0);
   const assemble = (nBlocks2, nRows2) => {
     const body3 = [...scoreboardTable(result, derived.slice(0, nRows2), standard, s, lang), ""];
     if (nRows2 < derived.length) body3.push(s.scoreboardClamped(derived.length - nRows2), "");

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
 license: MIT
 metadata:
-  version: 5.8.0
+  version: 5.9.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join51, relative as relative5, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.8.0";
+var VERSION = "5.9.0";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -57504,7 +57504,7 @@ function adjudicationContract() {
     verdicts: [...VERDICTS],
     manualReasons: [...MANUAL_REASON_VALUES],
     requires: {
-      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence); a criterion with no harvested evidence cannot be C at all",
+      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence, and about the same kind of element the harvest recorded there \u2014 copy the evidence's own `snippet` rather than retyping the element); a criterion with no harvested evidence cannot be C at all",
       NA: "a non-empty justification",
       NC: "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
       manual: `a reason \u2208 {${MANUAL_REASON_VALUES.join(", ")}}`
@@ -57640,6 +57640,61 @@ function auditFiles(audit2, cwd) {
     return /* @__PURE__ */ new Set();
   }
 }
+function tagOf2(x) {
+  const fromSnippet = /<\s*([a-zA-Z][\w-]*)/.exec(x.snippet ?? "");
+  if (fromSnippet) return fromSnippet[1].toLowerCase();
+  const fromSelector = /^\s*([a-zA-Z][\w-]*)/.exec(x.selector ?? "");
+  return fromSelector ? fromSelector[1].toLowerCase() : void 0;
+}
+function contentTokens(markup) {
+  const out2 = /* @__PURE__ */ new Set();
+  const withoutTags = markup.replace(/<[^>]*>/g, " ");
+  for (const m of markup.matchAll(/=\s*"([^"]*)"|=\s*'([^']*)'/g)) {
+    for (const w of (m[1] ?? m[2] ?? "").split(/[\s/_-]+/)) if (w.length >= 3) out2.add(w.toLowerCase());
+  }
+  for (const w of withoutTags.split(/[\s/_-]+/)) if (w.length >= 3) out2.add(w.toLowerCase());
+  return out2;
+}
+function recognisablySame(cite, anchor) {
+  const ta = tagOf2(cite);
+  const tb = tagOf2(anchor);
+  if (ta !== void 0 && tb !== void 0 && ta !== tb) return false;
+  if (!cite.snippet || !anchor.snippet) return true;
+  const want = contentTokens(anchor.snippet);
+  if (!want.size) return true;
+  const got = contentTokens(cite.snippet);
+  if (!got.size) return true;
+  for (const w of got) if (want.has(w)) return true;
+  return false;
+}
+function overlap(cite, anchor) {
+  if (!cite.snippet || !anchor.snippet) return 0;
+  const want = contentTokens(anchor.snippet);
+  if (!want.size) return 0;
+  let n = 0;
+  for (const w of contentTokens(cite.snippet)) if (want.has(w)) n++;
+  return n;
+}
+function anchorFor(evidence, c2, drift) {
+  const reps = evidence.filter((e) => e.file === c2.file && Math.abs(e.line - c2.line) <= drift);
+  const best = (cands) => {
+    let top;
+    let score = -1;
+    for (const e of cands) {
+      const n = overlap(c2, e);
+      if (n > score) {
+        score = n;
+        top = e;
+      }
+    }
+    return top;
+  };
+  const rep = best(reps);
+  if (rep) return { at: rep, representative: true };
+  const siblings = evidence.filter((e) => cites0(e.alsoAt ?? [], c2, drift));
+  const sib = best(siblings);
+  return sib ? { at: sib, representative: false } : void 0;
+}
 function cites0(anchors, c2, drift) {
   for (const a of anchors) {
     const at = a.lastIndexOf(":");
@@ -57775,7 +57830,20 @@ function applyAdjudication(audit2, adj, opts = {}) {
           if (!cites0(anchors, c2, citationDrift) && !scopeFiles().has(c2.file)) {
             blame(it.criteriaId, `criterion ${it.criteriaId}: citation ${c2.file}:${c2.line} is not among this criterion's harvested evidence (fabricated?)`);
           }
-          toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: c2.selector, snippet: c2.snippet });
+          const anchor = anchorFor(it.evidence, c2, citationDrift);
+          if (anchor && !recognisablySame(c2, anchor.at)) {
+            blame(
+              it.criteriaId,
+              `criterion ${it.criteriaId}: citation ${c2.file}:${c2.line} does not describe the element harvested there (${anchor.at.snippet ? `\`${anchor.at.snippet.slice(0, 80)}\`` : `<${tagOf2(anchor.at)}>`}) \u2014 cite the element you actually read, copying its \`snippet\` from the brief`
+            );
+          }
+          if (anchor?.representative) {
+            toGround(it.criteriaId, { file: anchor.at.file, line: anchor.at.line, selector: anchor.at.selector ?? c2.selector, snippet: anchor.at.snippet });
+          } else if (anchor) {
+            toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: anchor.at.selector ?? c2.selector });
+          } else {
+            toGround(it.criteriaId, { file: c2.file, line: c2.line, selector: c2.selector, snippet: c2.snippet });
+          }
         }
       }
     } else if (v === "NC") {
@@ -57941,6 +58009,7 @@ function recomputeTallies(a) {
 var residualScanReason = () => "Rendering criterion \u2014 decide on the rendered DOM (`scan`).";
 var residualUndecidableReason = () => "Left as an explicit residual risk (not decidable from the available evidence).";
 var residualRejectedReason = (why) => `Adjudication refused by the gate \u2014 ${why.replace(/^criterion \S+: /, "")}. Re-adjudicate this criterion.`;
+var SNIPPET_SHOWN = 200;
 var T2 = {
   fr: {
     title: "# Adjudication des crit\xE8res \xE0 \xE9valuer (ultra11y)",
@@ -57959,6 +58028,7 @@ var T2 = {
     pagesWord: "page(s)",
     on: "sur",
     alsoAt: "aussi en",
+    snippetLabel: "`snippet` \xE0 copier dans la citation",
     incomplete: "LECTURE INCOMPL\xC8TE \u2014 un \xAB C \xBB sera refus\xE9 sur ce crit\xE8re",
     none: "(aucune \xE9vidence automatique \u2014 d\xE9cidez depuis la source, ou laissez `manual` avec une raison)",
     questions: "\xC0 v\xE9rifier manuellement",
@@ -57988,6 +58058,7 @@ var T2 = {
     pagesWord: "page(s)",
     on: "on",
     alsoAt: "also at",
+    snippetLabel: "`snippet` to copy into the citation",
     incomplete: "INCOMPLETE READING \u2014 a C will be refused on this criterion",
     none: "(no automatic evidence \u2014 decide from source, or leave `manual` with a reason)",
     questions: "To verify manually",
@@ -58048,6 +58119,10 @@ function formatAdjudication(items, lang = "en", standard = CORE2, opts = {}) {
           e.alsoAt?.length ? `${s.alsoAt} ${e.alsoAt.slice(0, shown).join(", ")}${e.alsoAt.length > shown ? "\u2026" : ""}` : ""
         ].filter(Boolean).join(" ");
         out2.push(`- \`${e.file}:${e.line}\` (\`${e.selector}\`)${extra ? ` [${extra}]` : ""}${e.note ? ` \u2014 ${e.note}` : ""}`);
+        if (e.snippet?.trim()) {
+          const snip = e.snippet.trim().replace(/\s+/g, " ").slice(0, SNIPPET_SHOWN);
+          out2.push(`  - ${s.snippetLabel} : \`${snip}${e.snippet.trim().length > SNIPPET_SHOWN ? "\u2026" : ""}\``);
+        }
       }
       out2.push("");
     }
@@ -61319,6 +61394,8 @@ var S = {
     pagesDetailNote: "Un bloc par page portant au moins une non-conformit\xE9, et seulement ses crit\xE8res **non conformes** \u2014 la grille compl\xE8te (tous les crit\xE8res de chaque page, avec leurs tests et leurs captures) vit dans l'artefact.",
     pagesClamped: (n) => `_Le d\xE9tail de ${n} page(s) a \xE9t\xE9 retir\xE9 de ce commentaire pour tenir dans la limite de GitHub \u2014 l'artefact les porte toutes._`,
     scoreboardClamped: (n) => `_${n} page(s) retir\xE9e(s) du tableau pour tenir dans la limite de GitHub \u2014 l'artefact les porte toutes._`,
+    pageDefects: "D\xE9fauts",
+    pageMoreDefects: (n) => `_\u2026 et ${n} autre(s) d\xE9faut(s) distinct(s) sur cette page \u2014 voir la fiche de page dans l'artefact._`,
     noCriterionForFindings: (n) => `${n} constat(s) sur cette page ne rendent aucun crit\xE8re du r\xE9f\xE9rentiel non conforme : leur r\xE8gle sort du p\xE9rim\xE8tre d'application de chacun. Ils comptent dans les colonnes ci-dessus, et sont d\xE9taill\xE9s dans l'artefact.`
   },
   en: {
@@ -61364,6 +61441,8 @@ var S = {
     pagesDetailNote: "One block per page carrying at least one non-conformity, and only its **non-conforming** criteria \u2014 the full grid (every criterion of every page, with its tests and its screenshot) lives in the artifact.",
     pagesClamped: (n) => `_The detail of ${n} page(s) was dropped from this comment to fit GitHub's limit \u2014 the artifact carries them all._`,
     scoreboardClamped: (n) => `_${n} page(s) dropped from the table to fit GitHub's limit \u2014 the artifact carries them all._`,
+    pageDefects: "Defects",
+    pageMoreDefects: (n) => `_\u2026 and ${n} more distinct defect(s) on this page \u2014 see its sheet in the artifact._`,
     noCriterionForFindings: (n) => `${n} finding(s) on this page make no criterion of the standard non-conforming: their rule falls outside every criterion's applicability. They are counted in the columns above, and detailed in the artifact.`
   }
 };
@@ -61508,7 +61587,8 @@ function basisCaveats(result, derived, s, lang) {
   if (notAudited && derived.some((p) => p.basis === "not-audited")) out2.push(`> ${notAudited}`, "");
   return out2;
 }
-function pageBlock(result, page, standard, lang) {
+var PAGE_DEFECTS_SHOWN = 6;
+function pageBlock(result, page, standard, lang, baseDir) {
   const s = S[lang];
   const rows = pageCriterionRows(result, page, standard, lang);
   const nc = rows.filter((r) => r.status === "NC");
@@ -61534,6 +61614,19 @@ function pageBlock(result, page, standard, lang) {
   for (const r of nc) {
     out2.push(withTests ? `| ${cell(r.label)} | ${r.tests.map((t3) => `\`${t3}\``).join(" ")} |` : `| ${cell(r.label)} |`);
   }
+  const defects = groupFindings(
+    page.findings.filter((f) => !f.advisory),
+    standard,
+    lang,
+    baseDir
+  );
+  if (defects.length) {
+    out2.push("", `| ${s.severity} | ${s.where} | ${s.what} | ${s.occurrences} |`, "| --- | --- | --- | ---: |");
+    for (const g of defects.slice(0, PAGE_DEFECTS_SHOWN)) {
+      out2.push(`| ${ICON5[g.severity]} ${g.severity} | \`${cell(g.where)}\` (\`${cell(g.selectorHint)}\`) | ${cell(g.message)} | ${g.occurrences} |`);
+    }
+    if (defects.length > PAGE_DEFECTS_SHOWN) out2.push("", s.pageMoreDefects(defects.length - PAGE_DEFECTS_SHOWN));
+  }
   out2.push("", "</details>");
   return out2.join("\n");
 }
@@ -61541,6 +61634,7 @@ function pagesComment(result, opts = {}) {
   const standard = opts.standard ?? CORE2;
   const lang = opts.lang ?? "en";
   const s = S[lang];
+  const baseDir = opts.baseDir ?? process.cwd();
   const stdLabel = isCore(standard) ? "WCAG 2.2 AA" : loadPack(standard).name;
   const redirected = result.scope.redirected ?? [];
   const scope = pagesOf(result);
@@ -61563,7 +61657,7 @@ function pagesComment(result, opts = {}) {
   if (rate.agentRuled) head.push(`> ${agentMarkNote(lang)}`, "");
   const blocks = [...derived].sort(
     (a, b) => severityCount(b, "bloquant") - severityCount(a, "bloquant") || severityCount(b, "majeur") - severityCount(a, "majeur") || severityCount(b, "mineur") - severityCount(a, "mineur")
-  ).map((p) => pageBlock(result, p, standard, lang)).filter((b) => b !== void 0);
+  ).map((p) => pageBlock(result, p, standard, lang, baseDir)).filter((b) => b !== void 0);
   const assemble = (nBlocks2, nRows2) => {
     const body3 = [...scoreboardTable(result, derived.slice(0, nRows2), standard, s, lang), ""];
     if (nRows2 < derived.length) body3.push(s.scoreboardClamped(derived.length - nRows2), "");

package/src/adjudicate.ts

@@ -183,7 +183,7 @@ export function adjudicationContract(): AdjudicationContract {
     verdicts: [...VERDICTS],
     manualReasons: [...MANUAL_REASON_VALUES],
     requires: {
-      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence); a criterion with no harvested evidence cannot be C at all",
+      C: "a non-empty justification AND citations[] naming the harvested evidence it cleared (each anchor resolvable and drawn from this criterion's own evidence, and about the same kind of element the harvest recorded there — copy the evidence's own `snippet` rather than retyping the element); a criterion with no harvested evidence cannot be C at all",
       NA: "a non-empty justification",
       NC: "at least one groundable finding, each citing a normativeRef that resolves against the active standard",
       manual: `a reason ∈ {${MANUAL_REASON_VALUES.join(", ")}}`,
@@ -428,6 +428,109 @@ function auditFiles(audit: AuditResult, cwd?: string): Set<string> {
  *  criterion was never given. And it is only half the gate — `groundFinding` still has to find
  *  the cited content in the real source, so a plausible-looking file:line in the right
  *  neighbourhood proves nothing on its own. */
+/** The tag a citation or an anchor is about, from its snippet first and its selector second.
+ *  Lowercased — HTML tag names are case-insensitive. Undefined when neither says. */
+function tagOf(x: { snippet?: string; selector?: string }): string | undefined {
+  const fromSnippet = /<\s*([a-zA-Z][\w-]*)/.exec(x.snippet ?? "");
+  if (fromSnippet) return fromSnippet[1]!.toLowerCase();
+  const fromSelector = /^\s*([a-zA-Z][\w-]*)/.exec(x.selector ?? "");
+  return fromSelector ? fromSelector[1]!.toLowerCase() : undefined;
+}
+
+/** The distinctive words of a markup fragment: attribute VALUES and text, minus the noise.
+ *
+ *  Values and text, never attribute names — every `<a>` has an `href`, so names carry no
+ *  identity. Short tokens go too: `""`, `en`, `0` are shared by half a document. */
+function contentTokens(markup: string): Set<string> {
+  const out = new Set<string>();
+  const withoutTags = markup.replace(/<[^>]*>/g, " ");
+  for (const m of markup.matchAll(/=\s*"([^"]*)"|=\s*'([^']*)'/g)) {
+    for (const w of (m[1] ?? m[2] ?? "").split(/[\s/_-]+/)) if (w.length >= 3) out.add(w.toLowerCase());
+  }
+  for (const w of withoutTags.split(/[\s/_-]+/)) if (w.length >= 3) out.add(w.toLowerCase());
+  return out;
+}
+
+/** Is the citation RECOGNISABLY the element the harvest recorded at that anchor?
+ *
+ *  This is what survives when byte-exact snippet matching is given up, and it has to do two
+ *  jobs at once. An adjudicator that retypes an element — attributes reordered, `class` left
+ *  off — named the right thing and must not be refused. An adjudicator that writes down a
+ *  DIFFERENT element at the same anchor (another link, another href, another label) has not
+ *  read what it claims to have read, and must be.
+ *
+ *  So: same tag, and at least one distinctive word in common — an attribute value or a word of
+ *  the text. `<img alt="" src="/assets/help.svg">` against
+ *  `<img src="/assets/help.svg" alt="" class="fr-responsive-img">` shares `assets` and
+ *  `help.svg`; `<a href="/invented">Nowhere</a>` against `<a href="/pricing">Read more</a>`
+ *  shares nothing at all.
+ *
+ *  Silence is not contradiction: a citation with no snippet, or an anchor whose markup carries
+ *  no distinctive word (`<br>`), is judged on the tag alone. Membership and the anchor's own
+ *  grounding still stand behind every one of them. */
+function recognisablySame(cite: { snippet?: string; selector?: string }, anchor: { snippet?: string; selector?: string }): boolean {
+  const ta = tagOf(cite);
+  const tb = tagOf(anchor);
+  if (ta !== undefined && tb !== undefined && ta !== tb) return false;
+  if (!cite.snippet || !anchor.snippet) return true;
+  const want = contentTokens(anchor.snippet);
+  if (!want.size) return true;
+  const got = contentTokens(cite.snippet);
+  if (!got.size) return true;
+  for (const w of got) if (want.has(w)) return true;
+  return false;
+}
+
+/** How much of the anchor's distinctive content the citation repeats. 0 = nothing in common. */
+function overlap(cite: { snippet?: string }, anchor: { snippet?: string }): number {
+  if (!cite.snippet || !anchor.snippet) return 0;
+  const want = contentTokens(anchor.snippet);
+  if (!want.size) return 0;
+  let n = 0;
+  for (const w of contentTokens(cite.snippet)) if (want.has(w)) n++;
+  return n;
+}
+
+/** The harvested anchor a citation resolves to, or undefined.
+ *
+ *  Two shapes, because a class carries two kinds of anchor. The REPRESENTATIVE has a snippet
+ *  the engine read out of the file itself; a SIBLING in `alsoAt` is a bare `file:line` — the
+ *  same content class at another occurrence, with no snippet recorded. Which one matched
+ *  decides what can be grounded, so the caller is told.
+ *
+ *  CONTENT BREAKS THE TIE, because the line often cannot. A page snapshot is
+ *  `documentElement.outerHTML`: one line, the whole document. Every anchor harvested from it
+ *  therefore sits at line 2, so "the anchor at the cited line" names dozens of elements at
+ *  once and taking the first is a coin toss — measured on a real run, that is how a citation
+ *  of an `<img>` came to be checked against an `<svg>` and refused for describing the wrong
+ *  element. So among the anchors the line admits, the one the citation actually describes
+ *  wins; ties and empty overlaps keep document order, which is what a single-anchor file
+ *  always did. */
+function anchorFor(
+  evidence: Evidence[],
+  c: { file: string; line: number; snippet?: string },
+  drift: number,
+): { at: Evidence; representative: boolean } | undefined {
+  const reps = evidence.filter((e) => e.file === c.file && Math.abs(e.line - c.line) <= drift);
+  const best = (cands: Evidence[]): Evidence | undefined => {
+    let top: Evidence | undefined;
+    let score = -1;
+    for (const e of cands) {
+      const n = overlap(c, e);
+      if (n > score) {
+        score = n;
+        top = e;
+      }
+    }
+    return top;
+  };
+  const rep = best(reps);
+  if (rep) return { at: rep, representative: true };
+  const siblings = evidence.filter((e) => cites0(e.alsoAt ?? [], c, drift));
+  const sib = best(siblings);
+  return sib ? { at: sib, representative: false } : undefined;
+}
+
 function cites0(anchors: string[], c: { file: string; line: number }, drift: number): boolean {
   for (const a of anchors) {
     const at = a.lastIndexOf(":");
@@ -716,7 +819,40 @@ export function applyAdjudication(
           if (!cites0(anchors, c, citationDrift) && !scopeFiles().has(c.file)) {
             blame(it.criteriaId, `criterion ${it.criteriaId}: citation ${c.file}:${c.line} is not among this criterion's harvested evidence (fabricated?)`);
           }
-          toGround(it.criteriaId, { file: c.file, line: c.line, selector: c.selector, snippet: c.snippet });
+          // GROUND THE ANCHOR, NOT THE TRANSCRIPTION.
+          //
+          // Once a citation lands on evidence this criterion was shown, the harvested anchor is
+          // the ground truth: the engine read it out of the file, so it is there by
+          // construction. Re-checking the agent's RETYPING of it against the file tests
+          // spelling, not evidence — and it fails constantly, because an adjudicator writes the
+          // element out from the brief rather than copying the `snippet` field byte for byte.
+          //
+          // Measured on a real run: 81 criteria adjudicated, 78 of 82 citations landing exactly
+          // on a harvested anchor, and 54 verdicts refused — every one of them for
+          // `cited snippet not found`. A rendered snapshot serializes the document on ONE line,
+          // so its anchors all sit at line 2 and the grounding window is the whole page: what
+          // failed was never the location, only the transcription of it.
+          //
+          // A sibling from `alsoAt` carries no snippet (it is a bare `file:line`), so there is
+          // nothing authoritative to ground — the selector probe runs against the real file
+          // instead, which is the same check a citation with no snippet has always had.
+          //
+          // Anything OUTSIDE the harvest keeps the strict check below, unchanged. That is where
+          // a fabricated location would hide, and this must not become a way to launder one.
+          const anchor = anchorFor(it.evidence, c, citationDrift);
+          if (anchor && !recognisablySame(c, anchor.at)) {
+            blame(
+              it.criteriaId,
+              `criterion ${it.criteriaId}: citation ${c.file}:${c.line} does not describe the element harvested there (${anchor.at.snippet ? `\`${anchor.at.snippet.slice(0, 80)}\`` : `<${tagOf(anchor.at)}>`}) — cite the element you actually read, copying its \`snippet\` from the brief`,
+            );
+          }
+          if (anchor?.representative) {
+            toGround(it.criteriaId, { file: anchor.at.file, line: anchor.at.line, selector: anchor.at.selector ?? c.selector, snippet: anchor.at.snippet });
+          } else if (anchor) {
+            toGround(it.criteriaId, { file: c.file, line: c.line, selector: anchor.at.selector ?? c.selector });
+          } else {
+            toGround(it.criteriaId, { file: c.file, line: c.line, selector: c.selector, snippet: c.snippet });
+          }
         }
       }
     } else if (v === "NC") {
@@ -945,6 +1081,11 @@ const residualUndecidableReason = () => "Left as an explicit residual risk (not
  *  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.`;
 
+/** Characters of a harvested snippet the brief prints. Long enough that the element is
+ *  unmistakable — its tag and its first distinctive attributes — and short enough that a page
+ *  snapshot's markup does not swamp a model's context. */
+const SNIPPET_SHOWN = 200;
+
 // ---- worklist file rendering ----
 const T = {
   fr: {
@@ -965,6 +1106,7 @@ const T = {
     pagesWord: "page(s)",
     on: "sur",
     alsoAt: "aussi en",
+    snippetLabel: "`snippet` à copier dans la citation",
     incomplete: "LECTURE INCOMPLÈTE — un « C » sera refusé sur ce critère",
     none: "(aucune évidence automatique — décidez depuis la source, ou laissez `manual` avec une raison)",
     questions: "À vérifier manuellement",
@@ -995,6 +1137,7 @@ const T = {
     pagesWord: "page(s)",
     on: "on",
     alsoAt: "also at",
+    snippetLabel: "`snippet` to copy into the citation",
     incomplete: "INCOMPLETE READING — a C will be refused on this criterion",
     none: "(no automatic evidence — decide from source, or leave `manual` with a reason)",
     questions: "To verify manually",
@@ -1152,6 +1295,23 @@ export function formatAdjudication(
           .filter(Boolean)
           .join(" ");
         out.push(`- \`${e.file}:${e.line}\` (\`${e.selector}\`)${extra ? ` [${extra}]` : ""}${e.note ? ` — ${e.note}` : ""}`);
+        // THE SNIPPET, SHOWN AND NAMED.
+        //
+        // The contract asks a citation to carry one, and this brief used to end each line with
+        // the harvester's NOTE — which for an image subject reads `<svg> alt="" aria-label=""
+        // src=""`. That is markup-shaped, and it was the only markup-shaped string on the line.
+        // Measured on a real run: the adjudicator copied it into 34 citations, each one a tag
+        // glued to three empty attributes, and the fold refused every one — correctly, and
+        // uselessly, because a citation that repeats a template proves nothing. The agent was
+        // copying the only thing it had been given.
+        //
+        // Its own line, and labelled, so it cannot be read as more of the note. Bounded because
+        // a rendered snapshot's markup can be long and this file is read by a model with a
+        // context to spend.
+        if (e.snippet?.trim()) {
+          const snip = e.snippet.trim().replace(/\s+/g, " ").slice(0, SNIPPET_SHOWN);
+          out.push(`  - ${s.snippetLabel} : \`${snip}${e.snippet.trim().length > SNIPPET_SHOWN ? "…" : ""}\``);
+        }
       }
       out.push("");
     }

package/src/annotate.ts

@@ -141,6 +141,8 @@ const S = {
     pagesClamped: (n: number) =>
       `_Le détail de ${n} page(s) a été retiré de ce commentaire pour tenir dans la limite de GitHub — l'artefact les porte toutes._`,
     scoreboardClamped: (n: number) => `_${n} page(s) retirée(s) du tableau pour tenir dans la limite de GitHub — l'artefact les porte toutes._`,
+    pageDefects: "Défauts",
+    pageMoreDefects: (n: number) => `_… et ${n} autre(s) défaut(s) distinct(s) sur cette page — voir la fiche de page dans l'artefact._`,
     noCriterionForFindings: (n: number) =>
       `${n} constat(s) sur cette page ne rendent aucun critère du référentiel non conforme : leur règle sort du périmètre d'application de chacun. Ils comptent dans les colonnes ci-dessus, et sont détaillés dans l'artefact.`,
   },
@@ -193,6 +195,8 @@ const S = {
       "One block per page carrying at least one non-conformity, and only its **non-conforming** criteria — the full grid (every criterion of every page, with its tests and its screenshot) lives in the artifact.",
     pagesClamped: (n: number) => `_The detail of ${n} page(s) was dropped from this comment to fit GitHub's limit — the artifact carries them all._`,
     scoreboardClamped: (n: number) => `_${n} page(s) dropped from the table to fit GitHub's limit — the artifact carries them all._`,
+    pageDefects: "Defects",
+    pageMoreDefects: (n: number) => `_… and ${n} more distinct defect(s) on this page — see its sheet in the artifact._`,
     noCriterionForFindings: (n: number) =>
       `${n} finding(s) on this page make no criterion of the standard non-conforming: their rule falls outside every criterion's applicability. They are counted in the columns above, and detailed in the artifact.`,
   },
@@ -445,6 +449,13 @@ function basisCaveats(result: AuditResult, derived: PageResult[], s: (typeof S)[
   return out;
 }
 
+/** Distinct defects shown under one page before the block says how many it held back.
+ *
+ *  Distinct, not occurrences — the grouping already folded the repeats. Six is what fits
+ *  beside the criterion table without turning a 35-page comment into something nobody scrolls,
+ *  and the ones held back are counted rather than dropped in silence. */
+const PAGE_DEFECTS_SHOWN = 6;
+
 /** One page's collapsed block: its severity counts in the summary line, its standing as the
  *  shared tally sentence, and the criteria that are actually NON-CONFORMING.
  *
@@ -453,7 +464,7 @@ function basisCaveats(result: AuditResult, derived: PageResult[], s: (typeof S)[
  *  reviewer needs inline is which pages fail and on what — the tally line carries the rest
  *  (conforming, not applicable, and how many nobody has ruled on yet) without pretending the
  *  undecided ones are fine. */
-function pageBlock(result: AuditResult, page: PageResult, standard: StandardId, lang: Lang): string | undefined {
+function pageBlock(result: AuditResult, page: PageResult, standard: StandardId, lang: Lang, baseDir: string): string | undefined {
   const s = S[lang];
   const rows = pageCriterionRows(result, page, standard, lang);
   const nc = rows.filter((r) => r.status === "NC");
@@ -484,6 +495,32 @@ function pageBlock(result: AuditResult, page: PageResult, standard: StandardId,
   for (const r of nc) {
     out.push(withTests ? `| ${cell(r.label)} | ${r.tests.map((t) => `\`${t}\``).join(" ")} |` : `| ${cell(r.label)} |`);
   }
+
+  // WHAT TO CHANGE, not only what was failed.
+  //
+  // The rows above name the criterion; a criterion is the norm, not the work. Measured on a
+  // real pull request: 506 lines, 35 pages, every non-conforming criterion listed — and not
+  // one file, line, selector or description of the defect anywhere in the document. A
+  // reviewer read « les couleurs sont-elles suffisamment contrastées ? » and had to download
+  // a 4 MB artifact to find out which element. The digest comment has carried location and
+  // defect since it existed; this is the same audit read page-first, and there is no reason
+  // for it to be the half that says nothing.
+  //
+  // Grouped, never listed: one design-system defect repeated on twenty rows is ONE thing to
+  // fix, and twenty identical lines is how a comment becomes unreadable and then gets muzzled.
+  const defects = groupFindings(
+    page.findings.filter((f) => !f.advisory),
+    standard,
+    lang,
+    baseDir,
+  );
+  if (defects.length) {
+    out.push("", `| ${s.severity} | ${s.where} | ${s.what} | ${s.occurrences} |`, "| --- | --- | --- | ---: |");
+    for (const g of defects.slice(0, PAGE_DEFECTS_SHOWN)) {
+      out.push(`| ${ICON[g.severity]} ${g.severity} | \`${cell(g.where)}\` (\`${cell(g.selectorHint)}\`) | ${cell(g.message)} | ${g.occurrences} |`);
+    }
+    if (defects.length > PAGE_DEFECTS_SHOWN) out.push("", s.pageMoreDefects(defects.length - PAGE_DEFECTS_SHOWN));
+  }
   out.push("", "</details>");
   return out.join("\n");
 }
@@ -504,6 +541,7 @@ export function pagesComment(result: AuditResult, opts: AnnotateOptions & { runU
   const standard = opts.standard ?? CORE;
   const lang = opts.lang ?? "en";
   const s = S[lang];
+  const baseDir = opts.baseDir ?? process.cwd();
   const stdLabel = isCore(standard) ? "WCAG 2.2 AA" : loadPack(standard).name;
   const redirected = result.scope.redirected ?? [];
   const scope = pagesOf(result);
@@ -539,7 +577,7 @@ export function pagesComment(result: AuditResult, opts: AnnotateOptions & { runU
         severityCount(b, "majeur") - severityCount(a, "majeur") ||
         severityCount(b, "mineur") - severityCount(a, "mineur"),
     )
-    .map((p) => pageBlock(result, p, standard, lang))
+    .map((p) => pageBlock(result, p, standard, lang, baseDir))
     .filter((b): b is string => b !== undefined);
 
   // WHOLE blocks and WHOLE rows, never a slice of the finished string — cutting a rendered

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "5.8.0";
+export const VERSION = "5.9.0";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,