@1aboveio/skills 0.10.0

package/skills/engineering/e2e-test/references/authoring/playwright-patterns.md

@@ -0,0 +1,219 @@
+# Playwright Patterns
+
+## Locators
+
+```typescript
+// Prefer semantic locators
+page.getByRole('button', { name: 'Submit' })
+page.getByLabel('Email')
+page.getByText(/success/i)
+
+// Avoid CSS selectors
+page.locator('.btn-primary.text-red-500')  // breaks on style changes
+```
+
+## Waiting
+
+```typescript
+// Wait for real state
+await page.getByRole('button', { name: 'Save' }).click();
+await expect(page.getByText('Saved')).toBeVisible();
+
+// No fixed sleeps
+await page.waitForTimeout(3000);  // flaky
+```
+
+## Assertions
+
+```typescript
+// Assert on behavior
+await expect(page.getByText(/invalid.*range/i)).toBeVisible();
+
+// Don't assert CSS classes
+await expect(page.locator('.text-red-500')).toBeVisible();  // implementation detail
+```
+
+## No Skips — Seed, Route, or Quarantine
+
+The committed suite contains only tests that run. **Never** disable a test to get past a missing precondition or a failure — seed the state instead (full policy + per-case solutions map: [test-skipping.md](test-skipping.md)).
+
+```typescript
+// ✗ All of these are banned — they remove the signal and read as "handled":
+test.skip();                       // naked
+test.skip(true, 'issue #123');     // annotated, still a skip
+if (!user) test.skip();            // conditional skip
+if (!order) return;                // disguised skip — WORST: reports PASSED, asserts nothing
+
+// ✓ Seed the precondition, then assert against the real path.
+const user = await factory.user({ role: 'admin' });
+const order = await factory.order({ userId: user.id, status: 'pending' });
+await login(page, user);
+await page.goto(`/orders/${order.id}`);
+// …assertions on the real, seeded path
+
+// ✓ Only-valid-on-one-target → ROUTE via project config, don't skip in the body:
+//   playwright.config.ts → projects: [{ name: 'webkit', use: devices['Desktop Safari'] }]
+//   the test simply isn't *selected* off-target; it is never disabled.
+
+// ✓ Un-sandboxable external / genuine flake → QUARANTINE lane (non-blocking job that
+//   still runs + reports; surface graded `Unverified`), never test.skip(). See ci-integration.md.
+```
+
+## Tier Examples
+
+### Tier 1 — Render-health
+
+One test per route: navigate, verify no crash.
+
+```typescript
+test.describe('Render-health: all routes load', () => {
+  for (const route of ['/', '/login', '/dashboard', '/settings']) {
+    test(`${route} loads`, async ({ page }) => {
+      const errors: string[] = [];
+      page.on('pageerror', (err) => errors.push(err.message));
+      await page.goto(route);
+      await expect(page.locator('body')).toBeVisible();
+      expect(errors).toEqual([]);
+    });
+  }
+});
+```
+
+### Tier 2 — Functional
+
+Cover success + failure + edge cases per feature.
+
+```typescript
+test.describe('Date Range Filter', () => {
+  test('applies range and updates data', async ({ page }) => {
+    await page.goto('/dashboard');
+    await page.getByLabel('From').fill('2026-01-01');
+    await page.getByRole('button', { name: 'Apply' }).click();
+    await expect(page.getByTestId('data-table')).toBeVisible();
+  });
+
+  test('shows error for invalid range', async ({ page }) => {
+    await page.goto('/dashboard');
+    await page.getByLabel('From').fill('2026-12-31');
+    await page.getByLabel('To').fill('2026-01-01');
+    await page.getByRole('button', { name: 'Apply' }).click();
+    await expect(page.getByText(/invalid.*range/i)).toBeVisible();
+  });
+});
+```
+
+### Tier 3 — Journey (golden paths)
+
+Multi-step flow, real API calls. Mock only external third-party APIs. These are the golden paths; the do-not-ship subset is tagged `@smoke` for the smoke gate.
+
+```typescript
+test('login then view dashboard then filter', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Token').fill(process.env.E2E_TOKEN!);
+  await page.getByRole('button', { name: 'Login' }).click();
+  await expect(page.getByRole('heading', { name: /dashboard/i })).toBeVisible();
+  await page.getByRole('button', { name: '7d' }).click();
+  const resp = await page.waitForResponse('**/api/data*');
+  expect(resp.status()).toBe(200);
+});
+```
+
+## Route Mocking (Tier 2 only)
+
+```typescript
+await page.route('**/api/data*', (route) => {
+  void route.fulfill({ status: 500, contentType: 'application/json',
+    body: JSON.stringify({ error: 'SERVER_ERROR', message: 'boom' }) });
+});
+await page.goto('/dashboard');
+await expect(page.getByText(/failed to fetch/i)).toBeVisible();
+```
+
+## Presentation checks (ensure-coverage's Presentation axis)
+
+A functional journey proves the page *works*; it does not prove a human can *see and use* it. The Presentation axis adds per-route render checks against the real page. The spine ships the **Spatial / overflow** invariant via `scripts/presentation-checks.mjs`. Tag the spec so the Coverage Ledger resolves it to the route's `presentation:spatial` obligation.
+
+```typescript
+// @covers /dashboard
+// @level browser-journey
+// @level presentation:spatial
+import { test, expect } from '@playwright/test';
+import { assertNoHorizontalOverflow } from '../scripts/presentation-checks.mjs';
+
+test('dashboard renders and has no horizontal overflow', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.getByRole('heading', { name: /dashboard/i })).toBeVisible(); // journey
+  await assertNoHorizontalOverflow(page); // presentation:spatial, at 375 + 1280
+});
+```
+
+- It drives a **real browser** at both floor viewports (375, 1280). A DOM-only / JSDOM equivalent is graded `Over-mocked` by the ledger — it cannot see layout.
+- Suppress *intentional* overflow (a scrolling carousel) with `assertNoHorizontalOverflow(page, { ignore: ['carousel'] })` — curate sparingly; the gated-allowlist seam later slices formalize.
+- `presentation:spatial` is a **separate** obligation from `browser-journey` — a journey alone does not satisfy it.
+- It also covers **overlap** via `assertNoOverlap(page)` (bounding-box intersection). Intentional z-stacks use a *gated* allowlist — `assertNoOverlap(page, { allowlist: [{ match: 'carousel', category: 'decorative', reason: 'z-stacked slides' }] })` — which returns a census of suppressions; an entry that would hide an overlap occluding an interactive control is rejected.
+
+`presentation:perceivability` (contrast / invisible controls) uses `scripts/presentation-perceivability.mjs`:
+
+```typescript
+// @covers /dashboard
+// @level presentation:perceivability
+import { assertContrast, assertHiddenFromWrongRole } from '../scripts/presentation-perceivability.mjs';
+
+test('dashboard is perceivable', async ({ page }) => {
+  await page.goto('/dashboard');
+  await assertContrast(page); // axe color-contrast; throws on violation
+  // negative form: an admin-only control must not be visible to a non-admin
+  await assertHiddenFromWrongRole(page, page.getByRole('button', { name: 'Delete org' }));
+});
+```
+
+- On an axe **abstain** (`incomplete` — text over an image/gradient) `assertContrast` throws `AbstainError`: a **blocking Unverified**, resolved by reviewer attestation or escalation, never a silent pass.
+- Disabled controls are skipped (WCAG-exempt), not false-flagged.
+
+`presentation:reachability` (nav-orphan + affordance) uses `scripts/presentation-reachability.mjs`. This is **navigational** reachability (can a user click here from an entry point), distinct from guard-chain reachability:
+
+```typescript
+import { assertNoNavOrphans, assertTargetSizes, assertFocusVisible } from '../scripts/presentation-reachability.mjs';
+
+// once per app: every manifest route must be reachable by crawling nav from '/'
+test('no navigational orphans', async ({ page }) => {
+  await assertNoNavOrphans(page, manifestRoutes, { ignore: ['/auth/callback', '/deep/*'] });
+});
+
+// @covers /dashboard
+// @level presentation:reachability
+test('dashboard controls are actionable', async ({ page }) => {
+  await page.goto('/dashboard');
+  await assertTargetSizes(page);                          // >=44px targets
+  await assertFocusVisible(page, page.getByRole('button', { name: 'Save' })); // focus ring present
+});
+```
+
+`presentation:temporal` (layout shift) uses `scripts/presentation-temporal.mjs`. First-party shift is a hermetic gate; third-party payfields runs in a non-blocking lane:
+
+```typescript
+import { assertNoFirstPartyShift, assertNoThirdPartyShift, assertNoDynamicViewportShift } from '../scripts/presentation-temporal.mjs';
+
+// @covers /dashboard
+// @level presentation:temporal
+test('dashboard layout holds still', async ({ page }) => {
+  await page.goto('/dashboard');
+  await assertNoFirstPartyShift(page, {                   // hermetic: no network
+    trigger: () => page.getByRole('button', { name: 'Load more' }).click(),
+    settle: page.getByTestId('row-50'),                   // stable condition, NOT a sleep
+  });
+  await assertNoDynamicViewportShift(page);              // 100vh/dvh on mobile
+});
+
+// SEPARATE non-blocking lane (continue-on-error) — provider SANDBOX iframe:
+test('@checkout payfields do not shift layout', async ({ page }) => {
+  await page.goto('/checkout');
+  await assertNoThirdPartyShift(page, {
+    container: 'stripe',
+    ready: page.frameLocator('iframe[name^="__privateStripeFrame"]').getByLabel('Card number'),
+  });
+});
+```
+
+- Top-page CLS can't see inside the cross-origin payment iframe — that's why the third-party check is before/after geometry gated on a provider-ready locator, not a `PerformanceObserver`.
+- A third-party-lane failure is annotated and the surface stays `Unverified` until attested; it never hard-blocks the PR.

