@pathbit/agentdevkit 0.0.21 → 0.0.23

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/.pbai4devs/templates/clients/ADAPTERS.json

@@ -79,9 +79,10 @@
       "name": "Codex",
       "root": ".codex",
       "formats": {
-        "skills": "agrupado"
+        "skills": "nenhum"
       },
-      "reason": "Skills agrupadas; a entrada nativa de projeto é .agents/skills. Outros recursos em .codex são referências, não registros de agentes.",
+      "skillFallback": ".agents",
+      "reason": "Skills usam apenas .agents/skills para evitar descoberta duplicada; os demais recursos em .codex são referências.",
       "sources": [
         "https://learn.chatgpt.com/docs/build-skills",
         "https://github.com/openai/codex/blob/392ced7d3a9160fd35d40c606359869215f50522/codex-rs/ext/skills/src/loader/host.rs"

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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
+  rota principal está obstruída.
+- Sincronização e atualização reconciliam o estado sem substituir recursos ou
+  metadados humanos.
+- Scripts reconhecem caminhos por aliases e exemplos de maturidade usam saídas isoladas.
+- Testes ampliados para combinações de clientes, projetos existentes e
+  preservação do Git.
+
 ## 0.0.21 — 2026-11-13
 
 - Criação automática da tag da versão após aprovação da matriz de CI.

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,11 @@ 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.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

package/docs/specs/discovery-preservation/SPEC.md

@@ -0,0 +1,26 @@
+---
+description: Descoberta de skills e preservação em projetos existentes.
+---
+
+# Descoberta e preservação
+
+As integrações devem disponibilizar os recursos sem duplicar skills geradas
+para o Codex e sem substituir configurações ou alterações próprias do projeto.
+
+## Critérios de aceite
+
+- AC-001: O Codex descobre cada skill na rota principal; rotas alternativas
+  são usadas por recurso quando necessário e conflitos são informados.
+- AC-002: `init`, `update` e `sync` preservam conteúdo humano, índice Git e
+  `.gitignore` da raiz; limpeza exige propriedade comprovada.
+- AC-003: A sincronização independente e a atualização reconciliam o estado,
+  preservando campos adicionais e sinalizando inconsistências.
+- AC-004: Scripts identificam sua execução principal por caminhos reais ou
+  aliases, sem executar novamente quando importados.
+- AC-005: Os exemplos de maturidade funcionam também a partir do pacote
+  distribuído, preservando arquivos da origem e exemplos anteriores.
+- AC-006: Testes cobrem combinações de clientes e projetos existentes; resultados,
+  clones e projetos gerados ficam ignorados ou fora do repositório.
+
+Descoberta e validação estrutural não demonstram execução completa de todas as
+skills e perfis em cada cliente. Registre os limites das provas realizadas.

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.21",
+  "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);
@@ -169,6 +185,19 @@ export function safePath(root, path) {
   return current;
 }
 
+// Inspect the route without following user-owned links. A final directory is
+// also unavailable where the generated skill requires a regular file.
+function nativeOutputBoundary(root, path, ownedPaths) {
+  let boundary = nativePathBoundary(root, path, ownedPaths, { preserveRootAliases: true });
+  if (!boundary) {
+    const info = stat(safePath(root, path));
+    if (info && !info.isFile()) boundary = { path, reason: 'non-file' };
+  }
+  if (!boundary) return { blocked: false };
+  const info = lstatSync(join(root, ...boundary.path.split('/')));
+  return { blocked: true, ...boundary, identity: [info.dev, info.ino, info.mode, info.size, info.mtimeMs, info.ctimeMs] };
+}
+
 function resourceAllowed(path, directory = false) {
   const parts = path.split('/');
   const folders = new Set(['agents', 'commands', 'external-skills', 'rules', 'scripts', 'skills', 'templates', 'tools', 'state']);
@@ -388,30 +417,85 @@ function copyResources(source, destination) {
   return files;
 }
 
+// Change only one top-level JSON member. Other fields, escaping and whitespace
+// remain byte-for-byte intact, including user-provided fields in local state.
+function replaceJsonMember(bytes, member, value) {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text, 'utf8').equals(bytes)) fail('E_STATE', 'Invalid UTF-8 in derived state.');
+  let i = 0;
+  const space = () => { while (/\s/.test(text[i] || '') && i < text.length) i++; };
+  const stringEnd = () => {
+    if (text[i++] !== '"') fail('E_STATE', 'Invalid JSON member.');
+    while (i < text.length) {
+      const char = text[i++];
+      if (char === '\\') { i++; continue; }
+      if (char === '"') return;
+    }
+    fail('E_STATE', 'Unterminated JSON string.');
+  };
+  space(); if (text[i++] !== '{') fail('E_STATE', 'Invalid derived state.');
+  const properties = [];
+  while (true) {
+    space(); if (text[i] === '}') break;
+    const start = i; stringEnd(); const key = JSON.parse(text.slice(start, i));
+    space(); if (text[i++] !== ':') fail('E_STATE', 'Invalid JSON member.');
+    space(); const valueStart = i;
+    if (text[i] === '"') stringEnd();
+    else if (text[i] === '{' || text[i] === '[') {
+      const stack = [];
+      do {
+        const char = text[i];
+        if (char === '"') { stringEnd(); continue; }
+        i++;
+        if (char === '{' || char === '[') stack.push(char);
+        else if (char === '}' || char === ']') stack.pop();
+      } while (stack.length && i < text.length);
+      if (stack.length) fail('E_STATE', 'Invalid derived state.');
+    } else { while (i < text.length && text[i] !== ',' && text[i] !== '}') i++; while (i > valueStart && /\s/.test(text[i - 1])) i--; }
+    const end = i; properties.push({ key, start, valueStart, end });
+    space(); if (text[i] === ',') { i++; continue; } if (text[i] === '}') break;
+    fail('E_STATE', 'Invalid JSON member separator.');
+  }
+  const matches = properties.filter(item => item.key === member);
+  if (matches.length !== 1) fail('E_STATE', 'Ambiguous derived state member.');
+  const current = matches[0], index = properties.indexOf(current);
+  let next;
+  if (value !== undefined) next = text.slice(0, current.valueStart) + JSON.stringify(value, null, 2) + text.slice(current.end);
+  else if (index > 0) next = text.slice(0, properties[index - 1].end) + text.slice(current.end);
+  else if (properties.length > 1) next = text.slice(0, current.start) + text.slice(properties[1].start);
+  else next = text.slice(0, current.start) + text.slice(current.end);
+  try { JSON.parse(next); } catch { fail('E_STATE', 'Unable to preserve derived state safely.'); }
+  return Buffer.from(next);
+}
+
 function readDerivedState(target) {
-  let entries = {}, outputs = {}, blocks = {}, files = {}, removedBlocks = [];
+  let entries = {}, outputs = {}, blocks = {}, files = {}, removedBlocks = [], removedFiles = {};
   const derived = read(target, actualStatePath(target).replace(/agentdevkit\.json$/, 'derived.json'));
   if (derived) {
     try {
       const value = JSON.parse(derived);
       if (value.schemaVersion !== 1 || !value.entries || typeof value.entries !== 'object' || Array.isArray(value.entries)
-        || ['outputs', 'blocks', 'files'].some(key => value[key] !== undefined && (!value[key] || typeof value[key] !== 'object' || Array.isArray(value[key])))) fail('E_STATE', 'Invalid derived entrypoint state.');
-      entries = value.entries; outputs = value.outputs ?? {}; blocks = value.blocks ?? {}; files = value.files ?? {};
+        || ['outputs', 'blocks', 'files', 'removedFiles'].some(key => value[key] !== undefined && (!value[key] || typeof value[key] !== 'object' || Array.isArray(value[key])))) fail('E_STATE', 'Invalid derived entrypoint state.');
+      entries = value.entries; outputs = value.outputs ?? {}; blocks = value.blocks ?? {}; files = value.files ?? {}; removedFiles = value.removedFiles ?? {};
       removedBlocks = value.removedBlocks ?? [];
       if (!Array.isArray(removedBlocks) || removedBlocks.some(path => typeof path !== 'string' || !nativeManagedText(path))) fail('E_STATE', 'Invalid removed block state.');
       for (const [path, digest] of Object.entries(entries)) if (!canonicalEntrypoint(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived entrypoint state.');
       for (const [path, digest] of Object.entries(outputs)) if (!allowedManaged(path) || !/^\.[^/]+\/(?:skills|agents|rules)\.json$/.test(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived output state.');
-      for (const [path, digest] of Object.entries(blocks)) if (!nativeManagedText(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived block state.');
+      for (const [path, digest] of Object.entries(blocks)) if (!(nativeManagedText(path) || adapterRoots.some(root => path === `${root}/.gitignore`)) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived block state.');
       for (const [path, digest] of Object.entries(files)) if (!allowedManaged(path) || !/\.(?:md|mdc|toml)$/.test(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived file state.');
+      for (const [path, digest] of Object.entries(removedFiles)) if (canonicalEntrypoint(path) || !(nativeMarkdown(path) || nativeToml(path)) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid removed file state.');
+      const installed = loadState(target);
+      if (Object.entries(removedFiles).some(([path, digest]) => installed?.files?.[path] && installed.files[path] !== digest)) fail('E_STATE', 'Removed file state differs from installation.');
     }
     catch { fail('E_STATE', 'Invalid derived entrypoint state.'); }
-    for (const path of [...Object.keys(entries), ...Object.keys(outputs), ...Object.keys(blocks), ...Object.keys(files), ...removedBlocks]) safePath(target, path);
+    for (const path of [...Object.keys(entries), ...Object.keys(outputs), ...Object.keys(blocks), ...Object.keys(files), ...Object.keys(removedFiles), ...removedBlocks]) safePath(target, path);
   }
-  return { entries, outputs, blocks, files, removedBlocks };
+  return { entries, outputs, blocks, files, removedBlocks, removedFiles };
 }
 
 export function planInstallation({ target, language = 'pt', mode = 'init', force = false, clients }) {
-  const previous = loadState(target);
+  let previous = loadState(target);
+  const installedState = previous;
   const migration = legacyStateMigration(target);
   // A migration must update the installed scripts and pointers in the same
   // transaction; a plain sync/agents/lang would leave old hard-coded paths.
@@ -427,7 +511,8 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (original === null ? content !== null : !content?.equals(original)) fail('E_CHANGED', `File changed while planning: ${path}`);
     } else nativeInputs.set(path, content);
   };
-  const { entries: derivedEntries, outputs: derivedOutputs, blocks: derivedBlocks, files: derivedFiles, removedBlocks } = readDerivedState(target);
+  const { entries: derivedEntries, outputs: derivedOutputs, blocks: derivedBlocks, files: derivedFiles, removedBlocks, removedFiles } = readDerivedState(target);
+  if (previous) previous = { ...previous, files: Object.fromEntries(Object.entries(previous.files).filter(([path, digest]) => removedFiles[path] !== digest)) };
   const previousBlocks = Object.fromEntries(Object.entries(previous?.blocks || {}).filter(([path]) => !removedBlocks.includes(path)));
   const knownBlocks = { ...previousBlocks, ...derivedBlocks };
   const ownedPaths = [...Object.keys(previous?.files || {}), ...Object.keys(previousBlocks), ...Object.keys(derivedEntries), ...Object.keys(derivedOutputs), ...Object.keys(derivedBlocks), ...Object.keys(derivedFiles)];
@@ -436,6 +521,14 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     ?? (canonicalEntrypoint(path) ? Object.entries(knownBlocks).find(([candidate]) => canonicalEntrypoint(candidate) === canonicalEntrypoint(path))?.[1] : undefined);
   const preserved = new Map();
   const recordPreserved = (path, reason) => { preserved.set(path, { path, reason }); return true; };
+  const fallbackChecks = new Map();
+  const outputBlocked = path => {
+    const result = nativeOutputBoundary(target, path, ownedPaths);
+    if (fallbackChecks.has(path) && JSON.stringify(fallbackChecks.get(path)) !== JSON.stringify(result)) fail('E_CHANGED', `Skill route changed while planning: ${path}`);
+    fallbackChecks.set(path, result);
+    if (result.blocked) recordPreserved(result.path, result.reason);
+    return result;
+  };
   const stagedHuman = stagedDivergences(target);
   const native = path => canonicalEntrypoint(path) || path === 'README.md' || adapterRoots.some(root => path === root || path.startsWith(`${root}/`));
   const boundary = path => {
@@ -504,7 +597,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const ownIgnore = read(target, '.pbai4devs/.gitignore');
     if (ownIgnore) write(stage, '.pbai4devs/.gitignore', ownIgnore);
     writeAdapterManifest(stage, { clients: selected });
-    const synchronized = synchronize({ root: stage, force: true, localIgnores: false, generateEntrypoints: false, recordDerivedState: false, output() {} });
+    const synchronized = synchronize({ root: stage, force: true, localIgnores: false, generateEntrypoints: false, recordDerivedState: false, outputBlocked, output() {} });
     for (const canonical of active.entrypoints) {
       const name = entryPaths.get(canonical);
       if (preserveNative(name)) continue;
@@ -577,14 +670,45 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (block) manifest.blocks[path] = block;
       else manifest.files[path] = hash(content);
     }
-    desired.set(statePath, Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`));
+    // A standalone sync records its proven outputs separately. During a later
+    // check/sync, compare that overlay before declaring the installation state
+    // stale; update still consolidates it into the main state transactionally.
+    let stateContent = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+    if (mode === 'sync' && installedState && !changingClients) {
+      const files = { ...installedState.files }, blocks = { ...installedState.blocks };
+      for (const [path, digest] of Object.entries(removedFiles)) {
+        if (files[path] === digest && !stat(safePath(target, path))) delete files[path];
+      }
+      for (const path of removedBlocks) delete blocks[path];
+      for (const [path, digest] of Object.entries({ ...derivedFiles, ...derivedOutputs, ...derivedEntries })) { files[path] = digest; delete blocks[path]; }
+      for (const [path, digest] of Object.entries(derivedBlocks)) { blocks[path] = digest; delete files[path]; }
+      const same = (a, b) => {
+        const keys = Object.keys(a).sort();
+        return keys.length === Object.keys(b).length && keys.every(key => a[key] === b[key]);
+      };
+      if (installedState.schemaVersion === manifest.schemaVersion && installedState.version === manifest.version && installedState.language === manifest.language
+        && JSON.stringify(installedState.clients) === JSON.stringify(manifest.clients) && same(files, manifest.files) && same(blocks, manifest.blocks)) stateContent = read(target, statePath);
+    }
+    desired.set(statePath, stateContent);
+    const derivedPath = actualStatePath(target).replace(/agentdevkit\.json$/, 'derived.json');
+    const derivedBytes = !migration ? read(target, derivedPath) : null;
+    if (derivedBytes && Object.keys(removedFiles).length) {
+      const finalState = JSON.parse(stateContent);
+      const remaining = Object.fromEntries(Object.entries(removedFiles).filter(([path, digest]) =>
+        finalState.files[path] === digest && !stat(safePath(target, path))));
+      if (Object.keys(remaining).length !== Object.keys(removedFiles).length) {
+        observeNative(derivedPath, derivedBytes);
+        desired.set(derivedPath, replaceJsonMember(derivedBytes, 'removedFiles', Object.keys(remaining).length ? remaining : undefined));
+      }
+    }
     const changes = [], conflicts = [];
     const aliasedEntrypoint = path => canonicalEntrypoint(path) && entryPaths.get(canonicalEntrypoint(path)) !== path;
     for (const [path, content] of desired) {
       const current = read(target, path);
       if (nativeInputs.has(path) && (nativeInputs.get(path) === null ? current !== null : !current?.equals(nativeInputs.get(path)))) fail('E_CHANGED', `File changed while planning: ${path}`);
       if (current?.equals(content)) continue;
-      const managed = [previous?.files[path], derivedOutputs[path], derivedEntries[path], derivedFiles[path]].some(digest => digest && hash(current || '') === digest)
+      const managed = path === derivedPath && derivedBytes && current?.equals(derivedBytes)
+        || [previous?.files[path], derivedOutputs[path], derivedEntries[path], derivedFiles[path]].some(digest => digest && hash(current || '') === digest)
         || knownBlocks[path] && blockDigest(path, current || Buffer.alloc(0)) === knownBlocks[path];
       const appendBlock = mixedPaths.has(path) || canonicalEntrypoint(path) || path === '.gitignore' || path.endsWith('/.gitignore');
       const conflict = current && path !== statePath && !managed && !appendBlock;
@@ -704,7 +828,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const localIgnore = planLocalIgnore(target, { outputs: ownedOutputs, templateRoot: stage });
     const localIgnoreCheck = checkLocalIgnore(localIgnore, { replacedBlocks: replacedIgnoreBlocks(target, changes, previous) });
     conflicts.push(...(untrack?.conflicts || []), ...localIgnoreCheck.missing);
-    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck, migration, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
+    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck, migration, fallbackChecks: [...fallbackChecks], fallbackOwnedPaths: ownedPaths, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
   } finally { rmSync(stage, { recursive: true, force: true }); }
 }
 
@@ -712,6 +836,15 @@ export function applyPlan(plan) {
   if (!plan.canApply) fail('E_CONFLICT', text(plan.language, 'conflict'));
   assertLocalIgnoreUnchanged(plan.localIgnore);
   const { target } = plan;
+  const assertFallbackChecks = () => {
+    for (const [path, expected] of plan.fallbackChecks || []) {
+      let current;
+      try { current = nativeOutputBoundary(target, path, plan.fallbackOwnedPaths || []); }
+      catch { fail('E_CHANGED', `Skill route changed after planning: ${path}`); }
+      if (JSON.stringify(current) !== JSON.stringify(expected)) fail('E_CHANGED', `Skill route changed after planning: ${path}`);
+    }
+  };
+  assertFallbackChecks();
   const stagedHuman = stagedDivergences(target);
   const currentState = loadState(target);
   const stagedChanges = plan.changes.filter(change => {
@@ -793,6 +926,7 @@ export function applyPlan(plan) {
         rmdirSync(file); removedDirectories.push({ path: directory.path, mode: directory.mode });
       }
     }
+    assertFallbackChecks();
     pruneRemovedDirectories(plan, directory => removedDirectories.push(directory));
     const changesFallback = plan.changes.some(change => change.path === '.gitignore');
     // Metadata is committed last; its writer rolls back partial writes itself.
@@ -881,6 +1015,10 @@ export function inspect(target) {
   for (const [path, digest] of Object.entries(state.files)) {
     if (derived.blocks[path] || derived.removedBlocks.includes(path)) continue;
     const content = read(target, path);
+    if (derived.removedFiles[path] === digest && !derived.files[path] && !derived.entries[path]) {
+      if (content) issues.push({ code: 'modified', path });
+      continue;
+    }
     if (!content || hash(content) !== digest && hash(content) !== derived.outputs[path] && hash(content) !== derived.files[path] && hash(content) !== derived.entries[path]) issues.push({ code: content ? 'modified' : 'missing', path });
   }
   for (const [path, digest] of Object.entries({ ...state.blocks, ...derived.blocks })) {

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],