@a11y-lens/cli 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duchan Jo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,27 @@
+a11y-lens
+Copyright (c) 2026 Duchan Jo
+
+The rule set in rules/ is an original distillation written for AI-agent
+consumption. It draws on the following prior work for rule coverage and
+accepted accessibility practice:
+
+1. eslint-plugin-jsx-a11y
+   https://github.com/jsx-eslint/eslint-plugin-jsx-a11y
+   License: MIT. Rule intents referenced for the "static baseline" sections.
+
+2. axe-core (Deque Systems, Inc.)
+   https://github.com/dequelabs/axe-core
+   License: MPL-2.0. Rule descriptions referenced for rule coverage mapping.
+   No axe-core source code is included in this package.
+
+3. W3C WAI-ARIA Authoring Practices Guide (APG)
+   https://www.w3.org/WAI/ARIA/apg/
+   License: W3C Document License / W3C Software and Document Notice.
+   Widget interaction patterns (combobox, dialog, tabs, menu, listbox)
+   summarized in rules/04-aria-widgets.md and rules/05-keyboard-interaction.md.
+
+4. WCAG 2.2 (W3C Recommendation)
+   https://www.w3.org/TR/WCAG22/
+   Success criteria referenced by ID throughout the rule set.
+
+This package contains no source code copied from the above projects.

package/README.md

