ultra11y 2.22.0 → 2.23.0

package/skills/ultra11y/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: ultra11y
-description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibility and produce a dated auditor-conformance report, OR to AUTHOR/REVIEW accessible markup (native-HTML-first, ARIA last). An install-free engine (`node scripts/ultra11y.mjs`, no keys) runs 72 static checks tied to WCAG criteria — alt/lang/title, unlabeled fields, empty links/buttons, tables, headings, ARIA vocabulary, label-in-name, autocomplete — measured against the official W3C ACT corpus. The engine decides 3 of the 55 criteria; the AI agent adjudicates the 38 judgment ones from harvested evidence + a per-criterion decision protocol (`verify --manual`, gated, fannable via `orchestrate`), and the 14 rendering ones go to `scan` — never silently conforming. Library/SFC code is audited as RENDERED captures (`render --setup`); country standards are pluggable packs (`--standard rgaa`, `scan --sample`). check/verify reject invented non-conformities. Triggers: 'audit WCAG/a11y', 'make accessible', 'fix a11y', 'audit RGAA'."
+description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibility and produce a dated auditor-conformance report, OR to AUTHOR/REVIEW accessible markup (native-HTML-first, ARIA last). An install-free engine (`node scripts/ultra11y.mjs`, no keys) runs 78 static checks tied to WCAG criteria — alt/lang/title, unlabeled fields, empty links/buttons, tables, headings, ARIA vocabulary, label-in-name, autocomplete — measured against the official W3C ACT corpus. The engine decides 3 of the 55 criteria; the AI agent adjudicates the 38 judgment ones from harvested evidence + a per-criterion decision protocol (`verify --manual`, gated, fannable via `orchestrate`), and the 14 rendering ones go to `scan` — never silently conforming. Library/SFC code is audited as RENDERED captures (`render --setup`); country standards are pluggable packs (`--standard rgaa`, `scan --sample`). check/verify reject invented non-conformities. Triggers: 'audit WCAG/a11y', 'make accessible', 'fix a11y', 'audit RGAA'."
 license: MIT
 metadata:
-  version: 2.22.0
+  version: 2.23.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup
@@ -83,6 +83,10 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 | `references/verify.md` | The `check`/`verify` gates |
 | `references/false-positives.md` | Where a finding may still be wrong, and how to refute it |
 | `references/rendered.md` · `references/automation.md` | Auditing produced HTML, captures, hooks and CI |
+| `references/ci.md` | `--format sarif\|github`: inline PR annotations, code scanning, job summary |
+| `references/pages.md` | Page snapshots + the per-page criterion grid (`pages`), and its honesty rules |
+| `references/e2e.md` | `render --e2e`: auditing a page during your Playwright/Cypress run |
+| `references/devtools.md` | `dev`: the live overlay while you build, and the per-page dashboard |
 | `references/dynamic.md` | The `scan` tier: runtimes, probes, authenticated pages |
 | `references/scale.md` | Focusing an audit on a large repository |
 | `references/fix.md` · `references/correction.md` | Applying fixes, by priority, without regressions |
@@ -153,6 +157,38 @@ Domain knowledge first, then the tooling. Read the one that matches the question
   "block only NEW non-conformities" variant. For library/SFC code, commit rendered
   **captures** (`render --setup`) and stage them so the real semantic HTML is what's
   checked (`audit --require-captures`); read **`references/automation.md`**.
