ultra11y 4.4.1 → 4.5.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "ultra11y",
       "source": "./",
       "description": "Automatic accessibility review of the code under change before every commit, push and pull request, plus full WCAG 2.2 AA / RGAA audits and conformance deliverables on demand.",
-      "version": "4.4.1",
+      "version": "4.5.1",
       "author": { "name": "maxgfr" },
       "homepage": "https://github.com/maxgfr/ultra11y",
       "repository": "https://github.com/maxgfr/ultra11y",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "author": { "name": "maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): an automatic review of the code under change before every commit, push and pull request, plus full audits and conformance deliverables on demand.",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "author": { "name": "maxgfr", "url": "https://github.com/maxgfr" },
   "homepage": "https://github.com/maxgfr/ultra11y",
   "repository": "https://github.com/maxgfr/ultra11y",

package/.opencode/plugins/ultra11y.js

@@ -27,7 +27,7 @@ import { fileURLToPath } from "node:url";
 // Ownership marker: `ultra11y install --opencode` refuses to overwrite a plugin file that
 // does not carry it, so a user's own ultra11y.js is never clobbered.
 const ULTRA11Y_OPENCODE_PLUGIN = "ULTRA11Y_OPENCODE_PLUGIN";
-const ULTRA11Y_PLUGIN_VERSION = "4.4.1";
+const ULTRA11Y_PLUGIN_VERSION = "4.5.1";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/README.md

@@ -125,7 +125,7 @@ claude mcp add ultra11y -- npx -y ultra11y mcp
 **As a GitHub Action** — audits the PR diff and, optionally, the served pages:
 
 ```yaml
-- uses: maxgfr/ultra11y@v3
+- uses: maxgfr/ultra11y@v4
   with: { since: auto, standard: rgaa, fail-on: blocking }
 ```
 
@@ -383,7 +383,7 @@ a test). See [`CONTRIBUTING.md`](CONTRIBUTING.md) and `skills/ultra11y/reference
   block. It re-decides nothing and invents no format, so a page sheet and the compliance report
   cannot disagree; `check` gates it against invented criteria like any other report.
   See `references/pages.md`.
-- **A shipped GitHub Action** — `uses: maxgfr/ultra11y@main` audits the **code** (PR diff) and,
+- **A shipped GitHub Action** — `uses: maxgfr/ultra11y@v4` audits the **code** (PR diff) and,
   optionally, the **pages** (it can start your app, wait for it, then scan real URLs or your
   declared sample). The engine ships inside the action, so there is nothing to install and no
   `setup-node`. The gate runs **last**, after SARIF, annotations, the summary, the sticky PR

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "4.4.1",
+  "version": "4.5.1",
   "description": "Audit HTML/CSS/JSX against WCAG 2.2 AA and produce a dated compliance report, or author/review accessible markup (native-HTML-first). A skills.sh agent skill: an install-free static engine (bundled, no npm install) plus the agent's judgment, with check/verify gates against hallucinated non-conformities, and pluggable in-repo standards packs (RGAA France first; Section 508 & EN 301 549 next).",
   "type": "module",
   "packageManager": "pnpm@10.33.0",

package/scripts/build-standards.mjs

@@ -13,6 +13,7 @@
 //   node scripts/build-standards.mjs --offline       # same (alias; the snapshots are always local)
 //   node scripts/build-standards.mjs --refresh <dir> # re-derive the vendored AA snapshot from a w3c/wcag checkout
 //   node scripts/build-standards.mjs --refresh-universe # re-fetch (network) the vendored FULL SC universe (all levels + removed 4.1.1)
+//   node scripts/build-standards.mjs --refresh-core # re-derive the shipped AA snapshot from that universe (no checkout, no network)
 //   node scripts/build-standards.mjs --refresh-fr    # re-fetch (network) the vendored French SC/guideline/principle titles
 //   node scripts/build-standards.mjs --refresh-text  # re-fetch (network) the vendored NORMATIVE SC text + the WCAG glossary
 import { writeFileSync, readFileSync, readdirSync, existsSync, mkdirSync } from "node:fs";
@@ -398,6 +399,49 @@ async function deriveFr() {
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// Core mode: the shipped AA snapshot, derived from the vendored UNIVERSE.
+//
+// `deriveSnapshot` above reads a local w3c/wcag checkout, which is why it was the one
+// vendored source the daily refresh could not touch — a new or renamed success criterion
+// would land in the universe and never reach the shipped core.
+//
+// It needs no checkout and no extra network: `--refresh-universe` already fetches the same
+// numbering and titles for EVERY criterion, and records which are `core-AA`. The AA slice
+// is that filter. Byte-identical to what the checkout produces (tests/wcag-core-sync).
+//
+//   node scripts/build-standards.mjs --refresh-core
+// ---------------------------------------------------------------------------
+function deriveCoreFromUniverse() {
+  if (!existsSync(VENDOR_UNIVERSE)) {
+    console.error(`build-standards --refresh-core: missing ${VENDOR_UNIVERSE}. Run: node scripts/build-standards.mjs --refresh-universe`);
+    process.exit(1);
+  }
+  const universe = JSON.parse(readFileSync(VENDOR_UNIVERSE, "utf8"));
+  const aa = universe.criteria.filter((c) => c.status === "core-AA").map(({ status, ...rest }) => rest);
+  if (!aa.length) {
+    console.error(`build-standards --refresh-core: ${VENDOR_UNIVERSE} classifies no criterion as core-AA — refusing to write an empty core.`);
+    process.exit(1);
+  }
+  const used = new Set(aa.map((c) => c.guideline));
+  const snapshot = {
+    wcagVersion: universe.wcagVersion,
+    source: universe.source,
+    criteriaSource: universe.criteriaSource,
+    principles: universe.principles.map((p) => ({ number: p.number, title: p.title })),
+    guidelines: universe.guidelines.filter((g) => used.has(g.number)).map((g) => ({ number: g.number, title: g.title })),
+    criteria: aa,
+  };
+  return JSON.stringify(snapshot, null, 2) + "\n";
+}
+
+function refreshCore() {
+  const text = deriveCoreFromUniverse();
+  mkdirSync(dirname(VENDOR), { recursive: true });
+  writeFileSync(VENDOR, text);
+  console.log(`build-standards --refresh-core: ${JSON.parse(text).criteria.length} A/AA criteria derived from the vendored universe → ${VENDOR}`);
+}
+
 // ---------------------------------------------------------------------------
 // Text mode: the NORMATIVE WORDING of every shipped success criterion, plus the terms
 // WCAG itself defines.
@@ -830,6 +874,7 @@ async function main() {
   const refreshIdx = process.argv.indexOf("--refresh");
   if (refreshIdx !== -1) deriveSnapshot(process.argv[refreshIdx + 1]);
   if (process.argv.includes("--refresh-universe")) await deriveUniverse();
+  if (process.argv.includes("--refresh-core")) refreshCore();
   if (process.argv.includes("--refresh-fr")) await deriveFr();
   if (process.argv.includes("--refresh-text")) await deriveText();
   build();

package/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join50, relative as relative5, resolve as resolve15, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "4.4.1";
+var VERSION = "4.5.1";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -2289,7 +2289,7 @@ var wcag_universe_default = {
   wcagVersion: "2.2",
   source: "https://www.w3.org/TR/WCAG22/",
   criteriaSource: "https://github.com/w3c/wcag",
-  provenance: "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-14 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
+  provenance: "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-17 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
   criteria: [
     {
       id: "1.1.1",
@@ -58352,6 +58352,20 @@ var LIVE_REGION_DETAIL = {
 function clicksAllowed(storageState, interactClicks) {
   return interactClicks === true || !storageState;
 }
+function landedOnRequestedPage(requested, landed) {
+  if (!landed || requested === landed) return true;
+  const path = (u) => {
+    try {
+      return new URL(u, "http://x.invalid").pathname.replace(/\/+$/, "");
+    } catch {
+      return void 0;
+    }
+  };
+  const a = path(requested);
+  const b = path(landed);
+  if (a === void 0 || b === void 0) return true;
+  return a === b;
+}
 async function probeLiveRegion(page, lang, allowClicks) {
   const detail = LIVE_REGION_DETAIL[lang] ?? LIVE_REGION_DETAIL.en;
   return await page.evaluate(liveRegionExpr(detail, allowClicks)).catch(() => []);
@@ -58520,6 +58534,7 @@ async function runSampleScanLocal(pages, opts) {
   const browser = await launchChromium(chromium);
   const findings = [];
   const snapshots = [];
+  const redirected = [];
   try {
     for (const page of pages) {
       const storageState = page.storageState ?? opts.storageState;
@@ -58531,6 +58546,10 @@ async function runSampleScanLocal(pages, opts) {
         lang,
         snapshot: Boolean(opts.snapshotRoot)
       });
+      if (!landedOnRequestedPage(page.url, out2.url)) {
+        redirected.push({ id: page.id, name: page.name, requested: page.url, landed: out2.url });
+        continue;
+      }
       findings.push(...tagSampleFindings(toDynamicResult(out2, page.url, lang, LOCAL_ENGINE).findings, page));
       const id = opts.snapshotRoot ? writeRunnerSnapshot(opts.snapshotRoot, out2, page.url, page) : void 0;
       if (id) snapshots.push(id);
@@ -58546,7 +58565,8 @@ async function runSampleScanLocal(pages, opts) {
     findings,
     sample: sampleScope({ pages }),
     testedScs: localTestedScs(interact),
-    ...snapshots.length ? { snapshots } : {}
+    ...snapshots.length ? { snapshots } : {},
+    ...redirected.length ? { redirected } : {}
   };
 }
 async function runCrawlScanLocal(opts) {
@@ -66645,6 +66665,13 @@ async function cmdScan(p) {
     console.error(`ultra11y scan: ${e instanceof Error ? e.message : String(e)}`);
     return 1;
   }
+  if (dynamic.redirected?.length) {
+    for (const r of dynamic.redirected) {
+      console.error(
+        lang === "fr" ? `\u26A0\uFE0F ultra11y scan : \xAB ${r.name} \xBB (${r.id}) non enregistr\xE9e \u2014 ${r.requested} a redirig\xE9 vers ${r.landed}. L'enregistrer aurait d\xE9crit cet \xE9cran sous le nom du premier.` : `\u26A0\uFE0F ultra11y scan: "${r.name}" (${r.id}) not recorded \u2014 ${r.requested} redirected to ${r.landed}. Recording it would have described that screen under the first one's name.`
+      );
+    }
+  }
   if (useSample && sampleConfig) {
     const lintKey = typeof p.flags.standard === "string" && p.flags.standard ? p.flags.standard : "rgaa";
     try {

package/scripts/vendor/wcag-2.2-fr.json

@@ -1,6 +1,6 @@
 {
   "source": "https://www.w3.org/Translations/WCAG22-fr/",
-  "fetchedAt": "2026-08-14",
+  "fetchedAt": "2026-08-17",
   "principles": {
     "1": "Perceptible",
     "2": "Utilisable",

package/scripts/vendor/wcag-2.2-sc-universe.json

@@ -2,7 +2,7 @@
   "wcagVersion": "2.2",
   "source": "https://www.w3.org/TR/WCAG22/",
   "criteriaSource": "https://github.com/w3c/wcag",
-  "provenance": "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-14 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
+  "provenance": "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-17 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
   "principles": [
     {
       "number": 1,

package/scripts/vendor/wcag-2.2-techniques.json

@@ -2,7 +2,7 @@
   "source": "https://github.com/w3c/wcag",
   "understanding": "https://www.w3.org/WAI/WCAG22/Understanding/",
   "license": "W3C Document License (code samples: W3C Software License)",
-  "fetchedAt": "2026-08-14",
+  "fetchedAt": "2026-08-17",
   "criteria": {
     "1.1.1": {
       "slug": "non-text-content",

package/scripts/vendor/wcag-2.2-text.json

@@ -1,7 +1,7 @@
 {
   "source": "https://github.com/w3c/wcag",
   "license": "W3C Document License",
-  "fetchedAt": "2026-08-14",
+  "fetchedAt": "2026-08-17",
   "criteria": {
     "1.1.1": "All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed below.\nControls, Input:\nIf non-text content is a control or accepts user input, then it has a name that describes its purpose. (Refer to Success Criterion 4.1.2 for additional requirements for controls and content that accepts user input.)\nTime-Based Media:\nIf non-text content is time-based media, then text alternatives at least provide descriptive identification of the non-text content. (Refer to Guideline 1.2 for additional requirements for media.)\nTest:\nIf non-text content is a test or exercise that would be invalid if presented in text, then text alternatives at least provide descriptive identification of the non-text content.\nSensory:\nIf non-text content is primarily intended to create a specific sensory experience, then text alternatives at least provide descriptive identification of the non-text content.\nCAPTCHA:\nIf the purpose of non-text content is to confirm that content is being accessed by a person rather than a computer, then text alternatives that identify and describe the purpose of the non-text content are provided, and alternative forms of CAPTCHA using output modes for different types of sensory perception are provided to accommodate different disabilities.\nDecoration, Formatting, Invisible:\nIf non-text content is pure decoration, is used only for visual formatting, or is not presented to users, then it is implemented in a way that it can be ignored by assistive technology.",
     "1.2.1": "For prerecorded audio-only and prerecorded video-only media, the following are true, except when the audio or video is a media alternative for text and is clearly labeled as such:\nPrerecorded Audio-only:\nAn alternative for time-based media is provided that presents equivalent information for prerecorded audio-only content.\nPrerecorded Video-only:\nEither an alternative for time-based media or an audio track is provided that presents equivalent information for prerecorded video-only content.",

package/skills/review-a11y/SKILL.md

@@ -5,7 +5,7 @@ when_to_use: "Invoke WITHOUT being asked whenever changed front-end code should
 allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs *), Read, Grep, Glob
 license: MIT
 metadata:
-  version: 4.4.1
+  version: 4.5.1
 ---
 
 # review-a11y — accessibility review of changed code

package/skills/review-a11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join50, relative as relative5, resolve as resolve15, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "4.4.1";
+var VERSION = "4.5.1";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -2289,7 +2289,7 @@ var wcag_universe_default = {
   wcagVersion: "2.2",
   source: "https://www.w3.org/TR/WCAG22/",
   criteriaSource: "https://github.com/w3c/wcag",
-  provenance: "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-14 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
+  provenance: "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-17 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
   criteria: [
     {
       id: "1.1.1",
@@ -58352,6 +58352,20 @@ var LIVE_REGION_DETAIL = {
 function clicksAllowed(storageState, interactClicks) {
   return interactClicks === true || !storageState;
 }
+function landedOnRequestedPage(requested, landed) {
+  if (!landed || requested === landed) return true;
+  const path = (u) => {
+    try {
+      return new URL(u, "http://x.invalid").pathname.replace(/\/+$/, "");
+    } catch {
+      return void 0;
+    }
+  };
+  const a = path(requested);
+  const b = path(landed);
+  if (a === void 0 || b === void 0) return true;
+  return a === b;
+}
 async function probeLiveRegion(page, lang, allowClicks) {
   const detail = LIVE_REGION_DETAIL[lang] ?? LIVE_REGION_DETAIL.en;
   return await page.evaluate(liveRegionExpr(detail, allowClicks)).catch(() => []);
@@ -58520,6 +58534,7 @@ async function runSampleScanLocal(pages, opts) {
   const browser = await launchChromium(chromium);
   const findings = [];
   const snapshots = [];
+  const redirected = [];
   try {
     for (const page of pages) {
       const storageState = page.storageState ?? opts.storageState;
@@ -58531,6 +58546,10 @@ async function runSampleScanLocal(pages, opts) {
         lang,
         snapshot: Boolean(opts.snapshotRoot)
       });
+      if (!landedOnRequestedPage(page.url, out2.url)) {
+        redirected.push({ id: page.id, name: page.name, requested: page.url, landed: out2.url });
+        continue;
+      }
       findings.push(...tagSampleFindings(toDynamicResult(out2, page.url, lang, LOCAL_ENGINE).findings, page));
       const id = opts.snapshotRoot ? writeRunnerSnapshot(opts.snapshotRoot, out2, page.url, page) : void 0;
       if (id) snapshots.push(id);
@@ -58546,7 +58565,8 @@ async function runSampleScanLocal(pages, opts) {
     findings,
     sample: sampleScope({ pages }),
     testedScs: localTestedScs(interact),
-    ...snapshots.length ? { snapshots } : {}
+    ...snapshots.length ? { snapshots } : {},
+    ...redirected.length ? { redirected } : {}
   };
 }
 async function runCrawlScanLocal(opts) {
@@ -66645,6 +66665,13 @@ async function cmdScan(p) {
     console.error(`ultra11y scan: ${e instanceof Error ? e.message : String(e)}`);
     return 1;
   }
+  if (dynamic.redirected?.length) {
+    for (const r of dynamic.redirected) {
+      console.error(
+        lang === "fr" ? `\u26A0\uFE0F ultra11y scan : \xAB ${r.name} \xBB (${r.id}) non enregistr\xE9e \u2014 ${r.requested} a redirig\xE9 vers ${r.landed}. L'enregistrer aurait d\xE9crit cet \xE9cran sous le nom du premier.` : `\u26A0\uFE0F ultra11y scan: "${r.name}" (${r.id}) not recorded \u2014 ${r.requested} redirected to ${r.landed}. Recording it would have described that screen under the first one's name.`
+      );
+    }
+  }
   if (useSample && sampleConfig) {
     const lintKey = typeof p.flags.standard === "string" && p.flags.standard ? p.flags.standard : "rgaa";
     try {

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.4.1
+  version: 4.5.1
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/references/ci.md

@@ -15,7 +15,7 @@ permissions:
 steps:
   - uses: actions/checkout@v4
     with: { fetch-depth: 0 }        # the diff gate needs the base ref
-  - uses: maxgfr/ultra11y@v3      # or pin the exact version, as `init --ci` does
+  - uses: maxgfr/ultra11y@v4      # or pin the exact version, as `init --ci` does
     with:
       since: auto                   # the PR's base branch
       standard: rgaa
@@ -27,7 +27,7 @@ steps:
 Page by page, with a real browser, in the same step:
 
 ```yaml
