ci(quality): cut PR gate wall time without dropping protection (#6716)

Collapse duplicate CI spend while keeping each gate's existence reason: - quality.yml: TIA __RUN_ALL__ defers full unit to fast-unit 4-shard (#6781); path filters via classify-pr-changes; docs-gates split; draft skip - ci.yml: wire docs/i18n/code path filters; ESLint JSON artifact for quality-gate; drop advisory typecheck:noimplicit; float actions/cache@v6 - TIA parity: memory/usage/combo/serial; **/*.test.mjs any depth; electron/bin no longer force unit __RUN_ALL__ - check:complexity-ratchets: one ESLint walk, ruleId-isolated baselines + cache - check:api-docs-refs + lib/apiRoutes: shared API route inventory - husky pre-push: intentionally light (gates live in pre-commit); CLAUDE.md + QUALITY_GATES.md docs synced - collect-metrics / lint:json: path.resolve cache path; Windows-safe eslint bin - env-doc allowlist for ESLINT_RESULTS_JSON / COMPLEXITY_ESLINT_REPORT - release-green --full-ci expects check:api-docs-refs (not docs-symbols alone) Tests: select-impacted, classify-pr-changes, api-routes lib, complexity-rule-count, validate-release-green. Reconciled after #6781 (fast-unit 2→4 shards) per maintainer request on #6716. Co-authored-by: Diego Rodrigues de Sa e Souza <8016841+diegosouzapw@users.noreply.github.com>
2026-08-01 21:02:12 +03:00 · 2026-07-11 20:03:11 +09:00
parent 2263377530
commit d1d75fdbf4
31 changed files with 1196 additions and 333 deletions
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -38,12 +38,17 @@ jobs:
        with:
          persist-credentials: false
          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
      - 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: |
+          # Single source of truth: scripts/quality/classify-pr-changes.mjs
+          # (unit-tested). Push/dispatch always enable every lane.
          if [ "$EVENT_NAME" != "pull_request" ]; then
            {
              echo "code=true"
@@ -54,51 +59,18 @@ jobs:
            exit 0
          fi

-          code=false
-          docs=false
-          i18n=false
-          workflow=false
-
          git diff --name-only "$BASE_SHA" "$HEAD_SHA" > changed-files.txt
-
-          while IFS= read -r file; do
-            case "$file" in
-              .github/workflows/*|.zizmor.yml)
-                workflow=true
-                code=true
-                ;;
-              docs/*|*.md)
-                docs=true
-                ;;
-              src/i18n/*|src/i18n/messages/*|scripts/i18n/*|config/i18n.json)
-                i18n=true
-                code=true
-                ;;
-              src/*|open-sse/*|bin/*|electron/*|tests/*|scripts/*|package.json|package-lock.json|tsconfig*.json|next.config.*|vitest*.config.*|playwright.config.*)
-                code=true
-                ;;
-              db/*|config/*)
-                code=true
-                ;;
-              *)
-                code=true
-                ;;
-            esac
-          done < changed-files.txt
-
-          {
-            echo "code=$code"
-            echo "docs=$docs"
-            echo "i18n=$i18n"
-            echo "workflow=$workflow"
-          } >> "$GITHUB_OUTPUT"
+          node scripts/quality/classify-pr-changes.mjs changed-files.txt >> "$GITHUB_OUTPUT"

  lint:
    name: Lint
    runs-on: ubuntu-latest
+    needs: changes
    # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
    # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    # Path filter: pure docs / pure message-catalog PRs skip the code lint bag + typecheck.
+    # Existence reason of this job is code regression; docs/i18n have dedicated jobs.
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.code == 'true') }}
    env:
      # tsx gates below (known-symbols, route-guard-membership) import modules that
      # open SQLite on load; provide DB env so a fresh CI DB initializes cleanly.
@@ -116,7 +88,27 @@ jobs:
      - uses: ./.github/actions/npm-ci-retry
      - run: npm run check:node-runtime
      - run: npm run audit:deps
-      - run: npm run lint
+      - name: Restore ESLint file cache
+        uses: actions/cache@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') }}
+          restore-keys: |
+            eslint-${{ runner.os }}-
+      # Single ESLint inventory (JSON) — quality-gate reuses the artifact instead of
+      # a second cold full-tree pass for eslintWarnings ratchet counts.
+      - name: ESLint (JSON report)
+        run: npm run lint:json
+      - name: Upload ESLint results
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: eslint-results
+          path: .artifacts/eslint-results.json
+          if-no-files-found: warn
+          retention-days: 7
      - run: npm run check:cycles
      - run: npm run check:route-validation:t06
      - run: npm run check:any-budget:t11
@@ -137,16 +129,16 @@ jobs:
      # check:docs-sync is run by the docs-sync-strict job (via check:docs-all) and the
      # husky pre-commit hook; the standalone copy here was redundant (ROI dedup).
      - run: npm run typecheck:core
-      # typecheck:noimplicit:core is a forward-looking gate (noImplicitAny).
-      # Run informationally for now — many pre-existing call sites still need
-      # explicit annotations; track in a dedicated follow-up.
-      - run: npm run typecheck:noimplicit:core
-        continue-on-error: true
+      # typecheck:noimplicit:core dropped from this job (2026-07 optimize):
+      # it was advisory (continue-on-error) and largely subsumed by the blocking
+      # check:type-coverage ratchet in quality-gate. Local: npm run typecheck:noimplicit:core.

  quality-gate:
    name: Quality Ratchet
    runs-on: ubuntu-latest
-    needs: test-coverage
+    # needs lint so eslint-results artifact is available (same inventory as the
+    # blocking lint step). Allow lint failure so other ratchets still run.
+    needs: [changes, test-coverage, lint]
    # Run even when test-coverage was SKIPPED/FAILED (e.g. a single flaky Coverage
    # Shard breaks the shard→coverage→ratchet chain). The DETERMINISTIC ratchets
    # (eslint / complexity / cognitive-complexity / duplication / codeql) do NOT need
@@ -155,7 +147,8 @@ jobs:
    # release PR #4854, where the drift cascade only surfaced post-merge in #5029).
    # The coverage.* metrics degrade gracefully: the download is continue-on-error and
    # the ratchet runs with --allow-missing, so absent coverage is skipped, not failed.
-    if: ${{ !cancelled() && (github.event_name != 'pull_request' || github.event.pull_request.draft == false) }}
+    # Path filter: code-only — pure docs/i18n PRs have nothing for these ratchets to guard.
+    if: ${{ !cancelled() && (github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.code == 'true' && (needs.lint.result == 'success' || needs.lint.result == 'failure'))) }}
    # security-events: read lets the CodeQL ratchet read open code-scanning alerts
    # via `gh api .../code-scanning/alerts`. contents: read keeps checkout working.
    permissions:
@@ -170,6 +163,15 @@ jobs:
          node-version: ${{ env.CI_NODE_VERSION }}
          cache: npm
      - uses: ./.github/actions/npm-ci-retry
+      - name: Restore ESLint file cache
+        uses: actions/cache@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') }}
+          restore-keys: |
+            eslint-${{ runner.os }}-
      # Coverage mergeada (coverage-summary.json) p/ o ratchet de cobertura.
      # continue-on-error: o artifact pode não existir se a job test-coverage foi
      # SKIPPED (shard flaky). Nesse caso collect-metrics pula coverage.* (ausente sem
@@ -180,6 +182,13 @@ jobs:
        with:
          name: coverage-report
          path: coverage/
+      # Prefer lint job's ESLint JSON (one inventory, two consumers).
+      - name: Download ESLint results
+        continue-on-error: true
+        uses: actions/download-artifact@v8
+        with:
+          name: eslint-results
+          path: .artifacts/
      - run: npm run quality:collect
      # Catraca: falha se qualquer métrica regredir vs quality-baseline.json (commitado).
      # Hoje: contagem de warnings do ESLint. Fase 4 estende com cobertura (lida do
@@ -201,15 +210,13 @@ jobs:
      # para não pesar no caminho crítico do lint.
      - name: Duplication ratchet
        run: npm run check:duplication
-      - name: Complexity ratchet
-        run: npm run check:complexity
-      # Fase 7 INT: dead-code, cognitive-complexity, type-coverage promovidos de
-      # advisory (quality-extended) para BLOQUEANTES aqui. Os 3 leem seus baseline
-      # de quality-baseline.json e saem 1 em regressão.
+      # Complexity + cognitive: one ESLint walk, two independent baselines (by ruleId).
+      - name: Complexity + cognitive ratchets
+        run: npm run check:complexity-ratchets
+      # Fase 7 INT: dead-code, type-coverage promovidos de advisory (quality-extended)
+      # para BLOQUEANTES aqui. cognitive-complexity is folded into the step above.
      - name: Dead-code ratchet (knip)
        run: npm run check:dead-code
-      - name: Cognitive complexity ratchet (sonarjs)
-        run: npm run check:cognitive-complexity
      - name: Type coverage ratchet
        run: npm run check:type-coverage
      - name: Compression budget ratchet (F2.4 / N4)
@@ -247,9 +254,11 @@ jobs:
  quality-extended:
    name: Quality Gates (Extended)
    runs-on: ubuntu-latest
+    needs: changes
    # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
    # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    # Path filter: code-only (scanners/ratchets target production surface).
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.code == 'true') }}
    steps:
      # fetch-depth: 0 — the OpenAPI breaking-change gate (oasdiff) reads the base
      # spec via `git show <base_ref>:docs/openapi.yaml`; a shallow clone
@@ -357,9 +366,11 @@ jobs:
  docs-sync-strict:
    name: Docs Sync (Strict)
    runs-on: ubuntu-latest
+    needs: changes
    # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
    # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    # Run when docs OR code change: API/route code can break doc/OpenAPI contract gates.
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && (needs.changes.outputs.docs == 'true' || needs.changes.outputs.code == 'true')) }}
    steps:
      - uses: actions/checkout@v7
        with:
@@ -379,19 +390,20 @@ jobs:
        run: npm run check:openapi-coverage
      - name: OpenAPI security-tier consistency (advisory)
        run: npm run check:openapi-security-tiers
-      - name: OpenAPI spec paths resolve to real routes (anti-hallucination)
-        run: npm run check:openapi-routes
-      - name: Doc /api refs resolve to real routes (anti-hallucination)
-        run: npm run check:docs-symbols
+      # One FS inventory of src/app/api for both anti-hallucination directions.
+      - name: API docs refs (openapi + prose → routes)
+        run: npm run check:api-docs-refs
      - name: i18n translation drift (warn)
        run: node scripts/i18n/check-translation-drift.mjs --warn

  docs-lint:
    name: Docs Lint (prose — advisory)
    runs-on: ubuntu-latest
+    needs: changes
    # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
    # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    # Prose/markdown only — skip when the PR has no doc surface.
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.docs == 'true') }}
    # Advisory (warning-first): prose/markdown style must not block merges while the
    # existing doc corpus is brought up to style. Promote to blocking once it converges.
    continue-on-error: true
@@ -418,9 +430,11 @@ jobs:
  i18n-ui-coverage:
    name: i18n UI Coverage
    runs-on: ubuntu-latest
+    needs: changes
    # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
    # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    # UI keys move with dashboard code OR message catalogs.
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && (needs.changes.outputs.i18n == 'true' || needs.changes.outputs.code == 'true')) }}
    steps:
      - uses: actions/checkout@v7
        with:
@@ -440,9 +454,11 @@ jobs:
  i18n:
    name: i18n Validation (all languages)
    runs-on: ubuntu-latest
+    needs: changes
    # P3 (plano mestre): a release-PR viva fica DRAFT o ciclo inteiro — jobs pesados pulam
    # drafts (ciclo v3.8.44: 123 runs pesados re-disparados por merges na release, 88 cancelados).
-    if: ${{ github.event_name != 'pull_request' || github.event.pull_request.draft == false }}
+    # Message-catalog / i18n-tooling only — pure code without i18n surface skips this lane.
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.i18n == 'true') }}
    continue-on-error: true
    steps:
      - uses: actions/checkout@v7
@@ -961,7 +977,7 @@ jobs:
      - uses: ./.github/actions/npm-ci-retry
      - run: npm run check:node-runtime
      - name: Cache Playwright browsers
-        uses: actions/cache@v6.1.0
+        uses: actions/cache@v6
        with:
          path: ~/.cache/ms-playwright
          key: playwright-chromium-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
--- a/.github/workflows/nightly-release-green.yml
+++ b/.github/workflows/nightly-release-green.yml
@@ -142,7 +142,7 @@ jobs:

      - name: Upload report artifact
        if: always()
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
        with:
          name: release-green-report
          path: |
--- a/.github/workflows/quality.yml
+++ b/.github/workflows/quality.yml
@@ -21,8 +21,68 @@ env:
  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 }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+      - 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"
+            } >> "$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"
+
+  # 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 && (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@v6
+        with:
+          node-version: ${{ env.CI_NODE_VERSION }}
+          cache: npm
+      - run: npm ci
+      # 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 && 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
@@ -44,12 +104,18 @@ jobs:
          node-version: ${{ env.CI_NODE_VERSION }}
          cache: npm
      - run: npm ci
+      - name: Restore ESLint file cache
+        uses: actions/cache@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') }}
+          restore-keys: |
+            eslint-${{ runner.os }}-
      - run: npm run check:provider-consistency
      - run: npm run check:fetch-targets
-      - run: npm run check:openapi-routes
-      - run: npm run check:docs-symbols
-      - name: Docs accuracy (fabricated-docs + i18n mirrors, strict)
-        run: npm run check:docs-all
+      # docs-all / openapi-routes / docs-symbols live in docs-gates (path-filtered).
      - run: npm run check:deps
      - run: npm run check:file-size
      - run: npm run check:error-helper
@@ -72,25 +138,21 @@ jobs:
      # leaking into the npm tarball (v3.8.36: 6 ops bin/*.sh) per-PR instead of only on
      # the release PR's heavy Package Artifact job.
      - run: npm run check:pack-policy
-      # Complexity + cognitive-complexity ratchets on the fast-path (PR→release) so
-      # cycle drift is rebaselined PER-PR instead of cascading onto the release PR's
-      # Quality Ratchet (v3.8.36: +30 complexity / +15 cognitive surfaced only post-merge).
-      - run: npm run check:complexity
-      - run: npm run check:cognitive-complexity
+      # Complexity + cognitive-complexity: ONE ESLint walk (both baselines still
+      # enforced separately by ruleId). Avoids two cold tree walks on fast-path.
+      - run: npm run check:complexity-ratchets
      - name: Typecheck (core)
        run: npm run typecheck:core
      # TIA: build the impact map at runtime (gitignored, ~21MB) and run only the
-      # unit tests impacted by this PR's changed files. Fail-safe runs the FULL
-      # unit suite on hub/unmapped changes — TIA accelerates, never replaces, the net.
+      # unit tests impacted by this PR's changed files. On hub/unmapped changes the
+      # selector returns __RUN_ALL__ — full-suite authority is the parallel
+      # `fast-unit` 4-shard job (test:unit:ci:shard; was 2-shard, #6781), NOT an
+      # unsharded re-run here. Stacking unsharded test:unit:ci on top of fast-unit
+      # doubled wall time (~16 min extra on ubuntu-latest) without extra coverage.
      #
-      # BLOCKING (flipped 2026-06-17). The pre-existing release unit test-debt that kept
-      # this advisory was cleared: #4030 (16 Zod/registry reds, lossless restore) and
-      # #4063 (the last red — the LiveWS boot test — root-caused as a real event-loop
-      # stall in the WS sidecar, fixed + relocated to the integration suite). A full
-      # ci.yml run on release/v3.8.28 then showed all 8 unit shards green, so PR->release
-      # now blocks on unit-test regressions in the impacted set (typecheck:core already
-      # blocked above). Fail-safe still runs the FULL unit suite on hub/unmapped changes.
-      - name: Impacted unit tests (TIA, fail-safe full; blocking)
+      # BLOCKING for the *impacted subset* (flipped 2026-06-17). Fail-safe full
+      # coverage remains required via `Unit Tests fast-path` (fast-unit).
+      - name: Impacted unit tests (TIA subset; blocking)
        env:
          GITHUB_BASE_REF: ${{ github.base_ref }}
        run: |
@@ -104,7 +166,9 @@ jobs:
          # 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 "Fail-safe: running FULL unit suite (CI concurrency)"; npm run test:unit:ci; exit $?
+            echo "Fail-safe: __RUN_ALL__ — deferring FULL unit suite to fast-unit (4-shard)."
+            echo "Not re-running unsharded test:unit:ci here (duplicate of fast-unit coverage)."
+            exit 0
          fi
          echo "Running impacted tests:"; echo "$SEL"
          mapfile -t FILES <<< "$SEL"
@@ -131,6 +195,8 @@ jobs:

  fast-vitest:
    name: Vitest (fast-path)
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.code == 'true') }}
    # Dynamic runner — see fast-gates (own-origin + flag; fork/unset → ubuntu-latest).
    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-latest' }}
    env:
@@ -150,11 +216,13 @@ jobs:

  fast-unit:
    name: Unit Tests fast-path (${{ matrix.shard }}/4)
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.code == 'true') }}
    # Dynamic runner — see fast-gates (own-origin + flag; fork/unset → ubuntu-latest).
-    # This is the heaviest fast-path job; 4-way sharding (was 2) halves the critical
-    # path again (~8.5min → ~4.5min on ubuntu-latest; ~2min on the 8-slot runner box).
-    # Node's native --test-shard=N/total takes any denominator — only this matrix and
-    # the TEST_SHARD env below encode the shard count.
+    # This is the heaviest fast-path job; 4-way sharding (was 2, #6781) halves the
+    # critical path again (~8.5min → ~4.5min on ubuntu-latest; ~2min on the 8-slot
+    # runner box). Node's native --test-shard=N/total takes any denominator — only
+    # this matrix and the TEST_SHARD env below encode the shard count.
    runs-on: ${{ (vars.USE_VPS_RUNNER == 'true' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository)) && fromJSON('["self-hosted","omni-release"]') || 'ubuntu-latest' }}
    strategy:
      fail-fast: false
@@ -194,6 +262,8 @@ jobs:
  # contribuidor NUNCA é bloqueado nem cobrado).
  lint-guard:
    name: No new ESLint warnings
+    needs: changes
+    if: ${{ github.event_name != 'pull_request' || (github.event.pull_request.draft == false && needs.changes.outputs.code == 'true') }}
    runs-on: ubuntu-latest
    continue-on-error: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true }}
    steps:
@@ -205,8 +275,18 @@ jobs:
          node-version: ${{ env.CI_NODE_VERSION }}
          cache: npm
      - run: npm ci
+      - name: Restore ESLint file cache
+        uses: actions/cache@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') }}
+          restore-keys: |
+            eslint-${{ runner.os }}-
      - name: ESLint (baseline congelado — warning novo = vermelho)
-        run: npx eslint . --suppressions-location config/quality/eslint-suppressions.json --max-warnings 0
+        # lint:json writes the report; --max-warnings 0 keeps no-new-warnings policy.
+        run: npm run lint:json -- --max-warnings 0

  # 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
@@ -221,6 +301,8 @@ jobs:
  # nunca é bloqueado.
  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 }}
    runs-on: ubuntu-latest
    continue-on-error: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.fork == true }}
    env: