git:20260930.d245d89 to git:20261004.5bbf263

- description: Plans and implements end-to-end tests for the PABX monorepo (tests/e2e/) using @playwright/test against the running app — one user flow per test, an action and its observable result, traced to the contract's surfaces and criteria by tags. Runs interactively (3 phases with an approval checkpoint) when a user calls directly, or autonomously (no pause) when dispatched by implement-feature/evaluator/qa-preflight. Also runs in correction mode to fix a specific failing e2e test, and in guard mode to add the missing test a report names. Enforces PABX rules (session reuse under the login rate limit, missing data fails instead of skipping, own data removed through the product, no SQL, headless). Never modifies production code nor the e2e harness.

- # E2E Test Writer (PABX)

- Plan and implement **end-to-end tests** that drive the running PABX app through a real browser:

- a user acts on the screen and the test asserts what observably follows. **Never modifies

- production code, the e2e harness, or `tests/visual/`** — if a test fails, only the test is

- > **Project scope:** PABX monorepo. All hard rules (the boundary with the visual and

- > integration suites, harness layout, session, assertions, data, execution) are in

- > **`references/pabx-rules.md`** — read it before writing.

- > `pabx-rules.md`** (TypeScript, one test per file, `specs/*.plan.md`, a seed that logs in),

- > **`pabx-rules.md` wins.**

- **Scope:** `tests/e2e/` — `tests/e2e/admin/**` and `tests/e2e/agent/**`.

- - `target` (required) — what to cover: contract surface ids (`UI-02`), criterion ids (`OC-08`), or a route for work outside a contract (then the route's slug stands in for the surface id in the file name and tags — rule S1). A report's `targetSurface` is a surface id optionally followed by its route (`UI-01 /agent-dashboard/tickets`, or `UI-02` alone), or a route alone when there is no contract. When the caller names specific behaviors, only those are in scope; otherwise every flow behavior of the surface is.

- - `test_file_path` / `profile` (`admin` | `agent`) / `batch_size` (optional; default 4, range 3–5).

- - New/expanded `tests/e2e/<profile>/*.spec.js`, each test tagged per rule S3.

- - A checklist `docs/<feature-id>-<kebab>/e2e-test.md` (planning may be Portuguese; test code follows rule S4) whose **coverage table** gives every row of the contract's `Test-suite hint` an outcome from **the closed list in `pabx-rules.md` ("Coverage outcomes")** — rows this dispatch covers get their result, rows it does not touch keep what a previous dispatch wrote (or `not in this request` when new), and **no `disputed` entry is ever removed by the writer** (only the `evaluator` closes a dispute). The `evaluator`, `implement-feature` and the validator reject anything else. Without a feature, next to the spec with the same basename and `.e2e-test.md`.

- - **One signal to the caller**, always one of: *done* (paths); **"not resolved — product diverges from `<ref>`: <observed>"** (with the path of every new test kept red); **"not resolved — environment: <which>"** (environment red, harness missing, a stack this skill does not cover, or tests written whose two proving runs could not happen — with their paths, marked unproven).

- - Production code, the harness and `tests/visual/` untouched.

- so it conforms to the PABX rules and passes — **when the test is what is wrong**. If the product

- 1. Read the e2e section of `GATES.md` and confirm the harness exists (rule H1). Missing → return **"not resolved — environment: e2e harness not built"**.

- 2. Environment preflight (rule E2): frontend answers, backend answers, **the dev server's last build succeeded** (read its log). Any failure → return **"not resolved — environment: <which>"**.

- 3. Read the contract: the target surfaces (initial state, behaviors), the observable criteria, the test-suite hint. Keep the in-scope behaviors that are **flows**; list the rest as out of scope with the suite they belong to (Boundary table in `pabx-rules.md`).

- 4. Read existing `tests/e2e/` for helpers and to avoid duplicating a flow already covered.

- 5. Explore each flow live with `playwright-cli`, **through a harness run** — `--config playwright.e2e.config.js --debug=cli` on a test of the right profile (its seed, for instance), then `attach` — so the stored session is reused, never a fresh login. **A write flow is explored under rule D6**: the attached page has no test fixtures, so create and remove the exploration's records through the API with the page's own token, or capture the request and abort it with `page.route(...)`. Note the locators and the requests each action fires.

- 6. For every flow that writes: what it creates (its own customer before its own ticket), what pre-existing configuration it only references, which API fixture removes it, and through which delete route (rules D1–D5).

- One row per behavior: contract id, profile, precondition data (existing, or created by the

- test), action, observable result, request assertion (V6), cleanup and its fixture. A flow that

- cannot be e2e gets a `not e2e-testable` outcome, and a behavior that is not a flow at all (a

- computed value, a theme) gets `out of e2e scope — <suite>` — both **only as the closed list in

- `pabx-rules.md` words them**; any other wording is rejected downstream and burns an attempt.

- Such rows stay with the evaluator or the human QA.

- - **Interactive:** ask — is every flow behavior covered? does any test write without a removal path? is any filter validated with an empty result? → **WAIT for approval.**

- GROUP 3–5 tests per batch (same surface and profile) → IMPLEMENT per `pabx-rules.md` → **prove

- each new test can fail**: in **every** new test invert the expectation on **the result of the

- action** — not a precondition — and run the batch once, confirming each is red at that line →

- against a defect still present flips the other way — inverted green, restored red — and that

- is its proof. → UPDATE the checklist and its coverage table (a test whose two runs could not

- happen stays `unproven`) → REPEAT.

- 3. Run only the failing test with `--config playwright.e2e.config.js --debug=cli`, attach, and diagnose.

- - Follow `references/pabx-rules.md` exactly (boundary, harness, session, assertions, data, execution).

- - Tag every test per S3; every row of the test-suite hint carries an outcome of the closed list in `pabx-rules.md`, and `disputed` entries are left as they are.

- - Create the test's own records, its own customer before its own ticket, and remove them through the product; cleanup always runs and fails loudly.

- - Modify production code, the harness (config, global setup, seed tests, shared fixtures) or anything under `tests/visual/`.

- - Log in inside a test, hook or fixture, read a storage-state file directly, forge a session, or bypass reCAPTCHA.

- - Skip on missing data, validate a filter with an empty result, or bend an assertion — existing or new — to match the screen.

- - Measure computed styles or boxes — that is the visual gate's suite.

- - Touch the database directly (SQL, `knex`, `mysql2`, the MySQL MCP).

- - **Harness missing, or the API fixture a write flow's setup needs is missing:** the first is "not resolved — environment: e2e harness not built"; the second puts that flow under D5 — report the gap. Building either is the `gate-builder` e2e gate type's job.

- - **The contract's test-suite hint predates the e2e suite** and maps a flow to `tests/visual/`: follow the Boundary table, write the e2e test, note the old hint in the checklist, leave the visual suite alone.

- - **The behavior is a computed value** (contrast, height, density): `out of e2e scope — visual gate` in the coverage table.

- - **The target file is under `tests/visual/`:** out of scope — report it; do not migrate it.

- - **A person watches an exploration session headed:** start in the **dark theme** (project accessibility rule), light only afterwards.

- - **Stack not PABX:** "not resolved — environment: stack not covered by e2e-test-writer" — the caller needs a generic approach.