diff --git a/agents/bugfixer.md b/agents/bugfixer.md index bcbc8f8..412725c 100644 --- a/agents/bugfixer.md +++ b/agents/bugfixer.md @@ -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 diff --git a/lib/contract-interview.md b/lib/contract-interview.md index 870cd11..1c453a6 100644 --- a/lib/contract-interview.md +++ b/lib/contract-interview.md @@ -114,7 +114,7 @@ Template: ```markdown # CONTRACT — -- date: | flow: | branch: +- date: | flow: | branch: - status: active ## REQUEST (verbatim — IMMUTABLE) diff --git a/lib/profiles/audit.profile b/lib/profiles/audit.profile index 7e15b9f..61d8602 100644 --- a/lib/profiles/audit.profile +++ b/lib/profiles/audit.profile @@ -6,6 +6,7 @@ cso harden personal guardrails personal +a11y personal analyze personal # SEO / GEO / web standards diff --git a/lib/profiles/dev.profile b/lib/profiles/dev.profile index cc07f11..300b4e0 100644 --- a/lib/profiles/dev.profile +++ b/lib/profiles/dev.profile @@ -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 diff --git a/lib/profiles/full.profile b/lib/profiles/full.profile index 55d18cc..b792eef 100644 --- a/lib/profiles/full.profile +++ b/lib/profiles/full.profile @@ -46,6 +46,7 @@ geo personal web-validate personal harden personal guardrails personal +a11y personal analyze personal cso diff --git a/lib/profiles/max.profile b/lib/profiles/max.profile index 5060c45..2792c78 100644 --- a/lib/profiles/max.profile +++ b/lib/profiles/max.profile @@ -47,6 +47,7 @@ geo personal web-validate personal harden personal guardrails personal +a11y personal analyze personal cso diff --git a/lib/profiles/web-full.profile b/lib/profiles/web-full.profile index 9376f75..1c49fcf 100644 --- a/lib/profiles/web-full.profile +++ b/lib/profiles/web-full.profile @@ -34,6 +34,7 @@ geo personal web-validate personal harden personal guardrails personal +a11y personal analyze personal # === Perf + canary =================================================== diff --git a/lib/profiles/web.profile b/lib/profiles/web.profile index ee53a99..7d32538 100644 --- a/lib/profiles/web.profile +++ b/lib/profiles/web.profile @@ -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 diff --git a/lib/tests/loops-light.test.sh b/lib/tests/loops-light.test.sh index 6d8ecb9..9d546de 100644 --- a/lib/tests/loops-light.test.sh +++ b/lib/tests/loops-light.test.sh @@ -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" diff --git a/lib/tests/model-routing.test.sh b/lib/tests/model-routing.test.sh index f24f890..5352078 100755 --- a/lib/tests/model-routing.test.sh +++ b/lib/tests/model-routing.test.sh @@ -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) diff --git a/lib/verify-secure-loop.md b/lib/verify-secure-loop.md index f75721f..8af5f2d 100644 --- a/lib/verify-secure-loop.md +++ b/lib/verify-secure-loop.md @@ -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 diff --git a/rules/a11y.md b/rules/a11y.md new file mode 100644 index 0000000..0dec6ab --- /dev/null +++ b/rules/a11y.md @@ -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. diff --git a/rules/web-building.md b/rules/web-building.md index 61fbc0e..809a0b4 100644 --- a/rules/web-building.md +++ b/rules/web-building.md @@ -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. diff --git a/skills/a11y/SKILL.md b/skills/a11y/SKILL.md new file mode 100644 index 0000000..760dcb5 --- /dev/null +++ b/skills/a11y/SKILL.md @@ -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 ] [--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" +``` + +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/-a11y-.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-`; on a working branch, stay. Never `finish`. +2. **Baseline**, before any edit: + `python3 -B --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. + CHECK: python3 -B "$HOME/.claude/skills/a11y/scripts/scan.py" '' --assert-absent 'RULE:path,RULE:path' + EXPECT: A11Y-CLEAR + EVIDENCE: pending + ``` + Add one criterion for the project suite when one exists + (`CHECK: && 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: + DIAGNOSIS: + FIX PLAN: + 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 --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 : + MESSAGE : fix(a11y): + ``` + Then `git add ` (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. diff --git a/skills/a11y/references/checks.md b/skills/a11y/references/checks.md new file mode 100644 index 0000000..7fd83c4 --- /dev/null +++ b/skills/a11y/references/checks.md @@ -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 ` | 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. diff --git a/skills/a11y/test-prompts.json b/skills/a11y/test-prompts.json new file mode 100644 index 0000000..ccc5f1d --- /dev/null +++ b/skills/a11y/test-prompts.json @@ -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"} +]