ultra11y 2.22.0

package/skills/ultra11y/references/judgment.md

@@ -0,0 +1,90 @@
+# Judgment phase (the criteria the AI agent adjudicates)
+
+The engine decides the machine-checkable subset; the **AI agent** (Claude running this skill)
+*adjudicates the rest itself*, gated: the **judgment** criteria (alt relevance, link purpose in
+context, reading order) it rules on **statically, from the evidence the engine harvests**; the
+**rendering** criteria (computed contrast, visible focus, zoom/reflow, content-on-hover) it routes
+to the `scan` tier (never source); and it adversarially verifies the detected non-conformities.
+This phase makes each verdict defensible and recorded, never invented, never silently "conforming".
+
+## Adjudication loop (the residual/manual criteria) — `verify --manual`
+
+1. **Harvest the worklist** 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 .
+   ```
+   writes an **ADJUDICATION worklist** — `ADJUDICATE.todo.json` + `ADJUDICATE.md`, one item per
+   residual (`manual`) criterion, each **pre-loaded with the 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.
+2. **Rule on each item**, filling its `verdict` in `ADJUDICATE.todo.json` (provenance
+   `decidedBy: "agent"` is recorded):
+   - `C` — conforming, with a `justification` from the evidence;
+   - `NC` — non-conforming, with ≥1 **groundable** finding (`file`/`line`/`message`/`snippet`)
+     **AND a `normativeRef`** citing the precise failed test of the *active standard* (a WCAG
+     technique/SC, or an RGAA test number under `--standard rgaa`). The fold rejects a missing
+     `normativeRef`, or one that does not resolve to a real test of the active standard
+     (anti-fabrication) — a non-conformity must always name the normative rule it breaks;
+   - `NA` — not applicable, with a `justification`;
+   - `manual` — undecidable from what is captured, with a `reason`: `"needs-rendered-dom"`
+     (decide via `scan`) or `"undecidable"`.
+   - `recommendations[]` — a **good practice with no failing normative test** (e.g. "state a
+     download link's format/weight", "one `<h1>` per page") is NOT an NC: record it as a
+     non-normative recommendation (groundable exactly like an NC, but **no `normativeRef`
+     required**). It renders under « Recommandations (non normatives) » and never flips the
+     criterion to NC. A purely UX concern is neither an NC nor a recommendation — leave it out.
+3. **Fold back FAIL-CLOSED**:
+   ```
+   node scripts/ultra11y.mjs verify --apply ADJUDICATE.todo.json --in audit.json --out .
+   ```
+   rejects a null verdict, a `C`/`NA` without a `justification`, an `NC` without a groundable
+   finding **or without a resolving `normativeRef`**, 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 the still-`manual` items.
+
+### The decision protocol
+
+Each residual criterion in `ADJUDICATE.md` is pre-loaded, alongside the harvested evidence,
+with its **decision protocol** (`src/data/adjudication.json`, both languages, covering ALL 52
+criteria the engine cannot decide):
+
+- **the decision rule** — what makes this criterion Conforming vs Non-conforming. Not a hint:
+  the rule you apply. A criterion handed over with no stated rule is where an audit quietly
+  turns into an opinion;
+- **when `NA` is legitimate** — so "not applicable" is a justified verdict rather than an
+  escape hatch;
+- **the questions** an auditor asks to get there;
+- **the citable references** — this criterion's W3C techniques and failures, i.e. exactly the
+  set a `normativeRef` may come from. `verify --apply` rejects one that does not resolve, so
+  proposing the valid ones is what stops an invented citation.
+
+The same protocol is published as a standalone page, `references/adjudication.md`, generated
+from that dataset — read it when you want the whole picture rather than one worklist item.
+They are prompts, not verdicts: you still answer from the evidence and record
+`C`/`NC`/`NA`/`manual` (+ a recommendation where a good practice has no failing normative
+test).
+4. **Rendering required**: a `manual` item marked `needs-rendered-dom` (computed contrast, visible
+   focus, 200% zoom, 320px reflow, content-on-hover) is decided on the **render** (the `scan` tier,
+   or inspection) — never from the source.
+5. **Library code (DSFR…)**: a `<Button>`/`<Card>` does not show its HTML in source. Adjudicate on
+   the **produced** HTML (see `render` / audit the build), otherwise the verdict is a false
+   negative.
+
+## Adversarial verification of the non-conformities — `verify --report`
+
+Unchanged: `node scripts/ultra11y.mjs verify --report audits/wcag-YYYY-MM-DD.md` writes `VERIFY.md`
++ `VERIFY.todo.json`, one entry per detected non-conformity, each grounded in the **WCAG success
+criterion's W3C Understanding reference** + techniques. Rule each, opening the file at the cited
+line:
+- `supported` — the non-conformity is real and correctly tied;
+- `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.
+
+Then `node scripts/ultra11y.mjs verify --apply VERIFY.todo.json` is green again (fails on any
+`refuted`/`unsupported`/missing verdict). `--semantic` folds the support-check into the same pass.
+
+> 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.

