@1aboveio/skills 0.10.0

package/skills/engineering/e2e-test/assets/ci-gates.github.yml

@@ -0,0 +1,451 @@
+# Coverage gates — GitHub Actions template (satisfies ensure-coverage references/enforcement/ci-contract.md).
+#
+# Each gate is its own BLOCKING job, none standing in for another. Two of the three
+# lanes live in this file (the release lane lives in resolve-release):
+#   PR lane (every PR, fast): inventory, accounting, render sweep, no-over-mock, the
+#     Review-Contract checklist validate, the quarantine auto-resurface gate, and the
+#     curated E2E SMOKE golden-path liveness gate (gate 8) — the minimal valuable floor.
+#   Integration/nightly lane (heavy, before release): the broad functional + journey E2E
+#     suite (gate 4), demoted OFF the per-PR critical path via `if:` below — it runs on
+#     the integration-branch push and nightly, and is verified green before release.
+# Plus the meta-gate that runs ci-audit against this file so the gates can't be silently
+# dropped, and the `all-gates` UMBRELLA job branch protection points at. Copy to
+# .github/workflows/coverage-gates.yml and replace <…>. Verify it stays wired with
+# ensure-coverage's CI audit (see references/enforcement/ci-contract.md).
+#
+# Conventions this template encodes (see e2e-test references/ci-playwright-container.md
+# and references/ci-integration.md):
+#   1. DOCKER-PREFERRED: every browser job runs in the official pinned Playwright
+#      container (browsers + OS deps ship in the image — nothing to install per job).
+#      The plain-runner alternative (`npx playwright install --with-deps chromium` on
+#      ubuntu-latest) is documented but NOT the default. Keep every image pin in this
+#      file IDENTICAL and matching the repo's @playwright/test version.
+#   2. SHARED DEPENDENCY INSTALL: one pnpm store cache (same key + restore-keys) is
+#      shared by every job and every run — after the first warm run, jobs restore
+#      instead of downloading, and a lockfile bump restores the previous store and
+#      only fetches the delta. (On the very first run after a bump, parallel jobs
+#      each miss and download — one save wins; steady-state is shared.)
+#   3. TIME BUDGET: PR-lane jobs carry `timeout-minutes: 5` — the per-PR floor targets
+#      ≤5 min wall clock. Only the demoted integration-lane suite gets a longer leash.
+#   4. UMBRELLA: branch protection requires ONLY the `all-gates` job (see bottom) — a
+#      renamed/added gate can never silently fall out of protection.
+
+name: Coverage Gates
+on:
+  pull_request:
+  push:
+    branches: [integration]   # the resolve-issues epic integration branch — runs the heavy E2E lane (REQUIRED before release)
+  # OPTIONAL extra cadence — uncomment to also run the broad suite nightly. Not required:
+  # the integration-branch push above is the gate that blocks release. Nightly only adds
+  # a time-based catch for drift between integration pushes.
+  # schedule:
+  #   - cron: '0 3 * * *'
+
+# ONE pinned image for every browser job — keep the tag identical everywhere in this
+# file and aligned with the repo's @playwright/test version (mismatch → either a
+# network `playwright install` per run, or protocol failures). Bump both together.
+# (GitHub Actions can't interpolate workflow env into `container.image`, so the tag is
+# repeated below — this comment is the single place that says which tag is canonical.)
+# Canonical pin: mcr.microsoft.com/playwright:v1.61.0-noble
+
+jobs:
+  # Static test-lint gates — fails if this PR ADDS a banned pattern to a test file:
+  # a skip/focus/xfail (no-skip), a fixed sleep (no-fixed-timeout), an empty test
+  # (no-empty-test), or a mock of a first-party internal seam (mock-internal-seam,
+  # default-on). Decidable, deterministic, ~zero false positives. Inherited diff-mode
+  # violations are left alone; a PR may not introduce a new one. Add rules in lint-tests.mjs.
+  lint-tests:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }   # need the base commit for the diff
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: node <ensure-coverage>/scripts/lint-tests.mjs --diff "origin/${{ github.base_ref }}"
+      # Gate 5 — no over-mock (depth axis), WHOLE-TREE lane: inherited first-party-seam
+      # mocks block until removed (the --diff run above already covers newly-added ones).
+      # Zero-tolerance, no waiver; ci-audit looks for `mock-internal-seam` by name.
+      - run: node <ensure-coverage>/scripts/lint-tests.mjs --rules mock-internal-seam
+
+  # Gate 1 — inventory freshness (a new route can't be silently uncovered).
+  inventory-freshness:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: node scripts/gen-inventory.mjs   # INVENTORY-CONTRACT adapter → surface-inventory.json
+      - run: node <e2e-test>/scripts/project-route-manifest.mjs --inventory docs/tests/_generated/surface-inventory.json --overlay e2e/route-manifest.overlay.json --out e2e/route-manifest.json
+      - run: git diff --exit-code docs/tests/_generated/surface-inventory.json e2e/route-manifest.json
+
+  # Gate 2 — accounting (ledger). Static; proves a qualifying test was AUTHORED.
+  coverage-accounting:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: node <ensure-coverage>/scripts/coverage-ledger.mjs validate   # fails on Missing/Over-mocked/Unverified
+
+  # Gate 6 — Review-Contract checklist validate. Static; the anti-ritual guard that
+  # every PASS/FAIL checklist row carries an evidence locator (file:line / `command` /
+  # #issue) and no gate row is left TODO. Doctrine: ensure-coverage hooks.md (CI tier) —
+  # it runs at the implement-and-pr gate step AND here. Point --target at the committed
+  # Review-Contract checklist doc (or the file the PR body's checklist is extracted to).
+  coverage-checklist:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: node <ensure-coverage>/scripts/coverage-checklist.mjs validate <docs/tests/CONTRACT-CHECKLIST.md>
+
+  # Gate 6b — Review-Contract evidence-block freshness. The block is stamped with the
+  # HEAD it describes and `validate` fails when the stamp isn't that HEAD.
+  # `implement-and-pr` already tells the producer to run it, but that is an instruction
+  # to do something last, and a fix round is exactly when a later commit appears. CI
+  # runs on the push that broke the stamp, so it can't be outrun. (Named incident: five
+  # docs-only "record round N evidence" commits on one PR, each invalidated by the next,
+  # generating evidence-fidelity findings for three consecutive rounds.)
+  #
+  # The `ref` below is load-bearing: actions/checkout defaults to the PR merge ref, so
+  # HEAD would be a synthetic merge commit, not the PR head the block was stamped at —
+  # without it this gate red-lights every correct PR, and a gate that cries wolf gets
+  # switched off within a day.
+  evidence-block:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+          fetch-depth: 0   # the block's base..head derivations need real history
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      # validate resolves the current head with `git rev-parse HEAD`, so the checkout
+      # ref above is what makes the stamp comparison correct — no flag needed.
+      # --source is what lets it also re-derive the production-diff-emptiness claim.
+      - run: node <ensure-coverage>/scripts/evidence-block.mjs validate <docs/tests/evidence.json> --source <src,app,packages>
+
+  # Gate 7 — quarantine auto-resurface. BLOCKING (distinct from the non-blocking
+  # quarantine *lane* below): fails once any `@quarantine(until=…)` / `until=` exit
+  # date is in the past, so a deferred suppression can't rot green into a permanent
+  # skip. ci-audit looks for `check-quarantine-expiry` by name.
+  quarantine-expiry:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: node <ensure-coverage>/scripts/check-quarantine-expiry.mjs   # exit 1 on any expired dated exit
+
+  # Gate 3 — render sweep. SEPARATE job: browser + seeded DB. Catches the crashing
+  # route a green functional suite sails past. NOT the functional suite.
+  # Runs in the pinned Playwright container (docker-preferred): browsers ship in the
+  # image, so there is no per-job `playwright install`. Inside a job container,
+  # services are reached by service label (postgres:5432), NOT localhost.
+  presentation-sweep:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    container:
+      image: mcr.microsoft.com/playwright:v1.61.0-noble   # keep identical to every other pin in this file
+      options: --ipc=host
+    services:
+      postgres: { image: postgres:16, env: { POSTGRES_PASSWORD: postgres } }
+    env: { E2E_AUTH_BYPASS: '1', DATABASE_URL: 'postgres://postgres:postgres@postgres:5432/test' }
+    steps:
+      - uses: actions/checkout@v4
+      # Shared pnpm store — SAME cache key + restore-keys as every other job, so
+      # steady-state runs restore instead of downloading (see header convention 2).
+      - uses: actions/cache@v4
+        with: { path: ~/.pnpm-store, key: 'pnpm-store-${{ hashFiles(''pnpm-lock.yaml'') }}', restore-keys: pnpm-store- }
+      - run: corepack enable && pnpm config set store-dir ~/.pnpm-store && pnpm install --frozen-lockfile
+      - run: <seed + migrate>
+      - run: <boot app on $BASE_URL> &
+      - run: |
+          node <e2e-test>/scripts/presentation-sweep.mjs \
+            --manifest e2e/route-manifest.json --base-url "${BASE_URL:-http://127.0.0.1:3000}" \
+            --fixtures e2e/sweep-fixtures.mjs --out docs/tests/_generated/presentation-results.json
+      # NEVER add `continue-on-error: true` here — that turns the gate into theatre.
+
+  # Gate 8 — curated E2E smoke (golden-path liveness). PR-LANE FLOOR, blocking.
+  # Boots the REAL app and drives only the handful of do-not-ship journeys
+  # (sign in → core action → pay), writes smoke-results.json, then reduces those
+  # observations through smoke.mjs verdict. Any fail/blocked/missing path reds the
+  # build. This — NOT the broad functional suite below — is the per-PR liveness
+  # gate. It catches the integrated, render-time bug a green unit/functional suite
+  # sails past (#237: an invisible primary button, a crash on mount).
+  # ci-audit looks for `smoke … verdict` by name.
+  #
+  # PARALLEL BY DEFAULT: the golden paths run concurrently inside this job
+  # (E2E_WORKERS > 1 + fullyParallel — each @smoke journey is an independent spec),
+  # so wall clock ≈ the slowest single path, not the sum. If the curated set still
+  # can't fit the 5-minute budget in one job, fan the paths out across a matrix —
+  # see the commented `smoke-drive` variant below this job.
+  smoke:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    container:
+      image: mcr.microsoft.com/playwright:v1.61.0-noble   # keep identical to every other pin in this file
+      options: --ipc=host
+    services:
+      postgres: { image: postgres:16, env: { POSTGRES_PASSWORD: postgres } }
+    env: { E2E_AUTH_BYPASS: '1', E2E_WORKERS: '4', DATABASE_URL: 'postgres://postgres:postgres@postgres:5432/test' }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with: { path: ~/.pnpm-store, key: 'pnpm-store-${{ hashFiles(''pnpm-lock.yaml'') }}', restore-keys: pnpm-store- }
+      - run: corepack enable && pnpm config set store-dir ~/.pnpm-store && pnpm install --frozen-lockfile
+      - run: <seed + migrate>
+      - run: <boot app on $BASE_URL> &
+      # Validate + reconcile BEFORE gating: shape-checks the manifest and, via
+      # --journeys, verifies every browser path references a real @smoke-tagged
+      # journey AND every @smoke journey is in the manifest — a drift either way
+      # (esp. an @smoke journey missing from the manifest, a silent false-ALIVE)
+      # reds the build here instead of passing vacuously.
+      - run: node <smoke>/scripts/smoke.mjs validate --manifest smoke.manifest.json --journeys <e2e-journeys-dir>
+      - run: node <smoke>/scripts/smoke.mjs plan --manifest smoke.manifest.json --target local --json > smoke-plan.json
+      - run: <drive smoke-plan.json through Playwright/API/CLI (browser paths run in parallel via E2E_WORKERS) and write smoke-results.json>
+      - run: node <smoke>/scripts/smoke.mjs verdict --manifest smoke.manifest.json --target local --results smoke-results.json --out smoke-verdict.json
+      # NEVER add `continue-on-error: true` here — that turns the liveness floor into theatre.
+
+  # ── OPTIONAL smoke fan-out (only when in-job parallelism can't hit the 5-min budget):
+  # split the plan into a matrix so each golden path (or shard) gets its own job, then
+  # merge the per-path results and compute ONE verdict. The verdict job stays the single
+  # blocking reduction — the umbrella needs `smoke-verdict`, not the shards.
+  #
+  # smoke-plan:
+  #   runs-on: ubuntu-latest
+  #   timeout-minutes: 5
+  #   outputs: { paths: '${{ steps.plan.outputs.paths }}' }
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-node@v4
+  #       with: { node-version: 20 }
+  #     - run: node <smoke>/scripts/smoke.mjs validate --manifest smoke.manifest.json --journeys <e2e-journeys-dir>
+  #     - id: plan
+  #       run: |
+  #         node <smoke>/scripts/smoke.mjs plan --manifest smoke.manifest.json --target local --json > smoke-plan.json
+  #         echo "paths=$(node -e 'console.log(JSON.stringify(JSON.parse(require("fs").readFileSync("smoke-plan.json","utf8")).run.map(p=>p.id)))')" >> "$GITHUB_OUTPUT"
+  # smoke-drive:
+  #   needs: smoke-plan
+  #   strategy: { fail-fast: false, matrix: { path: '${{ fromJSON(needs.smoke-plan.outputs.paths) }}' } }
+  #   runs-on: ubuntu-latest
+  #   timeout-minutes: 5
+  #   container: { image: 'mcr.microsoft.com/playwright:v1.61.0-noble', options: '--ipc=host' }
+  #   services:
+  #     postgres: { image: postgres:16, env: { POSTGRES_PASSWORD: postgres } }
+  #   env: { E2E_AUTH_BYPASS: '1', DATABASE_URL: 'postgres://postgres:postgres@postgres:5432/test' }
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/cache@v4
+  #       with: { path: ~/.pnpm-store, key: 'pnpm-store-${{ hashFiles(''pnpm-lock.yaml'') }}', restore-keys: pnpm-store- }
+  #     - run: corepack enable && pnpm config set store-dir ~/.pnpm-store && pnpm install --frozen-lockfile
+  #     - run: <seed + migrate>
+  #     - run: <boot app on $BASE_URL> &
+  #     - run: <drive ONLY path "${{ matrix.path }}" and write smoke-results-${{ matrix.path }}.json>
+  #     - uses: actions/upload-artifact@v4
+  #       with: { name: 'smoke-results-${{ matrix.path }}', path: 'smoke-results-*.json' }
+  # smoke-verdict:
+  #   needs: smoke-drive
+  #   if: always()   # a failed shard must still reach the verdict (→ DEAD), not vanish
+  #   runs-on: ubuntu-latest
+  #   timeout-minutes: 5
+  #   steps:
+  #     - uses: actions/checkout@v4
+  #     - uses: actions/setup-node@v4
+  #       with: { node-version: 20 }
+  #     - uses: actions/download-artifact@v4
+  #       with: { pattern: 'smoke-results-*', merge-multiple: true }
+  #     - run: node -e 'const fs=require("fs");const all=fs.readdirSync(".").filter(f=>/^smoke-results-.*\.json$/.test(f)).flatMap(f=>JSON.parse(fs.readFileSync(f,"utf8")));fs.writeFileSync("smoke-results.json",JSON.stringify(all,null,2))'
+  #     - run: node <smoke>/scripts/smoke.mjs verdict --manifest smoke.manifest.json --target local --results smoke-results.json --out smoke-verdict.json
+
+  # Gate 4 — broad functional + journey suite (distinct from gate 3 and gate 8).
+  # HEAVY/INTEGRATION LANE, blocking — but DEMOTED off the per-PR critical path: the
+  # `if:` runs it only on the integration-branch push and the nightly schedule, never
+  # on a PR. The per-PR floor is the curated E2E smoke gate above; the full behavioral
+  # suite (every form, error path, edge case) is verified before release, not on every
+  # PR. A journey-only regression is caught here, at integration — the accepted cost of
+  # the demotion. Excludes @quarantine-tagged tests, which run in the non-blocking lane.
+  e2e:
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30   # integration lane — the one lane allowed past the 5-min PR budget
+    container:
+      image: mcr.microsoft.com/playwright:v1.61.0-noble   # keep identical to every other pin in this file
+      options: --ipc=host
+    services:
+      postgres: { image: postgres:16, env: { POSTGRES_PASSWORD: postgres } }
+    env: { E2E_AUTH_BYPASS: '1', E2E_WORKERS: '4', DATABASE_URL: 'postgres://postgres:postgres@postgres:5432/test' }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with: { path: ~/.pnpm-store, key: 'pnpm-store-${{ hashFiles(''pnpm-lock.yaml'') }}', restore-keys: pnpm-store- }
+      - run: corepack enable && pnpm config set store-dir ~/.pnpm-store && pnpm install --frozen-lockfile
+      - run: <seed + migrate>
+      - run: pnpm playwright test --grep-invert "@quarantine"
+
+  # Quarantine lane — the ONLY sanctioned non-blocking path (tests are never skipped).
+  # Un-sandboxable externals or a genuine flake under active fix go HERE: the test
+  # still RUNS and REPORTS, it just doesn't block. Keep the surface graded `Unverified`
+  # in the ledger (never `verified: true`), with a dated exit. run+report ≠ stop running.
+  # Deliberately NOT in the all-gates umbrella below.
+  quarantine:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    continue-on-error: true   # the whole point — must never hard-block a PR
+    container:
+      image: mcr.microsoft.com/playwright:v1.61.0-noble   # keep identical to every other pin in this file
+      options: --ipc=host
+    services:
+      postgres: { image: postgres:16, env: { POSTGRES_PASSWORD: postgres } }
+    env: { E2E_AUTH_BYPASS: '1', DATABASE_URL: 'postgres://postgres:postgres@postgres:5432/test' }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with: { path: ~/.pnpm-store, key: 'pnpm-store-${{ hashFiles(''pnpm-lock.yaml'') }}', restore-keys: pnpm-store- }
+      - run: corepack enable && pnpm config set store-dir ~/.pnpm-store && pnpm install --frozen-lockfile
+      - run: <seed + migrate>
+      - run: pnpm playwright test --grep "@quarantine" --pass-with-no-tests   # provider test keys via secrets, never live keys; green when nothing is quarantined
+      # On failure: post a PR annotation and keep the surface `Unverified` — surfaced + tracked, not a green skip.
+
+  # Visual regression GATE (presentation:visual) — OPT-IN, BLOCKING when present.
+  # Runs ONLY in the pinned Playwright container so baselines (minted by the regen job
+  # below) and this comparison share one rendering environment — a baseline minted on
+  # another OS reds on every glyph's anti-aliasing, which is how visual gates get
+  # disabled. Compares the rendered page against the COMMITTED baselines; it never
+  # writes them. Uploads the 3-up diff as an artifact on failure. Only needed when a
+  # surface declares `requiredLevels: [presentation:visual]`; harmless (no specs) if none.
+  visual-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    container:
+      image: mcr.microsoft.com/playwright:v1.61.0-noble   # keep identical to every other pin in this file — and to visual-baseline-regen
+      options: --ipc=host
+    services:
+      postgres: { image: postgres:16, env: { POSTGRES_PASSWORD: postgres } }
+    env: { E2E_AUTH_BYPASS: '1', DATABASE_URL: 'postgres://postgres:postgres@postgres:5432/test' }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/cache@v4
+        with: { path: ~/.pnpm-store, key: 'pnpm-store-${{ hashFiles(''pnpm-lock.yaml'') }}', restore-keys: pnpm-store- }
+      - run: corepack enable && pnpm config set store-dir ~/.pnpm-store && pnpm install --frozen-lockfile
+      - run: <seed + migrate>
+      - run: <boot app on $BASE_URL> &
+      # --pass-with-no-tests: a repo with no @visual specs must stay green — without it,
+      # Playwright exits 1 on "no tests found" and the all-gates umbrella bricks every PR.
+      - run: pnpm playwright test --grep "@visual" --pass-with-no-tests   # toHaveScreenshot specs; fails on drift from committed baselines
+      # NEVER add `continue-on-error: true` here — that turns the gate into theatre.
+      - if: failure()
+        uses: actions/upload-artifact@v4
+        with: { name: visual-diff, path: 'test-results/**/*-diff.png', retention-days: 30 }
+
+  # Visual BASELINE-REGEN — ON-DEMAND only (PR label `update-visual-baselines`), the
+  # ONLY sanctioned writer of baselines. Same pinned image as the gate. Regenerates
+  # the PNGs, commits them back to the PR branch (a baseline change is reviewable
+  # evidence tied to a declared intended UI change — never a silent --update to green),
+  # then posts the durable baseline link + ephemeral diff URL to the issue AND PR and
+  # RETURNS both as a value (`--evidence-out`, plus stdout) for the resolve-issues
+  # orchestrator to record on the unit. This job never writes the run manifest itself —
+  # the orchestrator is its only writer (ADR 0001 decision 5). Never blocks; it's an
+  # explicit human/agent action.
+  visual-baseline-regen:
+    if: contains(github.event.pull_request.labels.*.name, 'update-visual-baselines')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    container:
+      image: mcr.microsoft.com/playwright:v1.61.0-noble   # MUST match visual-gate's image (and every other pin in this file)
+      options: --ipc=host
+    permissions: { contents: write, issues: write, pull-requests: write }
+    services:
+      postgres: { image: postgres:16, env: { POSTGRES_PASSWORD: postgres } }
+    env: { E2E_AUTH_BYPASS: '1', DATABASE_URL: 'postgres://postgres:postgres@postgres:5432/test', GH_TOKEN: '${{ github.token }}' }
+    steps:
+      - uses: actions/checkout@v4
+        with: { ref: '${{ github.head_ref }}' }
+      - uses: actions/cache@v4
+        with: { path: ~/.pnpm-store, key: 'pnpm-store-${{ hashFiles(''pnpm-lock.yaml'') }}', restore-keys: pnpm-store- }
+      - run: corepack enable && pnpm config set store-dir ~/.pnpm-store && pnpm install --frozen-lockfile
+      - run: <seed + migrate>
+      - run: <boot app on $BASE_URL> &
+      - run: pnpm playwright test --grep "@visual" --update-snapshots
+      - run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add '**/*-snapshots/**'
+          git diff --staged --quiet || git commit -m "chore(visual): regenerate baselines"
+          git push
+      - id: artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with: { name: visual-preview, path: 'test-results/**', retention-days: 30 }
+      - run: |
+          node <e2e-test>/scripts/post-visual-evidence.mjs \
+            --unit "${{ github.event.pull_request.number }}" \
+            --repo "${{ github.repository }}" --sha "$(git rev-parse HEAD)" \
+            --issue "<linked issue #>" --pr "${{ github.event.pull_request.number }}" \
+            --diff-artifact "${{ steps.artifact.outputs.artifact-url }}" \
+            --results docs/tests/_generated/presentation-results.json \
+            --evidence-out visual-evidence.json
+      # The evidence is a RETURNED value, never a manifest write — resolve-issues'
+      # orchestrator records it (ADR 0001 decision 5). Upload it so the run can read it.
+      - if: always()
+        uses: actions/upload-artifact@v4
+        with: { name: visual-evidence, path: visual-evidence.json, retention-days: 30 }
+
+  # Meta-gate (bootstrap) — run ci-audit against THIS workflow so the gates above
+  # can't be silently deleted or weakened later. Without this job, nothing guards the
+  # gates; ci-audit's own META_GATE is exactly "is ci-audit run by CI?". Keep the
+  # --files list in sync with the gate files you actually ship.
+  gate-audit:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: node <ensure-coverage>/scripts/ci-audit.mjs --files .github/workflows/coverage-gates.yml
+
+  # UMBRELLA — the ONE status check branch protection requires. Protect the branch
+  # with only `all-gates`: every blocking gate is in `needs`, so adding or renaming a
+  # gate job (and adding it here) can never silently fall out of protection, and a
+  # protection config listing eight job names by hand is never needed. `skipped` is
+  # deliberately allowed (gate 4 is PR-skipped by design; a conditional job that
+  # branch protection required directly would otherwise pass vacuously — here the
+  # umbrella still fails on any failure/cancellation of what DID run).
+  # The quarantine lane is deliberately absent from `needs` — it is non-blocking.
+  all-gates:
+    if: always()
+    needs:
+      - lint-tests
+      - inventory-freshness
+      - coverage-accounting
+      - coverage-checklist
+      - evidence-block
+      - quarantine-expiry
+      - presentation-sweep
+      - smoke
+      - e2e
+      - visual-gate
+      - gate-audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      # The check is an expression on needs.*.result — immune to a job OUTPUT that
+      # happens to contain the string "result": "failure" (toJSON(needs) includes
+      # outputs, so grepping it can false-fail).
+      - name: Fail if any required gate failed or was cancelled
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        env:
+          RESULTS: ${{ toJSON(needs) }}
+        run: |
+          echo "$RESULTS"
+          echo 'A required gate failed or was cancelled.'
+          exit 1
+      - name: All gates green
+        run: echo "All required gates passed (or were skipped by design)."