ultra11y 4.3.0 → 4.4.0

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD backlog, or tickets (GitHub/GitLab/Jira); author accessible markup from scratch; wire the repo gate (init --hook/--ci) or a rendered-DOM capture pipeline. For a review of the code UNDER CHANGE (diff, branch, PR), use the `review-a11y` skill instead."
 license: MIT
 metadata:
-  version: 4.3.0
+  version: 4.4.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup
@@ -47,17 +47,25 @@ adjudicates. So the engine's clean run is a starting point, never a verdict —
 >    *judgment* criterion itself (`verify --manual`, gated), and the *rendering* criteria go to
 >    `scan`; any criterion still unproven stays "to assess manually" — no status without a
 >    recorded, justified verdict.
-> 5. **The FINAL rendered semantic HTML must be correct.** The engine sees only source; a
+> 5. **Look the criterion up; never recall it.** `criteria [--standard <pack>] <id>` — or
+>    `ultra11y_criteria` over MCP — returns the criterion's own wording, its **numbered
+>    tests**, and the glossary definitions those tests cite. RGAA 8.3 is not "the page needs a
+>    `lang` attribute"; it is test `8.3.1` with two alternative conditions, and the glossary
+>    decides what its terms mean. An auditor block that cites `8.3.1` after reading it is
+>    grounded; one that cites it from memory is a guess wearing a reference. Before auditing
+>    against a country standard, run the plan (`ultra11y_method`): it tells you how many of its
+>    criteria no tool will decide for you — for RGAA, **58 of 106**. See `references/mcp.md`.
+> 6. **The FINAL rendered semantic HTML must be correct.** The engine sees only source; a
 >    component library (DSFR/MUI…) or `.vue`/`.svelte`/`.astro` SFC hides the real markup, so
 >    a green source audit is not proof. Verify the produced semantic HTML — install the
 >    zero-touch **capture** harvester (`render --setup`) so every component your tests render
 >    is serialized to `.ultra11y/captures` and audited, with `audit --require-captures` gating
 >    the blind spots. See `references/automation.md` / `rendered.md`.
-> 6. **Language**: ALWAYS pass `--lang` matching the language of your conversation with
+> 7. **Language**: ALWAYS pass `--lang` matching the language of your conversation with
 >    the user; ask the user when ambiguous. Without the flag the CLI auto-detects (repo
 >    `<html lang>` → the active standard's default locale → English) — a scripted/CI
 >    fallback, not a substitute for passing `--lang` yourself.
-> 7. **Technical tokens stay in English, even in French prose.** In any French deliverable
+> 8. **Technical tokens stay in English, even in French prose.** In any French deliverable
 >    you write (report commentary, PRD, tracker tickets, judgment verdicts), attribute/
 >    element/role names and their values are code, not prose — never translate them:
 >    `aria-live` stays `aria-live` (never « région live »), same for `tabindex`, `alt`,
@@ -102,6 +110,7 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 | `references/prd.md` | The auditor block as a backlog (markdown) |
 | `references/tickets.md` | Filing that backlog as tickets: GitHub, GitLab, Jira, and at which granularity |
 | `references/standards.md` · `references/packs.md` · `references/guidance.md` | Country standards, authoring a pack, implementation guidance |
+| `references/mcp.md` | **The standards as a rule engine**: look a criterion up instead of recalling it — its numbered tests, the terms it defines, the fix, and the work plan. As MCP tools and `std://` resources, or the same data on the CLI |
 | `references/methodology.md` | Statuses, pass rate, severities, report format |
 | `references/cross-file.md` | `--graph`: imports and cross-file rules |
 | `references/orchestration.md` | Fanning the judgment phases out across subagents |

package/skills/ultra11y/references/guidance.md

@@ -12,7 +12,8 @@ Guidance is looked up at **render time** by criterion / WCAG SC, so the canonica
 
 - **`prd`** — each backlog item gains a before/after example and an effort estimate; the
   `--format doc` PRD weaves it into the user stories and acceptance criteria.
-- **`criteria`** lookups for a pack criterion.
+- **`ultra11y_guidance`** over MCP — the direct lookup, by criterion.
+- **`ultra11y_criteria`** with `include_guidance: true`, attached to the criterion.
 
 Because attachment is presentation-only, guidance never marks anything conforming and
 never invents a non-conformity — it is illustration, not detection.
@@ -21,12 +22,37 @@ never invents a non-conformity — it is illustration, not detection.
 
 A guidance dataset is JSON: `{ pack, source, license, attribution, entries[] }`, where
 each entry is `{ id, criterionId, wcag[], title, summary, impact?, examples[], reference }`
-and an example is `{ lang: "html"|"jsx"|"css", bad?, good?, note? }`. The built-in RGAA
-guidance ships at `src/data/guidance/rgaa.json` (its entry ids mirror the SocialGouv rule
-files). Load external guidance with `--pack <dir>` (a `guidance.json` beside `pack.json`)
-or a `.ultra11yrc.json` `guidance` list. `pack check --guidance` validates that every
-entry resolves to a real criterion, maps to recognized WCAG SCs, and that every example
-parses.
+and an example is `{ lang: "html"|"jsx"|"css", bad?, good?, note? }`. Two ship built in:
+`src/data/guidance/rgaa.json` (93 entries, ids mirroring the SocialGouv rule files) and
+`src/data/guidance/wcag.json` (the WCAG-keyed set). Load external guidance with
+`--pack <dir>` (a `guidance.json` beside `pack.json`) or a `.ultra11yrc.json` `guidance`
+list. `pack check --guidance` validates that every entry resolves to a real criterion,
+maps to recognized WCAG SCs, and that every example parses.
+
+## Inheritance — why a new country pack is useful on day one
+
+Every entry declares the WCAG success criteria it implements, and a lookup walks **every**
+registered dataset. So a pack that ships no guidance of its own still gets examples, through
+the criteria it maps onto — a freshly authored Section 508 or EN 301 549 pack inherits the
+whole corpus the moment its `wcag[]` mappings exist.
+
+Resolution order (first wins, deduped by entry id):
+
+1. the pack's own entry for that criterion → `via: "pack"`, `inherited: false`
+2. every entry keyed to each WCAG SC the criterion maps to, in the pack's own SC order →
+   `via: "wcag:<sc>"`, `inherited: true`
+
+**The marking is the point.** An inherited example is not the national standard's own
+doctrine, and a report that presented it as one would be making a claim nobody wrote. Every
+surface carries `inherited` / `via`, and each entry also carries `languagesAvailable` — the
+RGAA dataset is French-first, so an English caller must be told when an entry has no English
+text rather than handed French silently.
+
+`src/data/guidance/wcag.json` exists for the one thing no country dataset can supply: the
+**ten AA criteria RGAA 4.1.2 never covered** — `1.2.4`, `2.3.1`, `2.4.5`, `2.4.11`, `2.5.7`,
+`2.5.8`, `3.2.6`, `3.3.3`, `3.3.7`, `3.3.8`. Six were added in WCAG 2.2, after RGAA
+(`wcagVersion: 2.1`) froze. With it in place, **no AA success criterion is without reachable
+guidance**, for any pack.
 
 ## Honesty rule — guidance is NOT a free detector
 

package/skills/ultra11y/references/harnesses.md

@@ -91,8 +91,18 @@ every `references/*.md` are exposed as `skill://` resources, plus three prompts
 
 ```
 claude mcp add ultra11y -- npx -y ultra11y mcp
+
+# better: dedicate it to one project, so `cwd` is optional on every tool AND that
+# project's own standards packs (.ultra11yrc.json) are loaded at startup
+claude mcp add ultra11y -- npx -y ultra11y mcp --cwd /abs/path/to/project
 ```
 
+It also carries the **standards themselves** — the reference block (`ultra11y_standards`,
+`ultra11y_criteria`, `ultra11y_glossary`, `ultra11y_guidance`, `ultra11y_method`) and the
+`std://` resources. That is the half that turns the server into a rule engine rather than a
+linter: an agent can read a criterion's numbered tests and the terms it defines instead of
+recalling them. See `references/mcp.md`.
+
 On a harness with no skill system at all, **reading `SKILL.md` directly with the file-read
 tool is the blessed path**, not a workaround. Discover what exists by listing
 `skills/*/SKILL.md` and reading the frontmatter.

package/skills/ultra11y/references/mcp.md

@@ -0,0 +1,215 @@
+# The standards as a rule engine — the MCP reference surface
+
+The audit tools tell you what a page *does*. The reference tools tell you what the standard
+*requires*. Without the second half an agent audits from memory, and a criterion recalled
+from memory is how an invented non-conformity gets written.
+
+This page is that second half: five read-only tools and a `std://` resource scheme that hand
+you any registered standard's criteria, its normative wording, the terms it defines, the
+before/after patterns that implement it, and an up-front plan for how much of it any tool can
+decide at all.
+
+Everything here works offline, from data vendored into the bundle. Nothing calls a network
+service, and no key is needed.
+
+## The one rule that makes it a rule engine
+
+**Look the criterion up. Do not recall it.**
+
+`ultra11y_criteria` returns the criterion's own words and its own numbered tests. RGAA 8.3 is
+not "the page needs a lang attribute" — it is a numbered test with two alternative
+conditions, and the glossary decides what its terms mean. An auditor block that cites
+`8.3.1` after reading `8.3.1` is grounded; one that cites it from memory is a guess wearing a
+reference.
+
+## The five tools
+
+| Tool | Answers |
+|---|---|
+| `ultra11y_standards` | Which standards exist here, and how much of each any engine can decide |
+| `ultra11y_criteria` | One criterion in full — wording, numbered tests, techniques, mapping, defined terms — or the index, or one theme |
+| `ultra11y_glossary` | What a term the standard **defines** actually means, and which criteria it governs |
+| `ultra11y_guidance` | The before/after implementation pattern for a criterion |
+| `ultra11y_method` | The work plan: what the engine settles, what needs a render, what is yours |
+
+All five are read-only and closed-world. All five take an **optional** `cwd` — they read the
+standard, not your files. `cwd` still matters, because *which standards exist* is a fact
+about a project (see **Packs are per-project** below).
+
+### `ultra11y_criteria` — the lookup
+
+```jsonc
+{ "standard": "rgaa", "sc": "8.3", "lang": "fr" }
+```
+
+Returns the criterion's theme, its localized title, its **numbered tests** (`8.3.1` and its
+sub-conditions, verbatim), its W3C technique codes, the WCAG success criteria it maps to, the
+**glossary definitions its tests cite**, the per-SC decision protocol, and a `coverage` block
+saying what it would take to decide it. `text` is byte-identical to what
+`criteria --standard rgaa 8.3` prints, so the two can never drift.
+
+- `sc` and `criterion` are aliases. "8.3" is not a *success criterion*, and a worldwide tool
+  should not force a country criterion to be called one.
+- Omit the id for the index; pass `theme: 8` for one theme.
+- `glossary: "<term>"` looks a defined term up; `glossary: ""` lists them all.
+- `include_guidance: true` attaches the before/after patterns (off by default — they are large).
+
+For the WCAG core the same call returns the criterion's **normative text**, verbatim from the
+W3C source, with its exceptions and notes kept as labelled lines, plus the WCAG terms that
+wording links to. `lang: "fr"` resolves the W3C **authorized French translation** — title,
+requirement prose and glossary together, never a French heading over English requirements.
+
+### `ultra11y_method` — read this before auditing anything
+
+The plan, derived rather than guessed. Every criterion of the standard lands in exactly one
+**evidence tier**:
+
+| Tier | What decides it | Who produces the evidence |
+|---|---|---|
+| `source` | an engine rule, from the source tree | `ultra11y_audit` |
+| `cross-file` | an engine rule, across the dependency graph | `ultra11y_audit` with `graph: true` |
+| `rendered-page` | computed styles, laid-out boxes, the screenshot | `ultra11y render` / `dev` / an E2E capture, then audit again |
+| `browser` | a live rendered DOM | `ultra11y scan <target> --merge` (CLI — this server does not drive a browser) |
+| `judgment` | a reading of meaning | `ultra11y_adjudicate`, then you |
+| `out-of-scope` | nothing — every mapped SC is outside the AA core | declare it; never claim it |
+
+The buckets **partition** the standard: 106 RGAA criteria in, 106 out. The classification is a
+lookup over data the repo already ships — each criterion's declared rule applicability, the
+WCAG automatability class, the pack's own judgment flags — never a regex over the wording of a
+test.
+
+Two counts are deliberately separate, and the distinction is easy to lose:
+
+- **`sourceIsEnough`** — the source tree can prove it **conformant**.
+- **`canFailFromSource`** — an engine rule can **fail** it, even though source cannot pass it.
+
+RGAA 4.10 is flagged `judgment` (no tool may declare it conformant) and still carries
+`autoplay-media`, which can fail it outright. Collapsing the two axes into one boolean throws
+that coverage away.
+
+The headline number for RGAA: **58 of its 106 criteria declare that no engine rule can
+evidence them at all.** That is not a gap in the tool — it is the standard saying those are
+yours. A plan that hides it reads as coverage that does not exist.
+
+### `ultra11y_glossary` — the definitions are normative
+
+A standard's tests lean constantly on terms it defines itself. RGAA ships 119; WCAG defines
+101 of its own in English and 102 in the authorized French translation. "Relevant", "if necessary", "large scale", "pure decoration" mean what the
+glossary says they mean, and that is what decides the verdict — not the everyday sense of the
+word.
+
+Each lookup also returns `citedBy`: the criteria whose tests actually cite that definition.
+
+### `ultra11y_guidance` — illustration, never detection
+
+The before/after pattern for a criterion: a non-compliant snippet, the compliant fix, the note
+explaining the difference.
+
+A criterion with no guidance of its own **inherits** what is keyed to the WCAG success
+criteria it maps to, and every inherited entry is marked `inherited: true` with
+`via: "wcag:<sc>"`. That is what makes a newly added country pack useful the day it lands —
+but an inherited example is not the national standard's own doctrine, and a report must never
+present it as one.
+
+**Guidance never decides a verdict.** It illustrates. A pattern earns a detector only when it
+is statically decidable *and* maps to a criterion in the WCAG 2.2 AA core; everything else
+lives here. See `references/guidance.md` for the honesty rule in full.
+
+## Packs are per-project
+
+A standards pack is project configuration — it arrives with a `--pack` flag or a
+`.ultra11yrc.json`. So a long-lived server serves many projects, and which standards exist
+depends on whose project is asking.
+
+- Every tool's `cwd` selects the project whose packs are visible. They are resolved once per
+  root and cached.
+- Two projects may each define a different pack under the **same key** without either
+  shadowing the other.
+- A project's `secondaryMappings` are applied to a **copy** of the built-in pack, never to the
+  shared one — one project cannot re-key RGAA for every other project the server is serving.
+- A pack that does not validate is a **hard error**. The server refuses to answer for that
+  project rather than quietly answering about WCAG instead, because being answered about a
+  different standard than the one you asked about is the failure this tool exists to prevent.
+
+`standard` therefore carries **no enum**. An enum pinned when the tool list was built would
+reject a pack that is perfectly valid for the project being asked about. The handler
+validates against the registry instead and names the standards it does know.
+
+Start the server dedicated to one project when you can:
+
+```bash
+claude mcp add ultra11y -- npx -y ultra11y mcp --cwd /abs/path/to/project
+```
+
+## The `std://` resources
+
+Documentation in MCP is a *resource*, not a tool call. `resources/list` carries a small,
+bounded index per standard; the per-item URIs are **templates**, because enumerating RGAA's
+106 criteria and 119 terms would bloat every client's listing and go stale the moment a
+project's own pack registers.
+
+```
+std://rgaa/criteria              the criterion index
+std://rgaa/criteria/8.3          one criterion, in full
+std://rgaa/themes/8              one theme
+std://rgaa/glossary              every term the standard defines
+std://rgaa/glossary/lien         one definition
+std://rgaa/guidance/13.2         before/after patterns
+std://rgaa/method                the work plan
+std://rgaa/pack.json             the pack as loaded, with its licence and attribution
+std://wcag/criteria/1.4.3        the same, for the worldwide core
+```
+
+`resources/templates/list` declares the four templated forms.
+
+A `std://` read carries no `cwd` of its own, so it resolves against the **server's** project
+root — the same packs its tools serve, when you started it with `--cwd`. Without a default
+project it sees the built-ins only. That is one more reason to dedicate the server.
+
+A `std://` read never touches the filesystem: the `skill://` scheme and its realpath
+containment live in a separate module, because a non-filesystem branch inside a
+path-containment function is exactly where a traversal bug hides later.
+
+## The gate that follows from all this
+
+`ultra11y_check` refuses a criterion declared **conformant** whose evidence tier this audit
+never ran. Claiming 1.4.3 Contrast conformant from a source-only audit is refused by name,
+with the command that would produce the evidence.
+
+Scoped tight, so it refuses only what is unambiguously wrong: it needs the audit in hand, it
+reads only the engine-decided half of the conformity list, and an absent `pagesAudited` is
+read as *unknown*, never as zero. An agent's own ruling is left alone — that claim is bound by
+the semantic gate instead (`references/judgment.md`).
+
+`not-tested` and `not-applicable` are exempt throughout, and for the same reason: they assert
+nothing.
+
+## Driving it as an RGAA rule engine
+
+```
+1. ultra11y_standards                              → confirm rgaa is loaded here
+2. ultra11y_method   { standard: "rgaa" }          → 39 source · 4 rendered · 3 browser · 59 judgment · 1 out of scope
+3. ultra11y_audit    { cwd, graph: true }          → settles the source tier
+4. ultra11y render / scan --merge                  → produces the rendered and browser tiers
+5. ultra11y_adjudicate { standard: "rgaa" }        → the judgment tier, with its evidence
+   ├─ ultra11y_criteria { standard:"rgaa", sc }    → the numbered tests you rule against
+   ├─ ultra11y_glossary { standard:"rgaa", term }  → what its terms normatively mean
+   └─ ultra11y_guidance { standard:"rgaa", ... }   → the fix to recommend
+6. ultra11y_report   { standard: "rgaa" }          → the dated deliverable
+7. ultra11y_check    { standard: "rgaa" }          → nothing claimed beyond the evidence
+```
+
+Steps 2 and 5 are the ones that make it a rule engine rather than a linter. Skipping step 2
+means auditing without knowing that 59 of 106 criteria were never going to be decided by a
+tool; skipping the lookups in step 5 means ruling on criteria from memory.
+
+**A criterion nobody tested is untested, never conformant.** Every tool description repeats
+it, because the failure mode here is not a wrong answer — it is a confident silence.
+
+## Related
+
+- `references/harnesses.md` — wiring the server into Claude Code, Codex, OpenCode, Cursor
+- `references/packs.md` — authoring and runtime-loading a country pack
+- `references/guidance.md` — the guidance dataset and its honesty rule
+- `references/standards.md` — the pack format, and adding your country
+- `references/adjudication.md` — the decision protocol the judgment tier works from