package/skills/ultra11y/references/media-and-motion.md

@@ -0,0 +1,116 @@
+# Media, pointer input and motion
+
+The criteria in this page are the ones a source-only audit is least able to settle: what a
+video actually contains, how big a target renders, whether an animation lasts five seconds.
+Each entry says what decides it — you, the `scan` tier, or the engine.
+
+## Time-based media (1.2.x)
+
+| Media | What it needs | Level |
+|---|---|---|
+| Audio-only, prerecorded | A text transcript | A (1.2.1) |
+| Video-only, prerecorded | A transcript OR an equivalent audio track | A (1.2.1) |
+| Video with audio, prerecorded | Synchronized captions | A (1.2.2) |
+| Video with audio, prerecorded | Audio description OR a full text alternative | A (1.2.3) |
+| Video with audio, prerecorded | Audio description — a transcript no longer suffices | **AA (1.2.5)** |
+| Any live audio | Real-time captions | AA (1.2.4) |
+
+```html
+<video controls>
+  <source src="talk.mp4" type="video/mp4">
+  <track kind="captions" src="talk.en.vtt" srclang="en" label="English" default>
+  <track kind="descriptions" src="talk.desc.vtt" srclang="en" label="Audio description">
+</video>
+<p><a href="talk-transcript.html">Read the transcript of this talk</a></p>
+```
+
+`kind` matters: `captions` include non-speech sounds and speaker identification;
+`subtitles` are a translation for people who can hear; `descriptions` narrate the picture.
+A `subtitles` track does not satisfy 1.2.2.
+
+**Why the engine only recommends here.** A `<video>` without `<track>` may still carry
+captions embedded in the container, and its audio track may be silent. Neither is knowable
+from source, so `media-no-track` is a **recommendation**: 1.2.2 stays yours to adjudicate
+against the real media. Check the file and the player before writing a verdict.
+
+Also in scope: a media player's own controls must be keyboard-operable and named (2.1.1,
+4.1.2) — a custom player is a composite widget, see `references/widgets.md`.
+
+## Autoplay (1.4.2, 2.2.2)
+
+Audio that plays automatically for more than 3 seconds needs a mechanism to pause, stop or
+control its volume, independent of the system volume. Native `controls` is that mechanism.
+
+```html
+<video autoplay muted playsinline>…</video>   <!-- no audio: 1.4.2 not engaged -->
+<audio src="jingle.mp3" autoplay controls>     <!-- ✓ a stop mechanism exists -->
+```
+
+Engine rule: `autoplay-media` — normative only when there is no `controls` and no `muted`;
+the muted-video case is raised as a recommendation, since the source cannot show whether the
+movement lasts the 5 seconds 2.2.2 requires.
+
+## Pointer input (2.5.x)
+
+| SC | Requirement | How to satisfy it |
+|---|---|---|
+| **2.5.1** Pointer Gestures | No function requires a multipoint or path-based gesture | Add buttons beside the swipe/pinch: carousel arrows, map zoom controls |
+| **2.5.2** Pointer Cancellation | No function executes on the DOWN event, or it is abortable | Act on `click`/`pointerup`, not `pointerdown`; allow the user to slide off to abort |
+| **2.5.3** Label in Name | Visible label contained in the accessible name | See `references/naming.md` |
+| **2.5.4** Motion Actuation | Motion-triggered functions have a UI equivalent AND can be disabled | Keep a button for "shake to undo"; offer a setting |
+| **2.5.7** Dragging Movements (2.2) | Every drag has a single-pointer alternative | "Move up"/"Move down" buttons beside a drag handle; a numeric input beside a slider |
+| **2.5.8** Target Size (2.2) | Targets are at least 24×24 CSS px | Or spaced so 24px circles do not overlap; inline links in text are exempt |
+
+```html
+<!-- ✓ drag remains, but is never the only way -->
+<li draggable="true">
+  Task one
+  <button aria-label="Move “Task one” up">↑</button>
+  <button aria-label="Move “Task one” down">↓</button>
+</li>
+```
+
+2.5.8 is decided on the render — `scan` measures it through axe's `target-size` rule.
+
+## Orientation, reflow, spacing, zoom (1.3.4, 1.4.4, 1.4.10, 1.4.12)
+
+All four are decided on the rendered page (`scan --runtime local` probes zoom, spacing and
+overflow). What to check:
+
+- **1.3.4 Orientation** — the content works in both portrait and landscape, unless the
+  orientation is genuinely essential (a piano keyboard, a cheque to photograph). A CSS
+  `transform` or a blocking orientation media query is the usual culprit.
+- **1.4.4 Resize Text** — at 200% text zoom nothing is lost, clipped or overlapped. A
+  `meta viewport` blocking zoom fails outright (engine rule: `meta-viewport-zoom-block`).
+- **1.4.10 Reflow** — at **320 CSS px** wide (the equivalent of 400% zoom on a 1280px
+  viewport) no two-dimensional scrolling is required, except for content that inherently
+  needs it: maps, data tables, diagrams, code.
+- **1.4.12 Text Spacing** — forcing line height 1.5×, paragraph spacing 2×, letter spacing
+  0.12× and word spacing 0.16× loses no content. Fixed-height containers are what break.
+
+## Motion and vestibular safety (2.3.1, 2.2.2)
+
+```css
+/* Respect the OS-level preference — a one-line win that costs nothing */
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+```
+
+`prefers-reduced-motion` is not itself a WCAG 2.2 AA requirement, but large parallax,
+auto-playing motion and full-page transitions trigger vestibular disorders, and honouring it
+is how you avoid the 2.2.2 problem entirely. 2.3.1 (nothing flashes more than three times a
+second) is decided on the render.
+
+## What the engine settles, and what stays yours
+
+| Decided by the engine | Decided by `scan` | Yours to adjudicate |
+|---|---|---|
+| `autoplay` with no stop mechanism; `meta viewport` blocking zoom; `blink`/`marquee`; timed `meta refresh` | Zoom 200%, reflow 320px, text spacing, target size, flashing | Whether captions/audio description/transcripts exist and are accurate (1.2.x) |
+| Missing `<track>` — as a recommendation, not a failure | — | Whether a gesture, a drag or a motion trigger has an alternative (2.5.1/2.5.2/2.5.4/2.5.7) |
+| — | — | Whether an orientation is genuinely essential (1.3.4) |

