@pathbit/agentdevkit 0.0.15 → 0.0.17

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

@@ -6,7 +6,7 @@ description: Cria uma spec de incremento, esclarecendo requisitos e dúvidas com
 # Criar spec
 
 Antes de escrever, aplique o inventário e plano de `atualizar-documentacao`.
-Leia os caminhos em `.pbai4devs/estado/configuracao/ESTADO.md`. Exija PRD/design
+Leia os caminhos em `.pbai4devs/state/configuracao/ESTADO.md`. Exija PRD/design
 aprovados e UX/UI aprovado ou não aplicável com justificativa aprovada.
 Confira evidências, atualidade e decisões essenciais ao incremento; se faltar
 algo, encaminhe à etapa correspondente antes de escrever a spec.

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

@@ -5,7 +5,7 @@ description: Planeja e implementa uma spec aprovada, acompanhando tarefas e crit
 
 # Implementar spec
 
-Leia `.pbai4devs/estado/configuracao/ESTADO.md`. Exija spec, PRD e design aprovados;
+Leia `.pbai4devs/state/configuracao/ESTADO.md`. Exija spec, PRD e design aprovados;
 UX/UI aprovado ou não aplicável com justificativa aprovada. Confira evidências,
 atualidade, decisões essenciais e vínculos com o roadmap; resolva pendências
 antes de implementar.

package/.pbai4devs/templates/entrypoints/AGENTS.md

@@ -15,5 +15,5 @@ cliente em `.pbai4devs/COMPATIBILIDADE.md`.
 
 Use o `README.md` do projeto para seu contexto. Os clientes escolhidos têm
 apontamentos; scripts, ferramentas e modelos permanecem na origem compartilhada.
-Respeite a seleção em `.pbai4devs/estado/agentdevkit.json`. Para alterá-la, use
+Respeite a seleção em `.pbai4devs/state/agentdevkit.json`. Para alterá-la, use
 `agents` na CLI; não deduza o agente ativo pelo aplicativo ou pelas pastas.

package/.pbai4devs/templates/gitignore/local.ignore

@@ -6,5 +6,7 @@
 /.pbai4devs/espelhos.conf
 /.pbai4devs/estado/agentdevkit.json
 /.pbai4devs/estado/derived.json
+/.pbai4devs/state/agentdevkit.json
+/.pbai4devs/state/derived.json
 {{ROOTS}}
 {{OUTPUTS}}

package/.pbai4devs/templates/gitignore/shared.ignore

@@ -6,6 +6,8 @@
 /espelhos.conf
 /estado/agentdevkit.json
 /estado/derived.json
+/state/agentdevkit.json
+/state/derived.json
 
 # Downloads e launchers de ferramentas
 /tools/bin/

package/CHANGELOG.md

@@ -4,6 +4,17 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.17 — 2026-11-13
+
+- A pasta compartilhada de estado passa a se chamar `.pbai4devs/state`.
+- Instalações existentes migram os dados sem alterar o índice ou o ignore.
+
+## 0.0.16 — 2026-11-13
+
+- Testes portáteis distribuídos entre jobs para Windows e macOS.
+- Diagnósticos de subprocessos e espera do CI melhorados para releases.
+- Instruções para recuperar o artefato da tentativa correta do CI.
+
 ## 0.0.15 — 2026-11-13
 
 - Especialistas e skills para arquitetura, backend, frontend, QA e performance.

package/docs/guides/troubleshooting.md

@@ -73,11 +73,19 @@ Os backups são locais e ignorados; não substituem o controle de versão.
 
 ## Estado ou apontamentos inconsistentes
 
+Se a instalação ainda usa `.pbai4devs/estado`, execute `agentdevkit update`
+para migrar os dados e atualizar os scripts juntos. Se `estado` e `state`
+coexistirem, compare e preserve as duas pastas antes de resolver o conflito;
+o kit não escolhe nem sobrescreve uma delas automaticamente.
+Se a configuração apontar para caminhos dentro da pasta antiga, atualize
+esses caminhos para `.pbai4devs/state` antes de tentar novamente. O kit não
+reescreve as decisões do projeto.
+
 `missing`, `modified` e `outdated` em `issues` indicam arquivo ausente,
 conteúdo alterado ou derivação pendente. Use `sync --check` para inspecionar;
 se as alterações da origem forem intencionais, execute `sync` e confira de novo.
 
-Se `.pbai4devs/estado/agentdevkit.json` estiver inválido, recupere um backup
+Se `.pbai4devs/state/agentdevkit.json` estiver inválido, recupere um backup
 local coerente com os arquivos correspondentes. O estado pessoal não é
 versionado. Não invente hashes nem apague o estado para ocultar conflitos;
 peça ao agente para comparar as fontes e planejar o reparo com `init`/`sync`.

