@pathbit/agentdevkit 0.0.22 → 0.0.24

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:
@@ -52,9 +56,10 @@ Compare cada `conflicts` com o que deseja manter. Edite a origem em
 recurso. Use `sync` para atualizar suas derivações. `update` reaplica os
 recursos do pacote invocado e pode conflitar com essa personalização.
 
-Quando a substituição for intencional, repita com `--force`. Arquivos
-existentes afetados recebem backup antes da escrita, inclusive em operações
-normais. O campo `backup` informa uma pasta relativa ao projeto:
+`--force` não substitui arquivos próprios nem blocos alterados. Resolva o
+conflito preservando o conteúdo que deseja manter e confira novamente o plano.
+Arquivos gerenciados afetados recebem backup antes da escrita, inclusive em
+operações normais. O campo `backup` informa uma pasta relativa ao projeto:
 
 ```text
 .agent-tests/agentdevkit/backups/<identificador>/
@@ -101,9 +106,10 @@ ou caminhos já gerenciados em links.
 Destinos dentro de `.git`, `node_modules` ou `.pbai4devs` são recusados,
 inclusive com variações de maiúsculas/minúsculas.
 
-Na CLI e no script `sincronizar-agentes`, `--force` repara conflitos gerenciados
-com backup. Recursos nativos humanos e links preservados continuam intactos.
-Para manter a instalação e sua seleção de clientes, prefira a CLI.
+No script `sincronizar-agentes`, `--force` repara conflitos gerenciados com
+backup. A CLI bloqueia conflitos de propriedade mesmo com `--force`. Recursos
+nativos humanos e links preservados continuam intactos. Para manter a instalação
+e sua seleção de clientes, prefira a CLI.
 
 ## Download, plataforma ou ferramenta falhando
 

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.24",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",

package/src/i18n.mjs

@@ -12,7 +12,7 @@ const messages = {
     preserved: 'Caminhos existentes preservados', preservedDetails: 'Use --json para consultar os caminhos e motivos.',
     help: 'AgentDevKit: init [diretório], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <ação>.\nOpções: --target <diretório>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAliases: --clients e clients.',
     clientsCurrent: 'Agentes selecionados', clientsAvailable: 'Agentes disponíveis', clientsSelect: 'Agentes (IDs separados por vírgula ou all) [all]: ', agents: 'Seleção de agentes atualizada.',
-    next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano; --force salva backup antes de substituir.',
+    next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano e resolva os conflitos; --force não substitui conteúdo próprio.',
     healthy: 'Estrutura verificada.', unhealthy: 'A estrutura precisa de ajustes.', missing: 'AgentDevKit ainda não foi inicializado neste diretório.', error: 'Não foi possível concluir a operação.', invalid: 'Argumentos inválidos.', language: 'Idioma atual', version: 'Versão', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Projeto', readme: 'AgentDevKit instalado. Leia AGENTS.md e siga as etapas de produto, design e implementação.', state: 'Estado local do AgentDevKit e configuração compartilhada do projeto.',
     agentLanguage: 'Responda em português, salvo quando o usuário solicitar outro idioma.', inspect: 'Verifique a instalação', workflow: 'Consulte a próxima etapa', install: 'Inicialize este projeto', repair: 'Confira a sincronização', review: 'Revise os arquivos em conflito', tools: 'Resultado da ferramenta',
@@ -23,7 +23,7 @@ const messages = {
     preserved: 'Existing paths preserved', preservedDetails: 'Use --json to inspect paths and reasons.',
     help: 'AgentDevKit: init [directory], update, doctor, sync [--check], lang [pt|en|es], agents [list], next, tools <action>.\nOptions: --target <directory>, --lang <language>, --agents <list>, --yes, --dry-run, --force, --json.\nAliases: --clients and clients.',
     clientsCurrent: 'Selected agents', clientsAvailable: 'Available agents', clientsSelect: 'Agents (comma-separated IDs or all) [all]: ', agents: 'Agent selection updated.',
-    next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review it; --force backs them up before replacement.',
+    next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review and resolve the conflicts; --force does not replace user content.',
     healthy: 'Structure verified.', unhealthy: 'The structure needs attention.', missing: 'AgentDevKit has not been initialized in this directory.', error: 'The operation could not be completed.', invalid: 'Invalid arguments.', language: 'Current language', version: 'Version', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Project', readme: 'AgentDevKit installed. Read AGENTS.md and follow the product, design and implementation stages.', state: 'AgentDevKit state and shared project configuration.',
     agentLanguage: 'Respond in English unless the user requests another language.', inspect: 'Check the installation', workflow: 'Review the next stage', install: 'Initialize this project', repair: 'Check synchronization', review: 'Review conflicting files', tools: 'Tool result',
@@ -34,7 +34,7 @@ const messages = {
     preserved: 'Rutas existentes preservadas', preservedDetails: 'Use --json para consultar las rutas y los motivos.',
     help: 'AgentDevKit: init [directorio], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <acción>.\nOpciones: --target <directorio>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAlias: --clients y clients.',
     clientsCurrent: 'Agentes seleccionados', clientsAvailable: 'Agentes disponibles', clientsSelect: 'Agentes (IDs separados por coma o all) [all]: ', agents: 'Selección de agentes actualizada.',
-    next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise el plan; --force guarda una copia antes de reemplazarlos.',
+    next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise y resuelva los conflictos; --force no reemplaza contenido propio.',
     healthy: 'Estructura verificada.', unhealthy: 'La estructura necesita ajustes.', missing: 'AgentDevKit no se ha inicializado en este directorio.', error: 'No se pudo completar la operación.', invalid: 'Argumentos inválidos.', language: 'Idioma actual', version: 'Versión', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Proyecto', readme: 'AgentDevKit instalado. Lea AGENTS.md y siga las etapas de producto, diseño e implementación.', state: 'Estado de AgentDevKit y configuración compartida del proyecto.',
     agentLanguage: 'Responde en español salvo que el usuario solicite otro idioma.', inspect: 'Compruebe la instalación', workflow: 'Consulte la siguiente etapa', install: 'Inicialice este proyecto', repair: 'Compruebe la sincronización', review: 'Revise los archivos en conflicto', tools: 'Resultado de la herramienta',

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);
@@ -441,7 +457,14 @@ function replaceJsonMember(bytes, member, value) {
     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.');
+  if (matches.length > 1) fail('E_STATE', 'Ambiguous state member.');
+  if (!matches.length) {
+    if (value === undefined) return bytes;
+    const insertion = `${properties.length ? ',' : ''}\n  ${JSON.stringify(member)}: ${JSON.stringify(value, null, 2)}\n`;
+    const next = text.slice(0, i) + insertion + text.slice(i);
+    try { JSON.parse(next); } catch { fail('E_STATE', 'Unable to preserve state safely.'); }
+    return Buffer.from(next);
+  }
   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);
@@ -452,29 +475,44 @@ function replaceJsonMember(bytes, member, value) {
   return Buffer.from(next);
 }
 
+function reconcileStateBytes(original, previous, next) {
+  if (!original) return Buffer.from(`${JSON.stringify(next, null, 2)}\n`);
+  const canonical = value => value && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]))
+    : Array.isArray(value) ? value.map(canonical) : value;
+  let result = original;
+  for (const key of ['schemaVersion', 'version', 'language', 'clients', 'files', 'blocks']) {
+    if (JSON.stringify(canonical(previous?.[key])) !== JSON.stringify(canonical(next[key]))) result = replaceJsonMember(result, key, next[key]);
+  }
+  return result;
+}
+
 function readDerivedState(target) {
-  let entries = {}, outputs = {}, blocks = {}, files = {}, removedBlocks = [], removedFiles = {};
+  let entries = {}, outputs = {}, blocks = {}, files = {}, catalogs = {}, config = null, 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', '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 ?? {};
+        || ['outputs', 'blocks', 'files', 'catalogs', '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 ?? {}; catalogs = value.catalogs ?? {}; removedFiles = value.removedFiles ?? {};
+      if (value.config !== undefined && (typeof value.config !== 'string' || !/^[a-f0-9]{64}$/.test(value.config))) fail('E_STATE', 'Invalid derived configuration state.');
+      config = value.config ?? null;
       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) || 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(blocks)) if (!(nativeManagedText(path) || path === '.pbai4devs/.gitignore' || 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(catalogs)) if (!/^\.pbai4devs\/(?:catalog|skills|agents|rules)\.json$/.test(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived catalogue 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), ...Object.keys(removedFiles), ...removedBlocks]) safePath(target, path);
+    for (const path of [...Object.keys(entries), ...Object.keys(outputs), ...Object.keys(blocks), ...Object.keys(files), ...Object.keys(catalogs), ...Object.keys(removedFiles), ...removedBlocks]) safePath(target, path);
   }
-  return { entries, outputs, blocks, files, removedBlocks, removedFiles };
+  return { entries, outputs, blocks, files, catalogs, config, removedBlocks, removedFiles };
 }
 
 export function planInstallation({ target, language = 'pt', mode = 'init', force = false, clients }) {
@@ -495,11 +533,12 @@ 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, removedFiles } = readDerivedState(target);
+  const { entries: derivedEntries, outputs: derivedOutputs, blocks: derivedBlocks, files: derivedFiles, catalogs: derivedCatalogs, config: derivedConfig, removedBlocks, removedFiles } = readDerivedState(target);
+  const derivedConfigFiles = derivedConfig ? { '.pbai4devs/espelhos.conf': derivedConfig } : {};
   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)];
+  const ownedPaths = [...Object.keys(previous?.files || {}), ...Object.keys(previousBlocks), ...Object.keys(derivedEntries), ...Object.keys(derivedOutputs), ...Object.keys(derivedBlocks), ...Object.keys(derivedFiles), ...Object.keys(derivedCatalogs), ...Object.keys(derivedConfigFiles)];
   const entryPaths = new Map(entryNames.map(name => [name, resolveEntrypoint(target, name)]));
   const blockHash = path => knownBlocks[path]
     ?? (canonicalEntrypoint(path) ? Object.entries(knownBlocks).find(([candidate]) => canonicalEntrypoint(candidate) === canonicalEntrypoint(path))?.[1] : undefined);
@@ -581,7 +620,17 @@ 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, outputBlocked, output() {} });
+    // Supply the already-validated ownership records to the private stage so
+    // the synchronizer can distinguish an owned ignore block from a user's.
+    // These temporary records never replace or bypass checks on the target.
+    const stagingState = '.pbai4devs/state/agentdevkit.json', stagingDerived = '.pbai4devs/state/derived.json';
+    if (previous) write(stage, stagingState, JSON.stringify(previous));
+    if (Object.keys(derivedEntries).length || Object.keys(derivedOutputs).length || Object.keys(derivedBlocks).length || Object.keys(derivedFiles).length || Object.keys(derivedCatalogs).length || derivedConfig || removedBlocks.length || Object.keys(removedFiles).length) {
+      write(stage, stagingDerived, JSON.stringify({ schemaVersion: 1, entries: derivedEntries, outputs: derivedOutputs, blocks: derivedBlocks, files: derivedFiles, catalogs: derivedCatalogs, ...(derivedConfig ? { config: derivedConfig } : {}), removedBlocks, removedFiles }));
+    }
+    let synchronized;
+    try { synchronized = synchronize({ root: stage, force: true, localIgnores: false, generateEntrypoints: false, recordDerivedState: false, outputBlocked, output() {} }); }
+    finally { rmSync(join(stage, stagingState), { force: true }); rmSync(join(stage, stagingDerived), { force: true }); }
     for (const canonical of active.entrypoints) {
       const name = entryPaths.get(canonical);
       if (preserveNative(name)) continue;
@@ -657,14 +706,14 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     // 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`);
+    let stateContent = reconcileStateBytes(installedState ? read(target, actualStatePath(target)) : null, installedState, manifest);
     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({ ...derivedFiles, ...derivedOutputs, ...derivedEntries, ...derivedCatalogs, ...derivedConfigFiles })) { 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();
@@ -676,23 +725,70 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     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) {
+    let nextDerivedBytes = derivedBytes;
+    if (nextDerivedBytes && 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));
+        nextDerivedBytes = replaceJsonMember(nextDerivedBytes, 'removedFiles', Object.keys(remaining).length ? remaining : undefined);
+      }
+    }
+    if (nextDerivedBytes && Object.keys(derivedCatalogs).length) {
+      const finalState = JSON.parse(stateContent);
+      const remaining = Object.fromEntries(Object.entries(derivedCatalogs).filter(([path]) => {
+        const content = desired.get(path);
+        return !content || finalState.files[path] !== hash(content);
+      }));
+      if (Object.keys(remaining).length !== Object.keys(derivedCatalogs).length) {
+        observeNative(derivedPath, derivedBytes);
+        nextDerivedBytes = replaceJsonMember(nextDerivedBytes, 'catalogs', Object.keys(remaining).length ? remaining : undefined);
+      }
+    }
+    if (nextDerivedBytes && Object.keys(derivedBlocks).length) {
+      const finalState = JSON.parse(stateContent);
+      const remaining = Object.fromEntries(Object.entries(derivedBlocks).filter(([path, digest]) => {
+        const content = desired.get(path);
+        // A deselected generated block is removed later in this transaction.
+        // Drop its overlay only if its current bytes are still proven; edited
+        // blocks remain conflicts and no metadata is committed on failure.
+        if (!content && !canonicalEntrypoint(path) && !finalState.blocks[path] && !finalState.files[path]) {
+          const current = read(target, path);
+          return Boolean(current && blockDigest(path, current) !== digest);
+        }
+        return !content || finalState.blocks[path] !== blockDigest(path, content);
+      }));
+      if (Object.keys(remaining).length !== Object.keys(derivedBlocks).length) {
+        observeNative(derivedPath, derivedBytes);
+        nextDerivedBytes = replaceJsonMember(nextDerivedBytes, 'blocks', Object.keys(remaining).length ? remaining : undefined);
       }
     }
