@pathbit/agentdevkit 0.0.7 → 0.0.9

package/docs/product/prd.md

@@ -1,7 +1,7 @@
 ---
 description: Requisitos da distribuição portátil AgentDevKit.
 status: aprovado
-version: 0.0.6
+version: 0.0.9
 ---
 
 # PRD do AgentDevKit
@@ -40,6 +40,9 @@ extraído do projeto de origem como produto independente.
 | FR-018 | Publicar autoria PathBit, palavras-chave e licença MIT no npm. |
 | FR-019 | Exibir README legível no npm sem alterar o Markdown fonte. |
 | FR-020 | Levar a licença do kit ao hub sem alterar a licença do projeto. |
+| FR-021 | Inventariar documentos existentes antes de propor alterações. |
+| FR-022 | Complementar documentação sem substituir arquivos por templates. |
+| FR-023 | Provar o fluxo documental em projetos reais e em projeto vazio. |
 
 Execuções repetidas devem ser idempotentes; a CLI oferece simulação e JSON.
 As instruções permanecem concisas, com detalhes opcionais em referências.

package/docs/product/roadmap.md

@@ -18,6 +18,8 @@ status: vigente
 | Instalação pelo registro v0.0.5 | Pacote publicado | [Spec][registry]. |
 | Apresentação e licença v0.0.6 | Distribuição e atualização | [Spec][public]. |
 | Compatibilidade real v0.0.7 | Testes em clones existentes | [Spec][oss]. |
+| Preservação v0.0.8 | Auditoria e regressões | [Spec][robustness]. |
+| Coexistência v0.0.9 | Agentes, documentos e projetos reais | [Spec][coexistence]. |
 
 A primeira entrega segue a [spec v0.0.1](../specs/v0.0.1/SPEC.md), disponível
 na [release v0.0.1][release]. Os detalhes de mudanças estão no
@@ -38,3 +40,5 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [registry]: ../specs/v0.0.5/SPEC.md
 [public]: ../specs/v0.0.6/SPEC.md
 [oss]: ../specs/v0.0.7/SPEC.md
+[robustness]: ../specs/v0.0.8/SPEC.md
+[coexistence]: ../specs/v0.0.9/SPEC.md

package/docs/specs/README.md

@@ -12,6 +12,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.5](v0.0.5/SPEC.md): instalação pelo registro em todos os fluxos.
 - [v0.0.6](v0.0.6/SPEC.md): apresentação pública, licença e atualização segura.
 - [v0.0.7](v0.0.7/SPEC.md): projetos reais e proteção local de artefatos.
+- [v0.0.8](v0.0.8/SPEC.md): preservação, transações e validação aprofundada.
+- [v0.0.9](v0.0.9/SPEC.md): coexistência e evolução documental sem perdas.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

package/docs/specs/v0.0.8/README.md

@@ -0,0 +1,10 @@
+---
+description: Validação aprofundada e preservação de dados do AgentDevKit.
+---
+
+# Versão 0.0.8
+
+A [spec](SPEC.md) reúne correções da auditoria do instalador, sincronizador,
+gerenciador de ferramentas, CLI e regras de ignore.
+
+[Specs](../README.md)

package/docs/specs/v0.0.8/SPEC.md

@@ -0,0 +1,62 @@
+---
+description: Correções verificadas de preservação, transações e interface CLI.
+status: aprovado
+version: 0.0.8
+---
+
+# Preservação e validação aprofundada
+
+## Objetivo e autorização
+
+Atender ao pedido de revisão profunda, corrigindo falhas comprovadas e
+publicando uma nova versão estável após validação. Esta etapa continua o
+[PRD](../../product/prd.md), o [design](../../product/design.md) e os
+[testes em projetos reais](../v0.0.7/SPEC.md).
+
+## Contrato
+
+- Não apagar ou sobrescrever arquivos humanos pela aparência de seu Markdown.
+  Exigir propriedade comprovada para limpeza automática de apontamentos.
+- Recusar conflitos conhecidos antes de escrever. Em falhas posteriores,
+  restaurar as alterações próprias sem substituir edições humanas concorrentes.
+- Preservar permissões em atualização, backup e rollback, inclusive em
+  arquivos somente para leitura quando a operação for permitida pelo sistema.
+- Recusar componentes simbólicos nos caminhos locais de ferramentas, inclusive
+  após operações externas, antes de escrever ou confirmar uma instalação.
+- Preservar integralmente argumentos após `tools ... --`; ajuda e versão
+  não exigem diretório de projeto válido.
+- Conferir artefatos existentes e exceções literais além dos nomes de amostra,
+  sem ler ignores de projetos irmãos ou desindexar arquivos humanos.
+- Manter a recusa de links simbólicos incompatíveis do Zod; não converter
+  esse bloqueio documentado em uma instalação bem-sucedida.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Markdown humano é preservado; limpeza usa propriedade comprovada. |
+| AC-002 | Falhas não deixam gravações próprias parciais nem mudam permissões. |
+| AC-003 | Gerenciador não escreve fora da instalação por links simbólicos. |
+| AC-004 | CLI repassa argumentos; ajuda funciona sem projeto. |
+| AC-005 | Ignore protege artefatos sem invadir projetos irmãos. |
+| AC-006 | Regressões, pacote público e atualização do router são verificados. |
+
+## Verificação
+
+Para AC-001 a AC-005, conservar reproduções anteriores e testes de regressão
+que falham antes da correção, com assertivas de conteúdo, modo, estado e Git.
+Executar os testes relevantes em Node 24/26 e revisar os diffs de forma
+independente. Limitações de plataforma devem ficar explícitas.
+
+Para AC-006, executar pipeline completo, cenários de maturidade e matriz OSS
+do pacote gerado. Confirmar no CI Linux, macOS e Windows; publicar o mesmo TGZ,
+comparar checksum e repetir o consumo público. Atualizar o router com preview,
+backup, diagnóstico e comparação da baseline, preservando o índice existente.
+
+Testes e fixtures são versionados. Clones e provas ficam em `tmp/` e o registro
+de revisão em `.agent-tests/`. Não prometer ausência universal de bugs.
+
+## Documentação afetada
+
+Atualizar referência da CLI, instalação, ferramentas, changelog, README,
+roadmap e índices. Não criar documentos de produto nos projetos consumidores.

