@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/ab-testing/references/pitfalls.md

@@ -0,0 +1,74 @@
+# Pitfalls — why "inconclusive" tests usually mean a broken design
+
+This is the diagnosis layer. When a test "won't go significant" or "flip-flops," it is almost always one
+of the failure modes below, not bad luck.
+
+## Peeking and optional stopping
+
+A fixed-horizon test is designed so that, under the null, you cross p < 0.05 about 5% of the time **when
+you look exactly once, at the planned n**. If you look every day and stop the first time you see p < 0.05,
+you take many independent-ish shots at that 5% door. With enough looks the cumulative chance of crossing
+0.05 under a true null climbs well past 5% — a pure-noise test can be "significant" the majority of the
+time if you peek long enough. The reported p-value is then a lie about a single planned look.
+
+Fixes, in order of preference:
+
+1. **Fixed horizon.** Commit to n/date; read once. Tightest read for declaring a winner.
+2. **Sequential / always-valid inference.** Confidence sequences and anytime-valid CIs (e.g. Netflix's
+   anytime-valid approach) stay valid under continuous monitoring — you may look every day and the
+   guarantee holds. Trade-off: wider intervals, so they are excellent for **stopping a clear loser early**
+   and comparatively weak for **declaring a winner early**. Use them when early stopping has real value,
+   not as a license to peek on a fixed-horizon design.
+
+Never: a fixed-horizon design read repeatedly and stopped at first significance.
+
+## Multiple comparisons
+
+Every metric, every variant, every segment is another hypothesis test. Test 20 independent nulls at
+α = 0.05 and you expect ~1 false positive by chance alone. Two corrections:
+
+- **Bonferroni** — divide α by the number of tests. Controls the chance of *any* false positive
+  (family-wise error). Simple and conservative; right for a small, pre-declared set of decision metrics.
+- **Benjamini-Hochberg (FDR)** — controls the *expected fraction* of false positives among the discoveries.
+  Far more powerful on large exploratory scans. Illustrative example: scanning 20 metrics with true
+  effects, an FDR procedure recovered ~17 while Bonferroni's stricter threshold recovered only ~12.
+
+Rule: Bonferroni for the handful of metrics a decision rests on; Benjamini-Hochberg for the big
+exploratory sweep where you can tolerate a known false-discovery rate.
+
+## Sample ratio mismatch (SRM)
+
+The observed split materially diverges from the intended ratio (chi-square p < 0.001). This is not a
+statistical nuance — it is a signal the experiment is mechanically broken: a bot filter dropping one arm,
+a redirect, differential caching, a bucketing-hash bug, or logging that fires on one variant only.
+Consequence: the arms are no longer comparable, so the treatment effect is confounded. Do not adjust,
+reweight, or "note it as a caveat." Find the cause, fix instrumentation, and rerun. The SRM chi-square
+snippet is in `sample-size-and-cuped.md`.
+
+## Underpowered ≠ "no effect"
+
+A non-significant result with a small sample means you could not have detected even a meaningful effect —
+absence of evidence, not evidence of absence. Before concluding "no difference," check whether the test
+reached its planned n and report the CI: "the effect is somewhere in [−0.8pp, +1.2pp]" is honest;
+"no effect" is not.
+
+## Novelty and primacy effects
+
+A shiny new variant can spike because regulars click it out of curiosity (novelty) — or dip because they
+are disoriented by a changed UI (primacy). Both fade. If the effect is concentrated in the first days and
+decays, you are measuring reaction-to-change, not the steady-state effect. Run long enough for the curve
+to flatten, and inspect new-user vs returning-user segments separately.
+
+## Simpson's paradox across segments
+
+An aggregate lift can reverse inside every segment (or vice versa) when segment mix differs between arms —
+often itself a symptom of SRM or a non-random assignment. If the overall result and the per-segment
+results disagree in direction, distrust the aggregate and find what is unbalanced between the arms before
+believing either number.
+
+## HARKing — hypothesizing after results are known
+
+Slicing the data until something is significant, then writing the hypothesis to match, is a fishing
+expedition wearing a lab coat. Any "finding" discovered this way must be treated as a hypothesis for a
+*fresh* experiment, never as a confirmed result. Pre-register the hypothesis and primary metric before
+launch so the analysis you run is the analysis you committed to.