package/skills/ultra11y/references/methodology.md

@@ -0,0 +1,72 @@
+# Methodology & report format
+
+## Per-criterion statuses
+
+- **C** — conforming (every applicable test passes).
+- **NC** — non-conforming (at least one test fails; a finding cites `file:line`).
+- **NA** — not applicable (no element in scope is concerned — justified).
+- **To assess (manual)** — a criterion the engine cannot decide on its own: the AI agent
+  adjudicates the *judgment* ones itself (`verify --manual`, gated); the *rendering* ones are
+  decided by the `scan` tier. Only the still-undecidable residue stays listed here.
+
+## Pass rate
+
+Conformance rate = **conforming criteria ÷ applicable criteria × 100**.
+
+The engine only computes the **automatic static-check pass rate**, over the small
+machine-decidable subset it can actually decide: `C ÷ (C + NC)`. Because WCAG success
+criteria are coarser than the engine's rules, that denominator is deliberately small —
+it is **not** a full conformance rate. Full WCAG 2.2 AA conformance requires completing
+the "to assess" criteria by hand.
+
+## Non-conformity priorities
+
+- 🔴 **Blocking** — prevents access to content/function (e.g. missing alt, unlabeled
+  field, empty link).
+- 🟠 **Major** — high impact but workaroundable (heading order, contrast, invisible focus).
+- 🟡 **Minor** — light friction (missing caption, redundant ARIA).
+
+## The division of labour (static / rendering / judgment)
+
+ultra11y is honest about what a static analyzer can decide:
+
+- **Automatable (static)** — decided by the engine: missing alt/lang/title, unlabeled
+  fields, `iframe` without a title, empty links/buttons, tables without headers, heading
+  skips, duplicate `id`s, invalid/broken ARIA, positive `tabindex`, autoplay…
+- **Needs rendering** — computed contrast (1.4.3), focus visible (2.4.7), zoom/reflow
+  (1.4.4/1.4.10), content on hover/focus (1.4.13). **Out of the engine**: decided by the `scan`
+  tier (axe-core in a real browser), flagged as residual risk until then.
+- **Agent judgment** — alt relevance (1.1.1), link purpose in context (2.4.4), reading/tab
+  order, navigation consistency, caption accuracy…: the AI agent adjudicates these itself from
+  the evidence the engine harvests (`verify --manual`, gated), never silently "conforming".
+
+See the full table of the 55 WCAG 2.2 AA success criteria in `references/criteria.md`.
+
+**Preliminary findings.** A finding raised on a `.vue`/`.svelte`/`.astro` source template (or
+library-rendered JSX) carries `preliminary: true` in the `--json` output, and the run adds a
+`scope.sourceTemplate` (or `scope.rendered`) caveat: the static parse cannot see slot/dynamic
+content, so the verdict is provisional — confirm against the rendered DOM or refute it
+(`references/rendered.md`, `references/false-positives.md`). It is never silently treated as final.
+
+## Report format (`report`)
+
+`audits/wcag-YYYY-MM-DD.md` has 5 sections: (1) synthesis by WCAG guideline
+(C/NC/NA/to assess), (2) non-conformities by priority — one **auditor conformance block**
+per NC criterion (theme, criterion + official wording, test(s), WCAG mapping + level,
+finding, expected state, verification, `file:line` occurrences), the SAME block `prd` and
+`--gh-issues` emit (see `references/prd.md`), (3) conforming criteria, (4) justified
+not-applicable criteria, (5) criteria to assess manually.
+
+## Worldwide: WCAG core, country standards as packs
+
+WCAG 2.2 Level AA is the engine's canonical key — the worldwide standard. A country
+standard (France's RGAA, the US Section 508, the EU's EN 301 549) is a pluggable in-repo
+**pack** that maps its criteria onto WCAG success criteria; `report --standard rgaa` (and
+`criteria`/`check`/`verify`/`prd --standard <pack>`) re-key the deliverable for that
+standard (`rgaa-YYYY-MM-DD.md`). The WCAG report is the canonical, gated one; a pack report
+is a derived view. See `references/standards.md`.
+
+**International equivalence (version-accurate)**: Section 508 incorporates WCAG 2.0 AA;
+EN 301 549 v3.2.1 references WCAG 2.1 and v4 references WCAG 2.2; AODA references WCAG 2.0
+AA. A WCAG 2.2 AA audit therefore covers these standards' web requirements at their
+respective WCAG versions.

