@fontdata/ai-harness 4.0.1 → 4.1.0

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.
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "fontdata",
3
- "version": "4.0.1",
3
+ "version": "4.1.0",
4
4
  "mcpServers": {
5
- "banco_dados": { "command": "npx", "args": ["-y", "@fontdata/ai-harness@4.0.1", "banco-dados-mcp"] }
5
+ "banco_dados": { "command": "npx", "args": ["-y", "@fontdata/ai-harness@4.1.0", "banco-dados-mcp"] }
6
6
  },
7
7
  "description": "Harness de engenharia com IA da Fontdata para Claude Code",
8
8
  "author": { "name": "Fontdata" },
@@ -13,6 +13,7 @@
13
13
  "./templates/agents/auditor-plano.md",
14
14
  "./templates/agents/investigador.md",
15
15
  "./templates/agents/qa.md",
16
+ "./templates/agents/revisor-spec.md",
16
17
  "./templates/agents/revisor-testes.md"
17
18
  ]
18
19
  }
package/README.md CHANGED
@@ -229,6 +229,7 @@ internamente não atrapalha o trabalho — exceto o de segurança em modo bloque
229
229
  | `revisor-testes` | Os testes da task falhariam com a implementação errada? |
230
230
  | `qa` | Critérios de aceite com evidência e suíte completa antes do gate |
231
231
  | `investigador` | Causa raiz de um bug, comprovada ou marcada como hipótese |
232
+ | `revisor-spec` | A SPEC se sustenta sozinha, sem a conversa? |
232
233
  | `auditor-plano` | O plano pode ser executado sem ninguém perguntar nada no meio? |
233
234
 
234
235
  ## Catálogo
package/dist/init.js CHANGED
@@ -207,7 +207,7 @@ async function runWizard(args) {
207
207
  }));
208
208
  }
209
209
  const agents = bail(await p.confirm({
210
- message: 'Instalar os agents somente leitura do harness (revisor-testes, qa, investigador, auditor-plano)?',
210
+ message: 'Instalar os agents somente leitura do harness (revisor-testes, qa, investigador, revisor-spec, auditor-plano)?',
211
211
  initialValue: true,
212
212
  }));
