0002 — Documentação Completa = livro autorado do estado atual¶

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-06-19 · Decidido em: 2026-06-16

Contexto¶

A Documentação Completa era montada concatenando as seções das etapas (projeto/NN-*.md) num esqueleto arc42 gerado pelo hook. Auditando a doc do piloto bi-transporte-xls, dois furos estruturais apareceram:

Monta deltas, não o estado atual. Concatenar etapas não produz o estado X. Prova dura: a mesma tabela física aparecia sob dois nomes — xls_nuke_replication (1×, etapa antiga) e xls_resetar_powersync (6×, após o rename V14) — porque nenhuma etapa "reconciliava" o rename; o leitor via duas tabelas onde há uma.
Ordem invertida. O livro abria pela conclusão (o Contrato da API), não pela cadeia problema → entrada → dados → processamento → contratos.

Decisão¶

A Documentação Completa (docs/projeto/index.md) passa a ser um esqueleto AUTORADO do estado atual, em ordem lógica (8 capítulos terminando nos contratos públicos), não uma montagem de deltas:

Factual vem de fonte mantida, não re-digitado: o modelo de dados é projeto/modelagem.md (Mermaid erDiagram) autorado e embutido por snippet — obrigatório em projeto com banco e evoluído no mesmo PR que a migration; a API vem do OpenAPI emitido pelo build; o changelog vem do frontmatter das etapas/decisões. Sem gerador reverso de schema no CI (o modelo é design-first).
Narrativa humana é marcada:  (defere ao humano onde a LLM não ancora),  (falha o build até resolver),  (o build injeta de fonte). A LLM redige a prosa que ancora no factual; não inventa.
Etapas e decisões viram o apêndice "changelog" (como chegamos a X), não o corpo do livro.

Consequências¶

O hook visao-tecnica.py virou processador-de-esqueleto (injeta GERADO, preserva HUMANO, falha em RECONCILIAR), não mais gerador do zero.
Novos templates: projeto-index.md (o esqueleto) e modelagem.md.
O central não é app → não autora o livro; o modelo é provado por fixture aqui e pelo piloto bi-transporte-xls (que adotou o livro no estado atual: ER consolidado, contratos no fim, zero RECONCILIAR).
capitulo: perde a função de rotear o livro (o esqueleto manda) — tolerado no-op.

Alternativas consideradas¶

Manter a montagem das etapas (arc42 gerado): estruturalmente incapaz de produzir o estado atual (a tabela sob dois nomes é a prova). Descartada.
Gerador reverso de schema no CI (Flyway-replay/Testcontainers): exigiria Docker/JVM/Postgres no runner de docs — inviável (o ci.yml roda sem daemon Docker) e contra o design (o modelo é autorado design-first). Descartada; o piloto faz o bootstrap do modelagem.md UMA vez, fora do pipeline.