@pathbit/agentdevkit 0.0.10 → 0.0.12

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

@@ -119,15 +119,15 @@ test('desindexação não descarta edição humana staged com workingtree restau
   assert.equal(readFileSync(join(root, 'generated.md'), 'utf8'), 'gerado\n');
 });
 
-test('raízes dedicadas são locais, enquanto configurações de GitHub e VS Code são fontes', t => {
+test('configurações humanas dos clientes continuam versionáveis', t => {
   const root = fixture(t); git(root, ['init', '-q']);
   applyLocalIgnore(planLocalIgnore(root));
   put(root, '.codex/config.toml', 'local'); put(root, '.claude/settings.json', 'local');
   put(root, '.github/settings.json', 'fonte'); put(root, '.vscode/settings.json', 'fonte');
   git(root, ['add', '--all']);
   const tracked = git(root, ['ls-files', '-z']).split('\0');
-  assert.equal(tracked.includes('.codex/config.toml'), false);
-  assert.equal(tracked.includes('.claude/settings.json'), false);
+  assert.equal(tracked.includes('.codex/config.toml'), true);
+  assert.equal(tracked.includes('.claude/settings.json'), true);
   assert.ok(tracked.includes('.github/settings.json')); assert.ok(tracked.includes('.vscode/settings.json'));
 });
 

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

@@ -0,0 +1,318 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { join, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { createHash } from 'node:crypto';
+import { syncBuiltinESMExports } from 'node:module';
+import { projectRoot } from '../../lib/runtime.mjs';
+import { extractManagedBlock, managedBlockDigest } from '../../lib/managed-content.mjs';
+import { extractTomlManagedBlock } from '../../lib/managed-toml.mjs';
+import { isReference, synchronize } from '../SCRIPT.mjs';
+
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+const read = (root, path) => fs.readFileSync(join(root, path), 'utf8');
+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-mixed-')));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  put(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\nagente|.cursor|plano\n');
+  put(root, '.pbai4devs/skills/old/demo/SKILL.md', '---\nname: demo\ndescription: Demo.\n---\n\n# Demo\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;
+}
+
+test('sync complementa Markdown humano, preserva CRLF/metadados e acompanha só o bloco', t => {
+  const root = fixture(t), path = '.claude/skills/demo/SKILL.md';
+  const human = '\ufeff---\r\nname: meu-demo\r\ncustom: manter\r\n---\r\n\r\n# Minhas instrucoes\r\n\r\nTexto humano sem newline';
+  put(root, path, human);
+  if (process.platform !== 'win32') fs.chmodSync(join(root, path), 0o640);
+  const mode = fs.statSync(join(root, path)).mode & 0o777;
+  const result = run(root);
+  const actual = read(root, path), block = extractManagedBlock(actual);
+  assert.ok(actual.startsWith(human));
+  assert.match(block, /old\/demo\/SKILL\.md/);
+  assert.ok(block.includes('\r\n'));
+  assert.equal(fs.statSync(join(root, path)).mode & 0o777, mode);
+  assert.equal(result.managedBlocks[path], managedBlockDigest(actual));
+  assert.ok(!result.ownedOutputs.includes(path));
+  const state = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  assert.equal(state.blocks[path], managedBlockDigest(actual));
+  assert.equal(state.files[path], undefined);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  run(root, { force: true });
+  assert.equal(read(root, path), actual);
+  put(root, path, actual + '\r\nOutro texto humano.\r\n');
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  fs.mkdirSync(join(root, '.pbai4devs/skills/new'), { recursive: true });
+  fs.renameSync(join(root, '.pbai4devs/skills/old/demo'), join(root, '.pbai4devs/skills/new/demo'));
+  run(root);
+  const updated = read(root, path);
+  assert.ok(updated.startsWith(human));
+  assert.ok(updated.endsWith('\r\nOutro texto humano.\r\n'));
+  assert.match(extractManagedBlock(updated), /new\/demo\/SKILL\.md/);
+  assert.equal(updated.split('<!-- BEGIN AGENTDEVKIT -->').length, 2);
+});
+
+test('sync promove apontamento editado por humano e nunca força um bloco alterado', t => {
+  const root = fixture(t), path = '.claude/skills/demo/SKILL.md';
+  run(root);
+  const generated = read(root, path);
+  const edited = generated.replace('description: Demo.', 'description: Escolha humana.') + '\nMinhas regras extras.\n';
+  put(root, path, edited);
+  run(root, { force: true });
+  const mixed = read(root, path);
+  assert.ok(mixed.startsWith(edited));
+  assert.ok(!run(root, { check: true }).ownedOutputs.includes(path));
+  const changed = mixed.replace(extractManagedBlock(mixed), extractManagedBlock(mixed).replace('Leia e siga [origem]', 'Leia [origem humana]'));
+  put(root, path, changed);
+  for (const options of [{}, { force: true }, { check: true }]) {
+    assert.throws(() => run(root, options), { code: 'E_MANAGED_BLOCK' });
+    assert.equal(read(root, path), changed);
+  }
+});
+
+test('remover recurso ou cliente retira somente bloco próprio de Markdown misto', t => {
+  for (const change of ['resource', 'client']) {
+    const root = fixture(t), path = '.claude/skills/demo/SKILL.md', human = '# Humano\n\nMinha skill.\n';
+    put(root, path, human); run(root);
+    const mixed = read(root, path), outside = mixed.replace(extractManagedBlock(mixed), '');
+    if (change === 'resource') fs.rmSync(join(root, '.pbai4devs/skills/old/demo'), { recursive: true });
+    else put(root, '.pbai4devs/espelhos.conf', 'agente|.cursor|plano\n');
+    run(root);
+    assert.equal(read(root, path), outside);
+    assert.ok(read(root, path).startsWith(human));
+    assert.equal(JSON.parse(read(root, '.pbai4devs/estado/derived.json')).blocks?.[path], undefined);
+    assert.equal(run(root, { check: true }).exitCode, 0);
+  }
+});
+
+test('entradas raiz com caixa existente recebem só a referência e mantêm alterações humanas', t => {
+  const root = fixture(t), paths = ['agents.md', 'claude.md', 'Gemini.md'];
+  for (const path of paths) put(root, path, `# Minhas instrucoes de ${path}\n\nNao apague.\n`);
+  const before = Object.fromEntries(paths.map(path => [path, read(root, path)]));
+  const result = run(root);
+  for (const path of paths) {
+    assert.ok(read(root, path).startsWith(before[path]));
+    assert.ok(result.managedBlocks[path]);
+    assert.ok(!result.ownedOutputs.includes(path));
+  }
+  assert.match(extractManagedBlock(read(root, 'claude.md')), /@agents\.md/);
+  assert.match(extractManagedBlock(read(root, 'Gemini.md')), /@\.\/agents\.md/);
+  for (const path of ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md']) assert.ok(!fs.readdirSync(root).includes(path));
+  put(root, 'agents.md', read(root, 'agents.md') + '\nTexto depois.\n');
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  const beforeRepeat = hash(read(root, 'agents.md')); run(root, { force: true });
+  assert.equal(hash(read(root, 'agents.md')), beforeRepeat);
+});
+
+test('comando TOML existente recebe referência dentro do prompt e mantém metadados', t => {
+  const root = fixture(t), path = '.gemini/commands/check.toml';
+  put(root, '.pbai4devs/espelhos.conf', 'agente|.gemini|plano\n');
+  put(root, '.pbai4devs/commands/check/COMMAND.md', '---\ndescription: Check.\n---\n\n# Check\n');
+  const before = 'description = "Escolha humana"\r\nprompt = \'Meu comando {{args}}\'\r\n# Comentario humano\r\n';
+  put(root, path, before);
+  const result = run(root);
+  const after = read(root, path);
+  assert.ok(after.startsWith('description = "Escolha humana"\r\n'));
+  assert.ok(after.endsWith('\r\n# Comentario humano\r\n'));
+  assert.match(after, /Meu comando \{\{args\}\}/);
+  assert.match(extractTomlManagedBlock(after), /@\{\.pbai4devs\/commands\/check\/COMMAND\.md\}/);
+  assert.ok(result.managedBlocks[path]);
+  assert.ok(!result.ownedOutputs.includes(path));
+  assert.equal(run(root, { check: true }).exitCode, 0);
+  run(root, { force: true }); assert.equal(read(root, path), after);
+});
+
+test('retirada standalone registra tombstone para bloco do estado instalado', t => {
+  const root = fixture(t), path = '.claude/skills/demo/SKILL.md';
+  put(root, path, '# Human\n'); run(root);
+  const block = managedBlockDigest(read(root, path));
+  put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { [path]: block } }));
+  fs.rmSync(join(root, '.pbai4devs/skills/old/demo'), { recursive: true });
+  run(root);
+  const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  assert.ok(derived.removedBlocks.includes(path));
+  assert.equal(extractManagedBlock(read(root, path)), null);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});
+
+test('stage pode gerar referências sem gravar estado derivado', t => {
+  const root = fixture(t);
+  run(root, { generateEntrypoints: false, recordDerivedState: false });
+  assert.ok(fs.existsSync(join(root, '.claude/skills/demo/SKILL.md')));
+  assert.ok(!fs.existsSync(join(root, '.pbai4devs/estado/derived.json')));
+});
+
+test('regra Cursor mantém globs e modo humanos ao receber referência', t => {
+  const root = fixture(t), path = '.cursor/rules/code.mdc';
+  put(root, '.pbai4devs/espelhos.conf', read(root, '.pbai4devs/espelhos.conf') + 'formato|.cursor|rules|mdc\n');
+  put(root, '.pbai4devs/rules/code/RULE.md', '---\ntrigger: always_on\ndescription: Canonical.\n---\n\n# Rule\n');
+  const human = '---\ndescription: Minha regra\nglobs: src/custom/**\nalwaysApply: false\n---\n\n# Regra própria\n\nConserve isto.\n';
+  put(root, path, human);
+  const result = run(root);
+  assert.ok(read(root, path).startsWith(human));
+  assert.equal(result.managedBlocks[path], managedBlockDigest(read(root, path)));
+  assert.ok(!result.ownedOutputs.includes(path));
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});
+
+test('edição humana durante planejamento não é sobrescrita pelo merge calculado antes', t => {
+  const root = fixture(t), path = '.claude/skills/demo/SKILL.md', before = '# Humano antes\n', concurrent = '# Humano durante planejamento\n';
+  put(root, path, before);
+  const originalRead = fs.readFileSync;
+  let injected = false;
+  t.mock.method(fs, 'readFileSync', (file, ...options) => {
+    const result = originalRead(file, ...options);
+    if (!injected && String(file) === join(root, '.pbai4devs/templates/entrypoints/AGENTS.md')) {
+      injected = true;
+      fs.writeFileSync(join(root, path), concurrent);
+    }
+    return result;
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root), /Arquivo mudou apos planejar/);
+  assert.equal(injected, true);
+  assert.equal(read(root, path), concurrent);
+  assert.ok(!fs.existsSync(join(root, '.pbai4devs/catalog.json')));
+});
+
+test('apontamento gerado que recebe edição concorrente antes do snapshot é preservado', t => {
+  const root = fixture(t), path = '.claude/skills/demo/SKILL.md', concurrent = '# Novo texto humano\n';
+  run(root);
+  const previousCatalog = read(root, '.pbai4devs/catalog.json');
+  put(root, '.pbai4devs/skills/old/demo/SKILL.md', '---\nname: demo\ndescription: Updated.\n---\n\n# Demo\n');
+  const originalRead = fs.readFileSync;
+  let injected = false;
+  t.mock.method(fs, 'readFileSync', (file, ...options) => {
+    const result = originalRead(file, ...options);
+    if (!injected && String(file) === join(root, '.pbai4devs/templates/entrypoints/AGENTS.md')) {
+      injected = true;
+      fs.writeFileSync(join(root, path), concurrent);
+    }
+    return result;
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root), /Arquivo mudou apos planejar/);
+  assert.equal(injected, true);
+  assert.equal(read(root, path), concurrent);
+  assert.equal(read(root, '.pbai4devs/catalog.json'), previousCatalog);
+});
+
+test('destino nativo customizado mantém compatibilidade e complementa o arquivo humano', t => {
+  const root = fixture(t), path = '.claude/custom.md', human = '# Meu documento\n';
+  put(root, path, human);
+  put(root, '.pbai4devs/espelhos.conf', read(root, '.pbai4devs/espelhos.conf') + `nativo|${path}|.pbai4devs/skills/old/demo/SKILL.md\n`);
+  const result = run(root, { force: true });
+  assert.ok(read(root, path).startsWith(human));
+  assert.match(read(root, path), /<!-- BEGIN AGENTDEVKIT -->/);
+  assert.ok(result.managedBlocks[path]);
+  assert.ok(!result.ownedOutputs.includes(path));
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});
+
+test('alteração apenas no YAML não pode ser apagada como wrapper integralmente gerado', t => {
+  for (const stale of [false, true]) {
+    const root = fixture(t), path = '.claude/skills/demo/SKILL.md';
+    run(root);
+    const human = read(root, path).replace('description: Demo.', 'description: Metadado humano.');
+    put(root, path, human);
+    if (stale) fs.rmSync(join(root, '.pbai4devs/skills/old/demo'), { recursive: true });
+    const result = run(root, { force: true });
+    assert.ok(read(root, path).startsWith(human));
+    assert.ok(!result.ownedOutputs.includes(path));
+    if (stale) assert.equal(read(root, path), human);
+    else assert.ok(result.managedBlocks[path]);
+    assert.equal(run(root, { check: true }).exitCode, 0);
+    run(root, { force: true });
+    assert.ok(read(root, path).startsWith(human));
+  }
+});
+
+test('destino Markdown com extensão em maiúsculas também preserva conteúdo humano', t => {
+  const root = fixture(t), path = '.claude/custom.MD', human = '# Humano\n';
+  put(root, path, human);
+  put(root, '.pbai4devs/espelhos.conf', read(root, '.pbai4devs/espelhos.conf') + `nativo|${path}|.pbai4devs/skills/old/demo/SKILL.md\n`);
+  const result = run(root);
+  assert.ok(result.managedBlocks[path]);
+  assert.ok(read(root, path).startsWith(human));
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});
+
+test('marcador legado sem hash não autoriza substituir ou remover texto humano', t => {
+  for (const stale of [false, true]) {
+    const root = fixture(t), path = '.claude/skills/demo/SKILL.md';
+    const human = '---\ndescription: Metadado humano\n---\n\n# Escolha humana\n\n<!-- gerado: sincronizar-agentes -->\nLeia e siga [origem](../../origem.md).\n';
+    assert.equal(isReference(human), true);
+    put(root, path, human);
+    if (stale) fs.rmSync(join(root, '.pbai4devs/skills/old/demo'), { recursive: true });
+    const result = run(root, { force: true });
+    assert.ok(read(root, path).startsWith(human));
+    assert.ok(!result.ownedOutputs.includes(path));
+    if (stale) assert.equal(read(root, path), human);
+    else assert.ok(result.managedBlocks[path]);
+    assert.equal(run(root, { check: true }).exitCode, 0);
+    run(root, { force: true });
+    assert.ok(read(root, path).startsWith(human));
+  }
+});
+
+test('arquivo humano criado durante planejamento não é substituído por saída prevista', t => {
+  for (const path of ['.claude/skills/demo/SKILL.md', '.agents/skills.json', '.claude/.gitignore']) {
+    const root = fixture(t), human = path.endsWith('.json') ? '{"entries":[],"human":true}\n' : '# Criado durante planejamento\n';
+    if (path.startsWith('.agents/')) put(root, '.pbai4devs/espelhos.conf', read(root, '.pbai4devs/espelhos.conf') + 'agente|.agents|plano\ndescoberta|.agents|antigravity\n');
+    const originalRead = fs.readFileSync;
+    let injected = false;
+    t.mock.method(fs, 'readFileSync', (file, ...options) => {
+      const result = originalRead(file, ...options);
+      if (!injected && String(file) === join(root, '.pbai4devs/templates/entrypoints/AGENTS.md')) {
+        injected = true;
+        put(root, path, human);
+      }
+      return result;
+    });
+    syncBuiltinESMExports();
+    try {
+      assert.throws(() => run(root, { force: true }), /Arquivo mudou apos planejar/);
+      assert.equal(injected, true, path);
+      assert.equal(read(root, path), human, path);
+      assert.ok(!fs.existsSync(join(root, '.pbai4devs/catalog.json')), path);
+    } finally {
+      t.mock.restoreAll(); syncBuiltinESMExports();
+    }
+  }
+});
+
+test('arquivo misto removido é recriado sem conservar propriedade do bloco ausente', t => {
+  for (const path of ['.claude/skills/demo/SKILL.md', 'AGENTS.md']) {
+    const root = fixture(t);
+    put(root, path, '# Humano\n'); run(root);
+    const hash = managedBlockDigest(read(root, path));
+    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: {}, blocks: { [path]: hash } }));
+    fs.rmSync(join(root, path));
+    run(root);
+    const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+    assert.ok(derived.removedBlocks.includes(path));
+    assert.ok(derived.files?.[path] || derived.entries?.[path]);
+    assert.equal(extractManagedBlock(read(root, path)), null);
+    assert.equal(run(root, { check: true }).exitCode, 0);
+  }
+});
+
+test('renomear caixa de entrada mista transfere só a propriedade do bloco', t => {
+  const root = fixture(t), before = '# Humano\n';
+  put(root, 'AGENTS.md', before); run(root);
+  const hash = managedBlockDigest(read(root, 'AGENTS.md'));
+  put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { 'AGENTS.md': hash } }));
+  fs.renameSync(join(root, 'AGENTS.md'), join(root, 'agents.md'));
+  const result = run(root);
+  const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  assert.ok(read(root, 'agents.md').startsWith(before));
+  assert.ok(derived.removedBlocks.includes('AGENTS.md'));
+  assert.equal(derived.blocks['agents.md'], result.managedBlocks['agents.md']);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});

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

