@pathbit/agentdevkit 0.0.22 → 0.0.23

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/verificar-configuracao/README.md

@@ -0,0 +1,22 @@
+---
+description: Confere os indicadores registrados antes da implementação.
+---
+
+# Verificar configuração
+
+```sh
+node .pbai4devs/scripts/executar-script/SCRIPT.mjs verificar-configuracao
+```
+
+Somente leitura: retorna `1` se o estado estiver ausente, inacessível,
+ambíguo ou com preparação ou configuração pendente. Retorna `0` e
+`verificar-evidencias` quando ambos os indicadores registram `concluido`.
+Para evitar ambiguidades, recusa chaves complexas e tags, âncoras, aliases ou
+mesclagens no topo do cabeçalho. Links simbólicos detectados são recusados;
+a leitura não é uma trava
+atômica contra mudanças simultâneas de caminhos.
+Não valida o YAML inteiro, a infraestrutura ou as provas; confira-os antes de
+escrever código. O comando não bloqueia alterações de quem ignore seu resultado.
+
+O estado legado é reconhecido sem migração; estados em conflito são recusados.
+Erros de uso retornam `2`.

package/.pbai4devs/scripts/verificar-configuracao/SCRIPT.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
+import { stateDirectory } from '../lib/state-path.mjs';
+
+const limit = 'O estado não comprova evidências nem impede um agente de escrever.';
+const blocked = motivo => ({ status: 'bloqueado', motivo, limite: limit });
+
+// Read only the two indicators; never print arbitrary state content.
+export function verifyConfiguration(root = projectRoot) {
+  requireNode();
+  try {
+    root = realpathSync(resolve(root));
+    const parts = `${stateDirectory(root)}/configuracao/ESTADO.md`.split('/');
+    let current = root; let info;
+    for (let index = 0; index < parts.length; index++) {
+      current = join(current, parts[index]);
+      info = lstatSync(current);
+      if (info.isSymbolicLink() || (index < parts.length - 1 && !info.isDirectory())) return blocked('estado-inseguro');
+    }
+    if (!info.isFile() || info.size > 1024 * 1024) return blocked('estado-invalido');
+    const text = readFileSync(current, 'utf8').replaceAll('\r\n', '\n');
+    const header = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1];
+    if (header === undefined) return blocked('estado-invalido');
+    const values = {};
+    for (const line of header.split('\n')) {
+      if (!line.trim() || line.trimStart().startsWith('#') || /^[ \t]/.test(line)) continue;
+      // Explicit mapping keys and merge keys may hide duplicate indicators.
+      if (/^(?:\?|<<\s*:)/.test(line)) return blocked('estado-invalido');
+      const match = line.match(/^("(?:[^"\\]|\\.)*"|'(?:[^']|'')*'|[a-zA-Z_][a-zA-Z0-9_.-]*)[ \t]*:(.*)$/);
+      if (!match) return blocked('estado-invalido');
+      if (/^[!&*]/.test(match[2].trim())) return blocked('estado-invalido');
+      let key = match[1];
+      if (key.startsWith('"')) {
+        try { key = JSON.parse(key); } catch { return blocked('estado-invalido'); }
+      } else if (key.startsWith("'")) key = key.slice(1, -1).replaceAll("''", "'");
+      if (!['preparacao', 'configuracao_tecnica'].includes(key)) continue;
+      if (Object.hasOwn(values, key)) return blocked('estado-invalido');
+      const value = match[2].trim().match(/^(?:concluido|pendente|'(?:concluido|pendente)'|"(?:concluido|pendente)")(?:[ \t]+#.*)?$/)?.[0];
+      if (!value) return blocked('estado-invalido');
+      values[key] = value.replace(/[ \t]+#.*$/, '').replace(/^['"]|['"]$/g, '');
+    }
+    if (!Object.hasOwn(values, 'preparacao') || !Object.hasOwn(values, 'configuracao_tecnica')) return blocked('estado-invalido');
+    if (values.preparacao !== 'concluido' || values.configuracao_tecnica !== 'concluido') return blocked('configuracao-pendente');
+    return { status: 'verificar-evidencias', estado: values, limite: limit };
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return blocked('estado-ausente');
+    return blocked('estado-inacessivel-ou-inseguro');
+  }
+}
+
+export function main(args = process.argv.slice(2)) {
+  if (args.length) throw new Error('Uso: verificar-configuracao sem argumentos.');
+  const report = verifyConfiguration();
+  console.log(JSON.stringify(report));
+  return report.status === 'bloqueado' ? 1 : 0;
+}
+
+if (isMain(import.meta.url)) {
+  try { process.exitCode = main(); }
+  catch (error) { console.error(error.message); process.exitCode = 2; }
+}

package/.pbai4devs/scripts/verificar-configuracao/tests/TEST.mjs

@@ -0,0 +1,145 @@
+import assert from 'node:assert/strict';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { projectRoot } from '../../lib/runtime.mjs';
+import { verifyConfiguration } from '../SCRIPT.mjs';
+
+function fixture(t) {
+  const base = join(projectRoot, '.agent-tests'); mkdirSync(base, { recursive: true });
+  const root = mkdtempSync(join(base, 'config-gate-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const write = (file, content) => {
+    const destination = join(root, file); mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, content);
+  };
+  for (const file of ['lib/runtime.mjs', 'lib/state-path.mjs', 'lib/script-config.mjs', 'executar-script/SCRIPT.mjs', 'verificar-configuracao/SCRIPT.mjs']) {
+    const destination = join(root, '.pbai4devs/scripts', file);
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(join(projectRoot, '.pbai4devs/scripts', file), destination);
+  }
+  const state = (body, folder = 'state') => write(`.pbai4devs/${folder}/configuracao/ESTADO.md`, body);
+  const run = (...args) => {
+    const file = join(root, '.pbai4devs/scripts/verificar-configuracao/SCRIPT.mjs');
+    const result = spawnSync(process.execPath, [file, ...args], { encoding: 'utf8' });
+    assert.ifError(result.error);
+    return { ...result, report: result.stdout ? JSON.parse(result.stdout) : null };
+  };
+  return { root, state, write, run };
+}
+
+const document = (preparation, configuration) => `---\npreparacao: ${preparation}\nconfiguracao_tecnica: ${configuration}\ndocumentos:\n  prd: docs/PRD.md\n---\n\n# Estado\n`;
+
+test('bloqueia antes do código quando o estado está ausente ou pendente', t => {
+  const { root, state, run } = fixture(t);
+  assert.deepEqual(run().report.motivo, 'estado-ausente');
+  assert.equal(run().status, 1);
+  for (const [preparation, configuration] of [['pendente', 'pendente'], ['concluido', 'pendente'], ['pendente', 'concluido']]) {
+    state(document(preparation, configuration));
+    const result = run(); assert.equal(result.status, 1);
+    assert.equal(result.report.motivo, 'configuracao-pendente');
+    assert.equal(existsSync(join(root, 'src')), false);
+  }
+});
+
+test('aceita o modelo real e mantém provas da aplicação como verificação separada', t => {
+  const { root, state, run } = fixture(t);
+  const template = readFileSync(join(projectRoot, '.pbai4devs/templates/configuracao/TEMPLATE.md'), 'utf8');
+  state(template); assert.equal(run().report.motivo, 'configuracao-pendente');
+  state(template.replace('preparacao: pendente', 'preparacao: concluido')
+    .replace('configuracao_tecnica: pendente', 'configuracao_tecnica: concluido'));
+  assert.equal(run().report.status, 'verificar-evidencias');
+  assert.equal(existsSync(join(root, 'src')), false);
+});
+
+test('indicadores concluídos exigem revisão adicional de evidências e não alteram Git', t => {
+  const { root, state, write, run } = fixture(t);
+  state(document('"concluido" # aprovado', "'concluido'"));
+  write('.gitignore', 'node_modules/\n'); write('AGENTS.md', '# Instruções humanas\n');
+  assert.equal(spawnSync('git', ['init', '--quiet', root]).status, 0);
+  assert.equal(spawnSync('git', ['-C', root, 'add', '.gitignore', 'AGENTS.md']).status, 0);
+  const index = readFileSync(join(root, '.git/index'));
+  const statePath = join(root, '.pbai4devs/state/configuracao/ESTADO.md');
+  const original = readFileSync(statePath), ignore = readFileSync(join(root, '.gitignore'));
+  const result = run(); assert.equal(result.status, 0);
+  assert.equal(result.report.status, 'verificar-evidencias');
+  assert.match(result.report.limite, /não comprova evidências/);
+  assert.deepEqual(readFileSync(statePath), original);
+  assert.deepEqual(readFileSync(join(root, '.git/index')), index);
+  assert.deepEqual(readFileSync(join(root, '.gitignore')), ignore);
+  assert.equal(existsSync(join(root, 'src')), false);
+});
+
+test('recusa indicadores ausentes, desconhecidos, duplicados e não expõe valores', t => {
+  const { state, run } = fixture(t);
+  const secret = 'SENSITIVE_VALUE_47849';
+  for (const value of [
+    'preparacao: concluido',
+    'preparacao: concluido\nconfiguracao_tecnica: ausente',
+    'preparacao: concluido\npreparacao: pendente\nconfiguracao_tecnica: concluido',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\n"configuracao_tecnica": pendente',
+    "'preparacao': concluido\npreparacao: pendente\nconfiguracao_tecnica: concluido",
+    'preparacao: concluido\n"prepara\\u0063ao": pendente\nconfiguracao_tecnica: concluido',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\n!!str configuracao_tecnica: pendente',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\npadrao: &base { configuracao_tecnica: pendente }',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\npadrao: *base',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\npadrao: !!str valor',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\n<<: *base',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\n? configuracao_tecnica\n: pendente',
+    `preparacao: concluido\nconfiguracao_tecnica: ${secret}`,
+    'preparacao: concluido\nconfiguracao_tecnica: true',
+  ]) {
+    state(`---\n${value}\n---\n# Estado\n`);
+    const result = run(); assert.equal(result.status, 1);
+    assert.equal(result.report.motivo, 'estado-invalido');
+    assert.ok(!result.stdout.includes(secret)); assert.ok(!result.stderr.includes(secret));
+  }
+  state('preparacao: concluido\nconfiguracao_tecnica: concluido\n');
+  assert.equal(run().report.motivo, 'estado-invalido');
+  state('---\n"preparacao": concluido\n\'configuracao_tecnica\': concluido\n---\n# Estado\n');
+  assert.equal(run().report.status, 'verificar-evidencias');
+});
+
+test('aceita estado legado e recusa coexistência de árvores de estado', t => {
+  const { state, run } = fixture(t);
+  state(document('concluido', 'concluido'), 'estado');
+  assert.equal(run().report.status, 'verificar-evidencias');
+  state(document('concluido', 'concluido'));
+  const result = run(); assert.equal(result.status, 1);
+  assert.equal(result.report.motivo, 'estado-inacessivel-ou-inseguro');
+});
+
+test('não segue link humano em arquivo ou pasta de estado', t => {
+  const { root, state, run } = fixture(t);
+  const outside = join(root, 'fora'); mkdirSync(outside);
+  const target = join(outside, 'ESTADO.md'); writeFileSync(target, document('concluido', 'concluido'));
+  const directory = join(root, '.pbai4devs/state/configuracao'); mkdirSync(directory, { recursive: true });
+  try { symlinkSync(target, join(directory, 'ESTADO.md')); }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOSYS'].includes(error.code)) { t.skip('Sem permissão para links.'); return; } throw error; }
+  assert.equal(run().report.motivo, 'estado-inseguro');
+  assert.equal(readFileSync(target, 'utf8'), document('concluido', 'concluido'));
+  unlinkSync(join(directory, 'ESTADO.md')); rmdirSync(directory);
+  symlinkSync(outside, directory, process.platform === 'win32' ? 'junction' : 'dir');
+  assert.equal(run().report.motivo, 'estado-inseguro');
+  assert.equal(readFileSync(target, 'utf8'), document('concluido', 'concluido'));
+});
+
+test('exige Node e rejeita argumentos extras sem ler outro projeto', t => {
+  const { root, run } = fixture(t);
+  const result = run('--root', root); assert.equal(result.status, 2);
+  assert.match(result.stderr, /sem argumentos/);
+  assert.equal(verifyConfiguration(root).status, 'bloqueado');
+});
+
+test('seletor de scripts propaga bloqueio e exige revisão de evidências', t => {
+  const { root, state } = fixture(t);
+  const selector = join(root, '.pbai4devs/scripts/executar-script/SCRIPT.mjs');
+  const execute = () => spawnSync(process.execPath, [selector, 'verificar-configuracao'], { cwd: root, encoding: 'utf8' });
+  state(document('concluido', 'pendente'));
+  const pending = execute(); assert.ifError(pending.error); assert.equal(pending.status, 1);
+  assert.match(pending.stdout, /"motivo":"configuracao-pendente"/);
+  state(document('concluido', 'concluido'));
+  const recorded = execute(); assert.ifError(recorded.error); assert.equal(recorded.status, 0);
+  assert.match(recorded.stdout, /"status":"verificar-evidencias"/);
+});

package/.pbai4devs/skills/desenvolvimento/implementar-backend/SKILL.md

@@ -5,9 +5,21 @@ description: Implementa mudanças de backend com contratos, dados e provas de co
 
 # Implementar backend
 
-Siga a spec e o plano aprovados, os contratos e a stack existentes. Esclareça
-dúvidas sobre entradas, saídas, persistência,
-compatibilidade e falhas antes de decidir. Altere somente o escopo atribuído.
+Siga o escopo aprovado, os contratos e a stack existentes. Ao implementar uma
+spec, confirme spec e plano aprovados e, antes de alterar código, execute
+`node .pbai4devs/scripts/executar-script/SCRIPT.mjs verificar-configuracao`.
+Se o estado estiver ausente, inválido ou pendente, ou faltar prova obrigatória,
+pare e informe o responsável. Saída zero ainda exige conferir as evidências.
+Siga a ordem e as pré-condições já acordadas em
+[implementar-spec](../../specs/implementar-spec/SKILL.md), sem reiniciar o fluxo
+nem pedir novamente aprovações já dadas.
+
+Em correção avulsa autorizada de projeto existente, preserve suas decisões e
+use `preparar-dev` quando necessário, sem inventar spec ou estado. Uma tarefa
+que cite uma spec ou esteja coberta por seu escopo é tarefa de spec, mesmo
+sendo correção pontual; não a trate como avulsa. Esclareça dúvidas sobre
+entradas, saídas, persistência, compatibilidade e falhas antes de decidir.
+Altere somente o escopo atribuído.
 
 Verifique validação de entrada, autorização por recurso e isolamento de dados.
 Considere limites, concorrência, repetição, timeout, migração e recuperação

package/.pbai4devs/skills/desenvolvimento/implementar-frontend/SKILL.md

@@ -5,9 +5,21 @@ description: Implementa interfaces web conforme a spec, o design e as provas de
 
 # Implementar frontend
 
-Siga a spec e o plano aprovados, o design e os componentes existentes.
-Esclareça comportamento, conteúdo e acessibilidade
-quando faltarem decisões; não escolha framework nem crie telas fora do escopo.
+Siga o escopo aprovado, o design e os componentes existentes. Ao implementar
+uma spec, confirme spec e plano aprovados e, antes de alterar código, execute
+`node .pbai4devs/scripts/executar-script/SCRIPT.mjs verificar-configuracao`.
+Se o estado estiver ausente, inválido ou pendente, ou faltar prova obrigatória,
+pare e informe o responsável. Saída zero ainda exige conferir as evidências.
+Siga a ordem e as pré-condições já acordadas em
+[implementar-spec](../../specs/implementar-spec/SKILL.md), sem reiniciar o fluxo
+nem pedir novamente aprovações já dadas.
+
+Em correção avulsa autorizada de projeto existente, preserve suas decisões e
+use `preparar-dev` quando necessário, sem inventar spec ou estado. Uma tarefa
+que cite uma spec ou esteja coberta por seu escopo é tarefa de spec, mesmo
+sendo correção pontual; não a trate como avulsa. Esclareça comportamento,
+conteúdo e acessibilidade quando faltarem decisões; não escolha framework nem
+crie telas fora do escopo.
 
 Considere estados de carregamento, vazio, erro e sucesso; navegação por teclado,
 semântica acessível e diferentes tamanhos de tela. Preserve contratos com o

package/.pbai4devs/skills/git/git-diff/SKILL.md

@@ -6,4 +6,6 @@ description: Examina e resume alterações Git.
 # git-diff
 
 Examine os diffs preparados e não preparados conforme o pedido, incluindo
-arquivos não rastreados quando relevantes. Não altere arquivos.
+arquivos não rastreados quando relevantes. Execute consultas com
+`GIT_OPTIONAL_LOCKS=0` no ambiente do subprocesso para evitar atualizar o índice;
+não altere arquivos.

package/.pbai4devs/skills/git/git-status/SKILL.md

@@ -6,4 +6,5 @@ description: Inspeciona o estado do repositório e das branches locais e remotas
 # git-status
 
 Mostre branch, alterações preparadas e não preparadas, arquivos não rastreados e
-divergência do upstream. Não altere arquivos.
+divergência do upstream. Execute a consulta com `GIT_OPTIONAL_LOCKS=0` no
+ambiente do subprocesso para evitar atualizar o índice; não altere arquivos.

package/.pbai4devs/skills/projeto/configurar-projeto/SKILL.md

@@ -42,20 +42,25 @@ aprovações já dadas.
 2. Prepare as ferramentas definidas em `.pbai4devs/tools/<nome>/TOOL.json` com
    `preparar-ferramentas`; confira versões e compatibilidade com SO/arquitetura.
    Reutilize instalações e lockfiles; não repita init nem troque a stack.
-3. Aplique a [estrutura e o ambiente obrigatórios][estrutura],
-   preenchendo os modelos de Makefile, Compose e dockerignore. Configure os
-   serviços reais, healthchecks, portas, volumes e comandos da tecnologia.
+3. Aplique a [estrutura e o ambiente obrigatórios][estrutura], preenchendo os
+   modelos de Makefile, Compose e dockerignore. Configure os serviços de
+   infraestrutura necessários, healthchecks, portas, volumes e comandos.
+   Antes de concluir a configuração, não implemente código da aplicação;
+   `src/` e `tests/` podem existir vazios ou conter apenas configuração.
 4. Configure VS Code e recomende EditorConfig, sem regras conflitantes.
    Termine `.gitignore` com o modelo CUSTOM IGNORE e os padrões da tecnologia;
    confirme que templates, scripts, testes e fixtures continuam versionáveis.
 5. Documente versões, estrutura, setup, comandos, origem do template/init e
    decisões no README/estado. Use `atualizar-documentacao` para contribuição,
    configuração e ADRs aplicáveis. Preserve arquivos e convenções existentes.
-6. Use `verificar-trabalho`: valide Compose, build, saúde dos serviços e testes
-   acordados; confira a estrutura com `inspecionar-projeto --check`.
-   Com aplicação, prove o fluxo real no navegador/desktop conforme
-   seu tipo; sem aplicação, registre a prova funcional pendente. Marque
-   `configuracao_tecnica: concluido` somente com evidência da configuração.
+6. Use `verificar-trabalho`: valide runtime, configuração Compose e saúde dos
+   serviços de infraestrutura necessários; confira a estrutura com
+   `inspecionar-projeto --check`. Se Docker ou outra dependência obrigatória
+   estiver inacessível, mantenha a configuração pendente e informe a prova
+   faltante. Sem aplicação, registre build, saúde e fluxo dela como pendentes;
+   não os reporte como aprovados. Com aplicação existente, prove o fluxo real
+   conforme seu tipo. Marque `configuracao_tecnica: concluido` somente com
+   evidência da configuração prévia e dos serviços aplicáveis.
 
 Após alterações técnicas, conclua `revisar-entrega`. Sincronize apontamentos
 somente quando recursos dos agentes forem alterados.

package/.pbai4devs/skills/projeto/proximos-passos/SKILL.md

@@ -17,7 +17,9 @@ Faça apenas as perguntas que impedem avançar.
 Continue o trabalho já autorizado; não reinicie fases concluídas nem apresente
 suposições como aprovações.
 
-Projeto novo segue preparação → PRD → UX/design → configuração → specs →
-implementação → revisão. Projeto existente parte de suas evidências atuais;
+Projeto novo segue preparação → PRD → UX → design (arquitetura e tecnologia) →
+roadmap → spec aprovada → plano aprovado → configuração técnica → implementação
+→ revisão. UX pode ser não aplicável com justificativa aprovada.
+Projeto existente parte de suas evidências atuais;
 instalar o kit não autoriza recriar documentos ou substituir decisões.
 Se não houver pendências no escopo, diga isso claramente.

package/.pbai4devs/skills/specs/implementar-spec/SKILL.md

@@ -18,8 +18,20 @@ antes de implementar.
    seus IDs/revisões. Não invente uma solução já atendida por elas.
 3. Depois da aprovação, crie ou retome `feature/<slug-da-spec>` de `develop`.
    Se faltar `develop`, use `main` quando seguro; sem base/remoto, combine como
-   proceder. Preserve alterações. Registre a aprovação no roadmap e confira a
-   configuração real; complete-a com `configurar-projeto` antes de codificar.
+   proceder. Preserve alterações. Registre a aprovação no roadmap e complete a
+   configuração real com `configurar-projeto` antes de codificar.
+   Antes de qualquer patch de código da spec, execute:
+
+   ```sh
+   node .pbai4devs/scripts/executar-script/SCRIPT.mjs verificar-configuracao
+   ```
+
+   Releia o estado e confira as evidências da infraestrutura obrigatória. Se o
+   estado estiver ausente, inválido ou pendente, ou uma prova falhar, pare sem
+   escrever código; retome quando o impedimento for resolvido. Código zero do
+   script só confirma o estado registrado, não comprova as evidências nem impede
+   escrita por um agente que ignore o resultado. Não peça novamente aprovações
+   já concedidas.
 4. Use o modelo de tarefas em `<documentos.tarefas>/<slug-da-spec>/TASKS.md`.
    Vincule spec/release e registre tarefas, dependências, critérios e evidências.
    Atualize `[ ]`, `[-]` e `[x]` ao avançar; conclusão exige prova. Ao retomar,

package/CHANGELOG.md

@@ -4,6 +4,16 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.23 — 2026-11-13
+
+- Corrige a resolução de destinos inexistentes diretamente sob a raiz.
+- Aceita aliases temporários confiáveis do macOS e recusa destinos que
+  atravessam links humanos, inclusive os indicados por variáveis de ambiente.
+- Orienta roadmap e spec antes da configuração técnica e acrescenta uma
+  verificação do estado antes da implementação.
+- Aplica a verificação também aos especialistas e orienta consultas Git que
+  preservam os bytes do índice.
+
 ## 0.0.22 — 2026-11-13
 
 - Descoberta de skills do Codex sem duplicação, com alternativa segura quando a

package/docs/guides/cli.md

@@ -125,5 +125,14 @@ do kit. Conteúdo humano não é substituído por `--force`.
 
 `doctor` verifica o kit, não o produto inteiro. `next` pode terminar com
 sucesso enquanto orienta uma etapa ainda pendente.
+Após produto e design, ele usa os caminhos de roadmap e specs registrados no
+estado. Para orientar uma spec existente, exige uma única referência aberta
+`[ ]` ou em andamento `[-]` no roadmap. Com mais de uma spec, entrega encerrada,
+vínculo ausente ou leitura ambígua, orienta a revisão do roadmap. Um status
+declarado não comprova aprovação: a skill confere decisões e evidências. Com uma
+spec aberta e declarada aprovada, `implementar-spec` verifica o plano antes de
+encaminhar a configuração técnica; `next` não presume aprovação do plano.
+Se o inventário for truncado, `next` orienta inspeção manual, sem escolher uma
+fase ou presumir que um projeto existente está vazio.
 
 [Wiki](../README.md) · [Solução de problemas](troubleshooting.md)

package/docs/guides/troubleshooting.md

@@ -39,6 +39,10 @@ agente; arquivos próprios também podem manter uma pasta após a desmarcação.
 | `E_MANAGED_BLOCK` | Revise marcadores ou formato; preserve suas instruções. |
 | `E_CHANGED` | Um arquivo mudou durante a operação; gere outro plano. |
 
+No macOS, `/tmp` e `/var/folders` são aceitos quando forem os aliases de
+sistema esperados. Destinos que atravessam links humanos continuam recusados,
+inclusive quando apontados por `TMPDIR`, `TEMP` ou `TMP`.
+
 ## Conflitos e backups
 
 Simule antes de substituir uma alteração própria:

package/docs/specs/README.md

@@ -28,6 +28,9 @@ description: Incrementos verificáveis do AgentDevKit.
 - [Ignore de clientes](client-ignore/SPEC.md): padrão local e exceções do projeto.
 - [Ferramenta e versões](tool-release/SPEC.md): atualização segura e tags de release.
 - [Tags automáticas](automatic-release-tags/SPEC.md): publicação após CI aprovada.
+- [Destinos temporários](target-paths/SPEC.md): caminhos corretos e links seguros.
+- [Ordem antes da implementação](preimplementation-order/SPEC.md): produto,
+  spec e configuração antes do código.
 - [Descoberta e preservação](discovery-preservation/SPEC.md): rotas de skills,
   sincronização segura e validação em projetos reais.
 

package/docs/specs/preimplementation-order/SPEC.md

@@ -0,0 +1,23 @@
+---
+description: Orientação e verificação da ordem anterior à implementação.
+---
+
+# Ordem antes da implementação
+
+O projeto deve partir de decisões de produto e design, passar por roadmap e
+spec e concluir a configuração técnica antes do código da aplicação.
+
+## Critérios de aceite
+
+- AC-001: `next` orienta roadmap e spec antes da configuração técnica e não
+  presume aprovação ou escolhe uma spec ambígua.
+- AC-002: A verificação prévia informa bloqueio se o estado de preparação ou
+  configuração estiver ausente, inválido ou pendente; ela não modifica Git.
+- AC-003: As skills exigem provas da infraestrutura antes de implementar e
+  registram como pendentes as provas de uma aplicação que ainda não existe.
+- AC-004: Projetos existentes, arquivos humanos, links e índice são
+  preservados; testes e revisão cobrem decisões, lacunas e retomada.
+
+O status registrado não comprova a evidência por si só. Instruções e scripts
+não impedem escrita arbitrária por um agente que os ignore; essa proteção
+depende das permissões ou hooks do cliente usado.

package/docs/specs/target-paths/SPEC.md

@@ -0,0 +1,19 @@
+---
+description: Resolução segura dos destinos de instalação.
+---
+
+# Destinos de instalação
+
+O instalador deve manter o caminho solicitado e preservar projetos existentes,
+inclusive quando trabalha com diretórios temporários no macOS.
+
+## Critérios de aceite
+
+- AC-001: Destinos inexistentes preservam todos os nomes e sua ordem,
+  inclusive quando o primeiro componente está diretamente sob a raiz.
+- AC-002: Os aliases temporários de sistema esperados no macOS funcionam para
+  instalação e consulta sem modificar o índice ou o `.gitignore` do projeto.
+- AC-003: Destinos que atravessam links humanos são recusados, inclusive os
+  apontados por variáveis de ambiente; caminhos reservados continuam protegidos.
+- AC-004: Testes de regressão, revisão independente e CI cobrem os cenários
+  pertinentes em Linux, Windows e macOS.

package/package.json

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

package/src/install.mjs

@@ -2,7 +2,7 @@ import { createHash, randomUUID } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, openSync, readFileSync, readSync, writeFileSync, readdirSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { synchronize, isReference } from '../.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
 import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, indexContentMatches } from '../.pbai4devs/scripts/lib/gitignore.mjs';
 import { nativePathBoundary } from '../.pbai4devs/scripts/lib/native-paths.mjs';
@@ -138,12 +138,28 @@ const checkTarget = path => {
   if (path.split(sep).some(part => reservedTargets.has(part.toLowerCase()))) fail('E_TARGET', 'Unsafe target directory.');
 };
 
+// Only normalize macOS aliases owned by the system. Environment-controlled
+// TMPDIR is not evidence that a symbolic link is safe to follow.
+function normalizeSystemTemporaryAlias(target) {
+  if (process.platform !== 'darwin') return target;
+  for (const { alias, allowed, physical } of [
+    { alias: '/tmp', allowed: '/tmp', physical: '/private/tmp' },
+    { alias: '/var', allowed: '/var/folders', physical: '/private/var' },
+  ]) {
+    if (target !== allowed && !target.startsWith(`${allowed}${sep}`)) continue;
+    const link = stat(alias), directory = stat(physical);
+    if (!link?.isSymbolicLink() || link.uid !== 0 || !directory?.isDirectory() || directory.uid !== 0) return target;
+    try { if (realpathSync(alias) !== physical) return target; }
+    catch (error) { if (error.code === 'ENOENT' || error.code === 'ELOOP') return target; throw error; }
+    return join(physical, relative(alias, target));
+  }
+  return target;
+}
+
 export function resolveTarget(input, cwd = process.cwd()) {
   let target = resolve(cwd, input || '.');
   checkTarget(target);
-  // The OS may expose its own temporary directory through a system alias.
-  const temporary = resolve(tmpdir()), insideTemporary = relative(temporary, target);
-  if (insideTemporary === '' || (!insideTemporary.startsWith(`..${sep}`) && insideTemporary !== '..' && !isAbsolute(insideTemporary))) target = join(realpathSync(temporary), insideTemporary);
+  target = normalizeSystemTemporaryAlias(target);
   let ancestor = target;
   while (true) {
     const info = stat(ancestor);
@@ -151,7 +167,7 @@ export function resolveTarget(input, cwd = process.cwd()) {
     const parent = dirname(ancestor); if (parent === ancestor) break; ancestor = parent;
   }
   const missing = []; let parent = target;
-  while (!stat(parent)) { missing.unshift(parent.slice(dirname(parent).length + 1)); parent = dirname(parent); }
+  while (!stat(parent)) { missing.unshift(basename(parent)); parent = dirname(parent); }
   const info = stat(parent);
   if (info.isSymbolicLink() || !info.isDirectory()) fail('E_TARGET', 'Target must be a real directory, without a symbolic link.');
   const canonical = join(realpathSync(parent), ...missing);

package/src/next.mjs

@@ -8,9 +8,11 @@ const messages = {
     install: 'Instale o AgentDevKit neste projeto.', verify: 'Confira a instalação.',
     configure: 'Conclua a preparação inicial.', prepare: 'Prepare o ambiente existente.',
     prd: 'Defina ou conclua o PRD.', ux: 'Defina UX/UI ou justifique sua não aplicação.',
-    design: 'Conclua o design técnico.', technical: 'Conclua a configuração técnica.',
-    spec: 'Defina a próxima spec.', roadmap: 'Revise o roadmap e escolha o próximo incremento.',
+    design: 'Conclua o design técnico.',
+    spec: 'Defina a próxima spec.', implement: 'Planeje a implementação da spec.', roadmap: 'Revise o roadmap e escolha o próximo incremento.',
     inspect: 'Confira o estado do projeto antes de avançar.',
+    incomplete: 'O inventário do projeto está incompleto.',
+    incompleteInstruction: 'Inspecione manualmente a estrutura e os documentos antes de escolher uma etapa; não presuma que o projeto está vazio.',
     ask: 'Use a skill indicada no agente; confirme as decisões ainda pendentes.',
     existing: 'Preserve código e decisões existentes; não reinicie a definição do produto.',
   },
@@ -18,9 +20,11 @@ const messages = {
     install: 'Install AgentDevKit in this project.', verify: 'Check the installation.',
     configure: 'Complete the initial preparation.', prepare: 'Prepare the existing environment.',
     prd: 'Define or complete the PRD.', ux: 'Define UX/UI or document why it does not apply.',
-    design: 'Complete the technical design.', technical: 'Complete the technical configuration.',
-    spec: 'Define the next spec.', roadmap: 'Review the roadmap and select the next increment.',
+    design: 'Complete the technical design.',
+    spec: 'Define the next spec.', implement: 'Plan the spec implementation.', roadmap: 'Review the roadmap and select the next increment.',
     inspect: 'Inspect the project before proceeding.',
+    incomplete: 'The project inventory is incomplete.',
+    incompleteInstruction: 'Inspect the structure and documents manually before choosing a step; do not assume the project is empty.',
     ask: 'Use the indicated skill in your agent; confirm outstanding decisions.',
     existing: 'Preserve existing code and decisions; do not restart product discovery.',
   },
@@ -28,9 +32,11 @@ const messages = {
     install: 'Instale AgentDevKit en este proyecto.', verify: 'Compruebe la instalación.',
     configure: 'Complete la preparación inicial.', prepare: 'Prepare el entorno existente.',
     prd: 'Defina o complete el PRD.', ux: 'Defina UX/UI o justifique que no se aplica.',
-    design: 'Complete el diseño técnico.', technical: 'Complete la configuración técnica.',
-    spec: 'Defina la próxima spec.', roadmap: 'Revise el roadmap y elija el próximo incremento.',
+    design: 'Complete el diseño técnico.',
+    spec: 'Defina la próxima spec.', implement: 'Planifique la implementación de la spec.', roadmap: 'Revise el roadmap y elija el próximo incremento.',
     inspect: 'Inspeccione el proyecto antes de continuar.',
+    incomplete: 'El inventario del proyecto está incompleto.',
+    incompleteInstruction: 'Inspeccione manualmente la estructura y los documentos antes de elegir una etapa; no suponga que el proyecto está vacío.',
     ask: 'Use la skill indicada en su agente y confirme las decisiones pendientes.',
     existing: 'Preserve el código y las decisiones existentes; no reinicie el producto.',
   },
@@ -48,14 +54,21 @@ function commandLine(args, platform) {
 function workflow(report) {
   const state = report.maturity;
   const app = state.signals.application;
+  if (report.scan.truncated) return ['incomplete', null];
   if (app && (!state.configuration.present || !state.planning.ready)) return ['prepare', 'preparar-dev'];
   if (state.configuration.preparacao !== 'concluido') return app ? ['prepare', 'preparar-dev'] : ['configure', 'configurar-projeto'];
   if (state.planning.prd.status !== 'aprovado') return ['prd', 'criar-prd'];
   if (!['aprovado', 'nao-aplicavel'].includes(state.planning.ux_ui.status)) return ['ux', 'criar-ux-ui'];
   if (state.planning.design.status !== 'aprovado') return ['design', 'criar-design-doc'];
-  if (state.configuration.configuracao_tecnica !== 'concluido') return ['technical', 'configurar-projeto'];
-  if (app && !report.contract.complete) return ['prepare', 'preparar-dev'];
-  return state.level === 'manutencao' ? ['roadmap', 'gerenciar-roadmap'] : ['spec', 'criar-spec'];
+  if (state.level === 'manutencao' || !state.releasesComplete) return ['roadmap', 'gerenciar-roadmap'];
+  if (app && state.configuration.configuracao_tecnica === 'concluido' && !report.contract.complete) return ['prepare', 'preparar-dev'];
+  const { roadmap, specs } = state.planning;
+  if (!roadmap?.present || !['planejado', 'aprovado'].includes(roadmap.status) || !specs?.path || !specs.complete || specs.items.length > 1) return ['roadmap', 'gerenciar-roadmap'];
+  if (!specs.items.length) return ['spec', 'criar-spec'];
+  const [spec] = specs.items;
+  if (!spec.linked || !['open', 'in-progress'].includes(spec.roadmapState) || !spec.status) return ['roadmap', 'gerenciar-roadmap'];
+  if (spec.status !== 'aprovado') return ['spec', 'criar-spec'];
+  return ['implement', 'implementar-spec'];
 }
 
 export function getNextSteps({ command, target, language = 'pt', installed, platform = process.platform }) {
@@ -68,6 +81,10 @@ export function getNextSteps({ command, target, language = 'pt', installed, plat
   try { report = inspectProject(target); }
   catch { return [verification]; }
   const [key, skill] = workflow(report);
+  if (key === 'incomplete') {
+    const step = { label: text.incomplete, instruction: text.incompleteInstruction };
+    return ['init', 'update', 'sync', 'lang', 'agents', 'tools'].includes(command) ? [verification, step] : [step];
+  }
   const inspector = join(target, '.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs');
   const step = {
     label: text[key],