@fontdata/ai-harness 2.0.0 → 2.2.0

package/dist/update/legado.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { templatesDir } from '../catalog.js';
+import { hashContent, LOCK_VERSION } from '../install/lock.js';
+/**
+ * Rules eram transcritas pelo modelo a partir do bloco do comando e, em vários projetos, passaram depois por um
+ * formatador. Por isso o manifesto guarda, para elas, o hash do texto normalizado: sem linhas em branco, sem espaço
+ * no fim das linhas e com as tabelas reduzidas ao conteúdo das células.
+ */
+export function normalizeText(text) {
+    const lines = text
+        .replace(/\r\n/g, '\n')
+        .split('\n')
+        .map((line) => line.replace(/\s+$/, ''))
+        .filter((line) => line !== '')
+        .map((line) => {
+        if (!line.trimStart().startsWith('|'))
+            return line;
+        const cells = line.split('|').map((cell) => cell.trim());
+        return cells.map((cell) => (/^:?-{3,}:?$/.test(cell) ? cell.replace(/-+/, '---') : cell)).join(' | ').trim();
+    });
+    return `${lines.join('\n')}\n`;
+}
+export function loadLegacyManifest() {
+    return JSON.parse(readFileSync(join(templatesDir, 'legado', 'manifesto.json'), 'utf8'));
+}
+/**
+ * Reconhece uma instalação anterior à 2.1, que não gravava lock, pelos caminhos que as versões
+ * publicadas instalavam, e monta o lock que o update compara em três pontas. Arquivo igual a
+ * qualquer versão publicada é intacto e entra com o próprio hash; arquivo editado entra com o
+ * hash da versão mais recente, para o update enxergar a alteração local. O CLAUDE.md só conta
+ * quando é igual a uma versão publicada, porque o nome não é exclusivo do harness.
+ */
+export function adoptLegacyInstall(root, manifest = loadLegacyManifest()) {
+    const order = (version) => manifest.versoes.indexOf(version);
+    const itens = [];
+    let newest = -1;
+    for (const item of manifest.itens) {
+        const arquivos = [];
+        for (const entry of item.arquivos) {
+            const local = join(root, entry.caminho);
+            if (!existsSync(local))
+                continue;
+            const content = readFileSync(local);
+            const hash = hashContent(content);
+            const versions = entry.hashes[hash] ?? (item.tipo === 'rule' ? entry.hashes[hashContent(normalizeText(content.toString('utf8')))] : undefined);
+            if (versions) {
+                newest = Math.max(newest, ...versions.map(order));
+                arquivos.push({ caminho: entry.caminho, sha256: hash });
+            }
+            else if (item.tipo !== 'claude-md') {
+                arquivos.push({ caminho: entry.caminho, sha256: latestHash(entry.hashes, order) });
+            }
+        }
+        if (arquivos.length)
+            itens.push({ tipo: item.tipo, id: item.id, arquivos });
+    }
+    if (!itens.length)
+        return null;
+    const versao = manifest.versoes[newest] ?? manifest.versoes.at(-1) ?? '2.0.0';
+    return { lock_versao: LOCK_VERSION, pacote: { nome: '@fontdata/ai-harness', versao }, gerado_em: '', itens };
+}
+function latestHash(hashes, order) {
+    let latest = '';
+    let latestOrder = -Infinity;
+    for (const [hash, versions] of Object.entries(hashes)) {
+        const top = Math.max(...versions.map(order));
+        if (top > latestOrder) {
+            latest = hash;
+            latestOrder = top;
+        }
+    }
+    return latest;
+}

package/dist/update/update.js

