@fontdata/ai-harness 4.0.0 → 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.
- package/.claude-plugin/plugin.json +3 -2
- package/README.md +1 -0
- package/dist/init.js +1 -1
- package/dist/install/plan.js +25 -5
- package/dist/update/update.js +1 -1
- package/package.json +1 -1
- package/templates/CLAUDE.md +1 -1
- package/templates/agents/revisor-spec.md +64 -0
- package/templates/catalog.json +2 -1
- package/templates/commands/sincronizar-claude-md.md +2 -2
- package/templates/skills/evoluir-harness/SKILL.md +2 -2
- package/templates/skills/evoluir-harness/references/agent.md +2 -2
- package/templates/skills/evoluir-harness/references/auditoria.md +1 -1
- package/templates/skills/executar-plan/SKILL.md +5 -2
- package/templates/skills/executar-plan/references/delegacao.md +2 -1
- package/templates/skills/executar-plan/references/resposta-a-achados.md +35 -0
- package/templates/skills/harness/SKILL.md +2 -2
- package/templates/skills/nova-tarefa/SKILL.md +21 -7
- package/templates/skills/nova-tarefa/references/resposta-a-achados.md +35 -0
- package/templates/skills/resolver-bug/SKILL.md +5 -2
- package/templates/skills/resolver-bug/references/resposta-a-achados.md +35 -0
- package/templates/skills/resolver-bug/templates/BLOQUEIOS.md +30 -0
- package/templates/skills/resolver-bug/templates/DECISOES.md +20 -0
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "fontdata",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.1.0",
|
|
4
4
|
"mcpServers": {
|
|
5
|
-
"banco_dados": { "command": "npx", "args": ["-y", "@fontdata/ai-harness@4.
|
|
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/dist/install/plan.js
CHANGED
|
@@ -3,7 +3,7 @@ import { join, sep } from 'node:path';
|
|
|
3
3
|
import { allCommands, recommendedCommands, templatesDir } from '../catalog.js';
|
|
4
4
|
import { runnableIds, suggestIds } from '../run.js';
|
|
5
5
|
import { applyAtomically } from './atomic.js';
|
|
6
|
-
import { buildLockItem, LOCK_VERSION, readLock, writeLock } from './lock.js';
|
|
6
|
+
import { buildLockItem, hashContent, LOCK_VERSION, readLock, writeLock } from './lock.js';
|
|
7
7
|
import { HOOKS_ITEM_ID, PROJECT_HOOKS_DIR, projectHooksConfig } from './hooks.js';
|
|
8
8
|
import { neededSkillsFor, resolveSelection } from './selection.js';
|
|
9
9
|
import { BANCO_MCP_NOME, bancoMcpServer, MCP_PATH, mergeMcpServers } from './mcp.js';
|
|
@@ -99,6 +99,7 @@ function selectCommands(catalog, options) {
|
|
|
99
99
|
export function planInstall(catalog, root, options) {
|
|
100
100
|
const wantMaster = options.includeMaster || options.commands.includes(catalog.master.id);
|
|
101
101
|
const { selected, autoAdded } = resolveSelection(catalog, selectCommands(catalog, options), wantMaster);
|
|
102
|
+
const alteradosLocalmente = [];
|
|
102
103
|
const plan = {
|
|
103
104
|
files: [],
|
|
104
105
|
skipped: [],
|
|
@@ -108,15 +109,30 @@ export function planInstall(catalog, root, options) {
|
|
|
108
109
|
registerHooks: Boolean(options.hooks),
|
|
109
110
|
registerComments: Boolean(options.comments),
|
|
110
111
|
comentariosRecusados: !options.comments,
|
|
112
|
+
alteradosLocalmente,
|
|
111
113
|
};
|
|
114
|
+
const hashNoLock = new Map((readLock(root)?.itens ?? []).flatMap((item) => item.arquivos.map((a) => [a.caminho, a.sha256])));
|
|
112
115
|
const add = (tipo, id) => {
|
|
113
116
|
const paths = [];
|
|
114
117
|
for (const entry of itemSources(catalog, tipo, id) ?? []) {
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
+
const content = readFileSync(entry.source);
|
|
119
|
+
const target = join(root, entry.path);
|
|
120
|
+
if (existsSync(target)) {
|
|
121
|
+
const local = hashContent(readFileSync(target));
|
|
122
|
+
if (local === hashContent(content)) {
|
|
123
|
+
paths.push(entry.path);
|
|
124
|
+
continue;
|
|
125
|
+
}
|
|
126
|
+
if (local !== hashNoLock.get(entry.path)) {
|
|
127
|
+
alteradosLocalmente.push(entry.path);
|
|
128
|
+
continue;
|
|
129
|
+
}
|
|
130
|
+
if (options.conflict === 'skip') {
|
|
131
|
+
plan.skipped.push(entry.path);
|
|
132
|
+
continue;
|
|
133
|
+
}
|
|
118
134
|
}
|
|
119
|
-
plan.files.push({ path: entry.path, content
|
|
135
|
+
plan.files.push({ path: entry.path, content });
|
|
120
136
|
paths.push(entry.path);
|
|
121
137
|
}
|
|
122
138
|
if (paths.length)
|
|
@@ -211,6 +227,10 @@ export function describePlan(plan) {
|
|
|
211
227
|
if (plan.skipped.length) {
|
|
212
228
|
lines.push(`Já existentes, mantidos (${plan.skipped.length}):`, ...plan.skipped.map((path) => ` = ${path}`));
|
|
213
229
|
}
|
|
230
|
+
const alterados = plan.alteradosLocalmente ?? [];
|
|
231
|
+
if (alterados.length) {
|
|
232
|
+
lines.push(`Alterados localmente, mantidos (${alterados.length}); para usar a versão do pacote, apague o arquivo e rode o comando de novo:`, ...alterados.map((path) => ` ! ${path}`));
|
|
233
|
+
}
|
|
214
234
|
if (plan.autoAdded.length)
|
|
215
235
|
lines.push(`Adicionados como dependência: ${plan.autoAdded.join(', ')}`);
|
|
216
236
|
if (plan.claudeMdBackup)
|
package/dist/update/update.js
CHANGED
|
@@ -293,7 +293,7 @@ export function applyUpdate(root, report, options, pkg, now = new Date()) {
|
|
|
293
293
|
for (const added of addedItems.values()) {
|
|
294
294
|
itens.push({ ...added, arquivos: added.arquivos.sort((a, b) => a.caminho.localeCompare(b.caminho)) });
|
|
295
295
|
}
|
|
296
|
-
// Com o hash do template, o arquivo do projeto aparece como modificado-local
|
|
296
|
+
// Com o hash do template, o arquivo do projeto aparece como modificado-local, que o update nunca regrava.
|
|
297
297
|
if (report.registrarHookComentarios) {
|
|
298
298
|
itens.push({ tipo: 'hook', id: 'comentarios', arquivos: [{ caminho: COMMENTS_HOOK_PATH, sha256: hashContent(readFileSync(COMMENTS_HOOK_TEMPLATE)) }] });
|
|
299
299
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fontdata/ai-harness",
|
|
3
|
-
"version": "4.
|
|
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": {
|
package/templates/CLAUDE.md
CHANGED
|
@@ -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
|
+
```
|
package/templates/catalog.json
CHANGED
|
@@ -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
|
|
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
|
|
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,
|
|
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:
|
|
110
|
-
**2 voltas**; na terceira, vira
|
|
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
|
|
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 —
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
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**.
|
|
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,8 +33,11 @@ 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`.
|
|
37
|
-
|
|
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.
|
|
38
|
+
3. Quando o trabalho registrar uma decisão ou um bloqueio, crie `DECISOES.md` a partir de `templates/DECISOES.md`
|
|
39
|
+
e `BLOQUEIOS.md` a partir de `templates/BLOQUEIOS.md`, sempre com o frontmatter. Nunca os escreva do zero.
|
|
40
|
+
4. Registre o início:
|
|
38
41
|
|
|
39
42
|
```bash
|
|
40
43
|
npx @fontdata/ai-harness evento trabalho_iniciado --trabalho <id> --nome resolver-bug --dados '{"trabalho_tipo":"bug"}'
|
|
@@ -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.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_versao: 1
|
|
3
|
+
tipo: bloqueios
|
|
4
|
+
id: "{{id}}"
|
|
5
|
+
trabalho_tipo: bug
|
|
6
|
+
titulo: "Bloqueios — {{titulo}}"
|
|
7
|
+
status: aberto
|
|
8
|
+
criado_em: "{{data}}"
|
|
9
|
+
atualizado_em: "{{data}}"
|
|
10
|
+
arquivos: []
|
|
11
|
+
bloqueios:
|
|
12
|
+
- id: B-01
|
|
13
|
+
task: T-01.02
|
|
14
|
+
status: aberto
|
|
15
|
+
aberto_em: "{{data}}"
|
|
16
|
+
resolvido_em: null
|
|
17
|
+
decisao: null
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
# Bloqueios — {{titulo}}
|
|
21
|
+
|
|
22
|
+
Dúvidas que pararam uma task durante a correção. Cada bloqueio é resolvido por uma decisão registrada em
|
|
23
|
+
`DECISOES.md`; depois disso, a task volta para `pendente`.
|
|
24
|
+
|
|
25
|
+
## B-01 — Pergunta objetiva que precisa de resposta
|
|
26
|
+
|
|
27
|
+
- **Task:** T-01.02
|
|
28
|
+
- **Contexto:** o que foi encontrado e por que a task não pode seguir.
|
|
29
|
+
- **Opções:** as alternativas possíveis, com a consequência de cada uma.
|
|
30
|
+
- **O que destrava:** a informação ou a escolha necessária.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
---
|
|
2
|
+
schema_versao: 1
|
|
3
|
+
tipo: decisoes
|
|
4
|
+
id: "{{id}}"
|
|
5
|
+
trabalho_tipo: bug
|
|
6
|
+
titulo: "Decisões — {{titulo}}"
|
|
7
|
+
status: ativo
|
|
8
|
+
criado_em: "{{data}}"
|
|
9
|
+
atualizado_em: "{{data}}"
|
|
10
|
+
arquivos: []
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Decisões — {{titulo}}
|
|
14
|
+
|
|
15
|
+
Decisões tomadas durante a investigação e a correção. Uma decisão que muda não é apagada: registre uma nova
|
|
16
|
+
dizendo qual ela substitui.
|
|
17
|
+
|
|
18
|
+
| # | Data | Decisão | Motivo | Alternativas descartadas |
|
|
19
|
+
|---|---|---|---|---|
|
|
20
|
+
| D-01 | {{data}} | Como a causa raiz é corrigida | Por que, com a correção mais conservadora | Que outra correção não foi escolhida |
|