@fontdata/ai-harness 2.0.0 → 2.2.0

package/templates/skills/nova-tarefa/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: nova-tarefa
+description: Planeja uma nova funcionalidade antes de implementar — gera a spec e o plano de implementação (start inicial ou nova tarefa) e, se confirmado, dispara o orquestrador.
+argument-hint: "[descrição da funcionalidade ou 'start']"
+---
+
+# Nova tarefa — planejar antes de implementar
+
+Tarefa / recorte: $ARGUMENTS
+
+Você transforma um pedido em um **trabalho** com `SPEC.md` e `PLAN.md` prontos para execução com sub-agents.
+Serve para o **start inicial** do projeto e para **cada nova tarefa**. Todo o esforço vai para o planejamento:
+uma pergunta durante a execução é falha do plano.
+
+> **🚦 Há GATEs de aprovação.** Nada é implementado nesta skill.
+
+## Passo 0 — Contexto (somente leitura)
+
+1. Leia o `SPEC.md` e o `CLAUDE.md` da raiz e, se existir, a rule de projeto `.claude/rules/harness-projeto.md`: o
+   mapa de agents por domínio e os portões extras entram no plano.
+2. Liste os trabalhos existentes em `docs/trabalhos/` (título, tipo e status no frontmatter) para não duplicar
+   nem contradizer um trabalho em andamento.
+3. **Start inicial** (não há trabalho do tipo `feature` ainda, ou o pedido é "start"/"primeira fatia"): derive o
+   recorte direto do `SPEC.md` — a primeira fatia vertical. **Nova tarefa:** siga para o Passo 1.
+
+## Passo 1 — Isso já existe?
+
+Antes de planejar, procure no código evidência de que a funcionalidade — ou parte dela — **já existe**. Siga
+`references/isso-ja-existe.md` e responda com uma de três conclusões, sempre com `arquivo:linha`:
+
+- **não existe** → siga;
+- **existe parcialmente** → o recorte passa a ser só o que falta;
+- **já existe** → pare e mostre onde está. Não crie trabalho sem a confirmação do usuário.
+
+Consulte também a memória dos arquivos candidatos: `npx @fontdata/ai-harness memoria --arquivo <arquivo>` mostra
+os trabalhos que já os tocaram e por quê.
+
+## Passo 2 — Recorte
+
+- **Nova tarefa:** faça de 2 a 3 perguntas, uma por vez, para entender o que deve ser feito.
+- Resuma o que foi entendido (o que entra, o que fica fora, critérios de aceite) e **aguarde aprovação**.
+
+Toda ambiguidade que você resolver por conta própria vira decisão registrada (Passo 5), sempre com a escolha
+mais conservadora.
+
+## Passo 3 — Pasta do trabalho e SPEC.md
+
+1. Defina o id `AAAA-MM-DD-<slug>` (data de hoje, slug curto em minúsculas, sem acento).
+2. Crie `docs/trabalhos/<id>/SPEC.md` a partir de `templates/SPEC.md`, preenchendo `{{id}}`, `{{titulo}}` e
+   `{{data}}`. Os nomes dos arquivos da pasta são sempre em caixa alta.
+3. Registre o início do trabalho:
+
+   ```bash
+   npx @fontdata/ai-harness evento trabalho_iniciado --trabalho <id> --nome nova-tarefa --dados '{"trabalho_tipo":"feature"}'
+   ```
+
+## Passo 4 — PLAN.md
+
+Crie `docs/trabalhos/<id>/PLAN.md` a partir de `templates/PLAN.md`, seguindo `references/regras-do-plano.md`:
+
+- as tasks aparecem **no frontmatter** (`tasks`) e na prosa, com os mesmos ids;
+- toda task de código tem pelo menos 2 testes críticos concretos e critério de aceite binário;
+- tasks paralelizáveis da mesma fase não tocam os mesmos arquivos;
+- `arquivos` do frontmatter lista todos os arquivos (ou pastas) que as tasks vão criar ou alterar — é por ele que
+  o `/executar-plan` impede dois trabalhos de mexerem no mesmo código ao mesmo tempo;
+- **plano condensado:** com 1 sprint e 1 fase, use `condensado: true` e omita os títulos de sprint e fase — o
+  contrato das tasks continua completo.
+
+## Passo 5 — Decisões
+
+Registre em `docs/trabalhos/<id>/DECISOES.md` (a partir de `templates/DECISOES.md`) cada ambiguidade resolvida:
+decisão, motivo e alternativas descartadas. Para cada decisão:
+
+```bash
+npx @fontdata/ai-harness evento decisao_registrada --trabalho <id> --nome nova-tarefa --dados '{"decisao_id":"D-01"}'
+```
+
+## Passo 6 — Auditoria do plano
+
+1. Delegue ao agent **`auditor-plano`** (no plugin, `fontdata:auditor-plano`) a auditoria de `SPEC.md` e `PLAN.md`.
+2. Corrija os achados BLOQUEANTES e IMPORTANTES no plano e peça nova auditoria até o veredito `APROVADO`.
+3. Grave `auditoria_plano: aprovado` e `status: aguardando-aprovacao` no frontmatter do `PLAN.md`.
+4. Rode `npx @fontdata/ai-harness doctor` e confirme que não há achado `contrato-*` neste trabalho.
+
+## Passo 7 — 🚦 GATE de aprovação
+
+Mostre ao usuário: os caminhos gravados, as tasks por fase (quais rodam em paralelo), quantos agents serão
+necessários e as decisões registradas. **Peça aprovação explícita.**
+
+- Com aprovação, grave `status: aprovado` no `SPEC.md`.
+- **Start inicial (fluxo `/harness`):** o próximo passo normalmente é a etapa scaffold do `/harness` — **não** dispare a execução.
+- **Nova tarefa:** se o usuário confirmar, chame **`/executar-plan <id>`** para executar o plano aprovado.
+
+## Guardrails
+
+- **Nunca** implementar nesta skill; **nunca** gravar `PLAN.md` na raiz do projeto.
+- **Nunca** criar trabalho para algo que já existe sem a confirmação do usuário.
+- Use os nomes de módulos do `SPEC.md` — sem nomenclatura nova.
+- Conteúdo em **pt-BR**.