+    if (nextDerivedBytes && derivedConfig) {
+      const finalState = JSON.parse(stateContent), path = '.pbai4devs/espelhos.conf', content = desired.get(path);
+      if (content && finalState.files[path] === hash(content)) {
+        observeNative(derivedPath, derivedBytes);
+        nextDerivedBytes = replaceJsonMember(nextDerivedBytes, 'config', undefined);
+      }
+    }
+    if (nextDerivedBytes && !nextDerivedBytes.equals(derivedBytes)) desired.set(derivedPath, nextDerivedBytes);
     const changes = [], conflicts = [];
     const aliasedEntrypoint = path => canonicalEntrypoint(path) && entryPaths.get(canonicalEntrypoint(path)) !== path;
+    const generatedInternal = new Set(['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json', '.pbai4devs/espelhos.conf']);
     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 wholeFileOwned = current && [previous?.files[path], derivedOutputs[path], derivedEntries[path], derivedFiles[path], derivedCatalogs[path], derivedConfigFiles[path]].some(digest => digest && digest === hash(current));
+      const existingBlock = current && (nativeManagedText(path) || canonicalEntrypoint(path) || path.endsWith('/.gitignore')) ? blockDigest(path, current) : null;
+      if (existingBlock && !wholeFileOwned && knownBlocks[path] !== existingBlock) conflicts.push(path);
+      if (current?.equals(content)) {
+        // Identical bytes do not prove ownership of a pre-existing catalogue.
+        // Refuse adoption: a later sync could otherwise overwrite user data.
+        if (!wholeFileOwned && (generatedInternal.has(path) || native(path) && !existingBlock && !mixedPaths.has(path) && !preserved.has(path))) conflicts.push(path);
+        continue;
+      }
       const managed = path === derivedPath && derivedBytes && current?.equals(derivedBytes)