-  - uses: maxgfr/ultra11y@v3
+  - uses: maxgfr/ultra11y@v4
     with:
       standard: rgaa
       start: npm run start
@@ -66,7 +66,7 @@ partial by construction. `adjudicate` closes that — opt-in, in two modes.
 env:
   ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}   # the job's env, never an input
 steps:
-  - uses: maxgfr/ultra11y@v3
+  - uses: maxgfr/ultra11y@v4
     with:
       standard: rgaa
       adjudicate: api          # or `agent`
@@ -89,14 +89,43 @@ open the cited files and read around them, which is what *link purpose **in cont
 asks for. Expect the API mode to answer `manual` more often; that is it being honest, not
 broken. The metric that separates them is the count of criteria left to assess.
 
-**Both modes read `ANTHROPIC_API_KEY` from the job environment, never from an input** — a
+**Both modes read their credential from the job environment, never from an input** — a
 composite action's steps inherit it, and a secret that never travels through an input is one
-fewer secret to leak into a log. When the key is absent the tier **skips itself**: the job stays
+fewer secret to leak into a log. When it is absent the tier **skips itself**: the job stays
 green, the report is still written, and the criteria stay « à évaluer ». That is not an edge
 case — it is precisely what a **fork's pull request** looks like, where secrets are never
 exposed. An adjudication that fails mid-flight (a rate-limited batch refuses the whole fold) is
 absorbed the same way, because losing the verdicts must never cost you the audit.
 
