@fontdata/ai-harness 3.1.2 → 3.2.0

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "fontdata",
-  "version": "3.1.2",
+  "version": "3.2.0",
   "mcpServers": {
-    "banco_dados": { "command": "npx", "args": ["-y", "@fontdata/ai-harness@3.1.2", "banco-dados-mcp"] }
+    "banco_dados": { "command": "npx", "args": ["-y", "@fontdata/ai-harness@3.2.0", "banco-dados-mcp"] }
   },
   "description": "Harness de engenharia com IA da Fontdata para Claude Code",
   "author": { "name": "Fontdata" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fontdata/ai-harness",
-  "version": "3.1.2",
+  "version": "3.2.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

@@ -14,7 +14,7 @@ Comece por `/harness`, que conduz o setup em etapas.
   task; uma task só fecha com suíte verde registrada no rastro.
 - **Quem implementa não aprova.** Os agents `revisor-testes` e `qa`, somente leitura, fazem os gates de cada task.
 - **Orquestração com sub-agents.** Tasks independentes da mesma fase rodam em paralelo; o orquestrador delega, não
-  implementa. **Sempre relatar qual agent está ativo** no chat.
+  implementa. Relatar no chat qual agent está ativo, para o usuário acompanhar a execução.
 
 ## Modelo de arquivos
 
@@ -66,13 +66,16 @@ de tratamento de erro —, mesmo que difira das convenções novas. As convenç
 No dia a dia: `/nova-tarefa`, `/executar-plan`, `/resolver-bug`, `/git-commit-push` e `/versao`. De vez em quando:
 `/sincronizar-claude-md` e `/evoluir-harness`.
 
-## Nunca fazer
+## Limites
 
-- Nunca implementar sem teste escrito antes.
-- Nunca avançar de fase com gate (testes) falhando nem fechar task sem suíte verde.
-- Nunca reescrever `SPEC.md`, `CLAUDE.md` ou planos sem pedido explícito.
-- Nunca usar `git push --force` ou comandos destrutivos sem confirmação.
-- Nunca comentar o passo a passo do código, decorar arquivo com banner de seção, nem escrever
-  task/fase/plano/data/hash de commit dentro de comentário — isso vai na mensagem de commit e em `docs/trabalhos/`.
-  O padrão completo está em `.claude/rules/comentarios.md`, instalada pelo `init`, e o hook de comentários bloqueia
-  a violação.
+Cada limite vem com o motivo, para valer também nos casos que a regra não cita.
+
+- Escrever o teste antes da implementação: só um teste que falhou antes prova que ele pega a implementação errada.
+- Avançar de fase só com o gate verde e fechar task só com suíte verde: uma fase construída sobre outra quebrada
+  esconde a origem do erro.
+- Alterar `SPEC.md`, `CLAUDE.md` e planos só a pedido: são o contrato que o usuário aprovou, e mudança de escopo vira
+  decisão registrada.
+- Pedir confirmação antes de `git push --force` e de comandos destrutivos: eles apagam trabalho que não se recupera.
+- Deixar o código sem comentário de passo a passo, sem banner de seção e sem task/fase/plano/data/hash de commit:
+  isso envelhece no código e já está na mensagem de commit e em `docs/trabalhos/`. O padrão completo está em
+  `.claude/rules/comentarios.md`, instalada pelo `init`, e o hook de comentários bloqueia a violação.

package/templates/agents/auditor-plano.md

@@ -27,7 +27,7 @@ ninguém pergunte nada no meio. Você não edita o plano: aponta o que precisa m
 7. **Tamanho:** cada task cabe numa sessão de trabalho; task grande demais é dividida.
 8. **Legado e riscos:** áreas de código legado tocadas estão identificadas, com o padrão local a preservar.
 
-Use `Bash` só para rodar o `doctor` e ler o histórico: **nunca** altere arquivos, faça commit ou push.
+Use `Bash` só para rodar o `doctor` e ler o histórico: você é somente leitura, então não altere arquivos, faça commit ou push.
 
 ## Saída
 

package/templates/agents/investigador.md

@@ -18,7 +18,7 @@ ou quando ficou claro que ela ainda é hipótese. Você não corrige o bug.
      frontmatter).
 3. **Comprove.** A causa raiz só é `comprovada` quando você mostra a linha ou a condição que produz o sintoma e
    por que a reprodução falha por causa dela. Caso contrário, ela é `hipotese`.
