Bra1nZ/evidence-first-docs

Documentação Orientada a Evidências

A documentação não é uma história sobre o sistema. É um livro-razão de alegações: cada afirmação material deve ser rastreável até um mecanismo e a evidências, com os limites declarados no mesmo local da alegação.

Uma frase confiante é barata. O trabalho é fazer com que o leitor seja capaz de dizer o que foi provado, o que foi testado, o que foi apenas revisado e o que permanece em aberto.

A regra central

Cada alegação material carrega quatro coisas:

1. Mecanismo — o que no sistema deve fazer a alegação ser verdadeira.
2. Evidência — o artefato de prova: prova, modelo, teste, relatório de análise, rastreamento, benchmark ou registro de revisão.
3. Escopo — onde a alegação se aplica e o que está fora do limite de confiança.
4. Status — o rótulo honesto mais forte que a evidência suporta.

Se um dos quatro estiver faltando, a alegação não está pronta. Reescreva-a como uma intenção de design, um plano ou uma pergunta em aberto — não a apresente como um resultado.

Livro-razão de alegações

Mantenha uma tabela, no documento ou em um arquivo de evidências vinculado:

ID	Alegação	Mecanismo	Evidência	Escopo / TCB	Status	Limitações	Última verificação
C-01	Apenas a função X pode escrever na tabela T	Verificação de permissão + política de banco de dados	Testes negativos T-04..T-11	PostgreSQL 14–17; função Y, sessão sem função	testado	Superusuário e DBA estão fora do modelo de ameaça	2026-11-02

Regras:

• Uma linha por alegação, não uma linha por documento.
• As alegações devem ser falseáveis. "O sistema é seguro" não é uma alegação; "a função Y não pode escrever em T por nenhum ponto de entrada suportado" é.
• Vincule o artefato, não apenas o nome da ferramenta. "SARIF" é um formato; o caminho do relatório e o conjunto de regras revisado são evidência.
• Atualize Última verificação quando o artefato for executado novamente; evidência desatualizada é uma constatação, não uma formalidade.
• Mantenha resultados negativos. "Tentamos quebrar e falhamos por causa de X" é evidência; ocultá-lo produz uma falsa sensação de cobertura.

Escada de status

Use o rótulo mais forte que a evidência suporta, nunca um mais forte:

Status	Significado
provado	Prova verificada por máquina da propriedade declarada, com suposições e TCB declarados
verificado-por-modelo	Exploração exaustiva ou limitada de um modelo; declare o limite e a lacuna modelo-código
testado	Testes executados que tentam a violação, com ambiente e resultado registrados
refinamento-estático	Análise estática ou verificação de refinamento; declare ferramenta, regras e achados não resolvidos
revisado	Apenas revisão humana; nenhuma evidência executável ou formal
aberto	A alegação existe, mas a evidência não; é um risco, não um resultado

Um status inferior não é uma falha. Um status inflado é.

Não escreva verificado, provado, correto, seguro, livre de perigos, completo, garantido, certificado ou em conformidade sem um status e escopo adjacentes. Se a palavra sobreviveria sem a evidência, exclua a palavra.

Força da evidência

Prefira evidências que podem falhar pelo motivo certo:

1. Prova formal da propriedade declarada sob suposições explícitas.
2. Verificação exaustiva de modelo dentro de um limite declarado.
3. Testes baseados em propriedades ou fuzzing com corpus e oráculo registrados.
4. Testes negativos direcionados que falham quando o mecanismo é removido.
5. Análise estática com conjunto de regras revisado e achados triados.
6. Revisão de código com revisores nomeados e uma lista de verificação.
7. Afirmação ou anedota.

A hierarquia não é absoluta: um teste direcionado pode ser mais forte do que uma prova mal aplicada. Combine a evidência com a alegação. Uma prova de um modelo que não refina o código não prova o código. Um teste que passa porque a plataforma recusou primeiro não prova sua proteção.

Escopo e limite de confiança

Declare o limite próximo à alegação, não em um apêndice distante:

• Versões e plataformas cobertas.
• Atores privilegiados excluídos: superusuário, DBA, administrador de implantação, gerenciador de segredos, sistema de build, operador.
• Suposições: primitivas criptográficas, relógio, rede, armazenamento, isolamento de inquilino, configuração.
• O que é modelado simbolicamente e o que é executado de verdade.
• O que está fora do escopo e por quê.

