@pathbit/agentdevkit 0.0.16 → 0.0.18

package/.pbai4devs/INSTRUCTIONS.md

@@ -31,7 +31,7 @@ serão preenchidos por perguntas e respostas quando o projeto começar.
 Combine destinos e registre-os no estado futuro de configuração. Ao finalizar
 uma etapa, explique a próxima e reúna suas perguntas. Use
 [proximos-passos](skills/projeto/proximos-passos/SKILL.md) e respeite o idioma
-salvo em `.pbai4devs/estado/agentdevkit.json`; sem escolha, use português.
+salvo em `.pbai4devs/state/agentdevkit.json`; sem escolha, use português.
 Evolua README e documentos pelos [modelos da fase](templates/README.md).
 Atualize fatos e links afetados; registre ausência de impacto com justificativa.
 

package/.pbai4devs/README.md

@@ -11,7 +11,7 @@ O catálogo local `catalog.json` é gerado das fontes pelo sincronizador.
 Ele inclui recursos, ferramentas, automações, modelos e referências externas.
 Os arquivos `skills.json`, `rules.json` e `agents.json` são índices auxiliares
 das fontes. Os clientes selecionados usam seus diretórios de apontamentos.
-O estado `estado/agentdevkit.json` guarda `clients`: `["all"]` ou os IDs
+O estado `state/agentdevkit.json` guarda `clients`: `["all"]` ou os IDs
 escolhidos. Catálogos, manifesto, estado e pastas nativas são derivados locais;
 não devem ser commitados. No repositório do kit, o código do produto fica em
 `src/`, `bin/`, `tests/` e `scripts/release/`, na raiz.

package/.pbai4devs/commands/sincronizar/COMMAND.md

@@ -4,14 +4,16 @@ description: Atualiza ou confere os apontamentos compartilhados dos agentes.
 
 # Sincronizar
 
-Entrada: sem argumentos usa `--force` para reparar; `--check` só confere.
+Entrada: este comando agêntico usa o script local com `--force` para reparar;
+`--check` só confere. O `sync` da CLI usa as fontes locais e não implica
+`--force`; `update` usa as fontes da versão do pacote executado.
 Pré-requisitos: Node.js 24+ e manifesto `.pbai4devs/espelhos.conf` válido.
 
 Siga [sincronizar-agentes](../../skills/projeto/sincronizar-agentes/SKILL.md)
 e execute o script correspondente pelo seletor. A reconstrução repara
-apontamentos e remove saídas obsoletas cuja propriedade do kit foi comprovada,
-com backup local. Recursos, configurações e links humanos são preservados,
-inclusive quando seus nomes coincidem com os destinos do kit.
+apontamentos e remove saídas obsoletas cuja propriedade do kit foi comprovada.
+Recursos adicionais, configurações, pastas e links humanos são preservados,
+inclusive em colisões de nomes. O backup local não substitui o histórico Git.
 Após reparar, execute também `--check`.
 
 Respeite os clientes registrados no manifesto. Para mudar a seleção salva,

package/.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { requireNode, isMain } from '../lib/runtime.mjs';
+import { stateDirectory } from '../lib/state-path.mjs';
 
 const repository = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..'));
 const defaultAgents = ['.agents', '.agent', '.gemini', '.claude', '.codex', '.cursor', '.github', '.opencode'];
@@ -61,7 +62,7 @@ function metadata(root, file) {
 }
 
 function maturity(root, report) {
-  const stateFile = '.pbai4devs/estado/configuracao/ESTADO.md'; const state = metadata(root, stateFile);
+  const stateFile = `${stateDirectory(root)}/configuracao/ESTADO.md`; const state = metadata(root, stateFile);
   const safeDocument = value => typeof value === 'string' && !path.isAbsolute(value) && !value.includes('\\') && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
   const planning = {};
   for (const name of ['prd', 'ux_ui', 'design']) {
@@ -211,7 +212,7 @@ export function inspectDocumentation(root, limits = {}) {
       else if (found.kind === 'symbolic-link') add(found.boundary, found, role);
     }
   }
-  const declared = metadata(root, '.pbai4devs/estado/configuracao/ESTADO.md').documents;
+  const declared = metadata(root, `${stateDirectory(root)}/configuracao/ESTADO.md`).documents;
   for (const [role, file] of Object.entries(declared)) {
     if (!documentRoles.has(role)) continue;
     if (!safeDocument(file)) { if (file !== null) warn(null, 'invalid-configured-path'); continue; }

package/.pbai4devs/scripts/inspecionar-projeto/tests/TEST.mjs

@@ -111,7 +111,7 @@ test('rejeita origens fora das fixtures e opções desconhecidas', () => {
 
 test('classifica sinais de maturidade sem confundir planejamento com produto funcionando', t => {
   const { directory, file, run } = fixture(t);
-  const state = stage => file('.pbai4devs/estado/configuracao/ESTADO.md', `---\npreparacao: concluido\nconfiguracao_tecnica: ${stage}\ndocumentos:\n  prd: docs/PRD.md\n  ux_ui: docs/UX.md\n  design: docs/DESIGN.md\n  releases: docs/releases\n---\n# Estado\n`);
+  const state = stage => file('.pbai4devs/state/configuracao/ESTADO.md', `---\npreparacao: concluido\nconfiguracao_tecnica: ${stage}\ndocumentos:\n  prd: docs/PRD.md\n  ux_ui: docs/UX.md\n  design: docs/DESIGN.md\n  releases: docs/releases\n---\n# Estado\n`);
   assert.equal(run().report.maturity.level, 'preparacao');
   state('pendente'); file('docs/PRD.md', '---\nstatus: rascunho\n---\n# PRD\n');
   assert.equal(run().report.maturity.level, 'descoberta');
@@ -131,6 +131,20 @@ test('classifica sinais de maturidade sem confundir planejamento com produto fun
   assert.match(result.report.maturity.limits[0], /nao substitui/);
 });
 
+test('inspeção lê decisões legadas e informa conflito entre pastas de estado', t => {
+  const { file, run } = fixture(t);
+  const decisions = '---\npreparacao: concluido\nconfiguracao_tecnica: pendente\n---\n# Estado\n';
+  file('.pbai4devs/estado/configuracao/ESTADO.md', decisions);
+  const legacy = run();
+  assert.equal(legacy.status, 0, legacy.stderr);
+  assert.equal(legacy.report.maturity.configuration.present, true);
+  assert.equal(legacy.report.maturity.configuration.preparacao, 'concluido');
+  file('.pbai4devs/state/configuracao/ESTADO.md', decisions);
+  const conflict = run();
+  assert.equal(conflict.status, 2);
+  assert.match(JSON.parse(conflict.stderr).error, /coexistem/);
+});
+
 test('exemplos e caches Playwright não viram aplicação do projeto real', t => {
   const { file, run } = fixture(t);
   for (const folder of ['examples/generated/a', 'examples/fixture', 'tmp/examples/a', 'TEMP/project', '.PLAYWRIGHT-MCP', 'playwright-results']) {
@@ -154,7 +168,7 @@ test('aceita inspecionar cenário em examples/generated sem liberar outras pasta
 
 test('status arbitrários e referências fora da raiz não expõem dados da configuração', t => {
   const { file, run } = fixture(t); const secret = 'PRIVATE_STATUS_192819';
-  file('.pbai4devs/estado/configuracao/ESTADO.md', `---\npreparacao: ${secret}\nconfiguracao_tecnica: ${secret}\ndocumentos:\n  prd: ../outside.md\n  design: docs/DESIGN.md\n---\n# Estado\n`);
+  file('.pbai4devs/state/configuracao/ESTADO.md', `---\npreparacao: ${secret}\nconfiguracao_tecnica: ${secret}\ndocumentos:\n  prd: ../outside.md\n  design: docs/DESIGN.md\n---\n# Estado\n`);
   file('docs/DESIGN.md', `---\nstatus: ${secret}\n---\n# Design\n`);
   const result = run(); assert.equal(result.status, 0);
   assert.equal(result.report.maturity.planning.prd.path, null);
@@ -199,7 +213,7 @@ test('descobre documentação real sem impor caixa, pasta docs ou frontmatter',
 
 test('caminhos cadastrados têm proveniência sem assumir status ou ler arquivos de configuração', t => {
   const { file, run } = fixture(t);
-  file('.pbai4devs/estado/configuracao/ESTADO.md', '---\ndocumentos:\n  design: architecture/current.md\n  specs: specifications\n  prd: planning/absent.md\n  readme: ../private-secret.md\n  seguranca: .env\n---\n# Estado\n');
+  file('.pbai4devs/state/configuracao/ESTADO.md', '---\ndocumentos:\n  design: architecture/current.md\n  specs: specifications\n  prd: planning/absent.md\n  readme: ../private-secret.md\n  seguranca: .env\n---\n# Estado\n');
   file('architecture/current.md', '# Existing architecture\n');
   file('specifications/current.mdx', '# Increment\n');
   file('.env', 'DO_NOT_EMIT_OR_HASH_THIS_SECRET');
@@ -231,7 +245,7 @@ test('documentos simbólicos permanecem opacos sem ler destinos internos, extern
     if (process.platform !== 'win32' || !['EPERM', 'EACCES'].includes(error.code)) throw error;
     t.skip('Links simbólicos indisponíveis sem permissão do Windows.'); return;
   }
-  file('.pbai4devs/estado/configuracao/ESTADO.md', '---\ndocumentos:\n  design: external/private.md\n---\n# State\n');
+  file('.pbai4devs/state/configuracao/ESTADO.md', '---\ndocumentos:\n  design: external/private.md\n---\n# State\n');
   const result = run();
   assert.equal(result.status, 0, result.stderr);
   const docs = result.report.documentation;

package/.pbai4devs/scripts/lib/README.md

@@ -14,3 +14,6 @@ Texto externo, nomes existentes e metadados humanos permanecem preservados.
 
 `gitignore.mjs` planeja exclusões locais e detecta regras conflitantes. Ele não
 altera o `.gitignore` da raiz; conflitos são informados para revisão humana.
+
+`state-path.mjs` identifica o estado atual ou legado sem dividir dados; duas
+pastas simultâneas ou links simbólicos exigem resolver o conflito antes do uso.

package/.pbai4devs/scripts/lib/gitignore.mjs

@@ -98,10 +98,33 @@ function localBlock(current, first, last, body) {
   return text.slice(0, start) + block + text.slice(finish);
 }
 
-function gitCommand(root, args, input) {
+function gitCommand(root, args, input, encoding = 'utf8') {
   const env = { ...process.env };
   for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE']) delete env[key];
-  return spawnSync('git', [...(['ls-files', 'rm'].includes(args[0]) ? ['--literal-pathspecs'] : []), '-C', root, ...args], { input, encoding: 'utf8', env, windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+  return spawnSync('git', [...(['ls-files', 'rm'].includes(args[0]) ? ['--literal-pathspecs'] : []), '-C', root, ...args], { input, encoding, env, windowsHide: true, maxBuffer: 16 * 1024 * 1024 });
+}
+
+// Compare exact bytes first. Only accept Git's plain text CRLF conversion when
+// effective attributes prove it applies and no custom transformation can run.
+// This deliberately does not invoke hash-object or repository-defined filters.
+export function indexContentMatches(root, path, working, indexed) {
+  if (working.equals(indexed)) return true;
+  const attributes = gitCommand(root, ['check-attr', '-z', 'text', 'eol', 'filter', 'working-tree-encoding', 'ident', '--', path]);
+  if (attributes.status !== 0) return false;
+  const parts = attributes.stdout.split('\0');
+  const values = {};
+  for (let i = 0; i + 2 < parts.length; i += 3) values[parts[i + 1]] = parts[i + 2];
+  const absent = value => value === 'unspecified' || value === 'unset';
+  if (!absent(values.filter) || !absent(values['working-tree-encoding']) || !absent(values.ident) || values.text === 'unset') return false;
+  const config = gitCommand(root, ['config', '--bool', 'core.autocrlf']);
+  if (config.status !== 0 && config.status !== 1) return false;
+  const textEnabled = values.text === 'set' || values.text === 'auto' || ['lf', 'crlf'].includes(values.eol) || config.status === 0 && config.stdout.trim() === 'true';
+  if (!textEnabled || !working.includes(13) || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(working.toString('latin1'))) return false;
+  try {
+    const text = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(working);
+    if (text.replaceAll('\r\n', '').includes('\r')) return false;
+    return Buffer.from(text.replaceAll('\r\n', '\n')).equals(indexed);
+  } catch { return false; }
 }
 
 function checkedOutput(path) {
@@ -502,25 +525,39 @@ export function planUntrack(root, expectedHashes = {}) {
   if (!candidates.length || !localStat(root)) return { root, paths: [], hashes: {}, index: '', conflicts: [] };
   const result = gitCommand(root, ['ls-files', '--stage', '-z']);
   if (result.status !== 0) {
-    if (result.error?.code === 'ENOENT' || /not a git repository/i.test(result.stderr || '')) return { root, paths: [], hashes: {}, index: '', conflicts: [] };
+    if (result.error?.code === 'ENOENT' || /not a git repository/i.test(result.stderr || '')) {
+      // Fail closed if a repository exists even when Git cannot be launched.
+      let directory = root;
+      while (true) {
+        if (localStat(join(directory, '.git'))) throw new Error('Nao foi possivel consultar o Git deste projeto; indice e arquivos preservados.');
+        const parent = dirname(directory);
+        if (parent === directory) break;
+        directory = parent;
+      }
+      return { root, paths: [], hashes: {}, index: '', conflicts: [] };
+    }
     throw new Error(result.error?.message || result.stderr || 'Falha ao ler indice Git.');
   }
   const conflicts = [];
   const records = result.stdout.split('\0').filter(Boolean);
-  const wanted = new Set(candidates);
+  const folded = new Map();
+  for (const path of candidates) folded.set(path.toLowerCase(), [...(folded.get(path.toLowerCase()) || []), path]);
   const matches = new Map();
   for (const record of records) {
     const position = record.indexOf('\t'), path = record.slice(position + 1);
-    if (position < 0 || !wanted.has(path)) continue;
-    matches.set(path, [...(matches.get(path) || []), record]);
+    if (position < 0) continue;
+    for (const candidate of folded.get(path.toLowerCase()) || []) {
+      matches.set(candidate, [...(matches.get(candidate) || []), record]);
+    }
   }
   const paths = [...matches.keys()].filter(path => {
     const file = checkedLocalPath(join(root, path));
     const entries = matches.get(path);
     const match = entries.length === 1 && entries[0].match(/^\d+ ([a-f0-9]+) 0\t/);
-    const blob = match ? gitCommand(root, ['cat-file', 'blob', match[1]]) : null;
-    const owned = localStat(file) && createHash('sha256').update(readFileSync(file)).digest('hex') === expectedHashes[path];
-    const indexOwned = blob?.status === 0 && createHash('sha256').update(blob.stdout).digest('hex') === expectedHashes[path];
+    const blob = match ? gitCommand(root, ['cat-file', 'blob', match[1]], undefined, null) : null;
+    const data = localStat(file) ? readFileSync(file) : null;
+    const owned = data && createHash('sha256').update(data).digest('hex') === expectedHashes[path];
+    const indexOwned = entries[0]?.slice(entries[0].indexOf('\t') + 1) === path && blob?.status === 0 && data && indexContentMatches(root, path, data, blob.stdout);
     if (!owned || !indexOwned) conflicts.push(path);
     return owned && indexOwned;
   });

package/.pbai4devs/scripts/lib/state-path.mjs

@@ -0,0 +1,20 @@
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Preserve legacy installations until the CLI migrates them. Do not silently
+// choose between two independently populated state trees.
+export function stateDirectory(root) {
+  const inspect = relative => {
+    let item;
+    try { item = lstatSync(join(root, relative)); }
+    catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null; throw error; }
+    if (item.isSymbolicLink()) throw new Error(`Link simbolico: ${relative}`);
+    if (!item.isDirectory()) throw new Error(`Pasta de estado inválida: ${relative}`);
+    return item;
+  };
+  if (!inspect('.pbai4devs')) return '.pbai4devs/state';
+  const current = inspect('.pbai4devs/state');
+  const legacy = inspect('.pbai4devs/estado');
+  if (current && legacy) throw new Error('Pastas .pbai4devs/state e .pbai4devs/estado coexistem; preserve os dados e resolva o conflito antes de continuar.');
+  return legacy ? '.pbai4devs/estado' : '.pbai4devs/state';
+}

package/.pbai4devs/scripts/sincronizar-agentes/README.md

@@ -12,6 +12,9 @@ node --test .pbai4devs/scripts/sincronizar-agentes/tests/TEST.mjs
 
 `--check` só confere; a execução normal atualiza os recursos. `--force` salva
 conflitos em `.agent-tests/` antes de reparar os caminhos gerenciados.
+O [comando agêntico](../../commands/sincronizar/COMMAND.md) usa `--force` por
+padrão; executar este script diretamente não ativa essa opção. A CLI oferece
+`sync --dry-run --json` para consultar o plano antes de aplicá-lo.
 Recursos nativos humanos recebem um bloco curto com a referência ao hub.
 Texto, frontmatter e nomes existentes são preservados. O estado guarda só o
 hash desse bloco; edições externas continuam permitidas. Um bloco alterado
@@ -41,6 +44,10 @@ sem Git, informa que a proteção fica pendente até `git init` e sincronizaçã
 Somente arquivos integralmente gerados são excluídos; pastas de clientes podem
 conter arquivos humanos versionados. Conteúdo próprio não é desindexado pela
 presença de um bloco gerenciado.
-Entradas novas usam os templates; hashes em `estado/derived.json` permitem
+Entradas novas usam os templates; hashes em `state/derived.json` permitem
 atualizar arquivos gerados e blocos separadamente, preservando alterações humanas.
 `--check` também acusa derivados ainda rastreados; não altera o índice.
+Apontamentos obsoletos podem ser removidos quando a propriedade é comprovada;
+arquivos e pastas próprios, inclusive os adicionais dentro do mesmo recurso,
+devem permanecer. Na CLI, confira `untrackedPaths` antes de aplicar: saídas
+geradas comprovadas podem deixar de ser rastreadas, sem excluir seus bytes.

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

@@ -3,6 +3,7 @@
 import { chmodSync, cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, posix, resolve } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { requireNode, projectRoot, isMain } from '../lib/runtime.mjs';
 import { buildCatalog } from '../lib/catalog.mjs';
 import { resourcePath } from '../lib/resource-path.mjs';
@@ -10,12 +11,13 @@ 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 { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
+import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, planUntrack, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
+import { stateDirectory } from '../lib/state-path.mjs';
 
 const marker = '<!-- gerado: sincronizar-agentes -->';
 const tomlMarker = '# gerado: sincronizar-agentes';
 const principals = { skills: 'SKILL.md', agents: 'AGENT.md', commands: 'COMMAND.md', rules: 'RULE.md' };
-const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'estado', 'tests', 'docs', 'adapters'];
+const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'state', 'estado', 'tests', 'docs', 'adapters'];
 const reserved = new Set(['.git', '.pbai4devs', '.agent-tests']);
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const sorted = values => [...new Set(values)].sort(compare);
@@ -78,6 +80,28 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   requireNode();
   root = realpathSync(resolve(root));
   const absolute = value => join(root, ...value.split('/'));
+  function assertGitReadableForChanges() {
+    // A project may be nested in a worktree; .git can be a file or directory.
+    // If that marker exists we must not treat an unavailable Git executable,
+    // an invalid repository or an unreadable index as a Git-free project.
+    let folder = root, found = false;
+    while (true) {
+      if (stat(join(folder, '.git'))) { found = true; break; }
+      const parent = dirname(folder);
+      if (parent === folder) break;
+      folder = parent;
+    }
+    if (!found) return false;
+    const env = { ...process.env };
+    for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE']) delete env[key];
+    const probe = spawnSync('git', ['-C', root, 'rev-parse', '--is-inside-work-tree'], {
+      encoding: 'utf8', env, windowsHide: true, timeout: 20000,
+    });
+    if (probe.error || probe.status !== 0 || probe.stdout.trim() !== 'true') {
+      fail('Nao foi possivel consultar o Git deste projeto; sincronizacao bloqueada para preservar arquivos e indice.');
+    }
+    return true;
+  }
   function safe(value) {
     if (typeof value !== 'string' || !value || /^[A-Za-z]:/.test(value) || /[|\\\x00-\x1f\x7f]/.test(value) || value.split('/').some(part => !part || part === '.' || part === '..')) fail(`Caminho invalido: ${value}`);
     let current = root;
@@ -129,7 +153,6 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const recorded = recordedHash === digest;
     return isReference(text) && recorded;
   };
-  const onlyReferences = value => { const files = scan(value); return files.length > 0 && ![...preserved.keys()].some(path => path === value || path.startsWith(`${value}/`)) && files.every(file => /\.(md|mdc|toml)$/i.test(file) && referenceFile(file)); };
   const protectedPath = value => /^(workflows(?:\/|$)|settings\.json$|extensions\.json$)/.test(value.slice(value.indexOf('/') + 1).toLowerCase());
   const agents = new Map();
   const formats = new Map();
@@ -140,11 +163,12 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const config = '.pbai4devs/espelhos.conf';
   const configExists = stat(safe(config));
   captureInput(config, configExists ? readFileSync(absolute(config)) : null);
-  const stateFile = '.pbai4devs/estado/agentdevkit.json';
+  const stateRoot = stateDirectory(root);
+  const stateFile = `${stateRoot}/agentdevkit.json`;
   const installed = stat(safe(stateFile)) ? JSON.parse(read(safe(stateFile))) : null;
   const configText = configExists ? read(safe(config)) : adapterManifest(root, { clients: installed?.clients });
   const rows = configText.split('\n');
-  const entryRegistry = '.pbai4devs/estado/derived.json';
+  const entryRegistry = `${stateRoot}/derived.json`;
   const registryBytes = stat(safe(entryRegistry)) ? readFileSync(absolute(entryRegistry)) : null;
   captureInput(entryRegistry, registryBytes);
   const previousEntries = registryBytes ? JSON.parse(registryBytes.toString('utf8')) : { schemaVersion: 1, entries: {} };
@@ -293,6 +317,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const remove = new Set();
   const backup = new Set();
   const conflicts = new Set();
+  const protectedConflicts = new Set();
   const expected = new Map();
   const managedBlocks = {};
   const generatedFiles = {};
@@ -305,17 +330,31 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   function planRemove(value, custom = false) {
     safe(value);
     if (!managed(value) || protectedPath(value)) fail(`Limpeza fora dos espelhos ou caminho protegido: ${value}`);
+    // Directories, unowned files and edited references can contain project
+    // data even when --force is used. Only a recorded, unchanged reference
+    // may be removed; empty directories are never removed recursively.
+    if (!stat(safe(value))?.isFile() || !referenceFile(value)) {
+      remember(value, 'existing-file');
+      if (custom) { conflicts.add(value); protectedConflicts.add(value); }
+      return;
+    }
     remove.add(value);
     if (custom) backup.add(value);
   }
   function cleanScope(value) {
     if (preserveBoundary(value)) return;
-    if (!stat(safe(value))) return;
-    if (stat(safe(value)).isDirectory() && !scan(value).length) return;
-    if (Object.keys(priorBlocks).some(path => path === value || path.startsWith(value + '/'))) return;
-    if (onlyReferences(value)) planRemove(value);
-    else if (claimed(value)) remember(value, 'edited-generated-file');
-    else remember(value);
+    const info = stat(safe(value));
+    if (!info) return;
+    const files = info.isDirectory() ? scan(value) : [value];
+    if (info.isDirectory() && !files.length) { remember(value, 'existing-directory'); return; }
+    let hasHumanContent = false;
+    for (const file of files) {
+      if (expected.has(file) || priorBlocks[file] || protectedPath(file)) continue;
+      if (referenceFile(file)) planRemove(file);
+      else if (claimed(file)) { remember(file, 'edited-generated-file'); hasHumanContent = true; }
+      else { remember(file); hasHumanContent = true; }
+    }
+    if (hasHumanContent && info.isDirectory()) remember(value);
   }
   const registries = new Map();
   const discoveryOutputs = {};
@@ -549,6 +588,22 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   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.
+  const affected = sorted([...removals, ...changed, ...registries.keys(), ...ignoreFiles.keys(), ...rootEntryChanges.map(([name]) => name), ...(configChanged ? [config] : [])]);
+  const emptyHash = createHash('sha256').update(Buffer.alloc(0)).digest('hex');
+  const affectedHashes = Object.fromEntries(affected.flatMap(value => {
+    const info = stat(safe(value));
+    if (info && !info.isFile()) return []; // A type conflict already blocks application.
+    return [[value, info ? createHash('sha256').update(readFileSync(absolute(value))).digest('hex') : emptyHash]];
+  }));
+  const hadGit = Object.keys(affectedHashes).length ? assertGitReadableForChanges() : false;
+  const affectedIndex = planUntrack(root, affectedHashes);
+  for (const path of affectedIndex.conflicts) {
+    conflicts.add(path);
+    remember(path, 'staged-content-preserved');
+  }
   function capture(value) {
     const file = safe(value), info = stat(file);
     if (!info) return null;
@@ -574,15 +629,15 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     let parent = posix.dirname(value);
     while (parent !== '.') { if (stat(safe(parent))?.isDirectory()) originalDirectories.add(parent); parent = posix.dirname(parent); }
   }
-  const touched = new Set(), createdDirectories = new Set(), restoredDirectories = new Set();
-  const prunedDirectories = new Map();
-  let restoring = false;
+  const touched = new Set(), createdDirectories = new Set();
   const summary = { changed: changed.length + rootEntryChanges.length, stale: removals.length, conflicts: conflicts.size, missing: missing.length, legacy: legacy.length, registries: registries.size, gitignores: ignoreFiles.size, manifests: configExists ? 0 : 1, localIgnores: localStatus.changed + localStatus.missing.length + localStatus.trackedOutputs.length + (localStatus.status === 'no-git' ? 1 : 0) };
   const dirty = Object.values(summary).some(Boolean);
   output(`${summary.changed} desatualizadas; ${summary.stale} obsoletas; ${summary.conflicts} conflitos; ${summary.missing} origens nativas ausentes; ${summary.legacy} documentos antigos; ${summary.registries} indices derivados; ${summary.gitignores} gitignores; ${summary.localIgnores} exclusoes locais.`);
   if (localStatus.status === 'no-git') output('Git ausente: apos git init, execute a sincronizacao para proteger os arquivos locais.');
   const preservedPaths = sorted(preserved.keys()).map(path => preserved.get(path));
   if (check) return { ...summary, ownedOutputs, managedBlocks, preserved: preservedPaths, exitCode: dirty ? 1 : 0 };
+  if (affectedIndex.conflicts.length) fail(`Indice Git contem alteracoes proprias; arquivos preservados: ${sorted(affectedIndex.conflicts).join(', ')}`);
+  if (protectedConflicts.size) fail(`Conteudo proprio preservado; resolva a colisao antes de sincronizar: ${sorted(protectedConflicts).join(', ')}`);
   if (conflicts.size) fail(`Use --force para reconstruir somente os caminhos gerenciados: ${sorted(conflicts).join(', ')}`);
   if (localStatus.missing.length) fail(`Regras humanas reabrem derivados locais: ${localStatus.missing.join(', ')}`);
   if (localPlan) assertLocalIgnoreUnchanged(localPlan);
@@ -592,7 +647,6 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     while (parent !== '.' && !stat(safe(parent))) { missing.push(parent); parent = posix.dirname(parent); }
     for (const directory of missing.reverse()) {
       mkdirSync(safe(directory)); createdDirectories.add(directory);
-      if (restoring) restoredDirectories.add(directory);
     }
   }
   function mutate(value, action, text) {
@@ -647,40 +701,27 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   try {
     if (localPlan) assertLocalIgnoreUnchanged(localPlan);
+    if (Object.keys(affectedHashes).length) {
+      if (!assertGitReadableForChanges() && hadGit) fail('Git deixou de estar disponivel antes da sincronizacao; arquivos preservados.');
+      const current = planUntrack(root, affectedHashes);
+      if (current.conflicts.length || current.index !== affectedIndex.index) fail('Indice Git mudou antes da sincronizacao; conteudo preservado.');
+    }
     for (const value of removals) mutate(value, () => rmSync(safe(value), { recursive: true, force: true }), null);
     for (const value of changed) mutate(value, () => atomic(value, expected.get(value)), expected.get(value));
     for (const [value, text] of registries) mutate(value, () => atomic(value, text), text);
     for (const [value, text] of ignoreFiles) mutate(value, () => atomic(value, text), text);
     for (const [value, text] of rootEntryChanges) mutate(value, () => atomic(value, text), text);
     if (configChanged) mutate(config, () => atomic(config, finalConfig), finalConfig);
-    // Só os ancestrais de remoções conhecidas são candidatos à limpeza.
-    for (const value of removals) {
-      let parent = posix.dirname(value);
-      const boundary = value.split('/').slice(0, 2).join('/');
-      while (parent.startsWith(boundary + '/') || parent === boundary) {
-        const info = stat(safe(parent));
-        if (!info?.isDirectory() || readdirSync(absolute(parent)).length) break;
-        rmdirSync(safe(parent)); prunedDirectories.set(parent, info.mode & 0o777); parent = posix.dirname(parent);
-      }
-    }
+    // Directory ownership is not recorded: keep even empty parent directories.
     if (localPlan) applyLocalIgnore(localPlan);
   } catch (error) {
     const failures = [];
-    restoring = true;
     for (const value of [...touched].reverse()) {
       try {
         if (fingerprint(capture(value)) !== currentHashes.get(value)) fail(`Mudanca concorrente preservada: ${value}`);
         restore(value, originals.get(value));
       } catch (failure) { failures.push(failure); }
     }
-    for (const [directory, mode] of [...prunedDirectories].sort(([left], [right]) => right.length - left.length)) {
-      try {
-        if (!stat(safe(directory))) ensureDirectory(`${directory}/.restore-probe`);
-        const info = stat(safe(directory));
-        if (!info?.isDirectory() || !restoredDirectories.has(directory) && (info.mode & 0o777) !== mode) fail(`Diretorio concorrente preservado: ${directory}`);
-        chmodSync(safe(directory), mode);
-      } catch (failure) { failures.push(failure); }
-    }
     for (const directory of sorted(createdDirectories).sort((a, b) => b.length - a.length)) {
       try { if (!originalDirectories.has(directory) && stat(safe(directory))?.isDirectory() && !readdirSync(absolute(directory)).length) rmdirSync(safe(directory)); }
       catch (failure) { failures.push(failure); }

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

@@ -95,8 +95,8 @@ test('link em caminho registrado continua sendo erro antes de qualquer escrita',
   for (const source of ['files', 'blocks', 'derived', 'outputs']) {
     const root = fixture(t), path = source === 'derived' ? 'CLAUDE.md' : source === 'outputs' ? '.agents/skills.json' : '.claude/skills/demo/SKILL.md';
     if (!link(t, root, 'missing', path)) return;
-    if (source === 'derived' || source === 'outputs') put(root, '.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: source === 'derived' ? { [path]: 'a'.repeat(64) } : {}, ...(source === 'outputs' ? { outputs: { [path]: 'a'.repeat(64) } } : {}) }));
-    else put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: source === 'files' ? { [path]: 'a'.repeat(64) } : {}, blocks: source === 'blocks' ? { [path]: 'a'.repeat(64) } : {} }));
+    if (source === 'derived' || source === 'outputs') put(root, '.pbai4devs/state/derived.json', JSON.stringify({ schemaVersion: 1, entries: source === 'derived' ? { [path]: 'a'.repeat(64) } : {}, ...(source === 'outputs' ? { outputs: { [path]: 'a'.repeat(64) } } : {}) }));
+    else put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: source === 'files' ? { [path]: 'a'.repeat(64) } : {}, blocks: source === 'blocks' ? { [path]: 'a'.repeat(64) } : {} }));
     const before = snapshot(root);
     assert.throws(() => run(root, { force: true }), /Link simbolico em caminho gerenciado/);
     assert.deepEqual(snapshot(root), before);
@@ -106,7 +106,7 @@ test('link em caminho registrado continua sendo erro antes de qualquer escrita',
 test('manifesto standalone editado pelo usuário passa a ser preservado', t => {
   const root = fixture(t); run(root);
   const path = '.agents/skills.json', original = fs.readFileSync(join(root, path), 'utf8');
-  const derived = JSON.parse(fs.readFileSync(join(root, '.pbai4devs/estado/derived.json')));
+  const derived = JSON.parse(fs.readFileSync(join(root, '.pbai4devs/state/derived.json')));
   assert.equal(derived.outputs[path], hash(original));
   put(root, path, '{"entries":[{"path":".agents/skills/custom"}]}\n');
   const result = run(root, { force: true });
@@ -151,7 +151,7 @@ test('tipo alterado em caminho nativo registrado continua recusado antes de grav
   ]) {
     const root = fixture(t);
     if (path === '.codex') put(root, path, 'Human root\n'); else put(root, `${path}/keep.txt`, 'Human directory\n');
-    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
+    put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
     const before = snapshot(root);
     assert.throws(() => run(root, { force: true }), /caminho gerenciado/);
     assert.deepEqual(snapshot(root), before);
@@ -191,7 +191,7 @@ test('variante única de entrada registrada conserva conteúdo como arquivo mist
   for (const owned of ['AGENTS.md', 'agents.md']) {
     const root = fixture(t); put(root, 'agents.md', '# Renamed human entry\n');
     assert.throws(() => nativePathBoundary(root, 'AGENTS.md', [owned], { preserveRootAliases: true }), /maiusculas\/minusculas/);
-    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
+    put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
     run(root, { force: true });
     assert.ok(fs.readFileSync(join(root, 'agents.md'), 'utf8').startsWith('# Renamed human entry\n'));
     assert.ok(!fs.readdirSync(root).includes('AGENTS.md'));

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

@@ -64,7 +64,7 @@ test('texto humano com formato de referência nunca comprova propriedade', t =>
 test('hash registrado comprova referência legada sem marcador e diretório vazio humano permanece', t => {
   const root = fixture(t), stale = '.claude/skills/legacy.md';
   write(root, stale, human);
-  write(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: { [stale]: hash(human) }, blocks: {} }));
+  write(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: { [stale]: hash(human) }, blocks: {} }));
   fs.mkdirSync(join(root, '.claude/skills/user-empty'), { recursive: true });
   run(root);
   assert.equal(fs.existsSync(join(root, stale)), false);

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

@@ -38,7 +38,7 @@ test('sync complementa Markdown humano, preserva CRLF/metadados e acompanha só
   assert.equal(fs.statSync(join(root, path)).mode & 0o777, mode);
   assert.equal(result.managedBlocks[path], managedBlockDigest(actual));
   assert.ok(!result.ownedOutputs.includes(path));
-  const state = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  const state = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
   assert.equal(state.blocks[path], managedBlockDigest(actual));
   assert.equal(state.files[path], undefined);
   assert.equal(run(root, { check: true }).exitCode, 0);
@@ -84,7 +84,7 @@ test('remover recurso ou cliente retira somente bloco próprio de Markdown misto
     run(root);
     assert.equal(read(root, path), outside);
     assert.ok(read(root, path).startsWith(human));
-    assert.equal(JSON.parse(read(root, '.pbai4devs/estado/derived.json')).blocks?.[path], undefined);
+    assert.equal(JSON.parse(read(root, '.pbai4devs/state/derived.json')).blocks?.[path], undefined);
     assert.equal(run(root, { check: true }).exitCode, 0);
   }
 });
@@ -130,10 +130,10 @@ test('retirada standalone registra tombstone para bloco do estado instalado', t
   const root = fixture(t), path = '.claude/skills/demo/SKILL.md';
   put(root, path, '# Human\n'); run(root);
   const block = managedBlockDigest(read(root, path));
-  put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { [path]: block } }));
+  put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { [path]: block } }));
   fs.rmSync(join(root, '.pbai4devs/skills/old/demo'), { recursive: true });
   run(root);
-  const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  const derived = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
   assert.ok(derived.removedBlocks.includes(path));
   assert.equal(extractManagedBlock(read(root, path)), null);
   assert.equal(run(root, { check: true }).exitCode, 0);
@@ -143,7 +143,7 @@ test('stage pode gerar referências sem gravar estado derivado', t => {
   const root = fixture(t);
   run(root, { generateEntrypoints: false, recordDerivedState: false });
   assert.ok(fs.existsSync(join(root, '.claude/skills/demo/SKILL.md')));
-  assert.ok(!fs.existsSync(join(root, '.pbai4devs/estado/derived.json')));
+  assert.ok(!fs.existsSync(join(root, '.pbai4devs/state/derived.json')));
 });
 
 test('regra Cursor mantém globs e modo humanos ao receber referência', t => {
@@ -292,10 +292,10 @@ test('arquivo misto removido é recriado sem conservar propriedade do bloco ause
     const root = fixture(t);
     put(root, path, '# Humano\n'); run(root);
     const hash = managedBlockDigest(read(root, path));
-    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: {}, blocks: { [path]: hash } }));
+    put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: {}, blocks: { [path]: hash } }));
     fs.rmSync(join(root, path));
     run(root);
-    const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+    const derived = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
     assert.ok(derived.removedBlocks.includes(path));
     assert.ok(derived.files?.[path] || derived.entries?.[path]);
     assert.equal(extractManagedBlock(read(root, path)), null);
@@ -307,10 +307,10 @@ test('renomear caixa de entrada mista transfere só a propriedade do bloco', t =
   const root = fixture(t), before = '# Humano\n';
   put(root, 'AGENTS.md', before); run(root);
   const hash = managedBlockDigest(read(root, 'AGENTS.md'));
-  put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { 'AGENTS.md': hash } }));
+  put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { 'AGENTS.md': hash } }));
   fs.renameSync(join(root, 'AGENTS.md'), join(root, 'agents.md'));
   const result = run(root);
-  const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  const derived = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
   assert.ok(read(root, 'agents.md').startsWith(before));
   assert.ok(derived.removedBlocks.includes('AGENTS.md'));
   assert.equal(derived.blocks['agents.md'], result.managedBlocks['agents.md']);