@softspark/ai-toolkit 4.20.0 → 4.22.0

package/CHANGELOG.md

@@ -7,6 +7,113 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.22.0 — the public surface is a test, not a promise (2026-08-06)
+
+### Added
+
+- **`scripts/surface_manifest.py` + `app/surface.json`** — 275 entries of public
+  surface (skills, agents, frontmatter fields, CLI commands, hook scripts and
+  events, KB categories, plugin packs) snapshotted and checked in `npm test`.
+  Removing any of them fails the build; adding is free, because a surface nobody
+  has installed has no users to break. The manifest is deliberately not
+  auto-regenerated — if it were, deleting a skill would delete its entry in the
+  same breath and the check would prove nothing.
+- **`BACKWARD_COMPATIBILITY.md`** — which surfaces are load-bearing, what may
+  change freely, and the deprecation path when a break is unavoidable.
+- **`DECISIONS.md`** — why things are the way they are, including what was
+  rejected and what may yet turn out to be ceremony.
+- **`scripts/check_split.py`** — five gates proving a `SKILL.md` → `reference/`
+  refactor lost nothing: fenced code lines survive, removed prose is traceable,
+  always-loaded sections stay in the body, `description` is byte-identical, and
+  every relative link still resolves. It caught a heading corrupted inside a
+  fenced example on its first real use.
+- **`scripts/sync_badges.py`** — README count badges derived from the tree and
+  rewritten inside `generate:all`, before `validate.py --strict` reads them.
+  Hand-maintained badges broke the build three times in one session.
+- **`/brainstorm`** — the first planning skill allowed to end in "do not build
+  this". Prices the zero option as a real candidate and sends the conclusion to a
+  separate challenger agent before routing anywhere.
+- **Skill body budget in `validate.py`** — error above 20,000 bytes, warn above
+  18,000, with the current headroom printed on every run and a ratchet step in
+  the release SOP.
+- **Hook events `MessageDisplay` and `DirectoryAdded`** added to
+  `VALID_HOOK_EVENTS`. Both are documented Claude Code events; without them
+  `validate.py` rejected a user's hook on either as an invalid name.
+
+### Changed
+
+- **`a11y-validate` and `seo-validate` now run the scanners they ship.**
+  `a11y-scanner.py` (643 lines) and `seo-scanner.py` (553 lines) were on disk and
+  invoked by nothing — the model was told to grep the pattern tables by hand.
+  Both skills now run their script for a deterministic baseline, then take an
+  explicit manual pass, with a measured coverage table in the body saying which
+  part is which. `a11y-scanner.py` covers 13 of ~50 documented WCAG success
+  criteria; `seo-scanner.py` covers 8 of 10 categories and none of category 7
+  (Rendering & Crawlability) or 10 (Topical Authority).
+- **Review severity is one four-tier scale.** `/review` asked for
+  `Critical/Major/Minor/Nit` while the `code-reviewer` agent it delegates to
+  reported `CRITICAL/HIGH/MEDIUM/LOW/INFO`. The agent won at runtime, so the
+  skill never received the format it specified. Both now use
+  `blocker/major/minor/nit` with a mechanical verdict rule, and severity (impact)
+  is explicitly separated from confidence (certainty).
+- **`/review`, `/ci` and `/debug` collect every failing signal before judging**
+  instead of stopping at the first red one.
+- **Three validator skills split into `reference/`**: `hipaa-validate`
+  23,905 → 10,433 B, `a11y-validate` 25,306 → 13,269 B, `seo-validate`
+  35,066 → 13,430 B. 47 KB off the hot path.
+- **`a11y-validate` and `seo-validate` gained `## Gotchas` and
+  `## When NOT to Use`**, written from the traps the scanner wiring introduced.
+
+### Fixed
+
+- **Four skills invoked their scripts through a path that never resolved.**
+  `debug`, `fix`, `pr` and `hipaa-validate` used `$(dirname "$0")`, which expands
+  to the shell's directory, not the skill's. All four now use
+  `${CLAUDE_SKILL_DIR}`, matching the other 14.
+
+---
+
+## v4.21.0 — one KB taxonomy, in one place (2026-07-28)
+
+### Fixed
+
+- **The `documentation-standards` skill contradicted itself.** Its frontmatter
+  said "5-category taxonomy", its table listed those five, and three paragraphs
+  below a "Valid categories" line named six — adding `planning`. An author
+  reading the table and a validator reading the code disagreed about what was
+  legal, and only the validator got a vote.
+- **`decisions` and `runbooks` were not valid categories**, while the
+  `kb-migration` SOP had been instructing people to create exactly those
+  directories for months. A correctly-filed ADR failed `scripts/validate.py`.
+  Both are now in the taxonomy, which is eight: `reference`, `howto`,
+  `procedures`, `troubleshooting`, `best-practices`, `decisions`, `runbooks`,
+  `planning`.
+- **`procedures` and `runbooks` no longer describe each other.** The table gave
+  "SOPs, runbooks, operational processes" for `procedures`, which left no way to
+  choose between them. `procedures` is a process a person follows; `runbooks`
+  are run against a live system, usually under pressure.
+
+### Added
+
+- **`section:` is documented as what it is: a legacy alias for `category:`.**
+  Older documents and the `kb-migration` SOP write `section:`; both names are
+  read in the wild. A document may carry both, and `validate.py` now rejects it
+  when they disagree — a document filed as `category: reference` and
+  `section: howto` is indexed twice and found once.
+- **`validate.py` checks that a document's category names its directory.** The
+  rule is scoped to directories that *are* category names, deliberately:
+  `kb/history/completed/` is a lifecycle location rather than a type, and a
+  finished plan filed there is still a `planning` document. Fifteen of this
+  project's own documents are in exactly that position.
+
+### Changed
+
+- `VALID_KB_CATEGORIES` in `scripts/validate.py` and the taxonomy table in
+  `app/skills/documentation-standards/SKILL.md` are one list in two places, and
+  each now says so. They were previously two lists that had drifted.
+
+---
+
 ## v4.20.0 — Apache-2.0, nine plugin packs removed (2026-07-27)
 
 ### Changed — licence: MIT to Apache-2.0