+- **"Show me the problems while I build the page"** → `dev --next` writes a one-line overlay
+  component and `dev` starts a loopback side-car: a floating panel lists the current page's
+  non-conformities, each opening its `file:line` in your editor, and `http://127.0.0.1:4111`
+  accumulates the per-page grid as you browse. Renders nothing outside development; read
+  **`references/devtools.md`**.
+- **"Check a page during our E2E tests"** → `render --e2e` writes Playwright/Cypress fixtures
+  that audit the page **as your test left it** (logged in, form filled, modal open) — state a
+  separate `scan` run does not have — and persist each checked page as a snapshot. `failOn`
+  gates the test; `failOn: false` records without failing, which is how you adopt it on an
+  existing backlog; read **`references/e2e.md`**.
+- **"Audit the real PAGE, not the component"** → a **page snapshot**
+  (`.ultra11y/pages/<id>/`) is the whole rendered document plus the browser-only signals
+  (computed styles, boxes, a11y tree, screenshot), ingested by `audit` automatically. Because
+  it is a FULL document, the page-scoped rules run on it — that is where RGAA 8.3 (lang),
+  8.5/8.6 (title) and 12.6 become decidable at all; read **`references/pages.md`**.
+- **"Decide the rendering criteria without a browser in CI"** → once a page snapshot exists,
+  the **rendered tier** runs inside the ordinary `audit`: computed-style contrast
+  (RGAA 3.2/10.5), screenshot-measured contrast for text over a gradient/image (the CSSOM
+  blind spot axe-core shares), and colour-only link identification (**RGAA 10.6**, previously
+  undecidable). Each leaves the criterion `manual` when it cannot measure — never a guess;
+  read **`references/pages.md`**.
+- **"Give me the RGAA grid, page by page"** → `pages --in audits/audit-latest.json --standard
+  rgaa` (also embedded in `report`): one row per criterion, one column per page, rebuilt from
+  the committed audit.json alone. Two rules hold: a finding is attributed to a page only when
+  something SAYS so (else it is reported as unattributed, never spread), and `C` by silence is
+  earned only by a page whose real DOM was audited — a source-only page keeps its undecided
+  criteria « à évaluer »; read **`references/pages.md`**.
+- **"Show the findings ON the pull request, not just a red job"** → `--format sarif` (upload
+  to code scanning → inline annotations at the right file:line) or `--format github`
+  (`::error::` workflow commands + a `$GITHUB_STEP_SUMMARY` table) — from `report
+  --standard rgaa` when you want the pack's criteria rather than WCAG's; read
+  **`references/ci.md`**.
 - **"Make this code accessible / review it"** → audit the snippet
   (`audit - < component.html`) native-first; read **`references/authoring.md`** and
   **`references/forbidden-patterns.md`**.

package/skills/ultra11y/references/ci.md

