@1aboveio/skills 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,290 @@
+# Playwright in Containers
+
+> Read when: running Playwright on a self-hosted Docker/Podman runner, choosing the container image, or a run fails on a missing browser shared library.
+
+**Running Playwright in the official pinned container is the preferred way to run
+browser automation** — 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 Cloud Build template defaults to option 1. The generated golden-path workflow
+uses option 2 (a GitHub-hosted runner with `playwright install --with-deps`).
+`ci-audit.mjs` checks only that the golden-path verdict is present and blocking; container choice remains operational guidance.
+**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.
+
+The same rule covers a browser that the **app** launches, not the test runner. For
+example, a Backend that renders PDFs with Puppeteer while it runs on the runner for
+an emulator or device journey. That fails with `Browser was not found at the
+configured executablePath`. Keep that process on the host and give it a wrapper
+that runs this image's browser: `github-actions` → `references/runners.md`, "A host
+process that needs a browser binary".
+
+## 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/presentation-sweep.md

@@ -0,0 +1,104 @@
+# Presentation Sweep (the third coverage axis)
+
+> Read when: running or wiring the presentation sweep, writing a spec that uses the instruments, or reading the results file the ledger consumes.
+
+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 and owns the result shape below).
+
+**It is separate evidence from the functional/journey suite, even though both use Playwright.** A passing functional E2E run is not presentation proof.
+
+## 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 |
+
+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 as review evidence, 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 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."
+
+## Design fidelity (`presentation:fidelity`)
+
+Opt-in, for a surface built from a cited design source. ensure-coverage owns the doctrine and the parity manifest (`references/presentation/axis.md` → `presentation:fidelity`, `scripts/design-parity.mjs`). The runner is an ordinary Playwright spec that measures at both floor viewports with the probe `design-parity.mjs probe` emits, then calls `design-parity.mjs validate --observed … --diff <merge-base>`; computed style is stable across OSes, so it needs no pinned container and no baseline image.
+
+## What the sweep must do, and the result shape the ledger consumes
+
+`coverage-ledger.mjs` is a static analyzer: it proves a qualifying real-browser, non-intercepting, attested test was *authored*. It cannot observe a `pageerror`, an overflow, or a layout shift. The coverage verdict therefore needs two evidence sources: **accounting** (the ledger) and **rendering** (this sweep). Neither is a CI gate; curated golden-path smoke is the sole CI gate.
+
+Given the generated route manifest (the `kind: "route"` surfaces from the surface inventory), the sweep must:
+
+1. **Open every manifest route in a real browser** at the viewport floor `[375, 1280]`. Never sample or top-N silently; if coverage is bounded, log what was dropped.
+2. **Drive the real render path.** `page.route('**/api/**')`, `route.fulfill`, MSW for owned paths, or first-party fixtures disqualify the run for that route. Externals may be faked.
+3. **Assert the floor invariants, spine first**, one result per `(route, level, viewport)`: `render-health`, `spatial`, `perceivability`, `reachability`, `temporal`. The sweep proves the load path; write paths are destructive and need authored journeys with the render-health watcher kept attached.
+4. **Abstain, never silently pass.** Ambiguous state (contrast over a gradient, a route whose seed failed) is `unverified` (a warning unless the user made it blocking), never `pass`. An environment that cannot render at all (no `DATABASE_URL`, no auth) is `blocked`, never `pass`.
+
+Repo-supplied fixtures: a deterministic **auth** bypass or seeded session (a login wall is not a render pass); **seed** data so `read` / `detail` routes render real content; **param substitution** for dynamic segments (an unresolvable param is `blocked`, not skipped); and a gated **allowlist** for intentional overlap (`category` + `reason`, surfaced in a census; an overlap occluding a reachable control can never be allowlisted).
+
+Emit JSON to `docs/tests/_generated/presentation-results.json`:
+
+```json
+{
+  "viewportFloor": [375, 1280],
+  "results": [
+    { "route": "/tasks", "level": "presentation:render-health", "status": "fail",
+      "evidence": "pageerror: Cannot read properties of undefined (reading 'id') at TasksToolbar" },
+    { "route": "/tasks", "level": "presentation:spatial", "status": "blocked",
+      "evidence": "render-health failed; layout not assessable" },
+    { "route": "/dashboard", "level": "presentation:render-health", "status": "pass" }
+  ]
+}
+```
+
+- `status` is `pass | fail | unverified | blocked`. `fail` and `blocked` exit the sweep non-zero. `unverified` is a ledger warning by default.
+- `evidence` names the concrete observation: the `pageerror` text, the offending selector and overflow px, the unreachable param.
+- The ledger reconciles these against each route's required levels: a `fail` / `blocked` / missing result on a required level is a finding; a `pass` still needs a clean authored test, read and marked `verified: true`, to reach `Covered`.

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