213
213
  const comments = bail(await p.confirm({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fontdata/ai-harness",
3
- "version": "4.0.1",
3
+ "version": "4.1.0",
4
4
  "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.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -40,7 +40,7 @@ Tipos de trabalho: `feature` (`/nova-tarefa`), `bug` (`/resolver-bug`), `auditor
40
40
  `segredo-no-commit` bloqueia commit com segredo; `proteger-contratos` avisa quando SPEC, PLAN ou CLAUDE.md são
41
41
  reescritos durante a execução; `task-so-fecha-verde` avisa sobre task concluída sem suíte verde; `sem-jargao`
42
42
  avisa sobre termo técnico no relatório para o cliente.
43
- - **Agents somente leitura:** `revisor-testes`, `qa`, `investigador` e `auditor-plano`.
43
+ - **Agents somente leitura:** `revisor-testes`, `qa`, `investigador`, `revisor-spec` e `auditor-plano`.
44
44
  - **Verificação:** `npx @fontdata/ai-harness doctor` confere instalação, contrato dos documentos e rastro;
45
45
  `npx @fontdata/ai-harness update` atualiza o que foi instalado sem perder alterações locais.
46
46
 
@@ -0,0 +1,64 @@
1
+ ---
2
+ name: revisor-spec
3
+ description: Revisa a SPEC.md de um trabalho sem o histórico da conversa, procurando excesso de escopo e o que um leitor de fora não entenderia, e devolve uma paráfrase para o usuário comparar com a intenção. Use no Passo 6 do /nova-tarefa, antes do auditor-plano. Somente leitura.
4
+ tools: Read, Grep, Glob, Bash
5
+ model: opus
6
+ ---
7
+
8
+ Você é o **revisor de SPEC** do harness. Quem vai implementar a SPEC não viu a conversa que a gerou: só tem o
9
+ documento e o código. Você lê a SPEC nessas mesmas condições e aponta o que faria essa pessoa travar ou construir
10
+ a coisa errada. Você não edita a SPEC: aponta o que precisa mudar.
11
+
12
+ ## Entrada
13
+
14
+ - Só o caminho de `docs/trabalhos/<id>/SPEC.md`. Você não recebe a conversa nem o resumo dela; se algo só faz
15
+ sentido com esse contexto, isso já é um achado.
16
+ - Leia o código, os arquivos e as decisões que a SPEC cita. Antes de aceitar que algo precisa ser criado, busque
17
+ no código (`Grep`, `Glob`) se já existe.
18
+
19
+ ## Lente 1: visão geral
20
+
21
+ 1. **Especulação:** recurso que ninguém pediu agora, opção ou extensão "para o futuro".
22
+ 2. **Excesso de engenharia:** camada, abstração ou configuração maior do que o problema descrito pede.
23
+ 3. **Reuso:** código novo onde já existe função, módulo ou padrão que resolve. Cite o `arquivo` e o símbolo que
24
+ você encontrou na busca.
25
+ 4. **Sintoma ou causa:** a proposta corrige o efeito visível e deixa a origem do problema no lugar.
26
+
27
+ ## Lente 2: compreensão
28
+
29
+ 1. **Termo não definido:** nome, sigla ou conceito usado sem explicação nem referência no repositório.
30
+ 2. **Decisão citada e não escrita:** "como combinado", "a opção escolhida", sem dizer qual.
31
+ 3. **Suposição implícita:** comportamento atual, dado de entrada ou restrição que a SPEC dá como sabido e não
32
+ está no texto nem no código.
33
+
34
+ Use `Bash` só para ler: busca, histórico do git e rastro do trabalho. Você é somente leitura, então não altere
35
+ arquivos, não faça commit nem push.
36
+
37
+ ## Saída
38
+
39
+ Comece pela paráfrase, nas duas seções abaixo, com estes títulos e de 2 a 5 frases cada, escritas só a partir da
40
+ SPEC e do código:
41
+
42
+ ### O que isto propõe
43
+
44
+ O que muda, para quem e por quê, nas suas palavras.
45
+
46
+ ### Como o sistema funciona hoje, segundo a SPEC
47
+
48
+ O comportamento atual que a SPEC descreve ou pressupõe.
49
+
50
+ O usuário compara essa paráfrase com o que ele quis dizer: se ela não bate com a intenção, a SPEC está ambígua,
51
+ e a divergência entra como achado.
52
+
53
+ Depois:
54
+
55
+ - **Achados** em BLOQUEANTE, IMPORTANTE e SUGESTÃO, cada um com a seção da SPEC afetada, a lente que o
56
+ encontrou e a correção esperada.
57
+ - **Veredito:** `APROVADO` ou `REPROVADO`. Qualquer BLOQUEANTE reprova.
58
+
59
+ Registre o veredito no rastro:
60
+
61
+ ```bash
62
+ npx @fontdata/ai-harness evento agent_veredito --trabalho <id> --nome revisor-spec \
63
+ --dados '{"veredito":"aprovado","motivo":"<resumo em uma linha>"}'
64
+ ```
@@ -17,6 +17,7 @@
17
17
  { "id": "auditor-plano", "file": "agents/auditor-plano.md", "title": "Agent auditor-plano", "description": "Audita o PLAN.md antes da execução: dependências, paralelismo, testes críticos e critérios binários." },
18
18
  { "id": "investigador", "file": "agents/investigador.md", "title": "Agent investigador", "description": "Investiga a causa raiz de um bug antes da correção, com evidência." },
19
19
  { "id": "qa", "file": "agents/qa.md", "title": "Agent qa", "description": "Valida critérios de aceite e roda a suíte completa antes do gate." },
20
+ { "id": "revisor-spec", "file": "agents/revisor-spec.md", "title": "Agent revisor-spec", "description": "Revisa a SPEC.md sem o contexto da conversa e devolve uma paráfrase para comparar com a intenção." },
20
21
  { "id": "revisor-testes", "file": "agents/revisor-testes.md", "title": "Agent revisor-testes", "description": "Verifica se cada teste crítico falharia com a implementação errada." }
21
22
  ],
22
23
  "skills": [
@@ -43,7 +44,7 @@
43
44
  "title": "Slash commands & dia a dia",
44
45
  "commands": [
45
46
  { "id": "resolver-bug", "skill": "skills/resolver-bug", "title": "/resolver-bug", "description": "Investiga a causa raiz, corrige com teste de regressão e entrega relatório técnico e para o cliente.", "recommended": true },
46
- { "id": "nova-tarefa", "skill": "skills/nova-tarefa", "title": "/nova-tarefa", "description": "Verifica se já existe, gera SPEC e PLAN do trabalho, audita o plano e, se confirmado, dispara a execução.", "recommended": true }
47
+ { "id": "nova-tarefa", "skill": "skills/nova-tarefa", "title": "/nova-tarefa", "description": "Verifica se já existe, gera SPEC e PLAN do trabalho, revisa a SPEC, audita o plano e, se confirmado, dispara a execução.", "recommended": true }
47
48
  ]
48
49
  },
49
50
  {
@@ -133,8 +133,8 @@ Liste as divergências do Passo 1 com o trecho atual e o trecho proposto, lado a
133
133
  ## Passo 3 — Seção de orquestração
134
134
 
135
135
  Vale para todo modo que grava o `CLAUDE.md`. Liste os agents do projeto em `.claude/agents/` (nome, descrição e as
136
- pastas que tocam) e os do harness (`revisor-testes`, `qa`, `investigador`, `auditor-plano`; no plugin, com o prefixo
137
- `fontdata:`). Gere ou atualize, no lugar, uma única seção — nunca duplicada:
136
+ pastas que tocam) e os do harness (`revisor-testes`, `qa`, `investigador`, `revisor-spec`, `auditor-plano`; no plugin, com o
137
+ prefixo `fontdata:`). Gere ou atualize, no lugar, uma única seção — nunca duplicada:
138
138
 
139
139
  ```markdown
140
140
  ## Orquestração
@@ -72,8 +72,8 @@ Mostre ao usuário, antes de gravar:
72
72
  ## Guardrails
73
73
 
74
74
  - **Nunca** gravar antes do GATE; **nunca** fazer commit ou push.
75
- - **Não recriar, renomear nem editar** as peças do harness: os agents `revisor-testes`, `qa`, `investigador` e
76
- `auditor-plano`, `.claude/hooks/ai-harness/`, `.claude/hooks/comentarios/` e `.claude/rules/comentarios.md`. O
75
+ - **Não recriar, renomear nem editar** as peças do harness: os agents `revisor-testes`, `qa`, `investigador`,
76
+ `revisor-spec` e `auditor-plano`, `.claude/hooks/ai-harness/`, `.claude/hooks/comentarios/` e `.claude/rules/comentarios.md`. O
77
77
  `update` as mantém; o que é específico do projeto vai para `.claude/rules/harness-projeto.md`.
78
78
  - Todo agent declara `tools:` mínimo e `model:`; hook novo nasce em `aviso`.
79
79
  - Uma fonte por assunto: não repetir em rule, skill ou agent o que já está no `CLAUDE.md` ou em outra rule.
@@ -9,8 +9,8 @@ Cria os **agents de domínio** do projeto em `.claude/agents/`.
9
9
 
10
10
  ## O que já vem com o harness
11
11
 
12
- `revisor-testes`, `qa`, `investigador` e `auditor-plano` são agents somente leitura do harness, instalados pelo
13
- `init` ou disponíveis no plugin como `fontdata:<nome>`. **Não os recrie nem crie agent com esses nomes**: um agent
12
+ `revisor-testes`, `qa`, `investigador`, `revisor-spec` e `auditor-plano` são agents somente leitura do harness,
13
+ instalados pelo `init` ou disponíveis no plugin como `fontdata:<nome>`. **Não os recrie nem crie agent com esses nomes**: um agent
14
14
  do projeto com o mesmo nome substitui o do harness e quebra os gates. Se o projeto precisa que o `qa` rode a suíte
15
15
  de outro jeito, isso vai para a seção "Suíte de testes" da rule de projeto, não para um agent novo.
16
16
 
@@ -27,7 +27,7 @@ de veredito sem justificativa — e não altere nada antes do GATE.
27
27
 
28
28
  ## 2. Agent do projeto com nome de agent do harness
29
29
 
30
- `qa`, `investigador`, `revisor-testes` e `auditor-plano` vêm com o harness. Para cada `.claude/agents/<nome>.md`
30
+ `qa`, `investigador`, `revisor-testes`, `revisor-spec` e `auditor-plano` vêm com o harness. Para cada `.claude/agents/<nome>.md`
31
31
  com um desses nomes:
32
32
 
33
33
  - registrado no lock e sem edição: é a cópia do harness, mantenha;
@@ -106,8 +106,11 @@ Quando o sub-agent disser que terminou:
106
106
  ```
107
107
 
108
108
  4. Só com os vereditos `APROVADO` (inclusive dos portões extras) e `suite_verde` registrado, troque o status da task
109
- para `concluida` e registre `task_concluida`. Reprovada: devolva ao implementador com os achados — no máximo
110
- **2 voltas**; na terceira, vira bloqueio (Passo 4).
109
+ para `concluida` e registre `task_concluida`. Reprovada: classifique os achados por
110
+ `references/resposta-a-achados.md` e devolva ao implementador — no máximo **2 voltas**; na terceira, vira
111
+ bloqueio (Passo 4).
112
+ 5. Gate que não rodou depois de 1 nova tentativa: a task vira bloqueio (Passo 4), nunca `concluida`. Isso não conta
113
+ como volta.
111
114
 
112
115
  ## Passo 6 — Gate de fase e progresso
113
116
 
@@ -49,7 +49,8 @@ sabendo para que a task serve, o sub-agent decide melhor o que a lista de campos
49
49
  - `suite_vermelha` com `--resultado falha` e o número de falhas.
50
50
  - `--resultado` aceita só `ok`, `aviso`, `bloqueio` ou `falha`, e `--task` só o id `T-SS.NN`; o CLI recusa
51
51
  outro valor (o veredito `aprovado`/`reprovado` vai em `--dados`).
52
- 3. **Voltas:** no máximo 2 retornos ao implementador por task. Na terceira reprovação, a task vira bloqueio.
52
+ 3. **Voltas:** no máximo 2 retornos ao implementador por task. Na terceira reprovação, a task vira bloqueio. Antes
53
+ de devolver, o orquestrador classifica os achados por `resposta-a-achados.md`.
53
54
 
54
55
  ## Fechamento
55
56
 
@@ -0,0 +1,35 @@
1
+ # Resposta a achados
2
+
3
+ Vale para os achados de qualquer revisor (`revisor-spec`, `auditor-plano`, `revisor-testes`, `qa`). Antes de
4
+ corrigir ou de pedir nova rodada, o orquestrador classifica cada achado. Quantas voltas cabem é definido pela skill
5
+ que chamou o revisor, não aqui.
6
+
7
+ ## Classificações
8
+
9
+ | Classificação | Quando usar |
10
+ |---|---|
11
+ | **CORRIGIR** | O achado procede. Corrige e segue |
12
+ | **CONTESTAR** | O achado está errado e a evidência é algo que o revisor consegue ler: `arquivo` e símbolo, ou decisão registrada no trabalho. A resposta cita essa evidência |
13
+ | **ESCALAR** | O achado parece errado, mas a evidência está fora do repositório (conversa, sistema externo, conhecimento do usuário). Vai ao usuário no GATE |
14
+ | **RECUSAR** | Só para SUGESTÃO. Fica registrado com o motivo, sem correção |
15
+
16
+ ## Regras
17
+
18
+ - Vontade de contestar não é evidência. Sem `arquivo`, símbolo ou decisão para apontar, o achado é CORRIGIR ou
19
+ ESCALAR.
20
+ - A severidade dada pelo revisor não é rebaixada. Quem discorda de um BLOQUEANTE responde com CONTESTAR e o motivo,
21
+ não com "na verdade é SUGESTÃO".
22
+ - Lacuna de compreensão (o revisor entendeu errado porque o texto não explica) não se contesta: se corrige o texto.
23
+ - Não se acrescenta texto só para satisfazer o revisor quando um leitor humano não precisaria dele. Nesse caso o
24
+ achado é ESCALAR.
25
+
26
+ ## Revisor que não rodou
27
+
28
+ Revisor que falhou, estourou o tempo ou não devolveu relatório **não rodou**. Tenta-se de novo uma vez. Se falhar de
29
+ novo, registra "não rodou". "Não rodou" nunca conta como aprovado nem como zero achados.
30
+
31
+ ## Onde registrar
32
+
33
+ - No relatório ao usuário: cada achado com a classificação e, para CONTESTAR, ESCALAR e RECUSAR, o motivo.
34
+ - Em `DECISOES.md`, quando a classificação vira decisão: contestação aceita, recusa de SUGESTÃO, risco aceito pelo
35
+ usuário num achado escalado.
@@ -45,8 +45,8 @@ As referências ficam na pasta `references` desta skill.
45
45
  2. preencha `.claude/rules/harness-projeto.md` (instalada pelo init): mapa de agents por domínio, portões
46
46
  extras, comando da suíte e verificação manual; apague as seções que não valem;
47
47
  3. `/evoluir-harness skill` — skills antes dos agents, que dependem delas;
48
- 4. `/evoluir-harness agent` — só os agents de domínio: `revisor-testes`, `qa`, `investigador` e
49
- `auditor-plano` já vêm instalados;
48
+ 4. `/evoluir-harness agent` — só os agents de domínio: `revisor-testes`, `qa`, `investigador`,
49
+ `revisor-spec` e `auditor-plano` já vêm instalados;
50
50
  5. `/evoluir-harness code-reviewer`;
51
51
  6. `/evoluir-harness rule` — incluindo a de precedência em código legado, quando houver legado;
52
52
  7. `/evoluir-harness hook` — só hooks específicos dos agents; os hooks do harness já estão ativos;
@@ -83,17 +83,31 @@ decisão, motivo e alternativas descartadas. Para cada decisão:
83
83
  npx @fontdata/ai-harness evento decisao_registrada --trabalho <id> --nome nova-tarefa --dados '{"decisao_id":"D-01"}'
84
84
  ```
85
85
 
86
- ## Passo 6 — Auditoria do plano
87
-
88
- 1. Delegue ao agent **`auditor-plano`** (no plugin, `fontdata:auditor-plano`) a auditoria de `SPEC.md` e `PLAN.md`.
89
- 2. Corrija os achados BLOQUEANTES e IMPORTANTES no plano e peça nova auditoria até o veredito `APROVADO`.
90
- 3. Grave `auditoria_plano: aprovado` e `status: aguardando-aprovacao` no frontmatter do `PLAN.md`.
91
- 4. Rode `npx @fontdata/ai-harness doctor` e confirme que não há achado `contrato-*` neste trabalho.
86
+ ## Passo 6 — Revisão da SPEC e auditoria do plano
87
+
88
+ Responda aos achados de cada revisor por `references/resposta-a-achados.md`.
89
+
90
+ 1. Delegue ao agent **`revisor-spec`** (no plugin, `fontdata:revisor-spec`), num sub-agent novo, a revisão da
91
+ SPEC: passe só o caminho da `SPEC.md`, nunca a conversa. Corrija a SPEC e peça **no máximo 1 reauditoria**.
92
+ - Ainda `REPROVADO`: **não** chame o `auditor-plano`. Mostre ao usuário os BLOQUEANTES escalados e pare. Ele
93
+ decide entre ajustar a SPEC (nova rodada autorizada por ele) e aceitar o risco, que vira decisão no
94
+ `DECISOES.md` e libera o `auditor-plano`.
95
+ - Sem o agent instalado, ou se ele não rodou: registre "não rodou" e siga; o GATE sugere o `update`.
96
+ 2. Delegue ao agent **`auditor-plano`** (no plugin, `fontdata:auditor-plano`) a auditoria de `SPEC.md` e
97
+ `PLAN.md`, com **no máximo 1 reauditoria**. Grave no frontmatter do `PLAN.md`:
98
+ - veredito final `APROVADO` → `auditoria_plano: aprovado`;
99
+ - ainda `REPROVADO` → `auditoria_plano: reprovado`, e o BLOQUEANTE vai ao GATE como escalado. O
100
+ `/executar-plan` só roda com `aprovado`: só uma nova rodada autorizada pelo usuário no GATE aprova o plano;
101
+ - não rodou → `auditoria_plano: pendente`.
102
+ 3. Grave `status: aguardando-aprovacao` no `PLAN.md`, rode `npx @fontdata/ai-harness doctor` e confirme que não há
103
+ achado `contrato-*` neste trabalho.
92
104
 
93
105
  ## Passo 7 — 🚦 GATE de aprovação
94
106
 
95
107
  Mostre ao usuário: os caminhos gravados, as tasks por fase (quais rodam em paralelo), quantos agents serão
96
- necessários, as decisões registradas e o resumo de **como vai operar**. Avise que, ao concluir, o `/executar-plan`
108
+ necessários, as decisões registradas e o resumo de **como vai operar**. Mostre também a paráfrase da SPEC feita pelo
109
+ `revisor-spec`, para ele comparar com o que pediu, os achados escalados e recusados e qualquer revisor que não
110
+ rodou (sem o `revisor-spec` instalado, sugira `npx @fontdata/ai-harness update`). Avise que, ao concluir, o `/executar-plan`
97
111
  entrega `relatorios/TECNICO.md` e `relatorios/CLIENTE.md`. **Peça aprovação explícita.**
98
112
 
99
113
  - Com aprovação, grave `status: aprovado` no `SPEC.md`.
@@ -0,0 +1,35 @@
1
+ # Resposta a achados
2
+
3
+ Vale para os achados de qualquer revisor (`revisor-spec`, `auditor-plano`, `revisor-testes`, `qa`). Antes de
4
+ corrigir ou de pedir nova rodada, o orquestrador classifica cada achado. Quantas voltas cabem é definido pela skill
5
+ que chamou o revisor, não aqui.
6
+
7
+ ## Classificações
8
+
9
+ | Classificação | Quando usar |
10
+ |---|---|
11
+ | **CORRIGIR** | O achado procede. Corrige e segue |
12
+ | **CONTESTAR** | O achado está errado e a evidência é algo que o revisor consegue ler: `arquivo` e símbolo, ou decisão registrada no trabalho. A resposta cita essa evidência |
13
+ | **ESCALAR** | O achado parece errado, mas a evidência está fora do repositório (conversa, sistema externo, conhecimento do usuário). Vai ao usuário no GATE |
14
+ | **RECUSAR** | Só para SUGESTÃO. Fica registrado com o motivo, sem correção |
15
+
16
+ ## Regras
17
+
18
+ - Vontade de contestar não é evidência. Sem `arquivo`, símbolo ou decisão para apontar, o achado é CORRIGIR ou
19
+ ESCALAR.
20
+ - A severidade dada pelo revisor não é rebaixada. Quem discorda de um BLOQUEANTE responde com CONTESTAR e o motivo,
21
+ não com "na verdade é SUGESTÃO".
22
+ - Lacuna de compreensão (o revisor entendeu errado porque o texto não explica) não se contesta: se corrige o texto.
23
+ - Não se acrescenta texto só para satisfazer o revisor quando um leitor humano não precisaria dele. Nesse caso o
24
+ achado é ESCALAR.
25
+
26
+ ## Revisor que não rodou
27
+
28
+ Revisor que falhou, estourou o tempo ou não devolveu relatório **não rodou**. Tenta-se de novo uma vez. Se falhar de
29
+ novo, registra "não rodou". "Não rodou" nunca conta como aprovado nem como zero achados.
30
+
31
+ ## Onde registrar
32
+
33
+ - No relatório ao usuário: cada achado com a classificação e, para CONTESTAR, ESCALAR e RECUSAR, o motivo.
34
+ - Em `DECISOES.md`, quando a classificação vira decisão: contestação aceita, recusa de SUGESTÃO, risco aceito pelo
35
+ usuário num achado escalado.
@@ -33,7 +33,8 @@ Se o relato não veio, peça os detalhes antes de começar: o que acontece, o qu
33
33
  - a **primeira task é sempre o teste de regressão** que reproduz o bug e falha hoje;
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
- grava `auditoria_plano: aprovado` ou `reprovado`. Não há outros valores.
36
+ grava `auditoria_plano: aprovado` ou `reprovado`. Responda aos achados por `references/resposta-a-achados.md`,
37
+ com **no máximo 1 reauditoria**. `auditor-plano` que não rodou grava `pendente`. Não há outros valores.
37
38
  3. Quando o trabalho registrar uma decisão ou um bloqueio, crie `DECISOES.md` a partir de `templates/DECISOES.md`
38
39
  e `BLOQUEIOS.md` a partir de `templates/BLOQUEIOS.md`, sempre com o frontmatter. Nunca os escreva do zero.
39
40
  4. Registre o início:
@@ -0,0 +1,35 @@
1
+ # Resposta a achados
2
+
3
+ Vale para os achados de qualquer revisor (`revisor-spec`, `auditor-plano`, `revisor-testes`, `qa`). Antes de
4
+ corrigir ou de pedir nova rodada, o orquestrador classifica cada achado. Quantas voltas cabem é definido pela skill
5
+ que chamou o revisor, não aqui.
6
+
7
+ ## Classificações
8
+
9
+ | Classificação | Quando usar |
10
+ |---|---|
11
+ | **CORRIGIR** | O achado procede. Corrige e segue |
12
+ | **CONTESTAR** | O achado está errado e a evidência é algo que o revisor consegue ler: `arquivo` e símbolo, ou decisão registrada no trabalho. A resposta cita essa evidência |
13
+ | **ESCALAR** | O achado parece errado, mas a evidência está fora do repositório (conversa, sistema externo, conhecimento do usuário). Vai ao usuário no GATE |
14
+ | **RECUSAR** | Só para SUGESTÃO. Fica registrado com o motivo, sem correção |
15
+
16
+ ## Regras
17
+
18
+ - Vontade de contestar não é evidência. Sem `arquivo`, símbolo ou decisão para apontar, o achado é CORRIGIR ou
19
+ ESCALAR.
20
+ - A severidade dada pelo revisor não é rebaixada. Quem discorda de um BLOQUEANTE responde com CONTESTAR e o motivo,
21
+ não com "na verdade é SUGESTÃO".
22
+ - Lacuna de compreensão (o revisor entendeu errado porque o texto não explica) não se contesta: se corrige o texto.
23
+ - Não se acrescenta texto só para satisfazer o revisor quando um leitor humano não precisaria dele. Nesse caso o
24
+ achado é ESCALAR.
25
+
26
+ ## Revisor que não rodou
27
+
28
+ Revisor que falhou, estourou o tempo ou não devolveu relatório **não rodou**. Tenta-se de novo uma vez. Se falhar de
29
+ novo, registra "não rodou". "Não rodou" nunca conta como aprovado nem como zero achados.
30
+
31
+ ## Onde registrar
32
+
33
+ - No relatório ao usuário: cada achado com a classificação e, para CONTESTAR, ESCALAR e RECUSAR, o motivo.
34
+ - Em `DECISOES.md`, quando a classificação vira decisão: contestação aceita, recusa de SUGESTÃO, risco aceito pelo
35
+ usuário num achado escalado.