@1aboveio/skills 0.10.0

package/skills/engineering/e2e-test/references/ci-playwright-container.md

@@ -0,0 +1,280 @@
+# Playwright in CI Containers (the preferred default)
+
+**Running Playwright in the official pinned container is the preferred way to run
+every CI browser job** — not a fallback for special runners. Two sanctioned
+options, in order:
+
+1. **Docker (preferred):** the job runs in `mcr.microsoft.com/playwright:<version>`
+   — GitHub-hosted via `container:`, self-hosted via explicit `docker run` (below),
+   Cloud Build via the step's `name:`. Browsers and OS deps ship in the image, so
+   there is **no per-job `playwright install`**, the rendering environment is **pinned
+   and identical** across jobs and machines (what makes visual baselines viable), and
+   a version bump is one tag edit.
+2. **Plain runner (alternative):** `ubuntu-latest` + `npx playwright install
+   --with-deps chromium` per job. Acceptable for a simple repo, but it re-downloads
+   browsers every job (cache `~/.cache/ms-playwright` if you keep this) and the
+   rendering environment drifts with the runner image. Prefer option 1.
+
+The `ci-gates.*` templates default to option 1; `ci-audit.mjs` reports the pinned
+container as a *preferred* convention (advisory — option 2 stays sanctioned).
+**Keep every image pin in a workflow identical**, matching the repo's
+`@playwright/test` version.
+
+Also use this reference on self-hosted Docker/Podman runners, an intentionally
+minimal runner image, or when CI fails with a browser shared-library error:
+
+```text
+error while loading shared libraries: libnspr4.so
+```
+
+That failure usually means Playwright is running directly in the runner
+container/host image — the official GitHub runner image is not a browser runtime
+and lacks Chromium dependencies. Do not fix it by installing random packages every
+job. Put the Playwright job in the official Playwright container, and let the app
+repo install its matching `@playwright/test` version via its package manager.
+
+## Standard GitHub Actions Pattern
+
+Prefer a normal self-hosted job that runs the official Playwright image manually
+with `docker run`. On rootless Podman-backed GitHub runners, native Actions
+`container:` jobs can fail before checkout because the runner auto-bind-mounts
+`/var/run/docker.sock` into the job container:
+
+```text
+Error response from daemon: container create: statfs /var/run/docker.sock: permission denied
+```
+
+That is runner/daemon plumbing, not a Playwright or app failure. The manual
+`docker run` pattern below keeps checkout and Actions setup on the runner, runs the
+browser work inside the Playwright image, and avoids mounting the Docker socket
+into the Playwright container.
+
+```yaml
+jobs:
+  e2e:
+    runs-on: [self-hosted, linux, x64, docker]
+    timeout-minutes: 10
+
+    env:
+      E2E_WORKERS: "4"
+      PLAYWRIGHT_IMAGE: mcr.microsoft.com/playwright:v1.61.0-noble
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Playwright in the official image
+        run: |
+          docker run --rm \
+            --network host \
+            --ipc=host \
+            --cpus 4 \
+            --memory 16g \
+            -e CI=true \
+            -e E2E_WORKERS="${E2E_WORKERS}" \
+            -v "${GITHUB_WORKSPACE}:/work:z" \
+            -w /work \
+            "${PLAYWRIGHT_IMAGE}" \
+            bash -lc 'corepack enable && pnpm install --frozen-lockfile && pnpm exec playwright test'
+```
+
+Choose the image tag to match the repo's `@playwright/test` version. If the
+package version and image version differ, install the matching browsers inside
+the Playwright container before the run:
+
+```bash
+pnpm exec playwright install chromium
+```
+
+Prefer matching versions instead. It avoids network installs and prevents
+browser/protocol mismatch failures.
+
+## Native `container:` Jobs
+
+Use native Actions `container:` only after the runner fleet has a passing smoke
+test for GitHub's generated job-container mounts, including the automatic
+`/var/run/docker.sock` bind. Useful on a compatible Docker runner, but not the
+portable default for rootless Podman-backed runner containers.
+
+```yaml
+container:
+  image: mcr.microsoft.com/playwright:v1.61.0-noble
+  options: --user 1001 --ipc=host --cpus 4 --memory 16g
+```
+
+If a native job-container workflow fails in `Initialize containers`, do not debug
+application code or Playwright first. Read the generated `docker create` line in
+the job log and verify every auto-mounted host path exists and can be `statfs`'d by
+the daemon.
+
+## Resource Envelope and Workers
+
+Document the intended per-job resource envelope and make the Playwright container
+enforce it. In the 1aboveio runner setup each slot is sized `4 CPU / 16 GB`, so
+Playwright jobs use `--cpus 4`, `--memory 16g`, `--ipc=host`, and:
+
+```yaml
+env:
+  E2E_WORKERS: "4"
+```
+
+The runner container's compose limits do not reliably cap sibling job containers
+created through the Docker/Podman socket. Put `--cpus`/`--memory` on the Playwright
+`docker run` or native job container when you need deterministic limits.
+
+Start with 4 Playwright workers for Chromium E2E on a `4 CPU / 16 GB` job. If the
+app server is heavy, the suite launches multiple browser contexts per test, or CI
+shows OOM/browser crashes under concurrent jobs, reduce PR-lane workers to 2 and
+reserve 4 for manual/nightly/integration-lane runs. The Playwright config reads the
+env rather than hardcoding:
+
+```ts
+// `|| 4`, not `?? 4`: an empty/garbage E2E_WORKERS must fall back too
+// (Number('') is 0, which Playwright rejects).
+workers: process.env.CI ? Number(process.env.E2E_WORKERS) || 4 : undefined,
+```
+
+## Service Containers
+
+With the recommended manual `docker run` pattern the Actions job does not use
+`jobs.<job>.container`, so GitHub service containers publish dynamic ports to the
+runner host. Run the Playwright container with `--network host` and connect through
+`127.0.0.1:${{ job.services.<name>.ports[...] }}`:
+
+```yaml
+jobs:
+  e2e:
+    runs-on: [self-hosted, linux, x64, docker]
+    timeout-minutes: 10
+
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: app
+        ports:
+          - 5432/tcp
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      PLAYWRIGHT_IMAGE: mcr.microsoft.com/playwright:v1.61.0-noble
+      E2E_WORKERS: "4"
+      DATABASE_URL: "postgresql://test:test@127.0.0.1:${{ job.services.postgres.ports[5432] }}/app"
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Playwright in the official image
+        run: |
+          docker run --rm \
+            --network host \
+            --ipc=host \
+            --cpus 4 \
+            --memory 16g \
+            -e CI=true \
+            -e E2E_WORKERS="${E2E_WORKERS}" \
+            -e DATABASE_URL="${DATABASE_URL}" \
+            -v "${GITHUB_WORKSPACE}:/work:z" \
+            -w /work \
+            "${PLAYWRIGHT_IMAGE}" \
+            bash -lc 'corepack enable && pnpm install --frozen-lockfile && pnpm prisma:migrate:deploy && pnpm exec playwright test'
+```
+
+GitHub Actions networking changes when `jobs.<job>.container` is present: service
+containers are on the same Docker/Podman network as the job container. Reach them by
+service label and container port:
+
+```yaml
+jobs:
+  e2e:
+    runs-on: [self-hosted, linux, x64, docker]
+    container:
+      image: mcr.microsoft.com/playwright:v1.61.0-noble
+      options: --user 1001 --ipc=host --cpus 4 --memory 16g
+
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_USER: test
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: app
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    env:
+      DATABASE_URL: postgresql://test:test@postgres:5432/app
+
+    steps:
+      - uses: actions/checkout@v4
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm prisma:migrate:deploy
+      - run: pnpm exec playwright test
+```
+
+Without a native job container, workflow steps run directly in the runner
+environment; reach services through the mapped localhost port:
+
+```yaml
+DATABASE_URL: "postgresql://test:test@127.0.0.1:${{ job.services.postgres.ports[5432] }}/app"
+```
+
+Do not mix the two models. A Playwright job container using
+`127.0.0.1:${{ job.services.postgres.ports[5432] }}` will often fail because
+`127.0.0.1` is the job container itself, not the host namespace where the port was
+published.
+
+## Self-Hosted Docker/Podman Runner Checks
+
+Before blaming Playwright, verify the runner can create sibling job/service
+containers. A rootless Podman-backed runner container needs: the Podman socket
+mounted; `DOCKER_HOST=unix:///run/user/<uid>/podman/podman.sock`; user/group mapping
+that can read the socket; SELinux labels disabled for the socket mount on SELinux
+hosts. Equivalent smoke checks:
+
+```bash
+# Runner container can reach the Docker-compatible Podman API.
+docker ps
+
+# A service container can publish a dynamic localhost port.
+docker run -d --name pg-smoke \
+  -e POSTGRES_USER=test \
+  -e POSTGRES_PASSWORD=test \
+  -e POSTGRES_DB=testdb \
+  -p 127.0.0.1::5432 \
+  postgres:17
+port="$(docker port pg-smoke 5432/tcp | sed 's/.*://')"
+docker run --rm --network host postgres:17 \
+  pg_isready -h 127.0.0.1 -p "$port" -U test
+docker rm -f pg-smoke
+```
+
+When this smoke passes but Playwright still fails with missing shared libraries,
+the workflow is running Playwright in the wrong container. Move the Playwright steps
+into the official Playwright image through `docker run` instead of adding browser
+dependencies to the runner image.
+
+## Review Checklist
+
+When reviewing/writing CI for Playwright on self-hosted Docker runners:
+
+- Playwright job runs `mcr.microsoft.com/playwright:<matching-version>-noble` through
+  explicit `docker run`, unless the fleet has proven native `container:` support.
+- A native `container:` job failing `Initialize containers` with
+  `statfs /var/run/docker.sock: permission denied` → runner socket auto-mount
+  incompatibility; switch to the manual `docker run` pattern.
+- The repo still runs `npm ci`/`pnpm install`; the image supplies browsers and OS
+  deps, not the app's node_modules.
+- `@playwright/test` and the image tag are aligned, or the workflow explicitly
+  installs matching browsers.
+- Manual `docker run` + `services.postgres`: `DATABASE_URL` uses
+  `${{ job.services.postgres.ports[5432] }}` on `127.0.0.1`, Playwright container uses
+  `--network host`. Native job container + `services.postgres`: `DATABASE_URL` uses
+  `postgres:5432`, not `127.0.0.1:<mapped-port>`.
+- The runner setup has a smoke check proving sibling service containers work.

