@fontdata/ai-harness 3.3.1 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,70 @@
1
+ # Referência — versao
2
+
3
+ Gera o `.ai-harness/versao.json`, que diz ao `/versao` e ao `/publicar-release` onde a versão do projeto mora, como
4
+ ela é formatada e o que nunca pode ser tocado. O contrato completo está em `docs/contratos/VERSAO.md` do pacote; o
5
+ guia com exemplos por stack e a migração das cópias customizadas, em `docs/guias/versao.md`.
6
+
7
+ Use quando:
8
+
9
+ - o projeto ainda não tem `versao.json` e a detecção automática erra ou fica incompleta;
10
+ - existe uma cópia customizada do `/versao` em `.claude/commands/versao.md` (o `doctor` acusa
11
+ `comando-customizado-defasado` ou `arquivo-modificado` nesse arquivo).
12
+
13
+ ## Leitura
14
+
15
+ 1. Rode `npx @fontdata/ai-harness versao detectar --json` e guarde `fontes`, `divergencias`, `problemas`, `tagBase`
16
+ e o `versaoJson` proposto. Ele é o ponto de partida, não a resposta final: a detecção não sabe quais arquivos o
17
+ projeto deixou de manter.
18
+ 2. Leia `.claude/commands/versao.md`. Se o `lock` em `.ai-harness/` mostra que ele foi alterado localmente, é uma
19
+ cópia customizada: tudo o que ela ensina ao agente vira campo do `versao.json` ou regra de texto do projeto.
20
+ 3. Confira as últimas tags (`git tag --sort=-creatordate | head`) e os últimos commits de versão
21
+ (`git log --format=%s | grep -i -m 5 'release\|versão'`).
22
+
23
+ ## O que extrair da cópia customizada
24
+
25
+ | A cópia diz | Campo do `versao.json` |
26
+ |---|---|
27
+ | 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`...) |
28
+ | tag consultada no `git describe --match` (`V*`, `v*`, `<app>-v*`) | `tag`: `V{versao}`, `v{versao}`, `{app}-v{versao}` |
29
+ | 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 |
30
+ | tipo padrão do argumento (`default: build`) | `bump.padrao` |
31
+ | versão por app, commits filtrados por pasta | `apps{}` com `caminhos`, `arquivos`, `changelogs` e, se preciso, `tag` própria |
32
+ | arquivos de changelog atualizados | `changelogs` (na raiz ou no app) |
33
+ | script que regenera arquivo derivado da versão | `gerador` |
34
+ | "nunca alterar" (`package.json` do app, `versionCode`, `buildNumber`, `runtimeVersion`, `.dproj` que não é fonte) | `naoTocar`: caminho de arquivo ou nome de campo `json:` |
35
+ | mensagem do commit de versão | `commit`, com `{versao}` e `{app}` |
36
+ | testes, lint ou compilação antes do commit | `validar`: o comando, ou `"ide"` no Delphi |
37
+
38
+ Fica fora do `versao.json` o que é **texto**: redação do `Versoes.txt` (particípio sem artigo, ordem novidades →
39
+ correções), estilo do changelog amigável, regra de bump que depende de pasta alterada, aviso de loja. Isso vai para
40
+ uma rule do projeto (`references/rule.md`), com `origem: "evoluir-harness"`. O resto da cópia (greps de
41
+ verificação, checklist do `.dproj`, BOM/CRLF, "não dar push") já é coberto pela CLI e pelo `/versao` do pacote:
42
+ não copie.
43
+
44
+ ## Validar
45
+
46
+ 1. Grave o arquivo proposto (depois do GATE) e rode `npx @fontdata/ai-harness versao detectar`.
47
+ 2. O resultado precisa listar só as fontes declaradas, a versão atual igual à da última tag (ou à do `Versoes.txt`)
48
+ e nenhum item em `Problemas`. Divergência é aceitável só quando é a que o `aplicar` vai corrigir (ex.: grupo
49
+ `Base` do `.dproj` parado em `1.0.0.0`); explique cada uma ao usuário.
50
+ 3. Confira o cálculo com `npx @fontdata/ai-harness versao calcular` e o que seria gravado com
51
+ `npx @fontdata/ai-harness versao aplicar <próxima> --dry-run`. Nunca rode `aplicar` sem `--dry-run` aqui: o bump
52
+ é do `/versao`.
53
+ 4. Monorepo: repita com `--app <nome>` para cada app.
54
+
55
+ ## Restaurar o comando
56
+
57
+ Com o `versao.json` validado e a rule de texto gravada, a cópia customizada deixa de ser necessária:
58
+
59
+ 1. `npx @fontdata/ai-harness update --check` lista os conflitos. Se o único for `.claude/commands/versao.md`, rode
60
+ `npx @fontdata/ai-harness update --yes --forcar`.
61
+ 2. Se houver outros arquivos em conflito que o projeto quer manter, restaure só o comando:
62
+ `npx @fontdata/ai-harness init --comandos versao --sem-harness --conflito sobrescrever --yes`.
63
+ 3. Rode `npx @fontdata/ai-harness doctor` e confirme que `comando-customizado-defasado` sumiu para o `versao.md`.
64
+
65
+ ## Contra-exemplos
66
+
67
+ - Copiar o `versaoJson` proposto sem revisar: a detecção inclui `package.json` de app Expo e `.dproj` que o
68
+ projeto não mantém.
69
+ - Declarar como fonte um arquivo que a cópia manda nunca tocar; ele vai para `naoTocar`.
70
+ - Manter a cópia customizada "por garantia" depois do `versao.json`: ela continua presa no template antigo.
@@ -34,7 +34,9 @@ Se o relato não veio, peça os detalhes antes de começar: o que acontece, o qu
34
34
  - plano **condensado** para correção simples, com `auditoria_plano: pendente` (ele não passa pelo
35
35
  `auditor-plano`); plano completo quando houver mais de uma fase, auditado pelo `auditor-plano`, cujo veredito
36
36
  grava `auditoria_plano: aprovado` ou `reprovado`. Não há outros valores.
37
- 3. Registre o início:
37
+ 3. Quando o trabalho registrar uma decisão ou um bloqueio, crie `DECISOES.md` a partir de `templates/DECISOES.md`
38
+ e `BLOQUEIOS.md` a partir de `templates/BLOQUEIOS.md`, sempre com o frontmatter. Nunca os escreva do zero.
39
+ 4. Registre o início:
38
40
 
39
41
  ```bash