@@ -0,0 +1,284 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { allCommands, loadCatalog } from '../catalog.js';
+import { commentsHooksConfig, ensureCommentsBaseline } from '../comentarios/instalar.js';
+import { readConfig, syncGitignore, writeDefaultConfig } from '../config/config.js';
+import { applyAtomically } from '../install/atomic.js';
+import { suggestFlag } from '../install/flags.js';
+import { HOOKS_ITEM_ID, isHarnessPluginEnabled, projectHooksConfig } from '../install/hooks.js';
+import { hashContent, LOCK_PATH, LOCK_VERSION, readLock, writeLock } from '../install/lock.js';
+import { itemSources, packageInfo, PROJECT_RULE_PATH, projectRuleContent } from '../install/plan.js';
+import { neededSkillsFor } from '../install/selection.js';
+import { combineHooks, HARNESS_PERMISSIONS, hasAllowRule, mergeSettings } from '../install/settings.js';
+import { adoptLegacyInstall } from './legado.js';
+/** `<id>-legado.md`, com sufixo numérico quando o nome já está em uso. */
+function legacyPath(root, path) {
+    const base = path.replace(/\.md$/, '');
+    for (let n = 1;; n += 1) {
+        const candidate = `${base}-legado${n === 1 ? '' : `-${n}`}.md`;
+        if (!existsSync(join(root, candidate)))
+            return candidate;
+    }
+}
+export function checkUpdate(root, catalog = loadCatalog(), legacy, home) {
+    const recorded = readLock(root);
+    const lock = recorded ?? adoptLegacyInstall(root, legacy);
+    if (!lock) {
+        throw new Error('Nenhuma instalação do ai-harness registrada neste projeto. Rode `npx @fontdata/ai-harness init` primeiro.');
+    }
+    const changes = [];
+    const stale = [];
+    for (const item of lock.itens) {
+        const key = `${item.tipo}:${item.id}`;
+        const sources = itemSources(catalog, item.tipo, item.id) ?? [];
+        const sourceByPath = new Map(sources.map((entry) => [entry.path, entry.source]));
+        for (const entry of item.arquivos) {
+            const local = join(root, entry.caminho);
+            const exists = existsSync(local);
+            const localChanged = exists && hashContent(readFileSync(local)) !== entry.sha256;
+            const source = sourceByPath.get(entry.caminho) ?? null;
+            if (!source) {
+                if (!exists)
+                    stale.push(entry.caminho);
+                else if (!localChanged)
+                    changes.push({ tipo: 'removido', caminho: entry.caminho, item: key, source });
+                // Comando editado que saiu do pacote: renomeado, para não sombrear a skill de mesmo nome (D-35).
+                else if (item.tipo === 'comando') {
+                    changes.push({ tipo: 'legado', caminho: entry.caminho, item: key, source, destino: legacyPath(root, entry.caminho) });
+                }
+                else
+                    changes.push({ tipo: 'conflito', caminho: entry.caminho, item: key, source });
+                continue;
+            }
+            const packageChanged = hashContent(readFileSync(source)) !== entry.sha256;
+            const tipo = !exists
+                ? 'faltando'
+                : packageChanged && localChanged
+                    ? 'conflito'
+                    : packageChanged
+                        ? 'alterado'
+                        : localChanged
+                            ? 'modificado-local'
+                            : null;
+            if (tipo)
+                changes.push({ tipo, caminho: entry.caminho, item: key, source });
+        }
+        const trackedPaths = new Set(item.arquivos.map((entry) => entry.caminho));
+        for (const { path, source } of sources) {
+            if (trackedPaths.has(path))
+                continue;
+            changes.push({ tipo: existsSync(join(root, path)) ? 'conflito' : 'novo', caminho: path, item: key, source });
+        }
+    }
+    // Itens que o lock não tem. Arquivo igual ao do pacote só entra no lock; `protect` mantém o do projeto mesmo com --forcar.
+    const trackedItems = new Set(lock.itens.map((item) => `${item.tipo}:${item.id}`));
+    const addItem = (tipo, id, protect) => {
+        const key = `${tipo}:${id}`;
+        if (trackedItems.has(key))
+            return;
+        trackedItems.add(key);
+        for (const { path, source } of itemSources(catalog, tipo, id) ?? []) {
+            const target = join(root, path);
+            const same = existsSync(target) && hashContent(readFileSync(target)) === hashContent(readFileSync(source));
+            const tipoMudanca = !existsSync(target) || same ? 'novo' : protect ? 'existente' : 'conflito';
+            changes.push({ tipo: tipoMudanca, caminho: path, item: key, source });
+        }
+    };
+    // Comando que virou skill, ou que foi incorporado a outro item (D-40 a D-43): quem o substitui entra como item
+    // novo, com as skills que exige.
+    const entries = [...allCommands(catalog), { ...catalog.master, group: '' }];
+    for (const item of lock.itens) {
+        if (item.tipo !== 'comando')
+            continue;
+        const successors = entries.filter((cmd) => (cmd.id === item.id && cmd.skill) || cmd.replaces?.includes(item.id));
+        for (const successor of successors) {
+            addItem(successor.skill ? 'skill' : 'comando', successor.id, false);
+            for (const skill of neededSkillsFor(catalog, [successor]))
+                addItem('skill', skill.id, false);
+        }
+    }
+    // Na adoção, a instalação antiga ganha o que a 2.1 instala e ela não tinha.
+    const adotada = !recorded;
+    const pluginHooks = adotada && isHarnessPluginEnabled(root, home);
+    if (adotada) {
+        for (const agent of catalog.agents ?? [])
+            addItem('agent', agent.id, true);
+        if (!pluginHooks)
+            addItem('hook', HOOKS_ITEM_ID, true);
+        addItem('rule', 'comentarios', true);
+        addItem('hook', 'comentarios', true);
+    }
+    return {
+        changes,
+        lock,
+        stale,
+        adotada,
+        registrarHooks: adotada && !pluginHooks,
+        registrarComentarios: adotada,
+        permissaoAusente: !HARNESS_PERMISSIONS.every((rule) => hasAllowRule(root, rule)),
+    };
+}
+/**
+ * Aplica o relatório: grava novos, alterados e faltando; apaga órfãos intactos; renomeia
+ * comandos editados que saíram do pacote; conflitos só com `force`. Arquivos modificados
+ * localmente sem mudança no pacote e arquivos do projeto com nome de item do harness nunca
+ * são tocados. O lock é regravado com a versão atual do pacote.
+ */
+export function applyUpdate(root, report, options, pkg, now = new Date()) {
+    const write = [];
+    const remove = [];
+    const kept = [];
+    const legacy = [];
+    for (const change of report.changes) {
+        if (change.tipo === 'modificado-local')
+            continue;
+        if (change.tipo === 'legado') {
+            legacy.push(change.caminho);
+            continue;
+        }
+        if (change.tipo === 'existente' || (change.tipo === 'conflito' && !options.force)) {
+            kept.push(change.caminho);
+            continue;
+        }
+        if (change.source)
+            write.push({ path: change.caminho, content: readFileSync(change.source) });
+        else
+            remove.push(change.caminho);
+    }
+    applyAtomically(root, write);
+    for (const path of remove)
+        rmSync(join(root, path), { force: true });
+    const renamed = legacy.map((path) => {
+        const para = legacyPath(root, path);
+        renameSync(join(root, path), join(root, para));
+        return { de: path, para };
+    });
+    const hooks = combineHooks(report.registrarHooks ? projectHooksConfig() : {}, report.registrarComentarios ? commentsHooksConfig() : {});
+    mergeSettings(root, { hooks, allow: HARNESS_PERMISSIONS }, now);
+    if (report.registrarComentarios)
+        ensureCommentsBaseline(root);
+    if (report.adotada) {
+        writeDefaultConfig(root);
+        syncGitignore(root, readConfig(root).config);
+        // Esqueleto da rule de projeto, com os comandos personalizados a extrair; uma rule existente nunca é tocada.
+        const projectRule = join(root, PROJECT_RULE_PATH);
+        if (!existsSync(projectRule)) {
+            mkdirSync(dirname(projectRule), { recursive: true });
+            writeFileSync(projectRule, projectRuleContent(renamed.map(({ para }) => para)));
+        }
+    }
+    const itemOf = new Map(report.changes.map((change) => [change.caminho, change.item]));
+    const writtenHash = new Map(write.map((file) => [file.path, hashContent(file.content)]));
+    const dropped = new Set([...remove, ...report.stale, ...legacy]);
+    const itens = [];
+    for (const item of report.lock.itens) {
+        const key = `${item.tipo}:${item.id}`;
+        const entries = new Map(item.arquivos.map((entry) => [entry.caminho, entry]));
+        for (const [path, sha256] of writtenHash) {
+            if (itemOf.get(path) === key)
+                entries.set(path, { caminho: path, sha256 });
+        }
+        for (const path of dropped)
+            entries.delete(path);
+        if (entries.size) {
+            itens.push({ ...item, arquivos: [...entries.values()].sort((a, b) => a.caminho.localeCompare(b.caminho)) });
+        }
+    }
+    // Itens que não existiam no lock (como a skill de um fluxo que era comando) entram com os arquivos gravados.
+    const knownItems = new Set(report.lock.itens.map((item) => `${item.tipo}:${item.id}`));
+    const addedItems = new Map();
+    for (const [path, sha256] of writtenHash) {
+        const key = itemOf.get(path);
+        if (!key || knownItems.has(key))
+            continue;
+        const separator = key.indexOf(':');
+        const added = addedItems.get(key) ?? { tipo: key.slice(0, separator), id: key.slice(separator + 1), arquivos: [] };
+        added.arquivos.push({ caminho: path, sha256 });
+        addedItems.set(key, added);
+    }
+    for (const added of addedItems.values()) {
+        itens.push({ ...added, arquivos: added.arquivos.sort((a, b) => a.caminho.localeCompare(b.caminho)) });
+    }
+    writeLock(root, { lock_versao: LOCK_VERSION, pacote: pkg, gerado_em: now.toISOString(), itens });
+    return { written: write.map((file) => file.path), removed: remove, kept, renamed };
+}
+const DESCRIPTIONS = {
+    novo: 'novo no pacote, será gravado',
+    alterado: 'mudou no pacote, será atualizado',
+    faltando: 'não existe no projeto, será restaurado',
+    removido: 'saiu do pacote, será apagado',
+    legado: 'editado localmente e saiu do pacote, será renomeado',
+    conflito: 'alterado localmente e no pacote, só com --forcar',
+    existente: 'já existe no projeto com outro conteúdo, será mantido',
+    'modificado-local': 'alterado localmente, será mantido',
+};
+export function describeUpdate(report) {
+    const adopted = report.adotada
+        ? [
+            `Instalação ${report.lock.pacote.versao} sem lock, reconhecida pelos arquivos em .claude/. ` +
+                `O --yes grava o ${LOCK_PATH}, a configuração do harness${report.registrarHooks ? ', os hooks' : ''}, o padrão de comentários, ` +
+                'a rule de projeto e a permissão do `ai-harness evento`.',
+        ]
+        : [];
+    const permission = report.permissaoAusente && !report.adotada ? [`Faltam permissões do harness (${HARNESS_PERMISSIONS.join(', ')}) em .claude/settings.json; o --yes as acrescenta.`] : [];
+    if (!report.changes.length) {
+        const status = adopted.length || permission.length ? 'Nenhum arquivo a atualizar.' : 'A instalação está em dia: nenhum arquivo a atualizar.';
+        return [...adopted, ...permission, status].join('\n');
+    }
+    return [
+        ...adopted,
+        ...permission,
+        `Mudanças em relação ao pacote ${packageInfo().versao} (instalado: ${report.lock.pacote.versao}):`,
+        ...report.changes.map((change) => `  ${change.tipo.padEnd(16)} ${change.caminho}${change.destino ? ` → ${change.destino}` : ''}  (${DESCRIPTIONS[change.tipo]})`),
+    ].join('\n');
+}
+const UPDATE_FLAGS = ['--check', '--yes', '-y', '--sim', '--forcar'];
+export function parseUpdateArgs(argv) {
+    const args = { path: undefined, check: false, yes: false, force: false };
+    for (const token of argv) {
+        if (!token.startsWith('-')) {
+            if (args.path !== undefined)
+                throw new Error(`Argumento inesperado: ${token}`);
+            args.path = token;
+        }
+        else if (token === '--check')
+            args.check = true;
+        else if (token === '--forcar')
+            args.force = true;
+        else if (token === '--yes' || token === '-y' || token === '--sim')
+            args.yes = true;
+        else {
+            const suggestion = suggestFlag(token, UPDATE_FLAGS);
+            throw new Error(`Flag desconhecida: ${token}.${suggestion ? ` Você quis dizer ${suggestion}?` : ''}`);
+        }
+    }
+    return args;
+}
+/** `ai-harness update [caminho] [--check] [--yes] [--forcar]`; sem `--yes` só simula. */
+export function runUpdateCommand(argv) {
+    const args = parseUpdateArgs(argv);
+    const root = resolve(process.cwd(), args.path ?? '.');
+    if (!existsSync(root))
+        throw new Error(`Pasta não encontrada: ${root}`);
+    const report = checkUpdate(root);
+    console.log(describeUpdate(report));
+    // Sem arquivo a atualizar, a adoção ainda grava o lock, e a permissão ausente ainda é acrescentada.
+    if (args.check || (!report.changes.length && !report.adotada && !report.permissaoAusente))
+        return 0;
+    if (!args.yes) {
+        const conflicts = report.changes.some((change) => change.tipo === 'conflito');
+        console.log(`\nSimulação — nada foi alterado. Rode de novo com --yes para aplicar${conflicts && !args.force ? ' (e --forcar para sobrescrever os conflitos)' : ''}.`);
+        return 0;
+    }
+    const result = applyUpdate(root, report, { force: args.force }, packageInfo());
+    console.log(`\nAtualização aplicada: ${result.written.length} gravado(s), ${result.removed.length} apagado(s), ` +
+        `${result.renamed.length} renomeado(s), ${result.kept.length} preservado(s).`);
+    if (result.renamed.length) {
+        console.log('Comandos personalizados renomeados (leve o que for do projeto para uma rule e apague o arquivo):\n' +
+            result.renamed.map(({ de, para }) => `  ${de} → ${para}`).join('\n'));
+    }
+    if (result.kept.length) {
+        console.log(`Preservados (conflito usa --forcar; arquivo do projeto nunca é sobrescrito):\n${result.kept.map((path) => `  = ${path}`).join('\n')}`);
+    }
+    return 0;
+}

