@pathbit/agentdevkit 0.0.8 → 0.0.9

package/.pbai4devs/COMPATIBILIDADE.md

@@ -87,8 +87,10 @@ remoção em fevereiro de 2027. No Copilot, use skills para rotinas invocáveis.
 
 O instalador gera a seleção e a política em `espelhos.conf`; `sincronizar`
 reconstrói os apontamentos somente com Node e os arquivos do hub instalado.
-`--check` não altera arquivos. `--force` faz backup ignorado antes de substituir
-conteúdo próprio que conflite com caminhos gerenciados.
+`--check` não altera arquivos. `--force` faz backup ignorado ao reparar
+conflitos gerenciados. Recursos e links humanos dos clientes são preservados;
+uma rota preservada não recebe apontamentos novos. No Zod, `.codex/skills`
+continua apontando para suas skills e o Codex recebe o kit em `.agents/skills`.
 
 As fontes confirmam formatos, não execução de cada cliente. Valide descoberta,
 invocação e resultado no cliente escolhido antes de considerar uma integração

package/.pbai4devs/INSTRUCTIONS.md

@@ -6,6 +6,10 @@ description: Ordem de trabalho e manutenção dos agentes.
 
 Peça a skill pelo nome ou solicite a leitura de seu `SKILL.md`.
 
+Antes de trabalhar na documentação, use `atualizar-documentacao` para inventariar
+e ler os arquivos existentes. Preserve seus caminhos e conteúdo; complemente
+lacunas e organize por índices, sem substituir documentos pelos modelos.
+
 Antes de instalar ou preparar ferramentas, pergunte quais clientes o usuário
 usa, se não houver escolha no pedido ou no estado do kit. A CLI aceita
 `--agents codex,claude`; `agents` consulta ou altera a seleção depois.

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

@@ -8,9 +8,10 @@ Entrada: sem argumentos usa `--force` para reparar; `--check` só confere.
 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 pode sobrescrever
-apontamentos e remover extras dos destinos gerenciados; preserva os arquivos
-nativos fora desse escopo e mantém backup local do conteúdo próprio removido.
+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.
 Após reparar, execute também `--check`.
 
 Respeite os clientes registrados no manifesto. Para mudar a seleção salva,

package/.pbai4devs/rules/documentacao/RULE.md

@@ -5,6 +5,10 @@ description: Documentação e revisão fazem parte de toda entrega implementada.
 
 # Documentação da entrega
 
+Antes de criar, organizar ou alterar documentação, use `atualizar-documentacao`:
+inventarie e leia o que já existe. Reutilize caminhos e formatos;
+complemente lacunas sem apagar, mover ou substituir arquivos por templates.
+
 Após implementar, siga `atualizar-documentacao` e o comando `revisar-entrega`
 antes de commit ou merge. Use os modelos da fase atual; registre decisões sem
 impacto com justificativa e resolva os achados da revisão independente.

package/.pbai4devs/rules/qualidade/RULE.md

@@ -15,8 +15,10 @@ Use `verificar-trabalho` para provar as mudanças. Alterações web exigem testa
 o fluxo real no navegador; desktop exige abrir e testar a aplicação. Código
 revisado, build ou fixture isolada não substituem essa prova funcional.
 
-Comece arquivos Markdown com frontmatter YAML adequado ao tipo e título H1;
-preserve os metadados exigidos pela ferramenta.
+Comece novos arquivos Markdown com frontmatter YAML adequado ao tipo e título
+H1; preserve os metadados exigidos pela ferramenta. Em documentos humanos
+existentes, mantenha o formato e o conteúdo: não os reformate apenas para
+impor esse padrão.
 
 Ao criar ou atualizar `.gitignore`, mantenha o bloco do
 [modelo de gitignore](../../templates/gitignore/TEMPLATE.md)

package/.pbai4devs/scripts/README.md

@@ -59,9 +59,9 @@ recursos, com frontmatter YAML sem corpo. Caminhos são relativos à raiz.
 Somente os quatro arquivos principais são fontes; não registre documentos.
 Use `gitignore|pasta` para gerar apenas o `.gitignore`, como em `.vscode`.
 
