@pathbit/agentdevkit 0.0.11 → 0.0.12

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);
 });
 

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

@@ -2,9 +2,12 @@
 import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
 import { buildCatalog } from '../lib/catalog.mjs';
 import { isGeneratedOutput } from '../lib/gitignore.mjs';
+import { canonicalEntrypoint, extractManagedBlock, managedBlockDigest } from '../lib/managed-content.mjs';
+import { extractTomlManagedBlock, tomlManagedBlockDigest } from '../lib/managed-toml.mjs';
 
 const fail = message => { throw new Error(message); };
 const normalize = value => value.split(sep).join('/');
@@ -29,28 +32,38 @@ function checkedPath(root, path) {
 
 function ownership(root) {
   const file = checkedPath(root, '.pbai4devs/estado/agentdevkit.json');
-  if (!checkedStat(root, file)) return null;
+  const derivedFile = checkedPath(root, '.pbai4devs/estado/derived.json');
+  if (!checkedStat(root, file) && !checkedStat(root, derivedFile)) 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 state = checkedStat(root, file) ? readState(file) : { schemaVersion: 1, files: {}, blocks: {} };
   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');
+  const blocks = { ...state.blocks };
   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))
+    if (derived?.schemaVersion !== 1 || !validMap(derived.entries) || Object.keys(derived.entries).some(path => !canonicalEntrypoint(path))
+      || !validMap(derived.files ?? {}) || !validMap(derived.blocks ?? {})
+      || !Array.isArray(derived.removedBlocks ?? []) || (derived.removedBlocks ?? []).some(path => typeof path !== 'string')
       || !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);
+    Object.assign(files, derived.entries, derived.outputs, derived.files);
+    for (const [path, hash] of Object.entries({ ...derived.entries, ...derived.files })) {
+      const location = checkedPath(root, path);
+      if (checkedStat(root, location)?.isFile() && createHash('sha256').update(readFileSync(location)).digest('hex') === hash) delete blocks[path];
+    }
+    for (const path of derived.removedBlocks ?? []) { checkedPath(root, path); delete blocks[path]; }
+    Object.assign(blocks, derived.blocks);
   }
-  for (const path of [...Object.keys(files), ...Object.keys(state.blocks)]) {
+  for (const path of Object.keys(blocks)) delete files[path];
+  for (const path of [...Object.keys(files), ...Object.keys(blocks)]) {
     const location = checkedPath(root, path);
     if (!checkedStat(root, location)?.isFile()) fail(`Arquivo gerenciado ausente: ${path}`);
   }
-  return { files, blocks: state.blocks };
+  return { files, blocks };
 }
 
 export function registryRoots(root) {
@@ -151,6 +164,28 @@ export function localLinkTargets(text) {
   }).filter(Boolean);
 }
 
+export function checkManagedBlocks(root, blocks) {
+  for (const [path, expected] of Object.entries(blocks)) {
+    const toml = extname(path).toLowerCase() === '.toml';
+    if (!toml && !['.md', '.mdc'].includes(extname(path).toLowerCase())) continue;
+    const file = checkedPath(root, path), bytes = readFileSync(file);
+    if ((toml ? tomlManagedBlockDigest(bytes) : managedBlockDigest(bytes)) !== expected) fail(`Bloco AgentDevKit alterado ou ausente: ${path}`);
+    const block = toml ? extractTomlManagedBlock(bytes) : extractManagedBlock(bytes);
+    const imports = [...block.matchAll(/^@(?:\{([^}\r\n]+)\}|([^\r\n]+))$/gm)]
+      .filter(match => !match[2]?.startsWith('['))
+      .map(match => ({ target: match[1] || match[2], base: match[1] ? root : dirname(file) }));
+    for (const { target, base } of [...localLinkTargets(block).map(target => ({ target, base: dirname(file) })), ...imports]) {
+      const destination = resolve(base, target), local = normalize(relative(root, destination));
+      if (!local || isAbsolute(local) || local === '..' || local.startsWith('../')) fail(`Referencia fora do projeto: ${path}`);
+      if (canonicalEntrypoint(local)) {
+        // The user's root entry may be an existing link; do not follow it.
+        const item = lstatSync(destination);
+        if (!item.isFile() && !item.isSymbolicLink()) fail(`Referencia indisponivel: ${path}`);
+      } else if (!checkedStat(root, checkedPath(root, local))?.isFile()) fail(`Referencia indisponivel: ${path}`);
+    }
+  }
+}
+
 export function checkMarkdown(root, files, { virtualPaths = new Set() } = {}) {
   for (const file of files) {
     const label = normalize(relative(root, file));
@@ -237,6 +272,7 @@ export function verifyResources({ root = projectRoot, sourceOnly = false, synchr
   const files = collectMarkdown(root, registry, { installed });
   const virtualPaths = new Set(sourceOnly ? [...built.outputs.keys(), '.pbai4devs/espelhos.conf'] : []);
   checkMarkdown(root, files, { virtualPaths });
+  if (installed) checkManagedBlocks(root, installed.blocks);
   checkResourceReferences(root, files);
   checkAgentExtras(root, registry.agents, { installed });
   return { files, messages: [...lint(root, files), 'recursos=passed'] };

package/.pbai4devs/scripts/verificar-recursos/tests/TEST.mjs

@@ -162,10 +162,11 @@ test('instalação confere entradas derivadas sem aplicar lint a blocos humanos'
   const contents = document('# Entrada gerada\n');
   file('GEMINI.md', contents);
   file('.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: { 'GEMINI.md': createHash('sha256').update(contents).digest('hex') } }));
-  file('AGENTS.md', '# Instruções humanas sem frontmatter\n\n<!-- BEGIN AGENTDEVKIT -->\nLeia as fontes.\n<!-- END AGENTDEVKIT -->\n');
+  const block = '<!-- BEGIN AGENTDEVKIT -->\nLeia as fontes.\n<!-- END AGENTDEVKIT -->';
+  file('AGENTS.md', `# Instruções humanas sem frontmatter\n\n${block}\n`);
   const statePath = join(root, '.pbai4devs/estado/agentdevkit.json');
   const state = JSON.parse(readFileSync(statePath, 'utf8'));
-  state.blocks['AGENTS.md'] = createHash('sha256').update('bloco registrado').digest('hex');
+  state.blocks['AGENTS.md'] = createHash('sha256').update(block).digest('hex');
   state.files['.pbai4devs/skills/exemplo/SKILL.md'] = createHash('sha256').update('fonte anterior').digest('hex');
   writeFileSync(statePath, JSON.stringify(state));
   const result = verify(root);