suaveplan/openspec/changes/enterprise-testing-a11y/proposal.md

Why

The 2026-04-25 test-suite audit (/mnt/s/web/genesis/docs/superpowers/specs/2026-04-25-test-suite-audit.md §2 + §7) flagged "no accessibility testing" as a critical gap. CLAUDE.md's "Web App & Page Verification" section requires every Playwright spec to verify rendered DOM correctness — a 200 response is not proof of correctness — yet nothing in the canonical openspec/specs/testing-e2e/spec.md enforces a11y. WCAG 2.1 AA conformance is a non-negotiable enterprise quality bar; shipping pages without an automated axe-core sweep means defects reach users.

This change adds first-class accessibility coverage to @suaveplan/testing-e2e via @axe-core/playwright, and makes a project-wide invariant that every page-level spec under apps/testbed/e2e/ SHALL assert zero serious / critical violations alongside the existing console- and network-monitor invariants.

What Changes

New surface in @suaveplan/testing-e2e

• attachAxe(page, options?): AxeHandle — returns { assertNoViolations(opts?), getViolations(opts?) }.
• Default rule set: WCAG 2.1 AA (['wcag2a','wcag2aa','wcag21a','wcag21aa']).
• serious and critical impact violations fail by default; moderate and minor fail in strict: true mode.
• Per-call overrides: runOnly, disableRules, include, exclude selectors.
• Dedicated reporter: violations dumped to playwright-report/a11y/<spec>.json with rule, impact, target selectors, and HTML snippet.
• Structured errors with stable codes under TESTING_E2E.A11Y.* (VIOLATIONS_FOUND, AXE_LOAD_FAILED, INVALID_RULESET).

Modified surface

• apps/testbed/e2e/**/*.spec.ts page-level specs SHALL invoke axe.assertNoViolations() after page load.
• The release-readiness gate (cross-link to the enterprise-testbed-verification change tracked separately) fails on any axe violation surfaced by these specs.

Capabilities

New Capabilities

(none — this is an extension to the existing testing-e2e capability)

Modified Capabilities

• testing-e2e: adds the attachAxe helper, structured TESTING_E2E.A11Y.* error codes, and a per-spec invariant requiring an axe sweep on every page-level spec.

Impact

• Affected code: /mnt/s/web/genesis/packages/testing/testing-e2e/src/a11y/** (new feature module), /mnt/s/web/genesis/apps/testbed/e2e/** (per-spec invariant additions).
• Catalog adds: @axe-core/playwright to catalogs.testing in root package.json.
• Coverage: axe wrapper code held to 100% Istanbul coverage (statements/branches/functions/lines). No "foundation only" carve-out — every package is 100% per openspec/project.md §Quality gates.
• Consumers: every downstream app or package that runs Playwright specs against rendered pages SHALL adopt the invariant.
• Cross-links: release-readiness gate is owned by the enterprise-testbed-verification change; this change wires the a11y check into it but does not own the gate itself.
• No version bump: @suaveplan/testing-e2e stays at 0.1.0 per genesis lifecycle.