-`sincronizar-agentes --force` reconstrói os destinos e limpa auxiliares,
-preservando configurações e workflows fora do escopo gerenciado. Conteúdo
-próprio substituído recebe backup em `.agent-tests/`; `--check` não altera nada.
+`sincronizar-agentes --force` repara os destinos gerenciados com backup em
+`.agent-tests/`. Recursos e configurações humanos permanecem intactos, inclusive
+quando ocupam o caminho de um apontamento. `--check` não altera arquivos.
 O sincronizador também gera o catálogo completo e os índices auxiliares a partir
 das fontes. Helpers e testes constam como suporte, sem fingir comandos próprios.
 Ele protege os derivados contra versionamento e preserva regras humanas.

package/.pbai4devs/scripts/inspecionar-projeto/README.md

@@ -0,0 +1,31 @@
+---
+description: Inventário somente leitura da estrutura e documentação do projeto.
+---
+
+# Inspecionar projeto
+
+```sh
+node .pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs
+```
+
+O JSON identifica tecnologia, comandos, estrutura e documentos existentes.
+`documentation.files` mantém caminhos e caixa, papel provável, tamanho e hash
+quando a leitura couber nos limites. Referências válidas do estado aparecem em
+`configured`; nomes sugerem papéis, mas não comprovam conteúdo ou aprovação.
+
+Links simbólicos são listados como opacos, sem ler seus destinos. Conteúdo dos
+documentos e valores de configuração não aparecem no relatório. `scan` e
+`warnings` informam limites e leitura incompleta; `scan.complete` resume essas
+condições. Uma pasta simbólica como `docs` também aparece, sem presumir que
+esteja vazia. Links não classificados recebem `role: unclassified`; enquanto
+existir uma fronteira não inspecionada, `scan.complete` será falso. Não use
+inventário incompleto como prova de ausência de documentos.
+
+`exclusions` descreve pastas de clientes, artefatos e caches fora do inventário.
+Documentos humanos em `.github`, exemplos, wiki e RFCs são incluídos; os
+apontamentos gerados em `.github/skills`, agentes e comandos ficam de fora.
+
+O script não cria nem altera arquivos. Leia os documentos relevantes antes de
+planejar complementos; preserve sua estrutura e use templates só para lacunas.
+`--check` confere a estrutura técnica. `--root` aceita somente as fixtures
+documentadas pelo próprio comando, sem ampliar o acesso a outros projetos.

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

@@ -2,6 +2,7 @@
 // Inventario somente leitura; nomes e caminhos, nunca valores de configuracao.
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { requireNode, isMain } from '../lib/runtime.mjs';
 
@@ -92,7 +93,146 @@ function maturity(root, report) {
   return { level, planning, configuration, released, signals: { application: report.mode === 'aplicacao-detectada', structure: report.contract.complete }, limits: ['Classificacao descritiva; status em arquivos nao substitui aprovacao, testes ou provas de funcionamento.'] };
 }
 
