Pular para conteúdo

0036 — Constituição 2.0.0: norma e kit à parte, perfis de repo, núcleo com âncora fixa

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-09-12 · Decidido em: 2026-09-12

Contexto

A constituição 1.5.0 não tinha falta de regra; faltava um dono para cada regra. O núcleo tinha 1.134 linhas, o java-micronaut.md 2.225, e o mesmo fato aparecia em três a cinco lugares que já divergiam entre si (o contrato do /health, os segredos de CI, as permissões do settings.json). O texto normativo carregava relatos de caso, datas, números de item de backlog e emendas empilhadas, sete delas escondidas em comentário HTML que o site não mostra. Afirmava como vigente o que já tinha saído (o Coolify buildando, a ponte SSH, o build-deploy.yml, o canário) e contradizia decisões do dono em vários pontos.

E toda mudança de template ou script bumpava a versão da constituição: 115 releases, um CHANGELOG de milhares de linhas e a frota inteira "defasada" por causa de um comentário de template — o aviso de defasagem deixou de dizer alguma coisa.

Decisão

A constituição passa à 2.0.0 numa release só, reestruturada em torno de um dono por regra.

  • Norma e kit versionados à parte. O número da norma (versao: da constituição) sobe só quando a norma muda; o do kit mora num arquivo KIT na raiz, carimba o mudou_em de cada artefato do manifesto e é publicado em kit-versao.txt. O app.json registra os dois. O site segue com o VERSION. Três números, três perguntas: o que exige ler e migrar, o que re-derivar, e qual release do portal.
  • Perfis de repo (perfil: app, config, lib). O manifesto diz, por artefato, os perfis e as stacks a que ele se aplica; a /xadm-docs filtra pelo dado. As stacks PowerSync e o xadm-commons deixam de viver de exceção espalhada pela prosa.
  • Núcleo curto, headings sem número e com âncora fixa. O núcleo fica com princípios e pisos, até três frases por regra e um link para a norma derivada dona; orçamento de 500 linhas. Seção se cita pelo nome, com link para a âncora (#convencoes, #definicao-de-pronto), nunca por número.
  • Redação com gate. Norma no presente, sem caso, data, número de spec ou de item de backlog, nem versão de release; "legado" proibido sem exceção — o termo técnico ganha nome. O checa-redacao.py cobra no núcleo, nas normas derivadas, nas páginas satélite e nos templates do kit, que afirmam o que a norma diz e eram onde o texto envelhecia sem ninguém cobrar.
  • ADR é retrato. Decisão aprovada muda só por obsoleto + superado-por ou por > **Correção …:** visível para fato incidental; decisão nova é ADR nova com supersede. O validador avisa quando uma ADR aprovada carrega bloco de "Emenda" ou "Evolução".
  • Dado que muda por fora vem de arquivo, não de prosa. Os pisos das libs moram no pisos-libs.json, lido pelas guardas e pelas skills e renderizado na página por hook.
  • Regra nova sai como erro já. O validador e os scripts publicados passam a reprovar o repo não migrado no primeiro push depois do deploy do central, sem fase de aviso nem gating por versão declarada; o custo é declarado na nota de migração.
  • Deploy só com gate verde. O pipeline não tem caminho que deploye com o gate pulado; emergência é consertar o teste ou reverter à mão para a tag imutável.

Alternativas descartadas

  • Soltar os defeitos de pipeline antes, em PATCH 1.5.x, e a reestruturação depois. Duas migrações para cada repo em sequência, com a norma pela metade publicada no meio.
  • Manter a numeração das seções (ou numerar com âncora ao lado). O número é o que envelhece: qualquer seção nova renumera as seguintes e quebra toda citação §N espalhada pela frota.
  • Fase de aviso antes do erro, ou reprovar só quem declarou a versão nova. Aviso que dura uma release é ignorado pela frota inteira, e o gating por versão declarada deixaria o repo parado na 1.x sem cobrança nenhuma.
  • Caminho de emergência que deploya sem testes (sem_testes=true no disparo manual). É a porta que fica aberta depois da emergência; reverter para a tag imutável resolve o mesmo caso sem ela.
  • Tabela de pisos escrita à mão na página. Foi a tabela de versões da 0019, que mentiu no mesmo dia em que a página foi editada.

Consequências

  • Todo repo da frota migra — o que cada perfil faz, a tabela das regras que viram erro e o mapa das âncoras antigas estão na nota de migração do CHANGELOG. Os apps com build.targets ficam com o job docs vermelho até migrar.
  • O aviso de defasagem volta a significar algo: norma defasada pede leitura e aprovação; kit defasado se re-deriva sem pergunta.
  • O CLAUDE.md do central vira roteador e o backlog vai para o backlog.md.
  • A 2.0.0 sai inteira na /xadm-release: até lá, nada é pushado, porque o site do central publica no push.
  • Detalhe operável: Versionamento, constituição e as ADRs que esta release criou — 0033, 0034, 0035.