gennady 0.6.0 → 0.7.0

package/dist/ai/directives/testing/playwright-cli.xml

@@ -0,0 +1,199 @@
+<PlaywrightCli keywords="playwright, playwright-cli, e2e-exploration, ax-tree, trace-viewer, codegen, debug, headless, locator-picker, aria-snapshot, screenshot, self-verify" type="testing-rules" ver="2.0">
+  <Mission>
+    Canonical rules for exploring a running web application through Playwright CLI BEFORE codifying a committed e2e test. This directive gives every execution-agent perception (AX tree, screenshots, trace viewer) and interaction (role-based locators, codegen) so it can see the page, manipulate it, and confirm that the rendered structure matches intent.
+
+    **Base axiom:** the rendered DOM is the only ground truth for an e2e test contract. Writing a test from memory, from a design doc, or from a guess produces locators that pass type-check and fail at runtime. So the order is fixed: navigate → snapshot AX tree → interact → snapshot delta → only then codify. The CLI session is the source of evidence for every locator and every assertion in the committed test.
+
+    Tooling reference (canonical CLI surface):
+    - `page.goto(url)` / `page.ariaSnapshot()` — primary navigation and perception channel.
+    - `page.getByRole(...)` — primary interaction surface.
+    - `page.screenshot({ fullPage: true })` — secondary visual channel for layout-only concerns.
+    - `npx playwright test --trace=on` + `npx playwright show-trace trace.zip` — failure diagnosis with DOM snapshots and timeline.
+    - `npx playwright codegen [url]` — interaction recorder; output requires review before commit.
+    - `npx playwright test --update-snapshots` — baseline rewrite (gated; see `AX_CLI_SNAPSHOT_UPDATE_GATE`).
+
+    Companion (codification of observations into committed tests): `ai/directives/testing/playwright-e2e.xml`.
+  </Mission>
+
+  <Depends_On>
+    - ai/directives/coding/typescript-rules.xml
+  </Depends_On>
+
+  <Belief_State>
+    <Axiom id="AX_CLI_EXPLORE_BEFORE_AUTHOR">
+      Exploration MUST precede authoring. Agent first sees the page through `page.ariaSnapshot()`, then interacts through `page.getByRole(...)`, then captures the post-state. Only after this loop completes does codification into a committed test file begin.
+
+      A locator that has never been resolved against a running page is a guess; committing it bypasses the only ground truth the test has.
+    </Axiom>
+
+    <Axiom id="AX_CLI_AX_TREE_AS_PRIMARY_VISION">
+      `page.ariaSnapshot()` is the primary perceptual channel for an agent. It emits a YAML representation of the accessibility tree — the same structure that `getByRole()` queries and `toMatchAriaSnapshot()` asserts. So the AX tree is the lingua franca across explore → interact → assert.
+
+      Pixel-level vision (screenshots, visual diff) is a secondary channel reserved for layout-only concerns. Choosing it as the primary signal binds the test to rendering pipelines that vary across machines.
+    </Axiom>
+
+    <Axiom id="AX_CLI_HEADLESS_FOR_AGENT">
+      Every CLI exploration session for an agent runs headless. The `--headed` / `--ui` / `--debug` modes are human-only — they assume a sighted operator at the terminal. An agent that opens a headed window has no consumer for the visual output and burns the session waiting for user input that will never arrive.
+    </Axiom>
+
+    <Axiom id="AX_CLI_ROLE_LOCATORS_FROM_AX_TREE">
+      Every locator used during exploration is derived from the AX tree just observed (`getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, `getByTestId`). CSS classes, ID selectors, and XPath expressions are forbidden as the primary locator strategy — they bind the test to implementation details that have no contract status.
+    </Axiom>
+
+    <Axiom id="AX_CLI_DEV_SERVER_PRECONDITION">
+      Every CLI command depends on a running application. The agent confirms the dev server is reachable (HTTP 200 at the expected URL, or the project's known boot-complete signal) BEFORE issuing the first Playwright call. Skipping this turns the first `page.goto` failure into a confusing «Playwright is broken» investigation instead of a one-line «start the dev server» fix.
+    </Axiom>
+
+    <Axiom id="AX_CLI_EXPLORE_LOOP_HAS_FOUR_STEPS">
+      The exploration loop is fixed at four steps and runs to completion before any test file is touched:
+      1. **Explore** — `page.goto(url)`; `page.ariaSnapshot()`; read structure.
+      2. **Interact** — `page.getByRole(...).click()` / `.fill()` / `.press()`; re-capture `ariaSnapshot()`; observe delta.
+      3. **Verify** — compare observed structure against expected intent; if mismatch, fix the component first, restart, re-explore.
+      4. **Capture** — record the final AX snapshot and any required screenshots as the basis for the committed test.
+
+      Skipping a step (e.g. interacting without re-snapshotting) hides the contract drift the loop exists to surface.
+    </Axiom>
+
+    <Axiom id="AX_CLI_TRACE_FOR_FAILURE_DIAGNOSIS">
+      When a test fails, the primary diagnostic is `playwright test --trace=on` followed by inspecting the trace via `show-trace`. The trace contains DOM snapshots at each step, network requests, console logs, and a timeline — enough to attribute the failure to a real cause instead of guessing.
+
+      «Edit the test until it passes» without trace inspection is forbidden — it routinely mutes real regressions by relaxing the assertion.
+    </Axiom>
+
+    <Axiom id="AX_CLI_CODEGEN_IS_RECORDER_NOT_AUTHOR">
+      `playwright codegen` records interactions but its output is NOT directly committable. The generated locators are typically CSS / nth-child / XPath chains — fragile and implementation-coupled. The agent reviews codegen output and replaces every selector with a role-based equivalent derived from the AX tree before any line of it lands in a committed file.
+    </Axiom>
+
+    <Axiom id="AX_CLI_SNAPSHOT_UPDATE_GATE">
+      `npx playwright test --update-snapshots` (rewriting AX/visual baselines) is a gated action. Allowed without confirmation only for the very FIRST snapshot of a NEW test (no prior baseline existed). For any update to an existing baseline the agent MUST stop, present the old vs new snapshot to the operator, name the cause of the diff (intentional UI change vs unexpected regression), and wait for explicit confirmation.
+
+      Silent `--update-snapshots` on every failure is the single most direct path for an agent to fabricate a green test under e2e.
+    </Axiom>
+
+    <Axiom id="AX_CLI_TRANSITION_TO_AUTHORING">
+      Exploration is complete only when: AX snapshot of the target region captured; every interactive element located via `getByRole(...)`; observed structure matches intent. At that point the agent transitions to `playwright-e2e.xml` for codification. Committing a test while exploration is still mid-loop produces a test that asserts the wrong contract.
+    </Axiom>
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_CLI_AX_SNAPSHOT">
+      Output of `locator.ariaSnapshot()` — YAML representation of the accessibility subtree rooted at `locator`. Default scope is partial (a region or named role), not full page.
+    </Definition>
+    <Definition id="DEF_CLI_TRACE">
+      Output of `playwright test --trace=on` — a `.zip` containing DOM snapshots at each test step, network entries, console logs, and a timeline. Inspected via `npx playwright show-trace trace.zip`.
+    </Definition>
+  </Definitions>
+
+  <Code_Patterns>
+    <Pattern id="PT_CLI_EXPLORE_LOOP">
+      <Intent>Canonical four-step exploration loop captured as a script before any test file is touched.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        // explore.session.ts — throwaway exploration script, NOT committed as a test.
+        import { chromium } from 'playwright';
+
+        const browser = await chromium.launch();
+        const context = await browser.newContext();
+        const page = await context.newPage();
+
+        // 1. Explore
+        await page.goto('http://localhost:5173/checkout');
+        console.log(await page.getByRole('region', { name: 'Checkout' }).ariaSnapshot());
+
+        // 2. Interact
+        await page.getByRole('textbox', { name: 'Email' }).fill('user@test.com');
+        await page.getByRole('button', { name: 'Place Order' }).click();
+
+        // 3. Verify — snapshot after interaction; compare delta against intent
+        console.log(await page.getByRole('region', { name: 'Checkout' }).ariaSnapshot());
+
+        // 4. Capture — final snapshot is the seed for the committed test's toMatchAriaSnapshot
+        await browser.close();
+        ```
+      </Snippet>
+      <Why>One concrete URL, role-based locators derived from the previous snapshot, two snapshots framing the interaction so the delta is observable. The script itself is not committed — it is the audit trail for the committed test's contract.</Why>
+    </Pattern>
+  </Code_Patterns>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_CLI_WRITE_TEST_WITHOUT_AX_TREE">
+      <Bad>Agent reads the design doc, writes `await page.locator('.submit-btn').click()` straight into a committed test file without ever running `page.ariaSnapshot()` against a live page.</Bad>
+      <Why_Bad>Locator never resolved against ground truth (`AX_CLI_EXPLORE_BEFORE_AUTHOR`). `.submit-btn` is a CSS class — implementation-coupled, with no contract status (`AX_CLI_ROLE_LOCATORS_FROM_AX_TREE`). First run fails or, worse, matches a different element with the same class and produces a misleading green.</Why_Bad>
+      <Good>Run the exploration loop, observe `- button "Place Order"` in the AX snapshot, then write `await page.getByRole('button', { name: 'Place Order' }).click()` in the committed test.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_CLI_CSS_XPATH_FROM_CODEGEN">
+      <Bad>Agent runs `playwright codegen`, copies `page.locator('#root > div:nth-child(3) > button.submit')` straight into the committed test.</Bad>
+      <Why_Bad>Codegen output committed without review (`AX_CLI_CODEGEN_IS_RECORDER_NOT_AUTHOR`). The structural path breaks on the first DOM reordering, and the CSS class is implementation-coupled. Codegen is a recorder, not an author.</Why_Bad>
+      <Good>Read the AX snapshot of the same region, replace the generated locator with the role-based equivalent (`getByRole('button', { name: 'Submit' })`) before any line of codegen output lands in the test.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_CLI_SKIP_TRACE_ON_FAILURE">
+      <Bad>Test fails red; agent edits the assertion (`toMatch` → `toContain` → eventual deletion of the assertion) until the test passes, never running `--trace=on`.</Bad>
+      <Why_Bad>Failure diagnosed by mutation of the test instead of inspection of the actual run (`AX_CLI_TRACE_FOR_FAILURE_DIAGNOSIS`). Real regressions get silenced by progressively weaker assertions; the trace would have shown what actually happened in 30 seconds.</Why_Bad>
+      <Good>`npx playwright test --trace=on path/to/failing.spec.ts`; `npx playwright show-trace test-results/.../trace.zip`; identify whether the failure is in the component (fix component) or in the test's contract (fix test, with the new contract documented).</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_CLI_HEADED_FOR_AGENT">
+      <Bad>Agent's exploration script launches the browser via `chromium.launch({ headless: false })` or invokes `npx playwright test --headed --ui`.</Bad>
+      <Why_Bad>Visual UI modes targeted at a human operator (`AX_CLI_HEADLESS_FOR_AGENT`). Agent has no consumer for the rendered window; the run hangs waiting for human input or burns CPU drawing pixels nobody reads.</Why_Bad>
+      <Good>Default headless: `chromium.launch()` (no `headless: false`). Perception flows through `ariaSnapshot()`, screenshots written to disk for retrospective review, traces for failure diagnosis.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_CLI_AUTO_UPDATE_SNAPSHOTS">
+      <Bad>CI fails on an AX snapshot diff; agent's response is `npx playwright test --update-snapshots` followed by a commit of the regenerated baselines.</Bad>
+      <Why_Bad>Snapshot baseline rewritten silently (`AX_CLI_SNAPSHOT_UPDATE_GATE`). The diff might have been a real regression; auto-update turns regressions into «accepted contract changes» with no operator visibility. Classic agent-side green-fabrication path.</Why_Bad>
+      <Good>Inspect the diff in the test-results report or via `show-trace`; if intentional, present old vs new snapshot to the operator, get confirmation, then `--update-snapshots` on the specific file; if unintentional, fix the component.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Workflow_Outline>
+    <Step id="WF_CLI_1_PREREQ">Confirm Playwright installed (`npx playwright --version`); if absent, `npm i -D @playwright/test &amp;&amp; npx playwright install --with-deps chromium`. Confirm dev server reachable at the expected URL.</Step>
+    <Step id="WF_CLI_2_EXPLORE">`page.goto(url)`; `page.ariaSnapshot()`; identify roles, accessible names, nesting.</Step>
+    <Step id="WF_CLI_3_INTERACT">`page.getByRole(...).click()` / `.fill()` / `.press()`; re-snapshot after each meaningful step; observe delta.</Step>
+    <Step id="WF_CLI_4_CAPTURE">Final AX snapshot of the target region; screenshots only when the test concerns visual layout.</Step>
+    <Step id="WF_CLI_5_TRANSITION">When exploration confirms structure matches intent, transition to `playwright-e2e.xml` for codification.</Step>
+  </Workflow_Outline>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_CLI_PLAYWRIGHT_INSTALLED">
+      <Purpose>Playwright + Chromium are installed and reachable.</Purpose>
+      <Command>npx playwright --version &amp;&amp; npx playwright install --dry-run chromium</Command>
+      <Expected>Version string printed; Chromium reported as already installed (or installed by the command).</Expected>
+    </Hook>
+    <Hook id="HOOK_CLI_DEV_SERVER_REACHABLE">
+      <Purpose>Dev server is reachable at the expected URL before exploration.</Purpose>
+      <Command>curl -fsS -o /dev/null -w "%{http_code}\n" "${BASE_URL:-http://localhost:5173}"</Command>
+      <Expected>HTTP 200 (or the project's known boot-complete status). Non-2xx means dev server is not ready; start it before exploring.</Expected>
+    </Hook>
+    <Hook id="HOOK_CLI_NO_HEADED_IN_AGENT_SCRIPTS">
+      <Purpose>No agent-committed script forces headed mode or `--ui`.</Purpose>
+      <Command>find . \( -name '*.ts' -o -name '*.js' \) -not -path '*/node_modules/*' -print0 | xargs -0 grep -nE 'headless\s*:\s*false|--headed|--ui|--debug' || true</Command>
+      <Expected>Empty output. Matches must either be human-only debugging scripts (excluded from the agent's workflow) or removed.</Expected>
+    </Hook>
+    <Hook id="HOOK_CLI_NO_AUTO_UPDATE_SNAPSHOTS">
+      <Purpose>Detect that the agent did not run `--update-snapshots` silently against an existing baseline.</Purpose>
+      <Command>git log -1 --name-only --pretty=format: | grep -E '\.snap$|snapshots/' || true</Command>
+      <Expected>If snapshot files appear in the last commit, the commit message MUST reference operator confirmation; uncomfirmed updates are a violation.</Expected>
+    </Hook>
+  </Verification_Hooks>
+
+  <Reward_Criteria>
+    ✅ Exploration loop completed (explore → interact → verify → capture) before any test is authored.
+    ✅ AX tree is the primary perceptual channel; screenshots reserved for visual-layout concerns.
+    ✅ Locators come from the just-observed AX tree; role-based queries only.
+    ✅ Headless for every agent-driven session; `--headed` / `--ui` / `--debug` reserved for humans.
+    ✅ Dev server reachability confirmed before the first `page.goto`.
+    ✅ Failures diagnosed via `--trace=on` + `show-trace`, not by mutating the assertion until green.
+    ✅ Codegen output reviewed and rewritten to role-based locators before commit.
+    ✅ Snapshot baseline updates pass operator confirm; first-baseline writes are the only ungated case.
+
+    ❌ Test authored without ever running `page.ariaSnapshot()` against a live page.
+    ❌ CSS / ID / XPath selectors used as primary locators.
+    ❌ Codegen output committed verbatim.
+    ❌ Test failure debugged by weakening or deleting assertions instead of inspecting the trace.
+    ❌ Agent-driven session running in `--headed`, `--ui`, or `--debug` mode.
+    ❌ `npx playwright test --update-snapshots` against an existing baseline without operator confirmation.
+    ❌ Committing a test while exploration is still mid-loop.
+  </Reward_Criteria>
+</PlaywrightCli>

package/dist/ai/directives/testing/playwright-e2e.xml

@@ -0,0 +1,292 @@
+<PlaywrightE2ERules keywords="playwright, e2e, aria-snapshot, role-locators, page-objects, fixture, storage-state, network-mock, route, visual-regression, self-verify" type="testing-rules" ver="2.0">
+  <Mission>
+    Canonical rules for authoring Playwright E2E tests. Every execution-agent MUST perceive the page through `page.ariaSnapshot()`, locate elements via `getByRole()` only, and codify the observed contract into committed test files backed by fixture-based Page Objects.
+
+    **Base axiom:** an e2e test asserts a USER-FACING contract — what a screen-reader-equivalent observer sees and what a role-driven interaction does. Anything in the test that ties to CSS classes, DOM structure, or pixel coordinates is contract leakage and will break on the first refactor that does not affect the contract. So locators come from accessible roles, structural assertions come from `toMatchAriaSnapshot`, and visual regression is reserved for explicitly visual concerns.
+
+    Scope: codification — turning exploration observations into committed test files. Companion (exploration before authoring): `ai/directives/testing/playwright-cli.xml`.
+  </Mission>
+
+  <Depends_On>
+    - ai/directives/coding/typescript-rules.xml
+    - ai/directives/testing/playwright-cli.xml
+  </Depends_On>
+
+  <Belief_State>
+    <Axiom id="AX_E2E_AX_TREE_AS_CONTRACT">
+      The accessibility-tree snapshot (`ariaSnapshot()` + `toMatchAriaSnapshot()`) IS the structural contract. It encodes roles, accessible names, and hierarchy — the same surface a screen reader perceives. Textual/structural assertions on the DOM (e.g. `toContainText`) are allowed where AX granularity is insufficient (specific dynamic copy), but they supplement the AX snapshot, not replace it.
+    </Axiom>
+
+    <Axiom id="AX_E2E_ROLE_LOCATORS_ONLY">
+      Locator vocabulary is fixed: `getByRole`, `getByLabel`, `getByPlaceholder`, `getByText`, `getByTestId`. CSS selectors (`.class`, `#id`), XPath, and `nth-child` chains are forbidden as primary locators — they bind the test to implementation details with no contract status. `getByTestId` is a last-resort fallback for elements with no semantic role, and it is reserved for stable test IDs the component team owns.
+    </Axiom>
+
+    <Axiom id="AX_E2E_FIXTURE_BASED_POM">
+      Page Objects extend Playwright's `test.extend` fixtures — they are NOT standalone classes the test instantiates by hand. Fixture lifecycle (setup per test, teardown after) is the framework's job; bypassing it by `new SomePage(page)` reintroduces the cleanup problem the fixtures solve.
+
+      One fixture file per business domain (e.g. `auth.fixture.ts`, `checkout.fixture.ts`); unrelated domains do NOT merge into one fixture file.
+    </Axiom>
+
+    <Axiom id="AX_E2E_STRUCTURE_AX_FIRST">
+      Test structure is fixed:
+      1. Navigate (`page.goto`).
+      2. Capture / assert structure via `toMatchAriaSnapshot` on a scoped region.
+      3. Interact via `getByRole(...)`.
+      4. Assert the delta via another `toMatchAriaSnapshot` (or focused role-based assertion).
+
+      Skipping the first AX assertion turns the test into «click + hope»; without an initial baseline the interaction's delta has nothing to be a delta from.
+    </Axiom>
+
+    <Axiom id="AX_E2E_SNAPSHOT_PARTIAL_BY_DEFAULT">
+      AX snapshots are scoped to a NAMED region by default (`page.getByRole('region', { name: '...' }).ariaSnapshot()`). Full-page snapshots are reserved for tests whose contract IS the full page (e.g. a landing-page structure test). Defaulting to full-page snapshots produces brittle baselines that explode on every unrelated nav/sidebar change.
+    </Axiom>
+
+    <Axiom id="AX_E2E_AUTH_VIA_STORAGE_STATE">
+      Authentication is handled exclusively via `storageState`: a setup project runs the login flow once, writes `storageState.json`, and dependent projects reuse it. Inline login inside every test is forbidden — it slows the suite, couples every test to the login UI, and turns a login regression into a cascading red across the entire suite.
+    </Axiom>
+
+    <Axiom id="AX_E2E_NETWORK_MOCK_AT_ROUTE">
+      External API calls are mocked via `page.route()` / `context.route()` at the network boundary. Mocking at the component level or hand-patching `window.fetch` is forbidden — it bypasses the request flow the production code actually exercises and routinely misses headers, CORS, or retries.
+
+      If the project standardises on a network-mocking harness (MSW, in-house helper), tests reuse it consistently rather than introducing a parallel mocking path per test.
+    </Axiom>
+
+    <Axiom id="AX_E2E_VISUAL_REGRESSION_GATED">
+      Visual regression (`toHaveScreenshot()`) is enabled ONLY when the task explicitly requires pixel-level verification. Default contract verification is structural (AX) + behavioural (interaction). Visual regression baselines drift across font rendering, OS chrome, and unrelated CSS, so they belong only on routes that genuinely care about pixels.
+    </Axiom>
+
+    <Axiom id="AX_E2E_FILE_LAYOUT">
+      Project-wide layout: tests under `e2e/tests/`, fixtures under `e2e/fixtures/`, auth setup under `e2e/auth/`, snapshot baselines under `e2e/__snapshots__/`. One subject per test file; one domain per fixture file. Mixing layouts forces every reader-agent to grep for the convention instead of trusting it.
+    </Axiom>
+
+    <Axiom id="AX_E2E_FILE_SIZE_BUDGET">
+      Soft target ≤200 lines per test file; hard ceiling 300 lines (code only). Approaching the budget triggers extraction of shared logic into fixtures or helpers; exceeding it triggers a split by scenario family. Past the ceiling, instruction-following degrades and the file becomes a maintenance liability.
+    </Axiom>
+
+    <Axiom id="AX_E2E_BROWSER_COVERAGE_PRAGMATIC">
+      Default browser coverage is Chromium. Firefox / WebKit projects are added ONLY when multi-browser support is an explicit ticket requirement. Running every test on every browser inflates CI time without proportional contract evidence; per-route multi-browser opt-in is the trade-off.
+    </Axiom>
+
+    <Axiom id="AX_E2E_HEADLESS_ALWAYS">
+      Test execution is headless. `--headed` is a human-only debugging mode and never appears in committed scripts or CI configuration.
+    </Axiom>
+
+    <Axiom id="AX_E2E_SELF_VERIFICATION_LOOP">
+      After authoring: `npx playwright test --project=chromium`. Observe output → fix failures (in component or test) → re-run. Loop continues until green. Submitting a red test without an EXPLICIT blocker note in the ticket is forbidden — silent red turns the suite into noise the next agent must reverse-engineer.
+    </Axiom>
+  </Belief_State>
+
+  <Definitions>
+    <Definition id="DEF_E2E_FIXTURE_POM">
+      A Page Object exposed as a Playwright fixture: `const test = base.extend&lt;{ checkout: CheckoutPage }&gt;({ checkout: async ({ page }, use) => { await use(new CheckoutPage(page)); } });`. Tests then declare `checkout` in their argument list and receive a fresh per-test instance.
+    </Definition>
+    <Definition id="DEF_E2E_AX_CONTRACT">
+      The YAML emitted by `ariaSnapshot()` IS the structural contract. Diffs against the committed baseline (`toMatchAriaSnapshot`) signal either a real regression or an intentional UI change requiring an operator-confirmed baseline update.
+    </Definition>
+  </Definitions>
+
+  <Code_Patterns>
+    <Pattern id="PT_E2E_AX_SNAPSHOT_BASELINE">
+      <Intent>Navigate to a route, assert the structural baseline against the AX snapshot of a named region.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        import { expect, test } from '@playwright/test';
+
+        test('should render checkout form', async ({ page }) => {
+          await page.goto('/checkout');
+          await expect(
+            page.getByRole('region', { name: 'Checkout' }),
+          ).toMatchAriaSnapshot(`
+            - heading "Checkout" [level=1]
+            - textbox "Email"
+            - button "Place Order"
+          `);
+        });
+        ```
+      </Snippet>
+      <Why>Scoped to the `Checkout` region — not the full page. AX literal expresses the contract in role/name terms only.</Why>
+    </Pattern>
+
+    <Pattern id="PT_E2E_INTERACTION_DELTA">
+      <Intent>Interact via role locator; assert the AX delta after the interaction.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        test('should show validation error on empty submit', async ({ page }) => {
+          await page.goto('/checkout');
+          await page.getByRole('button', { name: 'Place Order' }).click();
+          await expect(
+            page.getByRole('region', { name: 'Checkout' }),
+          ).toMatchAriaSnapshot(`
+            - textbox "Email" [invalid=true]
+            - text: "Email is required"
+          `);
+        });
+        ```
+      </Snippet>
+      <Why>Interaction via `getByRole`; delta asserted as a second AX snapshot of the same scoped region.</Why>
+    </Pattern>
+
+    <Pattern id="PT_E2E_FIXTURE_POM">
+      <Intent>Fixture-based Page Object — instantiated by the framework lifecycle, not by the test.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        // e2e/fixtures/checkout.fixture.ts
+        import { test as base, expect } from '@playwright/test';
+        import { CheckoutPage } from './checkout.page';
+
+        export const test = base.extend&lt;{ checkout: CheckoutPage }&gt;({
+          checkout: async ({ page }, use) => {
+            await use(new CheckoutPage(page));
+          },
+        });
+        export { expect };
+
+        // e2e/tests/checkout.spec.ts
+        import { expect, test } from '../fixtures/checkout.fixture';
+
+        test('happy path', async ({ checkout }) => {
+          await checkout.navigate();
+          await checkout.fillEmail('user@test.com');
+          await checkout.submit();
+          await expect(checkout.confirmation).toMatchAriaSnapshot(`
+            - heading "Order placed" [level=1]
+          `);
+        });
+        ```
+      </Snippet>
+      <Why>Test declares only `checkout`; the fixture handles construction per test. No `new CheckoutPage(...)` in the test body.</Why>
+    </Pattern>
+
+    <Pattern id="PT_E2E_AUTH_SETUP_PROJECT">
+      <Intent>Auth handled once via a setup project; dependent projects reuse `storageState`.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        // playwright.config.ts (excerpt)
+        export default defineConfig({
+          projects: [
+            { name: 'setup', testMatch: /auth\.setup\.ts$/ },
+            {
+              name: 'chromium',
+              use: { storageState: 'e2e/auth/user.json' },
+              dependencies: ['setup'],
+            },
+          ],
+        });
+        ```
+      </Snippet>
+      <Why>Login runs once; every chromium test starts already authenticated. No inline login per test.</Why>
+    </Pattern>
+
+    <Pattern id="PT_E2E_NETWORK_MOCK">
+      <Intent>Mock an external API at the network boundary; production code path is otherwise untouched.</Intent>
+      <Snippet language="typescript">
+        ```typescript
+        test('should show confirmation when order API succeeds', async ({ page }) => {
+          await page.route('**/api/orders', async (route) => {
+            await route.fulfill({
+              status: 200,
+              contentType: 'application/json',
+              body: JSON.stringify({ orderId: 'ord-1', status: 'confirmed' }),
+            });
+          });
+          await page.goto('/checkout');
+          await page.getByRole('button', { name: 'Place Order' }).click();
+          await expect(page.getByRole('status')).toContainText('Order ord-1');
+        });
+        ```
+      </Snippet>
+      <Why>`page.route` intercepts at the network layer; component code runs unchanged. Assertion via `getByRole('status')`.</Why>
+    </Pattern>
+  </Code_Patterns>
+
+  <Anti_Patterns>
+    <Anti_Pattern id="AP_E2E_CSS_LOCATOR">
+      <Bad>`await page.locator('.btn-primary.submit-action').click();` — CSS class chain as the primary locator.</Bad>
+      <Why_Bad>CSS selectors couple the test to implementation (`AX_E2E_ROLE_LOCATORS_ONLY`). Any class rename — even one driven by a refactor that does not change behaviour — turns the test red. The user-facing contract has no concept of `.btn-primary`.</Why_Bad>
+      <Good>`await page.getByRole('button', { name: 'Place Order' }).click();` — role + accessible name, mirroring how the user identifies the element.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_E2E_INLINE_LOGIN">
+      <Bad>Every test begins with `await page.goto('/login'); await page.getByLabel('Email').fill(...); await page.getByLabel('Password').fill(...); await page.getByRole('button', { name: 'Sign in' }).click();`.</Bad>
+      <Why_Bad>Inline login per test (`AX_E2E_AUTH_VIA_STORAGE_STATE`). One regression in the login UI cascades into every test going red; the suite spends most of its time logging in instead of exercising the contract being tested.</Why_Bad>
+      <Good>Extract the login flow into a setup project that writes `storageState.json`; configure the test project with `use: { storageState: 'e2e/auth/user.json' }, dependencies: ['setup']`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_E2E_FULL_PAGE_SNAPSHOT">
+      <Bad>`await expect(page).toMatchAriaSnapshot(\`- banner ... - main ... - contentinfo ...\`);` — full-page snapshot for a test that only verifies the checkout region.</Bad>
+      <Why_Bad>Snapshot scope mismatched to test intent (`AX_E2E_SNAPSHOT_PARTIAL_BY_DEFAULT`). Any change to the unrelated banner / footer / sidebar produces a snapshot diff that has nothing to do with the test's contract. Maintenance cost balloons; signal-to-noise drops.</Why_Bad>
+      <Good>Scope to the region under test: `await expect(page.getByRole('region', { name: 'Checkout' })).toMatchAriaSnapshot(\`...\`);`.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_E2E_STANDALONE_POM">
+      <Bad>`class CheckoutPage { constructor(page) { this.page = page; } } ... test('...', async ({ page }) => { const checkout = new CheckoutPage(page); ... });`</Bad>
+      <Why_Bad>Page Object instantiated by the test instead of supplied by a fixture (`AX_E2E_FIXTURE_BASED_POM`). Reintroduces the manual setup/teardown problem fixtures solve; no per-test lifecycle isolation; the page object cannot expose its own fixture-managed state (intercepts, storage, helpers).</Why_Bad>
+      <Good>Define `test = base.extend({ checkout: async ({ page }, use) => use(new CheckoutPage(page)) })`; the test declares `checkout` as an argument and receives a fresh per-test instance.</Good>
+    </Anti_Pattern>
+
+    <Anti_Pattern id="AP_E2E_UNMOCKED_NETWORK">
+      <Bad>Test exercises `/checkout` against the real backend; flakiness is «accepted» because the backend is «usually up».</Bad>
+      <Why_Bad>External dependency not mocked (`AX_E2E_NETWORK_MOCK_AT_ROUTE`). The test depends on infrastructure state outside the contract under test; one downstream incident turns the suite red and erodes trust. Worse, it cannot exercise failure paths because the real backend will not produce them on demand.</Why_Bad>
+      <Good>`await page.route('**/api/orders', route => route.fulfill({ status: 200, body: JSON.stringify(fixture) }));` for the happy path; `route.fulfill({ status: 500 })` for the failure path.</Good>
+    </Anti_Pattern>
+  </Anti_Patterns>
+
+  <Workflow_Outline>
+    <Step id="WF_E2E_1_EXPLORE">Run the exploration loop in `playwright-cli.xml` to capture AX snapshots and confirmed locators against the running app.</Step>
+    <Step id="WF_E2E_2_CODIFY">Author the fixture file (if a Page Object is needed) and the test file: AX baseline → interaction via role locator → AX delta.</Step>
+    <Step id="WF_E2E_3_MOCK_AND_AUTH">Mock external APIs via `page.route()`; reuse the auth setup project rather than logging in inline.</Step>
+    <Step id="WF_E2E_4_SELF_VERIFY">`npx playwright test --project=chromium`; fix failures (component or test); re-run until green.</Step>
+    <Step id="WF_E2E_5_FINALIZE">Confirm file under budget; snapshots scoped; no CSS/XPath locators; no inline login; no committed `.only` / `.skip` without deferred-ownership reference.</Step>
+  </Workflow_Outline>
+
+  <Verification_Hooks>
+    <Hook id="HOOK_E2E_RUN_CHROMIUM">
+      <Purpose>Run the e2e suite on Chromium.</Purpose>
+      <Command>npx playwright test --project=chromium</Command>
+      <Expected>Exit 0; all tests pass.</Expected>
+    </Hook>
+    <Hook id="HOOK_E2E_NO_CSS_LOCATORS">
+      <Purpose>Smoke-grep for forbidden CSS / XPath locator forms in test files.</Purpose>
+      <Command>find e2e -name '*.spec.ts' -o -name '*.test.ts' 2>/dev/null | xargs grep -nE "page\.locator\(['\"]([.#]|\.\\.|//|xpath=)" || true</Command>
+      <Expected>Empty output. Matches must be rewritten as `getByRole` / `getByLabel` / `getByTestId` derived from the AX tree.</Expected>
+    </Hook>
+    <Hook id="HOOK_E2E_NO_HEADED">
+      <Purpose>No committed configuration runs Playwright in headed mode.</Purpose>
+      <Command>find . \( -name 'playwright.config.*' -o -name '*.spec.ts' -o -name '*.test.ts' \) -not -path '*/node_modules/*' -print0 | xargs -0 grep -nE 'headless\s*:\s*false|--headed' || true</Command>
+      <Expected>Empty output.</Expected>
+    </Hook>
+    <Hook id="HOOK_E2E_FILE_SIZE_BUDGET">
+      <Purpose>Test files stay under the 300-line hard ceiling (code only).</Purpose>
+      <Command>find e2e -name '*.spec.ts' -o -name '*.test.ts' 2>/dev/null | while read f; do lines=$(grep -cvE '^\s*(//|/\*|\*|$)' "$f"); [ "$lines" -gt 200 ] &amp;&amp; echo "$lines $f"; done | sort -n</Command>
+      <Expected>No file exceeds 300 code-lines. Files over 200 carry a tracked split task or explicit justification.</Expected>
+    </Hook>
+    <Hook id="HOOK_E2E_NO_ONLY_OR_SKIP">
+      <Purpose>No committed `.only` / `.skip` without a deferred-ownership reference.</Purpose>
+      <Command>find e2e -name '*.spec.ts' -o -name '*.test.ts' 2>/dev/null | xargs grep -nE '\b(test|describe)\.(only|skip|fixme)\b' || true</Command>
+      <Expected>Empty output, or each match accompanied by an inline `TASK-` reference.</Expected>
+    </Hook>
+  </Verification_Hooks>
+
+  <Reward_Criteria>
+    ✅ AX snapshot is the structural contract; `toMatchAriaSnapshot` on scoped regions before and after interaction.
+    ✅ Locators come from accessible roles, labels, placeholders, text, or stable test IDs — never CSS / XPath / nth-child.
+    ✅ Page Objects exposed as fixtures via `test.extend`; one fixture file per business domain.
+    ✅ Auth via `storageState` from a setup project; no inline login per test.
+    ✅ External APIs mocked at the network boundary via `page.route()`; project-wide harness reused consistently.
+    ✅ Visual regression (`toHaveScreenshot`) used only when the contract is genuinely visual.
+    ✅ Files live under the documented layout (`e2e/tests/`, `e2e/fixtures/`, `e2e/auth/`, `e2e/__snapshots__/`).
+    ✅ Test files under 200 code-lines (soft) / 300 (hard); past the budget → split by scenario family.
+    ✅ Headless execution everywhere; self-verification loop completes before handoff.
+
+    ❌ CSS classes, IDs, XPath, or nth-child as primary locators.
+    ❌ Inline login inside every test.
+    ❌ Full-page AX snapshots for tests that target a specific region.
+    ❌ Standalone Page Object instantiated by the test (`new SomePage(page)`).
+    ❌ External APIs left unmocked; component-level `fetch` patching.
+    ❌ Visual regression baselines for tests whose contract is structural.
+    ❌ Test file exceeds the 300-line hard ceiling.
+    ❌ Committed `test.only` / `test.skip` / `test.fixme` without deferred-ownership reference.
+    ❌ Snapshot baselines updated silently via `--update-snapshots`.
+    ❌ Red test handed off without an EXPLICIT blocker note.
+  </Reward_Criteria>
+</PlaywrightE2ERules>