@pathbit/agentdevkit 0.0.17 → 0.0.18

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/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/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
@@ -44,3 +47,7 @@ presença de um bloco gerenciado.
 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,7 +11,7 @@ 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 -->';
@@ -79,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;
@@ -130,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();
@@ -295,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 = {};
@@ -307,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 = {};
@@ -551,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;
@@ -576,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);
@@ -594,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) {
@@ -649,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/PRESERVATION.mjs

@@ -0,0 +1,306 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { synchronize } from '../SCRIPT.mjs';
+import { indexContentMatches } from '../../lib/gitignore.mjs';
+
+const repository = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const original = '.pbai4devs/skills/projeto/criar-skill/SKILL.md';
+const pointer = '.claude/skills/criar-skill/SKILL.md';
+const file = (root, relative) => join(root, relative);
+const put = (root, relative, content) => { mkdirSync(dirname(file(root, relative)), { recursive: true }); writeFileSync(file(root, relative), content); };
+function git(root, ...args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+  assert.equal(result.status, 0, `${args.join(' ')}: ${result.stderr}`);
+  return result.stdout;
+}
+function fixture(t, withGit = true) {
+  mkdirSync(join(repository, '.agent-tests'), { recursive: true });
+  const root = mkdtempSync(join(withGit ? join(repository, '.agent-tests') : tmpdir(), 'sync-preservation-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  if (withGit) git(root, 'init', '--quiet');
+  populate(root);
+  return root;
+}
+function populate(root) {
+  put(root, '.gitignore', '# Human ignore\nnode_modules/\n');
+  put(root, '.pbai4devs/templates/gitignore/agents.ignore', '# Cache\n/*\n!/.gitignore\n{{ALLOWLIST}}\n/cache/\n*.log\n');
+  put(root, '.pbai4devs/templates/gitignore/clients.json', '{}\n');
+  put(root, '.pbai4devs/templates/gitignore/shared.ignore', '# Shared\n/tools/*/.local/\n');
+  put(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\n');
+  put(root, original, '---\nname: criar-skill\ndescription: Criar recurso.\n---\n\n# Criar skill\n');
+  assert.equal(run(root).exitCode, 0);
+  assert.ok(existsSync(file(root, pointer)));
+}
+function run(root, options = {}) {
+  return synchronize({ root, localIgnores: false, generateEntrypoints: false, output() {}, ...options });
+}
+function withoutGit(t, callback) {
+  const emptyPath = mkdtempSync(join(tmpdir(), 'sync-empty-path-'));
+  t.after(() => rmSync(emptyPath, { recursive: true, force: true }));
+  const keys = Object.keys(process.env).filter(key => key.toLowerCase() === 'path');
+  const previous = new Map(keys.map(key => [key, process.env[key]]));
+  if (!keys.length) keys.push('PATH');
+  try {
+    for (const key of keys) process.env[key] = emptyPath;
+    return callback();
+  } finally {
+    for (const key of keys) {
+      if (previous.has(key)) process.env[key] = previous.get(key);
+      else delete process.env[key];
+    }
+  }
+}
+
+for (const [withGit, force] of [[true, false], [true, true], [false, false], [false, true]]) {
+  test(`remoção obsoleta preserva pasta vazia humana (git=${withGit}, force=${force})`, t => {
+    const root = fixture(t, withGit), human = '.claude/skills/criar-skill/Equipe-Vazia';
+    mkdirSync(file(root, human));
+    const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+    const index = withGit ? git(root, 'ls-files', '--stage', '-z') : null;
+    const ignore = readFileSync(file(root, '.gitignore'));
+    rmSync(dirname(file(root, original)), { recursive: true });
+    const check = run(root, { check: true, force });
+    assert.notEqual(check.exitCode, 0);
+    assert.ok(existsSync(file(root, pointer)));
+    assert.ok(existsSync(file(root, human)));
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    run(root, { force });
+    assert.equal(existsSync(file(root, pointer)), false, 'apontamento obsoleto comprovado é removido');
+    assert.ok(existsSync(file(root, human)), 'pasta vazia própria permanece');
+    assert.deepEqual(readFileSync(file(root, '.gitignore')), ignore);
+    if (withGit) assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+for (const force of [false, true]) {
+  test(`índice com conteúdo humano divergente bloqueia remoção (force=${force})`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, pointer));
+    put(root, pointer, Buffer.concat([generated, Buffer.from('\nConteúdo humano staged.\n')]));
+    git(root, 'add', '-f', '--', pointer);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    put(root, pointer, generated);
+    rmSync(dirname(file(root, original)), { recursive: true });
+    const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+    const check = run(root, { check: true, force });
+    assert.notEqual(check.exitCode, 0);
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    assert.throws(() => run(root, { force }), /conflitos|indice|índice/i);
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+for (const force of [false, true]) {
+  test(`índice divergente impede atualização de apontamento ativo (force=${force})`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, pointer));
+    put(root, pointer, Buffer.concat([generated, Buffer.from('\nAlteração humana staged.\n')]));
+    git(root, 'add', '-f', '--', pointer);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    put(root, pointer, generated);
+    put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+    const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+    assert.notEqual(run(root, { check: true, force }).exitCode, 0);
+    assert.throws(() => run(root, { force }), /indice/i);
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+for (const flag of ['--assume-unchanged', '--skip-worktree']) {
+  test(`índice divergente continua protegido com ${flag}`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, pointer));
+    put(root, pointer, Buffer.concat([generated, Buffer.from('\nAlteração humana staged.\n')]));
+    git(root, 'add', '-f', '--', pointer);
+    put(root, pointer, generated);
+    git(root, 'update-index', flag, '--', pointer);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    const flags = git(root, 'ls-files', '-v', '--', pointer);
+    put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+    assert.notEqual(run(root, { check: true, force: true }).exitCode, 0);
+    assert.throws(() => run(root, { force: true }), /indice/i);
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+    assert.equal(git(root, 'ls-files', '-v', '--', pointer), flags);
+  });
+}
+
+test('índice com alias de caixa bloqueia alteração conservadoramente em qualquer sistema', t => {
+  const root = fixture(t), generated = readFileSync(file(root, pointer));
+  const alias = pointer.replace('/skills/', '/SKILLS/');
+  put(root, alias, Buffer.concat([generated, Buffer.from('\nAlteração humana staged.\n')]));
+  git(root, 'add', '-f', '--', alias);
+  const index = git(root, 'ls-files', '--stage', '-z');
+  put(root, pointer, generated);
+  put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+  const aliasBytes = readFileSync(file(root, alias));
+  const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+  const ignore = readFileSync(file(root, '.gitignore'));
+  const preserved = () => {
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.deepEqual(readFileSync(file(root, alias)), aliasBytes);
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    assert.deepEqual(readFileSync(file(root, '.gitignore')), ignore);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  };
+  let check, error;
+  try { check = run(root, { check: true, force: true }); } catch (failure) { error = failure; }
+  if (error) assert.match(error.message, /maiusculas\/minusculas/i);
+  else assert.notEqual(check.exitCode, 0);
+  preserved();
+  assert.throws(() => run(root, { force: true }), /indice|maiusculas\/minusculas/i);
+  preserved();
+});
+
+test('comparação de índice entende CRLF autorizado e recusa filtros, binários e divergência', t => {
+  const root = fixture(t), path = 'arquivo.txt';
+  const crlf = Buffer.from('texto\r\noutra linha\r\n'), lf = Buffer.from('texto\noutra linha\n');
+  git(root, 'config', 'core.autocrlf', 'false');
+  git(root, 'config', 'core.attributesfile', file(root, 'atributos-ausentes'));
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  git(root, 'config', 'core.autocrlf', 'true');
+  assert.equal(indexContentMatches(root, path, crlf, lf), true);
+  assert.equal(indexContentMatches(root, path, crlf, Buffer.from('texto humano\noutra linha\n')), false);
+  assert.equal(indexContentMatches(root, path, Buffer.from([0, 13, 10]), Buffer.from([0, 10])), false);
+  assert.equal(indexContentMatches(root, path, Buffer.from('um\r\ndois\r'), Buffer.from('um\ndois\r')), false);
+  assert.equal(indexContentMatches(root, path, Buffer.from('\ufefftexto\r\n'), Buffer.from('texto\n')), false);
+  assert.equal(indexContentMatches(root, path, Buffer.from('\ufefftexto\r\n'), Buffer.from('\ufefftexto\n')), true);
+  put(root, '.gitattributes', '*.txt -text\n');
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  put(root, '.gitattributes', '*.txt text filter=nao-executar\n');
+  git(root, 'config', 'filter.nao-executar.clean', 'exit 1');
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  put(root, '.gitattributes', '*.txt text working-tree-encoding=UTF-16\n');
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  put(root, '.gitattributes', '*.txt text ident\n');
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  put(root, '.gitattributes', '*.txt text eol=crlf\n');
+  git(root, 'config', 'core.autocrlf', 'false');
+  assert.equal(indexContentMatches(root, path, crlf, lf), true);
+});
+
+test('sync atualiza apontamento staged equivalente em repositório com autocrlf', t => {
+  const root = fixture(t), generated = readFileSync(file(root, pointer), 'utf8').replaceAll('\n', '\r\n');
+  git(root, 'config', 'core.autocrlf', 'true');
+  put(root, pointer, generated);
+  git(root, 'add', '-f', '--', pointer);
+  const index = git(root, 'ls-files', '--stage', '-z');
+  put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+  assert.equal(run(root, { force: true }).exitCode, 0);
+  assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+});
+
+for (const target of ['.pbai4devs/state/derived.json', '.claude/.gitignore']) {
+  test(`índice divergente impede atualização de ${target}`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, target));
+    put(root, target, Buffer.concat([generated, Buffer.from('\nAlteração humana staged.\n')]));
+    git(root, 'add', '-f', '--', target);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    put(root, target, generated);
+    if (target.endsWith('derived.json')) {
+      put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+    } else {
+      put(root, '.pbai4devs/templates/gitignore/agents.ignore', '# Cache atualizado\n/*\n!/.gitignore\n{{ALLOWLIST}}\n/cache/\n*.log\n');
+    }
+    assert.notEqual(run(root, { check: true, force: true }).exitCode, 0);
+    assert.throws(() => run(root, { force: true }), /indice/i);
+    assert.deepEqual(readFileSync(file(root, target)), generated);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+for (const options of [{ check: true }, { force: true }]) {
+  test(`Git indisponível bloqueia limpeza em repositório (check=${Boolean(options.check)}, force=${Boolean(options.force)})`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, pointer));
+    put(root, pointer, Buffer.concat([generated, Buffer.from('\nConteúdo humano staged.\n')]));
+    git(root, 'add', '-f', '--', pointer);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    put(root, pointer, generated);
+    rmSync(dirname(file(root, original)), { recursive: true });
+    const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+    withoutGit(t, () => assert.throws(() => run(root, options), /consultar o Git.*preservar/i));
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+test('projeto realmente sem Git pode limpar apontamento próprio sem executável Git', t => {
+  const root = fixture(t, false), human = '.claude/skills/criar-skill/equipe-vazia';
+  mkdirSync(file(root, human));
+  rmSync(dirname(file(root, original)), { recursive: true });
+  withoutGit(t, () => assert.equal(run(root, { force: true }).exitCode, 0));
+  assert.equal(existsSync(file(root, pointer)), false);
+  assert.ok(existsSync(file(root, human)));
+});
+
+test('preserva diretório preexistente sem prova de propriedade após remover único apontamento', t => {
+  const root = fixture(t), directory = dirname(file(root, pointer));
+  rmSync(dirname(file(root, original)), { recursive: true });
+  assert.equal(run(root, { force: true }).exitCode, 0);
+  assert.equal(existsSync(file(root, pointer)), false);
+  assert.ok(existsSync(directory));
+});
+
+test('alteração concorrente no índice bloqueia limpeza antes de qualquer exclusão', t => {
+  const root = fixture(t), generated = readFileSync(file(root, pointer));
+  rmSync(dirname(file(root, original)), { recursive: true });
+  let staged;
+  assert.throws(() => synchronize({ root, localIgnores: false, generateEntrypoints: false, force: true,
+    output() {
+      if (staged !== undefined) return;
+      put(root, pointer, Buffer.concat([generated, Buffer.from('\nStaged pela equipe.\n')]));
+      git(root, 'add', '-f', '--', pointer);
+      staged = git(root, 'ls-files', '--stage', '-z');
+      put(root, pointer, generated);
+    },
+  }), /indice git mudou/i);
+  assert.notEqual(staged, undefined);
+  assert.deepEqual(readFileSync(file(root, pointer)), generated);
+  assert.equal(git(root, 'ls-files', '--stage', '-z'), staged);
+});
+
+test('índice divergente é protegido quando o projeto fica em subpasta do repositório Git', t => {
+  const outer = mkdtempSync(join(tmpdir(), 'sync-parent-git-'));
+  t.after(() => rmSync(outer, { recursive: true, force: true }));
+  git(outer, 'init', '--quiet');
+  const root = join(outer, 'projeto'); mkdirSync(root);
+  populate(root);
+  const generated = readFileSync(file(root, pointer));
+  put(root, pointer, Buffer.concat([generated, Buffer.from('\nStaged pela equipe.\n')]));
+  git(root, 'add', '-f', '--', pointer);
+  const index = git(outer, 'ls-files', '--stage', '-z');
+  put(root, pointer, generated);
+  rmSync(dirname(file(root, original)), { recursive: true });
+  assert.throws(() => run(root, { force: true }), /indice/i);
+  assert.deepEqual(readFileSync(file(root, pointer)), generated);
+  assert.equal(git(outer, 'ls-files', '--stage', '-z'), index);
+});
+
+test('conteúdo humano na pasta e apontamento gerenciado editado sobrevivem à limpeza forçada', t => {
+  const root = fixture(t), human = '.claude/skills/criar-skill/notas-da-equipe.md';
+  const notes = '# Referência própria\n', edited = Buffer.concat([readFileSync(file(root, pointer)), Buffer.from('\nNota própria.\n')]);
+  put(root, human, notes);
+  put(root, pointer, edited);
+  rmSync(dirname(file(root, original)), { recursive: true });
+  run(root, { force: true });
+  assert.equal(readFileSync(file(root, human), 'utf8'), notes);
+  assert.deepEqual(readFileSync(file(root, pointer)), edited);
+});
+
+test('colisão com arquivo humano ancestral não é removida por --force', t => {
+  const root = fixture(t), ancestor = '.claude/skills/equipe-custom';
+  const human = 'Arquivo da equipe; não substituir.\n';
+  put(root, ancestor, human);
+  put(root, '.pbai4devs/skills/projeto/equipe-custom/SKILL.md', '---\nname: equipe-custom\ndescription: Exemplo.\n---\n\n# Equipe\n');
+  const index = git(root, 'ls-files', '--stage', '-z');
+  try { run(root, { force: true }); } catch (error) { assert.match(error.message, /conflito|gerenciado|arquivo|diretor/i); }
+  assert.equal(readFileSync(file(root, ancestor), 'utf8'), human);
+  assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+});

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

@@ -13,6 +13,7 @@ import './LOCAL_IGNORE.mjs';
 import './HUMAN_OWNERSHIP.mjs';
 import './COEXISTENCE.mjs';
 import './MANAGED_CONTENT.mjs';
+import './PRESERVATION.mjs';
 import { validateCatalog as validateExternalCatalog } from '../../gerenciar-skills-externas/SCRIPT.mjs';
 import { stateDirectory } from '../../lib/state-path.mjs';
 
@@ -140,7 +141,12 @@ test('sincroniza somente principais, preserva metadados e usa referências UTF-8
   assert.match(read(root, '.kimi-code/agents/revisor.md'), /tools: \[Read, Grep, Glob\]/);
   assert.ok(existsSync(join(root, '.claude/skills/projeto/demo/SKILL.md')));
   for (const client of ['.claude', '.opencode', '.github', '.codex', '.cursor', '.kimi-code', '.vscode', '.agents', '.agent', '.gemini']) {
-  for (const kind of ['templates', 'scripts', 'tools', 'external-skills', 'state', 'estado', 'tests', 'docs', 'adapters', 'extra', 'README.md', 'INSTRUCTIONS.md']) assert.equal(existsSync(join(root, client, kind)), false, `${client}/${kind}`);
+    for (const kind of ['templates', 'scripts', 'tools', 'external-skills', 'state', 'estado', 'tests', 'docs', 'adapters', 'extra', 'README.md', 'INSTRUCTIONS.md']) {
+      if (client === '.claude' && ['templates', 'scripts', 'tools', 'external-skills', 'state', 'tests', 'docs', 'adapters'].includes(kind)) {
+        assert.equal(existsSync(join(root, client, kind, 'demo/REFERENCE.md')), false);
+        assert.ok(existsSync(join(root, client, kind)), 'diretório sem prova de propriedade permanece');
+      } else assert.equal(existsSync(join(root, client, kind)), false, `${client}/${kind}`);
+    }
   }
   assert.deepEqual(JSON.parse(read(root, '.pbai4devs/agents.json')).entries, [{ path: '.pbai4devs/agents/revisor/AGENT.md' }]);
   assert.ok(JSON.parse(read(root, '.pbai4devs/skills.json')).entries.some(entry => entry.path === '.pbai4devs/skills/grupo com espaço/outro'));
@@ -441,7 +447,8 @@ test('atualiza fontes, adiciona clientes, remove recursos e migra agrupado para
   rmSync(join(root, '.pbai4devs/rules/example/RULE.md'));
   write(root, '.pbai4devs/espelhos.conf', read(root, '.pbai4devs/espelhos.conf').replace('agente|.claude\n', 'agente|.claude|plano\n'));
   run(root);
-  assert.equal(existsSync(join(root, '.claude/skills/projeto')), false);
+  assert.equal(existsSync(join(root, '.claude/skills/projeto/demo/SKILL.md')), false);
+  assert.ok(existsSync(join(root, '.claude/skills/projeto')));
   assert.ok(existsSync(join(root, '.claude/skills/demo/SKILL.md')));
   assert.equal(existsSync(join(root, '.codex/rules/example.md')), false);
   assert.deepEqual(JSON.parse(read(root, '.pbai4devs/rules.json')).entries, []);
@@ -882,7 +889,8 @@ test('manifestos Antigravity acompanham skills, regras e agentes agrupados', t =
   rmSync(join(root, '.pbai4devs/skills/projeto/demo'), { recursive: true });
   run(root, { generateEntrypoints: true });
   assert.deepEqual(JSON.parse(read(root, '.agents/skills.json')).entries, [{ path: '.agents/skills/projeto/new-skill' }]);
-  assert.equal(existsSync(join(root, '.agents/skills/projeto/demo')), false);
+  assert.equal(existsSync(join(root, '.agents/skills/projeto/demo/SKILL.md')), false);
+  assert.ok(existsSync(join(root, '.agents/skills/projeto/demo')));
   assertCheckReadonly(root, { generateEntrypoints: true }, 0);
 });
 

package/CHANGELOG.md

@@ -4,6 +4,12 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.18 — 2026-11-13
+
+- Sincronização preserva recursos próprios, colisões e alterações humanas.
+- Limpeza de recursos obsoletos exige comprovação de propriedade.
+- Comandos e efeitos sobre arquivos, índice e backups documentados.
+
 ## 0.0.17 — 2026-11-13
 
 - A pasta compartilhada de estado passa a se chamar `.pbai4devs/state`.

package/docs/guides/cli.md

@@ -22,17 +22,17 @@ atendido; lá os comandos de manutenção usam o pacote por `npx`.
 
 | Comando | Resultado |
 | --- | --- |
-| `init [pasta]` | Instala ou reaplica os recursos. |
-| `update` | Usa os recursos da versão do pacote executado. |
-| `sync` | Reconstrói as derivações da fonte do projeto. |
-| `sync --check` | Confere as derivações sem escrever. |
-| `doctor` | Diagnostica a instalação. |
-| `next` | Orienta a próxima etapa do projeto. |
+| `init [pasta]` | Instala o kit no projeto ou reaplica a instalação. |
+| `update` | Atualiza a fonte usando a versão do pacote executado. |
+| `sync` | Atualiza catálogos e apontamentos a partir da fonte local. |
+| `sync --check` | Confere sincronização sem alterar o projeto. |
+| `doctor` | Diagnostica o kit e indica divergências. |
+| `next` | Mostra a próxima etapa, sem iniciá-la. |
 | `lang [idioma]` | Consulta ou altera o idioma: pt, en ou es. |
-| `agents` | Consulta clientes disponíveis e seleção local. |
-| `agents codex,claude` | Altera a seleção local. |
-| `agents all` | Habilita todos os clientes. |
-| `tools <ação>` | Executa o gerenciador de ferramentas. |
+| `agents` | Mostra os clientes disponíveis e a seleção salva. |
+| `agents codex,claude` | Altera a seleção e os apontamentos necessários. |
+| `agents all` | Seleciona todos os clientes compatíveis. |
+| `tools <ação>` | Consulta, instala, atualiza ou executa ferramentas. |
 | `--help`, `--version` | Ajuda ou versão do pacote. |
 
 Sem comando, a CLI executa `init`, que pode criar arquivos. `language` é alias
@@ -48,16 +48,47 @@ de `lang`; `clients`, de `agents`. O idioma não traduz documentos existentes.
 | `--clients <lista>` | Alias de `--agents`. |
 | `--yes`, `-y` | Evita perguntas iniciais; não força conflitos. |
 | `--dry-run` | Exibe o plano sem aplicar alterações. |
-| `--force` | Substitui conflitos gerenciados, com backup. |
+| `--force` | Solicita reparos gerenciados permitidos, com backup. |
 | `--json` | Produz uma resposta JSON para automação. |
 
 O primeiro uso interativo reúne idioma e clientes. Sem interação, valem as
 opções explícitas, a escolha local salva e, por último, `all`. Confira os
 [IDs e dependências](../../.pbai4devs/COMPATIBILIDADE.md).
 
-`update` não procura automaticamente a próxima versão: execute o pacote
-da versão desejada. `sync` não atualiza a fonte distribuída.
-A seleção e os derivados são locais; o source compartilhado permanece no Git.
+`update` usa a versão executada; para escolher outra, fixe-a no nome do
+pacote. `sync` usa o que já está em `.pbai4devs`: ele não baixa outra versão.
+Ambos conciliam recursos e removem apontamentos obsoletos quando a propriedade
+do kit é comprovada. Recursos e configurações próprios permanecem no projeto.
+Diretórios antigos sem comprovação de propriedade podem permanecer vazios.
+Ao mudar a seleção, pastas compartilhadas continuam quando outro cliente
+precisa delas; arquivos adicionais da equipe devem ser preservados.
+
+Antes de aplicar em projeto existente, confira o plano e depois o diagnóstico:
+
+```console
+npx @pathbit/agentdevkit update --dry-run --json
+npx @pathbit/agentdevkit update
+npx @pathbit/agentdevkit doctor
+npx @pathbit/agentdevkit sync --check
+```
+
+Use `init --dry-run --json`, `sync --dry-run --json` ou
+`agents codex,claude --dry-run --json` para as outras operações. Examine
+`plan`, `conflicts`, `preserved`, `untrackedPaths` e `localIgnore` antes de
+aplicar. Conflitos sem solução interrompem a operação; não presuma que uma
+colisão de nomes torna um arquivo propriedade do kit.
+
+O sincronizador independente também pode ser executado pelo
+[script local](../../.pbai4devs/scripts/sincronizar-agentes/README.md). Seu
+`--check` apenas confere e `--force` é explícito na linha de comando. O
+comando agêntico [sincronizar](../../.pbai4devs/commands/sincronizar/COMMAND.md)
+orienta executar o script com `--force`; ele não é o mesmo que `sync` da CLI.
+
+No Git, o kit preserva o `.gitignore` da raiz e pode atualizar
+`.git/info/exclude`. Se o plano indicar `untrackedPaths`, a operação pode
+retirar do índice saídas comprovadamente geradas, mantendo seus arquivos no
+disco. Confira a lista: `--dry-run` e `sync --check` não alteram o índice.
+Backups locais ficam em `.agent-tests/` e não substituem o histórico Git.
 
 ## Ferramentas
 
@@ -80,7 +111,7 @@ do separador. `--help` e `--version` do kit não exigem um projeto instalado.
 As respostas incluem `ok`, `command`, `version`, `language`, `target` e
 `next`. Conforme a operação, há seleção, plano, conflitos, backup e erros.
 Leia os campos estruturados, não dependa da tradução da mensagem.
-`preserved` lista caminhos nativos humanos mantidos pelo projeto, com o motivo.
+`preserved` lista caminhos mantidos pelo projeto e o motivo.
 Um complemento pode ser gerenciado por bloco sem tornar o arquivo propriedade
 do kit. Conteúdo humano não é substituído por `--force`.
 

package/docs/guides/installation.md

@@ -111,7 +111,7 @@ usar `git add`. No GitHub Packages, use o prefixo de registry da instalação.
 
 O bloco local também protege `.agent-tests`, `tmp`, `temp`, `.playwright*`
 e relatórios de testes, inclusive com letras maiúsculas e em subpastas.
-O conteúdo do `.gitignore` existente e os arquivos rastreados são preservados.
+O conteúdo do `.gitignore` existente na raiz é preservado.
 Uma exceção que reabra arquivo privado ou artefato é informada como conflito;
 o projeto decide como ajustar suas próprias regras.
 Negativas com curingas também podem ser recusadas preventivamente, mesmo antes
@@ -121,6 +121,9 @@ a validação fica restrita ao projeto e aos ignores de seus ancestrais.
 
 Arquivos já rastreados exigem migração do índice: apenas saídas identificadas
 do kit podem deixar de ser rastreadas, preservando seus bytes no disco.
+O plano informa esses caminhos em `untrackedPaths` antes de aplicar; examine-os
+e preserve alterações preparadas da equipe. `--dry-run` e `sync --check` não
+alteram o índice.
 Artefatos já rastreados são informados por `doctor` e `sync --check` para
 revisão; não são removidos automaticamente do índice.
 Revise o plano e os conflitos em um projeto existente; use `--dry-run` antes
@@ -133,13 +136,20 @@ continua válida; `agents` consulta e `agents codex,claude` altera a seleção.
 `agents all` habilita todos. As pastas compartilhadas permanecem quando
 necessárias para outro cliente, como `.agents` para Codex e Antigravity.
 
-Confira a simulação antes de atualizar um projeto existente. Arquivos
-gerenciados alterados geram conflito; use `--force` somente após revisar o
-backup e o conteúdo que será substituído. Preserve os dados locais, as
-configurações próprias e os commits do projeto.
+Confira `update --dry-run --json` antes de atualizar um projeto existente.
+Revise arquivos criados, atualizados e removidos, conflitos, `preserved` e
+eventuais alterações do índice. `sync` usa as fontes já instaladas e não baixa
+uma nova versão. Consulte a [referência da CLI](cli.md) para todos os comandos.
 
-Entradas como `AGENTS.md`, `claude.md` e `GEMINI.md`, além de skills, agentes,
-comandos e regras existentes, recebem apenas um complemento do kit:
+Skills e outros recursos próprios podem coexistir com os do kit. Um nome
+igual não comprova propriedade: conteúdo humano e arquivos adicionais não
+devem ser descartados para reconstruir apontamentos. Remoções automáticas
+ficam restritas a arquivos obsoletos cuja propriedade possa ser comprovada.
+`--force` não autoriza substituir conteúdo próprio; backups ficam em
+`.agent-tests/` e devem ser revisados quando houver reparo gerenciado.
+
+Em entradas como `AGENTS.md`, `claude.md` e `GEMINI.md`, e em recursos nativos
+compatíveis, o kit pode acrescentar apenas uma referência delimitada:
 
 ```markdown
 <!-- BEGIN AGENTDEVKIT -->
@@ -148,7 +158,9 @@ Leia e siga [origem](caminho/para/.pbai4devs/recurso.md).
 ```
 
 O texto e o frontmatter humanos permanecem; a referência usa o caminho real
-do recurso. Repetir a operação não duplica o bloco. Edite suas instruções fora
+do recurso. Um arquivo que não possa receber o bloco é preservado e informado,
+sem prometer a adição do apontamento. Repetir a operação não duplica o bloco.
+Edite suas instruções fora
 dele: atualizações alteram somente a contribuição do kit. Nomes de entradas
 com caixa diferente são reaproveitados quando há uma única opção.
 Comandos Gemini mantêm a referência dentro do valor `prompt` em TOML válido.

package/docs/specs/README.md

@@ -21,6 +21,7 @@ description: Incrementos verificáveis do AgentDevKit.
   especialistas, colaboração e provas.
 - [Confiabilidade da pipeline](ci-resilience/SPEC.md): testes e releases.
 - [Pasta de estado](state-directory/SPEC.md): migração segura para `state`.
+- [Sincronização segura](safe-synchronization/SPEC.md): preservar recursos próprios.
 - [Integração sem substituição][additive]: acréscimos em arquivos existentes.
 - [Compatibilidade com projetos reais][oss]: projetos públicos e exemplos reproduzíveis.
 - [Ignore do projeto](project-ignore/SPEC.md): preservar o arquivo da raiz.

package/docs/specs/safe-synchronization/SPEC.md

@@ -0,0 +1,21 @@
+---
+description: Sincronização segura com recursos e alterações próprios do projeto.
+---
+
+# Sincronização segura
+
+Projetos podem ter arquivos próprios e recursos adicionais aos do pacote.
+Os comandos devem preservar esse conteúdo ao instalar, atualizar e sincronizar.
+
+## Critérios de aceite
+
+- AC-001: Recursos humanos ou modificados no hub e nos clientes são
+  preservados, inclusive em colisões e com `--force`.
+- AC-002: A limpeza remove somente saídas obsoletas com propriedade comprovada;
+  pastas e arquivos adicionais da equipe não são removidos.
+- AC-003: Um conteúdo divergente preparado no índice não é descartado pela
+  sincronização; `.gitignore` da raiz e dados humanos são preservados.
+- AC-004: `init`, `update`, `sync`, consultas e opções estão documentados com
+  seus efeitos sobre arquivos, backups, seleção de clientes e Git.
+- AC-005: Testes exercitam instalações existentes, obsolescência, colisões,
+  execução repetida, Git e falhas; a CI contempla Linux, Windows e macOS.

package/package.json

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

package/src/i18n.mjs

@@ -42,6 +42,16 @@ const messages = {
 };
 export const text = (language, key) => messages[language || 'pt'][key] || key;
 export function explainError(language, code) {
+  if (code === 'E_STAGED') return {
+    pt: 'Há alterações preparadas diferentes dos arquivos locais; revise-as antes de atualizar.',
+    en: 'Staged changes differ from the working files; review them before updating.',
+    es: 'Hay cambios preparados distintos de los archivos locales; revíselos antes de actualizar.',
+  }[language || 'pt'];
+  if (code === 'E_GIT') return {
+    pt: 'Não foi possível verificar o índice Git com segurança; nenhum arquivo foi alterado.',
+    en: 'The Git index could not be checked safely; no files were changed.',
+    es: 'No se pudo verificar el índice Git de forma segura; no se modificaron archivos.',
+  }[language || 'pt'];
   if (code === 'E_CONFIG_PARSE') return {
     pt: 'Não foi possível analisar a configuração legada com segurança; revise o frontmatter e as aspas antes de executar update.',
     en: 'The legacy configuration could not be safely parsed; review its frontmatter and quoted values before running update.',

package/src/install.mjs

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
 import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, writeFileSync, readdirSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { synchronize, isReference } from '../.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
-import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, planUntrack, applyUntrack, restoreUntrack } from '../.pbai4devs/scripts/lib/gitignore.mjs';
+import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, planUntrack, applyUntrack, restoreUntrack, indexContentMatches } from '../.pbai4devs/scripts/lib/gitignore.mjs';
 import { nativePathBoundary } from '../.pbai4devs/scripts/lib/native-paths.mjs';
 import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, extractManagedBlock, managedBlockDigest, mergeManagedContent, stripManagedContent } from '../.pbai4devs/scripts/lib/managed-content.mjs';
 import { extractTomlManagedBlock, tomlManagedBlockDigest, mergeTomlContent, stripTomlContent } from '../.pbai4devs/scripts/lib/managed-toml.mjs';
@@ -15,6 +16,122 @@ const hash = value => createHash('sha256').update(value).digest('hex');
 const portable = value => value.split(sep).join('/');
 const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
 const stat = path => { try { return lstatSync(path); } catch (error) { if (error.code === 'ENOENT') return null; throw error; } };
+
+// Protect staged human bytes that differ from the working tree, without
+// treating an unchanged HEAD entry as a staged edit or rewriting the index.
+function stagedDivergences(root) {
+  let anchor = resolve(root);
+  while (!existsSync(anchor)) {
+    const parent = dirname(anchor);
+    if (parent === anchor) break;
+    anchor = parent;
+  }
+  const prefix = portable(relative(anchor, root));
+  let hasGitMarker = false;
+  for (let current = anchor; ; current = dirname(current)) {
+    if (stat(join(current, '.git'))) { hasGitMarker = true; break; }
+    if (dirname(current) === current) break;
+  }
+  const env = { ...process.env, GIT_OPTIONAL_LOCKS: '0' };
+  for (const key of ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_COMMON_DIR', 'GIT_INDEX_FILE', 'GIT_EXTERNAL_DIFF']) delete env[key];
+  const run = args => spawnSync('git', ['-C', anchor, '-c', 'core.fsmonitor=false', ...args], {
+    env, timeout: 30000, windowsHide: true, maxBuffer: 16 * 1024 * 1024,
+  });
+  const repository = run(['rev-parse', '--is-inside-work-tree']);
+  if (repository.error || repository.status !== 0) {
+    if (hasGitMarker) fail('E_GIT', 'Unable to inspect the existing Git repository safely.');
+    if (repository.error?.code === 'ENOENT' || !repository.error && repository.status !== 0) return new Set();
+  }
+  if (repository.error || repository.status !== 0 || repository.stdout.toString('utf8').trim() !== 'true') fail('E_GIT', 'Unable to inspect Git worktree.');
+  // `git diff` against the worktree respects assume-unchanged and
+  // skip-worktree, so compare the actual bytes to the index blobs instead.
+  const stagedResult = run(['diff', '--cached', '--no-renames', '--no-ext-diff', '--no-textconv', '--name-only', '--relative', '-z']);
+  const indexResult = run(['ls-files', '--stage', '-z']);
+  if (stagedResult.error || stagedResult.status !== 0 || indexResult.error || indexResult.status !== 0) fail('E_GIT', 'Unable to inspect staged changes safely.');
+  const decode = buffer => {
+    const value = buffer.toString('utf8');
+    if (!Buffer.from(value, 'utf8').equals(buffer)) fail('E_GIT', 'Unable to safely inspect a non-UTF-8 staged path.');
+    return value;
+  };
+  const records = buffer => {
+    const result = []; let start = 0;
+    for (let i = 0; i < buffer.length; i++) if (buffer[i] === 0) { result.push(buffer.subarray(start, i)); start = i + 1; }
+    if (start !== buffer.length) fail('E_GIT', 'Unable to parse Git output safely.');
+    return result;
+  };
+  const paths = new Set(records(stagedResult.stdout).map(decode));
+  const entries = new Map();
+  for (const bytes of records(indexResult.stdout)) {
+    const tab = bytes.indexOf(9);
+    const record = bytes.subarray(0, tab).toString('ascii');
+    if (tab < 0) fail('E_GIT', 'Unable to parse the Git index safely.');
+    const match = /^(\d+) ([0-9a-f]+) ([0-3])$/.exec(record);
+    if (!match) fail('E_GIT', 'Unable to parse the Git index safely.');
+    const rawName = bytes.subarray(tab + 1);
+    const name = rawName.toString('utf8');
+    if (!paths.has(name)) continue;
+    if (!Buffer.from(name, 'utf8').equals(rawName)) fail('E_GIT', 'Unable to safely inspect a non-UTF-8 staged path.');
+    if (entries.has(name) || match[3] !== '0') entries.set(name, null);
+    else entries.set(name, { mode: match[1], oid: match[2] });
+  }
+  const divergent = new Set();
+  divergent.deleted = new Set();
+  for (const name of paths) {
+    if (prefix && !name.startsWith(`${prefix}/`)) continue;
+    const path = prefix ? name.slice(prefix.length + 1) : name;
+    const entry = entries.get(name);
+    // Distinguish a staged deletion from unresolved index stages.
+    if (!entries.has(name)) { divergent.add(path); divergent.deleted.add(path); continue; }
+    if (!entry || !['100644', '100755'].includes(entry.mode) || ![40, 64].includes(entry.oid.length)) { divergent.add(path); continue; }
+    let fd;
+    try {
+      const file = safePath(root, path), info = stat(file);
+      if (!info?.isFile()) { divergent.add(path); continue; }
+      fd = openSync(file, 'r');
+      const before = fstatSync(fd);
+      const digest = createHash(entry.oid.length === 64 ? 'sha256' : 'sha1').update(`blob ${before.size}\0`);
+      const buffer = Buffer.allocUnsafe(64 * 1024);
+      let count = 0, n;
+      while ((n = readSync(fd, buffer, 0, buffer.length, null)) !== 0) { digest.update(buffer.subarray(0, n)); count += n; }
+      const after = fstatSync(fd);
+      if (count !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs) { divergent.add(path); continue; }
+      if (digest.digest('hex') !== entry.oid) {
+        const indexed = run(['cat-file', 'blob', entry.oid]);
+        const working = readFileSync(file), latest = fstatSync(fd);
+        if (indexed.error || indexed.status !== 0) fail('E_GIT', 'Unable to inspect staged content safely.');
+        if (latest.size !== after.size || latest.mtimeMs !== after.mtimeMs || !indexContentMatches(root, path, working, indexed.stdout)) divergent.add(path);
+      }
+    } catch (error) {
+      // Treat paths that cannot be inspected (including symbolic links) as
+      // divergent; the normal safety checks still reject unsafe writes.
+      if (error.code === 'E_SYMLINK' || error.code === 'ENOENT' || error.code === 'ENOTDIR' || error.code === 'E_PATH') divergent.add(path);
+      else throw error;
+    } finally { if (fd !== undefined) closeSync(fd); }
+  }
+  return divergent;
+}
+// A staged name may use another case for the same path on macOS or Windows.
+// Probe an existing directory only; do not create files during a dry run.
+function stagedContains(root, paths, path) {
+  if (paths.has(path)) return true;
+  let current = root;
+  while (!stat(current) && dirname(current) !== current) current = dirname(current);
+  while (dirname(current) !== current) {
+    const base = current.slice(dirname(current).length + 1);
+    const index = base.search(/[A-Za-z]/);
+    if (index >= 0) {
+      const letter = base[index];
+      const other = letter === letter.toUpperCase() ? letter.toLowerCase() : letter.toUpperCase();
+      const alternative = join(dirname(current), `${base.slice(0, index)}${other}${base.slice(index + 1)}`);
+      const a = stat(current), b = stat(alternative);
+      if (!a || !b || a.dev !== b.dev || a.ino !== b.ino) return false;
+      return [...paths].some(candidate => candidate.toLowerCase() === path.toLowerCase());
+    }
+    current = dirname(current);
+  }
+  // If no existing name can be probed, preserve on ambiguity.
+  return [...paths].some(candidate => candidate.toLowerCase() === path.toLowerCase());
+}
 const ignored = new Set(['.git', '.local', '.cache', 'node_modules', '.agent-tests', 'opencode-loop']);
 const reservedTargets = new Set(['.git', 'node_modules', '.pbai4devs']);
 const checkTarget = path => {
@@ -71,7 +188,10 @@ function walk(root, path = '', filter = () => true) {
   for (const name of readdirSync(directory).sort()) {
     const child = path ? `${path}/${name}` : name;
     const info = lstatSync(join(root, child));
-    if (info.isSymbolicLink()) fail('E_SYMLINK', `Symbolic link refused: ${child}`);
+    if (info.isSymbolicLink()) {
+      if (!filter(child, false) && !filter(child, true)) continue;
+      fail('E_SYMLINK', `Symbolic link refused: ${child}`);
+    }
     if (!filter(child, info.isDirectory())) continue;
     if (info.isDirectory()) files.push(...walk(root, child, filter));
     else if (info.isFile()) files.push(child);
@@ -109,7 +229,7 @@ function read(root, path) {
 }
 
 function allowedManaged(path) {
-  if (path === '.pbai4devs/estado/README.md') return true;
+  if (['.pbai4devs/estado/README.md', '.pbai4devs/adapters/README.md'].includes(path)) return true;
   if (canonicalEntrypoint(path) || path === '.gitignore') return true;
   if (nativeMarkdown(path) || nativeToml(path)) return true;
   if (['catalog.json', 'skills.json', 'agents.json', 'rules.json', 'espelhos.conf'].some(name => path === `.pbai4devs/${name}`)) return true;
@@ -316,6 +436,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     ?? (canonicalEntrypoint(path) ? Object.entries(knownBlocks).find(([candidate]) => canonicalEntrypoint(candidate) === canonicalEntrypoint(path))?.[1] : undefined);
   const preserved = new Map();
   const recordPreserved = (path, reason) => { preserved.set(path, { path, reason }); return true; };
+  const stagedHuman = stagedDivergences(target);
   const native = path => canonicalEntrypoint(path) || path === 'README.md' || adapterRoots.some(root => path === root || path.startsWith(`${root}/`));
   const boundary = path => {
     if (!native(path)) return false;
@@ -353,8 +474,27 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     }
     const supplied = new Set(bundled);
     const internal = new Set(['catalog.json', 'skills.json', 'agents.json', 'rules.json', 'espelhos.conf', '.gitignore', 'state/README.md', 'estado/README.md']);
-    if (bundled.length) for (const path of Object.keys(previous?.files || {})) {
-      if (path.startsWith('.pbai4devs/') && !supplied.has(path.slice(11)) && !internal.has(path.slice(11))) rmSync(safePath(stage, path), { force: true });
+    // A pathname, matching contents, or --force alone do not establish that a
+    // project's hub source belongs to the kit. Restore human files *before*
+    // deriving native pointers so that the staged catalogue describes the
+    // source that will actually remain in the project.
+    const preservedHub = new Set();
+    for (const relative of existing) {
+      const path = `.pbai4devs/${relative}`;
+      if (internal.has(relative)) continue;
+      const current = read(target, path);
+      if (!current || previous?.files?.[path] === hash(current) && !stagedContains(target, stagedHuman, path)) continue;
+      if (supplied.has(relative)) write(stage, path, current);
+      preservedHub.add(path);
+      recordPreserved(path, stagedContains(target, stagedHuman, path) ? 'staged-content-differs' : previous?.files?.[path] ? 'edited-managed-file' : 'existing-file');
+    }
+    if (bundled.length) for (const [path, digest] of Object.entries(previous?.files || {})) {
+      if (!path.startsWith('.pbai4devs/') || supplied.has(path.slice(11)) || internal.has(path.slice(11))) continue;
+      const current = read(target, path);
+      if (current && (digest !== hash(current) || stagedContains(target, stagedHuman, path))) {
+        preservedHub.add(path);
+        recordPreserved(path, stagedContains(target, stagedHuman, path) ? 'staged-content-differs' : 'edited-managed-file');
+      } else rmSync(safePath(stage, path), { force: true });
     }
     for (const root of active.roots) {
       if (preserveNative(`${root}/.gitignore`)) continue;
@@ -432,7 +572,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const manifest = { schemaVersion: 1, version: bundled.length ? packageInfo.version : previous.version, language, files: {}, blocks: {} };
     if (mode !== 'sync' || clients !== undefined || previous?.clients !== undefined) manifest.clients = selected;
     for (const [path, content] of desired) {
-      if (path === 'README.md' || migratedHuman.has(path)) continue;
+      if (path === 'README.md' || migratedHuman.has(path) || preservedHub.has(path)) continue;
       const block = blockDigest(path, content);
       if (block) manifest.blocks[path] = block;
       else manifest.files[path] = hash(content);
@@ -460,8 +600,8 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (aliasedEntrypoint(path)) continue;
       const current = read(target, path); if (!current) continue;
       const known = wholeRecords.some(record => record[path] === hash(current));
-      if (nativeManagedText(path) && !known) { recordPreserved(path, 'existing-file'); continue; }
-      if (!known) conflicts.push(path);
+      if (stagedContains(target, stagedHuman, path)) { recordPreserved(path, 'staged-content-differs'); continue; }
+      if (!known) { recordPreserved(path, 'edited-managed-file'); continue; }
       changes.push({ path, action: 'remove', content: null, beforeHash: hash(current) });
     }
     for (const [recordedPath, digest] of Object.entries(knownBlocks)) {
@@ -509,13 +649,53 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (preserved.has(full) || !known || !generatedReference(current)) { recordPreserved(full, 'existing-file'); continue; }
       changes.push({ path: full, action: 'remove', content: null, beforeHash: hash(current) });
     }
-    const legacy = '.pbai4devs/adapters/README.md', legacyContent = read(target, legacy);
-    if (legacyContent) {
-      const known = legacyContent.toString('utf8').includes('# Adaptadores') && /Antigravity|metadados/.test(legacyContent.toString('utf8'));
-      if (!known) conflicts.push(legacy);
-      changes.push({ path: legacy, action: 'remove', content: null, beforeHash: hash(legacyContent) });
+    const legacy = '.pbai4devs/adapters/README.md', legacyRoot = '.pbai4devs/adapters';
+    const legacyRootInfo = stat(join(target, legacyRoot));
+    const legacyInfo = legacyRootInfo?.isDirectory() ? stat(join(target, legacy)) : null;
+    if (legacyRootInfo && !legacyRootInfo.isDirectory()) recordPreserved(legacyRoot, legacyRootInfo.isSymbolicLink() ? 'symbolic-link' : 'existing-file');
+    if (legacyInfo && !legacyInfo.isFile()) recordPreserved(legacy, legacyInfo.isSymbolicLink() ? 'symbolic-link' : 'existing-directory');
+    const legacyContent = legacyInfo?.isFile() ? read(target, legacy) : null;
+    if (legacyContent && !changes.some(change => change.path === legacy)) {
+      if (!stagedContains(target, stagedHuman, legacy) && previous?.files?.[legacy] === hash(legacyContent)) changes.push({ path: legacy, action: 'remove', content: null, beforeHash: hash(legacyContent) });
+      else recordPreserved(legacy, stagedContains(target, stagedHuman, legacy) ? 'staged-content-differs' : 'existing-file');
     }
     for (const item of migration?.files || []) changes.push({ path: item.path, action: 'remove', content: null, beforeHash: hash(item.content) });
+    // The generated catalogues must agree with the installed sources. A staged
+    // deletion has no indexed bytes to overwrite; allow their regeneration only
+    // when the current file exactly matches the previously owned digest.
+    const generatedCatalogues = new Set(['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']);
+    for (const change of changes) if (change.action === 'update' && generatedCatalogues.has(change.path)
+      && stagedContains(target, stagedHuman.deleted || new Set(), change.path)
+      && change.beforeHash && previous?.files?.[change.path] === change.beforeHash) change.stagedDeletionAllowed = true;
+    for (const change of changes) {
+      if (!stagedContains(target, stagedHuman, change.path)) continue;
+      const current = read(target, change.path);
+      if (change.action === 'update' && current && change.content && nativeManagedText(change.path)) {
+        // Preserve every byte outside a known managed block. Appending a block
+        // is also safe when the complete existing file is an exact prefix.
+        if (!nativeToml(change.path) && change.content.subarray(0, current.length).equals(current)) {
+          try {
+            const digest = managedBlockDigest(change.content);
+            const stripped = digest && stripManagedContent(change.content, digest);
+            const extra = stripped?.slice(current.toString('utf8').length);
+            if (stripped?.startsWith(current.toString('utf8')) && extra !== undefined && /^[\r\n]*$/.test(extra)) change.stagedBlockAllowed = true;
+          } catch { /* Invalid or unproven block: keep the path blocked. */ }
+        } else if (knownBlocks[change.path]) {
+          try {
+            const strip = nativeToml(change.path) ? stripTomlContent : stripManagedContent;
+            if (Buffer.from(strip(current, knownBlocks[change.path])).equals(change.content)) change.stagedBlockAllowed = true;
+          } catch { /* An edited block is not safe to remove. */ }
+        }
+      }
+      if (change.action === 'remove' && migration) {
+        const item = migration.files.find(file => file.path === change.path);
+        const copy = item && changes.find(candidate => candidate.path === item.target && candidate.action === 'create');
+        if (item && current?.equals(item.content) && copy?.content?.equals(item.content)
+          && changes.indexOf(copy) < changes.indexOf(change)) change.stagedMigrationTarget = item.target;
+      }
+    }
+    const stagedChanges = changes.filter(change => stagedContains(target, stagedHuman, change.path) && !change.stagedDeletionAllowed && !change.stagedBlockAllowed && !change.stagedMigrationTarget);
+    if (stagedChanges.length) fail('E_STAGED', `Staged content differs from the working tree for planned changes: ${stagedChanges.map(change => `${change.action} ${change.path}`).join(', ')}. Preserve and review these paths before updating.`);
     const retiredRoots = adapterRoots.filter(root => !active.roots.includes(root) && changes.some(change => change.action === 'remove' && change.path.startsWith(`${root}/`) && (previous?.files[change.path] || previous?.blocks[change.path])));
     const ownedOutputs = [...new Set([...synchronized.ownedOutputs, ...ownedEntrypoints, statePath])].filter(path => !mixedPaths.has(path) && !overlapsPreserved(path));
     const hashes = {};
@@ -539,6 +719,24 @@ export function applyPlan(plan) {
   if (!plan.canApply) fail('E_CONFLICT', text(plan.language, 'conflict'));
   assertLocalIgnoreUnchanged(plan.localIgnore);
   const { target } = plan;
+  const stagedHuman = stagedDivergences(target);
+  const currentState = loadState(target);
+  const stagedChanges = plan.changes.filter(change => {
+    if (!stagedContains(target, stagedHuman, change.path)) return false;
+    const current = read(target, change.path);
+    if ((current ? hash(current) : null) !== change.beforeHash) fail('E_CHANGED', `File changed after planning: ${change.path}`);
+    if (!current) return true;
+    if (change.stagedDeletionAllowed && stagedContains(target, stagedHuman.deleted || new Set(), change.path)
+      && currentState?.files?.[change.path] === change.beforeHash) return false;
+    if (change.stagedBlockAllowed) return false; // Exact source and planned bytes were checked above.
+    if (change.stagedMigrationTarget) {
+      const copy = plan.changes.find(candidate => candidate.path === change.stagedMigrationTarget && candidate.action === 'create');
+      if (copy?.content?.equals(current) && plan.changes.indexOf(copy) < plan.changes.indexOf(change)
+        && !stat(safePath(target, change.stagedMigrationTarget))) return false;
+    }
+    return true;
+  });
+  if (stagedChanges.length) fail('E_STAGED', `Staged content differs from the working tree for planned changes: ${stagedChanges.map(change => `${change.action} ${change.path}`).join(', ')}. Preserve and review these paths before updating.`);
   if (plan.migration) {
     if (stat(safePath(target, '.pbai4devs/state'))) fail('E_CHANGED', 'State destination appeared after planning.');
     for (const directory of plan.migration.directories) {
@@ -574,7 +772,18 @@ export function applyPlan(plan) {
       const file = safePath(target, change.path);
       const content = change.content;
       const signature = { path: change.path, hash: content === null ? null : hash(content) };
-      if (content === null) { rmSync(file, { force: true }); applied.push(signature); }
+      if (content === null) {
+        const migrated = plan.migration?.files.find(item => item.path === change.path);
+        if (migrated) {
+          const copy = plan.changes.find(candidate => candidate.path === migrated.target && candidate.action === 'create');
+          const copied = read(target, migrated.target);
+          if (!copy?.content || !copied?.equals(copy.content)
+            || migrated.path !== legacyStatePath && !copied.equals(before.get(change.path))) {
+            fail('E_CHANGED', `Migrated copy changed before removing: ${change.path}`);
+          }
+        }
+        rmSync(file, { force: true }); applied.push(signature);
+      }
       else atomicWrite(target, change.path, content, beforeModes.get(change.path) ?? change.mode, mode => {
         signature.mode = mode; applied.push(signature);
       }, () => assertOriginal(change.path));