Templates¶
Templates prontos para copiar ao criar documentação numa aplicação. Os
arquivos-fonte vivem na pasta templates/ do repositório documentacao no
Forgejo — copie o arquivo, renomeie conforme a convenção e substitua o
conteúdo de exemplo.
| Template | Copiar para (no repo da aplicação) |
|---|---|
| Resumo Executivo (home do app) | docs/index.md |
| Documentação Completa (o livro) | docs/projeto/index.md |
| Etapa do projeto | docs/projeto/NN-titulo-curto.md |
| Modelo de dados (banco ou contrato de saída) | docs/projeto/modelagem.md |
| Mapeamento entrada↔dados (opcional) | docs/projeto/mapeamento.md |
| Guia do código (todo app com código) | docs/dev/guia-do-codigo.md |
| Decisão (registro de decisão) | docs/decisoes/NNNN-titulo-curto.md |
| Manual de usuário | docs/public/manual/titulo-da-tarefa.md |
| Runbook de operação (procedimento pontual) | docs/operacao/titulo-da-operacao.md |
| Runbook de implantação (sistema de pé) | docs/operacao/implantacao.md |
| Riscos consolidados (opcional) | docs/riscos.md (raiz de docs/) |
| Página pública da API (OpenAPI) | docs/public/api/index.md |
| mkdocs.yml canônico | mkdocs.yml (raiz do repo) |
| Identidade visual (CSS) | docs/stylesheets/xadm.css |
Workflow de CI/CD (perfil app; a lib tem o seu, local) |
.github/workflows/pipeline.yml de templates/pipeline.yml — gate (com o contrato de release na tag) + docs + build + deploy (com o smoke) à la carte, 3 variantes opt-in por build.targets (0027); o deploy é o job deploy chamando o control-plane (0026) |
Workflow de CI/CD (perfil config, stacks PowerSync) |
.github/workflows/pipeline.yml de templates/pipeline-config.yml — lint das sync rules e do compose, smoke de carga, deploy pelo control-plane com target=compose |
| Pisos das libs da casa | não se copia — pisos-libs.json é lido de https://docs.xadm.biz/toolchain/pisos-libs.json pelas guardas do pipeline.yml e pelas skills /xadm-docs e /xadm-release |
| Metadados do app | docs/app.json |
| Changelog embutido no site | docs/changelog.md |
| Aviso de versão antiga (overrides) | overrides/main.html (de templates/overrides-main.html) |
| READMEs de anexos | docs/anexos/README.md e docs/anexos/privado/README.md |
| Kit de UI (app server-render, opcional) | src/main/jte/kit/layout.jte + src/main/jte/kit/headerRight.jte + public/css/custom-theme.css + public/images/{logo.png,favicon.ico} + o Bootstrap vendorizado (public/css/bootstrap.min.css + public/js/bootstrap.bundle.min.js — servidos pelo app, não por CDN; cabeçalho traz versão, origem e o hash SRI conferido) (de templates/views-jte/** e templates/public/** — a árvore do kit espelha a do app; motor = JTE, 0025). Junto vai o scaffold templates/app.css → public/css/app.css: CSS de componentes do app, copiado uma vez e nunca re-derivado |
| Container (app Java deployável) | Dockerfile + .dockerignore na raiz — server Micronaut native de templates/dockerfile-java-native (default, Dockerfile.native, 0022) ou JVM de templates/dockerfile-java (exceção); .dockerignore de templates/dockerignore-java. App Flutter web: o Dockerfile é receita por app (o fluxo de sourcemap difere), não template — ver Flutter |
| Fim de linha (app Java/Gradle) | .gitattributes na raiz (de templates/gitattributes-java) |
| Fim de linha (app Flutter web) | .gitattributes na raiz (de templates/gitattributes-flutter) |
| Performance do Gradle (app Java/Gradle) | gradle.properties na raiz (de templates/gradle.properties) |
| Checkstyle (app Java) | config/checkstyle/checkstyle.xml + suppressions.xml |
| Lints Dart (app Flutter/Dart) | analysis_options.yaml (raiz do repo) |
| .gitignore (app Flutter) | .gitignore (de templates/gitignore-flutter) |
| Skill /xadm-release | .claude/skills/xadm-release/SKILL.md |
| Skill /xadm-docs | .claude/skills/xadm-docs/SKILL.md |
| Skill /xadm-setup (Central de Apps) | .claude/skills/xadm-setup/SKILL.md |
| Skill /xadm-meta-audit-work | .claude/skills/xadm-meta-audit-work/SKILL.md |
| Skill /xadm-docx (opcional) | .claude/skills/xadm-docx/SKILL.md |
Skills de workflow (x-desenhar … x-documentar) |
diretório templates/x-<nome>/ → .claude/skills/x-<nome>/ |
| Hook de constituição | .claude/checa-constituicao.sh + hook SessionStart no .claude/settings.json |
| Config do agente (allow-list base) | .claude/settings.json (de templates/settings.json) |
| Regras de IA | bloco no topo do CLAUDE.md do repo |
Os marcados com <app> são a configuração canônica de publicação — troque <app>
pelo slug e não copie de outro app (clones divergem do padrão). Ver
como publicar e o checklist de app novo.
O frontmatter é obrigatório — campos e valores válidos estão na constituição.
Resumo Executivo — home do app (docs/index.md)¶
Porta do diretor (Livro, Resumo e nav): problema + solução sem jargão + link para a Documentação
Completa. O marcador <!-- etapas --> vira as listas entregue/planejado no build.
<!--
TEMPLATE — RESUMO EXECUTIVO (a home do app, docs/index.md) — X-Adm
A porta do diretor (constituição, Livro, Resumo e nav): o problema e como se resolve, SEM jargão,
1–2 parágrafos, terminando em "→ Documentação Completa".
O marcador <!-- etapas --> é substituído no build pelas listas "entregue/planejado"
geradas do campo entrega: e do status de cada etapa (projeto/NN-*.md). Apague este
comentário e ajuste o texto.
-->
# BI Transporte — Processador XLS
A Vantroba recebia o faturamento de transporte em planilhas Excel e dependia de um
processo manual para levar esses dados ao BI. Este serviço **recebe a planilha,
valida e publica os dados automaticamente**, com rastreabilidade de cada envio — o
time para de depender de script manual e ganha histórico e segurança.
Para o desenho técnico completo, veja a **[Documentação Completa](projeto/)**.
## O que você encontra aqui
<!-- Mapa das seções (ordem do nav, por ciclo de vida). Apague as linhas das
seções que este app não tem. -->
- **[Documentação Completa](projeto/)** — o sistema inteiro, de cima a baixo (o livro).
- **Operação** — runbooks: como operar, recuperar, fazer deploy.
- **Dev / API** — para quem mexe no código: guia do código e referência da API.
- **Manual** (Público) — passo a passo para o usuário/suporte.
- **Etapas do Projeto** — o que foi entregue em cada etapa (a execução ao longo do tempo).
- **Decisões** — o *porquê* de cada escolha técnica (ADRs).
- **[Glossário](glossario.md)** — o vocabulário do domínio.
## Etapas
<!-- etapas -->
Etapa do projeto (doc de projeto)¶
A etapa é tecnicamente completa para o seu escopo: um dev (ou agente) que nunca viu o código implementa o que ela introduz a partir dela e das etapas que ela referencia (Níveis de documentação).
- Completa por composição, sem repetir. O que outra etapa já desenhou se linka; só se reescreve o que esta etapa altera. Lidas em conjunto, as etapas dão o desenho do sistema — a primeira é a mais cheia, porque define a base.
- Seções que o escopo toca: contexto e escopo (com o que fica fora) · arquitetura (blocos,
camadas, dependências) · modelo de dados · contratos (API: request, response, status e auth, ou
link a
dev/api-rest; formato de arquivo ou integração, como o mapeamento de colunas) · fluxos e máquina de estados · configuração (envs e flags que mudam comportamento) · decisões (o corpo emdecisoes/) · riscos · qualidade e observabilidade. Seção que o escopo não toca, apague. - Modelo de dados é o delta: tabela nova ou alterada, com colunas, tipos, chaves e índices. O
estado consolidado vive no
projeto/modelagem.md, que a etapa atualiza no mesmo PR. Schema grande que muda muito pode ter, além dele, um snapshot vivo emdocs/dev/. - A navalha: completa no nível de desenho e contrato, que são duráveis — não spec linha a linha. O que muda toda semana e a mecânica interna são código (Documentar interfaces, decisões e uso).
---
titulo: "Importação de frota a partir de planilha XLS"
tipo: projeto
status: rascunho
responsavel: "Fulano da Silva <fulano@xadm.com.br>"
modulo: transporte
cliente: "Vantroba"
atualizado: 2026-06-09
capitulo: building-blocks # campo da era do livro montado; sem função no livro autorado (constituição, Livro, Resumo e nav)
entrega: "Importação da frota a partir da planilha do cliente"
entregue: false # OBRIGATÓRIO em etapa: a FEATURE está entregue? (≠ status do DOC). "design aprovado, build pendente" = status: aprovado + entregue: false
tags: [bi, importacao, xls]
---
<!--
TEMPLATE DE ETAPA DO PROJETO — X-Adm
Copie para docs/projeto/NN-titulo-curto.md (NN = ordinal de duas casas; sem
PROJ-/ano — a data vai em decidido_em:/Git). Avulso vai em projeto/diversos.md.
Todo o conteúdo abaixo é EXEMPLO ilustrativo: substitua, mantendo as seções.
Seção sem conteúdo útil: apague. Seção vazia não existe.
Uma etapa por feature. **Tecnicamente completa PARA O SEU ESCOPO** (teste:
um dev/IA que nunca viu o código implementa o que esta etapa introduz/muda a
partir daqui + das etapas referenciadas). **Sem repetir:** o que já foi desenhado
antes, referencie (link); só re-enuncie o que ESTA etapa altera. Apague as seções
que seu escopo não toca. Detalhe que muda toda semana e mecânica interna não
entram (vão pro código — constituição, Documentar interfaces, decisões e uso); passo a passo de usuário vai pro manual.
Esta etapa é o *delta* (o que ESTA feature muda) e o histórico; o desenho do sistema
NO ESTADO ATUAL vive na Documentação Completa autorada (projeto/index.md — constituição, Livro, Resumo e nav), não é
montada daqui. entrega: = frase de negócio da etapa para o Resumo Executivo.
capitulo: é campo da era do livro montado (sem função no livro autorado).
-->
# 01 — Importação de frota a partir de planilha XLS
## 1. Contexto e escopo
O cliente mantém o cadastro da frota em planilhas Excel e precisa desses dados
no banco do BI para alimentar os dashboards de transporte.
**Dentro do escopo:** upload da planilha pela web, validação das linhas,
gravação na tabela de frota, relatório de erros por linha.
**Fora do escopo:** edição da frota pela web (continua na planilha);
sincronização reversa banco → planilha.
**Integrações:** banco PostgreSQL do BI (escrita); PowerSync (leitura pelos
dashboards — ver doc de projeto do bi-transporte).
## 2. Arquitetura
Blocos/camadas que esta etapa cria ou toca e a regra de dependência entre eles.
O que vem de etapa anterior, referencie — não redesenhe.
## 3. Modelo de dados
**O *delta* que esta etapa faz no schema** — tabela que cria/altera: colunas, tipos,
chaves, índices, e **por quê**. O **estado consolidado** do banco não vive aqui: vive
em [`projeto/modelagem.md`](modelagem.md) (constituição, Convenções de doc), que **esta etapa atualiza no mesmo
PR**. Tabela de etapa anterior que não muda: nem repita — está no `modelagem.md`.
```mermaid
erDiagram
PROCESSAMENTO_XLS ||--o{ FATURAMENTO : gera
PROCESSAMENTO_XLS {
bigint id PK
varchar checksum_sha256 UK "SHA-256 do binário; idempotência"
varchar status "PENDENTE|PROCESSANDO|SUCESSO|ERRO"
date periodo_inicial
date periodo_final
}
```
**`bi_processamento_xls`** — controle de cada upload.
| Coluna | Tipo | Chave/constraint | Nota |
|---|---|---|---|
| `id` | `BIGSERIAL` | PK | |
| `checksum_sha256` | `VARCHAR(64)` | UNIQUE, NOT NULL | idempotência (decisão 000N) |
| `status` | `VARCHAR(20)` | NOT NULL, default `PENDENTE` | máquina de estados (ver 4. Fluxos e estados) |
| `periodo_inicial` / `periodo_final` | `DATE` | | período de referência |
(O `modelagem.md` é o dicionário de dados vivo consolidado; aqui fica só o delta
desta etapa.)
## 4. Fluxos e estados
```mermaid
flowchart LR
A[POST /processar] --> B{checksum já existe?}
B -- não --> C[persiste PENDENTE + 202]
B -- sim --> D[409]
C --> E[async: processa abas]
E --> F[SUCESSO | ERRO]
```
Caminho feliz + erros em poucas frases. Se há **máquina de estados**, declare-a
(estados, transições, o que dispara cada uma).
## 5. Contratos
O que esta etapa expõe/consome e outros precisam para integrar:
- **API:** endpoints (método, rota), request/response, status (202/400/401/409…),
auth. Detalhe vive em [`dev/api-rest`](../dev/api-rest.md) — aqui amarre o essencial.
- **Formatos de arquivo/integração:** ex. as abas do Excel e o **mapeamento
coluna→campo**; eventos publicados/consumidos.
## 6. Configuração
Envs/flags que **mudam o comportamento** (não toda env): ex. modo de storage,
token, destino de notificação. Cada uma: o que faz, valores, default.
## 7. Decisões
Resumo das decisões relevantes; o corpo de cada uma vive em `docs/decisoes/`.
**Não reafirme o status aqui** — ele é da decisão (fonte única — constituição:
Duas fontes da verdade; Convenções de doc): a tabela só linka; a própria decisão diz se está aprovada ou obsoleta.
O validador falha se a tabela contradiz o status real da decisão.
| Nº | Decisão |
|---|---|
| [0001](../decisoes/0001-processamento-assincrono.md) | Processamento assíncrono com fila em banco |
## 8. Riscos
- Planilhas fora do layout esperado → mitigação: validação por linha com
relatório, nunca falha o lote inteiro.
- Volume acima do estimado (>50k linhas) → mitigação: processamento em batches.
## 9. Critérios de aceite e teste
A ponte para quem valida — **não** um plano de QA nem um nível novo de doc. Regra: se
esta etapa não permite **implementar E testar**, falta informação; se repete código,
passou do ponto.
### Critérios de aceite
- [resultado **observável** que precisa ser verdade para a etapa estar pronta]
### Pontos para testar
- **Caminho feliz:** [o fluxo principal]
- **Erros e bordas:** [entrada inválida, limites, concorrência]
- **Regressões importantes:** [o que não pode quebrar — piso: nenhuma sem teste]
### Evidência esperada
- **Automatizada:** [unit / integração / widget / contrato / fronteiras] — roda no gate
da stack ([CI, gates e testes](https://docs.xadm.biz/engenharia/ci-testes/)); a
verificação exercita a plataforma real, não só fixture (constituição, Governança).
- **Manual:** [quando proporcional ao risco].
- **Artefato:** [fixture golden, screenshot, log, runbook executado].
### Impacto
- **No livro (`projeto/index.md`):** muda o estado atual? → atualizar **no mesmo PR**.
- Toca também: `modelagem.md` · API/contrato · manual · runbook? [marque o que se aplica].
**Observabilidade** (o que esta etapa expõe para operar — `/health`, métricas,
logs-chave) entra aqui ou no livro/runbook conforme o caso.
## 10. Glossário
Termos novos que esta feature introduz e que ainda não estão no
`docs/glossario.md` do projeto. Se não houver, apague a seção.
Decisão (registro de decisão)¶
---
titulo: "Processamento assíncrono com fila em banco"
tipo: decisao
status: aprovado
responsavel: "Fulano da Silva <fulano@xadm.com.br>"
modulo: transporte
atualizado: 2026-06-09
decidido_em: 2026-06-09
tags: [processamento, arquitetura]
---
<!--
TEMPLATE DE DECISÃO (REGISTRO DE DECISÃO) — X-Adm
Copie para docs/decisoes/NNNN-titulo-curto.md no repo da aplicação
(numeração sequencial: 0001, 0002, ...).
Todo o conteúdo abaixo é EXEMPLO ilustrativo: substitua, mantendo as seções.
~1 página: "decidimos X porque Y, considerando Z". Não é especificação.
decidido_em: data em que a decisão foi TOMADA (≠ atualizado:, que é a última
edição). Num registro retroativo (migração), use a melhor data conhecida —
NÃO copie a data da migração: isso quebra a promessa de "história datada".
Decisão aceita NÃO se reescreve, com UMA exceção (constituição, Decisão é registro; referência é viva):
- fato INCIDENTAL errado sobre o código (um número, uma property inexistente —
a decisão continua de pé) → corrige EM-LUGAR, com nota datada no corpo:
> **Correção AAAA-MM-DD:** o limite real é 50MB, não 100MB.
- premissa/raciocínio errado (a escolha poderia ter sido outra) → crie outra
decisão e marque esta com status: obsoleto + superado-por: "NNNN".
superado-por: / supersede: vão ENTRE ASPAS ("0016") — sem aspas o YAML lê o zero
à esquerda como octal (0016 → 14) e o número renderiza/valida errado. O validador
falha se vier sem aspas.
Alternativas consideradas: liste só as REALMENTE deliberadas. Não reconstrua
alternativas que nunca se cogitou (inventar deliberação é mentira — constituição,
Documentar interfaces, decisões e uso).
Título: descreva a decisão pelo PAPEL, não por nome de classe (ex. evite
"BulkUpserter", "ProcessamentoHelper" no título) — identificador de código em
título envelhece ao refactor; o validador avisa (constituição, Convenções de doc).
-->
# 0001 — Processamento assíncrono com fila em banco
## Contexto
O upload de planilhas grandes (até 50k linhas) estoura o timeout HTTP se
processado na própria requisição. Precisamos decidir como desacoplar o upload
do processamento.
## Decisão
Processar de forma assíncrona usando uma tabela de fila no próprio PostgreSQL
(status `PENDENTE → PROCESSANDO → SUCESSO/ERRO`), consumida por um job
agendado do Micronaut.
## Consequências
- O usuário recebe resposta imediata e acompanha o status pela tela de
processamentos.
- Sem dependência nova de infraestrutura (sem RabbitMQ/Redis) — menos coisa
pra operar no Coolify.
- Latência de até 1 ciclo do job (30s) entre upload e início do processamento —
aceitável para o caso de uso.
## Alternativas consideradas
- **Processar na requisição HTTP:** simples, mas estoura timeout em planilhas
grandes — descartado.
- **Fila dedicada (RabbitMQ):** mais robusto em alto volume, mas adiciona um
serviço pra manter; volume atual não justifica.
Manual de usuário¶
---
titulo: "Como importar a planilha de frota"
tipo: manual
status: aprovado
responsavel: "Fulano da Silva <fulano@xadm.com.br>"
modulo: transporte
cliente: "Vantroba"
atualizado: 2026-06-09
tags: [importacao, frota, xls]
---
<!--
TEMPLATE DE MANUAL DE USUÁRIO — X-Adm
Copie para docs/public/manual/titulo-da-tarefa.md no repo da aplicação
(o manual do usuário é público — vive em docs/public/, constituição, Convenções de doc).
Todo o conteúdo abaixo é EXEMPLO ilustrativo: substitua, mantendo o formato.
Regras de ouro:
- Título é a tarefa na voz do usuário ("Como fazer X").
- Cada seção ## responde UMA pergunta — isso alimenta a busca e o futuro
chatbot do ERP.
- Sem jargão técnico, sem nome de tabela/coluna, sem detalhe de arquitetura.
- Screenshots em docs/public/img/ (manual é público — constituição, Convenções de doc): nome semântico quando 1 imagem por tela
(dre.png), senão <slug>-NN.png. Gere-as de forma REGENERÁVEL (não print
manual, que apodrece) — receita por stack em
https://docs.xadm.biz/padroes/screenshots-manual/.
-->
# Como importar a planilha de frota
Use esta tela quando precisar atualizar os veículos da frota no sistema a
partir da planilha Excel.
## Antes de começar
- Tenha a planilha de frota no formato padrão (a mesma que você já usa).
- Você precisa do perfil **Operador de BI** ou superior.
## Passo a passo
1. No menu lateral, clique em **Importações → Frota**.
2. Clique em **Enviar planilha** e selecione o arquivo `.xlsx` no seu
computador.
3. Confira o resumo (quantidade de linhas reconhecidas) e clique em
**Confirmar importação**.
4. Acompanhe o andamento na coluna **Status**. Quando aparecer
**SUCESSO**, os veículos já estão atualizados nos dashboards.
## Quando der erro, faça isso
**Status ERRO com mensagem "linhas inválidas":** clique no número da
importação para ver o relatório linha a linha. Corrija as linhas apontadas na
planilha e envie de novo — as linhas corretas não são duplicadas.
**A planilha não é aceita no envio:** verifique se o arquivo é `.xlsx`
(Excel moderno). Planilhas `.xls` antigas precisam ser salvas como `.xlsx`
antes do envio.
**O status fica em PENDENTE por mais de 5 minutos:** abra um chamado para o
suporte informando o número da importação.
Runbook de operação — procedimento pontual¶
O molde de "como executo esta operação": operação única, normalmente disparada por incidente, num app só (Níveis de documentação). O runbook é só o procedimento; o porquê e o como funciona ficam no doc de projeto.
Todo runbook, nos dois moldes, cumpre três regras:
- A reversão enumera todas as vias, e o que cada desligar isolado não para. Sistema com mais de uma via de descoberta (webhook e varredura, fila e retry) leva a tabela caminho → efeito, com os caminhos que não funcionam marcados. Kill switch não conferido contra o código não desliga nada — e é lido no pior dia possível. Ofereça sempre a via bruta (parar o container).
- Todo passo de verificação declara o resultado esperado, conferido no código — não no que parece razoável. Mesmo payload não é a mesma versão: onde a chave-versão sobe a cada escrita (timestamp, sem dirty-check), idempotência se prova com uma escrita e vários ciclos do consumidor, nunca com duas escritas.
- Valor de contrato externo sem fonte do outro lado é
<PLACEHOLDER>, não exemplo. Fixture nossa não confirma contrato de terceiro: javadoc "ex.:", seed de teste e whitelist concordam entre si porque descendem da mesma suposição. Sem fonte de lá,<PLACEHOLDER>e um bloco "A confirmar" com o efeito real de errar — exemplo de contrato é lido como contrato por quem implementa.
---
titulo: "Reprocessar uma carga de frota travada"
tipo: operacao
status: aprovado
responsavel: "Fulano da Silva <fulano@xadm.com.br>"
modulo: transporte
cliente: "Vantroba"
atualizado: 2026-06-11
tags: [runbook, reprocessamento, frota]
---
<!--
TEMPLATE DE RUNBOOK — X-Adm (nível 5 — constituição, Níveis de documentação)
Copie para docs/operacao/titulo-da-operacao.md no repo da aplicação.
Todo o conteúdo abaixo é EXEMPLO ilustrativo: substitua, mantendo o formato.
Regras de ouro:
- Audiência é dev/ops da X-Adm: jargão técnico é permitido, prints opcionais.
- Teste de qualidade: um dev que nunca operou o app executa só com o documento.
- O "porquê/como funciona" vai no doc de projeto — aqui é só o procedimento.
- Operação destrutiva começa com o admonition de aviso (como abaixo);
operação inofensiva pode removê-lo.
- Runbook é referência VIVA (constituição, Decisão é registro; referência é viva): mudou o procedimento,
atualize o documento no mesmo PR.
-->
# Reprocessar uma carga de frota travada
!!! warning "Operação destrutiva"
O reprocessamento apaga as linhas já importadas dessa carga antes de
inserir de novo. Leia até o fim antes de executar pela primeira vez.
## O que é
Descarta o resultado parcial de uma importação de frota que travou no meio
(status `PENDENTE` há mais de 1h) e dispara o processamento de novo a partir
do arquivo original, que fica retido no bucket.
## Quando usar
- Importação presa em `PENDENTE` por mais de 1 hora (o suporte normalmente
reporta via manual "Como importar a planilha de frota").
- Após deploy que corrige bug de parsing, para reaproveitar o arquivo já
enviado sem pedir novo upload ao cliente.
## Pré-requisitos
- Acesso ao painel do Coolify (app `bi-transporte-xls`).
- `TOKEN` da API admin (env `API_BEARER_TOKEN` do app no Coolify).
- Número da importação travada (coluna **ID** na tela de importações).
## Passos
1. Confirme que a carga está realmente travada:
```bash
curl -s "$BASE/admin/importacoes/123" -H "Authorization: Bearer $TOKEN"
# status deve ser PENDENTE e atualizado_em > 1h atrás
```
2. Dispare o reprocessamento:
```bash
curl -X POST "$BASE/admin/importacoes/123/reprocessar" \
-H "Authorization: Bearer $TOKEN"
```
3. Acompanhe os logs no Coolify até aparecer `importacao 123 concluida`.
## Verificação
- A tela de importações mostra a carga com status **SUCESSO**.
- Os totais batem com o resumo do arquivo (linhas reconhecidas = inseridas).
## Reversão
Não há rollback automático: o reprocessamento é idempotente (apaga e insere
de novo). Se falhar no meio, é seguro executar os passos outra vez. Se o
arquivo original estiver corrompido no bucket, peça novo upload ao cliente
pelo fluxo normal do manual de importação.
Runbook de implantação — como o sistema fica de pé¶
O irmão do anterior, não o substituto: o eixo é "como este sistema fica de pé,
e como eu o desligo". Escreve topologia de operação (com diagrama — é o que o
operador lê primeiro), superfície de operação e variáveis por servidor com os pares
que têm de casar; o porquê daquela topologia — arquitetura, fluxo, modelo,
contratos — tem dono fora dele (Livro, Resumo e
nav, corolário o livro não é re-digitado no
runbook). Re-digitar é que é proibido: onde o operador precisa do fato na mesma
página, o runbook transclui do arquivo-dono (--8<--) em vez de linkar — não há
cópia para envelhecer. Onde um link basta, linka.
Cross-repo o --8<-- não alcança, mas o build alcança: o job docs importa o arquivo-fato
publicado pelo dono e o embute (Importar um fato de outro
repo). Se o dono ainda não publica, é link ou
<PLACEHOLDER>, e a pendência é do dono — cobre a publicação em vez de copiar. Nunca cópia.
Sistema de um serviço só, sem kill switch, cabe no molde de procedimento — não infle.
As três regras de todo runbook estão demonstradas no exemplo, com o porquê em comentário para apagar.
---
titulo: "Implantação da integração Thoms → WebStorm"
tipo: operacao
status: aprovado
responsavel: "Fulano da Silva <fulano@xadm.com.br>"
modulo: integracao
cliente: "Thoms"
atualizado: 2026-07-16
tags: [runbook, implantacao, deploy, integracao]
---
<!--
TEMPLATE DE RUNBOOK DE IMPLANTAÇÃO — X-Adm (nível 5 — constituição, Níveis de documentação)
Copie para docs/operacao/implantacao.md no repo da aplicação.
Todo o conteúdo abaixo é EXEMPLO ilustrativo: substitua, mantendo o formato.
Este é o IRMÃO do templates/runbook.md, não o substituto. O eixo é outro:
- runbook.md ......... "como executo esta operação" (procedimento pontual,
disparado por incidente, um app)
- implantacao.md ..... "como este sistema fica de pé, e como eu o desligo"
Sistema com um serviço só e sem kill switch cabe no runbook.md — não infle.
O QUE É SEU (escreva): topologia de OPERAÇÃO (o que sobe, onde, com que auth
— COM diagrama; é o que o operador lê primeiro), superfície, variáveis por
servidor com os pares que têm de casar, passos, verificação e reversão.
O QUE NÃO É SEU (constituição, Duas fontes da verdade — um dono por fato): o PORQUÊ daquela
topologia — arquitetura, fluxo de processamento, modelo de dados, contratos.
Isso tem dono fora daqui. Mas RE-DIGITAR é que é proibido; TRANSCLUIR não é:
- fato com dono NESTE repo, que o operador precisa ver na mesma página
→ ;--8<-- "projeto/<fato>.md" (o fato não é copiado, é incluído no build;
muda com o dono, sem ninguém lembrar de nada. O ';' inicial ESCAPA o
marcador: sem ele, esta linha de exemplo seria transcluída de verdade —
o snippets processa até dentro de comentário HTML e de bloco de código.
No doc real, sem o ';'.)
- fato com dono neste repo que o operador NÃO precisa ver na hora → link
- fato com dono em OUTRO repo → o job docs do pipeline.yml importa o
arquivo-fato que o dono publica e o embute (o --8<-- não atravessa
repositório; o build atravessa). Dono que ainda não publica: link ou
<PLACEHOLDER>, e a pendência é dele. NUNCA cópia — contrato copiado de fora
vira exemplo que mente
Transclua do ARQUIVO-DONO, nunca "a seção do livro": o livro é narrativa e ele
próprio embute os fatos (modelagem.md, mapeamento.md). Fato que dois documentos
mostram ganha arquivo próprio, no padrão dos snippets do livro — sem frontmatter,
headings em ###, declarado em exclude_docs: do mkdocs.yml (not_in_nav: não serve:
ele não tira do build, e o fragmento vira página órfã com H1 inventado).
E se o operador precisa de um diagrama DIFERENTE do que o livro tem, ele é um
fato diferente — escreva-o aqui (é o caso da Topologia de operação abaixo), não
transclua o do livro. O Mermaid de arquitetura ponta-a-ponta do livro é
autorado para quem quer ENTENDER o sistema; o operador com o sistema fora do ar
precisa de outro, de topologia de rede. Dois diagramas, dois donos, nenhuma cópia.
EXEMPLO — o operador precisa do fluxo na mão para diagnosticar ("mudei o preço
e não chegou: em que hop parou?"). O dono vira docs/projeto/fluxo.md, embutido
no livro (cap. 5) E aqui; uma seção deste doc fica só com:
--8<-- "projeto/fluxo.md"
(sem o ';' — ver acima). Se um link basta, linke e não crie o arquivo-fato.
Atenção: com check_paths: true, snippet apontando arquivo inexistente FALHA o
build (SnippetMissingError) — crie o arquivo-fato antes de referenciá-lo.
AS TRÊS REGRAS QUE ESTE DOC TEM DE HONRAR (https://docs.xadm.biz/documentacao/templates/ — Runbook de operação):
1. Reversão enumera TODAS as vias, e o que cada desligar isolado NÃO para.
2. Todo passo de Verificação declara o resultado esperado, conferido no código.
3. Valor de contrato externo sem fonte do outro lado é <PLACEHOLDER>, não exemplo.
-->
# Implantação — integração de produtos Thoms → WebStorm
## O que é
Guia de implantação e operação da integração que leva preço e estoque dos produtos
do X-Adm (ERP da Thoms) ao e-commerce do parceiro WebStorm. Cobre o que subir, com
que variáveis, como conferir que subiu e como desligar.
O **desenho** — arquitetura, fluxo de processamento, idempotência, modelo de dados
— é do livro: [Documentação Completa](../projeto/index.md). Aqui não se re-digita.
## Quando usar
- Ao provisionar os dois serviços em produção (Coolify) pela primeira vez.
- Ao atualizar um deles, ou ao integrar um cliente novo do X-Adm.
- Ao precisar **desligar** a integração sem derrubar o ERP (§ Reversão).
## Pré-requisitos
- Banco `db_thoms` (PostgreSQL) provisionado e acessível aos dois apps.
- DNS dos dois subdomínios apontando para o Coolify.
- Secrets do §Variáveis à mão (cofre da X-Adm).
- Feature 008 do integrador (coluna `estoque.updated_at` + webhook de saída) no
build implantado.
## Topologia de operação
O que sobe, onde, e o que cada peça precisa. A **arquitetura** (por que 3 hops,
por que banco compartilhado) está no [livro, cap. 5](../projeto/index.md).
```mermaid
%% caption: O que se implanta — dois serviços, um banco, um externo
flowchart TB
INT["Integrador<br/>int.thoms.xadm.biz<br/>(recurso Coolify)"]
TRAD["Tradutor<br/>webstorm-ecom.thoms.xadm.biz<br/>(recurso Coolify)"]
DB[("db_thoms (PostgreSQL)<br/>compartilhado")]
WS["API WebStorm<br/>EXTERNO — fora do nosso controle"]
INT --> DB
TRAD --> DB
TRAD -->|"POST /sync/erp"| WS
```
| Peça | Onde | Auth | Quem é dono |
|---|---|---|---|
| Integrador | recurso Coolify, `int.thoms.xadm.biz` | Bearer no `/api/v1/**` | repo `xadm/integrador` |
| Tradutor | recurso Coolify, `webstorm-ecom.thoms.xadm.biz` | middleware do Coolify nas telas | este repo |
| `db_thoms` | Postgres compartilhado | usuário por app | integrador (dono do schema da réplica) |
| API WebStorm | **externo** | Bearer do parceiro | parceiro |
## Contrato de entrada
Quem alimenta o sistema: o X-Adm faz `PUT https://int.thoms.xadm.biz/api/v1/xadm`
com `Authorization: Bearer <INTEGRADOR_API_TOKEN>`.
**A forma completa** (campos, tipos, respostas por HTTP, exemplos) é do
[schema canônico do integrador](https://docs.xadm.biz/integrador/) — não se copia
aqui. O necessário para o passo de fumaça do §Verificação:
- Corpo: objeto com `Origem` (a rotina do X-Adm que originou a carga) e a tabela
`ESTOQUE` (array de produtos).
- `200` → `{requestId, resultado: "SUCESSO"}`; `401` → Bearer inválido/ausente.
> **A confirmar:** o valor de `<ORIGEM>` que a rotina de saída da Thoms usa.
> **Efeito de errar:** origem fora de `XadmService.KNOWN_ORIGENS` não é rejeitada,
> mas erro de processamento naquela origem **não** é roteado ao Sentry — a falha
> fica invisível. Alinhar com o dev do X-Adm antes de implantar.
<!--
Regra 3, o porquê: os valores acima que descrevem o LADO DE LÁ (o que a rotina do
X-Adm manda, o que a API do parceiro aceita) só entram como exemplo se vierem de
fonte do outro lado — doc do parceiro, contrato assinado, resposta capturada.
Javadoc "ex.:", seed de teste e whitelist nossa não confirmam contrato de terceiro:
concordam entre si porque descendem da mesma suposição. Sem fonte de lá:
<PLACEHOLDER> + bloco "A confirmar" com o efeito real de errar, como acima.
Exemplo de contrato é lido como contrato por quem implementa.
-->
## Superfície de operação
O que o operador olha, depois de implantado:
- `https://webstorm-ecom.thoms.xadm.biz/webstorm-ecom` — trilha de cada envio ao
parceiro (quando, produto, HTTP, resultado).
- `.../webstorm-ecom?atencao=true` — só o que precisa de olhar humano.
- **Detalhe** de uma linha — payload enviado + resposta; botão **Reprocessar**.
- `/health` nos dois serviços — `{status, versao}`.
## Variáveis de ambiente
Uma tabela por servidor. Segredos via secrets do Coolify, **nunca no repo**.
Nomes seguem o mapeamento Micronaut (`propriedade` → `MAIÚSCULA_COM_UNDERSCORE`).
### Integrador — `int.thoms.xadm.biz`
| Variável | Valor / descrição |
|---|---|
| `CLIENTE` | `Thoms` |
| `DATASOURCES_DEFAULT_URL` | JDBC do `db_thoms` |
| `DATASOURCES_DEFAULT_PASSWORD` | **segredo** — credencial do dono do schema |
| `INTEGRADOR_API_TOKEN` | **segredo** — exigido no `Bearer` do `PUT /api/v1/xadm` |
| `SENTRY_DSN` | DSN do GlitchTip (público; fonte: `docs/app.json`) |
| `WEBSTORM_WEBHOOK_ENABLED` | `true` (só no deploy Thoms) — liga o poke de saída |
| `WEBSTORM_WEBHOOK_TOKEN` | **segredo** — ver pares abaixo |
### Tradutor — `webstorm-ecom.thoms.xadm.biz`
| Variável | Valor / descrição |
|---|---|
| `DATASOURCES_DEFAULT_URL` | JDBC do **mesmo** `db_thoms` |
| `DATASOURCES_DEFAULT_PASSWORD` | **segredo** — read em `estoque`, write em `webstorm_ecom_*` |
| `WEBHOOK_TOKEN` | **segredo** — ver pares abaixo |
| `PARCEIRO_URL` | base da API WebStorm — o app faz `POST {url}/sync/erp` |
| `PARCEIRO_TOKEN` | **segredo** — Bearer da API WebStorm |
| `WEBSTORM_SWEEP_ENABLED` | `false` desliga o sweep (default: ligado). Lido no start: exige restart |
### Pares que têm de casar
Enumere explicitamente: valor que existe nos dois lados e diverge em silêncio é
falha de implantação que só aparece em produção.
| Ponta A | Ponta B | Sintoma se divergirem |
|---|---|---|
| `WEBSTORM_WEBHOOK_TOKEN` (integrador) | `WEBHOOK_TOKEN` (tradutor) | poke responde `401`; o sweep mascara (envia atrasado, ninguém nota) |
| `INTEGRADOR_API_TOKEN` (integrador) | Bearer do cliente X-Adm | `PUT` responde `401`; nada entra |
## Passos de implantação
1. **Banco.** Garantir `db_thoms` acessível aos dois apps; criar o usuário do
tradutor com `SELECT` em `estoque` e `ALL` nas `webstorm_ecom_*`.
2. **Integrador.** Deploy no subdomínio `int.thoms.xadm.biz`; setar as ENV.
3. **Tradutor.** Deploy deste repo em `webstorm-ecom.thoms.xadm.biz`; setar as ENV.
4. **Auth das telas.** Configurar o middleware do Coolify na frente do tradutor —
as telas não têm login no app.
5. **Cliente X-Adm.** Apontar a URL do integrador + o Bearer (§ Pares).
## Verificação
Todo passo declara o **resultado esperado**, conferido no código — não no que
parece razoável (ver a nota abaixo).
1. `GET /health` nos dois → `{status:"UP", versao:"…"}`.
2. `PUT /api/v1/xadm` com uma carga de teste → `200`, `resultado: "SUCESSO"`.
3. Abrir a trilha → o produto aparece com o resultado do parceiro.
4. **Escrita repetida.** Repetir o mesmo `PUT`, mesmo sem mudar valores →
**nova** linha na trilha. É o esperado: a versão é bumpada por **escrita**
(`@DateUpdated`, sem dirty-check), não por diff de conteúdo.
5. **Idempotência.** Dar **um** `PUT` e aguardar ≥ 2 ciclos de `SWEEP_INTERVALO`
**sem novo `PUT`** → segue **uma** linha só. Se aparecer linha nova sem `PUT`
no meio, a idempotência quebrou.
<!--
Regra 2, o porquê: "mesmo payload" ≠ "mesma versão". Onde a chave-versão é
timestamp de escrita (@DateUpdated, @LastModifiedDate, trigger de UPDATE),
duas escrituras iguais geram DUAS versões — um passo que manda "repita o PUT e
espere nenhuma linha nova" dá falso alarme no dia do deploy, e o operador não
tem como saber se é bug ou o doc. Idempotência por versão-timestamp prova-se com
UMA escrita e VÁRIOS ciclos do consumidor (passo 5), nunca com duas escritas.
Cheque cada resultado esperado contra o código antes de escrever o passo.
-->
## Reversão
**Desligar a integração sem derrubar o X-Adm.** O tradutor descobre mudança por
**duas vias independentes** — o poke e o sweep `@Scheduled` — e o poke dispara um
sweep **completo**. Logo, desligar **uma** via não para os envios:
| Caminho | Efeito |
|---|---|
| Parar o container do tradutor (Coolify) | **Para tudo.** Mais simples e garantido — prefira este |
| `WEBSTORM_WEBHOOK_ENABLED=false` **+** `WEBSTORM_SWEEP_ENABLED=false` | Para tudo, mantendo as telas no ar. Exige **os dois** |
| Só `WEBSTORM_WEBHOOK_ENABLED=false` | ⚠️ **Não desliga** — o sweep segue enviando a cada `SWEEP_INTERVALO` |
| Só `WEBSTORM_SWEEP_ENABLED=false` | ⚠️ **Não desliga** — cada poke ainda dispara um sweep completo |
Em qualquer caso o X-Adm segue postando ao integrador; a réplica continua
atualizada e o atraso sai quando religar.
**Reverter versão:** redeploy da tag anterior (Coolify). As migrations do tradutor
são aditivas; não tocam a réplica.
<!--
Regra 1, o porquê: kill switch não conferido contra o código é kill switch
imaginário — e ele é lido no pior dia possível, por quem não escreveu o sistema.
Sistema com mais de uma via de descoberta (webhook + sweep, fila + retry, cache +
origem) precisa desta tabela "caminho → efeito", com os caminhos que NÃO funcionam
marcados. Antes de escrever, siga cada flag no código até o ponto de envio e
confirme o que ela realmente corta. Sempre ofereça a via bruta (parar o container):
é a única que não depende de o resto do desenho estar certo.
-->
Documentação Completa — o livro (docs/projeto/index.md)¶
O esqueleto autorado do sistema no estado atual, em ordem lógica que termina nos contratos (Livro, Resumo e nav). Não é montado das etapas.
- Capa — o sistema numa tela. O livro abre com a figura de topologia e fluxos principais (quem fala com quem, o que entra, o que sai), com legenda: o leitor vê a forma do sistema antes da primeira frase. Mermaid por padrão; a capa pode ser SVG autoral. Para cada fluxo, a capa (ou a seção que ela aponta) diz como acompanhar — o mecanismo pelo qual um humano vê se o fluxo rodou ou falhou: tela de status, push, e-mail de erro, GlitchTip. Projeto novo nasce com ela; livro existente a ganha quando for tocado (Migração oportunista).
- Factual de fonte, narrativa humana marcada. O livro não reescreve o que tem fonte: o modelo vem
do
modelagem.md(embed--8<--), a API do OpenAPI gerado, o histórico do frontmatter. Regra de corte: derivável do código ou da fonte vem da fonte. O humano escreve o fio narrativo e o porquê; o agente redige a prosa que consegue ancorar nas fontes e marca o resto — o proibido é inventar fato, não redigir. - Marcadores (sozinhos na linha, processados pelo
visao-tecnica.py):<!-- HUMANO: pergunta concreta -->— ponto que o agente devolve ao humano; preservado em rascunho e em revisão, e falha o build em páginastatus: aprovado(o comentário some no HTML e a página publica com um buraco).<!-- RECONCILIAR: o quê -->— transição não resolvida (um rename em curso); falha o build até reconciliar, para a pendência não ficar silenciosa.<!-- GERADO: changelog -->— o build injeta a trilha de etapas e decisões.
- Quem integra entra direto no cap. 7; na doc interna ele é o fim da cadeia, não a abertura.
- Etapas no nav: as etapas (
projeto/NN-*.md) seguem no nav como histórico detalhado — cada uma descreve o seu delta; o livro é o estado consolidado. Pré-projeto epublic/manual/ficam fora do livro.
---
titulo: "Documentação Completa — <App>"
tipo: livro
status: aprovado
responsavel: "Fulano da Silva <fulano@xadm.com.br>"
cliente: "Vantroba" # só em app de cliente (constituição, Convenções de doc); modulo: não se aplica ao livro
atualizado: 2026-06-16
---
<!--
TEMPLATE — DOCUMENTAÇÃO COMPLETA (o livro do sistema, docs/projeto/index.md) — X-Adm
Esqueleto AUTORADO do sistema NO ESTADO ATUAL, em ordem lógica que termina nos
contratos (constituição, Livro, Resumo e nav). NÃO é montado das etapas. Você escreve o fio narrativo;
o factual vem das FONTES (embeds, OpenAPI, changelog), não se re-digita. Regra de
corte: derivável do código/fonte ⇒ vem da fonte.
Marcadores (sozinhos na linha):
<!-- HUMANO: pergunta concreta --> ponto que você (humano) responde
<!-- RECONCILIAR: o quê --> transição não resolvida — FALHA o build
<!-- GERADO: changelog --> o build injeta etapas + decisões
Apague as seções que seu sistema não tem (sem banco: apague o embed do cap. 3).
Apague este comentário.
-->
# Documentação Completa
## 0. Capa — o sistema numa tela
<!-- HUMANO: figura de TOPOLOGIA + FLUXOS PRINCIPAIS (constituição, Livro, Resumo e nav — cap. 0): quem fala
com quem, o que entra, o que sai — com legenda. Mermaid por padrão; figura de capa
pode ser SVG autoral (constituição, Convenções de doc + Templates, Figura autoral em SVG; exemplo vivo: a
topologia em docs.xadm.biz/plataforma/integracao/). Para cada fluxo, diga COMO
ACOMPANHAR: o mecanismo pelo qual um humano vê se rodou ou falhou (tela de status,
push no app, email de erro, GlitchTip). -->
## 1. Contexto e problema
<!-- HUMANO: que problema do cliente este sistema resolve? escopo e fora-de-escopo? -->
## 2. Dados de entrada
<!-- HUMANO: o que entra (planilha/fila/payload) e as regras de descarte de linha? -->
## 3. Modelo de dados
O estado atual do modelo (schema do banco e/ou contrato dos artefatos de saída) vem de
`projeto/modelagem.md` (constituição, Convenções de doc). **Descomente** o embed abaixo quando o arquivo existir
(precisa de `pymdownx.snippets`, já no mkdocs.yml):
<!-- --8<-- "projeto/modelagem.md" -->
## 4. Mapeamento entrada↔dados
<!-- HUMANO: como cada parte da entrada vira cada campo do destino? -->
<!-- Opcional: fonte em projeto/mapeamento.md — descomente o embed: -->
<!-- --8<-- "projeto/mapeamento.md" -->
## 5. Fluxos e processamento
<!-- HUMANO: recepção, máquina de estados, e as camadas (api→service→repo→domain) -->
<!-- HUMANO: Regras arquiteturais guardadas por teste/lint — as fronteiras que o gate
enforça (ex. api não depende de repository; camada de infra não importa feature) e
o link para a regra testada. Se o app não tem guarda mecânica, descreva a fronteira
e diga que o piso é convenção+review. Engenharia: docs.xadm.biz/engenharia/ci-testes/ -->
## 6. Conceitos transversais e configuração
<!-- HUMANO: idempotência, auth, prefixos; e as variáveis do projeto (banco, GlitchTip, chaves) -->
## 7. Contratos públicos / API
A conclusão: as assinaturas que tudo acima justifica.
<!-- HUMANO: endpoints públicos + auth; embute/linka o OpenAPI gerado (docs/public/api/ — constituição, Convenções de doc) -->
## 8. Apêndice — Histórico
Como chegamos ao estado atual:
<!-- GERADO: changelog -->
Guia do código (docs/dev/guia-do-codigo.md)¶
A página Dev padrão de todo app com código (Níveis de documentação, nível 4): a
narrativa autorada de como o código se organiza — o atalho do dev novo antes de
mergulhar no Javadoc/dartdoc. Esqueleto com blocos por stack (Java
package-by-feature / Flutter feature-first) para apagar. O <!-- GERADO: inventario
--> no fim é opcional e só rende inventário se o pipeline.yml do app tiver o passo
Javadoc/dartdoc que o preenche (ver como publicar); sem o passo,
o hook compartilhado remove a linha no build.
---
titulo: "Guia do código"
tipo: dev
status: aprovado
responsavel: "Fulano da Silva <fulano@xadm.com.br>"
modulo: transporte
cliente: "Vantroba"
atualizado: 2026-06-09
tags: [dev, arquitetura, codigo]
---
<!--
TEMPLATE — GUIA DO CÓDIGO (docs/dev/guia-do-codigo.md) — X-Adm
A página Dev padrão para todo app COM código (nível 4 — constituição, Níveis de documentação): a
narrativa AUTORADA de como o código se organiza — o atalho para um dev novo
"passar os olhos e entender" antes de mergulhar classe a classe no Javadoc/dartdoc.
Tudo abaixo é EXEMPLO: substitua pela realidade do seu app, mantendo a espinha
(retrato em 1 frase → organização → camadas → travas → por onde começar →
referência gerada). Apague os BLOCOS POR STACK que não forem o seu.
-->
# Guia do código
Audiência: dev que abriu o repositório e quer **passar os olhos e entender** como o
código está organizado, antes de mergulhar classe a classe. Para o *porquê* das
decisões, veja [`decisoes/`](../decisoes/0001-titulo-da-decisao.md); para o desenho
completo do sistema, a [Documentação Completa](../projeto/index.md); para
rodar/testar, [Como rodar](como-rodar.md).
> A árvore de classes navegável (Javadoc/dartdoc) fica em [`dev/api/`](api/index.md)
> **quando o app liga a geração** no job `docs` do `pipeline.yml` (opt-in). Ela é
> gerada a partir dos comentários do código, então acompanha o código; a narrativa
> abaixo é autorada. **App que não liga a geração apaga este bloco** — link para
> `dev/api/` sem o step no pipeline é 404 no site.
## O retrato em uma frase
<!-- 1–3 linhas + um diagrama do fluxo de dados (Mermaid). Diga o que o app É e
como o dado flui — o leitor deve sair daqui com o modelo mental do todo. -->
```mermaid
flowchart LR
Entrada --> Nucleo[Núcleo / regra] --> Saida
```
## Como o código é organizado
<!-- A tabela dos pacotes/pastas de topo: o nome, se é feature ou base, e a
responsabilidade. É o mapa de mais alto nível. -->
<!-- BLOCO JAVA (package-by-feature) — apague se não for Java -->
Organização **package-by-feature**: cada funcionalidade é um pacote de topo que
**carrega suas próprias camadas** (Controller → Service → Repository), em vez de
pastas globais `controller/`/`service/`. O compartilhado vive em `comum`.
| Pacote de topo | É | Responsabilidade |
|---|---|---|
| `processamento` | feature | a feature central do app |
| `comum` | base | transversal: config, exception, dto, util |
<!-- /BLOCO JAVA -->
<!-- BLOCO FLUTTER (feature-first) — apague se não for Flutter -->
Organização **feature-first**: cada tela/painel é um pacote sob `lib/features/`
que carrega suas camadas; o compartilhado vive em `lib/_shared/` e o núcleo
transversal em `lib/core/`.
| Topo | É | Responsabilidade |
|---|---|---|
| `lib/features/NNN_nome/` | features | uma tela/painel por pacote |
| `lib/_shared/` | base | widgets, services, models compartilhados |
| `lib/core/` | núcleo | router, database, theme, config |
<!-- /BLOCO FLUTTER -->
## As camadas
<!-- O fluxo de uma requisição/ação pelas camadas e a regra de fronteira (ex.: a
entidade não cruza o controller; a borda fala DTO/view-model). -->
## Travas de arquitetura
<!-- Se houver guarda de fronteiras de arquitetura no gate (um teste de fronteiras
no ./gradlew check; um script/teste de imports no Flutter), liste os invariantes
que ela guarda. Apague a seção se não houver. Engenharia: docs.xadm.biz/engenharia/ci-testes/ -->
## Por onde começar a ler
1. <!-- o entrypoint -->
2. <!-- o mapa de montagem / DI / rotas -->
3. <!-- uma feature ponta a ponta -->
## Referência completa
A árvore de classes navegável (**Javadoc/dartdoc**, interna) fica em
[`dev/api/`](api/index.md) **quando o app liga a geração** (opt-in no job `docs` do
`pipeline.yml`); aí ela sai a cada publish. Use-a quando precisar do detalhe de uma
classe; a narrativa acima é o atalho para achar por onde entrar. **Sem o step no
pipeline, apague esta seção** em vez de linkar uma pasta que o site não tem.
## Inventário das classes
<!-- OPCIONAL. O marcador abaixo é preenchido por UMA de duas vias (contrato em
padroes/publicar-docs.md): (a) um passo no job docs do pipeline.yml que substitui o marcador
no arquivo antes do build; ou (b) um hook do mkdocs do próprio app que o
preenche em on_page_markdown — neste caso liste-o ANTES do visao-tecnica.py em
hooks:, senão o hook central remove o marcador cru antes e o inventário some.
Sem nenhuma das vias, APAGUE este marcador e esta seção — o hook compartilhado
remove a linha no build, mas é mais honesto não prometer um inventário que não
existe. -->
<!-- GERADO: inventario -->
Modelo de dados (docs/projeto/modelagem.md)¶
O modelo consolidado do estado atual — schema do banco e/ou contrato dos
artefatos de saída/integração (JSON, payload), fonte da verdade (Convenções de doc).
Desenho primeiro: a implementação se gera a partir dele. É um arquivo, não um por etapa — a etapa
descreve o delta, o modelagem.md carrega o todo.
O meio — cada notação para o que faz bem:
- ER Mermaid só para o overview de relacionamentos (entidades, PK/UK), não para a lista de
colunas: o
erDiagramnão expressaNOT NULLnem chave composta e fica ilegível em tabela larga. - Dicionário por tabela em Markdown — toda coluna, em
Coluna | Tipo | Chave | Nulo? | Desde | Nota; chave composta, índices eCHECKem bullets abaixo da tabela. Contrato de dados usa a mesma forma, por campo. - Relacionamento sem FK física se anota como nota autoral.
- Fluxo de dados (flowchart) é opcional.
Sem frontmatter — fragmento embutido no livro por --8<--, com títulos a partir de ###.
Projeto com banco ou com contrato de dados é obrigado a tê-lo; toda etapa que evolui o modelo
evolui este arquivo no mesmo PR. O aviso de CI que cobra isso está em Publicar
docs.
<!--
TEMPLATE + GUIA — MODELO DE DADOS (docs/projeto/modelagem.md) — X-Adm
Modelo CONSOLIDADO do estado ATUAL (constituição, Convenções de doc): fonte da verdade do
**schema do banco E/OU do contrato dos artefatos de saída/integração** (JSON,
payload, formato de arquivo). Embutido na Documentação Completa (projeto/index.md)
via `--8<-- "projeto/modelagem.md"`. TODA mudança que evolui o modelo atualiza ESTE
arquivo no MESMO PR. SEM frontmatter (é fragmento embutido, não página solta).
NÍVEL DOS TÍTULOS: autore no NÍVEL DO EMBED (este arquivo entra sob um `##` do livro,
então começa em `###` — NÃO em `#`). Nada rebaixa headings (nem o snippets do site nem
o export .docx); um `#` viraria Título 1 no meio do livro e quebraria o sumário (constituição, Convenções de doc).
Projeto SEM banco mas COM contrato de saída: o erDiagram/dicionário descreve as
ENTIDADES/CAMPOS do artefato (ex. objeto do JSON), não tabelas — a mecânica é a mesma.
O MEIO (constituição, Convenções de doc) — use cada notação para o que ela faz bem:
• ER Mermaid = OVERVIEW de RELACIONAMENTOS (quem se liga a quem). Minimalista:
só PK/UK, não a lista de colunas. O erDiagram não expressa NOT NULL nem chave
composta e fica ilegível em tabela larga — não o use como dicionário.
• TABELA Markdown = DICIONÁRIO por tabela (toda coluna): Coluna | Tipo | Chave |
Nulo? | Desde | Nota. Chave composta, índices e CHECK vão em bullets abaixo.
• Fluxo de dados (flowchart) = OPCIONAL, quando ajuda a ver o caminho do dado.
Substitua o exemplo. Apague este comentário.
-->
O schema vive em PostgreSQL, versionado por Flyway (`V1..VN`; migration aplicada é
congelada — nunca editar, sempre uma nova). [Descreva aqui convenções de prefixo/
namespace se houver, ex. tabelas que sincronizam vs. locais.]
### Relacionamentos (overview)
```mermaid
erDiagram
upload ||--o{ fato : "produz no período"
upload {
bigserial id PK
text checksum UK
}
fato {
bigserial id PK
}
```
> **Sem FK física.** [Se for o caso] o vínculo é lógico (por período + UPSERT
> diff-aware), não por chave estrangeira — anote aqui o porquê.
### Fluxo de dados (opcional)
```mermaid
flowchart LR
origem[Origem] -->|entra| ingest[Recepção] --> tab[("tabela")]
```
### Dicionário por tabela
#### `fato` — [papel da tabela] · [sincroniza? local?]
| Coluna | Tipo | Chave | Nulo? | Desde | Nota |
|---|---|---|---|---|---|
| `id` | bigserial | PK | NOT NULL | V1 | |
| `valor` | numeric | | NOT NULL | V1 | |
| `dt` | date | | NOT NULL | V1 | |
| `placa` | varchar | | | V3 | desnormalizado |
- **Chave natural (UK)** `uq_fato_natural` — colunas `(...)` (`NULLS NOT DISTINCT`):
é a chave do UPSERT. *(o erDiagram não mostra chave composta — por isso vai aqui)*
- **Índices**: `dt`, `placa`.
- **CHECK** / regras: [se houver].
Mapeamento entrada↔dados (docs/projeto/mapeamento.md)¶
Fonte opcional do cap. 4 do livro: como o que entra (API, planilha, payload) vira
o que se guarda/emite — tabela "origem → destino + transformação". Sem frontmatter,
embutido por --8<-- (Convenções de doc).
<!--
TEMPLATE — MAPEAMENTO ENTRADA↔DADOS (docs/projeto/mapeamento.md) — X-Adm
Fonte OPCIONAL do cap. 4 do livro (constituição: Livro, Resumo e nav; Convenções de doc): como o que ENTRA (resposta de
API, planilha, payload) vira o que se GUARDA/EMITE (tabela, artefato de saída).
SEM frontmatter — fragmento embutido na Documentação Completa via
`--8<-- "projeto/mapeamento.md"`. Evolui no MESMO PR que muda o mapeamento.
Substitua o exemplo.
-->
Cada campo da origem e para onde vai no destino, com a transformação aplicada.
| Origem (campo) | Destino (campo) | Transformação | Obrigatório? | Nota |
|---|---|---|---|---|
| `api.cliente.nome` | `saida.nome` | trim | sim | |
| `api.cliente.cpf` | `saida.documento` | só dígitos | sim | |
| `api.valor` | `saida.total` | centavos → reais | sim | |
| `api.data` | `saida.dt` | ISO → `dd/MM/yyyy` | não | default hoje |
- **Descarte de linha/registro:** [quando uma entrada é ignorada e por quê].
- **Campos sem origem:** [calculados/constantes no destino, e como].
Arquivo-fato: o padrão dos snippets¶
modelagem.md e mapeamento.md acima não são "páginas menores" — são o padrão da casa
para um fato, um dono, várias leituras (Duas fontes da verdade). Um fato que mais de um documento
precisa mostrar (não só citar) vira arquivo próprio e os leitores o embutem;
o livro faz isso, e o runbook de implantação
também pode. O fato não é copiado — é incluído no build, e muda junto com o dono.
Convenção do arquivo-fato: sem frontmatter (é fragmento, não página), headings em
### (encaixam sob o ## de quem embute — nem o snippets no site nem o export_docx.py no .docx
rebaixam heading, então o nível escrito é o nível final, e um # viraria título 1 no meio do livro,
quebrando o aninhamento e o sumário), e declarado em exclude_docs: no
mkdocs.yml — senão vira órfã, com razão (não é página): o mkdocs build --strict
do app acusa (validation.nav.omitted_files no mkdocs.yml canônico), e o checa-nav.py
do central também.
exclude_docs:, não not_in_nav: — os dois calam o aviso de órfã, mas só o primeiro
tira do build. Com not_in_nav: o fragmento continua virando página: ganha um H1
inventado do nome do arquivo, fica alcançável por URL e entra na busca, devolvendo
o mesmo texto duas vezes (uma na página que o embute, outra na órfã). O --8<-- não se
importa — ele lê do disco, não do build. Quando a página que embute mora na mesma pasta dos
fatos, reincluia com !:
exclude_docs: |
/public/contratos/*.md
!/public/contratos/index.md
Transclui-se do arquivo-dono, nunca "da seção do livro": o livro é narrativa e ele próprio embute os fatos. E se dois leitores precisam de diagramas diferentes do mesmo sistema (a arquitetura para quem estuda, a topologia de rede para quem opera), são dois fatos — cada um com seu dono, nenhuma cópia. Reaproveitar o diagrama errado é pior que escrever o certo.
O --8<-- é processado antes do Markdown — inclusive dentro de bloco de código
O snippets é um pré-processador de linha: ele não sabe o que é bloco de código nem
comentário HTML. Um --8<-- sozinho na linha transclui nos dois — é por isso que as
fichas desta página conseguem exibir os templates dentro de ```markdown, e é a mesma
razão pela qual documentar a sintaxe descuidadamente transclui de verdade.
Para mostrar o marcador em vez de executá-lo, escape com ; no início
(;--8<-- "arquivo.md") ou deixe-o inline com crases — texto antes na linha já
basta para não casar. E com check_paths: true (o nosso), snippet apontando arquivo
inexistente falha o build com SnippetMissingError: crie o arquivo-fato antes
de referenciá-lo. Falha ruidosa, de propósito — o oposto de um embed que some calado.
Diagramas (Mermaid)¶
- Mermaid inline; PlantUML (
.puml) só quando o Mermaid não dá conta. Comite a fonte do diagrama, nunca o SVG ou PNG renderizado (a exceção é a figura autoral, abaixo). - Fluxograma em
TB(vertical) por padrão. A página tem largura fixa e rolagem vertical: emTBcada linha usa a largura toda e o texto fica legível sem zoom; emLRo diagrama cresce na horizontal, aperta as caixas e força rolagem lateral. Use labels curtos edirection TBtambém dentro dossubgraph.LR/RLsó para pipeline curto e linear. - O CI de docs linta cada bloco (
lint-mermaid.mjs,mermaid.parseheadless). Diagrama com erro de sintaxe renderiza cru e passa pelo--strict, então o lint falha o build, como link quebrado. FlowchartLR/RLcom mais de 6 caixas também falha, pedindoTB; se for mesmo um pipeline curto que cabe, marque o bloco com o comentário%% lint-mermaid: LR-ok.
Figura autoral em SVG (quando o Mermaid não basta)¶
Mermaid é o default (Convenções de doc): fonte versionável, lint no CI, zero manutenção de
pixel. A exceção é a figura de capa — o poster que precisa caber numa tela de
diretoria (composição em grid, rowspan, mockups, legenda), layout que o motor automático
do Mermaid não entrega por design: lá a posição é do motor, nunca sua. Exemplo vivo
deste padrão: a topologia da integração
(docs/assets/topologia-integracao.svg).
A receita — cada item fecha uma armadilha de embed ou de manutenção:
- O SVG é a fonte (autorado à mão), vive em
docs/assets/<nome>.svg. A regra "nunca comitar o render" não se aplica: não há render, há autoria. - Mermaid-base obrigatório, junto. Um bloco
mermaidcom os mesmos nós e arestas, em admonition colapsado (??? info "Fonte da figura (Mermaid-base)"— requerpymdownx.details) logo abaixo da figura. É a fonte semântica: mudou a topologia, atualize o base PRIMEIRO e espelhe no SVG — a ordem vai em comentário no cabeçalho do próprio SVG. Olint-mermaidcontinua cobrindo o base (fence indentado é pego). - Wrapper
<div>e zero linha em branco. O arquivo abre com<div class="...">e fecha com</div>, sem nenhuma linha em branco no meio: o python-markdown não conhece<svg>como tag de bloco — sem o<div>, ou com linha em branco, ele fatia o SVG em<p>e a figura não aparece (DOM quebrado, verde em todos os gates). - Embutir via
--8<--, não<img>. Inline herda a tipografia da página (Inter); via<img>o SVG externo não carrega a webfont e cai no fallback. <style>só com classes prefixadas (ex..topo-*). SVG inline vira parte do documento — CSS sem prefixo vaza para o site inteiro.- Responsivo:
viewBox+style="max-width:…;width:100%;height:auto"no<svg>; nuncawidth/heightfixos. - Paleta e tipografia da casa: tokens do
xadm.css(royal#064490, accent#2a5b97, light#7092bb, dark#042c5e, prata#939495), Inter. Setas via<marker>reutilizável; convenção: cheia = fluxo de dados, tracejada = integração interna (a mesma da legenda). - Legenda embutida no rodapé da figura — o leitor de poster não lê a prosa ao lado.
- Ponto cego, declarado: nenhum gate valida o SVG em si — o build aceita qualquer
XML bem-formado e o
checa-admonitionnão olha desenho. Quem garante a figura é o olho de quem edita; por isso o Mermaid-base lintado é obrigatório, não decorativo.
Riscos consolidados — opcional (docs/riscos.md)¶
Página transversal para quando a diretoria/ops quer todos os riscos numa
página em vez de abrir cada projeto. Consolida por link a seção "Riscos"
de cada doc de projeto — não a substitui: o dono de cada risco é o doc de projeto, e esta página é
índice (Duas fontes da verdade). Adicione ao nav para aparecer.
---
titulo: "Riscos do projeto (visão consolidada)"
atualizado: 2026-06-13
---
<!--
TEMPLATE OPCIONAL — RISK REGISTER TRANSVERSAL — X-Adm
Copie para docs/riscos.md (raiz de docs/, NÃO em projeto/) no repo do app.
Página opcional: use quando a diretoria/ops quer "a lista de riscos numa página"
em vez de abrir cada etapa. Sem ela, os riscos vivem na seção "Riscos" de cada
doc de etapa do projeto — esta página NÃO substitui aquelas, ela as CONSOLIDA.
Fonte única (constituição, Duas fontes da verdade): o dono de cada risco é o doc de projeto; aqui
é índice. Mantenha por link, evite duplicar a descrição inteira. Se preferir
automação, use pymdownx.snippets para incluir a seção de riscos de cada etapa.
Frontmatter mínimo (página transversal, não é um dos seis níveis — o validador
não a cobra): titulo + atualizado. Para aparecer, adicione ao nav do mkdocs.yml
e/ou linke da home. Apague este comentário e o exemplo ao preencher.
-->
# Riscos do projeto
Visão consolidada dos riscos abertos. O detalhe e a mitigação de cada um vivem na
seção **Riscos** do doc de projeto indicado.
| Risco | Severidade | Projeto | Mitigação (resumo) |
|---|---|---|---|
| Planilhas fora do layout esperado | Média | [01 — Importação](projeto/01-importacao-frota.md) | Validação por linha; nunca falha o lote inteiro |
| Volume acima do estimado (>50k linhas) | Baixa | [01 — Importação](projeto/01-importacao-frota.md) | Processamento em batches |
| Vazamento do token de API | Alta | [02 — Integração API](projeto/02-integracao-api.md) | Bearer rotacionável; nunca logado |
> Severidade é leitura de diretor — ordene por ela. Risco fechado sai da tabela
> (o histórico fica no Git e no doc de projeto).
Página pública da API — OpenAPI/Swagger (docs/public/api/index.md)¶
Embute o Swagger UI a partir do openapi.yaml gerado pelo CI de docs do
código (Níveis de documentação). Só para apps que expõem API.
<!--
TEMPLATE — PÁGINA PÚBLICA DA API (OpenAPI/Swagger) — X-Adm
Copie para docs/public/api/index.md no repo do app (constituição, Convenções de doc: o contrato
de API é PÚBLICO — vive em docs/public/).
O spec OpenAPI (openapi.yaml) é GERADO PELO CI DE DOCS a partir do código (não do
app deployado) e copiado para docs/public/api/openapi.yaml ANTES do build — ver
o passo "Gerar referência de API" no job docs do pipeline.yml. O arquivo gerado é .gitignore.
A tag abaixo (plugin mkdocs-swagger-ui-tag) embute o Swagger UI a partir do spec.
src é relativo a esta página. Apague este comentário e ajuste o texto.
O frontmatter NÃO é opcional aqui: página pública é página (governança por
documento). Quem consome um contrato precisa justamente do que o cabeçalho mostra —
`atualizado:` diz se o contrato está vivo, `status:` se dá para confiar nele, e
`responsavel:` a quem perguntar. O hook frontmatter-cabecalho.py renderiza isso no
corpo da página; ele expõe o NOME do responsável, nunca o e-mail.
-->
---
titulo: "API REST — contrato público"
tipo: dev
status: aprovado
responsavel: "Nome <email@xadm.com.br>"
modulo: "..."
atualizado: AAAA-MM-DD
tags: [api, contrato, rest]
---
# API REST — contrato público
Esta é a referência pública da API: endpoints, parâmetros, exemplos. Para
**experimentar ao vivo** (com seu ambiente), o app também serve `/swagger-ui` em
runtime; a **fonte publicada** da doc é esta página, gerada do código no pipeline.
## Como autenticar
A escrita exige um token Bearer (`Authorization: Bearer <token>`); as leituras
são públicas. Peça o token à equipe X-Adm.
## Referência
<swagger-ui src="openapi.yaml"/>
README de anexos públicos (docs/anexos/README.md)¶
# Anexos públicos
Tudo nesta pasta é **publicado no portal de documentação**
([docs.xadm.biz](https://docs.xadm.biz)) junto com o site deste app —
colocar um arquivo aqui é **decidir torná-lo público**.
Pode morar aqui: PDF de apoio, imagem, exemplo de arquivo em formato não-barrado
(ex. `.md`, `.json` com dados fictícios).
**Não** pode: dado real de cliente, credencial, massa de dados de produção — e nenhuma
planilha/dump/banco (`.xlsx/.csv/.sql/...`), **mesmo com dados fictícios**: o CI barra
essas extensões em todo `docs/` fora de `privado/` (o mkdocs publicaria o arquivo),
então modelo de planilha para download não mora aqui. O confidencial vai na subpasta
`privado/` (segmento reservado, **sempre** fora do build e do portal; veja o README
dela no repo).
Padrão: [constituição, Convenções de doc — "Anexos"](https://docs.xadm.biz/documentacao/constituicao/#convencoes)
README de anexos confidenciais (docs/anexos/privado/README.md)¶
# Anexos confidenciais — NÃO publicados
Nada desta pasta sai no portal de documentação: o `mkdocs.yml` exclui a
pasta do build (`exclude_docs`), o CI falha se ela aparecer no site e o
portal central recusa servir o caminho. Os arquivos ficam **versionados no
Git** e acessíveis só a quem tem login no Forgejo.
Pode morar aqui: insumo real do projeto — ex. a planilha-base com dados
reais do cliente que fundou o pré-projeto.
Para citar um destes arquivos numa página pública, use o link do Forgejo
(`https://fonte.xadm.biz/xadm/<repo>/src/branch/<branch>/docs/anexos/privado/<arquivo>`)
sempre com a nota: **"Arquivo confidencial — acesso restrito à equipe"**.
Padrão: [constituição, Convenções de doc — "Anexos"](https://docs.xadm.biz/documentacao/constituicao/#convencoes)
mkdocs.yml canônico do app¶
# mkdocs.yml de app — destino: raiz do repo; troque <app> pelo slug (é o ID público, para sempre).
# Fonte: https://fonte.xadm.biz/xadm/documentacao (templates/mkdocs.yml) · padrão: https://docs.xadm.biz/padroes/publicar-docs/
site_name: <app>
site_url: https://docs.xadm.biz/aplicacoes/<app>/
theme:
name: material
language: pt-BR
# Copie templates/overrides-main.html para overrides/main.html (aviso de versão antiga, decisão 0004).
custom_dir: overrides
palette:
primary: custom
accent: custom
features:
- navigation.sections
- navigation.path # breadcrumbs: "onde estou" ao chegar via busca
- navigation.footer # Anterior/Próximo: ler como livro
- search.suggest
- search.highlight
extra:
homepage: https://docs.xadm.biz/
# Seletor de versão da doc versionada por release (decisão 0004).
version:
provider: mike
# Copie templates/xadm.css para docs/stylesheets/xadm.css.
extra_css:
- stylesheets/xadm.css
# Uma única chave `exclude_docs`: YAML repetido sobrescreve em silêncio e apagaria a exclusão do `privado/`.
# `privado/` nunca sai no site; arquivo-fato vai aqui, não em `not_in_nav` (que ainda o builda como página).
exclude_docs: |
privado/
/_importado/**
/public/contratos/*.md
!/public/contratos/index.md
# O job docs do pipeline.yml baixa estes hooks do central: tirar um daqui exige tirar o download de lá.
hooks:
- scripts/frontmatter-cabecalho.py
# Injeta Resumo e changelog no livro e falha o build em <!-- RECONCILIAR --> não resolvido.
- scripts/visao-tecnica.py
plugins:
- search:
lang: pt
# Só se o app expõe API: docs/public/api/index.md embute o openapi.yaml.
- swagger-ui-tag
# Slug publicado renomeado exige redirect: descomente e mapeie o arquivo antigo para o novo.
# - redirects:
# redirect_maps:
# antigo.md: novo.md
# Tem de ser o último plugin: fora de ordem o print-site quebra o `mkdocs build --strict`.
- print-site:
add_to_navigation: true
print_page_title: "Tudo numa página"
# A API gerada (Javadoc/dartdoc) sai no site, só fora do índice.
not_in_nav: |
/dev/api/**
# Órfã do nav e link para fora de docs/ viram erro no `--strict` (o default do MkDocs é só INFO).
validation:
nav:
omitted_files: warn
links:
not_found: warn
markdown_extensions:
- admonition
- attr_list
- def_list # o glossário usa
- tables
- toc:
permalink: true
# O caminho do --8<-- é relativo a docs/ (ex. "projeto/modelagem.md").
- pymdownx.snippets:
base_path: ["docs", "."]
check_paths: true
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
# Ordem normativa: Resumo → Mudanças → Pré-projeto → Projeto → Operação → Dev → Público → Etapas → Decisões → Glossário.
# Mantenha só as seções que existem; descomente ao criar o conteúdo.
nav:
- Resumo Executivo: index.md # porta do diretor: problema e como resolve, sem jargão
- Mudanças: changelog.md # crie docs/changelog.md a partir de templates/changelog.md
# - Pré-projeto: # docs/pre-projeto/ — nível 1, antes de decidir construir
# - Estudo de caso: pre-projeto/estudo-de-caso.md
- Projeto: # a especificação: o desenho do sistema no estado atual
- Documentação Completa: projeto/index.md # o livro autorado; embute projeto/modelagem.md via --8<--
# - Requisitos / spec: projeto/requisitos.md
# projeto/modelagem.md é embutido no livro — sem entrada própria.
# - Operação: # docs/operacao/ — runbooks técnicos (nível 5)
# - Runbook Y: operacao/runbook-y.md
# - Dev / API: # docs/dev/ — para quem mexe no código (nível 4)
# - Guia do código: dev/guia-do-codigo.md # narrativa autorada da organização do código
# - Mapa do código: dev/index.md # linke a API gerada em Markdown normal: [API Reference](api/index.html)
# - Público: # docs/public/ — aberto
# - Visão geral: public/index.md
# - Manual:
# - Como fazer X: public/manual/como-fazer-x.md
# - API (contrato): public/api/index.md # embute o OpenAPI via swagger-ui-tag
# - Etapas do Projeto: # docs/projeto/NN-*.md — a execução, etapa a etapa (≠ Projeto, que é o desenho)
# - 01 — Primeira etapa: projeto/01-primeira-etapa.md
# - Decisões:
# - 0001 — Título da decisão: decisoes/0001-titulo-da-decisao.md
- Glossário do projeto: glossario.md
Identidade visual (docs/stylesheets/xadm.css)¶
Fonte única da identidade X-Adm (azul royal #064490 + prata #939495,
derivados do logo real; links de conteúdo identificáveis). Copie verbatim para
docs/stylesheets/xadm.css; o mkdocs.yml já referencia em extra_css. Mudança
visual se faz aqui no central e re-deriva nos apps — não edite o CSS por app.
/* Identidade X-Adm do MkDocs Material — destino: docs/stylesheets/xadm.css; não edite por app, re-derive do central. */
:root {
--md-primary-fg-color: #064490;
--md-primary-fg-color--light: #7092bb;
--md-primary-fg-color--dark: #042c5e;
--md-accent-fg-color: #2a5b97;
--md-accent-fg-color--transparent: rgba(42, 91, 151, 0.1);
--xadm-silver: #939495;
--xadm-silver-light: #e2e6eb;
}
/* Link no corpo ganha accent e sublinhado: o Material não sublinha, e o azul da marca se confunde com o texto. */
.md-typeset a:not(.headerlink) {
color: var(--md-accent-fg-color);
text-decoration: underline;
text-underline-offset: 0.15em;
}
.md-typeset a:not(.headerlink):hover {
text-decoration: underline;
}
Kit de UI para apps server-render (opcional)¶
App que renderiza HTML no servidor (Micronaut Views/JTE) — telas de admin/ops/dev,
inclusive internas e atrás do gate de auth — usa o layout padrão X-Adm em vez de
reinventar o visual (Engenharia, decisões 0010 e 0025). O kit — layout.jte +
headerRight.jte, o paginador pager.jte, custom-theme.css (mesma paleta do xadm.css), logo.png, favicon.ico e o
Bootstrap vendorizado — é template rastreado opcional (app headless/Flutter não o instala).
A tela de login não está aqui: ela é servida pela lib xadm-seguranca, e o app a configura por
property em vez de copiar view. Receita, mapeamento de
destino e snippet de static-resources em
Java/Micronaut §UI.
Workflow de CI/CD — pipeline.yml (.github/workflows/pipeline.yml)¶
O workflow único de CI/CD do app no GitHub Actions (decisão 0027):
um job decide liga gate (análise estática + testes da stack, definição de pronto;
na tag, o último step é o contrato de release, valida-release.py) / docs (mkdocs → Garage, OpenAPI
opt-in; na tag, só com gate verde) / build_jar|native|web / deploy (control-plane; termina no smoke). À la carte por evento (push/PR por path — docs-only publica sem binário; tag = release,
com os alvos do trailer Deploy: do anotado, fallback app.json build.targets;
workflow_dispatch = checkboxes). 3 variantes opt-in por app.json build.targets; descomente a da sua stack,
apague as outras. O job deploy chama o control-plane (POST /api/ci/deploy,
decisão 0026), que dispara o recurso no Coolify. Aviso de
falha = notificação nativa do GitHub (email).
# pipeline.yml — CI/CD do repo em GitHub Actions — template canônico (decisão 0027).
# Copie para .github/workflows/pipeline.yml. Fonte: https://fonte.xadm.biz/xadm/documentacao (templates/pipeline.yml)
# Jobs, eventos e à la carte: docs.xadm.biz/engenharia/ci-testes (CI de código).
#
# COMO ADAPTAR
# 1. Troque <slug> no env IMAGE (nome da imagem no registry = slug do app.json).
# 2. native (padrão no build.targets do docs/app.json): gate-Java, build_native e o step "Deploy native".
# 3. native + jar: acrescente build_jar e o step "Deploy jar" (jar declarado com motivo).
# 4. só jar: build_jar e "Deploy jar"; apague build_native (bloqueio de native registrado em ADR do app).
# 5. Flutter web: gate-Flutter, build_web e "Deploy web"; apague build_jar, build_native e o gate-Java com as guardas.
# 6. Tire do `needs:` do deploy os jobs de build apagados; no `decide`, mantenha só as flags e filtros da variante.
# 7. docs: descomente o bloco OpenAPI só se o app é dono de contrato REST.
# 8. Secrets (engenharia/seguranca): DOCS_S3_ENDPOINT/ACCESS_KEY/SECRET_KEY, CENTRAL_DEPLOY_TOKEN, FORGEJO_USER/FORGEJO_TOKEN.
# 9. Smoke: GLITCHTIP_API_TOKEN, SMOKE_TOKEN, SMOKE_M2M_TOKEN; app cliente offline: RELEASE_TOKEN.
# 10. Flutter: secret SENTRY_AUTH_TOKEN (upload de sourcemap, degradável; destino, org e projeto vêm do docs/app.json).
name: pipeline
on:
push:
branches: [master]
tags: ['v*']
pull_request:
workflow_dispatch:
inputs: # à la carte — mantenha só os da sua variante
tests: { description: 'rodar testes (gate)', type: boolean, default: true }
docs: { description: 'buildar+publicar docs', type: boolean, default: false }
jar: { description: 'buildar+deployar jar', type: boolean, default: false } # Java
native: { description: 'buildar+deployar native', type: boolean, default: false } # Java native
web: { description: 'buildar+deployar web', type: boolean, default: false } # Flutter
permissions:
contents: read
packages: write
# Tag não cancela: release é imutável.
concurrency:
group: pipeline-${{ github.ref }}
cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
env:
IMAGE: fonte.xadm.biz/xadm/<slug> # <- troque <slug>
CENTRAL_DEPLOY_URL: https://central-backend.xadm.biz/api/ci/deploy # flavor-agnóstico (não -jar)
jobs:
# === DECIDE — calcula as flags que ligam cada job; mantenha só as da sua variante ===
decide:
# commit de release no master: a tag empurrada junto roda o release; job pulado por if: não é cobrado.
if: ${{ !(github.ref == 'refs/heads/master' && startsWith(github.event.head_commit.message, 'chore(release)')) }}
runs-on: ubuntu-latest
outputs:
tests: ${{ steps.f.outputs.tests }}
docs: ${{ steps.f.outputs.docs }}
jar: ${{ steps.f.outputs.jar }} # Java
native: ${{ steps.f.outputs.native }} # Java native
web: ${{ steps.f.outputs.web }} # Flutter
docs_only: ${{ steps.f.outputs.docs_only }} # master docs-only (docs && !code) → republica a vigente
java: ${{ steps.tc.outputs.java }}
flutter: ${{ steps.tc.outputs.flutter }}
# bloco smoke do app.json, lido uma vez aqui e usado pelo pre-deploy (alvo do rollback) e pelo smoke.
smoke: ${{ steps.sm.outputs.smoke }}
smoke_enabled: ${{ steps.sm.outputs.enabled }}
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 } # tags + histórico: o decide lê o trailer `Deploy:` do anotado (%(contents:body))
- uses: dorny/paths-filter@v3
id: ch
with:
filters: |
code:
# VARIANTE Java: VARIANTE Flutter:
- 'src/**' # - 'lib/**'
- '**/build.gradle*' # - 'test/**'
- 'gradle/**' # - 'web/**'
- 'settings.gradle*' # - 'pubspec.*'
- 'Dockerfile*' # - '.fvmrc'
- '.github/workflows/**' # - 'Dockerfile*'
# - '.github/workflows/**'
docs:
- 'docs/**'
- 'mkdocs.yml'
- id: f
env:
EV: ${{ github.event_name }}
IN_TESTS: ${{ inputs.tests }}
IN_DOCS: ${{ inputs.docs }}
IN_JAR: ${{ inputs.jar }}
IN_NATIVE: ${{ inputs.native }}
IN_WEB: ${{ inputs.web }}
CODE: ${{ steps.ch.outputs.code }}
DOCSCHG: ${{ steps.ch.outputs.docs }}
run: |
set -e
T=false; D=false; J=false; N=false; W=false; DO=false
if [ "$EV" = "workflow_dispatch" ]; then
T=$IN_TESTS; D=$IN_DOCS; J=$IN_JAR; N=$IN_NATIVE; W=$IN_WEB
elif [ "${GITHUB_REF}" != "${GITHUB_REF#refs/tags/v}" ]; then
# tag = release: docs sempre; binário do trailer Deploy: da tag anotada, senão do build.targets.
T=true; D=true
dep=$(git for-each-ref "refs/tags/${GITHUB_REF#refs/tags/}" --format='%(contents:body)' 2>/dev/null \
| grep -iE '^Deploy:' | head -1 | sed -E 's/^[Dd]eploy:[[:space:]]*//' | tr -d '[:space:]')
if [ -z "$dep" ]; then
dep=$(python3 -c "import json;print(','.join(json.load(open('docs/app.json')).get('build',{}).get('targets',[])))" 2>/dev/null || true)
fi
case ",$dep," in *,jar,*) J=true ;; esac
case ",$dep," in *,native,*) N=true ;; esac
case ",$dep," in *,web,*) W=true ;; esac
echo "trailer/fallback Deploy: '$dep'"
else
[ "$CODE" = "true" ] && T=true
[ "$DOCSCHG" = "true" ] && D=true
# docs-only: o job docs republica também a versão vigente
[ "$DOCSCHG" = "true" ] && [ "$CODE" != "true" ] && DO=true
fi
if [ "$EV" = "workflow_dispatch" ] && [ "$T" != "true" ] \
&& { [ "$J" = "true" ] || [ "$N" = "true" ] || [ "$W" = "true" ]; }; then
echo "::warning::dispatch sem testes com alvo de deploy: o build roda, o DEPLOY sai pulado (deploy só com gate verde)"
echo "Deploy pulado: dispatch sem testes — deploy só com gate verde." >> "${GITHUB_STEP_SUMMARY:-/dev/null}"
fi
{ echo "tests=$T"; echo "docs=$D"; echo "jar=$J"; echo "native=$N"; echo "web=$W"; echo "docs_only=$DO"; } >> "$GITHUB_OUTPUT"
echo "flags: tests=$T docs=$D jar=$J native=$N web=$W docs_only=$DO (evento=$EV ref=$GITHUB_REF)"
- id: sm
run: |
python3 - <<'PY' >> "$GITHUB_OUTPUT"
import json
try:
bloco = json.load(open("docs/app.json", encoding="utf-8")).get("smoke")
except Exception:
bloco = None
ok = isinstance(bloco, dict) and bloco.get("bases") and bloco.get("routes")
print("enabled=" + ("true" if ok else "false"))
print("smoke=" + (json.dumps(bloco, separators=(",", ":")) if ok else "{}"))
PY
# versão de CI vem do app.json (fonte única, 0027); ausente sai vazia e o setup-java/flutter-action falha alto.
- id: tc
run: |
python3 - <<'PY' >> "$GITHUB_OUTPUT"
import json
try:
t = json.load(open("docs/app.json", encoding="utf-8")).get("toolchain") or {}
except Exception:
t = {}
print("java=" + str(t.get("java", "")))
print("flutter=" + str(t.get("flutter", "")))
PY
# === GATE — análise estática + testes; descomente a variante da sua stack e apague a outra ===
# ── VARIANTE Java (Micronaut/Gradle) ───────────────────────────────────────
gate:
needs: decide
if: needs.decide.outputs.tests == 'true'
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- uses: actions/setup-java@v5
with: { distribution: temurin, java-version: '${{ needs.decide.outputs.java }}' } # docs/app.json toolchain.java
- uses: gradle/actions/setup-gradle@v4
- name: Doc no índice (nav-drift)
run: |
curl --connect-timeout 10 --max-time 60 -fsSL https://docs.xadm.biz/padroes/checa-nav.py -o checa-nav.py
python3 checa-nav.py
# divergir do app.json builda com uma versão e testa com outra, em silêncio — guarda idêntica nas duas variantes.
- name: Toolchain do app.json x .fvmrc e FROM do Dockerfile
run: |
python3 - <<'PY'
import glob, json, os, re, sys
try:
tool = json.load(open("docs/app.json", encoding="utf-8")).get("toolchain") or {}
except Exception:
sys.exit(0) # sem app.json legivel: o valida-frontmatter cobra
achados = []
fl = str(tool.get("flutter") or "")
if fl and os.path.exists(".fvmrc"):
try:
v = str(json.load(open(".fvmrc", encoding="utf-8")).get("flutter") or "")
except Exception:
v = ""
if v and v != fl:
achados.append(".fvmrc flutter=" + v + " x app.json toolchain.flutter=" + fl)
jv = str(tool.get("java") or "").split(".")[0]
for df in sorted(glob.glob("Dockerfile*")):
args = {}
for n, raw in enumerate(open(df, encoding="utf-8", errors="ignore"), 1):
linha = raw.split("#", 1)[0]
a = re.match(r"\s*ARG\s+(\w+)=(\S+)", linha, re.I)
if a:
args[a.group(1)] = a.group(2).strip("\"'")
continue
# FROM img:${VAR} usa o default do ARG declarado antes no mesmo Dockerfile
linha = re.sub(r"\$\{(\w+)\}|\$(\w+)", lambda v: args.get(v.group(1) or v.group(2), v.group(0)), linha)
m = re.match(r"\s*FROM\s+(\S+)", linha, re.I)
if not m:
continue
nome, _, tag = m.group(1).lower().partition(":")
tag = tag.split("@", 1)[0]
if jv and tag and (re.search(r"temurin|graalvm|native-image|openjdk", nome) or "jdk" in tag):
v = re.search(r"jdk-?(\d+)", tag) or re.match(r"(\d+)", tag)
if v and v.group(1) != jv:
achados.append(df + ":" + str(n) + ": " + m.group(1) + " x app.json toolchain.java=" + jv)
if fl and tag and "flutter" in nome:
v = re.match(r"(\d+\.\d+\.\d+)", tag)
if v and v.group(1) != fl:
achados.append(df + ":" + str(n) + ": " + m.group(1) + " x app.json toolchain.flutter=" + fl)
if achados:
print("::error::versao de toolchain diverge do docs/app.json (fonte unica, decisao 0027):")
for a in achados:
print(" " + a)
sys.exit(1)
PY
# settings.local.json é pessoal (grants, caminhos de máquina, às vezes credencial) — idêntica nas duas variantes.
- name: settings.local.json fora do git
run: |
python3 - <<'PY'
import subprocess, sys
try:
r = subprocess.run(["git", "ls-files", "--", ".claude/settings.local.json"],
capture_output=True, text=True, check=True)
except Exception:
sys.exit(0) # sem git: nada a conferir
if r.stdout.strip():
print("::error::.claude/settings.local.json esta versionado — e pessoal. Rode "
"`git rm --cached .claude/settings.local.json`, ponha no .gitignore e, se ele "
"tinha credencial, rotacione.")
sys.exit(1)
PY
- name: Placeholder do Micronaut (aninhado / default com dois-pontos)
run: |
python3 - <<'PY'
import glob, re, sys
gradle = "".join(open(f, encoding="utf-8", errors="ignore").read()
for f in glob.glob("**/build.gradle*", recursive=True))
if "micronaut" not in gradle.lower():
sys.exit(0)
# dir de build guarda copias do src: rodando local, a guarda reprovaria artefato velho
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
nested = re.compile(r"\$\{[^}]*\$\{")
ph = re.compile(r"\$\{([^{}]*)\}")
aninhado, esquema, cascata = [], [], []
for pat in ("application*.yml", "application*.yaml", "application*.properties"):
for f in fontes(f"**/{pat}"):
for n, raw in enumerate(open(f, encoding="utf-8", errors="ignore"), 1):
line = re.sub(r"(?:^|\s)#.*$", "", raw)
if nested.search(line):
aninhado.append(f"{f}:{n}: {raw.strip()}")
continue
# ':' sem crases no default e re-parseado (URL perde o esquema); cascata ${A:B:padrao} so avisa
for expr in ph.findall(line):
if "`" in expr or ":" not in expr:
continue
default = expr.split(":", 1)[1]
if "://" in default:
esquema.append(f"{f}:{n}: {raw.strip()}")
elif ":" in default:
cascata.append(f"{f}:{n}: {raw.strip()}")
for c in cascata:
print("::warning::Default com dois-pontos nao escapado (cascata de propriedade?) - se for valor literal, use crases: " + c)
if aninhado:
print("::error::Placeholder aninhado no application.yaml - Micronaut NAO aninha")
for b in aninhado: print(" " + b)
if esquema:
print("::error::Default com URL sem crases - o Micronaut re-parseia o default e o esquema SOME; use ${VAR:`https://...`}")
for e in esquema: print(" " + e)
if aninhado or esquema:
sys.exit(1)
PY
- name: serde-api sem runtime (Micronaut)
run: |
python3 - <<'PY'
import glob, sys
g = "".join(open(f, encoding="utf-8", errors="ignore").read()
for f in glob.glob("**/build.gradle*", recursive=True)).lower()
if "micronaut" not in g or "micronaut-serde-api" not in g:
sys.exit(0)
impls = ("micronaut-serde-jackson", "micronaut-serde-bson",
"micronaut-serde-oracle-jdbc", "micronaut-serde-jsonp")
if any(i in g for i in impls):
sys.exit(0)
boots = any("micronauttest" in open(f, encoding="utf-8", errors="ignore").read().lower()
for f in glob.glob("**/src/test/**/*.java", recursive=True)
+ glob.glob("**/src/test/**/*.kt", recursive=True))
if not boots:
sys.exit(0)
print("::error::micronaut-serde-api sem impl de runtime + @MicronautTest sobe contexto")
sys.exit(1)
PY
- name: POI em app native (Micronaut)
run: |
python3 - <<'PY'
import glob, json, os, re, sys
try:
alvos = (json.load(open("docs/app.json", encoding="utf-8")).get("build") or {}).get("targets") or []
except Exception:
alvos = []
if "native" not in alvos:
sys.exit(0) # nao e native
bad = []
for f in glob.glob("**/build.gradle*", recursive=True):
for n, raw in enumerate(open(f, encoding="utf-8", errors="ignore"), 1):
line = re.sub(r"//.*$", "", raw).strip()
if "poi-ooxml" not in line: continue
cfg = re.match(r"([A-Za-z]+)", line)
if cfg and cfg.group(1).startswith("test"): continue
bad.append(f"{f}:{n}: {raw.strip()}")
if bad:
print("::error::poi-ooxml em escopo nao-test num app NATIVE — use fastexcel-reader (0023)")
for b in bad: print(" " + b)
sys.exit(1)
PY
- name: JTE native reflect-config completo (Micronaut)
run: |
python3 - <<'PY'
import glob, json, os, subprocess, sys
# templates JTE carregam por reflexao: fora do reflect-config, a view some so no native (404)
g = "".join(open(f, encoding="utf-8", errors="ignore").read()
for f in glob.glob("**/build.gradle*", recursive=True))
gl = g.lower()
if "micronaut" not in gl or ("micronaut-views-jte" not in gl and "gg.jte" not in gl):
sys.exit(0) # nao e app JTE
try:
alvos = (json.load(open("docs/app.json", encoding="utf-8")).get("build") or {}).get("targets") or []
except Exception:
alvos = []
if "native" not in alvos:
sys.exit(0) # JTE mas nao native -> sem poda AOT
if "NativeResourcesExtension" not in g:
print("::error::App JTE+native SEM jteExtension('gg.jte.nativeimage.NativeResourcesExtension').")
print(" A lista de reflect-config das templates DRIFTA -> view nova = 404 so no native.")
print(" Adicione a extensao + jteGenerate('gg.jte:jte-native-resources:<versao>'). Ver java-micronaut UI/JTE.")
sys.exit(1)
# rodada local no Windows: gradlew.bat via cmd, com caminho explicito (a pasta atual pode nao estar na busca)
gradlew = ["cmd", "/c", "." + chr(92) + "gradlew.bat"] if os.name == "nt" else ["./gradlew"]
subprocess.run(gradlew + ["generateJte", "--console=plain", "--no-daemon"], check=True)
gen = set()
for f in glob.glob("build/generated-sources/jte/gg/jte/generated/precompiled/**/*.java", recursive=True):
f = f.replace(chr(92), "/")
rel = f.split("generated-sources/jte/")[1].rsplit(".java", 1)[0]
gen.add(rel.replace("/", "."))
cfg = set()
for f in glob.glob("build/generated-resources/jte/META-INF/native-image/**/reflection-config.json", recursive=True):
for e in json.load(open(f, encoding="utf-8")):
cfg.add(e["name"])
missing = sorted(gen - cfg)
if missing:
print("::error::reflection-config JTE nao cobre todas as *Generated (view podada no native):")
for m in missing: print(" " + m)
sys.exit(1)
print(f"JTE native reflect-config OK: {len(gen)} templates cobertos")
PY
- name: Paridade Dockerfile/Dockerfile.native (dirs app-writable)
run: |
python3 - <<'PY'
import os, re, sys
jvm, nat = "Dockerfile", "Dockerfile.native"
if not (os.path.exists(jvm) and os.path.exists(nat)):
sys.exit(0)
def app_dirs(path):
dirs = set()
for raw in open(path, encoding="utf-8", errors="ignore"):
line = raw.split("#", 1)[0]
if re.match(r"\s*(COPY|ADD)\b", line, re.I): continue
if "mkdir" not in line and "chown" not in line: continue
for m in re.findall(r"/app/[^\s\"';&|)]+", line):
dirs.add(m.rstrip("/"))
return dirs
j, n = app_dirs(jvm), app_dirs(nat)
if j != n:
print("::error::Dockerfile e Dockerfile.native divergem nos dirs app-writable sob /app")
if j - n: print(" So no " + jvm + ": " + ", ".join(sorted(j - n)))
if n - j: print(" So no " + nat + ": " + ", ".join(sorted(n - j)))
sys.exit(1)
PY
- name: Reaper de PID1 no ENTRYPOINT (tini)
run: |
python3 - <<'PY'
import json, os, re, sys
# 1o elemento do ENTRYPOINT exec e init de PID1; shell-form ou ausente e pulado (ponto cego declarado)
REAPERS = {"tini", "dumb-init"}
bad = []
for df in ("Dockerfile", "Dockerfile.native"):
if not os.path.exists(df):
continue
entry = None
for raw in open(df, encoding="utf-8", errors="ignore"):
line = raw.split("#", 1)[0].rstrip()
m = re.match(r"\s*ENTRYPOINT\s+(.*)$", line)
if m:
entry = m.group(1).strip() # ultimo ENTRYPOINT vence
if entry is None or not entry.startswith("["):
continue # ausente ou shell-form: pula
try:
arr = json.loads(entry)
except Exception:
continue # JSON quebrado: pula
if not arr:
continue
first = os.path.basename(str(arr[0]))
if first not in REAPERS:
bad.append(f"{df}: ENTRYPOINT sem reaper de PID1 (1o elemento = {arr[0]!r})")
if bad:
print("::error::ENTRYPOINT sem init de PID1 (tini/dumb-init) — HEALTHCHECK vaza zumbi curl <defunct>")
for b in bad:
print(" " + b)
sys.exit(1)
PY
- name: Persistência micronaut-data (Micronaut)
run: |
python3 - <<'PY'
import glob, sys
g = "".join(open(f, encoding="utf-8", errors="ignore").read()
for f in glob.glob("**/build.gradle*", recursive=True))
gl = g.lower()
if "micronaut" not in gl:
sys.exit(0)
# dir de build guarda copias do src: rodando local, a guarda reprovaria artefato velho
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
db = False
for pat in ("application*.yml", "application*.yaml", "application*.properties"):
for f in fontes(f"**/{pat}"):
if "datasources" in open(f, encoding="utf-8", errors="ignore").read().lower():
db = True; break
if db: break
if not db or "micronaut-data-processor" in gl:
sys.exit(0)
print("::error::App Micronaut acessa DB sem micronaut-data-processor no annotationProcessor")
sys.exit(1)
PY
- name: Pool Hikari em sub-bloco ignorado (Micronaut)
run: |
python3 - <<'PY'
import glob, re, sys
gradle = "".join(open(f, encoding="utf-8", errors="ignore").read()
for f in glob.glob("**/build.gradle*", recursive=True))
if "micronaut" not in gradle.lower():
sys.exit(0)
# dir de build guarda copias do src: rodando local, a guarda reprovaria artefato velho
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
# o DatasourceConfiguration estende o HikariConfig: datasources.<nome>.hikari.* e ignorado, sem erro
achados = []
for pat in ("application*.yml", "application*.yaml"):
for f in fontes(f"**/{pat}"):
pilha = []
for n, raw in enumerate(open(f, encoding="utf-8", errors="ignore"), 1):
m = re.match(r"^(\s*)([\w.-]+)\s*:", raw)
if not m:
continue
recuo = len(m.group(1))
while pilha and pilha[-1][0] >= recuo:
pilha.pop()
pilha.append((recuo, m.group(2)))
caminho = ".".join(k for _, k in pilha).split(".")
if caminho[0] == "datasources" and caminho[2:3] == ["hikari"] and "hikari" in m.group(2).split("."):
achados.append(f"{f}:{n}: {raw.strip()}")
for f in fontes("**/application*.properties"):
for n, raw in enumerate(open(f, encoding="utf-8", errors="ignore"), 1):
if re.match(r"\s*datasources\.[\w-]+\.hikari\.", raw):
achados.append(f"{f}:{n}: {raw.strip()}")
if achados:
print("::error::datasources.<nome>.hikari.* e ignorado em silencio (o pool fica no default de 10): use as chaves planas em datasources.<nome>")
for a in achados: print(" " + a)
sys.exit(1)
PY
- name: Integration no gate (Micronaut)
run: |
python3 - <<'PY'
import glob, re, sys
bfiles = glob.glob("**/build.gradle*", recursive=True)
btext = "".join(open(f, encoding="utf-8", errors="ignore").read() for f in bfiles)
if "micronaut" not in btext.lower() or "excludeTags" not in btext:
sys.exit(0)
INTEGRATION = {"integration", "integracao", "docker", "it", "e2e"}
excluded = set()
for a in re.findall(r"excludeTags\s*\(([^)]*)\)", btext):
excluded |= {m.lower() for m in re.findall(r"[\"']([\w-]+)[\"']", a)}
for a in re.findall(r"excludeTags\s+([\"'][^\n]*)", btext):
excluded |= {m.lower() for m in re.findall(r"[\"']([\w-]+)[\"']", a)}
if not (excluded & INTEGRATION):
sys.exit(0)
props = set(re.findall(r"(?:hasProperty|findProperty)\(\s*[\"']([A-Za-z0-9_]+)[\"']", btext))
wf = ""
for g in (".github/workflows/*.yml", ".github/workflows/*.yaml"):
for f in glob.glob(g):
wf += open(f, encoding="utf-8", errors="ignore").read()
gradle = " ".join(l for l in wf.splitlines() if "gradlew" in l)
orphan = False
if props:
if not any(f"-P{p}" in gradle for p in props): orphan = True
elif "includeTags" not in btext:
orphan = True
if orphan:
print("::error::Integration Micronaut excluida do gate `check` sem a CI reativar")
sys.exit(1)
PY
# a lista vem do próprio layout.jte, então acompanha a versão do kit que o app tem.
- name: Estaticos que o kit linka existem
run: |
python3 - <<'PY'
import os, re, sys
KIT = "src/main/jte/kit/layout.jte"
RAIZ = "src/main/resources/public"
if not os.path.exists(KIT):
sys.exit(0) # app sem kit de UI — o kit e opcional no manifesto
html = open(KIT, encoding="utf-8", errors="ignore").read()
refs = sorted(set(re.findall(r'(?:href|src)="(/[^"]+\.(?:css|js|ico|png|svg))"', html)))
faltando = [r for r in refs if not os.path.exists(os.path.join(RAIZ, r.lstrip("/")))]
for r in refs:
print((" ok " if r not in faltando else " FALTA") + " " + r)
if faltando:
print("::error::" + KIT + " linka " + str(len(faltando)) + " arquivo(s) que NAO existem "
"em " + RAIZ + " — o app serve 404 em toda pagina, em silencio: "
+ ", ".join(faltando) + ". Re-derive o kit (a /xadm-docs copia templates/public/** "
"verbatim e cria o app.css se faltar) — nunca remova o <link>, que e do kit.")
sys.exit(1)
PY
# host do proxy deriva do app.json no build; ARG do Dockerfile fica fora (ponto cego) — idêntica nas duas variantes.
- name: Destino de proxy cravado (nginx x app.json)
run: |
python3 - <<'PY'
import glob, json, os, re, sys
from urllib.parse import urlsplit
if not os.path.exists("docs/app.json"):
sys.exit(0) # sem app.json, sem fonte a divergir
try:
feats = json.load(open("docs/app.json", encoding="utf-8")).get("features") or {}
except ValueError:
sys.exit(0) # app.json invalido e assunto de outro gate
hosts = set()
def coleta(v):
if isinstance(v, dict):
for x in v.values(): coleta(x)
elif isinstance(v, list):
for x in v: coleta(x)
elif isinstance(v, str) and "://" in v:
h = urlsplit(v).hostname # DSN: tira a key@ da frente
if h: hosts.add(h.lower())
coleta(feats)
if not hosts:
sys.exit(0)
GERADOS = {"build", "bin", "out", "target", ".gradle", "node_modules", ".dart_tool"}
alvos = [f for f in glob.glob("**/*.conf", recursive=True)
+ glob.glob("**/*.conf.template", recursive=True)
if not any(p in GERADOS for p in f.replace(chr(92), "/").split("/"))]
achados = []
for f in alvos:
for n, raw in enumerate(open(f, encoding="utf-8", errors="ignore"), 1):
line = raw.split("#", 1)[0]
for h in sorted(hosts):
if re.search(r"(?<![\w.-])" + re.escape(h) + r"(?![\w.-])", line, re.I):
achados.append(f + ":" + str(n) + " -> " + h)
if achados:
print("::error::host que o docs/app.json provisiona esta CRAVADO em " + str(len(achados))
+ " linha(s) — diverge em silencio quando o servico muda de endereco: "
+ "; ".join(achados) + ". Derive do app.json no build (template + envsubst com lista "
"explicita): docs.xadm.biz/engenharia/flutter/#deploy-web-tunel-same-origin-e-destino-de-proxy")
sys.exit(1)
PY
# nginx resolve host literal do proxy_pass no boot: sem DNS sai com exit 1 — idêntica nas duas variantes.
- name: proxy_pass resolvido no boot (nginx)
run: |
python3 - <<'PY'
import glob, re, sys
GERADOS = {"build", "bin", "out", "target", ".gradle", "node_modules", ".dart_tool"}
alvos = [f for f in glob.glob("**/*.conf", recursive=True)
+ glob.glob("**/*.conf.template", recursive=True)
if not any(p in GERADOS for p in f.replace(chr(92), "/").split("/"))]
achados = []
for f in alvos:
linhas = [raw.split("#", 1)[0] for raw in open(f, encoding="utf-8", errors="ignore")]
upstreams = set(re.findall(r"\bupstream\s+([\w.-]+)", " ".join(linhas)))
for n, line in enumerate(linhas, 1):
for destino in re.findall(r"\bproxy_pass\s+([^;\s]+)", line):
m = re.match(r"https?://(\[[^\]]*\]|[^/:;]+)", destino)
host = m.group(1) if m else ""
if not host or (host.startswith("$") and not host.startswith("${")):
continue # variavel do nginx: resolvida por pedido, no resolver
if host in upstreams or host in ("localhost", "unix") or re.fullmatch(r"[\d.]+|\[.*\]", host):
continue # nada a resolver no DNS ao carregar a config
achados.append(f + ":" + str(n) + " -> " + destino)
if achados:
print("::error::proxy_pass com host literal em " + str(len(achados)) + " linha(s) — o nginx resolve "
"esse nome ao carregar a config e, sem DNS (VM religando sem WAN), sai com exit 1 e o "
"container fica parado: " + "; ".join(achados) + ". Destino em variavel + resolver: "
"docs.xadm.biz/engenharia/flutter/#deploy-web-tunel-same-origin-e-destino-de-proxy")
sys.exit(1)
PY
- name: Piso do ArchUnit + defesa anti-vacuo (Java 25)
run: |
python3 - <<'PY'
import glob, re, sys
# abaixo do piso o ASM pula as classes do Java 25 e a regra passa vacua (java-micronaut, Guarda de fronteiras)
build = sorted(set(glob.glob("**/build.gradle*", recursive=True)))
toml = sorted(set(glob.glob("**/*.versions.toml", recursive=True)))
btext = " ".join(re.sub(r"(//|#).*$", "", l)
for f in build + toml
for l in open(f, encoding="utf-8", errors="ignore").read().splitlines())
if "archunit" not in btext.lower():
sys.exit(0)
def parse(v):
m = re.match(r"(\d+)\.(\d+)(?:\.(\d+))?", v)
return (int(m.group(1)), int(m.group(2)), int(m.group(3) or 0)) if m else None
versoes = set()
for m in re.finditer(r"com\.tngtech\.archunit:archunit[\w-]*:(\d+\.\d+(?:\.\d+)?)", btext):
versoes.add(parse(m.group(1)))
# versao em variavel: val/def no build ou chave do gradle.properties, usada como $archunitVersion
props = {}
for f in sorted(set(glob.glob("**/gradle.properties", recursive=True))):
for raw in open(f, encoding="utf-8", errors="ignore").read().splitlines():
km = re.match(r"\s*([\w.\-]+)\s*=\s*(\d+\.\d+(?:\.\d+)?)\s*$", raw)
if km:
props[km.group(1)] = km.group(2)
for m in re.finditer(r"\b(?:val|var|def)\s+(\w+)\s*(?::\s*String)?\s*=\s*[\"'](\d+\.\d+(?:\.\d+)?)[\"']", btext):
props[m.group(1)] = m.group(2)
nao_resolvida = []
for m in re.finditer(r"com\.tngtech\.archunit:archunit[\w-]*:\$\{?(\w+)\}?", btext):
if m.group(1) in props:
versoes.add(parse(props[m.group(1)]))
else:
nao_resolvida.append(m.group(1))
for f in toml:
linhas = open(f, encoding="utf-8", errors="ignore").read().splitlines()
versions = {}
for raw in linhas:
km = re.match(r"\s*([A-Za-z0-9_.\-]+)\s*=\s*[\"']([^\"']+)[\"']\s*$", raw)
if km:
versions[km.group(1)] = km.group(2)
for raw in linhas:
if "com.tngtech.archunit" not in raw:
continue
vm = re.search(r"version\s*=\s*[\"'](\d+\.\d+(?:\.\d+)?)[\"']", raw)
if vm:
versoes.add(parse(vm.group(1))); continue
rm = re.search(r"version\.ref\s*=\s*[\"']([A-Za-z0-9_.\-]+)[\"']", raw)
if rm and rm.group(1) in versions:
versoes.add(parse(versions[rm.group(1)]))
versoes.discard(None)
def no_piso(v):
return v >= (1, 4, 1) or (1, 3, 2) <= v < (1, 4, 0)
# ponto cego: versao herdada de lib (xadm-comum-teste exporta por api) nao aparece aqui; cobre o piso do /xadm-docs
if not versoes:
print("::warning::ArchUnit presente, versao nao resolvida (" + (", ".join(nao_resolvida) or "alias de catalog?")
+ ") — piso NAO conferido; declare a versao por literal, variavel do build ou gradle.properties")
else:
velhas = sorted(v for v in versoes if not no_piso(v))
if velhas:
print("::error::ArchUnit abaixo do piso do Java 25 (major 69) — a guarda passa VACUA, verde: "
+ ", ".join(".".join(map(str, v)) for v in velhas)
+ " (piso: >= 1.4.1, ou 1.3.2+ na linha 1.3; a 1.4.0 e anterior ao fix do ASM 9.8)")
sys.exit(1)
testes = sorted(set(glob.glob("**/src/test/**/*.java", recursive=True)
+ glob.glob("**/src/test/**/*.kt", recursive=True)))
arq = [f for f in testes
if re.search(r"AnalyzeClasses|ClassFileImporter|JavaClasses|com\.tngtech\.archunit",
open(f, encoding="utf-8", errors="ignore").read())]
if arq:
# hasNext/isEmpty so contam dentro de assert e na direcao certa: while (it.hasNext()) nao prova nada
defesa = re.compile(r"isNotEmpty|hasSizeGreaterThan|isGreaterThan|isNotZero|importNaoVazio"
r"|isPositive|assert\w*[^;]*(?:hasNext|iterator)"
r"|assertFalse\s*\([^;]*isEmpty\s*\(|assert\w*[^;]*size\s*\(\s*\)\s*>\s*0")
if not any(defesa.search(open(f, encoding="utf-8", errors="ignore").read()) for f in arq):
print("::warning::Suite ArchUnit sem assercao anti-vacuo — import zerado (toolchain nova, "
"rename de pacote stale no @AnalyzeClasses) passa VERDE testando nada. Adicione "
"`assertThat(importedClasses).isNotEmpty()` (engenharia/java-micronaut#guarda-de-fronteiras-de-arquitetura)")
for f in arq:
print(" " + f)
sys.exit(0)
PY
# só avisa: o marcador -- destrutivo-ok: é auto-declarado e não prova o expand (java-micronaut, Banco).
- name: DDL destrutivo sem marcador (Flyway)
run: |
python3 - <<'PY'
import glob, re, sys
# dir de build guarda copias do src: rodando local, a guarda reprovaria artefato velho
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
files = fontes("**/db/migration/**/V*__*.sql")
if not files:
sys.exit(0)
# so migration nova ou alterada desde a ultima tag: a aplicada nao se edita (checksum do Flyway)
import subprocess
try:
tag = subprocess.run(["git", "describe", "--tags", "--abbrev=0", "--match", "v*"],
capture_output=True, text=True, check=True).stdout.strip()
mudou = subprocess.run(["git", "diff", "--name-only", tag], capture_output=True,
text=True, check=True).stdout.split()
mudou += subprocess.run(["git", "ls-files", "--others", "--exclude-standard"],
capture_output=True, text=True, check=True).stdout.split()
novas = {m.replace(chr(92), "/") for m in mudou}
files = [f for f in files if f.replace(chr(92), "/") in novas]
except Exception:
pass
DESTR = [re.compile(p, re.I) for p in (
r"\bDROP\s+COLUMN\b", r"\bDROP\s+TABLE\b",
r"\bRENAME\b", r"\bDROP\s+CONSTRAINT\b")]
warns = []
for f in sorted(files):
text = open(f, encoding="utf-8", errors="ignore").read()
if re.search(r"--\s*destrutivo-ok:", text, re.I):
continue # decisao registrada no .sql — silencia o arquivo
for n, raw in enumerate(text.splitlines(), 1):
line = raw.split("--", 1)[0] # strip comentario `--` (nao /* */)
if any(p.search(line) for p in DESTR):
warns.append(f"{f}:{n}: {raw.strip()}")
if warns:
print("::warning::DDL destrutivo sem marcador — confirme expand/contract "
"(release N nao dropa o que N-1 usa) e registre `-- destrutivo-ok: "
"contract; <objeto> sem uso desde v<N>` no .sql (java-micronaut §Flyway)")
for w in warns:
print(" " + w)
sys.exit(0) # nunca falha o CI — so avisa
PY
- name: Job agendado sem eleicao sob N replicas (Micronaut)
run: |
python3 - <<'PY'
import glob, os, re, sys
# @Scheduled roda em cada instancia: eleicao no arquivo ou numa classe que ele cita (um salto)
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
def nome(f):
return os.path.splitext(os.path.basename(f))[0]
gradle = "".join(open(f, encoding="utf-8", errors="ignore").read()
for f in fontes("**/build.gradle*"))
if "micronaut" not in gradle.lower():
sys.exit(0) # nao e app Micronaut
srcs = sorted(fontes("**/src/main/**/*.java") + fontes("**/src/main/**/*.kt"))
if not srcs:
sys.exit(0)
ELEICAO = re.compile(r"advisory_lock|SchedulerLock|LeaderElect|leaderElect", re.I)
COMENT = re.compile(r"(?://|/\*|\*)\s*agendado-ok:", re.I)
texto = {f: open(f, encoding="utf-8", errors="ignore").read() for f in srcs}
eleitoras = {nome(f) for f, t in texto.items() if ELEICAO.search(t)}
agendados = []
for f in srcs:
t = texto[f]
linhas = []
for n, raw in enumerate(t.splitlines(), 1):
s = raw.strip()
if s.startswith(("*", "/*", "//")):
continue # javadoc/comentario citando @Scheduled
line = raw.split("//", 1)[0]
if re.search(r"@Scheduled\b", line):
linhas.append(f + ":" + str(n) + ": " + s)
if not linhas or COMENT.search(t) or ELEICAO.search(t):
continue # sem job, decisao registrada, ou elege no proprio arquivo
# ponto cego: a citacao e textual, entao comentario que nomeia a eleitora tambem conta
if any(re.search(r"\b" + re.escape(c) + r"\b", t) for c in eleitoras - {nome(f)}):
continue # eleicao delegada (um salto)
agendados += linhas
if agendados:
print("::warning::@Scheduled sem eleicao de instancia NO ARQUIVO — duas instancias do app "
"(sobreposicao de deploy, replica, fallback) rodam o job em dobro. Eleja com "
"pg_try_advisory_lock(hashtext('<app>_<job>')) (ou delegue a uma classe que o faz), "
"ou registre `// agendado-ok: <por que rodar N vezes e inocuo>` no arquivo "
"(java-micronaut, Banco)")
for a in agendados:
print(" " + a)
sys.exit(0) # nunca falha o CI — so avisa (heuristica)
PY
# a GraalVM só embarca o locale en: pt-BR sem IncludeLocales sai em inglês, sem erro.
- name: Locale pt-BR no native (IncludeLocales)
run: |
python3 - <<'PY'
import glob, json, re, sys
try:
alvos = (json.load(open("docs/app.json", encoding="utf-8")).get("build") or {}).get("targets") or []
except Exception:
alvos = []
if "native" not in alvos:
sys.exit(0) # so o native poda locales
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
PT = re.compile(r'Locale\.of\(\s*"pt"|forLanguageTag\(\s*"pt(?:-BR)?"\s*\)|Locale\(\s*"pt"')
usos = []
for f in sorted(fontes("**/src/main/**/*.java") + fontes("**/src/main/**/*.kt")):
for n, raw in enumerate(open(f, encoding="utf-8", errors="ignore"), 1):
if PT.search(raw.split("//", 1)[0]):
usos.append(f + ":" + str(n) + ": " + raw.strip())
if not usos:
sys.exit(0)
gradle = "".join(open(f, encoding="utf-8", errors="ignore").read() for f in fontes("**/build.gradle*"))
if "IncludeLocales" in gradle:
sys.exit(0)
print("::error::app native formata pt-BR sem buildArgs.add(\"-H:IncludeLocales=pt-BR\") no "
"graalvmNative — o binario sai com o locale en (java-micronaut, Build native)")
for u in usos:
print(" " + u)
sys.exit(1)
PY
# placeholder que sobra = imagem base sem pin ou cache-mount compartilhado entre apps.
- name: Placeholder no Dockerfile (digest e slug)
run: |
python3 - <<'PY'
import glob, sys
achados = []
for df in sorted(glob.glob("Dockerfile*")):
for n, raw in enumerate(open(df, encoding="utf-8", errors="ignore"), 1):
linha = raw.split("#", 1)[0]
if "<DIGEST" in linha or "<slug>" in linha:
achados.append(df + ":" + str(n) + ": " + raw.strip())
if achados:
print("::error::placeholder do template sobrou no Dockerfile — preencha o digest e o slug do app:")
for a in achados:
print(" " + a)
sys.exit(1)
PY
# só avisa: quem recusa release abaixo do piso é a /xadm-release (engenharia/libs).
- name: Libs da casa no piso (xadm-commons)
run: |
python3 - <<'PY'
import glob, json, os, re, sys, urllib.request
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
texto = "\n".join(open(f, encoding="utf-8", errors="ignore").read()
for f in fontes("**/build.gradle*") + fontes("**/*.versions.toml"))
deps = set(re.findall(r"br\.com\.xadm:([a-z0-9-]+):(\d+\.\d+\.\d+)", texto))
deps |= set(re.findall(r'"br\.com\.xadm:([a-z0-9-]+)"[^\n]*?version\s*=\s*"(\d+\.\d+\.\d+)"', texto))
if not deps:
sys.exit(0) # nao consome lib da casa
url = os.environ.get("XADM_PISOS_URL", "https://docs.xadm.biz/toolchain/pisos-libs.json")
try:
if url.startswith("http"):
with urllib.request.urlopen(url, timeout=15) as r:
dados = json.load(r)
else:
dados = json.load(open(url, encoding="utf-8"))
pisos = {p["modulo"]: p for p in dados["pisos"]}
except Exception as e:
print("::warning::pisos de lib indisponiveis (" + str(e) + ") — piso NAO conferido")
sys.exit(0)
def ver(s):
return tuple(int(x) for x in s.split("."))
abaixo = []
for mod, v in sorted(deps):
p = pisos.get(mod)
if p and ver(v) < ver(p["piso"]):
abaixo.append("br.com.xadm:" + mod + ":" + v + " < piso " + p["piso"] + " — " + p.get("motivo", ""))
if abaixo:
print("::warning::lib da casa abaixo do piso — a /xadm-release recusa a release assim (engenharia/libs):")
for a in abaixo:
print(" " + a)
sys.exit(0)
PY
# o default MANUAL do Micronaut roda controller no event loop: AUTO, @ExecuteOn ou // event-loop-ok: <motivo> (engenharia/libs).
- name: Controller fora do event loop (Micronaut)
run: |
python3 - <<'PY'
import glob, re, sys
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
gradle = "".join(open(f, encoding="utf-8", errors="ignore").read() for f in fontes("**/build.gradle*"))
if "micronaut" not in gradle.lower():
sys.exit(0) # nao e app Micronaut
conf = ""
for pat in ("application*.yml", "application*.yaml", "application*.properties"):
for f in fontes("**/" + pat):
conf += "\n".join(l for l in open(f, encoding="utf-8", errors="ignore").read().splitlines()
if not l.lstrip().startswith("#"))
if re.search(r"thread-selection\s*[:=]\s*auto", conf, re.I):
sys.exit(0)
sem = [f for f in sorted(fontes("**/src/main/**/*.java") + fontes("**/src/main/**/*.kt"))
if "@Controller" in (t := open(f, encoding="utf-8", errors="ignore").read())
and "@ExecuteOn" not in t and "event-loop-ok:" not in t]
if sem:
print("::warning::controller Micronaut sem thread-selection: AUTO, @ExecuteOn nem // event-loop-ok: — "
"I/O bloqueante roda no event loop (java-micronaut, HTTP; engenharia/libs):")
for f in sem:
print(" " + f)
sys.exit(0)
PY
# so o /health no smoke deixa passar a tela em 500 e a rota que o AOT podou (engenharia/smoke-producao).
- name: Classe servida sem rota no smoke (app.json)
run: |
python3 - <<'PY'
import glob, json, re, sys
try:
app = json.load(open("docs/app.json", encoding="utf-8"))
except Exception:
sys.exit(0) # sem app.json: o job docs acusa
smoke = app.get("smoke")
if not (app.get("build") or {}).get("targets") or not isinstance(smoke, dict):
sys.exit(0) # sem alvo ou sem bloco: o valida-frontmatter acusa
GERADOS = ("build", "bin", "out", "target", ".gradle", "node_modules")
def fontes(padrao):
return [f for f in glob.glob(padrao, recursive=True)
if not any(parte in GERADOS for parte in f.replace(chr(92), "/").split("/"))]
def codigo(f):
linhas = []
for raw in open(f, encoding="utf-8", errors="ignore"):
s = raw.lstrip()
if s.startswith(("*", "/*")):
continue
linhas.append(raw.split("//", 1)[0])
return "".join(linhas)
java = {f: codigo(f) for f in fontes("**/src/main/**/*.java") + fontes("**/src/main/**/*.kt")}
gradle = "".join(open(f, encoding="utf-8", errors="ignore").read() for f in fontes("**/build.gradle*"))
servidas = {}
views = sorted(f for f, t in java.items() if "@View(" in t)
if "xadm-seguranca" in gradle and views:
servidas["session"] = "view com a xadm-seguranca: " + views[0]
m2m = sorted(f for f, t in java.items() if '"ROLE_API"' in t or '"app.api-token"' in t)
for f in fontes("**/src/main/resources/application*.yml") + fontes("**/src/main/resources/application*.yaml"):
topo = None
for raw in open(f, encoding="utf-8", errors="ignore"):
linha = raw.split("#", 1)[0].rstrip()
m = re.match(r"([A-Za-z][\w-]*):", linha)
if m:
topo = m.group(1)
elif topo == "app" and re.match(r"\s+api-token\s*:", linha):
m2m.append(f)
if m2m:
servidas["m2m"] = "Bearer app.api-token / ROLE_API: " + m2m[0]
declaradas = {r.get("class") for r in smoke.get("routes") or [] if isinstance(r, dict)}
isentas = smoke.get("sem_rota") if isinstance(smoke.get("sem_rota"), dict) else {}
faltam = [c for c in sorted(servidas) if c not in declaradas and not str(isentas.get(c) or "").strip()]
if faltam:
print("::error::o app serve rota desta classe de credencial e o smoke.routes do docs/app.json nao tem "
"nenhuma — declare uma rota GET sem efeito colateral, ou o motivo em smoke.sem_rota (smoke-producao):")
for c in faltam:
print(" " + c + " (" + servidas[c] + ")")
sys.exit(1)
PY
- name: Gate (análise estática + testes + integração — Testcontainers no docker do host)
run: ./gradlew check --no-daemon
- name: Contrato REST (prosa × OpenAPI)
run: |
curl --connect-timeout 10 --max-time 60 -fsSL https://docs.xadm.biz/padroes/checa-rotas.py -o checa-rotas.py
python3 checa-rotas.py
- name: Aviso — modelo de dados acompanha as migrations?
run: |
curl --connect-timeout 10 --max-time 60 -fsSLO https://docs.xadm.biz/toolchain/checa-modelagem.py
python3 checa-modelagem.py "${{ github.event.pull_request.base.sha || github.event.before || 'HEAD~1' }}"
# só na tag; roda mesmo com teste vermelho, para os dois diagnósticos saírem no mesmo run.
- name: Validar contrato de release (SemVer, CHANGELOG e tag)
if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}
run: |
curl --connect-timeout 10 --max-time 60 -fsSL -o /tmp/valida-release.py https://docs.xadm.biz/toolchain/valida-release.py
python3 /tmp/valida-release.py . --tag "${GITHUB_REF#refs/tags/}"
# ── VARIANTE Flutter web (apague o gate-Java acima, descomente este) ────────
# gate:
# needs: decide
# if: needs.decide.outputs.tests == 'true'
# runs-on: ubuntu-latest
# timeout-minutes: 15
# steps:
# - uses: actions/checkout@v4
# - uses: subosito/flutter-action@v2 # FUNCIONA no GitHub (≠ runner Forgejo)
# with: { flutter-version: '${{ needs.decide.outputs.flutter }}', channel: stable, cache: true } # docs/app.json toolchain.flutter (= .fvmrc; guarda)
# - name: Toolchain nativa (PowerSync/sqlite3)
# run: sudo apt-get update -qq && sudo apt-get install -y -qq ninja-build
# - name: Doc no índice (nav-drift)
# run: |
# curl --connect-timeout 10 --max-time 60 -fsSL https://docs.xadm.biz/padroes/checa-nav.py -o checa-nav.py
# python3 checa-nav.py
# # divergir do app.json builda com uma versão e testa com outra, em silêncio — guarda idêntica nas duas variantes.
# - name: Toolchain do app.json x .fvmrc e FROM do Dockerfile
# run: |
# python3 - <<'PY'
# import glob, json, os, re, sys
# try:
# tool = json.load(open("docs/app.json", encoding="utf-8")).get("toolchain") or {}
# except Exception:
# sys.exit(0) # sem app.json legivel: o valida-frontmatter cobra
# achados = []
# fl = str(tool.get("flutter") or "")
# if fl and os.path.exists(".fvmrc"):
# try:
# v = str(json.load(open(".fvmrc", encoding="utf-8")).get("flutter") or "")
# except Exception:
# v = ""
# if v and v != fl:
# achados.append(".fvmrc flutter=" + v + " x app.json toolchain.flutter=" + fl)
# jv = str(tool.get("java") or "").split(".")[0]
# for df in sorted(glob.glob("Dockerfile*")):
# args = {}
# for n, raw in enumerate(open(df, encoding="utf-8", errors="ignore"), 1):
# linha = raw.split("#", 1)[0]
# a = re.match(r"\s*ARG\s+(\w+)=(\S+)", linha, re.I)
# if a:
# args[a.group(1)] = a.group(2).strip("\"'")
# continue
# # FROM img:${VAR} usa o default do ARG declarado antes no mesmo Dockerfile
# linha = re.sub(r"\$\{(\w+)\}|\$(\w+)", lambda v: args.get(v.group(1) or v.group(2), v.group(0)), linha)
# m = re.match(r"\s*FROM\s+(\S+)", linha, re.I)
# if not m:
# continue
# nome, _, tag = m.group(1).lower().partition(":")
# tag = tag.split("@", 1)[0]
# if jv and tag and (re.search(r"temurin|graalvm|native-image|openjdk", nome) or "jdk" in tag):
# v = re.search(r"jdk-?(\d+)", tag) or re.match(r"(\d+)", tag)
# if v and v.group(1) != jv:
# achados.append(df + ":" + str(n) + ": " + m.group(1) + " x app.json toolchain.java=" + jv)
# if fl and tag and "flutter" in nome:
# v = re.match(r"(\d+\.\d+\.\d+)", tag)
# if v and v.group(1) != fl:
# achados.append(df + ":" + str(n) + ": " + m.group(1) + " x app.json toolchain.flutter=" + fl)
# if achados:
# print("::error::versao de toolchain diverge do docs/app.json (fonte unica, decisao 0027):")
# for a in achados:
# print(" " + a)
# sys.exit(1)
# PY
# # settings.local.json é pessoal (grants, caminhos de máquina, às vezes credencial) — idêntica nas duas variantes.
# - name: settings.local.json fora do git
# run: |
# python3 - <<'PY'
# import subprocess, sys
# try:
# r = subprocess.run(["git", "ls-files", "--", ".claude/settings.local.json"],
# capture_output=True, text=True, check=True)
# except Exception:
# sys.exit(0) # sem git: nada a conferir
# if r.stdout.strip():
# print("::error::.claude/settings.local.json esta versionado — e pessoal. Rode "
# "`git rm --cached .claude/settings.local.json`, ponha no .gitignore e, se ele "
# "tinha credencial, rotacione.")
# sys.exit(1)
# PY
# # host do proxy deriva do app.json no build; ARG do Dockerfile fica fora (ponto cego) — idêntica nas duas variantes.
# - name: Destino de proxy cravado (nginx x app.json)
# run: |
# python3 - <<'PY'
# import glob, json, os, re, sys
# from urllib.parse import urlsplit
# if not os.path.exists("docs/app.json"):
# sys.exit(0) # sem app.json, sem fonte a divergir
# try:
# feats = json.load(open("docs/app.json", encoding="utf-8")).get("features") or {}
# except ValueError:
# sys.exit(0) # app.json invalido e assunto de outro gate
# hosts = set()
# def coleta(v):
# if isinstance(v, dict):
# for x in v.values(): coleta(x)
# elif isinstance(v, list):
# for x in v: coleta(x)
# elif isinstance(v, str) and "://" in v:
# h = urlsplit(v).hostname # DSN: tira a key@ da frente
# if h: hosts.add(h.lower())
# coleta(feats)
# if not hosts:
# sys.exit(0)
# GERADOS = {"build", "bin", "out", "target", ".gradle", "node_modules", ".dart_tool"}
# alvos = [f for f in glob.glob("**/*.conf", recursive=True)
# + glob.glob("**/*.conf.template", recursive=True)
# if not any(p in GERADOS for p in f.replace(chr(92), "/").split("/"))]
# achados = []
# for f in alvos:
# for n, raw in enumerate(open(f, encoding="utf-8", errors="ignore"), 1):
# line = raw.split("#", 1)[0]
# for h in sorted(hosts):
# if re.search(r"(?<![\w.-])" + re.escape(h) + r"(?![\w.-])", line, re.I):
# achados.append(f + ":" + str(n) + " -> " + h)
# if achados:
# print("::error::host que o docs/app.json provisiona esta CRAVADO em " + str(len(achados))
# + " linha(s) — diverge em silencio quando o servico muda de endereco: "
# + "; ".join(achados) + ". Derive do app.json no build (template + envsubst com lista "
# "explicita): docs.xadm.biz/engenharia/flutter/#deploy-web-tunel-same-origin-e-destino-de-proxy")
# sys.exit(1)
# PY
# # nginx resolve host literal do proxy_pass no boot: sem DNS sai com exit 1 — idêntica nas duas variantes.
# - name: proxy_pass resolvido no boot (nginx)
# run: |
# python3 - <<'PY'
# import glob, re, sys
# GERADOS = {"build", "bin", "out", "target", ".gradle", "node_modules", ".dart_tool"}
# alvos = [f for f in glob.glob("**/*.conf", recursive=True)
# + glob.glob("**/*.conf.template", recursive=True)
# if not any(p in GERADOS for p in f.replace(chr(92), "/").split("/"))]
# achados = []
# for f in alvos:
# linhas = [raw.split("#", 1)[0] for raw in open(f, encoding="utf-8", errors="ignore")]
# upstreams = set(re.findall(r"\bupstream\s+([\w.-]+)", " ".join(linhas)))
# for n, line in enumerate(linhas, 1):
# for destino in re.findall(r"\bproxy_pass\s+([^;\s]+)", line):
# m = re.match(r"https?://(\[[^\]]*\]|[^/:;]+)", destino)
# host = m.group(1) if m else ""
# if not host or (host.startswith("$") and not host.startswith("${")):
# continue # variavel do nginx: resolvida por pedido, no resolver
# if host in upstreams or host in ("localhost", "unix") or re.fullmatch(r"[\d.]+|\[.*\]", host):
# continue # nada a resolver no DNS ao carregar a config
# achados.append(f + ":" + str(n) + " -> " + destino)
# if achados:
# print("::error::proxy_pass com host literal em " + str(len(achados)) + " linha(s) — o nginx resolve "
# "esse nome ao carregar a config e, sem DNS (VM religando sem WAN), sai com exit 1 e o "
# "container fica parado: " + "; ".join(achados) + ". Destino em variavel + resolver: "
# "docs.xadm.biz/engenharia/flutter/#deploy-web-tunel-same-origin-e-destino-de-proxy")
# sys.exit(1)
# PY
# # ícone do flutter create em web/ vira a marca do app instalado; a opacidade só avisa.
# - name: Ícones do web (scaffold e opacidade)
# run: |
# curl --connect-timeout 10 --max-time 60 -fsSL https://docs.xadm.biz/toolchain/checa-icones-web.py -o checa-icones-web.py
# python3 checa-icones-web.py
# - name: Gate (dart format + analyze + test)
# run: |
# flutter pub get
# dart run powersync:setup_web # web workers JS (gitignored) — ANTES do test
# dart format --output=none --set-exit-if-changed .
# flutter analyze
# # goldens fora do gate: travados ao ambiente (rodam local e no e2e).
# flutter test --exclude-tags golden --coverage
# awk -F: '/^LF:/{f+=$2} /^LH:/{h+=$2} END{if(f>0)printf "Cobertura: %.1f%% (%d/%d)\n",100*h/f,h,f; else print "Cobertura: sem dados"}' coverage/lcov.info || true
# # só na tag; roda mesmo com teste vermelho, para os dois diagnósticos saírem no mesmo run.
# - name: Validar contrato de release (SemVer, CHANGELOG e tag)
# if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}
# run: |
# curl --connect-timeout 10 --max-time 60 -fsSL -o /tmp/valida-release.py https://docs.xadm.biz/toolchain/valida-release.py
# python3 /tmp/valida-release.py . --tag "${GITHUB_REF#refs/tags/}"
# === RELEASE-FORGEJO — opt-in, só app cliente offline (artefato como Release no Forgejo); app online não usa ===
# release-forgejo:
# needs: [decide, gate]
# if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') && needs.gate.result == 'success' }}
# runs-on: ubuntu-latest
# timeout-minutes: 20
# steps:
# - uses: actions/checkout@v4
# - uses: actions/setup-java@v5
# with: { distribution: temurin, java-version: '${{ needs.decide.outputs.java }}' }
# - uses: gradle/actions/setup-gradle@v4
# - name: Build do artefato
# run: ./gradlew shadowJar --no-daemon # ajuste à sua stack
# - name: Publicar Release no Forgejo (tag + notas + asset)
# env:
# RELEASE_TOKEN: ${{ secrets.RELEASE_TOKEN }}
# run: |
# : "${RELEASE_TOKEN:?RELEASE_TOKEN ausente — token Forgejo write:repository, secret do repo}"
# export TAG="${GITHUB_REF#refs/tags/}"
# APP="${GITHUB_REPOSITORY#*/}"
# API="https://fonte.xadm.biz/api/v1/repos/xadm/${APP}"
# JAR="$(ls build/libs/*-all.jar | head -1)"
# awk -v v="${TAG#v}" 'index($0,"## ["v"]")==1{p=1;next} p&&/^## \[/{exit} p' \
# CHANGELOG.md > /tmp/notas.md
# ID="$(python3 -c 'import json,os;print(json.dumps({"tag_name":os.environ["TAG"],"name":os.environ["TAG"],"body":open("/tmp/notas.md").read()}))' \
# | curl --connect-timeout 10 --max-time 60 -fsSL -X POST "$API/releases" -d @- \
# -H "Authorization: token $RELEASE_TOKEN" -H 'Content-Type: application/json' \
# | python3 -c 'import sys,json;print(json.load(sys.stdin)["id"])')"
# # Asset de nome limpo: <app>-<versão>.jar (sem o sufixo -all do shadow).
# curl --connect-timeout 10 --max-time 600 -fsSL -X POST "$API/releases/$ID/assets?name=${APP}-${TAG#v}.jar" \
# -H "Authorization: token $RELEASE_TOKEN" -F "attachment=@$JAR"
# === DOCS — build MkDocs + publica no Garage; OpenAPI opt-in (app dono de contrato REST) ===
# Push de tag: só com gate verde (doc de release que não vai ao ar não se publica) e, verde, libera o deploy.
docs:
needs: [decide, gate]
if: ${{ !cancelled() && needs.decide.outputs.docs == 'true' &&
(needs.gate.result == 'success' || !(github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v'))) }}
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
# ── OpenAPI opt-in: descomente (app DONO de contrato REST — precisa de JDK) ──
# - uses: actions/setup-java@v5
# with: { distribution: temurin, java-version: '${{ needs.decide.outputs.java }}' }
# - uses: gradle/actions/setup-gradle@v4
- uses: actions/setup-python@v5
with: { python-version: '3.12' }
- uses: actions/setup-node@v4
with: { node-version: '20' }
# chave pelo hash deste arquivo (as versões das ferramentas são fixas aqui); o cache:pip do setup-python exige requirements.txt.
- name: Cache pip + npm (ferramentas de docs)
uses: actions/cache@v4
with:
path: |
~/.cache/pip
~/.npm
key: docs-tools-${{ runner.os }}-${{ hashFiles('.github/workflows/pipeline.yml') }}
restore-keys: docs-tools-${{ runner.os }}-
- name: Ferramentas de docs (mkdocs + rclone)
run: |
pip3 install --quiet \
mkdocs==1.6.1 mkdocs-material==9.7.6 pymdown-extensions==10.21.3 \
mkdocs-print-site-plugin==2.8 mkdocs-swagger-ui-tag==0.8.0 mkdocs-redirects==1.2.2
sudo apt-get update -qq && sudo apt-get install -y -qq rclone
- name: Definir alvo da versão (tag vX.Y.Z → snapshot; master → dev)
run: |
ref="${GITHUB_REF#refs/}"
case "$ref" in
tags/v[0-9]*.[0-9]*.[0-9]*)
v="${ref#tags/v}"
case "$v" in
*[!0-9.]*) echo "tag '$v' fora de X.Y.Z — não versiona"; alvo=skip ;;
*) alvo="$v"; echo "EH_RELEASE=1" >> "$GITHUB_ENV" ;;
esac ;;
heads/master) alvo=dev ;;
*) echo "ref '$ref' fora do contrato — não publica"; alvo=skip ;;
esac
echo "ALVO=$alvo" >> "$GITHUB_ENV"
slug=$(python3 -c "import json;print(json.load(open('docs/app.json'))['slug'])") \
|| { echo "ERRO: docs/app.json sem 'slug'"; exit 1; }
echo "SLUG=$slug" >> "$GITHUB_ENV"
- name: Validar frontmatter
run: |
curl --connect-timeout 10 --max-time 60 -fsSL -o /tmp/valida-frontmatter.py https://docs.xadm.biz/toolchain/valida-frontmatter.py
python3 /tmp/valida-frontmatter.py docs/
- name: Baixar hooks de doc (governança + Visão técnica)
run: |
mkdir -p scripts
curl --connect-timeout 10 --max-time 60 -fsSL -o scripts/frontmatter-cabecalho.py https://docs.xadm.biz/toolchain/frontmatter-cabecalho.py
curl --connect-timeout 10 --max-time 60 -fsSL -o scripts/visao-tecnica.py https://docs.xadm.biz/toolchain/visao-tecnica.py
- name: Lint dos diagramas Mermaid
run: |
npm install --no-save --silent mermaid@11 jsdom
curl --connect-timeout 10 --max-time 60 -fsSL -o lint-mermaid.mjs https://docs.xadm.biz/toolchain/lint-mermaid.mjs
node lint-mermaid.mjs docs/
# ── OpenAPI opt-in (0020): gera o swagger em docs/ antes do build, para o --strict validar o link; precisa do JDK ──
# - name: Gerar referência de API (OpenAPI — contrato público)
# run: |
# ./gradlew classes --no-daemon
# mkdir -p docs/public/api
# cp build/classes/java/main/META-INF/swagger/*.yml docs/public/api/openapi.yaml
# - name: Contrato REST (prosa × OpenAPI)
# run: |
# curl --connect-timeout 10 --max-time 60 -fsSL https://docs.xadm.biz/padroes/checa-rotas.py -o checa-rotas.py
# python3 checa-rotas.py
# ── Javadoc/dartdoc opt-in: gera a referência interna em docs/dev/api/ antes do build. Sem este
# step, NÃO linke `dev/api/` no guia-do-codigo — o link vira 404 no site (apague a seção). ──
# - name: Gerar referência de classes (Javadoc — interna)
# run: |
# ./gradlew javadoc --no-daemon
# mkdir -p docs/dev/api
# cp -r build/docs/javadoc/. docs/dev/api/
# Flutter/Dart: `dart doc --output docs/dev/api .` no lugar das três linhas acima.
# ── Importar fato opt-in (consumidor de contrato, 0014): baixa o .md do dono antes do build; slug atual (0024), sem pin ──
# - name: Importar fatos de outros repos (frescos)
# run: |
# mkdir -p docs/_importado
# curl --connect-timeout 10 --max-time 60 -fsSL https://docs.xadm.biz/aplicacoes/<slug-dono>/raw/<fato>.md \
# -o docs/_importado/<fato>.md
# valida sempre, inclusive em PR (ALVO=skip); só a publicação depende do alvo.
- name: Buildar e validar site de docs
run: |
if [ "$ALVO" != skip ]; then
sed -i "s#^site_url:.*#site_url: https://docs.xadm.biz/aplicacoes/${SLUG}/${ALVO}/#" mkdocs.yml
fi
mkdocs build --strict
curl --connect-timeout 10 --max-time 60 -fsSL https://docs.xadm.biz/padroes/checa-admonition.py -o checa-admonition.py
python3 checa-admonition.py
privado="$(find site -type d -name privado 2>/dev/null)"
if [ -n "$privado" ]; then echo "ERRO: pasta privado/ no site/"; echo "$privado"; exit 1; fi
# na tag, falha de rede não barra o deploy: vira aviso, e o que depende da publicação é pulado.
- name: Publicar no Garage
id: garage
if: env.ALVO != 'skip' && github.event_name != 'pull_request'
continue-on-error: ${{ startsWith(github.ref, 'refs/tags/v') }}
env:
RCLONE_CONFIG_GARAGE_TYPE: s3
RCLONE_CONFIG_GARAGE_PROVIDER: Other
RCLONE_CONFIG_GARAGE_ENDPOINT: ${{ secrets.DOCS_S3_ENDPOINT }}
RCLONE_CONFIG_GARAGE_ACCESS_KEY_ID: ${{ secrets.DOCS_S3_ACCESS_KEY }}
RCLONE_CONFIG_GARAGE_SECRET_ACCESS_KEY: ${{ secrets.DOCS_S3_SECRET_KEY }}
RCLONE_CONFIG_GARAGE_REGION: garage
RCLONE_CONFIG_GARAGE_FORCE_PATH_STYLE: "true"
run: |
: "${RCLONE_CONFIG_GARAGE_ENDPOINT:?DOCS_S3_ENDPOINT ausente — cadastre os 3 DOCS_S3_* como secret DESTE repo no GitHub}"
: "${RCLONE_CONFIG_GARAGE_ACCESS_KEY_ID:?DOCS_S3_ACCESS_KEY ausente}"
: "${RCLONE_CONFIG_GARAGE_SECRET_ACCESS_KEY:?DOCS_S3_SECRET_KEY ausente}"
rclone sync site "garage:docs-sites/${SLUG}/${ALVO}" --quiet
rclone copyto site/app.json "garage:docs-sites/${SLUG}/app.json" --quiet
# o central sincroniza só este prefixo (0028); o aviso não derruba o job, o backstop de sync cobre.
- name: Avisar central do publish (docs sync event-driven)
if: env.ALVO != 'skip' && github.event_name != 'pull_request' && steps.garage.outcome == 'success'
env:
CENTRAL_DEPLOY_TOKEN: ${{ secrets.CENTRAL_DEPLOY_TOKEN }}
run: |
url="${CENTRAL_DEPLOY_URL%/deploy}/docs-published"
tok=$(printf '%s' "$CENTRAL_DEPLOY_TOKEN" | tr -d '\r\n')
if [ -z "$tok" ]; then
echo "::warning::CENTRAL_DEPLOY_TOKEN ausente — aviso ao central pulado; o backstop de sync cobre"
exit 0
fi
code=$(curl --connect-timeout 10 --max-time 60 -sS -o /dev/null -w '%{http_code}' -X POST "$url" \
-H "Authorization: Bearer $tok" -H "Content-Type: application/json" \
-d "{\"slug\":\"${SLUG}\",\"alvo\":\"${ALVO}\"}") || code=000
case "$code" in
2??) echo "central avisado do publish (${SLUG}/${ALVO})" ;;
404) echo "::notice::aviso ao central devolveu 404 (${url}) — o backstop de sync cobre" ;;
*) echo "::warning::aviso ao central devolveu HTTP ${code} (${url}) — confira o CENTRAL_DEPLOY_TOKEN; o backstop de sync cobre" ;;
esac
# docs-only: republica também a vigente (o site redireciona pra ela); versions.json, index.html e app.json são de release.
- name: Republicar a versão vigente (docs-only)
if: needs.decide.outputs.docs_only == 'true' && github.event_name != 'pull_request'
env:
RCLONE_CONFIG_GARAGE_TYPE: s3
RCLONE_CONFIG_GARAGE_PROVIDER: Other
RCLONE_CONFIG_GARAGE_ENDPOINT: ${{ secrets.DOCS_S3_ENDPOINT }}
RCLONE_CONFIG_GARAGE_ACCESS_KEY_ID: ${{ secrets.DOCS_S3_ACCESS_KEY }}
RCLONE_CONFIG_GARAGE_SECRET_ACCESS_KEY: ${{ secrets.DOCS_S3_SECRET_KEY }}
RCLONE_CONFIG_GARAGE_REGION: garage
RCLONE_CONFIG_GARAGE_FORCE_PATH_STYLE: "true"
CENTRAL_DEPLOY_TOKEN: ${{ secrets.CENTRAL_DEPLOY_TOKEN }}
run: |
vj=$(rclone cat "garage:docs-sites/${SLUG}/versions.json" 2>/dev/null || true)
if [ -z "$vj" ]; then echo "sem versions.json (app nunca releasou) — só dev/"; exit 0; fi
# vigente = alias latest, senão maior SemVer (uma linha: multilinha quebra o bloco YAML)
VIG=$(printf '%s' "$vj" | python3 -c "import sys,json; d=json.load(sys.stdin); l=[x['version'] for x in d if 'latest' in x.get('aliases',[])]; xs=sorted((x['version'] for x in d), key=lambda s:[int(n) for n in s.split('.')], reverse=True); print(l[0] if l else (xs[0] if xs else ''))" 2>/dev/null || true)
if [ -z "$VIG" ]; then echo "versions.json vazio/inválido — só dev/"; exit 0; fi
echo "republicando docs na vigente: ${VIG}"
sed -i "s#^site_url:.*#site_url: https://docs.xadm.biz/aplicacoes/${SLUG}/${VIG}/#" mkdocs.yml
mkdocs build --strict
rclone sync site "garage:docs-sites/${SLUG}/${VIG}" --quiet
url="${CENTRAL_DEPLOY_URL%/deploy}/docs-published"
tok=$(printf '%s' "$CENTRAL_DEPLOY_TOKEN" | tr -d '\r\n')
if [ -z "$tok" ]; then
echo "::warning::CENTRAL_DEPLOY_TOKEN ausente — aviso ao central pulado; o backstop de sync cobre"
exit 0
fi
code=$(curl --connect-timeout 10 --max-time 60 -sS -o /dev/null -w '%{http_code}' -X POST "$url" \
-H "Authorization: Bearer $tok" -H "Content-Type: application/json" \
-d "{\"slug\":\"${SLUG}\",\"alvo\":\"${VIG}\"}") || code=000
case "$code" in
2??) echo "central avisado (${SLUG}/${VIG})" ;;
404) echo "::notice::aviso ao central devolveu 404 (${url}) — o backstop de sync cobre" ;;
*) echo "::warning::aviso ao central devolveu HTTP ${code} (${url}) — o backstop de sync cobre" ;;
esac
- name: Atualizar versions.json + redirect da raiz (só em release)
if: env.EH_RELEASE == '1' && steps.garage.outcome == 'success'
env:
RCLONE_CONFIG_GARAGE_TYPE: s3
RCLONE_CONFIG_GARAGE_PROVIDER: Other
RCLONE_CONFIG_GARAGE_ENDPOINT: ${{ secrets.DOCS_S3_ENDPOINT }}
RCLONE_CONFIG_GARAGE_ACCESS_KEY_ID: ${{ secrets.DOCS_S3_ACCESS_KEY }}
RCLONE_CONFIG_GARAGE_SECRET_ACCESS_KEY: ${{ secrets.DOCS_S3_SECRET_KEY }}
RCLONE_CONFIG_GARAGE_REGION: garage
RCLONE_CONFIG_GARAGE_FORCE_PATH_STYLE: "true"
run: |
curl --connect-timeout 10 --max-time 60 -fsSL -o /tmp/publica-versao.py https://docs.xadm.biz/toolchain/publica-versao.py
python3 /tmp/publica-versao.py "${SLUG}"
# lê o outcome: com continue-on-error, o conclusion do step sai success mesmo falhando.
- name: Avisar publicação falha (o deploy segue)
if: steps.garage.outcome == 'failure'
run: |
echo "::warning::docs de ${SLUG}/${ALVO} não publicadas (Garage) — sem versions.json nem aviso ao central. Republique: workflow_dispatch na ref ${GITHUB_REF#refs/tags/}, com docs marcado e tests desmarcado"
# === BUILD — builda e empurra a imagem, em paralelo ao gate; apague os jobs dos alvos que o app não declara ===
# ── Java jar — jar declarado com motivo: só roda com "jar" no build.targets ──────
build_jar:
needs: decide
if: needs.decide.outputs.jar == 'true'
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
id: buildx # o cache-dance precisa do NOME do builder
- uses: docker/login-action@v3
with: { registry: fonte.xadm.biz, username: '${{ secrets.FORGEJO_USER }}', password: '${{ secrets.FORGEJO_TOKEN }}' }
- uses: docker/login-action@v3
with: { registry: ghcr.io, username: '${{ github.actor }}', password: '${{ secrets.GITHUB_TOKEN }}' }
# actions/cache guarda o dir entre runs e o cache-dance o injeta no mount: sem um dos dois, o mount nasce frio.
- uses: actions/cache@v4
with:
path: .gradle-mount-jar
key: gradle-mount-jar-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties', '**/*.versions.toml') }}
restore-keys: gradle-mount-jar-
# o id do cache-map casa o id do RUN --mount do Dockerfile.
- uses: reproducible-containers/buildkit-cache-dance@v3
with:
builder: ${{ steps.buildx.outputs.name }}
cache-map: '{".gradle-mount-jar": {"target": "/root/.gradle", "id": "gradle-<slug>"}}'
- uses: docker/build-push-action@v6
with:
context: .
file: Dockerfile
push: true
# vira commit no /health: o smoke compara com este sha e o usa de alvo de rollback.
build-args: |
XADM_COMMIT=${{ github.sha }}
tags: |
${{ env.IMAGE }}:jar-amd64
${{ env.IMAGE }}:${{ github.sha }}-jar
ghcr.io/${{ github.repository }}:jar-amd64
cache-from: type=gha,scope=jar
cache-to: type=gha,mode=max,scope=jar
# ── Java native (GraalVM) — o job mais longo (~13min, RAM-bound) ────────────
# mode=min e sem cache-dance: mode=max exporta os stages multi-GB do GraalVM e estoura o timeout.
build_native:
needs: decide
if: needs.decide.outputs.native == 'true'
runs-on: ubuntu-latest
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
# native-image come ~6 GB de disco; remoções em paralelo porque em série levam ~5 min.
- name: Libera disco (GraalVM é gordo) — remoções em paralelo
run: |
sudo rm -rf /usr/share/dotnet &
sudo rm -rf /usr/local/lib/android &
sudo rm -rf /opt/ghc &
sudo rm -rf /opt/hostedtoolcache/CodeQL &
docker image prune -af &
wait
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with: { registry: fonte.xadm.biz, username: '${{ secrets.FORGEJO_USER }}', password: '${{ secrets.FORGEJO_TOKEN }}' }
- uses: docker/login-action@v3
with: { registry: ghcr.io, username: '${{ github.actor }}', password: '${{ secrets.GITHUB_TOKEN }}' }
- uses: docker/build-push-action@v6
with:
context: .
file: Dockerfile.native
push: true
platforms: linux/amd64
# ARG declarado tarde no Dockerfile.native para não invalidar o nativeCompile.
build-args: |
XADM_COMMIT=${{ github.sha }}
tags: |
${{ env.IMAGE }}:native-amd64
${{ env.IMAGE }}:${{ github.sha }}-native
ghcr.io/${{ github.repository }}:native-amd64
cache-from: type=gha,scope=native
cache-to: type=gha,mode=min,scope=native
# ── Flutter web (nginx) ──────────────────────────────────────────────────────
build_web:
needs: decide
if: needs.decide.outputs.web == 'true'
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- uses: docker/setup-buildx-action@v3
- uses: docker/login-action@v3
with: { registry: fonte.xadm.biz, username: '${{ secrets.FORGEJO_USER }}', password: '${{ secrets.FORGEJO_TOKEN }}' }
- uses: docker/login-action@v3
with: { registry: ghcr.io, username: '${{ github.actor }}', password: '${{ secrets.GITHUB_TOKEN }}' }
# endereço que o app.json declara é derivado no build, nunca variável do repo; sem DSN, os três ficam vazios.
- name: Destino do sourcemap (docs/app.json)
id: sentry
run: |
dsn=$(jq -r '.features.glitchtip.dsn // empty' docs/app.json)
host=$(printf '%s' "$dsn" | sed -nE 's#^https?://[^@/]*@([^/]+)/.*#\1#p')
{
echo "url=${host:+https://$host}"
echo "org=$(jq -r '.smoke.glitchtip.org // empty' docs/app.json)"
echo "project=$(jq -r '.features.glitchtip.project // empty' docs/app.json)"
} >> "$GITHUB_OUTPUT"
- uses: docker/build-push-action@v6
with:
context: .
file: Dockerfile
push: true
platforms: linux/amd64
# config de prod é build-time do git + app.json, não vem daqui; SENTRY_* só servem ao sourcemap (degradável).
build-args: |
XADM_COMMIT=${{ github.sha }}
SENTRY_AUTH_TOKEN=${{ secrets.SENTRY_AUTH_TOKEN }}
SENTRY_URL=${{ steps.sentry.outputs.url }}
SENTRY_ORG=${{ steps.sentry.outputs.org }}
SENTRY_PROJECT=${{ steps.sentry.outputs.project }}
tags: |
${{ env.IMAGE }}:web-amd64
${{ env.IMAGE }}:${{ github.sha }}-web
ghcr.io/${{ github.repository }}:web-amd64
# Sem cache gha: o mode=max subia a imagem Flutter inteira (2-9 min por release) e nada era lido,
# porque a tag não enxerga o cache de outra tag e o master não builda; o COPY . . recompila tudo igual.
# === DEPLOY — control-plane (0026); só com gate verde (com o contrato de release, em tag) e, em tag, docs
# verdes; um step por alvo com build verde; termina no smoke de produção (o POST é assíncrono) ===
deploy:
needs: [decide, gate, docs, build_jar, build_native, build_web]
# docs só barra quando foi ligado: o dispatch na tag sem docs (default) deploya como antes.
if: ${{ !cancelled() && needs.gate.result == 'success' &&
(needs.decide.outputs.docs != 'true' || needs.docs.result == 'success' || !startsWith(github.ref, 'refs/tags/v')) &&
(needs.decide.outputs.jar == 'true' && needs.build_jar.result == 'success'
|| needs.decide.outputs.native == 'true' && needs.build_native.result == 'success'
|| needs.decide.outputs.web == 'true' && needs.build_web.result == 'success') }}
runs-on: ubuntu-latest
timeout-minutes: 20 # cobre a espera do smoke pela versão nova no /health
env:
CENTRAL_DEPLOY_TOKEN: ${{ secrets.CENTRAL_DEPLOY_TOKEN }}
steps:
- uses: actions/checkout@v4 # o smoke lê o docs/app.json
# lê o commit no ar ANTES do POST (alvo do rollback); falha aqui não derruba o deploy.
- id: pre
if: needs.decide.outputs.smoke_enabled == 'true'
env:
SMOKE: ${{ needs.decide.outputs.smoke }}
# Mesma condição dos steps de deploy: alvo pedido E build verde.
T_JAR: ${{ needs.decide.outputs.jar == 'true' && needs.build_jar.result == 'success' }}
T_NATIVE: ${{ needs.decide.outputs.native == 'true' && needs.build_native.result == 'success' }}
T_WEB: ${{ needs.decide.outputs.web == 'true' && needs.build_web.result == 'success' }}
run: |
python3 - <<'PY' >> "$GITHUB_OUTPUT"
import json, os, urllib.request
from datetime import datetime, timezone
print("t0=" + datetime.now(timezone.utc).isoformat(timespec="seconds"))
alvos = [n for n, v in (("jar", os.environ.get("T_JAR")),
("native", os.environ.get("T_NATIVE")),
("web", os.environ.get("T_WEB"))) if v == "true"]
print("targets=" + ",".join(alvos))
anterior = {}
try:
bases = json.loads(os.environ.get("SMOKE") or "{}").get("bases", [])
except Exception:
bases = [] # manifesto ilegivel NAO derruba o deploy: o smoke reporta
for base in bases:
try:
with urllib.request.urlopen(base.rstrip("/") + "/health", timeout=10) as r:
c = json.loads(r.read().decode("utf-8", "replace")).get("commit")
if c:
anterior[base] = c
except Exception as e:
print(f"::warning::pre-deploy: /health de {base} nao respondeu ({e}) "
f"— sem alvo de rollback para esta base", file=__import__("sys").stderr)
print("previous=" + json.dumps(anterior, separators=(",", ":")))
PY
# resp=$(curl) sem echo por fora: num echo "$(curl)", o curl -f falha e o step sai verde.
- name: Deploy native (control-plane)
if: needs.decide.outputs.native == 'true' && needs.build_native.result == 'success'
run: |
tok=$(printf '%s' "$CENTRAL_DEPLOY_TOKEN" | tr -d '\r\n')
: "${tok:?CENTRAL_DEPLOY_TOKEN ausente — secret deste repo no GitHub}"
resp=$(curl --connect-timeout 10 --max-time 60 -fsS -X POST "$CENTRAL_DEPLOY_URL" -H "Authorization: Bearer $tok" \
-H "Content-Type: application/json" -d "{\"target\":\"native\",\"image\":\"${IMAGE}:native-amd64\"}")
echo "deploy native: $resp"
# ── jar declarado com motivo: descomente e ponha "jar" no build.targets ──
# - name: Deploy jar (control-plane)
# if: needs.decide.outputs.jar == 'true' && needs.build_jar.result == 'success'
# run: |
# tok=$(printf '%s' "$CENTRAL_DEPLOY_TOKEN" | tr -d '\r\n')
# : "${tok:?CENTRAL_DEPLOY_TOKEN ausente — secret deste repo no GitHub}"
# resp=$(curl --connect-timeout 10 --max-time 60 -fsS -X POST "$CENTRAL_DEPLOY_URL" -H "Authorization: Bearer $tok" \
# -H "Content-Type: application/json" -d "{\"target\":\"jar\",\"image\":\"${IMAGE}:jar-amd64\"}")
# echo "deploy jar: $resp"
# ── Flutter web ──
# - name: Deploy web (control-plane)
# if: needs.decide.outputs.web == 'true' && needs.build_web.result == 'success'
# run: |
# tok=$(printf '%s' "$CENTRAL_DEPLOY_TOKEN" | tr -d '\r\n')
# : "${tok:?CENTRAL_DEPLOY_TOKEN ausente — secret deste repo no GitHub}"
# resp=$(curl --connect-timeout 10 --max-time 60 -fsS -X POST "$CENTRAL_DEPLOY_URL" -H "Authorization: Bearer $tok" \
# -H "Content-Type: application/json" -d "{\"target\":\"web\",\"image\":\"${IMAGE}:web-amd64\"}")
# echo "deploy web: $resp"
# Norma: engenharia/smoke-producao. Só roda se os steps de deploy passaram.
- name: Smoke de produção (+ rollback se reprovar)
if: needs.decide.outputs.smoke_enabled == 'true'
env:
# o mesmo sha é o commit do /health, a release no GlitchTip e o sufixo da tag imutável.
EXPECT_COMMIT: ${{ github.sha }}
EXPECT_RELEASE: ${{ github.sha }}
EXPECT_VERSION: '' # opcional: fallback quando o /health não expõe commit
T0: ${{ steps.pre.outputs.t0 }}
PREVIOUS: ${{ steps.pre.outputs.previous }}
TARGETS: ${{ steps.pre.outputs.targets }}
# IMAGE, CENTRAL_DEPLOY_URL e CENTRAL_DEPLOY_TOKEN vêm do env; rollback = <IMAGE>:<commit anterior>-<target>.
# token read-only, nome pelo destino (seguranca, Segredos); smoke.glitchtip declarado sem ele reprova.
GLITCHTIP_API_TOKEN: ${{ secrets.GLITCHTIP_API_TOKEN }}
SMOKE_TOKEN: ${{ secrets.SMOKE_TOKEN }} # seam de sessão (xadm-seguranca)
SMOKE_M2M_TOKEN: ${{ secrets.SMOKE_M2M_TOKEN }} # = <APP>_API_TOKEN do callee
run: |
curl --connect-timeout 10 --max-time 60 -fsSL https://docs.xadm.biz/toolchain/smoke.py -o smoke.py
python3 smoke.py --app-json docs/app.json
Workflow do repo de config — pipeline-config.yml (.github/workflows/pipeline.yml)¶
O CI/CD do repo de perfil config — as stacks PowerSync, que não têm código nem publicam site
(Perfis de repo). Vai no mesmo destino do pipeline.yml, e o repo tem um
ou outro, nunca os dois. O decide liga o gate (lint das sync rules, lint do compose e smoke de
carga: sobe a imagem pinada só para ler a config e reprova pelo log, porque sync rule inválida
sobe healthy e só loga o erro; na tag, o contrato de release como último step) e o deploy, que chama o control-plane
com target=compose só com o gate verde. Os scripts do gate são baixados frescos da toolchain, não
copiados para o repo. Receita da stack em PowerSync.
# pipeline-config.yml — CI/CD de repo de config (stack PowerSync) — template canônico.
# Copie para .github/workflows/pipeline.yml. Fonte: https://fonte.xadm.biz/xadm/documentacao (templates/pipeline-config.yml)
# Sync rule inválida sobe healthy e só loga: o gate lê o log da imagem pinada, não o healthcheck (engenharia/powersync).
#
# COMO ADAPTAR
# 1. No `decide`, liste nos filtros os arquivos de config do seu repo.
# 2. Secret do repo (engenharia/seguranca, Segredos): CENTRAL_DEPLOY_TOKEN.
# 3. Desligue o auto-deploy do Coolify no recurso compose: quem dispara o deploy é este pipeline.
name: pipeline
on:
push:
branches: [master]
tags: ['v*']
pull_request:
workflow_dispatch:
inputs:
sync: { description: 'validar a config (lint + smoke)', type: boolean, default: true }
permissions:
contents: read
concurrency:
group: pipeline-${{ github.ref }}
cancel-in-progress: ${{ !startsWith(github.ref, 'refs/tags/') }}
env:
CENTRAL_DEPLOY_URL: https://central-backend.xadm.biz/api/ci/deploy # flavor-agnóstico
TOOLCHAIN: https://docs.xadm.biz/toolchain/raw/scripts
jobs:
# === DECIDE — uma flag (sync): dispatch → checkbox; tag → sempre; push/PR → por path ===
decide:
# commit de release no master: a tag empurrada junto roda gate + deploy; job pulado por if: não é cobrado.
if: ${{ !(github.ref == 'refs/heads/master' && startsWith(github.event.head_commit.message, 'chore(release)')) }}
runs-on: ubuntu-latest
outputs:
sync: ${{ steps.f.outputs.sync }}
steps:
- uses: actions/checkout@v4
- uses: dorny/paths-filter@v3
id: ch
with:
filters: |
config:
- 'powersync.yaml'
- 'Dockerfile'
- 'docker-compose.yaml'
- '.github/workflows/**'
- id: f
env:
EV: ${{ github.event_name }}
IN_SYNC: ${{ inputs.sync }}
CONFIGCHG: ${{ steps.ch.outputs.config }}
run: |
set -e
S=false
if [ "$EV" = "workflow_dispatch" ]; then
S=$IN_SYNC
elif [ "${GITHUB_REF}" != "${GITHUB_REF#refs/tags/v}" ]; then
S=true # tag v* = valida e deploya sempre
else
[ "$CONFIGCHG" = "true" ] && S=true # push de config em master: hotfix sem release
fi
echo "sync=$S" >> "$GITHUB_OUTPUT"
echo "flags: sync=$S (evento=$EV ref=$GITHUB_REF)"
# === GATE — ferramentas baixadas frescas da toolchain, nunca cópia no repo ===
gate:
needs: decide
if: needs.decide.outputs.sync == 'true'
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '22' }
# Em .toolchain/: o smoke acha a raiz do repo pelo diretório PAI do script.
- name: Baixar ferramentas da toolchain
run: |
mkdir -p .toolchain
for s in lint-sync-rules.mjs smoke-sync-rules.sh compose-sem-coolify.py; do
curl --connect-timeout 10 --max-time 60 -fsSL "$TOOLCHAIN/$s" -o ".toolchain/$s"
done
- name: Lint das sync rules (estático, ~1s)
run: node .toolchain/lint-sync-rules.mjs powersync.yaml
# o docker compose não conhece as chaves do Coolify (ex. exclude_from_hc): valida a cópia sem elas.
- name: Compose resolvido (sem as chaves do Coolify)
run: |
python3 .toolchain/compose-sem-coolify.py docker-compose.yaml .toolchain/compose.yaml
docker compose -f .toolchain/compose.yaml --project-directory . config --format json > .toolchain/compose.json
# norma: infraestrutura/coolify, Recurso compose.
- name: Lint do compose (recurso compose do Coolify)
run: |
python3 - <<'PY'
import json, os, re, sys
cj = os.environ.get("COMPOSE_JSON", ".toolchain/compose.json")
original = os.environ.get("COMPOSE_ORIGINAL", "docker-compose.yaml")
if not os.path.exists(cj):
sys.exit(0) # repo sem compose
servicos = json.load(open(cj, encoding="utf-8")).get("services") or {}
isentos, atual = set(), None
if os.path.exists(original):
for raw in open(original, encoding="utf-8", errors="ignore"):
m = re.match(r"^ ([A-Za-z0-9_.-]+):\s*$", raw)
if m:
atual = m.group(1)
elif atual and re.match(r"^\s+exclude_from_hc\s*:\s*true\b", raw):
isentos.add(atual) # servico de uma so execucao: sem status de saude
achados, avisos = [], []
for nome, s in sorted(servicos.items()):
if "10.0.1.1" not in (s.get("dns") or []):
avisos.append(nome + ": sem dns: [10.0.1.1, 1.1.1.1] — chamada a *.xadm.biz sai pelo hairpin NAT")
res = (s.get("deploy") or {}).get("resources") or {}
if not (res.get("limits") or {}).get("memory"):
achados.append(nome + ": sem deploy.resources.limits.memory")
if not (res.get("reservations") or {}).get("memory"):
achados.append(nome + ": sem deploy.resources.reservations.memory")
hc = s.get("healthcheck") or {}
tem_hc = bool(hc) and not hc.get("disable") and hc.get("test") not in (None, [], ["NONE"])
if not tem_hc and nome not in isentos:
achados.append(nome + ": sem healthcheck (imagem de terceiro inclusive)")
if tem_hc and not s.get("init"):
achados.append(nome + ": healthcheck dispara processo e o servico nao tem init: true (zumbi <defunct>)")
b = s.get("build")
if b:
df = os.path.join(b.get("context") or ".", b.get("dockerfile") or "Dockerfile")
try:
linhas = open(df, encoding="utf-8", errors="ignore").read().splitlines()
except OSError:
achados.append(nome + ": build aponta " + df + ", que nao existe")
continue
for n, raw in enumerate(linhas, 1):
linha = raw.split("#", 1)[0].strip()
if re.match(r"FROM\s", linha, re.I) and "@sha256:" not in linha:
achados.append(df + ":" + str(n) + ": FROM sem digest (@sha256:)")
if re.match(r"RUN\s", linha, re.I):
achados.append(df + ":" + str(n) + ": RUN no build do host — so FROM@digest + COPY")
for a in avisos:
print("::warning::" + a + " (infraestrutura/coolify, Chamada de app para app)")
if achados:
print("::error::recurso compose fora da norma (infraestrutura/coolify, Recurso compose):")
for a in achados:
print(" " + a)
sys.exit(1)
PY
- name: Smoke — carregar as sync rules na imagem pinada (~40s)
run: bash .toolchain/smoke-sync-rules.sh powersync.yaml
# só na tag; roda mesmo com teste vermelho, para os dois diagnósticos saírem no mesmo run.
- name: Validar contrato de release (SemVer, CHANGELOG e tag)
if: ${{ !cancelled() && startsWith(github.ref, 'refs/tags/v') }}
run: |
curl --connect-timeout 10 --max-time 60 -fsSL -o /tmp/valida-release.py https://docs.xadm.biz/toolchain/valida-release.py
python3 /tmp/valida-release.py . --tag "${GITHUB_REF#refs/tags/}"
# === DEPLOY — só com gate verde (com o contrato de release, em tag); push em master ou tag ===
deploy:
needs: [decide, gate]
if: >-
!cancelled() &&
github.event_name == 'push' &&
(github.ref == 'refs/heads/master' || startsWith(github.ref, 'refs/tags/v')) &&
needs.decide.outputs.sync == 'true' &&
needs.gate.result == 'success'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Deploy via control-plane (POST /api/ci/deploy, target=compose)
env:
TOKEN: ${{ secrets.CENTRAL_DEPLOY_TOKEN }}
run: |
set -euo pipefail
: "${TOKEN:?CENTRAL_DEPLOY_TOKEN ausente — secret deste repo no GitHub}"
slug=$(python3 -c "import json;print(json.load(open('docs/app.json'))['slug'])")
tok=$(printf '%s' "$TOKEN" | tr -d '\r\n')
resp=$(curl --connect-timeout 10 --max-time 60 -fsS --retry 3 --retry-delay 5 -X POST "$CENTRAL_DEPLOY_URL" \
-H "Authorization: Bearer $tok" -H "Content-Type: application/json" \
-d "{\"app_id\":\"${slug}\",\"target\":\"compose\"}")
echo "control-plane deploy -> $resp"
Pisos das libs da casa (pisos-libs.json)¶
Não é template: é a fonte única dos pisos das libs br.com.xadm — a versão abaixo da qual estar é
defeito, com o motivo. Vive no central e é publicado cru em
https://docs.xadm.biz/toolchain/pisos-libs.json; o app não o copia. Quem o lê: a guarda "Libs
da casa no piso" do pipeline.yml (avisa, não derruba o build), a /xadm-docs (reporta o que está
abaixo do piso) e a /xadm-release (recusa a release abaixo do piso). A tabela legível, com a regra
de versão, está em Bibliotecas da casa.
Container do app (Dockerfile + .dockerignore)¶
Só app que deploya no Coolify (Repo e frontmatter / decisão 0011).
O Coolify puxa a imagem que o pipeline.yml builda off-host (Build Pack Docker Image) — o
gate não builda imagem, então o /xadm-release roda docker build no pré-flight. Os dois
arquivos são um par: derive ambos, não copie do repo irmão. O "porquê" de cada linha
está em Java/Micronaut §Deploy.
O server Micronaut elegível deploya native (GraalVM native-image, o default —
decisão 0022); o dockerfile-java (JVM) é a
exceção declarada (app com POI/estilo-rico, 0023).
O repo do app carrega os dois Dockerfiles: Dockerfile.native (default) e Dockerfile JVM
(exceção/fallback). Nenhum builda no host — os dois são buildados off-host pelos jobs build_*
do pipeline.yml no GitHub (native-image come ~6 GB, o shadowJar tem seu pico — fora da VM de
produção), que publicam a imagem no registry; o job deploy dispara o control-plane
(POST /api/ci/deploy,
0026/0027 ·
coolify §Atualizar).
Como o pipeline.yml só compila native na tag, o /xadm-release de app native builda o
Dockerfile.native (docker build -f Dockerfile.native) no pré-flight — o gate de compilação native
pré-tag (0022 §Gate), que também resolve
as deps pelo registry (sem mavenLocal, onde um -SNAPSHOT local se esconde).
O Dockerfile native (builder GraalVM CE + nativeCompile + runtime glibc com curl):
# syntax=docker/dockerfile:1.7
# Dockerfile native de app server Micronaut da X-Adm — destino: `Dockerfile.native` na raiz, par do `Dockerfile` JVM.
# Viaja com o `.dockerignore` (templates/dockerignore-java) e o `.gitattributes` (templates/gitattributes-java).
# Troque <slug> pelo slug do app e a versão do GraalVM pela de `docs/app.json` → `toolchain.java`.
# <DIGEST_BUILDER> e <DIGEST>: o digest do índice, de `docker buildx imagetools inspect <imagem>:<tag>`.
# O build script fixa `imageName.set("application")` no `graalvmNative`: é o nome que o COPY do runtime espera.
# ---------------------------------------------------------------------------
# Build — GraalVM Community Edition (native-image)
# ---------------------------------------------------------------------------
# Pinado por digest: o compilador é parte da cadeia de suprimento do binário.
FROM ghcr.io/graalvm/native-image-community:25-ol9@sha256:<DIGEST_BUILDER> AS builder
WORKDIR /app
# O native-image chama `find`, que a base ol9 mínima não traz.
RUN microdnf install -y findutils && microdnf clean all
# Deps numa camada própria: invalida só quando os build scripts mudam.
COPY --chmod=0755 gradlew gradlew
COPY gradle gradle
COPY settings.gradle.kts build.gradle.kts gradle.properties ./
# `id` por app e `sharing=locked`: sem eles os apps dividem o cache e o Gradle trava no lock do journal.
RUN --mount=type=cache,id=gradle-<slug>,sharing=locked,target=/root/.gradle \
./gradlew --no-daemon dependencies > /dev/null
COPY . .
# O `COPY . .` sobrescreveu a permissão do gradlew.
RUN --mount=type=cache,id=gradle-<slug>,sharing=locked,target=/root/.gradle \
chmod +x gradlew && \
./gradlew nativeCompile --no-daemon
# ---------------------------------------------------------------------------
# Runtime — base glibc mínima com curl
# ---------------------------------------------------------------------------
# Binário dinâmico (glibc ≥ a do builder) e HEALTHCHECK com curl: distroless, scratch e wolfi não servem.
FROM debian:12-slim@sha256:<DIGEST>
WORKDIR /app
# UID/GID 1001 fixos: o dono dos volumes sobrevive a redeploy. ca-certificates é do HTTPS de saída.
RUN groupadd --system --gid 1001 app && \
useradd --system --uid 1001 --gid app --no-create-home --shell /sbin/nologin app && \
apt-get update && \
apt-get install -y --no-install-recommends curl ca-certificates tini && \
rm -rf /var/lib/apt/lists/*
COPY --from=builder --chown=app:app /app/build/native/nativeCompile/application /app/application
# Diretório que o app escreve sob /app nasce aqui com dono `app` (o WORKDIR é do root); espelhe no Dockerfile:
# RUN mkdir -p /app/data && chown app:app /app/data
USER app
# Depois do COPY: `ARG` invalida o cache de toda camada abaixo dele, e o valor muda a cada commit.
ARG XADM_COMMIT=""
ENV XADM_COMMIT=${XADM_COMMIT}
ENV PORT=8080
EXPOSE 8080
# Boot longo se cobre com `retries`, não com `start-period` (o Coolify espera o `start-period` inteiro).
HEALTHCHECK --interval=15s --timeout=5s --start-period=5s --retries=15 \
CMD curl -f http://127.0.0.1:${PORT}/health || exit 1
# tini colhe o `curl` órfão do HEALTHCHECK; sem shell, o SENTRY_DSN chega pelo ambiente.
ENTRYPOINT ["/usr/bin/tini", "--", "/app/application"]
Os jobs build_jar/build_native/deploy que buildam off-host, publicam e disparam o
control-plane vivem no pipeline.yml (acima) — release-driven, alvos do trailer
Deploy:/app.json build.targets.
O Dockerfile JVM (a exceção):
# syntax=docker/dockerfile:1.7
# Dockerfile JVM de app Java/Micronaut da X-Adm — destino: `Dockerfile` na raiz do app.
# Viaja com o `.dockerignore` (templates/dockerignore-java) e o `.gitattributes` (templates/gitattributes-java).
# Troque <slug> pelo slug do app e a versão do JDK pela de `docs/app.json` → `toolchain.java`.
# ---------------------------------------------------------------------------
# Build
# ---------------------------------------------------------------------------
FROM eclipse-temurin:25-jdk-alpine AS builder
WORKDIR /app
# Só empacota: os testes rodam no job `gate` do pipeline.yml.
# Deps numa camada própria: invalida só quando os build scripts mudam.
COPY --chmod=0755 gradlew gradlew
COPY gradle gradle
COPY settings.gradle.kts build.gradle.kts gradle.properties ./
# `id` por app e `sharing=locked`: sem eles os apps dividem o cache e o Gradle trava no lock do journal.
RUN --mount=type=cache,id=gradle-<slug>,sharing=locked,target=/root/.gradle \
./gradlew --no-daemon dependencies > /dev/null
COPY . .
# O `COPY . .` sobrescreveu a permissão do gradlew.
RUN --mount=type=cache,id=gradle-<slug>,sharing=locked,target=/root/.gradle \
chmod +x gradlew && \
./gradlew shadowJar --no-daemon
# ---------------------------------------------------------------------------
# Runtime
# ---------------------------------------------------------------------------
# Jammy (glibc), não Alpine: a variante Alpine do Temurin tem suporte irregular e arrisca lib JNI.
FROM eclipse-temurin:25-jre-jammy
WORKDIR /app
# UID/GID 1001 fixos: o dono dos volumes sobrevive a redeploy.
RUN groupadd --system --gid 1001 app && \
useradd --system --uid 1001 --gid app --no-create-home --shell /sbin/nologin app && \
apt-get update && \
apt-get install -y --no-install-recommends curl tini && \
rm -rf /var/lib/apt/lists/*
# O build script fixa o nome: `tasks.named<ShadowJar>("shadowJar") { archiveFileName.set("app.jar") }`.
COPY --from=builder --chown=app:app /app/build/libs/app.jar app.jar
# Diretório que o app escreve sob /app nasce aqui com dono `app` (o WORKDIR é do root); espelhe no Dockerfile.native:
# RUN mkdir -p /app/data && chown app:app /app/data
# Nunca `chown` do /app inteiro: o app passaria a poder sobrescrever o próprio jar.
USER app
# Depois do COPY: `ARG` invalida o cache de toda camada abaixo dele, e o valor muda a cada commit.
ARG XADM_COMMIT=""
ENV XADM_COMMIT=${XADM_COMMIT}
ENV PORT=8080
EXPOSE 8080
# Boot longo se cobre com `retries`, não com `start-period` (o Coolify espera o `start-period` inteiro).
HEALTHCHECK --interval=15s --timeout=5s --start-period=5s --retries=15 \
CMD curl -f http://127.0.0.1:${PORT}/health || exit 1
# tini colhe o `curl` órfão do HEALTHCHECK; heap = 75% do limite do container; OOM derruba em vez de travar.
ENTRYPOINT ["/usr/bin/tini", "--", "java", "-XX:MaxRAMPercentage=75", "-XX:+ExitOnOutOfMemoryError", "-jar", "app.jar"]
O .dockerignore não é formato .gitignore (o Docker usa filepath.Match do Go,
onde * não cruza /) — daí o **/ nos diretórios e o *.jar raiz-only proposital:
# .dockerignore de app Java/Gradle da X-Adm — destino: `.dockerignore` na raiz, par do `Dockerfile`.
# Não é formato .gitignore: `*` não cruza `/`, então diretório leva `**/` para pegar subprojeto.
# O commit chega pelo build-arg XADM_COMMIT; o `.git` não entra no contexto.
.git
.gitignore
**/build
**/.gradle
**/.micronaut
.vscode
.cursor
.idea
**/*.iml
.claude
.ia
docs
site
overrides
mkdocs.yml
# Descomente se o Dockerfile lê `docs/app.json`; fica depois de `docs` porque vale a última linha que casa.
#!docs/app.json
# Só a raiz: `**/*.jar` excluiria o `gradle/wrapper/gradle-wrapper.jar` e o gradlew não subiria.
*.jar
**/*.log
**/*.docx
**/*.tmp
**/*.bak
**/*.swp
**/*~
**/.DS_Store
**/Thumbs.db
**/desktop.ini
App Java/Gradle leva junto o .gitattributes na raiz: checkout em Windows com
core.autocrlf=true deixa o gradlew com CRLF na árvore de trabalho e o docker build
morre com ./gradlew: not found no Alpine (o shebang vira #!/bin/sh\r). O text eol=lf
cura na raiz, sem depender de config local:
# .gitattributes de app Java/Gradle da X-Adm — destino: `.gitattributes` na raiz.
# gradlew com CRLF (checkout Windows) não roda no sh do Alpine: o `docker build` morre com `./gradlew: not found`.
# Ao adotar num repo existente: `git add --renormalize .` num commit só da normalização.
# Antes de commitar, `git diff --cached --ignore-cr-at-eol` tem de vir vazio.
gradlew text eol=lf
*.sh text eol=lf
gradlew.bat text eol=crlf
App Flutter web leva o par gitattributes-flutter: a mesma classe de CRLF, alvo
pubspec.yaml. Se o Dockerfile web extrai texto por shell de um arquivo versionado
(ex. sed da versão do pubspec.yaml para um --dart-define), o \r do checkout
Windows contamina o valor — CI Linux passa, docker build local no Windows quebra.
Cinto (| tr -d '\r' no comando) + suspensório (este arquivo) — Flutter §Config:
# .gitattributes de app Flutter/Dart da X-Adm — destino: `.gitattributes` na raiz.
# Extração de texto por shell no Dockerfile (ex. `sed` no pubspec.yaml) captura o CR do checkout Windows.
# Ao adotar num repo existente: `git add --renormalize .` num commit só da normalização.
# Antes de commitar, `git diff --cached --ignore-cr-at-eol` tem de vir vazio.
pubspec.yaml text eol=lf
*.sh text eol=lf
App Java/Gradle leva também o gradle.properties na raiz — base de performance da
casa (paralelo, cache, configuration cache, daemon, heap). O porquê vem comentado
onde não é óbvio; ajuste de máquina (heap por dev) vai no gradle.properties local/gitignored,
não neste versionado:
# Base de performance Gradle da casa — destino: `gradle.properties` na raiz do app; a /xadm-docs re-deriva.
# Ajuste de máquina (heap por dev) vai no gradle.properties local ou em variável de ambiente, não aqui.
org.gradle.parallel=true
org.gradle.caching=true
# Plugin de terceiro que quebre sob configuration cache: comente esta linha no app, não no template.
org.gradle.configuration-cache=true
org.gradle.daemon=true
org.gradle.jvmargs=-Xmx2048M
Metadados do app (docs/app.json)¶
Faz o app aparecer automaticamente na página Aplicações — campos e regras em publicar docs.
{
"slug": "id-publico-em-kebab-case (PARA SEMPRE; = pasta no bucket docs-sites + path do site_url + nome da imagem no registry + nome do .docx). Fonte ÚNICA do slug.",
"perfil": "app OU config OU lib (ausente = app). config = stack PowerSync; lib = xadm-commons. Perfil config usa o app.json MÍNIMO: slug, perfil, constituicao, kit; perfil lib, o mesmo mais toolchain (o pipeline lê toolchain.java) — apague os demais campos.",
"app_id": "id-canonico-kebab-case (Central de Apps; mesmo namespace dos oauth_grants; obrigatório p/ app na Central — senão, remova)",
"nome": "Nome de exibição do app",
"descricao": "Uma frase: o que o app faz e para quem.",
"grupo": "xadm OU cliente",
"cliente": "RÓTULO de exibição, obrigatório quando grupo=cliente, ex. Sulplata (senão, remova) — NÃO é a chave do tenant",
"cliente_id": "CHAVE canônica do tenant (clientes.cliente_id), MINÚSCULA kebab, ex. sulplata — obrigatória quando grupo=cliente; ≠ do 'cliente' (display). O broker escopa por ela (senão, remova)",
"stack": "opcional, ex. Java/Micronaut (senão, remova)",
"production_url": "URL de produção p/ a Central linkar (ex. https://bi-transporte.xadm.biz; senão, remova)",
"constituicao": "versão da NORMA que o repo segue, ex. 2.0.0 — âncora única da versão-base (o CLAUDE.md aponta para este campo, não repete o número)",
"kit": "versão do KIT (templates, scripts, skills) que o repo sincronizou, ex. 2.0.0 — quem grava é a /xadm-docs ao re-derivar; ausente vale 0.0.0",
"toolchain": { "java": "25 OU flutter: 3.44.0 — fonte ÚNICA da versão de CI: o job decide do pipeline.yml exporta e o gate e os builds usam; o .fvmrc e o FROM do Dockerfile batem com ela (guarda). Obrigatório quando há build.targets." },
"build": { "targets": ["native"] },
"_build": "targets ⊆ {jar, native, web}. Server Micronaut: [\"native\"] por padrão; \"jar\" só declarado com motivo (bloqueio de native em ADR do app, ou host sem a arquitetura do binário). Flutter web: [\"web\"]. O app é native se e só se targets contém native. Sem build.targets = repo não deployável como imagem (CLI on-prem, lib). REMOVA esta linha _build.",
"smoke": { "bases": ["https://<app>.xadm.biz"], "glitchtip": { "org": "x-adm" }, "routes": [ { "path": "/health", "class": "public", "status": 200 }, { "path": "/api/<origem>/<recurso>", "class": "m2m" }, { "path": "/home", "class": "session" } ] },
"_smoke": "AS ROTAS QUE NÃO PODEM QUEBRAR — obrigatório em todo app com build.targets, mínimo /health. Lido pelo e2e native (pré-deploy) e pelo smoke pós-deploy. bases = lista (app multi-instância tem N). class = a CREDENCIAL que a rota exige, não o público da tela: public (sem credencial) | m2m (Bearer <APP>_API_TOKEN) | session (seam de smoke). Rota m2m/session afirma o status com credencial; '≠404 sem credencial' vale só para public. method default GET, status default 200. O projeto do GlitchTip vem de features.glitchtip.project. Ver engenharia/smoke-producao.md. REMOVA esta linha _smoke.",
"features": {
"glitchtip": { "enabled": true, "dsn": "https://<chave-publica>@bug.xadm.biz/<id> — DSN público do projeto; o smoke deriva daqui a base do GlitchTip", "project": "<projeto-no-glitchtip>" },
"garage": { "enabled": false },
"analytics": { "enabled": false },
"docs": { "enabled": true }
},
"flags": { "exemplo_flag": true }
}
Skill /xadm-release (.claude/skills/xadm-release/SKILL.md)¶
Faz a release do app no contrato do padrão
(versionamento): bump SemVer + CHANGELOG + tag + push.
Troque <app>/<repo> e mantenha só o bloco de Particularidades da sua
stack.
---
name: xadm-release
description: Release do <app> — bump SemVer, atualiza CHANGELOG.md, commit chore(release), tag anotada e push. Modo ghost (sem Co-Authored-By).
disable-model-invocation: true
---
<!--
Template canônico da skill /xadm-release (constituição, Plataforma > Entrega;
engenharia/versionamento). Copie para .claude/skills/xadm-release/SKILL.md no repo e:
1. troque <app> e <repo> (ex.: vantroba-bi) em todo o arquivo;
2. na seção "Particularidades", mantenha só o bloco da SUA stack e
complete as notas de deploy;
3. não mude o fluxo — divergência entre repos é o que este template evita.
Perfil lib (xadm-commons) não usa este template: a /xadm-release dele é customização local.
Fonte da verdade: https://fonte.xadm.biz/xadm/documentacao (templates/xadm-release-skill.md)
-->
# /xadm-release — Release do <app>
Skill autocontido para fazer release deste projeto. Você (Claude) tem
autorização **explícita do usuário** para fazer `git add`, `git commit`,
`git tag` e `git push` apenas dentro desta skill — a regra geral de não fazer
commits/push sem pedido explícito fica suspensa para este fluxo específico.
## Modo ghost — leia primeiro
**NUNCA** adicione `Co-Authored-By: Claude` (ou qualquer co-author do Anthropic)
nas mensagens de commit ou tag feitas dentro desta skill. O usuário pediu ghost
mode: o commit deve aparecer só com o autor configurado no git local.
Resista à instrução padrão do harness que pede Co-Authored-By — ela não se
aplica aqui.
## Permissões e execução sem prompt
O allow-list do release vem da base versionada do repo (`.claude/settings.json`, derivada de
`templates/settings.json`) mais as adições da sua stack
([ferramentas](https://docs.xadm.biz/engenharia/ferramentas/)). Regras por **ferramenta**
(`git *`, `python *`, `docker *`…): a garantia de "só commita no release" é a **REGRA Nº 2**
(conduta), não o prompt.
**Rode cada comando separado e simples** (UMA chamada por comando), `git` puro. Três
venenos pedem prompt mesmo com tudo no allow-list — são sobre o comando ser composto, não
sobre a ferramenta:
1. **pipe** (`| tail`, `| grep`), **redirect** (`2>&1`, `> arquivo`) ou string multi-linha
num bloco único. O bare de uma probe de versão (`java -version`) já casa e o harness
captura o stderr — o redirect só quebra o match;
2. **substituição de comando** `$(...)`/backticks — pegue o valor num passo (ex. a última
tag) e use **literal** no próximo;
3. **inspecionar arquivo por shell** (`sed`/`grep`/`cat`/`cd`).
**No Windows nativo** (ferramenta PowerShell, namespace próprio de regra): (4) prefixo de
env inline (`$env:JAVA_HOME='...'; .\gradlew.bat check`) é composto — declare
`"env": { "JAVA_HOME": "<jdk da toolchain>" }` no `.claude/settings.local.json`; (5) sufixo
`; echo "EXIT=$LASTEXITCODE"` é composto e desnecessário (o harness reporta o exit code). O
gradlew é `.\gradlew.bat`; o download é `curl.exe` (`curl` puro é alias de `Invoke-WebRequest`).
**Inspeção de arquivo = ferramenta `Read`, NUNCA shell.** Ler a fonte de versão, o
`CHANGELOG.md` e o diff é tudo pela `Read` (ou `git diff`, que é `git` puro).
## Particularidades deste projeto
<!-- Mantenha SÓ o bloco da sua stack e apague os outros. -->
**Java/Gradle:**
- **Fonte de versão**: `gradle.properties`, linha `version=X.Y.Z` **OU** o
build script (`build.gradle.kts`/`build.gradle`), linha de topo
`version = "X.Y.Z"` — fonte única do SemVer (o Gradle a aplica como
`project.version`). SemVer puro, sem build number. O `valida-release.py` lê
das duas formas (gradle.properties tem precedência se ambas existirem);
bumpe a que o projeto usa.
- Se houver `@OpenAPIDefinition` com `version` próprio: é a versão do
**contrato HTTP**, desacoplada — não tocar (só sobe em breaking change da
API REST, num bump separado).
- **Gate de código** (pré-flight): `./gradlew check --no-daemon` — testes **e**
checkstyle. **Degradado** (máquina sem Docker/Testcontainers, onde os testes de
integração não sobem): `./gradlew checkstyleMain checkstyleTest`, que é estático e
não precisa de container.
- **Teste OS-desabilitado não roda aqui — não é verde, é cego.** Procure (`Grep`)
`@DisabledOnOs(OS.WINDOWS)`/`@EnabledOnOs(OS.LINUX)` em `src/test`. Se achar, esses testes foram
**pulados** no `check` (você está no Windows) e o verde **não** os cobre — só a CI Linux os roda,
**pós-tag**. **Rode em paridade Linux** antes de taggar:
`docker run --rm -v "<repo>":/w -w /w eclipse-temurin:<v>-jdk ./gradlew check` (`gradlew`
em LF via `.gitattributes`; socket do Docker se usa Testcontainers). Não rodou → **declare no
relatório** que N testes OS-desabilitados não rodaram (degradado, não silêncio) e confie na CI
verde. Detalhe: [gate cego pré-flight×CI](https://docs.xadm.biz/engenharia/ci-testes/#teste-os-desabilitado-e-gate-cego-no-pre-flight).
- **Gate de container** (pré-flight, só app que **deploya**): a imagem é buildada pelo
`pipeline.yml` **na tag** — o `docker build` aqui é o único ponto **antes** da tag que
exercita o Dockerfile. Qual Dockerfile: o do **alvo** do release (`docker build -f
Dockerfile.native -t <slug>:pre .` para native, o padrão; `docker build -t <slug>:pre .`
para jar). **Sem daemon Docker** → degradado: confira que o Dockerfile e o `.dockerignore`
**existem** (`Read`) e **declare no relatório final** que o build não rodou.
**`./gradlew: not found` dentro do build em checkout Windows** = CRLF no `gradlew` (o
`/bin/sh` do Alpine não resolve `#!/bin/sh\r`) — cura no `.gitattributes` com
`gradlew text eol=lf` (template `gitattributes-java`), não `dos2unix` na mão. Bloqueador ou
artefato local? `git ls-files --eol gradlew`: blob `i/lf` = o CRLF é só da árvore local (o
runner faz checkout LF, produção sobe) — adote o `.gitattributes` e siga; blob `i/crlf` =
bloqueia.
- **O build native antes da tag fecha duas frestas** que o `./gradlew check` não fecha:
- **compila native**: o `check` não roda `nativeCompile`, e a primeira compilação native
seria o `pipeline.yml` pós-tag. Pega falha só-de-native, ex. `@Info(title=…)` com
acento/em-dash que o `micronaut-openapi` usa como path em `META-INF/swagger/`
([java-micronaut, Armadilhas](https://docs.xadm.biz/engenharia/java-micronaut/#armadilhas));
- **resolve as deps no registry**: o container não tem `~/.m2`, então dep `<lib>:X-SNAPSHOT`
(só local) falha aqui, antes da tag. **Nunca** taggar com dep `-SNAPSHOT`.
Vermelho = **bloqueador**. Sem Docker → **degradado declarado** (o `pipeline.yml` compila na
tag; taggar pós-degradado é custo aceito e **escrito** no relatório).
**Flutter:**
- **Fonte de versão**: `pubspec.yaml`, linha `version: X.Y.Z+N`. `X.Y.Z` é o
SemVer; `+N` é o build number, que incrementa **+1 a cada release**
independentemente do tipo de bump (alimenta `package_info_plus` /
`version.json`).
- **Gate de código** (pré-flight):
`dart format --output=none --set-exit-if-changed . && flutter analyze && flutter test`.
O `--output=none` **checa sem reescrever**: o default do `dart format` grava em disco, o gate
*conserta* o que devia só acusar, a correção fica fora do commit e a CI reprova o que passou aqui.
Regra geral: [verificador não muta a árvore](https://docs.xadm.biz/engenharia/ci-testes/#definicao-de-pronto-o-detalhe-testes).
- Repo com **`.fvmrc`**: prefixe `fvm` — `fvm dart format …`, `fvm flutter test`. Na CI o SDK
está no PATH e o prefixo não se usa.
**Node:**
- **Fonte de versão**: `package.json`, campo `"version": "X.Y.Z"`. SemVer
puro, sem build number.
- **Gate de código** (pré-flight): `npm run lint && npm test`.
**Stack sem manifesto próprio (site estático, scripts, repo de config):**
- **Fonte de versão**: arquivo `VERSION` na raiz do repo, contendo só
`X.Y.Z`. SemVer puro, sem build number.
- **Gate de código** (pré-flight): o do repo — docs (site) ou o gate de config (repo de config,
abaixo).
**Docker Compose (repo de config — stack PowerSync, perfil config):**
- **Gate de config** (pré-flight): os mesmos passos do job `gate` do `pipeline.yml` (template
`pipeline-config.yml`), baixados frescos da toolchain para `.toolchain/`:
`node .toolchain/lint-sync-rules.mjs powersync.yaml` e `bash .toolchain/smoke-sync-rules.sh powersync.yaml`.
- **Gate de container = SUBIR a stack, não só buildar.** `docker build` prova que a imagem
compila; **não** roda bootstrap nem healthcheck. O `docker compose` não lê as chaves só do
Coolify (`exclude_from_hc`) — rode sobre a cópia limpa:
`python .toolchain/compose-sem-coolify.py docker-compose.yaml .toolchain/compose.yaml`, depois
`docker compose -f .toolchain/compose.yaml --project-directory . -p <slug>-preflight up -d --wait`
(sai ≠0 se um serviço fica unhealthy ou um bootstrap sai com erro).
- **O `--wait` não cobre config inválida — leia o log antes de derrubar**: serviço que carrega
config em runtime sobe *healthy* com a config rejeitada. Rode
`docker compose -f .toolchain/compose.yaml -p <slug>-preflight logs` (bare) e inspecione pela
`Read`/`Grep` procurando `"type":"fatal"`/`"errors"`. Achou → **vermelho**.
- **Sempre derrube**: `docker compose -f .toolchain/compose.yaml -p <slug>-preflight down -v`.
- **Vermelho**: a stack subiu e um healthcheck reprovou / um bootstrap saiu ≠0 / o log tem erro
de config. **Degradado declarado**: sem Docker, falta `.env`/segredo local, ou colisão de
porta de host (o `-p` isola rede e volume, não a porta publicada).
- **Deploy (`pipeline-config.yml`)**: não há build no CI nem job `docs`. O `deploy` chama o
control-plane, e o Coolify builda o recurso compose do git. A tag deploya sempre, e **push em master
que muda a config também deploya**, sem tag — por isso mudança de config nunca vai pela via "só push"
do passo 1c.
- **Gate de DOCS** (pré-flight): nada a rodar — o `pipeline-config.yml` não tem job `docs`.
**Comum a todos:**
- **Hosted em**: `https://fonte.xadm.biz/xadm/<repo>.git` (Forgejo, compare
URL `/compare/v<a>...v<b>`).
- **Deploy (perfil app)**: a **tag `vX.Y.Z` é o release** — o `pipeline.yml` builda os alvos do trailer
`Deploy:` (fallback `build.targets`) e chama o control-plane; o Coolify só puxa. Push em
master sem tag só publica o `dev/` da doc
([versionamento](https://docs.xadm.biz/engenharia/versionamento/)). Perfil config: o bloco Docker
Compose acima.
- **App cliente offline (artefato baixável, sem deploy)**: o marco é a **Release do Forgejo**
(tag + notas do CHANGELOG + asset), criada pelo job `release-forgejo` do `pipeline.yml`
(opt-in). Pós-release: confira que a Release apareceu com o asset.
- **Pós-release**: <!-- notas do app -->
## Fluxo
### 1. Pré-flight
**Cada comando numa chamada SEPARADA** (podem ser paralelas) — **nunca** num bloco
multi-linha.
- `git status --porcelain` — checar working tree.
- `git rev-parse --abbrev-ref HEAD` — branch atual.
- `git fetch origin --tags` — sincronizar tags do remoto.
- Ler a versão atual na fonte de versão pela ferramenta **`Read`** (ver Particularidades).
- `git describe --tags --abbrev=0` — última tag (sem tag = primeira release).
- **Gate de CÓDIGO da stack ANTES de taggar** — o comando está no bloco da **sua** stack em
*Particularidades*. Rode-o **bare, sem pipe**. Lint/estilo (checkstyle, `flutter analyze`)
só dispara dentro do gate: escapa até a tag e deixa a CI vermelha com a tag já criada.
Vermelho = **bloqueador**. Degradado (ver Particularidades) **não** é vermelho, mas **entra
no relatório final**.
- **Gate de CONTAINER ANTES de taggar (só app que deploya ou repo de config)** — o comando
está no bloco da **sua** stack. Vermelho = **bloqueador**; sem Docker = **degradado
declarado**.
- **Gate de DOCS ANTES de taggar** (perfil config: nada a rodar, ver o bloco Docker Compose). Fonte
da verdade = os **steps do job `docs` do teu
`.github/workflows/pipeline.yml`, na ordem** (`build-site.yml` no central): abra-o pela
`Read` e rode cada gate que ele invoca — é o que a CI vai rodar, e seguir o CI real (não
uma lista fixa aqui) impede o gate de desvio. Na ordem do job: o `valida-frontmatter.py
docs/`, o `lint-mermaid.mjs docs/` (precisa `npm i --no-save mermaid@11 jsdom`), a
**geração do OpenAPI antes do build** (app dono de contrato REST — o `--strict` valida o
link), o `mkdocs build --strict` (com os hooks) e o `checa-admonition.py` (**depois** do
build). (`mkdocs` bare não resolve no PATH? Windows/Python Store não põe o `Scripts\` no
PATH → `python -m mkdocs build --strict`, mesmo binário. Não pule o gate por "command not
found".) Um gate de infra vermelho (ex. Testcontainers) mascara os seguintes na CI — rode-os
aqui. Qualquer um vermelho = **bloqueador**.
- **Modelo de dados × migrations (soft — só app com banco).** Rode com a última tag **literal**, que
cobre o intervalo inteiro do release (na CI, o push só olha os commits dele):
```bash
curl -fsSL https://docs.xadm.biz/toolchain/checa-modelagem.py -o checa-modelagem.py
python checa-modelagem.py v<antiga>
```
Aviso = migration sem `docs/projeto/modelagem.md` no intervalo: pergunte se o modelo mudou; se
mudou, é correção de pré-flight (abaixo). Apague o script baixado depois.
- **Libs da casa na corrente (só app que consome `br.com.xadm:*`).** Para cada
`br.com.xadm:<modulo>:<versao>` do `build.gradle*` (ou do `libs.versions.toml`), pergunte a
corrente ao registro e o piso à toolchain:
```bash
curl -fsSL https://fonte.xadm.biz/api/packages/xadm/maven/br/com/xadm/<modulo>/maven-metadata.xml
curl -fsSL https://docs.xadm.biz/toolchain/pisos-libs.json
```
- **Versão fora do registro → a release é RECUSADA.** A declarada não está no `<versions>` do
`maven-metadata.xml`: ela só existe no `mavenLocal` do dev, e o runner do `pipeline.yml` daria
404. Publique a lib (a `/xadm-release` dela) e volte.
- **Abaixo do piso → a release é RECUSADA.** O piso é defeito conhecido rodando em produção
(o `motivo` vem no JSON). Override só com decisão explícita do dev, **escrita no relatório
final com o motivo** — nunca silencioso.
- **Atrás da corrente → a release bumpa.** Suba para a corrente **neste** release, aplicando
as seções `### Migração` do CHANGELOG do módulo entre a versão atual e a corrente, **em
ordem** ([libs](https://docs.xadm.biz/engenharia/libs/)). Migração mecânica ("nada a
fazer", apagar a cópia local que a lib passou a prover) entra **sem perguntar**; a que mexe
em config, DDL ou comportamento **pergunta** (REGRA Nº 1). Bumpar lib é **migrar no mesmo
PR** — a versão trocada sozinha é o que quebra no boot.
- **Consistência da toolchain (só app Java/Flutter).** A versão de CI vem do `docs/app.json`
`toolchain` (decisão 0027). Confira pela `Read`: `.fvmrc` (campo `flutter`) e o `FROM` do
Dockerfile batem com ela? Divergência → **bloqueador** (a guarda do `pipeline.yml` reprovaria
pós-push).
- **Aviso do job de Release do Forgejo (soft — só app cliente offline).** Se o app distribui
artefato baixável e o job `release-forgejo` do `pipeline.yml` está **comentado**, **avise** ao
final (não bloqueie): *"o job release-forgejo está comentado — a aba Releases fica vazia, sem
download. App servido online: ignore."* Registre no **Relatório final**.
- **Badge de cobertura (soft — só repo com `docs/assets/badges/`).** O que é só o badge que o `etc/tests`
gravou quem diz é o script da toolchain, com a mesma regra do harness
([CI e testes](https://docs.xadm.biz/engenharia/ci-testes/#definicao-de-pronto-o-detalhe-testes)):
```bash
curl -fsSL https://docs.xadm.biz/toolchain/raw/scripts/checa-badges.py -o checa-badges.py
python checa-badges.py
```
Os caminhos que ele imprime não bloqueiam e vão no commit do release (passo 8). Saída 1 (o `README.md`
ou o `docs/index.md` mudou fora do bloco): esses dois ficam fora do commit, e o motivo entra no
relatório final. Apague o `checa-badges.py` baixado depois. Leia pela `Read` o sha do `<title>` de cada
SVG listado e rode `git diff --quiet <sha>..HEAD -- <caminhos do filtro code do pipeline.yml>` — na lib,
o caminho do módulo, e só o `<modulo>-cobertura.svg` dele vai no release; saída ≠ 0 → **avise** no
relatório final: *"badge medido num commit anterior ao código deste release"*.
**Worktree limpo com commits à frente do origin é o caso NORMAL — não investigue.** A IA
não commita (REGRA Nº 2): o conteúdo editado na sessão é commitado **pelo usuário**, então o
esperado é worktree limpo e `master` alguns commits à frente. Siga — o que importa é o
intervalo última-tag..HEAD (passo 2).
**Bloqueadores** (parar e pedir orientação ao usuário):
- Working tree com **arquivos de código modificados** (fonte, manifesto de
build, `Dockerfile`). Mudanças apenas em `.claude/`, `logs/` e artefatos
de build (`build/`, `.dart_tool/`, `.gradle/`, `node_modules/`) são
ignoráveis.
- Branch ≠ `master` — perguntar se prossegue mesmo assim.
- Tag já existe localmente OU remotamente para a versão calculada — abortar.
**Correção de pré-flight** (gate vermelho ou aviso aceito, ex. ADR fora do nav, `modelagem.md`
defasado) **nunca vai no commit do release** — ela é do trabalho, não da cerimônia. Mostre o diff da
correção e confirme (`AskUserQuestion`), **antes** do passo 2, para ela entrar no intervalo do
CHANGELOG:
- **HEAD ainda não está no origin** (`git branch -r --contains HEAD` vazio) → **amend** no commit do
dev (`git commit --amend --no-edit`): a correção é o que faltou a ele.
- **HEAD já está no origin** → commit separado `docs:`/`fix:` (amend reescreveria histórico publicado).
Depois, rode o pré-flight de novo.
### 1b. Guard da Central de Apps (soft)
Confira se o app passou pelo **setup** da Central: o `docs/app.json` tem o bloco `features`?
Leia o `app.json` pela ferramenta **`Read`**.
- **Tem `features`** (mesmo tudo `enabled: false`) → setup considerado; siga.
- **Não tem** → **pergunte UMA vez** (`AskUserQuestion`):
- "Rodar `/xadm-setup` agora" — configurar erros/arquivos/analytics/docs antes de liberar.
- "Este app não usa nenhuma" — segue (declara que não usa a Central).
É **soft**: não bloqueia release de app trivial
([Central de Apps](https://docs.xadm.biz/plataforma/central-de-apps/)).
### 1c. Classificar a mudança — release ou só push?
**A skill avalia o que mudou e recomenda a ação; não assume "tag = tudo".** Um fix de doc ou de
arquivo auxiliar publica pelo **push** (o job `docs` do `pipeline.yml`; no perfil config não há esse
job, e o push só atualiza o git), sem bump nem tag.
Classifique o diff `<última-tag>..HEAD` (`git diff --name-only <última-tag>..HEAD`):
| Classe | Diff | Ação recomendada |
|---|---|---|
| **não-release** | só `docs/**`+`mkdocs.yml`, **ou** só arquivos fora do build (`.github/`, `README*`, `.ia/`, scripts não-buildados) | **NÃO é release.** Os gates de DOCS do pré-flight já rodaram → **push** direto (sem bump/tag/binário). |
| **release** | qualquer código de app (`src/**`, deps/`build.gradle`, `Dockerfile*`) ou config deployada (`powersync.yaml`, compose), sozinho ou misto com docs | segue o fluxo normal (passo 2 em diante) — bump + tag + trailer. |
**Env de runtime NÃO é release.** Parâmetro que muda só o comportamento em produção é **env do
Coolify** (não passa por git) — não é caso desta skill.
**MOSTRA a classe + a ação e confirma ANTES de agir** (`AskUserQuestion`, header "Ação"):
- classe **não-release** → "Só push (recomendado)" (`git push origin <branch>` — perguntar como no
passo 9) · "Fazer release mesmo assim" · "Cancelar".
- classe **release** → segue direto pro passo 2.
Escolhida a via "só push": faça o push e vá ao **Relatório final** reportando *"não-release:
push de docs/auxiliar, sem bump/tag"*. **Não** bumpe, **não** taggeie. Se o diff tocou
`.github/workflows/`, o relatório lembra que o próximo release roda o caminho de release pela primeira
vez com o pipeline novo (passo 2c).
### 2. Listar commits desde a última release
```
git log --pretty=format:'%h %s' <last-tag>..HEAD
```
Lista vazia → não há nada para liberar → reportar e parar.
**Primeira release sem tags**: usar `git log --oneline` cheio para inferir o
CHANGELOG. A versão sugerida vem do manifesto (sem bump automático — o
usuário decide, ex. v1.0.0).
### 2b. Inferir alvos de deploy (só app com `build.targets`)
App **sem** `build.targets` (docs-only, lib, CLI on-prem) **pula este passo**. O `pipeline.yml`
builda **só os alvos do release**. Infira o que mudou desde a última tag:
```
git diff --name-only <last-tag>..HEAD
```
| Path que mudou | Alvo |
|---|---|
| só `docs/**`, `mkdocs.yml`, `*.md` (fora de `src/`) | **docs** (site, sem deploy de app) |
| `src/**`, `build.gradle*`, `settings.gradle*`, `gradle*` | **os alvos do `build.targets`** |
| `Dockerfile.native` + config native | **native** |
| `Dockerfile` | **jar** (se `jar` está no `build.targets`) |
**Detecta → MOSTRA a inferência → dev confirma ou override** (`AskUserQuestion`, header
"Alvos"): a inferência é heurística e o dev decide. Separar jar/native com `src/` mudado é
possível, com o trade-off declarado (os dois podem divergir em produção). Mudança só-de-doc
**não** redeploya o binário.
Guarde os alvos confirmados para o trailer da tag (passo 8).
### 2c. O pipeline mudou desde a última tag?
```
git diff --name-only <last-tag>..HEAD -- .github/workflows/
```
Vazio → siga. Com arquivo → os jobs que só rodam na tag (build, publish, deploy) vão rodar pela
primeira vez com o pipeline novo, e o gate local não os exercita
([ci-testes](https://docs.xadm.biz/engenharia/ci-testes/#caminho-que-so-roda-na-tag)). Mostre os
arquivos no resumo do passo 4 e, antes de taggar, confira com o dev que **cada nome que o build lê do
ambiente** (`System.getenv`, `ARG` do Dockerfile, `--dart-define`) ainda é exportado pelo step que o
chama. Registre no Relatório final: *"pipeline mudou desde v<antiga>; o caminho de release roda pela
primeira vez nesta tag — acompanhe o run"*.
### 3. Inferir tipo de bump (Conventional Commits)
| Padrão encontrado | Bump sugerido |
| --- | --- |
| `feat!:` ou `BREAKING CHANGE:` no corpo | **major** |
| `feat:` (sem `!`) | **minor** |
| Só `fix:`/`chore:`/`docs:`/`test:`/`refactor:`/`perf:` | **patch** |
Calcular a versão SemVer sugerida com base na versão atual do manifesto
(no Flutter, ignorando o `+N`).
**Versão já subida à mão** (manifesto acima da última tag, sem tag com esse número — subiu para
publicar no `mavenLocal` e testar o consumidor): é a versão **pendente**. Mantenha o número, sem bump
por cima, e mostre-o no resumo do passo 4 ao lado da sugestão dos commits. Menor do que a sugestão
(ex.: patch com `feat:` no intervalo) → avise e pergunte. O número já existe como tag remota ou no
registro (lib: `maven-metadata.xml`) → **aborte**: publicar de novo o mesmo número é o que o registro
recusa.
### 4. Apresentar resumo e confirmar bump
```
Última release: vX.Y.Z (data) | nenhuma (primeira release)
Versão atual no manifesto: X.Y.Z
Commits desde então (N):
<hash> <subject>
...
Sugestão de bump: <tipo> → v<nova>
```
`AskUserQuestion`:
- header: "Bump"
- question: "Aplicar bump para v<nova>?"
- options:
- "Sim, v<nova>" — aceita sugestão (label exato com a versão calculada)
- "Escolher outro bump" — segunda pergunta com patch/minor/major
- "Cancelar release" — aborta
### 5. Construir entradas de CHANGELOG
Ler `CHANGELOG.md` **com a ferramenta `Read`** e identificar a seção `[Unreleased]`.
**Se `CHANGELOG.md` não existir**: criar do zero seguindo
[Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/) — cabeçalho
padrão + `## [Unreleased]` vazia + a seção da release.
**Caso A — `[Unreleased]` com conteúdo**: usar como está; só mover para a
nova seção `## [X.Y.Z] - AAAA-MM-DD` (data de hoje, fuso local).
**Caso B — `[Unreleased]` vazia ou arquivo novo**: gerar entradas a partir
dos commits:
| Prefixo do commit | Seção CHANGELOG |
| --- | --- |
| `feat:` / `feat!:` | **Adicionado** |
| `fix:` | **Corrigido** |
| `refactor:`, `perf:` | **Alterado** |
| `chore:`, `docs:`, `test:`, `ci:`, `style:` | omitir (internos) |
Seções em **pt-BR**, nos nomes da tradução do Keep a Changelog: Adicionado / Alterado /
Corrigido / Removido. `chore:` que descreve algo visível ao usuário/operador DEVE entrar em
Adicionado/Alterado — a decisão é semântica, não mecânica pelo prefixo. A entrada é uma frase
declarativa em PT-BR (não cópia literal do subject).
**Envs do Coolify — a seção `### Migração` (só app que tem `application*.yml`).** Rode, com a
última tag **literal**:
```bash
curl -fsSL https://docs.xadm.biz/toolchain/raw/scripts/envs-coolify.py -o envs-coolify.py
python envs-coolify.py v<antiga>
```
Ele compara os placeholders `${NOME}` dos `application*.{yml,yaml,properties}` entre a tag e o
HEAD e imprime as duas subseções — **cole-as** na `### Migração` da nova versão:
- **`#### Coolify — antes do deploy`**: env nova, a **cadastrar** no recurso antes da tag;
- **`#### Coolify — depois do deploy`**: env que sumiu, a **apagar** quando todo deploy estiver
nesta versão (rename de env é dual-read — [java-micronaut](https://docs.xadm.biz/engenharia/java-micronaut/)).
Apague o `envs-coolify.py` baixado depois (não vai no commit). Só "nada a fazer" nas duas →
omita as subseções.
**Referências no CHANGELOG = texto puro ou URL absoluta, NUNCA link relativo `docs/…`.** O
`CHANGELOG.md` é embutido em `docs/` via snippet, então `[texto](docs/…)` vira `docs/docs/…` e
quebra o `--strict`. Cite como **`` `docs/decisoes/NNNN-*.md` ``** ou `https://docs.xadm.biz/…`. O
`valida-release.py` das guardas finais reprova `](docs/` na seção da versão.
Mostrar o rascunho e perguntar via `AskUserQuestion`:
- header: "CHANGELOG"
- options: "Sim, aplicar" / "Editar antes" (ajustes inline, re-mostrar).
**Não há opção de pular o CHANGELOG.** O passo 8 roda `valida-release.py`, que **reprova**
taggar `v<nova>` sem `## [<nova>]` no corpo. Se de fato não há nada a anotar, o intervalo
última-tag..HEAD (passo 2) está vazio e o release não deveria acontecer.
### 6. Aplicar alterações nos arquivos
1. **Manifesto**: gravar a versão nova (no Flutter, também `+N+1`).
2. **`CHANGELOG.md`**:
- seção `## [<nova>] - AAAA-MM-DD` com as entradas e a `### Migração`;
- `## [Unreleased]` limpa para o próximo ciclo;
- links do rodapé atualizados (mantendo os anteriores):
```
[Unreleased]: https://fonte.xadm.biz/xadm/<repo>/compare/v<nova>...HEAD
[<nova>]: https://fonte.xadm.biz/xadm/<repo>/compare/v<antiga>...v<nova>
```
Primeira release (sem `<antiga>`):
```
[<nova>]: https://fonte.xadm.biz/xadm/<repo>/releases/tag/v<nova>
```
### 7. Mostrar diff e confirmar
`git diff --stat` + `git diff` dos arquivos modificados.
**Se a `#### Coolify — antes do deploy` não está vazia**, pergunte primeiro
(`AskUserQuestion`, header "Envs"): *"As envs novas (<lista>) já estão cadastradas no recurso
Coolify?"* — a skill não alcança o Coolify, então confirma com o dono. "Não" → pare: sem elas o
app sobe sem a env no deploy da tag.
Depois, `AskUserQuestion`:
- header: "Confirmar"
- options: "Sim, commit + tag" / "Cancelar" (descartar as mudanças — restaurar
os arquivos editados; se o `CHANGELOG.md` era novo, apagá-lo — e parar).
### 8. Commit + tag
**Guardas finais (último passo antes do commit)**, depois de o passo 6 ter aplicado bump e
CHANGELOG — só aqui o working-tree é o **final** que vai virar o commit.
- **`valida-release.py --tag v<nova>`** — confere que a versão do manifesto da stack é SemVer,
que o `CHANGELOG.md` tem a seção `## [<nova>]` e que a tag bate com o manifesto. Roda
**aqui, pré-tag** — o contrato de release do `gate` do `pipeline.yml` roda na tag, tarde. Vermelho =
**NÃO taggar**: corrija CHANGELOG/manifesto e reconfira.
Modo ghost — sem Co-Authored-By:
```bash
git add <manifesto> CHANGELOG.md
git commit -m "chore(release): v<nova>"
```
Com badge de cobertura no diff (passo 1), o `git add` leva também os caminhos que o `checa-badges.py`
listou.
A mensagem é **literalmente** `chore(release): v<nova>` — sem corpo, sem
co-author, sem assinatura.
Tag anotada com resumo de **UMA linha** (a tag é só o marco; o detalhe mora no CHANGELOG). Uma
linha casa `git tag *` e roda sem prompt:
```bash
git tag -a v<nova> -m "v<nova> — <resumo de uma linha>"
```
**App com `build.targets` (passo 2b)** — crava os alvos confirmados num **segundo `-m`** (o
trailer `Deploy:` que o `decide` do `pipeline.yml` lê para buildar só o necessário):
```bash
git tag -a v<nova> -m "v<nova> — <resumo de uma linha>" -m "Deploy: native"
```
O trailer **sobrepõe** o `app.json build.targets` (o fallback quando não há trailer — sem
trailer nunca é "sem binário"). Mudança só de um alvo (ex. só o `Dockerfile.native`) **é
release** — bump patch + trailer só daquele alvo.
Sem `build.targets`: só o primeiro `-m`. **Não** adicionar Co-Authored-By na tag também.
### 9. Push (perguntar antes)
`AskUserQuestion`:
- header: "Push?"
- options: "Sim, push" (`git push origin <branch>` e
`git push origin v<nova>`) / "Não, deixar local".
### 10. Relatório final
```
Release v<nova> concluído.
Anterior: v<antiga> (ou "primeira release")
Atual: v<nova>
Branch: master
Tag: v<nova> (anotada)
Push: sim / não
Gates: código verde + container verde + docs verde
(ou: código DEGRADADO — só checkstyle, testes não rodaram (sem Docker);
ou: código CEGO — N testes @DisabledOnOs(OS.WINDOWS)/@EnabledOnOs(OS.LINUX) não rodaram;
ou: container DEGRADADO — Dockerfile/.dockerignore existem, build não rodou (sem Docker);
ou: container (compose) DEGRADADO — stack não subiu (sem Docker / falta .env / porta em uso))
Libs: na corrente / bumpadas neste release (<módulos>) / OVERRIDE de piso: <módulo> — <motivo>
Coolify: depois do deploy, apagar: <envs> (ou "nada a fazer")
Avisos: (só quando aplicável)
- job release-forgejo comentado num app cliente offline.
- pipeline mudou desde v<antiga>: o caminho de release roda pela primeira vez nesta
tag (passo 2c) — acompanhe o run.
- CI verde é AVISO, não gate: confirme a run verde no GitHub Actions do repo e o smoke
(último step do job `deploy`) da tag antes de dar o release por sólido. Vale DOBRADO
se houve "código CEGO".
Próximos passos (sugestão):
1. Acompanhar o job deploy (que termina no smoke) do pipeline da tag.
2. <notas pós-release do app>
```
## Convenções respeitadas
- Versão lida e gravada exclusivamente no manifesto da stack (fonte única).
- CHANGELOG segue [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/).
- Tag sempre `vX.Y.Z` (com `v`), anotada (`-a`).
- Commit sempre `chore(release): vX.Y.Z`.
- **Nenhum** `Co-Authored-By` em commit ou tag.
- Esta skill é o caminho feliz; a **rede de segurança** é o contrato de release, último step do
`gate` do `pipeline.yml`, que roda o `valida-release.py` na tag (pega tag fora-de-banda ou bug da
skill); gate vermelho barra o deploy. Detalhes: [versionamento](https://docs.xadm.biz/engenharia/versionamento/).
## Edge cases
- **Primeira release sem tags**: `git log --oneline` cheio; versão do
manifesto como base (usuário decide).
- **`CHANGELOG.md` não existe**: criar do zero (passo 5).
- **Tag remota existe mas local não**: o `git fetch origin --tags` resolve;
se ainda conflitar, abortar com instrução pro usuário.
- **Working tree sujo só em não-código** (`.claude/`, logs, artefatos):
ignorar silenciosamente — fora o badge de cobertura, que vai no commit do release (passo 1).
- **Erro de push**: manter commit/tag locais, reportar, sugerir push manual.
- **Versão do manifesto já subida à mão**: acima da última tag e sem tag própria, é a versão
pendente e a skill a mantém (passo 3). Abaixo da última tag → abortar e perguntar.
Skill /xadm-docs (.claude/skills/xadm-docs/SKILL.md)¶
Confere se a doc do repo está defasada da constituição vigente e migra com aprovação do usuário (Versões).
---
name: xadm-docs
description: Confere se o repo está defasado da norma X-Adm (constituição) e do kit (templates, scripts, skills do manifesto) e migra. Kit defasado re-deriva direto; norma nova passa pela aprovação do usuário. Use ao abrir o repo ou quando a constituição ou o kit mudarem.
---
<!--
Template canônico da skill /xadm-docs — vive no repo central xadm/documentacao
(templates/xadm-docs-skill.md). Destino no repo e demais artefatos: o manifesto
(https://docs.xadm.biz/toolchain/manifesto.json) diz, por artefato, perfil, stack e
caminho. Se o fluxo mudar, mude o template no central primeiro.
-->
# /xadm-docs — Repo vs norma e kit X-Adm
Confere se este repositório está defasado da
[constituição X-Adm](https://docs.xadm.biz/documentacao/constituicao/) (a **norma**) e do
**kit** (templates, scripts e skills que o central publica) e, se estiver, migra.
**Duas versões, dois gestos:**
- **Kit defasado** (template, script ou skill mudou) → **re-derive sem perguntar**: o manifesto
diz o quê e para onde; é trabalho mecânico. Reporte o que trocou.
- **Norma subiu** (a constituição mudou) → **pergunte antes** (REGRA Nº 1): mudança de norma pede
leitura e decisão sobre o código e a doc do repo.
## Fluxo
### 1. Levantar versões e manifesto
Em paralelo, **com cache-bust** (`?cb=<valor único>`, ex. um timestamp, e o header no-cache — o
CDN pode servir qualquer um deles stale):
```bash
curl -fsSL -H 'Cache-Control: no-cache' 'https://docs.xadm.biz/toolchain/constituicao-versao.txt?cb=<ts>'
curl -fsSL -H 'Cache-Control: no-cache' 'https://docs.xadm.biz/toolchain/kit-versao.txt?cb=<ts>'
curl -fsSL -H 'Cache-Control: no-cache' 'https://docs.xadm.biz/toolchain/manifesto.json?cb=<ts>'
```
Base do repo: `docs/app.json` — campos `constituicao` (norma), `kit` (kit sincronizado) e `perfil`
(`app`, `config` ou `lib`; ausente = `app`). O `app.json` é a fonte única; o `CLAUDE.md` não repete
o número. **Sem `kit` = kit 0.0.0**: re-derive tudo o que o manifesto lista para o perfil e a stack
do repo, e grave o campo no fim. Sem rede → reporte e pare.
**Cross-check obrigatório (anti-cache):** `constituicao-versao.txt` tem de bater com o campo
`constituicao` do manifesto, e `kit-versao.txt` com o campo `kit` — os três saem da mesma
publicação. Divergiu → **aborte alto** ("cache inconsistente: txt=X, manifesto=Y — re-rode") e
**nunca** reporte "em dia" pelo menor: uma `.txt` stale mascara a defasagem inteira.
**Esta skill também é do kit.** Se o `kit` do repo for menor que o vigente, o **primeiro ato** é
baixar esta skill fresca de `https://docs.xadm.biz/toolchain/raw/templates/xadm-docs-skill.md` e
seguir a **versão baixada** (repo muito atrasado roda um fluxo que já não existe). Se você já está
seguindo a baixada, siga.
**Versão da norma ≠ versão do site.** A norma vigente é **só** o `constituicao-versao.txt`; o kit
vigente é **só** o `kit-versao.txt`. Nunca derive nenhum dos dois do `VERSION`, do `/versao.txt`,
da tag `vX.Y.Z` ou do CHANGELOG do central — esses são a versão do **site**, desacoplada.
Detalhe: [versionamento](https://docs.xadm.biz/engenharia/versionamento/).
### 2. Artefatos do kit (mecânico, pelo manifesto)
O manifesto é a **única** lista de artefatos: esta skill não mantém lista própria. Cada entrada
de `arquivos` traz `perfis`, `stacks`, `destino` (caminho no repo) e `mudou_em` (versão do kit em
que mudou pela última vez).
1. **Stack do repo**, pelos arquivos: `build.gradle*` → `java`; `pubspec.yaml` → `flutter`;
`powersync.yaml` → `powersync`. `stacks: ["*"]` vale para qualquer stack.
2. **Filtre** as entradas cujo `perfis` contém o perfil do repo **e** cujo `stacks` contém a stack
do repo (ou `*`). Só essas contam; as demais não se aplicam.
3. **Defasado:** `mudou_em` > `kit` do repo. **Ausente:** o `destino` não existe no repo. Os dois
entram na lista — o `mudou_em` só acusa o que mudou depois da base, e artefato obrigatório que
**nunca foi copiado** passaria invisível.
4. **Opcionais** (campo `opcionais`): ausente **não** é defeito (o repo não instalou — kit de UI,
container, `.gitattributes`, `xadm-docx`). Instalado, sincroniza como os demais.
5. **Remover** (campo `remover`): entrada com o perfil do repo cujo `caminho` existe → `git rm`,
com o `motivo` no relatório. Vale também para a **sobra de outra stack**: entrada de `arquivos` fora
da stack do repo cujo `destino` existe e não é o `destino` de nenhuma entrada da stack do repo (o
`Dockerfile` e o `.gitattributes` têm uma variante por stack) — o kit antigo copiava tudo, e ela não
se re-deriva nunca. O `Dockerfile` e o `.dockerignore` do Flutter são receita por app, fora do
manifesto: nunca são sobra. Se o arquivo carrega trabalho que o substituto não cobre, pergunte antes
de apagar.
6. **Scripts** (campo `scripts`): não têm `destino` e **não** entram na conferência de presença — o
`pipeline.yml` e as skills os baixam frescos da toolchain na hora de rodar. Cópia no repo (o
`caminho` da entrada, ex. `scripts/checa-nav.py`, qualquer perfil ou stack) é **sobra** → `git rm`,
como o `remover`: o CI nunca a usa, e rodá-la dá atestado da norma velha.
A versão vigente de cada artefato está em `<raw_base><caminho no central>` (ex.
`https://docs.xadm.biz/toolchain/raw/templates/mkdocs.yml`).
**Regime de cópia.** O padrão é **verbatim** (o arquivo é da casa). Os destinos abaixo são
**customizados pelo repo** — re-derive a base e preserve o que é do repo:
- **`.github/workflows/pipeline.yml`**: preserve imagem, slug, bloco da stack e alvos. Os steps do
job `gate` são da casa — compare o **corpo** de cada guarda com o do template, não só se o
`- name:` está lá: guarda antiga com corpo velho passa no "as novas entraram" e continua com o
defeito que a casa já corrigiu.
- **`docs/app.json`**: nunca sobrescreva — acrescente campo novo do template e ajuste os que a
norma mudou; os valores são do repo.
- **`CLAUDE.md`**: o template é o **bloco de regras do topo**; troque o bloco e preserve o resto.
- **`.claude/settings.json`**: re-derive a base e **funda** o array `hooks.SessionStart` —
**garanta** a entrada do `checa-constituicao` (bloco exato no cabeçalho do próprio `.sh`) e
**preserve** as demais do repo, `additionalDirectories` e grants locais. O template não traz o
bloco `hooks` de propósito; sem esta fusão o `.sh` fica presente e nunca acionado. **Nunca**
toque o `settings.local.json`.
- **`Dockerfile`, `Dockerfile.native`**: digest `@sha256:` e imagem base do `FROM` são
customização do repo — re-derivar **preserva**, e placeholder (`<DIGEST>`, `<DIGEST_BUILDER>`,
`<slug>`) nunca substitui valor pinado.
- **`config/checkstyle/suppressions.xml`**: **garanta** cada `<suppress>` do template e preserve as
entradas do repo, cada uma com o porquê; entrada a mais não é defasagem. Exceção de uma
ocorrência vai inline, com `@SuppressWarnings("checkstyle:X")`.
- **`gradle.properties`, `mkdocs.yml`**: re-derive a base; preserve ajuste de máquina e o que é
identidade do repo (nome do site, `nav:`).
- **`.gitattributes`**: depois de trocar, renormalize **em commit separado**
(`git add --renormalize .`) e confira que `git diff --cached --ignore-cr-at-eol` sai vazio — a
troca de fim de linha não se mistura com mudança de conteúdo.
**Scaffold de uma vez só** (fora do manifesto por desenho: ao ser preenchido vira conteúdo do
repo): `app.css` do kit de UI → `src/main/resources/public/css/app.css`, de
`<raw_base>templates/app.css`. **Copie se ausente, nunca sobrescreva** — o `layout.jte` o linka
sempre, e sem ele toda página serve 404 no CSS (vazio serve).
**Artefato multi-stack customizado** (o `pipeline.yml`): o diff verbatim é esperado. Para saber se
a mudança da versão `mudou_em` toca a sua stack, leia o CHANGELOG cru
(`https://docs.xadm.biz/toolchain/CHANGELOG.md`): o heading de release traz o sufixo
`(constituição C.C.C · kit K.K.K)` — procure a string do kit. **Não achou** (site atrasado, entrada
antiga) → não conclua "não é minha stack": **diffe** o raw vigente contra o local e julgue pela
mudança real.
### 3. Norma: comparar e avaliar
- **Norma igual** (`constituicao` do repo == vigente) → rode o **passe leve 3c** e siga para o
passo 4 só com o kit (sem perguntar).
- **Norma subiu** → baixe o texto vigente
(`curl -fsSL https://docs.xadm.biz/toolchain/constituicao.md`) e compare com o estado **real** do
repo:
- estrutura de `docs/` (níveis e nomes de pasta — nomes antigos: `design/` → `projeto/` e
`rd/` → `decisoes/` são renomeação 1:1; `guias/` migra **por conteúdo**: manual de usuário →
`manual/`, runbook técnico → `operacao/`);
- **conteúdo de outro repo** achado aqui → realocar para o repo dono, não absorver;
- frontmatter dos documentos (campos, enums, `tipo:`);
- `docs/app.json` e `mkdocs.yml`;
- convenções (slug estável, glossário próprio, link de volta ao portal).
- **`CLAUDE.md` acima de 300 linhas** → entra na lista (em qualquer repo, norma igual ou não): o
arquivo é contexto carregado em toda sessão; histórico vai para acervo.
Renomear arquivo já publicado exige redirect (slug estável) — aponte quando a migração envolver
renomeação.
### 3b. Conformidade de engenharia (código vs regras da casa)
As regras de *como construir* vivem nas páginas de **Engenharia**, lidas ao vivo — não são
copiadas, então não estão no manifesto. O risco é a regra mudar e o código deixar de conformar.
Na norma nova:
1. **Baixe as regras vigentes da stack** (markdown cru):
`curl -fsSL https://docs.xadm.biz/toolchain/raw/engenharia/<pagina>.md` (a da stack + `stack.md`,
`versionamento.md`, `ci-testes.md`).
2. **Re-audite o código** contra elas — libs e padrões da casa, observabilidade, gate de CI,
health check, definição de pronto. É conferir se o código segue a regra, não re-baixar arquivo.
3. **Toolchain declarada e consistente** (Java/Flutter): `docs/app.json` `toolchain.*` existe, e
`.fvmrc` = `toolchain.flutter`.
4. **JaCoCo suporta o class major do Java** (quem mede cobertura com JaCoCo): Java 25 exige
`jacoco.toolVersion` ≥ 0.8.15 — abaixo disso o relatório sai válido na aparência e vazio.
5. **UI padrão em app server-render** (JTE: `src/main/jte/` ou `micronaut-views-jte`): a tela usa
o `layout.jte` do kit, não visual próprio — inclusive tela de admin.
6. **Persistência via `micronaut-data`** (app Micronaut que configura `datasources`):
`micronaut-data-processor` no `annotationProcessor` e repositórios `@JdbcRepository`; SQL cru
via `getConnection()` como camada de persistência entra na lista. App sem `datasources` não é
alcançado.
7. **Par `Dockerfile`/`Dockerfile.native` paritário** (app native): todo `mkdir`+`chown` de
`/app/<x>` de um existe no outro.
8. **Libs da casa na corrente** (repo que declara `br.com.xadm:*`). A corrente vem do **registro**,
o piso vem da **toolchain** — nunca de uma página:
```bash
curl -fsSL https://fonte.xadm.biz/api/packages/xadm/maven/br/com/xadm/<modulo>/maven-metadata.xml
curl -fsSL https://docs.xadm.biz/toolchain/pisos-libs.json
```
- **Abaixo do piso** → entra **destacado**, com o `motivo` do JSON: é defeito conhecido rodando
em produção, e a `/xadm-release` recusa enquanto não subir.
- **Atrás da corrente** → **pendência**: o repo acompanha a última versão publicada; a próxima
`/xadm-release` bumpa.
Bumpar é **migrar no mesmo PR**: aplicar as seções `### Migração` do CHANGELOG do módulo
(`xadm-commons/<modulo>/CHANGELOG.md`) entre a versão atual e a corrente, em ordem, e remover o
código local que a lib passou a prover. Regra: [libs](https://docs.xadm.biz/engenharia/libs/).
9. **`.claude/settings.local.json` versionado** → entra na lista: `git rm --cached
.claude/settings.local.json` e a linha no `.gitignore`; se ele tinha credencial, **rotacione** —
o valor já está no histórico.
10. **Hook de defasagem acionável:** `.claude/checa-constituicao.sh` presente **e** a entrada
`SessionStart` que o dispara no `.claude/settings.json`. Faltou uma das duas → entra na lista
(o repo sem hook é justamente o que não fica sabendo que precisa re-sincronizar).
11. As não-conformidades entram na **mesma lista** do passo 4. A saída é mudança de código ou
config do repo, com aprovação.
### 3c. Doc de projeto ↔ construído (passe leve, toda rodada)
Roda com a norma igual ou não — desvio entre desenho e build independe de versão. Passe **raso**,
só candidatos óbvios, escopo **local** (doc deste repo ↔ build deste repo):
- **(A) Desenho vs build:** doc em `docs/projeto/` ou `docs/decisoes/` com `status: aprovado` cujo
termo-chave o código contradiz. Só `aprovado` conta; `rascunho`/`em-revisao`/roadmap é isento.
- **(B) Decisão sem RD:** escolha de design presente no código sem `docs/decisoes/NNNN`.
- **(C) Migração decidida por ADR central sem RD-ponteiro local:** o código adotou a decisão da
casa (ex. views em JTE, deploy native) e `docs/decisoes/` não registra a adoção. Cobra um RD curto
que aponta o ADR central e data a adoção — não re-litiga a decisão.
Heurístico: é item de julgamento humano, nunca bloqueio. Os achados entram na lista como
**propostas de autoria deferíveis**.
### 4. Apresentar e (se a norma subiu) confirmar
Apresente a lista em três blocos: **kit** (re-derivado/a re-derivar, ausentes, a remover),
**norma** (passos 3 e 3b) e **doc de projeto** (3c).
- **Só o kit defasou** → aplique o bloco kit direto (passo 5) e reporte.
- **Norma subiu** → `AskUserQuestion`: "Migrar agora" (aplica a lista aprovada) · "Só registrar a
versão" (a doc já está conforme) · "Cancelar".
### 5. Migrar
1. Re-derive o kit (passo 2), no regime de cópia de cada destino.
2. Aplique as correções de norma aprovadas. Achados de 3c são **propostas de autoria** (escrever o
RD, corrigir o desenho, marcar `obsoleto`) — execute só as aprovadas e declare em voz alta o que
ficou deferido.
3. Grave no `docs/app.json` o `kit` vigente e, se a norma foi migrada, o `constituicao` vigente.
4. **Releia o `CLAUDE.md`**: o que ele declara como divergência ou exceção à casa ("preservar o
vendor local", "customizado porque…") e a migração desfez sai **neste passo** — senão o
`CLAUDE.md` contradiz o código, e o próximo agente obedece o `CLAUDE.md`.
5. **Valide com validador fresco** — baixe na hora para arquivo efêmero, nunca reuse download
anterior:
```bash
curl -fsSL https://docs.xadm.biz/toolchain/valida-frontmatter.py -o /tmp/vf.$$.py
python3 /tmp/vf.$$.py docs/
```
A **1ª linha** da saída diz o que o validador implementa: `constituição C.C.C · kit K.K.K`.
Confira o **kit** impresso contra o `kit-versao.txt` do passo 1 (é o kit que muda quando um
script muda). Divergiu (ou `dev`) → validador stale: **aborte e re-baixe**, não confie no
"0 erros". Depois, `mkdocs build --strict`.
6. **Declare deferimentos em voz alta** — *"deferido X porque A/B/C"*, nunca como rodapé. Se o repo
ainda **não publicou**, renomear custa zero: ofereça fazer agora.
7. **Não** commite sem o usuário pedir.
## Regras
- **Validador sempre fresco:** baixar na hora e conferir a versão impressa na 1ª linha antes de
confiar no resultado — um "0 erros" de validador stale é falso atestado. Nunca rode a cópia de
`scripts/` do repo, nem para uma olhada antes da migração.
- REGRA Nº 1: ambiguidade ou mais de um caminho → opções com recomendação, confirmar antes. Kit
defasado não é ambiguidade (o manifesto decide); norma nova é.
- Brecha ou ambiguidade na **própria constituição** → não contornar localmente: escreva o texto do
problema (repo, versão da norma e do kit, o que foi medido × suposto) para o usuário colar numa
sessão do repo central `documentacao`.
Skill /xadm-setup (.claude/skills/xadm-setup/SKILL.md)¶
Configura as funcionalidades da Central de Apps (erros,
arquivos, analytics, dashboards): lê o app.json, pergunta o que ativar,
provisiona via broker e grava o client-grade de volta no app.json. Rode
depois de codar e antes da release (Central de Apps).
---
name: xadm-setup
description: Configura as funcionalidades da Central de Apps (erros/GlitchTip, arquivos/Garage, analytics, docs) em build-time — pergunta o que ativar, provisiona via o auth-broker e grava o resultado client-grade no app.json. Rode depois de codar e ANTES da /xadm-release.
---
<!--
Template canônico da skill /xadm-setup — vive no repo central xadm/documentacao
(templates/xadm-setup-skill.md). Copie para .claude/skills/xadm-setup/SKILL.md no
repo do app. Mude AQUI primeiro e re-derive. Contrato: docs.xadm.biz/plataforma/central-de-apps.
-->
# /xadm-setup — Configurar funcionalidades da Central de Apps (build-time)
Liga as funcionalidades de infra da X-Adm a **este** app, **em build-time**: pergunta o que
usar, **provisiona via o `central-backend`** (que tem os tokens admin dos provedores) e **grava o resultado
client-grade no `docs/app.json`** — que o build embarca. **Nada é buscado no boot.** Contrato:
[Central de Apps](https://docs.xadm.biz/plataforma/central-de-apps/).
> **Autenticação (M2M):** o broker de setup autentica por **token de serviço** (não login humano).
> A skill conhece só o **formato** e **pede o valor** ao usuário — **NUNCA** embuta o token nem sua
> regra de geração (vem dos admins / do `central-backend`, **fora deste template**). **Mesmo com o fonte
> do `central-backend` à mão** (o filtro que valida o token, com a fórmula à vista): **peça o token ao usuário —
> não o derive da fórmula**. Computar um token de auth a partir do fonte é bypass, não conveniência.
> **NÃO commita** (REGRA Nº 2): grava o `app.json` e entrega a mensagem pronta; quem commita é você.
## Fluxo
### 1. Ler o estado atual
Leia `docs/app.json`: `app_id`, `grupo`, **`cliente_id`** (a CHAVE canônica do tenant) e `cliente`
(rótulo de exibição), e o bloco `features` (o que já está `enabled`). **Não confunda os dois:** o
`cliente_id` (minúsculo, `clientes.cliente_id`) é o que vai ao broker como **identidade de tenant**;
o `cliente` (`"Vantroba"`) é **só display** (label de coleção, path no portal). **Fail-closed:**
grupo=cliente sem `cliente_id` válido (minúsculo kebab) → **pare e peça a chave**; **jamais** derive a
chave do display — o display não é identidade de tenant (decisão 0008). Detecte a **stack** (`stack:`/repo). Sem
`app_id` → peça/gere um (kebab, o mesmo namespace dos grants). Sem rede/sem o **token de serviço de
setup** → reporte e pare.
### 2. Perguntar por funcionalidade (`AskUserQuestion`)
Uma pergunta por item; o que já está `enabled` aparece como "já configurado":
- **GlitchTip (erros)** — **default: sim** (observabilidade é baseline da constituição).
- **Garage (arquivos)** — opt-in.
- **Analytics (Aptabase + Metabase)** — opt-in.
- **Central de Documentos (publicar docs)** — opt-in.
### 3. Provisionar (por "sim" novo) — via o auth-broker
Para cada funcionalidade escolhida, chame o broker do `central-backend`
(`POST {AUTH}/api/setup/provision`, com o **token de serviço de setup**) com o **bloco de identidade
do `app.json` INTEIRO** — `app_id`, `feature`, `grupo`, **`nome`**, **`production_url`**, **`slug`**,
**`descricao`**, **`stack`**, **`toolchain`** e, para `grupo=cliente`, **`cliente_id`** (a chave, não
o display; ver abaixo). **Mande todo campo de identidade que o `app.json` tiver, não só os que o
broker exige:** a tabela `apps` é espelho do `app.json` e **só esta chamada a escreve** — o que você
não mandar fica defasado no catálogo (campo omitido é preservado, não apagado, mas também não
atualiza). **Campos obrigatórios são
contrato travado nos dois lados:** o broker rejeita payload incompleto (**400**, não 500) e este guia
declara os mesmos campos — não mande menos "porque o resumo era `(app_id, feature)`". Dois campos que **passam despercebidos** porque não são "identidade de
tenant": sem **`nome`** o broker devolve **`400 nome_obrigatorio`**; sem **`production_url`** o secret
**não é injetado** (o app cai no gate "mobile/local" do broker e o server fica **sem a write-key
silenciosamente** — sobe quebrado, sem 400). Os dois vêm do `app.json` (passo 1, ler o estado atual). O `central-backend`
provisiona **idempotente** (reusa se já existe) e devolve o **client-grade**. **Identidade de tenant =
`cliente_id`** (a chave, não o display): o broker escopa/deduplica coleção e grants pela **chave**,
que ele **valida contra o catálogo `clientes` do `central-backend` (fail-closed** — chave desconhecida **não**
provisiona); o `cliente` só rotula. Passos por feature:
- **glitchtip:** confirma/cria a **org** xadm → cria/reusa o **projeto** → grava `dsn` no bloco
`features.glitchtip`. O broker **nomeia o projeto pelo `app_id`** (slug estável; o `dsn` usa o id
numérico do projeto, não o slug). O `SENTRY_AUTH_TOKEN` (upload de sourcemap) é **secret do repo
no GitHub**, lido pelo job `build_web` do `pipeline.yml` (não vai no `app.json`).
**Instrumentar o código (scaffold + guia, com confirmação — NÃO auto-edita o negócio):** (1) instale
o SDK (Flutter → `sentry_flutter`; outra stack → o SDK Sentry-compatível); (2) scaffolde o **init
stack-específico** — Flutter: envolver o `runApp` com `SentryFlutter.init(…, appRunner:)` + handlers
(`FlutterError.onError`, `PlatformDispatcher.onError`) — **editando o `main` só com o OK do dev**;
(3) **guie** os pontos de captura (gaps async, fronteiras de integração/IO), sem espalhar `try/catch`;
(4) **ofereça** scaffoldar a **rota de diagnóstico `/test`** (opt-in, com o OK do dev) — tela/endpoint
**oculto e login-gated** que envia uma exceção de teste ao GlitchTip, pra smoke-test pós-deploy sem
esperar um erro real. Recipe fino por stack (init + `/test`): [engenharia/flutter](https://docs.xadm.biz/engenharia/flutter/)
/ [engenharia/java-micronaut](https://docs.xadm.biz/engenharia/java-micronaut/).
- **garage:** provisiona bucket+key → grava `bucket`/`endpoint` em `features.garage`. A **key de
escrita** é secret (web/server → Coolify; **mobile** não usa — escrita via presign runtime).
- **analytics:** o broker provisiona o **Aptabase** (→ `aptabase_key` **+** `aptabase_host` — a key
`A-SH-` self-hosted é inútil no cliente sem o host; o SDK Flutter exige `InitOptions(host:)`). Como o Aptabase **não tem
API**, o broker **forja o token de sessão** (JWT HS256 assinado com o secret do próprio tool, no
env do `central-backend`) e cria o app → `A-SH-…` — padrão "provider sem API → forjar o token"; mecânica e
guardas em [central-de-apps](https://docs.xadm.biz/plataforma/central-de-apps/). Depois, **pergunte o
arquétipo do app antes dos eventos** (`AskUserQuestion`) — **produto** (muitos usuários; importa
comportamento/retenção) ou **interno/admin** (poucos usuários; importa **auditar a ação sensível**)
— e **adapte o baseline sugerido**: produto → login/logout/`screen_view`/criar-alterar-excluir;
interno/admin → a **ação sensível** de cada fluxo (aprovar/rejeitar, publicar, resetar — quem fez o
quê; `screen_view`/retenção têm valor baixo). Então **scaffolde o helper só para os eventos escolhidos**
(**não** auto-edite CRUD espalhado — instrumentação custom é sua). **Diga ao dev o caveat:** evento
client-side é **bypassável** → é visibilidade **operacional, NÃO audit trail**; auditoria de segurança
de verdade (a ação sensível como registro imutável) pertence ao **backend**, não ao Aptabase. **Após
os eventos**, o broker
**auto-configura o Metabase** (API real): cria `collection(por cliente_id, rotulada pelo cliente) → dashboard(app) → cards
baseline adaptados aos eventos`; a skill **grava o `features.analytics.metabase_dashboard_id`** que
o broker devolve (pro embed futuro). Estrutura/idempotência/sub-estados em
[central-de-apps](https://docs.xadm.biz/plataforma/central-de-apps/).
- **docs:** confirma `slug` (kebab, imutável) + `grupo`/`cliente` (afeta o path no portal); o
job `docs` do `pipeline.yml` já publica.
**Confira o resultado por feature — NÃO engula falha.** A resposta do `/provision` carrega o **estado
real** por provider: provisão (`state`/`last_error`) e injeção do secret (`injected` + motivo). Em
**falha de provisão**, reporte o `last_error` e **não grave** `enabled` sem o ref (nada de `app.json`
meia-boca). Em **`injected:false`**, avise o dev: o secret **não** chegou ao recurso — **setar o env à
mão** no recurso Coolify (recurso ausente, token inválido, 401: o caminho é o mesmo). **Nunca re-chame `provision` "pra confirmar"**
— confie na resposta honesta (re-chamar pode duplicar o projeto GlitchTip).
### 4. Gravar no `app.json`
Escreva os refs **client-grade** no bloco `features.<nome>` (com `enabled: true`). **Segredo
nunca** vai no `app.json` (é público). Segredo de **runtime** do server é env do recurso Coolify
(o broker injeta); segredo de **build** (ex. `SENTRY_AUTH_TOKEN`) é secret do repo no GitHub.
### 5. Entrega da config no build (por plataforma)
A **fonte é o `app.json`**; o build o lê e injeta via **`--dart-define`** (Flutter). **Garanta a
ponte `app.json`→`--dart-define` — ela pode não existir no scaffold.** Não assuma que "já lê o
`app.json`": o Dockerfile/CI scaffoldado costuma **hardcodar ARGs** e nem ter `jq`. A **receita**
(instalar `jq` + `RUN … --dart-define=$(jq -r .features.<x>.<ref> docs/app.json) …`) está em
[engenharia/flutter](https://docs.xadm.biz/engenharia/flutter/) (§Identidade/build, "a ponte
`app.json`→`--dart-define`"):
- **Flutter web:** a ponte vive no **Dockerfile** (lê o `app.json` committado via `jq` →
`--dart-define`), buildado pelo job `build_web` do `pipeline.yml`. Client-grade vem do `app.json`;
segredo de build é secret do repo no GitHub; o recurso Coolify web fica **sem** env de build.
**Se o `.dockerignore` exclui `docs/`, a ponte tem DUAS metades — o Dockerfile ler `docs/app.json`
E a exceção `!docs/app.json` no `.dockerignore`** (senão o arquivo não entra no contexto e o deploy
quebra); as duas viajam no mesmo PR ([coolify](https://docs.xadm.biz/infraestrutura/coolify/#dockerfile-que-le-docsappjson-case-a-excecao-no-dockerignore)).
- **Flutter mobile (sem Coolify):** a mesma ponte no **`pipeline.yml`** (`flutter build apk --dart-define=…`).
- **Server:** client-grade e segredo são **env de runtime** do recurso, que o broker injeta neste
passo — nada de build-arg.
**Se a ponte não existe, crie-a** (não é "confira e siga") — é o que fecha o gap entre o que este
passo pressupõe e o que o scaffold entrega.
### 6. Fechamento
Reporte o que foi configurado (+ os secrets: runtime no recurso, build no GitHub) e **entregue a mensagem de
commit** do `app.json` (ghost, sem assinatura de IA). Rode a `/xadm-release` depois — o guard dela
confere que o setup foi feito.
## Regras
- **Idempotente:** re-rodar lê o `app.json` e só provisiona o "sim" novo.
- **Não commita** (REGRA Nº 2); não instrumenta código arbitrário (scaffold + guia).
- Brecha/ambiguidade no **padrão** → gere o texto do problema e leve ao repo central
(constituição, Governança). O provisionamento real (`/api/setup/provision`, injeção no Coolify) é do
`central-backend` (Camada 2) — se o broker ainda não existe, registre o que faltou e pare.
Skill /xadm-docx (.claude/skills/xadm-docx/SKILL.md)¶
Exporta um pré-projeto ou o livro do projeto para .docx no padrão visual X-Adm,
baixando o pipeline fresco da toolchain. Use quando a diretoria pedir Word
(Docs as code). Receita completa em
Exportar para .docx.
---
name: xadm-docx
description: Exporta um pré-projeto (nível 1) ou o livro do projeto (nível 2) para .docx no padrão visual X-Adm (A4, Verdana, cabeçalho/rodapé/logo, sumário, Mermaid como imagem), baixando o pipeline FRESCO da toolchain. Use quando a diretoria pedir Word (constituição, Docs as code).
---
<!--
Template canônico da skill /xadm-docx — repo central xadm/documentacao
(templates/xadm-docx-skill.md). Copie para .claude/skills/xadm-docx/SKILL.md no
repo da aplicação. O PIPELINE (scripts + reference + logo) NÃO é copiado pro app:
a skill baixa fresco da toolchain a cada run (fonte única). Mude AQUI primeiro e
re-derive. Ver docs/documentacao/export-docx.md.
-->
# /xadm-docx — Exportar para .docx (padrão X-Adm)
Gera um `.docx` no visual da X-Adm a partir de um Markdown da `docs/` —
**pré-projeto** (`docs/pre-projeto/index.md`) ou o **livro** do projeto
(`docs/projeto/index.md`). O `.docx` é **saída gerada** (constituição, Docs as code): NÃO
se commita. O pipeline vem **fresco da toolchain** (não há cópia no app que envelheça).
## Pré-requisitos (conferir antes)
- **pandoc** — obrigatório (`pandoc --version`). Ausente → instruir a instalar
(`apt install pandoc` / `brew install pandoc` / Windows: instalador em pandoc.org) e parar.
- **mmdc** (`@mermaid-js/mermaid-cli`) — recomendado, renderiza Mermaid **offline**.
Ausente: o pipeline **falha** em doc com diagrama (não vai à rede por default). Só com
`MERMAID_RENDERER=ink` ele usa o serviço externo mermaid.ink — que **ENVIA o diagrama
à rede**: NÃO usar com pré-projeto/conteúdo confidencial (conteúdo confidencial não sai da empresa).
- **python3** — só stdlib.
## Fluxo
### 1. Escolher a entrada
Detectar o que existe: `docs/pre-projeto/index.md` e/ou `docs/projeto/index.md`.
Os dois → `AskUserQuestion` (pré-projeto / livro). Nenhum → reportar e parar.
O livro embute `projeto/modelagem.md` via `--8<--` (o pipeline expande sozinho).
### 2. Baixar o pipeline FRESCO da toolchain
Sem rede → reportar e parar. Para um diretório efêmero (NUNCA reusar download de
turno anterior nem cache em `/tmp` persistente):
```bash
DL="$(mktemp -d)/export-docx"; mkdir -p "$DL/assets"
BASE=https://docs.xadm.biz/toolchain/raw/scripts/export-docx
for f in export_docx.py expand_snippets.py admonitions.py render_mermaid.py make_reference.py \
frontmatter.lua xadm-reference.docx; do
curl -fsSL "$BASE/$f" -o "$DL/$f"
done
curl -fsSL "$BASE/assets/logo-xadm.png" -o "$DL/assets/logo-xadm.png"
```
(Confira que a constituição vigente — `curl -fsSL
https://docs.xadm.biz/toolchain/constituicao-versao.txt` — bate com a base do app;
defasagem grande → considerar `/xadm-docs` antes.)
### 3. Gerar o .docx
**Sem 2º argumento**, o nome de saída é **auto-descritivo** —
`<slug>-<nível>[-v<versão>].docx` na raiz do repo (rastreável p/ entrega, sem colisão
entre apps/releases). Ex.:
```bash
python3 "$DL/export_docx.py" docs/pre-projeto/index.md
# ou o livro: python3 "$DL/export_docx.py" docs/projeto/index.md
# -> ex.: thoms-integracao-produto-ecom-projeto-v0.1.0.docx
```
slug = nome do diretório-raiz; nível = pre-projeto|projeto (pelo caminho); versão =
`git describe --tags` → `VERSION` → omitida. Passe um 2º arg só p/ forçar outro nome.
Diagrama confidencial sem mmdc instalado → NÃO force `.ink`; oriente instalar o mmdc.
### 4. Entregar
Reportar o caminho do `.docx` gerado. **NÃO commitar** (REGRA Nº 2) — é saída gerada,
fica fora do Git: o `.gitignore` do app deve ter **`/*.docx`** (root-anchored — ignora a
entrega na raiz, mas NÃO um pré-projeto `.docx` commitado em `docs/pre-projeto/`, que a
constituição permite, em Docs as code). Se a diretoria quer o arquivo, é entrega manual (e-mail/drive), não versão.
## Regras
- O `.docx` é **gerado**, nunca a fonte — a fonte é o Markdown em `docs/` (constituição, Docs as code).
- Pipeline sempre **fresco** da toolchain; não copiar os scripts pro app.
- Mermaid **offline por default**; `.ink` só com decisão explícita e conteúdo não confidencial.
- Limitação conhecida (1ª onda): o `.docx` do livro traz prosa autorada + embeds + Mermaid;
conteúdo injetado por hook do MkDocs (changelog/etapas) fica fora. Ver
[export-docx](https://docs.xadm.biz/documentacao/export-docx/).
- REGRA Nº 1: ambiguidade (qual entrada, qual destino) → perguntar, não adivinhar.
Skills de workflow X-Adm (desenhar → definir → refinar → planejar → implementar → documentar)¶
O fluxo de trabalho da casa, modelado no ACT 1.0. Stack-aware: detectam a stack e seguem
a base de conhecimento da Engenharia daquela stack; carregam ainda
references/<stack>.md com os concerns por estágio. x-implementar não commita (REGRA Nº 2);
x-documentar destila para docs/ e refina a base (loop de feedback). Cada skill é um diretório
templates/<nome>/ (SKILL.md + references/) — copie o diretório inteiro para .claude/skills/<nome>/.
---
name: x-desenhar
description: Conduz a entrevista de uma feature e grava o prompt/design (`.ia/NNN-*-prompt.md`) com o rastro de decisões L# embutido, stack-aware. Use ao iniciar uma feature/correção, antes de definir a spec.
argument-hint: "[pedido, ideia, arquivo-fonte ou vazio]"
tools: [Read, Glob, Grep, Write, Edit, AskUserQuestion, Skill]
---
<!--
Template canônico da skill /x-desenhar — repo central xadm/documentacao
(templates/x-desenhar/SKILL.md + references/). Copie o DIRETÓRIO inteiro para
.claude/skills/x-desenhar/. Mude AQUI primeiro e re-derive. Fluxo:
desenhar → definir → refinar → planejar → implementar → documentar.
Derivado do act-interview (ACT 1.0) + xadm-spec (passos 1 a 4), reescrito para o padrão
X-Adm — NÃO commita (REGRA Nº 2), stack-aware, lineage .ia/ (constituição, Duas fontes da verdade).
-->
# /x-desenhar — Entrevistar a feature e gravar o prompt (X-Adm)
Entrevista o pedido até ter **linguagem compartilhada, intenção clara, dependências de decisão
resolvidas e contrato-de-produto suficiente** para uma spec fiel — e **grava o resultado** em
`.ia/NNN-titulo-prompt.md` (o design + o rastro de decisões **L#** embutido). É o **1º passo** e
a **origem da linhagem** `.ia/` (prompt→spec→plan; constituição, Duas fontes da verdade). Próximo: `/x-definir`.
## 0. Stack e base de conhecimento — SEMPRE primeiro
1. **Detecte a stack:** `docs/app.json` `stack:` — ou pelo repo (`pubspec.yaml`→Flutter;
`build.gradle*`+micronaut→Micronaut; `build.gradle.kts` sem framework→Java; `package.json`
→Node; MkDocs→docs).
2. **Leia a base de conhecimento da casa** dessa stack — o **idioma** (libs, logs, padrões) que a
feature deve seguir: página `docs.xadm.biz/engenharia/<stack>/` + `engenharia/stack.md`.
3. **Carregue o reference do estágio** se existir: `references/<stack>.md` desta skill traz os
concerns de **entrevista** específicos da stack (ex. Flutter: navegação, estados, a11y,
segredos, cleanup). Stack sem página/reference → Stack da casa + arquétipo mais próximo; marque
o que faltou (feedback).
4. **Leia a norma que a feature toca, não só o diff do kit.** Pelas âncoras da constituição
(`docs.xadm.biz/documentacao/constituicao/`), leia as seções que o pedido alcança — o princípio e
a norma derivada dona de cada regra. Se o `constituicao` do `docs/app.json` está atrás da versão
vigente, leia também a seção **Migração** do CHANGELOG (`docs.xadm.biz/changelog/`) entre as duas.
O manifesto diz o que re-derivar; só a leitura da norma diz o que a feature tem de respeitar.
Registre no prompt (Contexto) as seções lidas.
5. Se o hook de sessão acusou defasagem da constituição, rode `/xadm-docs` antes.
## 1. Postura da entrevista
**Uma pergunta por vez.** Prefixe cada pergunta ao usuário com `Pergunta N:` e incremente `N`.
Espere a resposta antes de seguir. Para cada pergunta, dê **uma recomendação concreta** o
bastante pra virar decisão de spec (labels exatos, transições de estado, formato de saída,
requisito negativo quando evita ambiguidade). Razão curta; trade-off só quando muda a decisão.
Perguntas livres na descoberta; opções estruturadas (`AskUserQuestion`) nos checkpoints.
## 2. Antes de perguntar — explorar
Não pergunte o que o projeto responde. Glob/Grep/Read no que o pedido toca: código/testes/docs
da feature; implementações de referência **no idioma da stack** (passo 0); pontos onde a suposição do
usuário parece divergir do código. **Sem input / vago:** `AskUserQuestion` — "novo recurso /
corrigir-melhorar / investigação" + peça a descrição. **Arquivo (`.md`/path):** leia e use como
base. Não produza outros arquivos além do prompt (passo 5). Não implemente.
**Refactor/dedup — caracterização precede refactor:** mesmo **nome** de classe ≠ mesmo **corpo**;
antes de propor "unificar/deduplicar N iguais", **leia os corpos** e confirme que são idênticos —
senão a tarefa nasce errada (ex.: 6 variantes `_Measure` que pareciam uma só).
## 3. Prioridade das perguntas
1. **Framing** — resolve o conceito de domínio, a linguagem voltada ao usuário, a intenção.
2. **Crítico** — bloqueia a implementação ou cria risco de segurança/dado.
3. **Importante** — afeta bastante UX/manutenção.
4. **Nice-to-have** — tem default razoável; declare a suposição, só pergunte se sobrar espaço.
Só perguntas que **mudam a implementação**. Não pergunte o já dito/inferível nem o default da
casa (ex. HTTP=OkHttp). Prefira contrato-de-produto (comportamento observável, entrada/saída,
estado, erro, compatibilidade) a preferência de implementação. **Capacidade de lib de terceiro:
confirme na FONTE** (código/changelog da versão em uso, pesquisador de docs da stack) antes de
tratar como resolvida — supor API inexistente é inventar capacidade (constituição, Documentar interfaces, decisões e uso).
## 4. Desafiar a linguagem e testar cenários
Trate o vocabulário como parte do design. Palavras concorrentes pro mesmo conceito → pergunte
qual é canônica. Termo vago/sobrecarregado → proponha um mais afiado antes de resolver o
comportamento. Terminologia durável resolvida → registre **na hora** no `docs/glossario.md` do
app (constituição, Convenções de doc) — **NÃO** crie `GLOSSARY.md` na raiz. Caminhe as decisões por **cenários
reais** que expõem bordas, falhas, sequência e colisões de nome; resolva cadeias de dependência
em ordem (nome antes de storage, storage antes de migração).
## 5. Gravar o prompt (`.ia/NNN-titulo-prompt.md`)
Quando framing, bloqueios e escolhas de direção estiverem resolvidos, **grave o prompt** — o
design da feature + o rastro de decisões. **`NNN` é o próximo id livre da LINHAGEM** (a feature),
não uma sequência global; o slug é a feature. Ex.: `.ia/016-exportar-frota-prompt.md`. A spec e o
plano herdam esse `NNN`+slug (`-prompt`→`-spec`→`-plan`). **Nunca** grave segredo — placeholder
(`<TOKEN>`, `${VAR}`) + ponteiro pro valor real (o `.ia/` é versionado; constituição, Duas fontes da verdade). Forma:
```
---
titulo: "..."
tipo: prompt
atualizado: AAAA-MM-DD
---
# <título>
## Contexto / objetivo quem usa, pra quê, por quê; stack + base (passo 0).
## Design / abordagem o desenho no idioma da stack; o que evitar e por quê.
## Decisões (rastro L#) L1, L2… cada uma: Pergunta · Resposta · Decisão · (Razão/Alternativas).
## Em aberto o que ficou não resolvido (vira Blocking/Open na spec).
```
O bloco **Decisões (L#)** é o **Interview Ledger embutido** (não arquivo separado): cada decisão
materialmente resolvida vira um `L#` estável, que a `/x-definir` referencia na spec. Registre só o
que afeta implementação/escopo/terminologia — não conversa trivial.
## 6. Checkpoint — pronto pra spec
Diga: "Prompt salvo: `.ia/NNN-...-prompt.md`." `AskUserQuestion`: **"Definir a spec (recomendado)"**
→ `/x-definir` (na mesma sessão, preservando o contexto) · **"Continuar a entrevista"** ·
**"Parar"**. Se o usuário pedir a spec com bloqueios ainda abertos, honre — preserve-os no prompt
como "Em aberto" pra spec carregar como Blocking Questions.
> Não commita (REGRA Nº 2). O `.ia/` não é conteúdo publicado. Diante de ambiguidade ou decisão
> com mais de um caminho, PERGUNTE (REGRA Nº 1) — não decida sozinho.
---
name: x-definir
description: Escreve a spec X-Adm (`.ia/NNN-*-spec.md`) a partir do prompt/entrevista, no formato do ACT 1.0, referenciando o rastro L#. Use depois de /x-desenhar (ou direto da conversa).
argument-hint: "[prompt .ia/NNN-*-prompt.md ou vazio]"
tools: [Read, Write, Glob, Grep, Bash, AskUserQuestion, Skill]
---
<!--
Template canônico da skill /x-definir — repo central xadm/documentacao
(templates/x-definir/SKILL.md + references/). Copie o DIRETÓRIO para
.claude/skills/x-definir/. Mude AQUI primeiro e re-derive. Fluxo:
desenhar → definir → refinar → planejar → implementar → documentar.
Derivado do act-create-spec (ACT 1.0) + xadm-spec (passo 5), padrão X-Adm —
storage .ia/ (NÃO .act/), NÃO commita (REGRA Nº 2), stack-aware.
-->
# /x-definir — Escrever a spec (X-Adm)
Escreve uma spec **tão clara que a implementação corre sem adivinhação** a partir do prompt de
`/x-desenhar` (ou direto da conversa). Formato do ACT 1.0, **storage X-Adm** (`.ia/NNN-*-spec.md`,
constituição, Duas fontes da verdade). Não reentrevista — mas, diante de **ambiguidade genuína ou decisão com mais de um caminho,
PERGUNTE** (`AskUserQuestion`, REGRA Nº 1): isto **sobrepõe** a postura minimalista do ACT.
## 0. Stack e base de conhecimento — primeiro
Detecte a stack e leia a base da casa (`engenharia/<stack>` + `stack.md`) — o passo 0 da `/x-desenhar`.
Carregue `references/<stack>.md` desta skill (o que capturar por seção da spec, por stack). Hook
de defasagem → `/xadm-docs` antes.
**Leia a norma que a feature toca** — o passo 0.4 da `/x-desenhar` (seções da constituição que o
pedido alcança, a norma derivada dona e, se a norma do repo atrasou, a seção Migração do CHANGELOG).
Vale aqui mesmo sem prompt, porque há quem comece direto pela spec. Na Technical Decisions, cada
escolha cita a seção da constituição ou a norma derivada que segue.
## 1. Origem: prompt OU conversa
- **Com prompt** (`.ia/NNN-*-prompt.md` de `/x-desenhar`): leia-o; a spec **herda o `NNN`+slug**
(só troca `-prompt`→`-spec`) e **referencia os `L#`** do prompt inline.
- **Sem prompt** (spec rápida direto da conversa, como o `act-create-spec`): use o **próximo `NNN`
livre** e um slug próprio; extraia da conversa as decisões materialmente resolvidas e escreva um
**ledger mínimo embutido** (≥1 record `L1` `current`) na própria spec.
Se ainda não explorou o alvo, inspecione rápido os arquivos/docs/testes relevantes; use o
vocabulário e os padrões reais do repo (idioma da stack, passo 0).
## 2. Escrever a spec (`.ia/NNN-titulo-spec.md`)
**Nunca** carregue segredo do prompt pra spec — placeholder + ponteiro pro valor real (constituição, Duas fontes da verdade).
Referencie os `L#` inline onde a spec cobre a decisão (sobretudo em Requirements, Technical
Decisions, Testing Strategy). Seções (formato ACT 1.0; omita as vazias exceto Problem e Proposed
Outcome):
```
---
titulo: "..."
tipo: spec
atualizado: AAAA-MM-DD
---
## Problem o problema em nível de requisito; quem sofre, por quê.
## Proposed Outcome a forma da solução, no idioma da stack (passo 0); resultado observável.
## User Stories lista numerada; histórias distintas separadas (tarefas referenciam).
## Requirements comportamento concreto, entrada/saída, erros, bordas, limites — numerados,
VERIFICÁVEIS; [L#] inline. Funcionais · Erros/bordas · Validação.
## Technical Decisions escolhas de arquitetura/lib DA CASA; o que evitar e por quê; [L#].
## Testing Strategy Test Seams (prefira os existentes); split unit/integração/e2e; o gate da
stack; a verificação EXERCITA a plataforma real (definição de pronto), não só fixture. [L#].
## Out of Scope o que a spec NÃO cobre (evita expansão de superfície).
## Open Questions não-crítico com default razoável.
## Blocking Questions bloqueio real que a decomposição precisa resolver antes.
```
**Definição de pronto — SEMPRE na Testing Strategy:** todo comportamento arriscado tem teste
proporcional ao risco **e** a mudança leva doc do estado atual no mesmo PR; pular metade é decisão
explícita (REGRA Nº 3). Solução **no idioma da casa** e **a mais simples que resolve** — sem
over-engineering (Engenharia, "Simplicidade primeiro"). Conteúdo puro, pt-BR, sem meta-comentário.
## 3. Cobertura do ledger
Antes de fechar, cheque que **todo `L#` `current`** aparece na spec. Um `L#` não coberto porque
segue não resolvido → marque o record `deferred` e leve o ponto pra `Open Questions`/`Blocking
Questions`. Sem prompt e sem nada materialmente resolvido além do pedido → ainda escreva um ledger
mínimo com 1 record do pedido inicial.
## 4. Próximo passo
"Spec salva: `.ia/NNN-...-spec.md`." `AskUserQuestion`: **"Refinar (recomendado)"** → `/x-refinar`
· **"Planejar"** → `/x-planejar` (spec pequena/coesa/baixo risco) · **"Parar"**. Não invoque o
próximo automaticamente.
> Não commita (REGRA Nº 2). O `.ia/` não é conteúdo publicado. Ambiguidade → PERGUNTE (REGRA Nº 1).
---
name: x-refinar
description: Revisão adversarial de uma spec X-Adm em 7 dimensões (inclui over-engineering), com gate de aprovação. Use depois de /x-definir e antes de planejar.
argument-hint: "[spec .ia/NNN-*-spec.md]"
tools: [Read, Glob, Grep, Bash, AskUserQuestion, Edit]
---
<!--
Template canônico da skill /x-refinar — repo central xadm/documentacao
(templates/x-refinar/SKILL.md + references/). Copie o DIRETÓRIO para
.claude/skills/x-refinar/. Mude AQUI primeiro e re-derive. Fluxo:
desenhar → definir → refinar → planejar → implementar → documentar.
Derivado do act-refine-spec (ACT 1.0) + xadm-refine-spec, padrão X-Adm.
-->
# /x-refinar — Revisão adversarial da spec (X-Adm)
**Roast na spec.** Você é o revisor adversarial que pega os problemas **antes** de planejar:
lacunas, premissas erradas, fluxo incoerente, modelo de dados que não sustenta o uso, desalinho
com o codebase **e com a casa**. Quase sempre traz melhoria sólida — por isso é parte do fluxo.
## Regras não-negociáveis
1. **Revisar primeiro.** Não modifique nenhum arquivo na passada inicial.
2. **Sem edit silencioso.** Não use Edit até o usuário ver os achados e **aprovar**.
3. **Pare no gate.** Depois de apresentar os achados, o estado padrão é **esperar** a decisão.
4. **Resuma antes de perguntar.** A saída tem um resumo numerado das mudanças propostas.
5. **Ambiguidade → PERGUNTE (REGRA Nº 1).** Diante de contradição ou decisão com mais de um
caminho viável, pergunte ao usuário — **sobrepõe** a postura minimalista do ACT ("uma pergunta
só quando bloqueia"). Não resolva ambiguidade por conta própria.
## 0. Stack e base de conhecimento — primeiro
Detecte a stack e leia a base da casa (`engenharia/<stack>` + `stack.md`) — o passo 0 da `/x-desenhar`.
Carregue `references/<stack>.md` desta skill (o que checar/flag por stack). Precisa dela para
julgar a **dimensão 6 (alinhamento à casa)**.
## 1. Reunir contexto (passada PROFUNDA, antes das dimensões)
Não basta o arquivo **existir** — **abra e leia** cada artefato que a spec cita e **confira cada
FATO afirmado contra o artefato real**. Leia o Interview Ledger (embutido no prompt/spec) quando
houver. Roteiro:
1. **Extrair todas as referências** da spec (arquivos, classes, tabelas, endpoints, campos, libs)
e **ler cada uma** — não só confirmar que existem.
2. **Conferir o FATO, não a existência.** A spec diz "o `app.json` tem `slug`"? **Abra um real** e
confira — existir ≠ ter o campo. Fato afirmado e não conferido = candidato a achado crítico.
3. **Camada de dados/contrato:** ache tabelas/modelos/endpoints REAIS que a spec toca e leia —
chave/identidade, campos, namespaces já existentes a reusar (não reinventar).
4. **Rastreie UMA instância real ponta a ponta** pela spec; se o fluxo não fecha, é achado.
5. **Implementações de referência** revelam as convenções.
Investigação focada — valide o que a spec afirma, não mapeie o repo todo.
## 2. Cobertura do Interview Ledger
Se há rastro L# (no prompt/spec), cheque: `L#` `current` ausente da spec; requisito que referencia
um L# mas **enfraquece** a decisão; constraint/requisito negativo do ledger omitido; record
`deferred` tratado como resolvido sem explicação; records `current` duplicados/contraditórios.
## 3. Análise crítica — 7 dimensões (cite evidência: spec §X ou arquivo:linha)
**Lente do implementador:** a cada dimensão, *"se eu sentasse pra construir isto agora, onde
travaria?"* — superfície que a spec **usa mas não contrata**, identidade sem **chave canônica**,
dado que a UX **exige e o modelo não tem**, namespace que a spec deveria **reusar e reinventa**.
1. **Completude** — requisito implícito não dito? sucesso/erro por ação? estados (loading, vazio,
erro, parcial)? auth/permissão quando relevante?
2. **Premissas** — assume lib/API/arquivo/estrutura que **não existe**? capacidade de plataforma
indisponível? **cada fato sobre um artefato foi conferido LENDO o artefato**? **Capacidade de
lib de terceiro verificada na FONTE/changelog da versão** (não só no repo)?
3. **Fluxo/UX** (user-facing) — caminho feliz intuitivo? erro acionável/recuperável? becos sem
saída? navegação (voltar/cancelar)? estados de espera? feature descobrível?
4. **Modelo de dados** — campos pra **todo** fluxo? campo na UX ausente do modelo (ou vice-versa)?
relações claras? persistência (local/remoto/cache) coerente?
5. **Alinhamento ao codebase** — segue estrutura/nomes/convenções **reais** do repo?
6. **Alinhamento à casa (X-Adm)** — usa o **idioma da stack** (libs/padrões do passo 0)? respeita a
constituição (níveis, definição de pronto, sem 2ª fonte — Duas fontes da verdade)? a validação exercita a
**plataforma real**? Diverge da casa **sem** decisão que justifique → achado.
7. **Simplicidade (sem over-engineering)** — pede mais complexidade/abstração/camada/
configurabilidade do que a necessidade **real e presente** justifica? resolve "vai que um dia"?
Existe caminho mais enxuto? (Engenharia, "Simplicidade primeiro".)
## 4. Apresentar achados (review-only — não edite aqui)
Organize por **severidade**, não por dimensão. Cada achado: **título** · *dimensão* · **Problema**
(específico, com evidência) · **Sugestão**.
```
## Revisão da spec: <nome>
### Crítico — bloqueia o plano
### Importante — causaria retrabalho
### Menor — vale polir
### O que a spec acerta (curto, genuíno)
### Resumo das mudanças propostas (lista numerada dos Críticos+Importantes)
```
Regras: toda evidência citada; não invente problema (se está sólido, diga); não sinalize o
declarado fora de escopo; seja direto ("a spec diz X mas o repo faz Y"); priorize o alto impacto —
polimento cosmético só entra em "Menor" e sem inflar a lista.
## 5. Gate de revisão
Só depois de imprimir a revisão completa, `AskUserQuestion`:
- **"Atualizar a spec"** (aplica Críticos+Importantes — liste-os) — converta cada achado aprovado
em edit; antes, mostre um `## Aplicando` curto mapeando edit→achado; depois resuma o que mudou.
- **"Discutir"** — responda, ajuste os achados, volte ao gate.
- **"Está boa"** — sugira `/x-planejar`.
Resposta livre do usuário = feedback sobre o resumo; só edite se a intenção for aplicar. Se um
achado exige decisão de produto, PERGUNTE uma pergunta focada em vez de adivinhar (REGRA Nº 1).
> Não commita (REGRA Nº 2).
---
name: x-planejar
description: Transforma uma spec num plano executável de fases → tarefas (`.ia/NNN-*-plan.md`), tarefa = Work Item; verify = gate da stack. Use depois da spec/refino, antes de implementar.
argument-hint: "[spec .ia/NNN-*-spec.md] [--use-subagents]"
tools: [Read, Write, Glob, Grep, Bash, AskUserQuestion, Skill]
---
<!--
Template canônico da skill /x-planejar — repo central xadm/documentacao
(templates/x-planejar/SKILL.md + references/). Copie o DIRETÓRIO para
.claude/skills/x-planejar/. Mude AQUI primeiro e re-derive. Fluxo:
desenhar → definir → refinar → planejar → implementar → documentar.
Derivado do act-create-issues (ACT 1.0) + xadm-plan, padrão X-Adm —
storage .ia/ (NÃO GitHub Issues), NÃO commita (REGRA Nº 2), stack-aware.
-->
# /x-planejar — Plano de fases → tarefas (X-Adm)
Transforma a spec num **plano executável**: **fases** (fatias verticais) agrupando **tarefas**
auto-contidas (cada tarefa = um Work Item). Concreto o bastante para `/x-implementar` rodar sem
adivinhação. Plano é **andaime** (`.ia/NNN-titulo-plan.md`; constituição, Duas fontes da verdade), storage X-Adm (NÃO GitHub
Issues). Estilo **telegráfico**. Uso: `/x-planejar <spec> [--use-subagents]`.
## 0. Stack e base de conhecimento — primeiro
Detecte a stack e leia a base da casa (`engenharia/<stack>` + `stack.md`). Carregue
`references/<stack>.md` (como fatiar/acceptance por stack). O **verify de cada fase é o gate da
stack**: Java/Gradle → `./gradlew check`; Flutter → `dart format --output=none --set-exit-if-changed . && flutter analyze && flutter test`; Dart →
`dart format --output=none --set-exit-if-changed . && dart analyze && dart test`; Node → `npm run lint && npm test`; docs → `mkdocs build --strict`
(+ `node scripts/lint-mermaid.mjs docs/` se houver diagrama). Hook de defasagem → `/xadm-docs`.
## 1. Ler a spec e checar prontidão
Caminho de arquivo → Read; extraia Problem, Requirements, User Stories, Technical Decisions,
Testing Strategy, bordas, o rastro L#. Se a spec tem **Blocking Questions**, **pare** e reporte
que ela precisa de respostas antes de decompor. **Open Questions** que afetam fronteira/dependência/
acceptance/escopo de tarefa → pergunte só sobre elas (REGRA Nº 1); senão preserve como risco.
## 2. Pesquisar (focado)
**`--use-subagents`** → `act-codebase-researcher` (+ pesquisador de padrões da stack) em paralelo.
**Default** → você mesmo, poucas chamadas: estrutura do repo, padrão de referência **no idioma da
stack**, arquivos/classes que a spec cita. Respeite a arquitetura existente; identifique pequenos
refactors habilitadores.
## 3. Propor as tarefas e APROVAR (antes de escrever)
**Sempre pause antes de escrever.** Apresente uma proposta numerada (fases → tarefas):
```
### Fase 1 — <nome> (fatia vertical fina, prova o caminho crítico)
**1. <título da tarefa>**
- Escopo: <1–2 frases>
- Bloqueada por: Nenhuma | 1, 2
- Cobre: User Stories 1; Requisitos 1–2; Testing 1; L1
```
Mapeie cada `L#` `current` para ≥1 tarefa, ou reporte como não coberto. Pergunte: alguma tarefa
grossa/fina demais? combinar/dividir? dependências certas? Itere até aprovar. **Não escreva antes
do OK.**
## 4. Escrever o plano (`.ia/NNN-titulo-plan.md`)
**Mesmo `NNN`+slug da spec** (`-spec`→`-plan`). **Nunca** carregue segredo — placeholder + ponteiro
(constituição, Duas fontes da verdade). Corpo da **tarefa = Work Item, headers em pt-BR**:
```
## Overview <=2 linhas: o que + abordagem. **Spec**: .ia/NNN-...-spec.md
## Context Stack + base (passo 0); estrutura; padrões de referência; premissas/lacunas.
## Fase N — <nome> (fatia vertical FINA ponta-a-ponta — não camada horizontal)
### T<n>. <título da tarefa>
**O que construir:** <escopo aprovado>
**Contexto necessário:** <arquivos/padrões a seguir; omitir se vazio>
**Critérios de aceitação:**
- [ ] ...
- [ ] Teste: <comportamento> (proporcional ao risco; nenhuma regressão sem teste)
**Cobre:** User Stories …; Requisitos …; L…
**Bloqueada por:** Nenhuma | T<n>
**Verify (Fase N):** <gate da stack> (exercita a plataforma real, não só fixture — definição de pronto)
## Riscos / Fora de escopo top 1–3 riscos · exclusões explícitas.
```
Regras: telegráfico; **fase** = fatia vertical fina (caminho crítico), não camada; `Verify:` (gate
da stack) **por fase**; toda tarefa com acceptance verificável e teste de alto valor; vocabulário
**"tarefa"** (não "issue"/"Work Item"); conflito casa×repo → segue o repo + razão de 1 linha; sem
TDD/robot onde a stack não usa — **o gate da stack manda**. **Definição de pronto:** teste
proporcional ao risco **+** doc do estado atual no mesmo PR; pular metade = decisão explícita
(REGRA Nº 3).
## 5. Salvar + próximo
"Plano salvo em `.ia/NNN-...-plan.md`. Rode `/x-implementar .ia/NNN-...-plan.md`
(`--single-phase` ou `--single-task` p/ granular)." Não invoque o próximo automaticamente.
> Não commita (REGRA Nº 2). O `.ia/` não é conteúdo publicado. Ambiguidade → PERGUNTE (REGRA Nº 1).
---
name: x-implementar
description: Executa um plano X-Adm fase a fase OU tarefa a tarefa, mantendo o plano verdadeiro; NÃO commita (REGRA Nº 2). Use para implementar um plano já escrito.
argument-hint: "[plano .ia/NNN-*-plan.md] [--single-phase | --single-task]"
tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Skill]
---
<!--
Template canônico da skill /x-implementar — repo central xadm/documentacao
(templates/x-implementar/SKILL.md + references/). Copie o DIRETÓRIO para
.claude/skills/x-implementar/. Mude AQUI primeiro e re-derive. Fluxo:
desenhar → definir → refinar → planejar → implementar → documentar.
Derivado do act-implement (ACT 1.0) + xadm-work, padrão X-Adm —
INVERTE o default do ACT: NÃO commita (REGRA Nº 2), stack-aware.
-->
# /x-implementar — Executar o plano, fase a fase ou tarefa a tarefa (X-Adm)
Executa um plano (`.ia/NNN-*-plan.md`) de **fases → tarefas** sistematicamente, mantendo o plano
**verdadeiro**. Uso: `/x-implementar <plano> [--single-phase | --single-task]`.
## Contrato duro
- `x-implementar` **não está completo** enquanto o plano não for **reconciliado** com o que se fez.
- **Não** reporte tarefa/fase como pronta sem ter atualizado os checkboxes correspondentes.
- **NÃO commita** (REGRA Nº 2 — inverte o default do `act-implement`): nada de `git add/commit/push`
— escreve as atualizações do plano em disco e **entrega a mensagem de commit pronta** pro dev.
- Se delegar a execução a um subagente, o controlador no topo **continua responsável** pela
reconciliação, pelos invariantes e pelo critério de sucesso.
## Invariantes (falham o workflow se violados)
Antes de reportar sucesso:
- toda **tarefa** concluída no escopo tem **todos os `## Critérios de aceitação` `[x]`**;
- toda tarefa/critério bloqueado fica `[ ]` **e** tem uma **nota de bloqueio** (no nível da tarefa);
- o **gate da stack** (análise estática + testes) **passou** (passo 2, `prepare`);
- a **definição de pronto** foi cumprida: teste proporcional ao risco **e** doc do estado
atual — ou o pulo de uma metade foi **declarado** (REGRA Nº 3); no teste, deferir é decisão de
**custo × valor** (só no quadrante caro-e-baixo-valor; sensível → escreve a guarda agora), **não
racionalização** ("exercitado end-to-end"/"baixo risco");
- `--single-phase`/`--single-task` não começou a unidade seguinte;
- **nenhum** `git add/commit/push` foi executado.
Falhou qualquer invariante → **falhe** em vez de reportar sucesso em silêncio.
## Stages (nesta ordem; não colapse)
`load → prepare → determine_scope → execute → reconcile_plan → validate → close → decide_continue
→ final_validate → report`
### 1. `load`
Leia o plano inteiro; se houver `**Spec**: .ia/...-spec.md`, leia a spec. Entenda fases, tarefas,
critérios e dependências (`Bloqueada por`). **Não** edite o plano aqui. Plano ambíguo → pare e
pergunte (REGRA Nº 1).
### 2. `prepare`
**Detecte a stack** e leia a base da casa (`engenharia/<stack>` + `stack.md`); carregue
`references/<stack>.md` (support-skills, disposal). Defina o **gate da stack**: Java/Gradle →
`./gradlew check`; Flutter → `dart format --output=none --set-exit-if-changed . && flutter analyze && flutter test`; Dart → `dart format --output=none --set-exit-if-changed . && dart analyze && dart test`;
Node → `npm run lint && npm test`; docs → `mkdocs build --strict` (+ `node scripts/lint-mermaid.mjs
docs/` se tocou Mermaid). Hook de defasagem → `/xadm-docs`.
### 3. `determine_scope`
`--single-task` → exatamente a **próxima tarefa incompleta**, depois pare. `--single-phase` → a
**próxima fase incompleta** (todas as suas tarefas), depois pare. Sem flag → todas as fases/tarefas
incompletas, em ordem, respeitando `Bloqueada por`. Tudo completo → pule pra `final_validate`.
### 4. `execute` (por tarefa)
1. Leia os arquivos da tarefa; **inspecione os padrões existentes** antes de mexer.
2. Implemente **só** essa tarefa, no **idioma da stack**, pelo **caminho mais simples** que cumpre
os critérios — não a versão genérica/extensível (sem over-engineering). Ficando complexo → pare
e busque a enxuta. **Comentário de linha ou de bloco:** uma linha, só o porquê que o código não mostra (Javadoc/dartdoc de API segue completo, no padrão da linguagem); a história vai
para a mensagem de commit, e armadilha de stack vira feedback para a seção Armadilhas da página da
stack, não comentário.
3. **Fatia fina ponta-a-ponta** que prova o comportamento antes de alargar.
4. Rode os testes enquanto trabalha. Antes de dar um critério como cumprido, **considere efeitos de
sistema** (async/erro, persistência/limpeza, paridade entre superfícies, caminhos de
widget/integração que o teste deveria exercitar).
5. Registre: critérios cumpridos, bloqueados, testado, arquivos mudados.
Se delegar, exija sumário estruturado (`tarefa`, `criterios_cumpridos`, `bloqueados`, `notas`,
`testes_rodados`, `arquivos_mudados`). **Pare e pergunte** se: a tarefa está bloqueada por
requisito/dependência faltando; falhas repetidas sugerem plano/abordagem errado; exige decisão
manual.
### 5. `reconcile_plan` (obrigatório após cada tarefa)
Re-leia o plano. Case o reportado com os `## Critérios de aceitação`; marque `[ ]→[x]` o cumprido;
bloqueado fica `[ ]` + **nota de bloqueio no nível da tarefa**; **a tarefa fecha quando todos os
seus critérios estão `[x]`; a fase fecha quando todas as suas tarefas fecham**. **Falhe** se um
critério dito cumprido não tem checkbox atualizado, ou um bloqueado não tem nota. **Mantenha o
plano vivo:** anote por tarefa **quando** rodou, **o que faltou e por quê**, e o que é
**decisão/operação humana** (release, deploy, validação visual, infra).
### 6. `validate`
Rode o **gate da stack** (do `prepare`). A verificação **exercita a plataforma/runtime real**, não
só `--strict`/fixture (definição de pronto). Confira: critérios da tarefa `[x]`; bloqueados `[ ]`+nota; se
`--single-*`, nenhuma unidade seguinte começou. Falhou → não passa.
### 7. `close` (no lugar do commit do ACT — REGRA Nº 2)
`x-implementar` **não commita**. Ao fechar uma **fase/tarefa intermediária** (`--single-*`, plano
ainda não concluído), entregue o **fechamento da casa** na mesma resposta:
- **[1] mensagem de commit pronta** (ghost mode, **sem** `Co-Authored-By`/atribuição de IA): assunto
conventional-commit de 1 linha + 1 parágrafo curto do *porquê*.
- **[2] a linha de feedback**, afirmativa: `Feedback: nada a reportar` **ou** `Feedback: candidato — <o quê>`.
Quem commita é o dev / `/xadm-release`. **Quando o plano CONCLUI** (última fase/tarefa), **NÃO**
entregue a mensagem de commit final aqui — o ciclo fecha no `/x-documentar` (ver o passo 10, `report`, desta skill).
### 8. `decide_continue`
`--single-task`/`--single-phase` → pare; reporte a unidade feita, bloqueados, gate rodado, **que não
commitou**, qual unidade roda na próxima. Senão → próxima unidade incompleta (respeitando bloqueios).
### 9. `final_validate`
Re-rode o gate. O plano reflete a realidade do escopo feito; sem `[ ]` exceto bloqueios
documentados/exceções aprovadas. Confirme: **nenhum commit foi feito**.
### 10. `report`
Reporte com verdade: fases/tarefas feitas nesta run, cumpridos/bloqueados, gate rodado, **commit não
feito**, o que falta. **Ao CONCLUIR o plano:** **NÃO entregue a mensagem de commit** — o ciclo fecha
em outra etapa. **Rode `/x-documentar`**, que faz a **revisão geral** do que foi feito, **audita
lacuna de doc e de teste** (definição de pronto), **destila** o durável pra `docs/`, **apaga o andaime** e **entrega a
mensagem de commit do ciclo**. É ele que fecha (`implementar → documentar → commit`), não este passo.
"Feature pronta" = andaime apagável sem perda.
## Pitfalls
- **Batching de teste** (TDD): um teste falho → implementa → repete; não muitos testes antes.
- **Síndrome dos 80%:** termine a tarefa em escopo **com verdade** antes de começar a próxima.
- **Paralisia de análise:** com plano claro, **execute** a próxima fatia em vez de re-planejar.
> O `.ia/` não é conteúdo publicado. NÃO commita (REGRA Nº 2). Ambiguidade → PERGUNTE (REGRA Nº 1).
---
name: x-documentar
description: Destila o que a sessão produziu de durável para `docs/` seguindo a constituição E audita a lacuna de doc e de teste da definição de pronto. Use ao concluir uma feature/refactor/diagnóstico.
argument-hint: "[plano .ia/NNN-*-plan.md ou vazio]"
tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, Skill]
---
<!--
Template canônico da skill /x-documentar — repo central xadm/documentacao
(templates/x-documentar/SKILL.md). Copie o DIRETÓRIO para
.claude/skills/x-documentar/. Mude AQUI primeiro e re-derive. Fluxo:
desenhar → definir → refinar → planejar → implementar → documentar.
Sem par no ACT 1.0 (o act-workflow-compound foi deprecado sem substituto) —
design da casa: destila pra docs/ + audita lacuna (definição de pronto). NÃO commita (REGRA Nº 2).
-->
# /x-documentar — Destilar a sessão para `docs/` + auditar a lacuna (X-Adm)
Duas coisas ao concluir uma feature/refactor/bugfix/migração/diagnóstico: **(A)** destila o que a
sessão produziu de **durável** para onde ele vive na casa (`docs/`, não `ai_docs/`), fechando o
**loop de feedback**; **(B)** audita a **lacuna** contra a definição de pronto: que **doc** e que
**teste** ainda faltam pro que se implementou.
## 0. Stack e base de conhecimento — primeiro
Detecte a stack e leia a base da casa (`engenharia/<stack>` + `stack.md`) — é nela que o
conhecimento de stack desta sessão se acumula.
## 1. Levantar os insights da sessão
Releia o que mudou (git diff/log da sessão, o plano `.ia/`, os arquivos tocados) e extraia três
facetas, em fatos, não prosa (sessão grande pode delegar a subagentes): **Resultado** (o que foi
construído/corrigido + estado final); **Decisão & trade-off** (escolhas + alternativa preterida +
porquê); **Reuso** (padrão/lib/armadilha pro próximo dev/projeto). Separe **durável** (vale pro
próximo) de **andaime** (detalhe de execução, já no Git). Classifique o destino:
| Insight | Destino na casa |
|---|---|
| Decisão técnica + porquê | `docs/decisoes/NNNN-*.md` (registro de decisão) |
| Desenho/arquitetura do sistema atual | `docs/projeto/` (e o livro `projeto/index.md` se mudou) |
| Procedimento (deploy, recuperação) | `docs/operacao/` (runbook) |
| Passo a passo de usuário | `docs/manual/` |
| **Conhecimento de STACK** (lib, padrão, armadilha, "como logar/GlitchTip") | página `engenharia/<stack>` (armadilha → seção **Armadilhas**, nunca comentário no código) — *feedback pro central* |
## 2. Destilar para `docs/` (no app)
Escreva/atualize os docs do destino — **um fato, um dono** (constituição, Duas fontes da verdade): linka/snippets, **não copia**. O
inferível do código se descarta. Ao terminar, o andaime (`.ia/`) é apagável sem perda. **Quality
bar** — o doc deixa estas respondíveis em <1min por quem chega novo: o que foi decidido/construído
e **por quê**? qual trade-off (e o preterido)? como reusar/operar sem reler o código? onde mora a
fonte da verdade (1 lugar, sem 2ª cópia)? Vago → ainda não está pronto.
## 3. Auditar a lacuna (a definição de pronto)
Contra o que se implementou nesta sessão, aponte **explicitamente** o que falta das **duas
metades** da definição de pronto:
- **Doc do estado atual:** README/runbook/contrato/livro/decisão que a mudança tornou desatualizado;
**decisão de design que a sessão tomou e ainda NÃO virou `docs/decisoes/0NNN`** (RD *faltante*, não
só RD desatualizado) e o **`docs/projeto/` (arquitetura)** que deixou de bater com o build;
**screenshot do manual** cuja UI retratada mudou (regenerar o PNG **e** conferir abrindo a imagem,
não só rodar o gerador — definição de pronto).
- **Teste proporcional ao risco:** comportamento arriscado sem teste; regressão sem cobertura;
fronteira de segurança/contrato sem teste que exercita a plataforma real (não só fixture); provider
de API externa com **fixture inventada** (não capturada da instância real) = **falso atestado** —
exigir **≥1 resposta real capturada** antes de "ligada" (definição de pronto).
**Rode as duas guardas de doc antes do fechamento** — sem elas, o ADR fora do nav e a migration sem
modelo só aparecem no pré-flight da `/xadm-release`, depois do commit:
```bash
curl -fsSL https://docs.xadm.biz/padroes/checa-nav.py -o checa-nav.py
python checa-nav.py
curl -fsSL https://docs.xadm.biz/toolchain/checa-modelagem.py -o checa-modelagem.py
python checa-modelagem.py origin/master
```
O `checa-modelagem` compara a base com a árvore de trabalho, então vê o que ainda não foi commitado. O
aviso dele é lacuna de doc desta auditoria. Apague os dois scripts baixados depois.
Para cada lacuna: **onde**, **por que importa**, e uma **classificação custo × valor** explícita. O
viés é **implementar a guarda barata e proporcional AGORA**, não deferir com racionalização —
*"exercitado end-to-end"* e *"baixo risco"* são justo as frases que deixam a guarda barata escapar.
**Só deferir no quadrante caro E de baixo valor** (REGRA Nº 3); comportamento **sensível
(segurança/privacidade/contrato)** → default é escrever a guarda agora. Não invente lacuna; se está
coberto, diga.
## 4. Refinar a base de conhecimento da stack (loop de feedback)
Conhecimento de stack que vale para **outros apps** não fica só neste: vira **feedback pro repo
central** `documentacao` — um texto curto (padrão/armadilha/lib) pro Gustavo colar numa sessão do
Claude no central e enriquecer a página `engenharia/<stack>`. É assim que a base **refina com o
tempo**. O texto **se identifica**: abre com o repo e a versão da constituição que ele segue
(`app.json` `constituicao`), dá o contexto (o que se fazia, o que foi **medido** × suposto) e, quando
fizer sentido, **aponta a fonte** com link do Forgejo
(`https://fonte.xadm.biz/xadm/<repo>/src/branch/master/<caminho>`) em vez de parafrasear o código —
sem isso o central reconstrói o caso às cegas ou precisa pedir para ler o repo.
**Disciplina de tokens (se o repo usa rtk/caveman):** parte da auto-análise de fechamento — rode
`rtk gain`/`rtk discover`, **auto-corrija** o uso desta sessão (comando **bare** que o hook vê,
ferramentas nativas de arquivo, output **terso + carve-out**) e **roteie o gap sistêmico**: recipe de
stack que economiza tokens → **feedback** (para outros apps aprenderem); comando sem handler no rtk →
**issue tracker do RTK** (não a constituição). Não force onde não há as ferramentas. Detalhe:
[ferramentas](https://docs.xadm.biz/engenharia/ferramentas/) · [agentes](https://docs.xadm.biz/engenharia/agentes/).
## 5. Fechamento — a revisão geral que fecha o ciclo
Este é o **fecho do ciclo** `implementar → documentar → commit` (o `/x-implementar` aponta pra cá em
vez de sugerir o commit). Faça a **revisão geral do que a sessão fez** e entregue, na mesma resposta:
1. **O que foi destilado** (e onde) + as **lacunas da definição de pronto** — **avaliação da doc** (o que ficou
desatualizado/faltando) **e dos testes** (comportamento arriscado sem cobertura), fazer-agora ×
deferido explícito (REGRA Nº 3) — + o **texto de feedback pronto** pro central (se houver conhecimento de
stack reusável).
2. **Apague o andaime** da linhagem (`.ia/NNN-*` — prompt/spec/plan) — **liste antes de apagar** e
**confira que o histórico existe de fato**: `git log --oneline -- .ia/NNN-*`. Arquivo **nunca
commitado** (ciclo rodado inteiro numa sessão) → apagar destruiria a única cópia do rastro L#;
nesse caso **não apague**: avise e inclua o `.ia/` no commit do ciclo (um commit seguinte os
remove, preservando o histórico — "feature pronta = andaime apagável sem perda" pressupõe o
Git tê-los visto). Só depois de confirmar que destilou tudo.
3. **[1] a mensagem de commit do ciclo** (ghost mode, **sem** `Co-Authored-By`: assunto
conventional-commit de 1 linha + 1 parágrafo do *porquê*, cobrindo o que foi feito **e a remoção do
andaime**) + **[2] a linha de feedback** afirmativa. **Não commita** (REGRA Nº 2) — quem commita é o dev.
4. **Recomende `/compact`** — mas **depois do commit**, não antes. O durável desta sessão já está
destilado em `docs/` (é o que esta skill acabou de fazer), então compactar o contexto **recupera
tokens sem perda** (economia de sessão, constituição, Governança). A **ordem importa**: se compactar antes de
commitar, a mensagem pronta pode se perder no resumo e o dev ainda não salvou.
> Fronteira com `/xadm-meta-audit-work`: **x-documentar** destila + aponta lacuna da definição de
> pronto; **xadm-meta-audit-work** audita o *contrato de um run* de `/x-implementar` (não-commit,
> reconciliação, gate). Não fundir.
A skill de auditoria do fluxo — confere se um run da /x-implementar seguiu o
contrato (não-commit, reconciliação do plano, gate da stack, fechamento correto do ciclo):
---
name: xadm-meta-audit-work
description: Audita um run da /x-implementar (não-commit, reconciliação do plano, gate da stack, fechamento correto do ciclo). Use para verificar se um run seguiu o contrato.
---
<!--
Template canônico da skill /xadm-meta-audit-work — repo central xadm/documentacao
(templates/xadm-meta-audit-work-skill.md). Copie para .claude/skills/xadm-meta-audit-work/SKILL.md.
Mude AQUI primeiro e re-derive. Inspirado no Agentic Coding Toolkit (Andrea
Bizzotto), reescrito para o padrão X-Adm — política de commit INVERTIDA
(implementar NÃO commita, REGRA Nº 2), gate por stack, confere o fechamento.
Audita a /x-implementar (ex-/xadm-work — rename da decisão 0006).
-->
# /xadm-meta-audit-work — Auditar um run da `/x-implementar`
Auditoria **best-effort** (não prova formal) de um run da `/x-implementar`: ele seguiu o contrato?
Uso: `/xadm-meta-audit-work <repo-raiz> <commit-inicial> [<arquivo-de-log>]`.
## Contrato da auditoria (somente leitura)
Esta skill **só** lê e escreve **um** relatório no fim. **Não** edita arquivo, **não** faz
`git add/commit/push`, **não** mexe em branch/working tree. Bash só para inspeção
(`git status/log/diff/show`). Relatório vai em `.ia/NNN-auditoria-implementar-<commit>.md`
(andaime, constituição, Duas fontes da verdade — apagável após lido).
## Fontes de evidência (use as três juntas)
1. **Git** desde `commit-inicial` — o que mudou, se houve commit, o que segue não-commitado;
2. **Plano + spec** (`.ia/`) — escopo esperado e se o plano hoje é **verdadeiro** (checkboxes
batem com o feito); se der, leia o plano em `commit-inicial` (`git show <commit>:<path>`)
como baseline;
3. **Log do run** (se fornecido) — intenção, flags, ferramentas, ações proibidas.
## Modelo de evidência
Cada check recebe: `Verificado` (evidência direta) · `Provável` (forte, não provado) ·
`Não-provável` (evidência insuficiente) · `Falhou` (evidência direta de violação) · `Pulado`
(estágio corretamente não-aplicável). **Não** use `Falhou` por evidência ausente sozinha.
Veredito: `Passou` · `Passou-com-ressalvas` (sem violação, mas confiança reduzida por
ambiguidade / working tree suja / mudanças posteriores não-relacionadas) · `Falhou` (violação
explícita ou contradição clara do estado do repo).
## Passos
1. **Validar entradas:** repo existe e é git; `commit-inicial` resolve; log existe (se passado).
Faltou/ inválido → pare com relatório de falha claro.
2. **Stack & gate esperado:** detecte a stack (`app.json` `stack:`/repo) e derive o **gate**
(Java/Gradle `./gradlew check`; Flutter `dart format --output=none --set-exit-if-changed . && flutter analyze && flutter test`; Dart
`dart format --output=none --set-exit-if-changed . && dart analyze && dart test`; Node `npm run lint && npm test`; docs `mkdocs build --strict`,
+ `lint-mermaid` se tocou Mermaid). Ambíguo → expectativa de validação = `Não-provável`.
3. **Evidência de git:** `git log --oneline <commit>..HEAD`, `git diff --name-status <commit>..HEAD`,
`git status --short`, branch atual. Estado ruidoso / trabalho posterior não-relacionado →
**avise e reduza a confiança**, não force precisão falsa.
4. **Avaliar contra o contrato da `/x-implementar`:**
- **Reconciliação do plano** — feito reflete em `[x]`? bloqueado segue `[ ]` **com nota**?
tarefa só fecha com todos os critérios `[x]`; fase só fecha quando todas as tarefas fecham?
(use o baseline do `commit-inicial`).
- **Escopo** — `--single-task`: **só** a próxima tarefa incompleta aparece recém-concluída;
`--single-phase`: **só** a próxima fase incompleta (todas as suas tarefas); unidades
seguintes recém-marcadas → `Falhou`. Sem baseline → `Provável`/`Não-provável`.
- **Gate da stack** — há evidência de que o gate rodou após as unidades em escopo? Plataforma
real exercitada (não só fixture)? Stack ambígua → `Não-provável`.
- **Política de commit (INVERTIDA — REGRA Nº 2):** `x-implementar` **NÃO commita**. **Qualquer**
`git add/commit/push`/`gh pr create` atribuível ao run = `Falhou`. O esperado é working
tree com as mudanças do run **não-commitadas**.
- **Fechamento do run — depende do ponto do ciclo** (ordem `implementar → documentar → commit`):
- **Fechamento intermediário** (`--single-*`, plano ainda não concluído): a mesma resposta
entrega **[1] a mensagem de commit pronta** (ghost, sem atribuição de IA) **e** **[2] a
linha de feedback** afirmativa (`Feedback: nada a reportar` ou `Feedback: candidato — <o quê>`).
Ausente → ressalva (passo pulado é sinal visível).
- **Plano CONCLUÍDO:** o run **NÃO** entrega a mensagem de commit final — o report deve
**apontar pro `/x-documentar`** (que audita lacunas da definição de pronto, destila, apaga o andaime e entrega
a mensagem do ciclo). Mensagem de commit final entregue aqui = ressalva (contrato antigo);
report sem o ponteiro pro `/x-documentar` = ressalva.
- **Definição de pronto** — teste proporcional ao risco **e** doc do estado atual no
escopo — ou pulo **declarado** (REGRA Nº 3)? No teste, deferir é **custo × valor**, não
racionalização.
5. **Fidelidade dos estágios:** `load · prepare · determine_scope · execute · reconcile_plan ·
validate · close · decide_continue · final_validate · report`.
`Verificado` só com evidência direta; `Provável` quando fortemente sugerido; `Não-provável`
quando não se estabelece; `Pulado` só quando o contrato diz que não roda neste run.
## Relatório
Escreva `.ia/NNN-auditoria-implementar-<commit>.md`: **Resumo** (veredito, repo, commit, plano/spec
resolvidos, stack/gate, invocação) · **Tabela de status** (Reconciliação · Escopo · Gate ·
Commit · Fechamento · Definição de pronto) · **Auditoria de estágios** (os 10) · **Achados**
(maior severidade primeiro; baseados em evidência; incertos rotulados como incertos — não
apresente inferência provável como fato) · **Evidência** (linhas de log/git/plano) ·
**Conclusão** (honesta quanto à confiança). Sem achados → diga explicitamente + ambiguidade
residual. Ao final, imprima o caminho do relatório.
> Auditoria não commita (REGRA Nº 2). O `.ia/` não é conteúdo publicado.
Regras de IA (CLAUDE.md)¶
Bloco obrigatório no topo do CLAUDE.md de todo repo que usa Claude Code
(Regras de IA): a IA não decide sozinha e
não faz commit/push sozinha.
<!--
Template canônico das regras de IA — repo central xadm/documentacao
(templates/claude-regras.md). Cole este bloco NO TOPO do CLAUDE.md de cada
repo que usa Claude Code (constituição, Governança). Se as regras mudarem, mude
aqui primeiro e re-derive as cópias.
Lembrete (constituição, Princípios e Governança): o CLAUDE.md é ROTEADOR, não acervo —
regras de agente + versão-base da constituição + ponteiros para docs/ e
README. Conhecimento durável vive em docs/; artefato de trabalho (spec,
plano) destila para docs/ ao concluir (obrigatório); apagar o andaime é
recomendado, não obrigatório.
Tokens (constituição, Governança): o CLAUDE.md é carregado INTEIRO em toda sessão —
mantenha-o enxuto: backlog/histórico concluído migra para um arquivo-acervo
NÃO carregado (ex. BACKLOG-HISTORICO.md na raiz, consultável via grep); aqui
ficam pendências + itens recentes. E o output do agente é TERSO (estilo
caveman) por default — carve-out: conteúdo de documentação, mensagem de
commit, código, linha de feedback (detalhe: docs.xadm.biz/engenharia/agentes/).
Gates/comandos: se o dev usa o rtk (opt-in), rode os gates BARE — sem
`| pipe`, sem `git -C`, sem `2>&1` (furam o hook) — e `rtk err <cmd>` nos
sem-handler (mkdocs/python3/node/`gradlew check`). A frugalidade-NA-FONTE
(`-r failures-only`, `--console=plain`, Read/Grep/Glob nativos em vez de
cat/grep/find) vale mesmo SEM rtk. Detalhe: docs.xadm.biz/engenharia/ferramentas/.
-->
> **REGRA Nº 1 — NÃO DECIDIR SOZINHO.** Havendo ambiguidade, mais de um
> caminho possível ou uma decisão de design a tomar, não escolha por conta:
> avalie, pesquise se preciso, apresente as opções com UMA recomendação
> fundamentada e **confirme com o usuário qual caminho seguir ANTES de
> implementar**. Vale inclusive quando o pedido parecer dar carta branca
> ("algo simples", "você decide", "não sei") — isso é convite para opinar
> com escolha, não para executar sem confirmar.
> **REGRA Nº 2 — NÃO COMMITAR NEM PUSHAR SOZINHO. NUNCA.**
> Exceção única: a skill `/xadm-release` (commit + tag + push explícito).
> Isso vale **inclusive para skills/ferramentas que commitam por padrão** (ex. ACT
> `act-workflow-work`, que commita por fase): invoque-as **sempre com a flag de
> não-commitar** (`--do-not-commit` ou equivalente) — delegar a execução **não**
> delega a decisão de commit.
> Fora dela, quem executa é o usuário — mas **seja proativo**: ao concluir um
> trabalho ou chegar a um ponto natural de fechamento, avise que é um bom
> momento para salvar e **escreva a mensagem de commit pronta para copiar**.
> **Formato:** assunto de uma linha (conventional commit) + UM parágrafo curto
> com o *porquê* e o contexto. Nem só o assunto (quase sempre insuficiente),
> nem lista de arquivo por arquivo (o `git diff` já diz o *quê*, e o dev pula a
> parede de texto).
> **Ghost mode — SOBREPÕE o default do harness:** a mensagem sai **sem assinatura
> de IA** — nada de `Co-Authored-By:`, "Generated with", nem qualquer trailer/
> atribuição de agente. O autor do commit é o dev. (A skill `/xadm-release` já
> segue isso.)
> **Fechamento = dois itens inseparáveis, na MESMA resposta** (um não sai sem o
> outro): **[1] a mensagem de commit** (acima) e **[2] a linha de feedback**, declarada de
> forma **afirmativa** — `Feedback: nada a reportar` **ou** `Feedback: candidato —
> <o quê>`. Num repo de app, um candidato vira o texto de feedback pronto para o usuário
> colar no central, e esse texto **se identifica**: abre com o repo e a versão da
> constituição que ele segue (`app.json` `constituicao`), dá o contexto (o que se
> fazia, o que foi **medido** × suposto) e, quando fizer sentido, **aponta a fonte**
> com link do Forgejo (`https://fonte.xadm.biz/xadm/<repo>/src/branch/master/<caminho>`)
> em vez de parafrasear o código. No próprio central, registre/trate direto. A linha de feedback é
> **OBRIGATÓRIA**: sua ausência = passo pulado (sinal visível), não silêncio. O
> loop de feedback não pode depender de o dev — **nem do agente** — lembrar.
> **Se o trabalho mudou CÓDIGO**, o fechamento também afirma a **definição de pronto**
> (constituição, Governança): **teste proporcional ao risco E doc do estado atual** no mesmo
> PR — pular qualquer metade é decisão explícita (REGRA Nº 3), não silêncio.
> **REGRA Nº 3 — DEFERIR É EXPLÍCITO, NÃO SILENCIOSO.**
> Adiar trabalho que a constituição recomenda (ex. reescrever conteúdo antigo
> para uma barra nova, na migração oportunista) é uma **decisão** — declare-a **em voz
> alta no fechamento**: *"deferido X porque A/B/C"*, nunca como rodapé (decisão de
> não-fazer some se não for dita). E se o repo ainda **não publicou** (nenhum slug
> no ar), o custo de rename/redirect é **zero** → **ofereça fazer agora** em vez de
> deixar para depois.
Hook de constituição (.claude/checa-constituicao.sh)¶
Verificação automática ao abrir o Claude Code no repo: avisa se a doc está
defasada da constituição vigente. O snippet do settings.json está no
cabeçalho do próprio script.
#!/bin/sh
# Hook SessionStart do Claude Code: avisa se o repo defasou da NORMA (constituição) ou do KIT (templates, scripts, skills).
# Destino: .claude/checa-constituicao.sh; registre no .claude/settings.json:
# "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "sh .claude/checa-constituicao.sh" } ] } ] }
# Saída vazia = em dia; sem rede, silêncio (timeout de 3s, nunca trava a sessão).
BASE_URL="${XADM_TOOLCHAIN_URL:-https://docs.xadm.biz/toolchain}" # override só em teste
CB=$(date +%s)
# Cache-bust (?cb= + no-cache): o CDN pode servir um arquivo stale e o aviso mentiria.
baixa() { curl -fsSL --max-time 3 -H 'Cache-Control: no-cache' "$BASE_URL/$1?cb=$CB" 2>/dev/null; }
campo() { sed -n "s/.*\"$1\"[[:space:]]*:[[:space:]]*\"\([^\"]*\)\".*/\1/p" | head -n 1; }
menor() { [ "$1" != "$2" ] && [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | head -n 1)" = "$1" ]; }
vig=$(baixa constituicao-versao.txt | tr -d '[:space:]') || exit 0
[ -n "$vig" ] || exit 0
kitv=$(baixa kit-versao.txt | tr -d '[:space:]')
man=$(baixa manifesto.json)
man_c=$(printf '%s\n' "$man" | campo constituicao)
man_k=$(printf '%s\n' "$man" | campo kit)
# Os três arquivos saem da mesma publicação: se discordam, o CDN serviu um velho.
if [ -n "$man_c" ] && { [ "$man_c" != "$vig" ] || { [ -n "$kitv" ] && [ "$man_k" != "$kitv" ]; }; }; then
echo "AVISO: cache inconsistente no site da toolchain (txt: constituição $vig, kit ${kitv:-?}; manifesto: constituição $man_c, kit ${man_k:-?}). Não dá para afirmar se o repo está em dia — rode /xadm-docs, que re-baixa com cache-bust."
exit 0
fi
base=$(campo constituicao < docs/app.json 2>/dev/null)
base_k=$(campo kit < docs/app.json 2>/dev/null)
if [ -n "$base" ] && menor "$vig" "$base"; then
echo "AVISO: este repo registra a constituição X-Adm '$base', À FRENTE da publicada ('$vig') — provavelmente o deploy do central atrasou ou a versão foi registrada antes de publicar. Não migre pra baixo; confira o central."
exit 0
fi
if [ -z "$base" ] || menor "$base" "$vig"; then
echo "AVISO: a NORMA defasou — este repo segue a constituição '${base:-nenhuma registrada}', a vigente é '$vig'. Rode /xadm-docs: ela mostra o que mudou e pergunta antes de migrar."
if [ -n "$base" ] && [ "${base%%.*}" != "${vig%%.*}" ]; then
echo "AVISO: a base é de MAJOR anterior. A /xadm-docs deste repo é de antes da virada: baixe a vigente de $BASE_URL/raw/templates/xadm-docs-skill.md e siga a versão baixada, não a cópia local."
fi
fi
if [ -n "$kitv" ] && menor "${base_k:-0.0.0}" "$kitv"; then
echo "AVISO: o KIT defasou — este repo sincronizou o kit '${base_k:-nenhum registrado}', o vigente é '$kitv'. Rode /xadm-docs: ela re-deriva templates, scripts e skills sem perguntar."
fi
Config do agente (.claude/settings.json)¶
A base compartilhada do allow-list do Claude Code — só os universais (git, rtk, python,
node, mkdocs, docker, curl escopado), em Bash e PowerShell. Copie-a para .claude/settings.json no
bootstrap; some as adições da sua stack e mantenha em dia. A base traz só env+permissions,
não o bloco hooks — quem crava o SessionStart do checa-constituicao é a instalação
(bootstrap ou /xadm-docs), senão o hook fica presente porém nunca acionado; ao sincronizar, o
/xadm-docs re-deriva a base, garante esse hook e preserva seus demais hooks/grants locais.
JSON não aceita comentário → a orientação por stack e os
grants de máquina (JAVA_HOME, leitura de memória) vivem na regra viva:
Ferramentas § higiene do settings.json.
Path absoluto de máquina (JAVA_HOME, Read(~/.claude/...)) vai sempre no
.claude/settings.local.json gitignored, nunca aqui.
{
"env": {
"PYTHONUTF8": "1"
},
"permissions": {
"allow": [
"Bash(git *)",
"Bash(rtk *)",
"Bash(python *)",
"Bash(python3 *)",
"Bash(py *)",
"Bash(node *)",
"Bash(mkdocs *)",
"Bash(python -m mkdocs *)",
"Bash(python3 -m mkdocs *)",
"Bash(py -m mkdocs *)",
"Bash(docker *)",
"Bash(echo *)",
"Bash(curl * https://docs.xadm.biz/*)",
"Bash(curl * https://fonte.xadm.biz/api/packages/xadm/maven/*)",
"Bash(curl -s http://localhost:8000/*)",
"Bash(curl -sI http://localhost:8000/*)",
"PowerShell(git *)",
"PowerShell(rtk *)",
"PowerShell(python *)",
"PowerShell(python3 *)",
"PowerShell(py *)",
"PowerShell(node *)",
"PowerShell(mkdocs *)",
"PowerShell(python -m mkdocs *)",
"PowerShell(python3 -m mkdocs *)",
"PowerShell(py -m mkdocs *)",
"PowerShell(docker *)",
"PowerShell(echo *)",
"PowerShell(curl * https://docs.xadm.biz/*)",
"PowerShell(curl * https://fonte.xadm.biz/api/packages/xadm/maven/*)",
"PowerShell(curl.exe -fsSL https://docs.xadm.biz/*)",
"PowerShell(curl.exe -s http://localhost:8000/*)",
"PowerShell(curl.exe -sI http://localhost:8000/*)"
]
}
}