@pathbit/agentdevkit 0.0.7 → 0.0.9

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

@@ -0,0 +1,151 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { syncBuiltinESMExports } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { projectRoot } from '../../lib/runtime.mjs';
+import { isReference, synchronize } from '../SCRIPT.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const source = '.pbai4devs/skills/demo/SKILL.md';
+const generated = '.claude/skills/demo/SKILL.md';
+const human = '# Título\n\nLeia [manual](https://example.com/manual).\n';
+function write(root, path, data) { fs.mkdirSync(dirname(join(root, path)), { recursive: true }); fs.writeFileSync(join(root, path), data); }
+function fixture(t) {
+  const root = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), 'agentdevkit-ownership-')));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  write(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\n');
+  write(root, source, '---\nname: demo\ndescription: Exemplo.\n---\n\n# Demo\n');
+  for (const name of ['agents.ignore', 'shared.ignore', 'local.ignore', 'clients.json']) write(root, `.pbai4devs/templates/gitignore/${name}`, fs.readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore', name)));
+  const initialized = spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+  assert.equal(initialized.status, 0, initialized.stderr);
+  return root;
+}
+const run = (root, options = {}) => synchronize({ root, generateEntrypoints: false, localIgnores: false, output() {}, ...options });
+function snapshot(root) {
+  const files = {};
+  function visit(path, prefix = '') {
+    for (const entry of fs.readdirSync(path, { withFileTypes: true })) {
+      if (entry.name === '.git') continue;
+      const next = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) { files[next] = 'directory'; visit(join(path, entry.name), next); }
+      else files[next] = hash(fs.readFileSync(join(path, entry.name)));
+    }
+  }
+  visit(root); return files;
+}
+
+test('texto humano com formato de referência nunca comprova propriedade', t => {
+  for (const path of [generated, '.claude/skills/human.md']) {
+    const root = fixture(t); write(root, path, human);
+    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);
+    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);
+  }
+});
+
+test('hash registrado comprova referência legada sem marcador e diretório vazio humano permanece', t => {
+  const root = fixture(t), stale = '.claude/skills/legacy.md';
+  write(root, stale, human);
+  write(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: { [stale]: hash(human) }, blocks: {} }));
+  fs.mkdirSync(join(root, '.claude/skills/user-empty'), { recursive: true });
+  run(root);
+  assert.equal(fs.existsSync(join(root, stale)), false);
+  assert.equal(fs.existsSync(join(root, '.claude/skills/user-empty')), true);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});
+
+test('conflito de ignore é recusado antes de criar recursos ou catálogos', t => {
+  const root = fixture(t); write(root, '.gitignore', '!/.agent-tests/\n!/.agent-tests/**\n');
+  const before = snapshot(root), exclude = fs.readFileSync(join(root, '.git/info/exclude'));
+  assert.throws(() => run(root, { localIgnores: true, force: true }), /Regras humanas/);
+  assert.deepEqual(snapshot(root), before);
+  assert.deepEqual(fs.readFileSync(join(root, '.git/info/exclude')), exclude);
+  assert.equal(fs.existsSync(join(root, generated)), false);
+  assert.equal(fs.existsSync(join(root, '.pbai4devs/catalog.json')), false);
+});
+
+test('atualização de referência própria conserva permissões', t => {
+  const root = fixture(t); run(root);
+  fs.chmodSync(join(root, generated), 0o600);
+  const mode = fs.statSync(join(root, generated)).mode & 0o777;
+  write(root, source, '---\nname: demo\ndescription: Atualizado.\n---\n\n# Demo\n');
+  run(root);
+  assert.equal(fs.statSync(join(root, generated)).mode & 0o777, mode);
+});
+
+test('mudança concorrente de ignore após gravação reverte recursos e preserva a regra humana', t => {
+  const root = fixture(t); run(root);
+  write(root, source, '---\nname: demo\ndescription: Atualizado.\n---\n\n# Demo\n');
+  const before = snapshot(root), rename = fs.renameSync;
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    rename(from, to);
+    if (!injected && to === join(root, generated)) { injected = true; write(root, '.git/info/exclude', '# concurrent human change\n'); }
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root, { localIgnores: true }), /Exclusao alterada apos planejar/);
+  assert.equal(injected, true);
+  assert.deepEqual(snapshot(root), before);
+  assert.equal(fs.readFileSync(join(root, '.git/info/exclude'), 'utf8'), '# concurrent human change\n');
+});
+
+test('conteúdo humano concorrente não é apagado durante rollback', t => {
+  const root = fixture(t), rename = fs.renameSync;
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    rename(from, to);
+    if (!injected && to === join(root, generated)) { injected = true; write(root, generated, human); }
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root), /Mudanca concorrente preservada/);
+  assert.equal(injected, true);
+  assert.equal(fs.readFileSync(join(root, generated), 'utf8'), human);
+});
+
+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');
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    rename(from, to);
+    if (!injected && to === join(root, generated)) { injected = true; write(root, generated, human); throw failure; }
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root), error => error instanceof AggregateError && error.errors.includes(failure));
+  assert.equal(injected, true);
+  assert.equal(fs.readFileSync(join(root, generated), 'utf8'), human);
+});
+
+test('rollback recria ancestral podado com suas permissões originais', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t); run(root);
+  const parent = join(root, '.claude/skills'); fs.chmodSync(parent, 0o700);
+  fs.rmSync(join(root, '.pbai4devs/skills/demo'), { recursive: true });
+  const before = snapshot(root), rename = fs.renameSync;
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    rename(from, to);
+    if (!injected && to === join(root, '.pbai4devs/catalog.json')) { injected = true; write(root, '.git/info/exclude', '# concurrent human change\n'); }
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root, { localIgnores: true }), /Exclusao alterada apos planejar/);
+  assert.equal(injected, true);
+  assert.deepEqual(snapshot(root), before);
+  assert.equal(fs.statSync(parent).mode & 0o777, 0o700);
+});

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