package/templates/skills/nova-tarefa/references/isso-ja-existe.md

@@ -0,0 +1,24 @@
+# Isso já existe?
+
+Pedidos de funcionalidade nova muitas vezes descrevem algo que o sistema já faz, de outro jeito ou com outro nome.
+Antes de planejar, procure evidência — nunca presuma.
+
+## Onde procurar
+
+1. **Vocabulário do pedido:** entidades, ações e telas citadas, com sinônimos (cliente/pessoa/contato,
+   pedido/venda/ordem, desconto/abatimento). Busque nomes de classes, funções, rotas, tabelas e rótulos de tela.
+2. **Pontos de entrada:** rotas e controllers, menus e telas, comandos de CLI, jobs agendados.
+3. **Dados:** tabelas e colunas (migrations, models, scripts SQL) que já guardam o que o pedido precisa.
+4. **Configuração e flags:** a funcionalidade pode existir desligada por configuração ou feature flag.
+5. **Trabalhos anteriores:** `docs/trabalhos/*/SPEC.md` e o campo `arquivos` do frontmatter dos planos e relatórios.
+
+## Como concluir
+
+| Conclusão | Quando | O que fazer |
+|---|---|---|
+| **Não existe** | Nenhuma evidência nas cinco frentes | Seguir para o recorte |
+| **Existe parcialmente** | Parte do comportamento já está no código | Recortar só o que falta e citar o que será reaproveitado |
+| **Já existe** | O comportamento pedido está implementado | Parar, mostrar onde está e perguntar se o pedido é outra coisa |
+
+Toda conclusão vem com a evidência (`arquivo:linha`, rota, tabela) — inclusive a de "não existe", com o que foi
+buscado.

