@surea11y/core 1.6.0 → 1.8.0

package/docs/API_STABILITY.md

@@ -6,8 +6,8 @@
 
 Removing, renaming, or changing the type/meaning of any of these is a **major** version bump:
 
-- Top-level result: `engine.tag`, `engine.schemaVersion`, `engine.locale` (the field and its `requested`/`resolved`/`reason` keys — the set of `reason` *values* is open and may gain entries in a minor), `url`, `checksResults` (an array), `rulesResults` (an array).
-- Each `checksResults[i]` / `rulesResults[i]` entry: `ruleId`, `outcome`, `outcomeNormalized`, `severity`, `confidence`, `type`, `title`, `description`, `meta` (including `meta.normativeMappings`, `meta.deprecated`/`.deprecation` — see below), `engineOptions`, `schemaVersion`.
+- Top-level result: `engine.tag`, `engine.schemaVersion`, `engine.locale` (the field and its `requested`/`resolved`/`reason` keys — the set of `reason` *values* is open and may gain entries in a minor), `engine.wcagVersion`, `engine.profile` (when present; the set of profile names may grow in a minor), `engine.optInRules` (when present; the set of tags may grow in a minor), `url`, `checksResults` (an array), `rulesResults` (an array), `overriddenBuiltinIds` (an array, empty when no `customRules` entry shadowed a built-in id — part of the extension contract, see below).
+- Each `checksResults[i]` / `rulesResults[i]` entry: `ruleId`, `outcome`, `rollupIds` (check results only), `outcomeNormalized`, `severity`, `confidence`, `type`, `title`, `description`, `meta` (including `meta.normativeMappings`, `meta.deprecated`/`.deprecation` — see below), `engineOptions`, `schemaVersion`.
 - Each occurrence (`occurrences[i]`): `selector`, `html`, `summary`, `hint`, `i18n`, `structuralPath`.
 - The rule **catalog** (`getChecksCatalog()`/`getRulesCatalog()`, a separate surface from a scan result — see `RULE_AUTHORING.md`): `ruleId`, `title`, `description`, `tags`, `wcagSc`, `normativeMappings`, `defaultSeverity`, `defaultConfidence`, `type`, `deprecated`/`.deprecation`. Note `tags` lives here, not on a per-scan `checksResults[i].meta` — the two surfaces intentionally carry different subsets of a rule's metadata.
 
@@ -23,25 +23,84 @@ Since 1.4.0 the package declares an explicit `exports` map. These are the only i
 | `@surea11y/core/baseline` | `src/baseline.js` | `buildBaselineEntries()`, `matchBaseline()` |
 | `@surea11y/core/report` | `src/report.js` | `renderHtmlReport()` |
 | `@surea11y/core/sarif` | `src/sarif.js` | `renderSarifReport()` |
+| `@surea11y/core/junit` | `src/junit.js` | `renderJunitReport()` |
+| `@surea11y/core/earl` | `src/earl.js` | `renderEarlReport()` |
+| `@surea11y/core/en301549` | `src/en301549.js` | `EN301549_VERSIONS`, `EN301549_CLAUSES`, `en301549ClausesForSc()` |
+| `@surea11y/core/wcag` | `src/wcag.js` | `WCAG_VERSIONS`, `wcagCriteria()`, `wcagCriterion()`, `wcagTags()` |
 | `@surea11y/core/browser` | `surea11y.browser.js` | the standalone browser bundle, for bundlers that resolve it as a module |
 