package/skills/engineering/e2e-test/references/debugging.md

@@ -0,0 +1,36 @@
+# Debugging E2E Failures
+
+## Quick Triage
+
+1. Check the PR comment for which tests failed and why
+2. Check the GH Actions run log (link in PR comment)
+3. Download artifacts: `test-results/` and `playwright-report/`
+
+## Common Failures
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Timeout waiting for selector | Page didn't load or element renamed | Check service URL reachable; run test locally |
+| `ERR_TOO_MANY_REDIRECTS` | Auth cookie/secret mismatch | Verify E2E secrets match deployed service |
+| `reference is not a tree` | Short SHA passed to checkout | Use full 40-char commit SHA or branch name |
+| `ERR_CONNECTION_REFUSED` | Service not ready at test start | Add health-check wait loop before tests |
+| Flaky pass/fail | `waitForTimeout` or shared state | Replace with explicit waits; isolate tests |
+
+## Viewing Playwright Report Locally
+
+```bash
+# Download artifacts from GH Actions, then:
+npx playwright show-report path/to/playwright-report
+```
+
+## Re-running Failed Tests
+
+From GH Actions UI: click "Re-run failed jobs."
+
+Or trigger manually:
+```bash
+gh workflow run e2e.yml --repo 1aboveio/<repo> \
+  -f environment=dev \
+  -f service_url=https://<service>.run.app \
+  -f sha=<commit>
+```

