Documentação
A tese em uma linha: regra em markdown tem cumprimento perto de zero, regra em CI tem cem por cento. O que segue é o que sustenta essa frase.
O problema, medido
Numa forense de 161 commits em seis repositórios, os três sem CI eram exatamente os três com o lint quebrado naquele momento. O repositório com mais documento de governança — AGENTS.md com regras rígidas, SECURITY.md, GOVERNANCE.md, CONTRIBUTING.md — tinha 35 erros de lint e um script de verificação que nada nunca executava.
- Repositórios sem CI: 3 de 6
- Os mesmos 3 com lint quebrado agora
- Commits com coautoria de IA: 41 de 161
- Repositório com mais governança: 35 erros de lint
Se uma regra pode descer de nível, ela deve descer
Os níveis vão de N0 a N7. N0 é o compilador, N1 a análise estática, N4 o CI, N5 o hook. Acima de N5 é máquina; abaixo é pedido. Toda regra que mora em pedido e caberia numa máquina é dívida, e a conta é medível: cem linhas de regra sempre presente, em trinta sessões por semana durante um ano, passam de dois milhões de tokens.
- N0 compilador — falha como "não compila"
- N1 análise estática — "não passa no lint"
- N4 CI — "não entra na principal"
- N5 hook — "a ação não acontece"
- N6 instrução para IA — depende de ler e obedecer
Toda regra nasce com dois casos
Cada regra tem um repositório em miniatura que ela reprova e outro que ela aprova, montados num diretório temporário com git próprio. Nunca se escreve no repositório vivo. O lado que aprova carrega de propósito os falsos positivos previstos: o exemplo dentro de comentário, o arquivo de exemplo que é o conserto e não a falha, o pré-hash legítimo ao lado do bcrypt.
- Ler só o código de saída não bastava: passou e não se aplica saem os dois como zero
- Afrouxar a regra tem de pintar o lado que aprova de vermelho na primeira rodada
- Par impossível de montar é regra que não entra
O que não vira regra, e por quê
Oito classes de falha ficaram de fora por honestidade: nelas, duas árvores idênticas no disco têm veredito oposto. Rate limit mora no Cloudflare, autorização mora numa policy, RLS pode estar ligada pelo painel. Cada uma virou pergunta escrita, respondida com caminho de arquivo, em vez de placar inventado.
- IDOR e autorização por objeto
- Rate limit e força bruta
- IP tratado como identidade
- RLS ligada fora do repositório
Códigos de saída
O 127 domina o 1, e isso não é detalhe: não se acusa um repositório com uma régua que quebrou. Uma exceção dentro de uma regra é defeito da ferramenta e nunca entra na nota do alvo.
- 0 — tudo que se aplica passou
- 1 — reprovou, violação real
- 2 — alvo inválido ou invocação errada
- 127 — quebrou, defeito da ferramenta
O que ainda não está provado
O rebar impõe em dois repositórios. Uma regra continua só avisando porque perto de doze por cento do que ela acusa é ruído de vocabulário de interface. E a lição mais cara da árvore: o portão ficou verde por seis commits enquanto o gerador estava morto, porque nenhum passo gerava um projeto. A cobertura estava toda no ferramental e nenhuma no que se entrega.
- O gerador ganhou passo próprio depois disso, provado por mutação
- O varredor de segredo não tinha prova nenhuma até uma auditoria externa achar um vazamento em UTF-16