package/docs/specs/v0.0.9/README.md

@@ -0,0 +1,9 @@
+---
+description: Preservação de agentes e evolução da documentação existente.
+---
+
+# Versão 0.0.9
+
+[Spec](SPEC.md): preservar agentes e complementar documentos existentes.
+
+[Specs](../README.md) · [Changelog](../../../CHANGELOG.md)

package/docs/specs/v0.0.9/SPEC.md

@@ -0,0 +1,68 @@
+---
+description: Coexistência com agentes e evolução da documentação existente.
+status: aprovado
+version: 0.0.9
+---
+
+# Preservar agentes e documentação existentes
+
+## Objetivo
+
+Instalar e atualizar o AgentDevKit no Zod e em projetos com agentes próprios,
+preservando configurações, arquivos, permissões, links e estado do Git.
+Orientar também a evolução documental a partir do inventário e da leitura
+dos materiais existentes, sem reiniciar o projeto. O pedido atual substitui
+o bloqueio conservador documentado na
+[versão anterior](../v0.0.8/SPEC.md).
+
+## Contrato
+
+- Tratar links simbólicos humanos nas entradas e nos clientes como caminhos
+  preservados: não abrir, atravessar, converter, sobrescrever ou adotar.
+- Preservar agentes e skills humanos, inclusive nomes iguais aos do kit e
+  durante execução com `--force`. Informar os caminhos preservados.
+- Gerar os apontamentos disponíveis sem atribuir ao kit arquivos preservados.
+  No Zod, manter `.codex/skills` e usar também `.agents/skills` para o Codex.
+- Manter a validação estrita em fontes, estado, ferramentas, Git e caminhos
+  antes pertencentes ao kit. Um link não pode esconder alteração gerenciada.
+- Manter os mesmos contratos na CLI e no sincronizador instalado.
+- Antes de editar documentos, inventariar e ler os existentes. Reaproveitar
+  caminhos, seções e decisões; templates orientam somente lacunas.
+- Organizar por índices e links, sem apagar, mover ou substituir documentos.
+  Em projetos novos, não inventar produto ou aprovação sem respostas.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Links humanos internos, externos e quebrados permanecem intactos. |
+| AC-002 | Skills, agentes e configurações preexistentes são preservados. |
+| AC-003 | Caminhos gerenciados recusam links sem escrita externa. |
+| AC-004 | Init, update, doctor e sync são coerentes e idempotentes. |
+| AC-005 | Zod, Express e Chi passam na matriz do pacote, preservando Git. |
+| AC-006 | Regressões, documentação, CI e pacote público são verificados. |
+| AC-007 | Inventário detecta documentação real sem alterar arquivos. |
+| AC-008 | Skills exigem leitura e plano aditivo antes dos templates. |
+| AC-009 | Exercícios documentais preservam conteúdo e arquivos fora do plano. |
+| AC-010 | Projeto vazio recebe o kit sem documentos de produto inventados. |
+
+## Validação
+
+Executar testes de regressão para links e colisões, inclusive `--force`,
+substituição de caminhos após o plano e mudança de seleção dos clientes.
+Rodar pipeline completo, maturidade e matriz OSS com o TGZ candidato;
+repetir a matriz com o pacote publicado. Comparar bytes, tipos, modos,
+destinos de links, staging e configuração Git nos clones.
+Execute também o inventário instalado e o fluxo de documentação em clones
+reais: plano por arquivo, complemento baseado em fatos, índice novo e revisão.
+Separe essa prova da simples instalação e de fixtures do harness; não atribua
+ao pacote geração automática de conteúdo ou aprovações de produto.
+
+Clones e evidências ficam ignorados em `tmp/` e `.agent-tests/`.
+O escopo é o kit e seu fluxo documental; não afirmar execução das aplicações
+clonadas.
+
+## Documentação afetada
+
+Atualizar instalação, CLI, recuperação, recursos, sincronização, testes,
+changelog e índices. Preservar as specs antigas como histórico.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",
@@ -51,7 +51,8 @@
     "ci:full": "node scripts/release/pipeline.mjs full",
     "ci:portable": "node scripts/release/pipeline.mjs portable",
     "ci:smoke": "node scripts/release/pipeline.mjs smoke",
