@pathbit/agentdevkit 0.0.23 → 0.0.24

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

package/.pbai4devs/scripts/testar-maturidade/tests/TEST.mjs

@@ -1,11 +1,13 @@
 import assert from 'node:assert/strict';
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import fs from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import childProcess, { spawnSync } from 'node:child_process';
 import { syncBuiltinESMExports } from 'node:module';
 import { createHash } from 'node:crypto';
 import test from 'node:test';
 import { projectRoot, requireNode } from '../../lib/runtime.mjs';
+import { adapterManifest } from '../../lib/adapters.mjs';
 import { copyAgentStructure, prepareExamples as prepare, registeredRoots, resourceTargets, SCENARIOS } from '../SCRIPT.mjs';
 
 // As fixtures pequenas isolam a cópia; o caso source-only usa o renderizador real.
@@ -32,6 +34,23 @@ function fixture(t) {
   return { root, put, outputRoot: join(root, 'examples/generated') };
 }
 
+function controlledSource(root) {
+  const source = join(root, 'controlled-source');
+  // Only four explicit resources; exclude local state and additional skills.
+  for (const path of ['.pbai4devs/skills/projeto/criar-skill/SKILL.md', '.pbai4devs/templates/gitignore/clients.json', '.pbai4devs/templates/gitignore/agents.ignore', '.pbai4devs/templates/gitignore/shared.ignore']) {
+    let current = projectRoot;
+    for (const part of path.split('/')) {
+      current = join(current, part);
+      assert.equal(lstatSync(current).isSymbolicLink(), false, `Fonte não pode ser link: ${path}`);
+    }
+    const destination = join(source, path);
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(join(projectRoot, path), destination);
+  }
+  writeFileSync(join(source, '.gitignore'), 'node_modules/\n');
+  return source;
+}
+
 test('copia recursos e configurações, excluindo payloads, caches e segredos', t => {
   const { root, put } = fixture(t);
   put('.pbai4devs/tools/demo/TOOL.json', '{}'); put('.pbai4devs/tools/demo/SCRIPT.mjs', 'export {};'); put('.pbai4devs/tools/demo/README.md', '# Tool');
@@ -110,6 +129,34 @@ test('troca de ancestral por symlink antes da criação não escreve no destino
   }
 });
 