-4. Use `Bash` só para ler, buscar no histórico e reproduzir: **nunca** altere arquivos, instale dependências,
+4. Use `Bash` só para ler, buscar no histórico e reproduzir: você é somente leitura, então não altere arquivos, instale dependências,
    faça commit ou push.
 
 ## Saída

package/templates/agents/qa.md

@@ -22,7 +22,7 @@ Você não corrige nada: se algo falha, você reporta.
 2. Rode a **suíte completa** do projeto, não só os testes da task, com o comando declarado na rule de projeto quando
    houver. Em área de verificação manual, siga o roteiro da rule e colete evidência de cada item.
 3. Confira que nada fora do escopo da task foi alterado (`git diff --stat`).
-4. Use `Bash` só para ler e rodar testes: **nunca** altere arquivos, instale dependências, faça commit ou push.
+4. Use `Bash` só para ler e rodar testes: você é somente leitura, então não altere arquivos, instale dependências, faça commit ou push.
 
 ## Saída
 

package/templates/agents/revisor-testes.md

@@ -1,6 +1,6 @@
 ---
 name: revisor-testes
-description: Revisa os testes de uma task antes de ela fechar, perguntando se cada teste crítico passaria com a implementação errada. Use quando o implementador disser que a task está pronta. Somente leitura; roda a suíte, não edita.
+description: Revisa os testes de uma task antes de ela fechar, perguntando se cada teste crítico passaria com a implementação errada. Use quando o implementador disser que a task está pronta. Somente leitura; roda os testes da task, não edita.
 tools: Read, Grep, Glob, Bash
 model: sonnet
 ---
@@ -22,10 +22,25 @@ comportamento que a task promete.
    - mock que substitui justamente o que deveria ser testado;
    - só o caminho feliz, sem o caso de erro ou de borda que a task menciona;
    - dado de entrada que coincide com o resultado esperado por acaso.
-3. Rode a suíte com o comando declarado em `.claude/rules/harness-projeto.md` ou, sem ele, com o comando de teste
-   do projeto (`npm test`, `dotnet test`, `pytest`...), e anote o resultado. Em área de verificação manual declarada
-   na rule, revise se o roteiro cobre os critérios da task.
-4. Use `Bash` só para ler e rodar testes: **nunca** altere arquivos, instale dependências, faça commit ou push.
+3. Compare cada teste crítico com o texto do plano e com o `git diff`. O implementador é cobrado por suíte verde, e o
+   atalho mais barato é mexer no teste:
+   - teste crítico removido, pulado (`skip`, `only`, `xit`) ou com o valor esperado diferente do plano é
+     **BLOQUEANTE**;
+   - asserção trocada por uma mais fraca do que a que existia antes da task é **BLOQUEANTE**;
+   - código que devolve um valor fixo ou trata como caso especial justamente a entrada do teste, em vez de aplicar a
+     regra, é **BLOQUEANTE**.
+4. Rode só os testes da task (o arquivo ou o filtro que os seleciona), com o comando declarado em
+   `.claude/rules/harness-projeto.md` ou, sem ele, com o comando de teste do projeto (`npm test`, `dotnet test`,
+   `pytest`...), e anote o resultado. A suíte completa é rodada pelo `qa` logo depois. Em área de verificação manual
+   declarada na rule, revise se o roteiro cobre os critérios da task.
+5. Use `Bash` só para ler e rodar testes. Você é somente leitura porque um gate que altera o código deixa de provar
+   alguma coisa: não altere arquivos, não instale dependências, não faça commit nem push.
+
+<example>
+**BLOQUEANTE** — `tests/desconto.test.ts:22`: o plano declara "cupom de 10% sobre R$ 80,00 dá R$ 72,00", mas o
+teste foi trocado para `expect(total).toBeGreaterThan(0)`, que passa com qualquer cálculo. Restaure a asserção do
+valor exato.
+</example>
 
 ## Saída
 

package/templates/commands/sincronizar-claude-md.md

@@ -116,8 +116,8 @@ Não invente o que não surgiu na entrevista; ponto ambíguo fica como "a defini
 - Regra de cobertura: [...]
 - Testes críticos deste projeto: [lista extraída do SPEC]
 
-## Nunca fazer
-- Nunca [proibição específica deste projeto]
+## Limites
+- [O que fazer ou evitar neste projeto]: [o motivo, para valer também nos casos que a regra não cita]
 
 ## Decisões em aberto
 - [ ] [decisão não resolvida no SPEC]

package/templates/commands/versao.md

@@ -52,7 +52,8 @@ fique para trás. Determine também:
   - 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** — apenas commite; a Action cria a tag quando o commit chega na branch alvo.
+  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.
 
@@ -70,8 +71,8 @@ fique para trás. Determine também:
   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` é SEMPRE manual** — só sobe quando o usuário passa `X.Y.Z` explícito ou `major`. A inferência
-  jamais sobe major.
+- **`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.
 
 ## Passo 3 — Gerar o changelog (no padrão do projeto)
 
@@ -144,14 +145,15 @@ Apresente ao usuário, **antes de escrever qualquer coisa**:
 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
+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. Nunca `git push`.** Informe o fluxo manual de push ao usuário.
+4. **Pare aqui, sem `git push`.** Informe o fluxo manual de push ao usuário.
 
 ## Guardrails
 
-- **NUNCA** `git push`. Não criar tag se houver automação que já faça isso.
+- 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.

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

@@ -86,6 +86,10 @@ cada tipo na sua pasta dentro de `docs/`). Hoje cada trabalho mora em `docs/trab
 - **Comentários:** `.claude/rules/comentarios.md` ausente (o `init` e o `update` a instalam); outra rule que repete
   regra de comentário; bloco antigo de comentários no `CLAUDE.md`.
 - Rule com mais de 30 linhas, que repete o `CLAUDE.md`, descreve o que o código já mostra ou contradiz outra rule.
+- **Frontmatter:** rule sem frontmatter, sem `descricao` ou sem `origem` (ver `rule.md`), ou com YAML inválido, que
+  faz o Claude Code ignorar o `paths`. Exceções: `comentarios.md` e `harness-projeto.md`, instaladas pelo `init`.
+- **Rule que já não se paga:** sem `paths` embora trate de uma área só do código, ou nascida de um bug cujo padrão o
+  teste de regressão, um tipo, um lint ou um hook já impede. Proponha escopar, fundir com outra ou apagar.
 - Projeto com código legado sem a rule de precedência do padrão local (ver `rule.md`).
 
 ## 7. Skills e hooks do projeto

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

@@ -27,6 +27,8 @@ Os agents em `.claude/agents/`, o `CLAUDE.md`, o `SPEC.md` e as rules que já ex
 
    ```markdown
    ---
+   descricao: "Convenções do backend: validação de entrada e formato de erro"
+   origem: "evoluir-harness"
    paths:
      - "apps/api/**/*.ts"
    ---
@@ -45,11 +47,20 @@ Os agents em `.claude/agents/`, o `CLAUDE.md`, o `SPEC.md` e as rules que já ex
 
    Identifique as áreas legadas (pastas, extensões como `.pas` e `.dfm`, módulos antigos) e cite-as na rule.
 
-4. **Rule que teria evitado um bug**, quando o `/resolver-bug` sugerir: padrão proibido, validação obrigatória ou
-   teste exigido.
+4. **Rule que teria evitado um bug**, só quando a avaliação do Passo 5 do `/resolver-bug` concluir que ela é
+   necessária: padrão proibido, validação obrigatória ou teste exigido.
 
 ## Cada rule deve
 
+- **Começar com frontmatter**, inclusive a incondicional:
+  - `descricao`: o que a rule evita ou padroniza, em uma linha;
+  - `origem`: o id do trabalho que a motivou (uma lista, se forem vários), ou `evoluir-harness`;
+  - `paths`: os globs, entre aspas, quando a rule vale só para uma área do código.
+
+  O Claude Code só lê `paths` e retira o frontmatter antes de carregar a rule, então `descricao` e `origem` não
+  custam contexto: é por eles que a auditoria sabe por que a rule existe e se ela ainda vale. YAML inválido faz o
+  Claude Code ignorar o frontmatter, e a rule escopada passa a carregar em toda sessão.
+- Ser escopada por `paths` sempre que o assunto se limita a uma área, para não ocupar o contexto das outras.
 - Ser concisa — máximo de 30 linhas.
 - Conter apenas o que o agent não descobriria sozinho lendo o código.
 - Complementar o system prompt do agent, não repetir o que já está lá nem no `CLAUDE.md`.