package/skills/engineering/e2e-test/references/presentation-sweep.md

@@ -0,0 +1,131 @@
+# Presentation Sweep (the third coverage axis)
+
+A green functional suite can pass while a route throws on render — when the only spec for that route **intercepts its own API** (`page.route('**/api/**')`), it never exercises the real render path that crashes. The presentation sweep catches this: it opens **every manifest route** in a real browser over the real render path (no first-party interception) and asserts the presentation floor **spine first**. It is the runner half of ensure-coverage's presentation axis (that skill *grades* the axis; this skill *runs* it — see ensure-coverage `references/presentation/runner-contract.md`).
+
+**It is a separate gate from the functional/journey suite, even though both use Playwright.** A passing functional E2E run is not the presentation gate.
+
+## Instruments (import into a spec, or use the sweep)
+
+| Level | Spine? | Instrument | Catches |
+|---|---|---|---|
+| `presentation:render-health` | **yes** | `scripts/presentation-render-health.mjs` | `pageerror` / `console.error` / error boundary / HTTP ≥500 on render — **and through interactions** (mutate-health, see below) |
+| `presentation:spatial` | | `scripts/presentation-checks.mjs` | horizontal overflow / element overlap |
+| `presentation:perceivability` | | `scripts/presentation-perceivability.mjs` | contrast / invisible-but-present controls |
+| `presentation:reachability` | | `scripts/presentation-reachability.mjs` | nav orphans / missing affordance cues |
+| `presentation:temporal` | | `scripts/presentation-temporal.mjs` | layout shift |
+| `presentation:visual` | | `scripts/presentation-visual.mjs` (Playwright `toHaveScreenshot()`) | **opt-in** pixel drift from a committed baseline — restyle/wrong-content/visually-broken |
+
+Per-route spec usage (tag it so the Coverage Ledger resolves it):
+```ts
+// @covers /tasks
+// @level presentation:render-health
+import { test } from '@playwright/test'
+import { assertRenderHealthy } from '<skill-dir>/scripts/presentation-render-health.mjs'
+
+test('/tasks renders without error', async ({ page, baseURL }) => {
+  await assertRenderHealthy(page, '/tasks', { origin: baseURL }) // throws on pageerror/console.error/5xx
+})
+```
+
+## The sweep (mandatory for browser-route changes)
+
+Run the whole-manifest sweep — this is the CI gate, not a per-route afterthought:
+```bash
+E2E_AUTH_BYPASS=1 node <skill-dir>/scripts/presentation-sweep.mjs \
+  --manifest e2e/route-manifest.json --base-url http://127.0.0.1:3000 \
+  --out docs/tests/_generated/presentation-results.json [--fixtures e2e/sweep-fixtures.mjs]
+```
+It exits non-zero on any `fail`/`blocked` and writes the per-`(route, level)` result the ledger consumes.
+
+**Fixtures the repo supplies** (`--fixtures` default export): `applyAuth(context)` (a seeded/bypass session so guarded routes render as a real user), `paramResolver(route)` (a concrete seeded id per dynamic segment like `/tasks/[id]`), and optional `ignoreRoutes` / `spatialIgnore` allowlists. **A route the harness cannot render** (no `DATABASE_URL`, auth unavailable, unresolved param) is reported `blocked` — never silently skipped or passed. "Could not check" is not "checked and fine."
+
+#### "No in-app way to view it" is not blocked
+
+Reaching the route is your job. The sweep navigates *by URL*, so a route with no nav link or in-app entry point is still fully reachable. `blocked` is reserved for the genuinely un-renderable conditions above; "I had no convenient route to it" is never an excuse to skip the gate or merge without it. Stand up the local build (dev server + disposable DB + seeded/bypass auth) and drive the route's URL directly:
+
+- **Manifest route → `presentation-sweep.mjs`** (the canonical CI gate above) — the result the ledger and reviewer consume; run it whenever the route is in the manifest.
+- **Ad-hoc one-route check → `agent-browser` (preferred).** Navigate, screenshot the states that matter (expanded/collapsed/popover), read the console, clean up. The default for "is this one route OK before I merge."
+- When agent-browser doesn't fit: **chrome-devtools MCP** for devtools surfaces (console, network, a perf/Lighthouse trace) alongside the render; **raw Playwright** (`page.goto(url)`) when scripting navigation into an authored spec.
+
+All load the **real render path** (no first-party interception) — the whole point. Do this *before* merging; "there was no route to view it" before that build exists means the build was never stood up, not that the check was impossible.
+
+## render-health is continuous (mutate-health)
+
+The sweep only proves the **load** path — it never clicks submit (write paths are destructive and need valid domain input). But render-health must also hold **through** a write. Reuse the same watcher in authored mutation journeys and interaction-driven checks so an uncaught error / `console.error` / first-party 5xx fired *during* the action fails too — composed, not a re-driven form:
+
+```ts
+import { assertHealthyThrough } from '<skill-dir>/scripts/presentation-render-health.mjs'
+import { assertRemovedAfterMutation } from '<skill-dir>/scripts/presentation-perceivability.mjs'
+
+// fill + submit, assert durable state changed (the depth journey) AND nothing threw:
+await assertHealthyThrough(page, async () => {
+  await page.getByRole('button', { name: 'Delete' }).click()
+  await assertRemovedAfterMutation(page, row)   // perceivability post-state
+}, { origin: baseURL })
+```
+
+This is "mutate-health" — render-health × the trigger/mutation pattern `presentation:temporal` (`assertNoFirstPartyShift({ trigger })`) and `presentation:perceivability` (`assertRemovedAfterMutation`) already use. The journey's durable-state assertion stays as-is; this adds "…and nothing threw while it happened."
+
+## Visual regression (`presentation:visual`) — opt-in, CI-only, pinned container
+
+The floor levels above auto-apply to every route and assert *structure* (renders, no overflow, perceivable). `presentation:visual` is the **opt-in** level that pins *appearance*: it snapshots the rendered page and fails on drift from a committed baseline — catching the restyle / wrong-content / looks-broken-but-doesn't-throw class the structural levels miss. ensure-coverage owns the contract and the determinism/CI doctrine ([`references/presentation/runner-contract.md`](../../ensure-coverage/references/presentation/runner-contract.md) → "the opt-in `presentation:visual` level"); this file is the runner's operational how-to and does **not** restate those rules.
+
+**It is a per-opted-in-surface spec, not part of the whole-manifest sweep.** The sweep (`presentation-sweep.mjs`) opens *every* route for the floor levels; visual runs only for the handful of surfaces that raised `presentation:visual` in their `*.coverage.yml` (`requiredLevels: [presentation:visual]`, with a gated `visual.mask` list). Each gets its own `@visual`-tagged Playwright spec (the `visual-gate` CI job runs `playwright test --grep @visual`), because `toHaveScreenshot()` must execute inside a Playwright test, not a node script. Do **not** hand-roll a differ; baselines, the 3-up diff, masking, and `maxDiffPixelRatio` are native:
+
+```ts
+// @covers /dashboard
+// @level presentation:visual
+import { test, expect } from '@playwright/test'
+
+test('/dashboard matches visual baseline', async ({ page }) => {
+  await page.goto('/dashboard')
+  await page.getByRole('heading', { name: /dashboard/i }).waitFor()  // gate on a stable condition, never a sleep
+  await expect(page).toHaveScreenshot('dashboard-1280.png', {
+    mask: [page.getByTestId('last-updated'), page.locator('.avatar')], // gated dynamic regions
+    maxDiffPixelRatio: 0.001,
+    animations: 'disabled',
+  })
+})
+```
+
+**Two operational facts (the *why* is in the contracts):**
+
+1. It runs **CI-only, in a pinned Playwright container** for both baseline generation and the gate. The two CI jobs (`visual-gate` blocking, `visual-baseline-regen` on-demand) are templated in `assets/ci-gates.{github.yml,cloudbuild.yaml}`; the determinism rules (animations/clock/seed/mask/threshold) and container rationale live in the runner contract + [`ci-contract.md`](../../ensure-coverage/references/enforcement/ci-contract.md) → "Visual regression jobs". The in-loop hooks never run visual.
+2. After regen, **`scripts/post-visual-evidence.mjs`** upserts a marker-tagged comment to both the source issue and the PR (durable committed-baseline link at the SHA + ephemeral diff-artifact URL) and **returns** the same two URLs as a value — on stdout behind `visual-evidence:`, and to `--evidence-out <file>`. It does **not** write the `resolve-issues` run manifest: the orchestrator records the returned value on the unit, because it is the manifest's only writer (ADR 0001 decision 5 (`docs/adr/0001-interference-is-the-scheduling-primitive.md`)).
+
+## Design fidelity (`presentation:fidelity`) — opt-in, one spec per cited design source
+
+`presentation:visual` above pins a page against a baseline captured **from itself**, so it detects *drift* and can never detect *being wrong from the start* — a baseline shot of a page that never matched its design is green forever. `presentation:fidelity` is the opt-in level for a surface built from a cited design source (prototype, mockup, layout-fixing doc): it pins the load-bearing properties read off **the source** and fails when the built page disagrees. ensure-coverage owns the doctrine, the manifest format and the catalog ([`references/presentation/axis.md`](../../ensure-coverage/references/presentation/axis.md) → `presentation:fidelity`); this section is only the runner's how-to.
+
+**Why a spec and not a node script**: reading `max-width` or a responsive `font-size` step requires a laid-out page at a real viewport, which is a browser. The measuring code is *generated* rather than hand-written — `design-parity.mjs probe` emits it from the manifest, so the spec never drifts from the properties the manifest pins:
+
+```ts
+// @covers merchant-dashboard-charge-form
+// @level presentation:fidelity
+import { test, expect } from '@playwright/test'
+import { execFileSync } from 'node:child_process'
+
+const MANIFEST = 'docs/design/charge-form.parity.yml'
+const parity = (...args: string[]) =>
+  execFileSync('node', [`${process.env.SKILL_DIR}/scripts/design-parity.mjs`, ...args], { encoding: 'utf8' })
+
+test('the charge form matches the prototype it was derived from', async ({ page }) => {
+  const runs = []
+  for (const viewport of [375, 1280]) {
+    await page.setViewportSize({ width: viewport, height: 900 })
+    await page.goto('/dashboard')
+    await page.getByRole('heading', { name: /new payment/i }).waitFor()   // a stable condition, never a sleep
+    runs.push((await page.evaluate(parity('probe', MANIFEST, '--viewport', String(viewport)))).runs[0])
+  }
+  fs.writeFileSync('parity-observed.json', JSON.stringify({ runs }))
+  // The gate is the script's verdict, not a re-implementation of it here: it also
+  // decides manifest completeness and citation resolution, which a spec cannot see.
+  expect(() => parity('validate', MANIFEST, '--observed', 'parity-observed.json')).not.toThrow()
+})
+```
+
+**Three operational facts:**
+
+1. **Both floor viewports in one spec.** A responsive step-up (`24px → 30px`) is the classic silent loss in a hand-port, so the manifest pins scale rows per viewport and the spec must measure at each. Measuring only the default width passes a page that lost the step.
+2. **It runs in the ordinary browser lane**, not the pinned visual container. There are no pixels to compare — computed style is stable across OSes in a way anti-aliasing is not — so it needs no baseline image, no masking, and no `visual-baseline-regen` counterpart.
+3. **Pass `--diff <merge-base>` in CI.** That is what catches an `expected` edited to match the page instead of the page fixed to match the design — the fidelity analogue of a silent `--update-snapshots`, and the failure mode this level is most likely to die of.