package/templates/skills/nova-tarefa/references/regras-do-plano.md

@@ -0,0 +1,35 @@
+# Regras do plano
+
+Um plano aprovado precisa poder ser executado sem que ninguém pergunte nada no meio.
+
+## Estrutura
+
+- **Sprint** → **Fase** → **Task**. Cada sprint tem um critério de conclusão em uma frase verificável; cada fase
+  tem um critério de gate verificável por comando de terminal.
+- Ids de task no formato `T-SS.NN` (sprint e número, com dois dígitos).
+- As tasks ficam **no frontmatter** (`tasks`) e na prosa. O frontmatter é o que hooks, `doctor` e retomada leem;
+  quando os dois divergirem, vale o frontmatter.
+
+## Regras obrigatórias
+
+1. Toda task de código tem **pelo menos 2 testes críticos** definidos antes de qualquer código — entrada e
+   resultado esperado, não "testar o fluxo". Os testes são escritos primeiro.
+2. **Critério de aceite binário:** verificável com sim ou não, por comando ou observação.
+3. **Nenhum output vago:** descreva o arquivo, a função ou a estrutura exata que será entregue.
+4. Tasks `paralelizavel: true` da mesma fase **não tocam os mesmos arquivos** nem dependem uma da outra.
+5. `depende_de` declara toda dependência real; a ordem das fases respeita essas dependências.
+6. Use os nomes de módulos do `SPEC.md` — sem nomenclatura nova.
+7. Uma task cabe numa sessão de trabalho; task grande é dividida.
+8. `arquivos` no frontmatter lista todos os arquivos (ou pastas) que as tasks vão criar ou alterar. Trabalhos
+   executados em paralelo na mesma pasta são barrados quando essas listas se cruzam.
+
+## Plano condensado
+
+Quando o trabalho tem **1 sprint e 1 fase**, use `condensado: true`: omita os títulos de sprint e fase e liste as
+tasks direto. O contrato de cada task (testes, critério, dependências) continua completo.
+
+## Status
+
+- Ao criar: `status: rascunho` e `auditoria_plano: pendente`.
+- Depois do veredito do `auditor-plano`: `auditoria_plano: aprovado` e `status: aguardando-aprovacao`.
+- A execução muda para `em-execucao` e, ao fim, `concluido`. As tasks começam `pendente`.

package/templates/skills/nova-tarefa/templates/DECISOES.md

@@ -0,0 +1,20 @@
+---
+schema_versao: 1
+tipo: decisoes
+id: "{{id}}"
+trabalho_tipo: feature
+titulo: "Decisões — {{titulo}}"
+status: ativo
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# Decisões — {{titulo}}
+
+Decisões tomadas durante o planejamento e a execução. Uma decisão que muda não é apagada: registre uma nova
+dizendo qual ela substitui.
+
+| # | Data | Decisão | Motivo | Alternativas descartadas |
+|---|---|---|---|---|
+| D-01 | {{data}} | O que foi decidido | Por que, com a opção mais conservadora | O que não foi escolhido |

package/templates/skills/nova-tarefa/templates/PLAN.md

