@fontdata/ai-harness 2.0.0 → 2.1.0

package/dist/install/plan.js

@@ -0,0 +1,209 @@
+import { copyFileSync, existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { allCommands, recommendedCommands, templatesDir } from '../catalog.js';
+import { runnableIds, suggestIds } from '../run.js';
+import { applyAtomically } from './atomic.js';
+import { buildLockItem, LOCK_VERSION, readLock, writeLock } from './lock.js';
+import { HOOKS_ITEM_ID, PROJECT_HOOKS_DIR, projectHooksConfig } from './hooks.js';
+import { neededSkillsFor, resolveSelection } from './selection.js';
+import { COMMENTS_RULE_PATH, commentsHooksConfig, ensureCommentsBaseline } from '../comentarios/instalar.js';
+import { combineHooks, EVENT_PERMISSION, mergeSettings } from './settings.js';
+/** Rule de convenção com o que é específico do projeto (D-38): é do projeto, então fica fora do lock. */
+export const PROJECT_RULE_PATH = '.claude/rules/harness-projeto.md';
+/** Esqueleto da rule de projeto; os comandos `-legado` renomeados pelo update entram na última seção. */
+export function projectRuleContent(legacy) {
+    const template = readFileSync(join(templatesDir, 'rules', 'harness-projeto.md'), 'utf8');
+    const list = legacy.map((path) => `- \`${path}\``).join('\n');
+    return list ? `${template.trimEnd()}\n\n${list}\n` : template;
+}
+/** Padrões do modo não interativo: o mais conservador possível para rodar em CI. */
+export function resolveInstallOptions(args) {
+    return {
+        scope: args.scope ?? 'recommended',
+        commands: args.commands,
+        includeMaster: args.includeMaster ?? true,
+        claudeMd: args.claudeMd ?? 'create',
+        conflict: args.conflict ?? 'skip',
+        hooks: args.hooks ?? true,
+        agents: args.agents ?? true,
+        comments: args.comments ?? true,
+    };
+}
+export function packageInfo() {
+    const pkg = JSON.parse(readFileSync(join(templatesDir, '..', 'package.json'), 'utf8'));
+    return { nome: pkg.name, versao: pkg.version };
+}
+/** Arquivos de uma pasta de template, relativos a ela, com separador `/` e em ordem estável. */
+function listFiles(dir) {
+    return readdirSync(dir, { recursive: true, encoding: 'utf8' })
+        .filter((rel) => !rel.endsWith('.DS_Store') && statSync(join(dir, rel)).isFile())
+        .map((rel) => rel.split(sep).join('/'))
+        .sort();
+}
+/** Arquivos que o pacote atual instala para um item; `null` quando o item saiu do catálogo. */
+export function itemSources(catalog, tipo, id) {
+    if (tipo === 'comando') {
+        const cmd = id === catalog.master.id ? catalog.master : allCommands(catalog).find((c) => c.id === id);
+        return cmd?.file ? [{ path: `.claude/commands/${id}.md`, source: join(templatesDir, cmd.file) }] : null;
+    }
+    if (tipo === 'skill') {
+        // Skills avulsas (como a lgpd-checker) e fluxos do catálogo publicados como skill.
+        const dir = catalog.skills.find((s) => s.id === id)?.dir ??
+            allCommands(catalog).find((c) => c.id === id)?.skill ??
+            (catalog.master.id === id ? catalog.master.skill : undefined);
+        if (!dir)
+            return null;
+        const base = join(templatesDir, dir);
+        return listFiles(base).map((rel) => ({ path: `.claude/skills/${id}/${rel}`, source: join(base, rel) }));
+    }
+    if (tipo === 'claude-md' && id === catalog.claudeMd.target) {
+        return [{ path: id, source: join(templatesDir, catalog.claudeMd.file) }];
+    }
+    if (tipo === 'hook' && id === HOOKS_ITEM_ID) {
+        // Os scripts da raiz e a lib; subpastas de outros comandos (como comentarios/) ficam de fora.
+        const base = join(templatesDir, 'hooks');
+        return listFiles(base)
+            .filter((rel) => rel.endsWith('.mjs') && (!rel.includes('/') || rel.startsWith('lib/')))
+            .map((rel) => ({ path: `${PROJECT_HOOKS_DIR}/${rel}`, source: join(base, rel) }));
+    }
+    if (tipo === 'agent') {
+        const agent = catalog.agents?.find((candidate) => candidate.id === id);
+        return agent ? [{ path: `.claude/agents/${id}.md`, source: join(templatesDir, agent.file) }] : null;
+    }
+    if (tipo === 'rule' && id === 'comentarios') {
+        return [{ path: COMMENTS_RULE_PATH, source: join(templatesDir, 'rules', 'comentarios.md') }];
+    }
+    if (tipo === 'hook' && id === 'comentarios') {
+        return [{ path: '.claude/hooks/comentarios/check.mjs', source: join(templatesDir, 'hooks', 'comentarios', 'check.mjs') }];
+    }
+    return null;
+}
+function selectCommands(catalog, options) {
+    if (options.scope === 'all')
+        return allCommands(catalog);
+    if (options.scope === 'recommended')
+        return recommendedCommands(catalog);
+    const known = new Set([...allCommands(catalog).map((c) => c.id), catalog.master.id]);
+    for (const id of options.commands) {
+        if (known.has(id))
+            continue;
+        const near = suggestIds(id, runnableIds(catalog));
+        throw new Error(`Comando desconhecido: ${id}${near.length ? `\nVocê quis dizer: ${near.join(', ')}` : ''}`);
+    }
+    return allCommands(catalog).filter((c) => options.commands.includes(c.id));
+}
+/** Calcula o que a instalação vai gravar, sem tocar no projeto. */
+export function planInstall(catalog, root, options) {
+    const wantMaster = options.includeMaster || options.commands.includes(catalog.master.id);
+    const { selected, autoAdded } = resolveSelection(catalog, selectCommands(catalog, options), wantMaster);
+    const plan = {
+        files: [],
+        skipped: [],
+        items: [],
+        autoAdded,
+        claudeMdBackup: false,
+        registerHooks: Boolean(options.hooks),
+        registerComments: Boolean(options.comments),
+    };
+    const add = (tipo, id) => {
+        const paths = [];
+        for (const entry of itemSources(catalog, tipo, id) ?? []) {
+            if (options.conflict === 'skip' && existsSync(join(root, entry.path))) {
+                plan.skipped.push(entry.path);
+                continue;
+            }
+            plan.files.push({ path: entry.path, content: readFileSync(entry.source) });
+            paths.push(entry.path);
+        }
+        if (paths.length)
+            plan.items.push({ tipo, id, paths });
+    };
+    for (const cmd of selected)
+        add(cmd.skill ? 'skill' : 'comando', cmd.id);
+    if (wantMaster)
+        add(catalog.master.skill ? 'skill' : 'comando', catalog.master.id);
+    for (const skill of neededSkillsFor(catalog, selected))
+        add('skill', skill.id);
+    if (options.hooks)
+        add('hook', HOOKS_ITEM_ID);
+    if (options.agents)
+        for (const agent of catalog.agents ?? [])
+            add('agent', agent.id);
+    if (options.comments) {
+        add('rule', 'comentarios');
+        add('hook', 'comentarios');
+    }
+    // Esqueleto da rule de projeto quando há fluxos ou agents que a leem; um arquivo existente nunca é tocado.
+    const readsProjectRule = options.agents || selected.some((cmd) => cmd.skill);
+    if (readsProjectRule && !existsSync(join(root, PROJECT_RULE_PATH))) {
+        plan.files.push({ path: PROJECT_RULE_PATH, content: Buffer.from(projectRuleContent([])) });
+    }
+    const target = catalog.claudeMd.target;
+    const claudeExists = existsSync(join(root, target));
+    const writeClaude = options.claudeMd === 'overwrite' || options.claudeMd === 'backup' || (options.claudeMd === 'create' && !claudeExists);
+    if (writeClaude) {
+        plan.files.push({ path: target, content: readFileSync(join(templatesDir, catalog.claudeMd.file)) });
+        plan.items.push({ tipo: 'claude-md', id: target, paths: [target] });
+        plan.claudeMdBackup = options.claudeMd === 'backup' && claudeExists;
+    }
+    return plan;
+}
+/**
+ * Aplica o plano de forma atômica e regrava o lock. Itens de instalações
+ * anteriores continuam no lock; arquivos regravados substituem os hashes antigos.
+ */
+export function executePlan(root, plan, pkg, now = new Date()) {
+    const previous = readLock(root);
+    const claudeItem = plan.items.find((item) => item.tipo === 'claude-md');
+    if (plan.claudeMdBackup && claudeItem) {
+        copyFileSync(join(root, claudeItem.id), join(root, `${claudeItem.id}.bak`));
+    }
+    applyAtomically(root, plan.files);
+    const permission = needsEventPermission(plan);
+    const hooks = combineHooks(plan.registerHooks ? projectHooksConfig() : {}, plan.registerComments ? commentsHooksConfig() : {});
+    if (Object.keys(hooks).length || permission)
+        mergeSettings(root, { hooks, allow: permission ? [EVENT_PERMISSION] : [] }, now);
+    if (plan.registerComments)
+        ensureCommentsBaseline(root);
+    const items = new Map();
+    for (const item of previous?.itens ?? [])
+        items.set(`${item.tipo}:${item.id}`, item);
+    for (const planned of plan.items) {
+        const key = `${planned.tipo}:${planned.id}`;
+        const fresh = buildLockItem(root, planned.tipo, planned.id, planned.paths);
+        const files = new Map((items.get(key)?.arquivos ?? []).map((entry) => [entry.caminho, entry]));
+        for (const entry of fresh.arquivos)
+            files.set(entry.caminho, entry);
+        items.set(key, { ...fresh, arquivos: [...files.values()].sort((a, b) => a.caminho.localeCompare(b.caminho)) });
+    }
+    const lock = {
+        lock_versao: LOCK_VERSION,
+        pacote: pkg,
+        gerado_em: now.toISOString(),
+        itens: [...items.values()].sort((a, b) => `${a.tipo}:${a.id}`.localeCompare(`${b.tipo}:${b.id}`)),
+    };
+    writeLock(root, lock);
+    return lock;
+}
+/** Skills e agents do harness registram o rastro com `npx @fontdata/ai-harness evento`. */
+function needsEventPermission(plan) {
+    return plan.items.some((item) => item.tipo === 'skill' || item.tipo === 'agent');
+}
+export function describePlan(plan) {
+    const lines = [`Arquivos a gravar (${plan.files.length}):`, ...plan.files.map((file) => `  + ${file.path}`)];
+    if (plan.skipped.length) {
+        lines.push(`Já existentes, mantidos (${plan.skipped.length}):`, ...plan.skipped.map((path) => `  = ${path}`));
+    }
+    if (plan.autoAdded.length)
+        lines.push(`Adicionados como dependência: ${plan.autoAdded.join(', ')}`);
+    if (plan.claudeMdBackup)
+        lines.push('O CLAUDE.md atual será copiado para CLAUDE.md.bak.');
+    if (plan.registerHooks)
+        lines.push('Hooks do harness registrados em .claude/settings.json (sem duplicar os existentes).');
+    if (needsEventPermission(plan))
+        lines.push(`Permissão ${EVENT_PERMISSION} em .claude/settings.json, para o rastro não pedir aprovação.`);
+    if (plan.registerComments) {
+        lines.push('Padrão de comentários: rule carregada em toda sessão, hook que bloqueia a violação e catraca do legado (gerada só na primeira instalação).');
+    }
+    return lines.join('\n');
+}

package/dist/install/selection.js

@@ -0,0 +1,77 @@
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { allCommands } from '../catalog.js';
+/**
+ * Manifestos de stack: se algum existir na raiz, é um projeto já existente.
+ */
+const PROJECT_MANIFESTS = [
+    'package.json', 'pyproject.toml', 'requirements.txt', 'go.mod',
+    'Cargo.toml', 'pom.xml', 'build.gradle', 'build.gradle.kts',
+    'composer.json', 'Gemfile', 'Makefile', 'CMakeLists.txt',
+    'tsconfig.json', 'pubspec.yaml', 'mix.exs',
+];
+/** Pastas de código-fonte que, se tiverem conteúdo, indicam projeto existente. */
+const SOURCE_DIRS = ['src', 'app', 'lib', 'source'];
+/**
+ * Detecta se a pasta alvo já é um projeto com código ('existing') ou está
+ * essencialmente vazia/recém-criada ('new'). Ignora .git e .claude — a presença
+ * deles sozinha não caracteriza um projeto existente.
+ */
+export function detectProjectKind(repoPath) {
+    // 1. Manifesto de stack na raiz.
+    if (PROJECT_MANIFESTS.some((f) => existsSync(resolve(repoPath, f))))
+        return 'existing';
+    // 2. Arquivo de solução/projeto .NET na raiz.
+    let rootEntries = [];
+    try {
+        rootEntries = readdirSync(repoPath);
+    }
+    catch {
+        return 'new';
+    }
+    if (rootEntries.some((f) => /\.(sln|csproj|fsproj|vbproj)$/i.test(f)))
+        return 'existing';
+    // 3. Pasta de código-fonte com algum conteúdo.
+    for (const dir of SOURCE_DIRS) {
+        const dirPath = resolve(repoPath, dir);
+        try {
+            if (statSync(dirPath).isDirectory() && readdirSync(dirPath).length)
+                return 'existing';
+        }
+        catch {
+            // pasta não existe — segue.
+        }
+    }
+    return 'new';
+}
+/**
+ * Completa a seleção com as dependências: os comandos que o /harness invoca
+ * (quando escolhido) e os declarados em `requires` por comando.
+ * Retorna a seleção final e os títulos adicionados automaticamente.
+ */
+export function resolveSelection(catalog, selected, wantMaster) {
+    let result = selected;
+    let autoAdded = [];
+    if (wantMaster) {
+        const required = catalog.master.requires || [];
+        const selectedIds = new Set(result.map((c) => c.id));
+        const missing = allCommands(catalog).filter((c) => required.includes(c.id) && !selectedIds.has(c.id));
+        if (missing.length) {
+            result = [...result, ...missing];
+            autoAdded = missing.map((c) => c.title);
+        }
+    }
+    const selectedIds = new Set(result.map((c) => c.id));
+    const deps = allCommands(catalog).filter((c) => !selectedIds.has(c.id) &&
+        result.some((sel) => (sel.requires || []).includes(c.id)));
+    if (deps.length) {
+        result = [...result, ...deps];
+        autoAdded = [...autoAdded, ...deps.map((c) => c.title)];
+    }
+    return { selected: result, autoAdded };
+}
+/** Skills exigidas pelos comandos selecionados (campo `requiresSkills`). */
+export function neededSkillsFor(catalog, selected) {
+    const neededSkillIds = new Set(selected.flatMap((c) => c.requiresSkills || []));
+    return (catalog.skills || []).filter((sk) => neededSkillIds.has(sk.id));
+}

package/dist/install/settings.js

@@ -0,0 +1,108 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const SETTINGS_PATH = join('.claude', 'settings.json');
+/** As skills de fluxo e os agents registram o rastro por este comando; sem a regra, cada evento pede aprovação. */
+export const EVENT_PERMISSION = 'Bash(npx @fontdata/ai-harness evento:*)';
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function timestamp(date) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return (`${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-` +
+        `${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`);
+}
+/** Junta configurações de hooks, evento por evento, na ordem recebida. */
+export function combineHooks(...configs) {
+    const combined = {};
+    for (const config of configs) {
+        for (const [event, groups] of Object.entries(config))
+            combined[event] = [...(combined[event] ?? []), ...groups];
+    }
+    return combined;
+}
+/** A regra já está em `permissions.allow` do `.claude/settings.json` do projeto? */
+export function hasAllowRule(root, rule) {
+    try {
+        const settings = JSON.parse(readFileSync(join(root, SETTINGS_PATH), 'utf8'));
+        const allow = settings.permissions?.allow;
+        return Array.isArray(allow) && allow.includes(rule);
+    }
+    catch {
+        return false;
+    }
+}
+export function mergeHooksIntoSettings(root, hooks, now = new Date()) {
+    return mergeSettings(root, { hooks }, now);
+}
+/**
+ * Acrescenta hooks e regras de `permissions.allow` ao `.claude/settings.json` do projeto
+ * sem perder o que já existe. Um hook é considerado presente quando algum grupo do mesmo
+ * evento já tem o mesmo `command`, e uma regra quando já está na lista, o que torna a
+ * operação idempotente. Tudo é gravado de uma vez, com um único backup datado do arquivo
+ * original; JSON inválido é recusado sem tocar em nada.
+ */
+export function mergeSettings(root, additions, now = new Date()) {
+    const file = join(root, SETTINGS_PATH);
+    const original = existsSync(file) ? readFileSync(file, 'utf8') : null;
+    let settings = {};
+    if (original !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(original);
+        }
+        catch {
+            parsed = undefined;
+        }
+        const invalid = !isPlainObject(parsed) ||
+            (parsed.hooks !== undefined && !isPlainObject(parsed.hooks)) ||
+            (parsed.permissions !== undefined && !isPlainObject(parsed.permissions)) ||
+            (isPlainObject(parsed.permissions) && parsed.permissions.allow !== undefined && !Array.isArray(parsed.permissions.allow));
+        if (invalid) {
+            throw new Error(`O ${SETTINGS_PATH} está com JSON inválido; corrija-o antes de instalar os hooks.`);
+        }
+        settings = parsed;
+    }
+    const next = { ...settings };
+    let changed = false;
+    const hookEntries = Object.entries(additions.hooks ?? {});
+    if (hookEntries.length) {
+        const merged = { ...(settings.hooks ?? {}) };
+        for (const [event, groups] of hookEntries) {
+            const eventGroups = [...(merged[event] ?? [])];
+            const known = new Set(eventGroups.flatMap((group) => group.hooks.map((hook) => hook.command)));
+            for (const group of groups) {
+                const missing = group.hooks.filter((hook) => !known.has(hook.command));
+                if (!missing.length)
+                    continue;
+                eventGroups.push({ ...group, hooks: missing });
+                for (const hook of missing)
+                    known.add(hook.command);
+                changed = true;
+            }
+            merged[event] = eventGroups;
+        }
+        next.hooks = merged;
+    }
+    const rules = additions.allow ?? [];
+    if (rules.length) {
+        const permissions = { ...(settings.permissions ?? {}) };
+        const allow = [...(permissions.allow ?? [])];
+        for (const rule of rules) {
+            if (allow.includes(rule))
+                continue;
+            allow.push(rule);
+            changed = true;
+        }
+        next.permissions = { ...permissions, allow };
+    }
+    if (!changed)
+        return { changed: false, backup: null };
+    let backup = null;
+    if (original !== null) {
+        backup = join('.claude', `settings.json.bak-${timestamp(now)}`);
+        copyFileSync(file, join(root, backup));
+    }
+    mkdirSync(join(root, '.claude'), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(next, null, 2)}\n`);
+    return { changed: true, backup };
+}

package/dist/memoria/indice.js

@@ -0,0 +1,195 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { EOL } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { ARTIFACT_TYPES, readArtifact, WORKS_DIR } from '../contratos/artefatos.js';
+import { suggestFlag } from '../install/flags.js';
+export const INDEX_PATH = join('.ai-harness', 'memoria', 'indice.json');
+export const INDEX_VERSION = 1;
+const BACKSLASH = String.fromCharCode(92);
+function normalizePath(path) {
+    return path.trim().split(BACKSLASH).join('/').replace(/^(\.\/)+/, '');
+}
+const text = (value) => (typeof value === 'string' ? value : null);
+const earliest = (a, b) => (!a ? b : !b ? a : a < b ? a : b);
+const latest = (a, b) => (!a ? b : !b ? a : a > b ? a : b);
+/** Data do último `trabalho_concluido` no rastro do trabalho, incluindo arquivos rotacionados. */
+function conclusionDate(root, workId) {
+    const dir = join(root, 'docs', 'eventos');
+    if (!existsSync(dir))
+        return null;
+    let date = null;
+    const logs = readdirSync(dir).filter((name) => name === `${workId}.jsonl` || (name.startsWith(`${workId}.`) && /^\d+\.jsonl$/.test(name.slice(workId.length + 1))));
+    for (const log of logs) {
+        for (const line of readFileSync(join(dir, log), 'utf8').split('\n')) {
+            try {
+                const event = JSON.parse(line);
+                if (event.evento === 'trabalho_concluido' && typeof event.ts === 'string')
+                    date = latest(date, event.ts.slice(0, 10));
+            }
+            catch {
+                // linha vazia ou incompleta.
+            }
+        }
+    }
+    return date;
+}
+/**
+ * Índice "quem mexeu neste arquivo e por quê", gerado do frontmatter dos trabalhos e do rastro.
+ * Não é busca semântica: toda resposta aponta um trabalho que pode ser conferido.
+ */
+export function buildIndex(root, now = new Date()) {
+    const index = { indice_versao: INDEX_VERSION, gerado_em: now.toISOString(), trabalhos: {}, arquivos: {}, problemas: [] };
+    const worksDir = join(root, WORKS_DIR);
+    if (!existsSync(worksDir))
+        return index;
+    const workIds = readdirSync(worksDir)
+        .filter((name) => statSync(join(worksDir, name)).isDirectory())
+        .sort();
+    for (const id of workIds) {
+        const summary = { trabalho_tipo: null, titulo: null, status: null, data: null, causa_raiz: null, criado_em: null, arquivos: [] };
+        const files = new Set();
+        let updatedAt = null;
+        let fallbackStatus = null;
+        let readable = false;
+        for (const rel of Object.keys(ARTIFACT_TYPES)) {
+            const path = join(worksDir, id, rel);
+            if (!existsSync(path))
+                continue;
+            const { data, problems } = readArtifact(`docs/trabalhos/${id}/${rel}`, readFileSync(path, 'utf8'));
+            if (!data) {
+                index.problemas.push(...problems.map(({ arquivo, mensagem }) => ({ arquivo, mensagem })));
+                continue;
+            }
+            readable = true;
+            summary.titulo ??= text(data.titulo);
+            summary.trabalho_tipo ??= text(data.trabalho_tipo);
+            if (rel === 'PLAN.md') {
+                summary.status = text(data.status);
+                summary.causa_raiz = text(data.causa_raiz);
+            }
+            fallbackStatus ??= text(data.status);
+            summary.criado_em = earliest(summary.criado_em, text(data.criado_em));
+            updatedAt = latest(updatedAt, text(data.atualizado_em));
+            if (Array.isArray(data.arquivos)) {
+                for (const file of data.arquivos)
+                    if (typeof file === 'string')
+                        files.add(normalizePath(file));
+            }
+        }
+        if (!readable)
+            continue;
+        summary.status ??= fallbackStatus;
+        summary.data = conclusionDate(root, id) ?? updatedAt ?? summary.criado_em;
+        summary.arquivos = [...files].sort();
+        index.trabalhos[id] = summary;
+        for (const file of summary.arquivos) {
+            const { trabalho_tipo, titulo, status, data, causa_raiz } = summary;
+            (index.arquivos[file] ??= []).push({ trabalho: id, trabalho_tipo, titulo, status, data, causa_raiz });
+        }
+    }
+    for (const entries of Object.values(index.arquivos)) {
+        entries.sort((a, b) => (a.data ?? '').localeCompare(b.data ?? '') || a.trabalho.localeCompare(b.trabalho));
+    }
+    index.arquivos = Object.fromEntries(Object.entries(index.arquivos).sort(([a], [b]) => a.localeCompare(b)));
+    return index;
+}
+export function writeIndex(root, index) {
+    const file = join(root, INDEX_PATH);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(index, null, 2)}\n`);
+}
+export function lookupFile(index, path) {
+    return index.arquivos[normalizePath(path)] ?? [];
+}
+/**
+ * Trabalhos que tocaram os arquivos da causa raiz de um bug. Só é candidata a regressão quando valem
+ * as três condições: o arquivo está na causa raiz, o trabalho terminou antes de o bug aparecer e a
+ * causa raiz foi comprovada.
+ */
+export function findRegressionCandidates(index, bugId) {
+    const bug = index.trabalhos[bugId];
+    if (!bug)
+        throw new Error(`Trabalho não encontrado no índice da memória: ${bugId}`);
+    const shared = new Map();
+    for (const file of bug.arquivos) {
+        for (const entry of index.arquivos[file] ?? []) {
+            if (entry.trabalho === bugId)
+                continue;
+            shared.set(entry.trabalho, [...(shared.get(entry.trabalho) ?? []), file]);
+        }
+    }
+    const proven = bug.causa_raiz === 'comprovada';
+    return [...shared]
+        .map(([id, arquivos]) => {
+        const work = index.trabalhos[id];
+        const before = Boolean(work?.data && bug.criado_em && work.data < bug.criado_em);
+        const motivo = !proven
+            ? 'causa raiz do bug ainda não comprovada'
+            : !before
+                ? 'o trabalho terminou depois de o bug aparecer'
+                : 'tocou arquivo da causa raiz comprovada antes de o bug aparecer';
+        return { trabalho: id, titulo: work?.titulo ?? null, data: work?.data ?? null, arquivos: arquivos.sort(), candidata: proven && before, motivo };
+    })
+        .sort((a, b) => (a.data ?? '').localeCompare(b.data ?? '') || a.trabalho.localeCompare(b.trabalho));
+}
+const FLAGS = ['--arquivo', '--regressao'];
+/** `ai-harness memoria [caminho] [--arquivo <caminho>] [--regressao <id>]` */
+export function runMemoryCommand(argv) {
+    let path;
+    let file;
+    let bugId;
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i] ?? '';
+        if (!token.startsWith('-')) {
+            if (path !== undefined)
+                throw new Error(`Argumento inesperado: ${token}`);
+            path = token;
+            continue;
+        }
+        if (!FLAGS.includes(token)) {
+            const suggestion = suggestFlag(token, FLAGS);
+            throw new Error(`Flag desconhecida: ${token}.${suggestion ? ` Você quis dizer ${suggestion}?` : ''}`);
+        }
+        const value = argv[i + 1];
+        if (value === undefined)
+            throw new Error(`${token} precisa de um valor.`);
+        i++;
+        if (token === '--arquivo')
+            file = value;
+        else
+            bugId = value;
+    }
+    const root = resolve(process.cwd(), path ?? '.');
+    if (!existsSync(root))
+        throw new Error(`Pasta não encontrada: ${root}`);
+    const index = buildIndex(root);
+    writeIndex(root, index);
+    if (file) {
+        const entries = lookupFile(index, file);
+        console.log(entries.length
+            ? [
+                `Trabalhos que tocaram ${normalizePath(file)}, do mais antigo ao mais recente:`,
+                ...entries.map((entry) => `  ${entry.data ?? 'sem data'}  ${entry.trabalho}  [${entry.trabalho_tipo ?? '?'}] ${entry.titulo ?? ''} (${entry.status ?? 'sem status'}${entry.causa_raiz ? `, causa raiz ${entry.causa_raiz}` : ''})`),
+            ].join(EOL)
+            : `Nenhum trabalho registrado tocou ${normalizePath(file)}.`);
+        return 0;
+    }
+    if (bugId) {
+        const suspects = findRegressionCandidates(index, bugId);
+        console.log(suspects.length
+            ? [
+                `Trabalhos que tocaram os arquivos de ${bugId}:`,
+                ...suspects.map((suspect) => `  ${suspect.candidata ? 'candidata ' : 'descartada'}  ${suspect.trabalho} — ${suspect.titulo ?? ''} (${suspect.data ?? 'sem data'}): ${suspect.motivo}; arquivos: ${suspect.arquivos.join(', ')}`),
+            ].join(EOL)
+            : `Nenhum outro trabalho tocou os arquivos de ${bugId}.`);
+        return 0;
+    }
+    const works = Object.keys(index.trabalhos).length;
+    const files = Object.keys(index.arquivos).length;
+    const lines = [`Índice da memória atualizado em ${INDEX_PATH}: ${works} trabalhos, ${files} arquivos.`];
+    if (index.problemas.length) {
+        lines.push('Artefatos ignorados por estarem fora do contrato:', ...index.problemas.map((p) => `  ! ${p.arquivo}: ${p.mensagem}`));
+    }
+    console.log(lines.join(EOL));
+    return 0;
+}