package/docs/guides/workflow.md

@@ -56,7 +56,7 @@ Neste momento quero apenas preparar os agentes; não crie produto ou aplicação
 
 Quando o produto começar, combine os caminhos dos documentos no estado de
 configuração. Não presuma que todo projeto usa as mesmas pastas de documentos.
-O registro é `.pbai4devs/estado/configuracao/ESTADO.md`.
+O registro é `.pbai4devs/state/configuracao/ESTADO.md`.
 
 ## 3. Definir produto e experiência
 

package/docs/maintainers/maintenance.md

@@ -19,22 +19,26 @@ Resultados e capturas de verificação permanecem ignorados.
 
 ## Verificar sem desperdiçar CI
 
-O CI tem quatro perfis:
+O CI verifica Linux e distribui a portabilidade em grupos independentes:
 
 | Perfil | Responsabilidade |
 | --- | --- |
 | Linux / Node 24 | Fontes, produto, infraestrutura, lint e pacote real. |
-| Windows / Node 24 | Portabilidade da CLI, arquivos e runtime. |
-| macOS / Node 24 | Portabilidade da CLI, arquivos e runtime. |
+| Windows / Node 24 | CLI, projetos, recursos e layout em jobs separados. |
+| macOS / Node 24 | Os mesmos grupos de portabilidade em jobs separados. |
 | Linux / Node 26 | Smoke de compatibilidade. |
 
 O perfil macOS usa o runner padrão `macos-15-intel`. O label `macos-latest`
 usa ARM64 e pode ter filas diferentes; confira os [runners disponíveis][runners]
 antes de mudar a arquitetura. Provas locais devem informar a arquitetura usada.
 
-A distribuição real é testada uma vez no perfil completo. Os outros perfis
-validam seus riscos específicos. Execuções antigas da mesma referência podem
+A distribuição real é testada uma vez no perfil completo. Todos os grupos de
+Windows e macOS precisam passar para aprovar o CI. Cada grupo tem seu próprio
+log e limite, o que facilita identificar o teste que falhou. Execuções antigas
+da mesma referência podem
 ser canceladas quando substituídas, sem cancelar uma publicação em andamento.
+Novas suítes devem integrar um grupo portátil ou registrar uma justificativa
+explícita para executar somente no perfil completo.
 
 O workflow [Security tools smoke][security-ci] instala os três scanners com
 pins revisados em Linux, macOS e Windows. Depois analisa fixtures locais sem
@@ -81,7 +85,10 @@ Também envia o mesmo pacote ao [npm público e GitHub Packages](packages.md),
 confere a integridade nos dois destinos e testa versão, instalação, diagnóstico
 e sincronização. O consumo pelo npm é anônimo; pelo GitHub, autenticado.
 
-Se o artifact expirou, reexecute o CI original do push e depois a release.
+Se o artifact expirou ou um job do CI falhou, use **Re-run all jobs** no CI
+original do push e aguarde todos os jobs. **Re-run failed jobs** pode manter o
+pacote de uma tentativa anterior, que a release não aceita. Depois reexecute
+a release.
 Uma execução manual de CI serve para diagnóstico, mas não substitui essa
 procedência. Uma release existente não é sobrescrita.
 

package/docs/specs/README.md

@@ -19,6 +19,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [Ecossistema de segurança](security-ecosystem/SPEC.md): fluxos e scanners locais.
 - [Ecossistema de desenvolvimento](development-ecosystem/SPEC.md):
   especialistas, colaboração e provas.
+- [Confiabilidade da pipeline](ci-resilience/SPEC.md): testes e releases.
+- [Pasta de estado](state-directory/SPEC.md): migração segura para `state`.
 - [Integração sem substituição][additive]: acréscimos em arquivos existentes.
 - [Compatibilidade com projetos reais][oss]: projetos públicos e exemplos reproduzíveis.
 - [Ignore do projeto](project-ignore/SPEC.md): preservar o arquivo da raiz.

package/docs/specs/ci-resilience/SPEC.md

