# ADR-023 — Qualidade no nível máximo, com ratchet

| Campo | Valor |
|---|---|
| **Status** | Substituído parcialmente por **ADR-038** (cobertura) e **ADR-040** (baseline/relaxamento) |
| **Data** | 2026-10-14 |
| **Plano de origem** | `wiki/plan/01-analise-e-decisoes.md` |
| **Relacionadas** | ADR-013, ADR-001 |

## Contexto

O `cms/` tinha inconsistência: as specs citavam PHPStan **L9**, mas o `phpstan.neon` estava em
**L7** — ambiguidade que gera erosão. O `prefeituras_v5` mostra o custo de não ter análise
estática. É preciso um alvo **inequívoco** e um caminho de adoção sem travar o início.

## Decisão

- **PHPStan + Larastan no nível máximo** (`level: max`) + `phpstan-strict-rules` +
  `phpstan-deprecation-rules`.
- **Baseline commitado que só encolhe** (ratchet): nenhum erro novo; cada ciclo reduz entradas.
- **PHPUnit estrito** (`failOnWarning/Notice/Risky/Deprecation/Empty`) e cobertura por camada
  (core ≥90%, services ≥85%, layout ≥80%, modules ≥75%).
- **Pint** (PHP) e **Prettier + ESLint** (JS/TS) obrigatórios.
- **Gate de fronteiras** (`tools/arch-check`) que quebra o build.

## Justificativa (alternativas descartadas)

- **Nível 5/7** — descartada: ambíguo e permissivo; o custo migra para produção.
- **Sem baseline** — descartada: travaria o início do projeto.
- **Baseline que cresce** — descartada: vira dívida permanente.

## Consequências

**Positivas**
- Padrão correto é o caminho de menor resistência; feedback em um comando (`make check`).

**Custos / negativas**
- Nível máximo exige `@var`/tipos em pontos de fronteira (Laravel dinâmico).
- Falsos positivos do Larastan exigem `ignoreErrors` justificado por entrada.

## Exemplo mínimo (comparativo)

```neon
# ❌ Ambíguo (specs diziam L9, arquivo tinha L7)
parameters: { level: 7 }

# ✅ Nível máximo + ratchet
parameters:
  level: max
  treatPhpDocTypesAsCertain: true
  reportUnmatchedIgnoredErrors: true
```

## Verificação

- `make check` verde no esqueleto; baseline encolhe ≥1 entrada no primeiro ciclo.
- `tools/arch-check` falha no fixture inválido.

## Referências

- `wiki/plan/05-qualidade-phpstan-max.md`.