@pathbit/agentdevkit 0.0.22 → 0.0.24

package/.pbai4devs/rules/ambiente-local/RULE.md

@@ -27,6 +27,11 @@ O Makefile deve oferecer `help`, `doctor`, `setup`, `up`, `down`, `logs`,
 `test`, `lint` e `build`, com comandos reais da stack. Etapas ainda indefinidas
 devem falhar com mensagem útil; não simule sucesso. Documente os comandos,
 dependências e URL/porta no README; valide Compose e saúde antes de concluir.
+Antes de existir aplicação, valide o runtime, o Compose e os serviços de
+infraestrutura necessários. Build, saúde e fluxo da aplicação inexistente
+permanecem pendentes; não crie código de negócio para simular essas provas. Se
+uma dependência obrigatória estiver indisponível, mantenha a configuração
+pendente e registre o impedimento. Após a implementação, prove a aplicação.
 
 Use o [modelo de ambiente](../../templates/ambiente-local/TEMPLATE.md) para
 perguntas e arquivos-base. Versões da aplicação seguem as decisões do projeto;

package/.pbai4devs/rules/git/RULE.md

@@ -1,10 +1,14 @@
 ---
 trigger: model_decision
-description: Aplique ao preparar, integrar ou publicar alterações Git.
+description: Aplique ao consultar, preparar, integrar ou publicar alterações Git.
 ---
 
 # Regras Git
 
+Em consultas sem alterações, defina `GIT_OPTIONAL_LOCKS=0` no ambiente do
+subprocesso para evitar atualizações opcionais dos bytes do índice. Isso não
+substitui as travas necessárias para operações que alteram o Git.
+
 Use Conventional Commits (`tipo(escopo): descrição`, escopo opcional), inclusive
 em checkpoints e merges; destaque mudanças incompatíveis com `!` ou
 `BREAKING CHANGE:`. Autor e committer devem ser o usuário, nunca um agente;

package/.pbai4devs/scripts/README.md

@@ -26,6 +26,7 @@ node .pbai4devs/scripts/executar-script/SCRIPT.mjs diagnosticar-ambiente
 | --- | --- |
 | `diagnosticar-ambiente` | Runtimes, pacotes e navegadores disponíveis |
 | `inspecionar-projeto` | Detecta manifests, comandos e estrutura |
+| `verificar-configuracao` | Confere o estado antes de implementar código |
 | `preparar-ferramentas` | Instala/atualiza ferramentas locais |
 | `gerenciar-skills-externas` | Instala/check/read de skills curadas locais |
 | `auditar-seguranca` | Scanners offline, bases locais e relatórios redigidos |

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

@@ -12,6 +12,10 @@ 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.
+Na maturidade, o roadmap e as specs são consultados nos caminhos configurados;
+status são declarações e um vínculo local não comprova aprovação ou revisão.
+Uma lista de specs ambígua ou incompleta não autoriza escolher um incremento;
+o estado do vínculo no roadmap também é apenas uma indicação para consulta.
 
 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
