@fontdata/ai-harness 2.0.0 → 2.1.0

package/templates/commands/sincronizar-claude-md.md

@@ -1,15 +1,183 @@
 ---
-description: Relê o código e aponta onde o CLAUDE.md/SPEC.md divergiu da realidade — sem reescrever sozinho.
+description: Gera o SPEC.md (entrevista) e o CLAUDE.md que faltam e reconcilia os existentes com o código e os agents do projeto, incluindo a seção de orquestração. Só grava o que for aprovado.
+argument-hint: "[spec | claude-md | reconciliar] [seção ou tema opcional]"
 ---
 
-# Sincronização do CLAUDE.md com o código
+# /sincronizar-claude-md — SPEC.md e CLAUDE.md gerados e em dia com o código
 
-Foco (opcional — seção ou tema): $ARGUMENTS
+Argumentos: $ARGUMENTS
 
-Passos:
+> **🚦 Há um GATE de aprovação** antes de gravar qualquer arquivo. Este comando **não faz commit nem push**. Rode no
+> setup e sempre que o projeto mudar: o que não existe é gerado, o que existe é reconciliado.
 
-1. Leia o `CLAUDE.md` (e o `SPEC.md`, se existir) e confronte com o estado **real** do código: stack, scripts, estrutura de pastas, comandos de build/test, convenções e fluxos descritos.
-2. Liste as **divergências** encontradas, cada uma com: o que o doc afirma, o que o código mostra e o trecho/arquivo de evidência (use links clicáveis `arquivo:linha`).
-3. Classifique cada divergência em **DESATUALIZADO** (doc ficou para trás), **FALTANDO** (existe no código, não no doc) ou **OBSOLETO** (no doc, não existe mais).
-4. **Não reescreva** `CLAUDE.md`/`SPEC.md` por conta própria — essa é uma regra do harness. Apresente as correções propostas e **pergunte quais devo aplicar**.
-5. Só depois da minha confirmação, aplique exatamente as mudanças aprovadas.
+## Passo 0 — Detectar o modo (somente leitura)
+
+1. Leia o primeiro argumento. `spec`, `claude-md` ou `reconciliar` forçam o modo; o resto é o foco (seção ou tema).
+2. Sem modo forçado, decida pelo que existe na raiz:
+
+| Situação | Modo |
+|---|---|
+| Sem `SPEC.md` | **gerar SPEC** |
+| Com `SPEC.md` e sem `CLAUDE.md` (ou só o modelo base, com o título `[NOME DO PROJETO]`) | **gerar CLAUDE.md** |
+| Com os dois | **reconciliar** |
+
+3. Levante também, sem alterar nada: `.claude/agents/`, `.claude/rules/harness-projeto.md`, os scripts de build e
+   teste (`package.json`, `composer.json`, `Makefile`, `docker-compose.yml`, `.dproj`...) e os trabalhos em
+   `docs/trabalhos/<id>/` (`SPEC.md`, `PLAN.md`, `DECISOES.md`) que mudaram o que os documentos descrevem.
+4. Casos forçados: `spec` com `SPEC.md` existente avisa que a entrevista gera um arquivo novo e pergunta se não é o
+   caso de `reconciliar`; `claude-md` com `CLAUDE.md` existente regenera a partir do SPEC e lista no GATE tudo que
+   seria perdido; `reconciliar` sem `SPEC.md` confronta só o `CLAUDE.md` e registra a falta do SPEC.
+5. Informe o modo escolhido e o motivo antes de seguir.
+
+## Passo 1 — Coletar o conteúdo
+
+### Modo gerar SPEC — entrevista
+
+Conduza uma entrevista de requisitos, **uma pergunta por vez**. Se já houver código, leia-o antes e pergunte só o que
+ele não responde, confirmando o que foi inferido. Cubra obrigatoriamente:
+
+- problema real que o sistema resolve e quem são os usuários;
+- funcionalidades essenciais, nice-to-have e o que está fora do escopo;
+- módulos e a responsabilidade de cada um;
+- stack técnica e constraints (prazo, infraestrutura, integrações, legado);
+- como saber que está pronto (critérios de aceitação verificáveis).
+
+Com informação suficiente, avise que está pronto para rascunhar.
+
+### Modo gerar CLAUDE.md
+
+Leia o `SPEC.md` para intenção, escopo e stack pretendida. Leia o código para o que é **fato**: stack instalada,
+estrutura de pastas, comandos de instalação, execução e teste, framework e pasta dos testes, convenções já em uso.
+Se existir o `CLAUDE.md` modelo base, guarde as seções do harness (filosofia de trabalho, modelo de arquivos,
+garantias do harness, código legado) para preservá-las.
+
+### Modo reconciliar
+
+Confronte `CLAUDE.md` e `SPEC.md` com o estado **real** — stack, scripts, estrutura de pastas, comandos de build e
+teste, convenções e fluxos descritos — e com os agents de `.claude/agents/`. Com foco nos argumentos, limite-se a ele.
+Para cada divergência, registre o que o documento afirma, o que o código mostra e a evidência (`arquivo:linha`),
+classificada em:
+
+- **DESATUALIZADO** — o documento ficou para trás;
+- **FALTANDO** — existe no código ou em `.claude/agents/`, não no documento;
+- **OBSOLETO** — está no documento, não existe mais (inclui agent ou comando citado que não está instalado).
+
+Marque como **OBSOLETO** o bloco antigo "Comentários em código" e a linha `@.claude/rules/comentarios.md`: a rule
+`.claude/rules/comentarios.md` é carregada automaticamente pelo Claude Code e não precisa estar no `CLAUDE.md`.
+
+## Passo 2 — Rascunhar (sem gravar)
+
+### SPEC.md
+
+Estrutura fixa, sem adicionar nem remover seções:
+
+```markdown
+# SPEC.md
+
+## Problema
+## Usuários
+## Funcionalidades
+### Essenciais
+### Fora do escopo
+## Módulos
+## Stack
+## Constraints técnicas
+## Critérios de aceitação
+```
+
+Não invente o que não surgiu na entrevista; ponto ambíguo fica como "a definir" e vira decisão em aberto no
+`CLAUDE.md`. Este é o SPEC **principal**; a spec de cada trabalho fica em `docs/trabalhos/<id>/SPEC.md`, gerada pelo
+`/nova-tarefa`.
+
+### CLAUDE.md
+
+```markdown
+# [NOME DO PROJETO]
+> [1 frase: o que o sistema faz e qual problema resolve]
+
+## Stack
+| Camada | Tecnologia |
+|--------|------------|
+
+## Estrutura de pastas
+[árvore com um comentário curto por pasta]
+
+## Como rodar localmente
+[comandos exatos de instalação e execução, por parte do sistema]
+
+## Padrões de código
+- Nomenclatura de arquivos / variáveis e funções / endpoints / componentes / tipagem: [regra]
+
+## Orquestração
+[seção do Passo 3]
+
+## TDD
+- Framework e onde ficam os testes: [...]
+- Regra de cobertura: [...]
+- Testes críticos deste projeto: [lista extraída do SPEC]
+
+## Nunca fazer
+- Nunca [proibição específica deste projeto]
+
+## Decisões em aberto
+- [ ] [decisão não resolvida no SPEC]
+```
+
+Preencha só com o que está no SPEC ou verificado no código; o resto fica "a definir". Preserve integralmente, na
+posição atual, as seções do harness que já existirem. Não gere bloco de comentários nem `@import` de rule.
+
+### Correções (modo reconciliar)
+
+Liste as divergências do Passo 1 com o trecho atual e o trecho proposto, lado a lado, agrupadas por arquivo.
+
+## Passo 3 — Seção de orquestração
+
+Vale para todo modo que grava o `CLAUDE.md`. Liste os agents do projeto em `.claude/agents/` (nome, descrição e as
+pastas que tocam) e os do harness (`revisor-testes`, `qa`, `investigador`, `auditor-plano`; no plugin, com o prefixo
+`fontdata:`). Gere ou atualize, no lugar, uma única seção — nunca duplicada:
+
+```markdown
+## Orquestração
+
+- A sessão principal é a **orquestradora**: delega cada task ao agent do domínio dela e não implementa diretamente.
+- Planejamento com `/nova-tarefa`; execução com `/executar-plan`; defeitos com `/resolver-bug`.
+- Nenhuma task fecha sem os gates `revisor-testes` e `qa` (agents do harness, somente leitura) e suíte verde.
+- Toda delegação e todo gate são relatados no chat, dizendo **qual agent está ativo**.
+- Dúvida durante a execução vira bloqueio em `docs/trabalhos/<id>/BLOQUEIOS.md`, não pergunta ao usuário.
+- Mapa de agents por domínio, portões extras e comando da suíte: `.claude/rules/harness-projeto.md`.
+```
+
+O `CLAUDE.md` aponta para a rule e **não duplica** o que está nela. Rascunhe também a atualização de
+`.claude/rules/harness-projeto.md` (criando-a se não existir), só com as seções que valem:
+
+- **Mapa de agents por domínio** — uma linha por agent do projeto, com a pasta ou área que implementa;
+- **Portões extras** — além de `revisor-testes` e `qa`, só os que existem (ex.: um agent de code review instalado);
+- **Suíte de testes** — comando e onde roda, **verificados** nos scripts do projeto.
+
+Agent listado na rule que não existe mais sai; agent novo entra. Sem agents do projeto, deixe o mapa vazio e sugira
+`/evoluir-harness` para criá-los.
+
+## Passo 4 — 🚦 GATE de aprovação
+
+Mostre, por arquivo, o conteúdo completo (arquivo novo) ou as mudanças propostas (arquivo existente), incluindo o
+que seria removido. No modo reconciliar, **pergunte quais correções aplicar**. Nada é gravado sem aprovação explícita.
+
+## Passo 5 — Gravar e encadear
+
+1. Grave exatamente o que foi aprovado e mostre os trechos que ficaram em cada arquivo.
+2. Se houver um trabalho em execução, registre a mudança também no `DECISOES.md` dele — o hook `proteger-contratos`
+   avisa sobre edição de contrato durante a execução.
+3. Acabou de gravar o `SPEC.md` e o `CLAUDE.md` não existe? Volte ao Passo 1 no modo gerar CLAUDE.md.
+4. Encerre sugerindo o próximo passo: `/nova-tarefa` para planejar, `/evoluir-harness` para criar agents, rules,
+   skills ou hooks, `/harness` para o setup completo, e `npx @fontdata/ai-harness doctor` para conferir o contrato.
+
+## Guardrails
+
+- **Nunca** gravar `SPEC.md`, `CLAUDE.md` ou `.claude/rules/harness-projeto.md` sem aprovação no GATE.
+- **Nunca** fazer commit, push ou qualquer outra alteração fora desses três arquivos (e do `DECISOES.md` do trabalho
+  em execução).
+- **Nunca** inventar stack, comando ou convenção: comando citado precisa estar verificado no código; o que não se
+  sabe fica "a definir".
+- **Nunca** duplicar a seção de orquestração nem copiar para o `CLAUDE.md` o conteúdo de `harness-projeto.md`.
+- **Nunca** gerar bloco de comentários ou `@import` de rule no `CLAUDE.md`.
+- Conteúdo em **pt-BR**.

