@pathbit/agentdevkit 0.0.21 → 0.0.22

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/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/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.

package/.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs

@@ -21,7 +21,7 @@ const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'state',
 const reserved = new Set(['.git', '.pbai4devs', '.agent-tests']);
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const sorted = values => [...new Set(values)].sort(compare);
-const layouts = new Set(['agrupado', 'plano', 'arquivo', 'mdc', 'instrucoes', 'prompt', 'agente']);
+const layouts = new Set(['agrupado', 'plano', 'arquivo', 'mdc', 'instrucoes', 'prompt', 'agente', 'nenhum']);
 const fail = message => { throw new Error(message); };
 const normalize = text => text.replace(/\r\n?/g, '\n');
 const read = file => normalize(readFileSync(file, 'utf8'));
@@ -30,6 +30,77 @@ const stat = file => {
   catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; }
 };
 
+function replaceJsonMember(bytes, member, value) {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text, 'utf8').equals(bytes)) fail('Invalid UTF-8 in derived state.');
+  let i = 0;
+  const space = () => { while (/\s/.test(text[i] || '') && i < text.length) i++; };
+  const stringEnd = () => {
+    if (text[i++] !== '"') fail('Invalid JSON member.');
+    while (i < text.length) {
+      const char = text[i++];
+      if (char === '\\') { i++; continue; }
+      if (char === '"') return;
+    }
+    fail('Unterminated JSON string.');
+  };
+  space(); if (text[i++] !== '{') fail('Invalid derived state.');
+  const properties = [];
+  while (true) {
+    space(); if (text[i] === '}') break;
+    const start = i; stringEnd(); const key = JSON.parse(text.slice(start, i));
+    space(); if (text[i++] !== ':') fail('Invalid JSON member.');
+    space(); const valueStart = i;
+    if (text[i] === '"') stringEnd();
+    else if (text[i] === '{' || text[i] === '[') {
+      const stack = [];
+      do {
+        const char = text[i];
+        if (char === '"') { stringEnd(); continue; }
+        i++;
+        if (char === '{' || char === '[') stack.push(char);
+        else if (char === '}' || char === ']') stack.pop();
+      } while (stack.length && i < text.length);
+      if (stack.length) fail('Invalid derived state.');
+    } else { while (i < text.length && text[i] !== ',' && text[i] !== '}') i++; while (i > valueStart && /\s/.test(text[i - 1])) i--; }
+    const end = i; properties.push({ key, start, valueStart, end });
+    space(); if (text[i] === ',') { i++; continue; } if (text[i] === '}') break;
+    fail('Invalid JSON member separator.');
+  }
+  const matches = properties.filter(item => item.key === member);
+  if (matches.length > 1) fail('Ambiguous derived state member.');
+  if (!matches.length) {
+    if (value === undefined) return bytes;
+    const insertion = `${properties.length ? ',' : ''}\n  ${JSON.stringify(member)}: ${JSON.stringify(value, null, 2)}\n`;
+    const next = text.slice(0, i) + insertion + text.slice(i);
+    try { JSON.parse(next); } catch { fail('Unable to preserve derived state safely.'); }
+    return Buffer.from(next);
+  }
+  const current = matches[0], index = properties.indexOf(current);
+  let next;
+  if (value !== undefined) next = text.slice(0, current.valueStart) + JSON.stringify(value, null, 2) + text.slice(current.end);
+  else if (index > 0) next = text.slice(0, properties[index - 1].end) + text.slice(current.end);
+  else if (properties.length > 1) next = text.slice(0, current.start) + text.slice(properties[1].start);
+  else next = text.slice(0, current.start) + text.slice(current.end);
+  try { JSON.parse(next); } catch { fail('Unable to preserve derived state safely.'); }
+  return Buffer.from(next);
+}
+
+
+// Compare owned fields structurally, preserving all other JSON bytes.
+function derivedContent(original, previous, next) {
+  if (!original) return JSON.stringify(next, null, 2) + '\n';
+  const keys = ['schemaVersion', 'entries', 'outputs', 'files', 'blocks', 'removedBlocks', 'removedFiles'];
+  const canonical = value => value && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.keys(value).sort(compare).map(key => [key, canonical(value[key])]))
+    : Array.isArray(value) ? value.map(canonical) : value;
+  let result = original;
+  for (const key of keys) {
+    if (JSON.stringify(canonical(previous[key])) !== JSON.stringify(canonical(next[key]))) result = replaceJsonMember(result, key, next[key]);
+  }
+  return result.toString('utf8');
+}
+
 export function header(text) {
   const lines = normalize(text).split('\n');
   if (lines[0] !== '---') fail('Frontmatter YAML ausente.');
@@ -76,7 +147,7 @@ function link(target, source) {
 
 export { resourcePath } from '../lib/resource-path.mjs';
 
-export function synchronize({ root = projectRoot, check = false, force = false, localIgnores = true, generateEntrypoints = true, recordDerivedState = true, output = console.log } = {}) {
+export function synchronize({ root = projectRoot, check = false, force = false, localIgnores = true, generateEntrypoints = true, recordDerivedState = true, outputBlocked, output = console.log } = {}) {
   requireNode();
   root = realpathSync(resolve(root));
   const absolute = value => join(root, ...value.split('/'));
@@ -156,6 +227,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const protectedPath = value => /^(workflows(?:\/|$)|settings\.json$|extensions\.json$)/.test(value.slice(value.indexOf('/') + 1).toLowerCase());
   const agents = new Map();
   const formats = new Map();
+  const fallbacks = new Map();
   const discoveries = new Set();
   const ignoreRoots = new Set();
   const natives = [];
@@ -182,14 +254,20 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       && !['readme.md', 'instructions.md'].includes(posix.basename(path).toLowerCase())
       && (/\.(md|mdc)$/i.test(path) || path.startsWith('.gemini/commands/') && path.endsWith('.toml'));
   };
+  const validIgnoreBlock = path => typeof path === 'string' && /^\.[A-Za-z0-9][A-Za-z0-9._-]*\/\.gitignore$/.test(path) && !reserved.has(path.split('/')[0].toLowerCase());
   for (const [name, values] of [['files', previousEntries.files ?? {}], ['blocks', previousEntries.blocks ?? {}]]) {
-    if (!values || typeof values !== 'object' || Array.isArray(values) || Object.entries(values).some(([path, hash]) => !(validResourcePath(path) || name === 'blocks' && canonicalEntrypoint(path)) || !/^[a-f0-9]{64}$/.test(hash))) fail(`Registro de ${name} derivados invalido.`);
+    if (!values || typeof values !== 'object' || Array.isArray(values) || Object.entries(values).some(([path, hash]) => !(validResourcePath(path) || name === 'blocks' && (canonicalEntrypoint(path) || validIgnoreBlock(path))) || !/^[a-f0-9]{64}$/.test(hash))) fail(`Registro de ${name} derivados invalido.`);
     for (const path of Object.keys(values)) safe(canonicalEntrypoint(path) ? resolveEntrypoint(root, canonicalEntrypoint(path)) : path);
   }
   const removedBlocks = new Set(previousEntries.removedBlocks ?? []);
   if (!Array.isArray(previousEntries.removedBlocks ?? []) || [...removedBlocks].some(path => typeof path !== 'string' || !(validResourcePath(path) || canonicalEntrypoint(path)))) fail('Registro de blocos removidos invalido.');
   for (const path of removedBlocks) safe(canonicalEntrypoint(path) ? resolveEntrypoint(root, canonicalEntrypoint(path)) : path);
-  const priorFiles = { ...installed?.files, ...previousEntries.files };
+  const removedFiles = previousEntries.removedFiles ?? {};
+  if (!removedFiles || typeof removedFiles !== 'object' || Array.isArray(removedFiles) || Object.entries(removedFiles).some(([path, hash]) => !validResourcePath(path) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de arquivos removidos invalido.');
+  if (Object.entries(removedFiles).some(([path, hash]) => installed?.files?.[path] && installed.files[path] !== hash)) fail('Registro de arquivos removidos diverge do estado instalado.');
+  for (const path of Object.keys(removedFiles)) safe(path);
+  const effectiveRemovedFiles = Object.fromEntries(Object.entries(removedFiles).filter(([path, hash]) => installed?.files?.[path] === hash));
+  const priorFiles = { ...Object.fromEntries(Object.entries(installed?.files ?? {}).filter(([path, hash]) => effectiveRemovedFiles[path] !== hash)), ...previousEntries.files };
   const priorBlocks = { ...Object.fromEntries(Object.entries(installed?.blocks ?? {}).filter(([path]) => !removedBlocks.has(path))), ...previousEntries.blocks };
   const ownedPaths = new Set([...Object.keys(priorFiles), ...Object.keys(priorBlocks), ...Object.keys(previousEntries.entries), ...Object.keys(previousOutputs)]);
   const nativeRoots = new Set(rows.map(row => row.split('|')).filter(([type]) => ['agente', 'gitignore'].includes(type)).map(([, target]) => target));
@@ -200,6 +278,28 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const boundary = nativePathBoundary(root, value, ownedPaths, { preserveRootAliases: true });
     return boundary ? remember(boundary.path, boundary.reason) : false;
   }
+  const fallbackChecks = new Map();
+  function blockedOutput(path) {
+    if (outputBlocked) return outputBlocked(path);
+    let boundary = nativePathBoundary(root, path, ownedPaths, { preserveRootAliases: true });
+    if (!boundary) {
+      const info = stat(safe(path));
+      if (info && !info.isFile()) boundary = { path, reason: 'non-file' };
+    }
+    if (!boundary) return { blocked: false };
+    remember(boundary.path, boundary.reason);
+    const info = lstatSync(absolute(boundary.path));
+    return { blocked: true, ...boundary, identity: [info.dev, info.ino, info.mode, info.size, info.mtimeMs, info.ctimeMs] };
+  }
+  function unavailable(path) {
+    const status = blockedOutput(path);
+    if (fallbackChecks.has(path) && JSON.stringify(fallbackChecks.get(path)) !== JSON.stringify(status)) fail(`Caminho de skill mudou durante o planejamento: ${path}`);
+    fallbackChecks.set(path, status);
+    return status.blocked;
+  }
+  function assertFallbackChecks() {
+    for (const [path, status] of fallbackChecks) if (JSON.stringify(blockedOutput(path)) !== JSON.stringify(status)) fail(`Caminho de skill mudou apos o planejamento: ${path}`);
+  }
   function claimed(value) {
     if (ownedPaths.has(value)) return true;
     const info = stat(safe(value));
@@ -241,7 +341,8 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       agents.set(target, mode);
     } else if (type === 'formato') {
       if (fields.length !== 4 || !Object.hasOwn(principals, source) || !layouts.has(metadata)) fail(`Formato invalido: ${row}`);
-      if (source === 'skills' && !['agrupado', 'plano'].includes(metadata)) fail(`Skills exigem formato agrupado ou plano: ${row}`);
+      if (source === 'skills' && !['agrupado', 'plano', 'nenhum'].includes(metadata)) fail(`Skills exigem formato agrupado, plano ou nenhum: ${row}`);
+      if (metadata === 'nenhum' && source !== 'skills') fail(`Formato incompativel com recurso: ${row}`);
       if ((metadata === 'mdc' || metadata === 'instrucoes') && source !== 'rules' || metadata === 'prompt' && source !== 'commands' || metadata === 'agente' && source !== 'agents') fail(`Formato incompativel com recurso: ${row}`);
       const key = `${target}/${source}`;
       if (formats.has(key)) fail(`Formato duplicado: ${key}`);
@@ -249,6 +350,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     } else if (type === 'descoberta') {
       if (fields.length !== 3 || target !== '.agents' || source !== 'antigravity' || discoveries.has(target)) fail(`Descoberta invalida: ${row}`);
       discoveries.add(target);
+    } else if (type === 'fallback') {
+      if (fields.length !== 4 || metadata !== 'skills' || target === source || fallbacks.has(target)) fail(`Fallback invalido: ${row}`);
+      fallbacks.set(target, source);
     } else if (type === 'gitignore') {
       if (fields.length !== 2) fail('gitignore aceita somente a pasta de destino.');
       ignoreRoot(target);
@@ -269,6 +373,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   if (!agents.size) fail('Nenhum agente cadastrado.');
   for (const key of formats.keys()) if (!agents.has(key.split('/')[0])) fail(`Formato fora dos agentes: ${key}`);
+  for (const [target, source] of fallbacks) if (!agents.has(target) || !agents.has(source) || formats.get(`${target}/skills`) !== 'nenhum' || formats.get(`${source}/skills`) === 'nenhum') fail(`Fallback fora dos agentes: ${target}`);
   for (const root of discoveries) if (!agents.has(root)) fail(`Descoberta fora dos agentes: ${root}`);
   const managed = value => [...agents.keys()].some(agent => value.startsWith(agent + '/'));
   const built = buildCatalog(root);
@@ -287,7 +392,19 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   for (const [source, kind] of sources) {
     for (const [agent, mode] of agents) {
-      let path = resourcePath(source, kind, formats.get(`${agent}/${kind}`) || mode);
+      const format = formats.get(`${agent}/${kind}`) || mode;
+      if (format === 'nenhum') {
+        const primary = kind === 'skills' && fallbacks.get(agent);
+        if (!primary) continue;
+        const primaryFormat = formats.get(`${primary}/${kind}`) || agents.get(primary);
+        const primaryTarget = `${primary}/${resourcePath(source, kind, primaryFormat)}`;
+        if (!unavailable(primaryTarget)) continue;
+        const target = `${agent}/${resourcePath(source, kind, mode)}`;
+        if (unavailable(target)) fail(`Skill indisponivel: ${source}; caminhos ${primaryTarget} e ${target} obstruidos.`);
+        add(target, source);
+        continue;
+      }
+      let path = resourcePath(source, kind, format);
       if (agent === '.gemini' && kind === 'commands') path = path.replace(/\.md$/, '.toml');
       add(`${agent}/${path}`, source);
     }
@@ -385,7 +502,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       const unchanged = current === null || priorHashes.includes(createHash('sha256').update(current).digest('hex'));
       if (!unchanged) { remember(manifest, 'edited-generated-file'); continue; }
       const nextHash = createHash('sha256').update(content).digest('hex');
-      if (installed?.files?.[manifest] !== nextHash) discoveryOutputs[manifest] = nextHash;
+      if (installed?.files?.[manifest] !== nextHash || Object.hasOwn(previousOutputs, manifest)) discoveryOutputs[manifest] = nextHash;
       if (!info || readFileSync(absolute(manifest), 'utf8') !== content) {
         if (info && force) backup.add(manifest);
         registries.set(manifest, content);
@@ -416,6 +533,10 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       merged = mergeGitignore(current, patterns);
     }
     catch (error) { fail(`${target}: ${error.message}`); }
+    if (target !== '.pbai4devs/.gitignore') {
+      const start = merged.text.indexOf(ignoreBegin), finish = merged.text.indexOf(ignoreEnd);
+      if (start >= 0 && finish > start) managedBlocks[target] = createHash('sha256').update(merged.text.slice(start, finish + ignoreEnd.length)).digest('hex');
+    }
     if (merged.text !== current) {
       ignoreFiles.set(target, merged.text);
       if (force && info && merged.hasBlock) backup.add(target);
@@ -568,8 +689,11 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   if (Object.keys(derivedBlocks).length) next.blocks = derivedBlocks;
   for (const path of Object.keys(managedBlocks)) removedBlocks.delete(path);
   if (removedBlocks.size) next.removedBlocks = sorted(removedBlocks);
-  const registryContent = JSON.stringify(next, null, 2) + '\n';
-  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
+  for (const path of expected.keys()) delete effectiveRemovedFiles[path];
+  for (const path of remove) if (validResourcePath(path) && installed?.files?.[path] && !expected.has(path)) effectiveRemovedFiles[path] = installed.files[path];
+  if (Object.keys(effectiveRemovedFiles).length) next.removedFiles = Object.fromEntries(Object.entries(effectiveRemovedFiles).sort(([a], [b]) => compare(a, b)));
+  const registryContent = derivedContent(registryBytes, previousEntries, next);
+  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || Object.keys(effectiveRemovedFiles).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
   const ownedOutputs = sorted([...targets, ...built.outputs.keys(), '.pbai4devs/espelhos.conf', ...rootEntries.keys(), ...(recordDerivedState && (stat(safe(entryRegistry)) || registries.has(entryRegistry)) ? [entryRegistry] : []),
     ...[...discoveries].flatMap(agent => ['skills', 'rules', 'agents'].map(kind => `${agent}/${kind}.json`)),
     ...[...ignoreTemplates.keys()].filter(target => {
@@ -633,6 +757,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const summary = { changed: changed.length + rootEntryChanges.length, stale: removals.length, conflicts: conflicts.size, missing: missing.length, legacy: legacy.length, registries: registries.size, gitignores: ignoreFiles.size, manifests: configExists ? 0 : 1, localIgnores: localStatus.changed + localStatus.missing.length + localStatus.trackedOutputs.length + (localStatus.status === 'no-git' ? 1 : 0) };
   const dirty = Object.values(summary).some(Boolean);
   output(`${summary.changed} desatualizadas; ${summary.stale} obsoletas; ${summary.conflicts} conflitos; ${summary.missing} origens nativas ausentes; ${summary.legacy} documentos antigos; ${summary.registries} indices derivados; ${summary.gitignores} gitignores; ${summary.localIgnores} exclusoes locais.`);
+  assertFallbackChecks();
   if (localStatus.status === 'no-git') output('Git ausente: apos git init, execute a sincronizacao para proteger os arquivos locais.');
   const preservedPaths = sorted(preserved.keys()).map(path => preserved.get(path));
   if (check) return { ...summary, ownedOutputs, managedBlocks, preserved: preservedPaths, exitCode: dirty ? 1 : 0 };
@@ -700,6 +825,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     chmodSync(safe(value), content.mode);
   }
   try {
+    assertFallbackChecks();
     if (localPlan) assertLocalIgnoreUnchanged(localPlan);
     if (Object.keys(affectedHashes).length) {
       if (!assertGitReadableForChanges() && hadGit) fail('Git deixou de estar disponivel antes da sincronizacao; arquivos preservados.');
@@ -712,6 +838,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     for (const [value, text] of ignoreFiles) mutate(value, () => atomic(value, text), text);
     for (const [value, text] of rootEntryChanges) mutate(value, () => atomic(value, text), text);
     if (configChanged) mutate(config, () => atomic(config, finalConfig), finalConfig);
+    assertFallbackChecks();
     // Directory ownership is not recorded: keep even empty parent directories.
     if (localPlan) applyLocalIgnore(localPlan);
   } catch (error) {

package/.pbai4devs/scripts/sincronizar-agentes/tests/HUMAN_OWNERSHIP.mjs

@@ -122,6 +122,36 @@ test('conteúdo humano concorrente não é apagado durante rollback', t => {
   assert.equal(fs.readFileSync(join(root, generated), 'utf8'), human);
 });
 
+test('falha ao registrar remoção derivada restaura fallback e preserva índice', t => {
+  const root = fixture(t), fallback = '.codex/skills/demo/SKILL.md';
+  write(root, '.pbai4devs/espelhos.conf', [
+    'agente|.agents|agrupado', 'agente|.codex|plano',
+    'formato|.codex|skills|nenhum', 'fallback|.codex|.agents|skills',
+  ].join('\n') + '\n');
+  write(root, '.agents/skills', 'obstrução humana');
+  write(root, '.gitignore', '# ignore humano\n');
+  assert.equal(spawnSync('git', ['-C', root, 'add', '.gitignore']).status, 0);
+  run(root);
+  const initial = fs.readFileSync(join(root, fallback));
+  write(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [fallback]: hash(initial) }, blocks: {} }));
+  fs.rmSync(join(root, '.pbai4devs/state/derived.json'), { force: true });
+  fs.rmSync(join(root, '.agents/skills')); // A obstrução pertence à fixture.
+  const before = snapshot(root), index = fs.readFileSync(join(root, '.git/index'));
+  const originalRename = fs.renameSync;
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    if (!injected && to === join(root, '.pbai4devs/state/derived.json')) { injected = true; throw new Error('falha injetada no registro derivado'); }
+    return originalRename(from, to);
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root), /falha injetada no registro derivado/);
+  assert.equal(injected, true);
+  assert.deepEqual(snapshot(root), before);
+  assert.deepEqual(fs.readFileSync(join(root, '.git/index')), index);
+  assert.deepEqual(fs.readFileSync(join(root, fallback)), initial);
+});
+
 test('conteúdo humano é preservado quando a escrita lança erro após promover o arquivo', t => {
   const root = fixture(t), rename = fs.renameSync;
   const failure = new Error('falha depois de promover');

package/.pbai4devs/scripts/sincronizar-agentes/tests/TEST.mjs

@@ -913,6 +913,9 @@ test('formatos desconhecidos ou fora do cliente falham antes de mutar', t => {
   for (const row of [
     'formato|.missing|skills|agrupado', 'formato|.codex|unknown|agrupado',
     'formato|.codex|skills|mdc', 'formato|.codex|rules|prompt',
+    'formato|.codex|agents|nenhum', 'formato|.codex|commands|nenhum',
+    'fallback|.codex|.missing|skills', 'fallback|.codex|.codex|skills',
+    'fallback|.codex|.agents|rules',
     'formato|.codex|skills|plano\nformato|.codex|skills|agrupado',
     'descoberta|.codex|antigravity', 'descoberta|.agents|antigravity',
   ]) {
@@ -922,3 +925,22 @@ test('formatos desconhecidos ou fora do cliente falham antes de mutar', t => {
   assert.equal(resourcePath('.pbai4devs/commands/team/check/COMMAND.md', 'commands', 'arquivo'), 'commands/team/check.md');
   assert.throws(() => resourcePath(source, 'skills', 'arquivo'), /Skills/);
 });
+
+test('sincronização direta recusa troca concorrente da obstrução de fallback', t => {
+  const root = fixture(t, true);
+  write(root, source, skill);
+  write(root, '.pbai4devs/espelhos.conf', [
+    'agente|.agents|agrupado', 'agente|.codex|agrupado',
+    'formato|.codex|skills|nenhum', 'fallback|.codex|.agents|skills',
+  ].join('\n') + '\n');
+  write(root, '.agents/skills/projeto', 'Obstrução humana.');
+  let called = false;
+  assert.throws(() => synchronize({ root, localIgnores: false, generateEntrypoints: false, output() {
+    if (called) return;
+    called = true;
+    rmSync(join(root, '.agents/skills/projeto')); // Simula mudança humana após o planejamento.
+  } }), /mudou apos o planejamento/);
+  assert.equal(called, true);
+  assert.equal(existsSync(join(root, '.codex')), false);
+  assert.equal(existsSync(join(root, '.agents/skills/projeto/demo/SKILL.md')), false);
+});

package/.pbai4devs/scripts/testar-maturidade/README.md

@@ -14,19 +14,21 @@ node .pbai4devs/scripts/testar-maturidade/SCRIPT.mjs run --case legado
 node --test .pbai4devs/scripts/testar-maturidade/tests/TEST.mjs
 ```
 
-`prepare` só gera as cópias; `run` gera e executa. Os oito cenários ficam em
-`examples/generated/`: agentes, descoberta, planejamento, aplicação inicial,
-configurada, manutenção, legado e monorepo com caminhos em português.
+`prepare` só gera as cópias; `run` gera e executa. Cada execução cria uma nova
+pasta `examples/generated/maturity-*` e informa seu caminho no console. Por
+padrão são oito cenários: agentes, descoberta, planejamento, aplicação inicial,
+configurada, manutenção, legado e monorepo com caminhos em português. Use
+`--case` para executar apenas um.
 
 O harness copia recursos e configurações reais; exclui pacotes, caches, logs,
 resultados de testes, Playwright e pastas temporárias em qualquer caixa,
 `.git` e nomes conhecidos de credenciais/overrides locais. Não faz varredura
 semântica de segredos. A API também aceita `tmp/examples/` para compatibilidade
-e descendentes de `.agent-tests/`. Regenera apenas pastas identificadas como
-suas. Cada exemplo recebe Git local, sem commits nem identidade alterada.
-O diretório gerado contém um ignore próprio, inclusive em projetos consumidores.
-`prepare` redefine o relatório como `prepared`, sem conservar provas antigas.
-Se a preparação falhar, o índice fica em `preparing` e o relatório antigo sai.
+e descendentes de `.agent-tests/`. Um destino explícito deve ser inexistente;
+execuções e projetos anteriores não são substituídos nem removidos. Cada
+exemplo recebe Git local, sem commits nem identidade alterada. O diretório
+gerado contém um ignore próprio, inclusive em projetos consumidores. Se a
+preparação falhar, o índice da nova execução permanece em `preparing`.
 O hub `.pbai4devs` e os clientes registrados são copiados, incluindo comandos
 nativos em TOML. Sem manifesto local, os templates definem os clientes em
 memória, respeitando a seleção salva. `.vscode` exige registro. Apenas as entradas
@@ -50,5 +52,5 @@ O gate positivo simula o parecer para testar seu contrato; não representa
 revisão humana. Estados de aprovação são dados sintéticos. Nenhum teste
 certifica produção, Docker, interface visual ou outro sistema operacional.
 
-Índice e relatório: `examples/generated/README.md` e `REPORT.json`. Logs e provas
-individuais ficam em `.agent-tests/` dentro de cada exemplo, todos ignorados.
+Índice e relatório ficam em `README.md` e `REPORT.json` na pasta informada.
+Logs e provas ficam em `.agent-tests/` dentro de cada exemplo, todos ignorados.