@@ -0,0 +1,165 @@
+# CI — the shipped action, SARIF, annotations, job summary
+
+## The action
+
+The whole surface in one step. The engine ships **inside** the action (one bundled `.mjs`,
+zero dependencies), so there is nothing to install, no `setup-node`, and no version that can
+drift from the action's own.
+
+```yaml
+permissions:
+  contents: read
+  security-events: write   # SARIF upload; without it the annotations still report
+  pull-requests: write     # only if you set `comment: 'true'`
+
+steps:
+  - uses: actions/checkout@v4
+    with: { fetch-depth: 0 }        # the diff gate needs the base ref
+  - uses: maxgfr/ultra11y@v2      # or pin the exact version, as `init --ci` does
+    with:
+      since: auto                   # the PR's base branch
+      standard: rgaa
+      fail-on: blocking
+      baseline: audits/baseline.json
+      comment: 'true'
+```
+
+Page by page, with a real browser, in the same step:
+
+```yaml
+  - uses: maxgfr/ultra11y@v2
+    with:
+      standard: rgaa
+      start: npm run start
+      wait-on: http://localhost:3000
+      urls: http://localhost:3000 http://localhost:3000/contact
+      # …or `sample: 'true'` to scan the sample declared in .ultra11yrc.json
+```
+
+`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. `@v2` is a moving major alias
+the release workflow keeps pointing at the latest release, for teams who would rather take
+fixes automatically. Never `@main`: it would change under you without a version to blame.
+
+**Order matters, and it is deliberate**: the audit runs first, then SARIF, annotations, the
+summary, the comment and the report — and the **gate runs last**. A failing audit has
+therefore already produced every surface, so a red job is never a dead end. `fail-on: ''`
+turns the gate off entirely (report-only), which is how you adopt this on an existing backlog;
+`baseline` is the other way — only NEW non-conformities can fail.
+
+The SARIF upload is `continue-on-error`: a repository without Advanced Security keeps its
+annotations instead of failing. Each upload carries `category: ultra11y-<standard>`, so a WCAG
+run and an RGAA run coexist rather than overwriting each other. The Markdown report goes
+through `check` before being uploaded, so CI cannot publish a report citing an invented
+criterion.
+
+# The `--format` renderings
+
+A gate tells a developer *that* the build failed; it does not put the non-conformity **on the
+line of code that caused it**. These two renderings do — they are what the action posts, and
+you can run them yourself outside it.
+
+Nothing new is measured here. Both are projections of the same `AuditResult`.
+
+```
+node scripts/ultra11y.mjs audit  "src/**/*.tsx" --jsx --format sarif  > a11y.sarif
+node scripts/ultra11y.mjs audit  "src/**/*.tsx" --jsx --format github
+node scripts/ultra11y.mjs report --in audits/audit-latest.json --standard rgaa --format sarif > rgaa.sarif
+```
+
+## `--format sarif` — inline PR annotations via code scanning
+
+SARIF 2.1.0, the format GitHub code scanning ingests. Upload it and every finding becomes an
+annotation on the right file and line of the pull request, plus an entry in the Security tab.
+
+```yaml
+- run: node scripts/ultra11y.mjs audit "src/**/*.tsx" --jsx --format sarif > a11y.sarif
+- uses: github/codeql-action/upload-sarif@v3
+  with: { sarif_file: a11y.sarif }
+```
+
+What the projection guarantees:
+
+- **Levels.** `bloquant → error`, `majeur → warning`, `mineur → note`. An **advisory**
+  (non-normative recommendation) is **never** an `error`, whatever its severity rank — it is
+  always a `note`, so a recommendation cannot fail a reviewer's build on principle.
+- **Stable alert identity.** `partialFingerprints` reuses `findingId()` — the *same* identity
+  the baseline gate uses — so an alert survives line drift instead of being closed and
+  reopened on every edit above it.
+- **Rules table.** One entry per `ruleId`, tagged `accessibility`, `wcag:<sc>` and, under
+  `--standard`, `<pack>:<criterion>` (e.g. `rgaa:1.1`), with the WCAG *Understanding* page as
+  `helpUri`.
+- **Repo-relative URIs.** An absolute path is relativised against the working directory;
+  GitHub matches alerts against the checkout and would silently drop an absolute one.
+- **No invented locations.** A finding keyed to a **URL** (a `scan` result the host-anchor
+  resolver could not map back to source) is emitted with **no** physical location and its URL
+  in `properties.url`. Pinning it to a guessed `file:line` is exactly the class of error the
+  engine exists to refuse.
+
+## `--format github` — annotations without code scanning
+
+Advanced Security is not available on every plan. This mode writes
+`::error file=…,line=…,col=…,title=…::` workflow commands to **stdout**, which every GitHub
+plan renders inline on the diff, and appends a Markdown job summary to
+`$GITHUB_STEP_SUMMARY` (severity table, and the per-page synthesis once a page sample has
+been scanned and merged). With no `$GITHUB_STEP_SUMMARY` set, the summary goes to stderr so a
+local run still shows it.
+
+URL-keyed findings are **skipped** for annotations — there is no repo line to point at — and
+counted in the summary instead, so they are never silently dropped.
+
+## Which command to run it from
+
+`audit` is always WCAG-keyed: it takes **no** `--standard`, by design (a pack is a derived
+view, never a second source of truth). So:
+
+| You want | Run |
+|---|---|
+| WCAG-keyed CI output, one shot | `audit … --format sarif` |
+| **RGAA**-keyed CI output | `audit … --out audits` then `report --in audits/audit-latest.json --standard rgaa --format sarif` |
+| Only what the PR introduced | `audit --since origin/main --baseline audits/baseline.json --format sarif` |
+
+In `--baseline` gate mode the CI rendering covers **exactly the new findings** — the subject
+of the gate is the regression, not the backlog, so a PR is annotated with what it introduced
+and the existing backlog stays out of the diff.
+
+Uploading two SARIF files in one workflow (a source audit and a page scan) is supported:
+each run carries a distinct `automationDetails.id` (`ultra11y/<standard>/`), so GitHub keeps
+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).
+
+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
+listing the existing comments fails (permissions, rate limit) it creates a new one — a
+duplicate comment is a far smaller harm than dropping the report.
+
+## How this repo publishes itself (npm trusted publishing)
+
+ultra11y's own release workflow holds **no npm token**. It publishes by OIDC: the job asks
+GitHub for a short-lived id-token (`permissions: id-token: write`) and exchanges it with
+registry.npmjs.org for a credential scoped to this package. Nothing long-lived is stored, so
+there is no secret to leak or rotate.
+
+Two things it depends on, both easy to break silently:
+
+- **A trusted publisher** configured on npmjs.com for the package, naming this repository and
+  **this workflow file**. Rename `release.yml` and the exchange stops matching.
+- **npm >= 11.5.1** on the runner. `@semantic-release/npm` only *pre-flights* the exchange;
+  the publish itself is `npm publish`, and the CLI does its own OIDC handshake. Node 24 still
+  ships an older 11.x, so the workflow upgrades the CLI explicitly.
+
+The package must exist before a trusted publisher can be attached to it, so the **first**
+publish is manual — `npm publish` from a logged-in shell, after `pnpm run build`. The name is
+unscoped and `publishConfig.access` is set, so nothing else is needed. Every release after
+that is tokenless.
+
+If the exchange fails, `@semantic-release/npm` logs why and falls back to demanding a token —
+it does not publish unauthenticated.

package/skills/ultra11y/references/criteria.md

@@ -31,20 +31,20 @@ criteria that map to it. SC ids, titles and levels are derived from the W3C sour
 | 1.3.1 | Info and Relationships | A | judgment | fieldset-legend-missing, data-table-no-headers, table-caption-missing, layout-table-data-markup, heading-order-skip, h1-missing, h1-multiple, list-structure, dl-structure, empty-heading, label-for-dangling, missing-main-landmark, multiple-main-landmark, sortable-header-no-aria-sort, nav-landmark-missing, nav-landmark-unnamed, aria-required-parent, headers-attr-dangling, th-no-data-cells, radio-checkbox-group-ungrouped, table-empty-data-cell, css-generated-content-informative | 3.1, 5.1, 5.2, 5.4, 5.5, 5.6, 5.7, 5.8, 7.3, 8.9, 9.1, 9.2, 9.3, 9.4, 10.1, 10.2, 11.1, 11.5, 11.6, 11.7, 11.8, 12.6, 13.3, 13.4 |
 | 1.3.2 | Meaningful Sequence | A | judgment | — | 5.3, 8.10, 10.1, 10.3, 10.8, 13.3, 13.4 |
 | 1.3.3 | Sensory Characteristics | A | judgment | — | 10.9, 10.10 |
-| 1.3.4 | Orientation | AA | needs-rendering | — | 13.9 |
+| 1.3.4 | Orientation | AA | needs-rendering | rendered-orientation-lock | 13.9 |
 | 1.3.5 | Identify Input Purpose | AA | judgment | field-purpose-incomplete, autocomplete-token-invalid | 11.13 |
 
 ## 1.4 Distinguishable
 
 | SC | Title | Level | Automatability | Rules | RGAA |
 |---|---|---|---|---|---|
-| 1.4.1 | Use of Color | A | needs-rendering | — | 3.1, 10.6, 10.7, 10.9, 10.10 |
+| 1.4.1 | Use of Color | A | needs-rendering | rendered-link-colour-only | 3.1, 10.6, 10.7, 10.9, 10.10 |
 | 1.4.2 | Audio Control | A | static | autoplay-media | 4.10 |
-| 1.4.3 | Contrast (Minimum) | AA | needs-rendering | contrast-literal | 3.2, 10.5 |
+| 1.4.3 | Contrast (Minimum) | AA | needs-rendering | contrast-literal, rendered-contrast, rendered-contrast-pixel | 3.2, 10.5 |
 | 1.4.4 | Resize Text | AA | needs-rendering | meta-viewport-zoom-block | 10.4 |
 | 1.4.5 | Images of Text | AA | needs-rendering | — | 1.8 |
 | 1.4.10 | Reflow | AA | needs-rendering | — | 10.11 |
-| 1.4.11 | Non-text Contrast | AA | needs-rendering | — | 3.3 |
+| 1.4.11 | Non-text Contrast | AA | needs-rendering | rendered-nontext-contrast | 3.3 |
 | 1.4.12 | Text Spacing | AA | needs-rendering | — | 10.12 |
 | 1.4.13 | Content on Hover or Focus | AA | needs-rendering | — | 10.13 |
 
@@ -79,7 +79,7 @@ criteria that map to it. SC ids, titles and levels are derived from the W3C sour
 | 2.4.4 | Link Purpose (In Context) | A | judgment | link-empty-name, icon-only-control-unnamed | 6.1, 6.2 |
 | 2.4.5 | Multiple Ways | AA | judgment | — | 12.1, 12.3, 12.4 |
 | 2.4.6 | Headings and Labels | AA | judgment | — | 9.1, 11.1, 11.2 |
-| 2.4.7 | Focus Visible | AA | needs-rendering | — | 7.3, 10.7 |
+| 2.4.7 | Focus Visible | AA | needs-rendering | rendered-focus-not-visible | 7.3, 10.7 |
 | 2.4.11 | Focus Not Obscured (Minimum) | AA | needs-rendering | — | — |
 
 ## 2.5 Input Modalities

package/skills/ultra11y/references/devtools.md

@@ -0,0 +1,67 @@
+# See the defects while you build — `dev`
+
+An audit at the end of a sprint finds the same defect fifty times. The cheapest moment to fix
+an accessibility problem is the moment you write it, in the page you are looking at.
+
+```
+node scripts/ultra11y.mjs dev --next    # write the overlay component (once)
+node scripts/ultra11y.mjs dev           # start the side-car, then run your app as usual
+```
+
+Two halves, deliberately separate:
+
+- **the side-car** — a `node:http` server (a builtin: the zero-dependency promise holds) on
+  `http://127.0.0.1:4111`. It receives collected pages, writes them as snapshots, audits them,
+  and serves the dashboard.
+- **the overlay** — framework-agnostic vanilla JS, served by the side-car and loaded by the
+  app. A floating panel lists the current page's non-conformities; each links to its
+  `file:line` and opens it in your editor through Next's own `/__nextjs_launch-editor`
+  endpoint. It re-checks on every client-side navigation, not just the first paint.
+
+## Wiring it into Next
+
+`dev --next` writes `.ultra11y/next/overlay.jsx`. You add one line:
+
+```tsx
+// app/layout.tsx
+import { Ultra11yOverlay } from "../.ultra11y/next/overlay";
+
+<body>{children}<Ultra11yOverlay /></body>
+```
+
+A component you import, not a bundler hack — deliberately. Custom webpack configuration does
+not exist under Turbopack (the Next default), and entry-point patching breaks across Next
+versions; a client component does not. It **renders nothing outside development**: the whole
+body short-circuits on `NODE_ENV`, so shipping it is inert.
+
+The same overlay serves any framework — point a `<script src="http://127.0.0.1:4111/overlay.js">`
+at it in dev and set `window.__ULTRA11Y_ENDPOINT__` if you moved the port.
+
+## The dashboard
+
+`http://127.0.0.1:4111` renders the **per-page criterion grid** (`references/pages.md`) for
+every page you have visited: one row per criterion, one column per page, in the standard you
+chose (`--standard rgaa`). It is a self-contained page — no external stylesheet, no script, no
+network — and it accumulates as you browse. Visit five pages of your app and you have the
+beginnings of a real échantillon, snapshotted and re-auditable offline.
+
+## Two things worth knowing
+
+**The overlay removes itself from the page before collecting.** It is DOM, and the collector
+serializes DOM: left in place it would be captured, audited, and would report non-conformities
+about *itself* — and, worse, its element would shift every document-order index by one and
+break the join between the styles digest and the DOM. So the host is detached for the duration
+of the collection and re-attached immediately after. It also lives in a shadow root, so the
+app's CSS cannot reach it and its own cannot leak.
+
+**The server binds to loopback only.** It writes files and returns audit results, so it is
+never reachable from the network — `127.0.0.1`, never `0.0.0.0`. CORS is permissive because
+the app runs on a different port; the loopback bind is what actually contains it. This is a
+development tool, not something to expose.
+
+## What it does NOT do
+
+It runs the same static engine as `audit`, plus the rendered tier when the page carries
+signals. It does not adjudicate the judgment criteria — alt relevance, link purpose, reading
+order remain yours (`verify --manual`) — and a clean panel means "the engine found nothing
+here", never "this page is accessible".

