@binclusive/a11y 0.1.0 → 0.1.1

package/README.md

@@ -4,7 +4,7 @@ A local accessibility checker for React/TSX code, grounded in a real-world audit
 
 > **It runs entirely on your machine. No network, no account, no upload — your code never leaves the laptop.** That's not a privacy policy, it's how it's built: there's nothing to upload. Point it at a private repo with zero hesitation.
 
-This is a private review build. Clone it, point it at any React codebase (yours, ours), and see what it finds — no setup, no explanation needed.
+This is a private review build. Clone it, point it at any React codebase (yours or ours), and see what it finds — no setup, no explanation needed.
 
 > **New here? Start with the [Getting Started](docs/GETTING-STARTED.md) walkthrough.** Zero to your first fix — install, `init`, wire your editor, read a finding, clear it, gate CI.
 
@@ -12,11 +12,11 @@ This is a private review build. Clone it, point it at any React codebase (yours,
 
 ## See it in 30 seconds
 
-On **an open-source component library's own demo app**, `eslint-plugin-jsx-a11y` (the linter everyone runs) passes the docs search box **clean** — while a11y-checker catches its unlabeled `<Input>`, ranks it (`22/26 orgs`), and hands you the fix.
+On **shadcn/ui's own `taxonomy` app**, `eslint-plugin-jsx-a11y` (the linter everyone runs) passes the docs search box **clean** — while a11y-checker catches its unlabeled `<Input>`, ranks it (`22/26 orgs`), and hands you the fix.
 
-![a11y-checker vs eslint on a component library demo app](demo/component-library.gif)
+![a11y-checker vs eslint on shadcn/ui taxonomy](demo/taxonomy.gif)
 
-**▶ [Watch all five demos →](demo/README.md)** — the head-to-head above, a getting-started walkthrough on an open-source monorepo, the `binclusive.json` config reference, the state of accessibility across 31 OSS repos, and the agentic self-fix loop. Each is a replayable [asciinema](https://asciinema.org) cast (`asciinema play demo/<name>.cast`), not just a GIF.
+**▶ [Watch all five demos →](demo/README.md)** — the head-to-head above, a getting-started walkthrough on the cal.com monorepo, the `binclusive.json` config reference, the state of accessibility across 31 OSS repos, and the agentic self-fix loop. Each is a replayable [asciinema](https://asciinema.org) cast (`asciinema play demo/<name>.cast`), not just a GIF.
 
 ---
 
@@ -33,7 +33,7 @@ That's the whole thing. It scans every `.tsx` under the folder and prints a cove
 
 No clone handy? Point it at this repo's own test fixtures: `pnpm scan ./test/fixtures`.
 
-> **No React source?** (A live site, an ASP.NET/Razor app, plain HTML.) The same checker can render a real page in a browser and audit the live DOM — `pnpm scan:url https://example.com`. See **[Auditing HTML & live pages (non-React)](#auditing-html--live-pages-non-react)** below.
+> **No React source?** (A live site, an ASP.NET/Razor app, plain HTML.) The same checker can render a real page in a browser and audit the live DOM — `pnpm scan:url https://www.example.com`. See **[Auditing HTML & live pages (non-React)](#auditing-html--live-pages-non-react)** below.
 
 > **Using your own design system?** (Almost everyone is.) A cold scan leaves most of your components in `declare` — *that's expected, not a failure.* To turn on its best trick (finding bugs *inside* your own components), it needs to know which of your components are buttons, inputs, etc. You don't write that by hand:
 >
@@ -88,19 +88,19 @@ There's also a **second producer**: a rendered-DOM collector that drives a real
 
 ## Auditing HTML & live pages (non-React)
 
-The scan above works on `.tsx` source. But not every page *has* React source on disk — a deployed customer site, an ASP.NET/Razor app, a plain HTML/Bootstrap/jQuery page. For those, point the checker at the **rendered page** instead of the source:
+The scan above works on `.tsx` source. But not every page *has* React source on disk — a deployed site, an ASP.NET/Razor app, a plain HTML/Bootstrap/jQuery page. For those, point the checker at the **rendered page** instead of the source:
 
 ```bash
 pnpm exec playwright install chromium   # one-time: the browser the render path drives
 ```
 
 ```bash
-pnpm scan:url https://example.com       # any deployed URL
+pnpm scan:url https://www.example.com   # a deployed site
 pnpm scan:url http://localhost:5000     # your local dev server
 pnpm scan:url ./wwwroot/index.html      # a local static .html file (bare path works)
 ```
 
-`<target>` takes an `http(s)://` URL, a `file://` URL, or a **bare local path** (auto-converted to `file://`). Under the hood it renders the page in real Chromium (via Playwright), runs **axe-core** against the live DOM, then flows every finding through the *same* corpus / WCAG / enforcement machinery as the source scan — so a contrast bug on example.com comes back tiered and gated exactly like a missing label in your `.tsx`.
+`<target>` takes an `http(s)://` URL, a `file://` URL, or a **bare local path** (auto-converted to `file://`). Under the hood it renders the page in real Chromium (via Playwright), runs **axe-core** against the live DOM, then flows every finding through the *same* corpus / WCAG / enforcement machinery as the source scan — so a contrast bug on a live site comes back tiered and gated exactly like a missing label in your `.tsx`.
 
 This is the source-less path — one command audits any live site, React or not.
 
@@ -136,7 +136,7 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - id: a11y
-        uses: Binclusive/a11y-checker-plugin@main
+        uses: Binclusive/a11y@main
       - if: always()  # advisory gate exits 0; upload regardless of findings
         uses: github/codeql-action/upload-sarif@v3
         with:
@@ -148,6 +148,12 @@ provenance (`deterministic` vs `agent`) in the SARIF property bag. The SARIF
 file exists only to render on **your** GitHub — it carries file/line for local
 annotation and is never sent to the Binclusive dashboard.
 
+> **Pin for supply-chain safety.** The examples use `@main` for readability, but
+> production workflows should pin the Action to a commit SHA — `uses:
+> Binclusive/a11y@<sha>  # v0.1.0` — rather than a floating tag or
+> branch, so a compromised upstream tag can't silently change what runs in your
+> CI. Dependabot (`github-actions` ecosystem) will bump the pin for you.
+
 ### Optional — opt into a blocking check (default off)
 
 The check is **non-blocking by default**: it exits 0 on any severity or volume of
@@ -163,7 +169,7 @@ way.
 
 ```yaml
       - id: a11y
-        uses: Binclusive/a11y-checker-plugin@main
+        uses: Binclusive/a11y@main
         with:
           fail-on: critical    # optional — block only on critical findings
           # max-violations: 0  # optional — block on any finding at all
@@ -188,7 +194,7 @@ means "lane off", never an error; the scan still exits 0.
 
 ```yaml
       - id: a11y
-        uses: Binclusive/a11y-checker-plugin@main
+        uses: Binclusive/a11y@main
         with:
           llm-api-key:  ${{ secrets.LLM_API_KEY }}  # optional — your BYOK model key
           llm-model:    ""                          # optional — override the model
@@ -218,7 +224,7 @@ does not, and nothing new crosses the wire.
 
 ```yaml
       - id: a11y
-        uses: Binclusive/a11y-checker-plugin@main
+        uses: Binclusive/a11y@main
         with:
           binclusive-app-id:          ${{ vars.BINCLUSIVE_APP_ID }}
           binclusive-app-private-key: ${{ secrets.BINCLUSIVE_APP_PRIVATE_KEY }}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@binclusive/a11y",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Local accessibility checker for React/TSX, grounded in axe-core's published rule catalog. Runs entirely on your machine — no network, no upload.",
   "main": "./src/index.ts",
@@ -15,7 +15,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Binclusive/a11y-checker-plugin.git"
+    "url": "git+https://github.com/Binclusive/a11y.git"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -56,6 +56,8 @@
     "mcp": "tsx ./src/mcp.ts",
     "gen:baseline": "tsx ./src/baseline/gen-baseline.ts",
     "typecheck": "tsc --noEmit",
+    "decisions:check": "tsx ./scripts/check-decisions.ts",
+    "check:action-pin": "node ./scripts/check-action-pin.mjs",
     "test": "vitest run",
     "//test:e2e": "Rendered-DOM e2e (real Chromium). Excluded from `test`. CI must run `npx playwright install chromium` first.",
     "test:e2e": "vitest run --config vitest.e2e.config.ts",
@@ -63,6 +65,9 @@
     "matrix:run": "tsx experiments/stack-matrix/run.ts",
     "matrix:report": "tsx experiments/stack-matrix/report.ts",
     "matrix:baseline": "tsx experiments/stack-matrix/baseline.ts",
-    "matrix:check": "tsx experiments/stack-matrix/check.ts"
+    "matrix:check": "tsx experiments/stack-matrix/check.ts",
+    "android:matrix:run": "tsx experiments/android-matrix/run.ts",
+    "android:matrix:baseline": "tsx experiments/android-matrix/baseline.ts",
+    "android:matrix:check": "tsx experiments/android-matrix/check.ts"
   }
 }

package/src/cli.ts

@@ -6,6 +6,7 @@ import { Effect, Option } from "effect";
 import type { Impact } from "@binclusive/a11y-contract";
 import { type AgentLaneOverrides, augmentWithAgentLane } from "./agent-lane";
 import { collectTsx } from "./collect";
+import { scanAndroidXml } from "./collect-android-xml";
 // Type-only: the rendered-DOM lane (playwright/@axe-core) is loaded lazily inside
 // `runCheckUrl` so the static `check` path carries no eager browser-stack import
 // and the CI image can ship without it (issue #2133).
@@ -17,9 +18,10 @@ import { collectUnityFindings } from "./unity-findings";
 import { type FindingProvenance, scan } from "./core";
 import { type Evidence, type EnrichedFinding, enrichAll, evidenceImpact, resolveDisplay } from "./evidence";
 import { runHookCli } from "./hook";
-import { phoneHome } from "./phone-home";
+import { type PhoneHomeDeps, phoneHome } from "./phone-home";
 import { formatSarif } from "./sarif";
 import {
+  GATE_ADVISORY,
   GATE_OFF,
   type GateConfig,
   gateExitCode,
@@ -47,10 +49,14 @@ export function detailLines(f: EnrichedFinding): string[] {
         : f.provenance === "swiftui"
           ? "  (SwiftUI static)"
           : "";
+  // Impact-first voice (#14): the message LEADS — it names the harmed user and
+  // the human consequence, the first thing a reader sees under the location. The
+  // rule id and WCAG SC follow as SECONDARY lines (and the corpus block further
+  // below), so the identifiers frame the finding without burying the impact.
   const lines = [
+    `    ${f.message}`,
     `    rule:   ${f.ruleId}  [${f.enforcement}]${via}`,
     `    wcag:   ${scList}`,
-    `    ${f.message}`,
   ];
 
   // The display contract resolves the axe-vs-SC policy once (see resolveDisplay):
@@ -355,6 +361,66 @@ export function buildJsonReport(
   };
 }
 
+/**
+ * The zeroed coverage literal for a stack with no component resolver (Liquid,
+ * Unity) or an empty scan — the `--json`/`buildJsonReport` shape stays identical
+ * to `check` even when there is nothing to resolve.
+ */
+const EMPTY_COVERAGE: Coverage = {
+  total: 0,
+  declared: 0,
+  registry: 0,
+  traced: 0,
+  opaque: 0,
+  trusted: 0,
+  icons: 0,
+  structural: 0,
+  declare: 0,
+};
+
+/** The run context a machine-readable emit needs, threaded from each stack runner. */
+interface EmitContext {
+  readonly root: string;
+  readonly runId: string;
+  readonly filesScanned: number;
+  readonly coverage: Coverage;
+  /** ABSOLUTE paths this run analyzed — phone-home relativizes them into `scannedPaths` (ADR 0043). */
+  readonly analyzedFiles: readonly string[];
+  readonly gate: GateConfig;
+  /** Test-only seam: override phone-home transport deps to capture the projected wire batch (#163 tracer). */
+  readonly phoneHome?: Partial<PhoneHomeDeps>;
+}
+
+/**
+ * The ONE machine-readable emit path, shared by every stack runner (#163). SARIF
+ * and phone-home are the only two consumers that carry findings off the machine,
+ * and both narrow through the canonical `@binclusive/a11y-contract` vocabulary —
+ * so a new stack (`check-shopify`, and next `check-swift`/`check-unity`/…) reaches
+ * the wire by routing HERE, never by re-forking a bespoke `buildJsonReport`→stdout
+ * path. `text` is intentionally excluded: the human report differs per stack and
+ * stays in each runner.
+ */
+async function emitFindings(
+  format: "json" | "sarif",
+  findings: readonly EnrichedFinding[],
+  ctx: EmitContext,
+): Promise<void> {
+  if (format === "sarif") {
+    console.log(formatSarif(findings, ctx.runId, { root: ctx.root }));
+  } else {
+    console.log(JSON.stringify(buildJsonReport(ctx.root, ctx.filesScanned, ctx.coverage, findings), null, 2));
+    // OPTIONAL, non-blocking phone-home (#2108): file metadata-only findings to the
+    // dashboard when the CI env carries a `b8e_` token + org/project. Env-gated, so a
+    // local run silently skips; a failure is swallowed inside `phoneHome` and never
+    // changes the exit code. Inject this run's analyzed set (ADR 0043) as `scannedPaths`.
+    await phoneHome(findings, ctx.root, process.env, {
+      analyzedFiles: () => [...ctx.analyzedFiles],
+      ...ctx.phoneHome,
+    });
+  }
+  process.exitCode = gateExitCode(findings.map(toGateFinding), ctx.gate);
+}
+
 /**
  * The shared report tail for both runners (source + rendered-DOM): empty-state,
  * grouped findings, the totals rollup, and the blocking-gated exit code. Each
@@ -430,14 +496,13 @@ export async function runCheck(
     // Non-blocking — agent findings are warn-only, so the block-gated exit is
     // computed on the augmented list and can only reflect the deterministic floor.
     const findings = await augmentWithAgentLane(deterministic, root, process.env, agentOverrides);
-    console.log(formatSarif(findings, runId, { root }));
-    process.exitCode = gateExitCode(findings.map(toGateFinding), gate);
+    await emitFindings("sarif", findings, { root, runId, filesScanned: files.length, coverage: EMPTY_COVERAGE, analyzedFiles: [], gate });
     return;
   }
 
   if (json) {
     if (files.length === 0) {
-      const report = buildJsonReport(root, 0, { total: 0, declared: 0, registry: 0, traced: 0, opaque: 0, trusted: 0, icons: 0, structural: 0, declare: 0 }, []);
+      const report = buildJsonReport(root, 0, EMPTY_COVERAGE, []);
       console.log(JSON.stringify(report, null, 2));
       return;
     }
@@ -445,18 +510,17 @@ export async function runCheck(
     const deterministic = enrichAll(result.findings);
     // AI lane (issue #2182): agent findings flow through the SAME JSON report and
     // phone-home envelope as the deterministic floor. When no key is present this
-    // returns `deterministic` unchanged.
+    // returns `deterministic` unchanged. Inject this run's true analyzed set (ADR
+    // 0043) so phone-home emits it as `scannedPaths` — 4b's reconcile keys on it.
     const findings = await augmentWithAgentLane(deterministic, root, process.env, agentOverrides);
-    const report = buildJsonReport(root, files.length, result.coverage, findings);
-    console.log(JSON.stringify(report, null, 2));
-    // OPTIONAL, non-blocking phone-home (#2108): file metadata-only findings to
-    // the dashboard when the CI env carries a `b8e_` token + org/project. Fully
-    // env-gated, so a local `check --json` (no such env) silently skips; a
-    // failure here is swallowed inside `phoneHome` and never changes exit code.
-    // Inject this run's true analyzed set (ADR 0043) so phone-home emits it as
-    // `scannedPaths` — the source-scan-scope coverage 4b's reconcile keys on.
-    await phoneHome(findings, root, process.env, { analyzedFiles: () => result.analyzedFiles });
-    process.exitCode = gateExitCode(findings.map(toGateFinding), gate);
+    await emitFindings("json", findings, {
+      root,
+      runId,
+      filesScanned: files.length,
+      coverage: result.coverage,
+      analyzedFiles: result.analyzedFiles,
+      gate,
+    });
     return;
   }
 
@@ -504,8 +568,16 @@ function normalizeTarget(target: string): string {
  * selectors instead of source lines. This is the source-less path — it inspects
  * what actually ships, so it covers non-React pages and anything the static
  * .tsx scan can't see (server-rendered markup, third-party widgets, runtime DOM).
+ *
+ * The optional {@link PhoneHomeDeps} overrides mirror `runCheck`'s `agentOverrides`
+ * seam: the CLI handler never passes them (phone-home resolves its config + fetch
+ * from the env), but the behavioral tracer test injects a stub `fetch` to prove a
+ * real rendered-URL finding reaches the wire as a page-shaped contract.
  */
-async function runCheckUrl(url: string): Promise<void> {
+export async function runCheckUrl(
+  url: string,
+  phoneHomeOverrides: Partial<PhoneHomeDeps> = {},
+): Promise<void> {
   const target = normalizeTarget(url);
   console.log(`a11y-checker — rendering ${target} and running axe-core\n`);
 
@@ -532,6 +604,21 @@ async function runCheckUrl(url: string): Promise<void> {
     groupHeader: (ruleId) => ruleId,
     formatItem: (f) => formatUrlFinding(f),
   });
+
+  // OPTIONAL, non-blocking phone-home (#2335): route the rendered-URL findings
+  // through the SAME emit seam the static `check --json` path uses. Inside
+  // `phoneHome`, `toFindingPayloadLenient` → `resolveLocations` branches each
+  // `^https?://` finding to the canonical page-shaped `{ location: { kind: "page",
+  // url }, … }` contract and POSTs it when the CI env carries a `b8e_` token +
+  // org/project. Fully env-gated, swallows its own failures, and never touches the
+  // exit code the gate above set. The scanned page IS the scanned target — the
+  // same `url` vocabulary platform-side scope-reconcile keys on (#2166). `root` is
+  // the cwd: page findings resolve their location from the URL, not `root`, and a
+  // URL scan analyzes no source files (`scannedPaths` stays the safe empty set).
+  await phoneHome(findings, process.cwd(), process.env, {
+    scanTargets: () => [target],
+    ...phoneHomeOverrides,
+  });
 }
 
 /**
@@ -577,22 +664,32 @@ async function runCheckSwift(dir: string): Promise<void> {
  * has no component resolver, so coverage is zeroed in the `--json` shape. A file
  * the parser rejects is skipped (surfaced as a count), never fatal.
  */
-async function runCheckShopify(dir: string, json = false): Promise<void> {
+export async function runCheckShopify(
+  dir: string,
+  format: OutputFormat = "text",
+  runId = "local",
+  phoneHomeOverrides: Partial<PhoneHomeDeps> = {},
+): Promise<void> {
   const { root, files, findings: raw, parseErrors } = await scanLiquid(dir);
   const findings = enrichAll(raw);
 
-  if (json) {
-    // Liquid carries no resolver coverage — emit the zeroed coverage literal so
-    // the JSON shape stays identical to `check`.
-    const report = buildJsonReport(
+  if (format !== "text") {
+    // Route the Liquid scan through the SAME canonical emit path `check` uses
+    // (#163): SARIF or the JSON report + `toContractFinding` phone-home projection,
+    // so a Shopify scan hands real `@binclusive/a11y-contract` findings to a real
+    // consumer instead of a bespoke `buildJsonReport`→stdout report. Liquid carries
+    // no component resolver (zeroed coverage) and the whole scanned set is analyzed.
+    // Non-blocking (`GATE_ADVISORY`): the stack scan reports, it doesn't gate (exit
+    // 0 even with findings) — the opt-in blocking gate is a noted follow-up (#163 AC).
+    await emitFindings(format, findings, {
       root,
-      files.length,
-      { total: 0, declared: 0, registry: 0, traced: 0, opaque: 0, trusted: 0, icons: 0, structural: 0, declare: 0 },
-      findings,
-    );
-    console.log(JSON.stringify(report, null, 2));
-    const blocking = findings.filter((f) => f.enforcement === "block").length;
-    process.exitCode = blocking > 0 ? 1 : 0;
+      runId,
+      filesScanned: files.length,
+      coverage: EMPTY_COVERAGE,
+      analyzedFiles: files,
+      gate: GATE_ADVISORY,
+      phoneHome: phoneHomeOverrides,
+    });
     return;
   }
 
@@ -654,6 +751,29 @@ async function runCheckUnity(dir: string, json = false): Promise<void> {
   });
 }
 
+/**
+ * The Android counterpart to `runCheck`: statically scan an Android project's
+ * `res/layout*` XML in-process (`scanAndroidXml`), enrich through the SAME corpus
+ * cross-ref, and report findings anchored on `file:line` like every other
+ * producer. No browser, no network, no second toolchain — Android layouts are
+ * plain XML parsed in Node. A missing or unreadable project dir is an empty scan,
+ * never a throw. The collector returns the canonical `root` it scanned so
+ * `relative(root, …)` renders clean `app/src/main/res/layout/…:line` locations.
+ */
+async function runCheckAndroid(dir: string): Promise<void> {
+  const { root, findings: raw } = await scanAndroidXml(dir);
+  console.log(`a11y-checker — scanning res/layout XML under ${root} for Android a11y\n`);
+
+  const findings = enrichAll(raw);
+
+  renderReport(findings, {
+    emptyMessage: "No Android XML a11y violations found.",
+    groupKey: (f) => f.file,
+    groupHeader: (file) => relative(root, file),
+    formatItem: (f) => formatFinding(f, root),
+  });
+}
+
 async function runInit(suggest: boolean, dirArg: string): Promise<void> {
   const dir = resolve(dirArg);
   const r = await init(dir, { suggest });
@@ -877,11 +997,21 @@ const checkSwiftCommand = Command.make(
 
 const checkShopifyCommand = Command.make(
   "check-shopify",
-  { dir: dirArg, json: Options.boolean("json") },
-  ({ dir, json }) => Effect.promise(() => runCheckShopify(dir, json)),
+  {
+    dir: dirArg,
+    json: Options.boolean("json"),
+    sarif: Options.boolean("sarif"),
+    format: formatOption,
+    runId: Options.text("run-id").pipe(Options.withDefault("local")),
+  },
+  ({ dir, json, sarif, format, runId }) =>
+    // Reuse the CANONICAL `--format text|json|sarif` selector (`--json`/`--sarif`
+    // aliases) the default `check` uses, so the Shopify scan reaches SARIF + the
+    // phone-home contract projection through the SAME path, not a bespoke flag (#163).
+    Effect.promise(() => runCheckShopify(dir, resolveFormat(format, json, sarif), runId)),
 ).pipe(
   Command.withDescription(
-    "scan .liquid Shopify theme source for structural a11y findings (static, no browser; --json: machine-readable)",
+    "scan .liquid Shopify theme source for structural a11y findings (static, no browser; --format text|json|sarif, canonical — routes findings through the same canonical contract wire path as `check`)",
   ),
 );
 
@@ -895,6 +1025,16 @@ const checkUnityCommand = Command.make(
   ),
 );
 
+const checkAndroidCommand = Command.make(
+  "check-android",
+  { dir: dirArg },
+  ({ dir }) => Effect.promise(() => runCheckAndroid(dir)),
+).pipe(
+  Command.withDescription(
+    "scan Android res/layout XML for accessibility findings (static, in-process — no browser, no toolchain)",
+  ),
+);
+
 const initCommand = Command.make(
   "init",
   { suggest: Options.boolean("suggest"), dir: optionalDir },
@@ -976,6 +1116,7 @@ const rootCommand = Command.make("a11y-checker", { dir: rootDir }, ({ dir }) =>
     checkSwiftCommand,
     checkShopifyCommand,
     checkUnityCommand,
+    checkAndroidCommand,
     initCommand,
     learnCommand,
     genCommand,

package/src/collect-android-xml.ts

@@ -0,0 +1,447 @@
+/**
+ * The Android XML layout STATIC collector — an IN-PROCESS producer of
+ * {@link Finding}s, parallel to `collect-swift.ts` (SwiftUI) and
+ * `collect-liquid.ts` (Shopify Liquid).
+ *
+ * Unlike the SwiftUI collector — which shells to an out-of-process SwiftSyntax
+ * binary because SwiftSyntax can't run from Node — Android layouts are plain XML
+ * and parse perfectly well in-process, so there is NO second toolchain here: a
+ * thin line-aware element scanner ({@link parseAndroidLayout}) walks each
+ * layout file into a node tree, and two structural-absence rules read each
+ * element's attributes (and, for controls, its subtree) to decide whether it
+ * carries an accessible name.
+ *
+ * The two rules mirror the SwiftUI two-rule shape (#109):
+ *   - `android-xml/image-no-label` (WCAG 1.1.1) — an image-presenting widget
+ *     (`ImageView` / `ImageButton`) that exposes no `android:contentDescription`.
+ *     A decorative opt-out — `contentDescription="@null"` or
+ *     `importantForAccessibility="no"` — is honored, not flagged.
+ *   - `android-xml/control-no-name` (WCAG 4.1.2) — an interactive control (a
+ *     `Button` / `ImageButton`, or any element marked `android:clickable="true"`)
+ *     that exposes no accessible name. The name may come from the control itself
+ *     (`contentDescription` / `android:text` / `android:hint`) OR — for a
+ *     clickable CONTAINER — from a descendant that carries text or a
+ *     contentDescription (Android announces a clickable group by its labeled
+ *     children). This descendant-climb is the Android analog of the SwiftUI
+ *     collector's ancestor-climb: it stops a label on a child from reading as a
+ *     false positive on the wrapping clickable group.
+ *
+ * Both rules honor Android lint's own suppression seam: `tools:ignore="ContentDescription"`
+ * on an element — or on any of its ancestors, exactly as Android Studio's lint
+ * scopes a suppression to a subtree — silences both rules for it, so the
+ * collector never re-flags what the team has already deliberately waived.
+ *
+ * An `ImageButton` is BOTH an image widget and a control, so an unlabeled one
+ * yields two findings on the same line (one per rule) — the proven prototype
+ * behavior the `experiments/android-matrix` corpus reproduces.
+ */
+
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve, sep } from "node:path";
+import { contractForFiles, enforcementFor } from "./config-scan";
+import type { Finding } from "./core";
+
+/** The two Android-XML static rule ids this collector emits. */
+export type AndroidXmlRuleId = "android-xml/image-no-label" | "android-xml/control-no-name";
+
+/** Build/generated dirs that are never layout source — skipped on the walk. The
+ * Android ones (`build`, `.gradle`, `.idea`) hold generated/merged resources;
+ * the rest match the other collectors' skip set. */
+const SKIP_DIRS = new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  ".gradle",
+  ".idea",
+  ".cxx",
+  "intermediates",
+]);
+
+/**
+ * A layout XML file is one named `*.xml` living directly inside a `res/layout…`
+ * directory: `res/layout/foo.xml`, `res/layout-land/foo.xml`,
+ * `res/layout-sw600dp/foo.xml`, etc. The resource-qualifier suffix on `layout`
+ * is arbitrary (orientation, size, locale…), so we match any directory whose
+ * name is `layout` or starts with `layout-`, and require its parent to be `res`
+ * — that pairing is what distinguishes a real Android layout resource from an
+ * unrelated `layout/` directory elsewhere in a tree.
+ */
+export function isAndroidLayoutFile(absPath: string): boolean {
+  if (!absPath.endsWith(".xml")) return false;
+  const parts = absPath.split(sep);
+  if (parts.length < 3) return false;
+  const dir = parts[parts.length - 2] as string;
+  const parent = parts[parts.length - 3] as string;
+  const isLayoutDir = dir === "layout" || dir.startsWith("layout-");
+  return parent === "res" && isLayoutDir;
+}
+
+/**
+ * Recursively collect the `layout` resource `.xml` files under `dir`, skipping
+ * build/generated dirs. A missing or unreadable directory yields `[]` rather
+ * than throwing — a non-existent scan target is an empty scan, the forgiving
+ * contract the other collectors give the CLI.
+ */
+export async function collectAndroidLayoutFiles(dir: string): Promise<string[]> {
+  const out: string[] = [];
+  let entries: Awaited<ReturnType<typeof readdir>>;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out.push(...(await collectAndroidLayoutFiles(full)));
+    } else if (entry.isFile() && isAndroidLayoutFile(full)) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * One element from an Android layout, as a tree node: its local widget name (the
+ * last `.`-segment of a possibly-qualified tag —
+ * `androidx.appcompat.widget.AppCompatImageButton` → `AppCompatImageButton`),
+ * its attribute map (raw `name → value`, namespace prefix kept), the 1-based
+ * source `line` the `<` sits on (the location the rules report), and its child
+ * elements (empty for a self-closing/leaf element).
+ */
+export interface AndroidNode {
+  readonly name: string;
+  readonly line: number;
+  readonly attrs: ReadonlyMap<string, string>;
+  readonly children: readonly AndroidNode[];
+}
+
+interface MutableNode {
+  name: string;
+  line: number;
+  attrs: Map<string, string>;
+  children: MutableNode[];
+}
+
+/**
+ * Parse an Android layout XML string into a tree of element nodes, line-aware.
+ *
+ * A hand-rolled scanner (not a DOM parser) because the rules need the START-tag
+ * line + attributes + nesting, and a streaming scan keeps the exact line number
+ * of each `<` — the location the prototype reported and the corpus baseline
+ * pins. The scanner skips the `<?xml …?>` declaration, comments, CDATA, and
+ * doctypes; it reads attribute values respecting quotes, so a multi-line start
+ * tag (ubiquitous in Android layouts) is parsed as one element anchored on the
+ * line of its `<`. Returns the top-level node(s) — usually one root, but a
+ * `<merge>` or malformed file may yield several.
+ */
+export function parseAndroidLayout(source: string): AndroidNode[] {
+  const roots: MutableNode[] = [];
+  const stack: MutableNode[] = [];
+  const n = source.length;
+  let i = 0;
+  let line = 1;
+
+  const step = (): void => {
+    if (source[i] === "\n") line++;
+    i++;
+  };
+  const push = (node: MutableNode): void => {
+    const parent = stack[stack.length - 1];
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+  };
+
+  while (i < n) {
+    if (source[i] !== "<") {
+      step();
+      continue;
+    }
+    const next = source[i + 1];
+    if (next === "?") {
+      while (i < n && !(source[i] === "?" && source[i + 1] === ">")) step();
+      step();
+      step();
+      continue;
+    }
+    if (next === "!") {
+      if (source.startsWith("<!--", i)) {
+        while (i < n && !source.startsWith("-->", i)) step();
+        for (let k = 0; k < 3 && i < n; k++) step();
+      } else {
+        while (i < n && source[i] !== ">") step();
+        if (i < n) step();
+      }
+      continue;
+    }
+    if (next === "/") {
+      // closing tag </name> — pop one level
+      while (i < n && source[i] !== ">") step();
+      if (i < n) step();
+      if (stack.length > 0) stack.pop();
+      continue;
+    }
+
+    // an element start tag
+    const tagLine = line;
+    step(); // '<'
+    let name = "";
+    while (i < n && !/[\s/>]/.test(source[i] as string)) {
+      name += source[i];
+      step();
+    }
+    const attrs = new Map<string, string>();
+    let selfClosing = false;
+    while (i < n) {
+      while (i < n && /\s/.test(source[i] as string)) step();
+      if (i >= n) break;
+      if (source[i] === "/" && source[i + 1] === ">") {
+        selfClosing = true;
+        step();
+        step();
+        break;
+      }
+      if (source[i] === ">") {
+        step();
+        break;
+      }
+      let attrName = "";
+      while (i < n && !/[\s=/>]/.test(source[i] as string)) {
+        attrName += source[i];
+        step();
+      }
+      while (i < n && /\s/.test(source[i] as string)) step();
+      let attrValue = "";
+      if (source[i] === "=") {
+        step();
+        while (i < n && /\s/.test(source[i] as string)) step();
+        const quote = source[i];
+        if (quote === '"' || quote === "'") {
+          step();
+          while (i < n && source[i] !== quote) {
+            attrValue += source[i];
+            step();
+          }
+          if (i < n) step();
+        } else {
+          while (i < n && !/[\s/>]/.test(source[i] as string)) {
+            attrValue += source[i];
+            step();
+          }
+        }
+      }
+      if (attrName !== "") attrs.set(attrName, attrValue);
+    }
+
+    const local = name.includes(".") ? name.slice(name.lastIndexOf(".") + 1) : name;
+    if (local === "") continue;
+    const node: MutableNode = { name: local, line: tagLine, attrs, children: [] };
+    push(node);
+    if (!selfClosing) stack.push(node);
+  }
+  return roots;
+}
+
+/** Image-presenting widget names — the `android-xml/image-no-label` set. Matched
+ * on the bare widget name (`ImageView` / `ImageButton`); AppCompat/Material
+ * variants are intentionally NOT image widgets here (they are controls, caught by
+ * the control rule via their `clickable`/inherent-control status). */
+const IMAGE_WIDGETS = new Set(["ImageView", "ImageButton"]);
+
+/** Inherently-interactive control names — half of the `control-no-name` trigger
+ * (the other half is `android:clickable="true"`). `Button`/`ImageButton` are
+ * interactive regardless of an explicit `clickable` attribute. */
+const INHERENT_CONTROLS = new Set(["Button", "ImageButton"]);
+
+/** True when the element waives Android lint's `ContentDescription` check via its
+ * OWN `tools:ignore`. The value is a comma/space-separated id list; `ContentDescription`
+ * or `all` silences both rules. */
+function ownSuppressed(attrs: ReadonlyMap<string, string>): boolean {
+  const ignore = attrs.get("tools:ignore");
+  if (ignore === undefined) return false;
+  return ignore
+    .split(/[\s,]+/)
+    .some((id) => id === "ContentDescription" || id === "all");
+}
+
+/** An attribute is present and meaningful when set to a non-empty value. */
+const has = (attrs: ReadonlyMap<string, string>, key: string): boolean => {
+  const v = attrs.get(key);
+  return v !== undefined && v !== "";
+};
+
+/** True when an image widget carries a text alternative OR is explicitly marked
+ * decorative — either way it must NOT be flagged `image-no-label`. A
+ * `contentDescription` (including the `@null` decorative sentinel) or an
+ * `importantForAccessibility="no"` opt-out both satisfy 1.1.1. */
+function imageLabeled(attrs: ReadonlyMap<string, string>): boolean {
+  if (attrs.has("android:contentDescription")) return true;
+  if (attrs.get("android:importantForAccessibility") === "no") return true;
+  return false;
+}
+
+/** True when a control exposes its OWN accessible name — a `contentDescription`,
+ * a visible `android:text`, or a `android:hint`. */
+function controlNamedSelf(attrs: ReadonlyMap<string, string>): boolean {
+  if (attrs.has("android:contentDescription")) return true;
+  if (has(attrs, "android:text")) return true;
+  if (has(attrs, "android:hint")) return true;
+  // A design-time `tools:text` preview mirrors the text the control is populated
+  // with at runtime — so a control carrying one is named, even with no static
+  // `android:text` (the dominant pattern for runtime-bound labels/buttons).
+  if (has(attrs, "tools:text")) return true;
+  if (attrs.get("android:importantForAccessibility") === "no") return true;
+  return false;
+}
+
+/** True when a node is a text-presenting widget — a `TextView` (any variant:
+ * `AppCompatTextView`, a vendor `…TextView`, `CheckedTextView`) or an `EditText`.
+ * Its presence in a clickable group's subtree means the group is announced by
+ * that child's text even when the text is populated at runtime (no static
+ * `android:text`), which is the dominant pattern in list-item rows. */
+function isTextWidget(name: string): boolean {
+  return name.endsWith("TextView") || name.endsWith("EditText");
+}
+
+/** True when ANY element in the subtree (excluding `node` itself) provides text a
+ * screen reader would announce for the enclosing clickable group: a non-empty
+ * `android:text`, a `contentDescription` that is not the `@null` decorative
+ * sentinel, or a text-presenting widget (whose text is often set at runtime).
+ * This is the descendant-climb that keeps a labeled child from making its
+ * wrapping clickable container read as unnamed. */
+function subtreeProvidesName(node: AndroidNode): boolean {
+  for (const child of node.children) {
+    if (isTextWidget(child.name)) return true;
+    if (has(child.attrs, "android:text")) return true;
+    if (has(child.attrs, "tools:text")) return true;
+    const cd = child.attrs.get("android:contentDescription");
+    if (cd !== undefined && cd !== "" && cd !== "@null") return true;
+    if (subtreeProvidesName(child)) return true;
+  }
+  return false;
+}
+
+const isImageWidget = (name: string): boolean => IMAGE_WIDGETS.has(name);
+const isControl = (node: AndroidNode): boolean =>
+  INHERENT_CONTROLS.has(node.name) || node.attrs.get("android:clickable") === "true";
+
+/** One raw rule hit before it is mapped onto the shared `Finding` shape. */
+interface RawAndroidFinding {
+  readonly file: string;
+  readonly line: number;
+  readonly ruleId: AndroidXmlRuleId;
+}
+
+/** Per-rule WCAG SC + the human-facing message, keyed by rule id. */
+const RULE_META: Record<AndroidXmlRuleId, { wcag: readonly string[]; message: string }> = {
+  "android-xml/image-no-label": {
+    wcag: ["1.1.1"],
+    message:
+      'Image widget has no android:contentDescription — a screen reader announces nothing (set contentDescription, or contentDescription="@null" if purely decorative).',
+  },
+  "android-xml/control-no-name": {
+    wcag: ["4.1.2"],
+    message:
+      "Interactive control exposes no accessible name — add android:contentDescription (or android:text, or a labeled child) so assistive tech can announce it.",
+  },
+};
+
+/**
+ * Walk one parsed layout tree and apply the two rules, accumulating raw hits.
+ * `suppressedAbove` carries an ancestor's `tools:ignore="ContentDescription"`
+ * down the subtree, matching Android lint's subtree-scoped suppression. An
+ * `ImageButton` that is both an unlabeled image AND an unnamed control emits two
+ * findings on the same line — once per rule.
+ */
+function walkTree(
+  file: string,
+  node: AndroidNode,
+  suppressedAbove: boolean,
+  out: RawAndroidFinding[],
+): void {
+  const suppressed = suppressedAbove || ownSuppressed(node.attrs);
+  if (!suppressed) {
+    if (isImageWidget(node.name) && !imageLabeled(node.attrs)) {
+      out.push({ file, line: node.line, ruleId: "android-xml/image-no-label" });
+    }
+    if (isControl(node) && !controlNamedSelf(node.attrs) && !subtreeProvidesName(node)) {
+      out.push({ file, line: node.line, ruleId: "android-xml/control-no-name" });
+    }
+  }
+  for (const child of node.children) walkTree(file, child, suppressed, out);
+}
+
+/**
+ * Apply the two Android-XML rules to one parsed file's root nodes. `file` is
+ * carried through unchanged onto each finding so the caller controls the path
+ * namespace.
+ */
+export function findingsForRoots(file: string, roots: readonly AndroidNode[]): RawAndroidFinding[] {
+  const out: RawAndroidFinding[] = [];
+  for (const root of roots) walkTree(file, root, false, out);
+  return out;
+}
+
+/** Parse + rule a single layout source string — the unit-testable seam. */
+export function findingsForSource(file: string, source: string): RawAndroidFinding[] {
+  return findingsForRoots(file, parseAndroidLayout(source));
+}
+
+/**
+ * The full output of an Android-XML scan, parallel to `SwiftScanResult`: the
+ * findings plus the canonical `root` the collector scanned in (so the CLI renders
+ * `relative(root, …)` against the exact namespace the findings carry) and a
+ * `parseErrors` count for files that could not be read.
+ */
+export interface AndroidXmlScanResult {
+  readonly root: string;
+  readonly files: readonly string[];
+  readonly findings: readonly Finding[];
+  readonly parseErrors: number;
+}
+
+/**
+ * Scan the `layout` resource `.xml` files under `dir` for static Android-XML
+ * accessibility findings, in-process. Collects the layout files, parses each,
+ * applies the two rules, and maps every raw hit onto a full {@link Finding} —
+ * `provenance: "android-xml"`, the rule's WCAG SC, and the enforcement level the
+ * governing `binclusive.json` assigns that SC (or `block` with no contract, the
+ * historical default). One unreadable file is counted in `parseErrors` and the
+ * scan continues — a single bad file never aborts the scan.
+ */
+export async function scanAndroidXml(dir: string): Promise<AndroidXmlScanResult> {
+  const root = resolve(dir);
+  const files = await collectAndroidLayoutFiles(root);
+
+  const raw: RawAndroidFinding[] = [];
+  let parseErrors = 0;
+  for (const file of files) {
+    let source: string;
+    try {
+      source = await readFile(file, "utf8");
+    } catch {
+      parseErrors++;
+      continue;
+    }
+    raw.push(...findingsForSource(file, source));
+  }
+
+  // The contract that governs these files, found by walking up from them — same
+  // package-up rule the other collectors use. With no `binclusive.json` every
+  // finding is `block`.
+  const contract = contractForFiles(raw.map((f) => f.file));
+
+  const findings: Finding[] = raw.map((f) => ({
+    file: f.file,
+    line: f.line,
+    ruleId: f.ruleId,
+    message: RULE_META[f.ruleId].message,
+    wcag: RULE_META[f.ruleId].wcag,
+    enforcement: enforcementFor(RULE_META[f.ruleId].wcag, contract),
+    provenance: "android-xml",
+  }));
+
+  return { root, files, findings, parseErrors };
+}

package/src/contract.ts

@@ -18,8 +18,13 @@ export const CONTRACT_VERSION = 1 as const;
 /** Which Next.js router the repo uses, or `null` when not a Next app. */
 export type Router = "app" | "pages" | null;
 
-/** Source language of the repo, decided by tsconfig presence. */
-export type Language = "ts" | "js";
+/**
+ * Source language of the repo. `ts`/`js` are decided by tsconfig presence for a
+ * web project; `android-xml` is set when the repo is detected as an Android
+ * project (a Gradle/manifest layout with `res/layout*` resources), which routes
+ * it to the Android XML layout collector instead of the React/TSX path.
+ */
+export type Language = "ts" | "js" | "android-xml";
 
 /**
  * The detected stack. Every field is a best-effort signal from
@@ -134,8 +139,8 @@ function parseRouter(v: unknown): Router {
 }
 
 function parseLanguage(v: unknown): Language {
-  if (v === "ts" || v === "js") return v;
-  throw new ContractParseError(`stack.language must be "ts" or "js"`);
+  if (v === "ts" || v === "js" || v === "android-xml") return v;
+  throw new ContractParseError(`stack.language must be "ts", "js", or "android-xml"`);
 }
 
 function parseStack(v: unknown): Stack {

package/src/core.ts

@@ -22,6 +22,7 @@ import {
 } from "./config-scan";
 import type { Contract } from "./contract";
 import { enforceContent } from "./enforce";
+import { impactFirstJsxA11yMessage } from "./finding-voice";
 import { isRouterLinkControl } from "./registry";
 import {
   type ComponentResolution,
@@ -75,6 +76,7 @@ export type FindingProvenance =
   | "swiftui"
   | "liquid"
   | "unity"
+  | "android-xml"
   | "corpus-agent";
 
 /**
@@ -440,7 +442,9 @@ export async function scan(filePaths: readonly string[]): Promise<ScanResult> {
         file: result.filePath,
         line: msg.line,
         ruleId: msg.ruleId,
-        message: msg.message,
+        // Impact-first voice (#14): rewrite the upstream eslint message to lead
+        // with the harmed user. Unmapped rules keep their original message.
+        message: impactFirstJsxA11yMessage(msg.ruleId, msg.message),
         wcag,
         enforcement: enforcementFor(wcag, contract),
         provenance: "jsx-a11y",

package/src/decisions-lint.ts

@@ -0,0 +1,137 @@
+/**
+ * ADR-sequence collision gate for `.decisions/` (issue #77, ADR 0008).
+ *
+ * The why: `write-code` allocates the next ADR number at *branch-creation* time
+ * with no reservation on the monotonic `.decisions/` sequence, so two
+ * decision-builders fanned out in parallel both derive the same next id and
+ * collide silently when their branches reach `main` — a duplicate ADR file id
+ * and a duplicate row in `.decisions/index.md`. A per-PR review gate cannot see
+ * a cross-PR collision on shared global state, so the collision is invisible
+ * until both branches merge. This is the *combined-tree* detection/rejection
+ * gate ADR 0008 chooses: it runs over the merged `.decisions/` directory and
+ * fails loud on any duplicate sequence number (in the files or the index) and
+ * on any file<->index drift, so the collision is rejected instead of shipping.
+ *
+ * Pure and filesystem-narrow: it reads a `.decisions` directory and returns a
+ * structured verdict. No process exit, no console — the CLI shell
+ * (`scripts/check-decisions.ts`) and the regression test (`test/
+ * decisions-collision.test.ts`) both drive this same function.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export interface DecisionsLintResult {
+  /** true iff no collision and no file<->index drift was found. */
+  ok: boolean;
+  /** Human-readable lines, one per problem; empty when ok. */
+  errors: string[];
+  /** Sorted unique 4-digit ADR ids discovered among the `.decisions/` files. */
+  ids: string[];
+}
+
+/** An ADR filename is `NNNN-slug.md` with a zero-padded 4-digit sequence. */
+const ADR_FILE_RE = /^(\d{4})-.*\.md$/;
+/** The optional frontmatter `id:` line, used to cross-check the filename. */
+const FRONTMATTER_ID_RE = /^id:\s*(\d{4})\s*$/m;
+
+/** Pull the 4-digit ADR id out of an `index.md` table row's FIRST cell only. */
+function indexRowId(line: string): string | null {
+  if (!line.trimStart().startsWith("|")) return null;
+  const cells = line.split("|");
+  // cells[0] is the empty span before the leading pipe; cells[1] is column 1.
+  const firstCell = cells[1];
+  if (firstCell === undefined) return null;
+  // The header cell is `#` and the separator cell is `---`; neither carries a
+  // 4-digit run, so matching \d{4} in column 1 selects only real ADR rows.
+  const m = firstCell.match(/(\d{4})/);
+  return m ? m[1]! : null;
+}
+
+/**
+ * Lint a `.decisions` directory for ADR-sequence collisions and index drift.
+ * Returns ok:false with one error line per problem; never throws on a
+ * malformed-but-present tree (a missing `index.md` is itself reported).
+ */
+export function lintDecisions(decisionsDir: string): DecisionsLintResult {
+  const errors: string[] = [];
+
+  // 1. Map every ADR file to its sequence id; flag duplicate sequence numbers.
+  const filesById = new Map<string, string[]>();
+  for (const name of readdirSync(decisionsDir).sort()) {
+    const m = name.match(ADR_FILE_RE);
+    if (!m) continue;
+    const id = m[1]!;
+    const list = filesById.get(id) ?? [];
+    list.push(name);
+    filesById.set(id, list);
+
+    // Frontmatter `id:` must agree with the filename, so a renumbered-by-hand
+    // file whose frontmatter still claims the old id is caught too.
+    const fmId = readFileSync(join(decisionsDir, name), "utf8").match(
+      FRONTMATTER_ID_RE,
+    )?.[1];
+    if (fmId !== undefined && fmId !== id) {
+      errors.push(
+        `ADR file ${name}: frontmatter id '${fmId}' does not match filename sequence '${id}'`,
+      );
+    }
+  }
+  for (const [id, names] of [...filesById].sort()) {
+    if (names.length > 1) {
+      errors.push(
+        `duplicate ADR sequence number ${id}: ${names.join(", ")} — two decisions collide on the same id (issue #77)`,
+      );
+    }
+  }
+
+  // 2. Parse `index.md` rows; flag duplicate rows for the same id.
+  const indexById = new Map<string, number>();
+  let indexPresent = true;
+  let indexText: string;
+  try {
+    indexText = readFileSync(join(decisionsDir, "index.md"), "utf8");
+  } catch {
+    indexPresent = false;
+    indexText = "";
+    errors.push(`.decisions/index.md is missing — cannot verify ADR rows`);
+  }
+  if (indexPresent) {
+    for (const line of indexText.split("\n")) {
+      const id = indexRowId(line);
+      if (id === null) continue;
+      indexById.set(id, (indexById.get(id) ?? 0) + 1);
+    }
+    for (const [id, count] of [...indexById].sort()) {
+      if (count > 1) {
+        errors.push(
+          `duplicate index.md row for ADR ${id} (${count} rows) — two decisions appended the same id (issue #77)`,
+        );
+      }
+    }
+  }
+
+  // 3. Cross-check files <-> index 1:1, so a collision that surfaces as a file
+  //    without a row (or a row without a file) is rejected too.
+  if (indexPresent) {
+    for (const id of [...filesById.keys()].sort()) {
+      if (!indexById.has(id)) {
+        errors.push(
+          `ADR ${id} has a file but no row in index.md — index out of sync`,
+        );
+      }
+    }
+    for (const id of [...indexById.keys()].sort()) {
+      if (!filesById.has(id)) {
+        errors.push(
+          `index.md row for ADR ${id} has no matching .decisions/${id}-*.md file — index out of sync`,
+        );
+      }
+    }
+  }
+
+  return {
+    ok: errors.length === 0,
+    errors,
+    ids: [...filesById.keys()].sort(),
+  };
+}

package/src/detect-stack.ts

@@ -12,8 +12,8 @@
  * builds) so detection and scanning agree on what a "component import" is.
  */
 
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join, sep } from "node:path";
 import type { Language, Router, Stack } from "./contract";
 import { familyLabel, isFrameworkPrimitive, isOwnModule, packageNameOf } from "./module-scope";
 import { resolveComponents } from "./resolve-components";
@@ -125,6 +125,67 @@ function detectLanguage(dir: string): Language {
   return findUp(dir, "tsconfig.json") !== null ? "ts" : "js";
 }
 
+/** Build/output dirs not worth descending into when sniffing for Android markers. */
+const ANDROID_SCAN_SKIP = new Set([
+  "node_modules",
+  ".git",
+  ".gradle",
+  "build",
+  "dist",
+  ".idea",
+]);
+
+/**
+ * Bounded find-down for an Android marker — an `AndroidManifest.xml` or a
+ * `res/layout…` resource directory — within `maxDepth` levels of `dir`. Android
+ * projects nest these under `app/src/main/…`, so a pure package-up probe (used
+ * for tsconfig) would miss them; a shallow, skip-pruned descent is the cheap,
+ * reliable signal. Short-circuits on the first marker found.
+ */
+function hasAndroidMarker(dir: string, maxDepth: number): boolean {
+  let entries: ReturnType<typeof readdirSync>;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return false;
+  }
+  for (const entry of entries) {
+    if (entry.isFile() && entry.name === "AndroidManifest.xml") return true;
+    if (entry.isDirectory()) {
+      // a `layout` / `layout-…` dir whose parent is `res` is a layout resource dir
+      if ((entry.name === "layout" || entry.name.startsWith("layout-")) && dir.endsWith(`${sep}res`)) {
+        return true;
+      }
+    }
+  }
+  if (maxDepth <= 0) return false;
+  for (const entry of entries) {
+    if (!entry.isDirectory() || ANDROID_SCAN_SKIP.has(entry.name)) continue;
+    if (hasAndroidMarker(join(dir, entry.name), maxDepth - 1)) return true;
+  }
+  return false;
+}
+
+/**
+ * True when `dir` is an Android project: a Gradle root (a `build.gradle` /
+ * `settings.gradle`, in Groovy or Kotlin DSL) paired with an Android marker
+ * (`AndroidManifest.xml` or a `res/layout*` dir) reachable a few levels down.
+ * Requiring BOTH keeps a plain JVM Gradle project (no Android UI) from being
+ * misread as Android.
+ */
+export function detectAndroid(dir: string): boolean {
+  const gradle =
+    existsSync(join(dir, "build.gradle")) ||
+    existsSync(join(dir, "build.gradle.kts")) ||
+    existsSync(join(dir, "settings.gradle")) ||
+    existsSync(join(dir, "settings.gradle.kts"));
+  if (!gradle && !existsSync(join(dir, "AndroidManifest.xml"))) {
+    // No gradle root and no manifest right here — not the root of an Android repo.
+    return false;
+  }
+  return hasAndroidMarker(dir, 5);
+}
+
 /**
  * The repo's design system: the published package that contributes the most
  * components RESOLVING TO A KNOWN INTERACTIVE HOST (registry or traced). That
@@ -193,6 +254,13 @@ export function detectDesignSystem(tsxFiles: readonly string[], rootDir?: string
  * signal; see the per-field helpers for what each reads.
  */
 export function detectStack(dir: string, tsxFiles: readonly string[]): Stack {
+  // Android is a distinct platform from the React/TSX path: an Android repo has
+  // no `package.json`/tsconfig to read, and its UI is `res/layout*` XML, not
+  // `.tsx`. Detect it first so it routes to the Android XML collector instead of
+  // degrading to a `framework: unknown · custom · js` web stack.
+  if (detectAndroid(dir)) {
+    return { framework: "android", router: null, designSystem: "android-views", language: "android-xml" };
+  }
   // Package-up: a scan pointed at a nested `src/` finds the app's package.json
   // (and the on-disk app/pages layout) one or more levels above.
   const pkgRoot = findUp(dir, "package.json") ?? dir;

package/src/enforce.ts

@@ -605,36 +605,48 @@ interface EnforceRule {
   readonly message: string;
 }
 
+/**
+ * Every finding message — here and in the jsx-a11y wrapper (see {@link
+ * import("./finding-voice")}) — leads with the IMPACT-FIRST template:
+ *
+ *   [who is affected] can't [do what] because [cause], so [fix].
+ *
+ * The lead names the harmed user and the human consequence (#14), not the rule
+ * id. The rule id, WCAG SC, and corpus "seen-in-the-wild" frequency are SECONDARY
+ * lines the report renders separately ({@link import("./cli").detailLines}), so
+ * the message carries NO `(corpus: …)` suffix — that data is not dropped, it just
+ * lives on its own line rather than inline in the impact sentence.
+ */
 const RULES: Record<string, EnforceRule> = {
   buttonNoName: {
     ruleId: "enforce/button-no-name",
     wcag: ["4.1.2"],
     message:
-      "Control resolves to a button but has no accessible name: children are empty or icon-only and there is no aria-label/aria-labelledby/title. Give it discernible text or an aria-label (corpus: 4.1.2-button-no-name).",
+      "Screen-reader users can't tell what this button does because it has no accessible name — its children are empty or icon-only and there is no aria-label, aria-labelledby, or title, so add visible text or an aria-label that names its action.",
   },
   imageNoAlt: {
     ruleId: "enforce/image-no-alt",
     wcag: ["1.1.1"],
     message:
-      'Control resolves to an image but has no alt and no aria-label/aria-labelledby. Add an alt that conveys the image\'s meaning, or alt="" if decorative (corpus: 1.1.1).',
+      'Blind users can\'t perceive this image because it has no text alternative — no alt and no aria-label/aria-labelledby, so add an alt that conveys its meaning, or alt="" if it is purely decorative.',
   },
   linkNoName: {
     ruleId: "enforce/link-no-name",
     wcag: ["2.4.4"],
     message:
-      "Control resolves to a link but has no discernible name: no text child and no aria-label/aria-labelledby/title. Give the link visible text or an aria-label that names its destination (corpus: 2.4.4-link-no-name).",
+      "Screen-reader users can't tell where this link goes because it has no discernible name — no text child and no aria-label, aria-labelledby, or title, so give it visible text or an aria-label that names its destination.",
   },
   dialogNoName: {
     ruleId: "enforce/dialog-no-name",
     wcag: ["4.1.2", "1.3.1"],
     message:
-      "Control resolves to a dialog/modal but has no accessible name: no aria-label/aria-labelledby, no title/label prop, and no nested title subcomponent. Name the dialog so assistive tech announces it (corpus: 4.1.2).",
+      "Screen-reader users can't tell what this dialog is for because it has no accessible name — no aria-label/aria-labelledby, no title or label prop, and no nested title subcomponent, so name the dialog and assistive tech will announce it on open.",
   },
   inputNoName: {
     ruleId: "enforce/input-no-name",
     wcag: ["1.3.1", "3.3.2"],
     message:
-      "Control resolves to a form input but has no associated label: no aria-label/aria-labelledby, no label/title prop, and no id to pair with a <label for>. Associate a real label (corpus: 1.3.1 / 3.3.2-form-control-no-name).",
+      "Screen-reader users can't tell what to enter in this field because it has no associated label — no aria-label/aria-labelledby, no label or title prop, and no id to pair with a <label for>, so associate a real label and the field will be announced.",
   },
 };
 
@@ -703,7 +715,7 @@ function preferTagOverRole(
     const line = sf.getLineAndCharacterOfPosition(attr.getStart(sf)).line + 1;
     return {
       line,
-      message: `This <${tag}> sets role="${value}", which ${native.suggest} conveys natively. Use ${native.suggest} instead of the role so the semantics work without ARIA (corpus: 1.3.1-prefer-tag-over-role).`,
+      message: `Assistive-tech users get fragile semantics here because <${tag}> hand-sets role="${value}" instead of using the native element ${native.suggest} that conveys it, so switch to ${native.suggest} and the role works without relying on ARIA.`,
     };
   }
   return null;

package/src/finding-voice.ts

@@ -0,0 +1,66 @@
+/**
+ * Impact-first message voice (#14).
+ *
+ * Every finding a11y-checker surfaces leads with one consistent shape:
+ *
+ *   [who is affected] can't [do what] because [cause], so [fix].
+ *
+ * The lead names the harmed user and the human consequence — the first thing a
+ * reader sees — rather than a rule id or SC number. The rule id, WCAG SC, and
+ * corpus "seen-in-the-wild" frequency stay, but as SECONDARY lines the report
+ * renders separately (see `cli.ts` `detailLines`), never inline in the sentence.
+ *
+ * The enforce content rules (`enforce.ts`) author their own messages in this
+ * shape. The jsx-a11y structural pass does NOT — its findings come straight from
+ * eslint-plugin-jsx-a11y, whose upstream messages lead with the rule requirement
+ * ("Buttons must have discernible text"), not the impacted user. This module is
+ * the wrapper that rewrites those upstream messages into the same impact-first
+ * voice, keyed by jsx-a11y rule id. It covers exactly the rules we score
+ * (`core.ts` `SCORED_RULES`); any rule not mapped here falls back to its upstream
+ * message unchanged, so the remap can only improve voice, never blank a finding.
+ *
+ * This is a display-only rewrite: it changes the `message` string, nothing about
+ * detection, the rule id, the WCAG mapping, the corpus enrichment, or the matrix
+ * baseline (which records file/line/ruleId, not message text).
+ */
+
+/**
+ * Impact-first messages for the jsx-a11y rules we score. Keyed by the bare rule
+ * name (no `jsx-a11y/` prefix) — the caller strips the namespace before lookup.
+ * Each follows the [who] can't [do what] because [cause], so [fix] template.
+ */
+const JSX_A11Y_IMPACT_MESSAGES: Readonly<Record<string, string>> = {
+  "label-has-associated-control":
+    "Screen-reader users can't tell what to enter in this field because its control has no associated <label>, so pair the control with a <label> (htmlFor + id, or wrap it) and the field will be announced.",
+  "alt-text":
+    'Blind users can\'t perceive this image because it has no alt text, so add an alt that conveys its meaning, or alt="" if it is purely decorative.',
+  "anchor-has-content":
+    "Screen-reader users can't tell where this link goes because it has no discernible content, so give the anchor visible text or an aria-label that names its destination.",
+  "anchor-is-valid":
+    "Keyboard and screen-reader users can't reliably follow this link because it has no valid href, so give it a real href — or use a <button> if it triggers an action rather than navigating.",
+  "aria-props":
+    "Assistive tech can't interpret this element because it carries an attribute that isn't a valid aria-* property, so remove or correct the invalid ARIA attribute.",
+  "role-has-required-aria-props":
+    "Screen-reader users can't fully operate this control because its role is missing ARIA properties that role requires, so add the required aria-* attributes for the role.",
+  "role-supports-aria-props":
+    "Screen-reader users can't rely on this element because it has an aria-* attribute its role doesn't support, so remove the unsupported attribute or change the role.",
+  "interactive-supports-focus":
+    "Keyboard users can't reach this control because it is interactive but not focusable, so make it focusable (use a native control, or add tabIndex) and it can be operated without a mouse.",
+  "click-events-have-key-events":
+    "Keyboard users can't activate this element because it has a click handler but no keyboard handler, so add a key handler — or use a <button> — and it will work without a mouse.",
+  "no-static-element-interactions":
+    "Keyboard and screen-reader users can't operate this element because a click handler sits on a non-interactive element with no role, so use a native control, or add an interactive role plus keyboard support.",
+  "heading-has-content":
+    "Screen-reader users can't navigate by this heading because it has no text content, so give the heading discernible text (or remove it if it is not really a heading).",
+};
+
+/**
+ * Rewrite a jsx-a11y finding's upstream eslint message into the impact-first
+ * voice. `ruleId` is the full id (`jsx-a11y/alt-text`); `fallback` is the
+ * upstream message used verbatim when the rule isn't in the map — so a finding
+ * always carries a message, and an unmapped rule degrades to its original text.
+ */
+export function impactFirstJsxA11yMessage(ruleId: string, fallback: string): string {
+  const bare = ruleId.startsWith("jsx-a11y/") ? ruleId.slice("jsx-a11y/".length) : ruleId;
+  return JSX_A11Y_IMPACT_MESSAGES[bare] ?? fallback;
+}