-Anything **not** in that table — `src/core/*`, `src/checks/*`, `src/i18n/*`, `src/policy/*`, and the generated `src/core.js` itself — is internal. Before 1.4.0 there was no `exports` map, so those paths were technically reachable via deep `require()`; they were never documented as public and are no longer resolvable. The `<script src="node_modules/@surea11y/core/surea11y.browser.js">` form documented in the README is a filesystem path, not module resolution, and is unaffected.
+Anything **not** in that table — `src/core/*`, `src/checks/*`, `src/i18n/*`, `src/policy/*`, `profiles/*` (a profile's tables and rules, which the engine reads), and the generated `src/core.js` itself — is internal. Before 1.4.0 there was no `exports` map, so those paths were technically reachable via deep `require()`; they were never documented as public and are no longer resolvable. The `<script src="node_modules/@surea11y/core/surea11y.browser.js">` form documented in the README is a filesystem path, not module resolution, and is unaffected.
 
 Declaring this map is what lets the engine's internal file layout change without a major bump. Note that `src/checks/*` is still *shipped* (the generated bundle `require()`s it at runtime) — shipped is not the same as public.
 
+## Extension points
+
+The `exports` map above says which **paths** are importable. It does not say which **symbols** behind them are supported, and that distinction matters here: `src/index.js` re-exports the generated core verbatim, so every symbol the build emits reaches consumers whether or not it was meant for them. The classification lives in [`scripts/data/public-api.json`](../scripts/data/public-api.json) and is checked by `tests/public-api.test.js`, which fails when a new export appears unclassified — a leak has to be a decision, not an accident.
+
+**Supported** — covered by semver, safe to build on:
+
+| Export | For |
+|---|---|
+| `runa11yCoreInPage` | Scanning from another JS realm: the whole engine is inlined, so `fn.toString()` re-evaluated in a browser tab works. What all five browser bindings use. |
+| `runDomRulesInPage` | Scanning in the same Node process, dispatching through real `require()`. What `@surea11y/test-matchers` uses. |
+| `runa11yCoreAcrossFrames` / `a11yCoreEnableFrameResponder` | Cross-frame scanning without an automation driver. |
+| `getChecksCatalog()` / `getRulesCatalog()` | Reading the rule catalog; its stable fields are listed above. |
+
+**Exported but internal** — reachable today, not supported, and free to change or disappear in a minor: `CHECK_DEFS`, `TEST_DEFS`, `COMPOSITE_RULES`, `DEFAULT_POLICY`, `POLICY_CONTRACTS`, `ENGINE_TAG`, `SCHEMA_VERSION`, `resolvePolicy`, `getCheckDefById`, `getCompositeRuleById`, `getChecksForRunOnly`, `getTestsForRunOnly`, `__internal`.
+
+They stay exported rather than being removed, because removing them is itself a breaking change and no consumer needs it yet; the honest fix for now is to say they are not part of the contract. Note the two constants have supported equivalents on every result — `engine.tag` and `engine.schemaVersion` — so read them from there rather than importing them. Curating this list down to the supported set is a candidate for the next major.
+
+### Extending the engine
+
+Three things are meant to be extended, and all three go through `engineOptions` or a separate entry point rather than through the exported symbols above:
+
+- **`engineOptions.customRules`** — the plugin mechanism: an array of rule descriptors registered for one call, never added to the static catalog and never persisted between calls. **The descriptor contract is covered by semver**: `id`, `meta`, `runInPage(ctx)` and the optional `applicability(ctx)` and `data`, along with the `ctx.helpers` a rule receives and the `{outcome, severity, occurrences}` it returns. That `runInPage`/`applicability` may be passed as a function *or* as a function-source string is part of the contract too, not a convenience: `engineOptions` crossing into another realm (a Playwright `page.evaluate`, say) cannot carry a live `Function`, so a binding has no other way to register one. A custom rule that shadows a built-in id replaces it for that scan and is reported back in `overriddenBuiltinIds`, so an accidental collision is visible rather than silent. A custom rule written against today's contract keeps working across minors; requiring a new field of it is a major. The full descriptor shape is in [`ENGINE_OPTIONS.md`](./ENGINE_OPTIONS.md#customrules--runtime-registered-rules), the helpers in [`RULE_HELPERS.md`](./RULE_HELPERS.md), and the outcome rules a custom rule must obey in [`RULE_TAXONOMY.md`](./RULE_TAXONOMY.md).
+- **`engineOptions.policyContract` / `engineOptions.policy`** — which outcomes and confidence values a scan may report, and whether a manual rule's would-be `fail` is coerced. The two option names, the built-in contract ids `'a11y'` and `'generic'`, and the inline-contract shape are supported; the `POLICY_CONTRACTS` export itself is not, since passing a string or an inline object is all a caller needs. See [`POLICY.md`](./POLICY.md).
+- **Reporters** — `@surea11y/core/baseline`, `/report`, `/sarif` and `/earl` consume a result rather than hooking into the scan, which is why they are separate entry points. A consumer wanting a different output format reads the result shape above; nothing needs to be registered with the engine.
+
+There is deliberately no hook for changing what a built-in rule decides. Overriding one means shipping a `customRules` entry that reuses its id, which the engine allows for a single call, warns about, and reports in `overriddenBuiltinIds` — so a scan that silently disagrees with the catalog is not possible.
+
 ## Explicitly unstable (not covered by semver)
 
+- **What profiles build on: a rule's `settings` and `src/profile-kit.js`.** A rule's settings are the thresholds a built-in rule declares it reads from `ctx.config` (`contrast-minimum`'s `boldLargeMinPx`, `largeTextRatio`, `normalTextRatio`), for its variants ([`RULE_AUTHORING.md`](./RULE_AUTHORING.md#rule-variants)); a scan's `engineOptions.rules` cannot set them. `src/profile-kit.js` is the mapping a profile made with `npm run profile:new` uses, and is not exported. Both serve the profiles in this repository, which change with them, so they stay outside this contract until a profile can live outside it ([`profiles/README.md`](../profiles/README.md)).
 - `perfStats` and `ruleTimings` — internal timing/debug counters, only present when `engineOptions.perfStats`/`.profileRules` is set. Shape not covered by this document.
-- `occurrences[i].data.details` — rule-specific, non-normative extra context. Shape varies per rule and may change in a patch release; treat as best-effort, not a stable contract (this was already noted in `docs/OUTPUT_SCHEMA.md` before this document existed).
+- `occurrences[i].data.details` — rule-specific, non-normative extra context. Shape varies per rule and may change in a patch release; treat as best-effort, not a stable contract (this was already noted in `docs/OUTPUT_SCHEMA.md` before this document existed). **`data.details.reasonCode` is the exception** and is stable — see [Finding identity](#finding-identity) below.
 - `ruleInterfaceVersion` / `ruleVersion` on a rule's meta — currently unused scaffolding (every rule defaults to the same two static strings; nothing meaningfully sets or consumes them today). Not part of this contract until they're actually wired up to mean something.
 
+## Finding identity
+
+A consumer needs to know whether a finding it is looking at is the same one it saw last week. Two things in this package answer that, and both compute it the same way — `computeBaselineKey(ruleId, reasonCode, html)` in `src/baseline.js`:
+
+- **Baselines.** `--write-baseline`/`--baseline` suppress known findings so a build only breaks on new ones.
+- **SARIF.** `partialFingerprints['surea11y/violation/v1']`, which GitHub Code Scanning uses to decide whether an alert is the same alert or a new one.
+
+So the identity is `ruleId` + `reasonCode` + the occurrence `html`, and two of those three are promises:
+
+- **A rule id, once published, does not change.** Renaming or removing one is a major change. The supported path is to keep the id, mark it `deprecated` with `deprecation.replacedBy` naming the successor, and remove it only after the notice period.
+- **A reason code, once a rule has shipped it, does not change.** This is a deliberate exception to the surrounding "`data.details` is unstable" rule: everything else under `data.details` is free-form, but `reasonCode` is load-bearing for identity, so it is pinned. Adding a new code to a rule is a minor change; changing or dropping an existing one is not, because every stored baseline entry and every open Code Scanning alert keyed on it stops matching.
+- **A reason code retires only with the finding it named.** The promise is that a finding the engine still makes keeps its identity, not that a finding is made forever. When a correctness fix (a patch, see [below](#what-triggers-which-version-bump)) changes what a rule reports for an element, the finding the old code named no longer exists, and its code may go with it: a baseline entry or alert for it then closes, as it would for any fixed bug, rather than silently stopping to match a finding that is still there. Renaming a code for a finding that stays, or dropping one the rule still has a case for, is never allowed. A retirement is recorded, with its reason, in `CHANGELOG.md`, and under `retired` in `scripts/data/released-finding-ids.json` until the next release.
+
+What the last release shipped is frozen in [`scripts/data/released-finding-ids.json`](../scripts/data/released-finding-ids.json), written by `npm run finding-ids:release -- <version>` as part of each release, and `tests/released-finding-ids.test.js` fails when a rule id or reason code from it is missing and not listed under `retired` with its reason. No commit rewrites that file between releases, so an identity cannot be dropped and the inventory regenerated in the same change without the test noticing. Each release freezes a new inventory and starts the `retired` list empty again, since what it held was not in that release; the changelog keeps the reasons.
+
+Both are inventoried in [`scripts/data/finding-ids.json`](../scripts/data/finding-ids.json) for core's rules, and in each profile's own `scripts/data/finding-ids.json` for its rules, regenerated with `npm run finding-ids` and checked by `tests/finding-ids.test.js`, which fails when a published rule id or reason code disappears. The inventory is the record of what has been promised; the test is what stops the promise being broken by accident.
+
+Note what identity does **not** include: `selector` and `structuralPath` deliberately stay out of the fingerprint, because both change when the surrounding page is edited, which would make every finding look new after an unrelated refactor. `html` is in, so editing the flagged element itself does read as a new finding — that is the intended trade-off, since the element's markup is the thing the finding is about.
+
+### A removal that predates this guard
+
+`area-alt-decorative`, shipped in 1.7.0, was removed afterwards without the deprecation period described [below](#rule-id-deprecation-policy). It asked a human whether an `<area>` with an empty `alt` was decorative, a question with no legitimate "yes": `area-alt-present` now fails that case outright ([`DESIGN_CHALLENGES.md`](./DESIGN_CHALLENGES.md)). The removal was accepted as an exception rather than reverted, and is recorded in the 1.8.0 changelog. Anything holding its id — a `runOnly` list, a baseline entry — matches nothing from the release after 1.7.0; the empty-`alt` area it asked about is reported by `area-alt-present` instead.
+
+### A rename that predates this
+
+`role-img-alt-present` became `role-img-text-alternative-present` with no deprecation entry and no major bump, before any of the above was written down. Anything holding the old id — a baseline entry, a `runOnly` list — silently matched nothing. The rename is not reversible now: the old id has been absent across every 1.x release, so a deprecation entry today would announce the retirement of something no current version answers to. It is recorded here instead, because it is the reason this section exists. Its source file, fixture and test kept the old name for a while afterwards, which is what made the rename easy to miss; they carry the rule's own id now.
+
 ## What triggers which version bump
 
 - **Patch**: a correctness fix that changes *which* outcome a rule produces for the same input, without changing the shape or mechanism. Example: the fragment-scan applicability fix (`engineOptions.fragment`, see `ENGINE_OPTIONS.md`) changed several rules from incorrectly `fail`ing on a scoped subtree to correctly `notApplicable` — that's a patch, not a major bump, because no stable field's *shape* changed, only a bug got fixed. Don't over-index on "any output change = major" — bug fixes are expected to change output.
 - **Minor**: adding a new stable field, adding a new rule to the catalog, or marking an existing rule `deprecated` (see below).
 - **Major**: removing or renaming a stable field, changing a stable field's type or meaning, or removing a rule ID once its deprecation notice period has passed. Paired with an `engine.schemaVersion` bump specifically when the *shape* changes (as opposed to package-level major bumps for other reasons, e.g. dropping support for an old Node version).
 
-`engine.schemaVersion` has been `"1.0.0"` since the engine's first release and has never needed a bump — nothing has changed a stable field's shape yet. Adding the `deprecated`/`deprecation` meta fields described below is purely additive (new optional fields, ignored safely by anything not looking for them), so it does **not** warrant a schema bump either — this is the policy's first real application. `engine.locale` is the second: a new field next to the existing ones, with no change to any field a consumer already reads.
+`engine.schemaVersion` has been `"1.0.0"` since the engine's first release and has never needed a bump — nothing has changed a stable field's shape yet. Adding the `deprecated`/`deprecation` meta fields described below is purely additive (new optional fields, ignored safely by anything not looking for them), so it does **not** warrant a schema bump either — this is the policy's first real application. `engine.locale` is the second: a new field next to the existing ones, with no change to any field a consumer already reads. `engine.wcagVersion` and the optional per-result `wcagVersionScope` are the third, on the same reasoning — but note the *outcome* change that came with them (a rule mapped to the removed SC 4.1.1 now reports `cantTell` instead of `fail` under the default 2.2 target) is an outcome fix of the kind described above, not a shape change.
 
 ## Release cadence
 
@@ -53,6 +112,8 @@ The version number is the contract — not a measure of how much has changed or
 
 Because every `1.x` release is backward-compatible, a consumer pinned to a `^1.y.0` range is never broken by an upgrade within the line — so a steady stream of patch/minor releases reflects active maintenance and prompt fixes, not instability. Frequency of releases is not a signal of churn; a change to a **major** version is.
 
+Each release freezes the finding identities it ships: run `npm run finding-ids:release -- <version>` and commit `scripts/data/released-finding-ids.json` with the release (see [Finding identity](#finding-identity)).
+
 ## Rule-ID deprecation policy
 
 A rule can be marked deprecated in its own `meta`:
@@ -78,7 +139,7 @@ The process:
 2. Leave it running normally for at least one full minor version cycle after the deprecation, so integrators pinned to `^x.y.0` have a real chance to see it before it's gone.
 3. Remove the rule file entirely in a future **major** version, documented under `### Removed`.
 
-No rule has been deprecated yet as of this document's introduction — this is the mechanism, ready for the first real case.
+`iframe-title-unique` was the first rule to use this mechanism, deprecated in 1.8.0 in favour of `identical-iframes-same-purpose` (see `DESIGN_CHALLENGES.md`). It also reports `notApplicable` on every page, because the `fail` it used to report was not a WCAG violation and waiting for 2.0.0 to stop reporting one was not acceptable. That is a property of the retired check, not of deprecation: a deprecated rule whose results are still correct keeps producing them, as described above. Its reason code, `IFRAME_TITLE_DUPLICATE`, is no longer emitted, so it retired with the finding it named, as the 1.8.0 changelog records (see [Finding identity](#finding-identity)).
 
 ## See also
 

package/docs/BINDING_AUTHORS_GUIDE.md

@@ -36,6 +36,108 @@ A short list, derived from what the audit pass on `@surea11y/playwright` actuall
 - [ ] If you support cross-frame scanning via your own driver, confirm each frame's result gets the same normalization (selector/structuralPath/severity) as a single-document scan — don't let a "per-frame" code path silently skip the shared result-shaping logic.
 - [ ] TypeScript types (if you ship any) stay in sync with actual engine output — `structuralPath: number[] | null` and any new fields ([`OUTPUT_SCHEMA.md`](./OUTPUT_SCHEMA.md) is the source of truth) are easy to leave stale after an engine update.
 
-## A known engine-side tradeoff worth knowing about
+## Getting the engine into the page without paying for it twice
 
-`src/core.js` is not small (~4.3MB as of 2026-08-20) because the bundler-free, no-driver-context functions (`runa11yCoreInPage`, `runa11yCoreAcrossFrames`, `a11yCoreEnableFrameResponder`) each carry their own complete self-contained copy of the rule catalog. If your binding only ever uses `require('@surea11y/core')` in Node and injects `runa11yCoreInPage.toString()` into the page (the same pattern `@surea11y/playwright` uses), your actual browser-injected payload is unaffected by this — only your Node-side `require()` footprint grows. Worth knowing if your binding's own package size matters to your consumers.
+A binding that crosses a realm boundary has to get the engine into the page
+somehow. The obvious way — serialize `runa11yCoreInPage` with `.toString()` and
+hand it to the driver's evaluate-in-page call — works, and is what
+`@surea11y/playwright` did first, but it sends the whole engine **on every
+call**: about 2.1MB per frame, per scan. A five-frame scan sends it five times,
+and the next scan sends it all again.
+
+The package ships a smaller way. `@surea11y/core/browser` is the standalone
+bundle: the same `runa11yCoreInPage`, minified, about 780KB, which defines
+`window.a11ycore`. Load it into the document once and every later scan costs a
+few hundred bytes.
+
+The shape below is deliberately driver-neutral — `evaluateInPage` stands for
+whatever your driver calls it (`page.evaluate` in Playwright and Puppeteer,
+`browser.execute` in WebdriverIO, `driver.executeScript` in Selenium, which
+takes a *string* of script text rather than a function):
+
+```js
+const fs = require('fs');
+const BUNDLE = fs.readFileSync(require.resolve('@surea11y/core/browser'), 'utf8');
+
+// Returns true when window.a11ycore is ready to use in this document.
+async function ensureEngine(target) {
+  if (await evaluateInPage(target, () => typeof window.a11ycore !== 'undefined')) return true;
+  try {
+    await evaluateInPage(target, (src) => (0, eval)(src), BUNDLE);
+  } catch {
+    return false;
+  }
+  // Confirm it actually landed rather than assuming: see the CSP note below.
+  return evaluateInPage(target, () => typeof window.a11ycore !== 'undefined');
+}
+```
+
+Then use it if it is there, and keep the serialize path as the fallback:
+
+```js
+async function scan(target, args) {
+  if (await ensureEngine(target)) {
+    return evaluateInPage(
+      target,
+      (a) => window.a11ycore.runa11yCoreInPage(a.url, a.contextSelector, a.engineOptions, a.runOnly),
+      args
+    );
+  }
+  return evaluateInPage(target, serializedRunnerFn, args); // what your binding does today
+}
+```
+
+Four things to know before adapting it:
+
+- **Verify the global appeared; don't assume.** That is what makes this safe to
+  adopt across drivers without auditing each one's execution model. A driver
+  whose script execution is subject to the page's own CSP will fail to define
+  the global, `ensureEngine` returns false, and the scan falls back to the
+  payload it uses today rather than breaking.
+- **Don't reach for `addScriptTag`.** It injects an inline `<script>`, which a
+  page serving `script-src 'self'` refuses — confirmed in Chromium against both
+  a page and a sub-frame. Playwright's and Puppeteer's `evaluate` run through
+  CDP, outside the page's CSP, so the snippet above was confirmed working under
+  `script-src 'self'` with no `unsafe-eval`. Other drivers execute scripts by
+  other means; the presence check above is what covers the difference.
+- **A navigation clears it.** `window.a11ycore` belongs to the document, so the
+  check has to run per frame and after every navigation. That is why `scan`
+  calls `ensureEngine` unconditionally rather than caching a flag on the
+  binding.
+- **The bundle carries English only.** Every other locale is a side file, so a
+  binding forwarding `engineOptions.locale` must load the matching one the same
+  way, before the scan:
+
+  ```js
+  const primary = String(locale || 'en').trim().toLowerCase().split('-')[0];
+  if (primary && primary !== 'en') {
+    let localePath;
+    try {
+      localePath = require.resolve(`@surea11y/core/i18n/${primary}`);
+    } catch {
+      localePath = null; // not a locale this build ships; English is the fallback
+    }
+    if (localePath) {
+      await evaluateInPage(target, (src) => (0, eval)(src), fs.readFileSync(localePath, 'utf8'));
+    }
+  }
+  ```
+
+  Without it the scan still succeeds, but in English, with
+  `engine.locale.reason` reporting `dictionary-not-loaded` — the engine saying
+  this step was missed, rather than a failure to swallow.
+
+Results are identical either way: same rules, same composites, same `engine`
+block, verified over a page seeded with a spread of violations. This is only
+about what crosses the wire.
+
+### Which situation is your binding in
+
+Only the first row pays the serialization cost this section is about.
+
+| Binding | Realm | What to do |
+|---|---|---|
+| Playwright, Puppeteer, Selenium, WebdriverIO | Node drives a separate browser realm | Everything above: load `@surea11y/core/browser` into the document once, scan through `window.a11ycore`, keep the serialize path as fallback. |
+| Cypress | Test code already runs in the browser, with the app under test in a same-origin frame | No serialization boundary, so nothing crosses the wire — but the engine still has to be evaluated into the app's realm rather than called from the runner's, or it reads the wrong `document`. `require` the engine and `win.eval` its source there (what `@surea11y/cypress` does), or read the bundle with `cy.readFile` and evaluate that instead; both put it in the right realm. Size is not the deciding factor here. |
+| Jest, Vitest, or anything else driving jsdom in-process | One realm, in Node | None of this applies. `require('@surea11y/core')` and call `runDomRulesInPage` against the DOM you already have — see [`INTEGRATION.md`](./INTEGRATION.md) Pattern 1. Injecting a bundle here would be strictly worse. |
+| Browser extension, bookmarklet, injected script | Already in the page | Load the bundle once and call it; that is the case it was built for. |

package/docs/CI_INTEGRATIONS.md

@@ -98,6 +98,49 @@ pipelines:
 
 The step fails the pipeline on the CLI's exit code exactly like any other `script` entry; `a11y-report.html` (see [`REPORT.md`](./REPORT.md)) is attached as a downloadable build artifact so a reviewer can open it without re-running the scan locally.
 
+## JUnit test reports
+
+GitLab, Azure DevOps, Jenkins and CircleCI show JUnit XML in their own test views: each WCAG criterion becomes a suite and each rule a test (see [`JUNIT.md`](./JUNIT.md)). Save the scan as JSON, render it with `@surea11y/core/junit`, and keep the CLI's exit code for gating. The render step needs `@surea11y/core` in the project's own `devDependencies`.
+
+### GitLab CI
+
+```yaml
+a11y:
+  image: node:20
+  script:
+    - npm ci
+    - npm run build
+    - npx @surea11y/cli scan ./dist/index.html --json > a11y-scan.json || scan_exit=$?
+    - node -e "const fs = require('fs'); const { renderJunitReport } = require('@surea11y/core/junit'); fs.writeFileSync('a11y.junit.xml', renderJunitReport(JSON.parse(fs.readFileSync('a11y-scan.json', 'utf8'))))"
+    - exit ${scan_exit:-0}
+  artifacts:
+    when: always
+    reports:
+      junit: a11y.junit.xml
+```
+
+`when: always` uploads the report even when the scan's exit code fails the job, which is exactly when the merge request widget is worth reading.
+
+### Azure DevOps
+
+```yaml
+steps:
+  - script: |
+      npm ci
+      npm run build
+      npx @surea11y/cli scan ./dist/index.html --json > a11y-scan.json || scan_exit=$?
+      node -e "const fs = require('fs'); const { renderJunitReport } = require('@surea11y/core/junit'); fs.writeFileSync('a11y.junit.xml', renderJunitReport(JSON.parse(fs.readFileSync('a11y-scan.json', 'utf8'))))"
+      exit ${scan_exit:-0}
+    displayName: Accessibility scan
+  - task: PublishTestResults@2
+    condition: succeededOrFailed()
+    inputs:
+      testResultsFormat: JUnit
+      testResultsFiles: a11y.junit.xml
+```
+
+`cantTell` rules arrive as skipped tests, never failures. To gate on them too, pass `{ cantTellAs: 'failure' }` as the second argument to `renderJunitReport`; note that it changes the report, not the CLI's exit code.
+
 ## Free-tier/private-repo minute limits
 
 If your pipeline provider's free tier is minute-limited (Bitbucket Pipelines' free tier is 50 build-minutes/month on private workspaces, for example), a `jsdom`-based scan of static/server-rendered HTML (what the CLI does) is far cheaper than driving a real browser — see [the CLI docs](https://github.com/SureA11y/cli/blob/main/docs/CLI.md#what-it-can-and-cant-scan) for what that trades away (no client-rendered content, no real CSS layout).

package/docs/DESIGN_CHALLENGES.md

@@ -2,6 +2,18 @@
 
 A running log of engine design decisions worth re-examining: cases where an existing choice turned out to conflict with a ground-truth source (usually the W3C ACT rules test corpus), or just looks questionable on a second look. Not all of these are bugs; some are tradeoffs that deserve a second opinion before being confirmed or overturned. Each entry has the decision as it stands, why it's being questioned, and its current status. Settled entries move to [Decided](#decided) at the bottom, with the reasoning kept, since a decision is only useful later if the argument behind it survives with it.
 
+## Method
+
+Before changing behavior that already ships, or agreeing that a challenge to it is right, establish why the current behavior exists rather than assuming it was either careless or considered.
+
+- **Read the history first.** `git log -L <start>,<end>:<file>` (or `git log -S<token>`) on the exact lines, and check whether the commit message, this document, `RULE_AUTHORING.md`, or `CHANGELOG.md` already recorded a reason. A comment that states what the code does is not evidence of why it does it — say explicitly when no rationale can be found instead of inventing one to fill the gap.
+- **Check for a second implementation of the same concept.** A question this engine has needed to answer more than once (eligibility, focusability, naming, inertness) is sometimes reimplemented locally inside one rule rather than shared through `dom-helpers.js`. When two independent implementations disagree on the same input, that disagreement is stronger evidence of a real problem than either implementation's own comment defending itself.
+- **Weigh it against ground truth, not intuition:** the WCAG Understanding documents and Techniques, the ACT rules corpus (this repo's primary source, see the intro above), and the HTML/ARIA spec text for the exact mechanism in question — what `inert`, `aria-hidden`, or a native role default actually do, not what seems reasonable.
+- **Compare against other accessibility testing engines where practical**, as one more data point on how the same ambiguity is usually resolved in the field — never as an authority on its own, and never named or quoted in a rule's comments, commits, or docs (this repo never names competing engines).
+- **State the counter-argument before concluding.** Write down why the current behavior might be right, and why it hasn't already been revisited, before deciding it should change. "Nobody thought this through" and "this was already considered and rejected" call for different next steps.
+- **Land the decision somewhere.** Fix it with a `CHANGELOG.md` entry that states the reasoning, or add/update an entry in this file's [Open](#open) or [Decided](#decided) section, so the argument survives with the decision the next time someone re-examines it.
+- **After changing a rule's behavior**, regenerate every generated artifact that describes it, not just the code and tests: `npm run docs:rule-catalog`, `npm run coverage`, `npm run fixtures:index`, `npm run fixtures:markers`, `npm run finding-ids`, and `npm run docs:rule-review` (the by-hand review page). None of these run automatically from a source edit, and a stale one is easy to miss since nothing fails loudly except `fixtures:markers:check`/`coverage:check`/`finding-ids`'s own test.
+
 ## Open
 
 ### `label-in-name` compares against accessibility-tree text, where ACT uses *visible* inner text
@@ -28,6 +40,52 @@ A running log of engine design decisions worth re-examining: cases where an exis
 
 ## Decided
 
+### `aria-required-children` failed a container for being empty, when its sibling already owns the question of whether the contents are valid, now advisory
+
+**Decision as it stands (before the change):** the rule failed any container role with a "required owned elements" entry that had no descendant (or `aria-owns` target) carrying one of those roles. An empty `<div role="list">`, a `role="tablist"` before its tabs arrive, a `role="rowgroup"` with no rows: all `fail` at `moderate`, mapped to SC 1.3.1.
+
+**Why it was questioned:** the rule asks one thing, whether the required content is PRESENT. Whether the content a container does own is VALID is `aria-prohibited-children`'s decision, and that rule fails independently. Absence conveys nothing false: an empty `role="list"` is announced as a list with no items, which is exactly what it is. The engine's own native-HTML rules already work this way, which made the ARIA side incoherent by comparison: `<ul></ul>` passes and `<div role="list"></div>` failed, same structure, same emptiness, opposite verdicts, with nothing in WCAG distinguishing them. ACT `bc4a75`, the authority this rule's `fail` rests on, turns out not to cover the shape at all: its Expectation is "each test target only owns elements with a semantic role from the required owned element list", which an empty container satisfies vacuously, and it publishes no empty-container example in either direction. The engine's clean run against that corpus was therefore silent about this case rather than confirming it.
+
+**What was weighed:** three predicates were on the table. Cap the rule at `cantTell` outright; keep a `fail` for a container that owns roles but none of the required ones; or the stricter line used elsewhere in the industry, `cantTell` only when the container owns no content whatsoever, so a container of unroled elements still fails. The middle option was dropped once it was clear that every shape it would fail is already failed by `aria-prohibited-children`, making it a second rule agreeing with the first rather than a decision of its own, against this repo's one-rule-one-decision principle. The strict option was dropped because a container of unroled elements is equally "a broken list" and "an empty list with content inside it", and static markup does not settle which.
+
+**Decision (2026-08-28):** the rule reports `cantTell` for every finding and can no longer `fail`. Applicability, the `aria-busy` escape hatch, accessibility-tree eligibility, `aria-owns` resolution and slot expansion are all unchanged, as is `aria-prohibited-children`.
+
+**Accepted cost:** `<div role="list"><div>Item one</div><div>Item two</div></div>`, a list whose items never got their role, is now reported for review rather than failed, and no other rule fails it. That is the only shape that loses a failure; the fixture carries it as case 09 and a test pins the sibling rule still failing a genuinely disallowed child, so the safety net this depends on cannot be removed quietly.
+
+**Status:** resolved 2026-08-28.
+
+### The `aria-*` family reported ARIA-spec conformance as a WCAG 4.1.2 failure, where ACT's own mapping calls most of it "not required for conformance", now graded
+
+**Decision as it stands (before the change):** 13 of the 16 automatic `aria-*` rules declared `wcagSc: ['4.1.2']` at level A (the other three were re-mapped to 1.3.1, see Status), `normative: true` (no rule anywhere in this repo sets `normative: false`) and `defaultConfidence: 'high'` — the exception being `aria-required-parent`, which is `medium` and still emits a flat `fail`. Eleven of the sixteen emit a flat `fail` with no second tier; five grade into a `cantTell` tier (`aria-allowed-attr`, `aria-deprecated-role`, `aria-prohibited-attr`, `aria-valid-attr-value`, `aria-hidden-focus`). Seventeen atomic rules feed one composite, `wcag-4.1.2-aria-validity`, whose own description says it rolls up checks "that ARIA role and attribute usage conforms to the WAI-ARIA specification"; any single contributor `fail` makes that SC verdict `fail`.
+
+**Why it's being questioned:** the strictness is not in the detection logic, which is conservative and well guarded — `aria-required-children` honours `aria-busy`, accessibility-tree eligibility, `aria-owns` and slot projection; `REQUIRED_PROPS_BY_ROLE` deliberately omits context-dependent properties; `ALLOWED_ROLES_BY_ELEMENT` treats unmodelled elements as unconstrained. It is entirely in the verdict layer, and ACT's own Accessibility Requirements Mapping disagrees with it for most of the family:
+
+| ACT rule | This repo | ACT's primary requirement | WCAG status per ACT |
+|---|---|---|---|
+| `4e8ab6` required states/properties | `aria-required-attr` | ARIA5 technique; ARIA 1.2 §5.2.2 | not required for WCAG conformance; 1.3.1/4.1.2 are secondary and "less strict", they "allow for fallback default values that may make some failures acceptable" |
+| `5c01ea` property permitted | `aria-allowed-attr` | ARIA5 technique; ARIA 1.2 §8.6 | not required for WCAG conformance; 1.3.1/4.1.2 secondary, "less strict" |
+| `5f99a7` attribute defined | `aria-valid-attr` | none | 1.3.1/4.1.2 secondary, "less strict" |
+| `6a7281` valid value | `aria-valid-attr-value` | none | "not required for conformance to WCAG 2.1 at any level" |
+| `674b10` role has valid value | `aria-roles-valid` | ARIA4, G108 techniques | not required for conformance to any W3C recommendation; 4.1.2 "can be satisfied through the implicit role" |
+| `bc4a75` required owned elements | `aria-required-children`, `aria-prohibited-children` | **1.3.1 Info and Relationships** | required for conformance, on **1.3.1** |
+| `ff89c9` required context role | `aria-required-parent` | **1.3.1 Info and Relationships** | required for conformance, on **1.3.1** |
+
+Two separate problems fall out of that table. Five of the seven are ARIA *author* requirements that WCAG does not mandate, reported here as level-A WCAG failures at high confidence. The other two are conformance-required, but on 1.3.1, not the 4.1.2 all three rules declare: a plain SC misattribution that lands the verdict on the wrong criterion (the level is unaffected, both are A). `aria-allowed-role` is the weakest claim in the family — no ACT rule covers it and no external source maps ARIA-in-HTML's permitted-roles table to a Success Criterion, yet it fails at high confidence. Six ARIA rules have no ACT counterpart at all (`ACT_RULE_MAPPING.md`'s no-ground-truth list), which is exactly where the `fail` decision has nothing external checking it.
+
+The distinction ACT is drawing is whether the exposed name, role and value survive the violation. `<button role="buton">` is still exposed as a button; `<div role="checkbox">` with no `aria-checked` gets ARIA's own `false` default, and whether that default is *wrong* is `aria-checked-state-mismatch`'s question, already capped at `cantTell`; `<div role="heading">` with no `aria-level` is still a heading at the user agent's default level; `aria-brailleroledescription` without `aria-roledescription` reaches no user at all and is currently `serious`. Against that, `aria-label` on a roleless `<span>` genuinely loses the name — and that case is already graded, by `aria-prohibited-attr`, on precisely this reasoning.
+
+The engine's stated bar is that `fail` stays reserved for deterministic violations. The family currently reads that as high confidence *that the ARIA specification was violated*, which it reliably is; the argument here is that it should mean high confidence that *the Success Criterion the rule names is failed*, which for most of the family it is not.
+
+**What the graded family looks like:** `aria-hidden-body`, `aria-hidden-focus` and `aria-role-name-present` stay `fail` unchanged — each is a present barrier, not a spec citation. `aria-required-children`/`-prohibited-children`/`-required-parent` stay `fail` on ACT's authority, and are the part of this entry already acted on. Four rules gain a second tier on the fallback-survival axis: `aria-roles-valid` (`fail` only where the host has no implicit role to fall back on, a distinction `getNativeRoleForElement` already computes), `aria-required-attr` (`fail` for `slider`/`scrollbar`/`meter` missing `aria-valuenow`, which is a genuinely absent value; `cantTell` for the roles ARIA gives a default), `aria-valid-attr` (an undefined attribute is inert, so `fail` only where the misspelling plausibly cost the element a name it does not otherwise have), and `aria-braille-equivalent` (the `aria-brailleroledescription` half has no user-facing consequence and should not be `serious`). The remaining question is whether the family needs a third outcome tier altogether — an ARIA-conformance finding that is real, reported, and does not claim a WCAG SC, expressible today as `normative: false` plus a WAI-ARIA `normativeMappings` entry, which would also keep it out of the SC composite.
+
+**What was weighed against changing it:** it moves scans that are red today to yellow, which is a louder change for existing baselines than removing false positives ever was, and it weakens what integrators can gate CI on: `cantTell` is not enforceable the way `fail` is. There is also a real argument for the status quo — an ARIA spec violation is a decent leading indicator even when it is not itself a barrier, since undefined behaviour differs across assistive technology and today's harmless default is tomorrow's regression. The rebuttal is that the package's premise is telling you what it cannot tell you, and a graded `cantTell` carrying a reason code says more than a `fail` that overstates its own authority. Every mechanism this needs already ships: `aria-deprecated-role` grades on the strength of the spec's own statement (MUST NOT versus SHOULD NOT), `resolveTieredOutcome` carries both tiers, the 4.1.1 handling already coerces an out-of-scope SC to `cantTell` with a `wcagVersionScope` field, and `POLICY_CONTRACTS` exposes `allowedOutcomes`/`allowedConfidence`. What is missing is the second axis — grading on whether name, role and value survive, not only on how strongly ARIA words the requirement.
+
+**Two by-products found while reading, both smaller and independently fixable:** `aria-hidden-body` and `aria-role-name-present` were missing the `aria` tag the rest of the family carries, so filtering by tag leaked; both carry it now. The second was wrong as written: `aria-required-parent` is not the only rule emitting a flat `fail` at `medium` confidence, it is one of six, three of them outside the ARIA family, so there is no anomaly at that rule to fix. What the reading did turn up is a documented contradiction, since `OUTPUT_SCHEMA.md` defined `fail` as a high-confidence outcome while six automatic rules shipped `fail` at `medium`; the outcome describes the decision procedure and `confidence` the model it decides against, and the docs say so now. `aria-required-parent` separately gained the `aria-busy` ancestor guard its two siblings already had. `nested-interactive-controls-absent` is untagged for `aria` too, left alone on purpose, since it covers native nesting as much as the ARIA kind.
+
+**Status:** resolved 2026-08-28. The six rules above now grade, `aria-required-attr` and `aria-roles-valid` on a computed predicate and the other four wholesale, with the two implicit-value cases generated from aria-query so the tiers cannot drift from the spec by hand. Across the 137-fixture corpus the change moves 12 rule verdicts and one composite (`wcag-4.1.2-aria-validity`, `fail` to `cantTell` on 13 fixtures); no occurrence count changes anywhere, so nothing stopped being reported. ACT `674b10`, `4e8ab6` and `5f99a7` still run clean against their live corpora (25 cases, 0 mismatches), since the checker counts a `cantTell` carrying occurrences as satisfying a "failed" expectation.
+
+Then the remaining overstatement went too. `aria-allowed-role` declared SC 4.1.2 with no ACT rule and no source mapping ARIA-in-HTML's permitted-roles table to a criterion; it now declares none, tagged `best-practice` with `wcagSc: []`, out of `wcag-4.1.2-aria-validity` and out of the facet registry. It is this engine's first automatic rule with no WCAG mapping, which `meta.normative` could not have expressed (that field is inert) and which needed the composites catalog, the facet registry and the level tags edited by hand. The rule still runs by default, still reports the same findings; on the fixture corpus the only effect is that `wcag-4.1.2-aria-validity` reaches `pass` on 8 fixtures where an ARIA-in-HTML nit was the sole remaining contributor. `docs/RULE_TAXONOMY.md` §1.1 was rewritten alongside it: the automatic/manual line is whether a rule can decide, not which outcome it reports, so a deterministic rule reporting `cantTell` is still automatic.
+
 ### `contrast-minimum`/`contrast-enhanced` treated symbol-only text as real text needing a contrast ratio, fixed
 
 **Decision as it stands (before the fix):** the shared text scan's applicability gate (`isNonEmptyText` in `getTextScan()`, `src/core/contrast-helpers.js`) only checked for non-whitespace characters. A text node made entirely of punctuation/symbol glyphs (`----=====+++...±±±±@@@@@@@@`) counted the same as real words.
@@ -72,7 +130,7 @@ A running log of engine design decisions worth re-examining: cases where an exis
 
 **Decision as it stands (before the fix):** `hasHeading()` credited any `<h1>`-`<h6>`/`[role="heading"]` that was included in the accessibility tree; an off-screen-positioned, clipped, opacity:0, or zero-size-overflow-hidden heading counted the same as a fully visible one. This mismatch was never individually triaged; it sat inside `ye5d6e`/`047fe0`'s combined "1, 2" mismatch count, both filed under one blanket "deliberate leniency" reason that only actually described a *different* shape (a heading positioned inside the repeated content it's supposed to be an escape from).
 
-**Why it was questioned:** re-fetching `047fe0`'s live corpus surfaced a case that reason doesn't cover at all: `<h1 class="off-screen">` inside `<div id="main">`, correctly positioned *after* the repeated nav, still expected **failed** by ACT. Its own Expectation text requires the heading to be both "included in the accessibility tree" *and* "[visible](#visible)." A screen-reader-only heading gives sighted keyboard users no equivalent way to locate the start of non-repeated content, which is exactly the gap `047fe0` is checking for.
+**Why it was questioned:** re-fetching `047fe0`'s live corpus surfaced a case that reason doesn't cover at all: `<h1 class="off-screen">` inside `<div id="main">`, correctly positioned *after* the repeated nav, still expected **failed** by ACT. Its own Expectation text requires the heading to be both "included in the accessibility tree" *and* "[visible](https://www.w3.org/WAI/standards-guidelines/act/rules/047fe0/#visible)." A screen-reader-only heading gives sighted keyboard users no equivalent way to locate the start of non-repeated content, which is exactly the gap `047fe0` is checking for.
 
 **Decision (2026-08-19):** `hasHeading()` now also requires the heading to carry no CSS-hiding hint (`helpers.getVisibilityHintsInfo`: off-screen, clipped, opacity:0, zero-size-overflow-hidden). The sibling `hasMainLandmark()`/`hasWorkingAnchorLink()` checks are left untouched; `cf77f2`'s own live text doesn't carry the same visibility requirement for a `<main>` landmark, confirmed by an existing regression test that pins a clipped-but-accessible `<main>` as still credited.
 
@@ -172,7 +230,7 @@ A running log of engine design decisions worth re-examining: cases where an exis
 
 **Decision as it stands:** `src/checks/automatic/duplicate-id-aria.js` only flags a duplicate `id` when it's referenced by an ARIA ID-reference attribute. Its header comment: "Scoped to ids referenced by ARIA, not the broader/deprecated page-wide duplicate-id check (see ROADMAP.md's 'Skip' list)." That `ROADMAP.md` no longer exists in the repo (not found in the working tree or as a tracked file in `git log`, likely a local planning doc that was never committed), so the original reasoning behind "skip" isn't recoverable verbatim, only the pointer to it.
 
-**Why it's being questioned:** while mining ACT's gap list (per the user's request to find gaps worth turning into new rules), `3ea0c8` "Id attribute value is unique" is exactly this broader page-wide check, and it's detectable with a simple, deterministic document-wide scan. Checked ACT's own SC mapping for it: `3ea0c8` maps to **WCAG 4.1.1 Parsing**, which the Working Group formally **removed in WCAG 2.2** (browsers/AT no longer depend on strict-parsing conformance the way they did when that SC was written), and axe-core deprecated its own equivalent broad `duplicate-id` check around the same time, for the same reason. So the original "skip" call was well-founded *for WCAG 2.2 conformance scoring specifically*.
+**Why it's being questioned:** while mining ACT's gap list for gaps worth turning into new rules, `3ea0c8` "Id attribute value is unique" is exactly this broader page-wide check, and it's detectable with a simple, deterministic document-wide scan. Checked ACT's own SC mapping for it: `3ea0c8` maps to **WCAG 4.1.1 Parsing**, which the Working Group formally **removed in WCAG 2.2** (browsers/AT no longer depend on strict-parsing conformance the way they did when that SC was written) and other accessibility engines deprecated their equivalent broad `duplicate-id` checks around the same time, for the same reason. So the original "skip" call was well-founded *for WCAG 2.2 conformance scoring specifically*.
 
 That said, duplicate IDs are still a real, practical bug independent of which SC currently covers them: they break `<label for>` association, fragment navigation, and any `getElementById`/`querySelector('#...')` call, not just ARIA references. This engine already supports WCAG-version-scoped tagging (`wcag2a`/`wcag21a`/`wcag22aa`-style tags, see `docs/ENGINE_OPTIONS.md`'s WCAG-version filtering). A page-wide duplicate-id rule could be added and tagged as WCAG 2.0/2.1-only (`wcag411`-style, excluded from WCAG 2.2 tag sets) rather than either fully skipped or wrongly counted against 2.2 conformance, the two options the original either/or "skip" decision didn't have room for.
 
@@ -299,3 +357,105 @@ One existing test changed meaning with it: a bare `<option>` under `role="listbo
 **Interaction with the item-wrapper fix above:** the two sets are used for different questions, on purpose. Only a *required* role makes a roleless wrapper an item wrapper, so a wrapper holding nothing but a separator is still interposed content and is still reported under a container that prohibits separators. The allowed set decides only the final verdict.
 
 **Status:** resolved 2026-08-21. Separators in menus/menubars and captions on tables/grids pass; separators under `list`/`listbox`/`tablist`, captions under `treegrid`, and any stray role with no source behind it still fail. The reported allowed-roles list in the failure message now names the full allowed set rather than only the required roles.
+
+### A dangling `aria-controls` was a `fail`, in a rule that cannot see the DOM the reference is about
+
+**Decision as it stood:** `aria-valid-attr-value` treats every ID-reference attribute the same way. An idref-list whose tokens all fail to resolve is an invalid value, hence a `fail` under SC 4.1.2. Exactly one attribute already had a carve-out: `aria-errormessage`, on the strength of ACT 6a7281's own Background text, which names it as a non-required property whose target "may be created in response to an event that may or may not happen."
+
+**Why it was questioned:** that carve-out's reasoning covers `aria-controls` at least as well. A disclosure button, a combobox, a menu button and a tab all name content the widget *builds when it opens*, so the reference is correct and the element genuinely is not in the DOM yet. A static scan that looks for it and does not find it has not established a defect; it has established that it looked at the wrong moment. Other accessibility engines reach the same conclusion: they do not report a missing `aria-controls` target as a violation, and at most ask for a review when the widget is expanded.
+
+**Decision (2026-08-27):** `aria-controls` no longer fails on an unresolved target. When the element carries `aria-expanded="false"` or `aria-selected="false"` the absence is exactly what that state means, so the rule passes outright; otherwise it reports `cantTell` for human review, with reason code `idref-controls-not-found`. Every other idref/idref-list attribute keeps its `fail`, since a dangling `aria-labelledby` or `aria-owns` names content that was supposed to be there already and no state excuses it. The rule now reports two tiers through `helpers.resolveTieredOutcome`, so a real invalid value elsewhere on the page still gates as `fail` and carries the `cantTell` occurrences along rather than dropping them.
+
+**Status:** resolved 2026-08-27.
+
+### SC 4.1.1 Parsing could still fail a WCAG 2.2 run, unless the caller remembered a tag
+
+**Decision as it stood:** `duplicate-id` maps to SC 4.1.1 and carries `wcag22-removed` (see the entry above). The tag was inert engine-side: it existed for consumers to pass to `excludeTags` themselves, and `docs/ENGINE_OPTIONS.md` told them to.
+
+**Why it was questioned:** the package describes itself as a WCAG 2.2 engine, and a plain run, with no tags and no options, still reported a `fail` against a criterion WCAG 2.2 does not contain. The correct behaviour was reachable but opt-in, which is backwards: the default should be right and the deviation should be the thing you ask for. Leaving it to the caller also meant the honesty the tag was created to protect, that "the conformance arithmetic stays honest for every version", only held for callers who knew the tag existed.
+
+**Decision (2026-08-27):** the engine resolves a target WCAG version per run, from `engineOptions.wcagVersion`, else whatever the caller's own version-origin tags imply, else `2.2`, and reports it as `engine.wcagVersion`. Under a 2.2 target a `wcag22-removed` rule cannot report `fail`: it runs, keeps every occurrence, and its outcome is coerced to `cantTell` with a `wcagVersionScope` field naming the removed criterion. Coercing rather than excluding was the deliberate choice, since a duplicate id still breaks `<label for>`, fragment navigation and `getElementById`, so dropping the rule from a 2.2 run would hide a real defect, and this engine's whole premise is telling you what it cannot tell you. `excludeTags: ['wcag22-removed']` still removes it entirely for anyone who wants that. The coercion deliberately does not go through `error`, the channel the two existing coercions use, because consumers read a non-empty `error` as "this rule threw" and nothing went wrong here.
+
+**Status:** resolved 2026-08-27.
+
+### `iframe-title-unique` failed any repeated frame `title`, filed as a deliberate stricter-than-ACT check, now deprecated in favour of `identical-iframes-same-purpose`
+
+**Decision as it stood:** `ACT_RULE_MAPPING.md` recorded that `iframe-title-unique` flags any duplicate `title` attribute on `<iframe>`/`<frame>` elements "by design", a stricter check with no ACT counterpart of its own, and that `4b1c6c` would be closed by a separate rule. `identical-iframes-same-purpose` later closed it, and the two ran side by side, the older one reporting `fail` with `defaultConfidence: 'high'` under a normative mapping to WCAG 4.1.2 level A.
+
+**Why it was questioned:** running ACT 4b1c6c's own test cases against the engine (#16) showed seven of its ten passed examples and one inapplicable example reported as `fail` by `iframe-title-unique`: two frames titled "List of Contributors" both showing `page-one.html`, a directory written with and without its trailing slash, the same page under two paths. WCAG 4.1.2 asks that a frame's name be programmatically determinable, not that it be unique, so a duplicate title establishes no violation, and `POLICY.md` promises that `fail` means a deterministic normative violation. The rule was breaking the engine's own contract, not only disagreeing with ACT. The first proposal (#17 as opened) kept the rule and gave it the sibling's verdict on the `title` attribute: pass when every frame in a set resolves to one resource, `cantTell` otherwise. But a frame's `title` is its accessible name unless `aria-label`/`aria-labelledby` overrides it, and in the one case where the two differ the title becomes the accessible description, a duplicate of which 4.1.2 does not forbid either. Reshaped, the rule reported the same elements, with the same outcome and uncertainty code, as `identical-iframes-same-purpose`, and copied its accessibility-tree gating to do so.
+
+**Decision (2026-09-03):** the rule is deprecated, `replacedBy: 'identical-iframes-same-purpose'`, `sinceVersion: '1.8.0'`, the first use of the mechanism in `API_STABILITY.md`. Because a deprecated rule keeps running and reporting normally, deprecation alone would have left the wrong `fail` alive until 2.0.0, so `runInPage` is reduced to `notApplicable` on every page. The id stays in the catalog until the file is removed in 2.0.0, so a `runOnly` list holding it keeps resolving. `IFRAME_TITLE_DUPLICATE` is no longer emitted and retires with the finding it named: it was listed, with its reason, under `retired` in `scripts/data/released-finding-ids.json` until the 1.8.0 release froze its own inventory, so a stored baseline entry or open Code Scanning alert for it closes, as for a fixed false failure. The rule's facet under SC 4.1.2 is retired and its `coverage.facetsBySc` points at the successor's facet, which the validator requires to be non-empty for a rule with a WCAG mapping; the coverage report leaves deprecated rules out of a facet's coverage (#31), so it does not count as covering it. The scenario fixture is removed rather than left claiming outcomes the rule no longer produces, which is what the fixture-marker check exists to catch; the one case the sibling's tests lacked, several same-named sets on one page where only the set whose resources differ is reported, moved to its test file. This is recorded as a change of mind, not a bug fix: the old behaviour was chosen on purpose, and a stricter check still has to rest on a requirement.
+
+**Revised (2026-10-02):** how the retired code is recorded. The PR first kept `IFRAME_TITLE_DUPLICATE` in `scripts/data/finding-ids.json` through an exemption in `tests/finding-ids.test.js`. Review found that `npm run finding-ids` still dropped it with every test passing, and agreed that the rule would declare its retired codes for the generator to read. Before the PR landed, `main` gained `scripts/data/released-finding-ids.json` and `tests/released-finding-ids.test.js`: what a release shipped is frozen there, no regeneration rewrites it, and a code can go only when it is listed under `retired` with its reason. That closes the same gap without a new deprecation field, so the code is retired there and the exemption was dropped.
+
+**Status:** resolved 2026-09-03. Over the 23 ACT 4b1c6c test cases, passed/inapplicable fixtures yielding `fail` went 8 → 0; every failed example either iframe rule caught before is still `cantTell` from `identical-iframes-same-purpose`.
+
+### `area-alt-present` treated `<area alt="">` as satisfying its check, borrowing `<img>`'s decorative marker for an element that can't be decorative
+
+**Decision as it stands (before the change):** an `<area>` with a present-but-empty `alt` passed `area-alt-present` outright, the same treatment `<img alt="">` gets. A separate manual rule, `area-alt-decorative`, then asked a human to confirm the empty-`alt` area really was decorative.
+
+**Why it was questioned:** `<img alt="">` has a real decorative use: the image can carry zero information while everything else on the page still works. An `<area>` has no equivalent — it exists in a used `<map>` only to be a hyperlink hotspot (that's the whole point of the `usemap`/`href` mechanism), so its HTML-AAM role is `link` and an empty `alt` just means an unnamed link, not a decorative one. There is no redundant sibling content standing in for it the way there is for a decorative image; the geometry itself is invisible.
+
+**Decision (2026-09-14):** `area-alt-present` now fails an `<area>` with `alt=""` and no other accessible name (`aria-label`/`aria-labelledby`/`title` still count, same fallback order as before), with its own summary/hint distinct from the missing-`alt` case. `area-alt-decorative` is retired rather than kept dormant, since "is this decorative" never had a legitimate yes for this element — see [Removed] in `CHANGELOG.md`. `area-alt-quality` (non-empty `alt`, asking whether the text is accurate) is unaffected and stays a legitimate manual question.
+
+**Accepted cost:** `scripts/data/finding-ids.json`'s rule-id inventory drops from 133 to 132. A stored baseline holding a `cantTell` finding against `area-alt-decorative` finds the id gone, not resolved.
+
+**Status:** resolved 2026-09-14.
+
+### `hasBlockingInert` ignored `inert` on an `<area>` itself or on its `<map>`, undocumented since the project's first commit
+
+**Decision as it stands (before the change):** `hasBlockingInert` in `dom-helpers.js` carried an `<area>`-specific exception: `inert` on the area itself, or on its closest `<map>`, was ignored; only an `inert` ancestor outside that chain excluded the area. Present since the very first commit (`4961752`), pinned by a pointed unit test, with no rationale recorded in the commit, this file, or `RULE_AUTHORING.md`.
+
+**Why it was questioned:** the shape reads like a generalization of a different, correct rule — that `aria-hidden` on a focusable element does not remove it from eligibility, since a real user can still Tab onto it (the exact pattern `aria-hidden-focus` exists to catch). `inert` is not `aria-hidden`: the HTML spec has it remove focusability directly, for every element type, with no image-map carve-out in the algorithm, so the "still really reachable" premise that justifies the `aria-hidden` exception does not hold for `inert`. More directly: `aria-hidden-focus.js` already implements this exact question independently (`hasInertAncestor`, walking the element itself and every ancestor) with no `<area>`/`<map>` exception at all — two pieces of code in the same repo disagreed on the identical input, `<area inert>`.
+
+**Decision (2026-09-14):** the exception is removed. `inert` on the `<area>`, its `<map>`, or any ancestor now excludes the area uniformly, matching every other element's default handling and matching `aria-hidden-focus.js`'s own independent check. A genuinely inert `<area>` is `notApplicable` rather than a reported failure.
+
+**Correction (2026-09-14, same day):** wrong. This reasoned from spec text without checking what a real browser actually does, which is exactly the thing the Method section above says to verify. Tested via real keyboard Tab navigation in Chromium and Firefox: an `<area inert>` and an `<area>` inside an `inert <map>` both stay in the tab order. `<area>`/`<map>` generate no box, so a browser's image-map hit-testing sits outside the pipeline `inert` operates on — the original, undocumented exception was empirically correct despite having no stated reason, and the `aria-hidden-focus.js` comparison that seemed to settle the question was comparing the wrong thing: that rule never evaluates `<area>` in practice, so it never had occasion to get this right or wrong. Re-reverted; see the entry below for the full, verified picture, which also turned up two related gaps this entry didn't touch.
+
+**Status:** superseded 2026-09-14 by the entry below.
+
+### `isPlatformFocusable` treated every `<area>` in a used map as focusable, `href` or not, unlike its own `<a>` branch three lines above it, fixed
+
+**Decision as it stands (before the change):** `isPlatformFocusable`'s `tag === 'area'` branch (`dom-helpers.js`) treated an `<area>` as focusable purely for belonging to a `<map>` a rendered `<img usemap>` references — no `href` check. The `tag === 'a'` branch immediately above it requires a non-empty `href` before returning focusable. `area-alt-present` and `area-alt-quality` inherited this: both evaluated any `<area>` in a used map, `href` or not, at their own applicability gate (each rule's local `getReferencingImgForArea`/used-map lookup, not `isPlatformFocusable` itself for the baseline case).
+
+**Why it was questioned:** per the HTML spec, an `<area>` with no `href` does not represent a hyperlink at all — "represents merely a region of the map that has no associated action" — so it is not focusable, not in the accessibility tree as a link, and has no accessible-name requirement to fail. Run against `scripts/other-engine-corpus-check.js` (built 2026-09-14) scoped to a third-party scanner's own area-alt rule, `area-alt-present`'s fixture agreed on exactly one of its seven failing cases — the one case that happened to carry `href` (`area_case_16`). The other six (missing alt, empty alt, aria-hidden-but-focusable, `role="presentation"`, `aria-disabled`, a dangling `aria-labelledby`) all omitted `href` entirely and the other tool didn't flag any of them. `area-alt-present` has no ACT counterpart (`docs/ACT_RULE_MAPPING.md`'s "Extra coverage beyond ACT" list), so this never surfaced through that comparison either — first time this rule had been checked against any outside ground truth. The `<area>` branch's own comment ("Engine policy: treat `<area>` as focusable when it's part of a *used* image map") dated to the project's first commit, with nothing explaining why `href` was left out unlike the `<a>` branch beside it.
+
+**Decision (2026-09-14):** `isPlatformFocusable`'s `<area>` branch now requires a non-empty `href` before doing the used-map lookup, matching the `<a>` branch. `area-alt-present.js` and `area-alt-quality-manual.js` each gained the same `href` check at their own applicability gate, right after the existing used-map lookup, since that gate — not `isPlatformFocusable` — is what actually governs a case's baseline applicability; `isPlatformFocusable`'s branch only mattered for the `aria-hidden`-override and `role="presentation"`-exclusion paths. Both rules' fixtures had `href` retrofitted onto every case testing naming/eligibility logic (all but one case in each fixture previously omitted it), and `area_case_16` in `area-alt-present`'s fixture — previously "href present, still fails" — was repurposed to cover the newly-distinct branch, an `<area>` with no `href` in a used map, since its original point had become redundant with `area_case_01` once every other case also gained `href`.
+
+**Status:** resolved 2026-09-14.
+
+### `<area>`/`<map>` eligibility was checked against the wrong ground truth: spec text and `isAccTreeEligible`'s own layered design, not what a real browser does with a non-rendered element pair
+
+**Decision as it stands (before the change):** three related exclusions, none verified against a real browser. `hidden`/`display:none`/`inert` on the `<area>` itself, or `display:none`/`inert` on its `<map>`, all excluded the area (the entry above covers `inert` specifically; `hidden` and `display:none` on the `<map>` were separate, pre-existing gaps with no carve-out at all, not something this session introduced). Separately, `area-alt-present.js`/`area-alt-quality-manual.js` gated the area's applicability on `isAccTreeEligible(img, ctx)` for the referencing `<img>`, which folds in `aria-hidden`.
+
+**Why it was questioned:** the entry above records getting the `inert` question wrong once already by reasoning from spec text instead of testing it. Doing the same check for `hidden`/`display:none` this time, and testing all of it directly: loaded each scenario in a real page and drove actual keyboard Tab navigation in Chromium and Firefox (WebKit's headless tab handling looked broken in the same harness, so not counted). Result: `hidden` on the `<area>`, and `display:none` or `inert` on the `<map>`, all leave the area fully reachable — same non-rendered-element reasoning as `inert`, just never applied to the other two mechanisms. Separately, `aria-hidden` on the referencing `<img>` also leaves the area reachable, for a different reason: `<area>` is not a DOM descendant of `<img>`, only linked by the `usemap` IDREF, so `aria-hidden` has no ancestor relationship to propagate along, and the img is still rendered regardless of its ARIA state. Gating the area's applicability on the img's full `isAccTreeEligible` — which folds in `aria-hidden` — conflated two different questions: is the img actually rendered (genuinely relevant, since that's what the hotspot geometry depends on) versus is the img exposed to the accessibility tree (irrelevant here).
+
+**Decision (2026-09-14):** `hasBlockingInert`'s `<area>` carve-out is restored (see entry above) with the verified reason recorded this time. The structural `hidden`-attribute check and the CSS `display:none` ancestor check in `isAccTreeEligible` both gained the same carve-out, extended to a `<map>` ancestor as well as the area itself (`visibility:hidden` needed no change — it was already skipped for `<area>` nodes and already gave the right answer). `area-alt-present.js`/`area-alt-quality-manual.js`'s referencing-`<img>` gate switched from `isAccTreeEligible` to `isDomVisibleEligible` (`{ visibilityMode: 'styleOnly', disableGeometry: true }`), the same DOM-only helper `aria-hidden-focus.js` already uses for this exact distinction — `hidden`/`display:none`/`visibility` on the img still excludes the area; `aria-hidden` on the img no longer does. Both fixtures gained the corrected titles/spans and cases, and a note in the `hidden_css`/`inertness` section headings that these mechanisms are ignored on the area/map itself but still block on a genuine outside ancestor.
+
+**Accepted cost:** `area-alt-present`'s fixture goes from 6 failing cases to 11; `area-alt-quality`'s goes from 1 applicable case to 4. Both increases are real markup this rule should have been flagging all along, not new false positives — a genuinely inert or `hidden`-marked `<area>` in a used map, or one behind an `aria-hidden` image, is still a real, reachable, unnamed link.
+
+**Status:** resolved 2026-09-14.
+
+### Ancestor/group `opacity` was treated as an unconditional contrast-computability blocker, even when the backdrop is a single flat resolvable color, fixed
+
+**Decision as it stands (before the change):** `contrast-computable`/`contrast-minimum`/`contrast-enhanced` all reported `cantTell` for any text with a fractional-`opacity` ancestor (group opacity), unconditionally. `contrast-all-scenarios.html`'s `case-blocker-ancestor-opacity` was the documented example: a `<p>` with `color:#000000; background-color:#ffffff; opacity:1` inside a `<div style="opacity:0.5">`, itself on a flat white (`bgWhite`) section.
+
+**Why it was questioned:** run through `scripts/other-engine-corpus-check.js` unscoped against every fixture with a case, this was one of a small number of gaps that survived filtering out same-page noise and matched a same-topic finding (`color-contrast`) from the other tool. Verified directly rather than trusting either side: rendered the fixture in real Chromium and sampled the actual composited pixel color at the text (`(126,126,126)`) against the background (`(255,255,255)`) — a deterministic WCAG contrast ratio of ~4.06, which fails AA's 4.5:1 for normal text. The existing `getComputabilityBlocker` code comment gave the real reason it stayed unconditional: naively combining the existing per-element opacity product (used for the foreground) with the existing ancestor-opacity-aware background walk double-counts the ancestor's opacity, confirmed by hand with a second scenario (a colored ancestor background rather than white-on-white, where the two independently-computed colors landed on a visibly different, wrong answer from real compositing).
+
+**Decision (2026-09-14):** `resolveGroupOpacityColors` in `contrast-helpers.js` resolves both colors in a single walk instead of combining two independently-computed ones after the fact: a background accumulator (as `computeEffectiveBackground` already builds) and a parallel foreground accumulator that receives the text's own color as its innermost layer, with every ancestor's own background-color and opacity applied to *both* accumulators in lockstep. Nothing is combined after the fact, so there is nothing left to double-count, and it handles any number of nested opacity ancestors — with or without their own background-color — uniformly. It only bails (falls back to the existing `ANCESTOR_OPACITY` `cantTell`, unchanged) for a blend-mode/filter/background-image anywhere in the chain, a missing declared text color, or a background that never reaches full opacity even after the whole chain is walked — the genuinely hard general case (a group over a gradient or other unresolvable content) stays exactly as conservative as before. `getComputabilityBlocker`, `computeEffectiveForeground` and `computeEffectiveBackground` all consult it transparently, so no call site elsewhere needed to change. `contrast-all-scenarios.html` gained a second ancestor-opacity case (a gradient sitting further out, beyond the resolvable opacity ancestor) specifically to keep `ANCESTOR_OPACITY` reachable in the fixture corpus `scripts/generate-finding-ids.js` scans — removing that reachability would have silently dropped a still-real reason code from the finding-ids inventory.
+
+**Accepted cost:** the fixture's `case-blocker-ancestor-opacity` moves from `cantTell` (computable) to `pass` for `contrast-computable`, and from excluded to `fail` for `contrast-minimum`/`contrast-enhanced` — a real finding these rules should have caught all along, not a new false positive.
+
+**Status:** resolved 2026-09-14.
+
+### Six ARIA-widget naming rules credited a `<label>` to elements it never actually named, via an unguarded local copy of the label-association lookup
+
+**Decision as it stands (before the change):** `combobox-name-present`, `listbox-name-present`, `searchbox-name-present`, `spinbutton-name-present`, `textbox-name-present` and `slider-name-present` each carried an identical local `getNativeLabelText(el)`, falling back to `el.closest('label')` (wrapping) or a `label[for]` map (`buildLabelForMap`) with no check that `el` was actually a labelable element. Each rule's own JSDoc already stated the intended contract correctly ("On a labelable element (`<input role="combobox">`) an associated `<label>` counts as well") — the implementation just never enforced the "labelable" half of it.
+
+**Why it was questioned:** run through `scripts/other-engine-corpus-check.js` unscoped, `combobox-name-present`/`listbox-name-present`/`searchbox-name-present`/`spinbutton-name-present`/`textbox-name-present` all disagreed with the *same* other-tool rule, `aria-input-field-name` — a recurring pattern across five rules pointed at one systemic thing rather than five coincidences. Verified directly: rendered `<label>Wrapped label text <div role="combobox" tabindex="0"></div></label>` in real Chromium and Firefox and read the actual accessibility tree (`ariaSnapshot()`) — the combobox has no accessible name in either browser, wrapping or `for`-based. `slider-name-present` shared the same buggy local function but never actually triggered it: its own call site already gates the label lookup behind `kind === 'native-slider'`, so it was dead code there, not a live bug — its fixture already had the correct expectation on record.
+
+**Decision (2026-09-14):** all six rules' local `getNativeLabelText` now delegate to the shared `getAssociatedLabelElements` (`dom-helpers.js`), which already correctly restricted the *wrapping* case to `wrap.querySelector(LABELABLE_SELECTOR) === el` but, it turned out, never applied the equivalent check to the `for`-based case — so `getAssociatedLabelElements` itself gained a labelable check up front, benefiting every existing caller, not just these six. That surfaced a second instance of the identical bug one level down: a pinned unit test in `tests/core/dom-helpers-name-computation.test.js` explicitly asserted that `<label for="x">Name</label><div id="x" role="button">` resolves to the name `"Name"` — verified against real Chromium/Firefox as wrong the same way, and corrected alongside a new test pinning the correct behavior for a genuinely labelable target.
+
+**Accepted cost:** each of the five previously-affected rules (not `slider-name-present`) gains two new failing fixture cases — a wrapping-`<label>` case and a `label[for]`-plus-empty-content-title-fallback case — both real markup a screen reader user hears as unnamed, not new false positives.
+
+**Status:** resolved 2026-09-14. `form-control-single-label.js` and `binary-control-name-present.js` have their own separate, similarly-unguarded `closest('label')` fallbacks, not touched here since their applicability already appears scoped to genuinely labelable elements (not verified) — worth a look if they ever start evaluating non-labelable targets.