# Princípios do Protocolo de Dossiê

Cada princípio tem: **regra**, **por que existe**, **como verificar**,
**contraexemplo observed**. O contraexemplo vem da execução real do dossiê
do Portal Municipal — são erros que de fato ocorreram e custaram retrabalho.

---

## P1 — O inventário decide o escopo, não a intuição

**Regra.** A lista de módulos sai de um artefato verificável do projeto:
tabela de registro, seed, ou pastas físicas. Rostos que "parecem módulos"
entram na lista **apenas** se houver evidência estrutural (rota + controller +
migration, por exemplo).

**Por quê.** A intuição erra nos dois sentidos: inclui o que não é módulo
(`Gemini` é uma integração, não um módulo de negócio) e perde o que é
(`Transparência Fiscal` não tem tabela própria, mas é um módulo de portal).
O inventário mecânico erra menos e é auditável.

**Como verificar.** `inventario.py` produz a lista; cada item tem um
classificador que registra **por que** ele entrou (rota? controller? pasta?).
A F2 exige que todo diretório de código relevante tenha dono.

**Contraexemplo.** Na primeira execução, "Transparência Fiscal" foi
descrito pelo usuário como módulo com "tabelas de despesas". O inventário
mostrou que o módulo é um **catálogo de links** sobre `contents`, sem tabela
própria. Documentar a premissa errada teria contaminado o dossiê inteiro.

---

## P2 — Toda afirmação é ancorável

**Regra.** Comportamento, rota, coluna ou regra de negócio é citado com
`caminho/arquivo.ext:linha` ou `caminho/arquivo.ext`. O que não foi
verificado é marcado literalmente `[NÃO VERIFICADO]`.

**Por quê.** O leitor do dossiê vai reconstruir o módulo. Um substantivo sem
âncora é opinião; com âncora, é verificável em 10 segundos.

**Como verificar.** `auditar.py` varre todos os `.md` e extrai caminhos
citados; cada um precisa existir no workspace. Caminho inexistente é erro
de documento — a menos que o próprio documento afirme que ele não existe
(daí a checagem de negação no auditor).

**Contraexemplo.** Na primeira execução, um relatório de auditoria acusou
falsos positivos porque o `grep` de caminhos capturava `.../foo.json` como
`.../foo.js` — a ordem das extensões no padrão importa. Passou a ser a
extensão mais longa primeiro, e o padrão virou expressão regular com
alternativa ordenada.

---

## P3 — Crítico se prova em runtime

**Regra.** Um defeito só entra no registro com severidade **crítica** depois
de **executado**: reproduzido no ambiente real, com requisição/consulta
concreta e saída observada. Defeito só lido fica como *suspeito* até ser
provado — e o registro diz qual é o caso.

**Por quê.** Severidade errada distorce o backlog. O caso real: a escalada
de privilégio `BUG-SEC-026` foi registrada como "análise estática" e
depois confirmada em runtime — e a confirmação mudou o texto do bug
(incluindo o fato de que `.create`/`.edit` **não** são liberados, só
`.store`/`.update`/`.destroy`).

**Como verificar.** A F5 tem um caderno de sondas: cada teste deixa registro
de requisição, resposta e estado antes/depois. Defeito crítico sem caderno
não fecha.

**Contraexemplo.** O bug "SQL injection" foi reportado 8 vezes por leitura.
Só 3 dos 8 pontos eram de fato exploráveis publicamente; os outros exigiam
sessão. A distinção só apareceu na execução.

---

## P4 — O workspace volta como estava

**Regra.** Qualquer sonda que toque banco, arquivo ou serviço é revertida
imediatamente, e o estado final é **verificado por contagem** (não por
impressão).

**Por quê.** O dossiê é feito no ambiente de trabalho de outra pessoa. Um
usuário de teste esquecido, um perfil criado, uma tabela com dados de
teste — tudo isso polui o trabalho de quem vem depois, e pode até ser
levado para produção.

**Como verificar.** Antes da sonda, conte; depois, conte de novo. Se
divergiu, corrija e reconte. A F5 §5 traz o roteiro.

**Contraexemplo.** Na execução real, a escalada de privilégio exigiu criar
um usuário, dois perfis e dois vínculos. O cleanup exigiu lidar com
*soft delete* (`users.deleted_at`), que deixa a linha invisível para a
aplicação mas presente no banco — e `role_users` órfão continuava lá.
A verificação por contagem foi o que pegou isso.

---

## P5 — Premissa do enunciado se verifica

**Regra.** Se o pedido de quem contrata a pesquisa afirma algo que o código
contradiz, o dossiê documenta **o que o código faz** e registra a divergência
explicitamente. Não se "adapta" ao enunciado.

