@pathbit/agentdevkit 0.0.8 → 0.0.10

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

@@ -7,6 +7,7 @@ import { requireNode, projectRoot, isMain } from '../lib/runtime.mjs';
 import { buildCatalog } from '../lib/catalog.mjs';
 import { resourcePath } from '../lib/resource-path.mjs';
 import { adapterManifest, resolveAdapters } from '../lib/adapters.mjs';
+import { nativePathBoundary } from '../lib/native-paths.mjs';
 import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
 
 const marker = '<!-- gerado: sincronizar-agentes -->';
@@ -90,6 +91,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     return current;
   }
   function scan(value, { markdownOnly = false, prune = false } = {}) {
+    if (preserveBoundary(value)) return [];
     const path = safe(value);
     const item = stat(path);
     if (!item) return [];
@@ -99,6 +101,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     function visit(folder) {
       for (const name of readdirSync(safe(folder)).sort(compare)) {
         const child = `${folder}/${name}`;
+        if (preserveBoundary(child)) continue;
         const info = stat(safe(child));
         if (prune && isGeneratedOutput(child, info.isDirectory())) continue;
         if (info.isDirectory()) {
@@ -119,7 +122,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const marked = text.split('\n').includes(marker) || text.startsWith(tomlMarker + '\n');
     return isReference(text) && (marked || recorded);
   };
-  const onlyReferences = value => { const files = scan(value); return files.length > 0 && files.every(file => /\.(md|mdc|toml)$/.test(file) && referenceFile(file)); };
+  const onlyReferences = value => { const files = scan(value); return files.length > 0 && ![...preserved.keys()].some(path => path === value || path.startsWith(`${value}/`)) && files.every(file => /\.(md|mdc|toml)$/.test(file) && referenceFile(file)); };
   const protectedPath = value => /^(workflows(?:\/|$)|settings\.json$|extensions\.json$)/.test(value.slice(value.indexOf('/') + 1).toLowerCase());
   const agents = new Map();
   const formats = new Map();
@@ -133,10 +136,41 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const installed = stat(safe(stateFile)) ? JSON.parse(read(safe(stateFile))) : null;
   const configText = configExists ? read(safe(config)) : adapterManifest(root, { clients: installed?.clients });
   const rows = configText.split('\n');
+  const entryRegistry = '.pbai4devs/estado/derived.json';
+  const previousEntries = stat(safe(entryRegistry)) ? JSON.parse(read(safe(entryRegistry))) : { schemaVersion: 1, entries: {} };
+  if (previousEntries?.schemaVersion !== 1 || !previousEntries.entries || typeof previousEntries.entries !== 'object' || Array.isArray(previousEntries.entries) || Object.entries(previousEntries.entries).some(([name, hash]) => !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(name) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de entradas derivadas invalido.');
+  const previousOutputs = previousEntries.outputs ?? {};
+  if (!previousOutputs || typeof previousOutputs !== 'object' || Array.isArray(previousOutputs) || Object.entries(previousOutputs).some(([path, hash]) => !/^\.[A-Za-z0-9][A-Za-z0-9._-]*\/(skills|rules|agents)\.json$/.test(path) || reserved.has(path.split('/')[0].toLowerCase()) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de saidas derivadas invalido.');
+  const ownedPaths = new Set([...Object.keys(installed?.files || {}), ...Object.keys(installed?.blocks || {}), ...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));
+  const preserved = new Map();
+  const remember = (path, reason = 'user-owned') => { preserved.set(path, { path, reason }); return true; };
+  function preserveBoundary(value) {
+    if (!nativeRoots.has(value.split('/')[0]) && !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md', 'README.md'].includes(value)) return false;
+    const boundary = nativePathBoundary(root, value, ownedPaths, { preserveRootAliases: true });
+    return boundary ? remember(boundary.path, boundary.reason) : false;
+  }
+  function claimed(value) {
+    if (ownedPaths.has(value)) return true;
+    const info = stat(safe(value));
+    if (!info?.isFile() || info.size > 1024 * 1024) return false;
+    const text = read(safe(value));
+    return text.split('\n').includes(marker) || text.startsWith(tomlMarker + '\n');
+  }
+  function preserveUnknown(value) {
+    if (preserveBoundary(value)) return true;
+    const info = stat(safe(value));
+    return info && !referenceFile(value) && !claimed(value) ? remember(value) : false;
+  }
+  function preserveNativeType(value, info, type) {
+    if (!info || info[type]()) return false;
+    if ([...ownedPaths].some(path => path === value || path.startsWith(`${value}/`))) fail(`Tipo alterado em caminho gerenciado: ${value}`);
+    return remember(value, info.isDirectory() ? 'existing-directory' : info.isFile() ? 'existing-file' : 'existing-other');
+  }
   function ignoreRoot(target) {
     if (!/^\.[^/]+$/.test(target) || reserved.has(target.toLowerCase())) fail(`Pasta de agente invalida: ${target}`);
-    const info = stat(absolute(target));
-    if (info && !info.isDirectory()) fail(`Pasta de agente nao e diretorio: ${target}`);
+    const info = preserveBoundary(target) ? null : stat(safe(target));
+    preserveNativeType(target, info, 'isDirectory');
     for (const known of ignoreRoots) if (known !== target && known.toLowerCase() === target.toLowerCase()) fail('Raizes de agentes diferem somente por maiusculas/minusculas.');
     ignoreRoots.add(target);
   }
@@ -145,7 +179,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const fields = row.split('|');
     if (fields.length < 2 || fields.length > 4) fail('Campos invalidos no manifesto.');
     const [type, target, source = '', metadata = ''] = fields;
-    safe(target);
+    if (!preserveBoundary(target)) safe(target);
     if (type === 'agente') {
       if (fields.length > 3) fail(`Pasta de agente invalida: ${target}`);
       ignoreRoot(target);
@@ -191,6 +225,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const entries = new Map();
   const folded = new Map();
   function add(target, source, metadata = '') {
+    if (preserveUnknown(target)) return;
     safe(target);
     const alias = folded.get(target.toLowerCase());
     if (alias && alias !== target) fail(`Destinos diferem somente por maiusculas/minusculas: ${target}`);
@@ -240,14 +275,15 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     if (custom) backup.add(value);
   }
   function cleanScope(value) {
+    if (preserveBoundary(value)) return;
     if (!stat(safe(value))) return;
     if (stat(safe(value)).isDirectory() && !scan(value).length) return;
-    if (force && value.split('/')[1] === 'external-skills') planRemove(value, true);
-    else if (onlyReferences(value)) planRemove(value);
-    else if (force) planRemove(value, true);
-    else conflicts.add(value);
+    if (onlyReferences(value)) planRemove(value);
+    else if (claimed(value)) { if (force) planRemove(value, true); else conflicts.add(value); }
+    else remember(value);
   }
   const registries = new Map();
+  const discoveryOutputs = {};
   for (const [target, content] of built.outputs) {
     const info = stat(safe(target));
     if (info && !info.isFile()) fail(`Registro nao e arquivo: ${target}`);
@@ -259,22 +295,22 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   for (const agent of discoveries) {
     for (const kind of ['skills', 'rules', 'agents']) {
       const manifest = `${agent}/${kind}.json`;
+      if (preserveBoundary(manifest)) continue;
       const paths = [...entries].filter(([target, value]) => target.startsWith(`${agent}/`) && sources.get(value.source) === kind)
         .map(([target]) => kind === 'skills' ? posix.dirname(target) : target).sort(compare);
       const content = JSON.stringify({ entries: paths.map(path => ({ path })) }, null, 2) + '\n';
       const info = stat(safe(manifest));
+      if (preserveNativeType(manifest, info, 'isFile')) continue;
       if (info && !info.isFile()) fail(`Registro nao e arquivo: ${manifest}`);
+      if (info && !ownedPaths.has(manifest)) { remember(manifest); continue; }
+      const current = info ? readFileSync(absolute(manifest)) : null;
+      const priorHashes = [previousOutputs[manifest], installed?.files?.[manifest]];
+      const unchanged = current === null || priorHashes.includes(createHash('sha256').update(current).digest('hex'));
+      if (!unchanged && !force) conflicts.add(manifest);
+      if (!unchanged && force) backup.add(manifest);
+      const nextHash = createHash('sha256').update(content).digest('hex');
+      if (installed?.files?.[manifest] !== nextHash) discoveryOutputs[manifest] = nextHash;
       if (!info || readFileSync(absolute(manifest), 'utf8') !== content) {
-        let managedManifest = false;
-        if (info) {
-          try {
-            const previous = JSON.parse(read(absolute(manifest)));
-            managedManifest = Object.keys(previous).length === 1 && Array.isArray(previous.entries) && previous.entries.every(entry =>
-              entry && Object.keys(entry).length === 1 && typeof entry.path === 'string' && entry.path.startsWith(`${agent}/${kind}/`) && !entry.path.split('/').some(part => !part || part === '..' || part === '.')
-            );
-          } catch { /* Um manifesto customizado ou corrompido requer --force e backup. */ }
-        }
-        if (info && !managedManifest && !force) conflicts.add(manifest);
         if (info && force) backup.add(manifest);
         registries.set(manifest, content);
       }
@@ -289,11 +325,14 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     ...sorted(ignoreRoots).map(folder => [`${folder}/.gitignore`, '.pbai4devs/templates/gitignore/agents.ignore']),
   ]);
   for (const [target, template] of ignoreTemplates) {
+    if (preserveBoundary(target)) continue;
     if (!stat(safe(template))?.isFile()) fail(`Template .gitignore ausente ou invalido: ${template}`);
     const info = stat(safe(target));
+    if (target !== '.pbai4devs/.gitignore' && preserveNativeType(target, info, 'isFile')) continue;
     if (info && !info.isFile()) fail(`.gitignore nao e arquivo: ${target}`);
     let merged;
     const current = info ? readFileSync(absolute(target), 'utf8') : '';
+    if (target !== '.pbai4devs/.gitignore' && info && !ownedPaths.has(target) && !current.split(/\r?\n/).some(line => [ignoreBegin, ignoreEnd].includes(line))) { remember(target); continue; }
     try {
       let patterns = readFileSync(absolute(template), 'utf8');
       if (target !== '.pbai4devs/.gitignore') patterns = renderClientIgnore(patterns, ignoreClients[posix.dirname(target)]);
@@ -349,18 +388,20 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     for (const kind of [...auxiliary, 'README.md', 'INSTRUCTIONS.md']) cleanScope(`${agent}/${kind}`);
     for (const kind of Object.keys(principals)) {
       const scope = `${agent}/${kind}`;
+      if (preserveBoundary(scope)) continue;
       const info = stat(safe(scope));
       if (!info) continue;
       const files = scan(scope);
-      if (!info.isDirectory()) { if (force) planRemove(scope, true); else conflicts.add(scope); continue; }
+      if (!info.isDirectory()) { if (claimed(scope)) { if (force) planRemove(scope, true); else conflicts.add(scope); } else remember(scope); continue; }
       for (const file of files) if (!expected.has(file)) {
         if (referenceFile(file)) planRemove(file);
-        else if (force) planRemove(file, true);
-        else conflicts.add(file);
+        else if (claimed(file)) { if (force) planRemove(file, true); else conflicts.add(file); }
+        else remember(file);
       }
       function directories(value) {
         for (const name of readdirSync(safe(value))) {
           const child = `${value}/${name}`;
+          if (preserveBoundary(child)) continue;
           if (!stat(safe(child))?.isDirectory()) continue;
           if (![...expected.keys()].some(target => target.startsWith(child + '/'))) cleanScope(child);
           directories(child);
@@ -377,18 +418,19 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   for (const { target } of missing) cleanScope(target);
   const rootEntries = new Map();
-  const entryRegistry = '.pbai4devs/estado/derived.json';
   if (generateEntrypoints) {
-    const previous = stat(safe(entryRegistry)) ? JSON.parse(read(safe(entryRegistry))) : { schemaVersion: 1, entries: {} };
-    if (previous?.schemaVersion !== 1 || !previous.entries || typeof previous.entries !== 'object' || Array.isArray(previous.entries) || Object.entries(previous.entries).some(([name, hash]) => !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(name) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de entradas derivadas invalido.');
+    const previous = previousEntries;
     const next = { schemaVersion: 1, entries: {} };
+    if (Object.keys(discoveryOutputs).length) next.outputs = discoveryOutputs;
     for (const name of resolveAdapters(installed?.clients).entrypoints) {
       const template = `.pbai4devs/templates/entrypoints/${name}`;
       if (!stat(safe(template))?.isFile()) continue;
+      if (preserveBoundary(name)) continue;
       const info = stat(safe(name));
+      if (preserveNativeType(name, info, 'isFile')) continue;
       const current = info?.isFile() ? readFileSync(absolute(name)) : null;
       const previousHash = previous.entries[name] ?? installed?.files?.[name];
-      if (info && (!current || createHash('sha256').update(current).digest('hex') !== previousHash)) continue;
+      if (info && (!current || createHash('sha256').update(current).digest('hex') !== previousHash)) { remember(name); continue; }
       if (current && createHash('sha256').update(current).digest('hex') === installed?.files?.[name]) {
         rootEntries.set(name, current.toString('utf8'));
         continue;
@@ -399,17 +441,18 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       rootEntries.set(name, content);
     }
     const content = JSON.stringify(next, null, 2) + '\n';
-    if ((Object.keys(next.entries).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== content)) registries.set(entryRegistry, content);
+    if ((Object.keys(next.entries).length || Object.keys(discoveryOutputs).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== content)) registries.set(entryRegistry, content);
   }
   const ownedOutputs = sorted([...targets, ...built.outputs.keys(), '.pbai4devs/espelhos.conf', ...rootEntries.keys(), ...(generateEntrypoints && (stat(safe(entryRegistry)) || registries.has(entryRegistry)) ? [entryRegistry] : []),
     ...[...discoveries].flatMap(agent => ['skills', 'rules', 'agents'].map(kind => `${agent}/${kind}.json`)),
     ...[...ignoreTemplates.keys()].filter(target => {
       if (target === '.pbai4devs/.gitignore') return false;
+      if (preserved.has(target) || preserveBoundary(target)) return false;
       const content = ignoreFiles.get(target) ?? readFileSync(absolute(target), 'utf8');
       const start = content.indexOf(ignoreBegin), finish = content.indexOf(ignoreEnd);
       return start >= 0 && finish > start && !(content.slice(0, start) + content.slice(finish + ignoreEnd.length)).trim();
     }),
-  ]);
+  ]).filter(path => ![...preserved.keys()].some(value => path === value || path.startsWith(`${value}/`)));
   const localPlan = localIgnores ? planLocalIgnore(root, { outputs: ownedOutputs }) : null;
   const localStatus = localPlan ? checkLocalIgnore(localPlan) : { changed: 0, missing: [], trackedOutputs: [] };
   const removals = topPaths(remove);
@@ -442,7 +485,8 @@ 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 };
   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.`);
-  if (check) return { ...summary, ownedOutputs, exitCode: dirty ? 1 : 0 };
+  const preservedPaths = sorted(preserved.keys()).map(path => preserved.get(path));
+  if (check) return { ...summary, ownedOutputs, preserved: preservedPaths, exitCode: dirty ? 1 : 0 };
   if (conflicts.size) fail(`Use --force para reconstruir somente os caminhos gerenciados: ${sorted(conflicts).join(', ')}`);
   if (localStatus.missing.length) fail(`Regras humanas reabrem derivados locais: ${localStatus.missing.join(', ')}`);
   if (localPlan) assertLocalIgnoreUnchanged(localPlan);
@@ -548,7 +592,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     if (failures.length) throw new AggregateError([error, ...failures], `${error.message}; rollback incompleto: ${failures.map(failure => failure.message).join('; ')}`);
     throw error;
   }
-  return { ...summary, ownedOutputs, exitCode: 0, ...(backupRoot ? { backupRoot } : {}) };
+  return { ...summary, ownedOutputs, preserved: preservedPaths, exitCode: 0, ...(backupRoot ? { backupRoot } : {}) };
 }
 
 export function main(args = process.argv.slice(2)) {

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

@@ -0,0 +1,190 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { projectRoot } from '../../lib/runtime.mjs';
+import { nativePathBoundary } from '../../lib/native-paths.mjs';
+import { synchronize } from '../SCRIPT.mjs';
+
+const hash = content => createHash('sha256').update(content).digest('hex');
+const put = (root, path, text) => { fs.mkdirSync(dirname(join(root, path)), { recursive: true }); fs.writeFileSync(join(root, path), text); };
+const run = (root, options = {}) => synchronize({ root, localIgnores: false, output() {}, ...options });
+function fixture(t) {
+  const root = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), 'agentdevkit-coexist-')));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  put(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\nagente|.codex|plano\nagente|.agents|plano\ndescoberta|.agents|antigravity\n');
+  put(root, '.pbai4devs/skills/demo/SKILL.md', '---\nname: demo\ndescription: Demo.\n---\n\n# Demo\n');
+  put(root, '.pbai4devs/agents/revisor/AGENT.md', '---\nname: revisor\ndescription: Revisor.\n---\n\n# Revisor\n');
+  for (const name of ['agents.ignore', 'shared.ignore', 'local.ignore', 'clients.json']) put(root, `.pbai4devs/templates/gitignore/${name}`, fs.readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore', name)));
+  for (const name of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) put(root, `.pbai4devs/templates/entrypoints/${name}`, `---\ndescription: Entry.\n---\n\n# ${name}\n\nLeia AGENTS.md.\n`);
+  return root;
+}
+function link(t, root, target, path, type = 'file') {
+  fs.mkdirSync(dirname(join(root, path)), { recursive: true });
+  try { fs.symlinkSync(target, join(root, path), type); return true; }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) { t.skip('Sistema não permite criar este link simbólico.'); return false; } throw error; }
+}
+function snapshot(root) {
+  const result = {};
+  function visit(prefix = '') {
+    for (const name of fs.readdirSync(join(root, prefix)).sort()) {
+      const path = prefix ? `${prefix}/${name}` : name, info = fs.lstatSync(join(root, path));
+      result[path] = info.isSymbolicLink() ? ['link', fs.readlinkSync(join(root, path))] : info.isDirectory() ? ['directory', info.mode & 0o777] : ['file', info.mode & 0o777, hash(fs.readFileSync(join(root, path)))];
+      if (info.isDirectory()) visit(path);
+    }
+  }
+  visit(); return result;
+}
+
+test('coexiste com aliases nativos, configuração e colisão humana sem alterar os destinos', t => {
+  const root = fixture(t);
+  put(root, '.claude/skills/existing/SKILL.md', '# Human skill\n');
+  put(root, '.claude/agents/revisor.md', '# Human reviewer\n');
+  put(root, '.claude/.gitignore', '# Human ignore\n*.private\n');
+  put(root, 'AGENTS.md', '# Human instructions\n');
+  put(root, 'external/config.json', '{"human":true}\n');
+  if (!link(t, root, '../.claude/skills', '.codex/skills', 'dir') || !link(t, root, 'AGENTS.md', 'CLAUDE.md') || !link(t, root, '../external/config.json', '.claude/settings.local.json')) return;
+  const original = snapshot(root), result = run(root, { force: true });
+  for (const [path, before] of Object.entries(original)) assert.deepEqual(snapshot(root)[path], before, path);
+  for (const path of ['.codex/skills', 'CLAUDE.md', '.claude/agents/revisor.md', '.claude/.gitignore', '.claude/settings.local.json']) assert.ok(result.preserved.some(item => item.path === path), path);
+  assert.ok(result.ownedOutputs.includes('.agents/skills/demo/SKILL.md'));
+  assert.ok(result.ownedOutputs.every(path => !path.startsWith('.codex/skills/') && path !== '.claude/agents/revisor.md' && path !== 'CLAUDE.md'));
+  const stable = snapshot(root);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  run(root, { force: true });
+  assert.deepEqual(snapshot(root), stable);
+});
+
+test('preserva raiz simbólica externa, link pendente e loop sem abri-los', t => {
+  for (const targetKind of ['external', 'dangling', 'loop']) {
+    const root = fixture(t), outside = fixture(t);
+    put(outside, 'sentinel.txt', 'outside\n');
+    const beforeOutside = snapshot(outside);
+    const target = targetKind === 'external' ? outside : targetKind === 'loop' ? '.codex' : join(outside, 'missing');
+    if (!link(t, root, target, '.codex', targetKind === 'external' && process.platform === 'win32' ? 'junction' : 'dir')) return;
+    const result = run(root, { force: true });
+    assert.equal(fs.readlinkSync(join(root, '.codex')), target);
+    assert.deepEqual(snapshot(outside), beforeOutside);
+    assert.ok(result.preserved.some(item => item.path === '.codex' && item.reason === 'symbolic-link'));
+    assert.equal(run(root, { check: true }).exitCode, 0);
+  }
+});
+
+test('ignore nativo simbólico permanece opaco na política local do Git', t => {
+  const root = fixture(t), outside = fixture(t);
+  const git = spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+  assert.equal(git.status, 0, git.stderr);
+  put(outside, 'ignore', '# External human ignore\n!*.private\n');
+  if (!link(t, root, join(outside, 'ignore'), '.claude/.gitignore')) return;
+  const before = snapshot(outside);
+  const result = run(root, { localIgnores: true });
+  assert.ok(result.preserved.some(item => item.path === '.claude/.gitignore'));
+  assert.deepEqual(snapshot(outside), before);
+  assert.equal(run(root, { localIgnores: true, check: true }).exitCode, 0);
+});
+
+test('link em caminho registrado continua sendo erro antes de qualquer escrita', t => {
+  for (const source of ['files', 'blocks', 'derived', 'outputs']) {
+    const root = fixture(t), path = source === 'derived' ? 'CLAUDE.md' : source === 'outputs' ? '.agents/skills.json' : '.claude/skills/demo/SKILL.md';
+    if (!link(t, root, 'missing', path)) return;
+    if (source === 'derived' || source === 'outputs') put(root, '.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: source === 'derived' ? { [path]: 'a'.repeat(64) } : {}, ...(source === 'outputs' ? { outputs: { [path]: 'a'.repeat(64) } } : {}) }));
+    else put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: source === 'files' ? { [path]: 'a'.repeat(64) } : {}, blocks: source === 'blocks' ? { [path]: 'a'.repeat(64) } : {} }));
+    const before = snapshot(root);
+    assert.throws(() => run(root, { force: true }), /Link simbolico em caminho gerenciado/);
+    assert.deepEqual(snapshot(root), before);
+  }
+});
+
+test('manifesto standalone tem propriedade explícita e alterações humanas exigem reparo autorizado', t => {
+  const root = fixture(t); run(root);
+  const path = '.agents/skills.json', original = fs.readFileSync(join(root, path), 'utf8');
+  const derived = JSON.parse(fs.readFileSync(join(root, '.pbai4devs/estado/derived.json')));
+  assert.equal(derived.outputs[path], hash(original));
+  put(root, path, '{"entries":[{"path":".agents/skills/custom"}]}\n');
+  const before = snapshot(root);
+  assert.throws(() => run(root), /--force/);
+  assert.deepEqual(snapshot(root), before);
+  const result = run(root, { force: true });
+  assert.equal(fs.readFileSync(join(root, path), 'utf8'), original);
+  assert.equal(fs.readFileSync(join(result.backupRoot, path), 'utf8'), '{"entries":[{"path":".agents/skills/custom"}]}\n');
+});
+
+test('manifesto nativo omite colisões preservadas e inclui somente apontamentos ativos', t => {
+  const root = fixture(t), collision = '.agents/skills/demo/SKILL.md';
+  put(root, collision, '# Human demo\n');
+  const result = run(root);
+  assert.deepEqual(JSON.parse(fs.readFileSync(join(root, '.agents/skills.json'))).entries, []);
+  assert.ok(result.preserved.some(item => item.path === collision));
+  assert.ok(!result.ownedOutputs.includes(collision));
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});
+
+test('preserva diretórios humanos no lugar de índices, ignores e entradas, e arquivo no lugar de raiz', t => {
+  const root = fixture(t);
+  for (const path of ['.agents/skills.json', '.claude/.gitignore', 'CLAUDE.md']) put(root, `${path}/keep.txt`, 'Human data\n');
+  put(root, '.codex', 'Human native configuration\n');
+  const before = snapshot(root), result = run(root, { force: true });
+  for (const [path, value] of Object.entries(before)) assert.deepEqual(snapshot(root)[path], value, path);
+  for (const path of ['.agents/skills.json', '.claude/.gitignore', 'CLAUDE.md', '.codex']) {
+    assert.ok(result.preserved.some(item => item.path === path), path);
+    assert.ok(result.ownedOutputs.every(output => output !== path && !output.startsWith(`${path}/`)), path);
+  }
+  const stable = snapshot(root);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  run(root, { force: true });
+  assert.deepEqual(snapshot(root), stable);
+});
+
+test('tipo alterado em caminho nativo registrado continua recusado antes de gravar', t => {
+  for (const [path, owned] of [
+    ['.agents/skills.json', '.agents/skills.json'],
+    ['.claude/.gitignore', '.claude/.gitignore'],
+    ['CLAUDE.md', 'CLAUDE.md'],
+    ['.codex', '.codex/skills/demo/SKILL.md'],
+  ]) {
+    const root = fixture(t);
+    if (path === '.codex') put(root, path, 'Human root\n'); else put(root, `${path}/keep.txt`, 'Human directory\n');
+    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
+    const before = snapshot(root);
+    assert.throws(() => run(root, { force: true }), /caminho gerenciado/);
+    assert.deepEqual(snapshot(root), before);
+  }
+});
+
+test('classificação preservável não encobre aliases por caixa nem caminhos fora do escopo', t => {
+  const root = fixture(t);
+  put(root, '.Claude/notes.txt', 'human\n');
+  assert.throws(() => nativePathBoundary(root, '.claude/skills'), /maiusculas\/minusculas/);
+  assert.throws(() => nativePathBoundary(root, '.claude/skills', [], { preserveRootAliases: true }), /maiusculas\/minusculas/);
+  for (const path of ['../outside', '/outside', '.claude//skills', '.claude/./skills', '.claude/skills\n']) assert.throws(() => nativePathBoundary(root, path), /Caminho invalido/);
+});
+
+test('variantes humanas de entradas da raiz são preservadas sem criar duplicatas', t => {
+  const root = fixture(t);
+  for (const path of ['Readme.md', 'agents.md', 'claude.md', 'gemini.md']) put(root, path, `# Human ${path}\n`);
+  const before = snapshot(root), result = run(root, { force: true });
+  for (const [path, content] of Object.entries(before)) assert.deepEqual(snapshot(root)[path], content, path);
+  for (const [canonical, alias] of [['README.md', 'Readme.md'], ['AGENTS.md', 'agents.md'], ['CLAUDE.md', 'claude.md'], ['GEMINI.md', 'gemini.md']]) {
+    assert.deepEqual(nativePathBoundary(root, canonical, [], { preserveRootAliases: true }), { path: alias, reason: 'case-variant' });
+    if (canonical !== 'README.md') assert.ok(result.preserved.some(item => item.path === alias));
+    assert.ok(!result.ownedOutputs.includes(canonical));
+    assert.ok(!fs.readdirSync(root).includes(canonical), canonical);
+  }
+  const stable = snapshot(root);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  assert.deepEqual(snapshot(root), stable);
+});
+
+test('variante de caixa de entrada registrada não esconde drift de propriedade', t => {
+  for (const owned of ['AGENTS.md', 'agents.md']) {
+    const root = fixture(t); put(root, 'agents.md', '# Renamed human entry\n');
+    assert.throws(() => nativePathBoundary(root, 'AGENTS.md', [owned], { preserveRootAliases: true }), /maiusculas\/minusculas/);
+    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
+    const before = snapshot(root);
+    assert.throws(() => run(root, { force: true }), /maiusculas\/minusculas/);
+    assert.deepEqual(snapshot(root), before);
+  }
+});

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

@@ -44,9 +44,15 @@ test('texto humano com formato de referência nunca comprova propriedade', t =>
     const before = snapshot(root);
     assert.equal(isReference(human), true, 'O parser de formato continua independente da propriedade.');
     assert.equal(run(root, { check: true }).exitCode, 1);
-    assert.throws(() => run(root), /--force/);
-    assert.deepEqual(snapshot(root), before);
+    const result = run(root);
+    assert.ok(result.preserved.some(item => item.path === path));
+    assert.ok(!result.ownedOutputs.includes(path));
     assert.equal(fs.readFileSync(join(root, path), 'utf8'), human);
+    assert.equal(snapshot(root)[path], before[path]);
+    assert.equal(run(root, { check: true }).exitCode, 0);
+    const stable = snapshot(root);
+    run(root, { force: true });
+    assert.deepEqual(snapshot(root), stable);
   }
 });
 

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

@@ -11,6 +11,7 @@ import { toolWrapper } from '../../preparar-ferramentas/SCRIPT.mjs';
 import { mergeGitignore, ignoreBegin, ignoreEnd, validateIgnoreClients } from '../../lib/gitignore.mjs';
 import './LOCAL_IGNORE.mjs';
 import './HUMAN_OWNERSHIP.mjs';
+import './COEXISTENCE.mjs';
 import { validateCatalog as validateExternalCatalog } from '../../gerenciar-skills-externas/SCRIPT.mjs';
 
 const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
@@ -21,6 +22,7 @@ const source = '.pbai4devs/skills/projeto/demo/SKILL.md';
 const read = (root, path) => readFileSync(join(root, path), 'utf8');
 const write = (root, path, content) => { mkdirSync(dirname(join(root, path)), { recursive: true }); writeFileSync(join(root, path), content); };
 const pointer = (origin = 'origem.md', title = 'Referencia') => `---\ndescription: Referencia.\n---\n\n# ${title}\n\n${marker}\nLeia e siga [origem](${origin}).\n`;
+const recordOwned = (root, paths) => write(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: Object.fromEntries(paths.map(path => [path, createHash('sha256').update(readFileSync(join(root, path))).digest('hex')])), blocks: {} }));
 const toolConfig = (name = 'demo') => ({ name, description: `Ferramenta ${name}.`, group: 'base', source: `https://github.com/fixture/${name}`, download: { provider: 'npm', package: name, registry: 'https://registry.npmjs.org/', repository: `fixture/${name}`, channel: 'latest' }, platforms: [`${process.platform}-${process.arch}`], scripts: { entry: 'SCRIPT.mjs' }, probe: ['--version'] });
 const externalConfig = () => ({ schemaVersion: 1, allowlist: ['fixture/skills'], skills: [{ id: 'external-demo', repository: 'fixture/skills', commit: 'a'.repeat(40), path: 'skills/demo/SKILL.md', name: 'external-demo', license: 'MIT', use: 'Revisar exemplo externo.', status: 'reviewed', notes: 'Sem execução automática.' }] });
 const run = (root, options = {}) => synchronize({ root, localIgnores: false, generateEntrypoints: false, output() {}, ...options });
@@ -334,7 +336,7 @@ test('registros são derivados, determinísticos e --check nunca os corrige', t
   assertCheckReadonly(empty, {}, 0);
 });
 
-test('skills externas baixadas não entram nos índices; --force salva e limpa cópias indevidas', t => {
+test('skills externas baixadas não entram nos índices; cópias humanas permanecem intactas', t => {
   const root = fixture(t);
   write(root, '.pbai4devs/external-skills/README.md', '# Catálogo externo\n');
   write(root, '.pbai4devs/external-skills/CATALOG.json', JSON.stringify(externalConfig()));
@@ -348,38 +350,34 @@ test('skills externas baixadas não entram nos índices; --force salva e limpa c
   write(root, '.codex/external-skills/.local/upstream-0/SKILL.md', '# Cópia indevida\n');
   write(root, '.claude/external-skills/README.md', pointer('../../.pbai4devs/external-skills/README.md'));
   assertCheckReadonly(root);
-  rejected(root, {}, /--force/);
   const result = run(root, { force: true });
-  for (const client of ['.codex', '.claude']) {
-    assert.equal(existsSync(join(root, client, 'external-skills')), false);
-    assert.ok(existsSync(join(result.backupRoot, client, 'external-skills')));
-  }
+  assert.equal(existsSync(join(root, '.claude/external-skills')), false);
+  assert.ok(result.preserved.some(item => item.path === '.codex/external-skills'));
   assert.equal(read(root, '.pbai4devs/external-skills/.local/upstream-0/SKILL.md'), sourceBefore);
-  assert.equal(read(result.backupRoot, '.codex/external-skills/.local/upstream-0/SKILL.md'), '# Cópia indevida\n');
+  assert.equal(read(root, '.codex/external-skills/.local/upstream-0/SKILL.md'), '# Cópia indevida\n');
   assertCheckReadonly(root, {}, 0);
 });
 
-test('--force salva conteúdo próprio, repara ancestrais e preserva arquivos fora do escopo', t => {
+test('--force repara conteúdo registrado e preserva recursos humanos sem propriedade', t => {
   const root = fixture(t);
   run(root);
+  recordOwned(root, ['.claude/skills/projeto/demo/SKILL.md', '.kimi-code/agents/revisor.md']);
   write(root, '.claude/scripts/local.sh', 'script humano\n');
   write(root, '.claude/tools/program.exe', Buffer.from([1, 2, 3]));
   write(root, '.claude/docs/plain.md', '# Documento auxiliar\n');
   write(root, '.claude/skills/local.bin', 'custom\n');
   write(root, '.claude/skills/projeto/demo/SKILL.md', 'corrompido\n');
   write(root, '.kimi-code/agents/revisor.md', 'corrompido\n');
-  rmSync(join(root, '.codex/skills/outro'), { recursive: true });
-  write(root, '.codex/skills/outro', 'ancestral arquivo\n');
   write(root, '.github/prompts/edited.prompt.md', pointer() + '\nRevisar [manual](bar).\n');
   assertCheckReadonly(root);
   assertCheckReadonly(root, { force: true });
   rejected(root, {}, /--force/);
   const result = run(root, { force: true });
   assert.ok(result.backupRoot.startsWith(join(root, '.agent-tests')));
-  for (const path of ['.claude/scripts/local.sh', '.claude/tools/program.exe', '.claude/docs/plain.md', '.claude/skills/local.bin', '.claude/skills/projeto/demo/SKILL.md', '.kimi-code/agents/revisor.md', '.codex/skills/outro', '.github/prompts/edited.prompt.md']) assert.ok(existsSync(join(result.backupRoot, path)), `Backup ausente: ${path}`);
-  assert.deepEqual(readFileSync(join(result.backupRoot, '.claude/tools/program.exe')), Buffer.from([1, 2, 3]));
-  assert.equal(existsSync(join(root, '.claude/scripts')), false);
-  assert.equal(existsSync(join(root, '.claude/skills/local.bin')), false);
+  for (const path of ['.claude/skills/projeto/demo/SKILL.md', '.kimi-code/agents/revisor.md', '.github/prompts/edited.prompt.md']) assert.ok(existsSync(join(result.backupRoot, path)), `Backup ausente: ${path}`);
+  assert.deepEqual(readFileSync(join(root, '.claude/tools/program.exe')), Buffer.from([1, 2, 3]));
+  assert.equal(read(root, '.claude/scripts/local.sh'), 'script humano\n');
+  assert.equal(read(root, '.claude/skills/local.bin'), 'custom\n');
   assert.equal(existsSync(join(root, '.github/prompts/edited.prompt.md')), false);
   assert.match(read(root, '.codex/skills/outro/SKILL.md'), /name: outro/);
   assert.match(read(root, '.github/workflows/ci.yml'), /workflow-preservado/);
@@ -466,8 +464,8 @@ test('metadados incompletos, ausentes e com corpo são rejeitados antes de alter
   rejected(root, { force: true }, /Titulo/);
 });
 
-test('symlinks são rejeitados sem efeitos quando o sistema permite criá-los', t => {
-  for (const location of ['.claude/tools', '.pbai4devs/skills/projeto/demo/external.md', '.pbai4devs/skills.json', '.pbai4devs/espelhos.conf']) {
+test('symlinks canônicos são rejeitados sem efeitos quando o sistema permite criá-los', t => {
+  for (const location of ['.pbai4devs/skills/projeto/demo/external.md', '.pbai4devs/skills.json', '.pbai4devs/espelhos.conf']) {
     const root = fixture(t);
     rmSync(join(root, location), { recursive: true, force: true });
     try { symlinkSync(join(root, 'missing-target'), join(root, location)); }
@@ -500,6 +498,8 @@ test('registros não regulares são rejeitados sem efeitos', t => {
 test('backup recusa raiz simbólica antes de remover conteúdo próprio', t => {
   const root = fixture(t);
   run(root);
+  recordOwned(root, ['.claude/skills/projeto/demo/SKILL.md']);
+  write(root, '.claude/skills/projeto/demo/SKILL.md', 'registrado alterado\n');
   write(root, '.claude/scripts/own.sh', 'preservar\n');
   const outside = join(root, 'outside');
   mkdirSync(outside);
@@ -824,33 +824,33 @@ test('manifestos Antigravity acompanham skills, regras e agentes agrupados', t =
   write(root, '.pbai4devs/agents/review/security/AGENT.md', '---\nname: security\ndescription: Perfil.\n---\n\n# Perfil\n');
   write(root, '.pbai4devs/espelhos.conf', 'agente|.agents|agrupado\ndescoberta|.agents|antigravity\n');
   const before = snapshot(root);
-  assert.equal(run(root, { check: true }).exitCode, 1);
+  assert.equal(run(root, { check: true, generateEntrypoints: true }).exitCode, 1);
   assert.deepEqual(snapshot(root), before);
-  run(root);
+  run(root, { generateEntrypoints: true });
   assert.deepEqual(JSON.parse(read(root, '.agents/skills.json')).entries, [{ path: '.agents/skills/projeto/demo' }]);
   assert.deepEqual(JSON.parse(read(root, '.agents/rules.json')).entries, [{ path: '.agents/rules/projeto/style/RULE.md' }]);
   assert.deepEqual(JSON.parse(read(root, '.agents/agents.json')).entries, [{ path: '.agents/agents/review/security/AGENT.md' }]);
   write(root, '.pbai4devs/skills/projeto/new-skill/SKILL.md', skill.replace('name: demo', 'name: new-skill'));
-  run(root);
+  run(root, { generateEntrypoints: true });
   assert.equal(JSON.parse(read(root, '.agents/skills.json')).entries.length, 2);
   rmSync(join(root, '.pbai4devs/skills/projeto/demo'), { recursive: true });
-  run(root);
+  run(root, { generateEntrypoints: true });
   assert.deepEqual(JSON.parse(read(root, '.agents/skills.json')).entries, [{ path: '.agents/skills/projeto/new-skill' }]);
   assert.equal(existsSync(join(root, '.agents/skills/projeto/demo')), false);
-  assertCheckReadonly(root, {}, 0);
+  assertCheckReadonly(root, { generateEntrypoints: true }, 0);
 });
 
-test('manifesto de descoberta customizado exige force e recebe backup', t => {
+test('manifesto de descoberta humano permanece intacto mesmo com force', t => {
   const root = fixture(t, true);
   write(root, source, skill);
   write(root, '.pbai4devs/espelhos.conf', 'agente|.agents|agrupado\ndescoberta|.agents|antigravity\n');
-  run(root);
-  const custom = '{"entries":[{"path":"custom/skill"}]}\n';
+  const custom = '{"entries":[{"path":".agents/skills/custom"}]}\n';
   write(root, '.agents/skills.json', custom);
-  rejected(root, {}, /force/);
-  const result = run(root, { force: true });
-  assert.equal(readFileSync(join(result.backupRoot, '.agents/skills.json'), 'utf8'), custom);
-  assertCheckReadonly(root, {}, 0);
+  const result = run(root, { force: true, generateEntrypoints: true });
+  assert.equal(read(root, '.agents/skills.json'), custom);
+  assert.ok(result.preserved.some(item => item.path === '.agents/skills.json'));
+  assert.ok(!result.ownedOutputs.includes('.agents/skills.json'));
+  assertCheckReadonly(root, { generateEntrypoints: true }, 0);
 });
 
 test('formatos desconhecidos ou fora do cliente falham antes de mutar', t => {