@fontdata/ai-harness 3.3.0 → 4.0.0

package/dist/versao/git.js

@@ -0,0 +1,91 @@
+import { spawnSync } from 'node:child_process';
+const TIPOS_PATCH = new Set(['fix', 'chore', 'refactor', 'docs', 'style', 'perf', 'test', 'build', 'ci']);
+const SEP_CAMPO = '\x1f';
+const SEP_COMMIT = '\x1e';
+function rodarGit(raiz, args) {
+    const r = spawnSync('git', args, { cwd: raiz, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+    if (r.error)
+        throw new Error(`Não foi possível rodar o git: ${r.error.message}`);
+    if (r.status !== 0)
+        throw new Error(`git ${args.join(' ')} falhou: ${r.stderr.trim()}`);
+    return r.stdout;
+}
+function escaparRegex(texto) {
+    return texto.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function regexDoModelo(modelo, app) {
+    if (modelo.split('{versao}').length !== 2) {
+        throw new Error(`O modelo de tag "${modelo}" precisa ter exatamente um {versao}.`);
+    }
+    if (modelo.includes('{app}') && !app) {
+        throw new Error(`O modelo de tag "${modelo}" usa {app}, mas nenhum app foi informado.`);
+    }
+    const literal = modelo.split('{versao}').map((parte) => escaparRegex(parte.replaceAll('{app}', app ?? '')));
+    return new RegExp(`^${literal[0]}(\\d+(?:\\.\\d+)*)${literal[1]}$`);
+}
+function compararVersoes(a, b) {
+    const sa = a.split('.').map(Number);
+    const sb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(sa.length, sb.length); i++) {
+        const diferenca = (sa[i] ?? 0) - (sb[i] ?? 0);
+        if (diferenca !== 0)
+            return diferenca;
+    }
+    return 0;
+}
+/**
+ * Acha a tag de maior versão alcançável do HEAD que casa com o modelo (ex.: `V{versao}`, `{app}-v{versao}`).
+ * Retags com sufixo `-N` não casam, porque `{versao}` só aceita segmentos numéricos separados por ponto.
+ * Sem tag, a base é o primeiro commit e `primeiroRelease` fica true.
+ */
+export function acharTagBase(raiz, modelo, app) {
+    const regex = regexDoModelo(modelo, app);
+    let melhor = null;
+    for (const tag of rodarGit(raiz, ['tag', '--merged', 'HEAD']).split('\n')) {
+        const versao = regex.exec(tag.trim())?.[1];
+        if (!versao)
+            continue;
+        if (!melhor || compararVersoes(versao, melhor.versao) > 0)
+            melhor = { tag: tag.trim(), versao };
+    }
+    if (melhor)
+        return { ...melhor, base: melhor.tag, primeiroRelease: false };
+    const primeiro = rodarGit(raiz, ['rev-list', '--max-parents=0', 'HEAD']).trim().split('\n').at(-1) ?? '';
+    return { tag: null, versao: null, base: primeiro, primeiroRelease: true };
+}
+/**
+ * Commits de `base..HEAD`, do mais novo ao mais antigo. Com `primeiroRelease`, lista todo o histórico do HEAD,
+ * incluindo o primeiro commit. Com `caminhos`, só os commits que tocam esses caminhos.
+ */
+export function listarCommits(raiz, base, caminhos, primeiroRelease = false) {
+    const intervalo = primeiroRelease ? 'HEAD' : `${base}..HEAD`;
+    const args = ['log', `--format=%H${SEP_CAMPO}%s${SEP_CAMPO}%b${SEP_COMMIT}`, intervalo];
+    if (caminhos?.length)
+        args.push('--', ...caminhos);
+    return rodarGit(raiz, args)
+        .split(SEP_COMMIT)
+        .map((bloco) => bloco.replace(/^\n+/, ''))
+        .filter((bloco) => bloco.trim())
+        .map((bloco) => {
+        const [hash = '', titulo = '', corpo = ''] = bloco.split(SEP_CAMPO);
+        return { hash: hash.trim(), titulo: titulo.trim(), corpo: corpo.trim() };
+    });
+}
+/** `feat` → minor; outro tipo semântico conhecido → patch. Mudança incompatível só gera aviso, nunca major. */
+export function classificarBump(commits) {
+    let tipo = 'nenhum';
+    const avisos = [];
+    for (const commit of commits) {
+        const casamento = /^(\w+)(?:\([^)]*\))?(!)?:/.exec(commit.titulo);
+        const tipoCommit = casamento?.[1]?.toLowerCase();
+        if (tipoCommit === 'feat')
+            tipo = 'minor';
+        else if (tipoCommit && TIPOS_PATCH.has(tipoCommit) && tipo === 'nenhum')
+            tipo = 'patch';
+        if (casamento?.[2] || /^BREAKING[ -]CHANGE:?/m.test(commit.corpo)) {
+            avisos.push(`O commit ${commit.hash.slice(0, 7)} "${commit.titulo}" declara mudança incompatível; ` +
+                'o bump calculado não passa de minor. Se for o caso, peça o major explicitamente.');
+        }
+    }
+    return { tipo, avisos };
+}

package/dist/versao/texto.js

@@ -0,0 +1,16 @@
+import { readFileSync } from 'node:fs';
+/** Lê o arquivo como bytes, sem decodificar; o EOL é o da primeira quebra (LF se não houver). */
+export function lerTexto(caminho) {
+    const conteudo = readFileSync(caminho);
+    const bom = conteudo.length >= 3 && conteudo[0] === 0xef && conteudo[1] === 0xbb && conteudo[2] === 0xbf;
+    const lf = conteudo.indexOf(0x0a);
+    const eol = lf > 0 && conteudo[lf - 1] === 0x0d ? '\r\n' : '\n';
+    return { conteudo, bom, eol };
+}
+/** Troca os bytes [inicio, fim) por `novo` em UTF-8; o resto do buffer sai idêntico. */
+export function substituirTrecho(buffer, inicio, fim, novo) {
+    if (!Number.isInteger(inicio) || !Number.isInteger(fim) || inicio < 0 || fim < inicio || fim > buffer.length) {
+        throw new Error(`intervalo inválido [${inicio}, ${fim}) para buffer de ${buffer.length} bytes`);
+    }
+    return Buffer.concat([buffer.subarray(0, inicio), Buffer.from(novo, 'utf8'), buffer.subarray(fim)]);
+}

package/dist/versao/tipos.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fontdata/ai-harness",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "Harness de engenharia com IA da Fontdata para Claude Code: roda os slash commands direto na pasta do projeto via npx, sem instalar nada — ou instala-os em .claude/commands.",
   "type": "module",
   "bin": {

package/templates/CLAUDE.md

@@ -27,6 +27,7 @@ Comece por `/harness`, que conduz o setup em etapas.
 | `docs/trabalhos/<id>/DECISOES.md` | Decisões tomadas no planejamento e na execução |
 | `docs/trabalhos/<id>/BLOQUEIOS.md` | Dúvidas que pararam uma task |
 | `docs/trabalhos/<id>/relatorios/TECNICO.md` e `relatorios/CLIENTE.md` | Relatório para engenharia e para cliente e suporte (sem jargão) |
+| `docs/trabalhos/<id>/<id>.sql` | Script SQL entregável do trabalho, opcional (`<id>-<sufixo>.sql` se houver mais de um); apoio vai em `anexos/` |
 | `docs/eventos/<id>.jsonl` | Rastro de eventos (não versionado por padrão) |
 | `.ai-harness/` | Lock da instalação e configuração dos hooks (versionar) |
 

package/templates/catalog.json

@@ -79,7 +79,8 @@
       "title": "Utilitário",
       "commands": [
         { "id": "git-commit-push", "file": "commands/git-commit-push.md", "title": "/git-commit-push", "description": "Gera mensagem e executa git add/commit/push em PT-BR.", "recommended": true },
-        { "id": "versao", "file": "commands/versao.md", "title": "/versao", "description": "Detecta o versionamento do projeto (qualquer stack) e aplica o bump de versão + changelog (autossuficiente), com gate de aprovação e sem push.", "recommended": true },
+        { "id": "versao", "file": "commands/versao.md", "title": "/versao", "description": "Detecta as fontes de versão do projeto (qualquer stack) pela CLI `ai-harness versao` e pelo `.ai-harness/versao.json` e aplica o bump de versão + changelog, com gate de aprovação e sem push.", "recommended": true },
+        { "id": "publicar-release", "file": "commands/publicar-release.md", "title": "/publicar-release", "description": "Depois do /versao, cria a tag pelo modelo do versao.json (exceto com auto-tag), faz o push após confirmação e cria o GitHub Release com notas geradas.", "recommended": false },
         { "id": "revisar-pr", "file": "commands/revisar-pr.md", "title": "/revisar-pr", "description": "Revisa um PR ou o diff atual em BLOQUEANTE/IMPORTANTE/SUGESTÃO e, se pedido, organiza as correções num trabalho com teste de regressão.", "recommended": false, "replaces": ["corrigir-review"] }
       ]
     }

package/templates/commands/publicar-release.md

@@ -0,0 +1,93 @@
+---
+description: Publica no GitHub a versão que o /versao acabou de gerar — tag, push e release com notas geradas. Opcional; roda depois do /versao.
+argument-hint: "[--app <nome>]"
+---
+
+# /publicar-release — Tag, push e GitHub Release
+
+Você publica a versão que o `/versao` acabou de commitar: cria a tag (quando o projeto não tem auto-tag), envia o
+commit e a tag ao remoto e cria o GitHub Release. **O bump não é feito aqui**: versão, arquivos e changelog são do
+`/versao`. Publicações em npm, lojas ou servidores seguem pelos workflows do próprio projeto.
+
+> **🚦 Há um GATE de confirmação obrigatório antes do push (Passo 4).** Nada vai para o remoto sem o "sim" do
+> usuário.
+
+## Uso
+
+- `/publicar-release` — publica a versão do HEAD.
+- `/publicar-release --app <nome>` — em monorepo, publica a versão do app indicado.
+
+Argumento recebido: $ARGUMENTS
+
+## Passo 0 — Pré-checagens (somente leitura; abortar se alguma falhar)
+
+1. **Árvore limpa:** `git status --short` sem saída. Se houver mudança, pare e sugira `/git-commit-push`.
+2. **Branch e remoto:** `git branch --show-current` (pare se o HEAD estiver destacado) e `git fetch --tags`.
+   Compare com o upstream (`git rev-list --left-right --count @{u}...HEAD`): se estiver **atrás** ou divergente,
+   pare e avise. Estar à frente só pelo commit de release é o esperado.
+3. **GitHub CLI:** `gh auth status`. Sem autenticação, pare e peça para o usuário rodar `gh auth login`.
+
+## Passo 1 — Ler a versão e o modelo da tag (somente leitura)
+
+Rode `npx @fontdata/ai-harness versao detectar --json` (com `--app <nome>` se ele veio em `$ARGUMENTS`). Do JSON,
+use `versaoAtual`, `tag` (o modelo, ex.: `v{versao}` ou `{app}-v{versao}`), `fontes`, `divergencias` e `problemas`.
+
+- `ok: false`, `problemas` não vazio ou `divergencias` não vazio: pare, mostre o que veio e sugira o `/versao`.
+- `apps` não vazio e sem `--app`: pare e pergunte qual app publicar.
+- `tag` nulo: pergunte o padrão de tag do projeto (veja `git tag --sort=-creatordate | head`) e sugira gravá-lo no
+  campo `tag` do `.ai-harness/versao.json`.
+
+Nome da tag: troque `{versao}` por `versaoAtual` e `{app}` pelo nome do app. Se a CLI não responder, leia a versão
+nas fontes do `.ai-harness/versao.json` (ou do projeto) e siga o padrão das tags existentes, avisando o usuário.
+
+## Passo 2 — Conferir que o HEAD é o commit de release do `/versao`
+
+1. A tag ainda não existe: `git rev-parse -q --verify "refs/tags/<tag>"` e `git ls-remote --tags origin "<tag>"`
+   sem saída. Se existir, pare: a versão já foi publicada ou o `/versao` não rodou.
+2. O commit do HEAD mudou a versão: `git show --stat HEAD` toca as fontes listadas em `fontes`, e
+   `git log -1 --format=%s` segue o modelo `commit` do `.ai-harness/versao.json` (quando houver) ou cita a versão.
+3. O valor das fontes no HEAD é `versaoAtual` (o `detectar` lê a árvore, que está limpa pelo Passo 0).
+
+Se algum item falhar, pare e explique; o caminho é rodar o `/versao` antes.
+
+## Passo 3 — Tag (só se o projeto não tiver auto-tag)
+
+- Procure `.github/workflows/*auto-tag*`. **Se existir**, não crie a tag: a Action cria quando o commit de release
+  chegar na branch de produção. Avise isso e siga sem tag local.
+- **Senão**, crie a tag anotada local: `git tag -a "<tag>" -m "<tag>"`.
+
+## Passo 4 — 🚦 GATE: confirmar o envio
+
+Mostre e **aguarde confirmação explícita** do usuário:
+
+- branch e remoto de destino;
+- commits que vão subir: `git log --oneline @{u}..HEAD`;
+- tag que vai junto (ou "nenhuma, o auto-tag cria");
+- o release que será criado em seguida.
+
+Sem "sim", pare. Se a tag foi criada no Passo 3 e o usuário desistir, ofereça removê-la com `git tag -d "<tag>"`.
+
+## Passo 5 — Push
+
+`git push --follow-tags` (envia o commit de release e a tag anotada). Se o push for recusado, pare e explique.
+
+## Passo 6 — GitHub Release
+
+- Com tag local: `gh release create "<tag>" --title "<tag>" --generate-notes`.
+- Com auto-tag: espere a tag aparecer no remoto (`git ls-remote --tags origin "<tag>"`, ou acompanhe com
+  `gh run list --workflow <arquivo-do-auto-tag>`) antes de criar o release; se o workflow já cria o release, não
+  crie outro.
+
+## Passo 7 — Resumo
+
+- Link do release (`gh release view "<tag>" --json url -q .url`).
+- Versão publicada, tag e status do push.
+- Lembre que publicações (npm, lojas, deploy) seguem pelos workflows do projeto disparados pela tag ou pelo release;
+  aponte o `gh run list` para acompanhar.
+
+## Guardrails
+
+- Nunca use `--force` em push nem em tag; nunca mova nem apague tag publicada no remoto.
+- Não faça bump: sem `npm`, `dotnet`, `flutter` ou edição de arquivo de versão. Versão errada volta para o `/versao`.
+- Não pule as pré-checagens nem o GATE do Passo 4.
+- Se qualquer comando falhar, pare e explique o erro e o próximo passo; não contorne sozinho.

package/templates/commands/versao.md

@@ -1,87 +1,81 @@
 ---
-description: Detecta como o versionamento funciona no projeto atual (qualquer stack) e aplica o bump de versão + changelog, com gate de aprovação. Para antes do push.
-argument-hint: "[X.Y.Z | major | minor | patch | build]"
+description: Aplica o bump de versão em qualquer stack (Node, Delphi, .NET, Flutter, Python, monorepo) pela CLI versao do ai-harness, gera o changelog amigável e commita, com gate de aprovação. Para antes do push.
+argument-hint: "[X.Y.Z | major | minor | patch | build] [--app <nome>]"
 ---
 
-# /versao — Bump de versão (agnóstico de stack)
+# /versao — Bump de versão sobre a CLI
 
-Você é o **orquestrador de release** deste projeto. Sua tarefa é **descobrir como o versionamento já
-funciona aqui** (React+Vite, React+Next, Node, Delphi, .NET, Flutter, etc.) e **replicar exatamente esse
-padrão** ao aplicar o novo bump. Não imponha um formato seu: o projeto manda.
+Você é o **orquestrador de release** deste projeto. Quem acha e grava a versão é a CLI determinística
+`npx @fontdata/ai-harness versao detectar|calcular|aplicar`, que lê o `.ai-harness/versao.json` quando ele existe e
+detecta as fontes por stack quando não existe. Ela não faz commit, tag nem push e não escreve changelog. A você
+cabe o que exige julgamento: o changelog amigável, o gate, a validação e o commit, sempre no padrão que o projeto
+já usa.
 
-> **🚦 Há um GATE de aprovação obrigatório** antes de qualquer escrita. **PARE antes de `git push`** —
-> push é sempre ação manual do usuário.
+> **🚦 Há um GATE de aprovação obrigatório** antes de qualquer escrita. **PARE antes de `git push`**: push é sempre
+> ação manual do usuário.
 
 ## Uso
 
-- `/versao` — **infere** a próxima versão pelos commits (regra SemVer abaixo) ou pelo padrão do projeto.
-- `/versao X.Y.Z` — usa a versão explícita como **override** (único caminho que permite subir `major`).
-- `/versao major|minor|patch|build` — incrementa o segmento indicado, respeitando o **número de segmentos**
-  que o projeto usa (3 segmentos `X.Y.Z` ou 4 segmentos `X.Y.Z.W`, comum em Delphi/.NET).
+- `/versao`: usa o `bump.padrao` do `versao.json` ou, sem ele, **infere** pelos commits (nunca sobe major).
+- `/versao X.Y.Z`: versão explícita como **override** (único caminho, junto com `major`, que sobe o major).
+- `/versao major|minor|patch|build`: incrementa o segmento indicado, respeitando os segmentos do projeto
+  (`X.Y.Z` ou `X.Y.Z.W`, comum em Delphi/.NET).
+- `--app <nome>`: em monorepo, versiona só aquele app (versão, tag e changelogs próprios).
+
+Todos os comandos da CLI aceitam `--json` e `--app <nome>`. Com `"ok": false` a resposta traz `erro` e o código de
+saída é 1. Se o próprio `npx @fontdata/ai-harness versao` falhar (pacote antigo sem o subcomando, sem rede), siga a
+seção **Sem a CLI** no fim deste arquivo. Erro de conteúdo (ex.: `versao.json` inválido, app inexistente) não é
+motivo para o plano B: mostre o `erro` ao usuário e corrija a causa.
 
 ## Passo 0 — Pré-checagem (abortar se falhar)
 
-1. **Working tree limpo:** rode `git status --short`. Se houver saída → **abortar** e instruir a
-   commitar/limpar antes (sugerir `/git-commit-push`). Não bumpar com árvore suja.
-2. **Base (última versão registrada):** `git describe --tags --abbrev=0 --match "v*"`. Se não houver tag,
-   use o primeiro commit (`git rev-list --max-parents=0 HEAD`) como base e avise que é o primeiro release.
-
-## Passo 1 — Detectar o mecanismo de versionamento (somente leitura)
-
-Investigue o projeto e **identifique TODAS as fontes de verdade da versão**. Não assuma; confirme lendo.
-Possíveis fontes, por stack:
-
-- **Node / React+Vite / React+Next / qualquer JS-TS:** campo `version` em `package.json` (e
-  `package-lock.json`/`pnpm-lock.yaml`/`yarn.lock` se contiverem a versão do pacote raiz).
-- **Delphi:** `*.dproj` (chaves `VerInfo_Keys`, `FileVersion`/`ProductVersion` e os campos
-  `MajorVersion/MinorVersion/Release/Build`) **e** constantes de versão em `.pas` (ex.: `About*`,
-  `BibVariavel`). Liste cada `arquivo:linha`.
-- **.NET / C#:** `*.csproj` (`<Version>`, `<AssemblyVersion>`, `<FileVersion>`), `AssemblyInfo.cs`,
-  `Directory.Build.props`.
-- **Flutter / Dart:** campo `version:` do `pubspec.yaml`.
-- **Python:** `pyproject.toml` (`[project] version` ou `[tool.poetry] version`), `setup.py`,
-  `__version__` em `__init__.py`.
-- **Outras:** procure por arquivos `VERSION`, constantes `VERSION`/`APP_VERSION`, badges no README.
-
-Use `grep`/busca para encontrar **toda ocorrência** do número de versão atual, garantindo que nenhuma
-fique para trás. Determine também:
-
-- O **formato/número de segmentos** vigente (`X.Y.Z` ou `X.Y.Z.W`, com ou sem zero à esquerda).
-- Onde mora o **changelog**, replicando o que existir:
-  - `CHANGELOG.md` (formato Keep a Changelog ou similar);
-  - arquivos de "Novidades" consumidos pela UI (ex.: `src/data/novidades.ts`);
-  - arquivos texto de histórico (ex.: `Versoes.txt` na raiz, com padrão de espaçamento/formatação próprio).
-- Se há **automação de tag** (ex.: `.github/workflows/auto-tag.yml` que cria a tag na `main`). Se houver,
-  não crie a tag, só commite: a Action cria a tag quando o commit chega na branch alvo, e uma tag criada à mão
-  duplica a dela.
-- O **gerenciador de pacotes / runner de testes** do projeto (npm/pnpm/yarn, `dotnet`, etc.), lendo
-  `package.json` scripts ou os manifestos.
-
-> Se não encontrar nenhuma fonte de versão, **pergunte ao usuário** onde a versão deve ser registrada
-> antes de prosseguir.
-
-## Passo 2 — Levantar commits e calcular a nova versão
-
-- `git log <base>..HEAD --pretty=format:%H%x09%s`. Liste ao usuário os commits considerados (título +
-  tipo semântico) e a base usada.
-- **Se veio versão explícita `X.Y.Z`:** assuma exatamente ela (override total).
-- **Se veio um tipo (`major|minor|patch|build`):** incremente esse segmento e zere os à direita,
-  respeitando o número de segmentos do projeto.
-- **Senão, infira por SemVer** (precedência minor > patch, com reset em cascata):
-  1. Algum `feat:` → **minor**: `Y = Y + 1`, demais à direita = `0`.
-  2. Senão, algum `fix:`/`chore:`/`refactor:`/`docs:`/`style:`/`perf:`/`test:` → **patch**.
-  3. Senão → sem bump elegível: avise e **peça confirmação** (abortar ou versão explícita).
-- **`major` é manual** — só sobe quando o usuário passa `X.Y.Z` explícito ou `major`, porque sinaliza quebra de
-  compatibilidade e isso é decisão de quem mantém o projeto. A inferência não sobe major.
+1. **Working tree limpo:** rode `git status --short`. Se houver saída, **aborte** e instrua a commitar ou limpar
+   antes (sugira `/git-commit-push`). Bump com árvore suja mistura no commit de release o que não é release.
+2. **Argumento:** separe a versão ou o tipo de bump e o `--app <nome>`, para repassar à CLI nos passos seguintes.
+
+## Passo 1 — Detectar as fontes da versão (somente leitura)
+
+Rode `npx @fontdata/ai-harness versao detectar --json` (com `--app <nome>` se for o caso) e leia:
+
+- `versaoAtual`, `tag` (modelo da tag, ex.: `v{versao}`, `V{versao}`, `{app}-v{versao}`), `segmentos`, `formato` e
+  `base` (`tag`, `versao`, `primeiroRelease`: sem tag anterior, avise que é o primeiro release);
+- `fontes`: cada `caminho` e `extrator`, com as `ocorrencias` (`linha`, `valor`). Fonte com `somenteLeitura`
+  (ex.: `Versoes.txt`) é lida, não gravada pela CLI; fonte com `naoTocar` nunca é gravada;
+- `apps`: se não estiver vazio e o usuário não passou `--app`, liste os apps com as versões e pergunte qual
+  versionar antes de seguir;
+- `divergencias` e `problemas`: **destaque** cada um. Fontes com versões diferentes precisam de decisão do usuário
+  (qual é a certa) antes do gate; não escolha por conta própria.
+
+**Sem `versao.json` (`origem` é `deteccao`):** mostre o `versaoJson` proposto e explique em uma frase cada campo
+relevante (`arquivos`, `tag`, `bump.padrao`, `changelogs`, `naoTocar`). Ofereça gravá-lo em
+`.ai-harness/versao.json`, que passa a ser a fonte de verdade do projeto. Só grave com aprovação; se o usuário
+ajustar algo, grave a versão ajustada e rode o `detectar` de novo. Se ele recusar, siga com a detecção.
+
+## Passo 2 — Calcular a nova versão, levantar os commits e simular a gravação
+
+Rode `npx @fontdata/ai-harness versao calcular [argumento] --json` repassando o argumento do usuário (`X.Y.Z`,
+`major`, `minor`, `patch` ou `build`) e o `--app`. Leia `versaoAtual`, `proxima`, `tagProxima`, `bump` (`tipo` e
+`origem`: explícito, config ou inferido) e `commits` (`hash`, `titulo`, `corpo`), que já vêm filtrados pelos
+`caminhos` do app em monorepo.
+
+- Mostre a base (`base.tag`), a regra do bump e a lista de commits considerados (título e tipo semântico).
+- Repasse os `avisos` (ex.: `!:`/`BREAKING CHANGE` virou minor, próxima versão não é maior que a atual).
+- **`major` é manual:** a inferência nunca sobe major, porque isso sinaliza quebra de compatibilidade e é decisão
+  de quem mantém o projeto. Se houver commit de quebra, diga isso e ofereça `/versao major` ou `X.Y.Z`.
+- Sem commit elegível ou sem `proxima`: avise e **peça confirmação** (abortar ou versão explícita).
+
+Com a nova versão definida, rode `npx @fontdata/ai-harness versao aplicar <nova> --dry-run --json` (com `--app` se
+for o caso), em que `<nova>` é a `proxima`. Ele não grava nada e devolve, por arquivo, o `diff` que o gate vai
+mostrar. Se vier `problemas` ou alguma fonte com `status` de erro, pare e resolva antes do gate: o `aplicar` real
+não grava nada quando uma fonte falha.
 
 ## Passo 3 — Gerar o changelog (no padrão do projeto)
 
-Este comando é **autossuficiente**: gere aqui mesmo o changelog **amigável ao usuário final** (pt-BR,
-sem hash/arquivo/jargão) a partir dos commits do intervalo **`<base>..HEAD`** (a base do Passo 0), sem
-depender de nenhuma skill ou comando externo. Quem grava os artefatos é o Passo 5.
+Este comando é **autossuficiente**: gere aqui o changelog **amigável ao usuário final** (pt-BR, sem
+hash/arquivo/jargão) a partir dos `commits` do Passo 2, sem depender de skill ou comando externo. A CLI não escreve
+changelog; quem grava os blocos é o Passo 5.
 
-**3.1 — Leia os commits.** Use os commits já levantados no Passo 2 (`git log <base>..HEAD`); leia o corpo
-quando precisar de contexto para entender o que a mudança entrega.
+**3.1 — Leia os commits.** Use o `titulo` e, quando precisar entender o que a mudança entrega, o `corpo`.
 
 **3.2 — Categorize (modo compacto, 3 categorias).** Agrupe mapeando os prefixos semânticos:
 
@@ -89,73 +83,116 @@ quando precisar de contexto para entender o que a mudança entrega.
 - **🐛 Correções** — `fix:`
 - **⚡ Melhorias** — `perf:`/`refactor:`/`chore:`/`style:`/`docs:`/`test:`/`build:`/`ci:`
 
-Mantenha **⚠️ Mudanças importantes** (`BREAKING CHANGE`/`!:` — destaque o que o usuário precisa fazer) e
-**🔒 Segurança** como blocos próprios **só se houver itens**. Commits sem prefixo: classifique pelo
-conteúdo da mensagem. Inclua apenas as seções que tiverem itens.
+Mantenha **⚠️ Mudanças importantes** (`BREAKING CHANGE`/`!:`, destacando o que o usuário precisa fazer) e
+**🔒 Segurança** como blocos próprios **só se houver itens**. Commits sem prefixo: classifique pelo conteúdo da
+mensagem. Inclua apenas as seções que tiverem itens.
 
 **3.3 — Traduza técnico → usuário final.** Para cada item que vai aparecer:
 
-- Reescreva em **linguagem clara e não técnica**, focando no **benefício para quem usa o produto**, não na
-  implementação. Quando fizer sentido, use **negrito com o nome do recurso + frase do ganho**
-  (ex.: `**Sincronização mais rápida**: arquivos sincronizam 2x mais rápido entre dispositivos`).
-- **Filtre o ruído**: descarte merges, bumps triviais de versão, ajustes de lint/formatação e commits
-  puramente internos sem impacto perceptível. O bloco "Melhorias" deve ser um resumo curto, não um
-  despejo de commits. Ignore `docs:`/`chore:` puramente internos quando o projeto assim fizer no histórico.
+- Reescreva em **linguagem clara e não técnica**, focando no **benefício para quem usa o produto**. Quando fizer
+  sentido, use **negrito com o nome do recurso + frase do ganho** (ex.: `**Sincronização mais rápida**: arquivos
+  sincronizam 2x mais rápido entre dispositivos`).
+- **Filtre o ruído**: descarte merges, bumps triviais de versão, ajustes de lint/formatação e commits puramente
+  internos sem impacto perceptível. O bloco "Melhorias" é um resumo curto, não um despejo de commits. Ignore
+  `docs:`/`chore:` puramente internos quando o projeto assim fizer no histórico.
 - Não invente recursos que os commits não suportam; em dúvida, descreva de forma conservadora.
-- **Sem emoji dentro dos itens** — os emojis ficam apenas nos títulos das seções.
+- **Sem emoji dentro dos itens**: os emojis ficam apenas nos títulos das seções.
 
-**3.4 — Siga o estilo do projeto.** Se existir um `CHANGELOG_STYLE.md` na raiz, **siga as diretrizes dele**
-(tom, formato, seções). De todo modo, **replique o formato existente** do arquivo de changelog/novidades/
-`Versoes.txt` do projeto (espaçamento, cabeçalho, formato do número de versão). Não introduza um formato
-novo — o Passo 5 é quem grava, seguindo exatamente esse padrão.
+**3.4 — Siga o estilo do projeto.** Se existir um `CHANGELOG_STYLE.md` na raiz, **siga as diretrizes dele** (tom,
+formato, seções). Prepare um bloco por arquivo de histórico, replicando o formato que já está nele:
+
+- cada caminho de `changelogs` do `versao.json` (do app, em monorepo) e, sem config, o `CHANGELOG.md` e os
+  arquivos de novidades consumidos pela UI (ex.: `src/data/novidades.ts`);
+- `CHANGELOG.md`: nova seção `## [X.Y.Z] - <currentDate>` no topo (após o cabeçalho), no estilo das anteriores;
+- `Versoes.txt` (fonte `versoes-txt`, só leitura na CLI): o bloco que você escreve, com o **mesmo espaçamento**
+  entre blocos, o mesmo cabeçalho e o **mesmo formato de número** (inclusive zeros à esquerda, conforme o
+  `formato`) das entradas existentes;
+- use a data de `currentDate`; **nunca invente data**.
 
 ## Passo 4 — 🚦 GATE de aprovação (obrigatório)
 
 Apresente ao usuário, **antes de escrever qualquer coisa**:
 
-- versão atual → nova versão;
-- a lista completa de **arquivos:linha** que serão alterados (todas as ocorrências do Passo 1);
-- o changelog proposto e **o bloco exato** que será anexado a cada arquivo de histórico.
+- versão atual → nova versão, e a tag que o release terá (`tagProxima`);
+- o **diff exato** de cada arquivo do `aplicar --dry-run` do Passo 2 (`caminho` e, de cada linha do `diff`, o
+  `antes` e o `depois`);
+- o changelog proposto e **o bloco exato** de cada arquivo de histórico (inclusive o do `Versoes.txt`, que o
+  dry-run lista como changelog gravado pelo `/versao`);
+- em destaque: arquivos `.dproj` (o bump mexe em várias chaves de cada configuração e a IDE reescreve o arquivo
+  ao salvar), fontes e campos em `naoTocar` que ficaram de fora, `divergencias` e `avisos`.
 
-**Peça aprovação explícita.** Não grave nada sem o "ok". Se o bump tocar arquivos sensíveis (ex.: `.dproj`,
-`.csproj`), destaque o risco.
+**Peça aprovação explícita.** Não grave nada sem o "ok". Se o usuário pedir outra versão, volte ao Passo 2 com ela.
 
-## Passo 5 — Aplicar artefatos (somente após aprovação)
+## Passo 5 — Aplicar (somente após aprovação)
 
-- Atualize **todas** as ocorrências da versão de forma **consistente** (todas as fontes do Passo 1).
-- Atualize o(s) arquivo(s) de changelog/novidades seguindo **exatamente o padrão existente**:
-  - `CHANGELOG.md`: nova seção `## [X.Y.Z] - <currentDate>` no topo (após o cabeçalho); crie com cabeçalho
-    se não existir.
-  - Arquivo de novidades da UI (se houver): adicione o release no topo do array, no mesmo tipo/formato já
-    usado (datas no formato local do arquivo).
-  - `Versoes.txt`/histórico texto (se houver): anexe ao final, com o **mesmo espaçamento** entre blocos e o
-    **mesmo formato de número** (inclusive zeros à esquerda) das entradas existentes.
-- Use a data de `currentDate`; **nunca invente data**.
+1. Rode `npx @fontdata/ai-harness versao aplicar <nova> --json` (com `--app` se for o caso). Confira que cada
+   arquivo saiu com `gravado: true`; se vier `ok: false` ou `problemas`, pare e reporte: nada foi gravado.
+2. Grave os blocos de changelog aprovados no gate, exatamente como mostrados (Edit, no topo ou no fim conforme o
+   padrão de cada arquivo).
+3. Se o `versao.json` tiver `gerador`, rode o comando para regenerar os arquivos derivados da versão e mostre o
+   que ele alterou (`git status --short`).
 
 ## Passo 6 — Validar (abortar se vermelho)
 
-- Rode os testes do projeto (ex.: `pnpm test`/`npm test`/`dotnet test`). Se fizer sentido para o escopo do
-  release, rode também o build (`pnpm build`/`npm run build`/`dotnet build`).
-- Se algo falhar → **abortar** sem commitar e reportar o erro.
-
-## Passo 7 — Finalizar (somente commit — SEM push)
-
-1. Estagie **apenas** os arquivos do release (nunca `git add -A`): liste explicitamente os arquivos
-   alterados nos passos anteriores.
-2. Commit semântico (1ª letra maiúscula após `: `): `chore: Release vX.Y.Z` (ou, em projetos Delphi que já
-   usem o padrão, `build: Modificada versão do sistema no projeto`). Finalize com a linha
-   `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.
-3. **Tag:** se existir automação de tag (Action na `main`), não crie a tag — informe que ela será criada
-   automaticamente quando o commit chegar na branch alvo. Caso contrário, e somente se o usuário pedir,
-   ofereça criar a tag `v<X.Y.Z>` localmente.
-4. **Pare aqui, sem `git push`.** Informe o fluxo manual de push ao usuário.
+- Com `validar` no `versao.json`, rode exatamente esse comando.
+- Sem `validar`, use o runner detectado no projeto (scripts do `package.json` com npm/pnpm/yarn, `dotnet test`,
+  `flutter test`, `pytest` etc.) e, se fizer sentido para o release, o build.
+- Se `validar` for `"ide"` ou não houver build por linha de comando (Delphi), peça ao usuário que abra o projeto
+  na IDE, compile e confirme que a versão aparece certa, e **aguarde a confirmação** antes de seguir.
+- Se algo falhar, **aborte** sem commitar e reporte o erro.
+
+## Passo 7 — Finalizar (somente commit, sem `git push`)
+
+1. Estagie **apenas** os arquivos do release, listados um a um: os do `aplicar`, os changelogs e o que o
+   `gerador` alterou (e o `.ai-harness/versao.json`, se foi criado no Passo 1). Nunca `git add -A`.
+2. Mensagem: o modelo `commit` do `versao.json` com `{versao}` e `{app}` substituídos; sem ele, o padrão do
+   histórico do projeto (`git log --oneline` dos últimos releases) ou `chore: Release vX.Y.Z`. Commit semântico,
+   com maiúscula após `: `. Finalize com o rodapé `Co-Authored-By` vigente desta sessão, como indicado pelo
+   Claude Code, sem escrever um nome de modelo por conta própria.
+3. **Tag:** se existir automação de tag (ex.: `.github/workflows/auto-tag.yml`), não crie a tag: a Action cria
+   quando o commit chega na branch alvo, e uma tag manual duplicaria a dela. Caso contrário, só se o usuário pedir,
+   crie a tag `tagProxima` localmente.
+4. **Pare aqui, sem `git push`.** Informe o fluxo manual de push e, se o `/publicar-release` estiver instalado em
+   `.claude/commands/`, mencione que ele faz a publicação a partir deste commit.
+
+## Sem a CLI
+
+Use este modo só quando o `npx @fontdata/ai-harness versao` não responder (pacote sem o subcomando, falha de rede).
+Avise o usuário que está no modo manual e siga os mesmos Passos 0, 3, 4, 6 e 7, trocando a CLI pelo que segue.
+
+- **Base:** liste as tags com `git tag --sort=-creatordate` e descubra o modelo do projeto: `v*`, `V*`,
+  `<app>-v*` (monorepo) ou sem prefixo (`1.2.3`). Use a tag mais recente desse modelo, **ignorando retags com
+  sufixo `-N`** (ex.: `v1.2.3-1` é a mesma versão retagueada). Sem tag no modelo, use o primeiro commit
+  (`git rev-list --max-parents=0 HEAD`) e avise que é o primeiro release. Os commits vêm de
+  `git log <base>..HEAD` (em monorepo, filtre pelo caminho do app).
+- **Fontes:** se houver `.ai-harness/versao.json`, ele lista as fontes. Senão, procure por stack: `version` do
+  `package.json` (e do pacote raiz no lock), `.dproj` e constantes em `.pas`, `.csproj`/`AssemblyInfo.cs`/
+  `Directory.Build.props`, `pubspec.yaml`, `pyproject.toml`/`__version__`, arquivo `VERSION`. Busque a versão
+  atual em todo o projeto para não deixar ocorrência para trás e respeite o `naoTocar` (ex.: `versionCode`,
+  `buildNumber`, `runtimeVersion` têm outra numeração).
+- **Cálculo:** versão explícita é override; tipo incrementa o segmento e zera os à direita; sem argumento, `feat:`
+  dá minor, os demais tipos dão patch, e quebra dá minor com aviso (major só explícito).
+- **`.dproj`:** atualize as 3 famílias, coerentes entre si:
+  1. `FileVersion` e `ProductVersion` dentro de **todos** os `VerInfo_Keys`, de todas as configurações;
+  2. `VerInfo_MajorVer`, `VerInfo_MinorVer`, `VerInfo_Release` e `VerInfo_Build` em **cada** `PropertyGroup` que
+     tem `VerInfo_Keys`, criando as chaves que a IDE omitiu (ela não grava valor zero);
+  3. o bloco legado `<VersionInfo>` (`MajorVer`, `MinorVer`, `Release`, `Build`), quando existir.
+
+  No `.dproj` os números são inteiros, sem zero à esquerda. Preserve o BOM e o fim de linha CRLF: use
+  **Edit, nunca Write** em `.dproj`, porque reescrever o arquivo inteiro perde o BOM e converte as quebras de linha.
+- **Verificação pós-aplicação:** busque a versão antiga de novo e confirme que não sobrou ocorrência fora do
+  histórico (changelogs, `Versoes.txt`); em cada `.dproj`, confirme que existe um único valor de `FileVersion` e
+  que ele é a versão nova. Mostre o `git diff --stat` ao usuário.
 
 ## Guardrails
 
 - Sem `git push`: o push publica a versão para todos, e quem decide quando é o usuário. Não criar tag se houver
   automação que já faça isso.
-- **Sempre** confirmar versão + changelog no GATE antes de gravar.
-- **Abortar** se a working tree estiver suja ou se os testes/build falharem.
-- **Replicar o padrão do projeto** (formato de versão, changelog, commit) — nunca impor um novo.
+- **Sempre** mostrar o diff do `aplicar --dry-run`, o changelog e os blocos no GATE antes de gravar.
+- Versão nos arquivos-fonte só pela CLI (ou pelo modo **Sem a CLI** quando ela falhar); não edite à mão o que o
+  `aplicar` grava.
+- **Abortar** se a working tree estiver suja ou se a validação falhar.
+- **Replicar o padrão do projeto** (formato de versão, changelog, commit); nunca impor um novo.
 - `major` só por argumento explícito; a inferência jamais sobe major.
+- Gravar `.ai-harness/versao.json` só com aprovação do usuário.
 - Changelog em **pt-BR**, voltado ao usuário final; usar a data de `currentDate`.

package/templates/rules/comentarios.md

@@ -47,6 +47,7 @@ Se o porquê não cabe em 3 linhas, **ele não pertence ao código**.
 | Task / fase / plano / spec | `PLAN.md` e `SPEC.md` do trabalho em `docs/trabalhos/<id>/` | comentário |
 | Diagnóstico e correção de um defeito | trabalho do tipo `bug` em `docs/trabalhos/<id>/` | comentário |
 | Investigação, medição, auditoria, paridade, comparação | `relatorios/TECNICO.md` do trabalho em `docs/trabalhos/<id>/` | comentário |
+| Script SQL entregável do trabalho (DDL/DML) | raiz do trabalho, `docs/trabalhos/<id>/<id>.sql` | comentário |
 | Documento de apoio do trabalho (imagem, planilha, export, contrato de API) | `anexos/` do trabalho em `docs/trabalhos/<id>/` | comentário |
 | Achado de review | resposta do review, commit | comentário |
 | Decisão de arquitetura | `SPEC.md` | comentário |
@@ -59,7 +60,8 @@ auditoria, paridade com legado, medição, comparação, levantamento, handoff o
 
 Convenção: uma pasta por trabalho, `docs/trabalhos/<yyyy-mm-dd>-<slug>/`. Relatório não ganha nome livre em
 `relatorios/`: o conteúdo vai para `relatorios/TECNICO.md` e o arquivo de apoio para `anexos/`, senão o `doctor`
-avisa `arquivo-fora-do-contrato`.
+avisa `arquivo-fora-do-contrato`. O script SQL do trabalho é entregável, não apoio: fica na raiz como `<id>.sql`
+(ou `<id>-<sufixo>.sql`).
 
 ## Antes e depois
 

package/templates/skills/evoluir-harness/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: evoluir-harness
-description: Cria ou ajusta peças do harness no projeto — agents, skills, rules, hooks, code-reviewer e design system — ou audita a pasta .claude e sugere o que mudar. Use de vez em quando, conforme o projeto cresce.
-argument-hint: "[agent|skill|rule|hook|code-reviewer|design-system|auditar]"
+description: Cria ou ajusta peças do harness no projeto — agents, skills, rules, hooks, code-reviewer, design system e o versao.json do /versao — ou audita a pasta .claude e sugere o que mudar. Use de vez em quando, conforme o projeto cresce.
+argument-hint: "[agent|skill|rule|hook|code-reviewer|design-system|versao|auditar]"
 ---
 
 # Evoluir o harness
@@ -27,6 +27,7 @@ A primeira palavra do pedido é o tipo; o resto é contexto (nome, domínio, URL
 | `hook` | `references/hook.md` | Hooks por agent sobre a biblioteca do harness |
 | `code-reviewer` | `references/code-reviewer.md` | Agent de review somente leitura e o portão extra |
 | `design-system` | a referência `design-system.md` em `references/` | Agent, skill e rules da identidade visual |
+| `versao` | `references/versao.md` | `.ai-harness/versao.json` do `/versao`, inclusive a partir de uma cópia customizada do comando |
 
 Tipo desconhecido: mostre a tabela e pergunte. Não carregue as outras referências.