package/templates/skills/executar-plan/SKILL.md

@@ -9,7 +9,12 @@ argument-hint: "[id do trabalho]"
 Trabalho: $ARGUMENTS
 
 Você é o **ORQUESTRADOR**. Você não implementa nada: lê o plano, delega cada task a sub-agents, aplica os gates e
-mantém o estado em disco. **Sempre relate no chat qual agent está ativo**, principalmente nos gates.
+mantém o estado em disco. Relate no chat qual agent está ativo, principalmente nos gates: é por esse relato que o
+usuário acompanha uma execução que roda sem perguntas.
+
+A execução é longa e o contexto pode ser compactado no meio dela. Como o estado está em disco (frontmatter do
+`PLAN.md`, `BLOQUEIOS.md` e o rastro), siga até o fim da fase em vez de encerrar por causa do limite de contexto;
+depois de uma compactação, retome pelo `references/retomada.md`.
 
 ## Passo 0 — Identificar o trabalho (somente leitura)
 
@@ -56,7 +61,9 @@ abertos e eventos do rastro. Apresente ao usuário:
 
 1. Nunca inicie uma fase antes de todas as tasks da anterior estarem `concluida` (ou `bloqueada`/`pulada` com
    registro).
-2. Dentro da fase, dispare em paralelo as tasks `paralelizavel: true` cujas dependências estão concluídas.
+2. Dentro da fase, dispare em paralelo as tasks `paralelizavel: true` cujas dependências estão concluídas: uma
+   chamada de sub-agent por task, todas na **mesma mensagem**. Chamadas em mensagens separadas rodam uma depois da
+   outra.
 3. Ao delegar uma task, registre o início, troque o status da task para `em-andamento` e passe ao sub-agent o
    contexto de `references/delegacao.md`:
 

package/templates/skills/executar-plan/references/delegacao.md

@@ -2,24 +2,41 @@
 
 ## Contexto passado ao sub-agent
 
+Os dados da task vão dentro de `<task>`, separados das instruções fixas. O objetivo vem da `SPEC.md` do trabalho:
+sabendo para que a task serve, o sub-agent decide melhor o que a lista de campos não cobre.
+
 > Você é responsável pela task **T-SS.NN — [título]** do trabalho `docs/trabalhos/<id>/`.
 >
+> <task>
+> - **Objetivo do trabalho:** [uma ou duas frases da SPEC: o problema e quem ganha com a solução]
 > - **Input:** [o que já está pronto]
 > - **Output esperado:** [arquivo, função ou estrutura exata]
 > - **Testes críticos:**
 >   - [teste 1]
 >   - [teste 2]
 > - **Critério de aceite:** [verificável com sim ou não]
+> </task>
 >
 > Siga as convenções do `CLAUDE.md` e as rules do projeto. Escreva os testes primeiro (RED), confirme que falham,
-> implemente o mínimo para passar (GREEN) e rode a suíte do módulo.
+> implemente o necessário para passar (GREEN) e rode os testes do módulo.
+>
+> Implemente a regra de verdade, que funcione para qualquer entrada válida, e não só para os casos dos testes: os
+> testes verificam a solução, não a definem. Os testes críticos são o contrato da task e o `revisor-testes` compara
+> cada um com o plano, então não os altere, não os enfraqueça nem os remova para fazê-los passar. Se um teste parecer
+> errado ou contradizer a `SPEC.md`, implemente a regra da `SPEC.md` mesmo assim e relate o teste que continuou
+> falhando como dúvida, com a conta que mostra a contradição: assim a task fica a uma decisão de fechar.
+>
+> Faça só o que a task pede: sem refatorar o entorno, sem abstração para um uso só, sem opção de configuração e sem
+> tratamento de erro para cenário que não pode acontecer. O que ficar fora do escopo entra no seu relato como
+> sugestão.
 >