package/skills/engineering/e2e-test/references/reviewing.md

@@ -0,0 +1,39 @@
+# Reviewing PRs (E2E coverage)
+
+Checklist:
+
+- [ ] Route discovery and reachability analysis were run before coverage audit; output is included or summarized
+- [ ] Route manifest regenerated (projection) if routes added/removed; no drift vs the surface inventory
+- [ ] New routes have at least Tier 1 test
+- [ ] Interactive routes have Tier 2 (success + error cases)
+- [ ] Browser-route changes ran the presentation sweep (separate gate); no `fail` results. **A `blocked` result depends on who is running this list.** Producing the work (fixtures yours to supply), `blocked` is a genuine gap — a route the harness cannot render is a route nobody proved renders, so it blocks. *Reviewing* a diff from a read-only sandbox, `blocked` usually means your environment lacks a `DATABASE_URL`, an auth session, or a resolvable param — an inability to verify, which is never evidence of absence ([review-pr](../../review-pr/SKILL.md) § Verdicts and the blocking bar). Report the route and the error and take `BLOCKED` for that route's obligation; do not convert it into a finding against the diff
+- [ ] No `waitForTimeout()` -- use explicit waits
+- [ ] No CSS class assertions -- test user-visible behavior
+- [ ] **No test skipped or disabled.** The PR adds no `test.skip` / `xit` / `describe.skip`, no conditional skip, no disguised `if (!x) return` guard. A missing precondition is **seeded**; an un-sandboxable/flaky case goes to the **quarantine lane** (non-blocking, graded `Unverified`), never skipped. A `TODO`/issue link does **not** authorize a skip (see [authoring/test-skipping.md](authoring/test-skipping.md))
+- [ ] No assertion that passes on a **404 / not-found / empty / error** page where the test name promises a real render — that goes green when the feature is broken or unseeded; a route returning HTTP 200 with not-found content is itself a status-code bug to file
+- [ ] **Each authorized lane asserts a positive marker unique to its subject having rendered.** The row above rejects a *negative* (an assertion that survives a degraded page) and is the half a reviewer can see; this one requires a *positive* — a row, a heading, a seeded value the real producer emits — and is the half that fails **silently**. "Didn't crash" and "didn't 404" are not "rendered". A lane whose tenant/auth is misconfigured fails closed and dies on a timeout with **no assertion in the diff to catch**: see [authoring/auth-flows.md](authoring/auth-flows.md) § A session fixture asserts its own preconditions
+- [ ] Auth in shared fixtures, not duplicated
+- [ ] Bugfix PRs have regression test covering the exact failure
+- [ ] Tier 3 journeys use real APIs (no mocking internal endpoints)
+- [ ] Do-not-ship golden journeys (sign in → core action → pay) are tagged `@smoke` so the curated smoke gate selects them; a new critical flow with no `@smoke` tag / smoke-manifest entry is a gap
+- [ ] Specs tagged `@covers`/`@level` so the ledger resolves them
+
+**Red flags (block PR):** route discovery/reachability not run before audit, route treated as valid only because a file exists, tests assert implementation details, fixed sleeps, new route without manifest entry, copy-pasted auth setup, happy-path-only Tier 2, presentation sweep absent or warn-only for a browser-route change (a sweep you could not *run* is a `BLOCKED`, not a red flag — the distinction is whether the sweep is missing or your environment is), **any test skipped/disabled/guarded** instead of seeded-or-quarantined, an assertion that passes on a 404/not-found/empty page where a real render is expected, **an authorized lane whose only observed failure mode is a timeout** (it is failing closed before it renders, not asserting).
+
+**Lead with the verdict, then follow-ups.** Put the verdict at the **top** of the review (and any coverage `notes.md`) — *is this surface covered / ship-ready, or do gaps remain?* — then what the tests prove and deliberately don't, and concrete follow-up action items (owner/level where known) for anything uncovered.
+
+**Comment template:**
+```
+### E2E Coverage
+
+**Missing:**
+- Route `/new-page` added but not in the surface inventory / route manifest
+- No Tier 2 test for the date filter (need: valid range, invalid range, empty)
+- `/tasks` has no presentation-sweep result (render unproven)
+
+**Issues:**
+- `line 42`: Uses `waitForTimeout(3000)` -- replace with `waitForResponse`
+
+**Good:**
+- Journey test covers the full flow
+```

