ultra11y 5.39.2 → 5.40.0

package/.claude-plugin/marketplace.json

@@ -9,8 +9,8 @@
     {
       "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": "5.39.2",
+      "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.40.0",
       "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": "5.39.2",
+  "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.40.0",
   "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": "5.39.2",
+  "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.40.0",
   "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 = "5.39.2";
+const ULTRA11Y_PLUGIN_VERSION = "5.40.0";
 
 const here = dirname(fileURLToPath(import.meta.url));
 

package/README.md

@@ -523,6 +523,13 @@ node scripts/ultra11y.mjs check  --report audits/wcag-YYYY-MM-DD.md # integrity
 
 ### A report someone will actually open
 
+There are two deliberate publication profiles. In an interactive Claude Code audit, the skill
+produces the detailed deliverable: adjudicated Markdown, a printable single-file HTML report,
+per-page HTML/Markdown dossiers, screenshots and annotated evidence. In GitHub Actions,
+`pages-report: compact` with `report`, `html` and `evidence` disabled still gates every criterion
+on every page but uploads only the status Markdown, page JSON, source audit and verdict ledger.
+The CI profile is a gate and handoff; it is not a second remediation report.
+
 `--html` turns the audit into a page: `audits/index.html` as the entry point, plus — from
 `report` — a detachable single file that prints to PDF. Self-contained — no script, no
 external asset, nothing pointing outside the directory — and it passes this engine's own

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ultra11y",
-  "version": "5.39.2",
+  "version": "5.40.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 join53, relative as relative6, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.39.2";
+var VERSION = "5.40.0";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 

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.39.2
+  version: 5.40.0
 ---
 
 # review-a11y — accessibility review of changed code

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

@@ -6,7 +6,7 @@ import { join as join53, relative as relative6, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.39.2";
+var VERSION = "5.40.0";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 

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.39.2
+  version: 5.40.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup
@@ -119,6 +119,7 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 | Running the tool | |
 |---|---|
 | `references/runbook.md` | **The reliable run**: the one recipe, the transport to use and why, and what a pass costs. Read this before paying for an adjudication |
+| `references/claude-code-report.md` | Claude Code's detailed publication route: rendered scope, direct adjudication, adversarial verification, Markdown + HTML + per-page evidence |
 | `references/audit.md` | The audit loop end to end, and the normative page sample |
 | `references/judgment.md` | The adjudication + refutation worklists, verdict vocabulary, fail-closed fold |
 | `references/verify.md` | The `check`/`verify` gates |
@@ -144,6 +145,11 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 
 ## Choose by situation
 
+- **"Produce a detailed audit/report in Claude Code"** → use the active Claude session as the
+  auditor, close the rendered and judgment criteria, challenge its claims, then publish the
+  dated Markdown report, printable HTML and evidenced per-page dossiers. Read
+  **`references/claude-code-report.md`**. This is the interactive publication profile; finish
+  with its full deliverable set. The compact summary is the CI branch below.
 - **"Audit / compliance report"** → `node scripts/ultra11y.mjs audit … --json`, then
   `report` (synthesis table + one **auditor conformance block** per NC criterion — same
   block `prd` and `tickets` use), then `check`; read **`references/audit.md`**.

package/skills/ultra11y/references/ci.md

@@ -38,6 +38,30 @@ Page by page, with a real browser, in the same step:
       comment-kind: pages           # the page-by-page grid, under its own sticky marker
 ```
 
+For an exhaustive certification run whose output must stay small, use the compact profile:
+
+```yaml
+  - uses: maxgfr/ultra11y@v5
+    with:
+      standard: rgaa
+      crawl: http://localhost:3000
+      crawl-max: '0'
+      ledger: 'true'
+      require-rendered: 'true'
+      require-decided: pages
+      undecidable-file: .ultra11y/undecidable-rgaa.json
+      report: 'false'
+      html: 'false'
+      evidence: 'false'
+      pages-report: compact
+```
+
+This still gates every criterion on every captured page. Its visible summary lists the complete
+page-by-page grid, while its artifact contains only `pages-status.md`, `pages.json`,
+`audit-latest.json` and the portable verdict ledger. Use the detailed Claude Code route when a
+human-readable conformance dossier is the deliverable; CI's job here is exhaustive evidence,
+fast feedback and a clean handoff.
+
 A page sweep is usually a **second job** — it needs a built app, a database, a browser — and
 it can comment alongside the code gate above without either overwriting the other, because
 each kind has its own marker. Give the two jobs distinct `artifact-name`s too: artifact names

package/skills/ultra11y/references/claude-code-report.md

@@ -0,0 +1,102 @@
+# Detailed conformance reports in Claude Code
+
+Use this route when the user asks Claude Code for an audit or conformance report. The active
+Claude Code session is the auditor: it reads the criterion briefs and writes the verdicts
+itself. It does not launch a nested `judge --runner claude` session.
+
+The completion criterion is a **defensible deliverable**, not merely a clean static scan:
+
+- every declared page was captured, or the missing page is named;
+- every criterion on every captured page is `C`, `NC`, `NA`, or explicitly undecidable;
+- every `NC` has a resolvable occurrence and every `C`/`NA` has grounded justification;
+- the conformance report and per-page dossiers pass `check`;
+- the user receives the paths to the Markdown report, HTML entry point, printable single file,
+  page index and machine-readable grid.
+
+## 1. Establish the scope
+
+Read `.ultra11yrc.json` when present. Confirm the standard, language and page sample. For a
+country standard, prefer `sample check` plus `scan --sample`; otherwise crawl without a hidden
+cap (`--max 0`). A source-only country-standard report is partial and must say so.
+
+## 2. Audit source and rendered pages
+
+```sh
+node scripts/ultra11y.mjs audit <paths> --graph --standard <standard> --lang <lang> --out audits --json
+node scripts/ultra11y.mjs scan --sample --runtime local --cwd . \
+  --standard <standard> --merge audits/audit-latest.json --out audits
+```
+
+Use `--crawl <url> --max 0` instead of `--sample` when the project has no declared sample. A
+rendering criterion stays undecidable when no browser measurement exists; source inspection
+does not replace the scan.
+
+## 3. Adjudicate directly
+
+Generate the judgment worklist with `verify --manual`. Read each small
+`audits/adjudicate/<criterion>.md` brief, decide against its official tests, write the verdict
+file, then fold it with `verify --apply`. Use the orchestration route when the worklist is large,
+but keep the final fold in the parent session.
+
+```sh
+node scripts/ultra11y.mjs report --in audits/audit-latest.json \
+  --standard <standard> --lang <lang> --out audits
+node scripts/ultra11y.mjs verify --report audits/<standard>-<date>.md \
+  --in audits/audit-latest.json --manual --standard <standard> --out audits
+node scripts/ultra11y.mjs verify --apply audits/ADJUDICATE.verdicts.json \
+  --in audits/audit-latest.json --standard <standard> --out audits
+```
+
+The first report is a draft, not the final deliverable. Follow `references/judgment.md` for
+the verdict schema and fail-closed fold.
+
+## 4. Challenge the claims
+
+Render the report, generate the adversarial `VERIFY.todo.json`, adjudicate every claim, apply
+the verdicts with `--prune --ledger`, then render again. This trial covers both alleged
+non-conformities and agent-declared conformities.
+
+```sh
+node scripts/ultra11y.mjs report --in audits/audit-latest.json \
+  --standard <standard> --lang <lang> --out audits
+node scripts/ultra11y.mjs verify --report audits/<standard>-<date>.md \
+  --in audits/audit-latest.json --standard <standard> --semantic --out audits
+node scripts/ultra11y.mjs verify --apply audits/VERIFY.todo.json \
+  --report audits/<standard>-<date>.md --in audits/audit-latest.json \
+  --standard <standard> --out audits --prune --ledger
+```
+
+## 5. Publish the detailed deliverable
+
+```sh
+node scripts/ultra11y.mjs report --in audits/audit-latest.json \
+  --standard <standard> --lang <lang> --html --evidence --out audits
+node scripts/ultra11y.mjs pages --in audits/audit-latest.json \
+  --standard <standard> --lang <lang> --json --out audits
+node scripts/ultra11y.mjs pages --in audits/audit-latest.json \
+  --standard <standard> --lang <lang> --format report --split page \
+  --html --evidence --out audits/pages
+```
+
+This produces the dated Markdown conformance report, `audits/index.html`, the printable
+single-file HTML report, `audits/pages.json`, and the navigable per-page Markdown/HTML dossiers
+with screenshots and annotated evidence when snapshots support them. It is a conformance
+deliverable; generate a PRD, remediation backlog or tickets only when the user asks for fixes.
+
+## 6. Gate and hand over
+
+```sh
+node scripts/ultra11y.mjs check --report audits/<standard>-<date>.md \
+  --in audits/audit-latest.json --standard <standard>
+node scripts/ultra11y.mjs check --in audits/audit-latest.json \
+  --standard <standard> --require-rendered
+node scripts/ultra11y.mjs check --in audits/audit-latest.json \
+  --standard <standard> --require-decided=pages
+node scripts/ultra11y.mjs check --report audits/pages/index.md \
+  --standard <standard>
+```
+
+Append `--allow-undecided .ultra11y/undecidable-<standard>.json` to the completeness gate only
+when the project records named exceptions with reasons. Report the scope, page count, criterion
+count, provenance tally, remaining named exceptions and every deliverable path. A failed gate
+is part of the result and must not be summarized as a complete report.

package/skills/ultra11y/references/harnesses.md

@@ -25,6 +25,11 @@ Two things are worth knowing before the table:
 The plugin carries both skills *and* the hook. `hooks/hooks.json` → `hooks/pre-tool-use.mjs`
 → `ultra11y hook --claude-code`. The engine resolves from `${CLAUDE_SKILL_DIR}/scripts/ultra11y.mjs`.
 
+For a requested full audit, Claude Code follows `references/claude-code-report.md`: it acts as
+the auditor directly, then publishes the evidenced Markdown, HTML and per-page dossiers. The
+headless `judge --runner claude` transport is for CI or another unattended caller; nesting it
+inside the active Claude Code session wastes context and gives the report a weaker reader.
+
 The review arrives as `permissionDecision: "deny"` on the pending command, with the findings
 in `additionalContext`.
 

package/skills/ultra11y/scripts/ultra11y.mjs

@@ -6,7 +6,7 @@ import { join as join53, relative as relative6, resolve as resolve16, sep as sep
 import { fileURLToPath as fileURLToPath5, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/types.ts
-var VERSION = "5.39.2";
+var VERSION = "5.40.0";
 var SCHEMA_VERSION = 2;
 var INAPPLICABLE_STATUS = "C";
 

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