+test('troca de saída durante escrita é detectada, sem alegar atomicidade', t => {
+  const { root, outputRoot } = fixture(t);
+  const target = join(outputRoot, 'race-output'), outside = mkdtempSync(join(root, 'race-outside-'));
+  const sentinel = join(outside, 'sentinel'); writeFileSync(sentinel, 'Não alterar.\n');
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+  const probe = join(root, 'race-link-probe');
+  try { symlinkSync(outside, probe, linkType); }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) { t.skip('Links simbólicos indisponíveis.'); return; } throw error; }
+  unlinkSync(probe);
+  const original = fs.writeFileSync; let injected = false;
+  try {
+    fs.writeFileSync = (file, ...args) => {
+      if (!injected && String(file) === join(target, '.maturity-suite.json')) {
+        renameSync(target, `${target}-moved`); symlinkSync(outside, target, linkType); injected = true;
+      }
+      return original.call(fs, file, ...args);
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => prepareExamples({ sourceRoot: root, outputRoot: target, scenarios: [SCENARIOS[0]], initializeGit: false }), /link|alterado/i);
+  } finally { fs.writeFileSync = original; syncBuiltinESMExports(); }
+  assert.equal(injected, true);
+  assert.equal(readFileSync(sentinel, 'utf8'), 'Não alterar.\n');
+  // O write já em curso pode ter criado o marcador no destino externo: a
+  // verificação detecta a troca, mas não é uma operação atômica de diretório.
+  assert.equal(existsSync(join(outside, '.maturity-suite.json')), true);
+  assert.equal(existsSync(join(outside, 'REPORT.json')), false);
+});
+
 test('cada destino padrão é exclusivo, preserva provas anteriores e permanece ignorado', t => {
   const { root, outputRoot } = fixture(t);
   const git = (...args) => {
@@ -172,16 +219,16 @@ test('preparação interrompida não altera resultado anterior nem declara suces
   assert.doesNotMatch(readFileSync(index, 'utf8'), /status: passed|\| passed \|/);
 });
 
-test('usa entradas distribuídas do hub e mantém fallback legado', t => {
+test('sem estado comprovado conserva entradas humanas mesmo com template', t => {
   const { root, put } = fixture(t);
   const template = '---\ndescription: Entrada genérica.\n---\n\n# Agentes do projeto\n';
   put('AGENTS.md', '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
   put('.pbai4devs/templates/entrypoints/AGENTS.md', template);
   const destination = join(root, 'copy');
   const copied = copyAgentStructure(root, destination);
-  assert.equal(readFileSync(join(destination, 'AGENTS.md'), 'utf8'), template);
+  assert.equal(readFileSync(join(destination, 'AGENTS.md'), 'utf8'), '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
   assert.equal(readFileSync(join(destination, 'CLAUDE.md'), 'utf8'), 'fixture\n');
-  assert.equal(copied.entrypoints['AGENTS.md'], '.pbai4devs/templates/entrypoints/AGENTS.md');
+  assert.equal(copied.entrypoints['AGENTS.md'], 'AGENTS.md');
   assert.equal(copied.entrypoints['CLAUDE.md'], 'CLAUDE.md');
   assert.equal(readFileSync(join(root, 'AGENTS.md'), 'utf8'), '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
 });
@@ -315,7 +362,9 @@ test('checkout de fontes sem manifesto deriva clientes em memória', t => {
 test('prepare gera apontamentos reais mesmo sem pastas de clientes na origem', t => {
   const { root } = fixture(t);
   const sourceRoot = join(root, 'source-only');
-  copyAgentStructure(projectRoot, sourceRoot);
+  copyAgentStructure(controlledSource(root), sourceRoot);
+  // Model a clean source checkout regardless of ignored local developer data.
+  for (const path of ['.pbai4devs/espelhos.conf', '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json', '.pbai4devs/state/agentdevkit.json', '.pbai4devs/state/derived.json', '.pbai4devs/estado/agentdevkit.json', '.pbai4devs/estado/derived.json']) rmSync(join(sourceRoot, path), { force: true });
   const roots = registeredRoots(sourceRoot);
   for (const client of roots) rmSync(join(sourceRoot, client), { recursive: true, force: true });
   const [example] = prepare({ sourceRoot, scenarios: [SCENARIOS[0]], initializeGit: false });
@@ -325,6 +374,102 @@ test('prepare gera apontamentos reais mesmo sem pastas de clientes na origem', t
   for (const file of ['src/cli.mjs', 'bin/agentdevkit.mjs', 'scripts/release/pipeline.mjs', 'tests/cli.test.mjs']) assert.equal(existsSync(join(example.root, file)), false, file);
 });
 
+for (const withState of [false, true]) test(`prepare preserva catálogos humanos na cópia e na origem (estado=${withState})`, t => {
+  const { root } = fixture(t), sourceRoot = join(root, `source-catalog-${withState}`);
+  copyAgentStructure(controlledSource(root), sourceRoot);
+  // Source checkouts do not include generated manifests; provide this fixture
+  // explicitly instead of depending on ignored files in the developer's tree.
+  writeFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf'), adapterManifest(sourceRoot, { clients: ['codex'] }));
+  const state = join(sourceRoot, '.pbai4devs/state/agentdevkit.json');
+  const derived = join(sourceRoot, '.pbai4devs/state/derived.json');
+  rmSync(state, { force: true }); rmSync(derived, { force: true }); // Só cópias criadas nesta fixture.
+  if (withState) {
+    mkdirSync(dirname(state), { recursive: true });
+    writeFileSync(state, JSON.stringify({ schemaVersion: 1, version: '0.0.24', language: 'pt', clients: ['codex'], files: {}, blocks: {} }) + '\n');
+  }
+  const originals = {};
+  for (const name of ['catalog.json', 'skills.json', 'agents.json', 'rules.json']) {
+    const file = join(sourceRoot, '.pbai4devs', name), content = `{ "arquivo humano": ${JSON.stringify(name)} }\n`;
+    writeFileSync(file, content); originals[name] = content;
+  }
+  for (const path of ['.pbai4devs/.gitignore', '.codex/.gitignore']) {
+    const file = join(sourceRoot, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, '# BEGIN AGENT IGNORE\n# Alteração humana dentro do bloco\n!/nao-apagar/\n# END AGENT IGNORE\n');
+  }
+  const skill = '.pbai4devs/skills/projeto/equipe-local/SKILL.md';
+  const skillFile = join(sourceRoot, skill);
+  mkdirSync(dirname(skillFile), { recursive: true });
+  writeFileSync(skillFile, '---\nname: equipe-local\ndescription: Conteúdo próprio.\n---\n\n# Equipe local\n');
+  const sourceIgnore = readFileSync(join(sourceRoot, '.gitignore'));
+  const sourceConfig = readFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf'));
+  const [example] = prepare({ sourceRoot, scenarios: [SCENARIOS[0]], initializeGit: false });
+  assert.equal(example.copied.catalogSnapshots.length, 4);
+  for (const [name, content] of Object.entries(originals)) {
+    assert.equal(readFileSync(join(sourceRoot, '.pbai4devs', name), 'utf8'), content);
+    assert.equal(readFileSync(join(example.root, '.agent-tests/testar-maturidade/original-catalogs', name), 'utf8'), content);
+    assert.doesNotMatch(readFileSync(join(example.root, '.pbai4devs', name), 'utf8'), /arquivo humano/);
+  }
+  for (const path of ['.pbai4devs/.gitignore', '.codex/.gitignore']) {
+    const original = readFileSync(join(sourceRoot, path));
+    const saved = example.copied.overriddenSnapshots.find(item => item.source === path);
+    assert.ok(saved, path);
+    assert.deepEqual(readFileSync(join(example.root, saved.snapshot)), original);
+    assert.match(original.toString('utf8'), /Alteração humana/);
+    assert.doesNotMatch(readFileSync(join(example.root, path), 'utf8'), /Alteração humana/);
+  }
+  assert.equal(readFileSync(join(example.root, skill), 'utf8'), readFileSync(skillFile, 'utf8'));
+  assert.deepEqual(readFileSync(join(sourceRoot, '.gitignore')), sourceIgnore);
+  assert.deepEqual(readFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf')), sourceConfig);
+  const report = JSON.parse(readFileSync(join(dirname(example.root), 'REPORT.json'), 'utf8'));
+  assert.deepEqual(report.copies[0].catalogSnapshots, example.copied.catalogSnapshots);
+  assert.match(readFileSync(join(example.root, 'README.md'), 'utf8'), /não um teste no projeto original/);
+  assert.equal(existsSync(state), withState);
+});
+
+test('arquiva arquivos substituídos mesmo quando o cliente não está selecionado', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|plano\n');
+  const files = ['.vscode/settings.json', '.github/workflows/legacy.yml'];
+  for (const path of files) put(path, `Conteúdo de equipe: ${path}\r\n`);
+  const [example] = prepareExamples({ sourceRoot: root, scenarios: [SCENARIOS.find(item => item.id === 'legado')], initializeGit: false });
+  for (const path of files) {
+    const saved = example.copied.overriddenSnapshots.filter(item => item.source === path);
+    assert.equal(saved.length, 1, path);
+    assert.deepEqual(readFileSync(join(example.root, saved[0].snapshot)), readFileSync(join(root, path)));
+  }
+});
+
+test('arquivo de cliente não selecionado com ancestral simbólico é recusado', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|plano\n');
+  const outside = mkdtempSync(join(root, 'outside-'));
+  writeFileSync(join(outside, 'settings.json'), 'Conteúdo externo.\n');
+  rmSync(join(root, '.vscode'), { recursive: true });
+  try { symlinkSync(outside, join(root, '.vscode'), 'dir'); }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) { t.skip('Links simbólicos indisponíveis.'); return; } throw error; }
+  assert.throws(() => prepareExamples({ sourceRoot: root, scenarios: [SCENARIOS.find(item => item.id === 'legado')], initializeGit: false }), /link/i);
+  assert.equal(readFileSync(join(outside, 'settings.json'), 'utf8'), 'Conteúdo externo.\n');
+});
+
+test('arquivos da fonte substituídos por fixtures têm cópias byte a byte', t => {
+  const { root, put } = fixture(t);
+  const files = ['README.md', 'Makefile', '.dockerignore', '.env.example', '.pbai4devs/state/README.md', '.pbai4devs/state/configuracao/ESTADO.md', '.vscode/settings.json', '.github/workflows/legacy.yml'];
+  const contents = Object.fromEntries(files.map(file => [file, `Conteúdo humano sintético: ${file}\r\n`]));
+  for (const [file, content] of Object.entries(contents)) put(file, content);
+  const cases = [SCENARIOS.find(item => item.id === 'app-configurada'), SCENARIOS.find(item => item.id === 'legado')];
+  const examples = prepareExamples({ sourceRoot: root, scenarios: cases, initializeGit: false });
+  for (const example of examples) {
+    for (const { source, snapshot } of example.copied.overriddenSnapshots) {
+      assert.equal(readFileSync(join(example.root, snapshot), 'utf8'), contents[source], source);
+      assert.equal(readFileSync(join(root, source), 'utf8'), contents[source], source);
+    }
+    for (const path of ['README.md', 'Makefile', '.pbai4devs/state/README.md', '.pbai4devs/state/configuracao/ESTADO.md']) assert.ok(example.copied.overriddenSnapshots.some(item => item.source === path), path);
+    const expected = example.id === 'legado' ? ['.vscode/settings.json', '.github/workflows/legacy.yml'] : ['.dockerignore', '.env.example'];
+    for (const path of expected) assert.ok(example.copied.overriddenSnapshots.some(item => item.source === path), path);
+  }
+});
+
 test('saída não pode sobrepor recursos de origem nem escapar das áreas de teste', t => {
   const { root } = fixture(t);
   const original = readFileSync(join(root, '.pbai4devs/espelhos.conf'), 'utf8');

package/CHANGELOG.md

@@ -4,6 +4,13 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.24 — 2026-11-14
+
+- Preserva catálogos, configuração e blocos existentes sem comprovação de
+  propriedade, inclusive ao usar `--force` ou sincronização direta.
+- Mantém o estado coerente quando a sincronização atualiza saídas gerenciadas.
+- Acrescenta testes de colisão, arquivos idênticos e preservação do índice Git.
+
 ## 0.0.23 — 2026-11-13
 
 - Corrige a resolução de destinos inexistentes diretamente sob a raiz.

package/docs/guides/troubleshooting.md

@@ -56,9 +56,10 @@ Compare cada `conflicts` com o que deseja manter. Edite a origem em
 recurso. Use `sync` para atualizar suas derivações. `update` reaplica os
 recursos do pacote invocado e pode conflitar com essa personalização.
 
-Quando a substituição for intencional, repita com `--force`. Arquivos
-existentes afetados recebem backup antes da escrita, inclusive em operações
-normais. O campo `backup` informa uma pasta relativa ao projeto:
+`--force` não substitui arquivos próprios nem blocos alterados. Resolva o
+conflito preservando o conteúdo que deseja manter e confira novamente o plano.
+Arquivos gerenciados afetados recebem backup antes da escrita, inclusive em
+operações normais. O campo `backup` informa uma pasta relativa ao projeto:
 
 ```text
 .agent-tests/agentdevkit/backups/<identificador>/
@@ -105,9 +106,10 @@ ou caminhos já gerenciados em links.
 Destinos dentro de `.git`, `node_modules` ou `.pbai4devs` são recusados,
 inclusive com variações de maiúsculas/minúsculas.
 
-Na CLI e no script `sincronizar-agentes`, `--force` repara conflitos gerenciados
-com backup. Recursos nativos humanos e links preservados continuam intactos.
-Para manter a instalação e sua seleção de clientes, prefira a CLI.
+No script `sincronizar-agentes`, `--force` repara conflitos gerenciados com
+backup. A CLI bloqueia conflitos de propriedade mesmo com `--force`. Recursos
+nativos humanos e links preservados continuam intactos. Para manter a instalação
+e sua seleção de clientes, prefira a CLI.
 
 ## Download, plataforma ou ferramenta falhando
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.23",
+  "version": "0.0.24",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",

package/src/i18n.mjs

@@ -12,7 +12,7 @@ const messages = {
     preserved: 'Caminhos existentes preservados', preservedDetails: 'Use --json para consultar os caminhos e motivos.',
     help: 'AgentDevKit: init [diretório], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <ação>.\nOpções: --target <diretório>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAliases: --clients e clients.',
     clientsCurrent: 'Agentes selecionados', clientsAvailable: 'Agentes disponíveis', clientsSelect: 'Agentes (IDs separados por vírgula ou all) [all]: ', agents: 'Seleção de agentes atualizada.',
-    next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano; --force salva backup antes de substituir.',
+    next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano e resolva os conflitos; --force não substitui conteúdo próprio.',
     healthy: 'Estrutura verificada.', unhealthy: 'A estrutura precisa de ajustes.', missing: 'AgentDevKit ainda não foi inicializado neste diretório.', error: 'Não foi possível concluir a operação.', invalid: 'Argumentos inválidos.', language: 'Idioma atual', version: 'Versão', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Projeto', readme: 'AgentDevKit instalado. Leia AGENTS.md e siga as etapas de produto, design e implementação.', state: 'Estado local do AgentDevKit e configuração compartilhada do projeto.',
     agentLanguage: 'Responda em português, salvo quando o usuário solicitar outro idioma.', inspect: 'Verifique a instalação', workflow: 'Consulte a próxima etapa', install: 'Inicialize este projeto', repair: 'Confira a sincronização', review: 'Revise os arquivos em conflito', tools: 'Resultado da ferramenta',
@@ -23,7 +23,7 @@ const messages = {
     preserved: 'Existing paths preserved', preservedDetails: 'Use --json to inspect paths and reasons.',
     help: 'AgentDevKit: init [directory], update, doctor, sync [--check], lang [pt|en|es], agents [list], next, tools <action>.\nOptions: --target <directory>, --lang <language>, --agents <list>, --yes, --dry-run, --force, --json.\nAliases: --clients and clients.',
     clientsCurrent: 'Selected agents', clientsAvailable: 'Available agents', clientsSelect: 'Agents (comma-separated IDs or all) [all]: ', agents: 'Agent selection updated.',
-    next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review it; --force backs them up before replacement.',
+    next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review and resolve the conflicts; --force does not replace user content.',
     healthy: 'Structure verified.', unhealthy: 'The structure needs attention.', missing: 'AgentDevKit has not been initialized in this directory.', error: 'The operation could not be completed.', invalid: 'Invalid arguments.', language: 'Current language', version: 'Version', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Project', readme: 'AgentDevKit installed. Read AGENTS.md and follow the product, design and implementation stages.', state: 'AgentDevKit state and shared project configuration.',
     agentLanguage: 'Respond in English unless the user requests another language.', inspect: 'Check the installation', workflow: 'Review the next stage', install: 'Initialize this project', repair: 'Check synchronization', review: 'Review conflicting files', tools: 'Tool result',
@@ -34,7 +34,7 @@ const messages = {
     preserved: 'Rutas existentes preservadas', preservedDetails: 'Use --json para consultar las rutas y los motivos.',
     help: 'AgentDevKit: init [directorio], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <acción>.\nOpciones: --target <directorio>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAlias: --clients y clients.',
     clientsCurrent: 'Agentes seleccionados', clientsAvailable: 'Agentes disponibles', clientsSelect: 'Agentes (IDs separados por coma o all) [all]: ', agents: 'Selección de agentes actualizada.',
-    next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise el plan; --force guarda una copia antes de reemplazarlos.',
+    next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise y resuelva los conflictos; --force no reemplaza contenido propio.',
     healthy: 'Estructura verificada.', unhealthy: 'La estructura necesita ajustes.', missing: 'AgentDevKit no se ha inicializado en este directorio.', error: 'No se pudo completar la operación.', invalid: 'Argumentos inválidos.', language: 'Idioma actual', version: 'Versión', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Proyecto', readme: 'AgentDevKit instalado. Lea AGENTS.md y siga las etapas de producto, diseño e implementación.', state: 'Estado de AgentDevKit y configuración compartida del proyecto.',
     agentLanguage: 'Responde en español salvo que el usuario solicite otro idioma.', inspect: 'Compruebe la instalación', workflow: 'Consulte la siguiente etapa', install: 'Inicialice este proyecto', repair: 'Compruebe la sincronización', review: 'Revise los archivos en conflicto', tools: 'Resultado de la herramienta',