@fontdata/ai-harness 4.2.0 → 4.3.1

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.
Files changed (40) hide show
  1. package/.claude-plugin/plugin.json +2 -2
  2. package/README.md +10 -0
  3. package/dist/atalhos/atalhos.js +59 -0
  4. package/dist/cli.js +12 -0
  5. package/dist/comentarios/command.js +7 -1
  6. package/dist/comentarios/instalar.js +63 -11
  7. package/dist/contratos/artefatos.js +13 -5
  8. package/dist/fontes/listar.js +80 -0
  9. package/dist/mapa/config.js +152 -0
  10. package/dist/mapa/extratores/csharp.js +33 -0
  11. package/dist/mapa/extratores/dart.js +31 -0
  12. package/dist/mapa/extratores/go.js +17 -0
  13. package/dist/mapa/extratores/index.js +33 -0
  14. package/dist/mapa/extratores/java.js +7 -0
  15. package/dist/mapa/extratores/js.js +22 -0
  16. package/dist/mapa/extratores/kotlin.js +18 -0
  17. package/dist/mapa/extratores/pascal.js +39 -0
  18. package/dist/mapa/extratores/php.js +18 -0
  19. package/dist/mapa/extratores/python.js +19 -0
  20. package/dist/mapa/extratores/rust.js +19 -0
  21. package/dist/mapa/extratores/tipos.js +1 -0
  22. package/dist/mapa/mapa.js +123 -0
  23. package/dist/update/update.js +14 -2
  24. package/dist/versao/config.js +1 -1
  25. package/package.json +1 -1
  26. package/templates/agents/auditor-plano.md +4 -1
  27. package/templates/agents/investigador.md +3 -0
  28. package/templates/agents/qa.md +1 -0
  29. package/templates/agents/revisor-spec.md +6 -3
  30. package/templates/agents/revisor-testes.md +3 -1
  31. package/templates/commands/revisar-pr.md +21 -3
  32. package/templates/hooks/comentarios/check.mjs +208 -41
  33. package/templates/rules/comentarios.md +8 -2
  34. package/templates/skills/auditar-performance/SKILL.md +11 -1
  35. package/templates/skills/auditar-seguranca/SKILL.md +8 -0
  36. package/templates/skills/auditar-ui/SKILL.md +8 -0
  37. package/templates/skills/evoluir-harness/references/code-reviewer.md +16 -5
  38. package/templates/skills/executar-plan/references/delegacao.md +14 -3
  39. package/templates/skills/nova-tarefa/references/isso-ja-existe.md +3 -0
  40. package/templates/skills/resolver-bug/SKILL.md +8 -2
@@ -1,6 +1,7 @@
1
1
  #!/usr/bin/env node
2
+ import { spawnSync } from 'node:child_process';
2
3
  import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, openSync, closeSync, renameSync, rmSync, statSync } from 'node:fs';
3
- import { extname, relative, join, dirname, sep } from 'node:path';
4
+ import { extname, relative, join, dirname, sep, parse } from 'node:path';
4
5
 
5
6
  const MAX_BLOCO = Number(process.env.COMENTARIOS_MAX_BLOCO ?? 3);
6
7
  const MAX_DOCSTRING = Number(process.env.COMENTARIOS_MAX_DOCSTRING ?? 5);
@@ -10,19 +11,24 @@ const EXTENSOES = new Set([
10
11
  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
11
12
  '.py', '.go', '.rs', '.java', '.cs', '.php',
12
13
  '.pas', '.dpr', '.dpk', '.lpr', '.sql', '.sh', '.bash', '.zsh',
13
- '.ps1', '.psm1', '.bat', '.cmd',
14
+ '.ps1', '.psm1', '.bat', '.cmd', '.dart', '.kt', '.kts',
14
15
  ]);
15
16
 
