@pathbit/agentdevkit 0.0.23 → 0.0.25

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

@@ -0,0 +1,251 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { synchronize } from '../SCRIPT.mjs';
+import { entrypointReference, mergeManagedContent } from '../../lib/managed-content.mjs';
+import { mergeTomlContent } from '../../lib/managed-toml.mjs';
+
+const catalogs = ['catalog.json', 'skills.json', 'agents.json', 'rules.json'].map(name => `.pbai4devs/${name}`);
+const state = '.pbai4devs/state/derived.json';
+const original = '.pbai4devs/skills/demo/SKILL.md';
+const digest = bytes => createHash('sha256').update(bytes).digest('hex');
+const get = (root, path) => readFileSync(join(root, path));
+const put = (root, path, bytes) => { mkdirSync(dirname(join(root, path)), { recursive: true }); writeFileSync(join(root, path), bytes); };
+const gitEnvironment = root => ({ ...Object.fromEntries(Object.entries(process.env).filter(([key]) => !/^GIT_/i.test(key))), GIT_CONFIG_GLOBAL: join(root, '.git-config-ausente'), GIT_CONFIG_NOSYSTEM: '1', GIT_OPTIONAL_LOCKS: '0' });
+const sync = (root, options = {}) => {
+  // synchronize is synchronous and launches Git internally. Isolate only for
+  // this call so an inherited GIT_INDEX_FILE/GIT_DIR cannot touch another repo.
+  const saved = Object.fromEntries(Object.entries(process.env).filter(([key]) => /^GIT_/i.test(key)));
+  for (const key of Object.keys(saved)) delete process.env[key];
+  Object.assign(process.env, { GIT_CONFIG_GLOBAL: join(root, '.git-config-ausente'), GIT_CONFIG_NOSYSTEM: '1', GIT_OPTIONAL_LOCKS: '0' });
+  try { return synchronize({ root, localIgnores: false, generateEntrypoints: false, output() {}, ...options }); }
+  finally {
+    for (const key of Object.keys(process.env)) if (/^GIT_/i.test(key)) delete process.env[key];
+    Object.assign(process.env, saved);
+  }
+};
+function git(root, ...args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', env: gitEnvironment(root) });
+  assert.equal(result.status, 0, result.stderr);
+}
+function fixture(t) {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'adk-catalog-ownership-')));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  git(root, 'init', '-q');
+  put(root, '.gitignore', 'node_modules/\n');
+  put(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\n');
+  put(root, '.pbai4devs/templates/gitignore/agents.ignore', '# Cache\n/*\n!/.gitignore\n{{ALLOWLIST}}\n');
+  put(root, '.pbai4devs/templates/gitignore/clients.json', '{}\n');
+  put(root, '.pbai4devs/templates/gitignore/shared.ignore', '# Shared\n/tools/*/.local/\n');
+  put(root, original, '---\nname: demo\ndescription: Demo.\n---\n\n# Demo\n');
+  git(root, 'add', '-f', '.gitignore');
+  return root;
+}
+
+for (const path of catalogs) for (const force of [false, true]) {
+  test(`catálogo editado permanece intacto na sincronização direta: ${path}, force=${force}`, t => {
+    const root = fixture(t);
+    assert.equal(sync(root).exitCode, 0);
+    put(root, path, '{"human":"preservar"}\n');
+    git(root, 'add', '-f', '--', path);
+    const before = Object.fromEntries([path, state, '.gitignore', '.git/index'].map(name => [name, get(root, name)]));
+    assert.notEqual(sync(root, { check: true, force }).exitCode, 0);
+    assert.throws(() => sync(root, { force }), /Conteudo proprio preservado/);
+    for (const [name, content] of Object.entries(before)) assert.deepEqual(get(root, name), content, name);
+  });
+}
+
+test('catálogo anterior idêntico não é assumido como próprio sem estado', t => {
+  const root = fixture(t);
+  assert.equal(sync(root).exitCode, 0);
+  const recorded = JSON.parse(get(root, state));
+  delete recorded.catalogs;
+  put(root, state, `${JSON.stringify(recorded, null, 2)}\n`);
+  const before = Object.fromEntries([...catalogs, '.gitignore', '.git/index'].map(name => [name, get(root, name)]));
+  const result = sync(root, { force: true });
+  for (const path of catalogs) assert.ok(result.preserved.some(entry => entry.path === path && entry.reason === 'existing-catalog'), path);
+  assert.equal(JSON.parse(get(root, state)).catalogs, undefined);
+  for (const [name, content] of Object.entries(before)) assert.deepEqual(get(root, name), content, name);
+  put(root, original, '---\nname: demo\ndescription: Mudança humana.\n---\n\n# Demo\n');
+  assert.throws(() => sync(root, { force: true }), /Conteudo proprio preservado/);
+  for (const [name, content] of Object.entries(before)) assert.deepEqual(get(root, name), content, name);
+});
+
+test('sincronizações diretas sucessivas registram hashes dos catálogos criados', t => {
+  const root = fixture(t);
+  assert.equal(sync(root).exitCode, 0);
+  for (const path of catalogs) assert.equal(JSON.parse(get(root, state)).catalogs[path], digest(get(root, path)), path);
+  put(root, original, '---\nname: demo\ndescription: Nova descrição.\n---\n\n# Demo\n');
+  assert.equal(sync(root).exitCode, 0);
+  for (const path of catalogs) assert.equal(JSON.parse(get(root, state)).catalogs[path], digest(get(root, path)), path);
+  assert.equal(sync(root, { check: true }).exitCode, 0);
+});
+
+test('registro de catálogo desconhecido ou hash inválido bloqueia antes de alterar arquivos', t => {
+  const root = fixture(t);
+  assert.equal(sync(root).exitCode, 0);
+  const registry = JSON.parse(get(root, state));
+  registry.catalogs['.pbai4devs/other.json'] = 'a'.repeat(64);
+  put(root, state, JSON.stringify(registry));
+  const before = Object.fromEntries([...catalogs, state, '.gitignore', '.git/index'].map(name => [name, get(root, name)]));
+  assert.throws(() => sync(root, { force: true }), /Registro de catalogos derivados invalido/);
+  for (const [name, content] of Object.entries(before)) assert.deepEqual(get(root, name), content, name);
+  assert.ok(existsSync(join(root, original)));
+});
+
+for (const path of ['.pbai4devs/.gitignore', '.claude/.gitignore']) for (const force of [false, true]) {
+  test(`bloco ignore editado permanece intacto: ${path}, force=${force}`, t => {
+    const root = fixture(t);
+    assert.equal(sync(root).exitCode, 0);
+    const content = get(root, path).toString('utf8').replace('# BEGIN AGENT IGNORE', '# BEGIN AGENT IGNORE\n# Regra humana\n!/conteudo-humano/');
+    put(root, path, content);
+    git(root, 'add', '-f', '--', path);
+    const before = Object.fromEntries([path, state, '.gitignore', '.git/index'].map(name => [name, get(root, name)]));
+    assert.notEqual(sync(root, { check: true, force }).exitCode, 0);
+    assert.throws(() => sync(root, { force }), /Conteudo proprio preservado/);
+    for (const [name, bytes] of Object.entries(before)) assert.deepEqual(get(root, name), bytes, name);
+  });
+}
+
+for (const path of ['.pbai4devs/.gitignore', '.claude/.gitignore']) {
+  test(`bloco ignore igual sem comprovante não é adotado: ${path}`, t => {
+    const root = fixture(t);
+    assert.equal(sync(root).exitCode, 0);
+    const registry = JSON.parse(get(root, state));
+    delete registry.blocks[path];
+    put(root, state, JSON.stringify(registry, null, 2) + '\n');
+    const originalIgnore = get(root, path);
+    const result = sync(root, { force: true });
+    assert.ok(result.preserved.some(entry => entry.path === path && entry.reason === 'existing-ignore-block'));
+    assert.equal(JSON.parse(get(root, state)).blocks?.[path], undefined);
+    assert.deepEqual(get(root, path), originalIgnore);
+    const template = path.startsWith('.pbai4devs/') ? 'shared.ignore' : 'agents.ignore';
+    const templatePath = `.pbai4devs/templates/gitignore/${template}`;
+    put(root, templatePath, Buffer.concat([get(root, templatePath), Buffer.from('/novo-item/\n')]));
+    assert.throws(() => sync(root, { force: true }), /Conteudo proprio preservado/);
+    assert.deepEqual(get(root, path), originalIgnore);
+  });
+}
+
+test('bloco idêntico em AGENTS.md sem registro não é adotado', t => {
+  const root = fixture(t), path = 'AGENTS.md';
+  put(root, '.pbai4devs/templates/entrypoints/AGENTS.md', '# Instruções\n');
+  const content = mergeManagedContent('# Instruções humanas\n', entrypointReference(root, path)).text;
+  put(root, path, content);
+  const result = sync(root, { force: true, generateEntrypoints: true });
+  assert.ok(result.preserved.some(entry => entry.path === path && entry.reason === 'existing-managed-block'));
+  assert.equal(get(root, path).toString('utf8'), content);
+  const registry = JSON.parse(get(root, state));
+  assert.equal(registry.blocks?.[path], undefined);
+  assert.equal(registry.entries?.[path], undefined);
+  assert.equal(sync(root, { force: true, generateEntrypoints: true }).exitCode, 0);
+  assert.equal(get(root, path).toString('utf8'), content);
+});
+
+for (const kind of ['markdown', 'toml']) test(`bloco nativo ${kind} idêntico sem registro não é adotado`, t => {
+  const root = fixture(t);
+  const path = kind === 'markdown' ? '.claude/skills/demo/SKILL.md' : '.gemini/commands/demo.toml';
+  let content;
+  if (kind === 'markdown') {
+    content = mergeManagedContent('# Instruções humanas\n', 'Leia e siga [origem](../../../.pbai4devs/skills/demo/SKILL.md).').text;
+  } else {
+    put(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\nagente|.gemini|plano\n');
+    put(root, '.pbai4devs/commands/demo/COMMAND.md', '---\ndescription: Demo.\n---\n\n# Demo\n');
+    content = mergeTomlContent('description = "Humano"\nprompt = "Meu prompt"\n', '@{.pbai4devs/commands/demo/COMMAND.md}').text;
+  }
+  put(root, path, content);
+  const result = sync(root, { force: true });
+  assert.ok(result.preserved.some(entry => entry.path === path && entry.reason === 'existing-managed-block'));
+  assert.equal(get(root, path).toString('utf8'), content);
+  const registry = JSON.parse(get(root, state));
+  assert.equal(registry.blocks?.[path], undefined);
+  assert.equal(registry.files?.[path], undefined);
+  assert.equal(sync(root, { force: true }).exitCode, 0);
+  assert.equal(get(root, path).toString('utf8'), content);
+});
+
+for (const force of [false, true]) test(`configuração humana não é alterada nem adotada: force=${force}`, t => {
+  const root = fixture(t), path = '.pbai4devs/espelhos.conf';
+  const identical = get(root, path);
+  const result = sync(root, { force });
+  assert.ok(result.preserved.some(entry => entry.path === path && entry.reason === 'existing-configuration'));
+  assert.equal(JSON.parse(get(root, state)).config, undefined);
+  assert.deepEqual(get(root, path), identical);
+  put(root, path, Buffer.concat([identical, Buffer.from('documento|manual-humano\n')]));
+  git(root, 'add', '-f', '--', path);
+  const before = Object.fromEntries([path, state, '.gitignore', '.git/index'].map(name => [name, get(root, name)]));
+  assert.notEqual(sync(root, { check: true, force }).exitCode, 0);
+  assert.throws(() => sync(root, { force }), /Conteudo proprio preservado/);
+  for (const [name, content] of Object.entries(before)) assert.deepEqual(get(root, name), content, name);
+});
+
+test('overlay de configuração inválido não autoriza escrita', t => {
+  const root = fixture(t);
+  assert.equal(sync(root).exitCode, 0);
+  const registry = JSON.parse(get(root, state));
+  registry.config = 'nao-e-sha256';
+  put(root, state, JSON.stringify(registry));
+  const before = get(root, state);
+  assert.throws(() => sync(root, { force: true }), /Registro de configuracao derivada invalido/);
+  assert.deepEqual(get(root, state), before);
+});
+
+test('CLI reconhece catálogos da sincronização direta e preserva atualização de ignore', t => {
+  const root = realpathSync(mkdtempSync(join(tmpdir(), 'adk-cli-sync-ownership-')));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  git(root, 'init', '-q');
+  put(root, '.gitignore', 'node_modules/\n');
+  put(root, 'AGENTS.md', '# Instruções existentes\n');
+  put(root, 'staged.txt', 'Conteúdo staged humano.\n');
+  git(root, 'add', '-f', '.gitignore', 'AGENTS.md', 'staged.txt');
+  const initial = Object.fromEntries(['.gitignore', '.git/index', 'staged.txt'].map(path => [path, get(root, path)]));
+  const cliPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../bin/agentdevkit.mjs');
+  function runCli(...args) {
+    const result = spawnSync(process.execPath, [cliPath, ...args, '--target', root, '--json'], {
+      cwd: root, env: gitEnvironment(root), encoding: 'utf8', timeout: 90000, maxBuffer: 16 * 1024 * 1024,
+    });
+    let output; try { output = JSON.parse(result.stdout); } catch { assert.fail(`Resposta CLI inválida: ${result.stderr} ${result.stdout}`); }
+    assert.equal(result.status, 0, `${args.join(' ')}: ${result.stderr} ${result.stdout}`);
+    return output;
+  }
+  function direct() {
+    const result = spawnSync(process.execPath, [join(root, '.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs')], {
+      cwd: root, env: gitEnvironment(root), encoding: 'utf8', timeout: 90000,
+    });
+    assert.equal(result.status, 0, result.stderr || result.stdout);
+  }
+  runCli('init', '--agents', 'codex');
+  assert.ok(get(root, 'AGENTS.md').toString('utf8').startsWith('# Instruções existentes\n'));
+  put(root, '.pbai4devs/skills/projeto/human-extra/SKILL.md', '---\nname: human-extra\ndescription: Minha skill.\n---\n\n# Minha skill\n');
+  direct(); direct();
+  assert.equal(runCli('doctor').ok, true);
+  assert.equal(runCli('sync', '--check').ok, true);
+  assert.equal(runCli('update').ok, true);
+  assert.equal(runCli('sync', '--check').ok, true);
+  // Simule uma versão legada que registrou legitimamente este manifesto.
+  const config = '.pbai4devs/espelhos.conf', installed = '.pbai4devs/state/agentdevkit.json';
+  put(root, config, Buffer.concat([get(root, config), Buffer.from('documento|legado-comprovado\n')]));
+  const previous = JSON.parse(get(root, installed));
+  previous.files[config] = digest(get(root, config));
+  put(root, installed, JSON.stringify(previous, null, 2) + '\n');
+  direct();
+  assert.doesNotMatch(get(root, config).toString('utf8'), /documento\|legado-comprovado/);
+  assert.equal(JSON.parse(get(root, state)).config, digest(get(root, config)));
+  assert.equal(runCli('doctor').ok, true);
+  assert.equal(runCli('sync', '--check').ok, true);
+  assert.equal(runCli('update').ok, true);
+  const template = '.pbai4devs/templates/gitignore/shared.ignore';
+  const humanTemplate = Buffer.concat([get(root, template), Buffer.from('\n/artefato-humano/\n')]);
+  put(root, template, humanTemplate);
+  direct();
+  assert.match(get(root, '.pbai4devs/.gitignore').toString('utf8'), /\/artefato-humano\//);
+  assert.equal(runCli('update').ok, true);
+  assert.deepEqual(get(root, template), humanTemplate);
+  assert.equal(runCli('sync', '--check').ok, true);
+  for (const [path, content] of Object.entries(initial)) assert.deepEqual(get(root, path), content, path);
+});

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

@@ -14,6 +14,7 @@ import './HUMAN_OWNERSHIP.mjs';
 import './COEXISTENCE.mjs';
 import './MANAGED_CONTENT.mjs';
 import './PRESERVATION.mjs';
+import './CATALOG_OWNERSHIP.mjs';
 import { validateCatalog as validateExternalCatalog } from '../../gerenciar-skills-externas/SCRIPT.mjs';
 import { stateDirectory } from '../../lib/state-path.mjs';
 
@@ -276,21 +277,22 @@ test('gera gitignore canonico e de clientes; registro gitignore nao espelha recu
   assertCheckReadonly(root, {}, 0);
 });
 
-test('repara somente bloco gitignore e force salva o original sem perder regras externas', t => {
+test('preserva bloco gitignore editado e atualiza bloco conhecido sem perder regras externas', t => {
   const root = fixture(t, true); run(root);
   const prefix = '# Regras do usuario\r\n/private-cache/\r\n';
   const suffix = '# Excecao local\r\n!keep.log\r\n';
+  const original = read(root, '.codex/.gitignore');
   const old = `${prefix}${ignoreBegin}\r\n/custom-inside/\r\n${ignoreEnd}\r\n${suffix}`;
   write(root, '.codex/.gitignore', old);
   assertCheckReadonly(root); assertCheckReadonly(root, { force: true });
-  const result = run(root, { force: true });
-  assert.equal(readFileSync(join(result.backupRoot, '.codex/.gitignore'), 'utf8'), old);
-  const repaired = readFileSync(join(root, '.codex/.gitignore'), 'utf8');
-  assert.ok(repaired.startsWith(prefix)); assert.ok(repaired.endsWith(suffix));
-  assert.ok(!repaired.includes('/custom-inside/')); assert.ok(repaired.includes('/cache/'));
+  assert.throws(() => run(root, { force: true }), /Conteudo proprio preservado/);
+  assert.equal(read(root, '.codex/.gitignore'), old);
+  write(root, '.codex/.gitignore', `${prefix}${original}${suffix}`);
   write(root, '.pbai4devs/templates/gitignore/agents.ignore', '# Novo padrao\n{{ALLOWLIST}}\n/cache/\n/session/\n');
   assertCheckReadonly(root);
-  run(root);
+  const result = run(root, { force: true });
+  assert.equal(readFileSync(join(result.backupRoot, '.codex/.gitignore'), 'utf8'), `${prefix}${original}${suffix}`);
+  assert.ok(read(root, '.codex/.gitignore').startsWith(prefix));
   assert.ok(read(root, '.codex/.gitignore').includes('/session/'));
   assert.ok(readFileSync(join(root, '.codex/.gitignore'), 'utf8').endsWith(suffix));
   assertCheckReadonly(root, {}, 0);
@@ -374,6 +376,9 @@ test('registros são derivados, determinísticos e --check nunca os corrige', t
   run(root);
   write(root, '.pbai4devs/skills.json', '{"incorreto":true}\n');
   assertCheckReadonly(root);
+  assert.throws(() => run(root, { force: true }), /Conteudo proprio preservado/);
+  assert.equal(read(root, '.pbai4devs/skills.json'), '{"incorreto":true}\n');
+  rmSync(join(root, '.pbai4devs/skills.json'));
   run(root);
   assert.ok(Array.isArray(JSON.parse(read(root, '.pbai4devs/skills.json')).entries));
   rmSync(join(root, '.pbai4devs/adapters/antigravity/agents/revisor.md'));
@@ -455,7 +460,7 @@ test('atualiza fontes, adiciona clientes, remove recursos e migra agrupado para
   assertCheckReadonly(root, {}, 0);
 });
 
-test('remove linhas legadas e preserva arquivos sem prova de propriedade', t => {
+test('preserva linhas legadas humanas sem prova de propriedade', t => {
   const root = fixture(t);
   run(root);
   write(root, 'docs/produto/prd/demo/PRD.md', '# Produto real\n');
@@ -463,13 +468,26 @@ test('remove linhas legadas e preserva arquivos sem prova de propriedade', t =>
   write(root, '.claude/manual/DOC.md', pointer('../../manual/guia%20com%20espa%C3%A7o/DOC.md'));
   write(root, '.github/prompts/missing.prompt.md', pointer());
   write(root, '.pbai4devs/espelhos.conf', read(root, '.pbai4devs/espelhos.conf') + 'documento|manual\n' + 'nativo|.github/prompts/missing.prompt.md|.pbai4devs/commands/missing/COMMAND.md\n');
+  const config = read(root, '.pbai4devs/espelhos.conf');
   assertCheckReadonly(root);
-  run(root);
-  assert.doesNotMatch(read(root, '.pbai4devs/espelhos.conf'), /documento\||missing/);
+  assert.throws(() => run(root, { force: true }), /Conteudo proprio preservado/);
+  assert.equal(read(root, '.pbai4devs/espelhos.conf'), config);
   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);
+});
+
+test('limpa configuração legada comprovadamente gerenciada e registra novo hash', t => {
+  const root = fixture(t);
+  const path = '.pbai4devs/espelhos.conf';
+  write(root, path, read(root, path) + 'documento|manual\n');
+  recordOwned(root, [path]);
+  run(root);
+  assert.doesNotMatch(read(root, path), /documento\|/);
+  const derived = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
+  assert.equal(derived.config, createHash('sha256').update(readFileSync(join(root, path))).digest('hex'));
   assertCheckReadonly(root, {}, 0);
 });
 
@@ -745,13 +763,15 @@ test('criar editar e remover recursos atualiza todos os tipos e os índices nati
   assertCheckReadonly(root, {}, 0);
 });
 
-test('JSON derivado corrompido é detectado e reparado com backup sem editar fontes', t => {
+test('JSON derivado alterado é preservado até remoção deliberada pelo usuário', t => {
   const root = completeCatalogFixture(t);
   run(root);
   for (const path of ['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']) write(root, path, '{corrompido');
   assertCheckReadonly(root, { force: true });
-  const result = run(root, { force: true });
-  for (const path of ['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']) assert.equal(read(result.backupRoot, path), '{corrompido');
+  assert.throws(() => run(root, { force: true }), /Conteudo proprio preservado/);
+  for (const path of ['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']) assert.equal(read(root, path), '{corrompido');
+  for (const path of ['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']) rmSync(join(root, path));
+  run(root);
   assert.equal(JSON.parse(read(root, '.pbai4devs/catalog.json')).schemaVersion, 1);
   assertCheckReadonly(root, {}, 0);
 });

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

@@ -29,21 +29,30 @@ execuções e projetos anteriores não são substituídos nem removidos. Cada
 exemplo recebe Git local, sem commits nem identidade alterada. O diretório
 gerado contém um ignore próprio, inclusive em projetos consumidores. Se a
 preparação falhar, o índice da nova execução permanece em `preparing`.
+O gerador verifica links e identidade da saída antes e depois das etapas, mas
+isso não é uma proteção atômica. Um processo concorrente com permissão para
+trocar diretórios ainda pode redirecionar uma escrita entre as verificações;
+execute-o em uma área sem esse acesso concorrente.
 O hub `.pbai4devs` e os clientes registrados são copiados, incluindo comandos
 nativos em TOML. Sem manifesto local, os templates definem os clientes em
 memória, respeitando a seleção salva. `.vscode` exige registro. Apenas as entradas
 `AGENTS.md`, `CLAUDE.md` e `GEMINI.md` presentes na origem são incluídas na raiz.
 Os templates substituem somente entradas com blocos gerenciados válidos;
 entradas próprias ou editadas são preservadas. Sem estado de instalação,
-o mantenedor usa `.pbai4devs/templates/entrypoints/`, com fallback para a raiz.
+as entradas existentes são copiadas sem presumir propriedade do kit.
 Os testes resolvem cada apontamento pelo formato declarado do cliente e recurso.
 
-As cópias geram os derivados locais antes dos testes, sem alterar a origem.
+As cópias guardam os catálogos originais em `.agent-tests/testar-maturidade/original-catalogs/`
+e geram catálogos operacionais novos, sem alterar os arquivos da origem.
+Arquivos da origem substituídos pela fixture ficam em `original-files/` nessa
+mesma pasta. O relatório identifica cada cópia: o cenário não é um teste do
+projeto original no local.
 Não copiam o código do produto em `bin/`, `src/`, `scripts/` ou `tests/`,
 nem essas pastas na localização antiga dentro do hub.
 Executam sincronização/reparo/idempotência, catálogo, verificação de
 recursos, diagnóstico, inspeção e gates negativos/positivo. Em dois casos,
-criação/edição/renomeação/remoção e corrupção dos índices exercitam o ciclo todo.
+criação, edição, renomeação, remoção e preservação de índices alterados
+exercitam o ciclo todo.
 Aplicações executam testes HTTP reais em
 portas efêmeras, encerradas ao fim. Legado e monorepo preservam seus arquivos.
 Ferramentas copiadas ficam sem downloads: o check negativo é esperado.

package/.pbai4devs/scripts/testar-maturidade/SCRIPT.mjs

@@ -15,6 +15,7 @@ const assets = join(dirname(fileURLToPath(import.meta.url)), 'assets');
 const owner = 'testar-maturidade';
 const marker = '.maturity-case.json';
 const suiteMarker = '.maturity-suite.json';
+const generatedCatalogs = new Set(['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']);
 const outputIgnore = '# Exemplos gerados permanecem locais.\n*\n';
 const defaultOutput = root => join(root, 'examples/generated');
 const prepareResources = root => {
@@ -58,6 +59,7 @@ function createChild(root, parent, name, { allowExisting = false } = {}) {
   noLinks(root, join(parent, name));
   const output = stat(join(parent, name));
   if (!output?.isDirectory() || output.isSymbolicLink()) fail('Diretório de saída inválido.');
+  return output;
 }
 function ensureDirectories(root, target) {
   let current = root;
@@ -144,7 +146,7 @@ function copyAllowed(relativePath, directory = false) {
   return true;
 }
 
-export function copyAgentStructure(sourceRoot, destination) {
+export function copyAgentStructure(sourceRoot, destination, { archiveCatalogs = false, archiveOverrides = new Set(), archiveEntrypoints = false } = {}) {
   const roots = ['.pbai4devs', ...registeredRoots(sourceRoot)];
   const stateFile = join(sourceRoot, stateDirectory(sourceRoot), 'agentdevkit.json');
   const stateInfo = stat(stateFile);
@@ -152,7 +154,7 @@ export function copyAgentStructure(sourceRoot, destination) {
   const installation = stateInfo ? json(stateFile) : null;
   if (stateInfo && (!installation || !installation.blocks || typeof installation.blocks !== 'object' || Array.isArray(installation.blocks))) fail('Estado da instalação deve registrar os blocos gerenciados.');
   function managedEntry(name) {
-    if (!installation) return true;
+    if (!installation) return false;
     const expected = installation.blocks[name];
     if (typeof expected !== 'string') return false;
     const content = readFileSync(join(sourceRoot, name), 'utf8');
@@ -161,7 +163,7 @@ export function copyAgentStructure(sourceRoot, destination) {
     const start = content.indexOf(begin), finish = content.indexOf(end);
     return finish > start && digest(content.slice(start, finish + end.length)) === expected;
   }
-  const files = []; const entrypoints = {}; let skipped = 0;
+  const files = []; const entrypoints = {}; const catalogSnapshots = []; const overriddenSnapshots = []; const seenSources = new Set(); let skipped = 0;
   function copy(file, targetFile = file) {
     const source = join(sourceRoot, file);
     const item = stat(source); if (!item) return;
@@ -171,6 +173,14 @@ export function copyAgentStructure(sourceRoot, destination) {
       mkdirSync(join(destination, targetFile), { recursive: true });
       for (const name of readdirSync(source).sort()) copy(join(file, name), join(targetFile, name));
     } else if (item.isFile()) {
+      seenSources.add(portable(file));
+      if (archiveCatalogs && generatedCatalogs.has(portable(file))) {
+        targetFile = `.agent-tests/testar-maturidade/original-catalogs/${basename(file)}`;
+        catalogSnapshots.push({ source: portable(file), snapshot: targetFile });
+      } else if (archiveOverrides.has(portable(file))) {
+        targetFile = `.agent-tests/testar-maturidade/original-files/${portable(file)}`;
+        overriddenSnapshots.push({ source: portable(file), snapshot: targetFile });
+      }
       const target = join(destination, targetFile); mkdirSync(dirname(target), { recursive: true }); copyFileSync(source, target); files.push(portable(targetFile));
     } else fail(`Arquivo não regular na origem: ${file}`);
   }
@@ -183,11 +193,29 @@ export function copyAgentStructure(sourceRoot, destination) {
     const selected = managedEntry(name) && stat(join(sourceRoot, template)) ? template : name;
     const info = stat(join(sourceRoot, selected));
     if (info && !info.isFile()) fail(`Entrada de agente deve ser arquivo regular: ${selected}`);
+    if (archiveEntrypoints && selected !== name) {
+      const snapshot = `.agent-tests/testar-maturidade/original-files/${name}`;
+      copy(name, snapshot); overriddenSnapshots.push({ source: name, snapshot });
+    }
     copy(selected, name);
     if (info) entrypoints[name] = selected;
   }
+  // A fixture can create files belonging to an unselected client; archive
+  // those source files as well, without traversing symbolic-link ancestors.
+  for (const path of archiveOverrides) if (!seenSources.has(path)) {
+    noLinks(sourceRoot, join(sourceRoot, path));
+    copy(path);
+  }
   const sourceDigest = digest(files.map(file => `${file}\0${digest(readFileSync(join(destination, file)))}`).join('\n'));
-  return { roots, copiedFiles: files.length, skipped, files, sourceDigest, entrypoints, toolDefinitions: files.filter(file => /^\.pbai4devs\/tools\/[^/]+\/TOOL\.json$/.test(file)).length };
+  return { roots, copiedFiles: files.length, skipped, files, sourceDigest, entrypoints, catalogSnapshots, overriddenSnapshots, toolDefinitions: files.filter(file => /^\.pbai4devs\/tools\/[^/]+\/TOOL\.json$/.test(file)).length };
+}
+
+function fixtureOverrides(scenario, sourceRoot) {
+  const paths = ['README.md', '.pbai4devs/.gitignore', ...registeredRoots(sourceRoot).map(root => `${root}/.gitignore`), '.pbai4devs/state/configuracao/ESTADO.md', '.pbai4devs/estado/configuracao/ESTADO.md'];
+  if (scenario.planning !== 'none' || scenario.app) paths.push('.pbai4devs/state/README.md', '.pbai4devs/estado/README.md');
+  if (scenario.configured) paths.push('.dockerignore', '.env.example', 'Makefile');
+  if (scenario.layout === 'legacy') paths.push('Makefile', '.github/workflows/legacy.yml', '.vscode/settings.json');
+  return new Set(paths);
 }
 
 function planning(root, scenario) {
@@ -299,33 +327,41 @@ export function prepareExamples({ sourceRoot = projectRoot, outputRoot, scenario
   const parent = outputRoot === undefined ? base : dirname(base);
   ensureDirectories(sourceRoot, parent);
   const name = outputRoot === undefined ? `maturity-${randomUUID()}` : basename(base);
-  createChild(sourceRoot, parent, name);
+  const created = createChild(sourceRoot, parent, name);
   outputRoot = join(parent, name);
-  write(outputRoot, suiteMarker, JSON.stringify({ owner, version: 1 }, null, 2) + '\n');
-  write(outputRoot, '.gitignore', outputIgnore);
-  writeIndex(outputRoot, [], 'preparing');
+  const canonicalOutput = realpathSync(outputRoot);
+  const verifyOutput = (path = outputRoot) => {
+    noLinks(sourceRoot, path);
+    const current = stat(outputRoot);
+    if (!current?.isDirectory() || current.dev !== created.dev || current.ino !== created.ino || realpathSync(outputRoot) !== canonicalOutput) fail('Diretório de saída alterado durante a execução.');
+  };
+  const guarded = (path, operation) => { verifyOutput(path); const value = operation(); verifyOutput(path); return value; };
+  guarded(outputRoot, () => write(outputRoot, suiteMarker, JSON.stringify({ owner, version: 1 }, null, 2) + '\n'));
+  guarded(outputRoot, () => write(outputRoot, '.gitignore', outputIgnore));
+  guarded(outputRoot, () => writeIndex(outputRoot, [], 'preparing'));
   const examples = [];
   for (const scenario of scenarios) {
     const destination = join(outputRoot, scenario.id);
-    mkdirSync(destination);
-    write(destination, marker, JSON.stringify({ owner, version: 1, id: scenario.id }, null, 2) + '\n');
-    const copied = copyAgentStructure(sourceRoot, destination);
-    planning(destination, scenario);
-    const app = application(destination, scenario);
-    write(destination, 'README.md', document(scenario.title, `${scenario.note}\n\nEste é um exemplo gerado. Estados de aprovação/publicação são dados de teste.\nRevisão do gate é simulação contratual, não revisão humana.\n\nOs scripts dos agentes foram copiados, sem pacotes ou credenciais conhecidas.\nO filtro não detecta segredos em conteúdo arbitrário.\n${app.tests.length ? `\nPara repetir os testes: \`${scenario.layout === 'legacy' ? 'npm run test:legacy' : 'npm test'}\`.\nO harness executa os testes Node diretamente, sem instalar dependências.\nO teste abre HTTP em porta efêmera e encerra o servidor.\n` : '\nNão há aplicação; a prova real exercita os scripts copiados.\n'}`, `fase: ${scenario.expected}\n`));
-    renderResources(destination);
-    if (initializeGit) gitInit(destination);
+    guarded(outputRoot, () => mkdirSync(destination));
+    guarded(destination, () => write(destination, marker, JSON.stringify({ owner, version: 1, id: scenario.id }, null, 2) + '\n'));
+    const copied = guarded(destination, () => copyAgentStructure(sourceRoot, destination, { archiveCatalogs: true, archiveOverrides: fixtureOverrides(scenario, sourceRoot), archiveEntrypoints: true }));
+    guarded(destination, () => planning(destination, scenario));
+    const app = guarded(destination, () => application(destination, scenario));
+    guarded(destination, () => write(destination, 'README.md', document(scenario.title, `${scenario.note}\n\nEste é um exemplo gerado, não um teste no projeto original. Estados de aprovação/publicação são dados de teste.\nRevisão do gate é simulação contratual, não revisão humana.\nCatálogos originais e arquivos substituídos pela fixture ficam em \`.agent-tests/testar-maturidade/\`; os catálogos operacionais são regenerados.\n\nOs scripts dos agentes foram copiados, sem pacotes ou credenciais conhecidas.\nO filtro não detecta segredos em conteúdo arbitrário.\n${app.tests.length ? `\nPara repetir os testes: \`${scenario.layout === 'legacy' ? 'npm run test:legacy' : 'npm test'}\`.\nO harness executa os testes Node diretamente, sem instalar dependências.\nO teste abre HTTP em porta efêmera e encerra o servidor.\n` : '\nNão há aplicação; a prova real exercita os scripts copiados.\n'}`, `fase: ${scenario.expected}\n`)));
+    guarded(destination, () => renderResources(destination));
+    if (initializeGit) guarded(destination, () => gitInit(destination));
     examples.push({ ...scenario, root: destination, copied, application: app });
   }
-  write(outputRoot, 'REPORT.json', JSON.stringify({ owner, version: 1, status: 'prepared', scenarios: [...ids], results: [] }, null, 2) + '\n');
-  writeIndex(outputRoot, examples, 'prepared');
+  guarded(outputRoot, () => write(outputRoot, 'REPORT.json', JSON.stringify({ owner, version: 1, status: 'prepared', scenarios: [...ids], copies: examples.map(example => ({ id: example.id, catalogSnapshots: example.copied.catalogSnapshots, overriddenSnapshots: example.copied.overriddenSnapshots })), results: [] }, null, 2) + '\n'));
+  guarded(outputRoot, () => writeIndex(outputRoot, examples, 'prepared'));
+  Object.defineProperty(examples, 'verifyOutput', { value: verifyOutput });
   return examples;
 }
 
 function writeIndex(outputRoot, examples, status) {
   const rows = examples.map(item => `| [${item.id}](${item.id}/README.md) | ${item.expected} | ${item.status || 'prepared'} |`).join('\n');
   const progress = status === 'preparing' ? '\nPreparação em andamento nesta execução.\n' : '';
-  write(outputRoot, 'README.md', document('Exemplos de maturidade', `Projetos sintéticos com cópias locais da estrutura de agentes.\nNenhum resultado certifica produção, revisão humana ou outros sistemas operacionais.\n${progress}\n| Cenário | Nível esperado | Resultado |\n| --- | --- | --- |${rows ? '\n' + rows : ''}\n\nRelatório: \`REPORT.json\`. Logs e evidências por projeto ficam em \`.agent-tests/\`.\nCada execução usa uma pasta nova e preserva as anteriores.\n`, `status: ${status}\n`));
+  write(outputRoot, 'README.md', document('Exemplos de maturidade', `Projetos sintéticos com cópias locais da estrutura de agentes; não são testes no projeto original.\nCatálogos operacionais são regenerados e suas cópias originais ficam em cada \`.agent-tests/testar-maturidade/\`.\nNenhum resultado certifica produção, revisão humana ou outros sistemas operacionais.\n${progress}\n| Cenário | Nível esperado | Resultado |\n| --- | --- | --- |${rows ? '\n' + rows : ''}\n\nRelatório: \`REPORT.json\`. Logs e evidências por projeto ficam em \`.agent-tests/\`.\nCada execução usa uma pasta nova e preserva as anteriores.\n`, `status: ${status}\n`));
 }
 
 function hashes(root, files) { return Object.fromEntries(files.map(file => [file, digest(readFileSync(join(root, file)))])); }
@@ -399,13 +435,14 @@ function resourceLifecycle(example, run) {
   if (readFileSync(join(root, catalogPath), 'utf8') !== before.catalog || readFileSync(join(root, registryPath), 'utf8') !== before.registry) fail('O ciclo não restaurou os catálogos originais.');
   const corrupted = '{"tampered":true}\n'; write(root, catalogPath, corrupted);
   run(sync, ['--check'], 1, 'catalog-drift-detected');
-  const repair = run(sync, ['--force'], 0, 'catalog-drift-repaired');
-  const backup = repair.output.match(/Backup local: (.+)/)?.[1]?.trim();
-  if (!backup || readFileSync(join(root, backup, catalogPath), 'utf8') !== corrupted) fail('Correção forçada não preservou backup do JSON alterado.');
+  const blocked = run(sync, ['--force'], 2, 'catalog-drift-preserved');
+  if (!blocked.output.includes('Conteudo proprio preservado')) fail('A colisão não informou a preservação do catálogo.');
+  if (readFileSync(join(root, catalogPath), 'utf8') !== corrupted) fail('Sincronização alterou o JSON sintético sem ownership.');
+  write(root, catalogPath, before.catalog); // Restore only the content this fixture deliberately changed.
   rmSync(join(root, catalogPath)); run(sync, ['--check'], 1, 'catalog-missing-detected');
   run(sync, [], 0, 'catalog-missing-repaired'); run(sync, ['--check'], 0, 'lifecycle-clean');
   if (readFileSync(join(root, catalogPath), 'utf8') !== before.catalog || readFileSync(join(root, registryPath), 'utf8') !== before.registry) fail('Catálogos não foram restaurados após corrupção/remoção.');
-  return { status: 'passed', operations: ['create', 'edit-description', 'rename', 'delete', 'corrupt-json', 'remove-json'], clients: rows.length, backup, sourceRestored: true };
+  return { status: 'passed', operations: ['create', 'edit-description', 'rename', 'delete', 'protect-modified-json', 'remove-json'], clients: rows.length, sourceRestored: true };
 }
 
 function reviewContract(example, run, proof) {
@@ -444,7 +481,7 @@ function reviewContract(example, run, proof) {
 export function testExample(example) {
   const commands = []; const logRoot = '.agent-tests/maturity';
   const run = runner(example.root, logRoot, commands);
-  const result = { id: example.id, expected: example.expected, status: 'failed', copied: { files: example.copied.copiedFiles, roots: example.copied.roots, skipped: example.copied.skipped, sourceDigest: example.copied.sourceDigest, entrypoints: example.copied.entrypoints }, commands, limits: ['Executado somente no SO/runtime deste host.', 'Estado de produto e revisão do gate são dados sintéticos.', 'Build Docker, UI e implantação não são exercitados.', 'Cópia exclui credenciais por nomes conhecidos, sem varredura semântica de segredos.'] };
+  const result = { id: example.id, expected: example.expected, status: 'failed', copied: { files: example.copied.copiedFiles, roots: example.copied.roots, skipped: example.copied.skipped, sourceDigest: example.copied.sourceDigest, entrypoints: example.copied.entrypoints, catalogSnapshots: example.copied.catalogSnapshots, overriddenSnapshots: example.copied.overriddenSnapshots }, commands, limits: ['Cenário sintético: não testa o projeto original no local.', 'Executado somente no SO/runtime deste host.', 'Estado de produto e revisão do gate são dados sintéticos.', 'Build Docker, UI e implantação não são exercitados.', 'Cópia exclui credenciais por nomes conhecidos, sem varredura semântica de segredos.'] };
   const preserved = hashes(example.root, example.application.protected);
   try {
     const sync = '.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
@@ -493,11 +530,14 @@ export function testExample(example) {
 
 export function runExamples(options = {}) {
   const examples = prepareExamples(options);
-  const results = examples.map(example => { const result = testExample(example); console.log(`${example.id}=${result.status}${result.error ? ': ' + result.error : ''}`); return result; });
+  const results = examples.map(example => { examples.verifyOutput(example.root); const result = testExample(example); examples.verifyOutput(example.root); console.log(`${example.id}=${result.status}${result.error ? ': ' + result.error : ''}`); return result; });
   const outputRoot = dirname(examples[0].root);
   const report = { owner, version: 1, status: results.every(item => item.status === 'passed') ? 'passed' : 'failed', platform: process.platform, arch: process.arch, node: process.version, results, limits: ['Provas reais somente das operações descritas e APIs locais.', 'Pareceres do gate são simulações explícitas, sem revisão humana.', 'Não certifica produção nem sistemas operacionais não executados.'] };
+  examples.verifyOutput();
   write(outputRoot, 'REPORT.json', JSON.stringify(report, null, 2) + '\n');
+  examples.verifyOutput();
   writeIndex(outputRoot, examples.map(example => ({ ...example, status: results.find(result => result.id === example.id).status })), report.status);
+  examples.verifyOutput();
   return { outputRoot, report };
 }