@pathbit/agentdevkit 0.0.23 → 0.0.24

package/.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs

@@ -9,8 +9,8 @@ import { buildCatalog } from '../lib/catalog.mjs';
 import { resourcePath } from '../lib/resource-path.mjs';
 import { adapterManifest, resolveAdapters } from '../lib/adapters.mjs';
 import { nativePathBoundary } from '../lib/native-paths.mjs';
-import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, mergeManagedContent, stripManagedContent } from '../lib/managed-content.mjs';
-import { mergeTomlContent, stripTomlContent } from '../lib/managed-toml.mjs';
+import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, extractManagedBlock, mergeManagedContent, stripManagedContent } from '../lib/managed-content.mjs';
+import { extractTomlManagedBlock, mergeTomlContent, stripTomlContent } from '../lib/managed-toml.mjs';
 import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, planUntrack, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
 import { stateDirectory } from '../lib/state-path.mjs';
 
@@ -90,7 +90,7 @@ function replaceJsonMember(bytes, member, value) {
 // Compare owned fields structurally, preserving all other JSON bytes.
 function derivedContent(original, previous, next) {
   if (!original) return JSON.stringify(next, null, 2) + '\n';
-  const keys = ['schemaVersion', 'entries', 'outputs', 'files', 'blocks', 'removedBlocks', 'removedFiles'];
+  const keys = ['schemaVersion', 'entries', 'outputs', 'files', 'blocks', 'removedBlocks', 'removedFiles', 'catalogs', 'config'];
   const canonical = value => value && typeof value === 'object' && !Array.isArray(value)
     ? Object.fromEntries(Object.keys(value).sort(compare).map(key => [key, canonical(value[key])]))
     : Array.isArray(value) ? value.map(canonical) : value;
@@ -247,6 +247,11 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   if (previousEntries?.schemaVersion !== 1 || !previousEntries.entries || typeof previousEntries.entries !== 'object' || Array.isArray(previousEntries.entries) || Object.entries(previousEntries.entries).some(([name, hash]) => !canonicalEntrypoint(name) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de entradas derivadas invalido.');
   const previousOutputs = previousEntries.outputs ?? {};
   if (!previousOutputs || typeof previousOutputs !== 'object' || Array.isArray(previousOutputs) || Object.entries(previousOutputs).some(([path, hash]) => !/^\.[A-Za-z0-9][A-Za-z0-9._-]*\/(skills|rules|agents)\.json$/.test(path) || reserved.has(path.split('/')[0].toLowerCase()) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de saidas derivadas invalido.');
+  const previousCatalogs = previousEntries.catalogs ?? {};
+  const catalogPaths = new Set(['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']);
+  if (!previousCatalogs || typeof previousCatalogs !== 'object' || Array.isArray(previousCatalogs) || Object.entries(previousCatalogs).some(([path, hash]) => !catalogPaths.has(path) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de catalogos derivados invalido.');
+  for (const path of Object.keys(previousCatalogs)) safe(path);
+  if (previousEntries.config !== undefined && (typeof previousEntries.config !== 'string' || !/^[a-f0-9]{64}$/.test(previousEntries.config))) fail('Registro de configuracao derivada invalido.');
   const validResourcePath = path => {
     if (typeof path !== 'string' || !/^\.[A-Za-z0-9][A-Za-z0-9._-]*\/.+/.test(path)) return false;
     const [root, scope] = path.split('/');
@@ -254,7 +259,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       && !['readme.md', 'instructions.md'].includes(posix.basename(path).toLowerCase())
       && (/\.(md|mdc)$/i.test(path) || path.startsWith('.gemini/commands/') && path.endsWith('.toml'));
   };
-  const validIgnoreBlock = path => typeof path === 'string' && /^\.[A-Za-z0-9][A-Za-z0-9._-]*\/\.gitignore$/.test(path) && !reserved.has(path.split('/')[0].toLowerCase());
+  const validIgnoreBlock = path => path === '.pbai4devs/.gitignore' || typeof path === 'string' && /^\.[A-Za-z0-9][A-Za-z0-9._-]*\/\.gitignore$/.test(path) && !reserved.has(path.split('/')[0].toLowerCase());
   for (const [name, values] of [['files', previousEntries.files ?? {}], ['blocks', previousEntries.blocks ?? {}]]) {
     if (!values || typeof values !== 'object' || Array.isArray(values) || Object.entries(values).some(([path, hash]) => !(validResourcePath(path) || name === 'blocks' && (canonicalEntrypoint(path) || validIgnoreBlock(path))) || !/^[a-f0-9]{64}$/.test(hash))) fail(`Registro de ${name} derivados invalido.`);
     for (const path of Object.keys(values)) safe(canonicalEntrypoint(path) ? resolveEntrypoint(root, canonicalEntrypoint(path)) : path);
@@ -475,11 +480,23 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   const registries = new Map();
   const discoveryOutputs = {};
+  const catalogOutputs = {};
   for (const [target, content] of built.outputs) {
     const info = stat(safe(target));
     if (info && !info.isFile()) fail(`Registro nao e arquivo: ${target}`);
     const current = info ? readFileSync(absolute(target)) : null;
     captureInput(target, current);
+    const currentHash = current && createHash('sha256').update(current).digest('hex');
+    const known = current && [installed?.files?.[target], previousCatalogs[target]].some(digest => digest && digest === currentHash);
+    if (current && !known) {
+      // Identical bytes do not establish ownership. An unowned catalogue can
+      // remain if already current, but it cannot be adopted or regenerated.
+      remember(target, 'existing-catalog');
+      if (current.toString('utf8') !== content) { conflicts.add(target); protectedConflicts.add(target); }
+      continue;
+    }
+    const nextHash = createHash('sha256').update(content).digest('hex');
+    if (installed?.files?.[target] !== nextHash) catalogOutputs[target] = nextHash;
     if (!current || current.toString('utf8') !== content) {
       registries.set(target, content);
       if (force && info) backup.add(target);
@@ -533,10 +550,22 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       merged = mergeGitignore(current, patterns);
     }
     catch (error) { fail(`${target}: ${error.message}`); }
-    if (target !== '.pbai4devs/.gitignore') {
-      const start = merged.text.indexOf(ignoreBegin), finish = merged.text.indexOf(ignoreEnd);
-      if (start >= 0 && finish > start) managedBlocks[target] = createHash('sha256').update(merged.text.slice(start, finish + ignoreEnd.length)).digest('hex');
+    if (merged.hasBlock) {
+      const start = current.indexOf(ignoreBegin), finish = current.indexOf(ignoreEnd);
+      const blockHash = start >= 0 && finish > start ? createHash('sha256').update(current.slice(start, finish + ignoreEnd.length)).digest('hex') : null;
+      const fileHash = createHash('sha256').update(current).digest('hex');
+      const known = [installed?.blocks?.[target], previousEntries.blocks?.[target]].some(hash => hash && hash === blockHash)
+        || priorFiles[target] && priorFiles[target] === fileHash;
+      if (!known) {
+        // A marker or identical contents is not proof that this block belongs
+        // to the kit. Do not adopt, replace or remove it even with --force.
+        remember(target, 'existing-ignore-block');
+        if (merged.text !== current) { conflicts.add(target); protectedConflicts.add(target); }
+        continue;
+      }
     }
+    const start = merged.text.indexOf(ignoreBegin), finish = merged.text.indexOf(ignoreEnd);
+    if (start >= 0 && finish > start) managedBlocks[target] = createHash('sha256').update(merged.text.slice(start, finish + ignoreEnd.length)).digest('hex');
     if (merged.text !== current) {
       ignoreFiles.set(target, merged.text);
       if (force && info && merged.hasBlock) backup.add(target);
@@ -568,6 +597,10 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       if (!command) fail(`Comando Gemini exige COMMAND.md: ${source}`);
       const current = mixed ? targetBytes : null;
       const merged = mixed ? mergeTomlContent(current, `@{${source}}`, { expectedHash: priorBlocks[target] }) : null;
+      if (current && !priorBlocks[target] && priorFiles[target] !== createHash('sha256').update(current).digest('hex') && extractTomlManagedBlock(current)) {
+        // An identical block can remain, but its bytes are not ownership proof.
+        remember(target, 'existing-managed-block'); expected.set(target, current); continue;
+      }
       const content = merged ? merged.text : `${tomlMarker}\ndescription = ${JSON.stringify(command.description)}\nprompt = ${JSON.stringify(`@{${source}}\n\n{{args}}`)}\n`;
       if (mixed) { captureInput(target, current); managedBlocks[target] = merged.sha256; remember(target, 'existing-file-extended'); }
       else rememberGenerated(target, content);
@@ -588,6 +621,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const inclusion = ruleInclusion ? `@[origem](${link(target, source)})` : `Leia e siga [origem](${link(target, source)}).`;
     const current = mixed ? targetBytes : null;
     const merged = mixed ? mergeManagedContent(current, inclusion, { expectedHash: priorBlocks[target] }) : null;
+    if (current && !priorBlocks[target] && priorFiles[target] !== createHash('sha256').update(current).digest('hex') && extractManagedBlock(current)) {
+      remember(target, 'existing-managed-block'); expected.set(target, current); continue;
+    }
     const content = merged ? merged.text : `${frontmatter}\n${title}\n\n${marker}\n${inclusion}\n`;
     if (mixed) { captureInput(target, current); managedBlocks[target] = merged.sha256; remember(target, 'existing-file-extended'); }
     else rememberGenerated(target, content);
@@ -644,6 +680,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       const previousBlockHash = priorBlocks[name] ?? Object.entries(priorBlocks).find(([path]) => canonicalEntrypoint(path) === canonical)?.[1];
       if (current && (previousBlockHash || createHash('sha256').update(current).digest('hex') !== previousHash)) {
         const merged = mergeManagedContent(current, entrypointReference(root, canonical), { expectedHash: previousBlockHash });
+        if (!previousBlockHash && previousHash !== createHash('sha256').update(current).digest('hex') && extractManagedBlock(current)) {
+          remember(name, 'existing-managed-block'); continue;
+        }
         captureInput(name, current);
         managedBlocks[name] = merged.sha256;
         rootEntries.set(name, merged.text);
@@ -682,8 +721,20 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     removedBlocks.add(target);
     remember(target, 'existing-file-extended');
   }
+  const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
+  const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
+  const configChanged = !configExists || configText !== finalConfig;
+  const configHash = configExists ? createHash('sha256').update(readFileSync(absolute(config))).digest('hex') : null;
+  const configKnown = configExists && [installed?.files?.[config], previousEntries.config].some(hash => hash && hash === configHash);
+  if (configExists && !configKnown) {
+    remember(config, 'existing-configuration');
+    if (configChanged) { conflicts.add(config); protectedConflicts.add(config); }
+  }
   const next = { schemaVersion: 1, entries: nextEntries };
   if (Object.keys(discoveryOutputs).length) next.outputs = discoveryOutputs;
+  if (Object.keys(catalogOutputs).length) next.catalogs = catalogOutputs;
+  const nextConfigHash = createHash('sha256').update(finalConfig).digest('hex');
+  if ((!configExists || configKnown) && installed?.files?.[config] !== nextConfigHash) next.config = nextConfigHash;
   if (Object.keys(generatedFiles).length) next.files = generatedFiles;
   const derivedBlocks = Object.fromEntries(Object.entries(managedBlocks).filter(([path, hash]) => installed?.blocks?.[path] !== hash || Object.hasOwn(previousEntries.blocks ?? {}, path)));
   if (Object.keys(derivedBlocks).length) next.blocks = derivedBlocks;
@@ -693,7 +744,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   for (const path of remove) if (validResourcePath(path) && installed?.files?.[path] && !expected.has(path)) effectiveRemovedFiles[path] = installed.files[path];
   if (Object.keys(effectiveRemovedFiles).length) next.removedFiles = Object.fromEntries(Object.entries(effectiveRemovedFiles).sort(([a], [b]) => compare(a, b)));
   const registryContent = derivedContent(registryBytes, previousEntries, next);
-  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || Object.keys(effectiveRemovedFiles).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
+  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(catalogOutputs).length || next.config || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || Object.keys(effectiveRemovedFiles).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
   const ownedOutputs = sorted([...targets, ...built.outputs.keys(), '.pbai4devs/espelhos.conf', ...rootEntries.keys(), ...(recordDerivedState && (stat(safe(entryRegistry)) || registries.has(entryRegistry)) ? [entryRegistry] : []),
     ...[...discoveries].flatMap(agent => ['skills', 'rules', 'agents'].map(kind => `${agent}/${kind}.json`)),
     ...[...ignoreTemplates.keys()].filter(target => {
@@ -709,9 +760,6 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const removals = topPaths(remove);
   const backups = topPaths(backup);
   const rootEntryChanges = [...rootEntries].filter(([name, content]) => !stat(absolute(name)) || readFileSync(absolute(name), 'utf8') !== content);
-  const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
-  const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
-  const configChanged = !configExists || configText !== finalConfig;
   // Every planned write/removal may cover a different staged version. Compare
   // the worktree bytes with the index before touching any path, even in force
   // mode, and repeat immediately before applying the transaction.

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.