ultra11y 2.22.0

package/scripts/verify-skill-bundle.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+// Install-bundle gate: prove the repo is shaped so that `npx skills add
+// maxgfr/<name>` installs WORKING skills — engine + references included, not
+// just a lone SKILL.md.
+//
+// The `skills` CLI (skills.sh) early-returns the moment it sees a SKILL.md at
+// the repository ROOT and then installs that file ALONE — the sibling
+// scripts/ and references/ are dropped. A skill is only bundled whole when its
+// SKILL.md lives in a SUBDIRECTORY (skills/<name>/). This script asserts that
+// shape for EVERY skill under skills/ and that each embedded engine is
+// byte-identical to the tested bundle.
+//
+// Run by CI and by `pnpm run verify:bundle`. Pure Node, no deps, no network.
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Claude Code matches skill descriptions at <=1024 chars; 1000 leaves a safety
+// margin so a future edit can't silently cross the cap.
+const DESC_MAX = 1000;
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const engine = `scripts/${pkg.name}.mjs`;
+const errors = [];
+const ok = (m) => console.log(`  ok   ${m}`);
+const bad = (m) => {
+  errors.push(m);
+  console.log(`  FAIL ${m}`);
+};
+
+// 1. No SKILL.md at the repo root (would make `skills add` install it alone).
+existsSync(join(root, "SKILL.md"))
+  ? bad("a SKILL.md exists at the repo ROOT — `skills add` would install it alone, dropping the engine. Move it under skills/<name>/SKILL.md")
+  : ok("no root SKILL.md");
+
+const rootEngine = join(root, engine);
+if (!existsSync(rootEngine)) bad(`missing ${engine} at repo root — run \`pnpm run build\``);
+
+const skillNames = readdirSync(join(root, "skills")).filter((d) => statSync(join(root, "skills", d)).isDirectory());
+if (skillNames.length === 0) bad("skills/ contains no skill directory");
+
+for (const name of skillNames) {
+  const skillDir = join(root, "skills", name);
+  console.log(`skill ${name}:`);
+
+  // 2. The packaged SKILL.md exists with valid, installable frontmatter.
+  const skillMd = join(skillDir, "SKILL.md");
+  if (!existsSync(skillMd)) {
+    bad(`missing skills/${name}/SKILL.md — the skill package has no SKILL.md`);
+    continue;
+  }
+  const raw = readFileSync(skillMd, "utf8");
+  const fm = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!fm) bad(`skills/${name}/SKILL.md has no frontmatter block`);
+  else {
+    ok("packaged SKILL.md present with frontmatter");
+    const nameLine = fm[1].match(/^name:\s*(.+)$/m)?.[1]?.trim();
+    nameLine === name ? ok(`frontmatter name "${name}" matches its directory`) : bad(`frontmatter name "${nameLine}" != skill directory "${name}"`);
+    const desc = fm[1].match(/^description:\s*(.+)$/m)?.[1]?.trim();
+    if (!desc) bad(`skills/${name}: frontmatter has no description`);
+    else {
+      const len = desc.replace(/^["']|["']$/g, "").length;
+      len <= DESC_MAX ? ok(`description ${len} chars (<= ${DESC_MAX} safety cap)`) : bad(`skills/${name}: description ${len} chars exceeds the ${DESC_MAX}-char safety cap (matcher limit is 1024)`);
+    }
+  }
+
+  // 3. Every references/*.md mentioned exists, and every file is mentioned.
+  const refsDir = join(skillDir, "references");
+  if (existsSync(refsDir)) {
+    const mentioned = new Set(raw.match(/references\/[a-z0-9-]+\.md/g) ?? []);
+    for (const ref of mentioned) existsSync(join(skillDir, ref)) ? ok(`mentioned ${ref} exists`) : bad(`skills/${name}: ${ref} is mentioned in SKILL.md but missing from the package`);
+    for (const f of readdirSync(refsDir).filter((f) => f.endsWith(".md"))) raw.includes(`references/${f}`) ? null : bad(`skills/${name}: references/${f} exists but SKILL.md never mentions it`);
+    ok(`references/ present (${readdirSync(refsDir).filter((f) => f.endsWith(".md")).length} playbooks)`);
+  }
+
+  // 4. The embedded engine is byte-identical to the committed root bundle.
+  const pkgEngine = join(skillDir, engine);
+  if (!existsSync(rootEngine)) continue; // already reported above
+  if (!existsSync(pkgEngine)) bad(`missing skills/${name}/${engine} — run \`node scripts/copy-bundle.mjs\``);
+  else
+    readFileSync(rootEngine).equals(readFileSync(pkgEngine))
+      ? ok(`embedded engine skills/${name}/${engine} is byte-identical to ${engine}`)
+      : bad(`skills/${name}/${engine} differs from ${engine} — run \`node scripts/copy-bundle.mjs\` and commit`);
+}
+
+if (errors.length) {
+  console.error(`\nverify-skill-bundle: ${errors.length} problem(s) — a published skill would not install correctly.`);
+  process.exit(1);
+}
+console.log(`\nverify-skill-bundle: ok — ${skillNames.map((n) => `skills/${n}/`).join(", ")} install as complete skills.`);

package/skills/review-a11y/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: review-a11y
+description: "Use to REVIEW code changes for accessibility — '/review-a11y', 'review my changes/PR/branch for a11y', 'accessibility review of this diff'. Scopes to exactly the code under change (staged files, working diff, or branch vs merge-base), runs the bundled install-free ultra11y engine (node scripts/ultra11y.mjs, no keys; static WCAG 2.2 AA checks tied to success criteria, cross-file JSX/TSX via --graph), then adds YOUR judgment: refute false positives (SFC/library-source findings are preliminary), decide alt relevance and link purpose, name the rendering criteria (contrast, focus, zoom) as residual risks — never invent a non-conformity. Output: a severity-ranked review (blocking → major → minor) with file:line, concrete fixes, residual risks and a one-line verdict, in the conversation's language (technical tokens stay in English). Companion of the ultra11y skill (full audits, reports, PRD, RGAA packs). Triggers: 'review a11y', 'a11y review', 'accessibility review'."
+license: MIT
+metadata:
+  version: 2.22.0
+---
+
+# review-a11y — accessibility review of changed code
+
+The review counterpart of the `ultra11y` skill: where `ultra11y` produces full audits and
+compliance deliverables, **this skill reviews exactly the code under change** — a diff, a
+branch, a PR — and reports like a code reviewer. Same division of labour: the
+deterministic, install-free engine bundled with this skill does the *mechanical* work
+(machine-checkable WCAG 2.2 AA non-conformities, each tied to a success criterion, cited
+`file:line`), and **the AI agent** *adjudicates the judgment* — refute false positives, decide
+alt relevance/link purpose/focus logic statically from the code, and route what needs a rendered
+DOM to `scan`. A human is at most optional oversight.
+
+**Engine resolution:** every command below is `node scripts/ultra11y.mjs …` where
+`scripts/ultra11y.mjs` lives **next to this SKILL.md** (the engine ships inside the skill;
+no install, no key). Run it with the reviewed project as the working directory. In the
+ultra11y repository itself, the repo root's `scripts/ultra11y.mjs` is the same file.
+
+> **Core rules** (shared with `ultra11y`):
+> 1. **Never invent a non-conformity**: report only what the engine found or what you can
+>    see and cite in the code under review.
+> 2. **Review the change, not the world**: findings outside the reviewed scope are noted in
+>    one line at most ("pre-existing, out of scope"), never mixed into the verdict.
+> 3. **Residual is explicit, never silently conforming**: the *rendering* criteria (contrast,
+>    focus visibility, zoom/reflow, content-on-hover) are named as residual risks for the changed
+>    components — never asserted from source, resolved in the rendered page (`scan`). The
+>    *judgment* criteria (alt relevance, link purpose, reading order) the AI agent adjudicates
+>    from the code itself, recording a reason — no status without a justified verdict.
+> 4. **Language**: write the review in the conversation's language, but technical tokens
+>    stay in English even in French prose — `aria-live` stays `aria-live` (never
+>    « région live »), same for `tabindex`, `alt`, `role="alert"`, landmark role names.
+
+## 1. Scope — review what changed
+
+Pick the FIRST that applies (ask only when genuinely ambiguous):
+
+```
+node scripts/ultra11y.mjs audit <files the user named> --jsx --json     # explicit files
+node scripts/ultra11y.mjs audit --staged --graph --json                 # staged snapshot (pre-commit review)
+node scripts/ultra11y.mjs audit --changed --graph --json                # working diff
+node scripts/ultra11y.mjs audit --since origin/main --graph --json     # the whole branch (PR review) — use the repo's default branch
+```
+
+- Always pass `--graph` for JSX/TSX (real AST + cross-file rules: icon-only component used
+  without a name, anchor target defined in another file…); it also suppresses a class of
+  single-file false positives.
+- Pass `--lang` matching the conversation so the engine's message/remediation strings are
+  in the review's language (unset, the CLI auto-detects — a fallback, not a substitute).
+- Whole-repo review is an **audit**, not a review — offer the `ultra11y` skill instead.
+- Test/story markup (`*.test.*`, `*.stories.*`, `__tests__/`) is excluded by default; name
+  such a file explicitly to include it, or pass `--no-default-excludes`.
+
+## 2. Judge — the engine's findings are candidates, not verdicts
+
+For each finding (`--json` gives `criteria`, `severity`, `file:line`, `message`,
+`remediation`):
+
+- **Confirm the occurrence**: open the cited line; the offending element must really be
+  there in the change under review.
+- **`preliminary: true` findings** (`.vue`/`.svelte`/`.astro` source, library components):
+  the template parser cannot see slots, conditionals or provide/inject wiring. Confirm
+  against the rendered DOM if captures exist (`.ultra11y/captures`, from the `ultra11y`
+  skill's `render --setup` harvester), otherwise report them as **provisional** with that
+  caveat — or refute them with evidence from the code.
+- **Library-rendered JSX (DSFR, MUI…)**: a clean source review can still ship broken HTML
+  (false negatives) — say so explicitly when the change touches such components, and
+  recommend a rendered-DOM check (`scan`, or the `ultra11y` capture pipeline).
+- **The judgment criteria are the AI agent's to adjudicate**: alt text relevance, link purpose
+  in context, visible label vs accessible name, keyboard/focus logic of the changed component
+  (read the full component source, not just the flagged line), recording a reason for each call.
+- Refuting a finding requires **cited evidence** (the code that disproves it); silently
+  dropping findings is forbidden.
+
+## 3. Report — a review, not a compliance document
+
+Render in the conversation's language (Core rule 4), grouped by severity:
+
+```
+## Accessibility review — <scope, e.g. branch feat/x vs main, 12 files>
+
+### 🔴 Blocking
+- `src/components/Form.tsx:42` — **3.3.2 Labels or Instructions** — input has no
+  label and placeholder is its only hint → associate a real <label for>, keep the
+  placeholder as an example only.
+
+### 🟠 Major / 🟡 Minor
+- …same shape…
+
+### Residual risks (rendering-dependent — resolve in the rendered page via scan)
+- contrast of the new button variants (1.4.3), focus visibility on the custom menu (2.4.7)
+
+### Verdict
+1 blocking, 2 major to fix before merge; 2 provisional SFC findings to confirm on the
+rendered DOM; residual risks listed above.
+```
+
+- Keep the engine's `remediation` text as the base of each fix — it is already localized
+  and criterion-grounded.
+- Pre-existing issues spotted in passing go in ONE final line, out of the verdict.
+
+## 4. After the review (opt-in)
+
+- **Safe mechanical fixes**: `fix --staged --write --safe` (auto-applies the safe codemods
+  to staged files and re-stages them) or `node scripts/ultra11y.mjs fix <files> --write`;
+  dry-run without `--write`.
+- **Formal deliverables** (dated report, auditor conformance blocks, PRD backlog, GitHub
+  issues, RGAA/country-standard vocabulary): that is the `ultra11y` skill — same engine,
+  same findings (`report`, `prd`, `check`/`verify` gates).
+- **Make it automatic**: the `ultra11y` skill's `init --hook` installs a pre-commit gate
+  running this same staged review mechanically.
+
+## Do not
+
+- Invent a non-conformity the engine did not find and you cannot cite.
+- Assert contrast/focus/zoom from source — they are residual risks until rendered (resolve via `scan`).
+- Mix pre-existing repo issues into the verdict on the change.
+- Translate technical tokens in French prose (`aria-live`, never « région live »).