package/package.json

@@ -1,27 +1,30 @@
 {
   "name": "@fontdata/ai-harness",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "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.",
   "type": "module",
   "bin": {
-    "ai-harness": "bin/cli.js",
-    "fontdata-ai-harness": "bin/cli.js"
+    "ai-harness": "dist/cli.js",
+    "fontdata-ai-harness": "dist/cli.js"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
     ".claude-plugin/",
-    "bin/",
-    "src/",
+    "dist/",
     "templates/",
     "README.md"
   ],
   "scripts": {
-    "start": "node bin/cli.js",
+    "start": "node dist/cli.js",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.scripts.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json"
   },
   "keywords": [
@@ -39,6 +42,12 @@
     "url": "git+https://github.com/fontdata-tecnologia/ai-harness.git"
   },
   "dependencies": {
-    "@clack/prompts": "^0.7.0"
+    "@clack/prompts": "^0.7.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
   }
 }

package/templates/CLAUDE.md

@@ -1,49 +1,78 @@
 # [NOME DO PROJETO]
-> Substitua esta seção rodando `/gerar-claude-md` depois de gerar o `SPEC.md`.
+> Substitua esta seção rodando `/sincronizar-claude-md`, que gera o `SPEC.md` e este arquivo.
 
-Este projeto usa o **harness de engenharia com IA da Fontdata** para Claude Code.
-Os slash commands ficam em `.claude/commands/`. Comece por `/validar-ideia` (ou `/harness`).
+Este projeto usa o **harness de engenharia com IA da Fontdata** para Claude Code (`@fontdata/ai-harness`).
+Comece por `/harness`, que conduz o setup em etapas.
 
 ## Filosofia de trabalho
 
