ultra11y 2.24.0 → 2.26.0

package/skills/ultra11y/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: ultra11y
 description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibility and produce a dated auditor-conformance report, OR to AUTHOR/REVIEW accessible markup (native-HTML-first, ARIA last). An install-free engine (`node scripts/ultra11y.mjs`, no keys) runs 78 static checks tied to WCAG criteria — alt/lang/title, unlabeled fields, empty links/buttons, tables, headings, ARIA vocabulary, label-in-name, autocomplete — measured against the official W3C ACT corpus. The engine decides 3 of the 55 criteria; the AI agent adjudicates the 38 judgment ones from harvested evidence + a per-criterion decision protocol (`verify --manual`, gated, fannable via `orchestrate`), and the 14 rendering ones go to `scan` — never silently conforming. Library/SFC code is audited as RENDERED captures (`render --setup`); country standards are pluggable packs (`--standard rgaa`, `scan --sample`). check/verify reject invented non-conformities. Triggers: 'audit WCAG/a11y', 'make accessible', 'fix a11y', 'audit RGAA'."
+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 remediation backlog or GitHub issues; 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: 2.24.0
+  version: 2.26.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup
@@ -154,7 +155,9 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 - **"Automatic repo gate (hook / CI)"** → `init --hook` writes a git pre-commit gate over
   the **strict staged snapshot** (audits the exact index blobs, auto-applies safe fixes and
   re-stages them, blocks only on judgment issues); `init --baseline`/`--ci` is the opt-in
-  "block only NEW non-conformities" variant. For library/SFC code, commit rendered
+  "block only NEW non-conformities" variant. Installed as a **Claude Code plugin**, a third
+  gate runs the `review-a11y` *skill* (not just the engine) on a pending commit/push/PR —
+  that one is shipped by the plugin, not by `init`. For library/SFC code, commit rendered
   **captures** (`render --setup`) and stage them so the real semantic HTML is what's
   checked (`audit --require-captures`); read **`references/automation.md`**.
 - **"Show me the problems while I build the page"** → `dev --next` writes a one-line overlay

package/skills/ultra11y/references/automation.md

@@ -10,6 +10,43 @@ node scripts/ultra11y.mjs init --ci            # .github/workflows/a11y.yml (PR
 node scripts/ultra11y.mjs init --baseline …    # opt into the legacy regression gate (below)
 ```
 
+## Three gates, three different jobs
+
+| | what runs | when | who decides |
+|---|---|---|---|
+| `init --hook` | the engine, mechanically | every `git commit` | the engine's `--fail-on` |
+| `init --ci` | the engine, in CI | every pull request | the engine's `--fail-on` |
+| the **Claude Code plugin hook** | the `review-a11y` **skill** | a pending commit / push / PR, inside an agent session | the AI agent, adjudicating |
+
+The first two block on what a machine can decide. The third exists because most of WCAG is
+*judgment* — is this `alt` relevant, is this link's purpose clear — which no exit code
+settles. See below.
+
+## The Claude Code plugin hook — the agent review, unprompted
+
+Shipped by the plugin (`hooks/hooks.json` → `hooks/pre-tool-use.mjs` → `ultra11y hook
+--claude-code`), not by `init`. Claude Code has no git event, so it listens on `PreToolUse`
+for the Bash tool and recognises the commands that **publish** work — `git commit` (scoped
+to `--staged`), `git push` and `gh pr create` (scoped to `--since <default branch>`). When
+the change carries findings at or above the threshold it returns `permissionDecision:
+"deny"` with the findings attached, and the agent invokes `review-a11y` to adjudicate them.
+
+Two invariants make it liveable:
+
+- **It never fires twice for the same findings.** The finding set is fingerprinted per
+  session, so the retry after a review always goes through — a review that refutes
+  everything still lets the commit land.
+- **It never breaks a git flow.** Git's own `no-verify` bypass, a dry run, a cwd outside a
+  repository, an unresolvable base ref, an engine error or a timeout all resolve to silence,
+  never to an error the user has to work around.
+
+Threshold and off-switches: `ULTRA11Y_HOOK_FAIL_ON=blocking|major|minor|off` (env, wins),
+then `"hook": { "failOn": … }` in `.ultra11yrc.json`, else `blocking`. `SKIP_A11Y=1` (the
+same bypass as the pre-commit hook) and `ULTRA11Y_HOOK=off` disable it outright.
+
+A hook **cannot force** a skill invocation — it blocks and hands over the reason, the agent
+invokes. And a plugin's hooks are enabled by enabling the plugin, not by the install alone.
+
 ## Default: strict staged snapshot + safe auto-fix
 
 The default pre-commit hook operates on **exactly what is about to be committed** — the