@@ -0,0 +1,30 @@
+---
+description: Execução portátil e publicação confiáveis após falhas do CI.
+---
+
+# Confiabilidade da pipeline
+
+As verificações devem identificar a causa das falhas e oferecer margem para
+runners de velocidades diferentes, sem reduzir a cobertura nem liberar um
+pacote antes da aprovação de todos os jobs.
+
+## Critérios de aceite
+
+- AC-001: Os testes portáteis executam em grupos independentes no Windows e
+  no macOS; uma falha em qualquer grupo reprova o CI. O comando local continua
+  executando todos os grupos e as suítes críticas permanecem cobertas.
+- AC-002: Processos de teste e publicação reportam erros e sinais úteis sem
+  expor credenciais. Tempo esgotado continua sendo falha.
+- AC-003: A release aguarda o CI pelo período configurado com margem para a
+  duração e a fila; continua exigindo o artefato do commit e da tentativa
+  aprovados e não aceita CI falho ou de outra origem.
+- AC-004: Linux, Windows e macOS executam as verificações do CI real; os dois
+  registros recebem e verificam o mesmo pacote aprovado, se houver release.
+- AC-005: A documentação explica os perfis e como repetir todos os jobs ao
+  recuperar o artefato de uma tentativa anterior.
+
+## Verificação
+
+Execute testes de regressão dos limites, falhas, grupos e publicação, além do
+perfil completo local. Acompanhe os runners reais e a release até a conclusão;
+registre resultados e revisão independente no gate de entrega.

package/docs/specs/state-directory/SPEC.md

@@ -0,0 +1,22 @@
+---
+description: Nome em inglês para a pasta de estado compartilhado.
+---
+
+# Pasta de estado
+
+A pasta de primeiro nível passa de `.pbai4devs/estado` para
+`.pbai4devs/state`. Ela contém estado de instalação e configuração, não
+memória de conversas. Os nomes internos permanecem iguais.
+
+## Critérios de aceite
+
+- AC-001: Instalações novas usam `state` e recursos, documentação, exclusões
+  e pacote apontam para ela, sem expor estado local no pacote ou no Git.
+- AC-002: A atualização de instalações antigas preserva seleção, idioma,
+  decisões, conteúdo humano e permissões; conflitos e links inseguros não
+  causam perda ou sobrescrita silenciosa.
+- AC-003: Simulação, repetição, falhas e recuperação preservam arquivos,
+  índice Git e `.gitignore` do projeto. Scripts independentes identificam
+  instalações antigas e novas de forma coerente.
+- AC-004: Testes locais, CI em Linux, Windows e macOS e revisão independente
+  verificam o comportamento e os limites da migração.

package/package.json

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

package/src/cli.mjs

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
-import { packageInfo } from './config.mjs';
+import { packageInfo, statePath, legacyStatePath } from './config.mjs';
 import { text, normalizeLanguage, explainError } from './i18n.mjs';
 import { resolveTarget, loadState, planInstallation, applyPlan, inspect } from './install.mjs';
 import { getNextSteps } from './next.mjs';
@@ -169,7 +169,7 @@ export async function main(argv = process.argv.slice(2), context = {}) {
     }
     print(result, options, output); return exitCode;
   } catch (error) {
-    const result = { ok: false, command: options.command || 'help', version: packageInfo.version, language, clients, target, message: explainError(language, error.code), error: { code: error.code || 'E_OPERATION', detail: error.message }, next: getNextSteps({ command: 'error', language, target, installed: existsSync(join(target, '.pbai4devs/estado/agentdevkit.json')) }) };
+    const result = { ok: false, command: options.command || 'help', version: packageInfo.version, language, clients, target, message: explainError(language, error.code), error: { code: error.code || 'E_OPERATION', detail: error.message }, next: getNextSteps({ command: 'error', language, target, installed: existsSync(join(target, statePath)) || existsSync(join(target, legacyStatePath)) }) };
     if (!options.json) result.message += ` (${error.code || 'E_OPERATION'})`;
     print(result, options, output); return error.exitCode || 1;
   }

package/src/config.mjs

@@ -5,7 +5,8 @@ import { fileURLToPath } from 'node:url';
 export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const frameworkRoot = resolve(packageRoot, '.pbai4devs');
 export const packageInfo = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8'));
-export const statePath = '.pbai4devs/estado/agentdevkit.json';
+export const statePath = '.pbai4devs/state/agentdevkit.json';
+export const legacyStatePath = '.pbai4devs/estado/agentdevkit.json';
 export const entryNames = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
 export const begin = '<!-- BEGIN AGENTDEVKIT -->';
 export const end = '<!-- END AGENTDEVKIT -->';

package/src/i18n.mjs

