--- name: xadm-release description: Release do — bump SemVer, atualiza CHANGELOG.md, commit chore(release), tag anotada e push. Modo ghost (sem Co-Authored-By). disable-model-invocation: true --- # /xadm-release — Release do 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 — release sem prompt (opcional) Por padrão o Claude Code **pede autorização** a cada `git commit`/`git push` (rede de segurança). Como esta skill é o **único** ponto autorizado a commitar/ pushar (REGRA Nº 2), dá pra liberar essas operações no `.claude/settings.json` do app e o release roda sem prompt: ```json { "permissions": { "allow": [ "Bash(git *)", "Bash(echo *)", "Bash(./gradlew *)", "Bash(docker *)", "Bash(dart *)", "Bash(flutter *)", "Bash(fvm *)", "Bash(npm *)", "Bash(node *)", "Bash(python *)", "Bash(python3 *)", "Bash(py *)", "Bash(rtk *)", "Bash(mkdocs *)", "Bash(python -m mkdocs *)", "Bash(python3 -m mkdocs *)", "Bash(curl -fsSL https://docs.xadm.biz/*)", "Bash(curl -s http://localhost:8000/*)", "Bash(curl -sI http://localhost:8000/*)" ] } } ``` (Regras por **ferramenta**, não por prefixo de argumento: `git *` cobre leitura (pré-flight `status`/`log`/`diff`) **e** escrita (`add`/`commit`/`tag`/`push`) — a garantia de "só commita no release" passa a ser a **REGRA Nº 2** (conduta), não o prompt. Da `./gradlew` pra baixo são os **gates** — de código, de container e de docs. **Mantenha só as da SUA stack** e apague as demais. Wildcard por ferramenta mata a fragilidade de prefixo — `npm install` **e** `npm i`, `python` **e** `python3` **e** `py`, `git status` **e** `git --no-pager status` casam igual; um allow-list por prefixo exato voltava a pedir prompt a cada variação de forma. Só o `curl` fica **escopado** (`docs.xadm.biz` + `localhost:8000`) de propósito — não libere download genérico; ao baixar validador com `-o`, a **URL vem ANTES do `-o`** (`curl -fsSL https://docs.xadm.biz/… -o scripts/…`). As três de `curl`/`localhost` cobrem o **preview local** (`mkdocs serve` + conferência), o outro gerador recorrente de prompt em sessão de docs. `rtk *` cobre o wrapper de tokens da casa — `rtk err python scripts/…`, `rtk err mkdocs …`: o `rtk err` roda o comando **bare** e só cospe a saída na falha.) **Windows nativo (sem WSL):** o harness roda os comandos pela ferramenta **PowerShell**, que tem **namespace próprio de regra** — nenhuma regra `Bash(...)` casa com ela. Adicione o espelho (mesma lógica: git + echo + só os gates da sua stack): ```json { "permissions": { "allow": [ "PowerShell(git *)", "PowerShell(echo *)", "PowerShell(.\\gradlew.bat *)", "PowerShell(docker *)", "PowerShell(dart *)", "PowerShell(flutter *)", "PowerShell(fvm *)", "PowerShell(npm *)", "PowerShell(node *)", "PowerShell(python *)", "PowerShell(python3 *)", "PowerShell(py *)", "PowerShell(rtk *)", "PowerShell(mkdocs *)", "PowerShell(python -m mkdocs *)", "PowerShell(python3 -m mkdocs *)", "PowerShell(py -m mkdocs *)", "PowerShell(curl.exe -fsSL https://docs.xadm.biz/*)", "PowerShell(curl.exe -s http://localhost:8000/*)", "PowerShell(curl.exe -sI http://localhost:8000/*)" ] } } ``` (No PowerShell o gradlew é **`.\gradlew.bat`** e o download é **`curl.exe`** — `curl` puro é alias de `Invoke-WebRequest` e não casa com a regra. O **interpretador Python** varia por SO — `python3` no Linux, `python`/`py` no Windows —, então o allow-list lista as três formas; com wildcard por ferramenta qualquer uma casa, e os gates do pré-flight não pedem prompt um a um na máquina do dev.) **Trade-off:** as regras de escrita removem o prompt como rede de segurança — a garantia de "só commita no release" passa a ser a REGRA Nº 2 (conduta), não o prompt. **Opt-in**: deixe de fora se preferir confirmar cada release. **Dica de execução:** rode cada `git` **separado e simples** (UMA chamada Bash por comando), `git` puro (não `rtk proxy`). TRÊS venenos garantem o prompt mesmo com as regras — são sobre o comando ser **composto/opaco**, não sobre a ferramenta, então o wildcard por ferramenta não os cura: (1) **pipe** (`| tail`, `| grep`, `| head`) ou **redirect** (`2>&1`, `> arquivo`) ou string **multi-linha** num bloco único — vários comandos/operadores de shell juntos NÃO casam com um padrão do allow-list. Cuidado com o reflexo de anexar `2>&1` a probe de versão (`java -version`, que escreve no stderr): o bare já casa `java *` **e** o harness captura o stderr — o redirect só quebra o match; (2) **substituição de comando** `$(...)`/backticks (ex. `git log ...$(git describe)..HEAD`) — o matcher desconfia de `$(...)` por princípio; (3) **inspecionar arquivo por shell** (`sed`/`grep`/`cat`/`rtk grep`/`cd`). Pegue o valor num passo (ex. a última tag) e use **literal** no próximo, em vez de `$(...)`. **No Windows nativo, mais DOIS venenos** (ferramenta PowerShell): (5) **prefixo de env inline** — `$env:JAVA_HOME='...'; .\gradlew.bat check` é comando **composto** e nunca casa com regra de prefixo. A cura é **estrutural**, não de allowlist: declare `"env": { "JAVA_HOME": "" }` no `.claude/settings.local.json` do repo — o comando volta a ser simples e casável. Toda máquina Windows com JDK default ≠ baseline do projeto cai nisso; (6) **sufixo `; echo "EXIT=$LASTEXITCODE"`** — composto pelo mesmo motivo, e desnecessário: o harness já reporta o exit code; o sufixo só quebra o match. **Inspeção de arquivo = ferramenta `Read`, NUNCA shell.** Ler `VERSION`, ler/conferir o `CHANGELOG.md` (a seção `[Unreleased]`, o rodapé de links) e ver o diff é tudo pela ferramenta **`Read`** (ou `git diff`, que é `git` puro) — **nada** de `sed -n`/`grep`/ `cat`/`rtk grep`/`| head`. Foi exatamente uma inspeção com pipe (`sed … | grep`, `rtk grep … | head`) que disparou o único prompt de um release; o `Read` não precisa de allow-list e não pede confirmação. ## Particularidades deste projeto **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** (verde local, vermelho CI, tag no ar). **Rode em paridade Linux** antes de taggar: `docker run --rm -v "":/w -w /w ci-java: ./gradlew check` (mesmo ambiente da CI; `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**): `docker build -t :pre .` Nada mais exercita o `Dockerfile` antes do deploy — o `ci.yml` **não** builda imagem e o Coolify builda o Dockerfile do repo, então sem este gate o primeiro a descobrir que ele falta ou quebrou é a **produção** (constituição §3). **Sem daemon Docker na máquina** → degradado: confira que `Dockerfile` e `.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 o shebang `#!/bin/sh\r`) — cura na raiz: `.gitattributes` com `gradlew text eol=lf` (template `gitattributes-java` do central), não `dos2unix` na mão **nem** `git archive … | docker build -` (pipe é veneno de prompt, o PowerShell 5.1 corrompe stream binário no pipe, e buildaria o HEAD em vez da árvore que o release vai commitar). **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** e não é cosmético: o default do `dart format` é **gravar em disco**, então o gate *conserta* o que deveria só acusar — a 2ª rodada fica **verde**, o vermelho parece transitório, a correção fica **não-commitada** (o `git add` do passo 4 leva só manifesto + CHANGELOG) e o CI, que faz checkout limpo da tag, 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`** (pin de toolchain): prefixe `fvm` — `fvm dart format …`, `fvm flutter test`. Dentro do container `ci-flutter:` o SDK está no PATH e o prefixo **não** se usa; por isso os comandos acima são *bare*. **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):** - **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): não há gate de código separado — o gate do repo é o de docs (pré-flight, passo 1). **Docker Compose (serviço self-hosted, ex. PowerSync):** - **Fonte de versão**: como a stack de código do repo, se houver (Java/Node/…); um repo só de `compose.yaml` + config usa `VERSION` na raiz (SemVer puro), igual à stack sem manifesto próprio. - **Gate de container = SUBIR a stack, não só buildar.** `docker build` prova que a **imagem compila**; **não** roda bootstrap (init container, migração, load de sync rules) nem healthcheck — que só disparam no `up`. Bug de bootstrap/healthcheck passa **verde** no build e morre no **deploy**: o primeiro a rodar a stack de verdade é o **Coolify, em produção** (constituição §3). Gate: - Suba a stack **efêmera, volume novo**, e espere os healthchecks (a constituição §5 já os torna **obrigatórios**): `docker compose -p -preflight up -d --wait` (chamada Bash isolada, sem pipe). O `--wait` sai **≠0** se algum serviço fica *unhealthy* ou um container de bootstrap sai com erro. O nome de projeto próprio (`-p`) dá rede/volume isolados → volume novo a cada rodada. - **Sempre derrube** depois, removendo os volumes: `docker compose -p -preflight down -v`. - **Repo que PULLA a imagem** (só `image:` no compose, sem `Dockerfile` próprio) → o compose-up **substitui** o `docker build` (não há o que buildar; o build gate **some** do relatório). **Repo que builda E compõe** → compose-up **soma** ao `docker build` (build prova que compila, up prova que sobe). O skill escolhe pela presença de `Dockerfile`. - **Vermelho (bloqueador)**: a stack **subiu** e um healthcheck reprovou / um container de bootstrap saiu ≠0 — bug de deploy, igual aos outros gates. - **Degradado (não-vermelho, DECLARA no relatório)**: sem daemon Docker; **ou** o `up` nem começou por **falta de `.env`/segredo local** ou **colisão de porta de host** — o `-p` isola rede/volume, **não** a porta publicada no `ports:` do yaml (pare a stack dev viva ou rode noutra máquina; o `--wait` casa healthcheck **interno**, não precisa da porta publicada). Isso é **ambiente, não bug do app**; distinga pela saída (bind/`env not set` = degradado; container que *subiu* e ficou unhealthy = vermelho). Meio gate é decisão declarada, não silêncio. **Comum a todos:** - **Hosted em**: `https://fonte.xadm.biz/xadm/.git` (Forgejo, compare URL `/compare/v...v`). - **Deploy**: Coolify, gatilho = push em master (a tag é o marco; app **servidor** deploya por push — [versionamento](https://docs.xadm.biz/padroes/versionamento/)). - **App que distribui ARTEFATO** (jar/CLI/worker): o marco é a **Release do Forgejo** (tag + notas do CHANGELOG + **asset anexado**), criada pelo `release.yml` (bloco opt-in). O operador **baixa o jar da aba Releases** — não recebe cópia manual. Pós-release: conferir que a Release apareceu com o asset ([versionamento](https://docs.xadm.biz/padroes/versionamento/)). - **Pós-release**: ## Fluxo ### 1. Pré-flight **Cada comando numa chamada Bash SEPARADA** (podem ser paralelas) — **nunca** num bloco multi-linha (bloco multi-linha é veneno: pede prompt mesmo com tudo no allow-list). Com o allow-list por ferramenta (`git *`) flag antes do subcomando já não importa; ainda assim prefira `git` puro (em chamada não-interativa o git já não pagina). - `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**. O `ci.yml` roda *análise estática + testes*, e a parte de **lint/estilo** (checkstyle, `flutter analyze`) **não é coberta pela análise estática que você faz lendo o código**: ela só dispara dentro do gate, então escapa até o push da tag e deixa o CI vermelho com a tag já criada. Vermelho = **bloqueador**, igual aos gates de docs — não taggar. Se rodar o comando **degradado** (ver Particularidades), isso **não** é vermelho, mas **entra no relatório final** como gate degradado — pular metade do gate é decisão declarada, não silêncio. - **Gate de CONTAINER ANTES de taggar (só app que deploya)** — o comando está no bloco da **sua** stack em *Particularidades*. O `Dockerfile` é o único artefato do repo que **nenhum CI toca**: o `ci.yml` não builda imagem e o Coolify o builda direto do Git, em produção. Vermelho = **bloqueador**. Sem daemon Docker → **degradado** (só conferir que os arquivos existem), que **não** é vermelho mas **entra no relatório final** — meio gate é decisão declarada, não silêncio. **Stack Docker Compose (serviço self-hosted, ex. PowerSync):** o gate de container **não** é `docker build` — o `build` não roda bootstrap nem healthcheck; suba a stack efêmera (`docker compose … up -d --wait` + `down -v`). Ver o bloco *Docker Compose* em *Particularidades* (substitui o build se a imagem é pull; soma se o repo builda). - **Gate de DOCS ANTES de taggar** (o deploy é por push; se o gate do CI falhar, a tag já foi pushada e o **deploy trava sem ninguém ver**): rode o gate de docs que o CI roda mas que não é coberto pela análise estática local. `node scripts/lint-mermaid.mjs docs/` (o `mkdocs build --strict` **não** parseia Mermaid; precisa `npm i --no-save mermaid@11 jsdom`) + `gera-manifesto.py --check` + `valida-frontmatter.py docs/` — e, **se o repo os tiver** (central), `checa-dogfood.py` + `checa-export-download.py` + `checa-nav.py` + `testa-valida-frontmatter.py` + `testa-checa-nav.py` + `testa-checa-views.py` + `testa-checa-rotas.py` + `checa-admonition.py` (depois do build). **E o BUILD de docs que o `docs.yml` roda** — `mkdocs build --strict` (com os hooks) + `javadoc`/`dartdoc` se o app gera: um **gate de infra vermelho** (ex. Testcontainers/dind) **mascara os gates seguintes** (javadoc, mkdocs) no CI, então rode-os **aqui** pra não descobrir em prod atrás do vermelho de infra. Rode **todos** os checks que o CI do repo roda e que a análise estática local não cobre (o conjunto varia por repo). Qualquer um vermelho = **bloqueador**. - **Gate da baseline da fábrica (só app Java/Flutter que declara `toolchain`).** O `container:` do CI é `ci-:`; se a versão **não estiver homologada** na fábrica, a imagem nunca foi buildada e o CI quebra com **"manifest unknown"** — descoberto só aqui, com a tag já pushada e o deploy travado. Confira **antes de taggar**: leia `docs/app.json` (`toolchain.java`/ `toolchain.flutter`) e, se houver, o `.fvmrc` (campo `flutter`) pela ferramenta **`Read`**; baixe a baseline com `curl -fsSL https://docs.xadm.biz/toolchain/matriz-baseline.json` (chamada Bash isolada, sem pipe). Compare, no seu contexto (sem `grep`/`jq`): - versão declarada **∈** a lista da stack na baseline (ex. `toolchain.flutter` ∈ `.flutter`)? Não → **bloqueador**: *"flutter não homologada na fábrica — abra PR em `ci-images/matriz-baseline.json` no repo central, espere a fábrica buildar a imagem, e só então libere. Ver decisão 0003 / runbook fábrica-imagens-ci."* Não taggar. - `.fvmrc` (se existe) **==** `toolchain.flutter`? Divergência → **bloqueador** (drift de fonte; o `container:` segue o `.fvmrc`, mas a fábrica homologa pelo declarado). Reconcilie antes. - Baseline **inalcançável** (rede/404 — ex. central ainda não redeployou publicando a baseline) → **avisar e seguir** (não bloquear release por infra); registre o aviso no relatório final. - **Aviso do bloco Release do Forgejo (soft — só app que distribui artefato).** Se o repo tem `.forgejo/workflows/release.yml`, leia-o pela ferramenta **`Read`** e procure DOIS marcadores literais do template canônico: - `# - name: Publicar Release no Forgejo` (bloco de asset comentado); - `# contents: write` (permissions comentado — sem isso o POST de Release dá **403**, antes do 422). Se **algum** dos dois aparece **comentado** no arquivo, ao final do release **avise** (não bloqueie): *"release.yml tem o bloco 'Publicar Release' comentado (asset / permissions). Se este app distribui artefato (jar/CLI/worker), descomente ANTES de push da tag — senão `valida-release.py` passa verde e a aba Releases fica **vazia**, sem download. App só-deploya (Coolify) ou doc-only: ignore este aviso."* Registre no **Relatório final** (passo 10). Sem `release.yml` no repo → **skip silencioso** (release manual/sem CI de tag). O aviso é soft porque o pré-flight não tem sinal em `app.json` de "distribui artefato" — quem sabe é o dev; o gap que o aviso fecha é *silêncio* (release verde + Releases vazia é descoberto pelo operador na hora do download; item 95 fechou o irmão barulhento — descomentar o bloco sem trocar `container:`). **Worktree limpo com commits à frente do origin é o caso NORMAL — não investigue.** A IA não commita (REGRA Nº 2): o conteúdo que ela editou nesta sessão é commitado **pelo usuário**, então ao iniciar o release o esperado é worktree **limpo** e `master` alguns commits **à frente** do remoto. Isso **não** é violação nem anomalia: worktree limpo → **assuma que o usuário já commitou e siga**. Não audite a autoria dos commits à frente nem pare para explicá-los — o que importa é o intervalo última-tag..HEAD (passo 2), não quem commitou. (Só o passo 2 vazio — nada entre a tag e HEAD — encerra o release sem nada a liberar.) **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` e ≠ `main` — perguntar se prossegue mesmo assim. - Tag já existe localmente OU remotamente para a versão calculada — abortar. ### 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** (app novo / nunca rodou `/xadm-setup`) → **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; só garante que ninguém esquece o setup (constituição §7 / [Central de Apps](https://docs.xadm.biz/documentacao/central-de-apps/)). ### 2. Listar commits desde a última release ``` git log --pretty=format:'%h %s' ..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). ### 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`). ### 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): ... Sugestão de bump: → v ``` `AskUserQuestion`: - header: "Bump" - question: "Aplicar bump para v?" - options: - "Sim, v" — 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`** (não por `sed`/`grep`/pipe) 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** (constituição §1.8), nos nomes da tradução do Keep a Changelog: Adicionado / Alterado / Corrigido / Removido. **Exceção**: `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). **Referências no CHANGELOG = texto puro ou URL absoluta, NUNCA link relativo `docs/…`.** O `CHANGELOG.md` é **embutido em `docs/`** via snippet (`pymdownx.snippets`), então um `[texto](docs/…)` (que fica certo no Forgejo) vira `docs/docs/…` no mkdocs e **quebra o `--strict`**. Cite decisão/ página como **`` `docs/decisoes/NNNN-*.md` ``** (texto puro) ou `https://docs.xadm.biz/…` (URL absoluta). Mostrar o rascunho e perguntar via `AskUserQuestion`: - header: "CHANGELOG" - options: "Sim, aplicar" / "Editar antes" (ajustes inline, re-mostrar) / "Pular CHANGELOG" (só bump+tag). ### 6. Aplicar alterações nos arquivos 1. **Manifesto**: gravar a versão nova (no Flutter, também `+N+1`). 2. **`CHANGELOG.md`**: - seção `## [] - AAAA-MM-DD` com as entradas; - `## [Unreleased]` limpa para o próximo ciclo; - links do rodapé atualizados (mantendo os anteriores): ``` [Unreleased]: https://fonte.xadm.biz/xadm//compare/v...HEAD []: https://fonte.xadm.biz/xadm//compare/v...v ``` Primeira release (sem ``): ``` []: https://fonte.xadm.biz/xadm//releases/tag/v ``` ### 7. Mostrar diff e confirmar `git diff --stat` + `git diff` dos arquivos modificados. `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 **Guarda final (último passo antes do commit) — só repo com manifesto (central).** Rode `gera-manifesto.py --check` **agora**, depois de §6 já ter aplicado bump/ manifesto/CHANGELOG. O `--check` do pré-flight (§1) rodou **antes** dessas mudanças; este re-check garante que o manifesto a ser committado reflete o working-tree **final** — fecha a race "carimba→edita→commita" que deixou um drift subir no 0.26.1 (o `--update` carimbou um estado que não virou o commit, e o CI não-gating não barrou). Vermelho aqui = **NÃO commitar**: rode `gera-manifesto.py --update`, reconfira, e só então prossiga. Modo ghost — sem Co-Authored-By: ```bash git add CHANGELOG.md git commit -m "chore(release): v" ``` A mensagem é **literalmente** `chore(release): v` — sem corpo, sem co-author, sem assinatura. Tag anotada com resumo de **UMA linha** (a tag é só o marco; o detalhe mora no CHANGELOG). Mensagem de uma linha **de propósito**: uma tag multilinha é o veneno de prompt do passo 147 (a string com `\n` não casa nenhuma regra de prefixo, e a tag era a última exceção que ainda pedia autorização) — resumo numa linha casa `git tag *` e roda sem prompt: ```bash git tag -a v -m "v — " ``` **Não** adicionar Co-Authored-By na tag também. ### 9. Push (perguntar antes) `AskUserQuestion`: - header: "Push?" - options: "Sim, push" (`git push origin ` e `git push origin v`) / "Não, deixar local". ### 10. Relatório final ``` Release v concluído. Anterior: v (ou "primeira release") Atual: v Branch: master Tag: v (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 (só CI Linux, pós-tag); ou: container DEGRADADO — Dockerfile/.dockerignore existem, build não rodou (sem Docker); ou: container (compose) DEGRADADO — compose.yaml+healthcheck existem, stack não subiu (sem Docker / falta .env / porta em uso); ou: baseline da fábrica inalcançável — não verificada) Avisos: (só quando aplicável — ver pré-flight) - release.yml: bloco 'Publicar Release' comentado (asset / permissions). Se este app distribui artefato, descomente antes do próximo push de tag. - CI-verde é AVISO, não gate: a CI roda pós-push (deploy é por push; artefato por tag). Confirme a run verde em fonte.xadm.biz/xadm//actions antes de dar o release por sólido — vermelho pós-tag trava o deploy do próximo push / deixa a Release sem asset. Vale DOBRADO se houve "código CEGO" acima (o teste OS-desabilitado só roda lá). Próximos passos (sugestão): 1. Acompanhar o deploy do Coolify. 2. ``` ## 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 `.forgejo/workflows/release.yml` do app, que roda o `valida-release.py` em push de tag (pega tag fora-de-banda ou bug da skill) — não confundir com o `ci.yml`, que é o gate de qualidade (lint + testes). Detalhes: [versionamento](https://docs.xadm.biz/padroes/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. - **Erro de push**: manter commit/tag locais, reportar, sugerir push manual. - **Versão do manifesto já diferente do esperado** (bump manual): usar a do arquivo como base e perguntar antes de prosseguir.