@pathbit/agentdevkit 0.0.23 → 0.0.25

package/.pbai4devs/commands/revisar-entrega/COMMAND.md

@@ -24,6 +24,12 @@ urgente, defina critérios próprios AC-001 e registre o motivo.
    revisão e `revisar-entrega check <relatorio>` pelo mesmo seletor. Falha,
    critério sem prova ou revisão pendente bloqueiam o commit/merge.
 
+Antes de um merge fast-forward, na origem, execute `revisar-entrega check-merge
+--destino refs/heads/<destino> <relatorio> [outros-relatorios...]`. A verificação
+exige cobertura do diff e correspondência com o commit revisado. Ela bloqueia
+históricos divergentes, links, submódulos, arquivos executáveis e operações Git
+acima de 64 MiB. Confirme os hashes retornados antes de integrar.
+
 Saída: resultado por critério, pendências e caminho do único `revisao.json` em
 `.agent-tests/<referencia>/<execucao>/`. Esta etapa é obrigatória após qualquer
 implementação; a ausência de spec não elimina a revisão.

package/.pbai4devs/scripts/revisar-entrega/SCRIPT.mjs

@@ -26,7 +26,7 @@ function pathInRoot(root, input) {
 }
 
 function git(root, args, allowFailure = false) {
-  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 15000, windowsHide: true });
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 15000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' } });
   if ((result.error || result.status !== 0) && !allowFailure) fail(`Git: ${result.error?.message || result.stderr?.trim() || 'operacao falhou'}`);
   return result;
 }
@@ -53,7 +53,7 @@ function tracked(root, file) {
 
 function ignoredPaths(root, files) {
   if (!files.length) return new Set();
-  const result = spawnSync('git', ['check-ignore', '--no-index', '--stdin', '-z'], { cwd: root, input: files.join('\0') + '\0', encoding: 'utf8', timeout: 15000, windowsHide: true });
+  const result = spawnSync('git', ['check-ignore', '--no-index', '--stdin', '-z'], { cwd: root, input: files.join('\0') + '\0', encoding: 'utf8', timeout: 15000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' } });
   if (result.error || ![0, 1].includes(result.status)) fail(`Git: ${result.error?.message || result.stderr?.trim() || 'falha ao conferir ignores'}`);
   return new Set(result.stdout.split('\0').filter(Boolean));
 }
@@ -211,11 +211,79 @@ function validateReview(file, { root = projectRoot, requireSeal = true } = {}) {
     const recorded = JSON.parse(readFileSync(join(root, sealPath), 'utf8'));
     if (JSON.stringify(recorded) !== JSON.stringify(seal)) fail('Relatorio, baseline ou evidencia alterados apos selar a revisao.');
   }
-  return { root, prefix, seal, result: { status: 'passed', report: reportPath, criteria: ids.size, documents: docs.size } };
+  return { root, prefix, seal, snapshot: state, result: { status: 'passed', report: reportPath, criteria: ids.size, documents: docs.size } };
 }
 
 export function checkReview(file, { root = projectRoot } = {}) { return validateReview(file, { root, requireSeal: true }).result; }
 
+// This deliberately permits only a fast-forward and regular non-executable
+// files. Existing review snapshots do not record modes or merge results.
+export function checkMerge(reports, destination, { root = projectRoot } = {}) {
+  requireNode(); root = repository(root);
+  if (!Array.isArray(reports) || !reports.length) fail('Informe um ou mais relatorios selados, sem repeticao.');
+  reports = reports.map(file => pathInRoot(root, file));
+  if (new Set(reports).size !== reports.length) fail('Informe relatorios selados sem repeticao.');
+  if (typeof destination !== 'string' || !destination.startsWith('refs/heads/') || git(root, ['check-ref-format', destination], true).status !== 0) fail('Destino deve ser uma branch local completa: refs/heads/<nome>.');
+  const currentBranch = git(root, ['symbolic-ref', '--quiet', 'HEAD'], true);
+  if (currentBranch.status !== 0) fail('Confira a branch de origem; HEAD destacado nao e aceito.');
+  const sourceRef = currentBranch.stdout.trim();
+  if (!sourceRef.startsWith('refs/heads/') || git(root, ['check-ref-format', sourceRef], true).status !== 0) fail('A origem deve ser uma branch local valida.');
+  if (sourceRef === destination) fail('Origem e destino devem ser branches distintas.');
+  for (const ref of [sourceRef, destination]) if (git(root, ['symbolic-ref', '--quiet', ref], true).status === 0) fail(`Branch simbolica nao e aceita: ${ref}`);
+  const resolveCommit = ref => {
+    const out = git(root, ['rev-parse', '--verify', `${ref}^{commit}`], true);
+    const value = out.stdout?.trim();
+    if (out.status !== 0 || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value || '')) fail(`Branch ou commit invalido: ${ref}`);
+    return value;
+  };
+  const source = resolveCommit(sourceRef), target = resolveCommit(destination);
+  if (head(root) !== source) fail('HEAD diverge da branch de origem.');
+  if (git(root, ['merge-base', '--is-ancestor', target, source], true).status !== 0) fail('Apenas fast-forward comprovado e suportado; revise o resultado integrado para historico divergente.');
+  const bytes = args => {
+    const result = spawnSync('git', args, { cwd: root, timeout: 15000, windowsHide: true, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' } });
+    if (result.error || result.status !== 0) fail(`Git: ${result.error?.message || result.stderr?.toString().trim() || 'operacao falhou'}`);
+    return result.stdout;
+  };
+  const decode = data => { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { fail('Caminho Git nao e UTF-8 valido.'); } };
+  const raw = bytes(['diff', '--raw', '-z', '--no-abbrev', '--no-renames', '--no-ext-diff', '--no-textconv', '--ignore-submodules=none', target, source, '--']);
+  const parts = decode(raw).split('\0');
+  if (parts.pop() !== '' || parts.length % 2) fail('Diff Git incompleto ou ambiguo.');
+  const changes = new Map();
+  for (let i = 0; i < parts.length; i += 2) {
+    const match = /^:(\d{6}) (\d{6}) ([a-f0-9]+) ([a-f0-9]+) ([AMD])$/.exec(parts[i]);
+    if (!match) fail('Tipo de alteracao Git nao suportado.');
+    const [, beforeMode, afterMode, , , action] = match, path = pathInRoot(root, parts[i + 1]);
+    if (changes.has(path) || !['000000', '100644'].includes(beforeMode) || !['000000', '100644'].includes(afterMode)) fail(`Tipo ou modo nao comprovado: ${path}`);
+    changes.set(path, action);
+  }
+  if (!changes.size) fail('Nao ha alteracoes para integrar.');
+  const reviewed = new Set();
+  const verified = reports.map(file => validateReview(file, { root, requireSeal: true }));
+  for (const review of verified) {
+    if (review.snapshot.head !== source) fail('Relatorio nao corresponde ao commit de origem.');
+    for (const item of review.snapshot.files) {
+      const path = pathInRoot(root, item.path);
+      if (item.indexAction !== undefined) fail(`Acao de indice nao pode comprovar merge: ${path}`);
+      const tree = decode(bytes(['--literal-pathspecs', 'ls-tree', '-z', '--full-tree', source, '--', path]));
+      if (!tree) {
+        if (item.sha256 !== null) fail(`Conteudo revisado nao esta no commit de origem: ${path}`);
+      } else {
+        const m = /^(\d{6}) blob ([a-f0-9]+)\t([^\0]+)\0$/.exec(tree);
+        if (!m || m[1] !== '100644' || m[3] !== path) fail(`Arquivo, link ou modo nao comprovado no commit: ${path}`);
+        if (item.sha256 !== createHash('sha256').update(bytes(['cat-file', 'blob', m[2]])).digest('hex')) fail(`Conteudo revisado difere do commit de origem: ${path}`);
+      }
+      if (changes.has(path)) reviewed.add(path);
+    }
+  }
+  const missing = [...changes.keys()].filter(path => !reviewed.has(path));
+  if (missing.length) fail(`Alteracoes sem revisao selada: ${missing.join(', ')}`);
+  // Detect moved refs or changed worktree/reports during the validation.
+  if (git(root, ['symbolic-ref', '--quiet', 'HEAD']).stdout.trim() !== sourceRef || resolveCommit(sourceRef) !== source || resolveCommit(destination) !== target || head(root) !== source) fail('Origem ou destino mudou durante a verificacao.');
+  for (const file of reports) validateReview(file, { root, requireSeal: true });
+  if (git(root, ['symbolic-ref', '--quiet', 'HEAD']).stdout.trim() !== sourceRef || resolveCommit(sourceRef) !== source || resolveCommit(destination) !== target || head(root) !== source) fail('Origem ou destino mudou durante a verificacao.');
+  return { status: 'passed', sourceRef, source, destination, target, changes: changes.size, reports: reports.length, mode: 'fast-forward' };
+}
+
 export function sealReview(file, options) {
   const checked = validateReview(file, { ...options, requireSeal: false });
   const path = artifact(checked.root, `${checked.prefix}/seal.json`, checked.prefix, false);
@@ -224,12 +292,13 @@ export function sealReview(file, options) {
   return checkReview(file, options);
 }
 
-const usage = 'Uso: revisar-entrega prepare --id <slug> [--execution <slug>] [--spec <arquivo>] [--scope <arquivo>] [--document <arquivo>] [--output <artefato>]; seal|check <revisao.json>';
+const usage = 'Uso: revisar-entrega prepare --id <slug> [--execution <slug>] [--spec <arquivo>] [--scope <arquivo>] [--document <arquivo>] [--output <artefato>]; seal|check <revisao.json>; check-merge --destino refs/heads/<branch> <revisao.json> [...]';
 export function main(args = process.argv.slice(2)) {
   requireNode(); const [mode, ...rest] = args;
   if (!mode || ['--help', '-h'].includes(mode)) { console.log(usage); return 0; }
   if (mode === 'check' && rest.length === 1) { console.log(JSON.stringify(checkReview(rest[0]))); return 0; }
   if (mode === 'seal' && rest.length === 1) { console.log(JSON.stringify(sealReview(rest[0]))); return 0; }
+  if (mode === 'check-merge' && rest.length >= 3 && rest[0] === '--destino') { console.log(JSON.stringify(checkMerge(rest.slice(2), rest[1]))); return 0; }
   if (mode !== 'prepare') fail(usage);
   const options = { scope: [], documents: [] };
   const fields = { '--id': 'id', '--execution': 'execution', '--spec': 'spec', '--output': 'output' };

package/.pbai4devs/scripts/revisar-entrega/tests/TEST.mjs

@@ -1,9 +1,9 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { checkReview, prepareReview, sealReview, specCriteria } from '../SCRIPT.mjs';
+import { checkMerge, checkReview, prepareReview, sealReview, specCriteria } from '../SCRIPT.mjs';
 import { projectRoot } from '../../lib/runtime.mjs';
 
 function fixture(t) {
@@ -247,3 +247,113 @@ test('documentos rastreados permanecem obrigatórios mesmo com regra de ignore',
   assert.ok(f.report.documentation.some(item => item.path === 'spec.md'));
   assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
 });
+
+function mergeFixture(t, { scope = ['src/main.mjs', 'src/old.txt', 'src/new.txt'], dirty = false, seal = true, ignoredSubmodule = false } = {}) {
+  const f = fixture(t);
+  const commit = message => f.git('-c', 'user.name=Test User', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=disabled-hooks', 'commit', '-q', '-m', message);
+  f.put('src/old.txt', 'original\n'); f.git('add', '.'); commit('test: base');
+  f.git('branch', '-M', 'main'); f.git('checkout', '-q', '-b', 'feature');
+  f.put('src/main.mjs', 'export const value=2;\n');
+  f.git('mv', 'src/old.txt', 'src/new.txt'); f.git('add', 'src/main.mjs'); commit('test: source');
+  if (ignoredSubmodule) {
+    const object = f.git('rev-parse', 'HEAD').trim();
+    f.git('update-index', '--add', '--cacheinfo', `160000,${object},vendor`);
+    commit('test: submodule');
+    f.git('config', 'diff.ignoreSubmodules', 'all');
+  }
+  if (dirty) f.put('src/main.mjs', 'export const value=3; // not committed\n');
+  const made = prepareReview({ root: f.root, id: 'merge', execution: 'review', scope });
+  for (const item of made.report.documentation) Object.assign(item, { decision: 'no-impact', reason: 'Documento examinado na fixture.' });
+  const proof = '.agent-tests/merge/review/proof.txt'; f.put(proof, 'Prova sintetica para testar validacao.\n');
+  for (const item of made.report.validation) Object.assign(item, { method: 'fixture', prerequisite: 'fixture local', assertion: 'snapshot comparado', evidence: [proof], status: 'passed' });
+  made.report.review = { status: 'approved', reviewer: 'simulacao de teste', findings: [] };
+  f.put(made.file, JSON.stringify(made.report));
+  if (seal) sealReview(made.file, { root: f.root });
+  return { ...f, ...made, commit };
+}
+
+test('check-merge prova fast-forward completo sem alterar indice ou arquivos humanos', t => {
+  const f = mergeFixture(t);
+  f.put('human.txt', 'staged humano\n'); f.git('add', 'human.txt'); f.put('human.txt', 'alteracao humana\n');
+  const index = readFileSync(join(f.root, '.git/index')), human = readFileSync(join(f.root, 'human.txt'));
+  const result = checkMerge([f.file], 'refs/heads/main', { root: f.root });
+  assert.equal(result.status, 'passed'); assert.equal(result.mode, 'fast-forward'); assert.equal(result.changes, 3);
+  assert.equal(result.source, f.git('rev-parse', 'HEAD').trim()); assert.equal(result.target, f.git('rev-parse', 'main').trim());
+  assert.deepEqual(readFileSync(join(f.root, '.git/index')), index); assert.deepEqual(readFileSync(join(f.root, 'human.txt')), human);
+});
+
+test('check-merge funciona na CLI e rejeita relatorio duplicado por alias', t => {
+  const f = mergeFixture(t);
+  const script = '.pbai4devs/scripts/revisar-entrega/SCRIPT.mjs', runtime = '.pbai4devs/scripts/lib/runtime.mjs';
+  for (const file of [script, runtime]) { mkdirSync(dirname(join(f.root, file)), { recursive: true }); cpSync(join(projectRoot, file), join(f.root, file)); }
+  const args = [join(f.root, script), 'check-merge', '--destino', 'refs/heads/main', f.file];
+  const run = spawnSync(process.execPath, args, { cwd: f.root, encoding: 'utf8' });
+  assert.equal(run.status, 0, run.stderr); assert.equal(JSON.parse(run.stdout).status, 'passed');
+  assert.throws(() => checkMerge([f.file, `./${f.file}`], 'refs/heads/main', { root: f.root }), /sem repeticao/);
+});
+
+test('check-merge bloqueia conteudo nao commitado e escopo parcial', async t => {
+  await t.test('working tree diferente do commit', t => {
+    const f = mergeFixture(t, { dirty: true });
+    assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /difere do commit/);
+  });
+  await t.test('omissao de arquivo removido', t => {
+    const f = mergeFixture(t, { scope: ['src/main.mjs', 'src/new.txt'] });
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /sem revisao selada: src\/old.txt/);
+  });
+  await t.test('relatorio sem selo', t => {
+    const f = mergeFixture(t, { seal: false });
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /nao selada/);
+  });
+});
+
+test('check-merge aceita cobertura distribuida por relatorios selados', t => {
+  const f = mergeFixture(t, { scope: ['src/main.mjs', 'src/new.txt'] });
+  const made = prepareReview({ root: f.root, id: 'merge-extra', execution: 'review', scope: ['src/old.txt'] });
+  for (const item of made.report.documentation) Object.assign(item, { decision: 'no-impact', reason: 'Documento examinado na fixture.' });
+  const proof = '.agent-tests/merge-extra/review/proof.txt'; f.put(proof, 'Prova sintetica complementar.\n');
+  for (const item of made.report.validation) Object.assign(item, { method: 'fixture', prerequisite: 'fixture local', assertion: 'delecao revisada', evidence: [proof], status: 'passed' });
+  made.report.review = { status: 'approved', reviewer: 'simulacao de teste', findings: [] };
+  f.put(made.file, JSON.stringify(made.report)); sealReview(made.file, { root: f.root });
+  const result = checkMerge([f.file, made.file], 'refs/heads/main', { root: f.root });
+  assert.equal(result.status, 'passed'); assert.equal(result.reports, 2); assert.equal(result.changes, 3);
+});
+
+test('check-merge recusa origem e destino invalidos, divergencia e tipos nao comprovados', async t => {
+  await t.test('branch invalida ou identica', t => {
+    const f = mergeFixture(t);
+    for (const name of ['main', 'refs/heads/missing', 'refs/heads/feature', '--help']) assert.throws(() => checkMerge([f.file], name, { root: f.root }));
+  });
+  await t.test('historico divergente', t => {
+    const f = mergeFixture(t); f.git('checkout', '-q', 'main'); f.put('different.txt', 'destino\n'); f.git('add', 'different.txt'); f.commit('test: target'); f.git('checkout', '-q', 'feature');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /fast-forward/);
+  });
+  await t.test('HEAD destacado', t => {
+    const f = mergeFixture(t); f.git('checkout', '-q', '--detach');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /HEAD destacado/);
+  });
+  await t.test('origem fora das branches locais', t => {
+    const f = mergeFixture(t); f.git('symbolic-ref', 'HEAD', 'refs/remotes/origin/feature');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /origem deve ser uma branch local/);
+  });
+  await t.test('submodulo ignorado pela configuracao Git', t => {
+    const f = mergeFixture(t, { ignoredSubmodule: true });
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /modo nao comprovado: vendor/);
+    const script = '.pbai4devs/scripts/revisar-entrega/SCRIPT.mjs', runtime = '.pbai4devs/scripts/lib/runtime.mjs';
+    for (const file of [script, runtime]) { mkdirSync(dirname(join(f.root, file)), { recursive: true }); cpSync(join(projectRoot, file), join(f.root, file)); }
+    const run = spawnSync(process.execPath, [join(f.root, script), 'check-merge', '--destino', 'refs/heads/main', f.file], { cwd: f.root, encoding: 'utf8' });
+    assert.equal(run.status, 1); assert.match(run.stderr, /modo nao comprovado: vendor/);
+  });
+  await t.test('link simbolico', t => {
+    const f = mergeFixture(t);
+    try { symlinkSync('main.mjs', join(f.root, 'src/link')); }
+    catch (error) { if (['EPERM', 'EACCES', 'ENOSYS'].includes(error.code)) return t.skip('Sem permissao de symlink.'); throw error; }
+    f.git('add', 'src/link'); f.commit('test: link');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /simbolico|modo nao comprovado/);
+  });
+  await t.test('arquivo executavel', t => {
+    const f = mergeFixture(t); f.git('update-index', '--chmod=+x', 'src/main.mjs'); f.commit('test: mode');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /modo nao comprovado/);
+  });
+});

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.