-        || [previous?.files[path], derivedOutputs[path], derivedEntries[path], derivedFiles[path]].some(digest => digest && hash(current || '') === digest)
+        || [previous?.files[path], derivedOutputs[path], derivedEntries[path], derivedFiles[path], derivedCatalogs[path], derivedConfigFiles[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;
@@ -812,7 +908,9 @@ 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, fallbackChecks: [...fallbackChecks], fallbackOwnedPaths: ownedPaths, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
+    // A conflict means ownership or the managed bytes could not be proven.
+    // Backups do not authorize replacing user content, even with --force.
+    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: !conflicts.length && !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 }); }
 }
 
@@ -1003,7 +1101,7 @@ export function inspect(target) {
       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 });
+    if (!content || hash(content) !== digest && hash(content) !== derived.outputs[path] && hash(content) !== derived.files[path] && hash(content) !== derived.entries[path] && hash(content) !== derived.catalogs[path] && !(path === '.pbai4devs/espelhos.conf' && hash(content) === derived.config)) issues.push({ code: content ? 'modified' : 'missing', path });
   }
   for (const [path, digest] of Object.entries({ ...state.blocks, ...derived.blocks })) {
     if (derived.removedBlocks.includes(path) && !Object.hasOwn(derived.blocks, path)) continue;

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