@a11y-lens/cli 0.4.1 → 0.6.0

package/README.md

@@ -31,6 +31,8 @@ husky - pre-commit hook exited with code 1
 
 **Infrastructure never blocks a commit.** No agent CLI, no network, agent crash → a11y-lens warns and exits 0. Only real accessibility findings gate.
 
+**…but a skipped check does not pass for a clean one.** Exiting 0 means your hook runner shows the same ✔️ either way, so when a staged check could not review a file — the agent timed out or failed, its output could not be parsed, or the file was dropped for the prompt size budget — a11y-lens records it as *pending*. The next check warns about it, and `a11y-lens check --pending` reviews it later. See [Skipped checks](#skipped-checks).
+
 ## It samples; it does not audit
 
 a11y-lens is an AI reviewer, not a deterministic linter. The same files reviewed twice can return different findings — even zero on a run that flagged issues a moment earlier. Read the output with that in mind:
@@ -41,6 +43,31 @@ a11y-lens is an AI reviewer, not a deterministic linter. The same files reviewed
 
 This is deliberate: only clear `error`-severity violations gate and warnings never block, precisely because AI output varies run to run. (This note belongs here, in the tool's own README — not in the `AGENTS.md` rules block that `init` injects into a consuming project, which is reserved for the accessibility rules themselves.)
 
+## Levels: what gets checked, and what gets shown
+
+Not every project needs every check. Each check in the rule set is tagged by who it helps:
+
+- **`core`**: checks that help everyone. They cover accessible names on icon-only controls, labels that are not placeholders, names that match the visible label, autocomplete on identity fields, full keyboard operation, and focus that is moved, returned and never lost.
+- **`full`**: the core checks plus the ones that are specific to screen readers. They cover headings and landmarks, alt text, complete ARIA patterns, errors tied to their fields, and live-region announcements for async results and loading.
+
+A `full` review is a superset of a `core` one, so code written to `full` passes `core`.
+
+Set the level for the whole team in the repository:
+
+```json
+// a11y-lens.config.json at the repository root (or the "a11y-lens" field of the root package.json)
+{ "level": "core", "report": "errors" }
+```
+
+| Setting | Values | Default |
+|---|---|---|
+| `level` | `core`: only `[core]` checks are sent to the agent. `full`: all checks. | `full` |
+| `report` | `errors`: print errors, and say how many warnings were hidden. `all`: print everything. | `all` |
+
+The defaults run the same checks and print the same output as earlier versions, so upgrading changes nothing a project would notice until it opts in. The rule text itself now carries the tags. `A11Y_LENS_LEVEL` and `A11Y_LENS_REPORT` override the file for one run. `--strict` always prints warnings, because it makes them fail the commit. An unknown value is warned about and replaced by the default.
+
+These levels are not WCAG's A/AA/AAA. They sort checks by who benefits, not by conformance level.
+
 ## Install
 
 a11y-lens has two layers — install either or both:
@@ -76,11 +103,44 @@ 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 check --pending          # review files an earlier check skipped
 a11y-lens rules                    # list rule categories
 ```
 
 Escape hatches: `A11Y_LENS_SKIP=1 git commit …` or `git commit --no-verify`.
 
+| Environment | Effect |
+|---|---|
+| `A11Y_LENS_AGENT` | same as `--agent` |
+| `A11Y_LENS_MODEL` | model passed to `claude` |
+| `A11Y_LENS_TIMEOUT_MS` | agent timeout in milliseconds (default `180000`) |
+| `A11Y_LENS_LEVEL` | `core` or `full` for this run, over the project's setting |
+| `A11Y_LENS_REPORT` | `errors` or `all` for this run, over the project's setting |
+| `A11Y_LENS_SKIP=1` | skip the check entirely |
+
+## Skipped checks
+
+A staged check records a file as pending when it could not review it:
+
+| Why the file was not reviewed | Recorded? |
+|---|---|
+| Agent timed out, crashed, or exited non-zero (including logged out or out of quota) | yes |
+| Agent output could not be parsed as findings | yes |
+| Dropped because the prompt size budget was spent | yes |
+| `A11Y_LENS_SKIP=1`, no agent CLI installed, file over 48KB, no UI files staged | no: deliberate, or it would be skipped again |
+
+An entry is cleared when `check --pending` reviews it, or when a later `check --staged` in the same worktree reviews the very same staged content (a commit that was aborted and retried). If the skipped commit landed, its change is no longer in the next diff, so only `--pending` clears it. `--pending` reviews the content that was **staged at the time**, with its staged diff. That way it reports on the skipped change, not on the whole file as it is now. It works even after the file has changed or its worktree is gone. Each skipped check is reviewed in its own agent call. Anything that times out or is dropped again stays pending.
+
+**Layout (public contract, version 1).** Other tools may read this, for example a hook that reminds an agent to run `--pending`:
+
+```
+<git rev-parse --git-common-dir>/a11y-lens/pending/<sha1>.json
+{ "version": 1, "worktree": "/abs/path", "path": "src/A.tsx", "blob": "<index sha>",
+  "diff": "<staged diff>", "reason": "agent failed: …", "at": "2026-09-23T06:00:00.000Z" }
+```
+
+A non-empty directory means something was not reviewed. Any change to this layout bumps `version`. A record this version cannot read (another version wrote it, or it is damaged) is reported and never cleared automatically. Once it has been dealt with, delete the file by hand.
+
 ## 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.

package/bin/a11y-lens.mjs

@@ -7,6 +7,8 @@ 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';
+import { recordPending, listPending, clearReviewed, clearEntry, contentOf, pendingDir } from '../src/pending.mjs';
+import { loadConfig } from '../src/config.mjs';
 
 const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -15,6 +17,7 @@ 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 check --pending           review files an earlier check skipped
   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
@@ -30,15 +33,28 @@ 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)
+  A11Y_LENS_TIMEOUT_MS                agent timeout in ms (default 180000)
+  A11Y_LENS_LEVEL=core|full           override the project's level (see below)
+  A11Y_LENS_REPORT=errors|all         override the project's report setting
+
+Project settings, in a11y-lens.config.json at the repository root (or the
+"a11y-lens" field of package.json):
+  { "level": "core", "report": "errors" }
+  level   core = checks that help everyone (names, keyboard, focus);
+          full = those plus screen-reader-specific checks (default)
+  report  errors = print errors only, and count the hidden warnings;
+          all = print everything (default). --strict always prints all.
 
 Infrastructure failures (no agent CLI, no network, agent error) never block:
-a11y-lens warns and exits 0. Only accessibility findings gate.`;
+a11y-lens warns and exits 0. Only accessibility findings gate. When a staged
+check could not review a file (agent failure or timeout, unparseable output,
+prompt budget), the file is recorded as pending until a later run reviews it.`;
 
 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') {
+    if (token === '--staged' || token === '--strict' || token === '--no-hook' || token === '--pending') {
       args.flags[token.slice(2)] = true;
     }
     else if (token === '--agent') args.flags.agent = argv[++i];
@@ -48,17 +64,66 @@ function parseArgs(argv) {
   return args;
 }
 
+const RECHECK = 'a11y-lens check --pending';
+
 function softFail(message) {
   console.warn(`a11y-lens: ${message} — skipping check (commits are never blocked by infrastructure).`);
   process.exit(0);
 }
 
+/** Record what a staged run could not review, and say so where the committer will see it. */
+const RUN_STARTED = new Date();
+
+function notePending(files, reason) {
+  const result = recordPending(files, reason, { now: RUN_STARTED });
+  if (result.error) {
+    console.warn(`a11y-lens: could not record ${files.length} unreviewed file(s) as pending (${result.error}).`);
+  } else {
+    console.warn(`a11y-lens: recorded ${result.recorded} unreviewed file(s) as pending — review them later with: ${RECHECK}`);
+  }
+}
+
+function skipStaged(files, message) {
+  notePending(files, message);
+  softFail(message);
+}
+
+function warnUnreadable(count) {
+  console.warn(
+    `a11y-lens: ${count} pending record(s) in ${pendingDir()} could not be read (another a11y-lens version, or damaged). ` +
+      'This version never clears them; delete them by hand once you have dealt with them.',
+  );
+}
+
+/**
+ * Before anything can exit early (a skip, a commit with no UI files): a skipped check looks like a
+ * clean one, so the next run is the first chance to say it happened.
+ */
+function warnPending() {
+  const { entries, unreadable } = listPending();
+  if (entries.length) {
+    console.warn(
+      `a11y-lens: ${entries.length} file(s) from earlier commits were never reviewed (the check was skipped). Review them with: ${RECHECK}`,
+    );
+  }
+  if (unreadable) {
+    warnUnreadable(unreadable);
+  }
+}
+
+/** Settings for this run; `--strict` gates on warnings, so it always shows them. */
+function runSettings(args) {
+  const config = loadConfig();
+  return { level: config.level, report: args.flags.strict ? 'all' : config.report };
+}
+
 function commandCheck(args) {
+  if (args.flags.pending) return commandCheckPending(args);
+  warnPending();
   if (process.env.A11Y_LENS_SKIP === '1') softFail('A11Y_LENS_SKIP=1');
 
-  const { files, error } = args.flags.staged
-    ? collectStagedUIFiles()
-    : collectPathArgs(args._);
+  const staged = Boolean(args.flags.staged);
+  const { files, error } = staged ? collectStagedUIFiles() : collectPathArgs(args._);
   if (error) softFail(error);
 
   const reviewable = files.filter((f) => !f.skipped);
@@ -66,7 +131,7 @@ function commandCheck(args) {
     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.');
+    if (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);
   }
@@ -74,24 +139,112 @@ function commandCheck(args) {
   const detection = detectAgent(args.flags.agent);
   if (detection.error) softFail(detection.error);
 
-  const { prompt, dropped } = buildPrompt(reviewable);
+  const settings = runSettings(args);
+  const { prompt, dropped } = buildPrompt(reviewable, { level: settings.level });
   for (const path of dropped) {
     console.warn(`a11y-lens: dropped ${path} (prompt size budget exceeded)`);
   }
+  const included = reviewable.filter((f) => !dropped.includes(f.path));
+  if (staged && dropped.length) {
+    notePending(reviewable.filter((f) => dropped.includes(f.path)), 'prompt size budget exceeded');
+  }
 
-  console.log(
-    `a11y-lens: reviewing ${reviewable.length - dropped.length} file(s) with ${detection.name}…`,
-  );
+  if (included.length === 0) process.exit(0);
+  console.log(`a11y-lens: reviewing ${included.length} file(s) with ${detection.name}…`);
   const result = runAgent(detection.agent, prompt);
-  if (!result.ok) softFail(`agent failed: ${result.error}`);
+  if (!result.ok) {
+    if (staged) skipStaged(included, `agent failed: ${result.error}`);
+    softFail(`agent failed: ${result.error}`);
+  }
 
   const parsed = parseFindings(result.output);
-  if (parsed.error) softFail(parsed.error);
+  if (parsed.error) {
+    if (staged) skipStaged(included, parsed.error);
+    softFail(parsed.error);
+  }
+
+  // Reviewed now, so an entry left by an earlier skip of the same path — say, a commit that
+  // typecheck aborted in parallel — is answered.
+  if (staged) clearReviewed(included.map((f) => f.path));
 
-  printReport(parsed.findings, { agentName: detection.name });
+  printReport(parsed.findings, { agentName: detection.name, report: settings.report });
   process.exit(exitCodeFor(parsed.findings, { strict: args.flags.strict }));
 }
 
+/**
+ * Review what earlier staged runs skipped. One agent call per recorded skip, not one for all of
+ * them: a bad session leaves dozens of entries, and a single prompt that big would time out again
+ * and never let the list shrink. Each batch clears only what it actually reviewed.
+ */
+function commandCheckPending(args) {
+  const { entries, unreadable } = listPending();
+  if (unreadable) {
+    warnUnreadable(unreadable);
+  }
+  if (entries.length === 0) {
+    console.log('a11y-lens: nothing pending.');
+    process.exit(0);
+  }
+
+  const detection = detectAgent(args.flags.agent);
+  if (detection.error) softFail(`${detection.error}; ${entries.length} file(s) remain pending`);
+  const settings = runSettings(args);
+
+  const batches = new Map();
+  for (const item of [...entries].sort((a, b) => a.entry.at.localeCompare(b.entry.at))) {
+    const key = `${item.entry.worktree}\0${item.entry.at}`;
+    if (!batches.has(key)) batches.set(key, []);
+    batches.get(key).push(item);
+  }
+
+  const findings = [];
+  let remaining = 0;
+  for (const batch of batches.values()) {
+    const files = [];
+    for (const item of batch) {
+      const found = contentOf(item.entry);
+      if (found.gone) {
+        console.warn(`a11y-lens: dropping pending ${item.entry.path} (${found.gone})`);
+        clearEntry(item);
+        continue;
+      }
+      files.push({ path: item.entry.path, content: found.content, diff: item.entry.diff, item });
+    }
+    if (files.length === 0) continue;
+
+    const { prompt, dropped } = buildPrompt(files, { level: settings.level });
+    const included = files.filter((f) => !dropped.includes(f.path));
+    if (included.length === 0) {
+      console.warn(`a11y-lens: every file skipped at ${batch[0].entry.at} exceeds the prompt budget — they stay pending.`);
+      remaining += files.length;
+      continue;
+    }
+    console.log(
+      `a11y-lens: reviewing ${included.length} pending file(s) skipped at ${batch[0].entry.at} with ${detection.name}…`,
+    );
+    const result = runAgent(detection.agent, prompt);
+    const parsed = result.ok ? parseFindings(result.output) : { error: `agent failed: ${result.error}` };
+    if (parsed.error) {
+      console.warn(`a11y-lens: ${parsed.error} — ${files.length} file(s) stay pending.`);
+      remaining += files.length;
+      continue;
+    }
+    findings.push(...parsed.findings);
+    for (const f of files) {
+      if (dropped.includes(f.path)) {
+        console.warn(`a11y-lens: dropped ${f.path} (prompt size budget exceeded) — it stays pending.`);
+        remaining++;
+      } else {
+        clearEntry(f.item);
+      }
+    }
+  }
+
+  printReport(findings, { agentName: detection.name, report: settings.report });
+  if (remaining) console.warn(`a11y-lens: ${remaining} file(s) are still pending — run ${RECHECK} again.`);
+  process.exit(exitCodeFor(findings, { strict: args.flags.strict }));
+}
+
 function commandInit(args) {
   // 1. Pre-commit hook (lefthook / husky / plain git hooks, auto-detected)
   if (!args.flags['no-hook']) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a11y-lens/cli",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "publishConfig": {
     "access": "public"
   },
@@ -19,7 +19,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/"
+    "test": "node --test test/*.test.mjs"
   },
   "keywords": [
     "accessibility",

package/skills/a11y-lens/SKILL.md

@@ -20,11 +20,13 @@ Before writing or reviewing UI code, read the reference file for each category t
 | 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:
+**Levels.** Every check is tagged `[core]` or `[full]`. `[core]` checks help everyone — accessible names, keyboard operation, focus that is never lost. `[full]` checks are screen-reader specific — headings and landmarks, alt text, ARIA patterns, live-region announcements. If the project sets `"level": "core"` (in `a11y-lens.config.json`, or the `"a11y-lens"` field of `package.json`), apply only the `[core]` checks and `[core]` examples; otherwise apply all of them.
+
+Stances at every level (items that belong only to `full` are marked):
 
 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`.
+2. **Placeholder is not a label. Hover is not a keyboard path.** At `full`, also: **CSS state is not ARIA state.**
+3. Severity discipline: `error` = clear violations (keyboard-dead interactive elements, unnamed icon-only controls, unmanaged overlay focus; at `full`, also incomplete claimed ARIA patterns and silenced informative images). Judgment calls are `warning`.
 
 ## Commit-time gate (CLI)
 

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

@@ -13,16 +13,18 @@ sources: [WCAG 1.3.1, WCAG 2.4.1, WCAG 2.4.6, axe-core region/heading rules]
 
 ## Semantic checks (what you review)
 
-1. **Heading hierarchy must describe the document outline, not the visual design.**
+1. `[full]` **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`).
+2. `[full]` **`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. `[full]` **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. `[full]` **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
 
+### `[full]` Outline and landmark
+
 Bad — outline skips and decorative section:
 
 ```jsx

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

@@ -13,27 +13,41 @@ sources: [WCAG 1.1.1, eslint-plugin-jsx-a11y alt-text/img-redundant-alt, axe-cor
 
 ## Semantic checks (what you review)
 
-1. **Does the `alt` actually describe the image's function or content in context?**
+1. `[full]` **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.
+2. `[full]` **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. `[full]` **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. `[core]` **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. `[full]` **Text baked into images** (event banners with dates/prices in pixels) — the alt or adjacent text must carry the same information; otherwise `warning`.
+6. `[full]` **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
 
+### `[core]` Icon-only button
+
+Bad — no name:
+
+```jsx
+<button><CloseIcon /></button>
+```
+
+Good:
+
+```jsx
+<button aria-label="닫기"><CloseIcon aria-hidden="true" /></button>
+```
+
+### `[full]` Image inside a link
+
 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

@@ -12,27 +12,43 @@ sources: [WCAG 1.3.1, WCAG 3.3.1, WCAG 3.3.2, WCAG 4.1.2, eslint-plugin-jsx-a11y
 
 ## 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.
+1. `[core]` **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. `[core]` **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. `[full]` **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. `[full]` **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. `[full]` **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. `[core]` **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
 
+### `[core]` Label and autocomplete
+
 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}
+<input id="email" type="email" autoComplete="email" value={email} onChange={...} />
+```
+
+### `[full]` Error tied to its field
+
+Bad:
+
+```jsx
+<input id="email" type="email" value={email} onChange={...} />
+{error && <p className="error">이메일 형식이 아닙니다</p>}
+```
+
+Good:
+
+```jsx
+<input id="email" type="email" value={email} onChange={...}
        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

@@ -17,20 +17,22 @@ sources: [W3C WAI-ARIA APG patterns, WCAG 4.1.2, eslint-plugin-jsx-a11y role-* r
 
 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):
+1. `[full]` **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.
+2. `[full]` **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. `[full]` **Tabs**: `role="tablist"` / `tab` / `tabpanel`, `aria-selected` on the active tab, `aria-controls` ↔ `aria-labelledby` linkage between tab and panel.
+4. `[full]` **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. `[full]` **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. `[full]` **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. `[full]` **`aria-hidden` on focusable content** or on an element containing focusable children → `error` (focusable but invisible to AT).
+8. `[full]` **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
 
+### `[full]` Combobox
+
 Bad — half a combobox:
 
 ```jsx

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

@@ -13,19 +13,21 @@ sources: [WCAG 2.1.1, WCAG 2.1.2, W3C WAI-ARIA APG keyboard patterns, eslint-plu
 
 ## 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:**
+1. `[core]` **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. `[core]` **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).
+3. `[core]` **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. `[core]` **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. `[core]` **Scroll/drag-only interactions** (carousels, sliders, drag-to-reorder) need button or keyboard alternatives → `warning`.
+6. `[core]` **Global shortcuts on printable keys** without a modifier or an off-switch collide with AT and text input → `warning` (WCAG 2.1.4).
 
 ## Examples
 
+### `[core]` Hover-only reveal
+
 Bad — mouse-only reveal:
 
 ```jsx

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

@@ -12,18 +12,20 @@ sources: [WCAG 2.4.3, WCAG 2.4.7, WCAG 3.2.1, W3C WAI-ARIA APG dialog/disclosure
 
 ## 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`.
+1. `[core]` **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. `[core]` **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. `[core]` **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. `[full]` **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. `[full]` **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. `[full]` **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. `[core]` **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. `[core]` **`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:
+### `[core]` Modal focus contract
+
+Bad — focus goes nowhere on open, and nowhere on close:
 
 ```jsx
 {isOpen && <div className="modal"><h2>요금제 변경</h2>…</div>}
@@ -38,9 +40,19 @@ useEffect(() => {
 }, [isOpen]);
 
 {isOpen && (
-  <div ref={dialogRef} role="dialog" aria-modal="true"
-       aria-labelledby="plan-title" tabIndex={-1}>
-    <h2 id="plan-title">요금제 변경</h2>…
+  <div ref={dialogRef} tabIndex={-1} aria-label="요금제 변경">
+    <h2>요금제 변경</h2>…
   </div>
 )}
 ```
+
+### `[full]` Modal semantics
+
+The same modal, announced as one: `role="dialog"`, `aria-modal="true"` and a label (rules/04 §2).
+
+```jsx
+<div ref={dialogRef} role="dialog" aria-modal="true"
+     aria-labelledby="plan-title" tabIndex={-1}>
+  <h2 id="plan-title">요금제 변경</h2>…
+</div>
+```

package/src/agent.mjs

@@ -1,37 +1,47 @@
 import { spawnSync } from 'node:child_process';
 
-const TIMEOUT_MS = 180_000;
+const DEFAULT_TIMEOUT_MS = 180_000;
+
+/** A11Y_LENS_TIMEOUT_MS if it is a positive integer, else the default (with a warning for a bad value). */
+export function timeoutMs(env = process.env) {
+  const raw = env.A11Y_LENS_TIMEOUT_MS;
+  if (raw === undefined || raw === '') return DEFAULT_TIMEOUT_MS;
+  const value = Number(raw);
+  if (Number.isInteger(value) && value > 0) return value;
+  console.warn(`a11y-lens: ignoring A11Y_LENS_TIMEOUT_MS="${raw}" (not a positive integer); using ${DEFAULT_TIMEOUT_MS}ms`);
+  return DEFAULT_TIMEOUT_MS;
+}
 
 const AGENTS = {
   claude: {
     bin: 'claude',
-    invoke(prompt) {
+    invoke(prompt, timeout) {
       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,
+        timeout,
         maxBuffer: 10 * 1024 * 1024,
       });
     },
   },
   codex: {
     bin: 'codex',
-    invoke(prompt) {
+    invoke(prompt, timeout) {
       return spawnSync('codex', ['exec', prompt], {
         encoding: 'utf8',
-        timeout: TIMEOUT_MS,
+        timeout,
         maxBuffer: 10 * 1024 * 1024,
       });
     },
   },
   cursor: {
     bin: 'cursor-agent',
-    invoke(prompt) {
+    invoke(prompt, timeout) {
       return spawnSync('cursor-agent', ['-p', prompt, '--output-format', 'text'], {
         encoding: 'utf8',
-        timeout: TIMEOUT_MS,
+        timeout,
         maxBuffer: 10 * 1024 * 1024,
       });
     },
@@ -61,10 +71,10 @@ export function detectAgent(preferred) {
 }
 
 /** Run the review prompt through the agent. Returns { ok, output, error }. */
-export function runAgent(agent, prompt) {
+export function runAgent(agent, prompt, timeout = timeoutMs()) {
   let result;
   try {
-    result = agent.invoke(prompt);
+    result = agent.invoke(prompt, timeout);
   } catch (err) {
     return { ok: false, error: String(err) };
   }

package/src/config.mjs

@@ -0,0 +1,83 @@
+// Project settings: which checks run (`level`) and which findings are shown (`report`).
+//
+// Read from the repository, because what a team checks is a team decision: `a11y-lens.config.json`
+// at the git top level, else the `"a11y-lens"` field of its `package.json`. Environment variables
+// override either, for one person trying something out. A bad value is warned about and replaced by
+// the default — never an error, since a commit is never blocked by infrastructure.
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const LEVELS = ['core', 'full'];
+export const REPORTS = ['errors', 'all'];
+// The defaults are what every version before 0.6.0 did, so upgrading changes nothing by itself.
+export const DEFAULTS = { level: 'full', report: 'all' };
+
+function repoRoot(cwd) {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+  } catch {
+    return cwd;
+  }
+}
+
+/** `{ value }`, `{ missing: true }`, or `{ error }` — a file that is there but unreadable is worth a warning. */
+function readJson(path) {
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    return { missing: true };
+  }
+  try {
+    return { value: JSON.parse(text) };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+
+export function loadConfig({ cwd = process.cwd(), env = process.env, warn = (m) => console.warn(m) } = {}) {
+  const root = repoRoot(cwd);
+  let settings = {};
+  let source = 'defaults';
+
+  const file = join(root, 'a11y-lens.config.json');
+  const fromFile = readJson(file);
+  if (fromFile.error) {
+    warn(`a11y-lens: ignoring ${file} (${fromFile.error})`);
+  } else if (!fromFile.missing) {
+    if (isPlainObject(fromFile.value)) {
+      settings = fromFile.value;
+      source = 'a11y-lens.config.json';
+    } else {
+      warn(`a11y-lens: ignoring ${file} (expected an object)`);
+    }
+  } else {
+    const pkg = readJson(join(root, 'package.json'));
+    const field = pkg.value?.['a11y-lens'];
+    if (field !== undefined) {
+      if (isPlainObject(field)) {
+        settings = field;
+        source = 'package.json';
+      } else {
+        warn('a11y-lens: ignoring the "a11y-lens" field in package.json (expected an object)');
+      }
+    }
+  }
+
+  const pick = (key, allowed, envName) => {
+    for (const [value, from] of [[env[envName], envName], [settings[key], source]]) {
+      if (value === undefined || value === '') continue;
+      if (allowed.includes(value)) return value;
+      warn(`a11y-lens: ignoring ${key} "${value}" from ${from} (expected ${allowed.join(' | ')})`);
+    }
+    return DEFAULTS[key];
+  };
+
+  return {
+    level: pick('level', LEVELS, 'A11Y_LENS_LEVEL'),
+    report: pick('report', REPORTS, 'A11Y_LENS_REPORT'),
+  };
+}

package/src/pending.mjs

@@ -0,0 +1,166 @@
+// Pending reviews: staged files a check could not review, kept so the skip is visible later.
+//
+// A skipped check exits 0 so a commit is never blocked by infrastructure — which also makes it look
+// exactly like a clean one. Each file it failed to review is recorded here, and stays until a later
+// run actually reviews it (`check --staged` on the same path, or `check --pending`).
+//
+// Layout (a public contract — other tools read it; bump PENDING_VERSION on any change):
+//   <git-common-dir>/a11y-lens/pending/<sha1(worktree + NUL + path)>.json
+//   { version, worktree, path, blob, diff, reason, at }
+//
+// - One file per entry: parallel commits in several worktrees record at the same moment, and a
+//   single shared file would lose one of them. Each is written to a temp file and renamed, so a
+//   reader never sees half an entry (untested: the race cannot be staged deterministically).
+// - The common dir, so an entry recorded in a worktree is still visible after that worktree is gone.
+// - `blob` is the index object that was staged. It lives in the shared object store, so the exact
+//   content that went unreviewed can still be read after the worktree is removed or the file edited.
+// - `diff` is the staged diff, so a re-check reviews the change rather than the whole file and does
+//   not report pre-existing issues as if the skipped commit introduced them.
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const PENDING_VERSION = 1;
+
+function git(args, cwd) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 10 * 1024 * 1024 });
+}
+
+/** Absolute pending directory, or null outside a git repository. */
+export function pendingDir(cwd = process.cwd()) {
+  try {
+    const common = git(['rev-parse', '--path-format=absolute', '--git-common-dir'], cwd).trim();
+    return join(common, 'a11y-lens', 'pending');
+  } catch {
+    return null;
+  }
+}
+
+function worktreeOf(cwd) {
+  return git(['rev-parse', '--show-toplevel'], cwd).trim();
+}
+
+function entryName(worktree, path) {
+  return `${createHash('sha1').update(`${worktree}\0${path}`).digest('hex')}.json`;
+}
+
+/**
+ * Record staged files that were not reviewed. `files` are staged entries ({ path, diff }).
+ * Returns { recorded } or { error } — never throws, because a failure here must not block a commit.
+ */
+export function recordPending(files, reason, { cwd = process.cwd(), now = new Date() } = {}) {
+  if (files.length === 0) return { recorded: 0 };
+  try {
+    const dir = pendingDir(cwd);
+    if (!dir) return { error: 'not a git repository' };
+    const worktree = worktreeOf(cwd);
+    mkdirSync(dir, { recursive: true });
+    const at = now.toISOString();
+    for (const file of files) {
+      let blob = null;
+      try {
+        blob = git(['rev-parse', `:${file.path}`], worktree).trim();
+      } catch {
+        /* not in the index (non-staged run); the working-tree path is the only locator */
+      }
+      const entry = { version: PENDING_VERSION, worktree, path: file.path, blob, diff: file.diff ?? '', reason, at };
+      const target = join(dir, entryName(worktree, file.path));
+      const temp = `${target}.${process.pid}.tmp`;
+      writeFileSync(temp, JSON.stringify(entry));
+      renameSync(temp, target);
+    }
+    return { recorded: files.length };
+  } catch (err) {
+    return { error: String(err?.message ?? err) };
+  }
+}
+
+/** All readable entries, each with its file name. Unreadable or foreign-version files are counted, not returned. */
+export function listPending(cwd = process.cwd()) {
+  const dir = pendingDir(cwd);
+  if (!dir) return { entries: [], unreadable: 0 };
+  let names;
+  try {
+    names = readdirSync(dir).filter((n) => n.endsWith('.json'));
+  } catch {
+    return { entries: [], unreadable: 0 };
+  }
+  const entries = [];
+  let unreadable = 0;
+  for (const name of names) {
+    try {
+      const raw = readFileSync(join(dir, name), 'utf8');
+      const entry = JSON.parse(raw);
+      if (entry?.version !== PENDING_VERSION || typeof entry.path !== 'string') {
+        unreadable++;
+        continue;
+      }
+      entries.push({ name, raw, entry });
+    } catch {
+      unreadable++;
+    }
+  }
+  return { entries, unreadable };
+}
+
+/**
+ * Drop entries a staged run has just reviewed — only when the recorded blob is the one staged now.
+ * That is a commit aborted (typecheck failed in parallel, say) and retried as it was: the skipped
+ * content is exactly what was reviewed. If the skipped commit landed instead, its change is in HEAD
+ * and absent from the new diff, so this review did not look at it and the entry must stay.
+ */
+export function clearReviewed(paths, cwd = process.cwd()) {
+  try {
+    const dir = pendingDir(cwd);
+    if (!dir) return;
+    const worktree = worktreeOf(cwd);
+    for (const path of paths) {
+      const file = join(dir, entryName(worktree, path));
+      let entry;
+      try {
+        entry = JSON.parse(readFileSync(file, 'utf8'));
+      } catch {
+        continue;
+      }
+      const staged = git(['rev-parse', `:${path}`], worktree).trim();
+      if (entry.blob && entry.blob === staged) rmSync(file, { force: true });
+    }
+  } catch {
+    /* best effort: a stale entry is re-checked later, never lost */
+  }
+}
+
+/**
+ * Drop an entry read earlier, but only if it has not been re-recorded since — a commit that skipped
+ * the same path while `--pending` ran has content this run did not review.
+ */
+export function clearEntry({ name, raw }, cwd = process.cwd()) {
+  const dir = pendingDir(cwd);
+  if (!dir) return;
+  const file = join(dir, name);
+  try {
+    if (readFileSync(file, 'utf8') === raw) rmSync(file, { force: true });
+  } catch {
+    /* already gone */
+  }
+}
+
+/**
+ * The content an entry stands for: the staged blob, else the working-tree file.
+ * Returns { content } or { gone: reason }.
+ */
+export function contentOf(entry, cwd = process.cwd()) {
+  if (entry.blob) {
+    try {
+      return { content: git(['cat-file', '-p', entry.blob], cwd) };
+    } catch {
+      /* pruned by gc — fall through to the working tree */
+    }
+  }
+  try {
+    return { content: readFileSync(join(entry.worktree, entry.path), 'utf8') };
+  } catch {
+    return { gone: 'neither the staged blob nor the file exists any more' };
+  }
+}

package/src/prompt.mjs

@@ -8,12 +8,51 @@ const RULES_DIR = join(
 );
 const MAX_TOTAL_BYTES = 160_000;
 
-export function loadRules() {
-  return readdirSync(RULES_DIR)
+// Named per level so the prompt never cites a check the level left out — an agent told that
+// "incomplete claimed ARIA patterns" are errors reviews ARIA patterns whether or not they are listed.
+const SEVERITY_EXAMPLES = {
+  core: 'keyboard-dead interactive elements, missing accessible names on icon-only controls, focus not managed on overlays',
+  full: 'keyboard-dead interactive elements, missing accessible names on icon-only controls, incomplete claimed ARIA patterns, focus not managed on overlays, informative images silenced',
+};
+
+const LEVEL_TAG = /^`\[(core|full)\]`/;
+
+/**
+ * One rule file cut down to a level. `full` is the file as written. `core` keeps the numbered
+ * semantic checks and the example subsections tagged `[core]`, and drops a file with none — so what
+ * the agent is shown is only what it is asked to check. Numbers are kept, because other files refer
+ * to checks by number ("rules/03 §2").
+ */
+export function filterRule(text, level) {
+  if (level === 'full') return text;
+  const sections = text.split(/(?=^## )/m);
+  let kept = 0;
+  const out = sections.map((section) => {
+    if (section.startsWith('## Semantic checks')) {
+      const [intro, ...items] = section.split(/(?=^\d+\. )/m);
+      const chosen = items.filter((item) => item.replace(/^\d+\. /, '').match(LEVEL_TAG)?.[1] === level);
+      kept += chosen.length;
+      return intro + chosen.join('');
+    }
+    if (section.startsWith('## Examples')) {
+      const [intro, ...subsections] = section.split(/(?=^### )/m);
+      const chosen = subsections.filter((sub) => sub.replace(/^### /, '').match(LEVEL_TAG)?.[1] === level);
+      return chosen.length ? intro + chosen.join('') : '';
+    }
+    return section;
+  });
+  return kept === 0 ? null : out.join('');
+}
+
+/** The rule files at `level`, joined, and the ids of the categories that survived. */
+export function loadRules(level = 'full') {
+  const files = readdirSync(RULES_DIR)
     .filter((name) => name.endsWith('.md'))
     .sort()
-    .map((name) => readFileSync(join(RULES_DIR, name), 'utf8'))
-    .join('\n\n---\n\n');
+    .map((name) => filterRule(readFileSync(join(RULES_DIR, name), 'utf8'), level))
+    .filter((text) => text !== null);
+  const ids = files.map((text) => text.match(/^id: (\S+)$/m)?.[1]).filter(Boolean);
+  return { text: files.join('\n\n---\n\n'), ids };
 }
 
 function numbered(content) {
@@ -27,26 +66,26 @@ function numbered(content) {
  * 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();
+export function buildPrompt(files, { level = 'full' } = {}) {
+  const { text: rules, ids } = loadRules(level);
   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) {
+    const fileBlock = [`### FILE: ${file.path}`, '```', numbered(file.content), '```'].join('\n');
+    const withDiff = file.diff
+      ? `${fileBlock}\n#### Staged diff for ${file.path} (focus your review here)\n\`\`\`diff\n${file.diff}\n\`\`\``
+      : fileBlock;
+    // Content is capped at 48KB and a diff is not, so a rewrite can make one file's block larger
+    // than the whole budget — dropped every time, including on every `--pending` re-check. Without
+    // its diff it always fits an empty budget, so it is reviewed whole rather than never.
+    const block = [withDiff, fileBlock].find((b) => Buffer.byteLength(b, 'utf8') <= budget);
+    if (!block) {
       dropped.push(file.path);
       continue;
     }
-    budget -= size;
+    budget -= Buffer.byteLength(block, 'utf8');
     included.push(block);
   }
 
@@ -68,13 +107,13 @@ 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",
+  "ruleId": "one of: ${ids.join(' | ')}",
   "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 [].`;
+Severity discipline: "error" only for clear violations named as error in the rules (${SEVERITY_EXAMPLES[level]}). Judgment calls are "warning". ${level === 'core' ? 'Check only the rules above; this project has chosen not to review the others, so do not report them. ' : ''}If the code is clean, respond with [].`;
 
   return { prompt, dropped };
 }

package/src/report.mjs

@@ -31,9 +31,20 @@ export function parseFindings(text) {
   return { error: 'could not parse agent output as a findings array' };
 }
 
-export function printReport(findings, { agentName } = {}) {
+/**
+ * `report: 'errors'` shows errors only and says how many warnings it held back — the count, so a
+ * clean-looking run is not mistaken for a run that found nothing.
+ */
+export function printReport(allFindings, { agentName, report = 'all' } = {}) {
+  const findings = report === 'errors' ? allFindings.filter((f) => f.severity === 'error') : allFindings;
+  const hidden = allFindings.length - findings.length;
+  // On the last line, beside the totals it qualifies: printed above the report, the count was
+  // followed by a footer saying "0 warning(s)" — a clean-looking run again.
+  const hiddenNote = hidden ? `, ${YELLOW}${hidden} warning(s) hidden${RESET} ${DIM}(report: errors)${RESET}` : '';
   if (findings.length === 0) {
-    console.log(`a11y-lens: no findings ${DIM}(reviewed by ${agentName})${RESET}`);
+    console.log(hidden
+      ? `a11y-lens: no errors${hiddenNote} ${DIM}(reviewed by ${agentName})${RESET}`
+      : `a11y-lens: no findings ${DIM}(reviewed by ${agentName})${RESET}`);
     return;
   }
   const byFile = new Map();
@@ -56,7 +67,7 @@ export function printReport(findings, { agentName } = {}) {
   const warnings = findings.length - errors;
   console.log(
     `\na11y-lens: ${errors ? RED : ''}${errors} error(s)${RESET}, ` +
-    `${warnings ? YELLOW : ''}${warnings} warning(s)${RESET} ` +
+    (hidden ? `${hiddenNote.slice(2)} ` : `${warnings ? YELLOW : ''}${warnings} warning(s)${RESET} `) +
     `${DIM}(reviewed by ${agentName})${RESET}`,
   );
 }

package/src/staged.mjs

@@ -58,7 +58,7 @@ export function collectStagedUIFiles() {
 
     let diff = '';
     try {
-      diff = git(['diff', '--cached', '--unified=3', '--', path]);
+      diff = git(['diff', '--cached', '--unified=3', '--', `:(top)${path}`]);
     } catch {
       /* diff is best-effort context */
     }

package/templates/agents-snippet.md

@@ -12,6 +12,8 @@ When writing or modifying UI code (JSX/TSX/HTML/Vue/Svelte), apply the rule set
 - `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
 
+Each check is tagged `[core]` or `[full]`. If this project's `a11y-lens.config.json` (or the `"a11y-lens"` field of `package.json`) sets `"level": "core"`, apply only the `[core]` checks — the commit-time review checks nothing else.
+
 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.