@pathbit/agentdevkit 0.0.7 → 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/gitignore.mjs

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
@@ -63,6 +63,7 @@ export function renderClientIgnore(template, settings = {}) {
 
 const localStat = file => { try { return lstatSync(file); } catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; } };
 const localRead = file => localStat(file) ? readFileSync(file, 'utf8') : null;
+const localMode = file => { const item = localStat(file); return item ? item.mode & 0o777 : null; };
 const portable = path => path.split(sep).join('/');
 
 function canonicalExisting(path) {
@@ -144,6 +145,61 @@ function artifactProbes(root, patterns) {
   return [...probes];
 }
 
+const matchesComponent = (part, pattern) => posix.matchesGlob(`x${part}`, `x${pattern.replace(/[{}()]/g, '\\$&')}`);
+
+function matchesParts(parts, pattern) {
+  const cache = new Map();
+  function match(part, glob) {
+    const key = `${part}:${glob}`; if (cache.has(key)) return cache.get(key);
+    const expected = pattern[glob];
+    const result = glob === pattern.length ? part === parts.length
+      : expected === '**' ? match(part, glob + 1) || part < parts.length && match(part + 1, glob)
+        : part < parts.length && matchesComponent(parts[part], expected) && match(part + 1, glob + 1);
+    cache.set(key, result); return result;
+  }
+  return match(0, 0);
+}
+
+function artifactPath(path, patterns, directory = false) {
+  const parts = path.split('/');
+  return patterns.some(pattern => {
+    const rule = pattern.slice(3).replace(/\/$/, '');
+    return parts.some((part, index) => (index < parts.length - 1 || directory || !pattern.endsWith('/'))
+      && (rule.includes('/') ? matchesParts(parts.slice(0, index + 1), ['**', ...rule.split('/')])
+        : matchesComponent(part, rule)));
+  });
+}
+
+function visibleArtifactProbes(root, location, patterns) {
+  const listed = gitCommand(location.top, ['--literal-pathspecs', '-c', 'core.excludesFile=', 'ls-files', '--cached', '--others', '--exclude-standard', '-z', '--', location.prefix ? `${location.prefix}/` : '.']);
+  if (listed.error || listed.status !== 0) throw new Error(listed.error?.message || listed.stderr || 'Falha ao conferir artefatos existentes.');
+  const paths = listed.stdout.split('\0').filter(Boolean), prefix = location.prefix ? `${location.prefix}/` : '';
+  const probes = new Set(paths.filter(path => path.startsWith(prefix)).map(path => path.slice(prefix.length)).filter(path => artifactPath(path, patterns)));
+  const ignores = new Set(paths.filter(path => path.startsWith(prefix) && (path === '.gitignore' || path.endsWith('/.gitignore'))));
+  let ancestor = root;
+  while (true) {
+    ignores.add(portable(relative(location.top, join(ancestor, '.gitignore'))));
+    if (ancestor === location.top) break;
+    ancestor = dirname(ancestor);
+  }
+  for (const path of ignores) {
+    const file = join(location.top, path), item = localStat(file);
+    if (!item?.isFile() || item.isSymbolicLink()) continue;
+    // Git resolves precedence; these literals only add witnesses for named exceptions.
+    for (const line of readFileSync(checkedLocalPath(file), 'utf8').split(/\r?\n/)) {
+      if (!line.startsWith('!') || line.length === 1) continue;
+      const rule = line.slice(1).replace(/(?<!\\) +$/, ''), directory = rule.endsWith('/') || rule.endsWith('/**');
+      const literal = rule.replace(/(?:\/\*\*)+\/?$/, '').replace(/\/$/, '').replace(/^\//, '');
+      if (/(^|[^\\])[*?\[]/.test(literal)) continue;
+      const ruleBase = !rule.startsWith('/') && !literal.includes('/') && relative(dirname(file), root).split(sep)[0] !== '..' ? root : dirname(file);
+      const candidate = portable(relative(root, resolve(ruleBase, literal.replace(/\\(.)/g, '$1'))));
+      if (!candidate || candidate === '..' || candidate.startsWith('../') || !artifactPath(candidate, patterns, directory)) continue;
+      probes.add(checkedOutput(directory ? `${candidate}/.agentdevkit-artifact-probe` : candidate));
+    }
+  }
+  return [...probes];
+}
+
 function localIgnoreSource(location, source) {
   const path = resolve(location.top, source);
   if (path === location.exclude) return true;
@@ -204,9 +260,9 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const body = fixed.split(/\r?\n/).map(line => location?.prefix && line.startsWith('/') ? `/${escapePattern(location.prefix)}${line}` : line).join('\n');
   const target = location?.exclude ?? checkedLocalPath(join(root, '.gitignore'));
   const before = localRead(target), after = localBlock(before, first, last, body);
-  const edits = before === after ? [] : [{ path: target, before, after }];
+  const edits = before === after ? [] : [{ path: target, before, after, beforeMode: localMode(target) }];
   const probes = [...paths, ...rootProbes(root, roots)];
-  const artifactPaths = artifactProbes(root, artifacts);
+  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...(location ? visibleArtifactProbes(root, location, artifacts) : [])])];
   const wanted = new Set(probes.map(path => location?.prefix ? `${location.prefix}/${path}` : path));
   if (location && !before?.includes(first) && !localRead(join(root, '.gitignore'))?.includes(first)) {
     const ignored = ignoreMatches(location, [...probes, ...artifactPaths]);
@@ -215,10 +271,10 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   if (location) {
     const fallback = checkedLocalPath(join(root, '.gitignore'));
     const old = localRead(fallback), next = localBlock(old, first, last, null);
-    if (old !== null && old !== next) edits.push({ path: fallback, before: old, after: next });
+    if (old !== null && old !== next) edits.push({ path: fallback, before: old, after: next, beforeMode: localMode(fallback) });
   }
   const tracked = location ? gitCommand(location.top, ['ls-files', '-z']).stdout.split('\0').filter(path => wanted.has(path)).map(path => location.prefix ? path.slice(location.prefix.length + 1) : path) : [];
-  return { root, status: location ? 'git' : 'fallback', location, paths, roots, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last };
+  return { root, status: location ? 'git' : 'fallback', location, paths, roots, artifactPatterns: artifacts, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last };
 }
 
 export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
@@ -235,7 +291,8 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
     return { ...item, path };
   });
   if (plan.location && (plan.paths.length || plan.artifactProbes?.length)) {
-    const probes = [...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || [])];
+    const probes = [...new Set([...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || []),
+      ...(plan.artifactPatterns ? visibleArtifactProbes(plan.root, plan.location, plan.artifactPatterns) : [])])];
     const { paths: relativePaths, matches } = ignoreMatches(plan.location, probes);
     for (let index = 0; index < relativePaths.length; index++) {
       const match = matches.get(relativePaths[index]);
@@ -252,10 +309,21 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
 export function assertLocalIgnoreUnchanged(plan) {
   for (const edit of plan.edits) {
     checkedLocalPath(edit.path);
-    if (localRead(edit.path) !== edit.before) throw new Error(`Exclusao alterada apos planejar: ${edit.path}`);
+    if (localRead(edit.path) !== edit.before || Object.hasOwn(edit, 'beforeMode') && localMode(edit.path) !== edit.beforeMode) throw new Error(`Exclusao alterada apos planejar: ${edit.path}`);
   }
 }
 
+function atomicLocalWrite(path, content, mode, published) {
+  const temporary = `${path}.agentdevkit-${randomUUID()}`;
+  try {
+    writeFileSync(temporary, content, { flag: 'wx' });
+    if (mode !== null && mode !== undefined) chmodSync(temporary, mode);
+    const writtenMode = localMode(temporary);
+    renameSync(temporary, path);
+    published?.(writtenMode);
+  } finally { rmSync(temporary, { force: true }); }
+}
+
 export function applyLocalIgnore(plan) {
   assertLocalIgnoreUnchanged(plan);
   const before = checkLocalIgnore(plan);
@@ -264,18 +332,19 @@ export function applyLocalIgnore(plan) {
   try {
     for (const edit of plan.edits) {
       mkdirSync(dirname(edit.path), { recursive: true });
-      const temporary = `${edit.path}.agentdevkit-${randomUUID()}`;
-      try { writeFileSync(temporary, edit.after, { flag: 'wx' }); renameSync(temporary, edit.path); }
-      finally { rmSync(temporary, { force: true }); }
-      written.push(edit);
+      atomicLocalWrite(edit.path, edit.after, edit.beforeMode, mode => written.push({ edit, mode }));
     }
     const verified = checkLocalIgnore({ ...plan, edits: [], trackedOutputs: [] });
     if (verified.missing.length) throw new Error(`Regras humanas reabrem derivados locais: ${verified.missing.join(', ')}`);
   } catch (error) {
-    for (const edit of written.reverse()) {
-      if (localRead(edit.path) !== edit.after) continue;
-      if (edit.before === null) rmSync(edit.path, { force: true }); else writeFileSync(edit.path, edit.before);
+    const rollbackErrors = [];
+    for (const { edit, mode } of written.reverse()) {
+      try {
+        if (localRead(edit.path) !== edit.after || localMode(edit.path) !== mode) continue;
+        if (edit.before === null) rmSync(edit.path, { force: true }); else atomicLocalWrite(edit.path, edit.before, edit.beforeMode);
+      } catch (failure) { rollbackErrors.push(failure); }
     }
+    if (rollbackErrors.length) throw new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error });
     throw error;
   }
   return { status: plan.status, changed: plan.edits.length, trackedOutputs: plan.trackedOutputs };