@@ -0,0 +1,100 @@
+# a11y-lens
+
+> **Package** [`@a11y-lens/cli`](https://www.npmjs.com/package/@a11y-lens/cli) · **CLI** `a11y-lens` · **Skill** `npx skills add jo-duchan/a11y-lens`
+
+**AI-powered semantic accessibility linter.** Reviews what static linters can't see — using the AI coding agent you already have (Claude Code, Codex, or Cursor).
+
+Static linters check **syntax**: *does this `img` have an `alt`?*
+a11y-lens checks **semantics**: *does this `alt` actually describe the image? Is this custom dropdown's keyboard interaction complete per the WAI-ARIA combobox pattern? Does the modal return focus to its trigger?*
+
+```
+$ git commit -m "add plan selector"
+a11y-lens: reviewing 1 file(s) with claude…
+
+src/PlanSelect.jsx
+  ✖ error:23  [aria-widgets] Custom dropdown is a div with onClick only — no combobox
+     role, no aria-expanded, no listbox/option semantics. AT users get a plain text node.
+     fix: use role="combobox" + aria-expanded + role="listbox"/"option", or a native <select>
+  ✖ error:23  [keyboard-interaction] Dropdown cannot be operated by keyboard: no ArrowDown/
+     ArrowUp/Enter/Escape handling per the APG combobox pattern.
+     fix: add onKeyDown implementing the APG combobox key set
+
+a11y-lens: 2 error(s), 0 warning(s) (reviewed by claude)
+husky - pre-commit hook exited with code 1
+```
+
+## How it works
+
+1. Collects the **staged** UI files (`.jsx`, `.tsx`, `.html`, `.vue`, `.svelte`, …) and their diffs.
+2. Sends them — together with a distilled rule set (`skills/a11y-lens/references/*.md`, drawn from WAI-ARIA APG, WCAG 2.2, eslint-plugin-jsx-a11y and axe-core coverage) — to a headless agent CLI: `claude -p`, `codex exec`, or `cursor-agent -p`, whichever is installed.
+3. Parses the structured findings and gates the commit on `error` severity. Warnings report but never block (unless `--strict`).
+
+**Infrastructure never blocks a commit.** No agent CLI, no network, agent crash → a11y-lens warns and exits 0. Only real accessibility findings gate.
+
+## Install
+
+a11y-lens has two layers — install either or both:
+
+**Write time (agent skill).** Teaches your coding agent the rules so UI code is accessible *before* the hook ever runs. [The skills CLI](https://skills.sh) installs it for Claude Code, Codex, Cursor, and 60+ other agents:
+
+```bash
+npx skills add jo-duchan/a11y-lens
+```
+
+**Commit time (git hook gate):**
+
+```bash
+npm install -D @a11y-lens/cli   # or pnpm add -D / yarn add -D
+npx a11y-lens init
+```
+
+`init` installs the pre-commit hook for you — it detects lefthook (`lefthook.yml`), husky (`.husky/`), or plain `.git/hooks`, picks your package manager's runner (`pnpm exec` / `yarn` / `bunx` / `npx`), and adds the check idempotently. It also injects a rules reference into your `AGENTS.md` (a lightweight fallback for agents without skills support). Use `--no-hook` to skip hook installation.
+
+Example (lefthook):
+
+```yaml
+pre-commit:
+  jobs:
+    - name: a11y-lens
+      run: npx a11y-lens check --staged
+```
+
+## Usage
+
+```bash
+a11y-lens check --staged           # what the git hook runs
+a11y-lens check src/Modal.tsx      # review specific files
+a11y-lens check --staged --strict  # warnings also fail
+a11y-lens check --staged --agent codex
+a11y-lens rules                    # list rule categories
+```
+
+Escape hatches: `A11Y_LENS_SKIP=1 git commit …` or `git commit --no-verify`.
+
+## Rule set
+
+One markdown file per category in `skills/a11y-lens/references/`, consumed by both the skill and the CLI. Each separates the **static baseline** (what eslint/axe already catch — not re-reported) from the **semantic checks** this tool exists for.
+
+| Category | Semantic checks (examples) |
+|---|---|
+| `01-landmarks-headings` | outline describes the document, not the visual design; one `h1`; labelled landmarks |
+| `02-images-alt` | `alt` describes function in context; decorative silenced, informative never; icon-only controls named by action |
+| `03-forms-labels` | placeholder ≠ label; errors tied via `aria-describedby`; accessible name matches visible label |
+| `04-aria-widgets` | claimed APG patterns must be **complete** — half a combobox is worse than none; state in ARIA, not just CSS |
+| `05-keyboard-interaction` | full APG key sets; no hover-only affordances; no keyboard traps |
+| `06-focus-management` | overlays move focus in and return it; async results announced via live regions; SPA route changes handled |
+
+Rules are plain markdown — tune them for your project by editing the files, no code changes needed.
+
+## Why commit-time AI review is cheap now
+
+In AI-native workflows the entity blocked at pre-commit is usually **an agent, not a human**. A 10–30 second semantic review is a fine price when the committer can read the findings, fix them, and retry without getting annoyed.
+
+## Requirements
+
+- Node ≥ 18, zero runtime dependencies
+- One of: [Claude Code](https://claude.com/claude-code) (`claude`), [Codex CLI](https://github.com/openai/codex) (`codex`), [Cursor CLI](https://cursor.com/cli) (`cursor-agent`), logged in
+
+## License
+
+MIT © Duchan Jo — see [NOTICE](./NOTICE) for rule-set attributions (eslint-plugin-jsx-a11y, axe-core, W3C WAI-ARIA APG, WCAG 2.2).

package/bin/a11y-lens.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { collectStagedUIFiles, collectPathArgs } from '../src/staged.mjs';
+import { installHook, detectRunner } from '../src/hooks.mjs';
+import { detectAgent, runAgent } from '../src/agent.mjs';
+import { buildPrompt } from '../src/prompt.mjs';
+import { parseFindings, printReport, exitCodeFor } from '../src/report.mjs';
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+const HELP = `a11y-lens — AI-powered semantic accessibility linter
+
+Usage:
+  a11y-lens check --staged            review staged UI files (for git hooks)
+  a11y-lens check <files...>          review specific files
+  a11y-lens init                      install the pre-commit hook (lefthook/husky/git hooks,
+                                      auto-detected) + inject rules reference into ./AGENTS.md
+  a11y-lens rules                     list rule categories
+
+Options for check:
+  --agent <claude|codex|cursor>       force a specific agent CLI (default: auto-detect)
+  --strict                            exit non-zero on warnings too (default: errors only)
+
+Options for init:
+  --no-hook                           skip hook installation (AGENTS.md only)
+
+Environment:
+  A11Y_LENS_AGENT                     same as --agent
+  A11Y_LENS_MODEL                     model override passed to claude (optional)
+  A11Y_LENS_SKIP=1                    skip the check entirely (escape hatch)
+
+Infrastructure failures (no agent CLI, no network, agent error) never block:
+a11y-lens warns and exits 0. Only accessibility findings gate.`;
+
+function parseArgs(argv) {
+  const args = { _: [], flags: {} };
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--staged' || token === '--strict' || token === '--no-hook') {
+      args.flags[token.slice(2)] = true;
+    }
+    else if (token === '--agent') args.flags.agent = argv[++i];
+    else if (token === '--help' || token === '-h') args.flags.help = true;
+    else args._.push(token);
+  }
+  return args;
+}
+
+function softFail(message) {
+  console.warn(`a11y-lens: ${message} — skipping check (commits are never blocked by infrastructure).`);
+  process.exit(0);
+}
+
+function commandCheck(args) {
+  if (process.env.A11Y_LENS_SKIP === '1') softFail('A11Y_LENS_SKIP=1');
+
+  const { files, error } = args.flags.staged
+    ? collectStagedUIFiles()
+    : collectPathArgs(args._);
+  if (error) softFail(error);
+
+  const reviewable = files.filter((f) => !f.skipped);
+  for (const f of files.filter((f) => f.skipped)) {
+    console.warn(`a11y-lens: skipping ${f.path} (${f.skipped})`);
+  }
+  if (reviewable.length === 0) {
+    if (args.flags.staged) console.log('a11y-lens: no staged UI files, nothing to review.');
+    else console.log('a11y-lens: no reviewable files given. Try: a11y-lens check src/Component.tsx');
+    process.exit(0);
+  }
+
+  const detection = detectAgent(args.flags.agent);
+  if (detection.error) softFail(detection.error);
+
+  const { prompt, dropped } = buildPrompt(reviewable);
+  for (const path of dropped) {
+    console.warn(`a11y-lens: dropped ${path} (prompt size budget exceeded)`);
+  }
+
+  console.log(
+    `a11y-lens: reviewing ${reviewable.length - dropped.length} file(s) with ${detection.name}…`,
+  );
+  const result = runAgent(detection.agent, prompt);
+  if (!result.ok) softFail(`agent failed: ${result.error}`);
+
+  const parsed = parseFindings(result.output);
+  if (parsed.error) softFail(parsed.error);
+
+  printReport(parsed.findings, { agentName: detection.name });
+  process.exit(exitCodeFor(parsed.findings, { strict: args.flags.strict }));
+}
+
+function commandInit(args) {
+  // 1. Pre-commit hook (lefthook / husky / plain git hooks, auto-detected)
+  if (!args.flags['no-hook']) {
+    const result = installHook(process.cwd());
+    console.log(`a11y-lens: [${result.system}] ${result.message}`);
+  } else {
+    console.log(`a11y-lens: hook skipped (--no-hook). Manual command: ${detectRunner(process.cwd())} a11y-lens check --staged`);
+  }
+
+  // 2. Rules reference for interactive agents
+  const snippet = readFileSync(join(PACKAGE_ROOT, 'templates', 'agents-snippet.md'), 'utf8').trimEnd();
+  const target = join(process.cwd(), 'AGENTS.md');
+  const begin = '<!-- a11y-lens:begin -->';
+  const end = '<!-- a11y-lens:end -->';
+
+  if (existsSync(target)) {
+    const current = readFileSync(target, 'utf8');
+    const pattern = new RegExp(`${begin}[\\s\\S]*?${end}`);
+    const updated = pattern.test(current)
+      ? current.replace(pattern, snippet)
+      : `${current.trimEnd()}\n\n${snippet}\n`;
+    writeFileSync(target, updated);
+    console.log(`a11y-lens: ${pattern.test(current) ? 'updated' : 'appended'} rules section in AGENTS.md`);
+  } else {
+    writeFileSync(target, `${snippet}\n`);
+    console.log('a11y-lens: created AGENTS.md with rules section');
+  }
+
+  console.log(`
+Richer write-time guidance for skills-capable agents: npx skills add jo-duchan/a11y-lens
+Escape hatches: A11Y_LENS_SKIP=1 git commit …  |  git commit --no-verify`);
+}
+
+const args = parseArgs(process.argv.slice(2));
+const command = args._[0];
+args._ = args._.slice(1);
+
+if (args.flags.help || !command) {
+  console.log(HELP);
+  process.exit(0);
+}
+
+switch (command) {
+  case 'check':
+    commandCheck(args);
+    break;
+  case 'init':
+    commandInit(args);
+    break;
+  case 'rules': {
+    const rulesDir = join(PACKAGE_ROOT, 'skills', 'a11y-lens', 'references');
+    for (const name of readdirSync(rulesDir).filter((n) => n.endsWith('.md')).sort()) {
+      console.log(`${name}  →  ${join(rulesDir, name)}`);
+    }
+    break;
+  }
+  default:
+    console.error(`a11y-lens: unknown command "${command}"\n`);
+    console.log(HELP);
+    process.exit(2);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@a11y-lens/cli",
+  "version": "0.4.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "AI-powered semantic accessibility linter — reviews what static linters can't see. Runs on Claude Code, Codex, or Cursor at commit time.",
+  "type": "module",
+  "bin": {
+    "a11y-lens": "bin/a11y-lens.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "templates",
+    "README.md",
+    "NOTICE",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "accessibility",
+    "a11y",
+    "lint",
+    "wai-aria",
+    "wcag",
+    "ai",
+    "agent",
+    "pre-commit",
+    "semantic-review"
+  ],
+  "author": "Duchan Jo <jo_duchan@icloud.com> (https://github.com/jo-duchan)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jo-duchan/a11y-lens.git"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/skills/a11y-lens/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: a11y-lens
+description: Semantic accessibility rules for writing or reviewing UI code — components, forms, modals, dropdowns, images, interactive elements in JSX/TSX/HTML/Vue/Svelte. Use when implementing any user-facing markup, when reviewing UI changes, or when the user asks about accessibility, WCAG, ARIA, keyboard support, or screen readers. Covers what static linters (eslint-plugin-jsx-a11y, axe-core) structurally cannot check.
+---
+
+# a11y-lens
+
+You are applying the a11y-lens rule set: semantic accessibility review **above** the static-linter layer. Static linters check syntax ("does this `img` have an `alt`?"); you check meaning ("does this `alt` actually describe the image in context?", "is this custom dropdown's keyboard interaction complete per the WAI-ARIA APG combobox pattern?").
+
+## How to use the rules
+
+Before writing or reviewing UI code, read the reference file for each category the code touches. Do not guess the rules from the summaries below — the reference files carry severity guidance and good/bad examples.
+
+| When the code involves… | Read |
+|---|---|
+| Page/view structure, sections, headings | [references/01-landmarks-headings.md](references/01-landmarks-headings.md) |
+| Images, icons, icon-only buttons, SVG | [references/02-images-alt.md](references/02-images-alt.md) |
+| Inputs, forms, validation, error messages | [references/03-forms-labels.md](references/03-forms-labels.md) |
+| Custom widgets: dropdowns, modals, tabs, menus, toggles | [references/04-aria-widgets.md](references/04-aria-widgets.md) |
+| Click/hover handlers, shortcuts, drag, carousels | [references/05-keyboard-interaction.md](references/05-keyboard-interaction.md) |
+| Overlays, route changes, async results, toasts, loading | [references/06-focus-management.md](references/06-focus-management.md) |
+
+Core stances that apply everywhere:
+
+1. **Prefer native elements** (`button`, `select`, `details`, `dialog`) — they ship the complete pattern for free. A custom widget must implement the **whole** APG pattern; a partial pattern is worse than none.
+2. **Placeholder is not a label. Hover is not a keyboard path. CSS state is not ARIA state.**
+3. Severity discipline: `error` = clear violations (keyboard-dead interactive elements, unnamed icon-only controls, incomplete claimed ARIA patterns, unmanaged overlay focus, silenced informative images). Judgment calls are `warning`.
+
+## Commit-time gate (CLI)
+
+This skill has a companion CLI that runs the same rules through a headless agent at commit time:
+
+```bash
+npm install -D @a11y-lens/cli
+npx a11y-lens init                 # AGENTS.md reference + hook setup instructions
+npx a11y-lens check --staged       # what the pre-commit hook runs
+npx a11y-lens check src/Modal.tsx  # review specific files
+```
+
+If the project has the hook installed, self-check against the rules before finishing UI work — it is cheaper than failing the gate. Repository: https://github.com/jo-duchan/a11y-lens

package/skills/a11y-lens/references/01-landmarks-headings.md

@@ -0,0 +1,40 @@
+---
+id: landmarks-headings
+sources: [WCAG 1.3.1, WCAG 2.4.1, WCAG 2.4.6, axe-core region/heading rules]
+---
+
+# Landmarks & heading hierarchy
+
+## Static baseline (already caught by eslint/axe — do not re-report unless visible in the diff)
+
+- Page content not contained in landmarks (`header`, `nav`, `main`, `footer`, `aside`, `section[aria-label]`)
+- More than one `main`, duplicated `banner`/`contentinfo`
+- Empty headings
+
+## Semantic checks (what you review)
+
+1. **Heading hierarchy must describe the document outline, not the visual design.**
+   - Exactly one `h1` per page/view; levels must not skip downward (h1 → h3 with no h2 is an `error`).
+   - A heading chosen for its font size rather than its outline position is a violation — check whether the level makes sense relative to surrounding headings, not whether it "looks right".
+   - In SPAs, per-route views count as pages: a route component rendering only `h3`s is an `error` even if some layout file has an `h1` elsewhere — flag it as `warning` and say why (cannot see full composition).
+2. **`section` needs an accessible name to be a landmark.** A bare `section` used as a styling wrapper should be a `div`; a `section` that truly groups content needs `aria-labelledby` pointing at its heading (`warning`).
+3. **Landmark labels must be distinguishable.** Two `nav` elements require distinct `aria-label`s ("primary", "breadcrumb") — identical or missing labels on repeated landmarks is a `warning`.
+4. **Visual titles that are not headings.** A styled `div`/`p` acting as an obvious section title (short text, followed by related content, styled prominently) should be a heading (`warning`).
+
+## Examples
+
+Bad — outline skips and decorative section:
+
+```jsx
+<section>            {/* no accessible name → not a landmark, just noise */}
+  <h4>요금 안내</h4>  {/* previous heading was h1 → skipped to h4 */}
+</section>
+```
+
+Good:
+
+```jsx
+<section aria-labelledby="pricing-title">
+  <h2 id="pricing-title">요금 안내</h2>
+</section>
+```

package/skills/a11y-lens/references/02-images-alt.md

@@ -0,0 +1,39 @@
+---
+id: images-alt
+sources: [WCAG 1.1.1, eslint-plugin-jsx-a11y alt-text/img-redundant-alt, axe-core image-alt]
+---
+
+# Images & text alternatives
+
+## Static baseline
+
+- `img` missing `alt` attribute entirely
+- `alt` containing "image", "picture", "photo", "이미지", "사진" (redundant)
+- `input[type=image]`, `area`, `object` without text alternative
+
+## Semantic checks (what you review)
+
+1. **Does the `alt` actually describe the image's function or content in context?**
+   - `alt="banner"`, `alt="icon"`, `alt="img_03"`, filename-derived alt → `error`. These pass static linters and fail humans.
+   - An image inside a link: alt must describe the **destination/action**, not the picture ("에이닷 전화 다운로드", not "스마트폰 그림") — mismatch is `warning`.
+2. **Decorative images must be explicitly silenced**, not given filler alt. Purely decorative → `alt=""` (and `aria-hidden="true"` for inline SVG). Filler like `alt="장식"` is `warning`.
+3. **Informative images must not be silenced.** `alt=""` on an image that plainly carries information (chart, badge with a number, screenshot referenced by the copy) is an `error`.
+4. **Icon-only interactive elements.** A button/link whose only content is an icon (SVG, icon font, emoji) needs an accessible name (`aria-label` or visually-hidden text). Check the name describes the **action** ("닫기", not "X 아이콘"). Missing → `error`; vague → `warning`.
+5. **Text baked into images** (event banners with dates/prices in pixels) — the alt or adjacent text must carry the same information; otherwise `warning`.
+6. **CSS background-images conveying meaning** have no alt channel at all — if the diff shows meaningful content moved into a background-image, flag `warning` with the visually-hidden-text remedy.
+
+## Examples
+
+Bad — passes static linting, fails semantically:
+
+```jsx
+<a href="/download"><img src="/hero-phone.png" alt="phone image" /></a>
+<button><CloseIcon /></button>
+```
+
+Good:
+
+```jsx
+<a href="/download"><img src="/hero-phone.png" alt="에이닷 전화 앱 다운로드" /></a>
+<button aria-label="닫기"><CloseIcon aria-hidden="true" /></button>
+```

package/skills/a11y-lens/references/03-forms-labels.md

@@ -0,0 +1,38 @@
+---
+id: forms-labels
+sources: [WCAG 1.3.1, WCAG 3.3.1, WCAG 3.3.2, WCAG 4.1.2, eslint-plugin-jsx-a11y label-has-associated-control, axe-core label/select-name]
+---
+
+# Forms, labels & error states
+
+## Static baseline
+
+- Form control without any programmatic label (`label[for]`, wrapping `label`, `aria-label`, `aria-labelledby`)
+- `label` not associated with a control
+
+## Semantic checks (what you review)
+
+1. **Placeholder is not a label.** A control whose only "label" is `placeholder` is an `error` — it disappears on input and has no reliable AT exposure. Check the diff for inputs that visually rely on placeholder alone.
+2. **The accessible name must match the visible label.** If a visible text label says "휴대폰 번호" but `aria-label="phone"`, voice-control users cannot target it (WCAG 2.5.3 Label in Name) → `warning`.
+3. **Errors must be programmatically tied to their field.** Rendering an error message as a sibling `<p className="error">` with no `aria-describedby` on the input and no `aria-invalid` is `error` when the diff introduces validation UI. A live-updating error summary should use `role="alert"` or `aria-live="assertive"` — but only one, not both stacked.
+4. **Required and disabled semantics.** Visually-marked required fields (asterisk, "필수") need `required` or `aria-required="true"` (`warning`). A visually "disabled" button that is actually a styled `div` or keeps focus without `disabled`/`aria-disabled` misleads AT → `warning`.
+5. **Grouped controls need a group name.** Radio sets / related checkboxes introduced without `fieldset`+`legend` (or `role="radiogroup"` + `aria-labelledby`) → `warning`: each option is announced with no question attached.
+6. **Autocomplete on identity fields.** Login/checkout fields for name, email, tel, address should carry `autocomplete` tokens (WCAG 1.3.5) → `warning` when the diff adds such fields bare.
+
+## Examples
+
+Bad:
+
+```jsx
+<input placeholder="이메일" value={email} onChange={...} />
+{error && <p className="error">이메일 형식이 아닙니다</p>}
+```
+
+Good:
+
+```jsx
+<label htmlFor="email">이메일</label>
+<input id="email" type="email" autoComplete="email" value={email}
+       aria-invalid={!!error} aria-describedby={error ? "email-error" : undefined} />
+{error && <p id="email-error" role="alert">이메일 형식이 아닙니다</p>}
+```

package/skills/a11y-lens/references/04-aria-widgets.md

@@ -0,0 +1,51 @@
+---
+id: aria-widgets
+sources: [W3C WAI-ARIA APG patterns, WCAG 4.1.2, eslint-plugin-jsx-a11y role-* rules, axe-core aria-* rules]
+---
+
+# ARIA widget patterns
+
+> First rule of ARIA: prefer the native element (`button`, `select`, `details`, `dialog`) — it ships the whole pattern for free. Custom widgets must implement the **complete** APG pattern; a partial pattern is worse than none because it promises behavior that isn't there.
+
+## Static baseline
+
+- Invalid `role` values, `aria-*` attributes not permitted for the role
+- `role` requiring missing `aria-*` props (e.g. `role="checkbox"` without `aria-checked`)
+- Interactive `div`/`span` with `onClick` and no role/tabindex
+
+## Semantic checks (what you review)
+
+For any custom widget in the diff, identify which APG pattern it is imitating, then verify the pattern is **complete** — states, properties, and relationships all present. Missing pieces of a claimed pattern are `error`.
+
+1. **Combobox / select-like** (custom dropdown, autocomplete):
+   - Trigger: `role="combobox"`, `aria-expanded` toggling, `aria-controls` → listbox id, `aria-haspopup="listbox"` where appropriate.
+   - Popup: `role="listbox"`, options `role="option"` with `aria-selected`; active option tracked via `aria-activedescendant` on the combobox (or roving focus — one or the other, not both).
+   - A styled `div` dropdown with only `onClick` handlers and none of the above is the classic failure → `error`.
+2. **Dialog / modal**: `role="dialog"` + `aria-modal="true"`, labelled by its title. Background content must be inert or `aria-hidden` while open. (Focus behavior → rules/06.)
+3. **Tabs**: `role="tablist"` / `tab` / `tabpanel`, `aria-selected` on the active tab, `aria-controls` ↔ `aria-labelledby` linkage between tab and panel.
+4. **Menu**: `role="menu"`/`menuitem` is for **command menus**, not site navigation. Nav links wrapped in `role="menu"` is a misuse → `warning` (breaks expected keyboard model).
+5. **Switch vs checkbox vs button**: a toggle announced as what it visually is — `role="switch"` needs `aria-checked`, not `aria-pressed`; mixing the two vocabularies is `warning`.
+6. **State must live in ARIA, not only in CSS.** `className={isOpen ? 'open' : ''}` with no `aria-expanded` change means AT never hears the state change → `error` for expand/collapse triggers.
+7. **`aria-hidden` on focusable content** or on an element containing focusable children → `error` (focusable but invisible to AT).
+8. **Redundant/contradictory ARIA**: `role="button"` on `button`, `aria-label` duplicating identical visible text where unnecessary → `notice`-level `warning`; contradiction (label says one thing, visible text another) → follow rules/03 §2.
+
+## Examples
+
+Bad — half a combobox:
+
+```jsx
+<div className="select" onClick={toggle}>
+  {value}
+  {open && <ul>{options.map(o => <li onClick={() => pick(o)}>{o}</li>)}</ul>}
+</div>
+```
+
+Good (abridged):
+
+```jsx
+<button role="combobox" aria-expanded={open} aria-controls="fruit-list"
+        aria-activedescendant={activeId} onKeyDown={handleKeys}>…</button>
+<ul id="fruit-list" role="listbox" hidden={!open}>
+  <li id="opt-1" role="option" aria-selected={value === '사과'}>사과</li>
+</ul>
+```

package/skills/a11y-lens/references/05-keyboard-interaction.md

@@ -0,0 +1,43 @@
+---
+id: keyboard-interaction
+sources: [WCAG 2.1.1, WCAG 2.1.2, W3C WAI-ARIA APG keyboard patterns, eslint-plugin-jsx-a11y click-events-have-key-events]
+---
+
+# Keyboard interaction
+
+## Static baseline
+
+- `onClick` on non-interactive elements without `onKeyDown`/`onKeyUp`
+- `tabIndex` greater than 0
+- Interactive element with `tabIndex={-1}` and no programmatic focus management
+
+## Semantic checks (what you review)
+
+1. **Every pointer interaction needs a keyboard equivalent — the right one.** Adding `onKeyDown` that only handles Enter on a `div` "button" is incomplete: native buttons fire on Enter **and** Space. Check the handler actually implements the expected key set, not just any key (`error` if a claimed interactive element is keyboard-dead, `warning` if the key set is partial).
+2. **Widget key sets must match the APG pattern being imitated:**
+   - Combobox/listbox: `ArrowDown`/`ArrowUp` move the active option, `Enter` selects, `Escape` closes, `Home`/`End` jump, printable characters typeahead (typeahead is `warning`-level, the rest `error` if absent).
+   - Tabs: `ArrowLeft`/`ArrowRight` between tabs (roving tabindex), `Tab` leaves the tablist into the panel.
+   - Dialog: `Escape` closes; `Tab` cycles inside (focus trap — see rules/06).
+   - Menu: arrows navigate, `Escape` closes and returns focus to the trigger.
+3. **Hover-only affordances.** Content or controls revealed only on `:hover`/`onMouseEnter` with no focus/keyboard path (tooltips, hover menus, card action buttons) → `error`: keyboard users can never reach them. Also flag `onMouseDown`-only handlers (skips keyboard AND breaks click-drag expectations).
+4. **No keyboard traps.** Custom key handling that `preventDefault()`s Tab without providing an exit is an `error` (WCAG 2.1.2). Legitimate traps (modal dialogs) must be escapable via `Escape`.
+5. **Scroll/drag-only interactions** (carousels, sliders, drag-to-reorder) need button or keyboard alternatives → `warning`.
+6. **Global shortcuts on printable keys** without a modifier or an off-switch collide with AT and text input → `warning` (WCAG 2.1.4).
+
+## Examples
+
+Bad — mouse-only reveal:
+
+```jsx
+<div onMouseEnter={() => setShow(true)} onMouseLeave={() => setShow(false)}>
+  요금제 비교 {show && <button onClick={openDetail}>자세히</button>}
+</div>
+```
+
+Good:
+
+```jsx
+<div onMouseEnter={show} onMouseLeave={hide} onFocus={show} onBlur={hide}>
+  요금제 비교 <button onClick={openDetail} className={visible ? '' : 'sr-until-focus'}>자세히</button>
+</div>
+```

package/skills/a11y-lens/references/06-focus-management.md

@@ -0,0 +1,46 @@
+---
+id: focus-management
+sources: [WCAG 2.4.3, WCAG 2.4.7, WCAG 3.2.1, W3C WAI-ARIA APG dialog/disclosure patterns]
+---
+
+# Focus management & dynamic content
+
+## Static baseline
+
+- `outline: none` / `outline: 0` without a replacement `:focus-visible` style
+- `autoFocus` on elements below the fold
+
+## Semantic checks (what you review)
+
+1. **Opening an overlay must move focus into it; closing must return focus to the trigger.** A modal/drawer/popover in the diff that only toggles visibility state with no `focus()` call in either direction → `error`. Focus landing on the container is acceptable (`tabIndex={-1}` + label); focus landing nowhere (document.body) is the failure.
+2. **Focus trap completeness.** While a modal is open, `Tab` from the last focusable element must wrap to the first (and Shift+Tab the reverse). A "trap" implemented by `aria-hidden` on the background but with tab order still escaping → `error`.
+3. **Removing the focused element.** Deleting a list item, closing a tab, dismissing a toast that currently holds focus must move focus somewhere sensible (next item, list container, heading) — otherwise focus resets to `body` and keyboard users are lost → `warning`.
+4. **Route changes in SPAs.** Client-side navigation that only swaps content leaves focus and screen-reader context on the old page. New route should move focus to the new view's heading or main container, or announce via live region → `warning` when the diff adds routing.
+5. **Async results need announcement.** Content that appears after a delay (search results, form submission outcome, "저장되었습니다" toast) is silent to AT unless in an `aria-live` region (`polite` for results, `assertive`/`role="alert"` for errors) → `warning`; toast components with no live region → `error`.
+6. **Loading states.** Spinner-only loading (`<Spinner />` with no text, no `aria-busy`, no live announcement) → `warning`. Skeleton screens should be `aria-hidden` so AT doesn't read placeholder noise.
+7. **No focus stealing.** Auto-focusing an input on page load is acceptable for single-purpose pages (login); yanking focus on timers, carousel advance, or validation-while-typing → `warning` (WCAG 3.2.1 On Focus).
+8. **`scrollIntoView`/anchor jumps without focus.** Scrolling a target into view visually while focus stays behind creates divergence between sighted and keyboard experience → `warning`.
+
+## Examples
+
+Bad — modal with no focus contract:
+
+```jsx
+{isOpen && <div className="modal"><h2>요금제 변경</h2>…</div>}
+```
+
+Good (abridged):
+
+```jsx
+useEffect(() => {
+  if (isOpen) { dialogRef.current?.focus(); }
+  else { triggerRef.current?.focus(); }
+}, [isOpen]);
+
+{isOpen && (
+  <div ref={dialogRef} role="dialog" aria-modal="true"
+       aria-labelledby="plan-title" tabIndex={-1}>
+    <h2 id="plan-title">요금제 변경</h2>…
+  </div>
+)}
+```

package/src/agent.mjs

@@ -0,0 +1,76 @@
+import { spawnSync } from 'node:child_process';
+
+const TIMEOUT_MS = 180_000;
+
+const AGENTS = {
+  claude: {
+    bin: 'claude',
+    invoke(prompt) {
+      const args = ['-p', '--output-format', 'text'];
+      if (process.env.A11Y_LENS_MODEL) args.push('--model', process.env.A11Y_LENS_MODEL);
+      return spawnSync('claude', args, {
+        input: prompt,
+        encoding: 'utf8',
+        timeout: TIMEOUT_MS,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    },
+  },
+  codex: {
+    bin: 'codex',
+    invoke(prompt) {
+      return spawnSync('codex', ['exec', prompt], {
+        encoding: 'utf8',
+        timeout: TIMEOUT_MS,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    },
+  },
+  cursor: {
+    bin: 'cursor-agent',
+    invoke(prompt) {
+      return spawnSync('cursor-agent', ['-p', prompt, '--output-format', 'text'], {
+        encoding: 'utf8',
+        timeout: TIMEOUT_MS,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    },
+  },
+};
+
+const DETECTION_ORDER = ['claude', 'codex', 'cursor'];
+
+function isInstalled(bin) {
+  const result = spawnSync('/bin/sh', ['-c', `command -v ${bin}`], { encoding: 'utf8' });
+  return result.status === 0;
+}
+
+/** Pick an agent: explicit flag > A11Y_LENS_AGENT env > first installed. */
+export function detectAgent(preferred) {
+  const wanted = preferred || process.env.A11Y_LENS_AGENT;
+  if (wanted) {
+    const agent = AGENTS[wanted];
+    if (!agent) return { error: `unknown agent "${wanted}" (claude | codex | cursor)` };
+    if (!isInstalled(agent.bin)) return { error: `agent CLI "${agent.bin}" is not installed` };
+    return { name: wanted, agent };
+  }
+  for (const name of DETECTION_ORDER) {
+    if (isInstalled(AGENTS[name].bin)) return { name, agent: AGENTS[name] };
+  }
+  return { error: 'no agent CLI found (looked for: claude, codex, cursor-agent)' };
+}
+
+/** Run the review prompt through the agent. Returns { ok, output, error }. */
+export function runAgent(agent, prompt) {
+  let result;
+  try {
+    result = agent.invoke(prompt);
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+  if (result.error) return { ok: false, error: String(result.error) };
+  if (result.status !== 0) {
+    return { ok: false, error: (result.stderr || result.stdout || 'agent exited non-zero').trim().slice(0, 500) };
+  }
+  return { ok: true, output: result.stdout ?? '' };
+}

package/src/hooks.mjs

@@ -0,0 +1,102 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+
+const LEFTHOOK_FILES = ['lefthook.yml', 'lefthook.yaml', '.lefthook.yml', '.lefthook.yaml'];
+
+/** Pick the runner prefix from the repo's lockfile. */
+export function detectRunner(cwd) {
+  if (existsSync(join(cwd, 'pnpm-lock.yaml'))) return 'pnpm exec';
+  if (existsSync(join(cwd, 'yarn.lock'))) return 'yarn';
+  if (existsSync(join(cwd, 'bun.lockb')) || existsSync(join(cwd, 'bun.lock'))) return 'bunx';
+  return 'npx';
+}
+
+/**
+ * Install the pre-commit check into whichever hook system the repo uses.
+ * Returns { installed, system, message }. Never throws: callers report the message.
+ */
+export function installHook(cwd) {
+  const command = `${detectRunner(cwd)} a11y-lens check --staged`;
+
+  const lefthookFile = LEFTHOOK_FILES.map((f) => join(cwd, f)).find((p) => existsSync(p));
+  if (lefthookFile) return installLefthook(lefthookFile, command);
+
+  if (existsSync(join(cwd, '.husky'))) return installHusky(cwd, command);
+
+  if (existsSync(join(cwd, '.git'))) return installPlainHook(cwd, command);
+
+  return {
+    installed: false,
+    system: 'none',
+    message: 'no git repository found — run inside a repo, or add the hook manually',
+  };
+}
+
+function installLefthook(file, command) {
+  const original = readFileSync(file, 'utf8');
+  if (original.includes('a11y-lens check')) {
+    return { installed: false, system: 'lefthook', message: `already installed in ${file}` };
+  }
+
+  const job = (indent) =>
+    `${indent}- name: a11y-lens\n${indent}  run: ${command}\n`;
+
+  const lines = original.split('\n');
+  const preCommitIndex = lines.findIndex((l) => /^pre-commit:\s*$/.test(l));
+
+  if (preCommitIndex !== -1) {
+    // Find `jobs:` within the pre-commit block (stop at the next top-level key).
+    for (let i = preCommitIndex + 1; i < lines.length; i++) {
+      if (/^\S/.test(lines[i])) break; // left the block
+      const jobsMatch = lines[i].match(/^(\s+)jobs:\s*$/);
+      if (jobsMatch) {
+        const itemIndent = jobsMatch[1] + '  ';
+        lines.splice(i + 1, 0, job(itemIndent).trimEnd());
+        writeFileSync(file, lines.join('\n'));
+        return { installed: true, system: 'lefthook', message: `added a11y-lens job to ${file}` };
+      }
+    }
+    // pre-commit exists but no jobs: — unusual layout (e.g. `commands:`); don't guess.
+    return {
+      installed: false,
+      system: 'lefthook',
+      message: `${file} has a pre-commit section this tool doesn't recognize — add manually:\n\n  pre-commit:\n    jobs:\n      - name: a11y-lens\n        run: ${command}`,
+    };
+  }
+
+  writeFileSync(file, `${original.trimEnd()}\n\npre-commit:\n  jobs:\n${job('    ')}`);
+  return { installed: true, system: 'lefthook', message: `added pre-commit block to ${file}` };
+}
+
+function installHusky(cwd, command) {
+  const file = join(cwd, '.husky', 'pre-commit');
+  if (existsSync(file)) {
+    const current = readFileSync(file, 'utf8');
+    if (current.includes('a11y-lens check')) {
+      return { installed: false, system: 'husky', message: `already installed in ${file}` };
+    }
+    writeFileSync(file, `${current.trimEnd()}\n${command}\n`);
+    return { installed: true, system: 'husky', message: `appended to ${file}` };
+  }
+  writeFileSync(file, `${command}\n`);
+  chmodSync(file, 0o755);
+  return { installed: true, system: 'husky', message: `created ${file}` };
+}
+
+function installPlainHook(cwd, command) {
+  const hooksDir = join(cwd, '.git', 'hooks');
+  const file = join(hooksDir, 'pre-commit');
+  if (existsSync(file)) {
+    const current = readFileSync(file, 'utf8');
+    if (current.includes('a11y-lens check')) {
+      return { installed: false, system: 'git-hooks', message: `already installed in ${file}` };
+    }
+    writeFileSync(file, `${current.trimEnd()}\n${command}\n`);
+    chmodSync(file, 0o755);
+    return { installed: true, system: 'git-hooks', message: `appended to ${file}` };
+  }
+  mkdirSync(hooksDir, { recursive: true });
+  writeFileSync(file, `#!/bin/sh\n${command}\n`);
+  chmodSync(file, 0o755);
+  return { installed: true, system: 'git-hooks', message: `created ${file}` };
+}

package/src/prompt.mjs

@@ -0,0 +1,80 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const RULES_DIR = join(
+  dirname(fileURLToPath(import.meta.url)),
+  '..', 'skills', 'a11y-lens', 'references',
+);
+const MAX_TOTAL_BYTES = 160_000;
+
+export function loadRules() {
+  return readdirSync(RULES_DIR)
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => readFileSync(join(RULES_DIR, name), 'utf8'))
+    .join('\n\n---\n\n');
+}
+
+function numbered(content) {
+  return content
+    .split('\n')
+    .map((line, i) => `${String(i + 1).padStart(4)}: ${line}`)
+    .join('\n');
+}
+
+/**
+ * Assemble the review prompt. Files over the total budget are dropped
+ * (caller already reported per-file skips); we report drops via the return value.
+ */
+export function buildPrompt(files) {
+  const rules = loadRules();
+  const included = [];
+  const dropped = [];
+  let budget = MAX_TOTAL_BYTES;
+
+  for (const file of files) {
+    const block = [
+      `### FILE: ${file.path}`,
+      '```',
+      numbered(file.content),
+      '```',
+      file.diff ? `#### Staged diff for ${file.path} (focus your review here)\n\`\`\`diff\n${file.diff}\n\`\`\`` : '',
+    ].join('\n');
+    const size = Buffer.byteLength(block, 'utf8');
+    if (size > budget) {
+      dropped.push(file.path);
+      continue;
+    }
+    budget -= size;
+    included.push(block);
+  }
+
+  const prompt = `You are a11y-lens, a semantic accessibility reviewer. You review UI code against the rule set below. You are the layer ABOVE static linters: do not report what eslint-plugin-jsx-a11y or axe-core would already catch unless it is listed under "Semantic checks". Focus on meaning, completeness of patterns, and context — the things attribute-presence checks cannot see.
+
+## Rule set
+
+${rules}
+
+## Code under review
+
+Each file is shown with line numbers ("NNNN: code"). When a staged diff is provided, findings should concern changed or directly affected code; use the full file only for context.
+
+${included.join('\n\n')}
+
+## Output format
+
+Respond with ONLY a JSON array — no prose, no markdown fences. Each finding:
+{
+  "file": "path as given above",
+  "line": <number from the line-number prefix>,
+  "ruleId": "one of: landmarks-headings | images-alt | forms-labels | aria-widgets | keyboard-interaction | focus-management",
+  "severity": "error" | "warning",
+  "message": "what is wrong and why it matters, one or two sentences",
+  "suggestion": "the concrete fix, one sentence or a short code hint"
+}
+
+Severity discipline: "error" only for clear violations named as error in the rules (keyboard-dead interactive elements, missing accessible names on icon-only controls, incomplete claimed ARIA patterns, focus not managed on overlays, informative images silenced). Judgment calls are "warning". If the code is clean, respond with [].`;
+
+  return { prompt, dropped };
+}

package/src/report.mjs

@@ -0,0 +1,71 @@
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+
+const VALID_SEVERITIES = new Set(['error', 'warning']);
+
+/** Extract a findings array from agent output, tolerating fences and prose. */
+export function parseFindings(text) {
+  const candidates = [];
+  const trimmed = text.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
+  candidates.push(trimmed);
+  const match = trimmed.match(/\[[\s\S]*\]/);
+  if (match) candidates.push(match[0]);
+
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (!Array.isArray(parsed)) continue;
+      return {
+        findings: parsed.filter(
+          (f) => f && typeof f === 'object' && typeof f.message === 'string'
+            && VALID_SEVERITIES.has(f.severity),
+        ),
+      };
+    } catch {
+      /* try next candidate */
+    }
+  }
+  return { error: 'could not parse agent output as a findings array' };
+}
+
+export function printReport(findings, { agentName } = {}) {
+  if (findings.length === 0) {
+    console.log(`a11y-lens: no findings ${DIM}(reviewed by ${agentName})${RESET}`);
+    return;
+  }
+  const byFile = new Map();
+  for (const f of findings) {
+    const key = f.file ?? '(unknown file)';
+    if (!byFile.has(key)) byFile.set(key, []);
+    byFile.get(key).push(f);
+  }
+  for (const [file, list] of byFile) {
+    console.log(`\n${BOLD}${file}${RESET}`);
+    list.sort((a, b) => (a.line ?? 0) - (b.line ?? 0));
+    for (const f of list) {
+      const mark = f.severity === 'error' ? `${RED}✖ error${RESET}` : `${YELLOW}⚠ warning${RESET}`;
+      const line = f.line ? `${DIM}:${f.line}${RESET}` : '';
+      console.log(`  ${mark}${line}  [${f.ruleId ?? 'general'}] ${f.message}`);
+      if (f.suggestion) console.log(`     ${DIM}fix: ${f.suggestion}${RESET}`);
+    }
+  }
+  const errors = findings.filter((f) => f.severity === 'error').length;
+  const warnings = findings.length - errors;
+  console.log(
+    `\na11y-lens: ${errors ? RED : ''}${errors} error(s)${RESET}, ` +
+    `${warnings ? YELLOW : ''}${warnings} warning(s)${RESET} ` +
+    `${DIM}(reviewed by ${agentName})${RESET}`,
+  );
+}
+
+/** Exit code policy: errors gate; warnings gate only with --strict. */
+export function exitCodeFor(findings, { strict } = {}) {
+  const errors = findings.some((f) => f.severity === 'error');
+  const warnings = findings.some((f) => f.severity === 'warning');
+  if (errors) return 1;
+  if (strict && warnings) return 1;
+  return 0;
+}

package/src/staged.mjs

@@ -0,0 +1,90 @@
+import { execFileSync } from 'node:child_process';
+
+const UI_EXTENSIONS = new Set([
+  '.jsx', '.tsx', '.html', '.htm', '.vue', '.svelte', '.astro', '.mdx',
+]);
+// .js/.ts are included only when their content looks like markup (JSX, template strings with tags).
+const MAYBE_UI_EXTENSIONS = new Set(['.js', '.ts', '.mjs', '.cjs']);
+
+const MAX_FILE_BYTES = 48_000;
+
+function git(args, options = {}) {
+  return execFileSync('git', args, { encoding: 'utf8', ...options });
+}
+
+function extensionOf(path) {
+  const dot = path.lastIndexOf('.');
+  return dot === -1 ? '' : path.slice(dot).toLowerCase();
+}
+
+function looksLikeUI(content) {
+  // JSX/HTML-ish: an opening tag followed by attributes, `/>` or `>`.
+  return /<([a-z][\w-]*|[A-Z]\w*)(\s[^<>]*)?\/?>/.test(content);
+}
+
+/**
+ * Collect staged files that plausibly contain UI markup.
+ * Returns [{ path, content, diff, skipped? }]
+ */
+export function collectStagedUIFiles() {
+  let names;
+  try {
+    names = git(['diff', '--cached', '--name-only', '--diff-filter=ACMR'])
+      .split('\n')
+      .filter(Boolean);
+  } catch {
+    return { files: [], error: 'not a git repository (or git unavailable)' };
+  }
+
+  const files = [];
+  for (const path of names) {
+    const ext = extensionOf(path);
+    const isUI = UI_EXTENSIONS.has(ext);
+    const isMaybeUI = MAYBE_UI_EXTENSIONS.has(ext);
+    if (!isUI && !isMaybeUI) continue;
+
+    let content;
+    try {
+      content = git(['show', `:${path}`], { maxBuffer: 10 * 1024 * 1024 });
+    } catch {
+      continue; // deleted between index and now, submodule, etc.
+    }
+    if (isMaybeUI && !looksLikeUI(content)) continue;
+    if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {
+      files.push({ path, skipped: `larger than ${MAX_FILE_BYTES / 1000}KB` });
+      continue;
+    }
+
+    let diff = '';
+    try {
+      diff = git(['diff', '--cached', '--unified=3', '--', path]);
+    } catch {
+      /* diff is best-effort context */
+    }
+    files.push({ path, content, diff });
+  }
+  return { files };
+}
+
+/** Read explicit file paths from the working tree (non-staged mode). */
+export function collectPathArgs(paths) {
+  const files = [];
+  for (const path of paths) {
+    let content;
+    try {
+      content = execFileSync('cat', [path], {
+        encoding: 'utf8',
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    } catch {
+      files.push({ path, skipped: 'unreadable' });
+      continue;
+    }
+    if (Buffer.byteLength(content, 'utf8') > MAX_FILE_BYTES) {
+      files.push({ path, skipped: `larger than ${MAX_FILE_BYTES / 1000}KB` });
+      continue;
+    }
+    files.push({ path, content, diff: '' });
+  }
+  return { files };
+}

package/templates/agents-snippet.md

@@ -0,0 +1,18 @@
+<!-- a11y-lens:begin -->
+## Accessibility rules (a11y-lens)
+
+This project uses [a11y-lens](https://github.com/jo-duchan/a11y-lens) for semantic accessibility review. Staged UI changes are checked at commit time; findings with `error` severity block the commit.
+
+When writing or modifying UI code (JSX/TSX/HTML/Vue/Svelte), apply the rule set in `node_modules/@a11y-lens/cli/skills/a11y-lens/references/` — read the relevant category before implementing:
+
+- `01-landmarks-headings.md` — document outline, one h1, no level skips, labelled landmarks
+- `02-images-alt.md` — alt text that describes function in context; icon-only controls need accessible names
+- `03-forms-labels.md` — placeholder is not a label; errors tied via `aria-describedby`; name matches visible label
+- `04-aria-widgets.md` — prefer native elements; custom widgets implement the complete WAI-ARIA APG pattern
+- `05-keyboard-interaction.md` — full APG key sets, no hover-only affordances, no keyboard traps
+- `06-focus-management.md` — overlays move and return focus; async results are announced via live regions
+
+Tip: agents with skills support get richer guidance via `npx skills add jo-duchan/a11y-lens`.
+
+Self-check against these categories before finishing any UI task — it is cheaper than failing the pre-commit gate.
+<!-- a11y-lens:end -->