-export function inspectProject(root = repository, { check = false } = {}) {
+const documentRoles = new Set(['readme', 'contribuicao', 'changelog', 'seguranca', 'adrs', 'prd', 'ux_ui', 'design', 'roadmap', 'releases', 'specs', 'tarefas']);
+const documentLimits = { maxDepth: 12, maxEntries: 25000, maxFiles: 2000, maxFileBytes: 2 * 1024 * 1024, maxTotalBytes: 16 * 1024 * 1024 };
+const documentClients = [...defaultAgents, '.zcode', '.zai', '.kimi', '.kimi-code', '.minimax', '.mimocode', '.dsh'];
+const documentName = name => /\.(?:md|mdx|rst|adoc)$/i.test(name) || /^(?:readme|contributing|changelog|history|security|licen[cs]e|copying|notice|authors|code_of_conduct|architecture|design|roadmap)(?:\.txt)?$/i.test(name);
+const documentRole = file => {
+  const name = path.posix.basename(file).toLowerCase();
+  if (/^readme(?:\.|$)/.test(name)) return 'readme';
+  if (/^(?:agents|claude|gemini|copilot-instructions)\.md$/.test(name)) return 'instructions';
+  if (/^(?:licen[cs]e|copying|notice)(?:\.|$)/.test(name)) return 'license';
+  if (/^code_of_conduct(?:\.|$)/.test(name)) return 'conduct';
+  if (/^contribut/.test(name)) return 'contribution';
+  if (/^security(?:\.|$)/.test(name)) return 'security';
+  if (/^(?:changelog|history)(?:\.|$)/.test(name)) return 'changelog';
+  if (/(^|\/)(?:adr|adrs|decisions|rfcs)(\/|$)/i.test(file) || /^adr[-_.]/.test(name)) return 'decision';
+  if (/(^|\/)(?:prd|product|requisitos)(?:\.|\/|$)/i.test(file)) return 'product';
+  if (/(?:architecture|arquitetura|design)(?:\.|\/|$)/i.test(file)) return 'design';
+  if (/roadmap/i.test(name)) return 'roadmap';
+  if (/(^|\/)(?:spec|specs|specifications)(\/|$)/i.test(file)) return 'spec';
+  return 'document';
+};
+
+// Names, kinds and bounded hashes only. A guessed role is never an approval.
+export function inspectDocumentation(root, limits = {}) {
+  root = fs.realpathSync(path.resolve(root));
+  const bounds = { ...documentLimits, ...limits };
+  for (const [key, value] of Object.entries(bounds)) {
+    if (!(key in documentLimits) || !Number.isSafeInteger(value) || value < 0 || value > documentLimits[key]) throw new Error('Limite documental invalido.');
+  }
+  const ignored = new Set([...defaultExcluded, ...documentClients, ...agentRoots(root)].filter(name => !['examples', '.github'].includes(name)).map(name => name.toLowerCase()));
+  const excludedPaths = ['examples/generated', ...['skills', 'agents', 'commands', 'rules', 'instructions', 'prompts'].map(name => `.github/${name}`)];
+  const files = new Map();
+  const configured = [];
+  const warnings = [];
+  const scan = { ...bounds, entries: 0, bytesRead: 0, bytesHashed: 0, truncated: false };
+  const warn = (file, reason) => warnings.push({ file, reason });
+  const excludedDocument = file => file.split('/').some(name => ignored.has(name.toLowerCase()) || /^\.?playwright/i.test(name))
+    || excludedPaths.some(prefix => file.toLowerCase() === prefix || file.toLowerCase().startsWith(prefix + '/'));
+  const safeDocument = value => typeof value === 'string' && value.length > 0 && !path.isAbsolute(value) && !/[\\\x00-\x1f\x7f:]/.test(value)
+    && !value.split('/').some(part => !part || part === '.' || part === '..');
+  const locate = file => {
+    let current = root;
+    const parts = file.split('/');
+    for (const [index, part] of parts.entries()) {
+      current = path.join(current, part);
+      let item;
+      try { item = fs.lstatSync(current); }
+      catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return { kind: 'missing' }; throw error; }
+      if (item.isSymbolicLink()) return { kind: 'symbolic-link', boundary: parts.slice(0, index + 1).join('/'), item };
+      if (index < parts.length - 1 && !item.isDirectory()) return { kind: 'missing' };
+      if (index === parts.length - 1) return { kind: item.isFile() ? 'file' : item.isDirectory() ? 'directory' : 'unsupported', item };
+    }
+  };
+  function boundedHash(file, expected) {
+    if (expected.size > bounds.maxFileBytes || expected.size > bounds.maxTotalBytes - scan.bytesRead) {
+      scan.truncated = true; warn(file, 'hash-byte-limit'); return;
+    }
+    let descriptor;
+    try {
+      descriptor = fs.openSync(path.join(root, file), fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+      const before = fs.fstatSync(descriptor);
+      if (!before.isFile() || before.dev !== expected.dev || before.ino !== expected.ino || before.size !== expected.size
+        || before.mtimeMs !== expected.mtimeMs || before.ctimeMs !== expected.ctimeMs) { warn(file, 'changed-during-read'); return; }
+      const buffer = Buffer.alloc(Math.min(before.size + 1, bounds.maxTotalBytes - scan.bytesRead));
+      let length = 0;
+      while (length < buffer.length) {
+        const read = fs.readSync(descriptor, buffer, length, buffer.length - length, length);
+        if (!read) break;
+        length += read;
+        scan.bytesRead += read;
+      }
+      const after = fs.fstatSync(descriptor);
+      if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
+        warn(file, 'changed-during-read'); return;
+      }
+      scan.bytesHashed += length;
+      return createHash('sha256').update(buffer.subarray(0, length)).digest('hex');
+    } catch (error) { warn(file, error.code === 'ELOOP' ? 'symbolic-link-during-read' : 'unreadable-document'); }
+    finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
+  }
+  function add(file, found, role) {
+    if (files.has(file)) {
+      if (role) { const entry = files.get(file); entry.origin = 'configured'; entry.configuredAs = [...new Set([...(entry.configuredAs || []), role])].sort(); }
+      return;
+    }
+    if (files.size >= bounds.maxFiles) { scan.truncated = true; warn(file, 'file-limit'); return; }
+    const inferredRole = found.kind === 'symbolic-link' && !documentName(path.posix.basename(file)) ? 'unclassified' : documentRole(file);
+    const entry = { path: file, kind: found.kind, role: inferredRole, origin: role ? 'configured' : 'inferred', bytes: found.item.size };
+    if (role) entry.configuredAs = [role];
+    if (found.kind === 'symbolic-link') warn(file, 'symbolic-link-not-inspected');
+    if (found.kind === 'file') {
+      const digest = boundedHash(file, found.item);
+      if (digest) entry.sha256 = digest;
+    }
+    files.set(file, entry);
+  }
+  function walk(directory = '', depth = 0, role) {
+    if (directory) {
+      const found = locate(directory);
+      if (found.kind !== 'directory') { if (found.kind === 'symbolic-link') add(found.boundary, found, role); return; }
+    }
+    let children;
+    try { children = fs.readdirSync(path.join(root, directory), { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0); }
+    catch { warn(directory || '.', 'unreadable-directory'); return; }
+    // Discard a listing if the directory became a link while being inspected.
+    if (directory && locate(directory).kind !== 'directory') { warn(directory, 'changed-during-read'); return; }
+    for (const child of children) {
+      if (scan.entries >= bounds.maxEntries || files.size >= bounds.maxFiles) { scan.truncated = true; return; }
+      scan.entries++;
+      const file = directory ? `${directory}/${child.name}` : child.name;
+      if (excludedDocument(file)) continue;
+      const found = locate(file);
+      if (found.kind === 'directory') {
+        if (depth < bounds.maxDepth) walk(file, depth + 1, role);
+        else { scan.truncated = true; warn(file, 'depth-limit'); }
+      } else if (found.kind === 'file' && documentName(child.name)) add(file, found, role);
+      else if (found.kind === 'symbolic-link') add(found.boundary, found, role);
+    }
+  }
+  const declared = metadata(root, '.pbai4devs/estado/configuracao/ESTADO.md').documents;
+  for (const [role, file] of Object.entries(declared)) {
+    if (!documentRoles.has(role)) continue;
+    if (!safeDocument(file)) { if (file !== null) warn(null, 'invalid-configured-path'); continue; }
+    if (excludedDocument(file)) { configured.push({ role, path: file, kind: 'excluded' }); continue; }
+    const found = locate(file);
+    configured.push({ role, path: file, kind: found.kind });
+    if (found.kind === 'directory') walk(file, 0, role);
+    else if (found.kind === 'file' && documentName(path.posix.basename(file))) add(file, found, role);
+    else if (found.kind === 'file') warn(file, 'configured-path-not-document');
+    else if (found.kind === 'symbolic-link') add(found.boundary, found, role);
+  }
+  walk();
+  return {
+    files: [...files.values()].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0),
+    configured, scan: { ...scan, complete: !scan.truncated && warnings.length === 0 }, warnings,
+    exclusions: { directories: [...ignored].sort(), paths: excludedPaths, prefixes: ['playwright', '.playwright'] },
+    limits: ['Papeis inferidos por nome; confirme o conteudo antes de propor alteracoes.', 'Links simbolicos sao opacos; destinos nao sao lidos.', 'O inventario nao cria documentos nem comprova aprovacao ou completude.'],
+  };
+}
+
+export function inspectProject(root = repository, { check = false, documentationLimits } = {}) {
   requireNode();
   root = fs.realpathSync(path.resolve(root));
   if (!fs.statSync(root).isDirectory()) throw new Error('A origem deve ser um diretorio.');
@@ -160,6 +300,7 @@ export function inspectProject(root = repository, { check = false } = {}) {
   report.languages = [...languages].sort();
   report.contract = { checked: check, complete: report.structure.missing.length === 0 };
   report.maturity = maturity(root, report);
+  report.documentation = inspectDocumentation(root, documentationLimits);
   return report;
 }
 

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

@@ -1,9 +1,11 @@
 import assert from 'node:assert/strict';
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import test from 'node:test';
 import { projectRoot, requireNode } from '../../lib/runtime.mjs';
+import { inspectDocumentation } from '../SCRIPT.mjs';
 
 requireNode();
 const script = join(projectRoot, '.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs');
@@ -159,3 +161,168 @@ test('status arbitrários e referências fora da raiz não expõem dados da conf
   assert.equal(result.report.maturity.planning.ready, false);
   assert.ok(!result.stdout.includes(secret));
 });