**Por quê.** O enunciado vem de quem usa o sistema, não de quem leu o
código. Erros de premissa são comuns e precisa(m) virar dado, não sumir.

**Como verificar.** A F0 registra as premissas do pedido; a F4/F5 verificam
cada uma e o panorama tem uma seção de divergências.

**Contraexemplo.** Três premissas do pedido original estavam erradas:
(1) o módulo `a-cidade` **não** foi renomeado — o seed renomeia a
*categoria* 6 (`a-prefeitura` → `a-instituicao`); (2) "Transparência
Fiscal" não tem tabelas de despesas; (3) `enquetes` não usa
`questions`/`options` — esse motor é do módulo *Revisões*. As três foram
documentadas como divergências, não aceitas.

---

## P6 — O índice é gerado, nunca escrito

**Regra.** `README.md` de qualquer dossiê é emitido por
`gerar-readme.py` a partir dos dossiês + do registro de módulos. Editar à
mão é erro; a próxima geração sobrescreve.

**Por quê.** Índice escrito à mão dessincroniza em silêncio. O gerador é
idempotente e barato (segundos), então não há desculpa.

**Como verificar.** O gerador produz a mesma saída em execuções sucessivas
(idem, com a data excetuada) — e a auditoria checa que o número de arquivos citado bate
com o disco.

---

## P7 — O gate é automático

**Regra.** "O dossiê está pronto" é resposta do `auditar.py`, não
julgamento humano. O que é julgamento humano vai **dentro** do documento
(severidade, risco de negócio, pergunta em aberto), não **sobre** ele.

**Por quê.** Julgamento manual de 66 pastas × 9 arquivos não é confiável
nem repetível. Máquina verifica forma; humano verifica conteúdo.

**Como verificar.** `auditar.py` sai com código != 0 em caso de problema.

**Contraexemplo.** O primeiro auditor acusava `[MAPA v5->v6] ausente` em
módulos que já tinham o mapa — porque ele só olhava o `08-GAPS-E-DIVIDAS.md`
e o mapa estava num `09-`. O gate foi corrigido para varrer todos os
arquivos da pasta.

---

## P8 — O agente recebe fatia auto-contida

**Regra.** Cada agente recebe: **contexto** (objetivo do dossiê inteiro),
**contrato** (o que cada um dos 9 arquivos precisa conter), **alvo** (a pasta
e os arquivos que ele pode ler), **critério de aceite** (observável).
Nenhuma dependência de conversa anterior.

**Por quê.** Agente sem contexto reinventa convenções e produz dossiê
incompatível com o dossiê do vizinho. Sem critério de aceite, produz texto
genérico que passa no gate de forma mas falha no de conteúdo.

**Como verificar.** O `00-RESUMO.md` de cada módulo é autocontido: quem lê
só ele entende o módulo. A auditoria de-placeholder existe porque
"conteúdo vazio" passa em todos os checks mecânicos.

---

## P9 — Documento nasce do código

**Regra.** Bloco de código é **copiado** do repositório. Código inventado
para ilustrar é marcado `// exemplo ilustrativo`. Nomes de arquivo, rota,
coluna ou tabela nunca são inferidos — são `grep`ados.

**Por quê.** Dossiê com SQL inventado é pior que dossiê ausente: reconstrói
schema errado e o erro se propaga para a migration.

**Como verificar.** `auditar.py` confere que todo caminho citado existe —
código colado de arquivo real referencia arquivo real.

---

## P10 — O dossiê serve à reconstrução

**Regra.** Todo documento é avaliado pela pergunta: *"dá para reconstruir
este módulo sem abrir o legado?"*. Se a resposta é não, falta conteúdo.

**Por quê.** Dossiê histórico ("isto foi escrito em 2019") não tem valor
para a v7. Dossiê com **efeito** ("isto publica X no portal Y, sob a
condição Z") tem.

**Como verificar.** O `06-MIGRACAO-MODERNA.md` de cada módulo é a prova:
ele é o teste final de completude. Se não dá para escrever a migration
moderna a partir dele, falta algo no dossiê.

---

## A regra que emerge de todos

> **Mecânica para máquina, julgamento para o documento, execução para o
> crítico, e o workspace sempre como estava.**

Os quatro quadrantes:

| | Mecânica | Julgamento |
|---|---|---|
| **Máquina** | inventário, caminhos, tamanho, placeholder, índice | — |
| **Humano** | — | objetivo, efeito, risco, pergunta de negócio, plano de migração |
| **Execução** | reprodução de defeito, antes/depois, sondas | qual defeito merece ser crítico |
| **Contrato** | 9 arquivos, cobertura mínima | densidade e honestidade do conteúdo |