package/skills/ultra11y/references/naming.md

@@ -0,0 +1,117 @@
+# Accessible names — how one is computed, and how to get it right
+
+Most of what an audit calls "4.1.2" is a naming problem. This page is the reference for
+what a name IS, so a verdict rests on the computation rather than on the markup's appearance.
+
+## The precedence chain (accname), highest first
+
+A control's accessible name is the FIRST of these that yields non-empty text:
+
+| # | Source | Notes |
+|---|---|---|
+| 1 | `aria-labelledby` | Wins over everything, including visible content. Concatenates the text of every id, in the order listed. A dangling id contributes nothing — an all-dangling list leaves the element unnamed. |
+| 2 | `aria-label` | Replaces the visible text entirely. This is what breaks 2.5.3 (see below). |
+| 3 | Native host semantics | `<label for>` / wrapping `<label>` for form fields, `alt` for `<img>`, `<legend>` for `<fieldset>`, `<caption>` for `<table>`, `<figcaption>` for `<figure>`, `value` for `<input type="submit">`. |
+| 4 | Text content | For elements whose role allows "name from content": button, link, heading, menuitem, tab, option… NOT for a `<div>` or an `<input>`. |
+| 5 | `title` | Last resort. Hover-only: absent on touch, unevenly announced. A name that exists but should not be the plan. |
+
+Two consequences worth stating explicitly, because both produce confident wrong verdicts:
+
+- **A name that exists is not a name that works.** `aria-label="Button"` satisfies "has a
+  name" and helps nobody. Judge relevance, not presence.
+- **The chain stops at the first hit.** `<button aria-label="Close">Save</button>` is named
+  "Close". The visible word "Save" never enters the computation.
+
+## 2.5.3 Label in Name — the rule voice control depends on
+
+When a control shows visible text, that text must be **contained in** the accessible name.
+A speech-input user says what they see; if the name differs, the command silently does nothing.
+
+```html
+<!-- ✗ the spoken "click Send" matches nothing -->
+<button aria-label="Submit form">Send</button>
+
+<!-- ✓ the visible text is contained, and comes first -->
+<button aria-label="Send message to support">Send</button>
+
+<!-- ✓ best: no override at all — the text names the button -->
+<button>Send</button>
+```
+
+Rule of thumb: if you find yourself writing `aria-label` on an element that already shows
+text, you are usually about to break 2.5.3. Prefer `aria-describedby` for the extra detail.
+Engine rule: `label-in-name-mismatch`.
+
+## Visually-hidden text — the CSS that actually works
+
+Naming an icon control with text only screen readers reach is the native-first answer.
+`display:none` and `visibility:hidden` remove the text from the accessibility tree too;
+`text-indent:-9999px` breaks in RTL; `font-size:0` is unreliable.
+
+```css
+/* The only clipping recipe that survives every engine, and stays focusable. */
+.visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+/* Skip links: visible again once focused. */
+.visually-hidden:focus-visible {
+  position: static;
+  width: auto;
+  height: auto;
+  clip-path: none;
+  white-space: normal;
+}
+```
+
+## Naming non-text content
+
+```html
+<!-- Informative image: describe the MEANING in context, not the picture -->
+<img src="chart.png" alt="Sales up 25% in Q3 2025">
+
+<!-- Decorative image: an explicit empty alt, never a missing one -->
+<img src="divider.png" alt="">
+
+<!-- Icon control: the name describes the ACTION, not the glyph -->
+<button aria-label="Delete this comment"><svg aria-hidden="true" focusable="false">…</svg></button>
+
+<!-- Inline SVG treated as an image -->
+<svg role="img" aria-labelledby="logo-title"><title id="logo-title">Acme</title>…</svg>
+
+<!-- Decorative SVG: hide it and make sure it is not a tab stop in IE-era engines -->
+<svg aria-hidden="true" focusable="false">…</svg>
+
+<!-- Figure: the caption is visible text AND the accessible name -->
+<figure>
+  <img src="plan.png" alt="Ground floor: reception, then three meeting rooms along a corridor">
+  <figcaption>Ground floor plan</figcaption>
+</figure>
+
+<!-- Abbreviation: expand on first use in text; title alone is hover-only -->
+<p>The <abbr title="World Wide Web Consortium">W3C</abbr> publishes WCAG.</p>
+```
+
+**Charts.** An `alt` naming the chart ("Sales chart") is not an alternative — it names the
+container and drops the data. Either put the figures in the alt, or point at an equivalent
+table nearby. Engine rule: `chart-no-accessible-name`.
+
+## What the engine settles, and what stays yours
+
+| Decided by the engine | Yours to adjudicate |
+|---|---|
+| Name **absent** (`img-alt-missing`, `button-empty-name`, `link-empty-name`, `control-label-missing`, `iframe-title-missing`, `icon-only-control-unnamed`) | Whether the name is **relevant** (1.1.1, 2.4.4, 2.4.6) — the engine cannot read meaning |
+| Name provided only by `title` (`control-name-title-only`, `img-alt-missing.title-only` as a recommendation) | Whether an `alt=""` image is genuinely decorative |
+| Visible text not contained in the name (`label-in-name-mismatch`) | Whether an icon font makes the DOM text invisible (then 2.5.3 does not apply) |
+| Names prohibited by the role (`aria-prohibited-attr`) | Whether two same-named links share a destination (2.4.4) |
+
+Cross-file: under `--graph` the engine resolves a name passed as a prop into a component,
+and flags one that gets lost on the way (`cross-prop-drilled-name-lost`). See
+`references/cross-file.md`.