+**The two modes do not take the same credential.** `api` runs `judge`, which speaks `x-api-key`
+to `api.anthropic.com`; nothing else stands in for `ANTHROPIC_API_KEY` there. `agent` shells out
+to `claude-code-action`, which accepts **either** an API key **or** the OAuth token a Pro/Max
+subscriber mints with `claude setup-token` — so a repository that already runs Claude Code in CI
+and holds only `CLAUDE_CODE_OAUTH_TOKEN` can adjudicate without buying API credit. Set whichever
+you have; set both and the API key wins.
+
+```yaml
+env:
+  # `agent` takes either of these. `api` takes only the first.
+  ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+  CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+```
+
+Asking for `api` with only the OAuth token is a warning, not a failure — the tier skips and says
+which credential it would have needed, rather than failing a request the Messages API was always
+going to reject.
+
+**`agent` cannot run on every event.** `claude-code-action` resolves the GitHub event context
+*before* it reads the prompt, and throws `Unsupported event type: <event>` on anything outside
+`pull_request`, `pull_request_target`, `pull_request_review(_comment)`, `issues`,
+`issue_comment`, `workflow_dispatch`, `repository_dispatch`, `schedule` and `workflow_run`.
+**`push` is not in that list** — and `push` is exactly what an accessibility gate runs on. So the
+tier checks the event and degrades to a warning there, the same way it does without a credential:
+an a11y job must never go red for a reason that has nothing to do with accessibility. Put the
+agent tier on the `pull_request` or `schedule` job, or use `adjudicate: api`, which has no such
+constraint. The action also hands `claude-code-action` the job's own `GITHUB_TOKEN`, so this tier
+never obliges you to add `id-token: write` for a step that makes no GitHub API call.
+
 **Cost is per run and does not amortise.** Roughly $0.20 for a WCAG run and $0.50 for RGAA at
 Sonnet pricing — the worklist is re-sent whole each time and no batch is large enough to earn
 prompt caching. On a busy repository that is real money per push; this belongs on the default
