@fontdata/ai-harness 2.0.0 → 2.2.0

package/dist/cli.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { allCommands, loadCatalog } from './catalog.js';
+import { runCommand, runnableIds, suggestIds } from './run.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const RESERVED = new Set([
+    'init',
+    'doctor',
+    'update',
+    'migrar',
+    'evento',
+    'conflitos',
+    'comentarios',
+    'memoria',
+    'list',
+    'run',
+    'help',
+    '--help',
+    '-h',
+    '--version',
+    '-v',
+]);
+function pkgVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+        return pkg.version;
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+function printHelp() {
+    console.log(`
+@fontdata/ai-harness — harness de engenharia com IA para Claude Code
+
+Uso:
+  npx @fontdata/ai-harness <comando> [contexto]     roda o comando na pasta atual
+  npx @fontdata/ai-harness init                     instala os comandos no projeto
+
+Executar sem instalar:
+  <comando>       Abre o Claude Code aqui já executando o comando (ex.: harness)
+  run <comando>   Forma explícita, útil quando o nome colide com uma palavra reservada
+
+Gerenciar:
+  init [caminho]  Instala os slash commands em .claude/commands do projeto (interativo)
+  doctor [caminho]  Diagnostica a instalação (arquivos, lock, skills, agents, hooks, Node)
+  update [caminho]  Atualiza o que foi instalado: --check só lista, --yes aplica, --forcar sobrescreve conflitos
+  migrar [caminho]  Move docs/specs, plans, bugs e investigacoes para docs/trabalhos/<id>/ (--yes aplica)
+  comentarios [caminho]  Instala o hook de comentários e a catraca do legado (--yes aplica)
+  memoria [caminho]  Índice de quem mexeu em cada arquivo (--arquivo <caminho>, --regressao <id do bug>)
+  evento <evento>   Grava no rastro do trabalho (--trabalho, --task, --nome, --resultado, --dados '{json}')
+  conflitos <id>    Aponta trabalhos em execução que mexem nos mesmos arquivos (--aguardar espera liberar)
+  list            Lista todos os comandos disponíveis no catálogo
+
+Init sem perguntas (CI):
+  --escopo recomendado|tudo            ou  --comandos a,b,c
+  --sem-harness                        não inclui o comando-mestre /harness
+  --sem-hooks                          não instala os hooks do harness
+  --sem-agents                         não instala os agents somente leitura
+  --sem-comentarios                    não instala a rule, o hook e a catraca de comentários
+  --claude-md criar|manter|backup|sobrescrever   (padrão: criar)
+  --conflito sobrescrever|pular        (padrão: pular)
+  --yes                                aplica; sem ele o init só simula
+  --help, -h      Mostra esta ajuda
+  --version, -v   Mostra a versão
+
+Exemplos:
+  npx @fontdata/ai-harness harness
+  npx @fontdata/ai-harness resolver-bug "login 500 no refresh token"
+  npx @fontdata/ai-harness run versao minor
+  npx @fontdata/ai-harness harness -- --model claude-opus-5
+
+Tudo depois de \`--\` é repassado ao Claude Code (--model, --effort, -p, ...).
+`);
+}
+function printList() {
+    const catalog = loadCatalog();
+    console.log('\nComandos disponíveis:\n');
+    for (const group of catalog.groups) {
+        console.log(`  ${group.title}`);
+        for (const cmd of group.commands) {
+            const star = cmd.recommended ? ' *' : '  ';
+            console.log(`   ${star} ${cmd.title.padEnd(26)} ${cmd.description}`);
+        }
+        console.log('');
+    }
+    console.log(`  (* = conjunto recomendado · total: ${allCommands(catalog).length} comandos + /harness)\n`);
+}
+/** Separa os argumentos do comando dos flags destinados ao Claude Code. */
+function splitArgs(rest) {
+    const sep = rest.indexOf('--');
+    if (sep === -1)
+        return { args: rest, claudeFlags: [] };
+    return { args: rest.slice(0, sep), claudeFlags: rest.slice(sep + 1) };
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    const cmd = argv[0];
+    if (cmd === '--version' || cmd === '-v') {
+        console.log(pkgVersion());
+        return;
+    }
+    if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+        printHelp();
+        return;
+    }
+    if (cmd === 'list') {
+        printList();
+        return;
+    }
+    if (cmd === 'init') {
+        // Import dinâmico: só carrega @clack/prompts quando o init é realmente usado.
+        const { runInit } = await import('./init.js');
+        await runInit(argv.slice(1));
+        return;
+    }
+    if (cmd === 'doctor') {
+        const { formatFindings, runDoctor } = await import('./doctor/checks.js');
+        const root = resolve(process.cwd(), argv[1] ?? '.');
+        if (!existsSync(root))
+            throw new Error(`Pasta não encontrada: ${root}`);
+        const findings = runDoctor(root);
+        console.log(formatFindings(findings));
+        process.exit(findings.some((finding) => finding.severidade === 'erro') ? 1 : 0);
+    }
+    if (cmd === 'memoria') {
+        const { runMemoryCommand } = await import('./memoria/indice.js');
+        process.exit(runMemoryCommand(argv.slice(1)));
+    }
+    if (cmd === 'comentarios') {
+        const { runCommentsCommand } = await import('./comentarios/command.js');
+        process.exit(runCommentsCommand(argv.slice(1)));
+    }
+    if (cmd === 'migrar') {
+        const { runMigrationCommand } = await import('./migrar/migrar.js');
+        process.exit(runMigrationCommand(argv.slice(1)));
+    }
+    if (cmd === 'evento') {
+        const { runEventCommand } = await import('./rastro/command.js');
+        process.exit(await runEventCommand(argv.slice(1)));
+    }
+    if (cmd === 'conflitos') {
+        const { runConflictsCommand } = await import('./trabalhos/conflitos.js');
+        process.exit(await runConflictsCommand(argv.slice(1)));
+    }
+    if (cmd === 'update') {
+        const { runUpdateCommand } = await import('./update/update.js');
+        process.exit(runUpdateCommand(argv.slice(1)));
+    }
+    if (cmd === 'run') {
+        const id = argv[1];
+        if (!id) {
+            console.error('Informe o comando a executar. Ex.: npx @fontdata/ai-harness run harness\n');
+            printHelp();
+            process.exit(1);
+        }
+        const { args, claudeFlags } = splitArgs(argv.slice(2));
+        process.exit(runCommand(id, args, claudeFlags));
+    }
+    const ids = runnableIds();
+    if (ids.includes(cmd.replace(/^\//, ''))) {
+        const { args, claudeFlags } = splitArgs(argv.slice(1));
+        process.exit(runCommand(cmd, args, claudeFlags));
+    }
+    if (!RESERVED.has(cmd)) {
+        const near = suggestIds(cmd.replace(/^\//, ''), ids);
+        console.error(`Comando desconhecido: ${cmd}`);
+        if (near.length)
+            console.error(`\nVocê quis dizer: ${near.join(', ')}`);
+        console.error('');
+    }
+    printHelp();
+    process.exit(1);
+}
+main().catch((err) => {
+    console.error('Erro:', err instanceof Error ? err.message : err);
+    process.exit(1);
+});

package/dist/comentarios/command.js

@@ -0,0 +1,74 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { EOL } from 'node:os';
+import { join, resolve } from 'node:path';
+import { templatesDir } from '../catalog.js';
+import { suggestFlag } from '../install/flags.js';
+import { hashContent } from '../install/lock.js';
+import { executePlan, packageInfo } from '../install/plan.js';
+import { mergeSettings } from '../install/settings.js';
+import { COMMENTS_BASELINE_PATH, COMMENTS_HOOK_PATH, COMMENTS_RULE_PATH, commentsHooksConfig, ensureCommentsBaseline } from './instalar.js';
+export { COMMENTS_HOOK_PATH } from './instalar.js';
+const FLAGS = ['--yes', '-y', '--sim'];
+/** `ai-harness comentarios [caminho] [--yes]`: instala a rule, o hook de comentários e a catraca do legado. */
+export function runCommentsCommand(argv) {
+    let path;
+    let yes = false;
+    for (const token of argv) {
+        if (!token.startsWith('-')) {
+            if (path !== undefined)
+                throw new Error(`Argumento inesperado: ${token}`);
+            path = token;
+        }
+        else if (FLAGS.includes(token)) {
+            yes = true;
+        }
+        else {
+            const suggestion = suggestFlag(token, FLAGS);
+            throw new Error(`Flag desconhecida: ${token}.${suggestion ? ` Você quis dizer ${suggestion}?` : ''}`);
+        }
+    }
+    const root = resolve(process.cwd(), path ?? '.');
+    if (!existsSync(root))
+        throw new Error(`Pasta não encontrada: ${root}`);
+    const rule = readFileSync(join(templatesDir, 'rules', 'comentarios.md'));
+    const ruleTarget = join(root, COMMENTS_RULE_PATH);
+    // Uma rule com outro conteúdo é do projeto: fica como está.
+    const keepRule = existsSync(ruleTarget) && hashContent(readFileSync(ruleTarget)) !== hashContent(rule);
+    const hasBaseline = existsSync(join(root, COMMENTS_BASELINE_PATH));
+    console.log([
+        'Padrão de comentários:',
+        keepRule ? `  = ${COMMENTS_RULE_PATH} já existe com outro conteúdo e será mantida` : `  + ${COMMENTS_RULE_PATH}`,
+        `  + ${COMMENTS_HOOK_PATH}`,
+        '  + hook PostToolUse (Write|Edit|MultiEdit) em .claude/settings.json, sem duplicar',
+        hasBaseline
+            ? `  = ${COMMENTS_BASELINE_PATH} já existe e será mantido (a catraca só desce)`
+            : `  + ${COMMENTS_BASELINE_PATH} com as violações atuais do código (catraca do legado)`,
+    ].join(EOL));
+    if (!yes) {
+        console.log(`${EOL}Simulação — nada foi gravado. Rode de novo com --yes para instalar.`);
+        return 0;
+    }
+    const plan = {
+        files: [
+            ...(keepRule ? [] : [{ path: COMMENTS_RULE_PATH, content: rule }]),
+            { path: COMMENTS_HOOK_PATH, content: readFileSync(join(templatesDir, 'hooks', 'comentarios', 'check.mjs')) },
+        ],
+        skipped: keepRule ? [COMMENTS_RULE_PATH] : [],
+        items: [
+            ...(keepRule ? [] : [{ tipo: 'rule', id: 'comentarios', paths: [COMMENTS_RULE_PATH] }]),
+            { tipo: 'hook', id: 'comentarios', paths: [COMMENTS_HOOK_PATH] },
+        ],
+        autoAdded: [],
+        claudeMdBackup: false,
+        registerHooks: false,
+        registerComments: false,
+    };
+    executePlan(root, plan, packageInfo());
+    mergeSettings(root, { hooks: commentsHooksConfig() });
+    const legacy = ensureCommentsBaseline(root);
+    if (legacy !== null) {
+        console.log(`${EOL}Catraca gerada: ${legacy} arquivo(s) legado(s) com violações toleradas. Eles não precisam ser limpos de uma vez, só não podem piorar.`);
+    }
+    console.log(`${EOL}Padrão de comentários instalado. Versione .claude/rules/comentarios.md, .claude/hooks/comentarios/ e o .claude/settings.json.`);
+    return 0;
+}

package/dist/comentarios/instalar.js

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { templatesDir } from '../catalog.js';
+import { hashContent } from '../install/lock.js';
+export const COMMENTS_HOOK_PATH = '.claude/hooks/comentarios/check.mjs';
+export const COMMENTS_BASELINE_PATH = '.claude/hooks/comentarios/baseline.json';
+export const COMMENTS_RULE_PATH = '.claude/rules/comentarios.md';
+/** Mesmo texto das instalações feitas pelas versões antigas do /configurar-comentarios, para o merge não duplicar. */
+export const COMMENTS_HOOK_COMMAND = 'node "${CLAUDE_PROJECT_DIR}/.claude/hooks/comentarios/check.mjs"';
+export function commentsHooksConfig() {
+    return { PostToolUse: [{ matcher: 'Write|Edit|MultiEdit', hooks: [{ type: 'command', command: COMMENTS_HOOK_COMMAND }] }] };
+}
+/**
+ * Gera a catraca do legado na primeira instalação e devolve quantos arquivos entraram nela. Devolve `null` quando
+ * ela já existe (regerar reabriria tolerâncias que já desceram) ou quando o `check.mjs` do projeto não é o do
+ * pacote, que pode não saber gerá-la.
+ */
+export function ensureCommentsBaseline(root) {
+    const hook = join(root, COMMENTS_HOOK_PATH);
+    if (existsSync(join(root, COMMENTS_BASELINE_PATH)) || !existsSync(hook))
+        return null;
+    const packaged = readFileSync(join(templatesDir, 'hooks', 'comentarios', 'check.mjs'));
+    if (hashContent(readFileSync(hook)) !== hashContent(packaged))
+        return null;
+    const result = spawnSync(process.execPath, [hook, '--gerar-baseline'], {
+        env: { ...process.env, CLAUDE_PROJECT_DIR: root },
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        throw new Error(`Falha ao gerar a catraca do legado: ${result.stderr}`);
+    return Object.keys(JSON.parse(readFileSync(join(root, COMMENTS_BASELINE_PATH), 'utf8'))).length;
+}

package/dist/config/config.js

@@ -0,0 +1,99 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+export const CONFIG_PATH = join('.ai-harness', 'config.json');
+export const CONFIG_VERSION = 1;
+export const HOOK_MODES = ['aviso', 'bloqueio', 'desligado'];
+/** Hooks de segurança nascem em bloqueio; hooks de método nascem em aviso (D-13). */
+export const DEFAULT_HOOK_MODES = {
+    lembrete: 'aviso',
+    'segredo-no-commit': 'bloqueio',
+    'task-so-fecha-verde': 'aviso',
+    'proteger-contratos': 'aviso',
+    'sem-jargao': 'aviso',
+};
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function defaultConfig() {
+    return {
+        config_versao: CONFIG_VERSION,
+        hooks: { ...DEFAULT_HOOK_MODES },
+        rastro: { versionar: false },
+        bloqueios: { dias_para_aviso: 7 },
+    };
+}
+/** Lê a config sobre os padrões; valores inválidos são ignorados e viram problema, nunca erro. */
+export function readConfig(root) {
+    const config = defaultConfig();
+    const file = join(root, CONFIG_PATH);
+    if (!existsSync(file))
+        return { config, problems: [] };
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        return { config, problems: [`O ${CONFIG_PATH} está com JSON inválido; valem os padrões.`] };
+    }
+    if (!isObject(raw))
+        return { config, problems: [`O ${CONFIG_PATH} precisa ser um objeto JSON; valem os padrões.`] };
+    const problems = [];
+    if (isObject(raw.hooks)) {
+        for (const [hook, mode] of Object.entries(raw.hooks)) {
+            if (HOOK_MODES.includes(mode))
+                config.hooks[hook] = mode;
+            else
+                problems.push(`Modo "${String(mode)}" inválido para o hook ${hook} em ${CONFIG_PATH}; use aviso, bloqueio ou desligado.`);
+        }
+    }
+    if (isObject(raw.rastro) && 'versionar' in raw.rastro) {
+        if (typeof raw.rastro.versionar === 'boolean')
+            config.rastro.versionar = raw.rastro.versionar;
+        else
+            problems.push(`rastro.versionar deve ser true ou false em ${CONFIG_PATH}.`);
+    }
+    if (isObject(raw.bloqueios) && 'dias_para_aviso' in raw.bloqueios) {
+        const days = raw.bloqueios.dias_para_aviso;
+        if (typeof days === 'number' && Number.isInteger(days) && days > 0)
+            config.bloqueios.dias_para_aviso = days;
+        else
+            problems.push(`bloqueios.dias_para_aviso deve ser um inteiro positivo em ${CONFIG_PATH}.`);
+    }
+    return { config, problems };
+}
+/** Cria a config com os padrões; retorna false se já existia (nunca sobrescreve). */
+export function writeDefaultConfig(root) {
+    const file = join(root, CONFIG_PATH);
+    if (existsSync(file))
+        return false;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(defaultConfig(), null, 2)}\n`);
+    return true;
+}
+const BLOCK_START = '# ai-harness (gerenciado pelo harness; não edite entre estas linhas)';
+const BLOCK_END = '# /ai-harness';
+/**
+ * Mantém no .gitignore um bloco próprio: a memória gerada e o estado local da sessão
+ * (`estado.json`) são sempre ignorados, e o rastro só quando `rastro.versionar` é false.
+ * Linhas fora do bloco não são tocadas.
+ */
+export function syncGitignore(root, config) {
+    const file = join(root, '.gitignore');
+    const current = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const entries = ['.ai-harness/memoria/', '.ai-harness/estado.json', ...(config.rastro.versionar ? [] : ['docs/eventos/'])];
+    const block = [BLOCK_START, ...entries, BLOCK_END].join('\n');
+    const start = current.indexOf(BLOCK_START);
+    const end = start === -1 ? -1 : current.indexOf(BLOCK_END, start);
+    let next;
+    if (start !== -1 && end !== -1) {
+        next = current.slice(0, start) + block + current.slice(end + BLOCK_END.length);
+    }
+    else {
+        const separator = !current ? '' : current.endsWith('\n') ? '\n' : '\n\n';
+        next = `${current}${separator}${block}\n`;
+    }
+    if (next === current)
+        return { changed: false };
+    writeFileSync(file, next);
+    return { changed: true };
+}

package/dist/contratos/artefatos.js

@@ -0,0 +1,284 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, sep } from 'node:path';
+import { parse, YAMLParseError } from 'yaml';
+/** Versão do contrato de artefatos (docs/contratos/ARTEFATOS.md). */
+export const SCHEMA_VERSION = 1;
+export const WORKS_DIR = join('docs', 'trabalhos');
+/** Id de trabalho: `AAAA-MM-DD-<slug>` com slug em minúsculas, sem acento. */
+export const WORK_ID = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const TASK_ID = /^T-\d{2}\.\d{2}$/;
+/** Arquivo do trabalho → `tipo` que ele declara. */
+export const ARTIFACT_TYPES = {
+    'SPEC.md': 'spec',
+    'PLAN.md': 'plano',
+    'DECISOES.md': 'decisoes',
+    'BLOQUEIOS.md': 'bloqueios',
+    'relatorios/TECNICO.md': 'relatorio_tecnico',
+    'relatorios/CLIENTE.md': 'relatorio_cliente',
+};
+export const STATUS_BY_TYPE = {
+    spec: ['rascunho', 'aguardando-aprovacao', 'aprovado', 'substituido'],
+    plano: ['rascunho', 'aguardando-aprovacao', 'em-execucao', 'concluido', 'cancelado'],
+    decisoes: ['ativo'],
+    bloqueios: ['aberto', 'resolvido'],
+    relatorio_tecnico: ['rascunho', 'final'],
+    relatorio_cliente: ['rascunho', 'final'],
+};
+export const WORK_TYPES = ['feature', 'bug', 'investigacao', 'auditoria'];
+export const TASK_STATUS = ['pendente', 'em-andamento', 'concluida', 'bloqueada', 'pulada'];
+const REQUIRED_BY_WORK_TYPE = {
+    feature: ['SPEC.md', 'PLAN.md'],
+    bug: ['PLAN.md'],
+    investigacao: ['relatorios/TECNICO.md'],
+    auditoria: ['relatorios/TECNICO.md', 'relatorios/CLIENTE.md'],
+};
+const COMMON_KEYS = ['schema_versao', 'tipo', 'id', 'trabalho_tipo', 'titulo', 'status', 'criado_em', 'atualizado_em', 'arquivos'];
+const PLAN_KEYS = ['condensado', 'auditoria_plano', 'causa_raiz', 'tasks'];
+const TASK_KEYS = ['id', 'titulo', 'status', 'depende_de', 'paralelizavel', 'testes_criticos'];
+const BLOCK_KEYS = ['id', 'task', 'status', 'aberto_em', 'resolvido_em', 'decisao'];
+function isData(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringList(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+/** Lê o frontmatter de um artefato; `data` ausente quando há problema de leitura. */
+export function readArtifact(file, content) {
+    const match = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+    if (!match) {
+        return {
+            problems: [{ arquivo: file, regra: 'frontmatter-ausente', mensagem: 'O artefato não começa com um frontmatter YAML entre ---.', linha: 1 }],
+        };
+    }
+    let data;
+    try {
+        data = parse(match[1] ?? '');
+    }
+    catch (error) {
+        // +1 porque a primeira linha do arquivo é o `---` de abertura.
+        const line = error instanceof YAMLParseError ? (error.linePos?.[0]?.line ?? 0) + 1 : null;
+        const reason = error instanceof Error ? error.message.split('\n')[0] : String(error);
+        return { problems: [{ arquivo: file, regra: 'yaml-invalido', mensagem: `YAML inválido no frontmatter: ${reason}`, linha: line }] };
+    }
+    if (!isData(data)) {
+        return { problems: [{ arquivo: file, regra: 'formato-invalido', mensagem: 'O frontmatter precisa ser um mapa de chaves.', linha: 2 }] };
+    }
+    return { data, problems: [] };
+}
+function problem(arquivo, regra, mensagem) {
+    return { arquivo, regra, mensagem, linha: null };
+}
+function missingKeys(file, data, keys, context = '') {
+    return keys
+        .filter((key) => !(key in data))
+        .map((key) => problem(file, 'chave-ausente', `Chave obrigatória ausente${context}: ${key}.`));
+}
+function validateCommon(file, data, expectedType, folderId) {
+    const problems = missingKeys(file, data, COMMON_KEYS);
+    if (typeof data.schema_versao === 'number' && data.schema_versao > SCHEMA_VERSION) {
+        problems.push(problem(file, 'schema-futuro', `schema_versao ${data.schema_versao} é mais nova que a suportada (${SCHEMA_VERSION}); atualize o ai-harness.`));
+    }
+    else if ('schema_versao' in data && data.schema_versao !== SCHEMA_VERSION) {
+        problems.push(problem(file, 'formato-invalido', `schema_versao deve ser ${SCHEMA_VERSION}.`));
+    }
+    if ('tipo' in data && data.tipo !== expectedType) {
+        problems.push(problem(file, 'tipo-desconhecido', `tipo "${String(data.tipo)}" inválido para este arquivo; esperado: ${expectedType}.`));
+    }
+    if ('trabalho_tipo' in data && !WORK_TYPES.includes(String(data.trabalho_tipo))) {
+        problems.push(problem(file, 'tipo-desconhecido', `trabalho_tipo "${String(data.trabalho_tipo)}" desconhecido. Use: ${WORK_TYPES.join(', ')}.`));
+    }
+    const allowed = STATUS_BY_TYPE[expectedType] ?? [];
+    if ('status' in data && !allowed.includes(String(data.status))) {
+        problems.push(problem(file, 'status-invalido', `status "${String(data.status)}" inválido para ${expectedType}. Use: ${allowed.join(', ')}.`));
+    }
+    if ('id' in data && data.id !== folderId) {
+        problems.push(problem(file, 'id-divergente', `id "${String(data.id)}" difere do nome da pasta do trabalho (${folderId}).`));
+    }
+    if ('titulo' in data && (typeof data.titulo !== 'string' || !data.titulo.trim())) {
+        problems.push(problem(file, 'formato-invalido', 'titulo deve ser um texto não vazio.'));
+    }
+    for (const key of ['criado_em', 'atualizado_em']) {
+        if (key in data && (typeof data[key] !== 'string' || !DATE.test(data[key]))) {
+            problems.push(problem(file, 'formato-invalido', `${key} deve ser uma data AAAA-MM-DD.`));
+        }
+    }
+    if ('arquivos' in data) {
+        if (!isStringList(data.arquivos)) {
+            problems.push(problem(file, 'formato-invalido', 'arquivos deve ser uma lista de caminhos.'));
+        }
+        else {
+            for (const path of data.arquivos) {
+                if (isAbsolute(path) || /^[A-Za-z]:[\\/]/.test(path)) {
+                    problems.push(problem(file, 'caminho-absoluto', `Caminho absoluto em arquivos: ${path}. Use caminhos relativos à raiz do projeto.`));
+                }
+            }
+        }
+    }
+    if ('migrado' in data && typeof data.migrado !== 'boolean') {
+        problems.push(problem(file, 'formato-invalido', 'migrado, quando presente, deve ser true ou false.'));
+    }
+    return problems;
+}
+function findCycle(tasks) {
+    const deps = new Map(tasks.map((task) => [task.id, task.deps]));
+    const state = new Map();
+    const stack = [];
+    const visit = (id) => {
+        if (state.get(id) === 'feito')
+            return null;
+        if (state.get(id) === 'visitando')
+            return [...stack.slice(stack.indexOf(id)), id];
+        state.set(id, 'visitando');
+        stack.push(id);
+        for (const dep of deps.get(id) ?? []) {
+            if (!deps.has(dep))
+                continue;
+            const cycle = visit(dep);
+            if (cycle)
+                return cycle;
+        }
+        stack.pop();
+        state.set(id, 'feito');
+        return null;
+    };
+    for (const task of tasks) {
+        const cycle = visit(task.id);
+        if (cycle)
+            return cycle;
+    }
+    return null;
+}
+function validatePlan(file, data) {
+    const problems = missingKeys(file, data, PLAN_KEYS);
+    if ('condensado' in data && typeof data.condensado !== 'boolean') {
+        problems.push(problem(file, 'formato-invalido', 'condensado deve ser true ou false.'));
+    }
+    if ('auditoria_plano' in data && !['pendente', 'aprovado', 'reprovado'].includes(String(data.auditoria_plano))) {
+        problems.push(problem(file, 'status-invalido', 'auditoria_plano inválida. Use: pendente, aprovado, reprovado.'));
+    }
+    if ('causa_raiz' in data && data.causa_raiz !== null && !['hipotese', 'comprovada'].includes(String(data.causa_raiz))) {
+        problems.push(problem(file, 'status-invalido', 'causa_raiz inválida. Use: hipotese, comprovada ou null.'));
+    }
+    if (!('tasks' in data))
+        return problems;
+    if (!Array.isArray(data.tasks))
+        return [...problems, problem(file, 'formato-invalido', 'tasks deve ser uma lista.')];
+    const tasks = [];
+    data.tasks.forEach((entry, index) => {
+        if (!isData(entry)) {
+            problems.push(problem(file, 'formato-invalido', `tasks[${index}] deve ser um mapa de chaves.`));
+            return;
+        }
+        const label = typeof entry.id === 'string' ? entry.id : `tasks[${index}]`;
+        problems.push(...missingKeys(file, entry, TASK_KEYS, ` na task ${label}`));
+        if ('id' in entry && (typeof entry.id !== 'string' || !TASK_ID.test(entry.id))) {
+            problems.push(problem(file, 'formato-invalido', `id de task "${String(entry.id)}" fora do padrão T-SS.NN.`));
+        }
+        if ('status' in entry && !TASK_STATUS.includes(String(entry.status))) {
+            problems.push(problem(file, 'status-invalido', `status "${String(entry.status)}" inválido na task ${label}. Use: ${TASK_STATUS.join(', ')}.`));
+        }
+        if ('depende_de' in entry && !isStringList(entry.depende_de)) {
+            problems.push(problem(file, 'formato-invalido', `depende_de da task ${label} deve ser uma lista de ids.`));
+        }
+        if ('paralelizavel' in entry && typeof entry.paralelizavel !== 'boolean') {
+            problems.push(problem(file, 'formato-invalido', `paralelizavel da task ${label} deve ser true ou false.`));
+        }
+        if ('testes_criticos' in entry && !isStringList(entry.testes_criticos)) {
+            problems.push(problem(file, 'formato-invalido', `testes_criticos da task ${label} deve ser uma lista de textos.`));
+        }
+        tasks.push({ id: label, deps: isStringList(entry.depende_de) ? entry.depende_de : [] });
+    });
+    const ids = new Set(tasks.map((task) => task.id));
+    for (const task of tasks) {
+        for (const dep of task.deps) {
+            if (!ids.has(dep)) {
+                problems.push(problem(file, 'dependencia-inexistente', `A task ${task.id} depende de ${dep}, que não existe no plano.`));
+            }
+        }
+    }
+    const cycle = findCycle(tasks);
+    if (cycle)
+        problems.push(problem(file, 'ciclo-dependencia', `Ciclo de dependência entre tasks: ${cycle.join(' → ')}.`));
+    return problems;
+}
+function validateBlocks(file, data) {
+    if (!('bloqueios' in data))
+        return [problem(file, 'chave-ausente', 'Chave obrigatória ausente: bloqueios.')];
+    if (!Array.isArray(data.bloqueios))
+        return [problem(file, 'formato-invalido', 'bloqueios deve ser uma lista.')];
+    return data.bloqueios.flatMap((entry, index) => {
+        if (!isData(entry))
+            return [problem(file, 'formato-invalido', `bloqueios[${index}] deve ser um mapa de chaves.`)];
+        const label = typeof entry.id === 'string' ? entry.id : `bloqueios[${index}]`;
+        const problems = missingKeys(file, entry, BLOCK_KEYS, ` no bloqueio ${label}`);
+        if ('status' in entry && !['aberto', 'resolvido'].includes(String(entry.status))) {
+            problems.push(problem(file, 'status-invalido', `status "${String(entry.status)}" inválido no bloqueio ${label}. Use: aberto, resolvido.`));
+        }
+        return problems;
+    });
+}
+/** Arquivos da pasta do trabalho, relativos a ela, com separador `/`. */
+function listWorkFiles(dir) {
+    return readdirSync(dir, { recursive: true, encoding: 'utf8' })
+        .filter((rel) => statSync(join(dir, rel)).isFile())
+        .map((rel) => rel.split(sep).join('/'))
+        .sort();
+}
+export function validateWork(root, folderId) {
+    const base = `docs/trabalhos/${folderId}`;
+    const problems = [];
+    if (!WORK_ID.test(folderId)) {
+        problems.push(problem(base, 'nome-fora-do-padrao', `A pasta do trabalho "${folderId}" não segue o padrão AAAA-MM-DD-<slug>.`));
+    }
+    const artifactNames = Object.keys(ARTIFACT_TYPES);
+    const present = new Set();
+    const parsed = new Map();
+    for (const rel of listWorkFiles(join(root, WORKS_DIR, folderId))) {
+        const file = `${base}/${rel}`;
+        const expectedType = ARTIFACT_TYPES[rel];
+        if (!expectedType) {
+            const canonical = artifactNames.find((name) => name.toLowerCase() === rel.toLowerCase());
+            if (canonical) {
+                problems.push(problem(file, 'nome-fora-do-padrao', `Os artefatos têm nome em caixa alta: renomeie ${rel} para ${canonical}.`));
+            }
+            continue;
+        }
+        present.add(rel);
+        const { data, problems: readProblems } = readArtifact(file, readFileSync(join(root, WORKS_DIR, folderId, rel), 'utf8'));
+        problems.push(...readProblems);
+        if (!data)
+            continue;
+        parsed.set(rel, data);
+        problems.push(...validateCommon(file, data, expectedType, folderId));
+        if (expectedType === 'plano')
+            problems.push(...validatePlan(file, data));
+        if (expectedType === 'bloqueios')
+            problems.push(...validateBlocks(file, data));
+    }
+    const declared = [...parsed.values()].map((data) => data.trabalho_tipo).find((tipo) => WORK_TYPES.includes(String(tipo)));
+    // Trabalho migrado do layout antigo não tem os artefatos que o fluxo antigo não produzia (D-37).
+    const migrated = [...parsed.values()].some((data) => data.migrado === true);
+    if (typeof declared === 'string' && !migrated) {
+        const required = [...(REQUIRED_BY_WORK_TYPE[declared] ?? [])];
+        if (declared === 'bug' && parsed.get('PLAN.md')?.status === 'concluido') {
+            required.push('relatorios/TECNICO.md', 'relatorios/CLIENTE.md');
+        }
+        for (const rel of required) {
+            if (!present.has(rel)) {
+                problems.push(problem(base, 'artefato-obrigatorio-ausente', `Trabalho do tipo ${declared} sem o artefato obrigatório ${rel}.`));
+            }
+        }
+    }
+    return problems;
+}
+/** Valida todos os trabalhos em docs/trabalhos/; projeto sem a pasta não tem problemas. */
+export function validateAllWorks(root) {
+    const dir = join(root, WORKS_DIR);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter((name) => statSync(join(dir, name)).isDirectory())
+        .sort()
+        .flatMap((name) => validateWork(root, name));
+}