package/skills/ultra11y/references/e2e.md

@@ -0,0 +1,112 @@
+# Run the audit during your E2E tests (Playwright / Cypress)
+
+`scan` launches its **own** browser after the fact. That is a second run of your app, with
+none of the state your tests just built: no login, no filled form, no opened modal. The E2E
+integration inverts it — the audit runs **inside the run you already have**, on the page as
+your test left it.
+
+```
+node scripts/ultra11y.mjs render --e2e            # detects Playwright / Cypress, writes the fixtures
+node scripts/ultra11y.mjs render --e2e --runner cypress   # or force one
+```
+
+Fixtures land in `.ultra11y/e2e/`. They are **generated files**, not a published library: no
+install, and they target the engine build that produced them (`ULTRA11Y=<path>` overrides).
+
+## Playwright
+
+```js
+import { test, checkA11y } from "../.ultra11y/e2e/playwright.mjs";
+
+test("home page is accessible", async ({ page, ultra11y }) => {
+  await page.goto("/");
+  await ultra11y({ as: "accueil" });                 // via the fixture
+});
+
+// …or with no fixture, on any page object:
+await checkA11y(page, { as: "contact", failOn: "major" });
+```
+
+## Cypress
+
+Cypress test code runs in the **browser**, which cannot write to disk, so the collected page
+round-trips through a Node task. Two files, two wiring points:
+
+```js
+// cypress.config.js
+import ultra11y from "./.ultra11y/e2e/cypress-plugin.mjs";
+export default defineConfig({ e2e: { setupNodeEvents(on, config) { ultra11y(on); return config; } } });
+
+// cypress/support/e2e.js  (the supportFile)
+import "../../.ultra11y/e2e/cypress-commands.mjs";
+```
+
+```js
+cy.visit("/");
+cy.ultra11y({ as: "accueil" });
+```
+
+## Options
+
+| Option | Effect |
+|---|---|
+| `as` | the page **id** (directory name). Defaults to the slugified URL path |
+| `name` | human page name for the report. Defaults to the document title |
+| `failOn` | `"blocking"` (default), `"major"`, `"minor"`, or `false` to record without ever failing |
+| `auth` | mark the page as sitting behind authentication |
+| `sources` | source files that rendered it — findings are then reported against **your code** |
+| `notes` | reproduction notes carried into the auditor ticket |
+
+`failOn: false` is the useful one for adoption: record every page first, look at the real
+backlog, then turn the gate on.
+
+## What it does, exactly
+
+Two steps per checked page, and the fixture owns neither:
+
+1. the page is collected **in the browser** with the engine's own collector — DOM,
+   computed-style digest, bounding boxes;
+2. the payload is piped to `ultra11y snapshot write`, which persists
+   `.ultra11y/pages/<id>/` **and** audits it, returning the `AuditResult`.
+
+So the fixture knows nothing about the snapshot format, the provenance comment or the audit —
+it is a pipe. There is no second implementation to drift out of sync, and any other producer
+can use the same command.
+
+## One difference between the two runners
+
+The Playwright fixture also captures a **viewport screenshot** and sends it with the payload,
+which is what feeds the pixel tier (contrast over a gradient or a background image — the case
+computed styles cannot express). Pass `screenshot: false` to skip it.
+
+The Cypress command does **not**: `cy.screenshot()` writes to a path Cypress chooses and
+names, so wiring it back into the payload reliably is more machinery than it is worth. A
+Cypress-collected page therefore gets every rule except `rendered-contrast-pixel`, and that
+criterion simply stays undecided for it rather than being guessed. If you need the pixel tier,
+scan those pages separately (`scan <url>`), or capture them with Playwright.
+
+Everything else — the DOM, the computed styles, the boxes and the stylesheets — is identical
+between the two.
+
+## Why the artefact matters more than the assertion
+
+A failing assertion tells one developer, once. The **snapshot** is the durable part:
+
+- It records the page as the browser actually built it, so the same page can be re-audited
+  **offline, with no browser** — which is how CI decides rendering criteria without booting
+  the app, and how the report speaks page by page.
+- Because it is a full document (a component capture is a fragment), the page-scoped rules run
+  on it: **RGAA 8.3** (`lang`), **8.5/8.6** (`title`), 12.6 (`main`). Those are not decidable
+  from a component render, nor from source once a framework injects the document shell.
+- Every finding carries `page` **and** `origin.sourceFile`, so a defect found at render time
+  is reported against the code that caused it.
+
+Commit `.ultra11y/pages/` to gate on it (`audit` ingests the directory automatically). Add
+`sources` to your options and the failure message names your component instead of `dom.html`.
+
+## Scoping
+
+`snapshot write` audits **only the page it was handed** — never the whole pages tree — so a
+test checking the contact page is never failed by the home page's backlog. Findings are
+filtered to non-advisory ones before the gate: a non-normative recommendation never fails a
+test.