@@ -12,6 +12,7 @@ import { mergeGitignore, ignoreBegin, ignoreEnd, validateIgnoreClients } from '.
 import './LOCAL_IGNORE.mjs';
 import './HUMAN_OWNERSHIP.mjs';
 import './COEXISTENCE.mjs';
+import './MANAGED_CONTENT.mjs';
 import { validateCatalog as validateExternalCatalog } from '../../gerenciar-skills-externas/SCRIPT.mjs';
 
 const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
@@ -22,7 +23,11 @@ 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 recordOwned = (root, paths) => {
+  const statePath = '.pbai4devs/estado/agentdevkit.json';
+  const previous = existsSync(join(root, statePath)) ? JSON.parse(read(root, statePath)) : {};
+  write(root, statePath, JSON.stringify({ schemaVersion: 1, files: { ...previous.files, ...Object.fromEntries(paths.map(path => [path, createHash('sha256').update(readFileSync(join(root, path))).digest('hex')])) }, blocks: previous.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 });
@@ -53,6 +58,7 @@ function fixture(t, minimal = false) {
     'nativo|.opencode/agents/revisor/AGENT.md|.pbai4devs/agents/revisor/AGENT.md|.pbai4devs/agents/revisor/opencode.yaml',
   ].join('\n') + '\n');
   if (minimal) return root;
+  const ownedLegacy = ['.opencode/agents/revisor/AGENT.md'];
   write(root, source, skill);
   write(root, '.pbai4devs/skills/grupo com espaço/outro/SKILL.md', '---\nname: outro\ndescription: Outro.\n---\n\n# Outro\n');
   write(root, '.pbai4devs/agents/revisor/AGENT.md', '---\nname: revisor\ndescription: Perfil.\n---\n\n# Revisor\n');
@@ -71,14 +77,19 @@ function fixture(t, minimal = false) {
   write(root, 'README.md', 'README raiz preservado\n');
   for (const kind of ['templates', 'scripts', 'tools', 'external-skills', 'estado', 'tests', 'docs', 'adapters', 'extra']) {
     write(root, `.pbai4devs/${kind}/demo/REFERENCE.md`, '---\ndescription: Exclusivo.\n---\n\n# Exclusivo\n');
-    if (kind !== 'extra') write(root, `.claude/${kind}/demo/REFERENCE.md`, pointer(`../../../.pbai4devs/${kind}/demo/REFERENCE.md`));
+    if (kind !== 'extra') {
+      const target = `.claude/${kind}/demo/REFERENCE.md`;
+      write(root, target, pointer(`../../../.pbai4devs/${kind}/demo/REFERENCE.md`)); ownedLegacy.push(target);
+    }
   }
   write(root, '.pbai4devs/tools/demo/TOOL.json', JSON.stringify(toolConfig()));
   write(root, '.pbai4devs/tools/demo/SCRIPT.mjs', toolWrapper('demo'));
   for (const file of ['README.md', 'INSTRUCTIONS.md']) {
     write(root, `.pbai4devs/${file}`, '---\ndescription: Guia.\n---\n\n# Guia\n');
     write(root, `.claude/${file}`, pointer(`../.pbai4devs/${file}`, 'Guia'));
+    ownedLegacy.push(`.claude/${file}`);
   }
+  recordOwned(root, ownedLegacy);
   return root;
 }
 function rejected(root, options = {}, pattern) {
@@ -120,7 +131,7 @@ test('sincroniza somente principais, preserva metadados e usa referências UTF-8
   assert.deepEqual(snapshot(root), before, 'A segunda sincronização deve ser idempotente.');
 });
 
-test('metadados genericos seguem a origem e overrides nativos ficam no YAML central', t => {
+test('metadados gerados seguem a origem e metadados editados pelo humano permanecem', t => {
   const root = fixture(t); run(root);
   write(root, '.pbai4devs/commands/check/COMMAND.md', '---\nname: check-novo\ndescription: Comando atualizado.\n---\n\n# Comando\n');
   write(root, '.pbai4devs/rules/example/RULE.md', '---\ntrigger: glob\nglobs: "**/*.ts"\ndescription: Regra atualizada.\n---\n\n# Regra\n');
@@ -128,8 +139,8 @@ test('metadados genericos seguem a origem e overrides nativos ficam no YAML cent
   write(root, '.codex/commands/check.md', read(root, '.codex/commands/check.md').replace('description: Comando.', 'description: Obsoleto.\nlocal-only: true'));
   assertCheckReadonly(root);
   run(root);
-  assert.match(read(root, '.codex/commands/check.md'), /name: check-novo\ndescription: Comando atualizado\./);
-  assert.doesNotMatch(read(root, '.codex/commands/check.md'), /Obsoleto|local-only/);
+  assert.match(read(root, '.codex/commands/check.md'), /description: Obsoleto\.\nlocal-only: true/);
+  assert.match(read(root, '.codex/commands/check.md'), /<!-- BEGIN AGENTDEVKIT -->/);
   assert.match(read(root, '.codex/rules/example.md'), /trigger: glob\nglobs: "\*\*\/\*\.ts"/);
   assert.match(read(root, '.codex/agents/revisor.md'), /Perfil atualizado\./);
   assert.match(read(root, '.opencode/agents/revisor/AGENT.md'), /edit: deny/);
@@ -174,6 +185,7 @@ test('Gemini usa TOML com inclusao relativa ao workspace e argumentos, sem Markd
   const root = fixture(t);
   write(root, '.pbai4devs/commands/check/COMMAND.md', '---\ndescription: "Verifica \\"aspas\\" e regras."\n---\n\n# Check\n');
   write(root, '.gemini/commands/check.md', pointer('../../.pbai4devs/commands/check/COMMAND.md'));
+  recordOwned(root, ['.gemini/commands/check.md']);
   run(root);
   const target = '.gemini/commands/check.toml';
   const text = read(root, target); const lines = text.trimEnd().split('\n');
@@ -182,12 +194,18 @@ test('Gemini usa TOML com inclusao relativa ao workspace e argumentos, sem Markd
   assert.equal(JSON.parse(lines[2].slice('prompt = '.length)), '@{.pbai4devs/commands/check/COMMAND.md}\n\n{{args}}');
   assert.ok(isReference(text)); assert.equal(existsSync(join(root, '.gemini/commands/check.md')), false);
   write(root, target, text + '# instrucao propria\n');
-  assertCheckReadonly(root); rejected(root, {}, /--force/);
+  assertCheckReadonly(root);
   const repaired = run(root, { force: true });
-  assert.equal(read(repaired.backupRoot, target), text + '# instrucao propria\n');
-  assert.equal(read(root, target), text);
+  assert.ok(repaired.managedBlocks[target]);
+  assert.match(read(root, target), /# instrucao propria/);
+  assert.match(read(root, target), /BEGIN AGENTDEVKIT/);
   rmSync(join(root, '.pbai4devs/commands/check'), { recursive: true });
-  run(root); assert.equal(existsSync(join(root, target)), false);
+  run(root);
+  const stripped = read(root, target).split('\n');
+  assert.equal(stripped[0], '# gerado: sincronizar-agentes');
+  assert.equal(stripped[1], lines[1]);
+  assert.equal(JSON.parse(stripped[2].slice('prompt = '.length)).trimEnd(), '@{.pbai4devs/commands/check/COMMAND.md}\n\n{{args}}');
+  assert.equal(stripped[3], '# instrucao propria');
   assert.match(read(root, '.github/workflows/ci.yml'), /workflow-preservado/);
 });
 
@@ -349,16 +367,16 @@ test('skills externas baixadas não entram nos índices; cópias humanas permane
   const sourceBefore = read(root, '.pbai4devs/external-skills/.local/upstream-0/SKILL.md');
   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);
+  assertCheckReadonly(root, {}, 0);
   const result = run(root, { force: true });
-  assert.equal(existsSync(join(root, '.claude/external-skills')), false);
+  assert.equal(read(root, '.claude/external-skills/README.md'), pointer('../../.pbai4devs/external-skills/README.md'));
   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(root, '.codex/external-skills/.local/upstream-0/SKILL.md'), '# Cópia indevida\n');
   assertCheckReadonly(root, {}, 0);
 });
 
-test('--force repara conteúdo registrado e preserva recursos humanos sem propriedade', t => {
+test('--force complementa conteúdo editado e preserva recursos humanos', t => {
   const root = fixture(t);
   run(root);
   recordOwned(root, ['.claude/skills/projeto/demo/SKILL.md', '.kimi-code/agents/revisor.md']);
@@ -371,14 +389,16 @@ test('--force repara conteúdo registrado e preserva recursos humanos sem propri
   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/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}`);
+  for (const path of ['.claude/skills/projeto/demo/SKILL.md', '.kimi-code/agents/revisor.md']) {
+    assert.ok(read(root, path).startsWith('corrompido\n'));
+    assert.ok(result.managedBlocks[path]);
+    assert.ok(!result.ownedOutputs.includes(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, '.github/prompts/edited.prompt.md'), /Revisar \[manual\]/);
   assert.match(read(root, '.codex/skills/outro/SKILL.md'), /name: outro/);
   assert.match(read(root, '.github/workflows/ci.yml'), /workflow-preservado/);
   assert.match(read(root, '.codex/config.toml'), /config-native-preservada/);
@@ -403,7 +423,7 @@ test('atualiza fontes, adiciona clientes, remove recursos e migra agrupado para
   assertCheckReadonly(root, {}, 0);
 });
 
-test('remove linhas legadas e origens nativas ausentes sem replicar documentos', t => {
+test('remove linhas legadas e preserva arquivos sem prova de propriedade', t => {
   const root = fixture(t);
   run(root);
   write(root, 'docs/produto/prd/demo/PRD.md', '# Produto real\n');
@@ -414,8 +434,8 @@ test('remove linhas legadas e origens nativas ausentes sem replicar documentos',
   assertCheckReadonly(root);
   run(root);
   assert.doesNotMatch(read(root, '.pbai4devs/espelhos.conf'), /documento\||missing/);
-  assert.equal(existsSync(join(root, '.claude/manual/DOC.md')), false);
-  assert.equal(existsSync(join(root, '.github/prompts/missing.prompt.md')), false);
+  assert.equal(existsSync(join(root, '.claude/manual/DOC.md')), true);
+  assert.equal(existsSync(join(root, '.github/prompts/missing.prompt.md')), true);
   assert.ok(existsSync(join(root, 'docs/produto/prd/demo/PRD.md')));
   assert.ok(existsSync(join(root, 'manual/guia com espaço/DOC.md')));
   assertCheckReadonly(root, {}, 0);
@@ -441,8 +461,8 @@ test('colisões de destino, ancestral, metadados e slugs não são resolvidas po
     let extra;
     if (variant === 'slug') write(root, '.pbai4devs/skills/duplicado/demo/SKILL.md', skill);
     if (variant === 'source') extra = 'nativo|.codex/skills/demo/SKILL.md|.pbai4devs/commands/check/COMMAND.md';
-    if (variant === 'ancestor') extra = [`nativo|.github/custom.md|${source}`, `nativo|.github/custom.md/child.md|${source}`].join('\n');
-    if (variant === 'target-case') extra = [`nativo|.github/custom.md|${source}`, `nativo|.github/CUSTOM.md|${source}`].join('\n');
+    if (variant === 'ancestor') extra = [`nativo|.github/prompts/custom.md|${source}`, `nativo|.github/prompts/custom.md/child.md|${source}`].join('\n');
+    if (variant === 'target-case') extra = [`nativo|.github/prompts/custom.md|${source}`, `nativo|.github/prompts/CUSTOM.md|${source}`].join('\n');
     if (variant === 'metadata') {
       write(root, '.pbai4devs/agents/revisor/other.yaml', '---\nname: other\n---\n');
       extra = 'nativo|.kimi-code/agents/revisor.md|.pbai4devs/agents/revisor/AGENT.md|.pbai4devs/agents/revisor/other.yaml';
@@ -498,8 +518,7 @@ 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, '.pbai4devs/templates/gitignore/shared.ignore', read(root, '.pbai4devs/templates/gitignore/shared.ignore') + '*.extra-local\n');
   write(root, '.claude/scripts/own.sh', 'preservar\n');
   const outside = join(root, 'outside');
   mkdirSync(outside);
@@ -550,7 +569,8 @@ test('gera manifesto e entradas sem estado e atualiza apenas entradas integralme
   const first = run(root, { generateEntrypoints: true });
   assert.ok(first.ownedOutputs.includes('AGENTS.md'));
   assert.equal(first.ownedOutputs.includes('CLAUDE.md'), false);
-  assert.equal(read(root, 'CLAUDE.md'), '# Instruções humanas\n');
+  assert.ok(read(root, 'CLAUDE.md').startsWith('# Instruções humanas\n'));
+  assert.match(read(root, 'CLAUDE.md'), /<!-- BEGIN AGENTDEVKIT -->/);
   assert.ok(existsSync(join(root, '.agents/skills/projeto/demo/SKILL.md')));
   assertCheckReadonly(root, { generateEntrypoints: true }, 0);
   write(root, '.pbai4devs/templates/entrypoints/AGENTS.md', '---\ndescription: Entrada.\n---\n\n# Atualizada\n');
@@ -562,7 +582,7 @@ test('gera manifesto e entradas sem estado e atualiza apenas entradas integralme
   assert.match(read(root, 'AGENTS.md'), /Texto humano/);
 });
 
-test('entradas da CLI usam ownership integral sem criar registro derivado redundante', t => {
+test('entradas da CLI mantêm ownership integral e recursos têm proveniência derivada', t => {
   const root = fixture(t, true);
   const template = '---\ndescription: Entrada.\n---\n\n# Agentes\n';
   const entry = template + '\nResponda em português.\n';
@@ -573,7 +593,8 @@ test('entradas da CLI usam ownership integral sem criar registro derivado redund
   const result = run(root, { generateEntrypoints: true });
   assert.ok(result.ownedOutputs.includes('AGENTS.md'));
   assert.equal(read(root, 'AGENTS.md'), entry);
-  assert.equal(existsSync(join(root, '.pbai4devs/estado/derived.json')), false);
+  assert.equal(JSON.parse(read(root, '.pbai4devs/estado/derived.json')).entries['AGENTS.md'], undefined);
+  assert.ok(JSON.parse(read(root, '.pbai4devs/estado/derived.json')).files['.codex/skills/demo/SKILL.md']);
   assertCheckReadonly(root, { generateEntrypoints: true }, 0);
 });