ultra11y 2.26.0 → 2.28.0

package/skills/ultra11y/SKILL.md

@@ -4,7 +4,7 @@ description: "Use to AUDIT existing HTML/CSS/JSX against WCAG 2.2 AA accessibili
 when_to_use: "Invoke when the user asks for an accessibility AUDIT or a formal deliverable: audit a repo, site or page against WCAG 2.2 AA or a country standard (RGAA, Section 508, EN 301 549); produce a dated conformance report, a criterion grid, a PRD 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.26.0
+  version: 2.28.0
 ---
 
 # ultra11y — audit WCAG 2.2 AA and write accessible markup
@@ -84,6 +84,7 @@ Domain knowledge first, then the tooling. Read the one that matches the question
 | `references/verify.md` | The `check`/`verify` gates |
 | `references/false-positives.md` | Where a finding may still be wrong, and how to refute it |
 | `references/rendered.md` · `references/automation.md` | Auditing produced HTML, captures, hooks and CI |
+| `references/harnesses.md` | Where this runs: Claude Code, Codex CLI, OpenCode, and the AGENTS.md fallback |
 | `references/ci.md` | `--format sarif\|github`: inline PR annotations, code scanning, job summary |
 | `references/pages.md` | Page snapshots + the per-page criterion grid (`pages`), and its honesty rules |
 | `references/e2e.md` | `render --e2e`: auditing a page during your Playwright/Cypress run |

package/skills/ultra11y/references/automation.md

@@ -16,21 +16,26 @@ node scripts/ultra11y.mjs init --baseline …    # opt into the legacy regressio
 |---|---|---|---|
 | `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 **agent-harness 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
+## The agent-harness 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
+--claude-code`), not by `init`. **No** harness has a git event, so it listens on `PreToolUse`
+for the shell 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.
 
+The same file serves Claude Code and Codex (Codex exports `${CLAUDE_PLUGIN_ROOT}` and reads
+the same envelope); OpenCode has no decision channel, so there the gate throws and the
+findings arrive as the tool error. Per-harness install, deltas and off-switches:
+**`references/harnesses.md`**.
+
 Two invariants make it liveable:
 
 - **It never fires twice for the same findings.** The finding set is fingerprinted per

package/skills/ultra11y/references/harnesses.md