package/skills/engineering/e2e-test/references/authoring/test-skipping.md

@@ -0,0 +1,44 @@
+# No-Skip Policy
+
+The committed suite contains **only tests that run and assert**. A test is never disabled to get past a missing precondition or a failure — not with `test.skip()`, not `describe.skip` / `xit` / `it.skip`, not a conditional/dynamic skip, and not a *disguised* skip (`if (!data) return` or any guard that turns the body into a no-op). **The agent has no discretion to skip** — every situation has a non-skip answer (the map below).
+
+Disabling a test removes the signal while leaving a green-looking entry that reads as "handled" — the most dangerous false coverage. It doesn't even clear the gate: the ledger grades a disabled or guarded test **not-covered** and the sweep reports **blocked**, never `pass`. Disabling-to-green fails CI *and* lies to the reader.
+
+**Why no allow-list.** "Skip when it's outside your control" is the exact rationalization that shipped false coverage — an agent reclassifies *"I didn't seed the data"* as *"environment blocker."* Removing the category removes the loophole. Every honest "I have to skip" case keeps either the **signal** (run it — blocking, or quarantined non-blocking) or an honest **`Unverified`** status.
+
+## The solutions map (every case → a non-skip path)
+
+| Situation | Don't skip — instead |
+|---|---|
+| Missing data / row / tenant | **Seed it** — factory / seed script / SQL / API call that creates exactly what the assertion needs. |
+| No authenticated session | **Seed auth** — the shared auth fixture or `E2E_AUTH_BYPASS`. |
+| Schema not migrated | **Migrate** before the suite. |
+| Feature flag off / wrong config | **Set it** in the test's setup or env. |
+| Dynamic-route id needed (`/orders/[id]`) | **Seed the entity, use its id** (the sweep's `paramResolver` pattern). |
+| A specific entity *state* (e.g. a `payment_live` merchant) | **Seed that state** — it's a column/enum value; create a row that has it. |
+| Depends on a third-party service | **Sandbox at the boundary** — provider sandbox + test keys; fake only the external adapter (real internals, faked externals). |
+| Un-sandboxable external (paid API, prod-only secret) **or** genuinely flaky | **Quarantine lane**, never skip — a separate **non-blocking** job that still *runs and reports* the test, with the surface graded blocking-but-attestable `Unverified` (not `verified: true`) and a dated exit. Run + report + don't-block ≠ stop running. (See [ci-integration.md](../ci-integration.md) → Quarantine lane.) |
+| Only valid on a specific browser / OS / runtime | **Route it** — Playwright project / matrix / tag, so it runs where applicable and simply isn't *selected* elsewhere. Selection ≠ skip; the test is not disabled. |
+| Behavior not built yet | **Land the test with its behavior** (TDD red→green in the same PR), or don't merge the test yet. Never merge a disabled placeholder for unbuilt code. |
+| Test is obsolete / wrong / duplicate | **Delete it** (say why in the PR). A skip of a dead test is clutter that hides intent. |
+| Flaky because the *test* is racy | **Fix the race** (explicit waits; never `waitForTimeout`) — flakiness is a defect, not a skip reason. Quarantine while fixing; don't disable. |
+| Cannot execute in **any** environment we control | Then it isn't an automated test — **convert it to a documented manual-check** in the test plan / notes, tracked. Don't leave a `skip()` rotting in the suite. |
+
+The throughline: you either want the signal (run it — blocking or quarantined) or the test is invalid (delete it). **"Stop running but keep the green test" is never the right tool.**
+
+## Annotation is not authorization
+
+A `TODO` / issue link above a disabled test documents a gap; it does **not** make the skip acceptable. `TODO(#nnn): re-enable when we seed a payment_live merchant via /api/e2e/setup` is a *confession* that the state was seedable and the work was deferred — do the seed. There is no "skip + comment" compliant state.
+
+## Inherited (pre-existing) skips
+
+A skip already present at the review base is pre-existing — per `review-pr` diff-discipline it's a note, not a PR blocker. But **a PR may not add a skip**, and any PR touching the area of an inherited skip should convert it via the map above rather than leave or extend it.
+
+## Enforcement
+
+- The coverage gate is the real teeth: a disabled or guarded test grades **not-covered** (ledger) / **blocked** (sweep), so disabling-to-green can't clear CI regardless of how it's spelled — including `if (!x) return`.
+- **`lint-tests.mjs`** (the static gate engine) is the fast tripwire on the explicit forms: `node <ensure-coverage>/scripts/lint-tests.mjs --diff "$BASE"` fails the build on a `test.skip` / `xit` / `describe.skip` / `.only` / `xfail` **added in the diff** (the `no-skip` rule; inherited skips left alone — diff-discipline). It also carries `no-fixed-timeout`. Run a subset with `--rules no-skip`. Wired as the `lint-tests` job in `assets/ci-gates.*`. The lint catches the greppable forms; the ledger catches the disguised ones.
+
+The quarantine lane uses the **`@quarantine`** tag with a **dated exit**: `@quarantine(until=YYYY-MM-DD, issue=#nnn)`. The blocking `e2e` job runs `--grep-invert "@quarantine"`, the non-blocking lane runs `--grep "@quarantine"`. The exit **auto-resurfaces**: `check-quarantine-expiry.mjs` (run in the blocking lane) fails CI once `until=` is in the past, so a "temporary" quarantine can't rot green — by the date it must be fixed or the date extended with a reason (see [ci-integration.md](../ci-integration.md) → Quarantine lane).
+
+**Canonical source:** `ensure-coverage` → `references/process/test-strategy.md` owns the no-skip policy; this doc is its **browser/E2E-specific application** (the `@quarantine` tag, the sweep/journey grading), not an independent copy. On any disagreement, `test-strategy.md` wins — fix this doc, don't fork it. Enforcement is already single-sourced (`lint-tests.mjs` + the ledger), so the only drift risk is the prose; edit the policy there first.

package/skills/engineering/e2e-test/references/ci-integration.md

@@ -0,0 +1,121 @@
+# CI Integration
+
+Two things live here, with different force. The **coverage gates** ("start here" below) are the **required** CI contract, owned by ensure-coverage's `ci-contract.md` — blocking jobs. The **post-deploy dispatch pattern** further down (firing E2E against a deployed URL, PR-comment reporting) is **optional** — the skill works standalone without it. "Optional" does not apply to the gates.
+
+## The coverage gates (start here)
+
+The required CI shape is defined by **ensure-coverage's `references/enforcement/ci-contract.md`**: each a *separate* blocking job, none standing in for another. The **per-PR floor** (the minimal gate every PR pays), numbered by ensure-coverage's **canonical gate IDs** (the gaps are deliberate — gates 4, 6, 7 are not per-PR-floor, covered just below) —
+
+1. **Inventory freshness** — regenerate inventory + route manifest, fail on drift.
+2. **Accounting** — `coverage-ledger.mjs validate` (static; proves a qualifying test was *authored*).
+3. **Presentation render sweep** — `presentation-sweep.mjs` opens every manifest route in a real browser (needs browser + seeded DB + auth bypass; proves the page *renders*). **NOT the functional suite** — a green functional run is not the presentation gate.
+5. **No over-mock** — `lint-tests.mjs --rules mock-internal-seam` (diff + whole-tree; zero-tolerance).
+8. **Curated E2E smoke** — drive the selected do-not-ship golden journeys against the real app, write `smoke-results.json`, then run `smoke.mjs verdict`; ALIVE/DEAD. The per-PR golden-path liveness floor. **NOT the functional suite below** — the curated handful against the real app with no first-party interception; for browser paths it runs through Playwright by tag/manifest selection (`@smoke` / smoke manifest), not by running the broad suite.
+
+The **broad functional + journey E2E suite** (gate 4 — every form, error path, edge case) is **demoted off the per-PR critical path** to the **integration lane** (the integration-branch push; the `resolve-issues` epic gate runs there), required before release but not on every PR. Gate 8 stays per-PR because it is a tiny curated subset, not a second broad regression run. Plus the Review-Contract checklist validate (gate 6) and quarantine auto-resurface (gate 7).
+
+Copy a ready template and fill the `<…>` placeholders:
+
+- **Cloud Build**: [`assets/ci-gates.cloudbuild.yaml`](../assets/ci-gates.cloudbuild.yaml)
+- **GitHub Actions**: [`assets/ci-gates.github.yml`](../assets/ci-gates.github.yml)
+
+Then verify the wiring stays correct (nobody deleted the sweep/smoke or set `continue-on-error`) with the meta-gate: `node <ensure-coverage>/scripts/ci-audit.mjs --files <your ci configs>`. The post-deploy pattern below is complementary — it does not replace gate 3.
+
+### Branch protection: require ONE check, the umbrella
+
+On GitHub Actions the gates are ~8 separate jobs; pointing branch protection at each by name is the failure mode — a renamed or added gate silently falls out of protection, and a conditionally-skipped job counts as passing. So the template ends with an **`all-gates` umbrella job** that `needs:` every blocking gate and fails on any `failure`/`cancelled` — **branch protection requires only `all-gates`**. (`skipped` is allowed by design: gate 4 is PR-skipped; the umbrella still reds on anything that ran and failed. The quarantine lane is deliberately not in `needs`.) On Cloud Build no umbrella is needed — the build's single status is the one check. `ci-audit.mjs` checks the umbrella and the PR-lane time budget as required conventions, and the pinned-Playwright-container as preferred.
+
+### The PR-lane time budget (≤5 min) and parallel golden paths
+
+Every PR-lane job carries `timeout-minutes: 5` (GitHub) / `timeout: 300s` (Cloud Build) — the floor is only viable if it stays fast, and an unbounded job is how a 4-minute lane rots into a 25-minute one. The smoke gate's golden paths run **in parallel by default** (each `@smoke` journey is an independent spec; `E2E_WORKERS` > 1), so wall clock ≈ the slowest path; when even that can't fit, split across a job **matrix** from `smoke.mjs plan` output and reduce to one verdict (the commented `smoke-drive`/`smoke-verdict` variant in `assets/ci-gates.github.yml` — the umbrella then needs `smoke-verdict`, not the shards). Per-action/assertion timeouts are **15s** ([authoring/playwright-config.md](authoring/playwright-config.md)). Longer leashes belong to the integration-lane broad suite (30 min) and auxiliary quarantine/visual jobs — never the PR-lane gates.
+
+## Three lanes: PR lane, integration lane, release lane (production is read-only)
+
+*PR lane* = the per-PR floor (gates 1, 2, 3, 5, 6, 7, 8) against a seeded test DB / ephemeral env. *Integration lane* = the broad functional + journey suite (gate 4), on the integration-branch push (nightly optional). *Release lane* = a **promotion to production**; you must not run the mutating suite against prod:
+
+- **Don't re-run the heavy suite on prod.** Where the promotion fast-forwards, the promoted tip is the *exact SHA* the PR + integration gates already passed — gate the release on *"were the gates green at the promoted SHA?"*, a lookup, not a re-run. (Full mutating suite + sweep run pre-merge against integration/staging, never prod.) Under a single-branch model (GitHub Flow) the release branch is rebased before merging, so that lookup covers only *most* of the shipped SHA and demotes to a pre-filter — the real gate is the pre-exposure check below.
+- **Against prod, smoke runs before traffic and under a read-only production profile:** the candidate is deployed at **0% traffic**, smoked read-only (health + `presentation:render-health` on key routes + GET-only journeys) under `prod-preview`/`prod-active`, and traffic shifts only on ALIVE. A read-only production profile excludes every mutating path *regardless of declared tenant* — against production a synthetic tenant is not sufficient, because the candidate is wired to the real production database. **No mutating journeys against production data.**
+- **The post-deploy pattern below is the *integration* recorder, not the production gate.** It deploys at 100% and records a SHA-keyed verdict; production never uses that shape, because a smoke after traffic has shifted is a monitor rather than a gate. Production placement: `cloud-build` → Post-deploy smoke gate; sequencing: `resolve-release` step 4.
+
+Full doctrine: `ensure-coverage` → `references/enforcement/ci-contract.md` (the release lane).
+
+## Pattern: Post-Deploy E2E via GitHub Actions
+
+```
+CI/CD builds and deploys
+  → Post-deploy hook fires repository_dispatch
+      payload: { service_url, commit, env, pr_number }
+  → GitHub Actions runs E2E against deployed URL
+      → Posts PR comment with structured results
+      → Sets commit status (pass/fail)
+```
+
+On the integration environment (`dev`), the commit status this sets is **load-bearing, SHA-keyed release evidence**: `resolve-release` pins its release candidate to a SHA whose post-deploy smoke recorded ALIVE (its principle 11), and the verdict stays valid after `dev` moves on because the artifact for a SHA is immutable. Keep the dev deploy unblocked — 100% traffic, smoke never fails the build (`cloud-build` → *Post-deploy smoke gate* has the placement); the verdict blocks at promotion instead.
+
+### Triggering from CI
+
+Fire a `repository_dispatch` event to GitHub Actions post-deploy (implementation is CI-platform-specific). The payload shape must match:
+
+```json
+{
+  "event_type": "deploy-complete",
+  "client_payload": {
+    "env": "dev",
+    "service_url": "https://your-deployed-service.example.com",
+    "commit": "<full-40-char-sha>",
+    "pr_number": "42"
+  }
+}
+```
+
+**Example: Google Cloud Build post-deploy step** — a `waitFor: ["deploy"]` bash step in the `cloud-sdk` image that: reads a GitHub PAT from `gcloud secrets` (e.g. secret `github-pat-e2e-dispatch`); derives `PR_NUMBER` by curling the commit's `/pulls` API and parsing `prs[0]['number']`, and `SERVICE_URL` from `gcloud run services describe`; then POSTs the payload above to `/repos/{owner}/{repo}/dispatches` fire-and-forget (`|| true`).
+
+For other CI platforms, emit the same `repository_dispatch` payload via your platform's HTTP step or GitHub API action.
+
+### PR Comment Format
+
+The workflow template (`templates/e2e-workflow.yml`) posts a structured results comment — a `🧪 E2E PASSED — <env>` heading over a metric table (Total, ✅ Passed, ❌ Failed, 🟡 Quarantined, ⏱️ Duration, 📊 Route coverage).
+
+### Blocking vs Non-Blocking (this post-deploy pattern only)
+
+Applies to the **post-deploy reporting workflow above** — *not* the required per-PR gates (sweep, smoke, over-mock, ledger), which are always blocking and never carry `continue-on-error` (`ci-audit.mjs` enforces that).
+
+- **Non-blocking (initially):** `continue-on-error: true` in the test step — results reported but don't block merge.
+- **Blocking (once stable):** remove `continue-on-error` after 2+ weeks with no false-positives. This workflow fires on `repository_dispatch`, so it *can't* sit in the gates workflow's `all-gates` `needs:` — its `e2e` commit status is the one sanctioned **second** required check when blocking; everything inside the gates workflow still goes through `all-gates` only.
+
+#### Quarantine lane (the only sanctioned non-blocking path)
+
+Tests are **never skipped** (`authoring/test-skipping.md` is canonical). When a test genuinely cannot run hermetically — an **un-sandboxable external** (a provider with only a live/sandbox service, a prod-only secret) or a **genuine flake under active fix** — it goes here instead of being disabled. The lane keeps the *signal*: it **still runs and reports**, just doesn't hard-block. CI-specific wiring:
+
+- A **distinct job with `continue-on-error: true`** — never hard-blocks a PR.
+- On failure, **post a PR annotation/comment** and keep the surface **`Unverified`** in the Coverage Ledger (never `verified: true`) — surfaced and tracked, never a green skip.
+- **Dated exit that auto-resurfaces:** tag `@quarantine(until=YYYY-MM-DD, issue=#nnn)`. Until the date it runs non-blocking; **on the date the holding is void and the item re-blocks** — the flake must be fixed, the external must have a sandbox or nightly secret-gated run, or the date extended with a stated reason. Enforce with `node <ensure-coverage>/scripts/check-quarantine-expiry.mjs --files <test globs>` in the **blocking** lane. The same `until=`/`issue=` convention applies to any deferred-but-tracked suppression (an accepted-with-expiry review finding).
+- External **test keys** via secrets (e.g. `gcloud secrets`), never live keys. Everything hermetic stays in the blocking `e2e` lane.
+
+**Example — the third-party / payfields temporal check** (`presentation:temporal`, Stripe/Adyen/Braintree sandbox iframe): touches an external service → quarantine lane; the hermetic first-party temporal checks stay in the blocking `e2e` lane.
+
+### Workflow Template
+
+A reusable GitHub Actions workflow lives at `assets/e2e-workflow.yml` — copy to `.github/workflows/e2e.yml` and customize the marked sections. It handles: checkout at deployed commit; dependency install + Playwright browser setup; service readiness check; test execution with JSON reporter; PR comment posting (create/update); commit status reporting; Discord notification; artifact upload on failure.
+
+## Route Enforcement (PR Check)
+
+Separate from post-deploy E2E, add a **PR check** that validates every app route has a manifest entry. Runs on every PR, not just after deployment.
+
+A non-draft `pull_request` job (`.github/workflows/e2e-check.yml`, `types: [opened, synchronize, ready_for_review]`) that runs two steps after `actions/checkout`:
+
+<!-- skill-script-path: consumer-copy -->
+These paths are repo-relative on purpose, unlike the agent-invoked scripts elsewhere in this
+skill: they run on a GitHub Actions runner, which has no `~/.agents/skills/` tree. The copy step
+below is what puts them at `scripts/`.
+
+- **Next.js** — `node scripts/validate-manifest.mjs --manifest e2e/route-manifest.json --e2e-dir e2e` then `node scripts/detect-routes-nextjs.mjs --app-dir src/app --manifest e2e/route-manifest.json`.
+- **FastAPI** — `python3 scripts/detect-routes-fastapi.py --src-dir engine/api --manifest tests/e2e/endpoint-manifest.json`.
+
+Copy the scripts from the e2e-test skill into each repo's `scripts/` directory (or reference a shared location).
+
+### Adoption strategy
+
+1. **Week 1:** Add with `--no-strict` (warn only, don't block)
+2. **Week 2:** Switch to strict (block PRs with untracked routes)
+3. **Ongoing:** every new route gets a manifest entry (route + tier) so the sweep visits it. Coverage is the ledger's job (`@covers`), not a manifest field — a route with no test still appears in the manifest and shows uncovered in the ledger/PR reports. (No `specs` escape hatch; `specs` is informational-only, per [route-manifest.md](route-manifest.md).)