quality.yml

name: Quality Gates

on:
  push:
    # release/** pushes are covered by the PR run of each change plus Release-Green on the
    # merged combination (see ci.yml for the 2026-10-18 measurement); the per-push run here
    # only ever queued hosted slots and was cancelled by the next merge.
    branches: [main]
  pull_request:
    branches: [main, "release/**"]
    types: [opened, synchronize, reopened, ready_for_review, converted_to_draft, edited]
  merge_group:
    types: [checks_requested]
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

env:
  # CI must never mutate the runner's OS trust store (2026-07-05: a cert-flow
  # test installed a fake PEM on a persistent self-hosted runner and broke all
  # system TLS). Belt-and-suspenders with tests/_setup/isolateDataDir.ts.
  OMNIROUTE_SKIP_SYSTEM_TRUST: "1"
  CI_NODE_VERSION: "24"

jobs:
  # Same classifier as ci.yml (scripts/quality/classify-pr-changes.mjs) so PR→release
  # path filters share existence reasons: code / docs / i18n / workflow.
  changes:
    name: Change Classification
    runs-on: ubuntu-latest
    outputs:
      code: ${{ steps.classify.outputs.code }}
      docs: ${{ steps.classify.outputs.docs }}
      i18n: ${{ steps.classify.outputs.i18n }}
      workflow: ${{ steps.classify.outputs.workflow }}
      testsOnly: ${{ steps.classify.outputs.testsOnly }}
      # Exposure only (one-CI-policy step 1, RFC #8084): no job depends on it yet.
      domains: ${{ steps.classify.outputs.domains }}
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
          fetch-depth: 0
      - uses: actions/setup-node@v7
        with:
          package-manager-cache: false
          node-version: ${{ env.CI_NODE_VERSION }}
      - name: Validate gate inventory
        run: npm run check:gate-manifest
      - name: Validate recurring free catalog evidence
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.merge_group.base_sha || github.event.before }}
        run: npm run check:free-catalog-evidence
      - id: classify
        env:
          EVENT_NAME: ${{ github.event_name }}
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: |
          if [ "$EVENT_NAME" != "pull_request" ]; then
            {
              echo "code=true"
              echo "docs=true"
              echo "i18n=true"
              echo "workflow=true"
              echo "testsOnly=false"
              echo "domains=build,catalog,cli,core,db,docs,i18n,provider,routing,tests,ui,workflow"
            } >> "$GITHUB_OUTPUT"
            exit 0
          fi
          git diff --name-only "$BASE_SHA" "$HEAD_SHA" > changed-files.txt
          node scripts/quality/classify-pr-changes.mjs changed-files.txt >> "$GITHUB_OUTPUT"

  # Full build/package/boot authority lives in CI; no permanently skipped duplicate.

  # Docs/OpenAPI contract gates only — existence reason is doc accuracy + route refs.
  # Split out of fast-gates so pure-docs PRs skip typecheck/unit while still validating docs.
  docs-gates:
    name: Docs Gates (fast-path)
    needs: changes
    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && (needs.changes.outputs.docs == 'true' || needs.changes.outputs.code == 'true')) }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          package-manager-cache: false
          node-version: ${{ env.CI_NODE_VERSION }}
      - uses: ./.github/actions/npm-ci-retry
        with:
          # PR acceleration is not release-candidate provenance.
          cache: ${{ github.event_name == 'pull_request' }}
      # One walk of src/app/api for openapi-routes + docs-symbols (both still fail independently).
      - run: npm run check:api-docs-refs
      - name: Docs accuracy (fabricated-docs + i18n mirrors, strict)
        run: npm run check:docs-all

  fast-gates:
    name: Fast Quality Gates
    needs: changes
    # Code surface only — pure docs/i18n PRs skip this bag (docs-gates covers docs).
    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
    # Dynamic runner (same rule as ci.yml): use the self-hosted VPS pool only when the
    # release captain has USE_VPS_RUNNER=true AND this is not a fork PR (own-origin
    # branches only — a fork PR must never execute on the LAN runner). Var unset/false
    # or a fork PR falls back to ubuntu-latest, so this is inert until the flag flips.
    # PINNED to hosted (gap 19). This job carried the USE_VPS_RUNNER expression, and that
    # expression was DEAD CONFIGURATION: across 160 quality.yml runs the job never once landed on
    # a self-hosted runner — every non-skipped sample is `GitHub Actions NNNN`. The classifier is
    # not at fault: in the same window ci.yml's Build demonstrably ran on omniroute-113-7 and
    # omniroute-113-6, so self-hosted runs are visible when they happen.
    #
    # And if it ever HAD fired it would have inherited the measured penalty, because this job's
    # first two steps are exactly the bottleneck: actions/setup-node + npm ci took 20m06s on .113
    # with 4 concurrent runners versus 16s hosted (npm cache restore saturating the link). Median
    # here is 5.6 min hosted across 72 successful runs.
    #
    # With this pinned, USE_VPS_RUNNER governs ONLY build-like jobs — one variable, one coherent
    # purpose. That is what gap 19 asked for; a second variable turned out to be unnecessary.
    runs-on: ubuntu-latest
    # tsx gates (known-symbols, route-guard-membership) import modules that open
    # SQLite on load; provide DB env so a fresh CI DB initializes cleanly.
    env:
      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
      API_KEY_SECRET: ci-lint-api-key-secret-long
      DISABLE_SQLITE_AUTO_BACKUP: "true"
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          package-manager-cache: false
          node-version: ${{ env.CI_NODE_VERSION }}
      - uses: ./.github/actions/npm-ci-retry
        with:
          # PR acceleration is not release-candidate provenance.
          cache: ${{ github.event_name == 'pull_request' }}
      - name: Restore ESLint file cache
        if: github.event_name == 'pull_request'
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
        with:
          path: |
            .eslintcache
            .eslintcache-complexity
          key: eslint-${{ runner.os }}-${{ hashFiles('eslint.config.mjs', 'eslint.complexity-ratchets.config.mjs', 'config/quality/eslint-suppressions.json', 'package-lock.json') }}
          # No restore-keys fallback on purpose (#11600, P-II.1 of the v3.8.50 postmortem): a
          # cache built under a different suppressions file / lint config / lockfile reports
          # stale per-file verdicts, which is exactly how 215 pre-existing errors stayed
          # invisible for a whole cycle. Exact key or a cold full lint (~13 min) — never a
          # partial cache from another configuration.
      # Security scanners — same hardened install as ci.yml quality-extended
      # (gh release download = authenticated, 5000 req/hr; curl to api.github.com
      # is rate-limited to 60/hr and silently no-ops when throttled). The blocking
      # gates below SKIP (exit 0) when their binary is absent — only a measured
      # regression vs config/quality/quality-baseline.json blocks.
      - name: Install security scanners (gitleaks/osv/actionlint/zizmor/oasdiff)
        continue-on-error: true
        env:
          GH_TOKEN: ${{ github.token }}
        run: |
          set +e
          mkdir -p "$HOME/.local/bin"
          # Ratchets compare scanner COUNTS across runs. Pin every auditor: a rule-set
          # update must be an explicit PR that re-measures/rebaselines, never a random
          # red (or green) caused by whatever "latest" served that morning.
          GITLEAKS_VERSION=v8.30.1
          OSV_SCANNER_VERSION=v2.3.8
          ACTIONLINT_VERSION=v1.7.12
          ZIZMOR_VERSION=1.25.2
          OASDIFF_VERSION=v1.19.1
          # gitleaks — pinned linux x64 tarball via gh (authed), extract binary
          rm -rf /tmp/gl && mkdir -p /tmp/gl
          gh release download "$GITLEAKS_VERSION" --repo gitleaks/gitleaks --pattern '*linux_x64.tar.gz' --dir /tmp/gl
          tar -xzf /tmp/gl/*linux_x64.tar.gz -C "$HOME/.local/bin" gitleaks
          # osv-scanner — pinned linux amd64 bare binary via gh (authed)
          rm -rf /tmp/osv && mkdir -p /tmp/osv
          gh release download "$OSV_SCANNER_VERSION" --repo google/osv-scanner --pattern '*linux_amd64' --dir /tmp/osv
          install -m 0755 /tmp/osv/*linux_amd64 "$HOME/.local/bin/osv-scanner"
          # actionlint — official installer from a pinned release tag (never main)
          bash <(curl -fsSL "https://raw.githubusercontent.com/rhysd/actionlint/${ACTIONLINT_VERSION}/scripts/download-actionlint.bash") "${ACTIONLINT_VERSION#v}" "$HOME/.local/bin"
          # zizmor — pinned PyPI package (same version as ci.yml quality-extended)
          pipx install "zizmor==$ZIZMOR_VERSION" || pip install --user "zizmor==$ZIZMOR_VERSION"
          # oasdiff — pinned linux amd64 tarball via gh (authed), extract binary
          rm -rf /tmp/oasd && mkdir -p /tmp/oasd
          gh release download "$OASDIFF_VERSION" --repo Tufin/oasdiff --pattern '*linux_amd64.tar.gz' --dir /tmp/oasd
          tar -xzf /tmp/oasd/*linux_amd64.tar.gz -C "$HOME/.local/bin" oasdiff
          # ALWAYS export the bin dir (even if any step above failed)
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          "$HOME/.local/bin/gitleaks" version || true
          "$HOME/.local/bin/actionlint" -version || true
          "$HOME/.local/bin/osv-scanner" --version || true
          "$HOME/.local/bin/oasdiff" --version || true
          zizmor --version || true
      - name: Forgotten sibling tests (advisory)
        env:
          GITHUB_BASE_SHA: ${{ github.event.pull_request.base.sha }}
        run: |
          node scripts/quality/build-test-impact-map.mjs
          node scripts/check/check-forgotten-sibling-tests.mjs \
            --summary-file forgotten-sibling-tests.md \
            --json-file forgotten-sibling-tests.json
          cat forgotten-sibling-tests.md >> "$GITHUB_STEP_SUMMARY"
      - name: Upload forgotten sibling report
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: forgotten-sibling-tests
          path: |
            forgotten-sibling-tests.md
            forgotten-sibling-tests.json
          if-no-files-found: ignore
          retention-days: 30
      # Quality gates (all, non-fail-fast) — #8542: replaces 17 bare check:* steps,
      # 6 G0 gates, 4 ratchet gates, and 3 typecheck steps with a single aggregation
      # step. Each gate runs in a loop with ::group::; failures are collected and
      # reported at the end. set -uo pipefail (NOT set -e) so one failing gate does
      # not abort the job and mask every later gate. Release-added gates are folded
      # in: open-sse typecheck (#8781) and file-size base-relative mode (#8522).
      - name: Quality gates (all, non-fail-fast)
        env:
          # #8522: base-relative file-size mode on PR events — inherited drift (base
          # already over frozen cap) must not red an innocent PR. Unset on
          # workflow_dispatch (no PR base) → absolute comparison.
          PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
          BASE_REF: ${{ github.base_ref && format('origin/{0}', github.base_ref) || '' }}
        run: |
          set -uo pipefail
          gates=(
            provider-consistency provider-asset-provenance fetch-targets deps file-size error-helper
            migration-numbering public-creds db-rules known-symbols
            route-guard-membership test-discovery test-runner-api
            mutation-test-coverage any-budget:t11 build-scope pack-policy
            complexity-ratchets model-lifecycle
            lockfile duplication dead-code type-coverage compression-budget
            # #8781: open-sse workspace typecheck gate — the workspace imports @/ which
            # escapes to src/ via undeclared path aliases. See check-open-sse-typecheck.mjs.
            open-sse-typecheck
            # Hard Rule #16 — AI/bot attribution in PR commits, title or body (#14436). Reads the PR
            # from GITHUB_EVENT_PATH; no-op on non-PR events. ci.yml only runs on PRs to main.
            ai-attribution
          )
          # Ratchet-mode gates append --ratchet. `cycles` belongs here since #15281
          # (69cb18dca8): check-cycles.mjs exits 1 on ANY cycle without --ratchet, and
          # the frozen ceiling lives in quality-baseline.json → metrics.cycles — same
          # `check:cycles:ratchet` semantics ci.yml runs (base-red #15306). `boundary`
          # caps the open-sse → src edge count (measure-boundary.mjs --ratchet, ceiling
          # quality-baseline.json → metrics.boundaryOpenSseToSrc) — same as ci.yml lint.
          ratchet_gates=(
            secrets vuln-ratchet workflows openapi-breaking cycles boundary
          )
          failed=()
          for g in "${gates[@]}"; do
            echo "::group::check:$g"
            # #8522: file-size is base-relative on PR events (compare against
            # max(frozen, base)) so inherited drift doesn't red an innocent PR;
            # workflow_dispatch (no PR base) falls back to absolute comparison.
            # New-code mode (Clean-as-You-Code, 2026-08-30): complexity-ratchets and
            # dead-code compare the PR's files against the merge-base and block only on
            # what the PR added; the global totals are advisory on PRs and re-frozen at
            # release. See scripts/check/newCodeMode.mjs.
            case "$g" in file-size|complexity-ratchets|dead-code) NEW_CODE=1 ;; *) NEW_CODE= ;; esac
            if [ -n "$NEW_CODE" ] && [ -n "${PR_BASE_SHA:-}" ]; then
              npm run "check:$g" -- --base-ref "$PR_BASE_SHA" || failed+=("$g")
            else
              npm run "check:$g" || failed+=("$g")
            fi
            echo "::endgroup::"
          done
          for g in "${ratchet_gates[@]}"; do
            echo "::group::check:$g (ratchet)"
            # boundary is base-relative on PR events, like file-size (#8522): the ceiling
            # becomes max(baseline ceiling, edges on the PR base), so open-sse → src edges
            # other merges added after the seed never red an innocent PR; only edges this
            # PR adds block. workflow_dispatch (no PR base) keeps the absolute ceiling.
            case "$g" in boundary) BASE_RELATIVE=1 ;; *) BASE_RELATIVE= ;; esac
            if [ -n "$BASE_RELATIVE" ] && [ -n "${PR_BASE_SHA:-}" ]; then
              npm run "check:$g" -- --ratchet --base-ref "$PR_BASE_SHA" || failed+=("$g")
            else
              npm run "check:$g" -- --ratchet || failed+=("$g")
            fi
            echo "::endgroup::"
          done
          echo "::group::typecheck:core"
          npm run typecheck:core || failed+=("typecheck:core")
          echo "::endgroup::"
          echo "::group::check:dashboard-typecheck"
          npm run check:dashboard-typecheck || failed+=("check:dashboard-typecheck")
          echo "::endgroup::"
          # #10134: TS7 zero-new-diagnostics ratchet — folded into this non-fail-fast
          # loop (never a separate blocking step) so an earlier red gate cannot abort
          # the job and mask it (#8542 mechanism). PR-only: the base-relative
          # comparison needs the PR base SHA (empty on workflow_dispatch).
          if [ -n "${PR_BASE_SHA:-}" ]; then
            echo "::group::check:ts7-diagnostics-ratchet"
            npm run check:ts7-diagnostics-ratchet -- --base-ref "$PR_BASE_SHA" || failed+=("ts7-diagnostics-ratchet")
            echo "::endgroup::"
          fi
          if (( ${#failed[@]} )); then
            printf '::error::%d gate(s) failed: %s\n' "${#failed[@]}" "${failed[*]}"
            exit 1
          fi
      # WS4.2 (v3.8.49 plan): TypeScript 7 native-compiler SHADOW — advisory only.
      # TS7 went GA 2026-07-08 with 8-12x type-check speedups; its Compiler API only
      # arrives in 7.1, so typescript-eslint / type-coverage / Stryker stay on 6.x
      # (the hybrid is the officially documented pattern). Isolated npx on purpose:
      # installing an alias package could collide node_modules/.bin/tsc with 6.x.
      # The full result stays advisory while #8484 has a backlog. The blocking
      # base-relative ratchet (folded into the non-fail-fast gates step above)
      # rejects only diagnostics added by the PR, so existing release debt does
      # not block unrelated work.
      - name: Typecheck (core) — TS7 native shadow (advisory)
        continue-on-error: true
        run: |
          RC=0
          START=$(date +%s)
          npm exec --yes --package=typescript@7.0.2 -- tsc --pretty false -p tsconfig.typecheck-core.json || RC=$?
          echo "[ts7-shadow] exit=$RC elapsed=$(( $(date +%s) - START ))s — the 6.x step above stays authoritative"
          exit $RC
      # TIA: build the impact map at runtime (gitignored, ~21MB) and run only the
      # unit tests impacted by this PR's changed files. On hub/unmapped changes the
      # selector returns __RUN_ALL__ — full-suite authority is ci.yml's `test-unit`
      # 8-shard job (test:unit:ci:shard), NOT an unsharded re-run here. Stacking an
      # unsharded test:unit:ci on top of it doubled wall time without extra coverage.
      # (quality.yml had its own 4-shard `fast-unit` + `fast-vitest` for PR->release from
      # 2026-06-23; ci.yml runs on those PRs since #14420 (2026-10-01), so both were an
      # exact duplicate — ~62 runner-min and 5 hosted jobs per PR — and were removed.)
      #
      # BLOCKING for the *impacted subset* (flipped 2026-06-17). Fail-safe full
      # coverage remains required via ci.yml `Unit Tests (N/8)` (test-unit).
      - name: Impacted unit tests (TIA subset; blocking)
        env:
          GITHUB_BASE_REF: ${{ github.base_ref }}
        run: |
          git fetch --no-tags origin "$GITHUB_BASE_REF" || true
          # The advisory sibling-test step generates the same map earlier in this job.
          [ -f config/quality/test-impact-map.json ] || node scripts/quality/build-test-impact-map.mjs
          SEL="$(node scripts/quality/select-impacted-tests.mjs)"
          # Shadow evidence (#8084): persist every selection so TIA false negatives can
          # be measured against ci.yml test-unit's full-suite verdict across releases BEFORE
          # any gate authority moves off ordinary PRs. Artifact uploaded below.
          printf '%s\n' "$SEL" > tia-selection.txt
          if [ -z "$SEL" ]; then
            echo "TIA selection: empty (no source/test changes)" >> "$GITHUB_STEP_SUMMARY"
            echo "No source/test changes — skipping unit tests"; exit 0
          fi
          # CI runners are 4-vCPU; run at --test-concurrency=4 (matching the ci.yml unit
          # job) rather than test:unit's local-tuned concurrency=20. Oversubscribing the
          # runner makes timing-sensitive tests (db-backup, upstream-timeout, ...) flake,
          # which must not happen on a blocking gate. DATA_DIR isolation keeps the parallel
          # run race-free regardless of concurrency.
          if echo "$SEL" | grep -q "__RUN_ALL__"; then
            echo "TIA selection: __RUN_ALL__ (fail-safe) — full-suite authority stays with ci.yml test-unit" >> "$GITHUB_STEP_SUMMARY"
            echo "Fail-safe: __RUN_ALL__ — deferring FULL unit suite to ci.yml test-unit (8-shard)."
            echo "Not re-running unsharded test:unit:ci here (duplicate of test-unit coverage)."
            exit 0
          fi
          echo "TIA selection: $(grep -c . tia-selection.txt) impacted test file(s) — full suite still runs in ci.yml test-unit (shadow-evidence phase, #8084)" >> "$GITHUB_STEP_SUMMARY"
          echo "Running impacted tests:"; echo "$SEL"
          mapfile -t FILES <<< "$SEL"
          # Loader parity with test:unit:ci:shard (#6787): tests/unit/dashboard/** runs
          # under `--import tsx` (CJS transform — required for ESM-only deep imports like
          # @lobehub/icons/es/* reached via lobeProviderIcons.ts); everything else under
          # `--import tsx/esm`. A single tsx/esm invocation false-reds every dashboard
          # module-shape test the impact map selects ("Unexpected token 'export'").
          DASH=(); REST=()
          for f in "${FILES[@]}"; do
            case "$f" in
              tests/unit/dashboard/*) DASH+=("$f") ;;
              *) REST+=("$f") ;;
            esac
          done
          RC=0
          if [ ${#REST[@]} -gt 0 ]; then
            node --import tsx/esm --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 "${REST[@]}" || RC=$?
          fi
          if [ ${#DASH[@]} -gt 0 ]; then
            node --import tsx --import ./open-sse/utils/setupPolyfill.ts --import ./tests/_setup/isolateDataDir.ts --test --test-force-exit --test-concurrency=4 "${DASH[@]}" || RC=$?
          fi
          exit $RC
      # #8084 shadow evidence: keep the raw selection downloadable so TIA misses can be
      # audited against ci.yml test-unit failures on the same commit (gate moves need this data).
      - name: Upload TIA selection (shadow evidence)
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: tia-selection
          path: tia-selection.txt
          if-no-files-found: ignore
          retention-days: 30

  # ── Pacote 4 (plano mestre testes+CI, aprovado 2026-07-04) ─────────────────────────
  # No-new-warnings por PR via ESLint bulk suppressions nativo (>=9.24). O baseline
  # config/quality/eslint-suppressions.json congela as violações EXISTENTES por
  # arquivo+regra; qualquer warning NOVO aparece e o --max-warnings 0 falha o job — o
  # drift de +41/+88 warnings por ciclo passa a morrer no PR que o introduz, em vez de
  # ser rebaselinado às cegas na release. Aperto do baseline (na reconciliação da
  # release): npx eslint . --prune-suppressions --suppressions-location config/quality/eslint-suppressions.json
  #
  # Forks use hosted runners and the same required code-quality result. A base-red
  # is maintainer work, but must not be reported as a passing candidate.
  lint-guard:
    name: No new ESLint warnings
    needs: changes
    if: ${{ github.event_name != 'pull_request' || ((github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) && needs.changes.outputs.code == 'true') }}
    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && github.event_name != 'merge_group' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && fromJSON('["self-hosted","omni-light"]')) || 'ubuntu-latest' }}
    # 2026-08-30: a cold full lint with the eslint-plugin-react-hooks 7 compiler rules is
    # killed on the 7 GB hosted runner without a message (status null → exit 1, the
    # JSON never written); the box lints it in ~12 min with the heap below.
    # G0 (trilho .50): security-events:read lets the CodeQL ratchet below read open
    # code-scanning alerts via `gh api .../code-scanning/alerts` (same as ci.yml's
    # quality-gate job). contents: read keeps checkout working.
    permissions:
      contents: read
      security-events: read
    steps:
      - uses: actions/checkout@v7
        with:
          persist-credentials: false
      - uses: actions/setup-node@v7
        with:
          package-manager-cache: false
          node-version: ${{ env.CI_NODE_VERSION }}
      - uses: ./.github/actions/npm-ci-retry
        with:
          # PR acceleration is not release-candidate provenance.
          cache: ${{ github.event_name == 'pull_request' }}
      - name: Restore ESLint file cache
        if: github.event_name == 'pull_request'
        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6
        with:
          path: |
            .eslintcache
            .eslintcache-complexity
          key: eslint-${{ runner.os }}-${{ hashFiles('eslint.config.mjs', 'eslint.complexity-ratchets.config.mjs', 'config/quality/eslint-suppressions.json', 'package-lock.json') }}
          # No restore-keys fallback on purpose (#11600, P-II.1 of the v3.8.50 postmortem): a
          # cache built under a different suppressions file / lint config / lockfile reports
          # stale per-file verdicts, which is exactly how 215 pre-existing errors stayed
          # invisible for a whole cycle. Exact key or a cold full lint (~13 min) — never a
          # partial cache from another configuration.
      - name: ESLint (baseline congelado — warning novo = vermelho)
        # lint:json writes the report; --max-warnings 0 keeps no-new-warnings policy.
        run: npm run lint:json -- --max-warnings 0
        env:
          NODE_OPTIONS: --max-old-space-size=8192
      # ── G0 (trilho .50): motor de ratchet também no trilho B ─────────────────────
      # This job just wrote .artifacts/eslint-results.json — collect-metrics prefers
      # that file, so the ratchet engine lands here at ZERO extra ESLint cost (one
      # inventory, two consumers; same reason ci.yml chains lint → quality-gate).
      # The coverage-report artifact does not exist on this rail, so both ratchet
      # invocations run --allow-missing: coverage.* metrics skip gracefully while
      # the deterministic ones (eslint / openapi-coverage / i18n-ui) stay BLOCKING.
      # Coverage authority remains on the main rail (ci.yml test-coverage → quality-gate).
      - run: npm run quality:collect
      - name: Ratchet check (blocking)
        run: node scripts/quality/check-quality-ratchet.mjs --allow-missing --summary .artifacts/quality-ratchet.md
      - name: Require-tighten (blocking)
        run: node scripts/quality/check-quality-ratchet.mjs --allow-missing --require-tighten
      # CodeQL alerts ratchet — same semantics as ci.yml quality-gate: exits 1 ONLY
      # on a real regression (open alerts > baseline in quality-baseline.json);
      # a measurement failure (gh/auth/api) self-skips with exit 0.
      - name: CodeQL alerts ratchet (blocking)
        run: npm run check:codeql-ratchet
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Append ratchet summary
        if: always()
        run: cat .artifacts/quality-ratchet.md >> "$GITHUB_STEP_SUMMARY" || true

  # Merge-integrity: pega no PR os dois vazamentos crônicos de merge que hoje só
  # explodem na release-PR. (1) CHANGELOG-eat — o auto-resolve do merge come
  # bullets vizinhos/seções inteiras (incidente #6193, 2026-07-05: 212 linhas /
  # 130 bullets); o checkout de PR é refs/pull/N/merge, então comparar contra a
  # base detecta o eat ANTES do merge. (2) SKILL.md gerado stale vs o catálogo de
  # agent-skills (#6186 mergeou um id de catálogo sem rodar o gerador → 8 reds de
  # integration invisíveis até a release).
  #
  # Merge integrity is required regardless of who owns the PR branch.
  merge-integrity:
    name: Merge integrity (changelog + generated skills)
    # Always on non-draft PRs — CHANGELOG/skills can break on docs-only merges too.
    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false || startsWith(github.head_ref, 'mergify/merge-queue/')) }}
    runs-on: ubuntu-latest
    env:
      JWT_SECRET: ci-lint-secret-with-sufficient-length-for-validation
      API_KEY_SECRET: ci-lint-api-key-secret-long
      DISABLE_SQLITE_AUTO_BACKUP: "true"
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          fetch-depth: 0
          persist-credentials: false
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v6
        with:
          package-manager-cache: false
          node-version: ${{ env.CI_NODE_VERSION }}
      - uses: ./.github/actions/npm-ci-retry
        with:
          # PR acceleration is not release-candidate provenance.
          cache: ${{ github.event_name == 'pull_request' }}
      - name: CHANGELOG integrity (nenhum bullet da base pode sumir no merge-result)
        run: npm run check:changelog-integrity
      - name: Agent-skills generator sync (SKILL.md gerado ≡ catálogo)
        run: npm run check:agent-skills-sync

  admission-verdict:
    name: Gate / Quality
    if: ${{ always() }}
    runs-on: ubuntu-latest
    timeout-minutes: 5
    needs:
      - changes
      - docs-gates
      - fast-gates
      - lint-guard
      - merge-integrity
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
        with:
          ref: ${{ github.sha }}
          persist-credentials: false
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
        with:
          package-manager-cache: false
          node-version: ${{ env.CI_NODE_VERSION }}
      - name: Evaluate exact-candidate admission
        env:
          NEEDS_JSON: ${{ toJSON(needs) }}
        run: node scripts/quality/admission-verdict.mjs quality
      - name: Retain admission receipt
        if: ${{ always() }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
        with:
          name: quality-admission-${{ github.run_id }}-${{ github.run_attempt }}
          path: .artifacts/quality-admission.json
          if-no-files-found: error
          retention-days: 14