@fontdata/ai-harness 2.2.0 → 2.3.1

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "fontdata",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "description": "Harness de engenharia com IA da Fontdata para Claude Code",
   "author": { "name": "Fontdata" },
   "commands": ["./templates/commands"],

package/README.md

@@ -108,9 +108,9 @@ duas vezes.
 | Subcomando | O que faz |
 |---|---|
 | `init [caminho]` | Instala comandos, skills, agents e hooks no projeto |
-| `doctor [caminho]` | Diagnostica instalação, contrato dos documentos, rastro, bloqueios antigos e versão do Node |
+| `doctor [caminho]` | Diagnostica instalação, contrato dos documentos, rastro, bloqueios antigos, citações às pastas antigas de `docs/` no código e versão do Node |
 | `update [caminho]` | Atualiza o que foi instalado sem sobrescrever alterações locais (`--check`, `--yes`, `--forcar`) |
-| `migrar [caminho]` | Move os documentos do layout anterior para `docs/trabalhos/<id>/` (`--yes`) |
+| `migrar [caminho]` | Move os documentos do layout anterior para `docs/trabalhos/<id>/` (`--yes`); `--reclassificar` corrige planos migrados que ficaram em execução |
 | `memoria [caminho]` | Índice de quem mexeu em cada arquivo (`--arquivo <caminho>`, `--regressao <id>`) |
 | `evento <evento>` | Grava no rastro do trabalho (usado por fluxos e agents) |
 | `conflitos <id>` | Aponta trabalhos em execução que mexem nos mesmos arquivos; `--aguardar` espera liberar (usado pelo `/executar-plan`) |

package/dist/cli.js

@@ -48,6 +48,7 @@ Gerenciar:
   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)
+                    --reclassificar: planos já migrados em em-execucao viram concluido ou legado
   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}')

package/dist/contratos/artefatos.js

