feat(a11y): skill (scan, keyboard walk, report, fix loop on the bugfix circuit), lazy rules/a11y.md, profiles, locks

This commit is contained in:
bchanot committed 2026-10-19 00:48:09 +02:00
1 parent 45e3454b99
commit 60d447e544
16 files changed
+284 -7

No files matched your search

+1 -1
View File
@@ -1,6 +1,6 @@
---
name: bugfixer
description: Bug-fix EXECUTOR — dispatched by /bugfix (or /guardrails for accepted fixes) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite, reports. No investigation, no questions, no commit.
description: Bug-fix EXECUTOR — dispatched by /bugfix (or /guardrails and /a11y for accepted fixes) with a closed DIAGNOSIS + FIX PLAN + contract. Applies the fix and a regression test, runs the suite, reports. No investigation, no questions, no commit.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
effort: medium
+1 -1
View File
@@ -114,7 +114,7 @@ Template:
```markdown
# CONTRACT — <slug>
- date: <YYYY-MM-DD> | flow: <ship-feature|feat|bugfix|hotfix|init-project|onboard|guardrails> | branch: <branch>
- date: <YYYY-MM-DD> | flow: <ship-feature|feat|bugfix|hotfix|init-project|onboard|guardrails|a11y> | branch: <branch>
- status: active
## REQUEST (verbatim — IMMUTABLE)
+1
View File
@@ -6,6 +6,7 @@
cso
harden personal
guardrails personal
a11y personal
analyze personal
# SEO / GEO / web standards
+1
View File
@@ -19,6 +19,7 @@ code-clean personal
commit-change personal
explain-diff personal
guardrails personal
a11y personal
# Dev-lifecycle skills (agent-skills trio)
observability-and-instrumentation external
+1
View File
@@ -46,6 +46,7 @@ geo personal
web-validate personal
harden personal
guardrails personal
a11y personal
analyze personal
cso
+1
View File
@@ -47,6 +47,7 @@ geo personal
web-validate personal
harden personal
guardrails personal
a11y personal
analyze personal
cso
+1
View File
@@ -34,6 +34,7 @@ geo personal
web-validate personal
harden personal
guardrails personal
a11y personal
analyze personal
# === Perf + canary ===================================================
+1
View File
@@ -28,6 +28,7 @@ refactor personal
# Validation companion (basic W3C/a11y check during build)
web-validate personal
a11y personal
# External: design skills
emil-design-eng external
+10
View File
@@ -15,6 +15,7 @@ BSK="$REPO/skills/bugfix/SKILL.md"
HOT="$REPO/agents/hotfixer.md"
HSK="$REPO/skills/hotfix/SKILL.md"
GSK="$REPO/skills/guardrails/SKILL.md"
ASK="$REPO/skills/a11y/SKILL.md"
HSKL="$REPO/skills/hotfix/SKILL.md"
PASS=0; FAIL=0
@@ -79,6 +80,15 @@ tf "guardrails positive control" "$GSK" "Positive control"
tf "guardrails approval gate" "$GSK" "Nothing is applied without the user's explicit acceptance"
tf "guardrails re-pass baseline" "$GSK" "GUARDRAILS-NO-NEW"
echo "── skills/a11y/SKILL.md (fix loop reuses the bugfix circuit) ──"
tf "a11y contract include" "$ASK" "lib/contract-interview.md"
tf "a11y uses shared include" "$ASK" "lib/verify-secure-loop.md"
tf "a11y dispatches bugfixer" "$ASK" 'subagent_type="bugfixer"'
tf "a11y scanner is the oracle" "$ASK" "EXPECT: A11Y-CLEAR"
tf "a11y positive control" "$ASK" "Positive control"
tf "a11y approval gate" "$ASK" "Nothing is applied without the user's explicit acceptance"
tf "a11y re-pass baseline" "$ASK" "A11Y-NO-NEW"
echo "── agents/bugfixer.md (bugfix executor — sonnet, no Agent) ──"
tn "bugfixer lacks Agent tool" "$BUG" "Agent"
tf "bugfixer model sonnet" "$BUG" "model: sonnet"
+2 -2
View File
@@ -9,8 +9,8 @@ has() { if grep -qF "$2" "$R/$1"; then ok; else ko "$1 missing: $2"; fi; }
lacks() { if grep -qF "$2" "$R/$1"; then ko "$1 must NOT contain: $2"; else ok; fi; }
fm_lacks() { if awk 'NR<=10' "$R/$1" | grep -qF "$2"; then ko "$1 frontmatter must NOT contain: $2"; else ok; fi; }
# 1) gate wired in the 16 reflection skills (orchestrators, /analyze, /guardrails)
for s in ship-feature init-project feat bugfix onboard seo geo web-validate harden audit-delta tour code-clean hotfix client-handover analyze guardrails; do
# 1) gate wired in the 17 reflection skills (orchestrators, /analyze, /guardrails, /a11y)
for s in ship-feature init-project feat bugfix onboard seo geo web-validate harden audit-delta tour code-clean hotfix client-handover analyze guardrails a11y; do
has "skills/$s/SKILL.md" 'lib/model-gate.md'
done
# 2) gate NOT wired in the pure-execution/read-only skills (exclusion list)
+1 -1
View File
@@ -1,4 +1,4 @@
# Verify + secure loop — shared orchestrator include (feat, bugfix, guardrails)
# Verify + secure loop — shared orchestrator include (feat, bugfix, guardrails, a11y)
Runs in the ORCHESTRATOR MAIN LOOP after the dev step completes. Turns a
finished diff into a verified, security-cleared change through two fresh
+10
View File
@@ -0,0 +1,10 @@
---
paths: ["**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.svelte", "**/*.astro", "**/*.html", "**/*.css", "**/*.scss"]
---
# Accessibility baseline (audit and fix: `/a11y`)
- Everything reachable and usable by keyboard, focus always visible.
`:focus-visible` styled, never `outline: none` without a replacement.
- Every image has an `alt` (empty when decorative). Every field has a label;
a placeholder is not a label.
+2 -2
View File
@@ -27,7 +27,7 @@ paths: ["**/*.html", "**/*.astro", "**/*.css", "**/*.scss", "**/*.tsx", "**/*.js
- Motion: transform and opacity only; feedback under 200 ms, ease-out on
entrances, never from scale(0); `will-change` only during an active
animation; pause loops off-screen; honor `prefers-reduced-motion`.
- Touch targets 44 px minimum; visible `:focus-visible` ring; status never
- Touch targets 44 px minimum; keyboard and focus per `rules/a11y.md`; status never
by color alone, add text or an icon.
- Errors next to the field; empty state = one clear action; destructive
action confirmed first.
@@ -36,7 +36,7 @@ paths: ["**/*.html", "**/*.astro", "**/*.css", "**/*.scss", "**/*.tsx", "**/*.js
## Before declaring a public site done
Check: custom 404 · call to action in the first viewport · per-page
title + description · share/OG image · favicons · robots.txt · sitemap ·
alt text on images · layout tested at 375 px · loading states · form
accessibility baseline (`rules/a11y.md`) · layout tested at 375 px · loading states · form
error messages · confirmation page · real legal mentions · cookie banner
with a working refuse option · audience measurement · contact address ·
compressed images.
+200
View File
@@ -0,0 +1,200 @@
---
name: a11y
effort: high
description: 'Use when a web project needs its accessibility baseline checked and fixed: everything reachable by keyboard with a visible focus, an alt on every image, a label on every field. Full WCAG conformance (axe, pa11y, W3C) → /web-validate; security guardrails → /guardrails. Deterministic scanner (A11Y-* rules: img alt, field label, click without keyboard, focus outline removed, positive tabindex), judgment, a Tab-only walk of the main flow on --live (through /browse, else marked not done), report .claude/audits/A11Y.md, then fixes proposed with the alt and label wording as visible choices, applied only on acceptance (bugfixer executor, fresh verifier and security gates, the scanner as oracle) and re-scanned to prove each one. Triggers: "a11y", "accessibilité", "accessibility basics", "clavier", "focus visible", "alt manquant", "label sur les champs", "tab order", "corrige l''accessibilité".'
argument-hint: '[project path] [--exclude paths] [--live <url you own>] [--report-only]'
---
# /a11y
Checks a project's accessibility baseline (`rules/a11y.md`), then fixes what
the user accepts and proves each fix. A scanner reads the tree as data and
finds what text can prove: a missing alt, an unlabeled field, a click with no
keyboard path, a focus outline removed, a positive tabindex. This skill judges
the hits, walks the main flow with the keyboard when a browser is available,
proposes fixes, applies the accepted ones and scans again until every accepted
fix is proven.
The scanner proves absence of a baseline, never presence of accessibility. A
clean scan means "no static finding", and the report says exactly that. Full
WCAG conformance (contrast, structure, ARIA semantics, axe or pa11y runs) is
`/web-validate`'s job.
## MODEL GATE (blocking, before any other step)
Run `$HOME/.claude/lib/model-gate.md`. Judging hits and writing alt and label
text requires Fable or Opus. Verdict `small` → STOP: the gate prints the
remedy. ROUTING: follow `$HOME/.claude/lib/effort-shift.md` (phases via
`mcp__model-router__route`); each step below names its phase.
## STEP 1: Scope
Work in the project the user names, else the current directory. Say in one
line what you will scan. `--report-only` stops after STEP 5: audit, no fix.
## STEP 2: Run the scanner
```
python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" <path>
```
Add `--exclude a/b,c` to skip copies or vendored code, `--json` for machine
output. Exit 0 means no FAIL, 1 means at least one, 2 is a usage error. It
never executes project code. Severities: **FAIL**, the baseline is provably
missing; **WARN**, a pattern that is often wrong, judgment needed.
## STEP 3: Judge every FAIL and WARN
Read the file around each line. Label it CONFIRMED, FALSE POSITIVE (say why)
or ACCEPTED RISK (the user decides, never you). A decorative image with
`alt=""`, a field labeled through `aria-labelledby`, a click handler on a
`role="presentation"` overlay and an outline swapped for a visible border or
ring are the usual false positives; `references/checks.md` lists the blind
spots. Check them before calling a hit false.
## STEP 4: Keyboard walk (on `--live`, read-only)
With a dev server the user names, walk the main flow with Tab only through
`/browse`: every control reached in a sensible order, the focus visible at
each stop, Enter and Space working on what looks clickable, Escape closing
what opened. Record each stop that fails with the page and the element.
Without a browser tool, or without `--live`, the report marks the walk
"not done": a static scan cannot see a keyboard trap, a focus order or a
modal that loses focus.
## STEP 5: Report
Write `.claude/audits/A11Y.md`: one table with status PASS, FAIL, WARN or
N/A per rule, the evidence, the fix in one line, and the keyboard walk's
result (done, with its stops, or not done). PASS means "no static finding".
Keep it short; no filler sections. `--report-only`, or nothing CONFIRMED:
reply with counts, the FAILs with file:line and the walk's stops, then stop.
## STEP 6: Propose fixes
`mcp__model-router__route(phase="plan")`: wording is the deepest thinking in
this run, it goes to the plan row.
One proposal per CONFIRMED finding, grouped by rule and file; merge pairs
that one change closes (one `:focus-visible` rule closes every outline
removal in a stylesheet). FALSE POSITIVE and ACCEPTED RISK get no proposal.
Each proposal:
- **number, rule, file(s)**, and the problem in one line;
- **the fix**, concrete: file:line and the change. A missing alt gets a
description of what the image shows, or `alt=""` when it is decorative; an
unlabeled field gets a `label for`, a wrapping label or `aria-label`; a
clickable `div` becomes a `button`, or gains `role`, `tabindex` and a key
handler; a removed outline gets a `:focus-visible` style;
- **choices the user sees**: the alt text and the label wording, each with
your proposed value, named so the user can change it. These are content,
never invented silently: they ship only with the user's acceptance;
- **risk**: what it can break (`button` reset styles, a changed tab order).
`DECISION` when no wording is defensible (an image you cannot describe);
- **proof**: the scanner pairs that must disappear (`RULE:path`), and the
walk stop that must pass when `--live` ran.
Save the proposals to `.claude/tasks/plans/<YYYY-MM-DD>-a11y-<HHMM>.md` and
append them to the report. In the reply, show them as a numbered list, one or
two lines each, DECISION marked.
## STEP 7: Approval (gate, ends the turn)
Nothing is applied without the user's explicit acceptance. Ask once, then
stop the turn:
```
Which fixes do I apply? "all" (every proposal except DECISION ones),
numbers ("1,3,5-7"), "none", or an amendment ("2 with the alt 'Team photo'").
A DECISION proposal needs its number plus your wording.
```
On resume, `mcp__model-router__route(phase="reflect")`. "none" → stop,
proposals stay in the report. An amendment rewrites that proposal in the plan
file before anything else. Accepted set empty → stop.
## STEP 8: Apply
1. **Branch.** Not a git repository → stop: fixes need a diff to review.
On `main`/`develop`, `bash ~/.claude/lib/gitflow.sh start bugfix
a11y-<YYYY-MM-DD>`; on a working branch, stay. Never `finish`.
2. **Baseline**, before any edit:
`python3 -B <scan.py> <root> --json > .claude/audits/.a11y-baseline.json`.
A derived file: never staged, never committed.
3. **Contract** per `$HOME/.claude/lib/contract-interview.md` (STEP 4
template, `flow: a11y`). REQUEST = the user's acceptance verbatim plus the
accepted proposals. One criterion per accepted proposal, its oracle the
scanner itself:
```
1. <proposal 1 in one line>
CHECK: python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" '<abs root>' --assert-absent 'RULE:path,RULE:path'
EXPECT: A11Y-CLEAR
EVIDENCE: pending
```
Add one criterion for the project suite when one exists
(`CHECK: <test command> && echo TESTS-GREEN`, `EXPECT: TESTS-GREEN`). The
keyboard walk is a criterion without CHECK: STEP 9 settles it. FILE SCOPE
= the files the accepted proposals name. Paths go in single quotes; a path
holding a single quote is named to the user, never written into a CHECK.
4. **Positive control.** Run each oracle once on the unfixed tree: it must
fail. An oracle that passes before the fix proves nothing; drop it, find
why, and say so.
5. **Dispatch the executor**, one fresh `bugfixer` for the accepted set
(batches of 8 proposals at most, one after the other on the same branch):
```
mcp__model-router__route(phase="orchestrate") # send with the Agent call
Agent(subagent_type="bugfixer")
prompt: "CONTRACT: <path>
DIAGNOSIS: <each accepted finding: rule, file:line, evidence>
FIX PLAN: <the accepted proposals verbatim, with the user's wording; the
regression check of each is its contract oracle, plus the project test
the proposal names>
BRANCH: <current branch>
Apply to the letter. No commit, no branch ops, no security dispatch.
Finish with the BUGFIX-EXEC REPORT."
```
`NEED-DECISION` routes per MID-RUN CLARIFICATION of the contract include:
a wording, visible or scope question goes to the user verbatim.
`BLOCKED` → surface it, stop.
6. **Gates** per `$HOME/.claude/lib/verify-secure-loop.md`, `CONTRACT` the
path above, `DIFF` the executor's working-tree diff, `TEST` the suite.
GATE 0 runs every scanner oracle (the per-fix proof), GATE 1 a fresh
verifier, GATE 2 a fresh security-auditor. Loop caps and escalation are
the include's; loop decisions stay in this main loop.
## STEP 9: Re-pass (prove it all)
`mcp__model-router__route(phase="reflect")`. The gates proved each accepted
fix on its own; this pass proves the whole tree.
1. Full scan against the baseline:
```
python3 -B <scan.py> <root> --baseline .claude/audits/.a11y-baseline.json
```
Every accepted pair must show `FIXED`, and the run must end on
`A11Y-NO-NEW` (exit 0). A `NEW` hit is a regression the fix made.
2. Live: when STEP 4 ran, walk the same flow again once the user has reloaded
the dev server and says go. Each stop a proposal named must now pass.
3. Add an "after" column to `.claude/audits/A11Y.md`: proposal, before,
after, evidence.
Anything not fixed, or a NEW hit → one more round from STEP 6, limited to
those items. Two rounds at most: after the second, stop with the residuals
open and say so plainly. Never report a fix the re-pass did not prove.
## STEP 10: Commit and hand over
1. **Commit gate.** Show files, `git diff --stat` and the message, wait for
the user's go:
```
A11Y: READY TO COMMIT
FILES : <list>
MESSAGE : fix(a11y): <rules fixed, one line>
```
Then `git add <files touched>` (never `-A`, never the baseline file) and
commit, project convention else 50 words at most.
2. `mcp__model-router__route(phase="apply")` for the tail. Reply with: fixed
and proven (proposal, rule, file), still open and why, the walk's result,
the branch name. Merge waits for the user's explicit signal.
3. Offer to capitalize a reusable lesson (a false-positive class, a fix
pattern), entry pre-filled, written only on approval.
+44
View File
@@ -0,0 +1,44 @@
# Accessibility checks
Rule ids the scanner emits, what each proves, and the fix. Severity is the
default; a judged hit can be a false positive.
| Rule | Sev | Catches | Fix |
|---|---|---|---|
| A11Y-IMG-ALT | FAIL | `img` or `Image` without `alt` | describe it, or `alt=""` if decorative |
| A11Y-FIELD-LABEL | FAIL | native input, select, textarea with no label | `label for`, wrapping label or `aria-label` |
| A11Y-CLICK-NO-KEYBOARD | FAIL | click handler on a div or span lacking role, tabindex or key handler | use a `button` |
| A11Y-FOCUS-OUTLINE | FAIL / WARN | focus outline removed; WARN when a `:focus-visible` style exists elsewhere | style `:focus-visible` instead |
| A11Y-TABINDEX-POSITIVE | WARN | `tabindex` above 0 | use 0 or -1 and fix the DOM order |
## Blind spots
The scanner is regex over markup and styles. It cannot see:
- keyboard traps, focus order, a modal that keeps or loses focus, color
contrast: the `--live` walk covers the first three, `/web-validate` the
fourth
- a label wired through `aria-labelledby` to an element in another file
- components whose markup is built at runtime, minified bundles, anything
over 1 MB
- `.astro` files for the click rule (never flagged)
By design the scanner ignores: fields that are never rendered (`hidden`,
`display: none`), click handlers that only stop propagation or sit on
`role="presentation"`, focus styles that swap the outline for a border or
shadow, and `img` tags inside comments.
## Fix loop: oracles and re-pass
Every accepted fix is proven by the scanner itself, never by the executor's
word. Two check modes replace the report and its exit code:
| Mode | Passes when | Marker | Used by |
|---|---|---|---|
| `--assert-absent RULE:path,...` | none of these FAIL/WARN pairs remains, the domain was scanned, the tree is not empty | `A11Y-CLEAR <n>` | a contract `CHECK:` run by `lib/gates.sh` (GATE 0) |
| `--baseline before.json` | no FAIL/WARN hit appeared since the earlier `--json` run | `A11Y-NO-NEW` | STEP 9 re-pass |
Pairs match on rule and file, not line: a fix moves lines. An empty tree
fails the assertion, because absence there proves nothing. Run every oracle
once before the fix: it must fail. The baseline lists `FIXED` and `NEW`
pairs with their hit counts; a `NEW` hit after a fix is a regression.
+7
View File
@@ -0,0 +1,7 @@
[
{"id": 1, "prompt": "vérifie l'accessibilité de base de ~/Documents/faunosteo : clavier, alt, labels", "expected": "Runs the a11y scanner on the path, reads each A11Y FAIL and WARN in context, marks the keyboard walk not done (no --live), writes .claude/audits/A11Y.md, proposes fixes with alt and label wording as visible choices, stops for approval"},
{"id": 2, "prompt": "il manque des alt sur les images du site, corrige", "expected": "Scans, confirms each A11Y-IMG-ALT hit, proposes one alt text per image (or alt=\"\" for decorative ones) as a named choice, applies only after acceptance on a bugfix branch with --assert-absent oracles, re-scans against the baseline"},
{"id": 3, "prompt": "Walk my app at http://localhost:3000 with the keyboard only and tell me where focus gets lost", "expected": "Static scan first, then the Tab walk through /browse on the named localhost target, records each stop with no visible focus or unreachable control, reports them next to the static findings, fixes nothing without approval"},
{"id": 4, "prompt": "est-ce que mon site passe les critères WCAG AA ?", "expected": "Routes to /web-validate for WCAG conformance; runs /a11y only if the user asks for the keyboard/alt/label baseline"},
{"id": 5, "prompt": "a11y --report-only sur ce projet", "expected": "Scan and judgment only, report written, counts and file:line in the reply, no proposal, no branch, no edit"}
]