@@ -0,0 +1,58 @@
+---
+schema_versao: 1
+tipo: plano
+id: "{{id}}"
+trabalho_tipo: feature
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+condensado: false
+auditoria_plano: pendente
+causa_raiz: null
+tasks:
+  - id: T-01.01
+    titulo: "Nome curto da primeira task"
+    status: pendente
+    depende_de: []
+    paralelizavel: false
+    testes_criticos:
+      - "Entrada válida produz o resultado esperado"
+      - "Entrada inválida é recusada com a mensagem esperada"
+  - id: T-01.02
+    titulo: "Nome curto da segunda task"
+    status: pendente
+    depende_de:
+      - T-01.01
+    paralelizavel: false
+    testes_criticos:
+      - "Cenário principal integrado"
+      - "Caso de erro tratado"
+---
+
+# Plano — {{titulo}}
+
+## Sprint 1 — Critério de conclusão em uma frase verificável
+
+### Fase 1.1 — Nome da fase
+
+> Dependências: nenhuma
+> Paralelismo: quais tasks desta fase rodam juntas
+> Gate: comando de terminal que prova a fase concluída
+
+#### T-01.01 — Nome curto da primeira task
+
+- **Agent:** papel responsável
+- **Input:** o que precisa estar pronto para começar
+- **Output:** arquivo, função ou estrutura exata entregue
+- **Testes críticos:** os mesmos do frontmatter
+- **Critério de aceite:** verificável com sim ou não
+
+#### T-01.02 — Nome curto da segunda task
+
+- **Agent:** papel responsável
+- **Input:** saída da T-01.01
+- **Output:** arquivo, função ou estrutura exata entregue
+- **Testes críticos:** os mesmos do frontmatter
+- **Critério de aceite:** verificável com sim ou não

package/templates/skills/nova-tarefa/templates/SPEC.md

@@ -0,0 +1,37 @@
+---
+schema_versao: 1
+tipo: spec
+id: "{{id}}"
+trabalho_tipo: feature
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# {{titulo}}
+
+## Contexto
+
+Por que este trabalho existe e o que o `SPEC.md` principal diz sobre ele.
+
+## Isso já existe?
+
+Conclusão (não existe, existe parcialmente ou já existe) e a evidência encontrada.
+
+## O que será entregue
+
+- Comportamento 1, descrito do ponto de vista de quem usa.
+
+## Fora do escopo
+
+- O que fica explicitamente para depois.
+
+## Critérios de aceite
+
+- [ ] Critério verificável com sim ou não.
+
+## Riscos e código legado
+
+Áreas de código existente tocadas e o padrão local a preservar.

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

