ultra11y 2.22.0

package/skills/ultra11y/references/prd.md

@@ -0,0 +1,104 @@
+# Auditor backlog (`prd`) + GitHub issues
+
+`prd` turns an `AuditResult` into an **auditor-legible conformance backlog**, grouped by WCAG
+success criterion (or, with `--standard <pack>`, by a country standard's criteria). It is the
+"action" counterpart of `report` (which is the compliance document) — and they are not just
+similar, they render the literal **same auditor block** (`src/auditor.ts` `renderAuditorUnit`,
+fed by the same `prdUnits`): `report`'s "Non-conformities by priority" section (§2) IS one of
+these blocks per NC criterion, grouped by severity exactly like the `prd` backlog and the
+`--gh-issues`/`--gh-single` issue bodies. Change the block once, all four deliverables change
+together — there is no separate "report wording" to keep in sync.
+
+```
+node scripts/ultra11y.mjs audit "src/**/*.tsx" --graph --json > audit.json
+node scripts/ultra11y.mjs prd --in audit.json                      # auditor backlog (default)
+node scripts/ultra11y.mjs prd --in audit.json --split criterion    # one file per criterion
+node scripts/ultra11y.mjs prd --in audit.json --gh-issues          # + one GitHub issue per criterion
+node scripts/ultra11y.mjs prd --in audit.json --gh-single          # + ONE consolidated GitHub issue (whole audit)
+node scripts/ultra11y.mjs prd --in audit.json --standard rgaa --lang fr   # rendered with the RGAA (fr) vocabulary
+node scripts/ultra11y.mjs prd --in audit.json --format doc         # product-requirements doc (epics/stories/AC)
+node scripts/ultra11y.mjs prd --in audit.json --format remediation # legacy dev fix-backlog
+```
+
+## Output
+
+- **Default (`--format audit`) — the auditor conformance block**: one document
+  `audits/prd-YYYY-MM-DD.md`, sectioned by priority (🔴 blocking → 🟠 major → 🟡 minor). Each
+  criterion becomes a full **ticket** rendered **with the active standard's vocabulary** (see
+  `references/standards.md` → *Auditor vocabulary*):
+  1. **Auditor block** — **theme** (RGAA *Thématique* / WCAG core *Principle · Guideline*),
+     **criterion** + its official wording, **test(s)** (RGAA test numbers `11.6.1` / WCAG
+     techniques), **WCAG** mapping + level, **Priorité**, the **finding** (non-conformity,
+     labelled with the standard's *non-conformant* verdict), the **expected** conformant state,
+     a **verification** method, and the occurrence **checklist** (`file:line`) with the
+     cross-file **definition site** (`related`) when present.
+  2. **Partie technique / Technical details** — **impacted files** (source paths), **impacted
+     pages / URLs** (served locations, each with its sample **page name + auth flag** when
+     `scan --sample` provenance is present), the **expected change** + a before/after
+     **guidance example** (`references/guidance.md`), **Critères d'acceptation / Acceptance
+     criteria** as a Given/When/Then checkbox list, and **Complexité / Complexity** (a
+     deterministic t-shirt size + story points).
+  3. **Contexte de reproduction / Reproduction context** — emitted only when ≥1 occurrence
+     cites a served URL static grounding could not resolve, or a sample page behind
+     authentication: the URL, whether auth is required, and the required-state / reproduction
+     steps. This is what lets a developer reproduce a scan/`--sample` finding.
+
+  Sections 2–3 are opt-out with **`--no-technical`** (a pure-auditor consumption drops the
+  ticket scaffolding, keeping only the auditor block). Everything is localized by `--lang
+  fr|en`. The **GitHub issues** below use this same block by default.
+- **Advisory findings render as recommendations, never NCs.** A non-normative recommendation
+  (an advisory pack rule, or an agent `recommendations[]` verdict) is rendered under
+  « Recommandations (non normatives) » / "Recommendations (non-normative)" with a 💡 marker and
+  the « Recommandation (non normative) » tag — a distinct, non-parseable list so `verify` never
+  captures it as an NC claim. An advisory finding riding along in an otherwise-NC criterion is
+  split out under « Recommandations associées ». It never enters the occurrence checklist,
+  never flips a criterion to NC, and never counts toward `conformancePct`.
+- **`--format remediation` (legacy dev backlog)**: the previous developer-oriented block —
+  fix(es), an **effort estimate** (S/M/L), a **before/after example** from the implementation
+  guidance (`references/guidance.md`), and the occurrence checklist.
+- **`--format doc` (product-requirements doc)**: `audits/prd-doc-YYYY-MM-DD.md` — epics
+  grouped by theme, one **user story** per criterion, **Given/When/Then** acceptance criteria
+  templated from the real SC title/techniques (anchored to W3C text), and the task list.
+- **`--split criterion`**: a `prd-<criterion>-YYYY-MM-DD.md` file per criterion (handy for batching).
+- The markdown is **always** written, even with `--gh-issues`.
+- **`--json`**: emits a machine-readable object instead of the file paths —
+  `{paths, units, gh?}` where `units` is the structured per-criterion backlog an agent can consume.
+
+## Language of the prose (French deliverables)
+
+When you author or extend PRD/issue prose in French (extra context, acceptance criteria,
+issue comments), keep technical tokens in English exactly as the engine's fr catalog does:
+attribute/element/role names and their values are code, not prose — `aria-live` stays
+`aria-live` (never « région live »), same for `tabindex`, `alt`, `role="alert"`. Normative
+standard vocabulary (e.g. RGAA « lien d'évitement ») keeps its official French wording.
+
+## GitHub issues (`--gh-issues` / `--gh-single`, opt-in)
+
+- Uses the **`gh` CLI** (which handles its own auth) — **no** npm dependency, no key in
+  ultra11y.
+- **`--gh-issues` → one issue per criterion** (regardless of `--split`), stable title
+  `"[a11y] WCAG <sc> — <title>"` (or `"[a11y] <PACK> <id> — …"` under `--standard`), labels
+  `accessibility`, `wcag` (or the pack key), severity. The body is the **auditor conformance
+  block** (theme, criterion + wording, test(s), WCAG + level, finding, expected, verification,
+  `file:line` occurrences + definition site) — same as the default backlog, in the active
+  standard's vocabulary. `--format remediation` files the legacy dev body instead.
+- **`--gh-single` → ONE consolidated issue** for the whole audit, stable title
+  `"[a11y] WCAG — Accessibility audit"` (or `"[a11y] <PACK> — Accessibility audit"`). The body
+  is the full backlog **sectioned by severity** (🔴 blocking → 🟠 major → 🟡 minor), each
+  criterion carrying the auditor block. Labelled by the **most severe** criterion.
+- `--gh-single` **wins** if both flags are passed.
+- **De-dupe by title**: an existing issue (open or closed) is skipped, so re-running never
+  creates duplicates. The consolidated title carries **no count or date**, so it stays stable
+  across re-runs.
+- **Caveat — `--lang` changes the title**: the issue title embeds the localized criterion/pack
+  title (e.g. `[a11y] WCAG 1.4.3 — Contrast (Minimum)` vs `[a11y] WCAG 1.4.3 — Contraste (minimum)`).
+  Since de-dupe matches on the **exact title string**, re-running `prd --gh-issues` with a
+  **different `--lang`** than a previous run does **not** match the earlier issue and creates a
+  new one instead of updating it. Keep `--lang` consistent across re-runs against the same
+  repo, or accept the duplicate and close the stale one manually.
+- **Graceful degradation**: if `gh` is absent / unauthenticated, the command says so and exits
+  `0` — the markdown was still produced.
+
+> `prd` reads the `AuditResult` produced by `audit` (ideally `--graph` for cross-file
+> coverage); it reuses the criterion titles, severities, messages, remediations and
+> `file:line` already computed.

package/skills/ultra11y/references/rendered.md

@@ -0,0 +1,110 @@
+# Audit the RENDERED HTML (component libraries: DSFR, MUI…)
+
+Auditing a component library's **JSX sources** gives **false negatives**:
+`<Button iconId="fr-icon-add-line" />` (DSFR) actually renders
+`<button class="fr-btn fr-icon-add-line">` where the icon is a CSS pseudo-element
+(decorative) and the **accessible name comes only from `title`**. That HTML lives in
+`node_modules` at runtime — no source analysis sees it. So for those components, **audit
+what the JS produces**, not the source.
+
+## Honest by default
+
+When `audit` sees a JSX/TSX file rendering components imported from a **library** (a package
+specifier, e.g. `@codegouvfr/react-dsfr`), it does not invent a verdict: it adds a **scope
+risk** to the report ("preliminary source verdict — audit the build or `scan`") and names the
+library(ies). A source verdict is therefore never silently "complete".
+
+**`.vue`/`.svelte`/`.astro` single-file components are the same case.** They are parsed as
+SOURCE templates (the HTML path with component case preserved), so `<slot>`/`{@render}`,
+`v-for`/`{#each}`, dynamic bindings (`:aria-label`) and child components are invisible to
+static analysis. Every finding raised on them is flagged **`preliminary: true`** and the run
+adds a **`scope.sourceTemplate`** caveat ("audited SOURCE template only — audit the rendered
+output"). Treat those verdicts as provisional: audit the rendered HTML (a static Storybook
+build is ideal for SFCs) or `scan` a live page before concluding, and refute any source
+finding the rendered DOM disproves (`verify --apply`). See `references/false-positives.md`.
+
+## Zero-touch test-render captures (recommended)
+
+Rather than hand-write a render list, let your existing tests do the rendering. Install the
+capture harvester once and every component your tests already render is serialized to a
+provenance-tagged `.html` the static engine audits at full fidelity — the real markup a
+library/SFC emits, not its source call:
+
+```
+node scripts/ultra11y.mjs render --setup     # writes .ultra11y/capture-setup.mjs + prints the runner wiring
+# wire it into your runner (Vitest: setupFiles + globals:true; Jest: setupFilesAfterEnv), then:
+npm test                                      # every rendered component → .ultra11y/captures/*.html
+node scripts/ultra11y.mjs audit              # auto-ingests .ultra11y/captures; findings attribute to the source component
+```
+
+- **Attribution.** Each capture carries `<!-- ultra11y:capture source="src/Button.tsx" component="Button" … -->`,
+  so a finding on the rendered DOM is reported against the SOURCE component, not the anonymous
+  capture file. Storybook/manual dumps with no marker still audit as plain HTML.
+- **Coverage + gate.** `render --coverage` lists which components have a capture vs which are
+  still opaque-source-only blind spots; `audit --require-captures` fails when an opaque/control
+  component lacks one — so "all components" actually get rendered-DOM coverage.
+  `.vue`/`.svelte`/`.astro` self-defined components now count in this coverage universe too
+  (previously invisible to the graph), so a previously-green `--require-captures` gate can newly
+  report blind spots on an SFC-heavy repo — that is intended (a named blind spot beats
+  invisibility); capture those components or scope the gate.
+- **Commit `.ultra11y/captures`.** In diff-scoped mode (`--changed`/`--staged`/`--since`) the
+  audit automatically pulls in the captures whose provenance points at a diffed source file —
+  the pre-commit gate sees the real rendered markup for a touched component even though the
+  (unchanged) capture itself isn't part of the diff. After a component change, re-run your
+  tests so its capture refreshes, and stage the refreshed capture with the source change.
+  `fix` never rewrites captures (generated output). Add `.gitattributes`:
+  `.ultra11y/captures/*.html text eol=lf` for stable cross-platform diffs.
+- **Storybook**: with **portable stories** (composeStories) rendered in your test suite, the
+  harvester captures them for free. For per-story HTML produced another way (e.g.
+  `@storybook/test-runner`), `render --storybook [<storybook-static>] [--captures <html-dir>]`
+  attributes each file to its source component via the Storybook index, into `.ultra11y/captures`.
+- ultra11y renders nothing itself — your test toolchain (jsdom/happy-dom) does. Disable with `ULTRA11Y_CAPTURES=off`.
+- The harvester pipeline is covered by a real end-to-end test in ultra11y's own suite (a
+  spawned vitest+jsdom project renders, the capture lands with correct provenance, and the
+  engine ingests it) — the escaping scheme it embeds is locked byte-identical to the parser's.
+
+## Get rendered HTML
+
+`node scripts/ultra11y.mjs render [<dir>]` detects the framework and prints the
+"build → audit" recipe for the project (and flags the libraries it detects). Other routes,
+simplest to most faithful:
+
+1. **Build output** (recommended): build the site/pages, then audit the emitted HTML with the
+   static engine — it is real HTML, audited at full fidelity:
+   ```
+   npx astro build   # or next build (output:'export'), vite build…
+   node scripts/ultra11y.mjs audit "dist/**/*.html"
+   ```
+   **Storybook is the one exception**: a bare `storybook build` does **NOT** emit one HTML
+   file per story — `storybook-static/` is a single-page-app shell (`iframe.html`/`index.html`)
+   that renders stories client-side; auditing `storybook-static/**/*.html` sees only that shell,
+   not your components. Get REAL per-story HTML first, either via `@storybook/test-runner`
+   (renders every story in a real browser — dump/audit its output) or **portable stories**
+   (`composeStories`) rendered in your OWN test suite, where the zero-touch capture harvester
+   (`render --setup`) captures them for free. Only then does `render --storybook
+   [<storybook-static>] [--captures <html-dir>]` do anything useful: it ATTRIBUTES that
+   already-produced per-story HTML to its source component via the Storybook index — it does
+   not render anything itself. Point it at nothing but the shell and it now fails honestly
+   (exit 1, not a silent no-op) when candidate HTML existed but none could be attributed.
+2. **SSR snapshot**: `render --scaffold` writes `ultra11y-render.tsx`, a `react-dom/server`
+   harness (`renderToStaticMarkup`) that imports **your** components and writes HTML into
+   `audits/rendered/`. **The written file is INERT until you fill in `COMPONENTS`** — running
+   it as-is writes nothing (it self-reports `COMPONENTS is empty` and exits), and the CLI's own
+   write-time message says so. Fill in the list, run it with your toolchain (`npx tsx
+   ultra11y-render.tsx`), then audit `audits/rendered`. ultra11y does not embed React — your
+   project renders.
+3. **Headless browser**: `scan <url>` (Docker tier, axe-core) against the running app — the
+   most faithful, and required for the **rendering** criteria (computed contrast 1.4.3, reflow
+   1.4.10). `--merge` folds the result into a static AuditResult.
+
+## Choosing
+
+- Components WITH a test suite → zero-touch captures (`render --setup`), then `audit --require-captures`.
+- Components / design system (no tests) → portable stories + `@storybook/test-runner` (real
+  per-story HTML, then `render --storybook` to attribute it) **or** an SSR snapshot
+  (`render --scaffold`), then `audit`. A bare `storybook build` alone is NOT enough (see above).
+- Full pages / SSG → build output (`dist`/`out`), then `audit`.
+- Rendering criteria (contrast, focus, zoom) → `scan` (browser).
+- In all cases, do not conclude "conforming" on a library component from the source: that is
+  what the scope risk reminds you — resolve it on the produced HTML (captures / `scan`), then let
+  the AI agent adjudicate the criterion (`verify --manual`, gated).

package/skills/ultra11y/references/scale.md

@@ -0,0 +1,49 @@
+# Audit at scale — focus smartly
+
+You never audit "all" of a huge repo. The engine reads only the **markup** (HTML/JSX/Vue/
+Svelte/Astro), streams it (bounded memory, one file at a time, the `Doc` is dropped after use),
+and you **focus** it. Recommended loop:
+
+## The loop
+
+1. **Map without loading everything.** The engine ignores `node_modules`, `.git`, `dist`,
+   `build`, `.next`, `out`, `coverage`, `audits` by default, and skips **test/spec/story
+   markup** (`*.test.*`, `*.spec.*`, `*.stories.*`, `__tests__/`, `__mocks__/`,
+   `.storybook/`) — bad-by-design fixtures, never shipped UI (the drop count is logged).
+   Pass `--no-default-excludes` to include them, or name a file / `--include` it directly to
+   re-admit. Narrow further:
+   ```
+   node scripts/ultra11y.mjs audit "apps/web/**/*.{html,tsx}" --json > audit.json
+   ```
+2. **Pick the slice that matters.** Three levers, most targeted to broadest:
+   - **The diff** (hooks/CI, PR review): `--changed` (vs `HEAD`) or `--since <ref>` — audits
+     only the changed markup files (via `git diff`, no tree walk).
+   - **Shared templates/components first**: the engine **prioritizes** layouts, templates,
+     entry pages, then `components/`, `shared/`, `ui/`, `design-system/`, then leaves. A partial
+     run therefore covers the highest-impact markup first.
+   - **An explicit cap**: `--max-files <n>` bounds the number of files audited (highest-priority
+     first); truncation is **always logged** (never a silent drop) and recorded in the report.
+3. **De-duplicate the repetitive.** An identical component repeated N times is audited **once**
+   (`--dedup exact` by default; `normalized` ignores inter-tag whitespace; `off` disables). The
+   report cites the canonical file.
+4. **Audit → fix → re-audit → widen.** On the chosen slice: read the `AuditResult`, complete the
+   judgment, apply the fixes (`references/fix.md`), re-audit to prove no regression, then widen
+   the scope.
+
+## Why it is safe at scale
+
+- **Bounded memory**: file-by-file stream; only the finding count (not source size) stays in
+  memory.
+- **Deterministic**: stable order (priority then path) → reproducible audits, stable canonical
+  file choice, `check:build` holds.
+- **Incremental**: `--changed`/`--since` make the audit proportional to the diff, not the repo —
+  what makes hooks/CI viable (see `references/automation.md`). Honest caveat: the diff modes
+  pay a **fixed cost of a few `git` invocations** before auditing anything, so on a small repo
+  a full scan can actually be the faster of the two. The win starts around a few hundred
+  markup files and grows from there.
+- **One pass over the tree**: `--graph` discovers markup and the `.ts/.js` modules it resolves
+  through, but walks the tree once and parses each markup file once — the graph pass hands its
+  parsed documents to the audit pass instead of every file being read and parsed twice.
+
+> In `--changed` mode, de-duplication is disabled: a changed file is always audited, never
+> merged with a file that was not read.

package/skills/ultra11y/references/standards.md

@@ -0,0 +1,97 @@
+# Standards packs — WCAG core + pluggable country standards
+
+ultra11y's engine is keyed on **WCAG 2.2 Level AA** — the worldwide standard. Country
+accessibility standards ship as **standards packs**: small in-repo JSON files that map a
+national standard's criteria onto WCAG success criteria. The WCAG verdict is canonical and
+gated; a pack report is a *derived view* projected from the same audit.
+
+## Model
+
+- **Core = WCAG 2.2 AA.** 55 success criteria (Level A + AA), the engine's canonical key.
+  SC ids/titles/levels are derived from the W3C source (https://github.com/w3c/wcag).
+  **French SC/guideline/principle titles are the official W3C AUTHORIZED translation**
+  (https://www.w3.org/Translations/WCAG22-fr/, vendored at `scripts/vendor/wcag-2.2-fr.json`)
+  baked into the dataset — `--lang fr` output cites the normative French wording, never a
+  machine translation (the build fails if a core-AA title is missing).
+- **Packs = country standards.** Each pack (`src/data/standards/<key>.json`) declares its
+  own localized criteria and, per criterion, the WCAG SC ids it maps to. The engine audits
+  WCAG; `derivePackResults` projects that onto the pack's criteria with the same
+  NC-dominates rule. A pack carries **no** engine rules or automatability — only the mapping.
+- **The SC universe backs validation and scoping.** Alongside the AA core the engine ships
+  the full WCAG 2.x SC universe (every real SC at every level, plus the removed ones, from
+  the same vendored W3C source). A pack criterion may legitimately map to a real
+  out-of-core SC (an AAA criterion, or the removed `4.1.1`): validation accepts it with a
+  warning, and a criterion whose mapping is ENTIRELY out-of-core derives as **out of engine
+  scope** — status `manual` with a dedicated justification (never a silent NA). Shipped
+  example: **RGAA 8.1** (doctype → the removed 4.1.1). A well-formed id that never existed
+  (`9.9.9`) is rejected outright. See `references/packs.md`.
+- **Pack locales ≠ the CLI's `Lang`.** A pack's `LocaleString`s may carry any BCP-47-ish
+  tag (`pt-BR`, `nl-BE`…) — vocabulary and locales are decoupled from the CLI's own
+  `--lang fr|en` UI frame (whose `auto` default resolves conversation → repo `<html lang>`
+  → the pack's `defaultLocale` → English).
+
+## Using a pack
+
+`--standard <pack>` re-keys the output of `report`, `prd`, `criteria`, `check` and `verify`.
+The default is the WCAG core.
+
+```
+node scripts/ultra11y.mjs report   --in audits/audit-latest.json --standard rgaa   # → audits/rgaa-YYYY-MM-DD.md
+node scripts/ultra11y.mjs criteria --standard rgaa --theme 1                       # a pack theme
+node scripts/ultra11y.mjs criteria --standard rgaa 8.3                             # one pack criterion (shows its WCAG SCs)
+node scripts/ultra11y.mjs check    --report audits/rgaa-YYYY-MM-DD.md --standard rgaa
+```
+
+An unknown `--standard` value errors out (never a silent fallback to WCAG).
+
+## Auditor vocabulary
+
+The `prd` **auditor block** (the default output) and the **GitHub issues** it files are
+rendered with the **active standard's own vocabulary** — the nouns an auditor of that standard
+reads. A pack declares them under an optional `vocabulary` object (`LocaleString`s):
+
+| term | RGAA (fr) | WCAG core (en) | fallback |
+|---|---|---|---|
+| `theme` | Thématique | Principle · Guideline | Theme |
+| `criterion` | Critère | Success criterion | Criterion |
+| `test` | Test | Technique | Test |
+| `conformant` | Conforme (C) | Pass | Conformant |
+| `nonConformant` | Non conforme (NC) | Fail | Non-conformant |
+| `notApplicable` | Non applicable (NA) | Not applicable | Not applicable |
+| `auditorHeading` | Critère d'accessibilité | Accessibility criterion | Accessibility criterion |
+
+Every field is optional: what a pack omits falls back to a generic default, the WCAG core keeps
+its own built-in set (it is not a pack), and `--lang fr|en` picks the locale. So a new country
+pack ships its terminology and the auditor output speaks its language with **no engine change** —
+the modular seam that makes `prd` work for each country, not just France. Resolution lives in
+`src/standards/vocabulary.ts`; the RGAA terms are set in `scripts/build-pack-rgaa.mjs`.
+
+## Shipped packs
+
+- **RGAA 4.1.2** (`--standard rgaa`) — France, © DINUM, Licence Ouverte / Etalab 2.0.
+  13 themes, 106 criteria, French. The flagship example pack.
+
+## International equivalence (version-accurate)
+
+Several standards incorporate WCAG by reference, but **not all at the same version** — state
+the right one rather than blanket-claiming 2.2:
+
+- **Section 508** (US, revised 2018) incorporates **WCAG 2.0 Level AA** for web content.
+- **EN 301 549** (EU): v3.2.1 references **WCAG 2.1**; v4 (2024+) references **WCAG 2.2**.
+- **AODA** (Ontario, Canada) references **WCAG 2.0 AA**.
+
+A WCAG 2.2 AA audit therefore covers the web requirements of these standards at their
+respective WCAG versions; a country pack adds that standard's own numbering and wording.
+
+## Adding your country
+
+Two ways, depending on whether you want it shipped or just plugged locally:
+
+- **Built-in (shipped):** drop a pack JSON under `src/data/standards/`, register it in
+  `src/standards/registry.ts`, add a test, and open a PR. The full authoring contract
+  (pack schema, locale rules, licence requirements, the WCAG-SC mapping, tests) is in
+  **`../../CONTRIBUTING.md`**.
+- **Runtime (no rebuild):** author the pack JSON, gate it with `pack check`, and load it
+  with `--pack ./pack.json` (or a `.ultra11yrc.json`). An external standard or rule source
+  can be **AI-ingested** into a pack + implementation guidance and validated by the same
+  gate — see **`packs.md`** and **`guidance.md`**.

package/skills/ultra11y/references/structure.md

@@ -0,0 +1,138 @@
+# Structure — headings, landmarks, lists, tables
+
+1.3.1 is the criterion that fails most often in real audits, because it covers everything a
+sighted user reads from layout alone. The test is always the same: **is the relationship I
+can see also programmatically determinable?**
+
+## Headings
+
+Headings are the primary navigation aid for screen-reader users — most jump between them
+rather than reading linearly. Judge the OUTLINE, not the styling.
+
+```html
+<h1>Quarterly report</h1>
+  <h2>Revenue</h2>
+    <h3>Europe</h3>
+    <h3>Asia</h3>
+  <h2>Costs</h2>
+```
+
+- Never skip a level going down (`h2` → `h4`). Going back up is fine (`h3` → `h2`).
+- Style with CSS, not by picking a level. A "small heading" is still an `h2` if it opens a
+  second-level section.
+- A visually styled `<div class="title">` is not a heading. Either mark it up, or accept it
+  is not part of the outline.
+- One `<h1>` per page is a convention, not a rule — the engine reports it as a
+  recommendation, never a non-conformity.
+
+Engine rules: `heading-order-skip`, `empty-heading`; `h1-missing`/`h1-multiple` (advisory).
+Yours: whether each heading actually **describes** its section (2.4.6).
+
+## Landmarks
+
+```html
+<header>            <!-- banner -->
+  <nav aria-label="Main">…</nav>
+</header>
+<main id="content"> <!-- exactly one per page -->
+  …
+</main>
+<aside aria-label="Related articles">…</aside>  <!-- complementary -->
+<footer>…</footer>  <!-- contentinfo -->
+```
+
+- Every piece of content should sit inside a landmark; text stranded between them is
+  unreachable by landmark navigation.
+- Name repeated landmarks: two `<nav>`s need `aria-label` to be told apart. One `<nav>`
+  needs no label — "Navigation navigation" is what a redundant one produces.
+- `<main>` is the target of the skip link, and needs `tabindex="-1"` to accept focus.
+
+Engine rules: `missing-main-landmark`, `multiple-main-landmark`, `nav-landmark-missing`,
+`nav-landmark-unnamed`, `skip-link-target-missing`.
+
+## Lists
+
+```html
+<ul>                       <!-- unordered: order carries no meaning -->
+  <li>Coffee</li>
+</ul>
+<ol>                       <!-- ordered: steps, rankings -->
+  <li>Preheat the oven</li>
+</ol>
+<dl>                       <!-- name/value pairs: glossary, spec sheet, recap screens -->
+  <dt>Weight</dt><dd>1.2 kg</dd>
+  <div><dt>Colour</dt><dd>Black</dd></div>   <!-- a grouping <div> is allowed -->
+</dl>
+```
+
+Screen readers announce "list, 5 items" — that count is the information. A run of `<div>`s
+separated by `<br>` announces nothing. Only `<li>` (and `<script>`/`<template>`) may be a
+direct child of `<ul>`/`<ol>`; only `<dt>`/`<dd>` (optionally wrapped in a `<div>`) of `<dl>`.
+
+**The recap-screen pattern** is the one most often got wrong: a "Your details" summary built
+from `<div class="label">` / `<div class="value">` pairs conveys the relationship visually
+only. Use `<dl>`, or associate the pair programmatically. Engine rules: `list-structure`,
+`dl-structure`.
+
+## Tables
+
+A table is for **data**. Using one for layout is not a failure in itself, but it must then
+be marked `role="presentation"` and carry no data markup.
+
+```html
+<table>
+  <caption>Rainfall by city, 2025</caption>   <!-- the table's accessible name -->
+  <thead>
+    <tr><th scope="col">City</th><th scope="col">January</th></tr>
+  </thead>
+  <tbody>
+    <tr><th scope="row">Paris</th><td>52 mm</td></tr>
+  </tbody>
+</table>
+```
+
+- `scope` takes exactly `col`, `row`, `colgroup`, `rowgroup`. `scope="column"` is invalid and
+  silently does nothing (engine rule: `scope-value-invalid` is a declared gap — check it by
+  eye until it lands).
+- `<caption>` is the name; keep it SHORT. A long explanation belongs in a paragraph
+  associated via `aria-describedby`, not in the caption (RGAA 5.5).
+
+**Complex tables** — irregular headers, spans, two header rows — need explicit wiring, since
+`scope` can no longer express the relationship:
+
+```html
+<table>
+  <caption>Opening hours</caption>
+  <tr><td></td><th id="morning">Morning</th><th id="afternoon">Afternoon</th></tr>
+  <tr><th id="mon">Monday</th>
+      <td headers="mon morning">9–12</td>
+      <td headers="mon afternoon">14–18</td></tr>
+</table>
+```
+
+Every `headers` id must name a header cell **of the same table** (engine rule:
+`headers-attr-dangling`), and a header no cell references heads nothing (`th-no-data-cells`).
+Mixing `scope` and `headers` in one table is where associations quietly get lost — pick one.
+
+`colspan`/`rowspan` are fine in a simple table; once they make the header structure
+irregular, switch to `headers`/`id`. Engine rules: `data-table-no-headers`,
+`table-caption-missing`, `layout-table-data-markup`, `sortable-header-no-aria-sort`.
+
+## 1.3.2 Meaningful Sequence
+
+The DOM order is the reading order. CSS that reorders content visually
+(`order`, `flex-direction: row-reverse`, `position: absolute`, `grid-area`) makes the two
+diverge, and the divergence becomes a failure when it changes the meaning.
+
+Test: read the DOM top to bottom. Does the sequence still make sense? A sidebar declared
+between two paragraphs of an article will be read in the middle of the article.
+
+## What the engine settles, and what stays yours
+
+| Decided by the engine | Yours to adjudicate |
+|---|---|
+| Heading level skips, empty headings, malformed lists and description lists | Whether a heading **describes** its section (2.4.6) |
+| Missing/duplicate `<main>`, unnamed repeated `<nav>`, broken skip-link target | Whether every region of content sits in a landmark |
+| Data table with no headers, no caption, dangling `headers`, unreferenced `<th>` | Whether a table is data or layout in the first place |
+| — | Whether a visual relationship (recap screens, columns) exists programmatically (1.3.1) |
+| — | Whether the DOM order preserves meaning (1.3.2) |

package/skills/ultra11y/references/verify.md

@@ -0,0 +1,88 @@
+# `check` and `verify` gates
+
+Two assurance levels before shipping a report, plus the agent-adjudication worklist.
+
+## `check` — structural integrity
+
+```
+node scripts/ultra11y.mjs check --report audits/wcag-YYYY-MM-DD.md
+```
+Fails (non-zero) if: one of the 5 sections is missing, a cited criterion id does not exist in
+the active standard, an `NA` criterion has no justification, or the pass rate is absent. This
+is the baseline anti-hallucination guard. `--quiet` emits only the exit code; `--json` the
+structured list of problems. For a country pack report, add `--standard <pack>` so the right
+id grammar/registry is validated.
+
+### Semantic gate — `check --report … --semantic`
+
+```
+node scripts/ultra11y.mjs check --report audits/wcag-YYYY-MM-DD.md --semantic [--verdicts VERIFY.todo.json]
+```
+Fails **closed** if there is no adjudicated verdicts artifact (never green-but-inactive),
+re-runs the **uncapped** coverage check, and re-grounds every passing verdict against the cited
+source. `--verdicts` points at the artifact (default `VERIFY.todo.json` next to the report).
+
+### Applicability gate — `check --report … --standard rgaa --in audit.json`
+
+```
+node scripts/ultra11y.mjs check --report audits/rgaa-YYYY-MM-DD.md --standard rgaa --in audit.json
+```
+Re-derives the pack view from the audit and fails on any **over- or under-projected** NC — the
+RGAA applicability gate, so a pack report can neither drop nor invent a criterion vs the WCAG core.
+
+## `verify` — adversarial verification of non-conformities
+
+```
+node scripts/ultra11y.mjs verify --report audits/wcag-YYYY-MM-DD.md --semantic
+```
+Generates a **worklist** `VERIFY.md` + `VERIFY.todo.json`: one entry per non-conformity
+(criterion ↔ `file:line` ↔ cited claim), capped by `--max-verify` (default 40). For each
+entry, open the cited code and assign a verdict in `VERIFY.todo.json`:
+
+- `supported` — the non-conformity is real;
+- `partial` — real but the criterion/wording is imprecise;
+- `refuted` — false (the cited element is actually conforming);
+- `unsupported` — the cited element is not enough to decide.
+
+In `--semantic` mode, explicitly confirm the cited snippet **supports** the non-conformity.
+The worklist-generation step also accepts `--json` (emits `{mdPath, todoPath, count, items}`
+so an agent can fill verdicts in-memory). **Prioritise `preliminary` findings** (SFC/library
+source, see `references/false-positives.md`): refute the ones the rendered DOM disproves.
+Then apply the gate:
+```
+node scripts/ultra11y.mjs verify --apply VERIFY.todo.json
+```
+The gate fails (non-zero) if any entry is `refuted`, `unsupported`, or unadjudicated. Goal: no
+fabricated non-conformity survives into the final report.
+
+## `verify --manual` — adjudicate the residual (judgment / needs-rendering) criteria
+
+The **AI agent** decides the `manual` criteria itself, gated. Run from the audit's cwd
+(harvesting re-reads the audited source files):
+```
+node scripts/ultra11y.mjs verify --report audits/wcag-YYYY-MM-DD.md --in audit.json --manual --out .
+```
+This emits an **ADJUDICATION worklist** — `ADJUDICATE.todo.json` + `ADJUDICATE.md`, one item per
+residual criterion, pre-loaded with the engine's harvested evidence (every image's `alt`, every
+link's text + context, the literal colour pairs, control labels, the heading outline, ARIA state,
+`tabindex`, lang-of-parts). Fill each item's `verdict` (provenance `decidedBy: "agent"` recorded):
+
+- `C` / `NA` — with a `justification` from the evidence;
+- `NC` — with ≥1 **groundable** finding (`file`/`line`/`message`/`snippet`);
+- `manual` — with a `reason`: `"needs-rendered-dom"` (decide via `scan`) or `"undecidable"`.
+
+Fold the verdicts back FAIL-CLOSED:
+```
+node scripts/ultra11y.mjs verify --apply ADJUDICATE.todo.json --in audit.json --out .
+```
+It rejects a null verdict, a `C`/`NA` without a `justification`, an `NC` without a groundable
+finding, a `manual` without a `reason`, or any uncovered residual criterion. Agent `NC`s become
+real `agent:<sc>` findings that re-render in the report's §2 and re-enter the verify worklist;
+`report`/`prd` re-render with the adjudicated statuses; §5 shrinks to only still-`manual` items.
+
+## Residual risk
+
+After adjudication, only the criteria the agent marked `manual` (`needs-rendered-dom` /
+`undecidable`) stay in the report's "to assess manually" section — never mark them conforming
+without a recorded, gated justification (agent adjudication via `verify --manual`, or `scan`
+evidence for the rendering criteria).