package/templates/hooks/comentarios/check.mjs

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
+import { extname, relative, join, dirname } from 'node:path';
+
+const MAX_BLOCO = Number(process.env.COMENTARIOS_MAX_BLOCO ?? 3);
+const MAX_DOCSTRING = Number(process.env.COMENTARIOS_MAX_DOCSTRING ?? 5);
+const DENSIDADE_ALVO = 0.1;
+
+const EXTENSOES = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
+  '.py', '.go', '.rs', '.java', '.cs', '.php',
+  '.pas', '.dpr', '.sql', '.sh',
+]);
+
+const IGNORAR = [
+  /node_modules/,
+  /[\\/]\.git[\\/]/,
+  /[\\/](dist|build|coverage|out|\.next|\.nuxt|vendor|migrations|generated|__generated__)[\\/]/,
+  /\.d\.ts$/,
+  /\.(test|spec)\.[jt]sx?$/,
+];
+
+const CABECALHO_PERMITIDO =
+  /eslint|ts-nocheck|ts-ignore|prettier|@license|copyright|spdx|jshint|globals|^#!|use (strict|client|server)/i;
+
+const BANNER = /^[-=─-╿_*#~+]{3,}|[-=─-╿_*#~+]{3,}$/;
+
+const RASTREIO = [
+  [/\b(task|tarefa|fase|etapa|plano|spec|sprint|epico|épico)\s*[\dIVX]/i, 'referência a task/fase/plano/spec'],
+  [/\bT\d+(\.\d+)+\b/, 'referência a task (T0.0)'],
+  [/docs\/(plans|specs|bugs|investigacoes)\//i, 'caminho de docs/ dentro do código'],
+  [/\bachado d[oe]\b/i, 'achado de review no código'],
+  [/@[\w-]*(reviewer|auditor|orquestrador|agent)\b/i, 'menção a agent no código'],
+  [/\b(commit|sha|hash)\s+[0-9a-f]{7,40}\b/i, 'hash de commit'],
+];
+
+const DATA = /(^|[^"'\w])20\d{2}-\d{2}-\d{2}([^"'\w]|$)/;
+const CODIGO_TOKEN = /(^|\s)(const|let|var|function|return|if|for|while|await|import|export|def|class)\b/;
+const CODIGO_FIM = /[;{}]\s*$/;
+
+function comentario(linha, ext) {
+  const t = linha.trim();
+  if (!t) return null;
+  if (ext === '.py' || ext === '.sh') return t.startsWith('#') ? t.replace(/^#+/, '').trim() : null;
+  if (ext === '.sql') {
+    if (t.startsWith('--')) return t.replace(/^-+/, '').trim();
+    if (t.startsWith('/*') || t.startsWith('*')) return t.replace(/^[/*]+/, '').trim();
+    return null;
+  }
+  if (ext === '.pas' || ext === '.dpr') {
+    if (t.startsWith('//')) return t.replace(/^\/+/, '').trim();
+    if (t.startsWith('(*')) return t.replace(/^\(\*/, '').trim();
+    if (t.startsWith('{') && !t.startsWith('{$')) return t.replace(/^\{/, '').trim();
+    return null;
+  }
+  if (t.startsWith('//')) return t.replace(/^\/+/, '').trim();
+  if (t.startsWith('/*')) return t.replace(/^\/\*+/, '').trim();
+  if (t.startsWith('*')) return t.replace(/^\*+\/?/, '').trim();
+  return null;
+}
+
+function analisar(caminho, fonte) {
+  const ext = extname(caminho);
+  const linhas = fonte.split('\n');
+  const achados = [];
+  const marca = (linha, msg) => achados.push({ linha, msg });
+  const ehComentario = linhas.map((l) => comentario(l, ext));
+
+  let primeiroCodigo = -1;
+  for (let i = 0; i < linhas.length; i++) {
+    if (ehComentario[i] === null && linhas[i].trim()) { primeiroCodigo = i; break; }
+  }
+
+  let i = 0;
+  while (i < linhas.length) {
+    if (ehComentario[i] === null) { i++; continue; }
+    const inicio = i;
+    const conteudo = [];
+    while (i < linhas.length && ehComentario[i] !== null) { conteudo.push(ehComentario[i]); i++; }
+    const fim = i - 1;
+    const corpo = conteudo.filter(Boolean);
+    const texto = corpo.join(' ');
+
+    for (let k = 0; k < conteudo.length; k++) {
+      if (conteudo[k] && BANNER.test(conteudo[k])) {
+        marca(inicio + k + 1, 'separador/banner decorativo — divida o arquivo em vez de decorá-lo');
+        break;
+      }
+    }
+    for (const [re, motivo] of RASTREIO) {
+      if (re.test(texto)) { marca(inicio + 1, `${motivo} — isso mora no commit ou em docs/, não no código`); break; }
+    }
+    if (DATA.test(texto)) marca(inicio + 1, 'data de mudança no comentário — o git já registra isso');
+    for (let k = 0; k < conteudo.length; k++) {
+      if (conteudo[k] && CODIGO_TOKEN.test(conteudo[k]) && CODIGO_FIM.test(conteudo[k])) {
+        marca(inicio + k + 1, 'código comentado — apague, o git guarda');
+        break;
+      }
+    }
+
+    let proxima = fim + 1;
+    while (proxima < linhas.length && !linhas[proxima].trim()) proxima++;
+    const ehDocstring =
+      /^(\/\*\*|"""|'''|\/\/\/)/.test(linhas[inicio].trim()) &&
+      proxima < linhas.length &&
+      ehComentario[proxima] === null;
+    const teto = ehDocstring ? MAX_DOCSTRING : MAX_BLOCO;
+    if (corpo.length > teto) {
+      marca(inicio + 1, `bloco de ${corpo.length} linhas (teto ${teto}) — mova o rationale para o commit ou docs/`);
+    }
+
+    // `ehDocstring` exclui o caso do primeiro símbolo do arquivo já vir documentado:
+    // isso é docstring do símbolo, não cabeçalho.
+    if (primeiroCodigo !== -1 && inicio < primeiroCodigo && !ehDocstring && !CABECALHO_PERMITIDO.test(texto)) {
+      marca(inicio + 1, 'cabeçalho de arquivo — proibido; o nome do arquivo e os exports já dizem o que ele é');
+    }
+  }
+
+  const comentadas = ehComentario.filter((c) => c !== null).length;
+  const uteis = linhas.filter((l) => l.trim()).length;
+  return { achados, comentadas, uteis, densidade: uteis ? comentadas / uteis : 0 };
+}
+
+function elegivel(caminho) {
+  return EXTENSOES.has(extname(caminho)) && !IGNORAR.some((re) => re.test(caminho));
+}
+
+const raiz = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const BASELINE = join(raiz, '.claude', 'hooks', 'comentarios', 'baseline.json');
+
+function varrer(dir, saida = []) {
+  let itens;
+  try { itens = readdirSync(dir, { withFileTypes: true }); } catch { return saida; }
+  for (const item of itens) {
+    const cheio = join(dir, item.name);
+    if (item.isDirectory()) {
+      if (item.name === 'node_modules' || item.name === '.git') continue;
+      if (IGNORAR.some((re) => re.test(`${cheio}/`))) continue;
+      varrer(cheio, saida);
+    } else if (elegivel(cheio)) saida.push(cheio);
+  }
+  return saida;
+}
+
+if (process.argv.includes('--gerar-baseline')) {
+  const mapa = {};
+  let arquivos = 0;
+  let violacoes = 0;
+  for (const f of varrer(raiz)) {
+    let fonte;
+    try { fonte = readFileSync(f, 'utf8'); } catch { continue; }
+    const { achados } = analisar(f, fonte);
+    if (achados.length > 0) { mapa[relative(raiz, f)] = achados.length; arquivos++; violacoes += achados.length; }
+  }
+  if (!existsSync(dirname(BASELINE))) mkdirSync(dirname(BASELINE), { recursive: true });
+  writeFileSync(BASELINE, `${JSON.stringify(mapa, null, 2)}\n`);
+  console.log(`[comentarios] baseline gravado: ${arquivos} arquivos legados, ${violacoes} violações toleradas.`);
+  console.log('[comentarios] arquivo novo responde ao padrão cheio; legado só não pode piorar.');
+  process.exit(0);
+}
+
+if (process.env.COMENTARIOS_CHECK === 'off') process.exit(0);
+
+let payload = null;
+try { payload = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+const caminho = payload?.tool_input?.file_path;
+if (!caminho || !elegivel(caminho)) process.exit(0);
+
+let fonte;
+try { fonte = readFileSync(caminho, 'utf8'); } catch { process.exit(0); }
+
+const { achados, comentadas, uteis, densidade } = analisar(caminho, fonte);
+const chave = relative(raiz, caminho);
+const rel = !chave || chave.startsWith('..') ? caminho : chave;
+
+let baseline = null;
+try { baseline = JSON.parse(readFileSync(BASELINE, 'utf8')); } catch {}
+const tolerado = baseline?.[chave] ?? 0;
+
+if (achados.length <= tolerado) {
+  if (baseline && tolerado > 0 && achados.length < tolerado) {
+    if (achados.length === 0) delete baseline[chave];
+    else baseline[chave] = achados.length;
+    try { writeFileSync(BASELINE, `${JSON.stringify(baseline, null, 2)}\n`); } catch {}
+    console.error(`[comentarios] ${rel}: ${tolerado} → ${achados.length} violações. Catraca desceu — não pode mais subir.`);
+  } else if (achados.length === 0 && densidade > DENSIDADE_ALVO) {
+    console.error(`[comentarios] aviso: ${rel} tem ${(densidade * 100).toFixed(0)}% de linhas de comentário (${comentadas}/${uteis}), alvo <= ${DENSIDADE_ALVO * 100}%.`);
+  }
+  process.exit(0);
+}
+
+const lista = achados.sort((a, b) => a.linha - b.linha).map((a) => `  ${rel}:${a.linha}  ${a.msg}`);
+const contexto =
+  tolerado > 0
+    ? `Este arquivo é legado: a baseline tolera ${tolerado} violação(ões) e agora há ${achados.length}. Não é preciso limpar o arquivo inteiro — basta não piorá-lo.`
+    : 'Este arquivo não tem tolerância na baseline: vale o padrão cheio.';
+
+console.error(
+  [
+    `[comentarios] ${rel} viola a rule .claude/rules/comentarios.md:`,
+    '',
+    ...lista,
+    '',
+    contexto,
+    'Tetos: bloco interno <= 3 linhas, docstring pública <= 5, cabeçalho de arquivo proibido.',
+    'Task/plano/data/achado de review e rationale longo vão para a mensagem de commit ou docs/ — nunca para o código.',
+    'Corrija no próprio arquivo antes de continuar a task.',
+  ].join('\n'),
+);
+process.exit(2);

package/templates/hooks/hooks.json

@@ -0,0 +1,34 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/lembrete.mjs\"" }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          { "type": "command", "if": "Bash(git commit *)", "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/segredo-no-commit.mjs\"" }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/proteger-contratos.mjs\"" }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/task-so-fecha-verde.mjs\"" },
+          { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/templates/hooks/sem-jargao.mjs\"" }
+        ]
+      }
+    ]
+  }
+}

package/templates/hooks/lembrete.mjs

@@ -0,0 +1,29 @@
+// @ts-check
+// Hook UserPromptSubmit: quando o pedido parece bug, feature, segurança ou performance,
+// lembra o modelo de seguir o fluxo do harness em vez de agir por conta própria.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { runHook } from './lib/hook.mjs';
+import { classifyPrompt } from './lib/temas.mjs';
+
+/**
+ * @param {string} root
+ * @param {string} id
+ */
+function installed(root, id) {
+  return existsSync(join(root, '.claude', 'commands', `${id}.md`)) || existsSync(join(root, '.claude', 'skills', id, 'SKILL.md'));
+}
+
+await runHook('lembrete', (input, { root }) => {
+  const match = classifyPrompt(String(input.prompt ?? ''));
+  if (!match) return null;
+
+  // No plugin os fluxos existem sempre, com prefixo; instalado pelo init, só sugere o que está no projeto.
+  const plugin = Boolean(process.env.CLAUDE_PLUGIN_ROOT);
+  if (!plugin && !installed(root, match.comando)) return null;
+  const command = plugin ? `/fontdata:${match.comando}` : `/${match.comando}`;
+
+  return {
+    motivo: `Este pedido parece ${match.descricao}. Antes de agir por conta própria, siga o fluxo ${command} (${match.fluxo}).`,
+  };
+});

package/templates/hooks/lib/config.mjs

@@ -0,0 +1,40 @@
+// @ts-check
+// Modo de cada hook lido da config do projeto (.ai-harness/config.json).
+// Sem dependências: roda também no plugin instalado a partir do GitHub.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** @typedef {'aviso' | 'bloqueio' | 'desligado'} HookMode */
+
+/**
+ * Mesmos padrões de src/config/config.ts: segurança nasce em bloqueio, método em aviso.
+ * @type {Record<string, HookMode>}
+ */
+export const DEFAULT_HOOK_MODES = {
+  lembrete: 'aviso',
+  'segredo-no-commit': 'bloqueio',
+  'task-so-fecha-verde': 'aviso',
+  'proteger-contratos': 'aviso',
+  'sem-jargao': 'aviso',
+};
+
+/** @type {HookMode[]} */
+const MODES = ['aviso', 'bloqueio', 'desligado'];
+
+/**
+ * Modo configurado para o hook; config ausente, ilegível ou com valor inválido cai no padrão.
+ * @param {string} root
+ * @param {string} hook
+ * @returns {HookMode}
+ */
+export function hookMode(root, hook) {
+  const fallback = DEFAULT_HOOK_MODES[hook] ?? 'aviso';
+  const file = join(root, '.ai-harness', 'config.json');
+  if (!existsSync(file)) return fallback;
+  try {
+    const mode = JSON.parse(readFileSync(file, 'utf8'))?.hooks?.[hook];
+    return MODES.includes(mode) ? mode : fallback;
+  } catch {
+    return fallback;
+  }
+}

package/templates/hooks/lib/hook.mjs

@@ -0,0 +1,85 @@
+// @ts-check
+// Esqueleto comum dos hooks do ai-harness: lê o evento do stdin, respeita o modo da config,
+// responde no protocolo do Claude Code e registra no rastro. Sem dependências.
+import { DEFAULT_HOOK_MODES, hookMode } from './config.mjs';
+import { recordEvent } from './rastro.mjs';
+
+/**
+ * @typedef {{ motivo: string }} Violation
+ * @typedef {{ root: string, mode: 'aviso' | 'bloqueio' }} HookContext
+ * @callback Handler
+ * @param {Record<string, any>} input
+ * @param {HookContext} context
+ * @returns {Promise<Violation | null> | Violation | null}
+ */
+
+async function readStdin() {
+  let data = '';
+  for await (const chunk of process.stdin) data += chunk;
+  return data;
+}
+
+/**
+ * Resposta no formato de cada evento: em `PreToolUse` o bloqueio nega a permissão e o aviso só
+ * acrescenta contexto; nos demais eventos o bloqueio usa `decision: "block"`.
+ * @param {string} event
+ * @param {'aviso' | 'bloqueio'} mode
+ * @param {string} message
+ */
+function response(event, mode, message) {
+  if (event === 'PreToolUse') {
+    return mode === 'bloqueio'
+      ? { hookSpecificOutput: { hookEventName: event, permissionDecision: 'deny', permissionDecisionReason: message } }
+      : { hookSpecificOutput: { hookEventName: event, additionalContext: message } };
+  }
+  if (mode === 'bloqueio') return { decision: 'block', reason: message };
+  return { hookSpecificOutput: { hookEventName: event, additionalContext: message } };
+}
+
+/**
+ * Executa um hook. O handler devolve `{ motivo }` quando há algo a avisar ou bloquear, ou null.
+ * Erros falham abertos (não atrapalham o usuário), exceto em hook de segurança no modo bloqueio.
+ * @param {string} name
+ * @param {Handler} handler
+ */
+export async function runHook(name, handler) {
+  /** @type {any} */
+  let input;
+  try {
+    input = JSON.parse(await readStdin());
+  } catch {
+    return;
+  }
+  if (typeof input !== 'object' || input === null) return;
+
+  const root = process.env.CLAUDE_PROJECT_DIR || input.cwd || process.cwd();
+  const mode = hookMode(root, name);
+  if (mode === 'desligado') return;
+
+  /** @type {Violation | null} */
+  let violation;
+  try {
+    violation = await handler(input, { root, mode });
+  } catch (error) {
+    if (mode !== 'bloqueio' || DEFAULT_HOOK_MODES[name] !== 'bloqueio') return;
+    const reason = error instanceof Error ? error.message : String(error);
+    violation = { motivo: `o hook não conseguiu verificar (${reason}); por segurança, a ação foi bloqueada.` };
+  }
+  if (!violation) return;
+
+  const message = `[ai-harness · ${name}] ${violation.motivo}`;
+  process.stdout.write(JSON.stringify(response(String(input.hook_event_name ?? ''), mode, message)));
+
+  try {
+    recordEvent(root, {
+      evento: mode === 'bloqueio' ? 'hook_bloqueio' : 'hook_aviso',
+      origem: 'hook',
+      nome: name,
+      modo: mode,
+      resultado: mode,
+      dados: { motivo: violation.motivo.slice(0, 1000) },
+    });
+  } catch {
+    // o rastro nunca impede a resposta do hook.
+  }
+}