ADR-0037: Simplificar infraestrutura de qualidade para solo dev + LLM

Status: accepted
Date: 2026-08-10
Supersedes: none
Amended by: ADR-0046 — the docs/en mirror and the check-i18n.sh drift gate were removed, so the i18n guardrail this ADR chose to keep no longer exists

Context

Um audit de overengineering (2026-08-10) avaliou toda a infraestrutura de qualidade do repositório — quality gates, scripts, documentação, specs, ADRs — contra o perfil real do projeto: 1 desenvolvedor + LLM fazendo 100% do coding.

O resultado: várias estruturas foram dimensionadas para um time de 5-8 pessoas com compliance regulatório (DSL de pipeline declarativa, baseline store com audit trail, RTM formal, spec lifecycle manager com gráficos Unicode, barreira de drift i18n com tolerância de 1 commit). O time real não justifica esse overhead de manutenção.

Porém, parte dessa infraestrutura tem valor real para LLM:

• gates.registry → LLM lê 1 arquivo e descobre todos os gates, seus escopos, e se são blocking ou advisory
• schema-sql-lint.sh → LLMs alucinam nomes de coluna SQL; este linter pega antes do CI
• check-i18n.sh blocking → sem CI vermelho, o LLM nunca lembra de atualizar docs em inglês
• doc-audit.sh route count → quando o LLM adiciona/remove rotas, o README fica stale

Remover tudo indiscriminadamente pioraria a experiência de desenvolvimento assistido por IA.

Decision

Aplicar um refactor seletivo seguindo esta matriz:

Área	Decisão	Justificativa
gates.sh runner (414 linhas) + test-gates.sh (15KB)	Remover	Substituir por script linear de ~40 linhas
gates.registry (71 linhas)	Manter como documentação	LLM lê 1 arquivo e entende todos os gates
baselines.sh CLI (122 linhas)	Remover	CRUD com audit trail para 4 números
baselines.registry (33 linhas)	Substituir por scripts/thresholds.sh	Centralização sem overhead
schema-sql-lint.sh	Manter	LLM alucina nomes de coluna
check-i18n.sh drift blocking	Manter blocking, tolerância de 5 commits de atraso do pin (drift só bloqueia quando o pin está mais de 5 commits atrás do commit atual da raiz — ou seja, a partir do 6º commit; antes disso é não-bloqueante)	Sem CI vermelho, LLM esquece docs em inglês
RTM (generate-rtm.ts + generate-rtm-from-code.sh + ci-validate-rtm.sh)	Remover	Zero valor para LLM
doc-audit.sh semântico	Simplificar: manter só route count vs README	Útil como guardrail; resto é ruído
check-doc-staleness.sh	30→90 dias	30 dias é ansioso demais
spec-status.sh bar charts/JSON	Simplificar: só listagem	LLM não precisa de gráficos Unicode
Specs implementados	Arquivar	Menos ruído no contexto do LLM
ADRs >6 meses consolidados	Arquivar	Menos tokens para chegar nas decisões relevantes

O que NÃO muda

• Semgrep — relevante para LGPD e dados sensíveis
• DESIGN.md — referência compartilhada para humano e LLM
• Event sourcing no workers/ — decisão arquitetural mantida (robustez para expansão futura)
• Estrutura de pacotes — requer pesquisa separada sobre viabilidade do collapse
• Scripts de deploy e segurança — deploy.sh, deploy-docs.sh, pre-deploy-check.sh, secret-scan.sh, validate-csp.sh, generate-headers.ts, sign-license.ts

Consequences

Positivas

• Menos arquivos para manter (7 removidos, 2 criados, 13 modificados)
• Menos superfície para bugs em meta-scripts (gates.sh, baselines.sh)
• ~89 specs arquivados (2026-07-28) → contexto mais limpo para LLM
• Guardrails que o LLM realmente precisa (schema-sql-lint, i18n blocking, route count) permanecem
• gates.registry continua como single source of truth documental

Negativas

• CI jobs perdem a garantia formal de que cobrem todos os gates (o gates.sh verify era uma meta-gate). A mitigação é que o gates.registry permanece como documentação — o desenvolvedor consulta ao modificar CI.
• Baseline store perde audit trail de quem mudou threshold e por quê. Mitigação: git blame no thresholds.sh resolve.

Riscos

• Se o time crescer para 3+ pessoas, a registry declarativa pode fazer falta. A reintrodução é barata: o gates.registry continua existindo como documentação, só o runner foi simplificado.

References

• Spec: .specs/features/big-fat-refactor-02/spec.md
• Audit de overengineering: sessão 2026-08-10