package/skills/engineering/e2e-test/references/route-discovery.md

@@ -0,0 +1,50 @@
+# Route Discovery And Reachability Protocol
+
+> The framework-specific, executable form of route/surface discovery. `ensure-coverage`'s `references/breadth/surface-discovery.md` holds the same protocol as portable doctrine; this file adds the per-framework enumeration sources and is deliberately self-contained so e2e-test works standalone.
+
+Never audit E2E coverage from memory, sampling, or manual file browsing. First produce a deterministic route/endpoint inventory, then verify reachability. Listing route files is not discovery — verify whether each route can actually be reached through layouts, middleware, redirects, guards, rewrites, and route groups. If discovery or reachability can't produce a credible result, mark the audit `BLOCKED` and state what prevented it.
+
+Discovery order:
+
+1. Run framework-specific discovery scripts when available.
+2. Prefer runtime introspection for backends when the app can start (OpenAPI JSON, framework route registries).
+3. Use static discovery as a fallback and cross-check, not the only source when runtime introspection is available.
+4. For page routes, verify reachability through layout chains, middleware, guards, redirects, rewrites, route groups, and feature flags.
+5. Compare discovered routes/endpoints against the manifest, product journeys, navigation links, design docs, and test files.
+6. Compare changed files against affected routes/endpoints; call out newly added or changed entries.
+
+Frontend discovery sources:
+
+- Next.js App Router: enumerate `app/**/page.*` and `app/**/route.*`; include route groups, dynamic segments, parallel/intercepting routes, and exported HTTP methods for `route.*`.
+- Next.js Pages Router: `pages/**/*` excluding API files when auditing UI routes; include `pages/api/**/*` when auditing endpoints.
+- React Router: route config files, `createBrowserRouter`, `createRoutesFromElements`, `<Route path=...>`.
+- For each Next.js page route, walk the layout chain from root → route group → segment layout; inspect `layout.*`, `middleware.*`, redirects, `notFound`, auth/session checks, role/tenant guards, feature flags, rewrites, and navigation entry points.
+- Multiple apps (e.g. admin and portal) are discovered separately, with separate manifests.
+
+Backend discovery sources:
+
+- FastAPI: prefer runtime `app.routes` or `/openapi.json`; fallback to `@router.get/post/put/patch/delete` decorator scan.
+- Express/Nest-style: scan router registration, controller decorators, mounted prefixes, method decorators.
+- Include method + path and auth/permission metadata where available; distinguish health/internal from business endpoints without silently dropping them.
+
+Reachability classification:
+
+- `Reachable`: request/user can reach the route under documented conditions.
+- `Redirected`: route exists but redirects before page behavior is available.
+- `Guarded`: requires auth, role, tenant, feature flag, or other condition; state it.
+- `Blocked`: exists but cannot be reached in current product flow or environment.
+- `Unknown`: evidence insufficient; do not classify as covered without more inspection.
+
+Do not classify a route as covered, missing, or a valid journey solely because a `page.*`/`route.*` file exists — a route file is only a declared route until its guard chain and journey validity are checked.
+
+Required audit output:
+
+- Discovery method and command/source used.
+- Reachability classification and guard/layout/middleware evidence for relevant routes.
+- Count of discovered routes/endpoints; count of manifest entries.
+- Routes/endpoints missing from manifest; manifest entries not found in code.
+- Uncovered surfaces per the ledger (`coverage-ledger.mjs` status; not a manifest `specs` count).
+- Changed routes/endpoints and their coverage status.
+- Routes that are unreachable, misplaced, stale, missing from the manifest, absent from code, or contradicting PRD/spec claims.
+
+Discovery scripts: `scripts/detect-routes-nextjs.mjs`, `scripts/detect-routes-fastapi.py`.