package/skills/ultra11y/references/orchestration.md

@@ -0,0 +1,44 @@
+# Orchestration — fanning the judgment phases out
+
+The two judgment phases are per-item worklists: `ADJUDICATE.todo.json` holds one entry per
+residual criterion, `VERIFY.todo.json` one per detected non-conformity. Neither has
+cross-item dependencies, so both fan out cleanly across subagents — and both work exactly as
+well done sequentially. This is a wall-clock optimization, never a correctness requirement.
+
+`orchestrate` emits the orchestration from the worklists that CURRENTLY exist, with absolute
+paths and the real item ids baked in:
+
+```
+node scripts/ultra11y.mjs orchestrate --run <dir> [--phase adjudicate|verify-report] [--eco] [--list]
+```
+
+## Route by harness
+
+| Your harness | How to run each judgment phase |
+|---|---|
+| Has the Workflow tool | `orchestrate --run <RUN> --phase <p>`, then run `<RUN>/orchestration/<p>.workflow.mjs`. Subagents RETURN verdict fragments; you fold them into the worklist, then `verify --apply` as usual. |
+| 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 rules that do not bend
+
+- **Subagents never write.** Every emitted contract ends with the one-writer rule, and the
+  fail-closed `--apply` fold always stays with you, the orchestrator. Parallel writers to one
+  worklist is how a verdict silently disappears.
+- **The gates are harness-independent.** `check` and `verify --apply` behave identically
+  whether one agent or twelve produced the verdicts, so a fan-out can never buy a greener
+  result than the sequential path.
+- **Re-run `orchestrate` whenever a worklist changes.** Emission is deterministic and
+  idempotent, so re-running is free and keeps the batches aligned with reality.
+- `--phase <p>` before its worklist exists fails, and names the command that produces it.
+
+## Splitting the work sensibly
+
+An adjudication batch should hold criteria that share context — the media criteria together,
+the form criteria together — so each subagent reads one part of the codebase rather than all
+of it. The emitted contracts already group this way; if you dispatch by hand, keep it.
+
+A subagent adjudicating a criterion needs the same three things you do: the harvested
+evidence, the decision rule (`references/adjudication.md`), and the reminder that a
+non-conformity must cite a normative test that resolves. Point each contract at the relevant
+knowledge reference rather than restating it — a paraphrase drifts.

