0013 — O runbook transclui do arquivo-dono

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

Contexto

A 0.20.2 fechou o corolário "o livro não entra no runbook": arquitetura, fluxo, modelo e contratos têm dono no livro, e o runbook os linka. A regra nasceu de um defeito real — um contrato re-digitado longe do dono virou exemplo-que-mente em produção.

Um dev aplicou a regra ao runbook de implantação de um app, e reverteu. Não por preguiça: a versão conforme ficou pior para o uso real dela — mostrar a integração à equipe numa página, sem saltar entre documentos. O feedback que voltou apontou que a regra funde duas coisas: copiar o fato (envelhece — a regra está certa) e o leitor ver o fato na mesma página (não envelhece nada por si só).

O ponto procede, e por um motivo mais forte que o custo ao leitor: a regra contradizia o princípio que deveria implementar. O §1.9 diz que as páginas "linkam ou embutem (pymdownx.snippets), não copiam". O §2 dizia "linka" — mais restritivo que o §1.9, sem dizer por quê. Não era exceção pedida; era bug de constituição.

Decisão

O que muda: o corolário passa a ser "o livro não é re-digitado no runbook". Onde o operador precisa do fato na mesma página, o runbook transclui do arquivo-dono (--8<--) em vez de linkar. Não existe cópia para envelhecer: o fato é incluído no build e muda junto com o dono.

De onde se transclui: do arquivo-dono, nunca "da seção do livro". O livro é narrativa — ele próprio embute os fatos (modelagem.md, mapeamento.md) em vez de possuí-los. Fato que dois documentos precisam mostrar ganha arquivo próprio, no padrão já provado dos snippets do livro (sem frontmatter, headings em ###, exclude_docs:), e livro e runbook embutem o mesmo dono.

Cross-repo continua link. O --8<-- não atravessa repositório, e foi justamente um contrato de fora que virou o exemplo-que-mente. Contrato de terceiro: link ou <PLACEHOLDER>.

O §2 passa a nomear o que FICA no runbook — topologia de operação (com diagrama), superfície, variáveis por servidor, passos/verificação/reversão. Ele só enumerava proibições, e o silêncio custou: na migração revertida, o Mermaid de topologia de operação foi cortado junto, mesmo sendo o que o templates/implantacao.md prescreve. Regra que só diz o que sai é aplicada cortando demais.

Alternativas consideradas

• Manter "linka"; abrir exceção no §1.9. Rejeitada: inverte a hierarquia (o nível passaria a restringir o princípio) e mantém o custo que fez o dev reverter.
• Trocar o eixo para "dono local × dono remoto", como o feedback propôs. Rejeitada: "dono local" sozinho não segura nada — por esse critério o runbook pode transcluir o livro inteiro e virar o livro, e o gênero morre. O que segura é o eixo atual (o runbook escreve o que é de operar) mais transclusão do que o operador precisa na hora. A distinção local × remoto entra onde de fato manda: cross-repo o --8<-- nem funciona.
• Runbook transclui seções do livro (marcadores de seção no index.md). Rejeitada por um achado do caso concreto: no app em questão o livro tem um Mermaid de arquitetura ponta-a-ponta e o runbook, outro de topologia de rede. Não são o mesmo diagrama — a transclusão entregaria ao operador um diagrama autorado para outro leitor. Dois leitores que precisam de diagramas diferentes têm dois fatos, não um fato duplicado.
• Demonstrar o --8<-- vivo no templates/implantacao.md. Rejeitada na prática: o molde é exibido embutido em Templates, e o snippets é pré-processador de linha — o marcador do molde foi processado recursivamente e falhou o build (SnippetMissingError). Deixar ;--8<-- escapado para o autor desescapar seria falha silenciosa (o marcador apareceria como texto na página publicada), que é a classe de defeito que este padrão combate. A receita ficou no cabeçalho do molde, escapada.

Consequências

• Runbook de implantação pode voltar a ser uma página onde o operador precisa disso, sem reintroduzir cópia. O caso que originou o feedback volta a ser atendível — mas pelo arquivo-fato, não copiando o livro.
• Custo novo: quem transclui precisa criar o arquivo-fato antes. Com check_paths: true o build falha ruidosamente (SnippetMissingError) — de propósito.
• Armadilha registrada em Templates: o --8<-- é processado antes do Markdown, inclusive dentro de bloco de código e de comentário HTML. É o que permite as fichas de template desta plataforma funcionarem — e o que transclui sem querer quem documenta a sintaxe descuidadamente.
• Migração oportunista, não campanha: runbook conforme à 0.20.2 (que linka) continua conforme — transcluir é permissão, não obrigação.