ultra11y 5.43.5 → 5.45.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "ultra11y",
       "source": "./",
       "description": "Automatic accessibility review before commit, push and pull request, plus detailed evidenced Markdown, HTML and per-page WCAG 2.2 AA / RGAA reports in Claude Code.",
-      "version": "5.43.5",
+      "version": "5.45.0",
       "author": { "name": "maxgfr" },
       "homepage": "https://github.com/SocialGouv/ultra11y",
       "repository": "https://github.com/SocialGouv/ultra11y",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): automatic review before commit, push and pull request, plus detailed evidenced Markdown, HTML and per-page conformance reports in interactive agent sessions.",
-  "version": "5.43.5",
+  "version": "5.45.0",
   "author": { "name": "maxgfr" },
   "homepage": "https://github.com/SocialGouv/ultra11y",
   "repository": "https://github.com/SocialGouv/ultra11y",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ultra11y",
   "description": "Accessibility for WCAG 2.2 AA and country standards (RGAA…): automatic review before commit, push and pull request, plus detailed evidenced Markdown, HTML and per-page conformance reports in interactive agent sessions.",
-  "version": "5.43.5",
+  "version": "5.45.0",
   "author": { "name": "maxgfr", "url": "https://github.com/maxgfr" },
   "homepage": "https://github.com/SocialGouv/ultra11y",
   "repository": "https://github.com/SocialGouv/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 = "5.43.5";
+const ULTRA11Y_PLUGIN_VERSION = "5.45.0";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/README.md

@@ -160,7 +160,7 @@ ultra11y verify   --report <md> [--conformities <ledger|adjudication.json> | --n
 ultra11y fix      <globs… | ->  [--write] [--iterate] [--changed | --since <ref> | --staged] [--safe] [--only <ids>] [--jsx] [--json]
 ultra11y init     [--hook] [--ci] [--baseline] [--fail-on blocking|major|minor]
 ultra11y pack     check <pack.json> [--guidance <g.json>]  |  scaffold                 # gate an (AI-)authored standards pack
-ultra11y scan     <url|file…> [--runtime auto|local|docker] [--cwd <dir>] [--storage-state <file>] [--merge <audit.json>] [--out <dir>] [--json]
+ultra11y scan     <url|file…> [--runtime auto|local|docker] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--merge <audit.json>] [--out <dir>] [--json]
 ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime …] [--merge <audit.json>] [--json]
 ultra11y mcp      [--transport stdio|http] [--cwd <dir>] [--allow-write] [--port <n>] [--bind <addr>] [--allow-remote]
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "5.43.5",
+  "version": "5.45.0",
   "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/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join52, relative as relative6, resolve as resolve17, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.43.5";
+var VERSION = "5.45.0";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -66879,6 +66879,13 @@ function resolveHostAnchor(file, snippet2) {
   }
   return null;
 }