@@ -1,10 +1,12 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { syncBuiltinESMExports } from 'node:module';
 import { projectRoot } from '../../lib/runtime.mjs';
 import { planLocalIgnore, applyLocalIgnore, checkLocalIgnore, planUntrack, applyUntrack, restoreUntrack, assertLocalIgnoreUnchanged } from '../../lib/gitignore.mjs';
 
@@ -354,3 +356,145 @@ test('worktree usa a raiz nativa, exclude comum e seu próprio índice', t => {
   assert.equal(git(linked, ['show', ':generated.md']), 'gerado\n');
   assert.equal(git(root, ['ls-files', 'generated.md']), '');
 });
+
+test('exceções com nomes arbitrários de artefatos não passam por amostragem', t => {
+  for (const [name, directory] of [['.playwright-custom', true], ['.playwright-report.json', false], ['playwright-e2e', true]]) {
+    const root = fixture(t); git(root, ['init', '-q']);
+    const human = `!/${name}${directory ? '/' : ''}\n${directory ? `!/${name}/**\n` : ''}`;
+    put(root, '.gitignore', human);
+    const before = readFileSync(join(root, '.git/info/exclude'));
+    const plan = planLocalIgnore(root);
+    assert.ok(checkLocalIgnore(plan).missing.some(path => path.startsWith(name)), name);
+    assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+    assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), human);
+    assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), before);
+  }
+});
+
+test('arquivo real reaberto por glob é detectado também se surgir após o plano', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '!/.playwright-report-*.json\n');
+  const plan = planLocalIgnore(root), path = '.playwright-report-real.json';
+  put(root, path, 'artefato local\n');
+  assert.ok(checkLocalIgnore(plan).missing.includes(path));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.equal(readFileSync(join(root, path), 'utf8'), 'artefato local\n');
+});
+
+test('regras customizadas aninhadas continuam válidas e incluem pais ocultos', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const policy = readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore/agents.ignore'), 'utf8');
+  put(root, '.pbai4devs/templates/gitignore/agents.ignore', `${policy}\n**/reports/cache*/\n`);
+  const path = '.hidden/reports/cache-custom/out.json';
+  put(root, path, 'local\n');
+  put(root, '.gitignore', '!/.hidden/reports/cache-custom/\n!/.hidden/reports/cache-custom/**\n');
+  const plan = planLocalIgnore(root);
+  assert.ok(checkLocalIgnore(plan).missing.includes(path));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.equal(readFileSync(join(root, path), 'utf8'), 'local\n');
+});
+
+test('chaves literais em padrões Git não viram expansão de glob', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const policy = readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore/agents.ignore'), 'utf8');
+  put(root, '.pbai4devs/templates/gitignore/agents.ignore', `${policy}\n**/cache{keep,archive}/\n`);
+  put(root, 'cachekeep/source.txt', 'código humano\n');
+  put(root, '.gitignore', '!cachekeep/**\n');
+  assert.doesNotThrow(() => applyLocalIgnore(planLocalIgnore(root)));
+  assert.equal(readFileSync(join(root, 'cachekeep/source.txt'), 'utf8'), 'código humano\n');
+});
+
+test('exceção nominal de um ignore ancestral é conferida no subprojeto', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '!/modules/app/.playwright-personal/\n!/modules/app/.playwright-personal/**\n');
+  const child = join(root, 'modules/app'); mkdirSync(child, { recursive: true });
+  const plan = planLocalIgnore(child);
+  assert.ok(checkLocalIgnore(plan).missing.some(path => path.startsWith('.playwright-personal/')));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+});
+
+test('escrita de exclusões preserva permissões e detecta alteração concorrente', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const exclude = join(root, '.git/info/exclude'); chmodSync(exclude, 0o600);
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.equal(statSync(exclude).mode & 0o777, 0o600);
+  const changed = planLocalIgnore(root, { outputs: ['new-generated.md'] });
+  chmodSync(exclude, 0o640);
+  assert.throws(() => applyLocalIgnore(changed), /alterada apos planejar/);
+  assert.equal(statSync(exclude).mode & 0o777, 0o640);
+});
+
+test('fallback e rollback de exclusões mantêm o modo original', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t), ignore = join(root, '.gitignore');
+  put(root, '.gitignore', '# humano\n'); chmodSync(ignore, 0o600);
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.equal(statSync(ignore).mode & 0o777, 0o600);
+  const original = readFileSync(ignore); git(root, ['init', '-q']);
+  const exclude = join(root, '.git/info/exclude'), before = readFileSync(exclude);
+  chmodSync(exclude, 0o600);
+  const plan = planLocalIgnore(root); assert.equal(plan.edits.length, 2);
+  Object.defineProperty(plan.edits[1], 'after', { get() { throw new Error('injected rollback failure'); } });
+  assert.throws(() => applyLocalIgnore(plan), /injected rollback failure/);
+  assert.deepEqual(readFileSync(exclude), before); assert.equal(statSync(exclude).mode & 0o777, 0o600);
+  assert.deepEqual(readFileSync(ignore), original); assert.equal(statSync(ignore).mode & 0o777, 0o600);
+});
+
+test('rollback restaura exclusão somente leitura com escrita atômica', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t), ignore = join(root, '.gitignore');
+  put(root, '.gitignore', '# humano\n'); chmodSync(ignore, 0o444);
+  applyLocalIgnore(planLocalIgnore(root));
+  const original = readFileSync(ignore); git(root, ['init', '-q']);
+  const exclude = join(root, '.git/info/exclude'), before = readFileSync(exclude);
+  chmodSync(exclude, 0o444);
+  const plan = planLocalIgnore(root);
+  Object.defineProperty(plan.edits[1], 'after', { get() { throw new Error('readonly rollback probe'); } });
+  assert.throws(() => applyLocalIgnore(plan), /readonly rollback probe/);
+  assert.deepEqual(readFileSync(exclude), before); assert.equal(statSync(exclude).mode & 0o777, 0o444);
+  assert.deepEqual(readFileSync(ignore), original); assert.equal(statSync(ignore).mode & 0o777, 0o444);
+});
+
+test('projeto aninhado não lê gitignore inacessível do projeto irmão', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const other = join(root, 'other/.gitignore'); put(root, 'other/.gitignore', 'tmp/\n');
+  git(root, ['add', 'other/.gitignore']); chmodSync(other, 0o000);
+  t.after(() => { try { chmodSync(other, 0o600); } catch {} });
+  const child = join(root, 'app'); mkdirSync(child);
+  const plan = planLocalIgnore(child);
+  applyLocalIgnore(plan);
+  assert.equal(checkLocalIgnore(planLocalIgnore(child)).ok, true);
+});
+
+test('falha no cleanup após promoção ainda reverte a exclusão publicada', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const file = join(root, '.git/info/exclude'), original = readFileSync(file);
+  const plan = planLocalIgnore(root), remove = fs.rmSync;
+  const injected = new Error('published cleanup failure'); let failed = false;
+  try {
+    fs.rmSync = (path, options) => {
+      if (!failed && String(path).startsWith(`${file}.agentdevkit-`) && !existsSync(path)) { failed = true; throw injected; }
+      return remove(path, options);
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => applyLocalIgnore(plan), error => error === injected);
+  } finally { fs.rmSync = remove; syncBuiltinESMExports(); }
+  assert.equal(failed, true);
+  assert.deepEqual(readFileSync(file), original);
+});
+
+test('falha irrecuperável de rollback informa também o erro original', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const file = join(root, '.git/info/exclude'), plan = planLocalIgnore(root);
+  const remove = fs.rmSync, rename = fs.renameSync;
+  const original = new Error('original cleanup failure'), rollback = new Error('restore unavailable');
+  let failed = false;
+  try {
+    fs.rmSync = (path, options) => {
+      if (!failed && String(path).startsWith(`${file}.agentdevkit-`) && !existsSync(path)) { failed = true; throw original; }
+      return remove(path, options);
+    };
+    fs.renameSync = (from, to) => { if (failed && to === file) throw rollback; return rename(from, to); };
+    syncBuiltinESMExports();
+    assert.throws(() => applyLocalIgnore(plan), error => error instanceof AggregateError
+      && error.cause === original && error.errors.includes(rollback));
+  } finally { fs.rmSync = remove; fs.renameSync = rename; syncBuiltinESMExports(); }
+});

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

@@ -10,6 +10,8 @@ import { buildCatalog } from '../../lib/catalog.mjs';
 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)), '../../../..');
@@ -20,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 });
@@ -58,7 +61,7 @@ function fixture(t, minimal = false) {
   write(root, '.pbai4devs/agents/revisor/kimi-code.yaml', '---\nname: revisor\ntools: [Read, Grep, Glob]\n---\n');
   write(root, '.pbai4devs/agents/revisor/opencode.yaml', '---\nmode: subagent\npermission:\n  edit: deny\n---\n');
   write(root, '.pbai4devs/adapters/antigravity/agents/revisor.md', pointer('../../../agents/revisor/AGENT.md', 'Revisor'));
-  write(root, '.opencode/agents/revisor/AGENT.md', '---\nmode: subagent\npermission:\n  edit: deny\n---\n\n# Revisor\n\nLeia e siga [origem](../../../.pbai4devs/agents/revisor/AGENT.md).\n');
+  write(root, '.opencode/agents/revisor/AGENT.md', `---\nmode: subagent\npermission:\n  edit: deny\n---\n\n# Revisor\n\n${marker}\nLeia e siga [origem](../../../.pbai4devs/agents/revisor/AGENT.md).\n`);
   write(root, '.github/workflows/ci.yml', 'workflow-preservado\n');
   write(root, '.vscode/settings.json', '{"fixture":"config-preservada"}\n');
   write(root, '.vscode/extensions.json', '{"recommendations":[]}\n');
@@ -333,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()));
@@ -347,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/);
@@ -465,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)); }
@@ -499,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);
@@ -823,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 => {

package/.pbai4devs/scripts/verificar-recursos/SCRIPT.mjs

@@ -20,6 +20,39 @@ function checkedStat(root, location) {
   return item;
 }
 
+function checkedPath(root, path) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || /[\\\x00-\x1f\x7f:]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) fail(`Caminho gerenciado invalido: ${path}`);
+  let location = root;
+  for (const part of path.split('/')) { location = join(location, part); checkedStat(root, location); }
+  return location;
+}
+
+function ownership(root) {
+  const file = checkedPath(root, '.pbai4devs/estado/agentdevkit.json');
+  if (!checkedStat(root, file)) return null;
+  const readState = location => {
+    try { return JSON.parse(readFileSync(location, 'utf8')); }
+    catch { fail(`Estado invalido: ${normalize(relative(root, location))}`); }
+  };
+  const state = readState(file);
+  const validMap = value => value && typeof value === 'object' && !Array.isArray(value)
+    && Object.values(value).every(hash => typeof hash === 'string' && /^[a-f0-9]{64}$/.test(hash));
+  if (state?.schemaVersion !== 1 || !validMap(state.files) || !validMap(state.blocks)) fail('Estado de propriedade invalido.');
+  const files = { ...state.files };
+  const derivedFile = checkedPath(root, '.pbai4devs/estado/derived.json');
+  if (checkedStat(root, derivedFile)) {
+    const derived = readState(derivedFile);
+    if (derived?.schemaVersion !== 1 || !validMap(derived.entries) || Object.keys(derived.entries).some(path => !['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(path))
+      || !validMap(derived.outputs ?? {}) || Object.keys(derived.outputs ?? {}).some(path => !/^\.[a-z0-9][a-z0-9-]*\/(?:skills|rules|agents)\.json$/.test(path))) fail('Estado de entradas derivadas invalido.');
+    Object.assign(files, derived.entries, derived.outputs);
+  }
+  for (const path of [...Object.keys(files), ...Object.keys(state.blocks)]) {
+    const location = checkedPath(root, path);
+    if (!checkedStat(root, location)?.isFile()) fail(`Arquivo gerenciado ausente: ${path}`);
+  }
+  return { files, blocks: state.blocks };
+}
+
 export function registryRoots(root) {
   checkedStat(root, join(root, '.pbai4devs'));
   const file = join(root, '.pbai4devs/espelhos.conf');
@@ -44,7 +77,7 @@ function walk(root, location, files, { skipTools = true } = {}) {
   } else if (item.isFile() && ['.md', '.mdc'].includes(extname(location).toLowerCase())) files.add(location);
 }
 
-export function collectMarkdown(root, registry = registryRoots(root)) {
+export function collectMarkdown(root, registry = registryRoots(root), { installed = ownership(root) } = {}) {
   const agents = join(root, '.pbai4devs');
   checkedStat(root, agents);
   for (const directory of readdirSync(agents, { withFileTypes: true })) {
@@ -54,10 +87,18 @@ export function collectMarkdown(root, registry = registryRoots(root)) {
     if (item?.isDirectory() && !checkedStat(root, join(location, 'README.md'))?.isFile()) fail(`README ausente: .pbai4devs/${directory.name}/`);
   }
   const files = new Set();
-  const rootMarkdown = readdirSync(root).filter(name => ['.md', '.mdc'].includes(extname(name).toLowerCase()));
-  const sources = ['.pbai4devs', 'docs', 'src', 'bin', 'tests', 'scripts', 'examples',
-    '.github/PULL_REQUEST_TEMPLATE.md', '.github/ISSUE_TEMPLATE', ...rootMarkdown];
-  for (const name of [...sources, ...registry.paths]) walk(root, resolve(root, name), files);
+  if (installed) {
+    walk(root, agents, files);
+    for (const path of Object.keys(installed.files)) {
+      const file = checkedPath(root, path);
+      if (['.md', '.mdc'].includes(extname(path).toLowerCase())) files.add(file);
+    }
+  } else {
+    const rootMarkdown = readdirSync(root).filter(name => ['.md', '.mdc'].includes(extname(name).toLowerCase()));
+    const sources = ['.pbai4devs', 'docs', 'src', 'bin', 'tests', 'scripts', 'examples',
+      '.github/PULL_REQUEST_TEMPLATE.md', '.github/ISSUE_TEMPLATE', ...rootMarkdown];
+    for (const name of [...sources, ...registry.paths]) walk(root, resolve(root, name), files);
+  }
   const tools = join(agents, 'tools');
   if (checkedStat(root, tools)) {
     const guide = join(tools, 'README.md');
@@ -154,8 +195,14 @@ export function checkCatalog(root, build = buildCatalog) {
   return result.catalog;
 }
 
-export function checkAgentExtras(root, agents) {
+export function checkAgentExtras(root, agents, { installed = null } = {}) {
   for (const agent of agents) {
+    if (installed) {
+      const files = Object.keys(installed.files).filter(path => path.startsWith(`${agent}/`));
+      if (files.some(path => auxiliary.some(name => path === `${agent}/${name}` || path.startsWith(`${agent}/${name}/`)))) fail(`Auxiliar gerenciado indevido em ${agent}`);
+      if (files.some(path => ['README.md', 'INSTRUCTIONS.md'].includes(basename(path)))) fail(`Guia gerenciado indevido em ${agent}`);
+      continue;
+    }
     for (const name of auxiliary) if (existsSync(join(root, agent, name))) fail(`Auxiliar indevido em ${agent}/${name}`);
     const files = new Set();
     walk(root, join(root, agent), files);
@@ -183,14 +230,15 @@ export function checkLint(root, files, run = spawnSync) {
 
 export function verifyResources({ root = projectRoot, sourceOnly = false, synchronize = checkSynchronization, lint = checkLint, catalogCheck = checkCatalog } = {}) {
   requireNode();
+  const installed = sourceOnly ? null : ownership(root);
   const built = sourceOnly ? buildCatalog(root) : null;
   if (!sourceOnly) { synchronize(root); catalogCheck(root); }
   const registry = sourceOnly ? { agents: [], paths: [] } : registryRoots(root);
-  const files = collectMarkdown(root, registry);
+  const files = collectMarkdown(root, registry, { installed });
   const virtualPaths = new Set(sourceOnly ? [...built.outputs.keys(), '.pbai4devs/espelhos.conf'] : []);
   checkMarkdown(root, files, { virtualPaths });
   checkResourceReferences(root, files);
-  checkAgentExtras(root, registry.agents);
+  checkAgentExtras(root, registry.agents, { installed });
   return { files, messages: [...lint(root, files), 'recursos=passed'] };
 }