package/skills/ultra11y/references/judgment.md

@@ -88,3 +88,28 @@ Then `node scripts/ultra11y.mjs verify --apply VERIFY.todo.json` is green again
 > For a country standard's own test grid, `criteria --standard rgaa <id>` shows the RGAA tests
 > behind a WCAG SC. The pre-completion checklist stops you concluding too early. The rule that
 > never bends: no residual criterion reaches `C` without a recorded, gated justification.
+
+## Under a country standard, the worklist speaks that standard
+
+`verify --manual --standard rgaa` keys the worklist by **RGAA criteria**, not WCAG success
+criteria — which is the granularity that matters, since 99 of RGAA's 106 criteria can only
+ever derive `manual`. Each item carries, inline:
+
+- the criterion's **numbered tests, in full** (`11.2.1` … `11.2.6`) — what actually has to be
+  ruled on;
+- its **technical note** and **particular cases**;
+- its **implementation guidance** (before/after), previously reserved for criteria that
+  already had a finding;
+- the **definitions** of the terms its own tests cite, from the standard's glossary.
+
+**`normativeRef` must cite one of the item's OWN tests.** This is not pedantry: an RGAA test
+id has the same `N.N.N` shape as a WCAG success criterion, so a laxer check accepted the WCAG
+id an agent naturally reaches for and read it as an unrelated test — citing `1.4.3` (Contrast
+Minimum) validated as RGAA test 1.4.3, which is about CAPTCHA images. The worklist now lists
+the acceptable references per item, and anything else is rejected.
+
+Verdicts fold into `packAdjudication`, not onto the WCAG criteria: a pack decision must not
+rewrite the core verdict, and since WCAG 1.1.1 alone fans out to 19 RGAA criteria, folding by
+success criterion would let those criteria overwrite one another.
+
+Look a defined term up on its own with `criteria --standard rgaa --glossary <term>`.