ultra11y 5.2.1 → 5.3.2

package/skills/ultra11y/references/ci.md

@@ -34,8 +34,15 @@ Page by page, with a real browser, in the same step:
       wait-on: http://localhost:3000
       urls: http://localhost:3000 http://localhost:3000/contact
       # …or `sample: 'true'` to scan the sample declared in .ultra11yrc.json
+      comment: 'true'
+      comment-kind: pages           # the page-by-page grid, under its own sticky marker
 ```
 
+A page sweep is usually a **second job** — it needs a built app, a database, a browser — and
+it can comment alongside the code gate above without either overwriting the other, because
+each kind has its own marker. Give the two jobs distinct `artifact-name`s too: artifact names
+must be unique within a run.
+
 `ultra11y init --ci` writes a workflow using it, **pinned to the exact engine version that
 generated the file** (`@v<that version>`) so a CI run stays reproducible. `@v<major>` — `@v5`
 today — is a moving alias the release workflow repoints at each release, for teams who would
@@ -232,12 +239,27 @@ them as separate analyses instead of one overwriting the other.
 
 ## The sticky PR comment
 
-`ULTRA11Y_PR_COMMENT=1` (what the action's `comment: 'true'` sets) posts the job summary as a
-pull-request comment and **edits it in place** on every subsequent run — a CI job that appends
-a fresh comment on each push turns a busy PR into a wall of stale audits. The comment is keyed
-by an invisible marker that includes the standard, so a WCAG run and an RGAA run keep separate
-comments instead of overwriting each other, and a human's comment is never adopted (an edit is
-destructive, so the match has to be exact).
+`ULTRA11Y_PR_COMMENT=1` (what the action's `comment: 'true'` sets) posts a pull-request comment
+and **edits it in place** on every subsequent run — a CI job that appends a fresh comment on
+each push turns a busy PR into a wall of stale audits. The comment is keyed by an invisible
+marker, and a human's comment is never adopted (an edit is destructive, so the match has to be
+exact).
+
+It is **not** the job summary. That document has a 1 MiB budget and a reader who went looking
+for it; a comment has 64 KiB and a reader scanning a diff. Two documents are available, chosen
+with the action's `comment-kind` (`ULTRA11Y_PR_COMMENT_KIND`):
+
+| kind | what it posts |
+|---|---|
+| `digest` (default) | The verdict, the coverage, and the distinct defects — one row per (criterion, rule, selector), so 472 occurrences of one design-system defect are one row. Then a link. |
+| `pages` | The page-by-page grid: one row per page with its basis, its rate **and its denominator**, and its severities; then a collapsed block per failing page listing its non-conforming criteria. Needs pages in scope; with none it says so rather than posting an empty scoreboard. |
+
+**The marker carries both the standard and the kind**, so a WCAG run and an RGAA run keep
+separate comments — and so do the code digest and the page grid of one standard. That last
+part is not hypothetical: a workflow whose gate job and page-sweep job both commented under
+one marker had the sweep (337 files, 684 occurrences) overwrite the gate's four actionable
+findings on every run, and the tier that got muzzled was the page sweep. The kinds are also
+built so neither key is a substring of the other, because the lookup matches with `includes`.
 
 It is best-effort, like issue creation: off a pull request, or with no `gh`/no auth, it
 reports `skipped` and the run carries on. A comment is never worth failing a build over. If

package/skills/ultra11y/references/orchestration.md

@@ -20,6 +20,22 @@ node scripts/ultra11y.mjs orchestrate --run <dir> [--phase adjudicate|verify-rep
 | Subagents but no Workflow tool | Same `orchestrate`; dispatch one subagent per batch following `<RUN>/orchestration/agents/<role>.md` (the workflow script lists the batches and their prompts). One writer: you fold the results in. |
 | Eco mode, or no subagents | `orchestrate --run <RUN> --eco` → follow `<RUN>/orchestration/RUNBOOK.md` sequentially, playing each role yourself. Correctness-identical; only wall-clock differs. |
 
+## The other dispatch: the review
+
+The judgment phases are not the only thing that leaves this skill. Once the audit has
+produced fixes, the **`review-a11y` skill** reviews the code under change — dispatched the
+same way, and read from the same table:
+
+| Your harness | How to run the review |
+|---|---|
+| Subagents (Workflow tool or not) | One subagent, one prompt: use the `review-a11y` skill on the change, return its report verbatim. |
+| No subagents | Invoke `review-a11y` directly, in this session. |
+
+It differs from a judgment batch in one way that matters: **the review is not a worklist**.
+Nothing is folded back, no gate re-reads it, and it writes nothing — so the one-writer rule
+below is satisfied trivially, and there is no `--apply` step to keep. What comes back is a
+report for a human.
+
 ## The rules that do not bend
 
 - **Subagents never write.** Every emitted contract ends with the one-writer rule, and the

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join50, relative as relative5, resolve as resolve15, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.2.1";
+var VERSION = "5.3.2";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -53611,13 +53611,16 @@ function ghAvailable() {
 }
 
 // src/pr-comment.ts
-function COMMENT_MARKER(standard) {
-  return `<!-- ultra11y:report standard="${standard}" -->`;
+function COMMENT_MARKER(standard, kind = "digest") {
+  return `<!-- ultra11y:report standard="${standard}"${kind === "digest" ? "" : ` kind="${kind}"`} -->`;
 }
-function stickyBody(markdown, standard) {
-  return `${COMMENT_MARKER(standard)}
+function stickyBody(markdown, standard, kind = "digest") {
+  return `${COMMENT_MARKER(standard, kind)}
 ${markdown}`;
 }