@@ -0,0 +1,104 @@
+---
+name: resolver-bug
+description: Corrige um bug relatado — algo que não funciona, dá erro ou mostra valor errado — investigando a causa raiz, planejando a correção, pedindo aprovação e corrigindo passo a passo.
+argument-hint: "[relato do problema]"
+---
+
+# Resolver bug
+
+Relato: $ARGUMENTS
+
+Se o relato não veio, peça os detalhes antes de começar: o que acontece, o que era esperado, onde e desde quando.
+
+> **🚦 Há um GATE de aprovação** antes de alterar qualquer código.
+
+## Passo 1 — Investigar a causa raiz
+
+1. Delegue ao agent **`investigador`** (no plugin, `fontdata:investigador`) o relato completo.
+2. Ele devolve: sintoma, como reproduzir, causa raiz (`comprovada` ou `hipotese`) com evidência, arquivos envolvidos
+   e riscos da correção.
+3. **Consulte a memória** sobre cada arquivo envolvido: `npx @fontdata/ai-harness memoria --arquivo <arquivo>` mostra os
+   trabalhos anteriores que o tocaram. Depois de criar o trabalho (Passo 2) e com a causa comprovada,
+   `npx @fontdata/ai-harness memoria --regressao <id>` indica se algum deles é regressão candidata — registre a
+   conclusão no relatório técnico.
+4. **Não há defeito?** Se a apuração mostrar que é comportamento esperado, paridade com legado, medição ou
+   levantamento, crie um trabalho do tipo `investigacao` com `relatorios/TECNICO.md`, avise o usuário e encerre.
+
+## Passo 2 — Criar o trabalho do tipo bug
+
+1. Id `AAAA-MM-DD-<slug>`, com slug que descreve o sintoma.
+2. Crie `docs/trabalhos/<id>/PLAN.md` a partir de `templates/PLAN.md`:
+   - `causa_raiz`: `comprovada` ou `hipotese`, conforme o investigador;
+   - `arquivos`: os arquivos envolvidos;
+   - a **primeira task é sempre o teste de regressão** que reproduz o bug e falha hoje;
+   - plano **condensado** para correção simples, com `auditoria_plano: pendente` (ele não passa pelo
+     `auditor-plano`); plano completo quando houver mais de uma fase, auditado pelo `auditor-plano`, cujo veredito
+     grava `auditoria_plano: aprovado` ou `reprovado`. Não há outros valores.
+3. Registre o início:
+
+   ```bash
+   npx @fontdata/ai-harness evento trabalho_iniciado --trabalho <id> --nome resolver-bug --dados '{"trabalho_tipo":"bug"}'
+   ```
+
+## Passo 3 — 🚦 GATE de aprovação
+
+Mostre: sintoma, causa raiz e evidência, o plano de correção e os riscos. Com `causa_raiz: hipotese`, deixe
+explícito que a primeira task confirma ou derruba a hipótese. **Não altere nada sem o "ok".**
+
+## Passo 4 — Corrigir com TDD
+
+1. **Regressão primeiro (T-01.01):** escreva o teste de regressão, rode e **confirme que falha** pelo motivo do bug.
+   Com hipótese, o teste falhando pelo motivo esperado torna a causa `comprovada` — atualize o frontmatter.
+
+   ```bash
+   npx @fontdata/ai-harness evento task_iniciada --trabalho <id> --task T-01.01 --nome resolver-bug
+   npx @fontdata/ai-harness evento suite_vermelha --trabalho <id> --task T-01.01 --nome resolver-bug --resultado falha \
+     --dados '{"comando":"npm test","total":42,"falhas":1}'
+   ```
+
+2. **Correção mínima (T-01.02):** registre `task_iniciada` para a T-01.02, aplique a correção e rode a suíte completa.
+   Quando existir `.claude/rules/harness-projeto.md`, delegue ao agent do domínio e use o comando da suíte declarado.
+3. Passe pelos gates: `revisor-testes` e `qa` (no plugin, `fontdata:revisor-testes` e `fontdata:qa`). O `qa`
+   registra `suite_verde` para a T-01.02. Plano com várias tasks: execute com `/executar-plan <id>`.
+4. A T-01.01 **fecha junto com a correção**: o critério dela é falhar antes e passar depois, e a mesma suíte verde
+   prova as duas coisas. Registre `suite_verde` também para ela e feche as duas:
+
+   ```bash
+   npx @fontdata/ai-harness evento suite_verde --trabalho <id> --task T-01.01 --nome qa --resultado ok \
+     --dados '{"comando":"npm test","total":42,"falhas":0}'
+   npx @fontdata/ai-harness evento task_concluida --trabalho <id> --task T-01.01 --nome resolver-bug
+   npx @fontdata/ai-harness evento task_concluida --trabalho <id> --task T-01.02 --nome resolver-bug
+   ```
+
+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
+
+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.
+- **`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`.
+
+Para cada relatório e para o encerramento:
+
+```bash
+npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome resolver-bug --dados '{"caminho":"docs/trabalhos/<id>/relatorios/CLIENTE.md"}'
+npx @fontdata/ai-harness evento trabalho_concluido --trabalho <id> --nome resolver-bug
+```
+
+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.
+- **Nunca** alterar código antes do GATE; nada de refatoração oportunista junto com a correção.
+- Conteúdo em **pt-BR**.

package/templates/skills/resolver-bug/references/relatorio-para-cliente.md

@@ -0,0 +1,26 @@
+# Relatório para o cliente
+
+O relatório para o cliente é lido por quem usa o sistema ou decide sobre ele — não por quem o programa. O hook
+`sem-jargao` avisa quando aparecem termos técnicos.
+
+## O que responder
+
+1. **O que acontecia:** o problema como a pessoa via, com as palavras dela.
+2. **Quem foi afetado e desde quando:** perfis, telas, período, volume aproximado.
+3. **O que muda agora:** o comportamento correto, a partir de quando.
+4. **É preciso fazer algo?** Refazer uma operação, conferir registros de um período, avisar alguém. Se não, diga
+   que não.
+
+## Como escrever
+
+- Frases curtas, voz ativa, sem siglas.
+- Troque o termo técnico pelo efeito: em vez de "a consulta retornava null", "a tela mostrava o campo vazio".
+- Não cite arquivos, funções, versões de biblioteca, commits ou nomes de sistema interno.
+- Não culpe pessoas nem fornecedores.
+
+## Exemplo
+
+> Entre os dias 3 e 10, o valor do frete aparecia maior do que o correto nos pedidos com mais de um volume.
+> Os pedidos já emitidos nesse período foram listados para conferência. A partir de hoje, o frete considera o
+> peso de todos os volumes corretamente. Não é preciso refazer os pedidos: a equipe financeira vai tratar as
+> diferenças.

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

