Sobre o projeto

# Catálogo de Falhas Silenciosas (Silent Failure Catalog) Este é um catálogo sistemático de modos de falha em que **a validação parece passar, mas na verdade não verifica nada**. Ele se concentra em problemas de "verde falso" ou "lacunas de validação" em portões de CI, suítes de teste, pipelines de dados e cadeias de ferramentas de agentes de IA. ## Problema central > "Um teste que sempre passa é pior do que nenhum teste. Ele parece ter cobertura, mas na verdade não oferece nenhuma garantia." Falhas se anunciam sozinhas, mas falhas silenciosas não. A página carrega normalmente, o DOI resolve normalmente, o pipeline imprime `PASS` normalmente, o agente reporta progresso normalmente — **nada está vermelho, e nada está certo**. A característica comum dessas falhas é: o sistema carece do sinal de que "algo que deveria ter acontecido não aconteceu". Estados de ausência, vazio, pulo, não contagem e atribuição incorreta acabam sendo apresentados como **sucesso**. ## Estrutura do catálogo Este catálogo contém **14 modos de falha silenciosa nomeados**, divididos em cinco famílias: - **A · Verificação Vazia (Vacuous Verification)**: a verificação é executada, mas não tem poder discriminatório (SF-001 a SF-004) - **B · Ausência Não Contada (Uncounted Absence)**: itens obrigatórios estão ausentes, mas a ausência não conta como falha (SF-005 a SF-007) - **C · Evidência Errada (Wrong Evidence)**: o sinal utilizado não prova a conclusão obtida (SF-008 a SF-010) - **D · Oráculo à Deriva (Drifting Oracle)**: a própria verificação se degrada — isenções, correspondência por substring, atribuição incorreta (SF-011 a SF-012) - **E · Processo e Ambiente (Process & Environment)**: a falha existe fora da lógica — artefatos obsoletos, processos zumbis (SF-013 a SF-014) Cada entrada segue uma estrutura uniforme de seis partes: **Sintoma → Por que é silenciosa → Reprodução mínima → Autoteste → Correção → Relacionados**. ## Causa raiz comum Todas as famílias são essencialmente o mesmo defeito manifestado em níveis diferentes: > **Tratar "ausência de evidência" como "evidência de ausência de problema".** Disso derivam duas regras mais práticas: 1. **A ausência deve entrar no código de saída** — se o "deveria existir mas não existe" for registrado apenas como log, marcador neutro ou pulo, ele sempre produzirá `exit 0`, e o portão ficará cego exatamente onde mais importa. 2. **Sem controle negativo não há evidência** — uma verificação que nunca foi observada falhando não foi provada capaz de falhar. Toda conclusão negativa precisa de um controle positivo. ## Início rápido ```bash git clone https://github.com/zhaoxinghua09-cell/silent-failure-catalog.git cd silent-failure-catalog # Verifique os portões/validadores/scripts de auditoria em que você confia python tools/gate-lint.py path/to/your_gate.py # Valide a consistência interna do próprio catálogo python tools/check-catalog.py ``` Ambos os scripts são implementados com **biblioteca padrão pura** — sem instalação, sem necessidade de rede, Python 3.9+ é suficiente. ## Verificador integrado (gate-lint.py) Esta ferramenta pode escanear seus próprios scripts de portão e identificar esses modos de falha silenciosa, por exemplo: - `SFL-001 no-nonzero-exit`: nenhum `exit()`/`raise`/`assert` no arquivo, impossível falhar - `SFL-002 swallow-exception`: bloco `except` apenas executa `pass` - `SFL-003 unchecked-empty`: valores vazios/falsos são tratados como normais - `SFL-004 counter-does-not-gate-exit`: o contador nunca afeta o código de saída - `SFL-005 zero-item-pass`: chama o executor de testes mas nunca se protege contra "coleta de 0 itens" - `SFL-006 no-negative-control`: nenhuma amostra de controle negativo encontrada, impossível provar que a verificação pode falhar Descobertas de baixa severidade são **explicitamente marcadas como rebaixadas na saída**, em vez de descartadas silenciosamente — porque descarte silencioso é exatamente a falha documentada neste catálogo. Use `--strict` para elevar descobertas de baixo nível a saída diferente de zero. ## Integridade do conteúdo `INTEGRITY.md` e `manifest.sha256` registram resumos SHA-256 para cada arquivo e fornecem um resumo agregado, para que os leitores possam confirmar que possuem exatamente os mesmos bytes descritos nesta página. `tools/make-manifest.py --check` retorna código de saída 1 em qualquer desvio. O CI exige a regeneração do manifesto ao modificar arquivos de conteúdo e corrompe deliberadamente um byte para verificar que a verificação realmente pode falhar. ## Contribuição Novas entradas são bem-vindas quando você puder fornecer **reprodução** e **controle negativo** — apenas relatos de incidentes não são suficientes, pois não podem ser verificados mecanicamente. ## Licença Este repositório adota licenciamento em camadas: **código sob MIT**, **conteúdo com todos os direitos reservados** (citação permitida com atribuição).