package/skills/ultra11y/references/packs.md

@@ -0,0 +1,193 @@
+# Pluggable standards packs — runtime loading + AI ingestion, gated
+
+WCAG 2.2 AA is the engine's canonical key. A **standards pack** is a localized criterion
+set (RGAA, Section 508, EN 301 549…) that maps each of its criteria onto WCAG success
+criteria. RGAA ships built-in; you can add more **without rebuilding** the engine.
+
+## Load an external pack at runtime
+
+A pack is plain JSON conforming to `StandardPack` (see `references/standards.md` and
+`CONTRIBUTING.md`). Point the CLI at one — no install, no rebuild:
+
+```
+node scripts/ultra11y.mjs audit "src/**/*.tsx" --graph --pack ./packs/section508.json
+node scripts/ultra11y.mjs report --in audit.json --standard section508 --pack ./packs/section508.json
+```
+
+`--pack` accepts a JSON file, a directory holding `pack.json` (+ optional `glossary.json`
+/ `guidance.json`), or a comma-separated list. Or declare it once in a `.ultra11yrc.json`
+at the project root:
+
+```json
+{ "packs": ["./packs/section508.json"], "guidance": ["./packs/section508.guidance.json"], "standard": "section508" }
+```
+
+Every pack is validated **before** it is registered. An invalid pack is a hard error
+(never a silent skip): the runtime loader, the `pack check` command, and the AI-ingestion
+gate all share the one validator, so the rules below hold everywhere. A runtime pack whose
+`key` collides with a **built-in or already-loaded** standard (e.g. `rgaa`) is rejected —
+pass `--override` to deliberately replace it.
+
+## `pack check` — the anti-hallucination gate
+
+```
+node scripts/ultra11y.mjs pack check ./packs/rgaa.json
+node scripts/ultra11y.mjs pack check ./packs/rgaa.json --guidance ./packs/rgaa.guidance.json
+node scripts/ultra11y.mjs pack scaffold > ./packs/mypack.json     # a blank, valid skeleton to fill
+```
+
+`pack check` fails (exit 1) on any error: a missing required field, a `key` that collides
+with the reserved core `wcag`, an `idPattern` that won't compile, a theme `count` that
+disagrees with its criteria, a criterion whose `wcag` SC is **not a recognized WCAG
+success criterion**, and — with `--guidance` — a guidance entry whose `criterionId`
+doesn't resolve to a real pack criterion, or whose code example won't parse. This is what
+makes an AI-authored pack trustworthy: the model proposes, the deterministic gate refuses
+fabrication.
+
+**SC classification runs against the full WCAG 2.x universe** — every real 2.x success
+criterion at every level (A/AA/AAA) plus the removed ones, vendored from the same W3C
+source as the AA core (never invented, no id ever special-cased):
+
+- **core** (in the WCAG 2.2 AA core) — the normal case; the engine can audit it.
+- **out-of-core** (a real SC outside the AA core, e.g. an AAA criterion) or **removed**
+  (the obsolete `4.1.1 Parsing`) — accepted with a *warning*. At report/derive time a pack
+  criterion whose mapping is ENTIRELY out-of-core/removed is classed **out of engine
+  scope**: status `manual` with a dedicated out-of-scope justification (`outOfScope: true`
+  from `derivePackResults`), never a silent NA and never a fabricated verdict. RGAA 8.1
+  (doctype → the removed 4.1.1) is the shipped example.
+- **unknown** (a well-formed id that never existed — `9.9.9`) — **rejected** (error).
+
+**Pack locales are free-form.** `LocaleString` keys are BCP-47-ish tags (`fr`, `en`,
+`pt-BR`, `nl-BE`…) validated by shape only — a pack may be authored in any language,
+independent of the CLI's own `--lang fr|en` UI frame. The pack's `defaultLocale` also
+feeds the CLI's `--lang auto` fallback chain (used when it is `fr`/`en` and neither an
+explicit `--lang` nor a repo `<html lang>` signal decided the output language).
+
+## AI-assisted ingestion of any rule source (the primary path)
+
+To turn an external rule source — the RGAA SocialGouv/etalab rule packs, or any other
+national standard — into something ultra11y can use, drive this loop:
+
+1. **Read** the source (its criteria list, and its concrete good/bad implementation
+   rules). The fuzzy mapping `rule → criterion → WCAG SC` is yours to do — the model is
+   far better at it than a regex.
+2. **Draft** three artifacts: the `StandardPack` JSON (if the standard isn't already
+   built-in), a guidance dataset (`references/guidance.md`), and a list of *proposed*
+   new detectors (only the machine-checkable ones — see the honesty rule in
+   `references/guidance.md`).
+3. **Gate**: run `pack check <pack.json> --guidance <guidance.json>`. Fix every error.
+   A bogus criterion id misses; a bogus SC is rejected; an unparseable example fails.
+4. **Iterate** until green, then load it with `--pack` / `.ultra11yrc.json`.
+
+An optional deterministic scaffolder, `scripts/import-pack.mjs`, pre-fills a *draft*
+guidance dataset from a SocialGouv-style rules directory (frontmatter + before/after code
+blocks + reference link), leaving any unresolved `criterionId` as `null` for you to
+complete; it never finalizes — `pack check` is always the gate. See the script header for
+usage.
+
+## Pack-only detection: declarative `rules` + normativity `overrides`
+
+A pack can go beyond re-keying WCAG findings: it can ship its **own** detection and
+**re-normativize** a finding within its own projection — *without forking the engine*. Both
+mechanisms are pure data (no JavaScript plugins — a `--pack`-loaded pack stays fully
+validatable), and both are enforced by the same `validatePack` / `pack check` gate.
+
+### `rules` — a bounded declarative matcher
+
+Each rule matches source elements and emits a namespaced `pack:<key>:<id>` finding that
+projects onto the pack criterion it reports under (via the same `appliesTo`/`ruleMatches`
+machinery as engine findings). Rules run **after** the core engine rules and **never**
+affect the WCAG core verdict — they surface only in the pack's own report.
+
+```json
+{
+  "rules": [{
+    "id": "download-link-format",
+    "criterion": "6.1",
+    "wcag": ["2.4.4"],
+    "severity": "mineur",
+    "advisory": true,
+    "match": {
+      "tag": "a",
+      "attrs": [{ "name": "href", "op": "matches", "value": "\\.(pdf|docx?|zip)(\\?|#|$)" }],
+      "text": { "op": "lacks", "value": "(pdf|docx?|zip|\\d+\\s*(ko|mo|go))" }
+    },
+    "message": { "en": "…", "fr": "…" },
+    "remediation": { "en": "…", "fr": "…" }
+  }]
+}
+```
+
+The shipped RGAA pack uses exactly this rule (built by `scripts/build-pack-rgaa.mjs`, never
+hand-edited): an **advisory** flag on download links whose visible text omits the file
+format/weight — the DSFR auditor recommendation under criterion 6.1. Advisory ⇒ it renders
+as a recommendation and **never** makes 6.1 non-conformant. Its `message`/`remediation` pair
+is **localized**: the finding carries both `en` and `fr`, so a `--lang fr` RGAA report renders
+the French recommendation text (not the English bake).
+
+**The matcher vocabulary is deliberately CAPPED** at what RGAA needs today:
+
+| Field | Meaning |
+|---|---|
+| `tag` | intrinsic tag (case-insensitive) |
+| `attrs[]` | `{ name, op, value? }` — `op` ∈ `present` \| `absent` \| `equals` \| `matches` (regex, ReDoS-guarded, case-insensitive) |
+| `text` | `{ op, value }` — `op` ∈ `matches` \| `lacks` over the element's visible text (regex, case-insensitive) |
+| `has[]` / `lacks[]` | descendant conditions (each a match node); **nesting ≤ 3 levels** |
+| `scope` | `page` (full document only) \| `fragment` (default) |
+
+Anything more expressive — sibling/positional combinators, arbitrary CSS selectors,
+cross-file resolution — is **out of scope on purpose**: it belongs in a core WCAG-keyed
+engine rule instead, where every standard benefits. `pack check` rejects a rule whose
+criterion doesn't exist, whose SC isn't a real WCAG criterion, whose regex is unsafe/won't
+compile, whose has/lacks nest too deep, or whose `message`/`remediation` is missing `en`
+or `fr`. It also rejects a **match node with no condition** (`{}` — it would fire on every
+element) and a match node carrying an **unknown key** (a typo like `{ tgo: "a" }` is a hard
+error, never silently ignored): every node must carry ≥1 of `tag`/`attrs`/`text`/`has`/`lacks`.
+The **ReDoS guard** on every regex rejects the classic single-quantified-atom shape
+(`(a+)+`), an overlapping alternation under a quantifier (`(a|a)*`), and a nested quantifier
+over a group (`(ab+)+`) — while still accepting an anchored criterion grammar like `(\.\d+)*`
+and a non-quantified extension alternation like `(pdf|docx?|zip)`.
+
+### `overrides` — re-normativize within a projection
+
+```json
+{ "overrides": { "pack:rgaa:some-rule": { "advisory": false, "severity": "majeur" } } }
+```
+
+`overrides` is a map keyed by a finding's `ruleId` (a core engine rule, or a pack rule).
+Applied **only** in `derivePackResults`, it flips a finding's normativity
+(advisory↔normative) and/or re-grades its severity **inside that pack's projection** — the
+core WCAG result is never mutated. This is the precise *"WCAG can differ from RGAA"*
+mechanism: a standard can treat as normative something WCAG leaves advisory (or vice
+versa) without changing the canonical engine verdict.
+
+### `sampleMethodology` — the standard's required page kinds
+
+A country standard defines its audit over a **normative page sample** (see
+`references/audit.md`). A pack declares the page KINDS a real audit of it must cover; the
+mechanics (a project's actual `sample.pages`) live in `.ultra11yrc.json`, never in the pack.
+
+```json
+{ "sampleMethodology": {
+    "requiredKinds": [
+      { "id": "accueil", "label": { "fr": "Page d'accueil" }, "keywords": ["accueil", "home"] },
+      { "id": "mentions-legales", "label": { "fr": "Mentions légales" }, "keywords": ["mentions", "legal"] },
+      { "id": "declaration-accessibilite", "label": { "fr": "Déclaration d'accessibilité" }, "keywords": ["declaration", "accessibilite"] }
+    ] } }
+```
+
+`sample check` fuzzy-matches (accent-insensitive) each required kind's `keywords` against the
+configured pages' name/notes/url and reports the missing kinds. It is purely **advisory**
+(the sample is opt-in, the missing kinds are guidance not a gate), so a malformed
+`sampleMethodology` is a validator **warning** and the field is ignored — never a hard
+failure that blocks the pack from deriving reports. RGAA ships the reference list (accueil,
+contact, mentions légales, déclaration d'accessibilité, plan du site, aide, authentification,
+pages représentatives + éléments transverses).
+
+## Gate-compatibility note (id grammar)
+
+`check` and `verify` recognize a pack's criterion ids in a rendered report by building
+their citation regex FROM the pack's own `idPattern` (already validated compilable by
+`pack check`) — not a single fixed shape. RGAA's 2-segment `<n>.<n>` (`8.3`) and a
+hypothetical Section 508 `E<n>.<n>` (`E205.4`) are both fully gate-compatible out of the
+box; any `idPattern` a pack declares works, with zero engine changes.