@@ -235,7 +264,7 @@ The action audits the **code** and, when you point it at a served app, the **pag
 list can come from three places, and none of them has to be written by hand:
 
 ```yaml
-- uses: maxgfr/ultra11y@v3
+- uses: maxgfr/ultra11y@v4
   with:
     standard: rgaa
     start: npm run start
@@ -262,6 +291,40 @@ Two surfaces come out of it:
 
 A run with no page in scope is not a failure: the report step says so and the job carries on.
 
+### Pages behind a login (`storage-state`)
+
+The pages worth auditing are rarely the public ones. A form-heavy funnel, a dashboard, a
+back-office — all of them sit behind a sign-in, and a scan that reaches them anonymously does
+not fail: it records **the sign-in screen** under the name of the page you asked for. That is
+the worst failure mode an accessibility report has, because the document looks complete.
+
+Produce a Playwright `storageState` in the job — most repositories already have one, written by
+the setup project their E2E suite depends on — and hand the action its path:
+
+```yaml
+- run: npx playwright test --project=setup      # your existing login, writing the session file
+- uses: maxgfr/ultra11y@v4
+  with:
+    standard: rgaa
+    sample: 'true'
+    storage-state: test-results/.auth/user.json
+```
+
+The path is forwarded to Playwright as a path and never read by the engine, so a session file
+cannot end up in the job log. A per-page `storageState` in `.ultra11yrc.json` **overrides** this
+one, so a sample can mix public and signed-in pages in a single run.
+
+Two things worth knowing about an authenticated scan:
+
+- **The click probe is off.** With a session loaded, a click can trigger a real mutation on a
+  real record. The live-region probe still fills inputs and re-measures, but it does not click
+  buttons unless you set `interact-clicks: 'true'`. (Buttons whose accessible name reads
+  destructive are never clicked, session or not.)
+- **A session is not a state machine.** Being signed in gets you past the login; it does not put
+  a multi-step funnel on step 4. If a route is guarded by application state, seed that state in
+  the job before scanning — otherwise the page redirects and you are back to auditing the wrong
+  screen under the right name.
+
 ## What the artifact looks like when you open it
 
 `audits/` used to hold JSON, SARIF and Markdown: everything a machine needs and nothing that
@@ -395,9 +458,9 @@ one job — the code diff, then the served pages — died on a `409 Conflict`, w
 written and never uploaded. Pass `artifact-name` on each invocation:
 
 ```yaml