16
- const IGNORAR = [
17
- /node_modules/,
18
- /[\\/]\.git[\\/]/,
19
- /[\\/](dist|build|coverage|out|\.next|\.nuxt|vendor|migrations|generated|__generated__)[\\/]/,
20
- /\.d\.ts$/,
21
- /\.(test|spec)\.[jt]sx?$/,
17
+ const EXTENSOES_RECENTES = new Set(['.dart', '.kt', '.kts']);
18
+
19
+ // Cópia do critério de src/fontes/listar.ts: o hook é instalado sozinho, e o teste de paridade compara os dois.
20
+ const PASTAS_EXCLUIDAS = new Set([
21
+ 'node_modules', 'docs', 'doc', 'dist', 'build', 'coverage', 'out', 'vendor', 'migrations', 'generated',
22
+ '__generated__', '__history', '__recovery', 'fixtures', 'samples', 'examples', 'exemplos',
23
+ ]);
24
+
25
+ const ARQUIVO_EXCLUIDO = [
26
+ /\.d\.ts$/, /\.(test|spec)\.[jt]sx?$/, /\.min\.js$/i, /bundle[^/]*\.js$/i,
27
+ /\.(g|freezed|mocks|gr)\.dart$/, /^generated_plugin_registrant\.dart$/,
22
28
  ];
23
29
 
24
30
  const CABECALHO_PERMITIDO =
25
- /eslint|ts-nocheck|ts-check|ts-ignore|prettier|@license|copyright|spdx|jshint|globals|use (strict|client|server)|code generated|do not edit|auto-generated/i;
31
+ /eslint|ts-nocheck|ts-check|ts-ignore|prettier|@license|copyright|spdx|jshint|globals|use (strict|client|server)|code generated|generated code|do not edit|do not modify|auto-generated/i;
26
32
 
27
33
  const BANNER = /^[-=─-╿_*#~+]{3,}|[-=─-╿_*#~+]{3,}$/;
28
34
 
@@ -40,12 +46,17 @@ const RASTREIO = [
40
46
  ];
41
47
 
42
48
  const DATA = /(^|[^"'\w])20\d{2}-\d{2}-\d{2}([^"'\w]|$)/;
43
- const CODIGO_TOKEN = /(^|\s)(const|let|var|function|return|if|for|while|await|import|export|def|class)\b/;
49
+ const tokensDeCodigo = (...extras) =>
50
+ new RegExp(`(^|\\s)(${['const', 'let', 'var', 'function', 'return', 'if', 'for', 'while', 'await', 'import', 'export', 'def', 'class', ...extras].join('|')})\\b`);
51
+ const CODIGO_TOKEN = tokensDeCodigo();
52
+ const CODIGO_TOKEN_KOTLIN = tokensDeCodigo('fun', 'val');
44
53
  const CODIGO_FIM = /[;{}]\s*$/;
45
54
 
46
55
  const so = (...exts) => new Set(exts);
47
56
  const JS = so('.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs');
48
- const C_LIKE = so(...JS, '.go', '.rs', '.java', '.cs', '.php');
57
+ const DART = so('.dart');
58
+ const KOTLIN = so('.kt', '.kts');
59
+ const C_LIKE = so(...JS, '.go', '.rs', '.java', '.cs', '.php', ...DART, ...KOTLIN);
49
60
  const PASCAL = so('.pas', '.dpr', '.dpk', '.lpr');
50
61
  const SHELL = so('.sh', '.bash', '.zsh');
51
62
  const POWERSHELL = so('.ps1', '.psm1');
@@ -75,6 +86,8 @@ const DIRETIVAS = [
75
86
  [so('.java'), /^\/[/*]\s*(noinspection\b|NOSONAR\b|CHECKSTYLE[:.]|\$NON-NLS)/],
76
87
  [so('.cs'), /^#\s*(region|endregion|if|elif|else|endif|define|undef|pragma|nullable|warning|error|line)\b/],
77
88
  [so('.cs'), /^\/\/\s*(ReSharper\s|<\/?auto-generated)/i],
89
+ [DART, /^\/\/\s*(ignore_for_file:|ignore:|coverage:ignore-(line|start|end|file)\b|dart format (off|on)\b|@dart=)/],
90
+ [KOTLIN, /^\/\/\s*(ktlint-disable\b|ktlint-enable\b|noinspection\b)/],
78
91
  [so('.php'), /^\/[/*]\*?\s*(phpcs:|@phpstan-|@psalm-|@codeCoverageIgnore|@noinspection\b|@var\s)/],
79
92
  [so('.sql'), /^\/\*[!+]/],
80
93
  [so('.sql'), /^--\s*(liquibase\s|changeset\s|rollback\b|precondition|comment:|validCheckSum\b|ignoreLines:|\+(goose|migrate)\b|name:\s*\S+\s*:|noqa\b|sqlfluff:|#?(region|endregion)\b)/i],
@@ -167,16 +180,65 @@ function classificar(linhas, ext) {
167
180
 
168
181
  const ehTexto = (c) => typeof c === 'string';
169
182
 
170
- function analisar(caminho, fonte) {
171
- const ext = extname(caminho);
183
+ function linhasDoFonte(caminho, fonte) {
172
184
  const linhas = fonte.split('\n');
173
- if (PASCAL.has(ext)) {
185
+ if (PASCAL.has(extname(caminho))) {
174
186
  const fim = linhas.findLastIndex((l) => /^\s*end\.\s*$/i.test(l));
175
187
  if (fim >= 0) linhas.length = fim + 1;
176
188
  }
189
+ return linhas;
190
+ }
191
+
192
+ const MARCADOR_ATALHO = /^(TODO|FIXME):(.*)$/;
193
+
194
+ /**
195
+ * Lê `TODO:`/`FIXME:` de um texto de comentário; null quando não é marcador.
196
+ * O gatilho é o que vem depois da primeira vírgula e fica null se o limite ou ele estiver vazio.
197
+ */
198
+ function lerAtalho(comentario) {
199
+ const m = MARCADOR_ATALHO.exec(comentario);
200
+ if (!m) return null;
201
+ const resto = m[2].trim();
202
+ const virgula = resto.indexOf(',');
203
+ const limite = (virgula === -1 ? resto : resto.slice(0, virgula)).trim();
204
+ const gatilho = virgula === -1 ? '' : resto.slice(virgula + 1).trim();
205
+ return { marcador: m[1], limite, gatilho: limite && gatilho ? gatilho : null };
206
+ }
207
+
208
+ /** Atalhos das linhas de comentário do arquivo, com a linha contada a partir de 1. */
209
+ function listarAtalhos(caminho, fonte) {
210
+ const linhas = linhasDoFonte(caminho, fonte);
211
+ const saida = [];
212
+ classificar(linhas, extname(caminho)).forEach((c, i) => {
213
+ const atalho = ehTexto(c) ? lerAtalho(c) : null;
214
+ if (atalho) saida.push({ linha: i + 1, texto: linhas[i].trim(), ...atalho });
215
+ });
216
+ return saida;
217
+ }
218
+
219
+ function linhasDoToolInput(toolInput) {
220
+ const textos = [toolInput?.content, toolInput?.new_string, ...(toolInput?.edits ?? []).map((e) => e?.new_string)];
221
+ return new Set(textos.filter((t) => typeof t === 'string').flatMap((t) => t.split('\n').map((l) => l.trim())));
222
+ }
223
+
224
+ function avisoAtalhos(caminho, fonte, toolInput, rel) {
225
+ const novas = linhasDoToolInput(toolInput);
226
+ const sem = listarAtalhos(caminho, fonte).filter((a) => a.gatilho === null && novas.has(a.texto));
227
+ if (!sem.length) return null;
228
+ return [
229
+ `[comentarios] ${sem.length} TODO/FIXME sem gatilho (só aviso, não bloqueia):`,
230
+ ...sem.map((a) => ` ${rel}:${a.linha} ${a.texto}`),
231
+ 'Formato esperado: TODO: <limite>, <quando revisitar> — ex.: // TODO: sem paginação, quando passar de 1000 itens',
232
+ ].join('\n');
233
+ }
234
+
235
+ function analisar(caminho, fonte) {
236
+ const ext = extname(caminho);
237
+ const linhas = linhasDoFonte(caminho, fonte);
177
238
  const achados = [];
178
239
  const marca = (linha, msg) => achados.push({ linha, msg });
179
240
  const ehComentario = classificar(linhas, ext);
241
+ const codigoToken = KOTLIN.has(ext) ? CODIGO_TOKEN_KOTLIN : CODIGO_TOKEN;
180
242
 
181
243
  let primeiroCodigo = -1;
182
244
  for (let i = 0; i < linhas.length; i++) {
@@ -204,7 +266,7 @@ function analisar(caminho, fonte) {
204
266
  }
205
267
  if (DATA.test(texto)) marca(inicio + 1, 'data de mudança no comentário — o git já registra isso');
206
268
  for (let k = 0; k < conteudo.length; k++) {
207
- if (conteudo[k] && CODIGO_TOKEN.test(conteudo[k]) && CODIGO_FIM.test(conteudo[k])) {
269
+ if (conteudo[k] && codigoToken.test(conteudo[k]) && CODIGO_FIM.test(conteudo[k])) {
208
270
  marca(inicio + k + 1, 'código comentado — apague, o git guarda');
209
271
  break;
210
272
  }
@@ -236,17 +298,66 @@ function analisar(caminho, fonte) {
236
298
  const raiz = process.env.CLAUDE_PROJECT_DIR || process.cwd();
237
299
  const BASELINE = join(raiz, '.claude', 'hooks', 'comentarios', 'baseline.json');
238
300
 
239
- // Pasta oculta na raiz (.claude, .ai-harness, .vscode...) é de ferramenta, não do projeto.
240
- function emPastaOculta(caminho) {
241
- const rel = relative(raiz, caminho);
242
- if (!rel || rel.startsWith('..')) return false;
243
- return rel.split(sep).slice(0, -1).some((parte) => parte.startsWith('.'));
301
+ function pastaExcluida(nome) {
302
+ return nome.startsWith('.') || PASTAS_EXCLUIDAS.has(nome.toLowerCase());
303
+ }
304
+
305
+ function dependenciaBoss(base, pastas) {
306
+ return pastas.some((nome, i) => nome.toLowerCase() === 'modules' && existsSync(join(base, ...pastas.slice(0, i), 'boss.json')));
307
+ }
308
+
309
+ function ehFonte(base, rel) {
310
+ const partes = rel.split(/[\\/]/).filter((p) => p !== '' && p !== '.');
311
+ const nome = partes.pop();
312
+ if (!nome || !EXTENSOES.has(extname(nome))) return false;
313
+ if (ARQUIVO_EXCLUIDO.some((re) => re.test(nome))) return false;
314
+ if (partes.some(pastaExcluida)) return false;
315
+ return !dependenciaBoss(base, partes);
244
316
  }
245
317
 
246
318
  function elegivel(caminho) {
247
- return EXTENSOES.has(extname(caminho)) && !IGNORAR.some((re) => re.test(caminho)) && !emPastaOculta(caminho);
319
+ const rel = relative(raiz, caminho);
320
+ if (!rel || rel.startsWith('..')) return ehFonte(parse(caminho).root, caminho);
321
+ return ehFonte(raiz, rel) && !ignoradoPeloGit(rel);
322
+ }
323
+
324
+ // Só o status 0 é "ignorado": fora de repositório (128) ou sem git, vale o critério por caminho.
325
+ function ignoradoPeloGit(rel) {
326
+ const r = spawnSync('git', ['check-ignore', '-q', '--', rel], { cwd: raiz, stdio: 'ignore' });
327
+ return !r.error && r.status === 0;
248
328
  }
249
329
 
330
+ function listarPeloGit() {
331
+ const r = spawnSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], {
332
+ cwd: raiz,
333
+ encoding: 'utf8',
334
+ maxBuffer: 64 * 1024 * 1024,
335
+ stdio: ['ignore', 'pipe', 'ignore'],
336
+ });
337
+ if (r.error || r.status !== 0) return null;
338
+ return [...new Set(r.stdout.split('\0').filter((c) => c !== ''))].filter((c) => {
339
+ try { return statSync(join(raiz, c)).isFile(); } catch { return false; }
340
+ });
341
+ }
342
+
343
+ function varrer(prefixo = '', saida = []) {
344
+ let itens;
345
+ try { itens = readdirSync(join(raiz, prefixo), { withFileTypes: true }); } catch { return saida; }
346
+ for (const item of itens) {
347
+ const rel = prefixo ? `${prefixo}/${item.name}` : item.name;
348
+ if (item.isDirectory()) {
349
+ if (!pastaExcluida(item.name)) varrer(rel, saida);
350
+ } else if (item.isFile()) saida.push(rel);
351
+ }
352
+ return saida;
353
+ }
354
+
355
+ function listarFontes(candidatos = listarPeloGit() ?? varrer()) {
356
+ return candidatos.filter((c) => ehFonte(raiz, c)).sort();
357
+ }
358
+
359
+ const chaveDe = (rel) => rel.split('/').join(sep);
360
+
250
361
  function gravarAtomico(arquivo, conteudo) {
251
362
  const temp = `${arquivo}.${process.pid}.tmp`;
252
363
  writeFileSync(temp, conteudo);
@@ -256,7 +367,7 @@ function gravarAtomico(arquivo, conteudo) {
256
367
  const esperar = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
257
368
 
258
369
  // Vários agents editam em paralelo: a trava serializa o reler-e-gravar, e cada um mexe só na própria chave.
259
- function atualizarBaseline(chave, valor) {
370
+ function comTrava(alterar) {
260
371
  const trava = `${BASELINE}.lock`;
261
372
  let travado = false;
262
373
  for (let tentativa = 0; tentativa < 300 && !travado; tentativa++) {
@@ -267,42 +378,94 @@ function atualizarBaseline(chave, valor) {
267
378
  }
268
379
  try {
269
380
  const atual = JSON.parse(readFileSync(BASELINE, 'utf8'));
270
- if (valor === 0) delete atual[chave];
271
- else atual[chave] = Math.min(valor, atual[chave] ?? valor);
381
+ const resultado = alterar(atual);
272
382
  gravarAtomico(BASELINE, `${JSON.stringify(atual, null, 2)}\n`);
383
+ return resultado;
273
384
  } catch {} finally {
274
385
  if (travado) rmSync(trava, { force: true });
275
386
  }
276
387
  }
277
388
 
278
- function varrer(dir, saida = []) {
279
- let itens;
280
- try { itens = readdirSync(dir, { withFileTypes: true }); } catch { return saida; }
281
- for (const item of itens) {
282
- const cheio = join(dir, item.name);
283
- if (item.isDirectory()) {
284
- if (item.name === 'node_modules' || item.name.startsWith('.')) continue;
285
- if (IGNORAR.some((re) => re.test(`${cheio}/`))) continue;
286
- varrer(cheio, saida);
287
- } else if (elegivel(cheio)) saida.push(cheio);
389
+ function atualizarBaseline(chave, valor) {
390
+ comTrava((atual) => {
391
+ if (valor === 0) delete atual[chave];
392
+ else atual[chave] = Math.min(valor, atual[chave] ?? valor);
393
+ });
394
+ }
395
+
396
+ function limparBaseline() {
397
+ if (!existsSync(BASELINE)) return 0;
398
+ const doGit = listarPeloGit();
399
+ const fontes = doGit && new Set(listarFontes(doGit));
400
+ const manter = (chave) => {
401
+ const rel = chave.split(/[\\/]/).join('/');
402
+ return existsSync(join(raiz, chave)) && ehFonte(raiz, rel) && (!fontes || fontes.has(rel));
403
+ };
404
+ return comTrava((atual) => {
405
+ const antes = Object.keys(atual).length;
406
+ for (const chave of Object.keys(atual)) if (!manter(chave)) delete atual[chave];
407
+ return antes - Object.keys(atual).length;
408
+ }) ?? 0;
409
+ }
410
+
411
+ function completarBaseline() {
412
+ let previo;
413
+ try { previo = JSON.parse(readFileSync(BASELINE, 'utf8')); } catch { return 0; }
414
+ const novos = [];
415
+ for (const f of listarFontes()) {
416
+ if (!EXTENSOES_RECENTES.has(extname(f)) || Object.hasOwn(previo, chaveDe(f))) continue;
417
+ let fonte;
418
+ try { fonte = readFileSync(join(raiz, f), 'utf8'); } catch { continue; }
419
+ const { achados } = analisar(f, fonte);
420
+ if (achados.length > 0) novos.push([chaveDe(f), achados.length]);
288
421
  }
289
- return saida;
422
+ if (!novos.length) return 0;
423
+ return comTrava((atual) => {
424
+ const faltam = novos.filter(([chave]) => !Object.hasOwn(atual, chave));
425
+ for (const [chave, valor] of faltam) atual[chave] = valor;
426
+ return faltam.length;
427
+ }) ?? 0;
290
428
  }
291
429
 
292
- if (process.argv.includes('--gerar-baseline')) {
430
+ function gerarBaseline() {
293
431
  const mapa = {};
294
432
  let arquivos = 0;
295
433
  let violacoes = 0;
296
- for (const f of varrer(raiz)) {
434
+ for (const f of listarFontes()) {
297
435
  let fonte;
298
- try { fonte = readFileSync(f, 'utf8'); } catch { continue; }
436
+ try { fonte = readFileSync(join(raiz, f), 'utf8'); } catch { continue; }
299
437
  const { achados } = analisar(f, fonte);
300
- if (achados.length > 0) { mapa[relative(raiz, f)] = achados.length; arquivos++; violacoes += achados.length; }
438
+ if (achados.length > 0) { mapa[chaveDe(f)] = achados.length; arquivos++; violacoes += achados.length; }
301
439
  }
302
440
  if (!existsSync(dirname(BASELINE))) mkdirSync(dirname(BASELINE), { recursive: true });
303
441
  gravarAtomico(BASELINE, `${JSON.stringify(mapa, null, 2)}\n`);
304
- console.log(`[comentarios] baseline gravado: ${arquivos} arquivos legados, ${violacoes} violações toleradas.`);
305
- console.log('[comentarios] arquivo novo responde ao padrão cheio; legado só não pode piorar.');
442
+ return [
443
+ `[comentarios] baseline gravado: ${arquivos} arquivos legados, ${violacoes} violações toleradas.`,
444
+ '[comentarios] arquivo novo responde ao padrão cheio; legado só não pode piorar.',
445
+ ].join('\n');
446
+ }
447
+
448
+ function atalhosDoProjeto() {
449
+ return listarFontes().flatMap((arquivo) => {
450
+ let fonte;
451
+ try { fonte = readFileSync(join(raiz, arquivo), 'utf8'); } catch { return []; }
452
+ return listarAtalhos(arquivo, fonte).map(({ linha, marcador, limite, gatilho }) => ({ arquivo, linha, marcador, limite, gatilho }));
453
+ });
454
+ }
455
+
456
+ const MODOS = {
457
+ '--gerar-baseline': gerarBaseline,
458
+ '--limpar-baseline': () => `[comentarios] baseline: ${limparBaseline()} entradas removidas`,
459
+ '--completar-baseline': () => `[comentarios] baseline: ${completarBaseline()} entradas acrescentadas`,
460
+ '--listar-fontes': () => JSON.stringify(listarFontes()),
461
+ '--atalhos': () => JSON.stringify(atalhosDoProjeto()),
462
+ };
463
+
464
+ const modo = Object.keys(MODOS).find((m) => process.argv.includes(m));
465
+ if (modo) {
466
+ const saida = MODOS[modo]();
467
+ // Em pipe, o stdout é assíncrono: sair antes do callback corta listagens grandes.
468
+ await new Promise((pronto) => process.stdout.write(`${saida}\n`, pronto));
306
469
  process.exit(0);
307
470
  }
308
471
 
@@ -320,6 +483,8 @@ const { achados, comentadas, uteis, densidade } = analisar(caminho, fonte);
320
483
  const chave = relative(raiz, caminho);
321
484
  const rel = !chave || chave.startsWith('..') ? caminho : chave;
322
485
 
486
+ const aviso = avisoAtalhos(caminho, fonte, payload.tool_input, rel);
487
+
323
488
  let baseline = null;
324
489
  try { baseline = JSON.parse(readFileSync(BASELINE, 'utf8')); } catch {}
325
490
  const tolerado = baseline?.[chave] ?? 0;
@@ -331,6 +496,7 @@ if (achados.length <= tolerado) {
331
496
  } else if (achados.length === 0 && densidade > DENSIDADE_ALVO) {
332
497
  console.error(`[comentarios] aviso: ${rel} tem ${(densidade * 100).toFixed(0)}% de linhas de comentário (${comentadas}/${uteis}), alvo <= ${DENSIDADE_ALVO * 100}%.`);
333
498
  }
499
+ if (aviso) console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: aviso } }));
334
500
  process.exit(0);
335
501
  }
336
502
 
@@ -350,6 +516,7 @@ console.error(
350
516
  'Tetos: bloco interno <= 3 linhas, docstring pública <= 5, cabeçalho de arquivo proibido.',
351
517
  'Task/plano/data/achado de review e rationale longo vão para a mensagem de commit ou docs/ — nunca para o código.',
352
518
  'Corrija no próprio arquivo antes de continuar a task.',
519
+ ...(aviso ? ['', aviso] : []),
353
520
  ].join('\n'),
354
521
  );
355
522
  process.exit(2);
@@ -36,7 +36,10 @@ Se o porquê não cabe em 3 linhas, **ele não pertence ao código**.
36
36
 
37
37
  - **Contrato não óbvio** de função/método público — docstring de até 5 linhas.
38
38
  - **Armadilha real**: por que a abordagem óbvia quebra — até 3 linhas, **no presente**, sem contar a história.
39
- - **`TODO:` / `FIXME:`** com o motivo real — 1 linha.
39
+ - **`TODO:` / `FIXME:`** no formato `TODO: <limite>, <quando revisitar>` — 1 linha. O limite é o que o atalho
40
+ deixou de fazer; depois da primeira vírgula vem o gatilho, a situação em que o atalho deixa de servir. Exemplo:
41
+ `// TODO: sem paginação, quando passar de 1000 itens`. O hook avisa, sem bloquear, sobre `TODO:`/`FIXME:` novo
42
+ sem gatilho. Para listar os que estão sem gatilho: `npx @fontdata/ai-harness atalhos --sem-gatilho`.
40
43
  - **Referência externa** (RFC, issue da lib, doc de API) que justifica um workaround — 1 linha.
41
44
 
42
45
  ## Para onde vai cada informação
@@ -156,7 +159,7 @@ export function hashApiKey(plainKey: string): string {}
156
159
  function HashApiKey(const APlainKey: string): string;
157
160
  ```
158
161
 
159
- - **TypeScript/JavaScript/Java/C#/C++/Go/Rust/PHP:** `/** ... */` no topo do símbolo **público**.
162
+ - **TypeScript/JavaScript/Java/Kotlin/C#/C++/Go/Rust/PHP/Dart:** `/** ... */` no topo do símbolo **público**.
160
163
  - **Python:** docstring `"""..."""` curta logo abaixo da assinatura.
161
164
  - **Delphi/Pascal:** `///` (XMLDoc) nas rotinas públicas da `interface`; nunca repetir na `implementation`.
162
165
  O que vem depois do último `end.` (o rodapé de histórico, que o compilador ignora) fica fora deste padrão e do hook.
@@ -167,6 +170,9 @@ function HashApiKey(const APlainKey: string): string;
167
170
  O hook `.claude/hooks/comentarios/check.mjs` roda a cada `Write`/`Edit` e **bloqueia** banner, rastreabilidade
168
171
  de processo, data, cabeçalho de arquivo, código comentado e bloco acima do teto.
169
172
 
173
+ Ficam fora do hook e da catraca: `docs/`, as dependências do Boss (`modules/` com `boss.json` na pasta-mãe),
174
+ fixtures e exemplos, e os arquivos ignorados pelo git (`.gitignore`).
175
+
170
176
  Arquivos que já existiam quando o padrão foi instalado estão em
171
177
  `.claude/hooks/comentarios/baseline.json` (catraca): eles **não precisam ser limpos de uma vez**, só não
172
178
  podem piorar. Quando melhoram, a catraca desce e não volta.
@@ -26,13 +26,23 @@ Identifique a stack e percorra os pontos quentes de `references/pontos-quentes.m
26
26
  sempre que possível: profiler, `EXPLAIN`, análise de bundle, tempos em log ou teste de carga já existente.
27
27
  Achado sem medição é marcado como estimativa.
28
28
 
29
+ Sem caso concreto, não é achado: diga a situação (tela, endpoint, volume de dados) e o tempo ou consumo que ela
30
+ produz. Leia quem chama o trecho apontado e o que ele chama. Escale o impacto pela carga esperada que o projeto
31
+ declara (`SPEC.md`, `CLAUDE.md`, README, configuração de deploy); sem carga declarada, assuma a menor plausível. Diga
32
+ qual carga assumiu.
33
+
29
34
  Para cada achado: evidência (`arquivo:linha` e a medição), **impacto** (alto, médio, baixo), **esforço** de correção
30
35
  e a correção recomendada.
31
36
 
32
37
  ## Passo 3 — Relatório técnico
33
38
 
34
39
  Grave `docs/trabalhos/<id>/relatorios/TECNICO.md` a partir de `templates/relatorios/TECNICO.md`, com os achados
35
- priorizados por impacto e esforço e o que foi medido (comando e resultado). Preencha `arquivos`.
40
+ priorizados por impacto e esforço, o que foi medido (comando e resultado) e a carga assumida. Preencha `arquivos`.
41
+
42
+ Use numeração única sobre a escala de impacto (1, 2, 3… contínuos de alto a baixo). Cada achado vem em 4 partes:
43
+ **O que é** (`arquivo:linha` e a medição), **Problema** (o caso concreto), **Correção** e **Se não corrigir**. Antes
44
+ de citar, reconfirme que o `arquivo:linha` aponta o trecho no estado atual. Feche com **Não verificado**: o que não
45
+ foi lido, executado ou medido, e por quê.
36
46
 
37
47
  ## Passo 4 — Relatório para a gestão
38
48
 
@@ -27,6 +27,9 @@ autenticação e autorização, configuração. Classifique cada achado em **CR
27
27
  evidência (`arquivo:linha`) e correção recomendada. **Nunca** copie o valor de um segredo para o relatório — só a
28
28
  localização.
29
29
 
30
+ Sem caso concreto, não é achado: diga a entrada ou situação (requisição, usuário, dado) e o que ela expõe ou permite.
31
+ Leia quem chama o trecho apontado e o que ele chama.
32
+
30
33
  ## Passo 3 — Conformidade com a LGPD
31
34
 
32
35
  Use a skill **`lgpd-checker`** (no plugin, `fontdata:lgpd-checker`) e siga as fases dela:
@@ -47,6 +50,11 @@ severidade e veredito LGPD, achados críticos primeiro, segurança técnica, con
47
50
  formato do relatório da `lgpd-checker`), pontos positivos e plano de ação priorizado. Preencha `arquivos` com os
48
51
  arquivos citados.
49
52
 
53
+ Use numeração única sobre a escala (1, 2, 3… contínuos de CRÍTICO a BAIXO). Cada achado vem em 4 partes:
54
+ **O que é** (`arquivo:linha`), **Problema** (o caso concreto), **Correção** e **Se não corrigir**. Antes de citar,
55
+ reconfirme que o `arquivo:linha` aponta o trecho no estado atual. Feche com **Não verificado**: o que não foi lido,
56
+ executado ou medido, e por quê.
57
+
50
58
  ## Passo 5 — Relatório para a gestão
51
59
 
52
60
  Grave `docs/trabalhos/<id>/relatorios/CLIENTE.md` a partir de `templates/relatorios/CLIENTE.md`: os riscos em
@@ -38,6 +38,8 @@ A senha nunca vai para os relatórios nem para o rastro.
38
38
  2. Em cada tela, aplique a lente escolhida com o checklist de `references/lentes.md`.
39
39
  3. Classifique cada achado: **CRÍTICO** (bloqueia o uso), **SÉRIO**, **MODERADO** ou **MENOR**, citando o critério
40
40
  **WCAG** nos achados de acessibilidade.
41
+ 4. Sem caso concreto, não é achado: diga a ação na tela e o resultado errado que a pessoa vê ou deixa de conseguir.
42
+ Quando o achado aponta código, leia quem chama o trecho apontado e o que ele chama.
41
43
 
42
44
  ## Passo 3 — Relatório técnico
43
45
 
@@ -45,6 +47,12 @@ Grave `docs/trabalhos/<id>/relatorios/TECNICO.md` a partir de `templates/relator
45
47
  por **tela** e **severidade**, cada um com o elemento afetado, o critério WCAG (quando houver) e a correção
46
48
  recomendada.
47
49
 
50
+ Use numeração única sobre a escala (1, 2, 3… contínuos de CRÍTICO a MENOR), mesmo com os achados agrupados por
51
+ tela. Cada achado vem em 4 partes: **O que é** (tela, elemento e, quando houver, `arquivo:linha`), **Problema** (o
52
+ caso concreto), **Correção** e **Se não corrigir**. Antes de citar um `arquivo:linha`, reconfirme que ele aponta o
53
+ trecho no estado atual. Feche com **Não verificado**: telas, lentes ou fluxos que não foram percorridos ou medidos,
54
+ e por quê.
55
+
48
56
  ## Passo 4 — Relatório para a gestão
49
57
 
50
58
  Grave `docs/trabalhos/<id>/relatorios/CLIENTE.md` a partir de `templates/relatorios/CLIENTE.md`: quais perfis de
@@ -16,24 +16,35 @@ Cria o agent de review **somente leitura** em `.claude/agents/code-reviewer.md`
16
16
  olhando só o diff da task.
17
17
  - Classificação: **BLOQUEANTE**, **IMPORTANTE**, **SUGESTÃO**. Com BLOQUEANTE, o veredito é `REPROVADO`;
18
18
  IMPORTANTE é corrigido antes de a task fechar, salvo decisão registrada em `DECISOES.md`; SUGESTÃO não segura.
19
- - Saída: veredito e achados com `arquivo:linha`, severidade, problema e correção sugerida.
19
+ - Saída: veredito e achados com numeração única entre as severidades (1, 2, 3… de BLOQUEANTE a SUGESTÃO), cada um
20
+ em 4 partes: **O que é** (`arquivo:linha`), **Problema** (o caso concreto), **Correção** e **Se não corrigir**.
21
+ Fecha com **Não verificado**: o que não foi lido, executado ou medido, e por quê.
20
22
  - O agent não corrige nada: identifica e reporta.
21
23
 
22
24
  ## Checklist no system prompt
23
25
 
24
26
  Sem checklist explícito, o agent revisa o que lhe parecer relevante e ignora o resto.
25
27
 
28
+ Antes dos itens, três regras de evidência:
29
+
30
+ - **Sem caso concreto, não é achado:** a entrada ou situação e o resultado errado. Sem caso, vira pergunta no fecho.
31
+ - **Entorno, não só o diff:** ler quem chama o código alterado e o que ele chama; com assinatura ou comportamento
32
+ novo, procurar todas as chamadas e citar as não ajustadas.
33
+ - **Linha atual:** reconfirmar no estado atual do arquivo que o `arquivo:linha` aponta o trecho antes de citá-lo.
34
+
26
35
  1. **Correção** — bugs, casos de borda, erros silenciados.
27
36
  2. **Aderência** ao `SPEC.md` e ao `PLAN.md` do trabalho.
28
37
  3. **Testes** — existem e cobrem o crítico da task?
29
38
  4. **Segurança e isolamento de dados** — multi-tenant, autorização, segredos.
30
- 5. **Rules do projeto** em `.claude/rules/`.
31
- 6. **Código legado** — na área antiga tocada, o padrão local do arquivo foi preservado?
32
- 7. **Comentários** — classificar como **IMPORTANTE** (nunca SUGESTÃO): bloco interno acima de 3 linhas, docstring
39
+ 5. **Performance e concorrência** pela carga que o projeto declara (`SPEC.md`, `CLAUDE.md`, README, deploy); sem
40
+ carga declarada, a menor plausível. Dizer qual carga foi assumida.
41
+ 6. **Rules do projeto** em `.claude/rules/`.
42
+ 7. **Código legado** — na área antiga tocada, o padrão local do arquivo foi preservado?
43
+ 8. **Comentários** — classificar como **IMPORTANTE** (nunca SUGESTÃO): bloco interno acima de 3 linhas, docstring
33
44
  pública acima de 5, cabeçalho de arquivo, banner ou separador de seção, task/fase/plano/data/hash de
34
45
  commit/achado de review dentro do código, narração do passo a passo, código comentado. Ver
35
46
  `.claude/rules/comentarios.md`.
36
- 8. **Legibilidade e simplicidade.**
47
+ 9. **Legibilidade e simplicidade.**
37
48
 
38
49
  ## Guarda extra
39
50
 
@@ -26,9 +26,18 @@ sabendo para que a task serve, o sub-agent decide melhor o que a lista de campos
26
26
  > errado ou contradizer a `SPEC.md`, implemente a regra da `SPEC.md` mesmo assim e relate o teste que continuou
27
27
  > falhando como dúvida, com a conta que mostra a contradição: assim a task fica a uma decisão de fechar.
28
28
  >
29
- > Faça só o que a task pede: sem refatorar o entorno, sem abstração para um uso só, sem opção de configuração e sem
30
- > tratamento de erro para cenário que não pode acontecer. O que ficar fora do escopo entra no seu relato como
31
- > sugestão.
29
+ > Antes de escrever, leia o código que a task toca e liste tudo que a mudança alcança: quem chama, testes, fixtures,
30
+ > configuração e exports, e o que pode quebrar.
31
+ >
32
+ > Faça a menor mudança completa e pare no primeiro degrau que resolve: (1) precisa existir? (2) já existe no código?
33
+ > (3) a biblioteca padrão ou a plataforma resolve? (4) uma dependência já instalada resolve? Nunca adicione
34
+ > dependência para poucas linhas. (5) Senão, o mínimo que funciona. Ao corrigir defeito, procure todas as chamadas e
35
+ > corrija a causa no código compartilhado. Sem refatorar o entorno, sem abstração para um uso só, sem opção de
36
+ > configuração e sem tratamento de erro para cenário que não pode acontecer; o que ficar fora do escopo entra no seu
37
+ > relato como sugestão.
38
+ >
39
+ > Nunca se corta: validação na fronteira de entrada, tratamento que evita perda de dados, segurança e acessibilidade.
40
+ > Código movido leva junto a validação que tinha.
32
41
  >
33
42
  > `SPEC.md`, `CLAUDE.md` e `PLAN.md` ficam como estão: quem atualiza o status é o orquestrador. Também não pergunte
34
43
  > nada ao usuário, porque ninguém acompanha a execução: se precisar de uma decisão, pare e descreva a dúvida, as
@@ -39,6 +48,8 @@ sabendo para que a task serve, o sub-agent decide melhor o que a lista de campos
39
48
  > `docs/trabalhos/`, não para o código.
40
49
  >
41
50
  > Na área de código legado tocada, preserve o padrão local do arquivo; convenções novas valem para arquivo novo.
51
+ >
52
+ > Seu relato termina com a seção **Não verificado**: o que você não rodou nem conferiu e os riscos que ficaram.
42
53
 
43
54
  ## Gates depois da implementação
44
55
 
@@ -5,6 +5,9 @@ Antes de planejar, procure evidência — nunca presuma.
5
5
 
6
6
  ## Onde procurar
7
7
 
8
+ Comece por `npx @fontdata/ai-harness mapa` para a visão geral dos símbolos públicos por pasta (`mapa <pasta>` para
9
+ detalhar uma pasta) e depois busque pelo vocabulário do pedido.
10
+
8
11
  1. **Vocabulário do pedido:** entidades, ações e telas citadas, com sinônimos (cliente/pessoa/contato,
9
12
  pedido/venda/ordem, desconto/abatimento). Busque nomes de classes, funções, rotas, tabelas e rótulos de tela.
10
13
  2. **Pontos de entrada:** rotas e controllers, menus e telas, comandos de CLI, jobs agendados.
@@ -45,11 +45,15 @@ Se o relato não veio, peça os detalhes antes de começar: o que acontece, o qu
45
45
 
46
46
  ## Passo 3 — 🚦 GATE de aprovação
47
47
 
48
- Mostre: sintoma, causa raiz e evidência, o plano de correção e os riscos. Com `causa_raiz: hipotese`, deixe
49
- explícito que a primeira task confirma ou derruba a hipótese. **Não altere nada sem o "ok".**
48
+ 1. Grave `status: aguardando-aprovacao` no `PLAN.md` (e `atualizado_em`), rode `npx @fontdata/ai-harness doctor` e
49
+ confirme que não há achado `contrato-*` neste trabalho.
50
+ 2. Mostre: sintoma, causa raiz e evidência, o plano de correção e os riscos. Com `causa_raiz: hipotese`, deixe
51
+ explícito que a primeira task confirma ou derruba a hipótese. **Não altere nada sem o "ok".**
50
52
 
51
53
  ## Passo 4 — Corrigir com TDD
52
54
 
55
+ Com o "ok", antes de alterar qualquer código, grave `status: em-execucao` no `PLAN.md` (e `atualizado_em`).
56
+
53
57
  1. **Regressão primeiro (T-01.01):** escreva o teste de regressão, rode e **confirme que falha** pelo motivo do bug.
54
58
  Com hipótese, o teste falhando pelo motivo esperado torna a causa `comprovada` — atualize o frontmatter.
55
59
 
@@ -75,6 +79,8 @@ explícito que a primeira task confirma ou derruba a hipótese. **Não altere na
75
79
 
76
80
  5. No frontmatter do `PLAN.md`, cada task vai de `pendente` para `em-andamento` e, com `suite_verde` registrado, para
77
81
  `concluida`, no feminino. Os outros valores aceitos são `bloqueada` e `pulada`.
82
+ `em-andamento` é status de task, nunca do plano: o `status` do topo só passa por `rascunho`,
83
+ `aguardando-aprovacao`, `em-execucao`, `concluido` ou `cancelado`.
78
84
 
79
85
  ## Passo 5 — Evitar que volte: a rule é mesmo necessária?
80
86