package/README.md

@@ -1,31 +1,41 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 108 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude Code, Claude Chat/Cowork, Cursor, Devin, Copilot, Gemini, Cline, Roo/Zoo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode.
+> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 109 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude Code, Claude Chat/Cowork, Cursor, Devin, Copilot, Gemini, Cline, Roo/Zoo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-108-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1473%20passing-success)](tests/)
-
-## What's New in v4.20.0
-
-v4.20.0 relicenses the project to Apache-2.0 and removes nine plugin packs that installed nothing. Plugin count: 11 → 2.
-
-- **Licence: MIT → Apache-2.0.** Still permissive — fork it, modify it, ship it commercially. The change is what a redistributor owes back: the contents of [NOTICE](NOTICE) must travel with any redistribution (§4d), modified files must say they were modified (§4b), and there is now an express patent grant and a trademark reservation. Releases up to v4.20.0 stay available under MIT; nothing already granted is revoked. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
-
-- **Nine packs removed**: `csharp`, `java`, `kotlin`, `ruby`, `rust`, `swift`, `frontend`, `research`, `security`. Each declared only skills and agents that already ship in the core install, so `plugin install` reported `(0 file items)` and wrote no file — on both runtimes and all three profiles. Eight owned nothing but a `README.md`. See [the measurement](kb/history/completed/no-op-plugin-packs-removed-20260727.md).
-- **Nothing is lost by the removal.** `rust-patterns`, `java-patterns`, `security-patterns`, `research-mastery` and the rest are **core skills**, still installed, still triggering as before. The packs never held them — they only listed them.
-- **`memory-pack` and `enterprise-pack` stay**: the two packs that ship files of their own — hooks, scripts, and in memory-pack's case its own skill and a SQLite store.
-- **A pack must now earn its existence**: `plugin-creator`'s authoring rule required referencing core assets rather than forking them, which against a core install that ships everything produced a no-op every time. It now requires that a pack install files the core does not, with a verification step in the checklist.
-- **`rtk-pack` retired in v4.19.0**: it broke every command it rewrote — exit 127 on `git`, `ls`, `cat`, `find`, `grep`. Measured value was 0.0615% of input tokens against a 0.05% kill number. See [the retirement note](kb/history/completed/rtk-pack-retirement-20260727.md).
-
-If you installed any removed pack, run `ai-toolkit plugin remove <name>` to drop its bookkeeping entry. No skill or agent disappears.
+[![Tests](https://img.shields.io/badge/tests-1508%20passing-success)](tests/)
+
+## What's New in v4.22.0
+
+v4.22.0 turns compatibility promises into tests, and makes two validator skills
+actually run the scanners they ship.
+
+- **The public surface is checked, not documented.** `app/surface.json` pins 275
+  entries — skills, agents, frontmatter fields, CLI commands, hook scripts and
+  events, KB categories, plugin packs. Removing any of them fails `npm test`.
+  Adding is free: a surface nobody has installed has no users to break.
+  `BACKWARD_COMPATIBILITY.md` says which surfaces are load-bearing and how to
+  deprecate one properly.
+- **`a11y-validate` and `seo-validate` shipped scanners that nothing invoked.**
+  1,196 lines of working Python sat on disk while the model was told to grep the
+  pattern tables by hand. Both now run their script for a deterministic baseline,
+  then take an explicit manual pass — with a measured coverage table saying which
+  criteria the script handles and which are yours.
+- **`/brainstorm`** — the first planning skill allowed to conclude "do not build
+  this". Every other one produces an artifact; a pipeline that cannot say no is a
+  yes-machine.
+- **Skill bodies have a budget.** Error above 20,000 bytes, warn above 18,000,
+  headroom printed every run. Three validator skills were split into
+  `reference/`, taking 47 KB off the hot path, with `scripts/check_split.py`
+  proving nothing was lost.
+- **Four skills invoked their scripts through a path that never resolved.**
+  `$(dirname "$0")` expands to the shell's directory, not the skill's.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
----
-
 ## Table of Contents
 
 - [Install](#install)
@@ -54,7 +64,7 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 108 skills, 44 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 109 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
 **Windows:** WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover `winget`, Chocolatey, and Scoop. See [Windows Support](kb/reference/windows-support.md).
 
@@ -143,7 +153,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Component | Count | Description |
 |-----------|-------|-------------|
 | `skills/` (task) | 32 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/mcp-builder`, ... |
-| `skills/` (hybrid) | 30 | Slash commands with agent knowledge base |
+| `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
 | `skills/` (knowledge) | 46 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 28 entries / 14 events + statusLine | Quality gates, path safety, prompt governance, loop guard, session lifecycle |
@@ -160,7 +170,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
-│   ├── skills/          # 108 skills (task / hybrid / knowledge)
+│   ├── skills/          # 109 skills (task / hybrid / knowledge)
 │   ├── rules/           # Source rules synced into Claude/editor rule files
 │   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
 │   ├── claude-app/      # Generated Chat/Cowork plugin rules, hooks, instructions

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.20.0",
+  "version": "4.22.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/agents/code-reviewer.md

@@ -61,7 +61,7 @@ Before reviewing, gather context using available tools:
 
 ## Review Checklist
 
-### Security (CRITICAL)
+### Security (check first)
 - [ ] No hardcoded secrets or credentials
 - [ ] Input validation on all user data
 - [ ] Output encoding for XSS prevention
@@ -86,13 +86,29 @@ Before reviewing, gather context using available tools:
 
 ## Severity Levels
 
-| Level | Description | Action |
-|-------|-------------|--------|
-| 🔴 CRITICAL | Security vulnerability, data exposure | Block deployment |
-| 🟠 HIGH | Major bug, significant risk | Must fix before merge |
-| 🟡 MEDIUM | Code quality issue | Should fix |
-| 🟢 LOW | Suggestion, improvement | Nice to have |
-| ℹ️ INFO | Note, observation | FYI |
+Four tiers, identical to the `review` skill. This agent backs that skill — the two
+must never report on different scales.
+
+| Tier | Description | Merge impact |
+|------|-------------|--------------|
+| `blocker` | Security vulnerability, data exposure, data loss, money | Blocks merge, no exceptions |
+| `major` | Real defect that will bite in production | Blocks merge unless waived in writing |
+| `minor` | Code quality issue worth fixing | Does not block |
+| `nit` | Suggestion, taste, polish | Does not block |
+
+**Verdict rule** — mechanical, not impressionistic:
+
+- any `blocker` → `rejected`
+- any `major` without a documented waiver (who waived it, why, what the follow-up is) → `rejected`
+- only `minor` / `nit`, or majors that are all waived → `approved_with_changes`
+- nothing above `nit` → `approved`
+
+## Collect All Signals Before Judging
+
+Gather every failing signal — merge conflict, red CI, lint failure — record each as
+a `blocker` finding, then review the change in full anyway. Do not end the run on
+the first red signal: the tracker already showed the author that, and the finding
+they have not seen yet is the one worth the cycle.
 
 ## Output Format
 
@@ -102,19 +118,20 @@ agent: code-reviewer
 status: completed
 findings:
   security:
-    - "🔴 CRITICAL: Hardcoded API key in config.py:42"
-    - "🟢 PASS: No SQL injection vulnerabilities"
+    - "blocker: Hardcoded API key in config.py:42"
+    - "pass: No SQL injection vulnerabilities"
   quality:
-    - "🟡 MEDIUM: Function exceeds 50 lines - consider splitting"
-    - "🟢 PASS: Error handling comprehensive"
+    - "minor: Function exceeds 50 lines - consider splitting"
+    - "pass: Error handling comprehensive"
   performance:
-    - "🟠 HIGH: N+1 query in get_users() - add eager loading"
-approval: approved_with_changes | approved | rejected
+    - "major: N+1 query in get_users() - add eager loading"
+approval: rejected     # 1 blocker present — verdict rule, clause 1
+verdict_reason: "rejected — 1 blocker (config.py:42), 1 major (get_users)"
 kb_references:
   - kb/best-practices/security-checklist.md
 next_agent: devops-implementer | infrastructure-validator
 instructions: |
-  Fix CRITICAL and HIGH issues before proceeding
+  Fix every blocker and every unwaived major before proceeding
 ---
 ```
 

package/app/skills/a11y-validate/SKILL.md

@@ -62,9 +62,10 @@ Complements `/seo-validate` (which only covers SEO-a11y overlap shallowly). Use
 ## What This Command Does
 
 1. **Detect framework** from `package.json`, `pubspec.yaml`, and entry HTML.
-2. **Scan the codebase** using `Grep` / `Glob` / `Read` against framework-aware patterns per category in scope.
-3. **Interpret findings** with specific fixes tied to the detected framework.
-4. **Report** findings sorted by severity with WCAG / EN 301 549 citations.
+2. **Run the scanner script** for a deterministic baseline over 13 WCAG success criteria.
+3. **Extend the scan by hand** using `Grep` / `Glob` / `Read` against framework-aware patterns for everything the script does not cover.
+4. **Interpret findings** with specific fixes tied to the detected framework.
+5. **Report** findings sorted by severity with WCAG / EN 301 549 citations.
 
 ## Steps
 
@@ -90,11 +91,27 @@ Run detection before scanning. Same logic as `/seo-validate` plus mobile entries
 
 Also detect a11y libraries: `@react-aria/*`, `@reach/*`, `@angular/cdk/a11y`, `vue-a11y`, `svelte-a11y`, `react-axe`, `axe-core`. Their presence is INFO.
 
-### Step 2: Run Category Scans
+### Step 2: Run the Scanner Script
 
-For each category in `--scope`, apply the pattern set below using `Grep` + `Read`. Patterns adapt to the detected framework.
+```bash
+python3 ${CLAUDE_SKILL_DIR}/scripts/a11y-scanner.py [path] [--severity high|warn|info|all] [--output json|text]
+```
+
+Deterministic regex checks over 13 WCAG success criteria — images, headings,
+language, forms, keyboard, focus, colour contrast, media, ARIA and target size.
+No framework awareness and no heuristics: what it reports is real, what it misses
+is Step 3's job. Exit code is non-zero when HIGH findings exist.
+
+### Step 3: Extend the Scan by Hand
 
-### Step 3: Interpret and Enrich
+Read [reference/scanner-categories.md](reference/scanner-categories.md) in full,
+then work every category in `--scope` with `Grep` + `Read`, skipping only the
+success criteria Step 2 already reported. Patterns adapt to the detected framework.
+
+The coverage table under [Scanner Reference](#scanner-reference) says which criteria
+Step 2 handles per category. Everything else in the category is yours.
+
+### Step 4: Interpret and Enrich
 
 For each finding:
 1. **Read the flagged file/lines** to confirm the match.
@@ -102,186 +119,34 @@ For each finding:
 3. **Mark confidence** — `definitive` for regex matches, `heuristic` for co-occurrence / absence / target-size estimation.
 4. **Skip false positives** when context shows the concern is addressed (e.g., aria-label set via intl translation key).
 
-### Step 4: Report
+### Step 5: Report
 
 Present findings sorted by severity (HIGH → WARN → INFO), then file path.
+State which findings came from the script and which from the manual pass — a reader
+needs to know how much of the result is deterministic.
 
 ---
 
 ## Scanner Reference
 
-### Category 1: Semantic Structure & Landmarks
-
-WCAG 1.3.1 (Info and Relationships), 2.4.1 (Bypass Blocks), 2.4.6 (Headings and Labels), 3.1.1 (Language of Page), 3.1.2 (Language of Parts).
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| `<html>` missing `lang` attribute | HIGH | definitive | WCAG 3.1.1 |
-| Mixed-language content without `<span lang="...">` wrapper (heuristic: non-Latin characters in otherwise-Latin content) | WARN | heuristic | WCAG 3.1.2 |
-| Page/route component with >1 `<h1>` | WARN | heuristic | WCAG 1.3.1 |
-| Heading level skip (h1 → h3 without h2) | WARN | heuristic | WCAG 1.3.1 |
-| No landmark roles / semantic elements (`<main>`, `<nav>`, `<header>`, `<footer>`) | WARN | heuristic | WCAG 1.3.1, 2.4.1 |
-| `role="presentation"` / `role="none"` on semantic element | WARN | definitive | Strips meaning; misuse of ARIA |
-| Multiple `<main>` per page | HIGH | definitive | WCAG 1.3.1 — only one `<main>` allowed |
-
-### Category 2: Text Alternatives & Non-Text Content
-
-WCAG 1.1.1 (Non-text Content).
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| `<img>` without `alt` attribute | HIGH | definitive | WCAG 1.1.1 — required even if empty |
-| `<img alt="">` on informational image (heuristic: image inside `<article>`, `<figure>`, or with adjacent caption) | WARN | heuristic | Empty alt only for decorative |
-| `<img alt="image">` / `<img alt="photo">` / `<img alt="picture">` (redundant/meaningless) | WARN | definitive | Alt should describe content |
-| `<svg>` without `<title>` + `role="img"` + `aria-label`, used in interactive context | WARN | heuristic | Inline SVG needs alternative |
-| Icon font (`<i class="fa-...">`, `<span class="material-icons">`) without `aria-label` or text alternative | WARN | definitive | WCAG 1.1.1 |
-| `<img>` used for text content (heuristic: `alt` contains a full sentence like "Click here to...") | WARN | heuristic | WCAG 1.4.5 Images of Text |
-| Complex image (`<img>` with `src` matching `chart|graph|diagram|infographic`) without long description (`aria-describedby` or `longdesc` or linked description) | WARN | heuristic | WCAG 1.1.1 for complex content |
-
-### Category 3: Keyboard & Focus
-
-WCAG 2.1.1 (Keyboard), 2.1.2 (No Keyboard Trap), 2.4.3 (Focus Order), 2.4.7 (Focus Visible).
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| `tabindex` value >0 (positive) | HIGH | definitive | WCAG 2.4.3 — breaks natural tab order |
-| `tabindex="-1"` on natively interactive element (`<button>`, `<a href>`, `<input>`, etc.) | WARN | definitive | Removes from tab order |
-| `outline: none` or `outline: 0` on focusable selector without `:focus-visible` replacement | HIGH | definitive | WCAG 2.4.7 |
-| `onClick` / `onKeyDown` handler on `<div>` / `<span>` without `role="button"` + `tabindex="0"` + keydown handler for Enter/Space | HIGH | heuristic | WCAG 2.1.1 — not keyboard-accessible |
-| No skip link (`<a href="#main">`, `<a href="#content">`) on page with navigation | WARN | heuristic | WCAG 2.4.1 Bypass Blocks |
-| Potential keyboard trap: `event.preventDefault()` / `event.stopPropagation()` in keydown handler on modal/dialog without Escape handling | WARN | heuristic | WCAG 2.1.2 |
-| Custom dropdown / combobox without `aria-expanded` + `aria-haspopup` + keyboard handlers | WARN | heuristic | WAI-ARIA Authoring Practices |
-| `autofocus` on page load on non-critical input (distracts keyboard users, moves focus unexpectedly) | WARN | definitive | Confuses assistive tech |
-| `contenteditable="true"` without `aria-label` / `aria-labelledby` | WARN | definitive | WCAG 4.1.2 |
-
-### Category 4: Color, Contrast & Visual Cues
-
-WCAG 1.4.1 (Use of Color), 1.4.3 (Contrast Minimum), 1.4.11 (Non-text Contrast).
-
-**Static analysis limitation**: actual contrast ratios depend on the CSS cascade, custom properties, theme switching, and background images. The skill flags patterns where contrast is AT RISK; pair with runtime tools (axe-core, Lighthouse) for definitive measurement.
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| Hardcoded foreground+background color pairs in CSS where computed contrast is <4.5:1 (normal) or <3:1 (large text) | WARN | heuristic | WCAG 1.4.3 — verify at runtime |
-| Link inside body text without underline/border AND only `color` distinguishing it | WARN | heuristic | WCAG 1.4.1 — color-only signalling |
-| Error/required field indicated only by red color (no icon, text, or shape) | WARN | heuristic | WCAG 1.4.1 |
-| Required form field marked only with `*` character without `aria-required="true"` + text explanation | WARN | definitive | WCAG 1.4.1 + 3.3.2 |
-| CSS uses `color: red`/`color: green` as sole signal (success vs error) | WARN | heuristic | WCAG 1.4.1 |
-| Focus indicator with <3:1 contrast against background (heuristic from color values) | WARN | heuristic | WCAG 1.4.11 |
-| Button/input border color with <3:1 contrast against adjacent color | WARN | heuristic | WCAG 1.4.11 |
-| CSS `text-shadow`/`opacity` on body text reducing effective contrast | INFO | heuristic | May affect 1.4.3 |
-
-### Category 5: Forms, Labels & Errors
-
-WCAG 1.3.5 (Identify Input Purpose), 3.3.1 (Error Identification), 3.3.2 (Labels or Instructions), 3.3.3 (Error Suggestion), 4.1.2 (Name, Role, Value).
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| `<input>` / `<select>` / `<textarea>` without `<label for="...">` AND without `aria-label` / `aria-labelledby` | HIGH | heuristic | WCAG 3.3.2, 4.1.2 |
-| `<label>` without `for` attribute (implicit association only works if input is a child) | WARN | definitive | WCAG 3.3.2 |
-| `<input type="email"/tel/name/password/address">` without `autocomplete` attribute | WARN | definitive | WCAG 1.3.5 |
-| Missing `autocomplete="one-time-code"` on OTP input with `inputmode="numeric"` | INFO | definitive | Improves user experience |
-| Radio / checkbox group without `<fieldset>` + `<legend>` | WARN | heuristic | WCAG 1.3.1 |
-| Error messages displayed visually but not linked via `aria-describedby` to the input | WARN | heuristic | WCAG 3.3.1 |
-| `required` attribute without accompanying `aria-required="true"` (belt-and-suspenders for assistive tech consistency) | INFO | definitive | WCAG 4.1.2 (modern SR handle `required` but legacy may not) |
-| Error uses `role="alert"` without being updated dynamically (static alert on page load) | INFO | heuristic | WCAG 4.1.3 |
-| Placeholder used as label (no visible label, only `placeholder`) | WARN | heuristic | WCAG 3.3.2 — placeholder disappears on focus |
-| `<input type="email">` without `inputmode="email"` (mobile UX) | INFO | definitive | EN 301 549 mobile |
-
-### Category 6: Media (Audio, Video, Embeds)
-
-WCAG 1.2.1–1.2.5 (Captions, audio description, sign language), 1.4.2 (Audio Control).
-
-**EAA is specifically strict about media** — video without captions is a common legal-risk finding.
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| `<video>` without `<track kind="captions">` child (or `<track kind="subtitles">` for foreign-language) | HIGH | definitive | WCAG 1.2.2 — EAA legal risk |
-| `<video>` without transcript link or `<track kind="descriptions">` | WARN | heuristic | WCAG 1.2.3 / 1.2.5 |
-| `<audio>` without transcript link or `<track kind="captions">` | HIGH | definitive | WCAG 1.2.1 |
-| `<video autoplay>` without `muted` | HIGH | definitive | WCAG 1.4.2 — auto-playing audio |
-| `<video autoplay loop>` running >5 seconds without pause control | WARN | heuristic | WCAG 1.4.2, 2.2.2 |
-| YouTube/Vimeo embed URL without `cc_load_policy=1` or equivalent CC parameter | INFO | definitive | Platform-dependent captioning |
-| YouTube embed via `<iframe src="https://www.youtube.com/embed/...">` without accessibility enhancements | INFO | definitive | Note: platform controls most a11y |
-| Live media without real-time caption indication | WARN | heuristic | WCAG 1.2.4 |
-| Background video (hero section) without pause button in DOM | WARN | heuristic | WCAG 2.2.2 |
-
-### Category 7: ARIA, Live Regions & Dynamic Content
-
-WCAG 4.1.2 (Name, Role, Value), 4.1.3 (Status Messages).
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| `aria-hidden="true"` on focusable element | HIGH | definitive | Creates orphaned focus — serious a11y bug |
-| `role="button"` on native `<button>` (redundant ARIA) | WARN | definitive | ARIA Authoring: avoid redundant roles |
-| `role="link"` on `<a href>` / `role="heading"` on `<h1–h6>` (redundant ARIA) | WARN | definitive | Same |
-| Conflicting roles (`<button role="link">`, `<a role="button">`) | WARN | definitive | WAI-ARIA — wrong role |
-| Custom toggle (disclosure, menu, accordion) without `aria-expanded` + `aria-controls` | WARN | heuristic | WAI-ARIA |
-| `aria-labelledby` referencing non-existent ID | HIGH | heuristic | Broken reference |
-| `aria-describedby` referencing non-existent ID | HIGH | heuristic | Broken reference |
-| `aria-live` region without `role="status"` / `role="alert"` AND async updates in component (heuristic) | WARN | heuristic | WCAG 4.1.3 |
-| Toast/notification component without `role="status"` or `role="alert"` | WARN | heuristic | WCAG 4.1.3 |
-| Modal / dialog without `role="dialog"` + `aria-modal="true"` + focus trap | WARN | heuristic | WAI-ARIA Authoring Practices |
-| Tabs without proper roles (`role="tablist"` + `role="tab"` + `role="tabpanel"`) | WARN | heuristic | WAI-ARIA Authoring Practices |
-
-### Category 8: Motion, Target Size, Mobile & EAA Docs
-
-#### 8a. Motion & Animation
-
-WCAG 2.2.2 (Pause, Stop, Hide), 2.3.3 (Animation from Interactions — AAA but EAA-recommended).
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| CSS animation / transition / transform without matching `@media (prefers-reduced-motion: reduce)` override | WARN | heuristic | WCAG 2.3.3 |
-| JS animation library (GSAP, framer-motion, anime.js) without `matchMedia('(prefers-reduced-motion: reduce)')` check | WARN | heuristic | WCAG 2.3.3 |
-| Parallax scrolling without opt-out | WARN | heuristic | WCAG 2.3.3 |
-| Infinite animation (CSS `animation: name infinite`) on content element without pause control | WARN | heuristic | WCAG 2.2.2 |
-| `<marquee>` / `<blink>` (deprecated) | HIGH | definitive | WCAG 2.2.2 |
-
-#### 8b. Target Size (WCAG 2.2 Minimum AA 2.5.8 + EN 301 549)
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| Interactive target with declared size <24×24 px (heuristic from CSS: `width`/`height`/`padding` on buttons/links/inputs) | WARN | heuristic | WCAG 2.2 2.5.8 / EN 301 549 |
-| Touch-target spacing <8 px between adjacent interactive elements | INFO | heuristic | Best practice |
-
-#### 8c. Viewport & Zoom
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| `<meta name="viewport">` containing `user-scalable=no` / `user-scalable=0` | HIGH | definitive | WCAG 1.4.4 — blocks zoom |
-| `<meta name="viewport">` with `maximum-scale=1` / `maximum-scale=1.0` | HIGH | definitive | WCAG 1.4.4 |
-| Content rendered via `<img>` for text (text-as-image) | WARN | heuristic | WCAG 1.4.5 |
-
-#### 8d. Mobile (React Native + Flutter)
-
-EN 301 549 mobile chapter. Critical for EAA scope since consumer apps are in-scope.
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| **React Native**: `<TouchableOpacity>` / `<TouchableHighlight>` / `<Pressable>` without `accessibilityLabel` | HIGH | definitive | EN 301 549 mobile |
-| **React Native**: `<Image>` without `accessibilityLabel` or `accessible={false}` | WARN | heuristic | EN 301 549 |
-| **React Native**: Missing `accessibilityRole` on custom components that behave as buttons/links | WARN | heuristic | EN 301 549 |
-| **React Native**: `Alert.alert` for error flow without `AccessibilityInfo.announceForAccessibility` fallback | INFO | heuristic | — |
-| **Flutter**: Interactive widget (`GestureDetector`, `InkWell`, `TextButton`, `IconButton`) without `Semantics()` wrapper or `semanticLabel` parameter | HIGH | definitive | EN 301 549 mobile |
-| **Flutter**: `Image()` / `Image.asset()` / `Image.network()` without `semanticLabel` (or `excludeFromSemantics: true` for decorative) | WARN | definitive | EN 301 549 |
-| **Flutter**: Missing `ExcludeSemantics` / `MergeSemantics` where child semantics conflict | INFO | heuristic | Semantics tree cleanup |
-
-#### 8e. EAA Accessibility Documentation
-
-**Activated by `--standard eaa`.** EAA Article 14 + member-state transpositions require consumer-facing services to publish an accessibility statement. Missing statement = HIGH legal finding.
-
-| Pattern | Severity | Confidence | Description |
-|---------|----------|------------|-------------|
-| No route at any of: `/accessibility`, `/accessibility-statement`, `/a11y`, `/dostepnosc` (PL), `/barrierefreiheit` (DE), `/declaration-accessibilite` (FR), `/declaración-accesibilidad` (ES), `/dichiarazione-accessibilita` (IT), `/toegankelijkheidsverklaring` (NL) | HIGH | heuristic | EAA Article 14 |
-| Footer / sitemap lacks link to accessibility statement | HIGH | heuristic | EAA visibility requirement |
-| Accessibility statement present but missing required elements: (a) conformance level (WCAG/EN 301 549), (b) list of non-conformant content, (c) feedback mechanism, (d) enforcement procedure link | WARN | heuristic | Member-state template requirement |
-| No contact mechanism (email / form) for accessibility feedback referenced in statement | WARN | heuristic | EAA Article 14 |
-| `robots.txt` disallows `/accessibility*` path (accidentally blocks statement from crawlers + assistive tech) | WARN | definitive | Discoverability |
-
-See: [reference/eaa-compliance.md](reference/eaa-compliance.md) for directive text, member-state deadlines, statement templates.
-
----
+`scripts/a11y-scanner.py` gives a deterministic baseline over 13 WCAG success
+criteria. Everything else in each category is a manual pass, and the full pattern
+tables for it live in
+[reference/scanner-categories.md](reference/scanner-categories.md).
+
+| # | Category | Covered by the script | Manual pass |
+|---|----------|----------------------|-------------|
+| 1 | Semantic Structure & Landmarks | 1.3.1, 3.1.1 | rest of the category |
+| 2 | Text Alternatives & Non-Text Content | 1.1.1 | rest of the category |
+| 3 | Keyboard & Focus | 2.1.1, 2.4.3, 2.4.7 | rest of the category |
+| 4 | Color, Contrast & Visual Cues | 1.4.3 | rest of the category |
+| 5 | Forms, Labels & Errors | 3.3.2 | rest of the category |
+| 6 | Media (Audio, Video, Embeds) | 1.2.1, 1.2.2, 1.4.2 | rest of the category |
+| 7 | ARIA, Live Regions & Dynamic Content | 4.1.2 | rest of the category |
+| 8 | Motion, Target Size, Mobile & EAA Docs | 2.5.8 | rest of the category |
+
+The script never covers a whole category. Treat its output as the floor, not the
+result: a run that reports only script findings has skipped most of WCAG 2.1 AA.
 
 ## Output Format
 
@@ -362,6 +227,23 @@ For these, use: `axe-core`, `pa11y`, Lighthouse accessibility audit, manual assi
 - **No auto-fix**: A11y fixes often require design/content decisions that exceed pattern matching.
 - **Don't flag missing ARIA when native semantics suffice**: Prefer native HTML elements; flag redundant ARIA, not absence when the native element is already there.
 
+## Gotchas
+
+- `scripts/a11y-scanner.py` exits **1 when it finds HIGH findings**, which is success for this skill, not failure. A wrapper that treats non-zero as an error will report a clean scan on the codebase with the most problems.
+- The script covers 13 success criteria; `reference/wcag-2-1-aa.md` documents ~50. Reporting only script output looks like a full WCAG 2.1 AA pass and is not one — Step 3 is where most of the standard actually gets checked.
+- Colour contrast is computed from **hardcoded hex values in source**. A theme built on CSS custom properties, `oklch()`, or a design-token pipeline yields no matches at all, and "no contrast findings" then means "nothing was measurable", not "contrast is fine".
+- `alt=""` is correct for decorative images and wrong for meaningful ones. The scanner cannot see which is which — it flags missing `alt`, not useless `alt`, so a codebase that blanket-added `alt=""` scans clean while being less accessible than one that omitted the attribute.
+- React Native and Flutter have no DOM. Categories written around HTML elements (landmarks, heading order, `lang`) do not transfer; use `reference/mobile-eaa.md` instead of reporting the whole category as passing.
+- `--standard eaa` findings are **legal** risk with a June 2025 deadline, not code-quality suggestions. Downgrading a missing accessibility statement to WARN because it "isn't a code problem" misreports regulatory exposure.
+
+## When NOT to Use
+
+- To prove WCAG conformance for an audit or a VPAT — this is static analysis; conformance needs assistive-tech testing with disabled participants.
+- To check contrast in a themed or token-driven design system — run `axe-core` or Lighthouse against the rendered page instead.
+- For a runtime-only concern (focus traps, screen-reader announcement order, zoom reflow at 200%/400%) — see [Out of Scope](#out-of-scope-static-analysis-cannot-detect).
+- For the a11y subset that affects search ranking — use `/seo-validate`, category 9.
+- To fix what was found — this skill is read-only by contract; fixes usually need design and content decisions.
+
 ## Reference Documents
 
 - [reference/wcag-2-1-aa.md](reference/wcag-2-1-aa.md) — All 50 Level A + AA success criteria with detection status (statically detectable vs runtime-only).