@pathbit/agentdevkit 0.0.21 → 0.0.23

package/.pbai4devs/COMPATIBILIDADE.md

@@ -45,7 +45,8 @@ representa categorias opcionais; `nome` é o identificador único do recurso.
 Os caminhos são relativos à pasta do cliente, exceto onde indicado.
 
 - Codex: `.agents/skills/grupo/nome/SKILL.md` e referências agrupadas em
-  `.codex`. `AGENTS.md` apresenta o hub; demais tipos são referências.
+  `.codex`. Se a rota principal de uma skill estiver obstruída, ela usa
+  `.codex/skills` como alternativa. `AGENTS.md` apresenta o hub.
 - Claude: `skills/nome/SKILL.md`, `commands/grupo/nome.md`,
   `rules/grupo/nome/RULE.md` e `agents/nome.md`.
 - Cursor: `skills/grupo/nome/SKILL.md`, `rules/grupo/nome.mdc`,
@@ -91,12 +92,21 @@ Prompts `.prompt.md` pertencem ao harness Local do VS Code, anunciado para
 remoção em fevereiro de 2027. No Copilot, use skills para rotinas invocáveis.
 `GEMINI.md` importa `AGENTS.md`; `CLAUDE.md` aponta para esse mesmo guia.
 
+Com Claude e Copilot selecionados, o Copilot CLI pode receber referências
+equivalentes de `.claude/rules` e `.github/instructions`. As duas rotas são
+mantidas para seus respectivos clientes; o suporte a instruções varia entre
+[ambientes do Copilot](https://docs.github.com/en/copilot/reference/custom-instructions-support).
+
 O instalador gera a seleção e a política em `espelhos.conf`; `sincronizar`
 reconstrói os apontamentos somente com Node e os arquivos do hub instalado.
 `--check` não altera arquivos. `--force` faz backup ignorado ao reparar
 conflitos gerenciados. Recursos e links humanos dos clientes são preservados;
 uma rota preservada não recebe apontamentos novos. No Zod, `.codex/skills`
 continua apontando para suas skills e o Codex recebe o kit em `.agents/skills`.
+Quando a rota principal volta a ficar disponível, apontamentos alternativos
+obsoletos só são removidos com propriedade comprovada. Conteúdo humano e o
+índice Git são preservados; se ambas as rotas estiverem obstruídas, a operação
+informa o conflito sem substituí-las.
 
 As fontes confirmam formatos, não execução de cada cliente. Valide descoberta,
 invocação e resultado no cliente escolhido antes de considerar uma integração

package/.pbai4devs/rules/ambiente-local/RULE.md

@@ -27,6 +27,11 @@ O Makefile deve oferecer `help`, `doctor`, `setup`, `up`, `down`, `logs`,
 `test`, `lint` e `build`, com comandos reais da stack. Etapas ainda indefinidas
 devem falhar com mensagem útil; não simule sucesso. Documente os comandos,
 dependências e URL/porta no README; valide Compose e saúde antes de concluir.
+Antes de existir aplicação, valide o runtime, o Compose e os serviços de
+infraestrutura necessários. Build, saúde e fluxo da aplicação inexistente
+permanecem pendentes; não crie código de negócio para simular essas provas. Se
+uma dependência obrigatória estiver indisponível, mantenha a configuração
+pendente e registre o impedimento. Após a implementação, prove a aplicação.
 
 Use o [modelo de ambiente](../../templates/ambiente-local/TEMPLATE.md) para
 perguntas e arquivos-base. Versões da aplicação seguem as decisões do projeto;

package/.pbai4devs/rules/git/RULE.md

@@ -1,10 +1,14 @@
 ---
 trigger: model_decision
-description: Aplique ao preparar, integrar ou publicar alterações Git.
+description: Aplique ao consultar, preparar, integrar ou publicar alterações Git.
 ---
 
 # Regras Git
 
+Em consultas sem alterações, defina `GIT_OPTIONAL_LOCKS=0` no ambiente do
+subprocesso para evitar atualizações opcionais dos bytes do índice. Isso não
+substitui as travas necessárias para operações que alteram o Git.
+
 Use Conventional Commits (`tipo(escopo): descrição`, escopo opcional), inclusive
 em checkpoints e merges; destaque mudanças incompatíveis com `!` ou
 `BREAKING CHANGE:`. Autor e committer devem ser o usuário, nunca um agente;

package/.pbai4devs/scripts/README.md

@@ -26,6 +26,7 @@ node .pbai4devs/scripts/executar-script/SCRIPT.mjs diagnosticar-ambiente
 | --- | --- |
 | `diagnosticar-ambiente` | Runtimes, pacotes e navegadores disponíveis |
 | `inspecionar-projeto` | Detecta manifests, comandos e estrutura |
+| `verificar-configuracao` | Confere o estado antes de implementar código |
 | `preparar-ferramentas` | Instala/atualiza ferramentas locais |
 | `gerenciar-skills-externas` | Instala/check/read de skills curadas locais |
 | `auditar-seguranca` | Scanners offline, bases locais e relatórios redigidos |

package/.pbai4devs/scripts/diagnosticar-ambiente/tests/TEST.mjs

@@ -1,7 +1,9 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { chmodSync, existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { spawnSync } from 'node:child_process';
 import { diagnose } from '../SCRIPT.mjs';
 import { findExecutable, projectRoot, requireNode } from '../../lib/runtime.mjs';
 
@@ -28,3 +30,60 @@ test('requisito comum recusa Node antigo e procura executaveis sem shell', t =>
   assert.equal(findExecutable('fixture', { PATH: dirname(file) }), file);
   assert.equal(findExecutable('missing', { PATH: dirname(file) }), null);
 });
+
+test('isMain reconhece caminho principal por alias sem executar imports como entrada', t => {
+  const output = join(projectRoot, '.agent-tests'); mkdirSync(output, { recursive: true });
+  const root = mkdtempSync(join(output, 'runtime alias espaço-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const real = join(root, 'real'), alias = join(root, 'alias'); mkdirSync(real);
+  try { symlinkSync(real, alias, process.platform === 'win32' ? 'junction' : 'dir'); }
+  catch (error) {
+    if (!['EPERM', 'EACCES'].includes(error.code)) throw error;
+    t.skip('Sistema sem permissão para criar alias de diretório.'); return;
+  }
+  const script = join(real, 'entry.mjs');
+  const runtime = pathToFileURL(join(projectRoot, '.pbai4devs/scripts/lib/runtime.mjs')).href;
+  writeFileSync(script, `import { isMain } from ${JSON.stringify(runtime)};\nconst main = isMain(import.meta.url);\nconsole.log(main ? 'entrada' : 'importado');\nif (main && process.env.ADK_RUNTIME_IMPORT) { const target = process.env.ADK_RUNTIME_IMPORT; delete process.env.ADK_RUNTIME_IMPORT; await import(target); }\n`);
+  const run = (args, extra = {}) => {
+    const env = { ...process.env, ...extra }; if (!Object.hasOwn(extra, 'NODE_OPTIONS')) delete env.NODE_OPTIONS;
+    if (!Object.hasOwn(extra, 'NODE_PRESERVE_SYMLINKS_MAIN')) delete env.NODE_PRESERVE_SYMLINKS_MAIN;
+    if (!Object.hasOwn(extra, 'NODE_PRESERVE_SYMLINKS')) delete env.NODE_PRESERVE_SYMLINKS;
+    const result = spawnSync(process.execPath, args, { encoding: 'utf8', env, timeout: 30000, windowsHide: true });
+    assert.equal(result.status, 0, result.stderr); return result.stdout.trim().split(/\r?\n/);
+  };
+  assert.deepEqual(run([script]), ['entrada']);
+  assert.deepEqual(run([join(alias, 'entry.mjs')]), ['entrada']);
+  const fileAlias = join(root, 'entry-link.mjs');
+  try {
+    symlinkSync(script, fileAlias, 'file');
+    assert.deepEqual(run([fileAlias]), ['entrada']);
+  } catch (error) { if (!['EPERM', 'EACCES'].includes(error.code)) throw error; }
+  const importer = join(root, 'importer.mjs');
+  writeFileSync(importer, `await import(${JSON.stringify(pathToFileURL(join(alias, 'entry.mjs')).href)});\n`);
+  assert.deepEqual(run([importer]), ['importado']);
+  writeFileSync(importer, `await import(${JSON.stringify(pathToFileURL(script).href + '?importado')});\n`);
+  assert.deepEqual(run([importer]), ['importado']);
+  assert.deepEqual(run(['--input-type=module', '-e', `await import(${JSON.stringify(pathToFileURL(script).href)});`, script]), ['importado']);
+  assert.deepEqual(run(['--input-type=module', `--eval=await import(${JSON.stringify(pathToFileURL(script).href)});`, script]), ['importado']);
+  const physical = pathToFileURL(script).href, logical = pathToFileURL(join(alias, 'entry.mjs')).href;
+  assert.deepEqual(run(['--preserve-symlinks-main', join(alias, 'entry.mjs')], { ADK_RUNTIME_IMPORT: physical }), ['entrada', 'importado']);
+  assert.deepEqual(run(['--preserve-symlinks-main=false', join(alias, 'entry.mjs')], { ADK_RUNTIME_IMPORT: physical }), ['entrada', 'importado']);
+  assert.deepEqual(run(['--preserve-symlinks-main=ignored', join(alias, 'entry.mjs')], { ADK_RUNTIME_IMPORT: physical }), ['entrada', 'importado']);
+  assert.deepEqual(run(['--preserve-symlinks', script], { ADK_RUNTIME_IMPORT: logical }), ['entrada', 'importado']);
+  assert.deepEqual(run(['--preserve-symlinks', join(alias, 'entry.mjs')], { ADK_RUNTIME_IMPORT: logical }), ['entrada', 'importado']);
+  assert.deepEqual(run([join(alias, 'entry.mjs')], { NODE_OPTIONS: '--preserve-symlinks', ADK_RUNTIME_IMPORT: logical }), ['entrada', 'importado']);
+  assert.deepEqual(run([join(alias, 'entry.mjs')], { NODE_OPTIONS: '--preserve-symlinks-main', ADK_RUNTIME_IMPORT: physical }), ['entrada', 'importado']);
+  assert.deepEqual(run(['--no-preserve-symlinks-main', join(alias, 'entry.mjs')], { NODE_OPTIONS: '--preserve-symlinks-main' }), ['entrada']);
+  assert.deepEqual(run([join(alias, 'entry.mjs')], { NODE_PRESERVE_SYMLINKS_MAIN: '1', ADK_RUNTIME_IMPORT: physical }), ['entrada', 'importado']);
+  assert.deepEqual(run(['--no-preserve-symlinks-main', join(alias, 'entry.mjs')], { NODE_PRESERVE_SYMLINKS_MAIN: '1' }), ['entrada']);
+  const positiveText = join(root, 'preload --preserve-symlinks-main');
+  const negativeText = join(root, 'preload --no-preserve-symlinks-main');
+  for (const file of [positiveText, negativeText]) writeFileSync(file, '// preload sem efeitos\n');
+  assert.deepEqual(run(['--require', positiveText, join(alias, 'entry.mjs')]), ['entrada']);
+  assert.deepEqual(run([join(alias, 'entry.mjs')], { NODE_OPTIONS: `--require ${JSON.stringify(positiveText)}` }), ['entrada']);
+  assert.deepEqual(run(['--preserve-symlinks-main', '--require', negativeText, join(alias, 'entry.mjs')], { ADK_RUNTIME_IMPORT: physical }), ['entrada', 'importado']);
+  assert.deepEqual(run([join(alias, 'entry.mjs')], { NODE_OPTIONS: `--preserve-symlinks-main --require ${JSON.stringify(negativeText)}`, ADK_RUNTIME_IMPORT: physical }), ['entrada', 'importado']);
+  const toolAlias = join(root, 'tool');
+  symlinkSync(join(projectRoot, '.pbai4devs/scripts/gerenciar-skills-externas'), toolAlias, process.platform === 'win32' ? 'junction' : 'dir');
+  assert.match(run([join(toolAlias, 'SCRIPT.mjs'), '--help']).join('\n'), /Uso:/);
+});

package/.pbai4devs/scripts/inspecionar-projeto/README.md

@@ -12,6 +12,10 @@ O JSON identifica tecnologia, comandos, estrutura e documentos existentes.
 `documentation.files` mantém caminhos e caixa, papel provável, tamanho e hash
 quando a leitura couber nos limites. Referências válidas do estado aparecem em
 `configured`; nomes sugerem papéis, mas não comprovam conteúdo ou aprovação.
+Na maturidade, o roadmap e as specs são consultados nos caminhos configurados;
+status são declarações e um vínculo local não comprova aprovação ou revisão.
+Uma lista de specs ambígua ou incompleta não autoriza escolher um incremento;
+o estado do vínculo no roadmap também é apenas uma indicação para consulta.
 
 Links simbólicos são listados como opacos, sem ler seus destinos. Conteúdo dos
 documentos e valores de configuração não aparecem no relatório. `scan` e
@@ -20,6 +24,8 @@ condições. Uma pasta simbólica como `docs` também aparece, sem presumir que
 esteja vazia. Links não classificados recebem `role: unclassified`; enquanto
 existir uma fronteira não inspecionada, `scan.complete` será falso. Não use
 inventário incompleto como prova de ausência de documentos.
+O inspetor revalida a identidade dos caminhos durante a leitura; isso detecta
+mudanças, mas não é uma garantia atômica contra toda troca simultânea.
 
 `exclusions` descreve pastas de clientes, artefatos e caches fora do inventário.
 Documentos humanos em `.github`, exemplos, wiki e RFCs são incluídos; os

package/.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs

@@ -41,12 +41,69 @@ const present = (root, name, directory) => {
 const inside = candidate => { const relative = path.relative(repository, candidate); return relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative); };
 const fixturePath = candidate => /^(?:\.agent-tests\/|tmp\/examples\/|examples\/generated\/)/.test(normalize(path.relative(repository, candidate)));
 
+// Rechecking is a conservative race detection, not an atomic openat traversal.
+function pathIdentity(root, file = '') {
+  try {
+    let current = root; const result = [], parts = file ? file.split('/') : [];
+    for (const [index, part] of ['', ...parts].entries()) {
+      if (part) current = path.join(current, part);
+      const item = fs.lstatSync(current);
+      if (item.isSymbolicLink() || (index < parts.length && !item.isDirectory())) return null;
+      result.push({ dev: item.dev, ino: item.ino, mode: item.mode, size: item.size, directory: item.isDirectory() });
+    }
+    return result;
+  } catch { return null; }
+}
+const sameIdentity = (left, right) => left && right && left.length === right.length
+  && left.every((item, index) => item.dev === right[index].dev && item.ino === right[index].ino && item.mode === right[index].mode);
+
+function boundedEntries(folder, limit, verify = () => true) {
+  const handle = fs.opendirSync(folder), entries = [];
+  try {
+    if (!verify()) return { entries: [], truncated: true, changed: true };
+    while (true) {
+      const entry = handle.readSync();
+      if (!entry) return verify() ? { entries, truncated: false } : { entries: [], truncated: true, changed: true };
+      if (entries.length >= limit) return verify() ? { entries, truncated: true } : { entries: [], truncated: true, changed: true };
+      entries.push(entry);
+    }
+  } finally { handle.closeSync(); }
+}
+
+function stableDirectory(root, directory, limit) {
+  const identity = pathIdentity(root, directory);
+  if (!identity?.at(-1).directory) return { entries: [], truncated: true, changed: true, verify: () => false };
+  const verify = () => sameIdentity(identity, pathIdentity(root, directory));
+  return { ...boundedEntries(path.join(root, directory), limit, verify), verify };
+}
+
 function metadata(root, file) {
-  if (!present(root, file, false) || fs.statSync(path.join(root, file)).size > 1024 * 1024) return { fields: {}, documents: {} };
-  const text = fs.readFileSync(path.join(root, file), 'utf8').replaceAll('\r', '');
+  const empty = { fields: {}, documents: {}, text: null };
+  const identity = () => pathIdentity(root, file);
+  let descriptor, text;
+  try {
+    const name = path.join(root, file), ancestors = identity();
+    if (!ancestors || !sameIdentity(ancestors, identity())) return empty;
+    const before = ancestors.at(-1);
+    if (before.size > 1024 * 1024) return empty;
+    descriptor = fs.openSync(name, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const opened = fs.fstatSync(descriptor);
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== before.size || !sameIdentity(ancestors, identity())) return empty;
+    const buffer = Buffer.alloc(opened.size + 1); let length = 0;
+    while (length < buffer.length) {
+      const count = fs.readSync(descriptor, buffer, length, buffer.length - length, length);
+      if (!count) break;
+      length += count;
+    }
+    const after = fs.fstatSync(descriptor);
+    if (length !== opened.size || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs || !sameIdentity(ancestors, identity())) return empty;
+    text = buffer.subarray(0, length).toString('utf8').replaceAll('\r', '');
+  } catch { return empty; }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
   const header = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1];
-  const result = { fields: {}, documents: {} }; if (!header) return result;
-  let documents = false;
+  const result = { fields: {}, documents: {}, text }; if (!header) return result;
+  let documents = false, invalidDocuments = false;
+  const seen = new Set(), duplicates = new Set(), seenDocuments = new Set(), duplicateDocuments = new Set();
   const scalar = raw => {
     const value = raw.trim();
     if (!value || ['null', '~'].includes(value)) return null;
@@ -54,16 +111,131 @@ function metadata(root, file) {
     return value.startsWith("'") && value.endsWith("'") ? value.slice(1, -1).replaceAll("''", "'") : value;
   };
   for (const line of header.split('\n')) {
-    const top = line.match(/^([a-z_]+):\s*(.*)$/);
-    if (top) { documents = top[1] === 'documentos'; result.fields[top[1]] = scalar(top[2]); }
-    else if (documents) { const item = line.match(/^  ([a-z_]+):\s*(.*)$/); if (item) result.documents[item[1]] = scalar(item[2]); }
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const top = line.match(/^(?:([\p{L}_][\p{L}\p{N}_.-]*)|"([^"\n]+)"|'([^'\n]+)'):\s*(.*)$/u);
+    if (top) {
+      const key = top[1] || top[2] || top[3];
+      if (key.includes('\\')) return { ...empty, text };
+      if (seen.has(key)) duplicates.add(key);
+      seen.add(key); result.fields[key] = duplicates.has(key) ? null : scalar(top[4]);
+      if (key === 'documentos' && duplicates.has(key)) { invalidDocuments = true; result.documents = {}; }
+      documents = key === 'documentos' && !invalidDocuments && (!top[4].trim() || ['null', '~'].includes(top[4].trim()));
+    } else if (!/^\s/.test(line)) return { ...empty, text };
+    else if (documents) {
+      const item = line.match(/^  (?:([\p{L}_][\p{L}\p{N}_.-]*)|"([^"\n]+)"|'([^'\n]+)'):\s*(.*)$/u);
+      if (item) {
+        const key = item[1] || item[2] || item[3];
+        if (key.includes('\\')) { invalidDocuments = true; result.documents = {}; documents = false; continue; }
+        if (seenDocuments.has(key)) duplicateDocuments.add(key);
+        seenDocuments.add(key); result.documents[key] = duplicateDocuments.has(key) ? null : scalar(item[4]);
+      } else if (/^  \S/.test(line)) { invalidDocuments = true; result.documents = {}; documents = false; }
+    }
   }
   return result;
 }
 
+// The configured specs directory contains <slug>/SPEC.md. Refuse ambiguous
+// layouts instead of guessing which increment or declared status to use.
+function configuredSpecs(root, directory) {
+  const result = { path: directory, present: false, complete: false, items: [] };
+  if (!directory) return result;
+  let current = root;
+  for (const component of directory.split('/')) {
+    current = path.join(current, component);
+    try {
+      const info = fs.lstatSync(current);
+      if (info.isSymbolicLink() || !info.isDirectory()) return result;
+    } catch (error) {
+      if (error.code === 'ENOENT') result.complete = true;
+      return result;
+    }
+  }
+  result.present = true;
+  const incomplete = () => { result.items = []; return result; };
+  let scanned = 0;
+  function entriesAt(folder) {
+    const relative = normalize(path.relative(root, folder));
+    const result = stableDirectory(root, relative, Math.min(200, 500 - scanned));
+    scanned += result.entries.length;
+    return result.truncated ? null : result.entries;
+  }
+  try {
+    const entries = entriesAt(current);
+    if (!entries) return incomplete();
+    for (const entry of entries) {
+      if (/^readme(?:\.md)?$/i.test(entry.name) && !entry.isSymbolicLink()) continue;
+      if (['.git', '.pbai4devs', '.agent-tests', 'node_modules'].includes(entry.name.toLowerCase())) return incomplete();
+      if (!entry.isDirectory() || entry.isSymbolicLink()) return incomplete();
+      const folder = `${directory}/${entry.name}`;
+      if (!present(root, folder, true)) return incomplete();
+      const children = entriesAt(path.join(root, folder));
+      if (!children) return incomplete();
+      const names = children.filter(item => /^spec\.md$/i.test(item.name));
+      if (names.length !== 1 || !names[0].isFile() || names[0].isSymbolicLink()) return incomplete();
+      const file = `${folder}/${names[0].name}`;
+      if (!present(root, file, false)) return incomplete();
+      const document = metadata(root, file);
+      if (document.text === null) return incomplete();
+      result.items.push({ path: file, status: ['rascunho', 'pendente', 'aprovado'].includes(document.fields.status) ? document.fields.status : null });
+      if (result.items.length > 1) return incomplete();
+    }
+    if (!present(root, directory, true)) return incomplete();
+    result.complete = true;
+  } catch { return incomplete(); }
+  return result;
+}
+
+function referenceState(roadmap, roadmapFile, specFile) {
+  if (!roadmap || !roadmapFile) return { linked: false, roadmapState: 'unknown' };
+  // Examples and orphan reference definitions do not select an increment.
+  const lines = []; let fence = null;
+  const body = roadmap.replace(/^---\n[^]*?\n---(?:\n|$)/, '').replace(/<!--[^]*?-->/g, '');
+  for (const line of body.split('\n')) {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !line.slice(marker[0].length).trim()) fence = null;
+    } else if (marker) fence = marker[1];
+    else lines.push(line.replace(/(`+)[^`\n]*?\1/g, ''));
+  }
+  const normalizeLabel = label => label.trim().replace(/\s+/g, ' ').toLowerCase();
+  const definitions = new Map();
+  for (const line of lines) {
+    const match = line.match(/^ {0,3}\[([^\]]+)\]:[ \t]*(?:<([^>\n]+)>|(\S+))(?:[ \t]+(?:"[^"\n]*"|'[^'\n]*'))?[ \t]*$/);
+    if (match) { const label = normalizeLabel(match[1]); definitions.set(label, [...(definitions.get(label) || []), match[2] || match[3]]); }
+  }
+  const references = [], ancestry = [];
+  for (const line of lines) {
+    const list = line.match(/^([ \t]*)(?:[-+*]|\d+[.)])\s+(.*)$/);
+    const marker = list?.[2].match(/^\[([ xX-])\](?:\s|$)/);
+    const closed = /(?:^|[^\p{L}])(?:cancelad[ao]s?|conclu[ií]d[ao]s?|publicad[ao]s?|finalizad[ao]s?|descartad[ao]s?|cancelled|completed|published)(?=$|[^\p{L}])/iu.test(line);
+    let state = 'unknown';
+    if (list) {
+      const indent = list[1].length;
+      while (ancestry.length && ancestry.at(-1).indent >= indent) ancestry.pop();
+      const own = closed || marker && /x/i.test(marker[1]) ? 'closed' : marker?.[1] === ' ' ? 'open' : marker?.[1] === '-' ? 'in-progress' : 'unknown';
+      state = ancestry.some(item => item.state === 'closed') ? 'closed' : /\t/.test(list[1]) || ancestry.some(item => item.state === 'unknown') ? 'unknown' : own;
+      ancestry.push({ indent, state });
+    } else if (line.trim() && !/^\s/.test(line)) ancestry.length = 0;
+    for (const match of line.matchAll(/(?<![!\\])\[[^\]\n]+\]\(\s*(?:<([^>\n]+)>|([^\s)]+))(?:\s+(?:"[^"\n]*"|'[^'\n]*'))?\s*\)/g)) references.push({ destination: match[1] || match[2], state });
+    for (const match of line.matchAll(/(?<![!\\])\[([^\]\n]+)\]\[([^\]\n]*)\]/g)) {
+      const label = normalizeLabel(match[2] || match[1]);
+      if (definitions.get(label)?.length === 1) references.push({ destination: definitions.get(label)[0], state });
+    }
+  }
+  const matches = references.filter(({ destination }) => {
+    try {
+      const value = decodeURIComponent(destination).split(/[?#]/, 1)[0];
+      if (!value || /^(?:[a-z][a-z0-9+.-]*:|\/|\\)/i.test(value) || value.includes('\\')) return false;
+      return path.posix.resolve('/', path.posix.dirname(roadmapFile), value) === '/' + specFile;
+    } catch { return false; }
+  });
+  if (matches.length !== 1) return { linked: matches.length > 0, roadmapState: matches.length ? 'ambiguous' : 'unknown' };
+  return { linked: true, roadmapState: matches[0].state };
+}
+
 function maturity(root, report) {
   const stateFile = `${stateDirectory(root)}/configuracao/ESTADO.md`; const state = metadata(root, stateFile);
-  const safeDocument = value => typeof value === 'string' && !path.isAbsolute(value) && !value.includes('\\') && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
+  const safeDocument = value => typeof value === 'string' && !path.isAbsolute(value) && !/[\\\x00-\x1f\x7f:]/.test(value) && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part.toLowerCase()));
   const planning = {};
   for (const name of ['prd', 'ux_ui', 'design']) {
     const file = state.documents[name];
@@ -72,10 +244,22 @@ function maturity(root, report) {
     planning[name] = { path: safeDocument(file) ? file : null, present: Boolean(exists), status: ['rascunho', 'aprovado', 'nao-aplicavel', 'pendente'].includes(status) ? status : null };
   }
   planning.ready = planning.prd.status === 'aprovado' && planning.design.status === 'aprovado' && ['aprovado', 'nao-aplicavel'].includes(planning.ux_ui.status);
-  let released = false; const releases = state.documents.releases;
+  const roadmapPath = safeDocument(state.documents.roadmap) && /\.md$/i.test(state.documents.roadmap) ? state.documents.roadmap : null;
+  const roadmapPresent = Boolean(roadmapPath && present(root, roadmapPath, false));
+  const roadmapDocument = roadmapPresent ? metadata(root, roadmapPath) : { fields: {}, text: null };
+  planning.roadmap = { path: roadmapPath, present: roadmapPresent, status: ['pendente', 'rascunho', 'planejado', 'aprovado'].includes(roadmapDocument.fields.status) ? roadmapDocument.fields.status : null };
+  const specsPath = safeDocument(state.documents.specs) ? state.documents.specs : null;
+  planning.specs = configuredSpecs(root, specsPath);
+  for (const spec of planning.specs.items) Object.assign(spec, referenceState(roadmapDocument.text, roadmapPath, spec.path));
+  let released = false, releasesComplete = true; const releases = state.documents.releases;
   if (safeDocument(releases) && present(root, releases, true)) {
     const visit = (directory, depth = 0) => {
-      for (const entry of fs.readdirSync(path.join(root, directory), { withFileTypes: true }).slice(0, 100)) {
+      let listing;
+      try { listing = stableDirectory(root, directory, 100); }
+      catch { releasesComplete = false; return; }
+      if (listing.truncated) releasesComplete = false;
+      for (const entry of listing.entries) {
+        if (!listing.verify()) { releasesComplete = false; return; }
         const file = normalize(path.join(directory, entry.name));
         if (entry.isSymbolicLink()) continue;
         if (entry.isDirectory() && depth < 2) visit(file, depth + 1);
@@ -91,7 +275,7 @@ function maturity(root, report) {
   if (planning.ready) level = 'planejado';
   if (report.mode === 'aplicacao-detectada') level = 'implementacao';
   if (report.mode === 'aplicacao-detectada' && planning.ready && report.contract.complete && configuration.configuracao_tecnica === 'concluido') level = released ? 'manutencao' : 'configurado';
-  return { level, planning, configuration, released, signals: { application: report.mode === 'aplicacao-detectada', structure: report.contract.complete }, limits: ['Classificacao descritiva; status em arquivos nao substitui aprovacao, testes ou provas de funcionamento.'] };
+  return { level, planning, configuration, released, releasesComplete, signals: { application: report.mode === 'aplicacao-detectada', structure: report.contract.complete }, limits: ['Classificacao descritiva; status em arquivos nao substitui aprovacao, testes ou provas de funcionamento.'] };
 }
 
 const documentRoles = new Set(['readme', 'contribuicao', 'changelog', 'seguranca', 'adrs', 'prd', 'ux_ui', 'design', 'roadmap', 'releases', 'specs', 'tarefas']);
@@ -152,10 +336,12 @@ export function inspectDocumentation(root, limits = {}) {
     }
     let descriptor;
     try {
+      const identity = pathIdentity(root, file);
+      if (!identity || !sameIdentity(identity, pathIdentity(root, file))) { warn(file, 'changed-during-read'); return; }
       descriptor = fs.openSync(path.join(root, file), fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
       const before = fs.fstatSync(descriptor);
       if (!before.isFile() || before.dev !== expected.dev || before.ino !== expected.ino || before.size !== expected.size
-        || before.mtimeMs !== expected.mtimeMs || before.ctimeMs !== expected.ctimeMs) { warn(file, 'changed-during-read'); return; }
+        || before.mtimeMs !== expected.mtimeMs || before.ctimeMs !== expected.ctimeMs || !sameIdentity(identity, pathIdentity(root, file))) { warn(file, 'changed-during-read'); return; }
       const buffer = Buffer.alloc(Math.min(before.size + 1, bounds.maxTotalBytes - scan.bytesRead));
       let length = 0;
       while (length < buffer.length) {
@@ -165,7 +351,7 @@ export function inspectDocumentation(root, limits = {}) {
         scan.bytesRead += read;
       }
       const after = fs.fstatSync(descriptor);
-      if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
+      if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || !sameIdentity(identity, pathIdentity(root, file))) {
         warn(file, 'changed-during-read'); return;
       }
       scan.bytesHashed += length;
@@ -194,8 +380,13 @@ export function inspectDocumentation(root, limits = {}) {
       const found = locate(directory);
       if (found.kind !== 'directory') { if (found.kind === 'symbolic-link') add(found.boundary, found, role); return; }
     }
-    let children;
-    try { children = fs.readdirSync(path.join(root, directory), { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0); }
+    let children, listing;
+    try {
+      listing = stableDirectory(root, directory, Math.max(0, bounds.maxEntries - scan.entries));
+      if (listing.changed) { scan.truncated = true; warn(directory || '.', 'changed-during-read'); return; }
+      if (listing.truncated) scan.truncated = true;
+      children = listing.entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+    }
     catch { warn(directory || '.', 'unreadable-directory'); return; }
     // Discard a listing if the directory became a link while being inspected.
     if (directory && locate(directory).kind !== 'directory') { warn(directory, 'changed-during-read'); return; }
@@ -204,6 +395,7 @@ export function inspectDocumentation(root, limits = {}) {
       scan.entries++;
       const file = directory ? `${directory}/${child.name}` : child.name;
       if (excludedDocument(file)) continue;
+      if (!listing.verify()) { scan.truncated = true; warn(directory || '.', 'changed-during-read'); return; }
       const found = locate(file);
       if (found.kind === 'directory') {
         if (depth < bounds.maxDepth) walk(file, depth + 1, role);
@@ -244,8 +436,11 @@ export function inspectProject(root = repository, { check = false, documentation
   const warning = (file, reason) => report.warnings.push({ file, reason });
   function commands(file, name) {
     if (!['package.json', 'composer.json', 'deno.json', 'deno.jsonc', 'Makefile', 'makefile', 'GNUmakefile', 'pyproject.toml'].includes(name)) return;
-    if (fs.statSync(path.join(root, file)).size > 1024 * 1024) { warning(file, 'manifest-grande-demais'); return; }
-    const text = fs.readFileSync(path.join(root, file), 'utf8');
+    const identity = pathIdentity(root, file);
+    if (!identity) { warning(file, 'manifest-nao-inspecionado'); return; }
+    if (identity.at(-1).size > 1024 * 1024) { warning(file, 'manifest-grande-demais'); return; }
+    const text = metadata(root, file).text;
+    if (text === null) { warning(file, 'manifest-nao-inspecionado'); return; }
     let names = [];
     try {
       if (['package.json', 'composer.json', 'deno.json', 'deno.jsonc'].includes(name)) {
@@ -268,7 +463,10 @@ export function inspectProject(root = repository, { check = false, documentation
     } catch { warning(file, 'manifest-nao-interpretado'); }
   }
   function walk(directory = '', depth = 0) {
-    const children = fs.readdirSync(path.join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    const listing = stableDirectory(root, directory, Math.max(0, 25000 - entries));
+    if (listing.changed) { report.scan.truncated = true; warning(directory || '.', 'changed-during-read'); return; }
+    if (listing.truncated) report.scan.truncated = true;
+    const children = listing.entries.sort((a, b) => a.name.localeCompare(b.name));
     for (const item of children) {
       if (++entries > 25000) { report.scan.truncated = true; return; }
       const file = normalize(path.join(directory, item.name));
@@ -276,10 +474,12 @@ export function inspectProject(root = repository, { check = false, documentation
       if (item.isSymbolicLink()) continue;
       if (item.isDirectory()) {
         if (excluded.has(item.name) || excluded.has(item.name.toLowerCase()) || /^\.?playwright/i.test(item.name)) continue;
+        if (!listing.verify()) { report.scan.truncated = true; warning(directory || '.', 'changed-during-read'); return; }
         if (depth < report.scan.maxDepth) walk(file, depth + 1); else report.scan.truncated = true;
         continue;
       }
       if (!item.isFile()) continue;
+      if (!listing.verify()) { report.scan.truncated = true; warning(directory || '.', 'changed-during-read'); return; }
       let language = manifests.get(item.name);
       if (/\.(?:csproj|fsproj|vbproj|sln)$/.test(item.name)) language = 'dotnet';
       if (/^requirements(?:[.-][A-Za-z0-9_-]+)?\.txt$/.test(item.name)) language = 'python';

package/.pbai4devs/scripts/lib/adapters.mjs

@@ -6,15 +6,16 @@ import { isGeneratedOutput } from './gitignore.mjs';
 
 const policy = JSON.parse(readFileSync(new URL('../../templates/clients/ADAPTERS.json', import.meta.url), 'utf8'));
 const kinds = new Set(['skills', 'agents', 'commands', 'rules']);
-const layouts = new Set(['agrupado', 'plano', 'arquivo', 'mdc', 'agente', 'prompt', 'instrucoes']);
+const layouts = new Set(['agrupado', 'plano', 'arquivo', 'mdc', 'agente', 'prompt', 'instrucoes', 'nenhum']);
 const entryNames = new Set(['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']);
 const safeRoot = value => typeof value === 'string' && /^\.[a-z0-9][a-z0-9-]*$/.test(value) && !['.git', '.pbai4devs', '.agent-tests'].includes(value);
 const stringList = value => Array.isArray(value) && value.every(item => typeof item === 'string');
 if (policy.schemaVersion !== 1 || !Array.isArray(policy.adapters) || !policy.adapters.length || !stringList(policy.entrypoints) || policy.entrypoints.some(name => !entryNames.has(name))) throw new Error('Politica de clientes invalida.');
 const ids = new Set(), roots = new Set(), aliases = {};
 for (const adapter of policy.adapters) {
-  if (!adapter || typeof adapter.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(adapter.id) || adapter.id === 'all' || ids.has(adapter.id) || typeof adapter.name !== 'string' || !safeRoot(adapter.root) || roots.has(adapter.root) || !adapter.formats || Object.entries(adapter.formats).some(([kind, layout]) => !kinds.has(kind) || !layouts.has(layout))) throw new Error('Adaptador invalido.');
+  if (!adapter || typeof adapter.id !== 'string' || !/^[a-z][a-z0-9-]*$/.test(adapter.id) || adapter.id === 'all' || ids.has(adapter.id) || typeof adapter.name !== 'string' || !safeRoot(adapter.root) || roots.has(adapter.root) || !adapter.formats || Object.entries(adapter.formats).some(([kind, layout]) => !kinds.has(kind) || !layouts.has(layout) || layout === 'nenhum' && kind !== 'skills')) throw new Error('Adaptador invalido.');
   if (/[\r\n]/.test(adapter.name) || typeof adapter.reason !== 'string' || /[\r\n]/.test(adapter.reason) || (adapter.discovery !== undefined && adapter.discovery !== 'antigravity')) throw new Error('Descricao ou descoberta de adaptador invalida.');
+  if (adapter.skillFallback !== undefined && (!safeRoot(adapter.skillFallback) || adapter.skillFallback === adapter.root || adapter.formats.skills !== 'nenhum')) throw new Error('Fallback de skills invalido.');
   for (const field of ['aliases', 'requires', 'extraRoots', 'entrypoints', 'sources']) if (!stringList(adapter[field])) throw new Error('Lista invalida no adaptador: ' + field);
   if (adapter.extraRoots.some(root => !safeRoot(root)) || adapter.entrypoints.some(name => !entryNames.has(name)) || adapter.sources.some(url => !url.startsWith('https://'))) throw new Error('Caminho ou fonte invalida no adaptador.');
   for (const field of ['agentMetadata', 'ruleMetadata']) if (adapter[field] !== undefined && !/^[a-z0-9-]+\.ya?ml$/.test(adapter[field])) throw new Error('Metadados invalidos no adaptador.');
@@ -22,6 +23,7 @@ for (const adapter of policy.adapters) {
 }
 for (const adapter of policy.adapters) {
   if (adapter.requires.some(id => !ids.has(id))) throw new Error('Dependencia de adaptador desconhecida.');
+  if (adapter.skillFallback && !policy.adapters.some(other => other.root === adapter.skillFallback && adapter.requires.includes(other.id))) throw new Error('Fallback exige cliente de origem.');
   for (const alias of adapter.aliases) {
     if (!/^[a-z][a-z0-9-]*$/.test(alias) || ids.has(alias) || alias === 'all' || Object.hasOwn(aliases, alias)) throw new Error('Alias de adaptador invalido.');
     aliases[alias] = adapter.id;
@@ -102,6 +104,7 @@ export function adapterManifest(root, { clients } = {}) {
   for (const adapter of selection.adapters) {
     rows.push(`# ${adapter.id}: ${adapter.reason}`, `agente|${adapter.root}|agrupado`);
     for (const [kind, mode] of Object.entries(adapter.formats)) rows.push(`formato|${adapter.root}|${kind}|${mode}`);
+    if (adapter.skillFallback) rows.push(`fallback|${adapter.root}|${adapter.skillFallback}|skills`);
     if (adapter.discovery) rows.push(`descoberta|${adapter.root}|${adapter.discovery}`);
     for (const [kind, key] of [['agents', 'agentMetadata'], ['rules', 'ruleMetadata']]) {
       if (!adapter[key]) continue;

package/.pbai4devs/scripts/lib/runtime.mjs

@@ -1,6 +1,6 @@
 import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { accessSync, constants, statSync } from 'node:fs';
+import { accessSync, constants, realpathSync, statSync } from 'node:fs';
 
 export const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
 
@@ -10,8 +10,44 @@ export function requireNode(minimum = 24, version = process.versions.node) {
   }
 }
 
+// NODE_OPTIONS uses Node's double-quoted token syntax, not shell quoting.
+// Keep option values as a single token so text in a preload path is not a flag.
+function nodeOptionTokens(value) {
+  const result = []; let token = '', quoted = false, escaped = false, active = false;
+  for (const character of value) {
+    if (escaped) { token += character; escaped = false; active = true; }
+    else if (character === '\\' && quoted) escaped = true;
+    else if (character === '"') { quoted = !quoted; active = true; }
+    else if (character === ' ' && !quoted) { if (active) result.push(token); token = ''; active = false; }
+    else { token += character; active = true; }
+  }
+  if (escaped) token += '\\';
+  if (active) result.push(token);
+  return result;
+}
+
+function preserveMainSymlinks() {
+  let preserved = process.env.NODE_PRESERVE_SYMLINKS_MAIN === '1';
+  for (const tokens of [nodeOptionTokens(process.env.NODE_OPTIONS || ''), process.execArgv]) {
+    for (const token of tokens) {
+      if (/^--preserve-symlinks-main(?:=.*)?$/.test(token)) preserved = true;
+      else if (/^--no-preserve-symlinks-main(?:=.*)?$/.test(token)) preserved = false;
+    }
+  }
+  return preserved;
+}
+
 export function isMain(metaUrl) {
-  return Boolean(process.argv[1]) && metaUrl === pathToFileURL(resolve(process.argv[1])).href;
+  if (!process.argv[1] || typeof metaUrl !== 'string') return false;
+  // In eval/print mode argv[1] is a user argument, not the entry module.
+  if (process.execArgv.some(arg => /^-(?:e|p|ep|pe)$/.test(arg) || /^--(?:eval|print)(?:=|$)/.test(arg))) return false;
+  const entry = resolve(process.argv[1]);
+  // Only --preserve-symlinks-main keeps the main URL logical. The separate
+  // --preserve-symlinks option can preserve an imported alias while the main
+  // URL is physical, so comparing both paths would execute that import twice.
+  if (preserveMainSymlinks()) return metaUrl === pathToFileURL(entry).href;
+  try { return metaUrl === pathToFileURL(realpathSync(entry)).href; }
+  catch { return false; }
 }
 
 export function findExecutable(name, environment = process.env, platform = process.platform) {

package/.pbai4devs/scripts/sincronizar-agentes/README.md

@@ -29,7 +29,9 @@ catálogo; resultados, caches e pastas temporárias não entram nos índices.
 `formato|pasta|tipo|formato` e registrar `descoberta|.agents|antigravity`.
 `agrupado` preserva a árvore; `plano` retira categorias; `arquivo` preserva
 categorias e usa `nome.md`. `mdc`, `instrucoes`, `prompt` e `agente` produzem as
-extensões nativas. A descoberta gera os três manifestos JSON do Antigravity.
+extensões nativas; `nenhum` desativa a derivação de skills naquela rota.
+`fallback|destino|origem|skills` usa o destino para cada skill cuja rota de
+origem estiver obstruída. A descoberta gera os três manifestos JSON do Antigravity.
 Veja os motivos e limites em [Compatibilidade](../../COMPATIBILIDADE.md).
 
 Sem manifesto, o sincronizador gera a política de
@@ -49,3 +51,5 @@ atualizar arquivos gerados e blocos separadamente, preservando alterações huma
 Apontamentos obsoletos podem ser removidos quando a propriedade é comprovada;
 arquivos e pastas próprios, inclusive os adicionais dentro do mesmo recurso,
 devem permanecer.
+O estado derivado registra remoções comprovadas para reconciliá-las no próximo
+`update`; campos adicionais existentes no estado são preservados.