-> **Não** altere `SPEC.md`, `CLAUDE.md` nem o `PLAN.md`: quem atualiza o status é o orquestrador.
-> **Não** pergunte nada ao usuário: se precisar de uma decisão, pare e descreva a dúvida, as opções e o que
-> destrava — o orquestrador registra como bloqueio.
+> `SPEC.md`, `CLAUDE.md` e `PLAN.md` ficam como estão: quem atualiza o status é o orquestrador. Também não pergunte
+> nada ao usuário, porque ninguém acompanha a execução: se precisar de uma decisão, pare e descreva a dúvida, as
+> opções e o que destrava — o orquestrador registra como bloqueio.
 >
 > Comentários: o padrão é não comentar (bloco interno até 3 linhas, docstring pública até 5, sem cabeçalho de
-> arquivo). **Não** escreva no código o número da task, a fase, o plano, a data nem o que você investigou.
+> arquivo). O número da task, a fase, o plano, a data e o que você investigou vão para o commit e para
+> `docs/trabalhos/`, não para o código.
 >
 > Na área de código legado tocada, preserve o padrão local do arquivo; convenções novas valem para arquivo novo.
 

package/templates/skills/lgpd-checker/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: lgpd-checker
 description: >
-  Analisa um projeto de software em busca de falhas de conformidade com a LGPD (Lei Geral de Proteção de Dados — Lei nº 13.709/2018) e gera um relatório detalhado classificando os problemas encontrados por categoria e severidade. Use este skill SEMPRE que o usuário mencionar LGPD, proteção de dados, privacidade, compliance de dados pessoais, adequação à lei de privacidade brasileira, verificação de privacidade em código, auditoria de dados pessoais, ou quando perguntar se o sistema está em conformidade com a lei brasileira de dados. Também acione este skill quando o usuário quiser revisar código em busca de problemas relacionados a: coleta de consentimento, criptografia de dados pessoais, direitos dos titulares, logs de acesso, retenção de dados, ou política de privacidade.
+  Analisa um projeto de software em busca de falhas de conformidade com a LGPD (Lei Geral de Proteção de Dados — Lei nº 13.709/2018) e gera um relatório detalhado classificando os problemas encontrados por categoria e severidade. Use quando o usuário pedir uma análise ou auditoria de conformidade com a LGPD, perguntar se o sistema está adequado à lei brasileira de dados pessoais, ou quiser revisar o código em busca de problemas de consentimento, criptografia de dados pessoais, direitos dos titulares, logs de acesso, retenção de dados ou política de privacidade. Não é para mudanças pontuais que só tocam um dado pessoal, como mascarar um campo ou adicionar um cadastro.
 ---
 
 # LGPD Checker — Skill de Análise de Conformidade
@@ -56,7 +56,7 @@ Busque por nomes de campos, variáveis e comentários que indiquem:
 ### CAT-4: Segurança Técnica (Art. 46, 47, 48)
 Busque por:
 - Configurações de HTTPS/TLS (arquivos de configuração de servidor, `.env`, nginx/apache configs)
-- Criptografia de senhas: uso de bcrypt, argon2, scrypt (NÃO MD5, SHA1 puro, ou texto claro)
+- Criptografia de senhas: uso de bcrypt, argon2, scrypt (MD5, SHA1 puro ou texto claro são falha)
 - Criptografia em repouso para campos sensíveis
 - Variáveis de ambiente para credenciais (não hardcoded no código)
 - Tokens JWT: verificação de assinatura, expiração

package/templates/skills/resolver-bug/SKILL.md

@@ -73,12 +73,58 @@ explícito que a primeira task confirma ou derruba a hipótese. **Não altere na
 5. No frontmatter do `PLAN.md`, cada task vai de `pendente` para `em-andamento` e, com `suite_verde` registrado, para
    `concluida`, no feminino. Os outros valores aceitos são `bloqueada` e `pulada`.
 