@@ -0,0 +1,41 @@
+# Reviewing PRs (E2E coverage)
+
+> Read when: reviewing a PR for E2E coverage. The checklist, the red flags, and the comment template.
+
+Checklist:
+
+- [ ] Route discovery and reachability analysis were run before coverage audit
+- [ ] Route manifest regenerated (projection) if routes added/removed; no drift vs the surface inventory
+- [ ] New routes have render-health proof (Tier 1, or a Tier 2/3 test calling `assertRenderHealthy`); no duplicate Tier 1 for a route already proven
+- [ ] Interactive routes have Tier 2 (success + error cases)
+- [ ] Browser-route changes ran the presentation sweep (a separate run); 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. 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 unless CI still runs the test where the condition is false (a platform or optional-dependency 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 (policy: `ensure-coverage/references/process/test-strategy.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 `@golden-path` so the golden-path check selects them; a new critical flow with no `@golden-path` tag / `golden-paths.json` 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, no presentation sweep run 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-manifest.md

@@ -0,0 +1,51 @@
+# Route Discovery and the Route Manifest
+
+> Read when: a route was added or removed, the manifest is stale, or an audit needs the route inventory before it can grade anything.
+
+## Discover first, never audit from memory
+
+Never audit E2E coverage from memory, sampling, or browsing files. Produce a deterministic route inventory, then classify reachability. A `page.*` file is a declared route, not a reachable one, until its guard chain is checked.
+
+Discovery order: run the framework's discovery script when there is one; prefer runtime introspection for backends when the app can start (OpenAPI JSON, route registries); use static discovery as the fallback and cross-check; then walk each page route's layout chain, middleware, redirects, guards, rewrites, route groups and feature flags.
+
+- Next.js App Router: `app/**/page.*` and `app/**/route.*`, including route groups, dynamic segments, parallel and intercepting routes, and the HTTP methods a `route.*` exports (`scripts/detect-routes-nextjs.mjs`).
+- Next.js Pages Router: `pages/**/*`, with `pages/api/**` when auditing endpoints.
+- React Router: route config files, `createBrowserRouter`, `createRoutesFromElements`, `<Route path=…>`.
+- Backends: runtime `app.routes` or `/openapi.json` first; decorator or router-registration scan as the fallback. Keep method, path and auth metadata; do not drop health or internal endpoints silently.
+- Multiple apps (admin, portal) are discovered separately with separate manifests.
+
+Reachability: `Reachable`, `Redirected`, `Guarded` (say by what), `Blocked`, `Unknown`. Never grade `Unknown` as covered. The portable doctrine is ensure-coverage's `references/breadth/surface-discovery.md`; this is its executable form.
+
+An audit reports: the discovery method, reachability with guard evidence, discovered count versus manifest count, routes missing from the manifest and manifest entries absent from code, changed routes and their coverage status, and uncovered surfaces per the ledger (never a manifest `specs` count).
+
+## The manifest is a generated projection
+
+`e2e/route-manifest.json` is derived from ensure-coverage's surface inventory, never hand-maintained, and never the coverage source of truth (the ledger computes that from `@covers`). Its job is to be the route list the sweep iterates, with an E2E `tier`.
+
+```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
+```
+
+Shape: `{ version, generated: true, routes: [{ path, tier }] }`. Curation lives in the small hand-authored overlay:
+
+```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 or `ignore`s a route from the sweep (it still owes its ledger floor). `specs` is informational only.
+
+```
+detect-routes  →  surface-inventory.json  →  project-route-manifest.mjs (+ overlay)  →  route-manifest.json
+```
+
+Because the manifest is generated, its route set cannot drift: regenerate both during the audit and compare the result with the committed files. A new route appears in the inventory (a ledger obligation) and flows into the manifest (a sweep visit) from the same discovery pass. `staleOverlayEntries` warns when the overlay names a route the inventory no longer has. The backend `endpoint-manifest.json` is the API analog, projected from `kind === 'api'` with `method` and `tier`.
+
+Scripts: `scripts/project-route-manifest.mjs`, `scripts/validate-manifest.mjs`.

package/skills/engineering/e2e-test/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }