@fontdata/ai-harness 2.3.1 → 2.4.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fontdata",
-  "version": "2.3.1",
+  "version": "2.4.0",
   "description": "Harness de engenharia com IA da Fontdata para Claude Code",
   "author": { "name": "Fontdata" },
   "commands": ["./templates/commands"],

package/README.md

@@ -127,7 +127,7 @@ duas vezes.
 | `docs/trabalhos/<id>/PLAN.md` | Plano: sprints, fases e tasks (as tasks também no frontmatter) |
 | `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 `CLIENTE.md` | Relatório para engenharia e para cliente ou gestão |
+| `docs/trabalhos/<id>/relatorios/TECNICO.md` e `CLIENTE.md` | Relatório para engenharia e para cliente e suporte |
 | `docs/eventos/<id>.jsonl` | Rastro de eventos (não versionado por padrão) |
 | `.ai-harness/lock.json` e `config.json` | Lock da instalação e configuração dos hooks (versionar) |
 
@@ -141,7 +141,7 @@ Os formatos estão em [`docs/contratos/ARTEFATOS.md`](docs/contratos/ARTEFATOS.m
 | Hook | Quando | Modo inicial |
 |---|---|---|
 | `lembrete` | O pedido parece bug, funcionalidade nova, risco de segurança ou problema de performance: sugere o fluxo certo | aviso |
-| `segredo-no-commit` | `git commit` com chave de acesso, token, chave privada ou senha no diff | **bloqueio** |
+| `segredo-no-commit` | `git commit` com chave de acesso, token, chave privada ou senha no diff (em arquivo de teste, só token e chave de verdade) | **bloqueio** |
 | `proteger-contratos` | SPEC, PLAN ou CLAUDE.md reescritos durante a execução de um trabalho | aviso |
 | `task-so-fecha-verde` | Task marcada como concluída sem suíte verde no rastro | aviso |
 | `sem-jargao` | Termo técnico no relatório para o cliente | aviso |

package/dist/contratos/artefatos.js

@@ -154,6 +154,9 @@ function validatePlan(file, data) {
     if ('condensado' in data && typeof data.condensado !== 'boolean') {
         problems.push(problem(file, 'formato-invalido', 'condensado deve ser true ou false.'));
     }
+    if ('relatorios_entrega' in data && typeof data.relatorios_entrega !== 'boolean') {
+        problems.push(problem(file, 'formato-invalido', 'relatorios_entrega deve ser true ou false.'));
+    }
     if ('auditoria_plano' in data && !['pendente', 'aprovado', 'reprovado'].includes(String(data.auditoria_plano))) {
         problems.push(problem(file, 'status-invalido', 'auditoria_plano inválida. Use: pendente, aprovado, reprovado.'));
     }
@@ -261,7 +264,10 @@ export function validateWork(root, folderId) {
     const migrated = [...parsed.values()].some((data) => data.migrado === true);
     if (typeof declared === 'string' && !migrated) {
         const required = [...(REQUIRED_BY_WORK_TYPE[declared] ?? [])];
-        if (declared === 'bug' && parsed.get('PLAN.md')?.status === 'concluido') {
+        const plan = parsed.get('PLAN.md');
+        // Feature só exige relatórios quando o plano nasceu com relatorios_entrega; as anteriores ficam como estão.
+        const reportsDue = declared === 'bug' || (declared === 'feature' && plan?.relatorios_entrega === true);
+        if (reportsDue && plan?.status === 'concluido') {
             required.push('relatorios/TECNICO.md', 'relatorios/CLIENTE.md');
         }
         for (const rel of required) {

package/package.json

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

@@ -26,7 +26,7 @@ Comece por `/harness`, que conduz o setup em etapas.
 | `docs/trabalhos/<id>/PLAN.md` | Plano: sprints, fases e tasks (as tasks também no frontmatter) |
 | `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 ou gestão |
+| `docs/trabalhos/<id>/relatorios/TECNICO.md` e `relatorios/CLIENTE.md` | Relatório para engenharia e para cliente e suporte (sem jargão) |
 | `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/hooks/lib/segredos.mjs

@@ -33,6 +33,15 @@ function isEnvFile(path) {
   return /^\.env(\..+)?$/.test(name) && !/\.(example|sample|template|dist)$/.test(name);
 }
 
+/**
+ * Arquivo de teste: `tests/`, `test/`, `__tests__/`, `spec/` ou `*.test.ts` / `*.spec.js`...
+ * Fixture de senha é o caso normal em teste, então a heurística de atribuição não vale ali.
+ * @param {string} path
+ */
+function isTestFile(path) {
+  return /(^|\/)(tests?|__tests__|spec)\//.test(path) || /\.(test|spec)\.[cm]?[jt]sx?$/.test(basename(path));
+}
+
 /**
  * @param {string} path
  * @param {string} content Linha adicionada, sem o `+`.
@@ -47,6 +56,8 @@ function secretIn(path, content) {
     return value && !isPlaceholder(value) ? 'valor em arquivo .env' : null;
   }
 
+  if (isTestFile(path)) return null;
+
   const assigned = ASSIGNED_SECRET.exec(content);
   return assigned && !isPlaceholder(assigned[2] ?? '') ? 'senha ou token atribuído no código' : null;
 }

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

@@ -116,15 +116,32 @@ portões extras (com os achados IMPORTANTE e SUGESTÃO do `code-reviewer`), esta
    npx @fontdata/ai-harness evento trabalho_concluido --trabalho <id> --nome executar-plan
    ```
 
-2. Retire `<id>` da lista `trabalhos_ativos` de `.ai-harness/estado.json`, lendo o arquivo logo antes de gravar
+2. **Relatórios da entrega** (só trabalho do tipo `feature`; o de `bug` é escrito pelo `/resolver-bug`). Siga
+   `references/relatorios-da-entrega.md` e grave, a partir dos templates:
+
+   - **`relatorios/CLIENTE.md`** (`templates/relatorios/CLIENTE.md`): o que há de novo, para quem, o que preparar,
+     como usar, situações comuns e o que ainda não faz — **sem jargão técnico**. É o texto entregue ao cliente e
+     aos técnicos de suporte.
+   - **`relatorios/TECNICO.md`** (`templates/relatorios/TECNICO.md`): onde está no código, configuração e
+     implantação, testes que protegem e o diagnóstico para o suporte.
+
+   Preencha `arquivos` com os arquivos tocados, grave `status: final` e registre cada um:
+
+   ```bash
+   npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome executar-plan --dados '{"caminho":"docs/trabalhos/<id>/relatorios/CLIENTE.md"}'
+   npx @fontdata/ai-harness evento relatorio_gerado --trabalho <id> --nome executar-plan --dados '{"caminho":"docs/trabalhos/<id>/relatorios/TECNICO.md"}'
+   ```
+
+3. Retire `<id>` da lista `trabalhos_ativos` de `.ai-harness/estado.json`, lendo o arquivo logo antes de gravar
    e preservando os ids das outras sessões.
-3. Com bloqueios abertos, apresente cada um ao usuário. Cada resposta vira decisão em `DECISOES.md`
+4. Com bloqueios abertos, apresente cada um ao usuário. Cada resposta vira decisão em `DECISOES.md`
    (`decisao_registrada`), o bloqueio é fechado (`bloqueio_fechado`) e a task volta para `pendente` numa nova
    rodada desta skill.
 
 ## Restrições
 
-- **Não** modifique `SPEC.md`, `CLAUDE.md` nem o conteúdo do plano — só o status das tasks e do plano.
+- **Não** modifique `SPEC.md`, `CLAUDE.md` nem o conteúdo do plano — só o status das tasks e do plano. Os
+  relatórios da entrega são arquivos novos, não alteração do plano.
 - **Não** implemente fora do escopo do plano nem invente solução alternativa para task bloqueada.
 - **Não** feche task sem `suite_verde` no rastro.
 - Conteúdo em **pt-BR**.

package/templates/skills/executar-plan/references/relatorios-da-entrega.md

@@ -0,0 +1,51 @@
+# Relatórios da entrega
+
+Ao concluir um trabalho do tipo `feature`, o orquestrador entrega dois relatórios. Eles são escritos **depois** da
+execução, a partir do que foi de fato entregue, não do que foi planejado.
+
+| Relatório | Quem lê | Para quê |
+|---|---|---|
+| `relatorios/CLIENTE.md` | cliente e técnico de suporte | saber o que mudou, como usar e o que responder |
+| `relatorios/TECNICO.md` | engenharia e suporte avançado | manter, implantar e diagnosticar |
+
+## De onde tirar o conteúdo
+
+1. **`SPEC.md`**, seção *Como vai operar*: perfis, preparação, passo a passo e dúvidas previsíveis.
+2. **O código entregue** (diff do trabalho): nomes reais de telas, botões, mensagens e parâmetros. Onde o código
+   diverge da `SPEC.md`, vale o código, e a divergência entra em *Pendências e riscos* do `TECNICO.md`.
+3. **`DECISOES.md`**: regras de negócio escolhidas durante o trabalho que mudam o comportamento para quem usa.
+4. **`BLOQUEIOS.md`** e *Fora do escopo* da `SPEC.md`: o que **não** foi entregue vai para *O que ainda não faz*.
+
+Não invente passo, mensagem ou tela que não esteja no código. Sem informação para uma seção, escreva o que falta
+e avise o usuário no encerramento em vez de preencher com suposição.
+
+## Como escrever o relatório para o cliente
+
+O mesmo texto vai para o cliente e para o técnico de suporte: ele precisa bastar para o técnico atender um
+chamado sem abrir o código. O hook `sem-jargao` avisa quando aparecem termos técnicos.
+
+- Frases curtas, voz ativa, sem siglas.
+- Use os nomes como aparecem na tela, entre aspas: clique em "Salvar pedido".
+- Troque o termo técnico pelo efeito: em vez de "o endpoint retorna 404", "o sistema avisa que o pedido não foi
+  encontrado".
+- Não cite arquivos, funções, versões, commits ou nomes de sistema interno.
+- Em *Situações comuns*, liste as mensagens de aviso e erro que a funcionalidade mostra, com o texto exato.
+- Em *Perguntas frequentes*, parta das dúvidas previsíveis da `SPEC.md` e das regras de `DECISOES.md`.
+
+## Diagnóstico para o suporte (relatório técnico)
+
+Para cada situação comum do relatório para o cliente, diga onde o técnico confirma a causa: o log, a tela de
+configuração, o parâmetro ou o registro a conferir. É a ponte entre o que o cliente relata e o que engenharia
+precisaria investigar.
+
+## Exemplo — relatório para o cliente
+
+> **O que há de novo.** Agora é possível consultar um pedido direto pelo número, sem percorrer a lista inteira.
+>
+> **Antes de começar.** Não é preciso preparar nada.
+>
+> **Como usar.** 1. No menu "Pedidos", clique em "Consultar". 2. Digite o número do pedido. 3. O sistema mostra os
+> itens, o frete e o total.
+>
+> **Situações comuns.** "Pedido não encontrado": o número não existe ou foi digitado errado — confira o número no
+> comprovante do cliente.

package/templates/skills/executar-plan/templates/relatorios/CLIENTE.md

@@ -0,0 +1,51 @@
+---
+schema_versao: 1
+tipo: relatorio_cliente
+id: "{{id}}"
+trabalho_tipo: feature
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# {{titulo}}
+
+## O que há de novo
+
+Em duas ou três frases, o que a pessoa passa a conseguir fazer e por que isso ajuda.
+
+## Para quem é
+
+Perfis e setores que vão usar, e onde a funcionalidade aparece (tela, menu, relatório).
+
+## Antes de começar
+
+Permissão, parâmetro, cadastro ou configuração que precisa estar pronto, e quem faz isso — ou "Não é preciso
+preparar nada".
+
+## Como usar
+
+1. Primeiro passo, com o nome da tela ou do botão como aparece para quem usa.
+2. Próximo passo.
+3. O resultado esperado ao final.
+
+## O que muda no que você já fazia
+
+Telas, relatórios ou rotinas que passam a se comportar diferente — ou "Nada muda no que já existia".
+
+## Situações comuns
+
+| O que aparece ou acontece | O que significa | O que fazer |
+|---|---|---|
+| Mensagem ou situação | Explicação simples | Ação recomendada |
+
+## O que ainda não faz
+
+O que ficou para depois, para ninguém prometer ao cliente o que não foi entregue.
+
+## Perguntas frequentes
+
+**Pergunta que o suporte provavelmente vai ouvir?**
+Resposta curta.

package/templates/skills/executar-plan/templates/relatorios/TECNICO.md

@@ -0,0 +1,44 @@
+---
+schema_versao: 1
+tipo: relatorio_tecnico
+id: "{{id}}"
+trabalho_tipo: feature
+titulo: "{{titulo}}"
+status: rascunho
+criado_em: "{{data}}"
+atualizado_em: "{{data}}"
+arquivos: []
+---
+
+# Relatório técnico — {{titulo}}
+
+## O que foi entregue
+
+Resumo do comportamento implementado, com referência aos critérios de aceite do `SPEC.md`.
+
+## Onde está no código
+
+Módulos, arquivos e pontos de entrada, com `arquivo:linha`.
+
+## Configuração e implantação
+
+Variáveis de ambiente, migrações, permissões, parâmetros e a ordem de implantação — ou "nenhuma".
+
+## Decisões
+
+As decisões de `DECISOES.md` que afetam quem mantém ou dá suporte, com o id (`D-NN`).
+
+## Testes que protegem
+
+- Testes críticos: caminho e o que cada um verifica.
+- Suíte completa: comando e resultado.
+
+## Diagnóstico para o suporte
+
+| Sintoma relatado | Onde olhar | Causa provável |
+|---|---|---|
+| O que o cliente diz | Log, tela, tabela ou parâmetro | O que costuma estar errado |
+
+## Pendências e riscos
+
+Itens fora do escopo, bloqueios resolvidos com ressalva e pontos de atenção.

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

@@ -37,8 +37,11 @@ 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**.
+- **Nova tarefa:** faça de 2 a 3 perguntas, uma por vez, para entender o que deve ser feito. Uma delas cobre a
+  **operação**: quem vai usar, o que precisa estar configurado ou liberado antes e o que muda no que as pessoas já
+  fazem. Pule a pergunta só quando o pedido já responder.
+- Resuma o que foi entendido (o que entra, o que fica fora, critérios de aceite, como vai operar) 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.
@@ -48,6 +51,8 @@ mais conservadora.
 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.
+   A seção **Como vai operar** é obrigatória: é dela que o `/executar-plan` tira o relatório para o cliente e para
+   o suporte. Funcionalidade sem efeito visível para quem usa (ajuste interno, rotina técnica) diz isso na seção.
 3. Registre o início do trabalho:
 
    ```bash
@@ -63,6 +68,8 @@ Crie `docs/trabalhos/<id>/PLAN.md` a partir de `templates/PLAN.md`, seguindo `re
 - 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;
+- `relatorios_entrega: true` fica no frontmatter, como vem do template: com ela, o `doctor` exige
+  `relatorios/TECNICO.md` e `relatorios/CLIENTE.md` quando o plano chega a `concluido`;
 - **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.
 
@@ -85,7 +92,8 @@ npx @fontdata/ai-harness evento decisao_registrada --trabalho <id> --nome nova-t
 ## 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.**
+necessários, as decisões registradas e o resumo de **como vai operar**. Avise que, ao concluir, o `/executar-plan`
+entrega `relatorios/TECNICO.md` e `relatorios/CLIENTE.md`. **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.

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

@@ -11,6 +11,7 @@ arquivos: []
 condensado: false
 auditoria_plano: pendente
 causa_raiz: null
+relatorios_entrega: true
 tasks:
   - id: T-01.01
     titulo: "Nome curto da primeira task"

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

@@ -24,6 +24,17 @@ Conclusão (não existe, existe parcialmente ou já existe) e a evidência encon
 
 - Comportamento 1, descrito do ponto de vista de quem usa.
 
+## Como vai operar
+
+Base do relatório para o cliente, escrito no encerramento do `/executar-plan`. Responda do ponto de vista de quem
+usa o sistema e de quem dá suporte.
+
+- **Quem usa:** perfis, telas ou menus onde a funcionalidade aparece.
+- **Antes de usar:** permissão, parâmetro, cadastro ou configuração necessários — ou "nada".
+- **Passo a passo esperado:** o caminho principal, em poucas etapas.
+- **O que muda no que já existe:** telas, relatórios ou rotinas que passam a se comportar diferente.
+- **Dúvidas previsíveis:** o que o suporte provavelmente vai ouvir e a resposta.
+
 ## Fora do escopo
 
 - O que fica explicitamente para depois.