@@ -0,0 +1,62 @@
+---
+schema_versao: 1
+tipo: plano
+id: "{{id}}"
+trabalho_tipo: bug
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+condensado: true
+auditoria_plano: pendente
+causa_raiz: hipotese
+tasks:
+  - id: T-01.01
+    titulo: "Teste de regressão que reproduz o problema"
+    status: pendente
+    depende_de: []
+    paralelizavel: false
+    testes_criticos:
+      - "Com a entrada do relato, o resultado é o esperado (falha hoje)"
+      - "O caso vizinho que já funcionava continua funcionando"
+  - id: T-01.02
+    titulo: "Correção mínima da causa raiz"
+    status: pendente
+    depende_de:
+      - T-01.01
+    paralelizavel: false
+    testes_criticos:
+      - "O teste de regressão da T-01.01 passa"
+      - "A suíte completa continua verde"
+---
+
+# Correção — {{titulo}}
+
+## Sintoma
+
+O que acontece, o que era esperado, onde e desde quando.
+
+## Como reproduzir
+
+Passos, dados ou teste que mostram o problema.
+
+## Causa raiz
+
+Hipótese ou causa comprovada, com a evidência (`arquivo:linha`, trecho do histórico, saída da reprodução).
+
+## Tasks
+
+#### T-01.01 — Teste de regressão que reproduz o problema
+
+- **Output:** teste automatizado que falha hoje pelo motivo do problema
+- **Critério de aceite:** o teste falha antes da correção e passa depois
+
+#### T-01.02 — Correção mínima da causa raiz
+
+- **Output:** alteração restrita aos arquivos da causa raiz
+- **Critério de aceite:** regressão verde e suíte completa verde
+
+## Riscos
+
+O que mais depende do trecho alterado e como foi protegido.

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

@@ -0,0 +1,29 @@
+---
+schema_versao: 1
+tipo: relatorio_cliente
+id: "{{id}}"
+trabalho_tipo: bug
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# {{titulo}}
+
+## O que acontecia
+
+O problema como quem usa o sistema percebia.
+
+## Quem foi afetado
+
+Perfis, telas e período.
+
+## O que muda agora
+
+O comportamento correto, a partir de quando.
+
+## É preciso fazer algo?
+
+O que conferir ou refazer — ou a confirmação de que nada é necessário.

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

@@ -0,0 +1,32 @@
+---
+schema_versao: 1
+tipo: relatorio_tecnico
+id: "{{id}}"
+trabalho_tipo: bug
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# Relatório técnico — {{titulo}}
+
+## Sintoma e reprodução
+
+## Causa raiz
+
+Evidência com `arquivo:linha` e por que a condição produzia o sintoma.
+
+## Correção
+
+O que mudou e por que é a correção mínima.
+
+## Testes que protegem
+
+- Teste de regressão: caminho e o que ele verifica.
+- Suíte completa: comando e resultado.
+
+## Riscos remanescentes
+
+Pontos relacionados que não foram alterados e merecem atenção.

package/bin/cli.js

