@fontdata/ai-harness 3.3.0 → 4.0.0

package/templates/skills/evoluir-harness/references/versao.md

@@ -0,0 +1,70 @@
+# Referência — versao
+
+Gera o `.ai-harness/versao.json`, que diz ao `/versao` e ao `/publicar-release` onde a versão do projeto mora, como
+ela é formatada e o que nunca pode ser tocado. O contrato completo está em `docs/contratos/VERSAO.md` do pacote; o
+guia com exemplos por stack e a migração das cópias customizadas, em `docs/guias/versao.md`.
+
+Use quando:
+
+- o projeto ainda não tem `versao.json` e a detecção automática erra ou fica incompleta;
+- existe uma cópia customizada do `/versao` em `.claude/commands/versao.md` (o `doctor` acusa
+  `comando-customizado-defasado` ou `arquivo-modificado` nesse arquivo).
+
+## Leitura
+
+1. Rode `npx @fontdata/ai-harness versao detectar --json` e guarde `fontes`, `divergencias`, `problemas`, `tagBase`
+   e o `versaoJson` proposto. Ele é o ponto de partida, não a resposta final: a detecção não sabe quais arquivos o
+   projeto deixou de manter.
+2. Leia `.claude/commands/versao.md`. Se o `lock` em `.ai-harness/` mostra que ele foi alterado localmente, é uma
+   cópia customizada: tudo o que ela ensina ao agente vira campo do `versao.json` ou regra de texto do projeto.
+3. Confira as últimas tags (`git tag --sort=-creatordate | head`) e os últimos commits de versão
+   (`git log --format=%s | grep -i -m 5 'release\|versão'`).
+
+## O que extrair da cópia customizada
+
+| A cópia diz | Campo do `versao.json` |
+|---|---|
+| arquivo e campo onde a versão é gravada (`.dproj`, `app.json` `expo.version`, constante em `.ts`) | `arquivos[]` com `caminho` e `extrator` (`dproj`, `json:<caminho>`, `regex` com `padrao`, `versoes-txt`...) |
+| tag consultada no `git describe --match` (`V*`, `v*`, `<app>-v*`) | `tag`: `V{versao}`, `v{versao}`, `{app}-v{versao}` |
+| quantidade de números e zeros à esquerda (`5.000.05.01` × `5.0.5.1`) | `segmentos` e `formato` na raiz; `formato` por arquivo quando a representação difere |
+| tipo padrão do argumento (`default: build`) | `bump.padrao` |
+| versão por app, commits filtrados por pasta | `apps{}` com `caminhos`, `arquivos`, `changelogs` e, se preciso, `tag` própria |
+| arquivos de changelog atualizados | `changelogs` (na raiz ou no app) |
+| script que regenera arquivo derivado da versão | `gerador` |
+| "nunca alterar" (`package.json` do app, `versionCode`, `buildNumber`, `runtimeVersion`, `.dproj` que não é fonte) | `naoTocar`: caminho de arquivo ou nome de campo `json:` |
+| mensagem do commit de versão | `commit`, com `{versao}` e `{app}` |
+| testes, lint ou compilação antes do commit | `validar`: o comando, ou `"ide"` no Delphi |
+
+Fica fora do `versao.json` o que é **texto**: redação do `Versoes.txt` (particípio sem artigo, ordem novidades →
+correções), estilo do changelog amigável, regra de bump que depende de pasta alterada, aviso de loja. Isso vai para
+uma rule do projeto (`references/rule.md`), com `origem: "evoluir-harness"`. O resto da cópia (greps de
+verificação, checklist do `.dproj`, BOM/CRLF, "não dar push") já é coberto pela CLI e pelo `/versao` do pacote:
+não copie.
+
+## Validar
+
+1. Grave o arquivo proposto (depois do GATE) e rode `npx @fontdata/ai-harness versao detectar`.
+2. O resultado precisa listar só as fontes declaradas, a versão atual igual à da última tag (ou à do `Versoes.txt`)
+   e nenhum item em `Problemas`. Divergência é aceitável só quando é a que o `aplicar` vai corrigir (ex.: grupo
+   `Base` do `.dproj` parado em `1.0.0.0`); explique cada uma ao usuário.
+3. Confira o cálculo com `npx @fontdata/ai-harness versao calcular` e o que seria gravado com
+   `npx @fontdata/ai-harness versao aplicar <próxima> --dry-run`. Nunca rode `aplicar` sem `--dry-run` aqui: o bump
+   é do `/versao`.
+4. Monorepo: repita com `--app <nome>` para cada app.
+
+## Restaurar o comando
+
+Com o `versao.json` validado e a rule de texto gravada, a cópia customizada deixa de ser necessária:
+
+1. `npx @fontdata/ai-harness update --check` lista os conflitos. Se o único for `.claude/commands/versao.md`, rode
+   `npx @fontdata/ai-harness update --yes --forcar`.
+2. Se houver outros arquivos em conflito que o projeto quer manter, restaure só o comando:
+   `npx @fontdata/ai-harness init --comandos versao --sem-harness --conflito sobrescrever --yes`.
+3. Rode `npx @fontdata/ai-harness doctor` e confirme que `comando-customizado-defasado` sumiu para o `versao.md`.
+
+## Contra-exemplos
+
+- Copiar o `versaoJson` proposto sem revisar: a detecção inclui `package.json` de app Expo e `.dproj` que o
+  projeto não mantém.
+- Declarar como fonte um arquivo que a cópia manda nunca tocar; ele vai para `naoTocar`.
+- Manter a cópia customizada "por garantia" depois do `versao.json`: ela continua presa no template antigo.