package/skills/shared/ab-testing/references/sample-size-and-cuped.md

@@ -0,0 +1,128 @@
+# Sample size, duration, CUPED, and SRM — runnable snippets
+
+Versions assumed: **statsmodels 0.14.6** (stable), **scipy 1.17.1**. Install: `pip install "statsmodels>=0.14" "scipy>=1.15"`.
+
+All snippets are self-contained and print the numbers they compute.
+
+## 1. Sample size for a conversion rate (proportion)
+
+`proportion_effectsize` applies the arcsine (Cohen's h) transform so the normal-approximation power
+calculation is valid for proportions.
+
+```python
+import math
+from statsmodels.stats.power import NormalIndPower
+from statsmodels.stats.proportion import proportion_effectsize
+
+baseline = 0.12          # control conversion
+mde_abs  = 0.015         # minimum detectable effect, absolute (1.5 percentage points)
+alpha    = 0.05          # two-sided
+power    = 0.80
+
+variant = baseline + mde_abs
+h = proportion_effectsize(baseline, variant)
+n_per_arm = NormalIndPower().solve_power(effect_size=h, alpha=alpha, power=power, ratio=1.0)
+n_per_arm = math.ceil(n_per_arm)
+print(f"n per arm = {n_per_arm}, total = {2 * n_per_arm}")
+```
+
+Worked numbers for the example above: h ≈ 0.0449, **n per arm ≈ 7,773**, total ≈ 15,546.
+
+## 2. Sample size for a continuous metric
+
+Effect size is Cohen's d = (mean difference you care about) / (pooled standard deviation). Estimate the
+std from historical data on the same metric.
+
+```python
+import math
+from statsmodels.stats.power import TTestIndPower
+
+mde_units  = 0.50        # e.g. detect a $0.50 lift in revenue per user
+pooled_std = 4.0         # historical std of revenue per user
+d = mde_units / pooled_std
+n_per_arm = math.ceil(TTestIndPower().solve_power(effect_size=d, alpha=0.05, power=0.80, ratio=1.0))
+print(f"n per arm = {n_per_arm}")
+```
+
+## 3. n → calendar duration
+
+```python
+import math
+
+n_per_arm = 7773
+num_arms  = 2
+daily_eligible = 1800            # users entering the experiment per day
+
+days = math.ceil((n_per_arm * num_arms) / daily_eligible)
+print(f"raw days = {days}; run full weeks ->", math.ceil(days / 7) * 7)
+```
+
+Round **up to whole weeks**. A test that mathematically needs 9 days should run 14: weekday and weekend
+users are different populations, and stopping mid-week oversamples one slice.
+
+## 4. Analyze a finished proportion test
+
+```python
+import numpy as np
+from statsmodels.stats.proportion import proportions_ztest, proportion_confint
+
+conv  = np.array([540, 590])     # successes: control, variant
+nobs  = np.array([10000, 10000]) # exposures per arm
+
+stat, pval = proportions_ztest(conv, nobs)
+p_c, p_v = conv / nobs
+lift_abs = p_v - p_c
+lift_rel = lift_abs / p_c
+# CI on the difference of two proportions (Wald)
+se = ((p_c*(1-p_c)/nobs[0]) + (p_v*(1-p_v)/nobs[1])) ** 0.5
+lo, hi = lift_abs - 1.96*se, lift_abs + 1.96*se
+print(f"control={p_c:.3%} variant={p_v:.3%} abs lift={lift_abs:+.3%} ({lift_rel:+.1%} rel)")
+print(f"p={pval:.4f}  95% CI on abs lift=[{lo:+.3%}, {hi:+.3%}]")
+```
+
+Read it as a triple: lift, CI, p. Compare the CI to your MDE — if the interval includes effects below
+the MDE, you have not shown a *practically* meaningful result even if p < 0.05.
+
+## 5. CUPED — θ via OLS, then test the adjusted metric
+
+```python
+import numpy as np
+import statsmodels.api as sm
+from scipy import stats
+
+# y  = in-experiment metric per user (e.g. spend during the test)
+# x  = SAME metric measured in the pre-experiment window (must be pre-assignment)
+# arm = 0 control, 1 variant
+
+X = sm.add_constant(x)
+theta = sm.OLS(y, X).fit().params[1]          # slope = Cov(y,x)/Var(x)
+y_cuped = y - theta * (x - x.mean())          # variance-reduced metric
+
+t, p = stats.ttest_ind(y_cuped[arm == 1], y_cuped[arm == 0], equal_var=False)
+var_reduction = 1 - y_cuped.var() / y.var()
+print(f"theta={theta:.3f}  variance reduction={var_reduction:.1%}  t={t:.2f} p={p:.4f}")
+```
+
+`var_reduction` is the fraction of variance the covariate explained — that is the power you bought for
+free. Zero or negative means the covariate is useless here (new users, or `x` uncorrelated with `y`):
+drop CUPED, it cannot help and a post-assignment covariate would actively bias the estimate.
+
+## 6. Sample ratio mismatch (SRM) gate
+
+Run this *before* trusting any result. A significant deviation from the intended split means the
+experiment is broken at the assignment/logging layer.
+
+```python
+from scipy import stats
+
+observed = [10000, 9430]          # users actually seen in each arm
+expected_ratio = [0.5, 0.5]       # intended split
+total = sum(observed)
+expected = [total * r for r in expected_ratio]
+
+chi2, p = stats.chisquare(f_obs=observed, f_exp=expected)
+print(f"chi2={chi2:.1f} p={p:.6f}", "-> SRM, do not trust results" if p < 0.001 else "-> split OK")
+```
+
+If `p < 0.001`: stop, find why one arm is short (bot filtering, redirect, caching, a broken bucketing
+hash), fix instrumentation, and rerun. Never reweight your way out of an SRM.

package/skills/shared/ab-testing/scripts/verify.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# verify.sh — ab-testing skill gate. Run from your PROJECT root.
+#
+# What it does (read-only, idempotent, NEVER runs anything destructive):
+#   1. Discovers experiment artifacts produced by this skill:
+#        - Python sizing/analysis scripts whose names hint at experiments
+#          (*sample*size*.py, *ab*test*.py, *experiment*.py, *power*.py, *cuped*.py, *srm*.py)
+#        - experiment-design docs (*experiment*.md, *ab*test*.md, *design*.md)
+#   2. For each Python artifact: checks scipy + statsmodels import, then executes it under
+#      python3 and asserts it prints at least one integer (a sample size / count).  [warn-only]
+#   3. For each design doc: greps for a primary metric, an MDE, and power/alpha.   [warn-only]
+#
+# Exit code: non-zero ONLY when a discovered Python artifact crashes (non-zero exit) under an
+# environment that HAS python3 + scipy + statsmodels. Missing interpreter/libs -> skip, never fail.
+# Missing fields in a doc -> advisory warn. An empty or clean target exits 0 (no false failure).
+# Stock macOS bash 3.2 compatible (no mapfile, no associative arrays).
+
+YELLOW=$'\033[33m'; GREEN=$'\033[32m'; RED=$'\033[31m'; NC=$'\033[0m'
+EXIT=0
+skip() { printf '%s[skip]%s %s\n' "$YELLOW" "$NC" "$*"; }
+note() { printf '%s[warn]%s %s\n' "$YELLOW" "$NC" "$*"; }
+ok()   { printf '%s[ok]%s %s\n'   "$GREEN"  "$NC" "$*"; }
+err()  { printf '%s[fail]%s %s\n' "$RED"    "$NC" "$*"; EXIT=1; }
+
+ROOT="$(pwd)"
+
+# --- discover python sizing/analysis artifacts ---
+PY_FILES=()
+while IFS= read -r -d '' f; do
+  PY_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/.venv/*' -o -path '*/venv/*' -o -path '*/site-packages/*' \) -prune -o \
+    -type f \( -iname '*sample*size*.py' -o -iname '*ab*test*.py' -o -iname '*experiment*.py' \
+               -o -iname '*power*.py' -o -iname '*cuped*.py' -o -iname '*srm*.py' \) -print0 2>/dev/null
+)
+
+# --- discover experiment-design docs ---
+DOC_FILES=()
+while IFS= read -r -d '' f; do
+  DOC_FILES+=("$f")
+done < <(
+  find "$ROOT" \
+    \( -path '*/node_modules/*' -o -path '*/.git/*' -o -path '*/.venv/*' \) -prune -o \
+    -type f \( -iname '*experiment*.md' -o -iname '*ab*test*.md' -o -iname '*design*.md' \) -print0 2>/dev/null
+)
+
+if [ "${#PY_FILES[@]}" -eq 0 ] && [ "${#DOC_FILES[@]}" -eq 0 ]; then
+  skip "no experiment scripts or design docs found under $ROOT — design-only conversation"
+  ok "verify.sh passed (empty target)"
+  exit 0
+fi
+
+# --- python artifacts ---
+if [ "${#PY_FILES[@]}" -gt 0 ]; then
+  if ! command -v python3 >/dev/null 2>&1; then
+    skip "python3 not installed — cannot execute sizing scripts"
+  elif ! python3 -c 'import scipy, statsmodels' >/dev/null 2>&1; then
+    skip "scipy/statsmodels not importable — install with: pip install scipy statsmodels"
+  else
+    for f in "${PY_FILES[@]}"; do
+      out="$(python3 "$f" 2>&1)" || { err "$f: crashed under python3"; printf '%s\n' "$out" | sed 's/^/    /'; continue; }
+      if printf '%s' "$out" | grep -Eq '[0-9]+'; then
+        ok "$f: executed and printed a number"
+      else
+        note "$f: ran but printed no numeric output — a sizing/analysis script should print an n or p-value"
+      fi
+    done
+  fi
+fi
+
+# --- design docs ---
+for f in "${DOC_FILES[@]}"; do
+  miss=""
+  grep -Eiq 'primary[[:space:]]+metric|metric[[:space:]]*:'                  "$f" || miss="$miss primary-metric"
+  grep -Eiq 'mde|minimum[[:space:]]+detectable[[:space:]]+effect'           "$f" || miss="$miss MDE"
+  grep -Eiq 'power|alpha|significance[[:space:]]+level'                      "$f" || miss="$miss power/alpha"
+  if [ -n "$miss" ]; then
+    note "$f: experiment-design doc missing:$miss"
+  else
+    ok "$f: names a primary metric, an MDE, and power/alpha"
+  fi
+done
+
+printf '\n'
+if [ "$EXIT" -eq 0 ]; then ok "verify.sh passed"; else err "verify.sh found failures"; fi
+exit "$EXIT"

package/skills/shared/accessibility/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: accessibility
+description: "Use when making a web UI conform to WCAG 2.2 Level AA — axe-core or Lighthouse a11y violations, keyboard operability, focus management, ARIA roles/names/live regions, contrast, tap-target size. NOT palette or visual intent (that is `design`), NOT test-runner setup (that is `testing-web`), NOT LCP/page-speed (that is `performance`)."
+tags: [wcag, accessibility, a11y, aria, axe-core]
+recommends: [testing-web, e2e-testing, design, react, performance]
+origin: ai-hub
+---
+
+# Accessibility — Ship WCAG 2.2 AA, not vibes
+
+*The bar is conformance to WCAG 2.2 Level AA. "Looks fine to me" is not a measurement. Fix the semantics, scan what a machine can scan, then walk the part it can't.*
+
+## The loop (your 30-second model)
+
+Run these in order. Skipping a step front-loads rework.
+
+1. **Native semantics first.** A real `<button>` ships focus, keyboard, and role for free. Most "a11y bugs" are a `<div>` doing a button's job.
+2. **Automated scan.** axe-core catches roughly **57%** of WCAG issues — missing labels, bad roles, contrast (in a real browser), duplicate ids. Cheap, run it every commit.
+3. **Manual checklist for the rest.** The other **~43%** — keyboard order, focus traps, meaningful alt text, screen-reader flow — no engine can judge. A human (or you, deliberately) must.
+
+**Decision rule: never ship on a green axe run alone.** A clean automated scan means "no machine-detectable failures," not "accessible." Treat it as necessary, never sufficient.
+
+Legal stakes are real: the EU **European Accessibility Act became enforceable 2025-06-28** for many consumer products and services, on top of EN 301 549 / ADA. AA is the line.
+
+## Rule 0 — reach for HTML before ARIA
+
+The first rule of ARIA is: **don't use ARIA.** If a native element gives you the semantics and behavior, use it. Every `role` you add is behavior you now owe by hand — focus, keyboard, state.
+
+```html
+<!-- Bad: zero keyboard, no role, no focus, no Enter/Space -->
+<div class="btn" onclick="save()">Save</div>
+
+<!-- Good: focusable, Enter/Space fire it, announced as "Save, button" -->
+<button type="button" onclick="save()">Save</button>
+```
+
+| You want…              | Use native…                | Not…                          |
+| ---------------------- | -------------------------- | ----------------------------- |
+| A click action         | `<button type="button">`   | `<div role="button" onClick>` |
+| Navigation             | `<a href="…">`             | `<span onClick>` + JS routing |
+| Show/hide section      | `<details><summary>`       | hand-rolled `aria-expanded`   |
+| Form field             | `<input>`/`<select>`       | contenteditable div           |
+| Modal                  | `<dialog>` + `showModal()` | a div with `role="dialog"`    |
+
+Reach for ARIA only when no native element fits (tabs, comboboxes, toasts) — and then copy a vetted pattern (→ `references/aria-patterns.md`).
+
+## Semantics & accessible names
+
+- **One `<h1>` per page.** Headings describe structure; never skip a level (`<h2>` then `<h4>`) to get a font size — that's a CSS job.
+- **Landmark every region:** `<header> <nav> <main> <footer>`. Exactly one `<main>`. Screen-reader users jump by landmark; a wall of `<div>` has no map.
+- **Skip link first in the DOM** so keyboard users escape the nav: `<a href="#main" class="sr-only-focusable">Skip to content</a>`.
+- **Accessible name precedence** (what a screen reader announces), highest wins: `aria-labelledby` → `aria-label` → associated `<label>` / element text → `title`. Don't stack them hoping one sticks; pick one source.
+
+```html
+<!-- Bad: announced as just "button" -->
+<button><svg aria-hidden="true">…</svg></button>
+
+<!-- Good: announced as "Close dialog, button" -->
+<button aria-label="Close dialog"><svg aria-hidden="true">…</svg></button>
+```
+
+A `placeholder` is **not** a label — it vanishes on input and many SRs ignore it. Use a real `<label for>`.
+
+## Keyboard operability
+
+Everything a mouse can do, a keyboard must do.
+
+- **All interactive elements reachable and operable** with Tab + Enter/Space. Native controls give this free; custom ones don't.
+- **Tab order follows the DOM.** Fix order by reordering markup, not by patching `tabindex`.
+- **Never a positive `tabindex`.** Only `0` (in natural order) or `-1` (focusable by script, skipped by Tab). A positive value hijacks the whole page's order and breaks the next dev's mental model.
+- **Visible focus, always** (see next section). If you can't tell where focus is with the mouse unplugged, neither can the user.
+
+**Overlays (dialogs, menus, drawers) need focus management** — three obligations:
+
+1. **Move focus in** when it opens (to the dialog or its first control).
+2. **Trap focus** inside while open — Tab from the last element wraps to the first.
+3. **Escape closes**, and **focus returns to the trigger** that opened it.
+
+Composite widgets (menus, tabs, grids) use **roving tabindex**: one element is `tabindex="0"`, the rest `-1`, arrow keys move the `0`. Full keyboard tables per pattern — modal, disclosure, tabs, combobox, menu, toast → `references/aria-patterns.md`.
+
+## Visible focus & the WCAG 2.2 deltas
+
+```css
+/* Bad: kills the focus ring with nothing in its place */
+:focus { outline: none; }
+
+/* Good: ring only for keyboard users, not mouse clicks */
+:focus-visible { outline: 3px solid; outline-offset: 2px; }
+```
+
+WCAG 2.2 (W3C Recommendation, 2023-10-05) **adds 9 success criteria and removes 4.1.1 Parsing**. The six that matter at **Level AA** — know the numbers:
+
+- **2.4.11 Focus Not Obscured (Minimum)** — a focused element must not be fully hidden behind sticky headers/footers or cookie bars.
+- **2.5.7 Dragging Movements** — anything done by dragging (sliders, reorder, map pan) needs a single-pointer alternative (tap, buttons).
+- **2.5.8 Target Size (Minimum)** — interactive targets are at least **24×24 CSS px**, unless spacing keeps a 24px-radius circle from overlapping a neighbor (the spacing exception). 44×44 is the comfort bar; 24 is the floor.
+- **3.2.6 Consistent Help** — help mechanisms appear in the same relative order across pages.
+- **3.3.7 Redundant Entry** — don't make users re-enter info they already gave in the same process; auto-fill or let them pick it.
+- **3.3.8 Accessible Authentication (Minimum)** — no cognitive-function test to log in (no puzzles, no "transcribe this", no math). Allow paste, password managers, and copy.
+
+## Contrast & color
+
+Measured ratios, AA minimums:
+
+- **4.5:1** for normal text.
+- **3:1** for large text (**≥24px**, or **≥18.66px bold**).
+- **3:1** for UI components and graphical objects you must perceive (1.4.11) — input borders, icon glyphs, chart segments.
+
+**Never encode meaning in color alone** (1.4.1). A red border on an invalid field is invisible to many users — pair it with text and an icon.
+
+```html
+<!-- Bad: only color signals the error -->
+<input class="border-red-500" aria-invalid="true">
+
+<!-- Good: text + icon + programmatic association -->
+<input aria-invalid="true" aria-describedby="email-err">
+<p id="email-err">⚠ Enter a valid email address.</p>
+```
+
+Note: **jsdom can't compute contrast** (no real layout/paint), so jest-axe disables the rule. Verify contrast in a real browser (Playwright / Lighthouse) or by hand.
+
+## ARIA done right
+
+Mental model: **Name, Role, Value.** Every custom control needs an accessible *name*, the right *role*, and current *state/value* — and you must keep state in sync.
+
+- **State attributes:** `aria-expanded` on a disclosure trigger, `aria-controls` pointing at what it toggles, `aria-selected` / `aria-current` for the active item. Toggle them in the same handler that changes the visual state.
+- **Live regions** announce async changes without moving focus:
+  - `aria-live="polite"` — wait for a pause (status, "Saved", search-result counts). Default choice.
+  - `aria-live="assertive"` — interrupt now (form submit error, session-expiry). Use sparingly.
+- **Hiding — pick the right one:**
+
+| Technique          | Visual | Screen reader | Use for                                   |
+| ------------------ | ------ | ------------- | ----------------------------------------- |
+| `display:none`     | gone   | gone          | truly removed content                     |
+| `aria-hidden=true` | shown  | hidden        | decorative visuals — **never on a focusable element** |
+| `.sr-only` class   | hidden | read          | labels/skip links for SR users only       |
+
+```html
+<!-- Bad: focusable AND hidden from SR = a keyboard trap nobody can hear -->
+<button aria-hidden="true">Menu</button>
+
+<!-- Good: decorative icon hidden, the button keeps its name -->
+<button aria-label="Menu"><svg aria-hidden="true">…</svg></button>
+```
+
+## Automate it (versioned, 2026-06-02)
+
+Three layers — each catches what the cheaper one can't.
+
+**Lint (static, JSX only) — `eslint-plugin-jsx-a11y` 6.10.2.** Catches missing `alt`, label-less inputs, positive `tabindex`, invalid roles, at edit time.
+
+```jsonc
+// .eslintrc — extends, then runs in your existing lint step
+{ "extends": ["plugin:jsx-a11y/recommended"] }
+```
+
+**Unit (fast, no browser) — `jest-axe` 10.0.0.** Asserts no axe violations on rendered output. Remember: **contrast is off in jsdom.**
+
+```js
+import { axe, toHaveNoViolations } from "jest-axe";
+expect.extend(toHaveNoViolations);
+
+test("no a11y violations", async () => {
+  const { container } = render(<SignupForm />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+**Browser (the real thing, catches contrast) — `@axe-core/playwright` 4.11.3** (on `axe-core` 4.12.0). Scope it to the WCAG 2.2 AA tags:
+
+```js
+import AxeBuilder from "@axe-core/playwright";
+
+const results = await new AxeBuilder({ page })
+  .withTags(["wcag2a", "wcag2aa", "wcag22aa"])
+  .analyze();
+expect(results.violations).toEqual([]);
+```
+
+**Lighthouse a11y score** is a smoke signal for a quick pulse, not proof — it runs a subset of axe and gives a number, not a pass.
+
+`scripts/verify.sh` ties this together: it detects whatever tooling the project has and runs it, failing only on serious/critical violations (read-only, skips cleanly when no tooling is present).
+
+## Manual checklist (the ~43% a machine can't see)
+
+Do these by hand before you call it done:
+
+- [ ] **Unplug the mouse.** Tab through the entire flow — every control reachable, order logical, focus always visible, no trap, Escape closes overlays.
+- [ ] **One screen-reader spot check** — VoiceOver (macOS, ⌘F5) or NVDA (Windows). Do names, roles, and state read sensibly? Are errors announced?
+- [ ] **Zoom to 200%** — no content lost, no horizontal scroll, nothing clipped.
+- [ ] **`prefers-reduced-motion`** honored — no autoplay parallax/animation that ignores it.
+- [ ] **Alt text is meaningful, not decorative-as-content** — informative images describe; decorative images use `alt=""`.
+
+Full AA checklist grouped by POUR, with the per-item auto/manual split and the 6 new 2.2 criteria flagged → `references/wcag22-checklist.md`.
+
+## Anti-patterns
+
+| Anti-pattern                                   | Why it fails                                              | Do instead                                          |
+| ---------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------- |
+| `<div role="button" onClick>`                  | No keyboard, no focus, you owe all behavior by hand      | `<button>`                                          |
+| `outline: none` with no replacement            | Keyboard users lose all focus location (2.4.7)           | `:focus-visible` ring                               |
+| Positive `tabindex` (`tabindex="3"`)           | Hijacks page tab order, breaks for everyone              | DOM order + `tabindex="0"`/`-1`                      |
+| Placeholder as the only label                  | Disappears on input, many SRs skip it                    | real `<label for>`                                  |
+| `aria-label` on a non-interactive `<div>` text | Duplicates or overrides visible text confusingly         | label only interactive/landmark elements            |
+| `aria-hidden="true"` on a focusable element    | Reachable by Tab but silent — a trap                     | remove from tab order too, or don't hide it         |
+| Error shown by red color only                  | Invisible to color-blind / low-vision users (1.4.1)      | color **+** text **+** icon, `aria-describedby`     |
+| Redundant `role="button"` on `<button>`        | Noise; native role is already correct                    | drop the role                                       |
+| Shipping on a green axe run                    | Covers ~57%; keyboard/SR/cognitive untested              | run the manual checklist                            |
+| Autoplaying motion, no reduced-motion guard    | Triggers vestibular disorders (2.3.3)                    | gate behind `prefers-reduced-motion`                |
+
+## Hand off to
+
+- Test harness, render setup, fixtures, CI runner mechanics → `../testing-web/SKILL.md` (this skill supplies the a11y *assertions* that run inside it)
+- Full browser-driven flow orchestration → `../e2e-testing/SKILL.md`
+- Visual intent, color palette, spacing scale → `../design/SKILL.md` (this skill checks the contrast/target-size *outcome*, not the aesthetic)
+- Framework component architecture → `../react/SKILL.md` / `../nextjs/SKILL.md`
+- Page speed / LCP / Core Web Vitals tuning → the **performance** skill (not an a11y concern)

package/skills/shared/accessibility/evals/README.md

@@ -0,0 +1,3 @@
+# Evals — accessibility
+
+These cases are graded by eye, not by an auto-runner. Read `cases.yaml` against the live `SKILL.md` description and decide: every `should_trigger` prompt should clearly select **accessibility** (note that several are deliberately non-obvious — a focus-trap complaint, a tap-target-size question, and a Catalan/Spanish phrasing — so the description's `Triggers:` list has to cover them), while each `should_not_trigger` prompt should route to the named sibling instead (`performance`, `testing-web`, `e2e-testing`, `design`, `secure-coding`) and not pull this skill in. For the `capability` case, prompt the agent with the scenario and read its output for each `must_include` point — it passes only if the rewrite replaces the div with a native `<button>`, gives the control an accessible name, makes it keyboard-operable with a visible focus ring, flags that contrast needs a real browser, wires in an automated check (jest-axe or @axe-core/playwright with the `wcag22aa` tag), and explicitly says automation only covers ~57% while naming a manual check. There is no scoring script; this is a judgement pass over the skill's text and the agent's response.

package/skills/shared/accessibility/evals/cases.yaml

@@ -0,0 +1,47 @@
+skill: accessibility
+
+should_trigger:
+  - prompt: "Make this signup form accessible — WCAG 2.2 AA."
+    why: Direct conformance ask against the exact standard this skill owns.
+  - prompt: "axe-core reports color-contrast and button-name violations, fix them."
+    why: Tool-output trigger; named axe rules are this skill's home turf.
+  - prompt: "The modal doesn't trap focus and Escape doesn't close it."
+    why: Non-obvious phrasing — focus management for overlays, no a11y keyword in sight.
+  - prompt: "Tab order jumps around and the icon-only buttons have no label for screen readers."
+    why: Keyboard order plus accessible-name problem; core operable/perceivable work.
+  - prompt: "El lector de pantalla no lee los errores del formulario, fes-ho accessible."
+    why: Spanish/Catalan trigger — live region for errors plus general conformance ask.
+  - prompt: "Our tap targets are smaller than 24px — does WCAG 2.2 require bigger ones?"
+    why: Non-obvious specificity on SC 2.5.8 Target Size (Minimum), a 2.2 delta.
+  - prompt: "Lighthouse accessibility score is 62, get it into the green."
+    why: Low a11y score is a direct entry point even though Lighthouse is multi-purpose.
+
+should_not_trigger:
+  - prompt: "The page LCP is 4 seconds, make it load faster."
+    route_to: performance
+    why: Page-speed / Core Web Vitals tuning, not WCAG conformance.
+  - prompt: "Set up the Jest + React Testing Library harness for this repo."
+    route_to: testing-web
+    why: Test runner / render setup mechanics; this skill only supplies the a11y assertions that run inside it.
+  - prompt: "Write Playwright E2E tests for the checkout flow."
+    route_to: e2e-testing
+    why: Full browser-driven flow orchestration, not a WCAG audit.
+  - prompt: "Pick the brand colors and spacing scale for the design system."
+    route_to: design
+    why: Visual intent and design tokens; this skill checks the contrast/target-size outcome, not the aesthetic.
+  - prompt: "Sanitize this user input to prevent XSS."
+    route_to: secure-coding
+    why: Security hardening, unrelated to accessibility conformance.
+
+capability:
+  - scenario: >
+      Given a React component where an icon-only toggle is a <div onClick> inside a card,
+      with no labels, a custom brand color for the glyph, and no keyboard handler — produce
+      an accessible rewrite plus a way to verify it.
+    must_include:
+      - Replaces the div with a native <button> (Rule 0 — native HTML before ARIA).
+      - Adds an accessible name (aria-label or visually-hidden text) so the icon-only control is announced.
+      - Ensures keyboard operability and visible focus (:focus-visible rather than outline:none).
+      - Flags that contrast must be checked in a real browser because jsdom/jest-axe can't compute it.
+      - Adds an automated check (jest-axe, or @axe-core/playwright scoped to the wcag22aa tag).
+      - States automation catches only ~57% of issues and names at least one manual check (keyboard pass or screen-reader spot check).