+
+test('inventário documental vazio não cria arquivos nem presume aprovação', t => {
+  const { root, run } = fixture(t);
+  const result = run();
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(result.report.documentation.files, []);
+  assert.deepEqual(result.report.documentation.configured, []);
+  assert.equal(result.report.documentation.scan.truncated, false);
+  assert.equal(result.report.documentation.scan.complete, true);
+  assert.deepEqual(readdirSync(root), []);
+  assert.match(result.report.documentation.limits.at(-1), /nao cria documentos/);
+});
+
+test('descobre documentação real sem impor caixa, pasta docs ou frontmatter', t => {
+  const { root, file, run } = fixture(t);
+  const content = 'DOC_CONTENT_MUST_NOT_BE_EMITTED_182711';
+  for (const name of ['Readme.md', 'CONTRIBUTING.rst', 'SECURITY.adoc', 'History.md', 'ARCHITECTURE.md', 'AGENTS.md', 'LICENSE', 'examples/README', '_examples/server/README.md', 'wiki/guide.mdx', 'rfcs/001-change.md', 'packages/docs/content/api.mdx', '.github/CONTRIBUTING.md', '.github/SECURITY.md', '.github/copilot-instructions.md']) file(name, content);
+  for (const name of ['node_modules/lib/README.md', '.pbai4devs/README.md', '.claude/skills/private/SKILL.md', '.github/skills/demo/SKILL.md', '.github/agents/revisor.agent.md', 'examples/generated/fixture/README.md', '.PLAYWRIGHT-MCP/README.md', 'tmp/README.md']) file(name, content);
+  const result = run();
+  assert.equal(result.status, 0, result.stderr);
+  const docs = result.report.documentation;
+  assert.equal(docs.files.length, 15);
+  assert.equal(docs.files.find(item => item.path === 'Readme.md').role, 'readme');
+  assert.equal(docs.files.find(item => item.path === 'rfcs/001-change.md').role, 'decision');
+  assert.equal(docs.files.find(item => item.path === 'ARCHITECTURE.md').role, 'design');
+  assert.equal(docs.files.find(item => item.path === 'AGENTS.md').role, 'instructions');
+  assert.equal(docs.files.find(item => item.path === '.github/copilot-instructions.md').role, 'instructions');
+  assert.equal(docs.files.find(item => item.path === '.github/CONTRIBUTING.md').role, 'contribution');
+  assert.equal(docs.files.find(item => item.path === 'LICENSE').role, 'license');
+  assert.ok(docs.exclusions.paths.includes('.github/skills'));
+  assert.equal(docs.files.find(item => item.path === 'wiki/guide.mdx').sha256, createHash('sha256').update(content).digest('hex'));
+  assert.ok(docs.files.every(item => item.origin === 'inferred' && item.kind === 'file'));
+  assert.ok(!result.stdout.includes(content));
+  assert.equal(readFileSync(join(root, 'Readme.md'), 'utf8'), content);
+});
+
+test('caminhos cadastrados têm proveniência sem assumir status ou ler arquivos de configuração', t => {
+  const { file, run } = fixture(t);
+  file('.pbai4devs/estado/configuracao/ESTADO.md', '---\ndocumentos:\n  design: architecture/current.md\n  specs: specifications\n  prd: planning/absent.md\n  readme: ../private-secret.md\n  seguranca: .env\n---\n# Estado\n');
+  file('architecture/current.md', '# Existing architecture\n');
+  file('specifications/current.mdx', '# Increment\n');
+  file('.env', 'DO_NOT_EMIT_OR_HASH_THIS_SECRET');
+  const result = run();
+  assert.equal(result.status, 0, result.stderr);
+  const docs = result.report.documentation;
+  assert.deepEqual(docs.files.find(item => item.path === 'architecture/current.md').configuredAs, ['design']);
+  assert.equal(docs.files.find(item => item.path === 'specifications/current.mdx').origin, 'configured');
+  assert.ok(docs.configured.some(item => item.role === 'prd' && item.kind === 'missing'));
+  assert.ok(docs.warnings.some(item => item.reason === 'invalid-configured-path'));
+  assert.ok(docs.warnings.some(item => item.reason === 'configured-path-not-document'));
+  assert.ok(!docs.files.some(item => item.path === '.env'));
+  assert.ok(!result.stdout.includes('private-secret') && !result.stdout.includes('DO_NOT_EMIT'));
+  assert.equal(docs.files.some(item => Object.hasOwn(item, 'status')), false);
+});
+
+test('documentos simbólicos permanecem opacos sem ler destinos internos, externos ou ausentes', t => {
+  const { root, file, run } = fixture(t);
+  const outside = mkdtempSync(join(projectRoot, '.agent-tests', 'outside-docs-'));
+  t.after(() => rmSync(outside, { recursive: true, force: true }));
+  file('docs/real.md', '# Actual document\n');
+  writeFileSync(join(outside, 'private.md'), 'OUTSIDE_SECRET_MUST_NOT_APPEAR');
+  try {
+    symlinkSync('docs/real.md', join(root, 'README.md'));
+    symlinkSync(join(outside, 'private.md'), join(root, 'CLAUDE.md'));
+    symlinkSync('absent.md', join(root, 'missing.md'));
+    symlinkSync(outside, join(root, 'external'), process.platform === 'win32' ? 'junction' : 'dir');
+  } catch (error) {
+    if (process.platform !== 'win32' || !['EPERM', 'EACCES'].includes(error.code)) throw error;
+    t.skip('Links simbólicos indisponíveis sem permissão do Windows.'); return;
+  }
+  file('.pbai4devs/estado/configuracao/ESTADO.md', '---\ndocumentos:\n  design: external/private.md\n---\n# State\n');
+  const result = run();
+  assert.equal(result.status, 0, result.stderr);
+  const docs = result.report.documentation;
+  for (const name of ['README.md', 'CLAUDE.md', 'missing.md', 'external']) {
+    const item = docs.files.find(item => item.path === name);
+    assert.equal(item?.kind, 'symbolic-link', name);
+    assert.equal(item.sha256, undefined);
+  }
+  assert.ok(!docs.files.some(item => item.path === 'external/private.md'));
+  assert.ok(!result.stdout.includes(outside) && !result.stdout.includes('OUTSIDE_SECRET'));
+  assert.equal(docs.scan.complete, false);
+  assert.ok(docs.warnings.some(item => item.file === 'external' && item.reason === 'symbolic-link-not-inspected'));
+  assert.equal(readFileSync(join(outside, 'private.md'), 'utf8'), 'OUTSIDE_SECRET_MUST_NOT_APPEAR');
+});
+
+test('pastas documentais simbólicas sem cadastro não ocultam uma leitura incompleta', t => {
+  const { root, run } = fixture(t);
+  const outside = mkdtempSync(join(projectRoot, '.agent-tests', 'outside-doc-tree-'));
+  t.after(() => rmSync(outside, { recursive: true, force: true }));
+  const privateContent = 'UNREAD_EXTERNAL_DOCUMENT_719329';
+  writeFileSync(join(outside, 'private.md'), privateContent);
+  try {
+    for (const name of ['docs', 'wiki', 'rfcs', 'examples', 'custom-docs']) symlinkSync(outside, join(root, name), process.platform === 'win32' ? 'junction' : 'dir');
+    symlinkSync('absent-directory', join(root, 'missing-directory'), process.platform === 'win32' ? 'junction' : 'dir');
+  } catch (error) {
+    if (process.platform !== 'win32' || !['EPERM', 'EACCES'].includes(error.code)) throw error;
+    t.skip('Links simbólicos indisponíveis sem permissão do Windows.'); return;
+  }
+  const result = run();
+  assert.equal(result.status, 0, result.stderr);
+  const docs = result.report.documentation;
+  assert.equal(docs.scan.complete, false);
+  assert.equal(docs.scan.bytesRead, 0);
+  assert.deepEqual(docs.configured, []);
+  assert.deepEqual(docs.files.map(item => item.path), ['custom-docs', 'docs', 'examples', 'missing-directory', 'rfcs', 'wiki']);
+  assert.ok(docs.files.every(item => item.kind === 'symbolic-link' && item.role === 'unclassified' && !item.sha256));
+  assert.equal(docs.warnings.filter(item => item.reason === 'symbolic-link-not-inspected').length, 6);
+  assert.ok(!result.stdout.includes(outside) && !result.stdout.includes(privateContent));
+  assert.equal(readFileSync(join(outside, 'private.md'), 'utf8'), privateContent);
+  const limited = inspectDocumentation(root, { maxFiles: 1 });
+  assert.equal(limited.files.length, 1);
+  assert.equal(limited.scan.truncated, true);
+  assert.equal(limited.scan.complete, false);
+});
+
+test('limites documentais são explícitos e não retornam inventário parcial como completo', t => {
+  const { root, file } = fixture(t);
+  file('a.md', '123'); file('b.md', '456'); file('deep/nested/c.md', '789');
+  const files = inspectDocumentation(root, { maxFiles: 1 });
+  assert.equal(files.files.length, 1); assert.equal(files.scan.truncated, true);
+  assert.equal(files.scan.complete, false);
+  const entries = inspectDocumentation(root, { maxEntries: 1 });
+  assert.equal(entries.scan.entries, 1); assert.equal(entries.scan.truncated, true);
+  const depth = inspectDocumentation(root, { maxDepth: 0 });
+  assert.ok(!depth.files.some(item => item.path.startsWith('deep/')));
+  assert.ok(depth.warnings.some(item => item.reason === 'depth-limit'));
+  const bytes = inspectDocumentation(root, { maxFileBytes: 2 });
+  assert.equal(bytes.scan.bytesHashed, 0); assert.equal(bytes.scan.truncated, true);
+  assert.ok(bytes.files.every(item => !item.sha256));
+  const total = inspectDocumentation(root, { maxTotalBytes: 4 });
+  assert.ok(total.scan.bytesRead <= 4); assert.ok(total.scan.bytesHashed <= 4);
+  assert.equal(total.scan.truncated, true);
+  for (const limits of [{ maxFiles: -1 }, { maxEntries: 25001 }, { unknown: 1 }]) assert.throws(() => inspectDocumentation(root, limits), /Limite documental/);
+});
+
+test('inventário repetido preserva bytes, modos, caminhos e índice Git', t => {
+  const { root, file, run } = fixture(t);
+  file('README.md', '# Existing\n'); file('docs/guide.md', 'No imposed frontmatter\n');
+  const git = (...args) => {
+    const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+    assert.equal(result.status, 0, result.stderr); return result.stdout;
+  };
+  git('init', '--quiet', '--template='); git('add', '--', 'README.md');
+  const snapshot = () => {
+    const files = {};
+    const visit = (folder = '') => {
+      for (const name of readdirSync(join(root, folder)).sort()) {
+        if (name === '.git') continue;
+        const relative = folder ? `${folder}/${name}` : name;
+        const info = lstatSync(join(root, relative));
+        files[relative] = { mode: info.mode, kind: info.isDirectory() ? 'directory' : info.isSymbolicLink() ? 'symbolic-link' : 'file' };
+        if (info.isSymbolicLink()) files[relative].target = readlinkSync(join(root, relative));
+        else if (info.isDirectory()) visit(relative);
+        else files[relative].sha256 = createHash('sha256').update(readFileSync(join(root, relative))).digest('hex');
+      }
+    };
+    visit(); return { files, index: git('ls-files', '--stage'), staged: git('diff', '--cached', '--binary'), config: readFileSync(join(root, '.git/config'), 'utf8') };
+  };
+  const before = snapshot();
+  const first = run(), second = run();
+  assert.equal(first.status, 0, first.stderr); assert.equal(second.status, 0, second.stderr);
+  assert.deepEqual(first.report.documentation, second.report.documentation);
+  assert.deepEqual(snapshot(), before);
+});