-- **Documentação como contrato.** `SPEC.md` (raiz), `CLAUDE.md` (raiz) e os planos em `docs/plans/`
-  são a fonte da verdade. Agents não os reescrevem por conta própria.
-- **TDD obrigatório.** Toda task escreve os testes primeiro (RED), confirma que falham, e só então
-  implementa o mínimo para passar (GREEN). Mínimo de 2 testes críticos por task.
-- **Orquestração com sub-agents.** Tasks independentes da mesma fase rodam em paralelo. O orquestrador
-  delega, não implementa. Gates entre fases: só avança quando os testes da fase passam.
-- **Sempre relatar qual agent está ativo** no chat, principalmente nos gates entre agents.
+- **Documentação como contrato.** `SPEC.md` e `CLAUDE.md` na raiz e os artefatos de cada trabalho em
+  `docs/trabalhos/<id>/` são a fonte da verdade. Agents não os reescrevem por conta própria: mudança de escopo vira
+  decisão registrada.
+- **Planejar antes de executar.** Pergunta durante a execução é falha do plano: dúvida vira bloqueio registrado.
+- **TDD obrigatório.** Testes primeiro (RED), implementação mínima depois (GREEN). Mínimo de 2 testes críticos por
+  task; uma task só fecha com suíte verde registrada no rastro.
+- **Quem implementa não aprova.** Os agents `revisor-testes` e `qa`, somente leitura, fazem os gates de cada task.
+- **Orquestração com sub-agents.** Tasks independentes da mesma fase rodam em paralelo; o orquestrador delega, não
+  implementa. **Sempre relatar qual agent está ativo** no chat.
 
 ## Modelo de arquivos
 