+function commentKindFrom(value) {
+  return value === "pages" ? "pages" : "digest";
+}
 function prNumberFromEnv(env = process.env) {
   const explicit = Number.parseInt(env.ULTRA11Y_PR ?? "", 10);
   if (Number.isFinite(explicit) && explicit > 0) return explicit;
@@ -53628,11 +53631,11 @@ function prNumberFromEnv(env = process.env) {
 function pickExistingComment(comments, marker) {
   return comments.find((c2) => typeof c2.body === "string" && c2.body.includes(marker));
 }
-function pushPrComment(markdown, standard = "wcag") {
+function pushPrComment(markdown, standard = "wcag", kind = "digest") {
   const pr = prNumberFromEnv();
   if (pr === void 0) return { ok: true, action: "skipped", reason: "not a pull-request run" };
-  const marker = COMMENT_MARKER(standard);
-  const body3 = stickyBody(markdown, standard);
+  const marker = COMMENT_MARKER(standard, kind);
+  const body3 = stickyBody(markdown, standard, kind);
   try {
     const repo = ghExec(["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"]).trim();
     let existing;
@@ -55184,6 +55187,9 @@ function pageTally(rows) {
     manual: rows.filter((r) => r.status === "manual").length
   };
 }
+function pageTallyNote(t2, lang) {
+  return L7[lang].tally(t2.c, t2.nc, t2.na, t2.manual);
+}
 function pageCoverage(rows) {
   const t2 = pageTally(rows);
   return { decided: t2.c + t2.nc, total: rows.length };
@@ -55209,7 +55215,7 @@ function renderPageReport(result, page, opts = {}) {
   const cov = pageCoverage(rows);
   const rate = pageRatePct(rows);
   out2.push(`- **${s.rate}** : **${rate === null ? "\u2014" : `${rate} %`}** _(${s.rateNote})_`);
-  out2.push(`- ${s.tally(t2.c, t2.nc, t2.na, t2.manual)}`);
+  out2.push(`- ${pageTallyNote(t2, lang)}`);
   out2.push(`- ${s.coverage(cov.decided, cov.total)}`, "");
   if (page.basis !== "snapshot") out2.push(`> \u26A0\uFE0F ${s.sourceWarn}`, "");
   const shot = opts.screenshots?.get(page.id);
@@ -60052,7 +60058,15 @@ var S = {
     clamped: (n) => `_${n} groupe(s) retir\xE9(s) de ce commentaire pour tenir dans la limite de GitHub \u2014 le r\xE9sum\xE9 de job les porte tous._`,
     unanchored: (n) => `${n} constat(s) rattach\xE9(s) \xE0 une URL, sans ligne de code \xE0 annoter \u2014 voir le rapport.`,
     unattributed: (n) => `${n} constat(s) ne sont rattach\xE9s \xE0 aucune page (code partag\xE9, fichier hors routes) \u2014 compt\xE9s dans l'audit global, jamais r\xE9partis d'office.`,
-    sourceBasis: "Une page marqu\xE9e \xAB source \xBB n'a pas d'instantan\xE9 : l'absence de constat n'y vaut PAS conformit\xE9, et son taux ne porte que sur ce que le moteur a pu d\xE9cider ailleurs."
+    sourceBasis: "Une page marqu\xE9e \xAB source \xBB n'a pas d'instantan\xE9 : l'absence de constat n'y vaut PAS conformit\xE9, et son taux ne porte que sur ce que le moteur a pu d\xE9cider ailleurs.",
+    pageByPage: "page par page",
+    pagesCount: (n) => `${n} page(s)`,
+    testsCol: "Tests",
+    noPages: "Aucune page dans le p\xE9rim\xE8tre de ce run : le balayage n'a produit aucun instantan\xE9. Ce n'est pas un bilan vide, c'est un bilan absent \u2014 les crit\xE8res au rendu restent \xE0 \xE9valuer.",
+    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._`,
+    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: {
     title: "ultra11y accessibility audit",
@@ -60085,7 +60099,15 @@ var S = {
     clamped: (n) => `_${n} group(s) dropped from this comment to fit GitHub's limit \u2014 the job summary carries them all._`,
     unanchored: (n) => `${n} finding(s) keyed to a URL, with no code line to annotate \u2014 see the report.`,
     unattributed: (n) => `${n} finding(s) are attributed to no page (shared code, file outside any route) \u2014 counted in the overall audit, never spread across pages.`,
-    sourceBasis: 'A page marked "source" has no snapshot: the absence of a finding there does NOT mean conforming, and its rate covers only what the engine could decide elsewhere.'
+    sourceBasis: 'A page marked "source" has no snapshot: the absence of a finding there does NOT mean conforming, and its rate covers only what the engine could decide elsewhere.',
+    pageByPage: "page by page",
+    pagesCount: (n) => `${n} page(s)`,
+    testsCol: "Tests",
+    noPages: "No page in this run's scope: the sweep produced no snapshot. This is not an empty scoreboard, it is a missing one \u2014 the rendering criteria stay to assess.",
+    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._`,
+    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.`
   }
 };
 var MAX_ROWS = 50;
@@ -60201,23 +60223,106 @@ function perPageTable(result, standard = CORE2, lang = "en") {
   if (!scope.length) return "";
   attributePages(result, scope);
   const derived = derivePages(result, scope);
-  const out2 = [`### ${s.perPage}`, ""];
-  out2.push(`| ${s.page} | ${s.basis} | ${s.pageRate} | \u{1F534} | \u{1F7E0} | \u{1F7E1} |`, "| --- | --- | ---: | ---: | ---: | ---: |");
+  return [`### ${s.perPage}`, "", ...scoreboardTable(result, derived, standard, s, lang), "", ...basisCaveats(result, derived, s, lang)].join("\n");
+}
+function scoreboardTable(result, derived, standard, s, lang) {
+  const out2 = [`| ${s.page} | ${s.basis} | ${s.pageRate} | \u{1F534} | \u{1F7E0} | \u{1F7E1} |`, "| --- | --- | ---: | ---: | ---: | ---: |"];
   for (const pg of derived) {
-    const nc = pg.findings.filter((f) => !f.advisory);
-    const n = (sev) => nc.filter((f) => f.severity === sev).length;
+    const n = (sev) => severityCount(pg, sev);
+    const rows = pageCriterionRows(result, pg, standard, lang);
+    const cov = pageCoverage(rows);
     out2.push(
-      `| ${pg.name}${pg.auth ? " \u{1F512}" : ""} \u2014 \`${pg.url}\` | ${basisLabel(pg.basis, lang)} | ${formatRate(pg.conformancePct, pg.decided, pg.total)} | ${n("bloquant")} | ${n("majeur")} | ${n("mineur")} |`
+      `| ${pg.name}${pg.auth ? " \u{1F512}" : ""} \u2014 \`${pg.url}\` | ${basisLabel(pg.basis, lang)} | ${formatRate(pageRatePct(rows), cov.decided, cov.total)} | ${n("bloquant")} | ${n("majeur")} | ${n("mineur")} |`
     );
   }
-  out2.push("");
+  return out2;
+}
+function severityCount(pg, sev) {
+  return pg.findings.filter((f) => !f.advisory && f.severity === sev).length;
+}
+function basisCaveats(result, derived, s, lang) {
+  const out2 = [];
   const orphans = unattributedFindings(result).filter((f) => !f.advisory).length;
   if (orphans) out2.push(`> ${s.unattributed(orphans)}`, "");
   if (derived.some((p) => p.basis === "attributed")) out2.push(`> ${s.sourceBasis}`, "");
   const notAudited = pageBasisWarning("not-audited", lang);
   if (notAudited && derived.some((p) => p.basis === "not-audited")) out2.push(`> ${notAudited}`, "");
+  return out2;
+}
+function pageBlock(result, page, standard, lang) {
+  const s = S[lang];
+  const rows = pageCriterionRows(result, page, standard, lang);
+  const nc = rows.filter((r) => r.status === "NC");
+  const occurrences = page.findings.filter((f) => !f.advisory).length;
+  if (!nc.length && !occurrences) return void 0;
+  const cell = (v) => v.replace(/\|/g, "\\|");
+  const counts = `\u{1F534} ${severityCount(page, "bloquant")} \xB7 \u{1F7E0} ${severityCount(page, "majeur")} \xB7 \u{1F7E1} ${severityCount(page, "mineur")}`;
+  const withTests = nc.some((r) => r.tests.length);
+  const out2 = [
+    "<details>",
+    `<summary><b>${cell(page.name)}</b>${page.auth ? " \u{1F512}" : ""} \u2014 ${counts}</summary>`,
+    // GFM only renders Markdown inside <details> after a blank line; without it the table
+    // ships to the reader as literal pipes.
+    "",
+    `${pageTallyNote(pageTally(rows), lang)}`,
+    ""
+  ];
+  if (!nc.length) {
+    out2.push(s.noCriterionForFindings(occurrences), "", "</details>");
+    return out2.join("\n");
+  }
+  out2.push(withTests ? `| ${s.criterion} | ${s.testsCol} |` : `| ${s.criterion} |`, withTests ? "| --- | --- |" : "| --- |");
+  for (const r of nc) {
+    out2.push(withTests ? `| ${cell(r.label)} | ${r.tests.map((t2) => `\`${t2}\``).join(" ")} |` : `| ${cell(r.label)} |`);
+  }
+  out2.push("", "</details>");
   return out2.join("\n");
 }
+function pagesComment(result, opts = {}) {
+  const standard = opts.standard ?? CORE2;
+  const lang = opts.lang ?? "en";
+  const s = S[lang];
+  const stdLabel = isCore(standard) ? "WCAG 2.2 AA" : loadPack(standard).name;
+  const redirected = result.scope.redirected ?? [];
+  const scope = pagesOf(result);
+  const head = [`### ${s.title} \u2014 ${stdLabel} \xB7 ${s.pageByPage}`, ""];
+  const tail = [];
+  if (opts.artifactName) tail.push(s.artifact(opts.artifactName), "");
+  if (opts.runUrl) tail.push(s.runLink(opts.runUrl), "");
+  if (!scope.length) {
+    head.push(s.noPages, "");
+    if (redirected.length) head.push(...renderRedirected(redirected, lang), "");
+    return [...head, ...tail].join("\n").trimEnd();
+  }
+  attributePages(result, scope);
+  const derived = derivePages(result, scope);
+  const normative = findingsForStandard(result, standard).filter((f) => !f.advisory);
+  const blocking = normative.filter((f) => f.severity === "bloquant").length;
+  const rate = runRate(result, standard, lang);
+  head.push(blocking ? s.verdictFail(blocking) : normative.length ? s.verdictWarn : s.verdictPass, "");
+  head.push(`\`${result.date}\` \xB7 ${s.pagesCount(derived.length)} \xB7 **${rate.text}** ${s.rate}`, "");
+  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);
+  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), "");
+    body3.push(...basisCaveats(result, derived, s, lang));
+    if (redirected.length) body3.push(...renderRedirected(redirected, lang), "");
+    if (blocks.length) {
+      body3.push(`> ${s.pagesDetailNote}`, "");
+      body3.push(...blocks.slice(0, nBlocks2).flatMap((b) => [b, ""]));
+      if (nBlocks2 < blocks.length) body3.push(s.pagesClamped(blocks.length - nBlocks2), "");
+    }
+    return [...head, ...body3, ...tail].join("\n").trimEnd();
+  };
+  let nBlocks = blocks.length;
+  let nRows = derived.length;
+  while (nBlocks > 0 && assemble(nBlocks, nRows).length > COMMENT_LIMIT) nBlocks--;
+  while (nRows > 0 && assemble(nBlocks, nRows).length > COMMENT_LIMIT) nRows--;
+  return assemble(nBlocks, nRows);
+}
 
 // src/evidence.ts
 import { createHash as createHash6 } from "crypto";
@@ -65032,7 +65137,9 @@ function emitCiFormat(result, format, standard, lang, failOn) {
     console.error(md);
   }
   if (process.env.ULTRA11Y_PR_COMMENT === "1") {
-    const digest = prComment(result, {
+    const kind = commentKindFrom(process.env.ULTRA11Y_PR_COMMENT_KIND);
+    const render2 = kind === "pages" ? pagesComment : prComment;
+    const body3 = render2(result, {
       standard,
       lang,
       // The run is known before the artifact exists, so the link is always safe. The artifact
@@ -65041,7 +65148,7 @@ function emitCiFormat(result, format, standard, lang, failOn) {
       ...process.env.ULTRA11Y_RUN_URL ? { runUrl: process.env.ULTRA11Y_RUN_URL } : {},
       ...process.env.ULTRA11Y_ARTIFACT_NAME ? { artifactName: process.env.ULTRA11Y_ARTIFACT_NAME } : {}
     });
-    const c2 = pushPrComment(digest, standard);
+    const c2 = pushPrComment(body3, standard, kind);
     console.error(
       c2.ok ? lang === "fr" ? `ultra11y : commentaire de PR ${c2.action === "updated" ? "mis \xE0 jour" : c2.action === "created" ? "cr\xE9\xE9" : "ignor\xE9"}${c2.reason ? ` (${c2.reason})` : ""}.` : `ultra11y: PR comment ${c2.action}${c2.reason ? ` (${c2.reason})` : ""}.` : lang === "fr" ? `ultra11y : commentaire de PR impossible${c2.reason ? ` \u2014 ${c2.reason}` : ""}.` : `ultra11y: PR comment failed${c2.reason ? ` \u2014 ${c2.reason}` : ""}.`
     );

package/src/annotate.ts

@@ -11,6 +11,9 @@
 //    truncation of the one above: a reviewer scanning a PR needs the verdict, the coverage
 //    and the handful of distinct defects, then a link. Posting the full summary there is how
 //    a real audit (472 findings over 7 distinct selectors) became a wall nobody read.
+//  • `pagesComment()` — the PAGE-BY-PAGE grid, posted under its OWN sticky marker. The tier
+//    that sweeps pages and the tier that gates code both comment on the same pull request,
+//    and they answer different questions; sharing a marker made the sweep overwrite the gate.
 //
 // All are pure string builders. Nothing here decides anything: a finding that is not
 // anchorable in the repo tree (a URL-keyed dynamic result) is skipped rather than pinned
@@ -20,9 +23,20 @@ import { resolveMessage, resolveRemediation } from "./messages.js";
 import { findingsForStandard, packCriteriaForFinding } from "./standards/derive.js";
 import { CORE, type StandardId, isCore, loadPack } from "./standards/index.js";
 import { packReportGroups, reportCoverage, reportGroups } from "./report.js";
-import type { AuditResult, Finding, Lang, Severity } from "./types.js";
+import type { AuditResult, Finding, Lang, PageResult, Severity } from "./types.js";
 import { isUrlPath, repoRelative } from "./util.js";
-import { agentMarkNote, attributePages, basisLabel, derivePages, formatRate, pageBasisWarning, pagesOf, unattributedFindings } from "./pages.js";
+import {
+  agentMarkNote,
+  attributePages,
+  basisLabel,
+  derivePages,
+  formatRate,
+  pageBasisWarning,
+  pagesOf,
+  renderRedirected,
+  unattributedFindings,
+} from "./pages.js";
+import { pageCoverage, pageCriterionRows, pageRatePct, pageTally, pageTallyNote } from "./pages-report.js";
 
 export interface AnnotateOptions {
   standard?: StandardId;
@@ -112,6 +126,18 @@ const S = {
       `${n} constat(s) ne sont rattachés à aucune page (code partagé, fichier hors routes) — comptés dans l'audit global, jamais répartis d'office.`,
     sourceBasis:
       "Une page marquée « source » n'a pas d'instantané : l'absence de constat n'y vaut PAS conformité, et son taux ne porte que sur ce que le moteur a pu décider ailleurs.",
+    pageByPage: "page par page",
+    pagesCount: (n: number) => `${n} page(s)`,
+    testsCol: "Tests",
+    noPages:
+      "Aucune page dans le périmètre de ce run : le balayage n'a produit aucun instantané. Ce n'est pas un bilan vide, c'est un bilan absent — les critères au rendu restent à évaluer.",
+    pagesDetailNote:
+      "Un bloc par page portant au moins une non-conformité, et seulement ses critères **non conformes** — la grille complète (tous les critères de chaque page, avec leurs tests et leurs captures) vit dans l'artefact.",
+    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._`,
+    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.`,
   },
   en: {
     title: "ultra11y accessibility audit",
@@ -148,6 +174,17 @@ const S = {
       `${n} finding(s) are attributed to no page (shared code, file outside any route) — counted in the overall audit, never spread across pages.`,
     sourceBasis:
       'A page marked "source" has no snapshot: the absence of a finding there does NOT mean conforming, and its rate covers only what the engine could decide elsewhere.',
+    pageByPage: "page by page",
+    pagesCount: (n: number) => `${n} page(s)`,
+    testsCol: "Tests",
+    noPages:
+      "No page in this run's scope: the sweep produced no snapshot. This is not an empty scoreboard, it is a missing one — the rendering criteria stay to assess.",
+    pagesDetailNote:
+      "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._`,
+    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.`,
   },
 } as const;
 
@@ -346,22 +383,167 @@ export function perPageTable(result: AuditResult, standard: StandardId = CORE, l
   if (!scope.length) return "";
   attributePages(result, scope);
   const derived = derivePages(result, scope);
-  const out: string[] = [`### ${s.perPage}`, ""];
-  out.push(`| ${s.page} | ${s.basis} | ${s.pageRate} | 🔴 | 🟠 | 🟡 |`, "| --- | --- | ---: | ---: | ---: | ---: |");
+  // The summary has a 1 MiB budget: it never clamps, and passes every page.
+  return [`### ${s.perPage}`, "", ...scoreboardTable(result, derived, standard, s, lang), "", ...basisCaveats(result, derived, s, lang)].join("\n");
+}
+
+/** The scoreboard's rows. Extracted so the job summary and the page-by-page pull-request
+ *  comment draw ONE table from one projection — a second copy of this loop is a second chance
+ *  to disagree about what a page's rate is.
+ *
+ *  The rate comes from `pageCriterionRows`, in the ACTIVE standard's vocabulary — NOT from
+ *  `PageResult.conformancePct`, which is always WCAG-keyed. Under a pack the two count
+ *  different things, and the gap is visible in one glance: a page rendered « 50 % (4/55) »
+ *  here while its own sheet in the artifact counted those 4 against RGAA's 106, and the run
+ *  headline right above said `(9/106)`. One document, one standard, two denominators —
+ *  exactly the drift `formatRate` exists to prevent. */
+function scoreboardTable(result: AuditResult, derived: PageResult[], standard: StandardId, s: (typeof S)[Lang], lang: Lang): string[] {
+  const out: string[] = [`| ${s.page} | ${s.basis} | ${s.pageRate} | 🔴 | 🟠 | 🟡 |`, "| --- | --- | ---: | ---: | ---: | ---: |"];
   for (const pg of derived) {
-    const nc = pg.findings.filter((f) => !f.advisory);
-    const n = (sev: Severity): number => nc.filter((f) => f.severity === sev).length;
+    const n = (sev: Severity): number => severityCount(pg, sev);
+    const rows = pageCriterionRows(result, pg, standard, lang);
+    const cov = pageCoverage(rows);
     out.push(
-      `| ${pg.name}${pg.auth ? " 🔒" : ""} — \`${pg.url}\` | ${basisLabel(pg.basis, lang)} | ${formatRate(pg.conformancePct, pg.decided, pg.total)} | ${n("bloquant")} | ${n("majeur")} | ${n("mineur")} |`,
+      `| ${pg.name}${pg.auth ? " 🔒" : ""} — \`${pg.url}\` | ${basisLabel(pg.basis, lang)} | ${formatRate(pageRatePct(rows), cov.decided, cov.total)} | ${n("bloquant")} | ${n("majeur")} | ${n("mineur")} |`,
     );
   }
-  out.push("");
+  return out;
+}
+
+function severityCount(pg: PageResult, sev: Severity): number {
+  return pg.findings.filter((f) => !f.advisory && f.severity === sev).length;
+}
+
+/** The caveats a scoreboard must carry: findings no page could claim, and every basis weaker
+ *  than a snapshot actually present. One caveat per basis, from the shared sentences — a
+ *  « non audité » page must not be explained by the note that asserts it has no snapshot. */
+function basisCaveats(result: AuditResult, derived: PageResult[], s: (typeof S)[Lang], lang: Lang): string[] {
+  const out: string[] = [];
   const orphans = unattributedFindings(result).filter((f) => !f.advisory).length;
   if (orphans) out.push(`> ${s.unattributed(orphans)}`, "");
-  // One caveat per basis actually present, from the shared sentences — a « non audité » page must
-  // not be explained by the note that asserts it has no snapshot.
   if (derived.some((p) => p.basis === "attributed")) out.push(`> ${s.sourceBasis}`, "");
   const notAudited = pageBasisWarning("not-audited", lang);
   if (notAudited && derived.some((p) => p.basis === "not-audited")) out.push(`> ${notAudited}`, "");
+  return out;
+}
+
+/** 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.
+ *
+ *  Only the NC rows. A per-page norm has ~106 criteria and a sample has dozens of pages: the
+ *  full grid is thousands of rows, which is why it is an artifact and not a comment. What a
+ *  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 {
+  const s = S[lang];
+  const rows = pageCriterionRows(result, page, standard, lang);
+  const nc = rows.filter((r) => r.status === "NC");
+  const occurrences = page.findings.filter((f) => !f.advisory).length;
+  if (!nc.length && !occurrences) return undefined;
+  const cell = (v: string): string => v.replace(/\|/g, "\\|");
+  const counts = `🔴 ${severityCount(page, "bloquant")} · 🟠 ${severityCount(page, "majeur")} · 🟡 ${severityCount(page, "mineur")}`;
+  const withTests = nc.some((r) => r.tests.length);
+  const out: string[] = [
+    "<details>",
+    `<summary><b>${cell(page.name)}</b>${page.auth ? " 🔒" : ""} — ${counts}</summary>`,
+    // GFM only renders Markdown inside <details> after a blank line; without it the table
+    // ships to the reader as literal pipes.
+    "",
+    `${pageTallyNote(pageTally(rows), lang)}`,
+    "",
+  ];
+  // The summary line counts OCCURRENCES; the table below lists CRITERIA. They are two
+  // projections, and they can legitimately disagree: a finding whose rule sits outside every
+  // criterion's applicability under this standard is counted and decides nothing. Left
+  // unsaid, that page shows « 🟠 1 » over an empty block and the reader is owed an
+  // explanation rather than an inference.
+  if (!nc.length) {
+    out.push(s.noCriterionForFindings(occurrences), "", "</details>");
+    return out.join("\n");
+  }
+  out.push(withTests ? `| ${s.criterion} | ${s.testsCol} |` : `| ${s.criterion} |`, withTests ? "| --- | --- |" : "| --- |");
+  for (const r of nc) {
+    out.push(withTests ? `| ${cell(r.label)} | ${r.tests.map((t) => `\`${t}\``).join(" ")} |` : `| ${cell(r.label)} |`);
+  }
+  out.push("", "</details>");
   return out.join("\n");
 }
+
+/** The PAGE-BY-PAGE pull-request comment.
+ *
+ *  A second document under a second marker, for a second tier. The digest above answers
+ *  "what is broken in this diff"; this one answers "which pages conform, and on which
+ *  criteria" — the question a per-page standard like RGAA is actually written in. They cannot
+ *  share a sticky, and they did: the sweep's 337 files and 684 occurrences overwrote the four
+ *  actionable findings of the code gate on every run, which is why the sweep was muzzled
+ *  rather than fixed.
+ *
+ *  Nothing is decided here either. The scoreboard is the projection the job summary draws,
+ *  and each page's non-conformities come from `pageCriterionRows` — the very rows the per-page
+ *  sheet renders into the artifact. */
+export function pagesComment(result: AuditResult, opts: AnnotateOptions & { runUrl?: string; artifactName?: string } = {}): string {
+  const standard = opts.standard ?? CORE;
+  const lang = opts.lang ?? "en";
+  const s = S[lang];
+  const stdLabel = isCore(standard) ? "WCAG 2.2 AA" : loadPack(standard).name;
+  const redirected = result.scope.redirected ?? [];
+  const scope = pagesOf(result);
+
+  const head: string[] = [`### ${s.title} — ${stdLabel} · ${s.pageByPage}`, ""];
+  const tail: string[] = [];
+  if (opts.artifactName) tail.push(s.artifact(opts.artifactName), "");
+  if (opts.runUrl) tail.push(s.runLink(opts.runUrl), "");
+
+  // No page in scope is not a clean report, it is an ABSENT one. Saying so is what tells a
+  // reviewer the tier ran at all — silence here reads as "nothing to report".
+  if (!scope.length) {
+    head.push(s.noPages, "");
+    if (redirected.length) head.push(...renderRedirected(redirected, lang), "");
+    return [...head, ...tail].join("\n").trimEnd();
+  }
+
+  attributePages(result, scope);
+  const derived = derivePages(result, scope);
+  const normative = findingsForStandard(result, standard).filter((f) => !f.advisory);
+  const blocking = normative.filter((f) => f.severity === "bloquant").length;
+  const rate = runRate(result, standard, lang);
+
+  head.push(blocking ? s.verdictFail(blocking) : normative.length ? s.verdictWarn : s.verdictPass, "");
+  head.push(`\`${result.date}\` · ${s.pagesCount(derived.length)} · **${rate.text}** ${s.rate}`, "");
+  if (rate.agentRuled) head.push(`> ${agentMarkNote(lang)}`, "");
+
+  // Worst first, so the pages the size clamp drops are the least severe ones.
+  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 is string => b !== undefined);
+
+  // WHOLE blocks and WHOLE rows, never a slice of the finished string — cutting a rendered
+  // document at a byte offset lands mid-row and GFM then renders a broken table. The detail
+  // goes first because the scoreboard is the half that cannot be reconstructed from the
+  // artifact link alone.
+  const assemble = (nBlocks: number, nRows: number): string => {
+    const body: string[] = [...scoreboardTable(result, derived.slice(0, nRows), standard, s, lang), ""];
+    if (nRows < derived.length) body.push(s.scoreboardClamped(derived.length - nRows), "");
+    body.push(...basisCaveats(result, derived, s, lang));
+    if (redirected.length) body.push(...renderRedirected(redirected, lang), "");
+    if (blocks.length) {
+      body.push(`> ${s.pagesDetailNote}`, "");
+      body.push(...blocks.slice(0, nBlocks).flatMap((b) => [b, ""]));
+      if (nBlocks < blocks.length) body.push(s.pagesClamped(blocks.length - nBlocks), "");
+    }
+    return [...head, ...body, ...tail].join("\n").trimEnd();
+  };
+
+  let nBlocks = blocks.length;
+  let nRows = derived.length;
+  while (nBlocks > 0 && assemble(nBlocks, nRows).length > COMMENT_LIMIT) nBlocks--;
+  while (nRows > 0 && assemble(nBlocks, nRows).length > COMMENT_LIMIT) nRows--;
+  return assemble(nBlocks, nRows);
+}

package/src/cli.ts

@@ -18,7 +18,7 @@ import { runAudit } from "./audit.js";
 import { decide, type PreToolUsePayload } from "./hook.js";
 import { writeReport, untestedNeedsRendering, partialAuditBanner } from "./report.js";
 import { writePrd, prdUnits, type PrdFormat } from "./prd.js";
-import { pushPrComment } from "./pr-comment.js";
+import { commentKindFrom, pushPrComment } from "./pr-comment.js";
 import { buildTickets } from "./tickets/grain.js";
 import { pushTickets } from "./tickets/push.js";
 import { autoProvider, createProvider, isProviderId } from "./tickets/registry.js";
@@ -57,7 +57,7 @@ import { installForTargets, parseTargets, statusReport, uninstallForTargets } fr
 import { agentsMdBlock } from "./install/agents-md.js";
 import { auditSummary, captureCoverageSummary } from "./output.js";
 import { toSarif } from "./sarif.js";
-import { annotations, prComment, stepSummary } from "./annotate.js";
+import { annotations, pagesComment, prComment, stepSummary } from "./annotate.js";
 import { evidenceNotice, writeEvidence } from "./evidence.js";
 import { writeHtml } from "./html-emit.js";
 import { PAGES_DIR, readSnapshots, validateSnapshotMeta, writeSnapshot, type AxNode, type BoxDigest, type CssDigest, type StyleDigest } from "./snapshot.js";
@@ -789,7 +789,12 @@ function emitCiFormat(result: AuditResult, format: CiFormat, standard: StandardI
   // reader who went looking for it; a PR comment has 64 KiB and a reader scanning a diff.
   // Posting one string to both is what turned a 700-finding audit into a wall on the PR.
   if (process.env.ULTRA11Y_PR_COMMENT === "1") {
-    const digest = prComment(result, {
+    // WHICH document this run posts. Anything but an explicit `pages` is the historical
+    // digest under the historical marker: an unset — or misspelled — variable must degrade to
+    // the behaviour every existing workflow already depends on, never to silence.
+    const kind = commentKindFrom(process.env.ULTRA11Y_PR_COMMENT_KIND);
+    const render = kind === "pages" ? pagesComment : prComment;
+    const body = render(result, {
       standard,
       lang,
       // The run is known before the artifact exists, so the link is always safe. The artifact
@@ -798,7 +803,7 @@ function emitCiFormat(result: AuditResult, format: CiFormat, standard: StandardI
       ...(process.env.ULTRA11Y_RUN_URL ? { runUrl: process.env.ULTRA11Y_RUN_URL } : {}),
       ...(process.env.ULTRA11Y_ARTIFACT_NAME ? { artifactName: process.env.ULTRA11Y_ARTIFACT_NAME } : {}),
     });
-    const c = pushPrComment(digest, standard);
+    const c = pushPrComment(body, standard, kind);
     console.error(
       c.ok
         ? lang === "fr"

package/src/pages-report.ts

@@ -218,6 +218,15 @@ export function pageTally(rows: PageCriterionRow[]): { c: number; nc: number; na
   };
 }
 
+/** The tally as one sentence — « X conforme(s) · Y non conforme(s) · … ». Exported for the
+ *  same reason `formatRate` is: the sheet, the HTML and the pull-request grid all state a
+ *  page's standing, and a surface that phrases its own is a surface that will drift. The
+ *  « à évaluer » count is the half readers drop, and it is the one that says how much of the
+ *  page nobody has ruled on yet. */
+export function pageTallyNote(t: { c: number; nc: number; na: number; manual: number }, lang: Lang): string {
+  return L[lang].tally(t.c, t.nc, t.na, t.manual);
+}
+
 /** The rate's denominator, extracted so the sheet's « Couverture » line and the index cell are
  *  computed ONCE. They disagreed before: the sheet said 2/106 while the index printed a bare
  *  100 %, and the index is the artefact people paste into a pull request. */
@@ -259,7 +268,7 @@ export function renderPageReport(result: AuditResult, page: PageResult, opts: Pa
   const cov = pageCoverage(rows);
   const rate = pageRatePct(rows);
   out.push(`- **${s.rate}** : **${rate === null ? "—" : `${rate} %`}** _(${s.rateNote})_`);
-  out.push(`- ${s.tally(t.c, t.nc, t.na, t.manual)}`);
+  out.push(`- ${pageTallyNote(t, lang)}`);
   // The rate alone reads as a verdict on the page. Naming the denominator next to it is
   // what stops "100 %" over six decided criteria from being quoted as a conformant page.
   out.push(`- ${s.coverage(cov.decided, cov.total)}`, "");