40
42
  npx @fontdata/ai-harness evento trabalho_iniciado --trabalho <id> --nome resolver-bug --dados '{"trabalho_tipo":"bug"}'
@@ -0,0 +1,30 @@
1
+ ---
2
+ schema_versao: 1
3
+ tipo: bloqueios
4
+ id: "{{id}}"
5
+ trabalho_tipo: bug
6
+ titulo: "Bloqueios — {{titulo}}"
7
+ status: aberto
8
+ criado_em: "{{data}}"
9
+ atualizado_em: "{{data}}"
10
+ arquivos: []
11
+ bloqueios:
12
+ - id: B-01
13
+ task: T-01.02
14
+ status: aberto
15
+ aberto_em: "{{data}}"
16
+ resolvido_em: null
17
+ decisao: null
18
+ ---
19
+
20
+ # Bloqueios — {{titulo}}
21
+
22
+ Dúvidas que pararam uma task durante a correção. Cada bloqueio é resolvido por uma decisão registrada em
23
+ `DECISOES.md`; depois disso, a task volta para `pendente`.
24
+
25
+ ## B-01 — Pergunta objetiva que precisa de resposta
26
+
27
+ - **Task:** T-01.02
28
+ - **Contexto:** o que foi encontrado e por que a task não pode seguir.
29
+ - **Opções:** as alternativas possíveis, com a consequência de cada uma.
30
+ - **O que destrava:** a informação ou a escolha necessária.
@@ -0,0 +1,20 @@
1
+ ---
2
+ schema_versao: 1
3
+ tipo: decisoes
4
+ id: "{{id}}"
5
+ trabalho_tipo: bug
6
+ titulo: "Decisões — {{titulo}}"
7
+ status: ativo
8
+ criado_em: "{{data}}"
9
+ atualizado_em: "{{data}}"
10
+ arquivos: []
11
+ ---
12
+
13
+ # Decisões — {{titulo}}
14
+
15
+ Decisões tomadas durante a investigação e a correção. Uma decisão que muda não é apagada: registre uma nova
16
+ dizendo qual ela substitui.
17
+
18
+ | # | Data | Decisão | Motivo | Alternativas descartadas |
19
+ |---|---|---|---|---|
20
+ | D-01 | {{data}} | Como a causa raiz é corrigida | Por que, com a correção mais conservadora | Que outra correção não foi escolhida |