-| Arquivo | Local | Papel |
-|--------|-------|-------|
-| `SPEC.md` | raiz | Definição **principal** e completa do projeto (única). |
-| `CLAUDE.md` | raiz | Este context file, lido em toda sessão. |
-| `docs/specs/AAAA-MM-DD-*.md` | `docs/specs/` | Specs **complementares**: o start inicial e cada nova tarefa. |
-| `docs/plans/AAAA-MM-DD-*.md` | `docs/plans/` | Plano de implementação correspondente a cada spec complementar. |
-| `docs/bugs/AAAA-MM-DD-*.md` | `docs/bugs/` | Correção de defeito: sintoma, causa-raiz e fix (via `/resolver-bug`). |
-| `docs/investigacoes/AAAA-MM-DD-*.md` | `docs/investigacoes/` | Investigação, medição, auditoria, paridade e comparação (via `/auditar-*`, `/codigo-morto`). |
+| Arquivo | Papel |
+|---|---|
+| `SPEC.md` (raiz) | Definição **principal** e completa do projeto |
+| `CLAUDE.md` (raiz) | Este context file, lido em toda sessão |
+| `docs/trabalhos/AAAA-MM-DD-<slug>/SPEC.md` | Spec do trabalho |
+| `docs/trabalhos/<id>/PLAN.md` | Plano: sprints, fases e tasks (as tasks também no frontmatter) |
+| `docs/trabalhos/<id>/DECISOES.md` | Decisões tomadas no planejamento e na execução |
+| `docs/trabalhos/<id>/BLOQUEIOS.md` | Dúvidas que pararam uma task |
+| `docs/trabalhos/<id>/relatorios/TECNICO.md` e `relatorios/CLIENTE.md` | Relatório para engenharia e para cliente ou gestão |
+| `docs/eventos/<id>.jsonl` | Rastro de eventos (não versionado por padrão) |
+| `.ai-harness/` | Lock da instalação e configuração dos hooks (versionar) |
+
+Tipos de trabalho: `feature` (`/nova-tarefa`), `bug` (`/resolver-bug`), `auditoria` (`/auditar-seguranca`,
+`/auditar-performance`, `/auditar-ui`) e `investigacao`.
+
+## Garantias do harness
+
+- **Hooks** (modo de cada um em `.ai-harness/config.json`): `lembrete` sugere o fluxo certo para o pedido;
+  `segredo-no-commit` bloqueia commit com segredo; `proteger-contratos` avisa quando SPEC, PLAN ou CLAUDE.md são
+  reescritos durante a execução; `task-so-fecha-verde` avisa sobre task concluída sem suíte verde; `sem-jargao`
+  avisa sobre termo técnico no relatório para o cliente.
+- **Agents somente leitura:** `revisor-testes`, `qa`, `investigador` e `auditor-plano`.
+- **Verificação:** `npx @fontdata/ai-harness doctor` confere instalação, contrato dos documentos e rastro;
+  `npx @fontdata/ai-harness update` atualiza o que foi instalado sem perder alterações locais.
+
+## Código legado
+
+Na área de código legado tocada por uma task, vale o **padrão local** do arquivo — nomenclatura, estrutura e estilo
+de tratamento de erro —, mesmo que difira das convenções novas. As convenções novas valem para arquivo novo. Não
+"modernize" arquivo antigo fora do escopo da task.
 
 ## Fluxo recomendado (projeto novo)
 