package/skills/engineering/e2e-test/references/route-manifest.md

@@ -0,0 +1,44 @@
+# Route Manifest
+
+A **generated projection** of ensure-coverage's surface inventory — *not* hand-maintained, and *not* the coverage source of truth (coverage is computed by the ledger from `@covers` annotations). Its job is to be the route list the presentation sweep iterates, plus the E2E `tier`. Generate it so its route set can't drift from the inventory:
+
+```bash
+node <skill-dir>/scripts/project-route-manifest.mjs \
+  --inventory docs/tests/_generated/surface-inventory.json \
+  --overlay e2e/route-manifest.overlay.json --out e2e/route-manifest.json
+```
+
+`route-manifest.json` is `{ version, generated: true, routes: [{ path, tier }] }`. E2E-only curation lives in a small hand-authored **overlay** (`route-manifest.overlay.json`) — the manifest's analog of ensure-coverage's `*.coverage.yml` deviations:
+
+```json
+{
+  "routes": {
+    "/dashboard": { "tier": 3 },
+    "/legacy-print": { "ignore": true }
+  },
+  "spatialIgnore": [".sticky-header"]
+}
+```
+
+`tier` defaults from the inventory's `class` (read→1, detail/mutation→2); the overlay raises it (e.g. a route on a core journey → 3) or `ignore`s a route from the sweep (it still owes its ledger floor). `specs` is optional/informational only — do **not** use it as a coverage signal.
+
+The backend `endpoint-manifest.json` is the API analog — likewise a projection of the inventory (`kind === 'api'`), with `method` + `tier`. Endpoint coverage is also the ledger's job, not a `specs` count.
+
+## Single source of truth (no drift by construction)
+
+```
+detect-routes (one discovery pass)
+      │  writes
+      ▼
+surface-inventory.json   ← canonical, generated, ALL surfaces (routes/api/table/event/job)
+      │  project-route-manifest.mjs  (filter kind===route  ⨝  curated overlay)
+      ▼
+route-manifest.json      ← generated projection: the sweep's route list + tier
+```
+
+- The **inventory** is the source of truth for *obligations* (every surface's `(kind, class)` floor), spanning APIs/tables/events too; the **manifest** is a *derived view* for the E2E runner.
+- Because the manifest is **generated**, its route set cannot drift: regenerate both and `git diff --exit-code` is CI gate #1 (inventory freshness). A new route appears in the inventory (→ ledger obligation) and flows into the manifest (→ sweep) from the *same* discovery pass.
+- Curation (tier, sweep `ignore`) lives only in the small hand-authored overlay; `staleOverlayEntries` warns when the overlay references a route the inventory no longer has.
+- Inventory drives *what is owed*; manifest tracks *what the sweep visits*; the ledger tracks *what is proven* (via `@covers`). Three roles, one generated spine.
+
+Scripts: `scripts/project-route-manifest.mjs` (projection), `scripts/validate-manifest.mjs` (entries valid).