@@ -42,6 +42,21 @@ const messages = {
 };
 export const text = (language, key) => messages[language || 'pt'][key] || key;
 export function explainError(language, code) {
+  if (code === 'E_CONFIG_PARSE') return {
+    pt: 'Não foi possível analisar a configuração legada com segurança; revise o frontmatter e as aspas antes de executar update.',
+    en: 'The legacy configuration could not be safely parsed; review its frontmatter and quoted values before running update.',
+    es: 'No se pudo analizar la configuración anterior de forma segura; revise el frontmatter y las comillas antes de ejecutar update.',
+  }[language || 'pt'];
+  if (code === 'E_LEGACY_PATH') return {
+    pt: 'Ajuste os caminhos .pbai4devs/estado para .pbai4devs/state na configuração antes de executar update.',
+    en: 'Change .pbai4devs/estado paths to .pbai4devs/state in the configuration before running update.',
+    es: 'Cambie las rutas .pbai4devs/estado por .pbai4devs/state en la configuración antes de ejecutar update.',
+  }[language || 'pt'];
+  if (code === 'E_UPGRADE') return {
+    pt: 'Execute agentdevkit update antes de sincronizar ou alterar a configuração legada.',
+    en: 'Run agentdevkit update before syncing or changing the legacy configuration.',
+    es: 'Ejecute agentdevkit update antes de sincronizar o cambiar la configuración anterior.',
+  }[language || 'pt'];
   const value = {
     pt: { E_ARGS: 'Argumentos inválidos; consulte --help.', E_STATE: 'O estado do AgentDevKit está inválido.', E_SYMLINK: 'Um link simbólico impede a operação segura.', E_TARGET: 'Escolha uma pasta real e segura como destino.', E_PATH: 'Um caminho gerenciado é inválido.', E_BLOCK: 'Os marcadores do bloco gerenciado estão inválidos.', E_CHANGED: 'Um arquivo mudou depois do planejamento; execute novamente.', E_TEMPLATE: 'Um template necessário está inválido.' },
     en: { E_ARGS: 'Invalid arguments; see --help.', E_STATE: 'AgentDevKit state is invalid.', E_SYMLINK: 'A symbolic link prevents this operation.', E_TARGET: 'Choose a real, safe target directory.', E_PATH: 'A managed path is invalid.', E_BLOCK: 'Managed block markers are invalid.', E_CHANGED: 'A file changed after planning; try again.', E_TEMPLATE: 'A required template is invalid.' },

package/src/install.mjs

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { chmodSync, existsSync, lstatSync, readFileSync, writeFileSync, readdirSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync, rmdirSync } from 'node:fs';
+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 { synchronize, isReference } from '../.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
@@ -8,7 +8,7 @@ import { nativePathBoundary } from '../.pbai4devs/scripts/lib/native-paths.mjs';
 import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, extractManagedBlock, managedBlockDigest, mergeManagedContent, stripManagedContent } from '../.pbai4devs/scripts/lib/managed-content.mjs';
 import { extractTomlManagedBlock, tomlManagedBlockDigest, mergeTomlContent, stripTomlContent } from '../.pbai4devs/scripts/lib/managed-toml.mjs';
 import { writeAdapterManifest, adapterRoots, normalizeClients, resolveAdapters } from './adapters/index.mjs';
-import { packageRoot, packageInfo, statePath, entryNames, begin, end } from './config.mjs';
+import { packageRoot, packageInfo, statePath, legacyStatePath, entryNames, begin, end } from './config.mjs';
 import { normalizeLanguage, text } from './i18n.mjs';
 
 const hash = value => createHash('sha256').update(value).digest('hex');
@@ -54,11 +54,11 @@ export function safePath(root, path) {
 
 function resourceAllowed(path, directory = false) {
   const parts = path.split('/');
-  const folders = new Set(['agents', 'commands', 'external-skills', 'rules', 'scripts', 'skills', 'templates', 'tools', 'estado']);
+  const folders = new Set(['agents', 'commands', 'external-skills', 'rules', 'scripts', 'skills', 'templates', 'tools', 'state']);
   const files = new Set(['README.md', 'INSTRUCTIONS.md', 'COMPATIBILIDADE.md', 'LICENSE', '.gitignore']);
   if (!folders.has(parts[0]) && !(parts.length === 1 && files.has(parts[0]))) return false;
-  if (parts[0] === 'estado') return directory && parts.length === 1 || path === 'estado/README.md';
-  if (isGeneratedOutput(path, directory) || parts.some(part => ignored.has(part)) || parts[0] === 'adapters' || path === 'estado/agentdevkit.json' || path === '.npmignore') return false;
+  if (parts[0] === 'state') return directory && parts.length === 1 || path === 'state/README.md';
+  if (isGeneratedOutput(path, directory) || parts.some(part => ignored.has(part)) || parts[0] === 'adapters' || path === 'state/agentdevkit.json' || path === '.npmignore') return false;
   if (parts[0] === 'tools') return parts.length === 1 || (directory && parts.length === 2 && !['bin', 'npm-cache'].includes(parts[1])) || (parts.length === 2 && parts[1] === 'README.md') || (parts.length === 3 && ['TOOL.json', 'SCRIPT.mjs', 'README.md'].includes(parts[2]));
   if (parts[0] === 'external-skills') return parts.length === 1 || (parts.length === 2 && ['README.md', 'CATALOG.json'].includes(parts[1]));
   return true;
@@ -109,6 +109,7 @@ function read(root, path) {
 }
 
 function allowedManaged(path) {
+  if (path === '.pbai4devs/estado/README.md') return true;
   if (canonicalEntrypoint(path) || path === '.gitignore') return true;
   if (nativeMarkdown(path) || nativeToml(path)) return true;
   if (['catalog.json', 'skills.json', 'agents.json', 'rules.json', 'espelhos.conf'].some(name => path === `.pbai4devs/${name}`)) return true;
@@ -122,7 +123,7 @@ function nativeMarkdown(path) {
     && adapterRoots.some(root => {
       if (!path.startsWith(`${root}/`)) return false;
       const relative = path.slice(root.length + 1).split('/');
-      return !['tools', 'scripts', 'templates', 'external-skills', 'estado', 'tests', 'docs', 'adapters', 'workflows'].includes(relative[0].toLowerCase())
+      return !['tools', 'scripts', 'templates', 'external-skills', 'estado', 'state', 'tests', 'docs', 'adapters', 'workflows'].includes(relative[0].toLowerCase())
         && !['readme.md', 'instructions.md'].includes(relative.at(-1).toLowerCase());
     });
 }
@@ -130,7 +131,7 @@ const nativeToml = path => path.startsWith('.gemini/commands/') && path.endsWith
 const nativeManagedText = path => nativeMarkdown(path) || nativeToml(path);
 
 export function loadState(root) {
-  const content = read(root, statePath); if (content === null) return null;
+  const content = read(root, actualStatePath(root)); if (content === null) return null;
   let state; try { state = JSON.parse(content); } catch { fail('E_STATE', 'Invalid AgentDevKit state JSON.'); }
   if (state?.schemaVersion !== 1 || !normalizeLanguage(state.language) || typeof state.version !== 'string' || !state.files || typeof state.files !== 'object' || Array.isArray(state.files) || !state.blocks || typeof state.blocks !== 'object' || Array.isArray(state.blocks)) fail('E_STATE', 'Invalid AgentDevKit state.');
   if (state.clients !== undefined) {
@@ -144,6 +145,81 @@ export function loadState(root) {
   return state;
 }
 
+function actualStatePath(root) {
+  const legacy = stat(safePath(root, '.pbai4devs/estado'));
+  const current = stat(safePath(root, '.pbai4devs/state'));
+  if (legacy && !legacy.isDirectory() || current && !current.isDirectory()) fail('E_STATE', 'AgentDevKit state must be a directory.');
+  if (legacy && current) fail('E_STATE', 'Both .pbai4devs/estado and .pbai4devs/state exist; preserve both and resolve the conflict.');
+  return legacy ? legacyStatePath : statePath;
+}
+
+function readLegacyConfiguration(root, path) {
+  const limit = 4 * 1024 * 1024, fd = openSync(safePath(root, path), 'r');
+  try {
+    if (!fstatSync(fd).isFile() || fstatSync(fd).size > limit) fail('E_STATE', 'Legacy configuration is too large or not a regular file.');
+    const buffer = Buffer.allocUnsafe(limit + 1);
+    let total = 0, count;
+    while (total < buffer.length && (count = readSync(fd, buffer, total, buffer.length - total, null)) > 0) total += count;
+    if (total > limit) fail('E_STATE', 'Legacy configuration is too large to inspect safely.');
+    return buffer.subarray(0, total);
+  } finally { closeSync(fd); }
+}
+
+function assertNoLegacyReferences(value) {
+  const legacy = /\.pbai4devs\/estado(?=$|\/|[\s"'\],}:#])/i;
+  const reject = () => fail('E_LEGACY_PATH', 'Replace .pbai4devs/estado references with .pbai4devs/state in the legacy configuration before running update.');
+  if (legacy.test(value)) reject();
+  const normalized = value.replaceAll('\r', '');
+  const header = normalized.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1];
+  if (header === undefined) {
+    if (normalized.startsWith('---')) fail('E_CONFIG_PARSE', 'Legacy configuration has an incomplete frontmatter block.');
+    return;
+  }
+  let documents = false;
+  for (const line of header.split('\n')) {
+    const top = line.match(/^([a-z_]+):\s*(.*)$/);
+    if (top) documents = top[1] === 'documentos';
+    const nested = !top && documents ? line.match(/^  ([a-z_]+):\s*(.*)$/) : null;
+    const raw = (top?.[2] ?? nested?.[2])?.trim();
+    if (!raw?.startsWith('"')) continue;
+    let decoded;
+    try { decoded = JSON.parse(raw); }
+    catch { fail('E_CONFIG_PARSE', 'Legacy configuration contains an ambiguous quoted scalar.'); }
+    if (typeof decoded !== 'string') fail('E_CONFIG_PARSE', 'Legacy configuration contains an invalid quoted scalar.');
+    if (legacy.test(decoded)) reject();
+  }
+}
+
+function legacyStateMigration(root) {
+  if (actualStatePath(root) !== legacyStatePath) return null;
+  const base = '.pbai4devs/estado', files = [], directories = [];
+  const visit = folder => {
+    const info = stat(safePath(root, folder));
+    if (!info?.isDirectory()) fail('E_STATE', `Invalid state directory: ${folder}`);
+    const names = readdirSync(safePath(root, folder)).sort();
+    directories.push({ path: folder, mode: info.mode & 0o777, names });
+    for (const name of names) {
+      const path = `${folder}/${name}`, item = stat(safePath(root, path));
+      if (item?.isDirectory()) visit(path);
+      else if (item?.isFile()) {
+        const configuration = path === `${base}/configuracao/ESTADO.md`;
+        const content = configuration ? readLegacyConfiguration(root, path) : read(root, path);
+        if (configuration) {
+          if (content.includes(0)) fail('E_STATE', 'Legacy configuration contains binary data.');
+          let value;
+          try { value = new TextDecoder('utf-8', { fatal: true }).decode(content); }
+          catch { fail('E_STATE', 'Legacy configuration is not valid UTF-8.'); }
+          assertNoLegacyReferences(value);
+        }
+        files.push({ path, target: path.replace(`${base}/`, '.pbai4devs/state/'), mode: item.mode & 0o777, content });
+      }
+      else fail('E_STATE', `Unsupported state entry: ${path}`);
+    }
+  };
+  visit(base);
+  return { files, directories };
+}
+
 function extractBlock(content, first = begin, last = end) {
   const start = content.indexOf(first), finish = content.indexOf(last);
   if (start < 0 && finish < 0) return null;
@@ -194,7 +270,7 @@ function copyResources(source, destination) {
 
 function readDerivedState(target) {
   let entries = {}, outputs = {}, blocks = {}, files = {}, removedBlocks = [];
-  const derived = read(target, '.pbai4devs/estado/derived.json');
+  const derived = read(target, actualStatePath(target).replace(/agentdevkit\.json$/, 'derived.json'));
   if (derived) {
     try {
       const value = JSON.parse(derived);
@@ -216,6 +292,10 @@ function readDerivedState(target) {
 
 export function planInstallation({ target, language = 'pt', mode = 'init', force = false, clients }) {
   const previous = loadState(target);
+  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.
+  if (migration && !['init', 'update'].includes(mode)) fail('E_UPGRADE', 'Run AgentDevKit update before migrating the legacy state directory.');
   if (mode !== 'init' && !previous) fail('E_MISSING', text(language, 'missing'));
   const selected = normalizeClients(clients ?? previous?.clients ?? ['all']);
   const active = resolveAdapters(selected);
@@ -272,7 +352,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       bundled.push('LICENSE');
     }
     const supplied = new Set(bundled);
-    const internal = new Set(['catalog.json', 'skills.json', 'agents.json', 'rules.json', 'espelhos.conf', '.gitignore', 'estado/README.md']);
+    const internal = new Set(['catalog.json', 'skills.json', 'agents.json', 'rules.json', 'espelhos.conf', '.gitignore', 'state/README.md', 'estado/README.md']);
     if (bundled.length) for (const path of Object.keys(previous?.files || {})) {
       if (path.startsWith('.pbai4devs/') && !supplied.has(path.slice(11)) && !internal.has(path.slice(11))) rmSync(safePath(stage, path), { force: true });
     }
@@ -302,10 +382,32 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       }
     }
     if (!preserveNative('README.md') && !read(target, 'README.md')) write(stage, 'README.md', `---\ndescription: ${JSON.stringify(text(language, 'readme'))}\nlanguage: ${language}\n---\n\n# ${text(language, 'project')}\n\n${text(language, 'readme')}\n`);
-    if (!existsSync(join(stage, '.pbai4devs/estado/README.md'))) write(stage, '.pbai4devs/estado/README.md', `---\ndescription: AgentDevKit state.\n---\n\n# AgentDevKit\n\n${text(language, 'state')}\n`);
+    if (!existsSync(join(stage, '.pbai4devs/state/README.md'))) write(stage, '.pbai4devs/state/README.md', `---\ndescription: AgentDevKit state.\n---\n\n# AgentDevKit\n\n${text(language, 'state')}\n`);
     const unknown = new Set(existing.filter(path => !supplied.has(path) && !previous?.files[`.pbai4devs/${path}`] && !internal.has(path)));
     const paths = walk(stage, '', path => !path.split('/').includes('.agent-tests')).filter(path => !path.startsWith('.pbai4devs/') || !unknown.has(path.slice(11)));
     const desired = new Map(paths.filter(path => !preserveNative(path)).map(path => [path, readFileSync(join(stage, path))]));
+    const migratedHuman = new Set();
+    for (const item of migration?.files || []) {
+      if (item.path === legacyStatePath) continue;
+      if (item.path === '.pbai4devs/estado/README.md') {
+        const managed = previous?.files?.[item.path] === hash(item.content);
+        const matchesTemplate = desired.get(item.target)?.equals(item.content);
+        desired.set(item.target, item.content);
+        if (!managed || !matchesTemplate) { recordPreserved(item.target, 'existing-file'); migratedHuman.add(item.target); }
+        continue;
+      }
+      if (desired.has(item.target)) fail('E_STATE', `State migration collides with a managed file: ${item.target}`);
+      desired.set(item.target, item.content);
+      migratedHuman.add(item.target);
+    }
+    // Preserve human README content; verified managed files may be updated.
+    const stateReadme = '.pbai4devs/state/README.md';
+    const currentStateReadme = read(target, stateReadme);
+    if (currentStateReadme && previous?.files?.[stateReadme] !== hash(currentStateReadme)) {
+      desired.set(stateReadme, currentStateReadme);
+      migratedHuman.add(stateReadme);
+      recordPreserved(stateReadme, 'existing-file');
+    }
     for (const [path, content] of desired) {
       if (!nativeManagedText(path) || canonicalEntrypoint(path)) continue;
       const current = read(target, path);
@@ -330,7 +432,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const manifest = { schemaVersion: 1, version: bundled.length ? packageInfo.version : previous.version, language, files: {}, blocks: {} };
     if (mode !== 'sync' || clients !== undefined || previous?.clients !== undefined) manifest.clients = selected;
     for (const [path, content] of desired) {
-      if (path === 'README.md') continue;
+      if (path === 'README.md' || migratedHuman.has(path)) continue;
       const block = blockDigest(path, content);
       if (block) manifest.blocks[path] = block;
       else manifest.files[path] = hash(content);
@@ -348,10 +450,12 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       const conflict = current && path !== statePath && !managed && !appendBlock;
       const changedBlock = current && knownBlocks[path] && !managed;
       if (conflict || changedBlock) conflicts.push(path);
-      changes.push({ path, action: current ? 'update' : 'create', content, beforeHash: current ? hash(current) : null });
+      const migrated = migration?.files.find(item => item.target === path);
+      changes.push({ path, action: current ? 'update' : 'create', content, beforeHash: current ? hash(current) : null, ...(migrated ? { mode: migrated.mode } : {}) });
     }
     const wholeRecords = [previous?.files || {}, derivedEntries, derivedFiles];
     for (const path of new Set(wholeRecords.flatMap(record => Object.keys(record)))) if (!desired.has(path)) {
+      if (migration && path.startsWith('.pbai4devs/estado/')) continue;
       if (path === '.gitignore') { recordPreserved(path, 'project-owned'); continue; }
       if (aliasedEntrypoint(path)) continue;
       const current = read(target, path); if (!current) continue;
@@ -361,6 +465,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       changes.push({ path, action: 'remove', content: null, beforeHash: hash(current) });
     }
     for (const [recordedPath, digest] of Object.entries(knownBlocks)) {
+      if (migration && recordedPath.startsWith('.pbai4devs/estado/')) continue;
       const path = canonicalEntrypoint(recordedPath) ? entryPaths.get(canonicalEntrypoint(recordedPath)) : recordedPath;
       if (desired.has(path)) continue;
       if (changes.some(change => change.path === path)) continue;
@@ -410,6 +515,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (!known) conflicts.push(legacy);
       changes.push({ path: legacy, action: 'remove', content: null, beforeHash: hash(legacyContent) });
     }
+    for (const item of migration?.files || []) changes.push({ path: item.path, action: 'remove', content: null, beforeHash: hash(item.content) });
     const retiredRoots = adapterRoots.filter(root => !active.roots.includes(root) && changes.some(change => change.action === 'remove' && change.path.startsWith(`${root}/`) && (previous?.files[change.path] || previous?.blocks[change.path])));
     const ownedOutputs = [...new Set([...synchronized.ownedOutputs, ...ownedEntrypoints, statePath])].filter(path => !mixedPaths.has(path) && !overlapsPreserved(path));
     const hashes = {};
@@ -419,12 +525,13 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       const current = read(target, path);
       if (current) { const source = current.toString('utf8'), block = extractBlock(source, '# BEGIN AGENT IGNORE', '# END AGENT IGNORE'); if (block && source.trim() === block.trim() && hash(block) === previous.blocks[path]) hashes[path] = hash(current); }
     }
-    if (previous) hashes[statePath] = hash(read(target, statePath));
+    if (previous && !migration) hashes[statePath] = hash(read(target, statePath));
     const untrack = existsSync(target) ? planUntrack(target, hashes) : null;
+    if (migration && untrack?.paths.length) fail('E_STATE', 'State migration would change the Git index; preserve and resolve tracked outputs first.');
     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, 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, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
   } finally { rmSync(stage, { recursive: true, force: true }); }
 }
 
@@ -432,6 +539,17 @@ export function applyPlan(plan) {
   if (!plan.canApply) fail('E_CONFLICT', text(plan.language, 'conflict'));
   assertLocalIgnoreUnchanged(plan.localIgnore);
   const { target } = plan;
+  if (plan.migration) {
+    if (stat(safePath(target, '.pbai4devs/state'))) fail('E_CHANGED', 'State destination appeared after planning.');
+    for (const directory of plan.migration.directories) {
+      const info = stat(safePath(target, directory.path));
+      if (!info?.isDirectory() || (info.mode & 0o777) !== directory.mode || JSON.stringify(readdirSync(safePath(target, directory.path)).sort()) !== JSON.stringify(directory.names)) fail('E_CHANGED', `State directory changed after planning: ${directory.path}`);
+    }
+    for (const item of plan.migration.files) {
+      const info = stat(safePath(target, item.path));
+      if (!info?.isFile() || (info.mode & 0o777) !== item.mode || hash(readFileSync(safePath(target, item.path))) !== hash(item.content)) fail('E_CHANGED', `State file changed after planning: ${item.path}`);
+    }
+  }
   const backup = `.agent-tests/agentdevkit/backups/${Date.now()}-${randomUUID()}`;
   safePath(target, backup);
   for (const change of plan.changes) safePath(target, change.path);
@@ -457,10 +575,24 @@ export function applyPlan(plan) {
       const content = change.content;
       const signature = { path: change.path, hash: content === null ? null : hash(content) };
       if (content === null) { rmSync(file, { force: true }); applied.push(signature); }
-      else atomicWrite(target, change.path, content, beforeModes.get(change.path), mode => {
+      else atomicWrite(target, change.path, content, beforeModes.get(change.path) ?? change.mode, mode => {
         signature.mode = mode; applied.push(signature);
       }, () => assertOriginal(change.path));
     }
+    if (plan.migration) {
+      for (const directory of plan.migration.directories) {
+        const destination = directory.path.replace(/^\.pbai4devs\/estado/, '.pbai4devs/state');
+        const file = safePath(target, destination), existing = stat(file);
+        if (existing && !existing.isDirectory()) fail('E_CHANGED', `Invalid state destination: ${destination}`);
+        if (!existing) mkdirSync(file, { recursive: true, mode: directory.mode });
+        chmodSync(file, directory.mode);
+      }
+      for (const directory of [...plan.migration.directories].sort((a, b) => b.path.length - a.path.length)) {
+        const file = safePath(target, directory.path), info = stat(file);
+        if (!info?.isDirectory() || readdirSync(file).length) fail('E_CHANGED', `State directory changed during migration: ${directory.path}`);
+        rmdirSync(file); removedDirectories.push({ path: directory.path, mode: directory.mode });
+      }
+    }
     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.
@@ -498,6 +630,11 @@ export function applyPlan(plan) {
         else rollbackErrors.push(failure);
       }
     }
+    if (plan.migration) for (const directory of [...plan.migration.directories].sort((a, b) => b.path.length - a.path.length)) {
+      const destination = directory.path.replace(/^\.pbai4devs\/estado/, '.pbai4devs/state');
+      try { const file = safePath(target, destination); if (stat(file)?.isDirectory() && !readdirSync(file).length) rmdirSync(file); }
+      catch (failure) { if (!['ENOENT', 'ENOTEMPTY', 'EEXIST'].includes(failure.code)) rollbackErrors.push(failure); }
+    }
     if (preserved.length) {
       try { error.rollbackPreservedPaths = preserved; } catch { /* Preserve a exceção original. */ }
     }