-1. `/validar-ideia` — confere se cabe em ~4h com multi-agents
-2. `/gerar-spec` — gera o `SPEC.md` principal na raiz
-3. `/gerar-claude-md` — gera/atualiza este arquivo
-4. `/gerar-ignore` — `.claudeignore` e `.gitignore`
-5. `/nova-tarefa` — spec do start (derivada do SPEC) + plano em `docs/`
-6. `/scaffold` — estrutura inicial + `/health` + testes de smoke
-7. `/criar-agents`, `/criar-code-reviewer`, `/criar-rules`, `/criar-hooks` — monta o harness
+`/harness` conduz o setup em etapas, pedindo confirmação entre elas (`/harness <etapa>` roda uma só):
+
+1. Validar a ideia — o escopo cabe com multi-agents?
+2. `/sincronizar-claude-md` — `SPEC.md` principal e este arquivo, com a seção de orquestração
+3. Ignores — `.claudeignore` e `.gitignore`
+4. `/nova-tarefa start` — trabalho do start com `SPEC.md` e `PLAN.md`
+5. Scaffold — estrutura inicial, `/health` e testes de smoke
+6. `/evoluir-harness` — skills, agents, code-reviewer, rules e hooks do projeto, e a rule
+   `.claude/rules/harness-projeto.md` preenchida
+7. Auto-tag — Action que cria a tag quando a versão chega na branch principal (opcional)
 8. `/executar-plan` — orquestra a implementação
 
