Release v3.8.37

.env.example

@@ -378,6 +378,12 @@ NEXT_PUBLIC_CLOUD_URL=
 #OMNIROUTE_KIE_CALLBACK_URL=
 #OMNIROUTE_PUBLIC_URL=
 
+# Headroom token-saver proxy URL. The dashboard lifecycle (api/headroom/*) spawns
+# a local headroom-ai CLI on loopback by default; override only to point at an
+# external Docker sidecar proxy. Defaults to http://localhost:8787 when unset.
+# Used by: src/lib/headroom/detect.ts.
+#HEADROOM_URL=http://localhost:8787
+
 # Upstream quota endpoints used by the Usage page. Override only for
 # debugging or when routing through a corporate mirror. Used by:
 # open-sse/services/usage.ts.

.github/workflows/ci.yml

@@ -140,7 +140,15 @@ jobs:
     name: Quality Ratchet
     runs-on: ubuntu-latest
     needs: test-coverage
-    if: ${{ !cancelled() && needs.test-coverage.result == 'success' }}
+    # 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
+    # the coverage artifact and MUST still run so cycle drift is measured on the
+    # release PR — otherwise a flake silently skips the whole gate (incident: v3.8.36
+    # 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() }}
     # security-events: read lets the CodeQL ratchet read open code-scanning alerts
     # via `gh api .../code-scanning/alerts`. contents: read keeps checkout working.
     permissions:
@@ -156,16 +164,23 @@ jobs:
           cache: npm
       - uses: ./.github/actions/npm-ci-retry
       # 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
+      # erro) e o ratchet roda com --allow-missing — as métricas determinísticas
+      # (eslint/complexity/cognitive) seguem BLOQUEANTES.
       - uses: actions/download-artifact@v8
+        continue-on-error: true
         with:
           name: coverage-report
           path: coverage/
       - 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
       # coverage mergeado). Tamanho de arquivo e duplicação têm gates dedicados.
+      # --allow-missing: pula métricas do baseline ausentes do collect (coverage.* quando
+      # o artifact não veio) em vez de falhar — mantém os gates determinísticos ativos.
       - name: Ratchet check
-        run: node scripts/quality/check-quality-ratchet.mjs --summary .artifacts/quality-ratchet.md
+        run: node scripts/quality/check-quality-ratchet.mjs --allow-missing --summary .artifacts/quality-ratchet.md
       # Fase 6A.5: require-tighten — BLOQUEANTE (promovido de advisory no fim do ciclo
       # v3.8.27). Falha quando uma métrica MELHOROU sem o baseline ter sido apertado no
       # mesmo PR (força capturar ganhos permanentes). As métricas coverage.* carregam
@@ -174,7 +189,7 @@ jobs:
       # mergeada == baseline (ver a nota _require_tighten_flip_blocking em
       # config/quality/quality-baseline.json).
       - name: Require-tighten (blocking)
-        run: node scripts/quality/check-quality-ratchet.mjs --require-tighten
+        run: node scripts/quality/check-quality-ratchet.mjs --allow-missing --require-tighten
       # Catraca de duplicação (jscpd@4 sobre src+open-sse). Roda neste job (paralelo)
       # para não pesar no caminho crítico do lint.
       - name: Duplication ratchet

.github/workflows/quality.yml

@@ -53,6 +53,18 @@ jobs:
       - run: npm run check:test-discovery
       - run: npm run check:test-runner-api
       - run: npm run check:any-budget:t11
+      # Build-scope guard: fails if worktrees/cruft leak into the tsconfig include
+      # scope (would OOM `next build`). Instant. See incident 2026-06-25 / #5031.
+      - run: npm run check:build-scope
+      # Pack-policy (unexpected-files allowlist) WITHOUT a build — catches a stray file
+      # 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
       - name: Typecheck (core)
         run: npm run typecheck:core
       # TIA: build the impact map at runtime (gitignored, ~21MB) and run only the

.gitignore

@@ -161,6 +161,8 @@ typescript
 
 # Superpowers plans/specs (internal tooling, not project code)
 docs/superpowers/
+# Superpowers visual-companion brainstorm mockups (ephemeral)
+.superpowers/
 
 # TIA test-impact map — generated at runtime in CI (build-test-impact-map.mjs), never committed (~21MB)
 config/quality/test-impact-map.json