-    "test:oss": "node tests/oss-compatibility.mjs"
+    "test:oss": "node tests/oss-compatibility.mjs",
+    "test:docs": "node tests/documentation-compatibility.mjs"
   },
   "author": {
     "name": "PathBit",

package/src/cli.mjs

@@ -18,7 +18,10 @@ export function parseArgs(argv) {
   const options = { command: null, positionals: [], toolArgs: [], target: null, language: null, clients: undefined, yes: false, json: false, dryRun: false, force: false, check: false };
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
-    if (['--target', '--lang', '--agents', '--clients'].includes(arg)) {
+    if (arg === '--' && options.command === 'tools') {
+      options.toolArgs.push(...argv.slice(index));
+      break;
+    } else if (['--target', '--lang', '--agents', '--clients'].includes(arg)) {
       const value = argv[++index]; if (!value || value.startsWith('-')) usage(`Missing value: ${arg}`);
       if (arg === '--target') options.target = value;
       else if (arg === '--lang') { options.language = normalizeLanguage(value); if (!options.language) usage('Use --lang pt, en or es.'); }
@@ -59,6 +62,7 @@ function print(result, options, output) {
   if (result.clients) output.write(`${text(result.language, 'clientsCurrent')}: ${result.clients.join(', ')}\n`);
   if (result.availableClients) output.write(`${text(result.language, 'clientsAvailable')}: ${result.availableClients.map(client => client.id).join(', ')}\n`);
   if (result.toolOutput) output.write(`${result.toolOutput.trimEnd()}\n`);
+  if (result.preserved?.length) output.write(`${text(result.language, 'preserved')}: ${result.preserved.length}. ${text(result.language, 'preservedDetails')}\n`);
   if (result.plan?.length) {
     const names = { pt: { create: 'criar', update: 'atualizar', remove: 'remover' }, en: { create: 'create', update: 'update', remove: 'remove' }, es: { create: 'crear', update: 'actualizar', remove: 'eliminar' } };
     const labels = {
@@ -86,11 +90,14 @@ function print(result, options, output) {
 
 export async function main(argv = process.argv.slice(2), context = {}) {
   const output = context.stdout || process.stdout, input = context.stdin || process.stdin, errorOutput = context.stderr || process.stderr;
-  let options = { json: argv.includes('--json') }, language = normalizeLanguage(argv[argv.indexOf('--lang') + 1]) || 'pt', target = resolve(context.cwd || process.cwd()), clients = ['all'];
+  const separator = argv.indexOf('--'), globalArgs = separator < 0 ? argv : argv.slice(0, separator);
+  let options = { json: globalArgs.includes('--json') }, language = normalizeLanguage(globalArgs[globalArgs.indexOf('--lang') + 1]) || 'pt', target = resolve(context.cwd || process.cwd()), clients = ['all'];
   try {
     options = parseArgs(argv);
-    target = resolveTarget(options.target || (options.command === 'init' ? options.positionals[0] : '.'), context.cwd || process.cwd());
-    const previous = ['help', 'version'].includes(options.command) ? null : loadState(target);
+    const informational = ['help', 'version'].includes(options.command);
+    target = informational ? resolve(context.cwd || process.cwd(), options.target || '.')
+      : resolveTarget(options.target || (options.command === 'init' ? options.positionals[0] : '.'), context.cwd || process.cwd());
+    const previous = informational ? null : loadState(target);
     language = options.language || previous?.language || 'pt';
     clients = options.clients ?? previous?.clients ?? ['all'];
     if (options.command === 'init' && !previous && !options.yes && !options.json && !options.dryRun && input.isTTY && output.isTTY && (!options.language || options.clients === undefined)) {
@@ -117,6 +124,7 @@ export async function main(argv = process.argv.slice(2), context = {}) {
       const found = inspect(target);
       if (found.installed && !found.issues.length) {
         const plan = planInstallation({ target, language, mode: 'sync' });
+        result.preserved = plan.preserved;
         found.issues.push(...plan.changes.map(change => ({ code: 'outdated', path: change.path })));
         found.issues.push(...plan.localIgnoreCheck.missing.map(path => ({ code: 'unignored', path })));
         if (plan.localIgnore.edits.length || plan.untrack?.paths.length) found.issues.push({ code: 'local-ignore', path: '.gitignore / Git info/exclude' });
@@ -138,6 +146,7 @@ export async function main(argv = process.argv.slice(2), context = {}) {
         result.next = getNextSteps({ command: options.command, language, target, installed: Boolean(previous) });
       }
       const plan = planInstallation({ target, language, mode: options.command, force: options.force, clients: options.clients });
+      result.preserved = plan.preserved;
       result.plan = plan.changes.map(({ path, action }) => ({ path, action, conflict: plan.conflicts.includes(path) }));
       result.untrackedPaths = [...(plan.untrack?.paths || [])];
       result.localIgnore = { status: plan.localIgnore.status, edits: plan.localIgnore.edits.map(({ path, before }) => ({ path, action: before === null ? 'create' : 'update' })), missing: plan.localIgnoreCheck.missing };

package/src/i18n.mjs

@@ -7,6 +7,7 @@ export function normalizeLanguage(value) {
 
 const messages = {
   pt: {
+    preserved: 'Caminhos existentes preservados', preservedDetails: 'Use --json para consultar os caminhos e motivos.',
     help: 'AgentDevKit: init [diretório], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <ação>.\nOpções: --target <diretório>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAliases: --clients e clients.',
     clientsCurrent: 'Agentes selecionados', clientsAvailable: 'Agentes disponíveis', clientsSelect: 'Agentes (IDs separados por vírgula ou all) [all]: ', agents: 'Seleção de agentes atualizada.',
     next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano; --force salva backup antes de substituir.',
@@ -15,6 +16,7 @@ const messages = {
     agentLanguage: 'Responda em português, salvo quando o usuário solicitar outro idioma.', inspect: 'Verifique a instalação', workflow: 'Consulte a próxima etapa', install: 'Inicialize este projeto', repair: 'Confira a sincronização', review: 'Revise os arquivos em conflito', tools: 'Resultado da ferramenta',
   },
   en: {
+    preserved: 'Existing paths preserved', preservedDetails: 'Use --json to inspect paths and reasons.',
     help: 'AgentDevKit: init [directory], update, doctor, sync [--check], lang [pt|en|es], agents [list], next, tools <action>.\nOptions: --target <directory>, --lang <language>, --agents <list>, --yes, --dry-run, --force, --json.\nAliases: --clients and clients.',
     clientsCurrent: 'Selected agents', clientsAvailable: 'Available agents', clientsSelect: 'Agents (comma-separated IDs or all) [all]: ', agents: 'Agent selection updated.',
     next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review it; --force backs them up before replacement.',
@@ -23,6 +25,7 @@ const messages = {
     agentLanguage: 'Respond in English unless the user requests another language.', inspect: 'Check the installation', workflow: 'Review the next stage', install: 'Initialize this project', repair: 'Check synchronization', review: 'Review conflicting files', tools: 'Tool result',
   },
   es: {
+    preserved: 'Rutas existentes preservadas', preservedDetails: 'Use --json para consultar las rutas y los motivos.',
     help: 'AgentDevKit: init [directorio], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <acción>.\nOpciones: --target <directorio>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAlias: --clients y clients.',
     clientsCurrent: 'Agentes seleccionados', clientsAvailable: 'Agentes disponibles', clientsSelect: 'Agentes (IDs separados por coma o all) [all]: ', agents: 'Selección de agentes actualizada.',
     next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise el plan; --force guarda una copia antes de reemplazarlos.',

package/src/install.mjs

@@ -1,9 +1,10 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, lstatSync, readFileSync, writeFileSync, readdirSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync } from 'node:fs';
+import { chmodSync, existsSync, lstatSync, readFileSync, 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 { nativePathBoundary } from '../.pbai4devs/scripts/lib/native-paths.mjs';
 import { writeAdapterManifest, adapterRoots, normalizeClients, resolveAdapters } from './adapters/index.mjs';
 import { packageRoot, packageInfo, statePath, entryNames, begin, end } from './config.mjs';
 import { normalizeLanguage, text } from './i18n.mjs';
@@ -77,8 +78,24 @@ function walk(root, path = '', filter = () => true) {
   return files;
 }
 
-function write(root, path, content) {
-  const target = safePath(root, path); mkdirSync(dirname(target), { recursive: true }); writeFileSync(target, content);
+function write(root, path, content, mode) {
+  const target = safePath(root, path); mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, content, mode === undefined ? undefined : { mode });
+  if (mode !== undefined) chmodSync(target, mode);
+}
+
+function atomicWrite(root, path, content, mode, onPublished) {
+  const file = safePath(root, path);
+  mkdirSync(dirname(file), { recursive: true });
+  const temporary = `${file}.agentdevkit-${randomUUID()}`;
+  try {
+    writeFileSync(temporary, content, { flag: 'wx', ...(mode === undefined ? {} : { mode }) });
+    if (mode !== undefined) chmodSync(temporary, mode);
+    const writtenMode = stat(temporary).mode & 0o777;
+    renameSync(temporary, file);
+    onPublished?.(writtenMode);
+    return writtenMode;
+  } finally { rmSync(temporary, { force: true }); }
 }
 
 function read(root, path) {
@@ -157,6 +174,24 @@ function copyResources(source, destination) {
   return files;
 }
 
+function readDerivedState(target) {
+  let entries = {}, outputs = {};
+  const derived = read(target, '.pbai4devs/estado/derived.json');
+  if (derived) {
+    try {
+      const value = JSON.parse(derived);
+      if (value.schemaVersion !== 1 || !value.entries || typeof value.entries !== 'object' || Array.isArray(value.entries)
+        || value.outputs !== undefined && (!value.outputs || typeof value.outputs !== 'object' || Array.isArray(value.outputs))) fail('E_STATE', 'Invalid derived entrypoint state.');
+      entries = value.entries; outputs = value.outputs ?? {};
+      for (const [path, digest] of Object.entries(entries)) if (!entryNames.includes(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived entrypoint state.');
+      for (const [path, digest] of Object.entries(outputs)) if (!allowedManaged(path) || !/^\.[^/]+\/(?:skills|agents|rules)\.json$/.test(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived output state.');
+    }
+    catch { fail('E_STATE', 'Invalid derived entrypoint state.'); }
+    for (const path of [...Object.keys(entries), ...Object.keys(outputs)]) safePath(target, path);
+  }
+  return { entries, outputs };
+}
+
 export function planInstallation({ target, language = 'pt', mode = 'init', force = false, clients }) {
   const previous = loadState(target);
   if (mode !== 'init' && !previous) fail('E_MISSING', text(language, 'missing'));
@@ -164,16 +199,37 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
   const active = resolveAdapters(selected);
   const changingClients = clients !== undefined || mode === 'agents';
   const protectedEntries = new Set(), entryConflicts = [], ownedEntrypoints = new Set();
+  const { entries: derivedEntries, outputs: derivedOutputs } = readDerivedState(target);
+  const ownedPaths = [...Object.keys(previous?.files || {}), ...Object.keys(previous?.blocks || {}), ...Object.keys(derivedEntries), ...Object.keys(derivedOutputs)];
+  const preserved = new Map();
+  const recordPreserved = (path, reason) => { preserved.set(path, { path, reason }); return true; };
+  const native = path => entryNames.includes(path) || path === 'README.md' || adapterRoots.some(root => path === root || path.startsWith(`${root}/`));
+  const boundary = path => {
+    if (!native(path)) return false;
+    const found = nativePathBoundary(target, path, ownedPaths, { preserveRootAliases: path === 'README.md' || entryNames.includes(path) });
+    return found ? recordPreserved(found.path, found.reason) : false;
+  };
+  const owned = path => ownedPaths.includes(path);
+  const generatedReference = content => Boolean(content && isReference(content.toString('utf8'))
+    && (content.toString('utf8').split(/\r?\n/).includes('<!-- gerado: sincronizar-agentes -->') || content.toString('utf8').startsWith('# gerado: sincronizar-agentes\n')));
+  const preserveNative = path => {
+    if (!native(path)) return false;
+    if (boundary(path)) return true;
+    const item = stat(safePath(target, path));
+    if (!item || owned(path)) return false;
+    if (!item.isFile() && ownedPaths.some(value => value.startsWith(`${path}/`))) fail('E_PATH', `Managed subtree occupies a file destination: ${path}`);
+    if (item.isFile()) {
+      const current = read(target, path);
+      if (generatedReference(current)) return false;
+      if (path.endsWith('/.gitignore') && current.toString('utf8').split(/\r?\n/).some(line => ['# BEGIN AGENT IGNORE', '# END AGENT IGNORE'].includes(line))) return false;
+    }
+    return recordPreserved(path, item.isFile() ? 'existing-file' : 'existing-directory');
+  };
   for (const name of entryNames) {
+    if (preserveNative(name)) continue;
     const current = read(target, name);
     if (current && previous?.files[name] && previous.files[name] !== hash(current)) { protectedEntries.add(name); entryConflicts.push(name); }
   }
-  let derivedEntries = {};
-  const derived = read(target, '.pbai4devs/estado/derived.json');
-  if (derived) {
-    try { const value = JSON.parse(derived); if (value.schemaVersion === 1 && value.entries && typeof value.entries === 'object') derivedEntries = value.entries; }
-    catch { fail('E_STATE', 'Invalid derived entrypoint state.'); }
-  }
   const stage = realpathSync(mkdtempSync(join(tmpdir(), 'agentdevkit-')));
   try {
     const existing = copyResources(join(target, '.pbai4devs'), join(stage, '.pbai4devs'));
@@ -190,6 +246,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (path.startsWith('.pbai4devs/') && !supplied.has(path.slice(11)) && !internal.has(path.slice(11))) rmSync(safePath(stage, path), { force: true });
     }
     for (const root of active.roots) {
+      if (preserveNative(`${root}/.gitignore`)) continue;
       const content = read(target, `${root}/.gitignore`);
       if (content) write(stage, `${root}/.gitignore`, content);
     }
@@ -198,7 +255,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     writeAdapterManifest(stage, { clients: selected });
     const synchronized = synchronize({ root: stage, force: true, localIgnores: false, generateEntrypoints: false, output() {} });
     for (const name of active.entrypoints) {
-      if (protectedEntries.has(name)) continue;
+      if (protectedEntries.has(name) || preserveNative(name)) continue;
       const current = read(target, name), template = readFileSync(join(packageRoot, '.pbai4devs/templates/entrypoints', name), 'utf8');
       const legacy = entryContent(null, template, language, name);
       const content = legacy.replace(`${begin}\n`, '').replace(`\n${end}`, '');
@@ -206,11 +263,18 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       const knownLegacy = current && previous?.blocks[name] && current.toString('utf8') === entryContent(null, template, previous.language, name);
       if (!current || knownFile || knownLegacy) { write(stage, name, content); ownedEntrypoints.add(name); }
     }
-    if (!read(target, 'README.md')) write(stage, 'README.md', `---\ndescription: ${JSON.stringify(text(language, 'readme'))}\nlanguage: ${language}\n---\n\n# ${text(language, 'project')}\n\n${text(language, 'readme')}\n`);
+    if (!preserveNative('README.md') && !read(target, 'README.md')) write(stage, 'README.md', `---\ndescription: ${JSON.stringify(text(language, 'readme'))}\nlanguage: ${language}\n---\n\n# ${text(language, 'project')}\n\n${text(language, 'readme')}\n`);
     if (!existsSync(join(stage, '.pbai4devs/estado/README.md'))) write(stage, '.pbai4devs/estado/README.md', `---\ndescription: AgentDevKit state.\n---\n\n# AgentDevKit\n\n${text(language, 'state')}\n`);
     const unknown = new Set(existing.filter(path => !supplied.has(path) && !previous?.files[`.pbai4devs/${path}`] && !internal.has(path)));
     const paths = walk(stage, '', path => !path.split('/').includes('.agent-tests')).filter(path => !path.startsWith('.pbai4devs/') || !unknown.has(path.slice(11)));
-    const desired = new Map(paths.map(path => [path, readFileSync(join(stage, path))]));
+    const desired = new Map(paths.filter(path => !preserveNative(path)).map(path => [path, readFileSync(join(stage, path))]));
+    // Native discovery manifests must not advertise resources omitted at a human boundary.
+    const overlapsPreserved = path => [...preserved.keys()].some(kept => path === kept || path.startsWith(`${kept}/`) || kept.startsWith(`${path}/`));
+    for (const [path, content] of desired) if (/^\.agents\/(skills|rules|agents)\.json$/.test(path)) {
+      const discovery = JSON.parse(content);
+      discovery.entries = discovery.entries.filter(entry => !overlapsPreserved(entry.path));
+      desired.set(path, Buffer.from(`${JSON.stringify(discovery, null, 2)}\n`));
+    }
     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) {
@@ -224,7 +288,8 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     for (const [path, content] of desired) {
       const current = read(target, path);
       if (current?.equals(content)) continue;
-      const managed = previous?.blocks[path] ? blockDigest(path, current || Buffer.alloc(0)) === previous.blocks[path] : previous?.files[path] ? hash(current || '') === previous.files[path] : false;
+      const managed = previous?.blocks[path] ? blockDigest(path, current || Buffer.alloc(0)) === previous.blocks[path]
+        : [previous?.files[path], derivedOutputs[path], derivedEntries[path]].some(digest => digest && hash(current || '') === digest);
       const appendBlock = entryNames.includes(path) || path === '.gitignore' || path.endsWith('/.gitignore');
       const conflict = current && path !== statePath && !managed && !appendBlock;
       const changedBlock = current && previous?.blocks[path] && !managed;
@@ -254,11 +319,29 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       }
       changes.push({ path, action: content.trim() ? 'update' : 'remove', content: content.trim() ? Buffer.from(content) : null, beforeHash: hash(current) });
     }
-    for (const root of changingClients ? [] : active.roots) for (const path of walk(join(target, root), '', path => !path.split('/').some(part => ignored.has(part)))) {
+    function nativeFiles(root) {
+      if (boundary(root)) return [];
+      const directory = stat(safePath(target, root));
+      if (!directory?.isDirectory()) return [];
+      const files = [];
+      const visit = folder => {
+        for (const name of readdirSync(safePath(target, folder)).sort()) {
+          const path = `${folder}/${name}`;
+          if (boundary(path)) continue;
+          const info = stat(safePath(target, path));
+          if (path.split('/').some(part => ignored.has(part))) continue;
+          if (info?.isDirectory()) visit(path);
+          else if (info?.isFile()) files.push(path);
+        }
+      };
+      visit(root); return files;
+    }
+    for (const root of changingClients ? [] : active.roots) for (const full of nativeFiles(root)) {
+      const path = full.slice(root.length + 1);
       if (!['skills', 'agents', 'commands', 'rules', 'instructions', 'prompts'].includes(path.split('/')[0])) continue;
-      const full = `${root}/${path}`; if (desired.has(full) || changes.some(change => change.path === full)) continue;
+      if (desired.has(full) || changes.some(change => change.path === full)) continue;
       const current = read(target, full), source = current.toString('utf8');
-      if (!(source.includes('<!-- gerado: sincronizar-agentes -->') || source.startsWith('# gerado: sincronizar-agentes\n'))) continue;
+      if (!(source.includes('<!-- gerado: sincronizar-agentes -->') || source.startsWith('# gerado: sincronizar-agentes\n'))) { recordPreserved(full, 'existing-file'); continue; }
       if (!isReference(source)) conflicts.push(full);
       changes.push({ path: full, action: 'remove', content: null, beforeHash: hash(current) });
     }
@@ -269,7 +352,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       changes.push({ path: legacy, action: 'remove', content: null, beforeHash: hash(legacyContent) });
     }
     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])];
+    const ownedOutputs = [...new Set([...synchronized.ownedOutputs, ...ownedEntrypoints, statePath])].filter(path => !overlapsPreserved(path));
     const hashes = {};
     for (const [path, digest] of Object.entries(previous?.files || {})) if ((ownedOutputs.includes(path) || !path.startsWith('.pbai4devs/')) && !protectedEntries.has(path)) hashes[path] = digest;
     for (const path of ownedEntrypoints) { const current = read(target, path); if (current && (previous?.blocks[path] || derivedEntries[path] === hash(current))) hashes[path] = hash(current); }
@@ -282,7 +365,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const localIgnore = planLocalIgnore(target, { outputs: ownedOutputs, templateRoot: stage });
     const localIgnoreCheck = checkLocalIgnore(localIgnore, { replacedBlocks: replacedIgnoreBlocks(target, changes, previous) });
     conflicts.push(...(untrack?.conflicts || []), ...localIgnoreCheck.missing);
-    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck };
+    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
   } finally { rmSync(stage, { recursive: true, force: true }); }
 }
 
@@ -294,42 +377,63 @@ export function applyPlan(plan) {
   safePath(target, backup);
   for (const change of plan.changes) safePath(target, change.path);
   const before = new Map(plan.changes.map(change => [change.path, read(target, change.path)]));
+  const beforeModes = new Map(plan.changes.map(change => {
+    const info = stat(safePath(target, change.path));
+    return [change.path, info ? info.mode & 0o777 : undefined];
+  }));
   for (const change of plan.changes) if ((before.get(change.path) ? hash(before.get(change.path)) : null) !== change.beforeHash) fail('E_CHANGED', `File changed after planning: ${change.path}`);
-  for (const [path, content] of before) if (content) write(target, `${backup}/${path}`, content);
-  const applied = [];
+  for (const [path, content] of before) if (content) write(target, `${backup}/${path}`, content, beforeModes.get(path));
+  const applied = [], removedDirectories = [];
   let untracked = false;
   try {
     if (plan.untrack?.paths.length) { applyUntrack(plan.untrack); untracked = true; }
     for (const change of plan.changes) {
       const file = safePath(target, change.path);
-      if (change.content === null) rmSync(file, { force: true });
-      else {
-        mkdirSync(dirname(file), { recursive: true });
-        const temporary = `${file}.agentdevkit-${randomUUID()}`;
-        try { writeFileSync(temporary, change.content, { flag: 'wx' }); renameSync(temporary, file); }
-        finally { rmSync(temporary, { force: true }); }
-      }
-      applied.push(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); }
+      else atomicWrite(target, change.path, content, beforeModes.get(change.path), mode => {
+        signature.mode = mode; applied.push(signature);
+      });
     }
-    pruneRemovedDirectories(plan);
+    pruneRemovedDirectories(plan, directory => removedDirectories.push(directory));
     const changesFallback = plan.changes.some(change => change.path === '.gitignore');
     // Metadata is committed last; its writer rolls back partial writes itself.
     const ignored = applyLocalIgnore(changesFallback ? planLocalIgnore(target, { outputs: plan.ownedOutputs }) : plan.localIgnore);
     return { changed: Boolean(plan.changes.length || ignored.changed || untracked), backup: [...before.values()].some(Boolean) ? backup : null };
   } catch (error) {
-    const rollbackErrors = [];
-    for (const path of applied.reverse()) {
+    const rollbackErrors = [], preserved = [];
+    for (const removed of [...removedDirectories].sort((a, b) => a.path.length - b.path.length)) {
+      let directory, current;
+      try { directory = safePath(target, removed.path); current = stat(directory); }
+      catch { preserved.push(removed.path); continue; }
+      if (current) continue;
+      try { mkdirSync(directory, { mode: removed.mode }); chmodSync(directory, removed.mode); }
+      catch (failure) { rollbackErrors.push(failure); }
+    }
+    for (const appliedFile of applied.reverse()) {
+      const { path } = appliedFile;
+      let unchanged = false;
+      try {
+        const file = safePath(target, path), info = stat(file);
+        unchanged = appliedFile.hash === null ? !info : Boolean(info?.isFile()
+          && (info.mode & 0o777) === appliedFile.mode && hash(readFileSync(file)) === appliedFile.hash);
+      } catch { /* Não restaurar quando não é possível comprovar a própria gravação. */ }
+      if (!unchanged) { preserved.push(path); continue; }
       const content = before.get(path);
-      try { if (content) write(target, path, content); else rmSync(safePath(target, path), { force: true }); }
+      try { if (content) atomicWrite(target, path, content, beforeModes.get(path)); else rmSync(safePath(target, path), { force: true }); }
       catch (failure) { rollbackErrors.push(failure); }
     }
+    if (preserved.length) {
+      try { error.rollbackPreservedPaths = preserved; } catch { /* Preserve a exceção original. */ }
+    }
     if (untracked) try { restoreUntrack(plan.untrack); } catch (failure) { rollbackErrors.push(failure); }
     if (rollbackErrors.length) throw Object.assign(new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error }), { code: error.code || 'E_OPERATION' });
     throw error;
   }
 }
 
-function pruneRemovedDirectories(plan) {
+function pruneRemovedDirectories(plan, onRemoved) {
   const { target } = plan;
   const legacy = '.pbai4devs/adapters/README.md';
   const removed = plan.changes.filter(change => change.action === 'remove' && (allowedManaged(change.path) || change.path === legacy));
@@ -342,8 +446,9 @@ function pruneRemovedDirectories(plan) {
     const boundary = parent.startsWith('.pbai4devs/') ? '.pbai4devs' : adapterRoots.find(root => parent.startsWith(`${root}/`));
     while (boundary && parent.startsWith(`${boundary}/`)) {
       const directory = safePath(target, parent);
-      if (!stat(directory)?.isDirectory() || readdirSync(directory).length) break;
-      try { rmdirSync(directory); }
+      const info = stat(directory);
+      if (!info?.isDirectory() || readdirSync(directory).length) break;
+      try { rmdirSync(directory); onRemoved?.({ path: parent, mode: info.mode & 0o777 }); }
       catch (error) { if (['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) break; throw error; }
       parent = portable(dirname(parent));
     }
@@ -351,8 +456,9 @@ function pruneRemovedDirectories(plan) {
   for (const root of plan.retiredRoots || []) {
     if (!adapterRoots.includes(root)) continue;
     const directory = safePath(target, root);
-    if (!stat(directory)?.isDirectory()) continue;
-    try { if (readdirSync(directory).length === 0) rmdirSync(directory); }
+    const info = stat(directory);
+    if (!info?.isDirectory()) continue;
+    try { if (readdirSync(directory).length === 0) { rmdirSync(directory); onRemoved?.({ path: root, mode: info.mode & 0o777 }); } }
     catch (error) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(error.code)) throw error; }
   }
 }
@@ -360,10 +466,11 @@ function pruneRemovedDirectories(plan) {
 export function inspect(target) {
   const state = loadState(target);
   if (!state) return { installed: false, issues: [{ code: 'missing', path: statePath }] };
+  const derived = readDerivedState(target);
   const issues = [];
   for (const [path, digest] of Object.entries(state.files)) {
     const content = read(target, path);
-    if (!content || hash(content) !== digest) issues.push({ code: content ? 'modified' : 'missing', path });
+    if (!content || hash(content) !== digest && hash(content) !== derived.outputs[path]) issues.push({ code: content ? 'modified' : 'missing', path });
   }
   for (const [path, digest] of Object.entries(state.blocks)) {
     const content = read(target, path);