@@ -0,0 +1,117 @@
+# Where this runs — Claude Code, Codex CLI, OpenCode, and everything else
+
+The skills speak in **actions** — run the engine, invoke the review skill, adjudicate the
+findings. On each harness those resolve as below. Only the **deltas** are listed; anything
+not mentioned here is identical everywhere, because the engine is one zero-dependency
+bundle and the CLI it exposes is the same on all of them.
+
+Two things are worth knowing before the table:
+
+- **No harness has a git event.** None of them can hook "about to commit". So the automatic
+  review rides the *shell tool* on every one of them, recognising the commands that publish
+  work — `git commit`, `git push`, `gh pr create`. That is a deliberate design constraint,
+  not a Claude Code quirk.
+- **A hook cannot force a skill to be invoked.** It blocks the command and hands over the
+  reason and the findings; the agent is what invokes `review-a11y`. In practice a motivated
+  block is enough — it is not a guarantee, on any harness.
+
+## Claude Code
+
+```
+/plugin marketplace add maxgfr/ultra11y
+/plugin install ultra11y@ultra11y
+```
+
+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`.
+
+The review arrives as `permissionDecision: "deny"` on the pending command, with the findings
+in `additionalContext`.
+
+Skills only, no hook: `npx skills add maxgfr/ultra11y`. Gate only, for an npm install:
+`ultra11y install --claude-code`.
+
+## OpenAI Codex CLI
+
+```
+codex plugin marketplace add maxgfr/ultra11y
+codex plugin add ultra11y@ultra11y
+```
+
+Codex's hook engine is a near-clone of Claude Code's — same events, same payload fields,
+same `hookSpecificOutput` envelope — and it exports `${CLAUDE_PLUGIN_ROOT}` alongside its own
+`${PLUGIN_ROOT}`, so **`hooks/hooks.json` is shared verbatim** between the two.
+
+The deltas that actually matter:
+
+- Its shell tool is **`shell`**, not `Bash`, and its `command` is an **argv array**
+  (`["bash","-lc","git commit -m x"]`). `commandOf` in `src/hook.ts` extracts the script
+  argument rather than joining the array — joining would put `git` off a command position
+  and the gate would silently never fire.
+- On `PreToolUse` Codex accepts **only** `permissionDecision: "deny"`, with a non-empty
+  reason. That is exactly and only what this engine emits, so the envelope needs no branch.
+- `.codex-plugin/plugin.json` must not declare `hooks` — Codex's manifest validator rejects
+  any key outside its allowlist. `hooks/hooks.json` is found by convention at the plugin root.
+- Hooks are behind a feature flag: **`[features] hooks = true`** in `~/.codex/config.toml`.
+- Codex asks you to **trust** a hook command the first time it fires. Accept it, or review
+  it with `/hooks`.
+
+Gate only, without the marketplace: `ultra11y install --codex` (it sets the feature flag and
+copies both skills into `~/.codex/skills/`).
+
+## OpenCode
+
+```
+ultra11y install --opencode
+```
+
+…or pin it in `~/.config/opencode/opencode.json`: `"plugin": ["ultra11y@latest"]`.
+
+The delta: OpenCode has **no permission-decision channel**. Its plugin blocks a tool call by
+throwing, so the review arrives as a **failed bash call whose error message carries the
+findings**. Same content, different envelope — read the error, do not retry blindly.
+
+Skills live under `~/.config/opencode/skills/`; the plugin also registers the bundled
+`skills/` directory via `config.skills.paths`.
+
+## Everything else (Cursor, Amp, Zed, Gemini CLI, Windsurf, aider…)
+
+```
+ultra11y install --agents-md
+```
+
+Writes a managed block into the repository's `AGENTS.md`. Be clear-eyed about what that is:
+there is no hook API, so **nothing is automatic**. The block makes the engine discoverable
+and hands over the adjudication protocol. What actually enforces anything on these harnesses
+is the repo's own gate — `ultra11y init --hook` (git pre-commit) and `ultra11y init --ci`.
+
+There is also **MCP**, which carries the method where nothing else does — `SKILL.md` and
+every `references/*.md` are exposed as `skill://` resources, plus three prompts
+(`audit_wcag`, `adjudicate_criteria`, `review_diff_a11y`):
+
+```
+claude mcp add ultra11y -- npx -y ultra11y mcp
+```
+
+On a harness with no skill system at all, **reading `SKILL.md` directly with the file-read
+tool is the blessed path**, not a workaround. Discover what exists by listing
+`skills/*/SKILL.md` and reading the frontmatter.
+
+## The matrix
+
+| | skills | automatic review | how it blocks | MCP | repo gate |
+|---|---|---|---|---|---|
+| Claude Code | plugin / `skills add` | yes | `permissionDecision: "deny"` | yes | yes |
+| Codex CLI | plugin / `skills add` | yes | `permissionDecision: "deny"` | yes | yes |
+| OpenCode | plugin / `skills add` | yes | thrown tool error | yes | yes |
+| Cursor, Amp, Zed, Gemini… | AGENTS.md | **no** | — | yes | yes |
+
+`ultra11y status` reports which of these are actually wired on this machine — including the
+one silent failure worth naming, a Codex hook sitting behind a disabled feature flag.
+
+## Off-switches (identical everywhere)
+
+They live in the engine, not in any harness, so one answer covers all of them:
+`ULTRA11Y_HOOK_FAIL_ON=blocking|major|minor|off` (env, wins), then
+`"hook": { "failOn": … }` in `.ultra11yrc.json`, else `blocking`. `SKIP_A11Y=1` bypasses
+once; `ULTRA11Y_HOOK=off` disables the gate for the session.