-## Passo 5 — Relatório duplo
+## Passo 5 — Evitar que volte: a rule é mesmo necessária?
+
+O teste de regressão já protege o ponto corrigido. Uma rule só se justifica quando o mesmo erro pode ser cometido de
+novo **em outro código** e nada além dela o impediria. Toda rule entra no contexto das sessões (todas, ou as que tocam
+o `paths:` dela): rule desnecessária gasta contexto e dilui as que importam. Por isso o resultado esperado na maioria
+dos bugs é **nenhuma rule**.
+
+Responda com a evidência da investigação:
+
+1. **Padrão repetível:** o erro vem de um padrão que outro código pode repetir (ex.: usar `process.cwd()` onde o
+   projeto exige `acharRaiz()`), e não de um engano pontual (conta errada, condição invertida, caso esquecido)?
+2. **Fora do alcance do teste:** um código novo que repita o padrão passaria pelo teste de regressão sem falhar?
+3. **Não descobrível:** um agent lendo o código ao redor não chegaria sozinho à forma certa?
+4. **Sem cobertura:** nenhuma rule, `CLAUDE.md`, lint, tipo ou hook do projeto já trata do caso?
+5. **Rule é o mecanismo certo:** o erro não se evita melhor com algo que bloqueia em vez de orientar (tipo, lint,
+   hook, teste de contrato)? A rule é contexto e pode não ser seguida.
+
+| Respostas | Decisão |
+|---|---|
+| "Não" em 1, 2 ou 3 | **Nenhuma rule** |
+| "Não" em 4 | **Ajustar a rule existente**, sem criar outra sobre o mesmo assunto |
+| "Não" em 5 | **Outro mecanismo**: sugira o hook (`/evoluir-harness hook`), a regra de lint ou o tipo |
+| "Sim" em todas | **Nova rule** |
+
+Com nova rule ou ajuste, apresente o rascunho e **não grave sem aprovação**. A rule segue
+`evoluir-harness/references/rule.md` (até 30 linhas, a regra e o motivo dela) e **sempre começa com frontmatter**:
+
+```markdown
+---
+descricao: "Comandos do CLI resolvem a raiz do projeto com acharRaiz(), não com process.cwd()"
+origem: "2026-10-06-cli-grava-relativo-ao-cwd"
+paths:
+  - "src/**/*.ts"
+---
+
+# Raiz do projeto nos comandos do CLI
+```
+
+- `descricao` (o que a rule evita, em uma linha) e `origem` (o id deste trabalho) são obrigatórios. O Claude Code
+  só lê `paths` e retira o frontmatter antes de carregar a rule, então esses campos não custam contexto: servem
+  para a auditoria do `/evoluir-harness` e para quem decide se a rule ainda vale.
+- `paths` entra sempre que o padrão se limita a uma área do código, para a rule só carregar quando o trabalho toca
+  esses arquivos. Sem `paths`, ela vale em toda sessão: diga por quê.
+- Globs entre aspas. YAML inválido faz o Claude Code ignorar o frontmatter e carregar a rule em toda sessão.
+
+## Passo 6 — Relatório duplo
 
 Com a correção aprovada, escreva os dois relatórios a partir dos templates:
 
 - **`relatorios/TECNICO.md`** (`templates/relatorios/TECNICO.md`): sintoma, reprodução, causa raiz, correção,
-  testes que protegem e riscos remanescentes.
+  testes que protegem, riscos remanescentes e a decisão de prevenção do Passo 5 com o motivo — inclusive quando é
+  "nenhuma rule".
 - **`relatorios/CLIENTE.md`** (`templates/relatorios/CLIENTE.md`): o que acontecia, quem foi afetado, o que muda
   e se alguém precisa fazer algo — **sem jargão técnico**, seguindo `references/relatorio-para-cliente.md`.
 
@@ -92,11 +138,6 @@ npx @fontdata/ai-harness evento trabalho_concluido --trabalho <id> --nome resolv
 Troque o `status` do documento `PLAN.md` (o do topo do frontmatter, não o das tasks) para `concluido` e o dos
 relatórios para `final`.
 
-## Passo 6 — Evitar que volte
-
-Sugira uma rule em `.claude/rules/` que teria evitado o bug (padrão proibido, validação obrigatória, teste
-exigido). **Não grave sem aprovação.**
-
 ## Guardrails
 
 - **Nunca** corrigir antes do teste de regressão falhar pelo motivo do bug.

package/templates/skills/resolver-bug/templates/relatorios/TECNICO.md

@@ -30,3 +30,8 @@ O que mudou e por que é a correção mínima.
 ## Riscos remanescentes
 
 Pontos relacionados que não foram alterados e merecem atenção.
+
+## Prevenção
+
+Decisão: nenhuma rule, ajuste de `.claude/rules/<arquivo>.md`, nova rule `.claude/rules/<arquivo>.md` ou outro
+mecanismo (hook, lint, tipo). O motivo, citando a pergunta do Passo 5 que decidiu.