-No dia a dia: `/nova-tarefa`, `/resolver-bug`, `/git-commit-push`.
+No dia a dia: `/nova-tarefa`, `/executar-plan`, `/resolver-bug`, `/git-commit-push` e `/versao`. De vez em quando:
+`/sincronizar-claude-md` e `/evoluir-harness`.
 
 ## Nunca fazer
 
 - Nunca implementar sem teste escrito antes.
-- Nunca avançar de fase com gate (testes) falhando.
-- Nunca reescrever `SPEC.md`/`CLAUDE.md`/planos sem pedido explícito.
+- Nunca avançar de fase com gate (testes) falhando nem fechar task sem suíte verde.
+- Nunca reescrever `SPEC.md`, `CLAUDE.md` ou planos sem pedido explícito.
 - Nunca usar `git push --force` ou comandos destrutivos sem confirmação.
 - Nunca comentar o passo a passo do código, decorar arquivo com banner de seção, nem escrever
-  task/fase/plano/data/hash de commit dentro de comentário — isso vai na mensagem de commit e em `docs/`.
-  Rode `/configurar-comentarios` para instalar a rule, o hook e a catraca.
+  task/fase/plano/data/hash de commit dentro de comentário — isso vai na mensagem de commit e em `docs/trabalhos/`.
+  O padrão completo está em `.claude/rules/comentarios.md`, instalada pelo `init`, e o hook de comentários bloqueia
+  a violação.

package/templates/agents/auditor-plano.md

@@ -0,0 +1,44 @@
+---
+name: auditor-plano
+description: Audita um PLAN.md antes da execução, verificando dependências, paralelismo, testes críticos e critérios de aceite binários. Use depois do /nova-tarefa e antes do /executar-plan. Somente leitura.
+tools: Read, Grep, Glob, Bash
+model: opus
+---
+
+Você é o **auditor de plano** do harness. Um plano aprovado por você precisa poder ser executado sem que
+ninguém pergunte nada no meio. Você não edita o plano: aponta o que precisa mudar.
+
+## Entrada
+
+- `docs/trabalhos/<id>/SPEC.md` e `docs/trabalhos/<id>/PLAN.md`.
+
+## Checklist
+
+1. **Contrato:** rode `npx @fontdata/ai-harness doctor` e trate como BLOQUEANTE todo achado `contrato-*` deste
+   trabalho.
+2. **Escopo:** o plano cobre a SPEC inteira e nada além dela.
+3. **Testes críticos:** toda task de código tem pelo menos 2 testes concretos (entrada e resultado esperados), não
+   frases genéricas como "testar o fluxo".
+4. **Critérios de aceite binários:** cada critério pode ser verificado com sim ou não, por comando ou observação.
+5. **Dependências:** toda task que usa algo criado por outra declara `depende_de`; sem ciclos.
+6. **Paralelismo:** tasks `paralelizavel: true` da mesma fase não alteram os mesmos arquivos.
+   O `arquivos` do frontmatter lista tudo o que as tasks vão criar ou alterar: é por ele que o `/executar-plan`
+   impede dois trabalhos em paralelo de mexerem no mesmo código. Lista vazia num plano com código é BLOQUEANTE.
+7. **Tamanho:** cada task cabe numa sessão de trabalho; task grande demais é dividida.
+8. **Legado e riscos:** áreas de código legado tocadas estão identificadas, com o padrão local a preservar.
+
+Use `Bash` só para rodar o `doctor` e ler o histórico: **nunca** altere arquivos, faça commit ou push.
+
+## Saída
+
+- **Veredito:** `APROVADO` ou `REPROVADO`.
+- **Achados** em BLOQUEANTE, IMPORTANTE e SUGESTÃO, cada um apontando a task (`T-SS.NN`) e a correção esperada.
+- O valor para o orquestrador gravar em `auditoria_plano` no frontmatter do `PLAN.md` (`aprovado` ou
+  `reprovado`).
+
+Registre o veredito no rastro:
+
+```bash
+npx @fontdata/ai-harness evento agent_veredito --trabalho <id> --nome auditor-plano \
+  --dados '{"veredito":"aprovado","motivo":"<resumo em uma linha>"}'
+```