@@ -19,7 +19,7 @@ export const ARTIFACT_TYPES = {
 };
 export const STATUS_BY_TYPE = {
     spec: ['rascunho', 'aguardando-aprovacao', 'aprovado', 'substituido'],
-    plano: ['rascunho', 'aguardando-aprovacao', 'em-execucao', 'concluido', 'cancelado'],
+    plano: ['rascunho', 'aguardando-aprovacao', 'em-execucao', 'concluido', 'cancelado', 'legado'],
     decisoes: ['ativo'],
     bloqueios: ['aberto', 'resolvido'],
     relatorio_tecnico: ['rascunho', 'final'],

package/dist/doctor/checks.js

@@ -8,6 +8,7 @@ import { validateEventLog } from '../contratos/eventos.js';
 import { hashContent, LOCK_PATH, LOCK_VERSION } from '../install/lock.js';
 import { SETTINGS_PATH } from '../install/settings.js';
 import { adoptLegacyInstall } from '../update/legado.js';
+import { checkLegacyDocsCitations, checkMigratedPlansRunning } from './migracao.js';
 const MIN_NODE_MAJOR = 22;
 const PLUGIN_ID = 'fontdata@ai-harness';
 const HARNESS_HOOKS_DIR = '.claude/hooks/ai-harness/';
@@ -413,6 +414,8 @@ export function runDoctor(root, options = {}) {
         ...checkStaleBlocks(root, options.now ?? new Date(), options.staleBlockDays ?? config.bloqueios.dias_para_aviso),
         ...checkEventLogs(root),
         ...checkCompletedTasks(root),
+        ...checkMigratedPlansRunning(root),
+        ...checkLegacyDocsCitations(root),
     ];
 }
 export function formatFindings(findings) {

package/dist/doctor/migracao.js

@@ -0,0 +1,97 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { extname, join } from 'node:path';
+import { readArtifact, WORKS_DIR } from '../contratos/artefatos.js';
+/** As mesmas extensões e pastas ignoradas do hook de comentários (templates/hooks/comentarios/check.mjs). */
+const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.cs', '.php', '.pas', '.dpr', '.sql', '.sh']);
+const SKIPPED_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage', 'out', 'vendor', 'generated', '__generated__']);
+const MAX_FILE_BYTES = 1_000_000;
+const LEGACY_CITATION = /\b[Dd]ocs\/(?:specs|plans|bugs|investigacoes)\//g;
+const TEST_FILE = /\.(test|spec)\.[jt]sx?$/;
+const COMMENT_LINE = /^\s*(\*|\(\*|\{(?!\$))/;
+const COMMENT_MARKER = /\/\/|\/\*|#|--/;
+const EXAMPLES_SHOWN = 5;
+function codeFiles(root, dir = '', found = []) {
+    let entries;
+    try {
+        entries = readdirSync(join(root, dir), { withFileTypes: true });
+    }
+    catch {
+        return found;
+    }
+    for (const entry of entries) {
+        const rel = dir ? `${dir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (!entry.name.startsWith('.') && !SKIPPED_DIRS.has(entry.name))
+                codeFiles(root, rel, found);
+        }
+        else if (entry.isFile() && CODE_EXTENSIONS.has(extname(entry.name)) && !entry.name.endsWith('.d.ts') && !TEST_FILE.test(entry.name)) {
+            found.push(rel);
+        }
+    }
+    return found;
+}
+/**
+ * O `migrar` reescreve os links dos documentos, mas não toca no código: a citação às pastas antigas num comentário
+ * vira caminho quebrado, e a rule de comentários já proíbe citar docs/ no código.
+ */
+export function checkLegacyDocsCitations(root) {
+    const places = [];
+    let total = 0;
+    for (const rel of codeFiles(root).sort()) {
+        const file = join(root, rel);
+        if (statSync(file).size > MAX_FILE_BYTES)
+            continue;
+        const lines = readFileSync(file, 'utf8').split('\n');
+        lines.forEach((line, index) => {
+            // Só a citação em comentário: a mesma string num literal de código é dado, não rastreabilidade.
+            const inComment = COMMENT_LINE.test(line)
+                ? [...line.matchAll(LEGACY_CITATION)]
+                : [...line.matchAll(LEGACY_CITATION)].filter((match) => COMMENT_MARKER.test(line.slice(0, match.index)));
+            const count = inComment.length;
+            if (!count)
+                return;
+            total += count;
+            places.push(`${rel}:${index + 1}`);
+        });
+    }
+    if (!total)
+        return [];
+    const files = new Set(places.map((place) => place.slice(0, place.lastIndexOf(':')))).size;
+    const examples = places.slice(0, EXAMPLES_SHOWN).join(', ');
+    const more = places.length > EXAMPLES_SHOWN ? ` e mais ${places.length - EXAMPLES_SHOWN}` : '';
+    return [
+        {
+            id: 'citacao-docs-em-codigo',
+            severidade: 'aviso',
+            mensagem: `${total} citação(ões) em ${files} arquivo(s) de código apontam para docs/specs, docs/plans, docs/bugs ou ` +
+                `docs/investigacoes, pastas que o migrar substituiu por docs/trabalhos/: ${examples}${more}.`,
+            correcao: 'Remova a citação do comentário (o vínculo fica no commit ou em docs/trabalhos/), como pede a rule ' +
+                '.claude/rules/comentarios.md. Arquivo tolerado pela catraca pode ser limpo aos poucos.',
+        },
+    ];
+}
+/** Planos migrados antes da 2.3.0 ficaram `em-execucao` e aparecem como ativos em todo `conflitos`. */
+export function checkMigratedPlansRunning(root) {
+    const dir = join(root, WORKS_DIR);
+    if (!existsSync(dir))
+        return [];
+    const stuck = readdirSync(dir).filter((id) => {
+        const rel = `docs/trabalhos/${id}/PLAN.md`;
+        if (!existsSync(join(root, rel)))
+            return false;
+        const { data } = readArtifact(rel, readFileSync(join(root, rel), 'utf8'));
+        const arquivos = Array.isArray(data?.arquivos) ? data.arquivos : [];
+        return data?.migrado === true && data.status === 'em-execucao' && !arquivos.length;
+    });
+    if (!stuck.length)
+        return [];
+    return [
+        {
+            id: 'plano-migrado-em-execucao',
+            severidade: 'aviso',
+            mensagem: `${stuck.length} plano(s) migrado(s) do layout antigo estão como em-execucao sem declarar arquivos: ${stuck.slice(0, EXAMPLES_SHOWN).join(', ')}${stuck.length > EXAMPLES_SHOWN ? ' …' : ''}.`,
+            correcao: 'Rode `npx @fontdata/ai-harness migrar --reclassificar --yes`: plano sem caixa aberta vira concluido, e o ' +
+                'restante vira legado, que não conta como trabalho ativo.',
+        },
+    ];
+}

package/dist/migrar/migrar.js

@@ -179,6 +179,10 @@ function rootCauseOf(body) {
         return 'hipotese';
     return UNCONFIRMED.test(body.slice(label.index, label.index + 600)) ? 'hipotese' : 'comprovada';
 }
+/** Plano antigo com caixa aberta não está necessariamente em execução: `legado` não conta como trabalho ativo. */
+function legacyPlanStatus(body) {
+    return OPEN_BOX.test(body) ? 'legado' : 'concluido';
+}
 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/;
@@ -256,7 +260,7 @@ function contractFrontmatter(content, move, today) {
     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 status = move.tipo === 'spec' ? 'aprovado' : move.tipo === 'plano' ? legacyPlanStatus(body) : 'final';
     const data = {
         schema_versao: SCHEMA_VERSION,
         tipo: move.tipo,
@@ -366,18 +370,83 @@ export function applyMigration(root, plan) {
     for (const dir of SOURCE_DIRS)
         removeLegacyDir(root, `docs/${dir}`, git);
 }
-const MIGRATION_FLAGS = ['--yes', '-y', '--sim'];
+const FRONTMATTER = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/;
+/**
+ * Planos migrados antes da 2.3.0 ficaram `em-execucao` quando tinham caixa aberta. Os que não declaram `arquivos`
+ * ganham o status que a migração daria hoje; quem preencheu `arquivos` está trabalhando neles e fica como está.
+ */
+export function planReclassification(root) {
+    const dir = join(root, 'docs', 'trabalhos');
+    if (!existsSync(dir))
+        return [];
+    const found = [];
+    for (const id of readdirSync(dir).sort()) {
+        const file = join(dir, id, 'PLAN.md');
+        if (!existsSync(file))
+            continue;
+        const content = readFileSync(file, 'utf8');
+        const match = FRONTMATTER.exec(content);
+        if (!match)
+            continue;
+        let data;
+        try {
+            data = parse(match[1] ?? '');
+        }
+        catch {
+            continue;
+        }
+        if (typeof data !== 'object' || data === null)
+            continue;
+        const { migrado, status, arquivos } = data;
+        if (migrado !== true || status !== 'em-execucao' || (Array.isArray(arquivos) && arquivos.length))
+            continue;
+        found.push({ id, de: status, para: legacyPlanStatus(content.slice(match[0].length)) });
+    }
+    return found;
+}
+/** Troca só a linha `status:` do frontmatter, para não reformatar o resto do arquivo. */
+export function applyReclassification(root, changes) {
+    for (const change of changes) {
+        const file = join(root, 'docs', 'trabalhos', change.id, 'PLAN.md');
+        const content = readFileSync(file, 'utf8');
+        const match = FRONTMATTER.exec(content);
+        if (!match)
+            continue;
+        const frontmatter = match[0].replace(/^status:[ \t]*['"]?em-execucao['"]?[ \t]*$/m, `status: ${change.para}`);
+        writeFileSync(file, frontmatter + content.slice(match[0].length));
+    }
+}
+function runReclassification(root, yes) {
+    const changes = planReclassification(root);
+    if (!changes.length) {
+        console.log('Nenhum plano migrado sem `arquivos` está como em-execucao: nada a reclassificar.');
+        return 0;
+    }
+    console.log([`Planos migrados a reclassificar (${changes.length}):`, ...changes.map((change) => `  ${change.id}: ${change.de} → ${change.para}`)].join('\n'));
+    if (!yes) {
+        console.log('\nSimulação — nada foi alterado. Rode de novo com --yes para reclassificar.');
+        return 0;
+    }
+    applyReclassification(root, changes);
+    console.log(`\nReclassificados: ${changes.length} plano(s).`);
+    return 0;
+}
+const MIGRATION_FLAGS = ['--yes', '-y', '--sim', '--reclassificar'];
 const REFERENCES_SHOWN = 40;
-/** `ai-harness migrar [caminho] [--yes]`; sem `--yes` só simula. */
+/** `ai-harness migrar [caminho] [--reclassificar] [--yes]`; sem `--yes` só simula. */
 export function runMigrationCommand(argv) {
     let path;
     let yes = false;
+    let reclassify = false;
     for (const token of argv) {
         if (!token.startsWith('-')) {
             if (path !== undefined)
                 throw new Error(`Argumento inesperado: ${token}`);
             path = token;
         }
+        else if (token === '--reclassificar') {
+            reclassify = true;
+        }
         else if (MIGRATION_FLAGS.includes(token)) {
             yes = true;
         }
@@ -389,6 +458,8 @@ export function runMigrationCommand(argv) {
     const root = resolve(process.cwd(), path ?? '.');
     if (!existsSync(root))
         throw new Error(`Pasta não encontrada: ${root}`);
+    if (reclassify)
+        return runReclassification(root, yes);
     const plan = planMigration(root);
     if (!plan.moves.length && !plan.conflicts.length) {
         const ignored = plan.ignored.length ? `\nIgnorados: ${plan.ignored.join(', ')}` : '';

package/dist/trabalhos/conflitos.js

@@ -20,7 +20,7 @@ function readPlan(root, workId) {
         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 };
+    return { status: String(data.status ?? ''), arquivos, migrado: data.migrado === true };
 }
 /**
  * Trabalhos em execução (PLAN.md `em-execucao` ou listados no estado.json) que declaram arquivos em comum
@@ -40,7 +40,9 @@ export async function findConflicts(root, workId) {
         if (!plan || FINISHED.has(plan.status) || (plan.status !== 'em-execucao' && !listed.has(id)))
             continue;
         if (!plan.arquivos.length) {
-            report.semArquivos.push(id);
+            // Plano migrado do layout antigo não diz o que tocou; só avisa quando alguém o está executando de fato.
+            if (!plan.migrado || listed.has(id))
+                report.semArquivos.push(id);
             continue;
         }
         const shared = own.arquivos.filter((a) => plan.arquivos.some((b) => overlaps(a, b)));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fontdata/ai-harness",
-  "version": "2.2.0",
+  "version": "2.3.1",
   "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": {

package/templates/hooks/comentarios/check.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync } from 'node:fs';
-import { extname, relative, join, dirname } from 'node:path';
+import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, openSync, closeSync, renameSync, rmSync, statSync } from 'node:fs';
+import { extname, relative, join, dirname, sep } from 'node:path';
 
 const MAX_BLOCO = Number(process.env.COMENTARIOS_MAX_BLOCO ?? 3);
 const MAX_DOCSTRING = Number(process.env.COMENTARIOS_MAX_DOCSTRING ?? 5);
@@ -9,7 +9,8 @@ const DENSIDADE_ALVO = 0.1;
 const EXTENSOES = new Set([
   '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs',
   '.py', '.go', '.rs', '.java', '.cs', '.php',
-  '.pas', '.dpr', '.sql', '.sh',
+  '.pas', '.dpr', '.dpk', '.lpr', '.sql', '.sh', '.bash', '.zsh',
+  '.ps1', '.psm1', '.bat', '.cmd',
 ]);
 
 const IGNORAR = [
@@ -21,14 +22,18 @@ const IGNORAR = [
 ];
 
 const CABECALHO_PERMITIDO =
-  /eslint|ts-nocheck|ts-ignore|prettier|@license|copyright|spdx|jshint|globals|^#!|use (strict|client|server)/i;
+  /eslint|ts-nocheck|ts-check|ts-ignore|prettier|@license|copyright|spdx|jshint|globals|use (strict|client|server)|code generated|do not edit|auto-generated/i;
 
 const BANNER = /^[-=─-╿_*#~+]{3,}|[-=─-╿_*#~+]{3,}$/;
 
+// Só a palavra ignora caixa: com a flag `i`, o romano casaria o "i" de "specialty".
+const semCaixa = (texto) => texto.replace(/\p{L}/gu, (c) => `[${c.toLowerCase()}${c.toUpperCase()}]`);
+const PROCESSO = new RegExp(`\\b(${semCaixa('task|tarefa|fase|etapa|plano|spec|sprint|epico|épico')})\\s*(\\d|[IVX]+\\b)`, 'u');
+
 const RASTREIO = [
-  [/\b(task|tarefa|fase|etapa|plano|spec|sprint|epico|épico)\s*[\dIVX]/i, 'referência a task/fase/plano/spec'],
+  [PROCESSO, 'referência a task/fase/plano/spec'],
   [/\bT\d+(\.\d+)+\b/, 'referência a task (T0.0)'],
-  [/docs\/(plans|specs|bugs|investigacoes)\//i, 'caminho de docs/ dentro do código'],
+  [/docs\/(plans|specs|bugs|investigacoes|trabalhos)\//i, 'caminho de docs/ dentro do código'],
   [/\bachado d[oe]\b/i, 'achado de review no código'],
   [/@[\w-]*(reviewer|auditor|orquestrador|agent)\b/i, 'menção a agent no código'],
   [/\b(commit|sha|hash)\s+[0-9a-f]{7,40}\b/i, 'hash de commit'],
@@ -38,33 +43,136 @@ const DATA = /(^|[^"'\w])20\d{2}-\d{2}-\d{2}([^"'\w]|$)/;
 const CODIGO_TOKEN = /(^|\s)(const|let|var|function|return|if|for|while|await|import|export|def|class)\b/;
 const CODIGO_FIM = /[;{}]\s*$/;
 
-function comentario(linha, ext) {
-  const t = linha.trim();
-  if (!t) return null;
-  if (ext === '.py' || ext === '.sh') return t.startsWith('#') ? t.replace(/^#+/, '').trim() : null;
-  if (ext === '.sql') {
-    if (t.startsWith('--')) return t.replace(/^-+/, '').trim();
-    if (t.startsWith('/*') || t.startsWith('*')) return t.replace(/^[/*]+/, '').trim();
-    return null;
+const so = (...exts) => new Set(exts);
+const JS = so('.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs');
+const C_LIKE = so(...JS, '.go', '.rs', '.java', '.cs', '.php');
+const PASCAL = so('.pas', '.dpr', '.dpk', '.lpr');
+const SHELL = so('.sh', '.bash', '.zsh');
+const POWERSHELL = so('.ps1', '.psm1');
+const BATCH = so('.bat', '.cmd');
+
+const SINTAXE = [
+  [so('.php'), { linha: ['//', '#'], blocos: [['/*', '*/']], naoComentario: /^#\[/ }],
+  [C_LIKE, { linha: ['//'], blocos: [['/*', '*/']] }],
+  [PASCAL, { linha: ['//'], blocos: [['{', '}'], ['(*', '*)']] }],
+  [so('.sql'), { linha: ['--'], blocos: [['/*', '*/']] }],
+  [POWERSHELL, { linha: ['#'], blocos: [['<#', '#>']] }],
+  [so('.py', ...SHELL), { linha: ['#'], blocos: [] }],
+  [BATCH, { linha: ['::'], blocos: [] }],
+];
+
+// Têm forma de comentário, mas são lidas pelo compilador, pelo interpretador ou por uma ferramenta.
+const DIRETIVA = Symbol('diretiva');
+const DIRETIVAS = [
+  [PASCAL, /^(\{|\(\*)[$%]/],
+  [C_LIKE, /^\/[/*]\s*(#?region\b|#?endregion\b|<\/?editor-fold|@formatter:)/i],
+  [JS, /^\/\/\/\s*<(reference|amd-module|amd-dependency)\b/],
+  [JS, /^\/[/*]\*?\s*(@ts-(check|nocheck|ignore|expect-error)\b|eslint|jshint|jscs:|tslint:|prettier-ignore|(istanbul|c8|v8) ignore|biome-ignore|deno-|oxlint-|@flow\b|@jsx|@vite-ignore|@vitest-environment|@jest-environment|webpack[A-Z]\w*:|@refresh\b)/i],
+  [JS, /^\/\*+\s*globals?\s/],
+  [JS, /^\/\/[#@]\s*source(Mapping)?URL=/],
+  [so('.go'), /^\/\/(go:|line |export |extern )|^\/\/\s*(\+build\b|nolint\b|lint:ignore\b)/],
+  [so('.rs'), /^#!\[/],
+  [so('.java'), /^\/[/*]\s*(noinspection\b|NOSONAR\b|CHECKSTYLE[:.]|\$NON-NLS)/],
+  [so('.cs'), /^#\s*(region|endregion|if|elif|else|endif|define|undef|pragma|nullable|warning|error|line)\b/],
+  [so('.cs'), /^\/\/\s*(ReSharper\s|<\/?auto-generated)/i],
+  [so('.php'), /^\/[/*]\*?\s*(phpcs:|@phpstan-|@psalm-|@codeCoverageIgnore|@noinspection\b|@var\s)/],
+  [so('.sql'), /^\/\*[!+]/],
+  [so('.sql'), /^--\s*(liquibase\s|changeset\s|rollback\b|precondition|comment:|validCheckSum\b|ignoreLines:|\+(goose|migrate)\b|name:\s*\S+\s*:|noqa\b|sqlfluff:|#?(region|endregion)\b)/i],
+  [so('.py'), /^#\s*(-\*-.*-\*-|(en)?coding[:=]|vim?:|noqa\b|nosec\b|type:|pylint:|mypy:|pyright:|pyre-|pytype:|ruff:|isort:|fmt:|pragma\b)/i],
+  [SHELL, /^#\s*(shellcheck\s|-\*-.*-\*-|vim?:|ex:)|^#(compdef|autoload)\b/i],
+  [POWERSHELL, /^#(requires|region|endregion)\b/i],
+];
+const BLOCOS_DIRETIVA = [
+  [SHELL, /^###\s*BEGIN INIT INFO/, /^###\s*END INIT INFO/],
+  [POWERSHELL, /^#\s*SIG\s*#\s*Begin signature block/i, /^#\s*SIG\s*#\s*End signature block/i],
+];
+const HEREDOC = /(?<!<)<<(?!<)-?\s*(['"]?)([A-Za-z_]\w*)\1/g;
+
+const limpar = (texto) => texto.replace(/^\*+/, '').trim();
+
+function comentarioDeLinha(t, sintaxe, ext) {
+  if (BATCH.has(ext)) {
+    if (t.startsWith('::')) return t.replace(/^:+/, '').trim();
+    const rem = t.match(/^@?rem(?:[\s.:/\\](.*))?$/i);
+    return rem ? (rem[1] ?? '').trim() : null;
+  }
+  const marcador = sintaxe.linha.find((m) => t.startsWith(m));
+  if (!marcador || sintaxe.naoComentario?.test(t)) return null;
+  let k = 0;
+  while (t[k] === marcador[0]) k++;
+  return t.slice(k).trim();
+}
+
+// Devolve, por linha: o texto do comentário, DIRETIVA, ou null para código e linha em branco.
+function classificar(linhas, ext) {
+  const sintaxe = SINTAXE.find(([exts]) => exts.has(ext))?.[1] ?? { linha: ['//'], blocos: [['/*', '*/']] };
+  const saida = [];
+  const heredocs = [];
+  let fimTexto = null;
+  let fimDiretiva = null;
+  let bloco = null;
+  for (let i = 0; i < linhas.length; i++) {
+    const t = linhas[i].trim();
+    if (heredocs.length) {
+      if (t === heredocs[0]) heredocs.shift();
+      saida.push(null);
+      continue;
+    }
+    if (fimTexto) {
+      if (fimTexto.test(t)) fimTexto = null;
+      saida.push(null);
+      continue;
+    }
+    if (bloco) {
+      const pos = t.indexOf(bloco.fim);
+      saida.push(bloco.diretiva ? DIRETIVA : limpar(pos === -1 ? t : t.slice(0, pos)));
+      if (pos !== -1) bloco = null;
+      continue;
+    }
+    if (!t) { saida.push(null); continue; }
+    if (fimDiretiva) {
+      if (fimDiretiva.test(t)) fimDiretiva = null;
+      saida.push(DIRETIVA);
+      continue;
+    }
+    const linhaDiretiva = BLOCOS_DIRETIVA.find(([exts, abre]) => exts.has(ext) && abre.test(t));
+    if (linhaDiretiva) { fimDiretiva = linhaDiretiva[2]; saida.push(DIRETIVA); continue; }
+
+    const diretiva = (i === 0 && t.startsWith('#!')) || DIRETIVAS.some(([exts, re]) => exts.has(ext) && re.test(t));
+    const abre = sintaxe.blocos.find(([inicio]) => t.startsWith(inicio));
+    if (abre) {
+      const resto = t.slice(abre[0].length);
+      const pos = resto.indexOf(abre[1]);
+      if (pos === -1) bloco = { fim: abre[1], diretiva };
+      saida.push(diretiva ? DIRETIVA : limpar(pos === -1 ? resto : resto.slice(0, pos)));
+      continue;
+    }
+    if (diretiva) { saida.push(DIRETIVA); continue; }
+
+    const c = comentarioDeLinha(t, sintaxe, ext);
+    saida.push(c);
+    if (c !== null) continue;
+    if (SHELL.has(ext)) for (const m of t.matchAll(HEREDOC)) heredocs.push(m[2]);
+    if (POWERSHELL.has(ext) && /@["']$/.test(t)) fimTexto = t.endsWith('"') ? /^"@/ : /^'@/;
   }
-  if (ext === '.pas' || ext === '.dpr') {
-    if (t.startsWith('//')) return t.replace(/^\/+/, '').trim();
-    if (t.startsWith('(*')) return t.replace(/^\(\*/, '').trim();
-    if (t.startsWith('{') && !t.startsWith('{$')) return t.replace(/^\{/, '').trim();
-    return null;
+  // O comentário colado em `import "C"` é o preâmbulo do cgo: código C, não comentário.
+  if (ext === '.go') {
+    for (let i = 0; i < linhas.length; i++) {
+      if (linhas[i].trim() !== 'import "C"') continue;
+      for (let j = i - 1; j >= 0 && typeof saida[j] === 'string'; j--) saida[j] = DIRETIVA;
+    }
   }
-  if (t.startsWith('//')) return t.replace(/^\/+/, '').trim();
-  if (t.startsWith('/*')) return t.replace(/^\/\*+/, '').trim();
-  if (t.startsWith('*')) return t.replace(/^\*+\/?/, '').trim();
-  return null;
+  return saida;
 }
 
+const ehTexto = (c) => typeof c === 'string';
+
 function analisar(caminho, fonte) {
   const ext = extname(caminho);
   const linhas = fonte.split('\n');
   const achados = [];
   const marca = (linha, msg) => achados.push({ linha, msg });
-  const ehComentario = linhas.map((l) => comentario(l, ext));
+  const ehComentario = classificar(linhas, ext);
 
   let primeiroCodigo = -1;
   for (let i = 0; i < linhas.length; i++) {
@@ -73,10 +181,10 @@ function analisar(caminho, fonte) {
 
   let i = 0;
   while (i < linhas.length) {
-    if (ehComentario[i] === null) { i++; continue; }
+    if (!ehTexto(ehComentario[i])) { i++; continue; }
     const inicio = i;
     const conteudo = [];
-    while (i < linhas.length && ehComentario[i] !== null) { conteudo.push(ehComentario[i]); i++; }
+    while (i < linhas.length && ehTexto(ehComentario[i])) { conteudo.push(ehComentario[i]); i++; }
     const fim = i - 1;
     const corpo = conteudo.filter(Boolean);
     const texto = corpo.join(' ');
@@ -99,9 +207,9 @@ function analisar(caminho, fonte) {
     }
 
     let proxima = fim + 1;
-    while (proxima < linhas.length && !linhas[proxima].trim()) proxima++;
+    while (proxima < linhas.length && (!linhas[proxima].trim() || ehComentario[proxima] === DIRETIVA)) proxima++;
     const ehDocstring =
-      /^(\/\*\*|"""|'''|\/\/\/)/.test(linhas[inicio].trim()) &&
+      /^(\/\*\*|"""|'''|\/\/\/|<#)/.test(linhas[inicio].trim()) &&
       proxima < linhas.length &&
       ehComentario[proxima] === null;
     const teto = ehDocstring ? MAX_DOCSTRING : MAX_BLOCO;
@@ -116,17 +224,52 @@ function analisar(caminho, fonte) {
     }
   }
 
-  const comentadas = ehComentario.filter((c) => c !== null).length;
+  const comentadas = ehComentario.filter(ehTexto).length;
   const uteis = linhas.filter((l) => l.trim()).length;
   return { achados, comentadas, uteis, densidade: uteis ? comentadas / uteis : 0 };
 }
 
+const raiz = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const BASELINE = join(raiz, '.claude', 'hooks', 'comentarios', 'baseline.json');
+
+// Pasta oculta na raiz (.claude, .ai-harness, .vscode...) é de ferramenta, não do projeto.
+function emPastaOculta(caminho) {
+  const rel = relative(raiz, caminho);
+  if (!rel || rel.startsWith('..')) return false;
+  return rel.split(sep).slice(0, -1).some((parte) => parte.startsWith('.'));
+}
+
 function elegivel(caminho) {
-  return EXTENSOES.has(extname(caminho)) && !IGNORAR.some((re) => re.test(caminho));
+  return EXTENSOES.has(extname(caminho)) && !IGNORAR.some((re) => re.test(caminho)) && !emPastaOculta(caminho);
 }
 
-const raiz = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const BASELINE = join(raiz, '.claude', 'hooks', 'comentarios', 'baseline.json');
+function gravarAtomico(arquivo, conteudo) {
+  const temp = `${arquivo}.${process.pid}.tmp`;
+  writeFileSync(temp, conteudo);
+  renameSync(temp, arquivo);
+}
+
+const esperar = (ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+
+// Vários agents editam em paralelo: a trava serializa o reler-e-gravar, e cada um mexe só na própria chave.
+function atualizarBaseline(chave, valor) {
+  const trava = `${BASELINE}.lock`;
+  let travado = false;
+  for (let tentativa = 0; tentativa < 300 && !travado; tentativa++) {
+    try { closeSync(openSync(trava, 'wx')); travado = true; } catch {
+      try { if (Date.now() - statSync(trava).mtimeMs > 10_000) rmSync(trava, { force: true }); } catch {}
+      if (!travado) esperar(10);
+    }
+  }
+  try {
+    const atual = JSON.parse(readFileSync(BASELINE, 'utf8'));
+    if (valor === 0) delete atual[chave];
+    else atual[chave] = Math.min(valor, atual[chave] ?? valor);
+    gravarAtomico(BASELINE, `${JSON.stringify(atual, null, 2)}\n`);
+  } catch {} finally {
+    if (travado) rmSync(trava, { force: true });
+  }
+}
 
 function varrer(dir, saida = []) {
   let itens;
@@ -134,7 +277,7 @@ function varrer(dir, saida = []) {
   for (const item of itens) {
     const cheio = join(dir, item.name);
     if (item.isDirectory()) {
-      if (item.name === 'node_modules' || item.name === '.git') continue;
+      if (item.name === 'node_modules' || item.name.startsWith('.')) continue;
       if (IGNORAR.some((re) => re.test(`${cheio}/`))) continue;
       varrer(cheio, saida);
     } else if (elegivel(cheio)) saida.push(cheio);
@@ -153,7 +296,7 @@ if (process.argv.includes('--gerar-baseline')) {
     if (achados.length > 0) { mapa[relative(raiz, f)] = achados.length; arquivos++; violacoes += achados.length; }
   }
   if (!existsSync(dirname(BASELINE))) mkdirSync(dirname(BASELINE), { recursive: true });
-  writeFileSync(BASELINE, `${JSON.stringify(mapa, null, 2)}\n`);
+  gravarAtomico(BASELINE, `${JSON.stringify(mapa, null, 2)}\n`);
   console.log(`[comentarios] baseline gravado: ${arquivos} arquivos legados, ${violacoes} violações toleradas.`);
   console.log('[comentarios] arquivo novo responde ao padrão cheio; legado só não pode piorar.');
   process.exit(0);
@@ -179,9 +322,7 @@ const tolerado = baseline?.[chave] ?? 0;
 
 if (achados.length <= tolerado) {
   if (baseline && tolerado > 0 && achados.length < tolerado) {
-    if (achados.length === 0) delete baseline[chave];
-    else baseline[chave] = achados.length;
-    try { writeFileSync(BASELINE, `${JSON.stringify(baseline, null, 2)}\n`); } catch {}
+    atualizarBaseline(chave, achados.length);
     console.error(`[comentarios] ${rel}: ${tolerado} → ${achados.length} violações. Catraca desceu — não pode mais subir.`);
   } else if (achados.length === 0 && densidade > DENSIDADE_ALVO) {
     console.error(`[comentarios] aviso: ${rel} tem ${(densidade * 100).toFixed(0)}% de linhas de comentário (${comentadas}/${uteis}), alvo <= ${DENSIDADE_ALVO * 100}%.`);

package/templates/hooks/lib/rastro.mjs

@@ -61,7 +61,7 @@ export function buildEvent(fields) {
 
 /**
  * Trabalhos ativos: os `trabalhos_ativos` do .ai-harness/estado.json (ou o `trabalho_ativo` do formato
- * anterior) ou, sem eles, os PLAN.md com `status: em-execucao`. Várias sessões podem executar
+ * anterior) ou, sem eles, os PLAN.md com `status: em-execucao` (menos os migrados sem `arquivos`). Várias sessões podem executar
  * trabalhos diferentes na mesma pasta, então a lista pode ter mais de um id.
  * @param {string} root
  * @returns {string[]}
@@ -88,7 +88,10 @@ export function findActiveWorks(root) {
     if (!existsSync(plan)) return false;
     const frontmatter = /^\s*---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(plan, 'utf8'))?.[1] ?? '';
     // Só o status do plano, na coluna zero; os status das tasks ficam indentados.
-    return /^status:\s*['"]?em-execucao['"]?\s*$/m.test(frontmatter);
+    if (!/^status:\s*['"]?em-execucao['"]?\s*$/m.test(frontmatter)) return false;
+    // Plano migrado do layout antigo sem `arquivos` ficou em-execucao pela migração, não por alguém executá-lo.
+    const migradoSemArquivos = /^migrado:\s*true\s*$/m.test(frontmatter) && !/^arquivos:[ \t]*(\[[ \t]*[^\]\s]|\r?\n[ \t]*-\s)/m.test(frontmatter);
+    return !migradoSemArquivos;
   });
 }