package/skills/ultra11y/references/packs.md

@@ -18,6 +18,14 @@ node scripts/ultra11y.mjs report --in audit.json --standard section508 --pack ./
 / `guidance.json`), or a comma-separated list. Or declare it once in a `.ultra11yrc.json`
 at the project root:
 
+A pack loaded this way is a **first-class standard everywhere**, not just on the CLI: the
+MCP server resolves each project's packs from its own `.ultra11yrc.json`, so
+`ultra11y_criteria { standard: "<yourpack>" }`, `ultra11y_method`, `ultra11y_glossary` and
+the `std://<yourpack>/…` resources all work the moment it validates. Two projects may define
+different packs under the same key without either shadowing the other, and a project's
+`secondaryMappings` are applied to a *copy* of a built-in pack, never to the shared one. See
+`references/mcp.md`.
+
 ```json
 { "packs": ["./packs/section508.json"], "guidance": ["./packs/section508.guidance.json"], "standard": "section508" }
 ```

package/skills/ultra11y/references/standards.md

@@ -40,10 +40,28 @@ node scripts/ultra11y.mjs report   --in audits/audit-latest.json --standard rgaa
 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
+node scripts/ultra11y.mjs criteria --standard rgaa --glossary lien                 # a term the standard DEFINES
+node scripts/ultra11y.mjs criteria --standard wcag --glossary "large scale"        # the core defines its own terms too
 ```
 
 An unknown `--standard` value errors out (never a silent fallback to WCAG).
 
+**The core carries its own text, in both languages.** Each WCAG success criterion ships its
+normative wording verbatim (exceptions and notes kept as labelled lines), the terms WCAG
+defines, and the terms each criterion's wording links to. So `criteria 1.4.3` shows the
+4.5:1 requirement and its three exceptions rather than only naming the criterion — the same
+fidelity the RGAA pack has always had for its own criteria.
+
+`--lang fr` resolves the **W3C authorized French translation** throughout: the title, the
+requirement prose, and the glossary. There is no half-translated state where a French
+heading sits over English requirements — the build fails rather than ship one. The two W3C
+pages do not share definition slugs (the French page pluralizes many, and renames a few), so
+each language keeps its own term list and its own glossary keys; a build guard rejects any
+citation that does not resolve in its own language.
+
+Over MCP the same data is `ultra11y_criteria` and `std://wcag/criteria/1.4.3`; see
+`references/mcp.md`.
+
 ## Auditor vocabulary
 
 The `prd` **auditor block** (the default output) and the **GitHub issues** it files are