@fontdata/ai-harness 2.0.0 → 2.2.0

package/dist/migrar/migrar.js

@@ -0,0 +1,426 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, posix, resolve, sep } from 'node:path';
+import { parse, stringify } from 'yaml';
+import { SCHEMA_VERSION, WORK_ID } from '../contratos/artefatos.js';
+import { suggestFlag } from '../install/flags.js';
+/** Layout antigo (até a 2.0) → artefato do contrato de pastas por trabalho. */
+const SOURCES = {
+    specs: { tipo: 'spec', target: 'SPEC.md' },
+    plans: { tipo: 'plano', target: 'PLAN.md' },
+    bugs: { tipo: 'plano', target: 'PLAN.md' },
+    investigacoes: { tipo: 'relatorio_tecnico', target: 'relatorios/TECNICO.md' },
+};
+const SOURCE_DIRS = Object.keys(SOURCES);
+const IGNORED_NAME = /^(readme|index)\.md$/i;
+/** Sufixos de documentos que acompanham outro de mesmo nome base. */
+const SATELLITE_SUFFIXES = ['-plano', '-design', '-contrato-api', '-validacao'];
+const LEGACY_PATH = /\b[Dd]ocs\/(specs|plans|bugs|investigacoes)\b/;
+const OPEN_BOX = /^\s*[-*]\s+\[ \]/m;
+function slugOf(fileName) {
+    const slug = fileName
+        .replace(/\.md$/i, '')
+        .normalize('NFD')
+        .replace(/\p{Diacritic}/gu, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || 'documento';
+}
+function isGitRepo(root) {
+    return existsSync(join(root, '.git'));
+}
+function isTracked(root, path) {
+    try {
+        execFileSync('git', ['ls-files', '--error-unmatch', path], { cwd: root, stdio: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `docs` quando existe com esse nome; senão a pasta com outra caixa (como `Docs`), se houver. */
+function realDocsDir(root) {
+    const entries = readdirSync(root);
+    if (entries.includes('docs'))
+        return 'docs';
+    return entries.find((name) => name.toLowerCase() === 'docs' && statSync(join(root, name)).isDirectory()) ?? null;
+}
+/** Data do commit que criou o arquivo; fora do git, a data de modificação. */
+function creationDate(root, realPath, git) {
+    if (git) {
+        try {
+            const dates = execFileSync('git', ['log', '--diff-filter=A', '--follow', '--format=%cs', '--', realPath], {
+                cwd: root,
+                encoding: 'utf8',
+                stdio: ['ignore', 'pipe', 'ignore'],
+            })
+                .split('\n')
+                .filter(Boolean);
+            const first = dates.at(-1);
+            if (first)
+                return first;
+        }
+        catch {
+            // Fora do índice: vale a data do arquivo.
+        }
+    }
+    return statSync(join(root, realPath)).mtime.toISOString().slice(0, 10);
+}
+function markdownFiles(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir, { recursive: true, encoding: 'utf8' })
+        .filter((rel) => rel.endsWith('.md') && statSync(join(dir, rel)).isFile())
+        .map((rel) => rel.split(sep).join('/'))
+        .sort();
+}
+function legacyReferences(root) {
+    const files = [
+        'CLAUDE.md',
+        ...['rules', 'agents', 'skills', 'commands'].flatMap((dir) => markdownFiles(join(root, '.claude', dir)).map((rel) => `.claude/${dir}/${rel}`)),
+    ];
+    return files
+        .filter((rel) => existsSync(join(root, rel)))
+        .flatMap((rel) => readFileSync(join(root, rel), 'utf8')
+        .split('\n')
+        .flatMap((line, index) => (LEGACY_PATH.test(line) ? [`${rel}:${index + 1}`] : [])));
+}
+/** Destino de cada documento de um trabalho. Satélite sem lugar próprio vai para `anexos/`, sem frontmatter. */
+function assignTargets(members) {
+    const assigned = members.map(({ doc, suffix }) => {
+        if (suffix === '-plano')
+            return { doc, suffix, target: 'PLAN.md', tipo: 'plano' };
+        if (suffix === '-design')
+            return { doc, suffix, target: 'SPEC.md', tipo: 'spec' };
+        if (suffix)
+            return { doc, suffix, target: `anexos/${doc.name}`, tipo: 'anexo' };
+        return { doc, suffix, ...SOURCES[doc.dir] };
+    });
+    for (const entry of assigned.filter((candidate) => candidate.suffix === '-plano' || candidate.suffix === '-design')) {
+        const rival = assigned.find((other) => other !== entry && !other.suffix && other.target === entry.target);
+        if (!rival)
+            continue;
+        // Relatório do bug + plano de correção: o relatório vira o relatório técnico do trabalho.
+        if (entry.suffix === '-plano' && rival.doc.dir === 'bugs' && !assigned.some((other) => other.target === 'relatorios/TECNICO.md')) {
+            rival.target = 'relatorios/TECNICO.md';
+            rival.tipo = 'relatorio_tecnico';
+        }
+        else {
+            entry.target = `anexos/${entry.doc.name}`;
+            entry.tipo = 'anexo';
+        }
+    }
+    return assigned;
+}
+export function planMigration(root, options = {}) {
+    const today = options.today ?? new Date().toISOString().slice(0, 10);
+    const docsDir = realDocsDir(root);
+    const plan = { moves: [], ignored: [], conflicts: [], docsDir: docsDir ?? 'docs', references: [], today };
+    if (!docsDir)
+        return plan;
+    const git = isGitRepo(root);
+    const docs = [];
+    for (const dir of SOURCE_DIRS) {
+        const abs = join(root, docsDir, dir);
+        if (!existsSync(abs) || !statSync(abs).isDirectory())
+            continue;
+        const names = readdirSync(abs)
+            .filter((name) => name.toLowerCase().endsWith('.md') && statSync(join(abs, name)).isFile())
+            .sort();
+        for (const name of names) {
+            const from = `docs/${dir}/${name}`;
+            if (IGNORED_NAME.test(name))
+                plan.ignored.push(from);
+            else
+                docs.push({ dir, name, realPath: `${docsDir}/${dir}/${name}`, from, slug: slugOf(name) });
+        }
+    }
+    const slugs = new Set(docs.map((doc) => doc.slug));
+    const groups = new Map();
+    for (const doc of docs) {
+        const suffix = SATELLITE_SUFFIXES.find((candidate) => doc.slug.endsWith(candidate) && slugs.has(doc.slug.slice(0, -candidate.length))) ?? null;
+        const key = suffix ? doc.slug.slice(0, -suffix.length) : doc.slug;
+        groups.set(key, [...(groups.get(key) ?? []), { doc, suffix }]);
+    }
+    for (const [key, members] of groups) {
+        const firstDate = members.map(({ doc }) => creationDate(root, doc.realPath, git)).sort()[0] ?? today;
+        const id = WORK_ID.test(key) ? key : `${firstDate}-${key}`;
+        const trabalhoTipo = members.some(({ doc }) => doc.dir === 'bugs')
+            ? 'bug'
+            : members.some(({ doc }) => doc.dir === 'specs' || doc.dir === 'plans')
+                ? 'feature'
+                : 'investigacao';
+        const byTarget = new Map();
+        for (const entry of assignTargets(members))
+            byTarget.set(entry.target, [...(byTarget.get(entry.target) ?? []), entry]);
+        for (const [target, entries] of byTarget) {
+            const to = `docs/trabalhos/${id}/${target}`;
+            const [entry] = entries;
+            if (!entry || entries.length > 1 || existsSync(join(root, to))) {
+                plan.conflicts.push({ destino: to, origens: entries.map((candidate) => candidate.doc.from) });
+                continue;
+            }
+            plan.moves.push({ from: entry.doc.from, to, id, trabalhoTipo, tipo: entry.tipo });
+        }
+    }
+    const order = new Map(docs.map((doc, index) => [doc.from, index]));
+    plan.moves.sort((a, b) => (order.get(a.from) ?? 0) - (order.get(b.from) ?? 0));
+    if (plan.moves.length)
+        plan.references = legacyReferences(root);
+    return plan;
+}
+const ROOT_CAUSE_LABEL = /^(?:#{1,6}\s*(?:\d+[.)]\s*)?|\s*[-*]?\s*\*{0,2})causa[\s-]*raiz/im;
+const UNCONFIRMED = /n[ãa]o\s+(?:foi\s+)?(?:confirmad|comprovad)|hip[óo]tese|a\s+confirmar|suspeita/i;
+/** Com seção ou rótulo de causa raiz, a causa é comprovada, a não ser que o trecho diga que ainda é hipótese. */
+function rootCauseOf(body) {
+    const label = ROOT_CAUSE_LABEL.exec(body);
+    if (!label)
+        return 'hipotese';
+    return UNCONFIRMED.test(body.slice(label.index, label.index + 600)) ? 'hipotese' : 'comprovada';
+}
+const TASK_HEADING = /^(#{2,6})\s*(?:(?:task|tarefa)\s+|T-?)(\d+)\.(\d+)\b\s*[—–:.-]*\s*(.*)$/i;
+const TASK_ITEM = /^\s*[-*]\s+\[([ xX])\]\s+\*{0,2}(?:(?:task|tarefa)\s+|T-?)(\d+)\.(\d+)\b\s*[—–:.-]*\s*(.*)$/i;
+const ANY_HEADING = /^(#{1,6})\s/;
+const BOX = /^\s*[-*]\s+\[([ xX])\]/;
+const DONE_MARK = /✅|\bconclu[ií]d[ao]\b/i;
+function cleanTitle(raw, sprint, number) {
+    const title = raw
+        .replace(/[[(][^\])]*conclu[^\])]*[\])]/gi, '')
+        .replace(/✅/g, '')
+        .replace(/\bconclu[ií]d[ao]\b/gi, '')
+        .replace(/\*+/g, '')
+        .replace(/[\s—–:.-]+$/, '')
+        .trim()
+        .slice(0, 120);
+    return title || `Task ${sprint}.${number}`;
+}
+/**
+ * Tasks do plano antigo nos formatos encontrados nos projetos: `#### Task 1.1 — Título`, `### T1.1 — Título`
+ * e `- [x] **T1.1 — Título**`. Concluída quando marcada (✅, "concluída", `[x]`), quando a seção só tem caixas
+ * marcadas ou quando o plano inteiro não tem caixa aberta.
+ */
+function parseTasks(body) {
+    const found = [];
+    let current = null;
+    for (const line of body.split('\n')) {
+        const heading = TASK_HEADING.exec(line);
+        if (heading) {
+            const titulo = heading[4] ?? '';
+            current = { level: (heading[1] ?? '').length, sprint: Number(heading[2]), number: Number(heading[3]), titulo, marked: DONE_MARK.test(titulo), open: 0, closed: 0 };
+            found.push(current);
+            continue;
+        }
+        const item = TASK_ITEM.exec(line);
+        if (item) {
+            const titulo = item[4] ?? '';
+            found.push({ level: 7, sprint: Number(item[2]), number: Number(item[3]), titulo, marked: item[1] !== ' ' || DONE_MARK.test(titulo), open: 0, closed: 0 });
+            continue;
+        }
+        const other = ANY_HEADING.exec(line);
+        if (other && current && (other[1] ?? '').length <= current.level)
+            current = null;
+        const box = BOX.exec(line);
+        if (box && current) {
+            if (box[1] === ' ')
+                current.open += 1;
+            else
+                current.closed += 1;
+        }
+    }
+    const planDone = !OPEN_BOX.test(body);
+    const ids = new Set();
+    const tasks = [];
+    for (const task of found) {
+        let number = task.number;
+        const idFor = (n) => `T-${String(task.sprint).padStart(2, '0')}.${String(n).padStart(2, '0')}`;
+        while (ids.has(idFor(number)))
+            number += 1;
+        if (task.sprint > 99 || number > 99)
+            continue;
+        ids.add(idFor(number));
+        tasks.push({
+            id: idFor(number),
+            titulo: cleanTitle(task.titulo, task.sprint, task.number),
+            status: task.marked || planDone || (task.open === 0 && task.closed > 0) ? 'concluida' : 'pendente',
+            depende_de: [],
+            paralelizavel: false,
+            testes_criticos: [],
+        });
+    }
+    return tasks;
+}
+function contractFrontmatter(content, move, today) {
+    const match = /^\s*---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(content);
+    const parsed = match ? parse(match[1] ?? '') : null;
+    const existing = typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+    const body = match ? content.slice(match[0].length) : content;
+    const heading = /^#\s+(.+)$/m.exec(body)?.[1]?.trim();
+    const status = move.tipo === 'spec' ? 'aprovado' : move.tipo === 'plano' ? (OPEN_BOX.test(body) ? 'em-execucao' : 'concluido') : 'final';
+    const data = {
+        schema_versao: SCHEMA_VERSION,
+        tipo: move.tipo,
+        id: move.id,
+        trabalho_tipo: move.trabalhoTipo,
+        titulo: heading ?? move.id,
+        status,
+        criado_em: move.id.slice(0, 10),
+        atualizado_em: today,
+        arquivos: [],
+        migrado: true,
+        ...(move.tipo === 'plano'
+            ? {
+                condensado: false,
+                auditoria_plano: 'pendente',
+                causa_raiz: move.trabalhoTipo === 'bug' ? rootCauseOf(body) : null,
+                tasks: parseTasks(body),
+            }
+            : {}),
+    };
+    // O que já existia prevalece, exceto a identidade do artefato, que o contrato define.
+    const merged = { ...data, ...existing, schema_versao: SCHEMA_VERSION, tipo: move.tipo, id: move.id, trabalho_tipo: move.trabalhoTipo, migrado: true };
+    return `---\n${stringify(merged)}---\n${body.startsWith('\n') ? '' : '\n'}${body}`;
+}
+function safeDecode(path) {
+    try {
+        return decodeURI(path);
+    }
+    catch {
+        return path;
+    }
+}
+/**
+ * Links do documento migrado (D-36): o relativo é resolvido a partir do lugar antigo e reescrito a partir do
+ * novo, e o caminho de uma pasta antiga passa a apontar para o destino do documento citado.
+ */
+function rewriteLinks(content, move, destinations) {
+    const fromDir = posix.dirname(move.from);
+    const toDir = posix.dirname(move.to);
+    const destinationOf = (path) => destinations.get(path.replace(/^Docs\//, 'docs/'));
+    const relinked = content.replace(/\]\(([^)\s#]+)(#[^)\s]*)?\)/g, (whole, target, anchor) => {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith('/'))
+            return whole;
+        const decoded = safeDecode(target);
+        if (/^[Dd]ocs\//.test(decoded)) {
+            const moved = destinationOf(decoded);
+            return moved ? `](${moved}${anchor ?? ''})` : whole;
+        }
+        const resolved = posix.normalize(posix.join(fromDir, decoded));
+        const destination = destinationOf(resolved) ?? resolved;
+        const relative = posix.relative(toDir, destination) || posix.basename(destination);
+        return `](${target.includes('%') ? encodeURI(relative) : relative}${anchor ?? ''})`;
+    });
+    return relinked.replace(/\b[Dd]ocs\/(?:specs|plans|bugs|investigacoes)\/[^\s)`'"\]<>]+?\.md\b/g, (path) => destinationOf(path) ?? path);
+}
+/** `Docs/` → `docs/` em dois passos: num disco que não distingue caixa, a troca direta não tem efeito. */
+function renameDocsDir(root, from, git) {
+    const temp = `${from}-ai-harness-migrar`;
+    const move = (source, target) => {
+        if (git) {
+            try {
+                execFileSync('git', ['mv', source, target], { cwd: root, stdio: 'ignore' });
+                return;
+            }
+            catch {
+                // Pasta sem arquivo versionado: o git recusa, e a troca vai direto no disco.
+            }
+        }
+        renameSync(join(root, source), join(root, target));
+    };
+    move(from, temp);
+    move(temp, 'docs');
+}
+/** Pasta antiga vazia, ou só com `.gitkeep`, deixa de existir. */
+function removeLegacyDir(root, rel, git) {
+    const dir = join(root, rel);
+    if (!existsSync(dir))
+        return;
+    const entries = readdirSync(dir).filter((name) => name !== '.DS_Store');
+    if (entries.some((name) => name !== '.gitkeep'))
+        return;
+    const keep = `${rel}/.gitkeep`;
+    if (entries.includes('.gitkeep') && git && isTracked(root, keep))
+        execFileSync('git', ['rm', '-q', keep], { cwd: root, stdio: 'ignore' });
+    rmSync(dir, { recursive: true, force: true });
+}
+/** Move os documentos e aplica o frontmatter; arquivos versionados vão com `git mv` para manter o histórico. */
+export function applyMigration(root, plan) {
+    const git = isGitRepo(root);
+    if (plan.moves.length && plan.docsDir !== 'docs')
+        renameDocsDir(root, plan.docsDir, git);
+    for (const move of plan.moves) {
+        const target = join(root, move.to);
+        mkdirSync(dirname(target), { recursive: true });
+        if (git && isTracked(root, move.from))
+            execFileSync('git', ['mv', move.from, move.to], { cwd: root, stdio: 'ignore' });
+        else
+            renameSync(join(root, move.from), target);
+    }
+    // Links e frontmatter só depois de mover tudo: cada link precisa do destino final do documento citado.
+    const destinations = new Map(plan.moves.map((move) => [move.from, move.to]));
+    for (const move of plan.moves) {
+        const target = join(root, move.to);
+        const content = rewriteLinks(readFileSync(target, 'utf8'), move, destinations);
+        writeFileSync(target, move.tipo === 'anexo' ? content : contractFrontmatter(content, move, plan.today));
+    }
+    for (const dir of SOURCE_DIRS)
+        removeLegacyDir(root, `docs/${dir}`, git);
+}
+const MIGRATION_FLAGS = ['--yes', '-y', '--sim'];
+const REFERENCES_SHOWN = 40;
+/** `ai-harness migrar [caminho] [--yes]`; sem `--yes` só simula. */
+export function runMigrationCommand(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 (MIGRATION_FLAGS.includes(token)) {
+            yes = true;
+        }
+        else {
+            const suggestion = suggestFlag(token, MIGRATION_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 plan = planMigration(root);
+    if (!plan.moves.length && !plan.conflicts.length) {
+        const ignored = plan.ignored.length ? `\nIgnorados: ${plan.ignored.join(', ')}` : '';
+        console.log(`Nada a migrar: o projeto não tem documentos em docs/specs, docs/plans, docs/bugs nem docs/investigacoes.${ignored}`);
+        return 0;
+    }
+    const lines = [`Documentos a migrar (${plan.moves.length}):`, ...plan.moves.map((move) => `  ${move.from} → ${move.to}`)];
+    if (plan.docsDir !== 'docs') {
+        lines.push('', `A pasta ${plan.docsDir}/ será renomeada para docs/ antes de migrar, com git mv quando versionada.`);
+    }
+    if (plan.ignored.length) {
+        lines.push('', `Ignorados, ficam onde estão (${plan.ignored.length}):`, ...plan.ignored.map((ignored) => `  - ${ignored}`));
+    }
+    if (plan.conflicts.length) {
+        lines.push('', `Conflitos, ficam onde estão e o restante migra (${plan.conflicts.length}):`, ...plan.conflicts.map((conflict) => `  ! ${conflict.destino} ← ${conflict.origens.join(', ')}`));
+    }
+    if (plan.references.length) {
+        lines.push('', `Citações às pastas antigas no CLAUDE.md e em .claude/, para revisar à mão (${plan.references.length}):`, ...plan.references.slice(0, REFERENCES_SHOWN).map((reference) => `  ${reference}`));
+        if (plan.references.length > REFERENCES_SHOWN)
+            lines.push(`  … e mais ${plan.references.length - REFERENCES_SHOWN}`);
+    }
+    console.log(lines.join('\n'));
+    if (!plan.moves.length) {
+        console.error('\nNenhum documento pode ser migrado: resolva os conflitos acima.');
+        return 1;
+    }
+    if (!yes) {
+        console.log('\nSimulação — nada foi movido. Rode de novo com --yes para migrar.');
+        return 0;
+    }
+    applyMigration(root, plan);
+    console.log(`\nMigração concluída: ${plan.moves.length} documento(s) em docs/trabalhos/. ` +
+        'Rode `npx @fontdata/ai-harness doctor` para conferir o contrato.');
+    return 0;
+}

package/dist/rastro/command.js

@@ -0,0 +1,46 @@
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { templatesDir } from '../catalog.js';
+import { suggestFlag } from '../install/flags.js';
+/** O CLI grava pela mesma biblioteca dos hooks, para as duas formas produzirem o mesmo formato. */
+export async function loadRastroLib() {
+    return (await import(pathToFileURL(join(templatesDir, 'hooks', 'lib', 'rastro.mjs')).href));
+}
+const FLAGS = ['--trabalho', '--task', '--nome', '--resultado', '--dados'];
+/** `ai-harness evento <evento> [--trabalho id] [--task T-SS.NN] [--nome n] [--resultado r] [--dados json]` */
+export async function runEventCommand(argv) {
+    const [evento, ...rest] = argv;
+    if (!evento || evento.startsWith('-')) {
+        throw new Error('Informe o evento. Ex.: npx @fontdata/ai-harness evento suite_verde --task T-01.02');
+    }
+    const fields = { evento, origem: 'cli', nome: 'ai-harness' };
+    for (let i = 0; i < rest.length; i++) {
+        const flag = rest[i] ?? '';
+        if (!FLAGS.includes(flag)) {
+            const suggestion = suggestFlag(flag, FLAGS);
+            throw new Error(`Flag desconhecida: ${flag}.${suggestion ? ` Você quis dizer ${suggestion}?` : ''}`);
+        }
+        const value = rest[i + 1];
+        if (value === undefined)
+            throw new Error(`${flag} precisa de um valor.`);
+        i++;
+        if (flag === '--trabalho')
+            fields.trabalhoId = value;
+        else if (flag === '--task')
+            fields.taskId = value;
+        else if (flag === '--nome')
+            fields.nome = value;
+        else if (flag === '--resultado')
+            fields.resultado = value;
+        else {
+            try {
+                fields.dados = JSON.parse(value);
+            }
+            catch {
+                throw new Error('--dados precisa ser um JSON válido.');
+            }
+        }
+    }
+    (await loadRastroLib()).recordEvent(process.cwd(), fields);
+    return 0;
+}

package/dist/run.js

@@ -0,0 +1,86 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { allCommands, loadCatalog } from './catalog.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/** Raiz do pacote — é ela que vira o plugin carregado via `claude --plugin-dir`. */
+export const pluginRoot = join(__dirname, '..');
+/** Nome do plugin, lido do manifesto para não duplicar a string. */
+export function pluginName() {
+    const manifest = JSON.parse(readFileSync(join(pluginRoot, '.claude-plugin', 'plugin.json'), 'utf8'));
+    return manifest.name;
+}
+/**
+ * Ids executáveis: os comandos dos grupos mais o comando-mestre, que fica fora
+ * de `groups` no catálogo.
+ */
+export function runnableIds(catalog = loadCatalog()) {
+    const ids = allCommands(catalog).map((cmd) => cmd.id);
+    if (catalog.master?.id)
+        ids.unshift(catalog.master.id);
+    return [...new Set(ids)];
+}
+/** Ids mais parecidos com o que foi digitado, para sugerir em caso de erro. */
+export function suggestIds(input, ids) {
+    const needle = input.toLowerCase();
+    return ids
+        .filter((id) => id.includes(needle) || needle.includes(id) || id.startsWith(needle.slice(0, 4)))
+        .slice(0, 5);
+}
+const SYSTEM_NOTE = 'Os slash commands do harness Fontdata estão disponíveis nesta sessão com o prefixo ' +
+    '`/PLUGIN:` (ex.: `/PLUGIN:nova-tarefa`). Quando uma instrução referenciar um comando ' +
+    'como `/nome`, entenda que se trata de `/PLUGIN:nome`.';
+/**
+ * Executa um comando do catálogo abrindo o Claude Code na pasta atual, com o
+ * pacote carregado como plugin da sessão — sem instalar nada no projeto.
+ */
+export function runCommand(id, args = [], claudeFlags = []) {
+    const catalog = loadCatalog();
+    const ids = runnableIds(catalog);
+    const wanted = id.replace(/^\//, '');
+    if (!ids.includes(wanted)) {
+        const near = suggestIds(wanted, ids);
+        console.error(`Comando desconhecido: ${wanted}`);
+        if (near.length)
+            console.error(`\nVocê quis dizer: ${near.join(', ')}`);
+        console.error('\nRode `npx @fontdata/ai-harness list` para ver o catálogo completo.');
+        return 1;
+    }
+    const name = pluginName();
+    const prompt = [`/${name}:${wanted}`, ...args].join(' ').trim();
+    const argv = [
+        '--plugin-dir',
+        pluginRoot,
+        '--append-system-prompt',
+        SYSTEM_NOTE.replaceAll('PLUGIN', name),
+        ...claudeFlags,
+        '--',
+        prompt,
+    ];
+    const result = spawn(argv);
+    const error = result.error;
+    if (error?.code === 'ENOENT') {
+        console.error('Claude Code não encontrado no PATH.\n' +
+            'Instale com: npm install -g @anthropic-ai/claude-code');
+        return 127;
+    }
+    if (error) {
+        console.error('Erro ao executar o Claude Code:', error.message);
+        return 1;
+    }
+    return result.status ?? 0;
+}
+/**
+ * No Windows o `claude` costuma ser um `.cmd`, que o spawn sem shell não
+ * resolve; nesse caso repetimos a chamada pelo shell, com os argumentos citados.
+ */
+function spawn(argv) {
+    const direct = spawnSync('claude', argv, { stdio: 'inherit', cwd: process.cwd() });
+    const error = direct.error;
+    if (error?.code === 'ENOENT' && process.platform === 'win32') {
+        const quoted = argv.map((arg) => `"${String(arg).replaceAll('"', '\\"')}"`).join(' ');
+        return spawnSync(`claude ${quoted}`, { stdio: 'inherit', cwd: process.cwd(), shell: true });
+    }
+    return direct;
+}

package/dist/trabalhos/conflitos.js

@@ -0,0 +1,115 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { readArtifact } from '../contratos/artefatos.js';
+import { suggestFlag } from '../install/flags.js';
+import { loadRastroLib } from '../rastro/command.js';
+const FINISHED = new Set(['concluido', 'cancelado']);
+const normalize = (path) => path.trim().replace(/^\.\//, '').replace(/\/+$/, '');
+/** Mesmo arquivo, ou um dos caminhos é uma pasta que contém o outro. */
+function overlaps(a, b) {
+    return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+function readPlan(root, workId) {
+    const rel = `docs/trabalhos/${workId}/PLAN.md`;
+    const file = join(root, rel);
+    if (!existsSync(file))
+        return null;
+    const { data } = readArtifact(rel, readFileSync(file, 'utf8'));
+    if (!data)
+        return null;
+    const listed = Array.isArray(data.arquivos) ? data.arquivos : [];
+    const arquivos = listed.filter((entry) => typeof entry === 'string').map(normalize).filter(Boolean);
+    return { status: String(data.status ?? ''), arquivos };
+}
+/**
+ * Trabalhos em execução (PLAN.md `em-execucao` ou listados no estado.json) que declaram arquivos em comum
+ * com o plano do trabalho informado. Várias sessões executam trabalhos na mesma pasta; dois trabalhos
+ * mexendo no mesmo código ao mesmo tempo quebram os testes um do outro.
+ */
+export async function findConflicts(root, workId) {
+    const own = readPlan(root, workId);
+    if (!own)
+        throw new Error(`Não há docs/trabalhos/${workId}/PLAN.md com frontmatter legível.`);
+    const listed = new Set((await loadRastroLib()).findActiveWorks(root));
+    const report = { arquivos: own.arquivos, conflitos: [], semArquivos: [] };
+    for (const id of readdirSync(join(root, 'docs', 'trabalhos'))) {
+        if (id === workId)
+            continue;
+        const plan = readPlan(root, id);
+        if (!plan || FINISHED.has(plan.status) || (plan.status !== 'em-execucao' && !listed.has(id)))
+            continue;
+        if (!plan.arquivos.length) {
+            report.semArquivos.push(id);
+            continue;
+        }
+        const shared = own.arquivos.filter((a) => plan.arquivos.some((b) => overlaps(a, b)));
+        if (shared.length)
+            report.conflitos.push({ trabalho: id, arquivos: shared });
+    }
+    return report;
+}
+export function formatConflicts(workId, report) {
+    const lines = [];
+    if (!report.arquivos.length) {
+        lines.push(`O PLAN.md de ${workId} não declara arquivos em \`arquivos\`: sem eles não há como detectar conflito com outros trabalhos.`);
+    }
+    for (const id of report.semArquivos) {
+        lines.push(`O trabalho ${id} está em execução, mas o PLAN.md dele não declara arquivos: não há como comparar com ele.`);
+    }
+    if (!report.conflitos.length) {
+        lines.push(`Nenhum trabalho em execução mexe nos arquivos de ${workId}.`);
+        return lines.join('\n');
+    }
+    lines.push(`${workId} mexe em arquivos que estão em uso por outro trabalho em execução:`, ...report.conflitos.map((conflict) => `  - ${conflict.trabalho}: ${conflict.arquivos.join(', ')}`), `Aguarde a conclusão (npx @fontdata/ai-harness conflitos ${workId} --aguardar). Se um desses trabalhos foi ` +
+        'abandonado, troque o status do PLAN.md dele para `cancelado`.');
+    return lines.join('\n');
+}
+/** Espera até nenhum trabalho em execução mexer nos mesmos arquivos. */
+export async function waitForFreeFiles(root, workId, options) {
+    const wait = options.wait ?? sleep;
+    let previous = '';
+    for (;;) {
+        const report = await findConflicts(root, workId);
+        if (!report.conflitos.length)
+            return report;
+        const holders = report.conflitos.map((conflict) => conflict.trabalho).join(', ');
+        if (holders !== previous)
+            options.log(`Aguardando ${holders} concluir para liberar os arquivos de ${workId}...`);
+        previous = holders;
+        await wait(options.intervalMs);
+    }
+}
+const FLAGS = ['--aguardar', '--intervalo'];
+/** `ai-harness conflitos <id> [--aguardar] [--intervalo <segundos>]` — sai com 1 quando há conflito sem --aguardar. */
+export async function runConflictsCommand(argv, root = process.cwd()) {
+    const [workId, ...rest] = argv;
+    if (!workId || workId.startsWith('-')) {
+        throw new Error('Informe o id do trabalho. Ex.: npx @fontdata/ai-harness conflitos 2026-09-18-login --aguardar');
+    }
+    let waitMode = false;
+    let intervalMs = 30_000;
+    for (let i = 0; i < rest.length; i++) {
+        const flag = rest[i] ?? '';
+        if (flag === '--aguardar')
+            waitMode = true;
+        else if (flag === '--intervalo') {
+            const seconds = Number(rest[++i]);
+            if (!Number.isFinite(seconds) || seconds <= 0)
+                throw new Error('--intervalo precisa de um número de segundos maior que zero.');
+            intervalMs = seconds * 1000;
+        }
+        else {
+            const suggestion = suggestFlag(flag, FLAGS);
+            throw new Error(`Flag desconhecida: ${flag}.${suggestion ? ` Você quis dizer ${suggestion}?` : ''}`);
+        }
+    }
+    if (!waitMode) {
+        const report = await findConflicts(root, workId);
+        console.log(formatConflicts(workId, report));
+        return report.conflitos.length ? 1 : 0;
+    }
+    const report = await waitForFreeFiles(root, workId, { intervalMs, log: (line) => console.log(line) });
+    console.log(formatConflicts(workId, report));
+    return 0;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};