Uma alegação não qualificada é uma alegação sobre tudo, o que quase sempre é falso. "Seguro contra a função Y no PostgreSQL 14–17 com a configuração documentada; DBA está fora do modelo" é honesto e útil.

Fluxo de trabalho

1. Inventarie as alegações. Leia o texto e marque cada frase que afirma uma propriedade, resultado, garantia ou status de conformidade.
2. Classifique cada alegação. É uma intenção de design, um requisito, um fato de implementação, um resultado de teste, um resultado formal ou uma alegação de versão?
3. Atribua um ID e um status. Adicione mecanismo, evidência, escopo, limitações e Última verificação.
4. Teste a alegação contra o artefato. Abra o relatório, execute o comando novamente ou peça o artefato ausente. Não aceite um nome de arquivo como evidência.
5. Reescreva alegações não suportadas. Converta-as em "intenção de design", "planejado", "ainda não verificado" ou uma pergunta em aberto. Preserve a ambição; remova a falsa certeza.
6. Verifique os negativos. Para cada alegação de segurança ou correção, nomeie o teste ou análise que tentou violá-la. Se não houver nenhum, marque a alegação aberto.
7. Revise a linguagem. Remova palavras proibidas, quantificadores vagos e absolutos não qualificados. Veja references/banned-words.md.
8. Congele a evidência. Registre o comando, commit, ambiente, data e caminho do artefato para que um revisor possa reproduzir o resultado.
9. Controle a versão. Uma nota de versão pode alegar apenas o que o livro-razão suporta. Liste o risco residual e as alegações em aberto explicitamente.

Lista de verificação de revisão

• Toda alegação material tem um ID, mecanismo, evidência, escopo, status e limitações.
• Toda alegação testado nomeia um teste que pode falhar quando o mecanismo é removido.
• Toda alegação verificado-por-modelo declara o limite e a lacuna modelo-código.
• Toda alegação provado declara suposições e TCB.
• Resultados negativos e falhas conhecidas estão presentes, não filtrados.
• Datas e versões estão atualizadas; evidência desatualizada é marcada como desatualizada.
• Atores privilegiados e caminhos fora do escopo são nomeados.
• Nenhuma palavra proibida aparece sem evidência e escopo adjacentes.
• O README, documento de arquitetura, contrato de API e nota de versão não se contradizem.
• Um leitor pode reproduzir a evidência apenas a partir do documento.

Anti-padrões

1. Presente aspiracional. "O sistema impõe..." quando é um plano.
2. Evidência por nome de arquivo. "Veja report.pdf" sem resultado, escopo ou data.
3. Nome da ferramenta como prova. "Verificado com análise estática" sem regras, achados e triagem.
4. Lavagem de escopo. Um resultado de teste restrito apresentado como uma garantia de todo o produto.
5. Absolutismo do conjunto verde. "Todos os testes passam" sem dizer quais testes, em quais plataformas e o que eles tentaram violar.
6. Representação de conformidade. Um nome de padrão usado como certificado; um mapeamento não é uma auditoria.
7. Limitações enterradas. A ressalva existe, mas está longe da alegação.
8. Certeza desatualizada. Um resultado de um commit antigo apresentado como atual.
9. Nenhuma evidência negativa. Apenas sucessos são documentados; falhas e recusas desaparecem.

Formato de saída

Ao ser solicitado a escrever ou revisar um documento técnico, produza:

1. Um breve resumo de alegações com contagens por status.
2. O livro-razão de alegações (embutido ou vinculado).
3. Alegações em aberto e risco residual, explicitamente separados dos resultados.
4. Escopo e suposições, próximos às alegações que eles restringem.
5. Índice de evidências com caminhos, comandos, datas e versões.

Use references/evidence-template.md para o livro-razão e formato de nota de versão. Use references/banned-words.md antes da publicação. Se o repositório incluir um mapeamento de padrões, ele fica em references/standards-map.md; a habilidade em si não depende de um padrão.

Adapte a saída ao documento. Uma nota de versão curta precisa de uma tabela de alegações compacta e uma seção curta de risco residual, não de um pacote de auditoria completo. Um arquivo de evidências de certificação precisa do livro-razão completo, índice de evidências e escopo. Não confunda minúcia com extensão; cada linha deve conter informações que um leitor precisa.