@@ -1,122 +0,0 @@
-#!/usr/bin/env node
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
-import { loadCatalog, allCommands } from '../src/catalog.js';
-import { runCommand, runnableIds, suggestIds } from '../src/run.js';
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-const RESERVED = new Set(['init', 'list', 'run', 'help', '--help', '-h', '--version', '-v']);
-
-function pkgVersion() {
-  try {
-    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
-    return pkg.version;
-  } catch {
-    return '0.0.0';
-  }
-}
-
-function printHelp() {
-  console.log(`
-@fontdata/ai-harness — harness de engenharia com IA para Claude Code
-
-Uso:
-  npx @fontdata/ai-harness <comando> [contexto]     roda o comando na pasta atual
-  npx @fontdata/ai-harness init                     instala os comandos no projeto
-
-Executar sem instalar:
-  <comando>       Abre o Claude Code aqui já executando o comando (ex.: harness)
-  run <comando>   Forma explícita, útil quando o nome colide com uma palavra reservada
-
-Gerenciar:
-  init [caminho]  Instala os slash commands em .claude/commands do projeto (interativo)
-  list            Lista todos os comandos disponíveis no catálogo
-  --help, -h      Mostra esta ajuda
-  --version, -v   Mostra a versão
-
-Exemplos:
-  npx @fontdata/ai-harness harness
-  npx @fontdata/ai-harness resolver-bug "login 500 no refresh token"
-  npx @fontdata/ai-harness run versao minor
-  npx @fontdata/ai-harness harness -- --model claude-opus-5
-
-Tudo depois de \`--\` é repassado ao Claude Code (--model, --effort, -p, ...).
-`);
-}
-
-function printList() {
-  const catalog = loadCatalog();
-  console.log('\nComandos disponíveis:\n');
-  for (const group of catalog.groups) {
-    console.log(`  ${group.title}`);
-    for (const cmd of group.commands) {
-      const star = cmd.recommended ? ' *' : '  ';
-      console.log(`   ${star} ${cmd.title.padEnd(26)} ${cmd.description}`);
-    }
-    console.log('');
-  }
-  console.log(`  (* = conjunto recomendado · total: ${allCommands(catalog).length} comandos + /harness)\n`);
-}
-
-/** Separa os argumentos do comando dos flags destinados ao Claude Code. */
-function splitArgs(rest) {
-  const sep = rest.indexOf('--');
-  if (sep === -1) return { args: rest, claudeFlags: [] };
-  return { args: rest.slice(0, sep), claudeFlags: rest.slice(sep + 1) };
-}
-
-async function main() {
-  const argv = process.argv.slice(2);
-  const cmd = argv[0];
-
-  if (cmd === '--version' || cmd === '-v') {
-    console.log(pkgVersion());
-    return;
-  }
-  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
-    printHelp();
-    return;
-  }
-  if (cmd === 'list') {
-    printList();
-    return;
-  }
-  if (cmd === 'init') {
-    // Import dinâmico: só carrega @clack/prompts quando o init é realmente usado.
-    const { runInit } = await import('../src/init.js');
-    await runInit(argv[1]);
-    return;
-  }
-  if (cmd === 'run') {
-    const id = argv[1];
-    if (!id) {
-      console.error('Informe o comando a executar. Ex.: npx @fontdata/ai-harness run harness\n');
-      printHelp();
-      process.exit(1);
-    }
-    const { args, claudeFlags } = splitArgs(argv.slice(2));
-    process.exit(runCommand(id, args, claudeFlags));
-  }
-
-  const ids = runnableIds();
-  if (ids.includes(cmd.replace(/^\//, ''))) {
-    const { args, claudeFlags } = splitArgs(argv.slice(1));
-    process.exit(runCommand(cmd, args, claudeFlags));
-  }
-
-  if (!RESERVED.has(cmd)) {
-    const near = suggestIds(cmd.replace(/^\//, ''), ids);
-    console.error(`Comando desconhecido: ${cmd}`);
-    if (near.length) console.error(`\nVocê quis dizer: ${near.join(', ')}`);
-    console.error('');
-  }
-  printHelp();
-  process.exit(1);
-}
-
-main().catch((err) => {
-  console.error('Erro:', err?.message || err);
-  process.exit(1);
-});