@@ -20,6 +24,8 @@ 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.
+O inspetor revalida a identidade dos caminhos durante a leitura; isso detecta
+mudanças, mas não é uma garantia atômica contra toda troca simultânea.
 
 `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

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

@@ -41,12 +41,69 @@ const present = (root, name, directory) => {
 const inside = candidate => { const relative = path.relative(repository, candidate); return relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative); };
 const fixturePath = candidate => /^(?:\.agent-tests\/|tmp\/examples\/|examples\/generated\/)/.test(normalize(path.relative(repository, candidate)));
 
+// Rechecking is a conservative race detection, not an atomic openat traversal.
+function pathIdentity(root, file = '') {
+  try {
+    let current = root; const result = [], parts = file ? file.split('/') : [];
+    for (const [index, part] of ['', ...parts].entries()) {
+      if (part) current = path.join(current, part);
+      const item = fs.lstatSync(current);
+      if (item.isSymbolicLink() || (index < parts.length && !item.isDirectory())) return null;
+      result.push({ dev: item.dev, ino: item.ino, mode: item.mode, size: item.size, directory: item.isDirectory() });
+    }
+    return result;
+  } catch { return null; }
+}
+const sameIdentity = (left, right) => left && right && left.length === right.length
+  && left.every((item, index) => item.dev === right[index].dev && item.ino === right[index].ino && item.mode === right[index].mode);
+
+function boundedEntries(folder, limit, verify = () => true) {
+  const handle = fs.opendirSync(folder), entries = [];
+  try {
+    if (!verify()) return { entries: [], truncated: true, changed: true };
+    while (true) {
+      const entry = handle.readSync();
+      if (!entry) return verify() ? { entries, truncated: false } : { entries: [], truncated: true, changed: true };
+      if (entries.length >= limit) return verify() ? { entries, truncated: true } : { entries: [], truncated: true, changed: true };
+      entries.push(entry);
+    }
+  } finally { handle.closeSync(); }
+}
+
+function stableDirectory(root, directory, limit) {
+  const identity = pathIdentity(root, directory);
+  if (!identity?.at(-1).directory) return { entries: [], truncated: true, changed: true, verify: () => false };
+  const verify = () => sameIdentity(identity, pathIdentity(root, directory));
+  return { ...boundedEntries(path.join(root, directory), limit, verify), verify };
+}
+
 function metadata(root, file) {
-  if (!present(root, file, false) || fs.statSync(path.join(root, file)).size > 1024 * 1024) return { fields: {}, documents: {} };
-  const text = fs.readFileSync(path.join(root, file), 'utf8').replaceAll('\r', '');
+  const empty = { fields: {}, documents: {}, text: null };
+  const identity = () => pathIdentity(root, file);
+  let descriptor, text;
+  try {
+    const name = path.join(root, file), ancestors = identity();
+    if (!ancestors || !sameIdentity(ancestors, identity())) return empty;
+    const before = ancestors.at(-1);
+    if (before.size > 1024 * 1024) return empty;
+    descriptor = fs.openSync(name, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    const opened = fs.fstatSync(descriptor);
+    if (!opened.isFile() || opened.dev !== before.dev || opened.ino !== before.ino || opened.size !== before.size || !sameIdentity(ancestors, identity())) return empty;
+    const buffer = Buffer.alloc(opened.size + 1); let length = 0;
+    while (length < buffer.length) {
+      const count = fs.readSync(descriptor, buffer, length, buffer.length - length, length);
+      if (!count) break;
+      length += count;
+    }
+    const after = fs.fstatSync(descriptor);
+    if (length !== opened.size || after.size !== opened.size || after.mtimeMs !== opened.mtimeMs || after.ctimeMs !== opened.ctimeMs || !sameIdentity(ancestors, identity())) return empty;
+    text = buffer.subarray(0, length).toString('utf8').replaceAll('\r', '');
+  } catch { return empty; }
+  finally { if (descriptor !== undefined) fs.closeSync(descriptor); }
   const header = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1];
-  const result = { fields: {}, documents: {} }; if (!header) return result;
-  let documents = false;
+  const result = { fields: {}, documents: {}, text }; if (!header) return result;
+  let documents = false, invalidDocuments = false;
+  const seen = new Set(), duplicates = new Set(), seenDocuments = new Set(), duplicateDocuments = new Set();
   const scalar = raw => {
     const value = raw.trim();
     if (!value || ['null', '~'].includes(value)) return null;
@@ -54,16 +111,131 @@ function metadata(root, file) {
     return value.startsWith("'") && value.endsWith("'") ? value.slice(1, -1).replaceAll("''", "'") : value;
   };
   for (const line of header.split('\n')) {
-    const top = line.match(/^([a-z_]+):\s*(.*)$/);
-    if (top) { documents = top[1] === 'documentos'; result.fields[top[1]] = scalar(top[2]); }
-    else if (documents) { const item = line.match(/^  ([a-z_]+):\s*(.*)$/); if (item) result.documents[item[1]] = scalar(item[2]); }
+    if (!line.trim() || /^\s*#/.test(line)) continue;
+    const top = line.match(/^(?:([\p{L}_][\p{L}\p{N}_.-]*)|"([^"\n]+)"|'([^'\n]+)'):\s*(.*)$/u);
+    if (top) {
+      const key = top[1] || top[2] || top[3];
+      if (key.includes('\\')) return { ...empty, text };
+      if (seen.has(key)) duplicates.add(key);
+      seen.add(key); result.fields[key] = duplicates.has(key) ? null : scalar(top[4]);
+      if (key === 'documentos' && duplicates.has(key)) { invalidDocuments = true; result.documents = {}; }
+      documents = key === 'documentos' && !invalidDocuments && (!top[4].trim() || ['null', '~'].includes(top[4].trim()));
+    } else if (!/^\s/.test(line)) return { ...empty, text };
+    else if (documents) {
+      const item = line.match(/^  (?:([\p{L}_][\p{L}\p{N}_.-]*)|"([^"\n]+)"|'([^'\n]+)'):\s*(.*)$/u);
+      if (item) {
+        const key = item[1] || item[2] || item[3];
+        if (key.includes('\\')) { invalidDocuments = true; result.documents = {}; documents = false; continue; }
+        if (seenDocuments.has(key)) duplicateDocuments.add(key);
+        seenDocuments.add(key); result.documents[key] = duplicateDocuments.has(key) ? null : scalar(item[4]);
+      } else if (/^  \S/.test(line)) { invalidDocuments = true; result.documents = {}; documents = false; }
+    }
   }
   return result;
 }
 
+// The configured specs directory contains <slug>/SPEC.md. Refuse ambiguous
+// layouts instead of guessing which increment or declared status to use.
+function configuredSpecs(root, directory) {
+  const result = { path: directory, present: false, complete: false, items: [] };
+  if (!directory) return result;
+  let current = root;
+  for (const component of directory.split('/')) {
+    current = path.join(current, component);
+    try {
+      const info = fs.lstatSync(current);
+      if (info.isSymbolicLink() || !info.isDirectory()) return result;
+    } catch (error) {
+      if (error.code === 'ENOENT') result.complete = true;
+      return result;
+    }
+  }
+  result.present = true;
+  const incomplete = () => { result.items = []; return result; };
+  let scanned = 0;
+  function entriesAt(folder) {
+    const relative = normalize(path.relative(root, folder));
+    const result = stableDirectory(root, relative, Math.min(200, 500 - scanned));
+    scanned += result.entries.length;
+    return result.truncated ? null : result.entries;
+  }
+  try {
+    const entries = entriesAt(current);
+    if (!entries) return incomplete();
+    for (const entry of entries) {
+      if (/^readme(?:\.md)?$/i.test(entry.name) && !entry.isSymbolicLink()) continue;
+      if (['.git', '.pbai4devs', '.agent-tests', 'node_modules'].includes(entry.name.toLowerCase())) return incomplete();
+      if (!entry.isDirectory() || entry.isSymbolicLink()) return incomplete();
+      const folder = `${directory}/${entry.name}`;
+      if (!present(root, folder, true)) return incomplete();
+      const children = entriesAt(path.join(root, folder));
+      if (!children) return incomplete();
+      const names = children.filter(item => /^spec\.md$/i.test(item.name));
+      if (names.length !== 1 || !names[0].isFile() || names[0].isSymbolicLink()) return incomplete();
+      const file = `${folder}/${names[0].name}`;
+      if (!present(root, file, false)) return incomplete();
+      const document = metadata(root, file);
+      if (document.text === null) return incomplete();
+      result.items.push({ path: file, status: ['rascunho', 'pendente', 'aprovado'].includes(document.fields.status) ? document.fields.status : null });
+      if (result.items.length > 1) return incomplete();
+    }
+    if (!present(root, directory, true)) return incomplete();
+    result.complete = true;
+  } catch { return incomplete(); }
+  return result;
+}
+
+function referenceState(roadmap, roadmapFile, specFile) {
+  if (!roadmap || !roadmapFile) return { linked: false, roadmapState: 'unknown' };
+  // Examples and orphan reference definitions do not select an increment.
+  const lines = []; let fence = null;
+  const body = roadmap.replace(/^---\n[^]*?\n---(?:\n|$)/, '').replace(/<!--[^]*?-->/g, '');
+  for (const line of body.split('\n')) {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/);
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !line.slice(marker[0].length).trim()) fence = null;
+    } else if (marker) fence = marker[1];
+    else lines.push(line.replace(/(`+)[^`\n]*?\1/g, ''));
+  }
+  const normalizeLabel = label => label.trim().replace(/\s+/g, ' ').toLowerCase();
+  const definitions = new Map();
+  for (const line of lines) {
+    const match = line.match(/^ {0,3}\[([^\]]+)\]:[ \t]*(?:<([^>\n]+)>|(\S+))(?:[ \t]+(?:"[^"\n]*"|'[^'\n]*'))?[ \t]*$/);
+    if (match) { const label = normalizeLabel(match[1]); definitions.set(label, [...(definitions.get(label) || []), match[2] || match[3]]); }
+  }
+  const references = [], ancestry = [];
+  for (const line of lines) {
+    const list = line.match(/^([ \t]*)(?:[-+*]|\d+[.)])\s+(.*)$/);
+    const marker = list?.[2].match(/^\[([ xX-])\](?:\s|$)/);
+    const closed = /(?:^|[^\p{L}])(?:cancelad[ao]s?|conclu[ií]d[ao]s?|publicad[ao]s?|finalizad[ao]s?|descartad[ao]s?|cancelled|completed|published)(?=$|[^\p{L}])/iu.test(line);
+    let state = 'unknown';
+    if (list) {
+      const indent = list[1].length;
+      while (ancestry.length && ancestry.at(-1).indent >= indent) ancestry.pop();
+      const own = closed || marker && /x/i.test(marker[1]) ? 'closed' : marker?.[1] === ' ' ? 'open' : marker?.[1] === '-' ? 'in-progress' : 'unknown';
+      state = ancestry.some(item => item.state === 'closed') ? 'closed' : /\t/.test(list[1]) || ancestry.some(item => item.state === 'unknown') ? 'unknown' : own;
+      ancestry.push({ indent, state });
+    } else if (line.trim() && !/^\s/.test(line)) ancestry.length = 0;
+    for (const match of line.matchAll(/(?<![!\\])\[[^\]\n]+\]\(\s*(?:<([^>\n]+)>|([^\s)]+))(?:\s+(?:"[^"\n]*"|'[^'\n]*'))?\s*\)/g)) references.push({ destination: match[1] || match[2], state });
+    for (const match of line.matchAll(/(?<![!\\])\[([^\]\n]+)\]\[([^\]\n]*)\]/g)) {
+      const label = normalizeLabel(match[2] || match[1]);
+      if (definitions.get(label)?.length === 1) references.push({ destination: definitions.get(label)[0], state });
+    }
+  }
+  const matches = references.filter(({ destination }) => {
+    try {
+      const value = decodeURIComponent(destination).split(/[?#]/, 1)[0];
+      if (!value || /^(?:[a-z][a-z0-9+.-]*:|\/|\\)/i.test(value) || value.includes('\\')) return false;
+      return path.posix.resolve('/', path.posix.dirname(roadmapFile), value) === '/' + specFile;
+    } catch { return false; }
+  });
+  if (matches.length !== 1) return { linked: matches.length > 0, roadmapState: matches.length ? 'ambiguous' : 'unknown' };
+  return { linked: true, roadmapState: matches[0].state };
+}
+
 function maturity(root, report) {
   const stateFile = `${stateDirectory(root)}/configuracao/ESTADO.md`; const state = metadata(root, stateFile);
-  const safeDocument = value => typeof value === 'string' && !path.isAbsolute(value) && !value.includes('\\') && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
+  const safeDocument = value => typeof value === 'string' && !path.isAbsolute(value) && !/[\\\x00-\x1f\x7f:]/.test(value) && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part.toLowerCase()));
   const planning = {};
   for (const name of ['prd', 'ux_ui', 'design']) {
     const file = state.documents[name];
@@ -72,10 +244,22 @@ function maturity(root, report) {
     planning[name] = { path: safeDocument(file) ? file : null, present: Boolean(exists), status: ['rascunho', 'aprovado', 'nao-aplicavel', 'pendente'].includes(status) ? status : null };
   }
   planning.ready = planning.prd.status === 'aprovado' && planning.design.status === 'aprovado' && ['aprovado', 'nao-aplicavel'].includes(planning.ux_ui.status);
-  let released = false; const releases = state.documents.releases;
+  const roadmapPath = safeDocument(state.documents.roadmap) && /\.md$/i.test(state.documents.roadmap) ? state.documents.roadmap : null;
+  const roadmapPresent = Boolean(roadmapPath && present(root, roadmapPath, false));
+  const roadmapDocument = roadmapPresent ? metadata(root, roadmapPath) : { fields: {}, text: null };
+  planning.roadmap = { path: roadmapPath, present: roadmapPresent, status: ['pendente', 'rascunho', 'planejado', 'aprovado'].includes(roadmapDocument.fields.status) ? roadmapDocument.fields.status : null };
+  const specsPath = safeDocument(state.documents.specs) ? state.documents.specs : null;
+  planning.specs = configuredSpecs(root, specsPath);
+  for (const spec of planning.specs.items) Object.assign(spec, referenceState(roadmapDocument.text, roadmapPath, spec.path));
+  let released = false, releasesComplete = true; const releases = state.documents.releases;
   if (safeDocument(releases) && present(root, releases, true)) {
     const visit = (directory, depth = 0) => {
-      for (const entry of fs.readdirSync(path.join(root, directory), { withFileTypes: true }).slice(0, 100)) {
+      let listing;
+      try { listing = stableDirectory(root, directory, 100); }
+      catch { releasesComplete = false; return; }
+      if (listing.truncated) releasesComplete = false;
+      for (const entry of listing.entries) {
+        if (!listing.verify()) { releasesComplete = false; return; }
         const file = normalize(path.join(directory, entry.name));
         if (entry.isSymbolicLink()) continue;
         if (entry.isDirectory() && depth < 2) visit(file, depth + 1);
@@ -91,7 +275,7 @@ function maturity(root, report) {
   if (planning.ready) level = 'planejado';
   if (report.mode === 'aplicacao-detectada') level = 'implementacao';
   if (report.mode === 'aplicacao-detectada' && planning.ready && report.contract.complete && configuration.configuracao_tecnica === 'concluido') level = released ? 'manutencao' : 'configurado';
-  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.'] };
+  return { level, planning, configuration, released, releasesComplete, signals: { application: report.mode === 'aplicacao-detectada', structure: report.contract.complete }, limits: ['Classificacao descritiva; status em arquivos nao substitui aprovacao, testes ou provas de funcionamento.'] };
 }
 
 const documentRoles = new Set(['readme', 'contribuicao', 'changelog', 'seguranca', 'adrs', 'prd', 'ux_ui', 'design', 'roadmap', 'releases', 'specs', 'tarefas']);
@@ -152,10 +336,12 @@ export function inspectDocumentation(root, limits = {}) {
     }
     let descriptor;
     try {
+      const identity = pathIdentity(root, file);
+      if (!identity || !sameIdentity(identity, pathIdentity(root, file))) { warn(file, 'changed-during-read'); return; }
       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; }
+        || before.mtimeMs !== expected.mtimeMs || before.ctimeMs !== expected.ctimeMs || !sameIdentity(identity, pathIdentity(root, file))) { 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) {
@@ -165,7 +351,7 @@ export function inspectDocumentation(root, limits = {}) {
         scan.bytesRead += read;
       }
       const after = fs.fstatSync(descriptor);
-      if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) {
+      if (length !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || !sameIdentity(identity, pathIdentity(root, file))) {
         warn(file, 'changed-during-read'); return;
       }
       scan.bytesHashed += length;
@@ -194,8 +380,13 @@ export function inspectDocumentation(root, limits = {}) {
       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); }
+    let children, listing;
+    try {
+      listing = stableDirectory(root, directory, Math.max(0, bounds.maxEntries - scan.entries));
+      if (listing.changed) { scan.truncated = true; warn(directory || '.', 'changed-during-read'); return; }
+      if (listing.truncated) scan.truncated = true;
+      children = listing.entries.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; }
@@ -204,6 +395,7 @@ export function inspectDocumentation(root, limits = {}) {
       scan.entries++;
       const file = directory ? `${directory}/${child.name}` : child.name;
       if (excludedDocument(file)) continue;
+      if (!listing.verify()) { scan.truncated = true; warn(directory || '.', 'changed-during-read'); return; }
       const found = locate(file);
       if (found.kind === 'directory') {
         if (depth < bounds.maxDepth) walk(file, depth + 1, role);
@@ -244,8 +436,11 @@ export function inspectProject(root = repository, { check = false, documentation
   const warning = (file, reason) => report.warnings.push({ file, reason });
   function commands(file, name) {
     if (!['package.json', 'composer.json', 'deno.json', 'deno.jsonc', 'Makefile', 'makefile', 'GNUmakefile', 'pyproject.toml'].includes(name)) return;
-    if (fs.statSync(path.join(root, file)).size > 1024 * 1024) { warning(file, 'manifest-grande-demais'); return; }
-    const text = fs.readFileSync(path.join(root, file), 'utf8');
+    const identity = pathIdentity(root, file);
+    if (!identity) { warning(file, 'manifest-nao-inspecionado'); return; }
+    if (identity.at(-1).size > 1024 * 1024) { warning(file, 'manifest-grande-demais'); return; }
+    const text = metadata(root, file).text;
+    if (text === null) { warning(file, 'manifest-nao-inspecionado'); return; }
     let names = [];
     try {
       if (['package.json', 'composer.json', 'deno.json', 'deno.jsonc'].includes(name)) {
@@ -268,7 +463,10 @@ export function inspectProject(root = repository, { check = false, documentation
     } catch { warning(file, 'manifest-nao-interpretado'); }
   }
   function walk(directory = '', depth = 0) {
-    const children = fs.readdirSync(path.join(root, directory), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    const listing = stableDirectory(root, directory, Math.max(0, 25000 - entries));
+    if (listing.changed) { report.scan.truncated = true; warning(directory || '.', 'changed-during-read'); return; }
+    if (listing.truncated) report.scan.truncated = true;
+    const children = listing.entries.sort((a, b) => a.name.localeCompare(b.name));
     for (const item of children) {
       if (++entries > 25000) { report.scan.truncated = true; return; }
       const file = normalize(path.join(directory, item.name));
@@ -276,10 +474,12 @@ export function inspectProject(root = repository, { check = false, documentation
       if (item.isSymbolicLink()) continue;
       if (item.isDirectory()) {
         if (excluded.has(item.name) || excluded.has(item.name.toLowerCase()) || /^\.?playwright/i.test(item.name)) continue;
+        if (!listing.verify()) { report.scan.truncated = true; warning(directory || '.', 'changed-during-read'); return; }
         if (depth < report.scan.maxDepth) walk(file, depth + 1); else report.scan.truncated = true;
         continue;
       }
       if (!item.isFile()) continue;
+      if (!listing.verify()) { report.scan.truncated = true; warning(directory || '.', 'changed-during-read'); return; }
       let language = manifests.get(item.name);
       if (/\.(?:csproj|fsproj|vbproj|sln)$/.test(item.name)) language = 'dotnet';
       if (/^requirements(?:[.-][A-Za-z0-9_-]+)?\.txt$/.test(item.name)) language = 'python';

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

@@ -9,8 +9,8 @@ import { buildCatalog } from '../lib/catalog.mjs';
 import { resourcePath } from '../lib/resource-path.mjs';
 import { adapterManifest, resolveAdapters } from '../lib/adapters.mjs';
 import { nativePathBoundary } from '../lib/native-paths.mjs';
-import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, mergeManagedContent, stripManagedContent } from '../lib/managed-content.mjs';
-import { mergeTomlContent, stripTomlContent } from '../lib/managed-toml.mjs';
+import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, extractManagedBlock, mergeManagedContent, stripManagedContent } from '../lib/managed-content.mjs';
+import { extractTomlManagedBlock, mergeTomlContent, stripTomlContent } from '../lib/managed-toml.mjs';
 import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, planUntrack, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
 import { stateDirectory } from '../lib/state-path.mjs';
 
@@ -90,7 +90,7 @@ function replaceJsonMember(bytes, member, value) {
 // Compare owned fields structurally, preserving all other JSON bytes.
 function derivedContent(original, previous, next) {
   if (!original) return JSON.stringify(next, null, 2) + '\n';
-  const keys = ['schemaVersion', 'entries', 'outputs', 'files', 'blocks', 'removedBlocks', 'removedFiles'];
+  const keys = ['schemaVersion', 'entries', 'outputs', 'files', 'blocks', 'removedBlocks', 'removedFiles', 'catalogs', 'config'];
   const canonical = value => value && typeof value === 'object' && !Array.isArray(value)
     ? Object.fromEntries(Object.keys(value).sort(compare).map(key => [key, canonical(value[key])]))
     : Array.isArray(value) ? value.map(canonical) : value;
@@ -247,6 +247,11 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   if (previousEntries?.schemaVersion !== 1 || !previousEntries.entries || typeof previousEntries.entries !== 'object' || Array.isArray(previousEntries.entries) || Object.entries(previousEntries.entries).some(([name, hash]) => !canonicalEntrypoint(name) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de entradas derivadas invalido.');
   const previousOutputs = previousEntries.outputs ?? {};
   if (!previousOutputs || typeof previousOutputs !== 'object' || Array.isArray(previousOutputs) || Object.entries(previousOutputs).some(([path, hash]) => !/^\.[A-Za-z0-9][A-Za-z0-9._-]*\/(skills|rules|agents)\.json$/.test(path) || reserved.has(path.split('/')[0].toLowerCase()) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de saidas derivadas invalido.');
+  const previousCatalogs = previousEntries.catalogs ?? {};
+  const catalogPaths = new Set(['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json']);
+  if (!previousCatalogs || typeof previousCatalogs !== 'object' || Array.isArray(previousCatalogs) || Object.entries(previousCatalogs).some(([path, hash]) => !catalogPaths.has(path) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de catalogos derivados invalido.');
+  for (const path of Object.keys(previousCatalogs)) safe(path);
+  if (previousEntries.config !== undefined && (typeof previousEntries.config !== 'string' || !/^[a-f0-9]{64}$/.test(previousEntries.config))) fail('Registro de configuracao derivada invalido.');
   const validResourcePath = path => {
     if (typeof path !== 'string' || !/^\.[A-Za-z0-9][A-Za-z0-9._-]*\/.+/.test(path)) return false;
     const [root, scope] = path.split('/');
@@ -254,7 +259,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       && !['readme.md', 'instructions.md'].includes(posix.basename(path).toLowerCase())
       && (/\.(md|mdc)$/i.test(path) || path.startsWith('.gemini/commands/') && path.endsWith('.toml'));
   };
-  const validIgnoreBlock = path => typeof path === 'string' && /^\.[A-Za-z0-9][A-Za-z0-9._-]*\/\.gitignore$/.test(path) && !reserved.has(path.split('/')[0].toLowerCase());
+  const validIgnoreBlock = path => path === '.pbai4devs/.gitignore' || typeof path === 'string' && /^\.[A-Za-z0-9][A-Za-z0-9._-]*\/\.gitignore$/.test(path) && !reserved.has(path.split('/')[0].toLowerCase());
   for (const [name, values] of [['files', previousEntries.files ?? {}], ['blocks', previousEntries.blocks ?? {}]]) {
     if (!values || typeof values !== 'object' || Array.isArray(values) || Object.entries(values).some(([path, hash]) => !(validResourcePath(path) || name === 'blocks' && (canonicalEntrypoint(path) || validIgnoreBlock(path))) || !/^[a-f0-9]{64}$/.test(hash))) fail(`Registro de ${name} derivados invalido.`);
     for (const path of Object.keys(values)) safe(canonicalEntrypoint(path) ? resolveEntrypoint(root, canonicalEntrypoint(path)) : path);
@@ -475,11 +480,23 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   const registries = new Map();
   const discoveryOutputs = {};
+  const catalogOutputs = {};
   for (const [target, content] of built.outputs) {
     const info = stat(safe(target));
     if (info && !info.isFile()) fail(`Registro nao e arquivo: ${target}`);
     const current = info ? readFileSync(absolute(target)) : null;
     captureInput(target, current);
+    const currentHash = current && createHash('sha256').update(current).digest('hex');
+    const known = current && [installed?.files?.[target], previousCatalogs[target]].some(digest => digest && digest === currentHash);
+    if (current && !known) {
+      // Identical bytes do not establish ownership. An unowned catalogue can
+      // remain if already current, but it cannot be adopted or regenerated.
+      remember(target, 'existing-catalog');
+      if (current.toString('utf8') !== content) { conflicts.add(target); protectedConflicts.add(target); }
+      continue;
+    }
+    const nextHash = createHash('sha256').update(content).digest('hex');
+    if (installed?.files?.[target] !== nextHash) catalogOutputs[target] = nextHash;
     if (!current || current.toString('utf8') !== content) {
       registries.set(target, content);
       if (force && info) backup.add(target);
@@ -533,10 +550,22 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       merged = mergeGitignore(current, patterns);
     }
     catch (error) { fail(`${target}: ${error.message}`); }
-    if (target !== '.pbai4devs/.gitignore') {
-      const start = merged.text.indexOf(ignoreBegin), finish = merged.text.indexOf(ignoreEnd);
-      if (start >= 0 && finish > start) managedBlocks[target] = createHash('sha256').update(merged.text.slice(start, finish + ignoreEnd.length)).digest('hex');
+    if (merged.hasBlock) {
+      const start = current.indexOf(ignoreBegin), finish = current.indexOf(ignoreEnd);
+      const blockHash = start >= 0 && finish > start ? createHash('sha256').update(current.slice(start, finish + ignoreEnd.length)).digest('hex') : null;
+      const fileHash = createHash('sha256').update(current).digest('hex');
+      const known = [installed?.blocks?.[target], previousEntries.blocks?.[target]].some(hash => hash && hash === blockHash)
+        || priorFiles[target] && priorFiles[target] === fileHash;
+      if (!known) {
+        // A marker or identical contents is not proof that this block belongs
+        // to the kit. Do not adopt, replace or remove it even with --force.
+        remember(target, 'existing-ignore-block');
+        if (merged.text !== current) { conflicts.add(target); protectedConflicts.add(target); }
+        continue;
+      }
     }
+    const start = merged.text.indexOf(ignoreBegin), finish = merged.text.indexOf(ignoreEnd);
+    if (start >= 0 && finish > start) managedBlocks[target] = createHash('sha256').update(merged.text.slice(start, finish + ignoreEnd.length)).digest('hex');
     if (merged.text !== current) {
       ignoreFiles.set(target, merged.text);
       if (force && info && merged.hasBlock) backup.add(target);
@@ -568,6 +597,10 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       if (!command) fail(`Comando Gemini exige COMMAND.md: ${source}`);
       const current = mixed ? targetBytes : null;
       const merged = mixed ? mergeTomlContent(current, `@{${source}}`, { expectedHash: priorBlocks[target] }) : null;
+      if (current && !priorBlocks[target] && priorFiles[target] !== createHash('sha256').update(current).digest('hex') && extractTomlManagedBlock(current)) {
+        // An identical block can remain, but its bytes are not ownership proof.
+        remember(target, 'existing-managed-block'); expected.set(target, current); continue;
+      }
       const content = merged ? merged.text : `${tomlMarker}\ndescription = ${JSON.stringify(command.description)}\nprompt = ${JSON.stringify(`@{${source}}\n\n{{args}}`)}\n`;
       if (mixed) { captureInput(target, current); managedBlocks[target] = merged.sha256; remember(target, 'existing-file-extended'); }
       else rememberGenerated(target, content);
@@ -588,6 +621,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const inclusion = ruleInclusion ? `@[origem](${link(target, source)})` : `Leia e siga [origem](${link(target, source)}).`;
     const current = mixed ? targetBytes : null;
     const merged = mixed ? mergeManagedContent(current, inclusion, { expectedHash: priorBlocks[target] }) : null;
+    if (current && !priorBlocks[target] && priorFiles[target] !== createHash('sha256').update(current).digest('hex') && extractManagedBlock(current)) {
+      remember(target, 'existing-managed-block'); expected.set(target, current); continue;
+    }
     const content = merged ? merged.text : `${frontmatter}\n${title}\n\n${marker}\n${inclusion}\n`;
     if (mixed) { captureInput(target, current); managedBlocks[target] = merged.sha256; remember(target, 'existing-file-extended'); }
     else rememberGenerated(target, content);
@@ -644,6 +680,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       const previousBlockHash = priorBlocks[name] ?? Object.entries(priorBlocks).find(([path]) => canonicalEntrypoint(path) === canonical)?.[1];
       if (current && (previousBlockHash || createHash('sha256').update(current).digest('hex') !== previousHash)) {
         const merged = mergeManagedContent(current, entrypointReference(root, canonical), { expectedHash: previousBlockHash });
+        if (!previousBlockHash && previousHash !== createHash('sha256').update(current).digest('hex') && extractManagedBlock(current)) {
+          remember(name, 'existing-managed-block'); continue;
+        }
         captureInput(name, current);
         managedBlocks[name] = merged.sha256;
         rootEntries.set(name, merged.text);
@@ -682,8 +721,20 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     removedBlocks.add(target);
     remember(target, 'existing-file-extended');
   }
+  const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
+  const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
+  const configChanged = !configExists || configText !== finalConfig;
+  const configHash = configExists ? createHash('sha256').update(readFileSync(absolute(config))).digest('hex') : null;
+  const configKnown = configExists && [installed?.files?.[config], previousEntries.config].some(hash => hash && hash === configHash);
+  if (configExists && !configKnown) {
+    remember(config, 'existing-configuration');
+    if (configChanged) { conflicts.add(config); protectedConflicts.add(config); }
+  }
   const next = { schemaVersion: 1, entries: nextEntries };
   if (Object.keys(discoveryOutputs).length) next.outputs = discoveryOutputs;
+  if (Object.keys(catalogOutputs).length) next.catalogs = catalogOutputs;
+  const nextConfigHash = createHash('sha256').update(finalConfig).digest('hex');
+  if ((!configExists || configKnown) && installed?.files?.[config] !== nextConfigHash) next.config = nextConfigHash;
   if (Object.keys(generatedFiles).length) next.files = generatedFiles;
   const derivedBlocks = Object.fromEntries(Object.entries(managedBlocks).filter(([path, hash]) => installed?.blocks?.[path] !== hash || Object.hasOwn(previousEntries.blocks ?? {}, path)));
   if (Object.keys(derivedBlocks).length) next.blocks = derivedBlocks;
@@ -693,7 +744,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   for (const path of remove) if (validResourcePath(path) && installed?.files?.[path] && !expected.has(path)) effectiveRemovedFiles[path] = installed.files[path];
   if (Object.keys(effectiveRemovedFiles).length) next.removedFiles = Object.fromEntries(Object.entries(effectiveRemovedFiles).sort(([a], [b]) => compare(a, b)));
   const registryContent = derivedContent(registryBytes, previousEntries, next);
-  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || Object.keys(effectiveRemovedFiles).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
+  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(catalogOutputs).length || next.config || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || Object.keys(effectiveRemovedFiles).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
   const ownedOutputs = sorted([...targets, ...built.outputs.keys(), '.pbai4devs/espelhos.conf', ...rootEntries.keys(), ...(recordDerivedState && (stat(safe(entryRegistry)) || registries.has(entryRegistry)) ? [entryRegistry] : []),
     ...[...discoveries].flatMap(agent => ['skills', 'rules', 'agents'].map(kind => `${agent}/${kind}.json`)),
     ...[...ignoreTemplates.keys()].filter(target => {
@@ -709,9 +760,6 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const removals = topPaths(remove);
   const backups = topPaths(backup);
   const rootEntryChanges = [...rootEntries].filter(([name, content]) => !stat(absolute(name)) || readFileSync(absolute(name), 'utf8') !== content);
-  const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
-  const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
-  const configChanged = !configExists || configText !== finalConfig;
   // Every planned write/removal may cover a different staged version. Compare
   // the worktree bytes with the index before touching any path, even in force
   // mode, and repeat immediately before applying the transaction.