package/.pbai4devs/scripts/lib/native-paths.mjs

@@ -0,0 +1,35 @@
+import { lstatSync, readdirSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+
+// Inspect native paths without opening a symlink target. Callers restrict this
+// exception to user-owned adapter paths; canonical kit files stay strict.
+export function nativePathBoundary(root, path, ownedPaths = [], { preserveRootAliases = false } = {}) {
+  if (typeof path !== 'string' || !path || isAbsolute(path) || /[|\\\x00-\x1f\x7f:]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')) {
+    throw Object.assign(new Error(`Caminho invalido: ${path}`), { code: 'E_PATH' });
+  }
+  const parts = path.split('/');
+  let current = root;
+  for (const [index, part] of parts.entries()) {
+    try {
+      const aliases = lstatSync(current).isDirectory() ? readdirSync(current).filter(name => name.toLowerCase() === part.toLowerCase() && name !== part).sort() : [];
+      if (aliases.length) {
+        const rootEntry = parts.length === 1 && ['README.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md'].includes(path);
+        const owned = [...ownedPaths].some(value => value.toLowerCase() === path.toLowerCase() || value.toLowerCase().startsWith(`${path.toLowerCase()}/`));
+        if (preserveRootAliases && rootEntry && !owned) return { path: aliases[0], reason: 'case-variant' };
+        throw Object.assign(new Error(`Caminhos diferem somente por maiusculas/minusculas: ${path}`), { code: 'E_PATH' });
+      }
+    } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; }
+    current = join(current, part);
+    let info;
+    try { info = lstatSync(current); }
+    catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; }
+    const reason = info.isSymbolicLink() ? 'symbolic-link' : index < parts.length - 1 && !info.isDirectory() ? 'non-directory' : null;
+    if (!reason) continue;
+    const boundary = parts.slice(0, index + 1).join('/');
+    if ([...ownedPaths].some(value => value === boundary || value.startsWith(`${boundary}/`))) {
+      throw Object.assign(new Error(`${reason === 'symbolic-link' ? 'Link simbolico' : 'Ancestral nao e diretorio'} em caminho gerenciado: ${boundary}`), { code: reason === 'symbolic-link' ? 'E_SYMLINK' : 'E_PATH' });
+    }
+    return { path: boundary, reason };
+  }
+  return null;
+}

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.
+Recursos nativos humanos e seus links permanecem intactos, inclusive com
+`--force`. O retorno inclui `preserved`; esses caminhos não contam como
+derivados pendentes nem passam a pertencer ao kit.
 
 Metadados vêm da fonte ou do YAML nativo declarado no manifesto. Regras exigem
 `trigger` válido; `glob` exige `globs`. Origens nativas precisam pertencer ao