package/templates/agents/investigador.md

@@ -0,0 +1,32 @@
+---
+name: investigador
+description: Investiga a causa raiz de um bug antes de qualquer correção. Use no início do /resolver-bug, com o relato do sintoma. Lê código, histórico e logs e reproduz o problema; não edita nem roda comandos que alterem estado.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+Você é o **investigador** do harness. Seu trabalho termina quando a causa raiz está comprovada com evidência,
+ou quando ficou claro que ela ainda é hipótese. Você não corrige o bug.
+
+## Como investigar
+
+1. **Reproduza o sintoma.** Um teste, um comando ou os passos exatos. Sem reprodução, diga isso explicitamente.
+2. **Levante hipóteses** e, para cada uma, busque evidência que a confirme ou a descarte:
+   - leitura do código envolvido;
+   - histórico: `git log -p -S "<trecho>"`, `git log --follow <arquivo>`, `git blame -L <ini>,<fim> <arquivo>`;
+   - trabalhos anteriores que tocaram os mesmos arquivos (`docs/trabalhos/*/` e o campo `arquivos` do
+     frontmatter).
+3. **Comprove.** A causa raiz só é `comprovada` quando você mostra a linha ou a condição que produz o sintoma e
+   por que a reprodução falha por causa dela. Caso contrário, ela é `hipotese`.
+4. Use `Bash` só para ler, buscar no histórico e reproduzir: **nunca** altere arquivos, instale dependências,
+   faça commit ou push.
+
+## Saída
+
+- **Sintoma** e **como reproduzir**.
+- **Causa raiz:** `comprovada` ou `hipotese`, com a evidência (`arquivo:linha`, trecho do histórico, saída da
+  reprodução).
+- **Arquivos envolvidos**, para o campo `arquivos` do plano.
+- **Riscos da correção:** o que mais depende do trecho afetado.
+
+Não proponha refatorações amplas: a correção mínima fica para o plano do `/resolver-bug`.

package/templates/agents/qa.md

@@ -0,0 +1,44 @@
+---
+name: qa
+description: Valida os critérios de aceite de uma task ou fase e roda a suíte completa antes do gate. Use ao fim de cada task ou fase do /executar-plan. Somente leitura; não corrige o que encontrar.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+Você é o **QA** do harness. Você confirma, com evidência, que a task ou a fase entregou o que o plano promete.
+Você não corrige nada: se algo falha, você reporta.
+
+## Entrada
+
+- O id do trabalho e a task (ou fase) a validar, em `docs/trabalhos/<id>/PLAN.md`.
+- Os critérios de aceite e os testes críticos declarados no plano.
+- A rule de projeto `.claude/rules/harness-projeto.md`, quando existir: comando e local da suíte e, para área sem
+  testes automatizados, o roteiro de verificação manual.
+
+## Como validar
+
+1. Para cada critério de aceite, obtenha **evidência objetiva**: saída de comando, `arquivo:linha` ou resultado
+   de teste. Critério sem evidência conta como não atendido.
+2. Rode a **suíte completa** do projeto, não só os testes da task, com o comando declarado na rule de projeto quando
+   houver. Em área de verificação manual, siga o roteiro da rule e colete evidência de cada item.
+3. Confira que nada fora do escopo da task foi alterado (`git diff --stat`).
+4. Use `Bash` só para ler e rodar testes: **nunca** altere arquivos, instale dependências, faça commit ou push.
+
+## Saída
+
+- **Veredito:** `APROVADO` ou `REPROVADO`.
+- Tabela: critério → atendido (sim/não) → evidência.
+- Resultado da suíte: comando, total de testes e falhas.
+
+Registre a suíte e o veredito no rastro:
+
+```bash
+npx @fontdata/ai-harness evento suite_verde --trabalho <id> --task <T-SS.NN> --nome qa --resultado ok \
+  --dados '{"comando":"<comando>","total":<n>,"falhas":0}'
+npx @fontdata/ai-harness evento agent_veredito --trabalho <id> --task <T-SS.NN> --nome qa \
+  --dados '{"veredito":"aprovado","motivo":"<resumo em uma linha>"}'
+```
+
+Com falhas, use `suite_vermelha` e `--resultado falha`. Na verificação manual, registre `suite_verde` com
+`"comando":"manual"`, `total` igual ao número de itens do roteiro e `falhas` igual a 0; com item reprovado,
+`suite_vermelha`.