-- uses: maxgfr/ultra11y@v3
+- uses: maxgfr/ultra11y@v4
   with: { since: auto, artifact-name: a11y-code }
-- uses: maxgfr/ultra11y@v3
+- uses: maxgfr/ultra11y@v4
   with: { crawl: http://localhost:3000, artifact-name: a11y-pages }
 ```
 

package/skills/ultra11y/references/pages.md

@@ -220,7 +220,17 @@ Sheets are named `page-<id>.md`: a page whose id is `index` — the ordinary id
 gates that mean something here — above all **no invented criterion** — instead of demanding
 the §1–5 structure of a conformance document.
 
-### Three honesty rules
+### Four honesty rules
+
+**0. A page is recorded only if the browser stayed on it.** A sample page's declared `id` and
+`name` are the identity the report speaks, and they are applied to whatever was on screen. So a
+route that redirects — an expired session bouncing to sign-in, a wizard step the application
+state does not open — would be filed under the requested page's name while showing something
+else: a sheet, a screenshot and a rate that describe a different screen, with nothing about the
+document looking wrong. `scan --sample` compares the landed **path** against the requested one
+(a query string or fragment the app appends is the same page) and **drops** a page that moved,
+naming it and where it went. A page reported missing is a bug in the sample or in the state you
+seeded, and both are fixable; a page reported under the wrong name is a false conformance claim.
 
 **1. A finding is attributed to a page only when something says so.** In order: the snapshot
 path it was raised on (`.ultra11y/pages/<id>/dom.html` — the id is *in the path*, which is what

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join50, relative as relative5, resolve as resolve15, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "4.4.1";
+var VERSION = "4.5.1";
 var SCHEMA_VERSION = 2;
 
 // src/audit.ts
@@ -2289,7 +2289,7 @@ var wcag_universe_default = {
   wcagVersion: "2.2",
   source: "https://www.w3.org/TR/WCAG22/",
   criteriaSource: "https://github.com/w3c/wcag",
-  provenance: "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-14 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
+  provenance: "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-17 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
   criteria: [
     {
       id: "1.1.1",
@@ -58352,6 +58352,20 @@ var LIVE_REGION_DETAIL = {
 function clicksAllowed(storageState, interactClicks) {
   return interactClicks === true || !storageState;
 }
+function landedOnRequestedPage(requested, landed) {
+  if (!landed || requested === landed) return true;
+  const path = (u) => {
+    try {
+      return new URL(u, "http://x.invalid").pathname.replace(/\/+$/, "");
+    } catch {
+      return void 0;
+    }
+  };
+  const a = path(requested);
+  const b = path(landed);
+  if (a === void 0 || b === void 0) return true;
+  return a === b;
+}
 async function probeLiveRegion(page, lang, allowClicks) {
   const detail = LIVE_REGION_DETAIL[lang] ?? LIVE_REGION_DETAIL.en;
   return await page.evaluate(liveRegionExpr(detail, allowClicks)).catch(() => []);
@@ -58520,6 +58534,7 @@ async function runSampleScanLocal(pages, opts) {
   const browser = await launchChromium(chromium);
   const findings = [];
   const snapshots = [];
+  const redirected = [];
   try {
     for (const page of pages) {
       const storageState = page.storageState ?? opts.storageState;
@@ -58531,6 +58546,10 @@ async function runSampleScanLocal(pages, opts) {
         lang,
         snapshot: Boolean(opts.snapshotRoot)
       });
+      if (!landedOnRequestedPage(page.url, out2.url)) {
+        redirected.push({ id: page.id, name: page.name, requested: page.url, landed: out2.url });
+        continue;
+      }
       findings.push(...tagSampleFindings(toDynamicResult(out2, page.url, lang, LOCAL_ENGINE).findings, page));
       const id = opts.snapshotRoot ? writeRunnerSnapshot(opts.snapshotRoot, out2, page.url, page) : void 0;
       if (id) snapshots.push(id);
@@ -58546,7 +58565,8 @@ async function runSampleScanLocal(pages, opts) {
     findings,
     sample: sampleScope({ pages }),
     testedScs: localTestedScs(interact),
-    ...snapshots.length ? { snapshots } : {}
+    ...snapshots.length ? { snapshots } : {},
+    ...redirected.length ? { redirected } : {}
   };
 }
 async function runCrawlScanLocal(opts) {
@@ -66645,6 +66665,13 @@ async function cmdScan(p) {
     console.error(`ultra11y scan: ${e instanceof Error ? e.message : String(e)}`);
     return 1;
   }
+  if (dynamic.redirected?.length) {
+    for (const r of dynamic.redirected) {
+      console.error(
+        lang === "fr" ? `\u26A0\uFE0F ultra11y scan : \xAB ${r.name} \xBB (${r.id}) non enregistr\xE9e \u2014 ${r.requested} a redirig\xE9 vers ${r.landed}. L'enregistrer aurait d\xE9crit cet \xE9cran sous le nom du premier.` : `\u26A0\uFE0F ultra11y scan: "${r.name}" (${r.id}) not recorded \u2014 ${r.requested} redirected to ${r.landed}. Recording it would have described that screen under the first one's name.`
+      );
+    }
+  }
   if (useSample && sampleConfig) {
     const lintKey = typeof p.flags.standard === "string" && p.flags.standard ? p.flags.standard : "rgaa";
     try {

package/src/cli.ts

@@ -3044,6 +3044,18 @@ async function cmdScan(p: ParsedArgs): Promise<number> {
     console.error(`ultra11y scan: ${e instanceof Error ? e.message : String(e)}`);
     return 1;
   }
+  // Pages the scan refused to file, because the browser ended up on another route. Loud, and
+  // on stderr: a silently shorter sample is indistinguishable from a sample that passed, and
+  // the cause is always fixable — an expired session, or state the wizard step needs.
+  if (dynamic.redirected?.length) {
+    for (const r of dynamic.redirected) {
+      console.error(
+        lang === "fr"
+          ? `⚠️ ultra11y scan : « ${r.name} » (${r.id}) non enregistrée — ${r.requested} a redirigé vers ${r.landed}. L'enregistrer aurait décrit cet écran sous le nom du premier.`
+          : `⚠️ ultra11y scan: "${r.name}" (${r.id}) not recorded — ${r.requested} redirected to ${r.landed}. Recording it would have described that screen under the first one's name.`,
+      );
+    }
+  }
   // Advisory sample-methodology lint: which normative page KINDS the configured sample
   // lacks. Standard-agnostic mechanics + RGAA-specific required kinds; scan has no
   // --standard, so we lint against the config's default standard (else RGAA if registered).

