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

Tasks

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Catalog and dependency wiring

• 1.1 Add @axe-core/playwright to catalogs.testing in root /mnt/s/web/genesis/package.json (exact version, no bare strings).
• 1.2 Add the catalog ref to packages/testing/testing-e2e/package.json dependencies.
• 1.3 Run the nuclear clean install per openspec/AGENTS.md §1 to lock the version.

2. attachAxe implementation

• 2.1 Create packages/testing/testing-e2e/src/a11y/attach-axe.ts exporting attachAxe(page, options?) returning AxeHandle.
• 2.2 Implement assertNoViolations(opts?) — builds an AxeBuilder, runs, filters by impact, throws A11yError with code TESTING_E2E.A11Y.VIOLATIONS_FOUND on failure.
• 2.3 Implement getViolations(opts?) — returns the raw violation array without throwing.
• 2.4 Implement strict mode — when true, moderate + minor also fail.
• 2.5 Validate runOnly tags — unknown WCAG tags throw TESTING_E2E.A11Y.INVALID_RULESET.
• 2.6 Wrap axe-core injection — failures throw TESTING_E2E.A11Y.AXE_LOAD_FAILED with the underlying cause.

3. Reporter

• 3.1 Create packages/testing/testing-e2e/src/a11y/a11y-reporter.ts writing violations to playwright-report/a11y/<spec>.json.
• 3.2 Wire it into attachAxe so every assertion (pass or fail) emits its result.

4. Schemas, types, errors

• 4.1 Add attach-axe.schemas.ts with Zod schemas for options and reporter output.
• 4.2 Add attach-axe.types.ts for AxeHandle, A11yOptions, A11yViolation.
• 4.3 Add A11yError subclass of TestingE2eError to src/errors/.

5. Tests

• 5.1 Unit tests in src/a11y/attach-axe.test.ts covering: violations found, no violations, strict mode, disableRules, include/exclude, INVALID_RULESET, AXE_LOAD_FAILED.
• 5.2 Property tests over the impact-filter predicate using fast-check.
• 5.3 Integration test against a known-bad fixture page asserting at least one serious violation.
• 5.4 Cross-cutting test in tests/a11y-reporter.test.ts verifying the JSON report shape round-trips through the schema.

6. Docs

• 6.1 Sibling attach-axe.md (≥200 words, basic + advanced examples, full API reference, implementation notes).
• 6.2 Sibling a11y-reporter.md.
• 6.3 Update packages/testing/testing-e2e/README.md Modules section.

7. Subpath exports

• 7.1 Add "./a11y/attach-axe" and "./a11y/a11y-reporter" to package.json exports.
• 7.2 Verify subpath count matches feature module count.

8. Testbed adoption

• 8.1 Update every apps/testbed/e2e/*.spec.ts page-level spec to invoke axe.assertNoViolations() after page load.
• 8.2 Cross-link the release-readiness gate in ../enterprise-testbed-verification so a11y violations fail the gate.

9. Pre-publish gate

• 9.1 bunx turbo lint typecheck test --filter=@suaveplan/testing-e2e green.
• 9.2 bunx turbo test:coverage --filter=@suaveplan/testing-e2e at 100% statements / branches / functions / lines.
• 9.3 Banned-pattern scan clean (@deprecated, TODO, ts-ignore, .skip, .only).
• 9.4 Missing-.md scan clean.

10. Spec archive

• 10.1 Fold specs/testing-e2e/spec.md deltas into openspec/specs/testing-e2e/spec.md.
• 10.2 Move this folder to openspec/archive/<yyyy-mm-dd>-enterprise-testing-a11y/.