@fontdata/ai-harness 2.0.0 → 2.1.0

package/templates/hooks/lib/rastro.mjs

@@ -0,0 +1,130 @@
+// @ts-check
+// Gravação do rastro de eventos (contrato em docs/contratos/EVENTOS.md do ai-harness).
+// Sem dependências: roda também no plugin instalado a partir do GitHub, que não tem node_modules.
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const EVENT_VERSION = 1;
+export const MAX_LINE_BYTES = 4096;
+export const MAX_FILE_BYTES = 5 * 1024 * 1024;
+
+export const EVENTS = [
+  'trabalho_iniciado',
+  'trabalho_concluido',
+  'task_iniciada',
+  'task_concluida',
+  'suite_verde',
+  'suite_vermelha',
+  'hook_aviso',
+  'hook_bloqueio',
+  'agent_veredito',
+  'bloqueio_aberto',
+  'bloqueio_fechado',
+  'decisao_registrada',
+  'relatorio_gerado',
+];
+
+/**
+ * @typedef {object} EventFields
+ * @property {string | null} [trabalhoId] Sem valor, usa o trabalho ativo do projeto.
+ * @property {string} evento
+ * @property {'hook' | 'comando' | 'agent' | 'cli'} origem
+ * @property {string} nome
+ * @property {string | null} [taskId]
+ * @property {'aviso' | 'bloqueio' | 'desligado' | null} [modo]
+ * @property {'ok' | 'aviso' | 'bloqueio' | 'falha' | null} [resultado]
+ * @property {Record<string, unknown> | null} [dados]
+ * @property {Date} [now]
+ */
+
+/**
+ * Monta o evento com as chaves na ordem do contrato.
+ * @param {EventFields} fields
+ */
+export function buildEvent(fields) {
+  if (!EVENTS.includes(fields.evento)) {
+    throw new Error(`Evento fora do vocabulário do rastro: ${fields.evento}. Veja docs/contratos/EVENTOS.md.`);
+  }
+  return {
+    v: EVENT_VERSION,
+    ts: (fields.now ?? new Date()).toISOString(),
+    trabalho_id: fields.trabalhoId ?? null,
+    evento: fields.evento,
+    origem: fields.origem,
+    nome: fields.nome,
+    task_id: fields.taskId ?? null,
+    modo: fields.modo ?? null,
+    resultado: fields.resultado ?? null,
+    dados: fields.dados ?? null,
+  };
+}
+
+/**
+ * Trabalho ativo: o `trabalho_ativo` do .ai-harness/estado.json ou, sem ele,
+ * o único PLAN.md com `status: em-execucao`. Ambíguo ou ausente, retorna null.
+ * @param {string} root
+ * @returns {string | null}
+ */
+export function findActiveWork(root) {
+  const statePath = join(root, '.ai-harness', 'estado.json');
+  if (existsSync(statePath)) {
+    try {
+      const active = JSON.parse(readFileSync(statePath, 'utf8')).trabalho_ativo;
+      if (typeof active === 'string' && active) return active;
+    } catch {
+      // estado ilegível: segue para os planos.
+    }
+  }
+
+  const worksDir = join(root, 'docs', 'trabalhos');
+  if (!existsSync(worksDir)) return null;
+
+  const running = readdirSync(worksDir).filter((id) => {
+    const plan = join(worksDir, id, 'PLAN.md');
+    if (!existsSync(plan)) return false;
+    const frontmatter = /^\s*---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(plan, 'utf8'))?.[1] ?? '';
+    // Só o status do plano, na coluna zero; os status das tasks ficam indentados.
+    return /^status:\s*['"]?em-execucao['"]?\s*$/m.test(frontmatter);
+  });
+  return running.length === 1 ? (running[0] ?? null) : null;
+}
+
+/**
+ * Renomeia o arquivo para `.1.jsonl` (empurrando os anteriores) quando a próxima linha passaria do limite.
+ * @param {string} file
+ * @param {number} incoming
+ * @param {number} maxBytes
+ */
+function rotateIfNeeded(file, incoming, maxBytes) {
+  if (!existsSync(file) || statSync(file).size + incoming <= maxBytes) return;
+  const base = file.slice(0, -'.jsonl'.length);
+  let last = 1;
+  while (existsSync(`${base}.${last}.jsonl`)) last++;
+  for (let i = last - 1; i >= 1; i--) renameSync(`${base}.${i}.jsonl`, `${base}.${i + 1}.jsonl`);
+  renameSync(file, `${base}.1.jsonl`);
+}
+
+/**
+ * Grava um evento no rastro do trabalho (ou em _geral.jsonl, sem trabalho ativo).
+ * @param {string} root Raiz do projeto.
+ * @param {EventFields} fields
+ * @param {{ maxBytes?: number }} [options]
+ */
+export function recordEvent(root, fields, options = {}) {
+  const trabalhoId = fields.trabalhoId === undefined ? findActiveWork(root) : fields.trabalhoId;
+  const event = buildEvent({ ...fields, trabalhoId });
+  const line = `${JSON.stringify(event)}\n`;
+  const size = Buffer.byteLength(line);
+
+  // Linhas de até 4 KB mantêm atômicos os appends concorrentes (O_APPEND) em sistemas POSIX.
+  if (size > MAX_LINE_BYTES) {
+    throw new Error(`Evento acima de 4 KB (${size} bytes): grave o texto longo num artefato e referencie o caminho em dados.`);
+  }
+
+  const dir = join(root, 'docs', 'eventos');
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, `${trabalhoId ?? '_geral'}.jsonl`);
+  rotateIfNeeded(file, size, options.maxBytes ?? MAX_FILE_BYTES);
+  appendFileSync(file, line);
+  return event;
+}