package/src/data/wcag-universe.json

@@ -2,7 +2,7 @@
   "wcagVersion": "2.2",
   "source": "https://www.w3.org/TR/WCAG22/",
   "criteriaSource": "https://github.com/w3c/wcag",
-  "provenance": "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-14 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
+  "provenance": "Full WCAG 2.x SC universe (all levels incl. AAA, and the removed 4.1.1 Parsing) fetched from raw.githubusercontent.com/w3c/wcag@main on 2026-08-17 via `node scripts/build-standards.mjs --refresh-universe`. Classification: core-AA = ships in src/data/wcag.json (the shipped WCAG 2.2 AA core); out-of-core = WCAG AAA; removed = obsolete (4.1.1).",
   "criteria": [
     {
       "id": "1.1.1",

package/src/scan-local.ts

@@ -11,7 +11,7 @@
 import { existsSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { resolve } from "node:path";
-import type { DynamicFinding, DynamicResult, Lang, SamplePage } from "./types.js";
+import type { DynamicFinding, DynamicResult, Lang, SamplePage, ScanRedirect } from "./types.js";
 import { type DiscoverOpts, discoverUrls, type ProbeHit, type RunnerOutput, tagSampleFindings, toDynamicResult, writeRunnerSnapshot } from "./scan.js";
 import { sampleScope } from "./sample.js";
 import { COLLECT_SNAPSHOT, type CollectedPage } from "./snapshot.js";
@@ -604,6 +604,36 @@ export function clicksAllowed(storageState: string | undefined, interactClicks:
   return interactClicks === true || !storageState;
 }
 
+/** Did the browser end up on the page we ASKED for?
+ *
+ *  A sample page's declared id/name is the identity the report and the per-page grid speak,
+ *  and it is applied to whatever the browser had on screen. So a route that redirects — an
+ *  expired session bouncing to /login, a wizard step the application state does not open —
+ *  gets recorded under the requested page's name while showing another screen entirely.
+ *  Nothing about the resulting document looks wrong, which is what makes it the worst
+ *  failure mode an accessibility report has: a reader sees a page sheet, a screenshot and a
+ *  conformance rate, and none of it describes the page named at the top.
+ *
+ *  Only the PATH is compared. A query string or fragment the app appends to its own route is
+ *  the same page; a different path is a different page. Anything unparseable is treated as a
+ *  match — this guard exists to catch a redirect, not to invent one. Exported for the
+ *  browser-free policy test. */
+export function landedOnRequestedPage(requested: string, landed: string): boolean {
+  if (!landed || requested === landed) return true;
+  const path = (u: string): string | undefined => {
+    try {
+      // `file://` targets and relative paths never redirect; base makes them parseable.
+      return new URL(u, "http://x.invalid").pathname.replace(/\/+$/, "");
+    } catch {
+      return undefined;
+    }
+  };
+  const a = path(requested);
+  const b = path(landed);
+  if (a === undefined || b === undefined) return true;
+  return a === b;
+}
+
 async function probeLiveRegion(page: Any, lang: Lang, allowClicks: boolean): Promise<ProbeHit[]> {
   const detail = LIVE_REGION_DETAIL[lang] ?? LIVE_REGION_DETAIL.en;
   return (await page.evaluate(liveRegionExpr(detail, allowClicks)).catch(() => [])) as ProbeHit[];
@@ -880,6 +910,7 @@ export async function runSampleScanLocal(pages: SamplePage[], opts: LocalManyOpt
   const browser = await launchChromium(chromium);
   const findings: DynamicFinding[] = [];
   const snapshots: string[] = [];
+  const redirected: ScanRedirect[] = [];
   try {
     for (const page of pages) {
       const storageState = page.storageState ?? opts.storageState; // per-page override
@@ -891,6 +922,15 @@ export async function runSampleScanLocal(pages: SamplePage[], opts: LocalManyOpt
         lang,
         snapshot: Boolean(opts.snapshotRoot),
       });
+      // The declared identity is applied to whatever the browser had on screen, so a page
+      // that bounced elsewhere would be filed under the name of the page nobody looked at.
+      // Drop it instead, and say which one and where it went: a page reported missing is a
+      // bug in the sample or the seeded state, and both are fixable. A page reported under
+      // the wrong name is neither — it is a false conformance claim.
+      if (!landedOnRequestedPage(page.url, out.url)) {
+        redirected.push({ id: page.id, name: page.name, requested: page.url, landed: out.url });
+        continue;
+      }
       findings.push(...tagSampleFindings(toDynamicResult(out, page.url, lang, LOCAL_ENGINE).findings, page));
       // The sample page's declared id/name/auth/notes win over anything derived from the
       // URL: that identity is what the report and the per-page grid speak.
@@ -909,6 +949,7 @@ export async function runSampleScanLocal(pages: SamplePage[], opts: LocalManyOpt
     sample: sampleScope({ pages }),
     testedScs: localTestedScs(interact),
     ...(snapshots.length ? { snapshots } : {}),
+    ...(redirected.length ? { redirected } : {}),
   };
 }
 

package/src/types.ts

@@ -1,6 +1,6 @@
 // Single source of truth for shared types + the embedded version. sync-version.mjs
 // rewrites VERSION at release time (kept in lockstep with package.json + SKILL.md).
-export const VERSION = "4.4.1";
+export const VERSION = "4.5.1";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,
@@ -47,6 +47,18 @@ export interface SampleScope {
   transverse?: string[];
 }
 
+// A sample page the scan REFUSED to record, because the browser ended up somewhere else —
+// a session that had expired, a wizard step the application state does not open. Recording
+// it would have filed another screen under this page's name, which reads as a complete
+// report and is a false conformance claim. Reported so the sample or the seeded state can
+// be fixed; never silently dropped.
+export interface ScanRedirect {
+  id: string;
+  name: string;
+  requested: string;
+  landed: string;
+}
+
 // ---- WCAG 2.2 canonical core (src/data/wcag.json, produced by scripts/build-standards.mjs)
 // The engine's canonical key. Success-criterion ids/titles/levels are derived from the
 // official W3C source (https://github.com/w3c/wcag); rule coverage + automatability are
@@ -560,4 +572,7 @@ export interface DynamicResult {
   // static rules never ran against its DOM, so src/pages.ts keeps it `manual` forever).
   // Empty/absent when snapshotting was off or every collection failed. Optional/additive.
   snapshots?: string[];
+  // Sample pages dropped because the browser landed on a different path than the one asked
+  // for. Absent when every page was reached. Optional/additive — see ScanRedirect.
+  redirected?: ScanRedirect[];
 }