+function scanPageSummary(dynamic, sampleSize) {
+  return {
+    ...sampleSize === void 0 ? {} : { sample: sampleSize },
+    recorded: dynamic.snapshots ?? [],
+    refused: (dynamic.redirected ?? []).map((r) => ({ id: r.id, reason: r.reason }))
+  };
+}
 function mergeDynamic(audit2, dynamic, lang = "en") {
   const merged = JSON.parse(JSON.stringify(audit2));
   const seenFindings = new Set(merged.findings.map(portableFindingId));
@@ -74160,9 +74167,9 @@ Usage:
   ultra11y init     [--hook] [--ci] [--baseline] [--fail-on blocking|major|minor]
   ultra11y judge    --in <audit.json> [--standard <pack>] [--runner api|claude|codex] [--grain batch|criterion] [--max <n>] [--model <id>] [--effort <level>] [--max-budget-usd <n>] [--timeout <s>] [--out <dir>] [--apply]   (adjudicate manual criteria \u2014 api needs ANTHROPIC_API_KEY; claude/codex reuse their CLI login; cli aliases claude)
   ultra11y pack     check <pack.json> [--guidance <g.json>] [--json]  |  pack scaffold
-  ultra11y scan     <url|file\u2026> [--runtime auto|local|docker] [--cwd <dir>] [--storage-state <file>] [--no-interact] [--interact-clicks] [--no-snapshot] [--merge <audit.json>] [--out <dir>] [--json]
-  ultra11y scan     --sample [--runtime \u2026] [--cwd <dir>] [--storage-state <file>] [--merge <audit.json>] [--json]   (scan the .ultra11yrc.json page sample)
-  ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime \u2026] [--cwd <dir>] [--merge <audit.json>] [--json]
+  ultra11y scan     <url|file\u2026> [--runtime auto|local|docker] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--no-interact] [--interact-clicks] [--no-snapshot] [--merge <audit.json>] [--out <dir>] [--json]
+  ultra11y scan     --sample [--runtime \u2026] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--merge <audit.json>] [--json]   (scan the .ultra11yrc.json page sample)
+  ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime \u2026] [--cwd <dir>] [--root <dir>] [--merge <audit.json>] [--json]
   ultra11y scan     --clean        (remove the dynamic-tier Docker image + temp contexts)
   ultra11y sample   check [--standard <pack>] [--json]   (lint the .ultra11yrc.json page sample vs the standard's required page kinds)
   ultra11y snapshot write [--root <dir>] [--fail-on blocking|major|minor] [--json]   (payload on stdin \u2192 .ultra11y/pages/<id>/ + audit it)
@@ -74406,7 +74413,8 @@ Options:
   --no-captures      audit: do NOT auto-detect/ingest .ultra11y/captures nor .ultra11y/pages
   --e2e              render: write the Playwright/Cypress fixtures into .ultra11y/e2e/
   --runner <name>    render --e2e: force playwright|cypress instead of auto-detecting
-  --root <dir>       snapshot: project root holding .ultra11y/pages (default: .)
+  --root <dir>       snapshot, scan: project root holding .ultra11y/pages (default: . \u2014
+                     scan writes the snapshots it collects under it)
   --port <n>         dev: port for the side-car (default: 4111); mcp: HTTP transport port
   --transport <k>    mcp: stdio (default) or http
   --bind <addr>      mcp --transport http: address to bind (default 127.0.0.1)
@@ -74492,7 +74500,9 @@ Options:
                      (exit 2 with the producing command if its worklist is missing)
   --eco              orchestrate: emit only RUNBOOK.md + agents/*.md \u2014 the explicit
                      sequential low-token path (also what a no-subagent harness follows)
-  --merge <file>     scan: fold dynamic findings into this AuditResult JSON
+  --merge <file>     scan: fold dynamic findings into this AuditResult JSON. With --json the
+                     printed document opens with a 'pages' summary of the run \u2014
+                     {sample, recorded, refused:[{id, reason}]} \u2014 beside the document
   --sitemap <url>    scan: scan every URL listed in a sitemap.xml
   --crawl <url>      scan: BFS same-origin links from a start URL (served HTML)
   --depth <n>        scan: crawl link-hop depth from the start URL   (default: no limit; 0 = no limit)
@@ -77031,6 +77041,10 @@ Iterated over ${rounds} round(s) to a fixpoint \u2014 ${totalWritten} file(s) wr
   }
   return 0;
 }
+function scanSnapshotRoot(flags2) {
+  if (flags2["no-snapshot"] === true) return void 0;
+  return typeof flags2.root === "string" && flags2.root ? resolve17(flags2.root) : process.cwd();
+}
 async function cmdScan(p) {
   const standard = stdOf(p, "scan");
   if (standard === null) return 2;
@@ -77083,7 +77097,7 @@ async function cmdScan(p) {
   const interactClicks = p.flags["interact-clicks"] === true;
   const sitemap = typeof p.flags.sitemap === "string" ? p.flags.sitemap : void 0;
   const crawl = typeof p.flags.crawl === "string" ? p.flags.crawl : void 0;
-  const snapshotRoot = p.flags["no-snapshot"] === true ? void 0 : process.cwd();
+  const snapshotRoot = scanSnapshotRoot(p.flags);
   const useSample = p.flags.sample === true;
   let sampleConfig;
   if (useSample) {
@@ -77211,7 +77225,19 @@ async function cmdScan(p) {
     mkdirSync18(out2, { recursive: true });
     const mergedDocument = auditDocumentFor(merged, standard, lang);
     writeFileSync21(join52(out2, "audit-latest.json"), JSON.stringify(mergedDocument, null, 2) + "\n");
-    if (p.flags.json) console.log(JSON.stringify(mergedDocument, null, 2));
+    if (p.flags.json)
+      console.log(
+        JSON.stringify(
+          // `pages` opens the printed document: what this scan recorded (the
+          // .ultra11y/pages ids) and refused, which the stderr warnings alone don't make
+          // countable. An extra top-level key the `--in` readers never look at, so the
+          // document beside it stays pipeable into report/verify — and the file above
+          // keeps the plain audit schema.
+          { pages: scanPageSummary(dynamic, sampleConfig?.pages.length), ...mergedDocument },
+          null,
+          2
+        )
+      );
     else {
       console.log(
         lang === "fr" ? `Audit statique + dynamique fusionn\xE9 \u2192 ${join52(out2, "audit-latest.json")} (${merged.conformancePct}% r\xE9ussite, ${merged.findings.length} findings).` : `Static + dynamic audit merged \u2192 ${join52(out2, "audit-latest.json")} (${merged.conformancePct}% pass rate, ${merged.findings.length} findings).`
@@ -77768,6 +77794,7 @@ export {
   COMMANDS,
   REMOVED_FLAGS,
   main,
-  parseArgs
+  parseArgs,
+  scanSnapshotRoot
 };
 // "Copyright" and "@license" are already caught by DIRECTIVE_RE.

package/skills/review-a11y/SKILL.md

@@ -3,7 +3,7 @@ name: review-a11y
 description: "Use to REVIEW changed frontend code for accessibility: staged files, a working diff, branch, or PR; prompts such as 'review a11y', 'is this accessible?', or 'anything to fix before merge?'; and hook or CI findings on a change. Run the bundled install-free engine with cross-file JSX/TSX analysis, then adjudicate candidates and return a severity-ranked WCAG 2.2 AA review with file:line fixes, residual rendering risks, and a verdict. Use `ultra11y` instead for whole-repo audits, dated conformance reports, country standards, PRD backlogs, or authoring accessible markup."
 license: MIT
 metadata:
-  version: 5.43.5
+  version: 5.45.0
 ---
 
 # review-a11y — accessibility review of changed code

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

@@ -6,7 +6,7 @@ import { join as join52, relative as relative6, resolve as resolve17, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.43.5";
+var VERSION = "5.45.0";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -66879,6 +66879,13 @@ function resolveHostAnchor(file, snippet2) {
   }
   return null;
 }
+function scanPageSummary(dynamic, sampleSize) {
+  return {
+    ...sampleSize === void 0 ? {} : { sample: sampleSize },
+    recorded: dynamic.snapshots ?? [],
+    refused: (dynamic.redirected ?? []).map((r) => ({ id: r.id, reason: r.reason }))
+  };
+}
 function mergeDynamic(audit2, dynamic, lang = "en") {
   const merged = JSON.parse(JSON.stringify(audit2));
   const seenFindings = new Set(merged.findings.map(portableFindingId));
@@ -74160,9 +74167,9 @@ Usage:
   ultra11y init     [--hook] [--ci] [--baseline] [--fail-on blocking|major|minor]
   ultra11y judge    --in <audit.json> [--standard <pack>] [--runner api|claude|codex] [--grain batch|criterion] [--max <n>] [--model <id>] [--effort <level>] [--max-budget-usd <n>] [--timeout <s>] [--out <dir>] [--apply]   (adjudicate manual criteria \u2014 api needs ANTHROPIC_API_KEY; claude/codex reuse their CLI login; cli aliases claude)
   ultra11y pack     check <pack.json> [--guidance <g.json>] [--json]  |  pack scaffold
-  ultra11y scan     <url|file\u2026> [--runtime auto|local|docker] [--cwd <dir>] [--storage-state <file>] [--no-interact] [--interact-clicks] [--no-snapshot] [--merge <audit.json>] [--out <dir>] [--json]
-  ultra11y scan     --sample [--runtime \u2026] [--cwd <dir>] [--storage-state <file>] [--merge <audit.json>] [--json]   (scan the .ultra11yrc.json page sample)
-  ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime \u2026] [--cwd <dir>] [--merge <audit.json>] [--json]
+  ultra11y scan     <url|file\u2026> [--runtime auto|local|docker] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--no-interact] [--interact-clicks] [--no-snapshot] [--merge <audit.json>] [--out <dir>] [--json]
+  ultra11y scan     --sample [--runtime \u2026] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--merge <audit.json>] [--json]   (scan the .ultra11yrc.json page sample)
+  ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime \u2026] [--cwd <dir>] [--root <dir>] [--merge <audit.json>] [--json]
   ultra11y scan     --clean        (remove the dynamic-tier Docker image + temp contexts)
   ultra11y sample   check [--standard <pack>] [--json]   (lint the .ultra11yrc.json page sample vs the standard's required page kinds)
   ultra11y snapshot write [--root <dir>] [--fail-on blocking|major|minor] [--json]   (payload on stdin \u2192 .ultra11y/pages/<id>/ + audit it)
@@ -74406,7 +74413,8 @@ Options:
   --no-captures      audit: do NOT auto-detect/ingest .ultra11y/captures nor .ultra11y/pages
   --e2e              render: write the Playwright/Cypress fixtures into .ultra11y/e2e/
   --runner <name>    render --e2e: force playwright|cypress instead of auto-detecting
-  --root <dir>       snapshot: project root holding .ultra11y/pages (default: .)
+  --root <dir>       snapshot, scan: project root holding .ultra11y/pages (default: . \u2014
+                     scan writes the snapshots it collects under it)
   --port <n>         dev: port for the side-car (default: 4111); mcp: HTTP transport port
   --transport <k>    mcp: stdio (default) or http
   --bind <addr>      mcp --transport http: address to bind (default 127.0.0.1)
@@ -74492,7 +74500,9 @@ Options:
                      (exit 2 with the producing command if its worklist is missing)
   --eco              orchestrate: emit only RUNBOOK.md + agents/*.md \u2014 the explicit
                      sequential low-token path (also what a no-subagent harness follows)
-  --merge <file>     scan: fold dynamic findings into this AuditResult JSON
+  --merge <file>     scan: fold dynamic findings into this AuditResult JSON. With --json the
+                     printed document opens with a 'pages' summary of the run \u2014
+                     {sample, recorded, refused:[{id, reason}]} \u2014 beside the document
   --sitemap <url>    scan: scan every URL listed in a sitemap.xml
   --crawl <url>      scan: BFS same-origin links from a start URL (served HTML)
   --depth <n>        scan: crawl link-hop depth from the start URL   (default: no limit; 0 = no limit)
@@ -77031,6 +77041,10 @@ Iterated over ${rounds} round(s) to a fixpoint \u2014 ${totalWritten} file(s) wr
   }
   return 0;
 }
+function scanSnapshotRoot(flags2) {
+  if (flags2["no-snapshot"] === true) return void 0;
+  return typeof flags2.root === "string" && flags2.root ? resolve17(flags2.root) : process.cwd();
+}
 async function cmdScan(p) {
   const standard = stdOf(p, "scan");
   if (standard === null) return 2;
@@ -77083,7 +77097,7 @@ async function cmdScan(p) {
   const interactClicks = p.flags["interact-clicks"] === true;
   const sitemap = typeof p.flags.sitemap === "string" ? p.flags.sitemap : void 0;
   const crawl = typeof p.flags.crawl === "string" ? p.flags.crawl : void 0;
-  const snapshotRoot = p.flags["no-snapshot"] === true ? void 0 : process.cwd();
+  const snapshotRoot = scanSnapshotRoot(p.flags);
   const useSample = p.flags.sample === true;
   let sampleConfig;
   if (useSample) {
@@ -77211,7 +77225,19 @@ async function cmdScan(p) {
     mkdirSync18(out2, { recursive: true });
     const mergedDocument = auditDocumentFor(merged, standard, lang);
     writeFileSync21(join52(out2, "audit-latest.json"), JSON.stringify(mergedDocument, null, 2) + "\n");
-    if (p.flags.json) console.log(JSON.stringify(mergedDocument, null, 2));
+    if (p.flags.json)
+      console.log(
+        JSON.stringify(
+          // `pages` opens the printed document: what this scan recorded (the
+          // .ultra11y/pages ids) and refused, which the stderr warnings alone don't make
+          // countable. An extra top-level key the `--in` readers never look at, so the
+          // document beside it stays pipeable into report/verify — and the file above
+          // keeps the plain audit schema.
+          { pages: scanPageSummary(dynamic, sampleConfig?.pages.length), ...mergedDocument },
+          null,
+          2
+        )
+      );
     else {
       console.log(
         lang === "fr" ? `Audit statique + dynamique fusionn\xE9 \u2192 ${join52(out2, "audit-latest.json")} (${merged.conformancePct}% r\xE9ussite, ${merged.findings.length} findings).` : `Static + dynamic audit merged \u2192 ${join52(out2, "audit-latest.json")} (${merged.conformancePct}% pass rate, ${merged.findings.length} findings).`
@@ -77768,6 +77794,7 @@ export {
   COMMANDS,
   REMOVED_FLAGS,
   main,
-  parseArgs
+  parseArgs,
+  scanSnapshotRoot
 };
 // "Copyright" and "@license" are already caught by DIRECTIVE_RE.

package/skills/ultra11y/SKILL.md

@@ -3,7 +3,7 @@ name: ultra11y
 description: "Use to AUDIT a repository, site, or page against WCAG 2.2 AA or a country standard such as RGAA; produce a dated conformance report, criterion grid, PRD backlog, or tickets; AUTHOR accessible markup; fix accessibility; or wire a repo gate and rendered-DOM capture pipeline. The bundled install-free engine runs 93 static checks tied to success criteria, while the agent adjudicates judgment criteria and routes rendering criteria to browser scans; check/verify reject invented non-conformities. Use `review-a11y` instead for a review scoped only to a diff, branch, or PR."
 license: MIT
 metadata:
-  version: 5.43.5
+  version: 5.45.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup

package/skills/ultra11y/references/dynamic.md

@@ -233,7 +233,8 @@ and the scan stops there. Point `--crawl` at a real entry page, or pass the URLs
 `scan` does not only keep findings: each page it visits is persisted to
 `.ultra11y/pages/<id>/` (DOM + computed styles + boxes + stylesheets + a viewport
 screenshot). The browser is already on the page, so this costs one `evaluate`. `--no-snapshot`
-opts out.
+opts out; `--root <dir>` relocates the tree (default: the working directory — `--cwd` is
+where Playwright resolves from, not where snapshots land).
 
 ### …and what it MEASURED, not only what it saw
 

package/skills/ultra11y/references/orchestrators.md

@@ -166,9 +166,10 @@ repo it does not own — write the run's intermediates out-of-tree and let only
 dated report land in the project, if at all.
 
 `.ultra11y/pages/` is written only by the page-snapshot commands (`scan`, `snapshot`,
-`dev`). `snapshot`, `dev` and `pages discover` take `--root` to relocate it; `scan` does not —
-it writes under the current working directory, so run it from the directory that should
-hold the snapshots. `audit`, `report`, `prd`, `tickets`, `verify` and `check` never touch it.
+`dev`). All of them take `--root` to relocate it — for `scan`, where the snapshots it
+collects are written (`--cwd` stays where Playwright resolves from), so an orchestrator can
+run from the audited checkout without dirtying it. `audit`, `report`, `prd`, `tickets`,
+`verify` and `check` never touch it.
 
 ## Exit codes
 
@@ -207,6 +208,12 @@ Read exit codes from the process, **not** from a pipeline — `cmd --json | head
   standard's own conformance rate (validated ÷ validated + NC + à évaluer, NA excluded) is
   printed by the report; derive it from `criteria[]` if a number is needed in a pipeline.
 - `check --json` → `{ ok, issues[] }`.
+- `scan --merge --json` → the merged audit document, opened by a top-level `pages` summary:
+  `{ sample, recorded[], refused: [{id, reason}] }` — the declared sample's size (`--sample`),
+  the snapshot ids written under `.ultra11y/pages/`, and the pages the scan refused with
+  their reason (the refusal warnings also go to stderr). Report the rendered layer from it —
+  captured vs refused — instead of re-deriving it from directory mtimes. The document written
+  to `--out` keeps the plain audit schema; the summary travels in stdout only.
 
 ## Honesty rules an orchestrator has to carry
 

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join52, relative as relative6, resolve as resolve17, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.43.5";
+var VERSION = "5.45.0";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 
@@ -66879,6 +66879,13 @@ function resolveHostAnchor(file, snippet2) {
   }
   return null;
 }
+function scanPageSummary(dynamic, sampleSize) {
+  return {
+    ...sampleSize === void 0 ? {} : { sample: sampleSize },
+    recorded: dynamic.snapshots ?? [],
+    refused: (dynamic.redirected ?? []).map((r) => ({ id: r.id, reason: r.reason }))
+  };
+}
 function mergeDynamic(audit2, dynamic, lang = "en") {
   const merged = JSON.parse(JSON.stringify(audit2));
   const seenFindings = new Set(merged.findings.map(portableFindingId));
@@ -74160,9 +74167,9 @@ Usage:
   ultra11y init     [--hook] [--ci] [--baseline] [--fail-on blocking|major|minor]
   ultra11y judge    --in <audit.json> [--standard <pack>] [--runner api|claude|codex] [--grain batch|criterion] [--max <n>] [--model <id>] [--effort <level>] [--max-budget-usd <n>] [--timeout <s>] [--out <dir>] [--apply]   (adjudicate manual criteria \u2014 api needs ANTHROPIC_API_KEY; claude/codex reuse their CLI login; cli aliases claude)
   ultra11y pack     check <pack.json> [--guidance <g.json>] [--json]  |  pack scaffold
-  ultra11y scan     <url|file\u2026> [--runtime auto|local|docker] [--cwd <dir>] [--storage-state <file>] [--no-interact] [--interact-clicks] [--no-snapshot] [--merge <audit.json>] [--out <dir>] [--json]
-  ultra11y scan     --sample [--runtime \u2026] [--cwd <dir>] [--storage-state <file>] [--merge <audit.json>] [--json]   (scan the .ultra11yrc.json page sample)
-  ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime \u2026] [--cwd <dir>] [--merge <audit.json>] [--json]
+  ultra11y scan     <url|file\u2026> [--runtime auto|local|docker] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--no-interact] [--interact-clicks] [--no-snapshot] [--merge <audit.json>] [--out <dir>] [--json]
+  ultra11y scan     --sample [--runtime \u2026] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--merge <audit.json>] [--json]   (scan the .ultra11yrc.json page sample)
+  ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime \u2026] [--cwd <dir>] [--root <dir>] [--merge <audit.json>] [--json]
   ultra11y scan     --clean        (remove the dynamic-tier Docker image + temp contexts)
   ultra11y sample   check [--standard <pack>] [--json]   (lint the .ultra11yrc.json page sample vs the standard's required page kinds)
   ultra11y snapshot write [--root <dir>] [--fail-on blocking|major|minor] [--json]   (payload on stdin \u2192 .ultra11y/pages/<id>/ + audit it)
@@ -74406,7 +74413,8 @@ Options:
   --no-captures      audit: do NOT auto-detect/ingest .ultra11y/captures nor .ultra11y/pages
   --e2e              render: write the Playwright/Cypress fixtures into .ultra11y/e2e/
   --runner <name>    render --e2e: force playwright|cypress instead of auto-detecting
-  --root <dir>       snapshot: project root holding .ultra11y/pages (default: .)
+  --root <dir>       snapshot, scan: project root holding .ultra11y/pages (default: . \u2014
+                     scan writes the snapshots it collects under it)
   --port <n>         dev: port for the side-car (default: 4111); mcp: HTTP transport port
   --transport <k>    mcp: stdio (default) or http
   --bind <addr>      mcp --transport http: address to bind (default 127.0.0.1)
@@ -74492,7 +74500,9 @@ Options:
                      (exit 2 with the producing command if its worklist is missing)
   --eco              orchestrate: emit only RUNBOOK.md + agents/*.md \u2014 the explicit
                      sequential low-token path (also what a no-subagent harness follows)
-  --merge <file>     scan: fold dynamic findings into this AuditResult JSON
+  --merge <file>     scan: fold dynamic findings into this AuditResult JSON. With --json the
+                     printed document opens with a 'pages' summary of the run \u2014
+                     {sample, recorded, refused:[{id, reason}]} \u2014 beside the document
   --sitemap <url>    scan: scan every URL listed in a sitemap.xml
   --crawl <url>      scan: BFS same-origin links from a start URL (served HTML)
   --depth <n>        scan: crawl link-hop depth from the start URL   (default: no limit; 0 = no limit)
@@ -77031,6 +77041,10 @@ Iterated over ${rounds} round(s) to a fixpoint \u2014 ${totalWritten} file(s) wr
   }
   return 0;
 }
+function scanSnapshotRoot(flags2) {
+  if (flags2["no-snapshot"] === true) return void 0;
+  return typeof flags2.root === "string" && flags2.root ? resolve17(flags2.root) : process.cwd();
+}
 async function cmdScan(p) {
   const standard = stdOf(p, "scan");
   if (standard === null) return 2;
@@ -77083,7 +77097,7 @@ async function cmdScan(p) {
   const interactClicks = p.flags["interact-clicks"] === true;
   const sitemap = typeof p.flags.sitemap === "string" ? p.flags.sitemap : void 0;
   const crawl = typeof p.flags.crawl === "string" ? p.flags.crawl : void 0;
-  const snapshotRoot = p.flags["no-snapshot"] === true ? void 0 : process.cwd();
+  const snapshotRoot = scanSnapshotRoot(p.flags);
   const useSample = p.flags.sample === true;
   let sampleConfig;
   if (useSample) {
@@ -77211,7 +77225,19 @@ async function cmdScan(p) {
     mkdirSync18(out2, { recursive: true });
     const mergedDocument = auditDocumentFor(merged, standard, lang);
     writeFileSync21(join52(out2, "audit-latest.json"), JSON.stringify(mergedDocument, null, 2) + "\n");
-    if (p.flags.json) console.log(JSON.stringify(mergedDocument, null, 2));
+    if (p.flags.json)
+      console.log(
+        JSON.stringify(
+          // `pages` opens the printed document: what this scan recorded (the
+          // .ultra11y/pages ids) and refused, which the stderr warnings alone don't make
+          // countable. An extra top-level key the `--in` readers never look at, so the
+          // document beside it stays pipeable into report/verify — and the file above
+          // keeps the plain audit schema.
+          { pages: scanPageSummary(dynamic, sampleConfig?.pages.length), ...mergedDocument },
+          null,
+          2
+        )
+      );
     else {
       console.log(
         lang === "fr" ? `Audit statique + dynamique fusionn\xE9 \u2192 ${join52(out2, "audit-latest.json")} (${merged.conformancePct}% r\xE9ussite, ${merged.findings.length} findings).` : `Static + dynamic audit merged \u2192 ${join52(out2, "audit-latest.json")} (${merged.conformancePct}% pass rate, ${merged.findings.length} findings).`
@@ -77768,6 +77794,7 @@ export {
   COMMANDS,
   REMOVED_FLAGS,
   main,
-  parseArgs
+  parseArgs,
+  scanSnapshotRoot
 };
 // "Copyright" and "@license" are already caught by DIRECTIVE_RE.

package/skills/ultra11y/templates/gitlab-ci.yml

@@ -27,7 +27,7 @@ variables:
   ULTRA11Y_LANG: en
   # Exact by default: a CI report must say which engine produced it. The release script keeps
   # this pin aligned with the package version; override only for a deliberate upgrade test.
-  ULTRA11Y_VERSION: '5.43.5'
+  ULTRA11Y_VERSION: '5.45.0'
   # Batches of 8 amortise the prompt; each accepted verdict is checkpointed before the next
   # batch, and later passes receive only the residue.
   ULTRA11Y_GRAIN: batch

package/src/cli.ts

@@ -82,7 +82,7 @@ import {
 import { DEFAULT_CLI_MODEL, EFFORT_LEVELS, judgeBatchCli, refuteBatchCli } from "./agent-cli.js";
 import { CODEX_EFFORT_LEVELS, judgeBatchCodex, refuteBatchCodex } from "./agent-codex.js";
 import { BATCH_SIZE, apiKeyFromEnv, applyRawVerdicts, batchWorklist, isProviderUnavailableError, judgeAll, modelFromEnv, type LlmOptions } from "./llm.js";
-import { runScan, runScanMany, runCrawlScan, runSampleScan, mergeDynamic, mergeSnapshotAudit, cleanDynamic, dockerAvailable } from "./scan.js";
+import { runScan, runScanMany, runCrawlScan, runSampleScan, mergeDynamic, mergeSnapshotAudit, cleanDynamic, dockerAvailable, scanPageSummary } from "./scan.js";
 import { runScanLocal, runScanManyLocal, runCrawlScanLocal, runSampleScanLocal, localAvailable, localTierStatus } from "./scan-local.js";
 import { validateSample, lintSample, kindLabel, proposeSamplePages, mergeSample, sampleFromSnapshots, unionSample } from "./sample.js";
 import { createAdapter } from "./external/registry.js";
@@ -160,9 +160,9 @@ Usage:
   ultra11y init     [--hook] [--ci] [--baseline] [--fail-on blocking|major|minor]
   ultra11y judge    --in <audit.json> [--standard <pack>] [--runner api|claude|codex] [--grain batch|criterion] [--max <n>] [--model <id>] [--effort <level>] [--max-budget-usd <n>] [--timeout <s>] [--out <dir>] [--apply]   (adjudicate manual criteria — api needs ANTHROPIC_API_KEY; claude/codex reuse their CLI login; cli aliases claude)
   ultra11y pack     check <pack.json> [--guidance <g.json>] [--json]  |  pack scaffold
-  ultra11y scan     <url|file…> [--runtime auto|local|docker] [--cwd <dir>] [--storage-state <file>] [--no-interact] [--interact-clicks] [--no-snapshot] [--merge <audit.json>] [--out <dir>] [--json]
-  ultra11y scan     --sample [--runtime …] [--cwd <dir>] [--storage-state <file>] [--merge <audit.json>] [--json]   (scan the .ultra11yrc.json page sample)
-  ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime …] [--cwd <dir>] [--merge <audit.json>] [--json]
+  ultra11y scan     <url|file…> [--runtime auto|local|docker] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--no-interact] [--interact-clicks] [--no-snapshot] [--merge <audit.json>] [--out <dir>] [--json]
+  ultra11y scan     --sample [--runtime …] [--cwd <dir>] [--root <dir>] [--storage-state <file>] [--merge <audit.json>] [--json]   (scan the .ultra11yrc.json page sample)
+  ultra11y scan     --sitemap <url> | --crawl <url> [--depth <n>] [--max <n>] [--runtime …] [--cwd <dir>] [--root <dir>] [--merge <audit.json>] [--json]
   ultra11y scan     --clean        (remove the dynamic-tier Docker image + temp contexts)
   ultra11y sample   check [--standard <pack>] [--json]   (lint the .ultra11yrc.json page sample vs the standard's required page kinds)
   ultra11y snapshot write [--root <dir>] [--fail-on blocking|major|minor] [--json]   (payload on stdin → .ultra11y/pages/<id>/ + audit it)
@@ -406,7 +406,8 @@ Options:
   --no-captures      audit: do NOT auto-detect/ingest .ultra11y/captures nor .ultra11y/pages
   --e2e              render: write the Playwright/Cypress fixtures into .ultra11y/e2e/
   --runner <name>    render --e2e: force playwright|cypress instead of auto-detecting
-  --root <dir>       snapshot: project root holding .ultra11y/pages (default: .)
+  --root <dir>       snapshot, scan: project root holding .ultra11y/pages (default: . —
+                     scan writes the snapshots it collects under it)
   --port <n>         dev: port for the side-car (default: 4111); mcp: HTTP transport port
   --transport <k>    mcp: stdio (default) or http
   --bind <addr>      mcp --transport http: address to bind (default 127.0.0.1)
@@ -492,7 +493,9 @@ Options:
                      (exit 2 with the producing command if its worklist is missing)
   --eco              orchestrate: emit only RUNBOOK.md + agents/*.md — the explicit
                      sequential low-token path (also what a no-subagent harness follows)
-  --merge <file>     scan: fold dynamic findings into this AuditResult JSON
+  --merge <file>     scan: fold dynamic findings into this AuditResult JSON. With --json the
+                     printed document opens with a 'pages' summary of the run —
+                     {sample, recorded, refused:[{id, reason}]} — beside the document
   --sitemap <url>    scan: scan every URL listed in a sitemap.xml
   --crawl <url>      scan: BFS same-origin links from a start URL (served HTML)
   --depth <n>        scan: crawl link-hop depth from the start URL   (default: no limit; 0 = no limit)
@@ -4028,6 +4031,16 @@ async function cmdFix(p: ParsedArgs): Promise<number> {
   return 0;
 }
 
+/** Where `scan` writes the page snapshots it collects: `--root <dir>` when given — the same
+ *  contract as `snapshot write`, `dev` and `pages discover --from-snapshots` — else the
+ *  working directory. Absolute either way, as it always was: the merge audits the snapshot
+ *  DOMs by this path. Undefined under `--no-snapshot`: nothing is persisted. `--cwd` plays
+ *  no part here: it keeps its own meaning, where Playwright resolves from. */
+export function scanSnapshotRoot(flags: ParsedArgs["flags"]): string | undefined {
+  if (flags["no-snapshot"] === true) return undefined;
+  return typeof flags.root === "string" && flags.root ? resolve(flags.root) : process.cwd();
+}
+
 async function cmdScan(p: ParsedArgs): Promise<number> {
   // `scan` takes `--standard` for the same reason `audit` now does: it REWRITES
   // audit-latest.json mid-chain, and a merge that silently re-keyed an RGAA document back to
@@ -4135,7 +4148,7 @@ async function cmdScan(p: ParsedArgs): Promise<number> {
   // is already on the page, so this costs one `evaluate` — and it is what lets the page be
   // re-audited offline and earn a real per-page verdict instead of staying "to assess"
   // forever (src/pages.ts). `--no-snapshot` opts out.
-  const snapshotRoot = p.flags["no-snapshot"] === true ? undefined : process.cwd();
+  const snapshotRoot = scanSnapshotRoot(p.flags);
 
   // --sample: iterate the NORMATIVE page sample from `.ultra11yrc.json` (per-page
   // storageState overrides --storage-state). Loaded + validated here (hard error on a
@@ -4336,7 +4349,19 @@ async function cmdScan(p: ParsedArgs): Promise<number> {
     mkdirSync(out, { recursive: true });
     const mergedDocument = auditDocumentFor(merged, standard, lang);
     writeFileSync(join(out, "audit-latest.json"), JSON.stringify(mergedDocument, null, 2) + "\n");
-    if (p.flags.json) console.log(JSON.stringify(mergedDocument, null, 2));
+    if (p.flags.json)
+      console.log(
+        JSON.stringify(
+          // `pages` opens the printed document: what this scan recorded (the
+          // .ultra11y/pages ids) and refused, which the stderr warnings alone don't make
+          // countable. An extra top-level key the `--in` readers never look at, so the
+          // document beside it stays pipeable into report/verify — and the file above
+          // keeps the plain audit schema.
+          { pages: scanPageSummary(dynamic, sampleConfig?.pages.length), ...mergedDocument },
+          null,
+          2,
+        ),
+      );
     else {
       console.log(
         lang === "fr"

package/src/scan.ts

@@ -10,7 +10,7 @@ import { mkdtempSync, writeFileSync, existsSync, statSync, readdirSync, rmSync,
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { AuditResult, DynamicEngine, DynamicFinding, DynamicResult, Finding, Lang, SamplePage, Severity } from "./types.js";
+import type { AuditResult, DynamicEngine, DynamicFinding, DynamicResult, Finding, Lang, SamplePage, ScanRedirect, Severity } from "./types.js";
 import { lineStartsOf, lineColAt } from "./parse/html.js";
 import { allGuidelines } from "./wcag.js";
 import { PROBE_SEVERITY, PROBE_WCAG, scForAxe, severityFromImpact, isAxeAdvisory } from "./axe-map.js";
@@ -716,6 +716,31 @@ function resolveHostAnchor(file: string, snippet: string): { line: number; col:
   return null;
 }
 
+/** The `pages` block `scan --merge --json` prints in front of the merged document. A
+ *  PRINT-side envelope only — `audit-latest.json` keeps the plain audit schema — under a
+ *  top-level key no `--in` reader of the document looks at. */
+export interface ScanPageSummary {
+  // The declared sample's page count, on a `--sample` run; absent otherwise (a plain
+  // URL/sitemap/crawl scan has no sample to be short of).
+  sample?: number;
+  // Ids of the snapshots the run persisted under `.ultra11y/pages/<id>/`.
+  recorded: string[];
+  // Pages the scan refused to record, and why (see ScanRedirect).
+  refused: Array<{ id: string; reason?: ScanRedirect["reason"] }>;
+}
+
+/** What one scan RECORDED and REFUSED, page by page. Without it the merged `--json` output
+ *  carries neither: the refusals reach the caller on stderr only, and the recorded ids would
+ *  take a listing of `.ultra11y/pages` against the run's start time to recover — exactly the
+ *  re-derivation an orchestrator reporting « N pages capturées, M refusées » must not do. */
+export function scanPageSummary(dynamic: DynamicResult, sampleSize?: number): ScanPageSummary {
+  return {
+    ...(sampleSize === undefined ? {} : { sample: sampleSize }),
+    recorded: dynamic.snapshots ?? [],
+    refused: (dynamic.redirected ?? []).map((r) => ({ id: r.id, reason: r.reason })),
+  };
+}
+
 /** Fold dynamic findings into a static AuditResult: a needs-rendering/manual or
  *  clean criterion that axe flags becomes NC; tallies + conformance recompute. */
 export function mergeDynamic(audit: AuditResult, dynamic: DynamicResult, lang: Lang = "en"): AuditResult {

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 = "5.43.5";
+export const VERSION = "5.45.0";
 export const SCHEMA_VERSION = 2;
 
 // Lang = the UI FRAME's language — the `L` localization tables each module (report,