package/templates/hooks/lib/segredos.mjs

@@ -0,0 +1,91 @@
+// @ts-check
+// Detecção de segredos nas linhas adicionadas de um diff. Sem dependências.
+// Os achados nunca incluem o valor encontrado, só o arquivo, a linha e o tipo.
+import { basename } from 'node:path';
+
+/** @typedef {{ arquivo: string, linha: number, tipo: string }} Finding */
+
+const PATTERNS = [
+  { tipo: 'chave de acesso AWS', padrao: /\b(AKIA|ASIA)[0-9A-Z]{16}\b/ },
+  { tipo: 'segredo AWS', padrao: /aws_secret_access_key\s*[:=]\s*['"]?[A-Za-z0-9/+=]{40}/i },
+  { tipo: 'token do GitHub', padrao: /\b(gh[pousr]_[A-Za-z0-9]{36,}|github_pat_[A-Za-z0-9_]{50,})/ },
+  { tipo: 'token do npm', padrao: /\bnpm_[A-Za-z0-9]{36}\b/ },
+  { tipo: 'token do Slack', padrao: /\bxox[abprs]-[A-Za-z0-9-]{10,}/ },
+  { tipo: 'chave de API do Google', padrao: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+  { tipo: 'chave privada', padrao: /-----BEGIN ([A-Z]+ )?PRIVATE KEY-----/ },
+];
+
+const ASSIGNED_SECRET = /\b(password|passwd|senha|secret|api[_-]?key|access[_-]?token|token)\b\s*[:=]\s*['"]([^'"]{8,})['"]/i;
+const ENV_LINE = /^\s*(?:export\s+)?[A-Za-z_][A-Za-z0-9_]*\s*=\s*(.*)$/;
+const PLACEHOLDER = /^(x+|\*+|changeme|change-me|example|exemplo|placeholder|senha|password|secret|todo|<.*>|\$\{.*\}|(your|sua|seu)[-_ ].*)$/i;
+
+/** @param {string} value */
+function isPlaceholder(value) {
+  return PLACEHOLDER.test(value.trim().replace(/^['"]|['"]$/g, ''));
+}
+
+/**
+ * `.env`, `.env.local`, `.env.production`... mas não `.env.example`, `.env.sample` ou `.env.template`.
+ * @param {string} path
+ */
+function isEnvFile(path) {
+  const name = basename(path);
+  return /^\.env(\..+)?$/.test(name) && !/\.(example|sample|template|dist)$/.test(name);
+}
+
+/**
+ * @param {string} path
+ * @param {string} content Linha adicionada, sem o `+`.
+ * @returns {string | null} Tipo do segredo encontrado.
+ */
+function secretIn(path, content) {
+  const known = PATTERNS.find(({ padrao }) => padrao.test(content));
+  if (known) return known.tipo;
+
+  if (isEnvFile(path)) {
+    const value = ENV_LINE.exec(content)?.[1]?.trim() ?? '';
+    return value && !isPlaceholder(value) ? 'valor em arquivo .env' : null;
+  }
+
+  const assigned = ASSIGNED_SECRET.exec(content);
+  return assigned && !isPlaceholder(assigned[2] ?? '') ? 'senha ou token atribuído no código' : null;
+}
+
+/**
+ * Varre as linhas adicionadas de um diff unificado (`git diff --cached`).
+ * @param {string} diff
+ * @returns {Finding[]}
+ */
+export function scanDiff(diff) {
+  /** @type {Finding[]} */
+  const findings = [];
+  const seen = new Set();
+  let file = '';
+  let line = 0;
+
+  for (const raw of diff.split('\n')) {
+    if (raw.startsWith('+++ ')) {
+      file = raw === '+++ /dev/null' ? '' : raw.slice(4).replace(/^b\//, '');
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)/.exec(raw);
+    if (hunk) {
+      line = Number(hunk[1]);
+      continue;
+    }
+    if (!file || raw.startsWith('---')) continue;
+
+    if (raw.startsWith('+')) {
+      const tipo = secretIn(file, raw.slice(1));
+      const key = `${file}:${tipo}`;
+      if (tipo && !seen.has(key)) {
+        seen.add(key);
+        findings.push({ arquivo: file, linha: line, tipo });
+      }
+      line++;
+    } else if (raw.startsWith(' ')) {
+      line++;
+    }
+  }
+  return findings;
+}

package/templates/hooks/lib/temas.mjs

@@ -0,0 +1,111 @@
+// @ts-check
+// Classificação do prompt para o hook de lembrete: qual fluxo do harness o pedido pede.
+// Sem dependências; roda a cada prompt, então precisa ser barata.
+
+/**
+ * @typedef {object} Theme
+ * @property {'seguranca' | 'bug' | 'performance' | 'feature'} tema
+ * @property {string} comando Id do fluxo sugerido.
+ * @property {string} descricao Como o pedido é descrito na sugestão.
+ * @property {string} fluxo O que o fluxo garante.
+ * @property {RegExp[]} padroes Aplicados ao prompt normalizado (minúsculas, sem acento).
+ */
+
+/**
+ * Em ordem de prioridade: quando um prompt casa com mais de um tema, vale o primeiro.
+ * @type {Theme[]}
+ */
+export const THEMES = [
+  {
+    tema: 'seguranca',
+    comando: 'auditar-seguranca',
+    descricao: 'um risco de segurança ou de dados pessoais',
+    fluxo: 'auditoria defensiva com conformidade LGPD e relatório',
+    padroes: [
+      /\bvazamento\b/,
+      /\bdados pessoais\b/,
+      /\blgpd\b/,
+      /\bsql injection\b/,
+      /\binjecao de sql\b/,
+      /\bxss\b/,
+      /\bcsrf\b/,
+      /\bvulnerabilidade/,
+      /\bpentest\b/,
+      /\b(senha|token|chave|segredo|credencial)s? [\w ]{0,25}\b(expost|vazad)/,
+    ],
+  },
+  {
+    tema: 'bug',
+    comando: 'resolver-bug',
+    descricao: 'um relato de bug',
+    fluxo: 'investigação da causa raiz, plano aprovado e correção com TDD',
+    padroes: [
+      /\bnao (esta )?funciona/,
+      /\bparou de funcionar\b/,
+      /\b(dando|deu|da|com) erro\b/,
+      /\berro ao\b/,
+      /\b(valor|calculo|total|preco|frete|saldo|imposto|desconto)\b[\w ]{0,30}\berrad[oa]s?\b/,
+      /\b(esta|ficou|veio|saiu|vem) errad[oa]s?\b/,
+      /\bquebrou\b/,
+      /\bexception\b/,
+      /\bexcecao\b/,
+      /\bstack ?trace\b/,
+      /\bbug\b/,
+      /\bnao (esta )?(salvando|aparecendo|carregando|gravando|enviando)\b/,
+      /\bcrash/,
+    ],
+  },
+  {
+    tema: 'performance',
+    comando: 'auditar-performance',
+    descricao: 'um problema de performance',
+    fluxo: 'medição e auditoria dos gargalos antes de otimizar',
+    padroes: [
+      /\blent[oa]s?\b/,
+      /\blentidao\b/,
+      /\bdemora/,
+      /\btravand/,
+      /\btimeout\b/,
+      /\bgargalo/,
+      /\bperformance\b/,
+      /\bconsumo (alto )?de (memoria|cpu)\b/,
+    ],
+  },
+  {
+    tema: 'feature',
+    comando: 'nova-tarefa',
+    descricao: 'uma funcionalidade nova',
+    fluxo: 'spec e plano aprovados antes de implementar',
+    padroes: [
+      /\bimplementar\b/,
+      /\b(crie|criar|desenvolver|desenvolva) (uma |um )?(nova |novo )?(tela|funcionalidade|modulo|endpoint|relatorio|cadastro)/,
+      /\bnova funcionalidade\b/,
+      /\b(adicionar|adicione|incluir|inclua) (uma |um )?(nova |novo )?funcionalidade\b/,
+      /\bquero que o sistema\b/,
+    ],
+  },
+];
+
+/**
+ * Minúsculas, sem acento e com espaços simples.
+ * @param {string} text
+ */
+export function normalize(text) {
+  return text.normalize('NFD').replace(/\p{Diacritic}/gu, '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Tema do prompt, ou null quando nenhum casa, quando o prompt já é um slash command ou quando é uma
+ * mensagem do próprio Claude Code (notificação de agent em segundo plano, lembrete do sistema).
+ * @param {string} prompt
+ * @returns {Omit<Theme, 'padroes'> | null}
+ */
+export function classifyPrompt(prompt) {
+  if (typeof prompt !== 'string' || prompt.trim().startsWith('/')) return null;
+  if (/<(task-notification|system-reminder)\b/.test(prompt)) return null;
+  const text = normalize(prompt);
+  const match = THEMES.find((theme) => theme.padroes.some((pattern) => pattern.test(text)));
+  if (!match) return null;
+  const { padroes: _padroes, ...theme } = match;
+  return theme;
+}

package/templates/hooks/lib/trabalho.mjs

@@ -0,0 +1,94 @@
+// @ts-check
+// Leitura de trabalhos para os hooks de método: caminhos, tasks do PLAN.md e eventos do rastro.
+// Sem dependências: o frontmatter é lido linha a linha, no formato do contrato de artefatos.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, sep } from 'node:path';
+
+/**
+ * Caminho relativo à raiz do projeto com `/`; null quando está fora dele.
+ * @param {string} root
+ * @param {string} file
+ */
+export function relativeToRoot(root, file) {
+  if (!file) return null;
+  const rel = relative(root, file).split(sep).join('/');
+  return !rel || rel.startsWith('..') ? null : rel;
+}
+
+/** @param {string} content */
+function frontmatter(content) {
+  return /^\s*---\r?\n([\s\S]*?)\r?\n---/.exec(content)?.[1] ?? '';
+}
+
+/**
+ * Tasks (id e status) do frontmatter de um PLAN.md. Só considera os itens no nível da lista
+ * `tasks`, para que textos em listas internas (como testes_criticos) não virem tasks.
+ * @param {string} content
+ * @returns {Array<{ id: string, status: string }>}
+ */
+export function planTasks(content) {
+  /** @type {Array<{ id?: string, status?: string }>} */
+  const tasks = [];
+  /** @type {{ id?: string, status?: string } | null} */
+  let current = null;
+  let inTasks = false;
+  let itemIndent = -1;
+
+  for (const line of frontmatter(content).split(/\r?\n/)) {
+    if (/^tasks:/.test(line)) {
+      inTasks = true;
+      continue;
+    }
+    if (!inTasks) continue;
+    if (/^\S/.test(line)) break;
+
+    const item = /^(\s*)-\s+(\w+):\s*(.*)$/.exec(line);
+    if (item && (itemIndent === -1 || (item[1] ?? '').length === itemIndent)) {
+      itemIndent = (item[1] ?? '').length;
+      current = {};
+      tasks.push(current);
+      assign(current, item[2] ?? '', item[3] ?? '');
+      continue;
+    }
+    const field = /^(\s+)(\w+):\s*(.*)$/.exec(line);
+    if (field && current && (field[1] ?? '').length === itemIndent + 2) assign(current, field[2] ?? '', field[3] ?? '');
+  }
+  return /** @type {Array<{ id: string, status: string }>} */ (tasks.filter((task) => task.id));
+}
+
+/**
+ * @param {{ id?: string, status?: string }} task
+ * @param {string} key
+ * @param {string} raw
+ */
+function assign(task, key, raw) {
+  if (key === 'id' || key === 'status') task[key] = raw.trim().replace(/^['"]|['"]$/g, '');
+}
+
+/**
+ * Eventos do rastro de um trabalho, incluindo arquivos rotacionados; null quando não há rastro nesta máquina.
+ * @param {string} root
+ * @param {string} workId
+ * @returns {Array<Record<string, unknown>> | null}
+ */
+export function workEvents(root, workId) {
+  const dir = join(root, 'docs', 'eventos');
+  if (!existsSync(dir)) return null;
+  const files = readdirSync(dir).filter(
+    (name) => name === `${workId}.jsonl` || (name.startsWith(`${workId}.`) && /^\d+\.jsonl$/.test(name.slice(workId.length + 1)))
+  );
+  if (!files.length) return null;
+
+  /** @type {Array<Record<string, unknown>>} */
+  const events = [];
+  for (const file of files) {
+    for (const line of readFileSync(join(dir, file), 'utf8').split('\n')) {
+      try {
+        events.push(JSON.parse(line));
+      } catch {
+        // linha vazia ou incompleta.
+      }
+    }
+  }
+  return events;
+}

package/templates/hooks/proteger-contratos.mjs

@@ -0,0 +1,56 @@
+// @ts-check
+// Hook PreToolUse (Edit/Write): durante a execução de um trabalho, SPEC, PLAN e CLAUDE.md não são reescritos.
+// Atualizar só o status das tasks (e a data de atualização) continua permitido.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runHook } from './lib/hook.mjs';
+import { findActiveWork } from './lib/rastro.mjs';
+import { relativeToRoot, workEvents } from './lib/trabalho.mjs';
+
+const PROTECTED = [/^CLAUDE\.md$/, /^SPEC\.md$/, /^docs\/trabalhos\/[^/]+\/(SPEC|PLAN)\.md$/];
+const ALLOWED_LINE = /^\s*(-\s+)?(status|atualizado_em):/;
+
+/** @param {unknown} text */
+function withoutAllowedLines(text) {
+  return String(text ?? '')
+    .split(/\r?\n/)
+    .filter((line) => !ALLOWED_LINE.test(line))
+    .join('\n');
+}
+
+/**
+ * A edição só troca linhas de status e data?
+ * @param {string} root
+ * @param {string} rel
+ * @param {Record<string, any>} input
+ */
+function onlyStatusChange(root, rel, input) {
+  const toolInput = input.tool_input ?? {};
+  const sameEdit = (/** @type {Record<string, unknown>} */ edit) => withoutAllowedLines(edit.old_string) === withoutAllowedLines(edit.new_string);
+
+  if (input.tool_name === 'Edit') return sameEdit(toolInput);
+  if (input.tool_name === 'MultiEdit' && Array.isArray(toolInput.edits)) return toolInput.edits.every(sameEdit);
+  if (input.tool_name === 'Write') {
+    const file = join(root, rel);
+    return existsSync(file) && withoutAllowedLines(readFileSync(file, 'utf8')) === withoutAllowedLines(toolInput.content);
+  }
+  return false;
+}
+
+await runHook('proteger-contratos', (input, { root }) => {
+  const rel = relativeToRoot(root, String(input.tool_input?.file_path ?? ''));
+  if (!rel || !PROTECTED.some((pattern) => pattern.test(rel))) return null;
+
+  const active = findActiveWork(root);
+  const events = active ? workEvents(root, active) : null;
+  const running =
+    events !== null && events.some((event) => event.evento === 'task_iniciada') && !events.some((event) => event.evento === 'trabalho_concluido');
+  if (!active || !running || onlyStatusChange(root, rel, input)) return null;
+
+  return {
+    motivo:
+      `${rel} é contrato do trabalho ${active}, que está em execução, e não deve ser reescrito agora. ` +
+      `Registre a mudança de escopo em docs/trabalhos/${active}/DECISOES.md (ou abra um bloqueio em BLOQUEIOS.md); ` +
+      'no PLAN.md, só o status das tasks pode ser atualizado.',
+  };
+});

package/templates/hooks/segredo-no-commit.mjs

@@ -0,0 +1,76 @@
+// @ts-check
+// Hook PreToolUse (Bash `git commit`): impede commitar segredos. Nasce em modo bloqueio.
+import { execFileSync } from 'node:child_process';
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { runHook } from './lib/hook.mjs';
+import { scanDiff } from './lib/segredos.mjs';
+
+/**
+ * @param {string} root
+ * @param {string[]} args
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+const runGit = (root, args, env) =>
+  execFileSync('git', args, { cwd: root, env, encoding: 'utf8', maxBuffer: 50 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+
+/**
+ * Argumentos de um trecho do comando que chama o git, sem as aspas; `null` se o trecho não é git.
+ * @param {string} segment
+ */
+function gitArgs(segment) {
+  const words = segment.trim().split(/\s+/).map((word) => word.replace(/^['"]|['"]$/g, ''));
+  return words[0] === 'git' ? words.slice(1) : null;
+}
+
+/**
+ * Diff do que o commit vai gravar. Quando o hook dispara, os `git add` do mesmo comando
+ * (`git add x && git commit`) ainda não rodaram: eles são reproduzidos numa cópia do índice,
+ * sem tocar no stage real. Com `-a`/`--all` no commit entram as mudanças rastreadas fora do stage.
+ * @param {string} root
+ * @param {string} command
+ */
+function diffToCommit(root, command) {
+  const realIndex = resolve(root, runGit(root, ['rev-parse', '--git-path', 'index']).trim());
+  const dir = mkdtempSync(join(tmpdir(), 'ai-harness-segredo-'));
+  const index = join(dir, 'index');
+  if (existsSync(realIndex)) copyFileSync(realIndex, index);
+  const env = { ...process.env, GIT_INDEX_FILE: index };
+
+  try {
+    for (const segment of command.split(/&&|\|\||;|\n/)) {
+      const args = gitArgs(segment);
+      if (!args) continue;
+      try {
+        if (args[0] === 'add') runGit(root, args, env);
+        else if (args[0] === 'commit' && args.slice(1).some((arg) => arg === '--all' || /^-[A-Za-z]*a[A-Za-z]*$/.test(arg))) {
+          runGit(root, ['add', '-u'], env);
+        }
+      } catch {
+        // O git vai recusar esse trecho de verdade; o que deu para simular continua valendo.
+      }
+    }
+    return runGit(root, ['diff', '--cached', '--no-color', '--unified=0'], env);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+await runHook('segredo-no-commit', (input, { root }) => {
+  const command = String(input.tool_input?.command ?? '');
+  if (!/\bgit\b[^;&|]*\bcommit\b/.test(command)) return null;
+
+  const findings = scanDiff(diffToCommit(root, command));
+  if (!findings.length) return null;
+
+  const list = findings
+    .slice(0, 10)
+    .map((finding) => `${finding.arquivo}:${finding.linha} (${finding.tipo})`)
+    .join('; ');
+  return {
+    motivo:
+      `o commit inclui possível segredo em ${list}. Tire o arquivo do stage (git restore --staged <arquivo>), ` +
+      'leve o valor para uma variável de ambiente e, se a credencial já saiu desta máquina, troque-a.',
+  };
+});

package/templates/hooks/sem-jargao.mjs

@@ -0,0 +1,58 @@
+// @ts-check
+// Hook PostToolUse (Edit/Write): o relatório para o cliente é escrito na linguagem de quem usa o sistema.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runHook } from './lib/hook.mjs';
+import { normalize } from './lib/temas.mjs';
+import { relativeToRoot } from './lib/trabalho.mjs';
+
+/** Termos já normalizados (minúsculas, sem acento). */
+const TECHNICAL_TERMS = [
+  'endpoint',
+  'deploy',
+  'commit',
+  'merge',
+  'branch',
+  'pull request',
+  'refactor',
+  'refatoracao',
+  'stack trace',
+  'exception',
+  'excecao',
+  'null',
+  'undefined',
+  'query',
+  'sql',
+  'json',
+  'api',
+  'frontend',
+  'backend',
+  'hotfix',
+  'regex',
+  'cache',
+  'payload',
+  'schema',
+  'timeout',
+  'runtime',
+  'script',
+  'bug',
+];
+
+await runHook('sem-jargao', (input, { root }) => {
+  const rel = relativeToRoot(root, String(input.tool_input?.file_path ?? ''));
+  if (!rel || !/^docs\/trabalhos\/[^/]+\/relatorios\/CLIENTE\.md$/.test(rel)) return null;
+
+  const file = join(root, rel);
+  if (!existsSync(file)) return null;
+
+  const body = readFileSync(file, 'utf8').replace(/^\s*---\r?\n[\s\S]*?\r?\n---/, '');
+  const words = ` ${normalize(body).replace(/[^a-z0-9]+/g, ' ')} `;
+  const found = TECHNICAL_TERMS.filter((term) => words.includes(` ${term} `));
+  if (!found.length) return null;
+
+  return {
+    motivo:
+      `o relatório para o cliente usa termos técnicos: ${found.slice(0, 8).join(', ')}. ` +
+      'Reescreva na linguagem de quem usa o sistema (o que acontecia e o que muda para ele); o detalhe técnico fica no TECNICO.md.',
+  };
+});

package/templates/hooks/task-so-fecha-verde.mjs

@@ -0,0 +1,33 @@
+// @ts-check
+// Hook PostToolUse (Edit/Write): avisa quando o PLAN.md tem task concluída sem suíte verde no rastro.
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { runHook } from './lib/hook.mjs';
+import { planTasks, relativeToRoot, workEvents } from './lib/trabalho.mjs';
+
+await runHook('task-so-fecha-verde', (input, { root }) => {
+  const rel = relativeToRoot(root, String(input.tool_input?.file_path ?? ''));
+  const match = rel ? /^docs\/trabalhos\/([^/]+)\/PLAN\.md$/.exec(rel) : null;
+  if (!rel || !match) return null;
+
+  const workId = match[1] ?? '';
+  const events = workEvents(root, workId);
+  if (!events || !existsSync(join(root, rel))) return null;
+
+  const green = new Set(events.filter((event) => event.evento === 'suite_verde').map((event) => event.task_id));
+  // Task concluída antes de o rastro existir (sem task_iniciada nem task_concluida) não é cobrada.
+  const tracked = new Set(
+    events.filter((event) => event.evento === 'task_iniciada' || event.evento === 'task_concluida').map((event) => event.task_id)
+  );
+  const missing = planTasks(readFileSync(join(root, rel), 'utf8'))
+    .filter((task) => task.status === 'concluida' && tracked.has(task.id) && !green.has(task.id))
+    .map((task) => task.id);
+  if (!missing.length) return null;
+
+  return {
+    motivo:
+      `${missing.join(', ')} está marcada como concluída em ${rel}, mas o rastro não registra suíte verde para ela. ` +
+      `Rode a suíte e registre o resultado (npx @fontdata/ai-harness evento suite_verde --trabalho ${workId} --task <id> ` +
+      `--dados '{"comando":"<comando>","total":<n>,"falhas":0}') ou volte a task para em-andamento.`,
+  };
+});