@pathbit/agentdevkit 0.0.16 → 0.0.17

package/.pbai4devs/INSTRUCTIONS.md

@@ -31,7 +31,7 @@ serão preenchidos por perguntas e respostas quando o projeto começar.
 Combine destinos e registre-os no estado futuro de configuração. Ao finalizar
 uma etapa, explique a próxima e reúna suas perguntas. Use
 [proximos-passos](skills/projeto/proximos-passos/SKILL.md) e respeite o idioma
-salvo em `.pbai4devs/estado/agentdevkit.json`; sem escolha, use português.
+salvo em `.pbai4devs/state/agentdevkit.json`; sem escolha, use português.
 Evolua README e documentos pelos [modelos da fase](templates/README.md).
 Atualize fatos e links afetados; registre ausência de impacto com justificativa.
 

package/.pbai4devs/README.md

@@ -11,7 +11,7 @@ O catálogo local `catalog.json` é gerado das fontes pelo sincronizador.
 Ele inclui recursos, ferramentas, automações, modelos e referências externas.
 Os arquivos `skills.json`, `rules.json` e `agents.json` são índices auxiliares
 das fontes. Os clientes selecionados usam seus diretórios de apontamentos.
-O estado `estado/agentdevkit.json` guarda `clients`: `["all"]` ou os IDs
+O estado `state/agentdevkit.json` guarda `clients`: `["all"]` ou os IDs
 escolhidos. Catálogos, manifesto, estado e pastas nativas são derivados locais;
 não devem ser commitados. No repositório do kit, o código do produto fica em
 `src/`, `bin/`, `tests/` e `scripts/release/`, na raiz.

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

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { requireNode, isMain } from '../lib/runtime.mjs';
+import { stateDirectory } from '../lib/state-path.mjs';
 
 const repository = fs.realpathSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..'));
 const defaultAgents = ['.agents', '.agent', '.gemini', '.claude', '.codex', '.cursor', '.github', '.opencode'];
@@ -61,7 +62,7 @@ function metadata(root, file) {
 }
 
 function maturity(root, report) {
-  const stateFile = '.pbai4devs/estado/configuracao/ESTADO.md'; const state = metadata(root, stateFile);
+  const stateFile = `${stateDirectory(root)}/configuracao/ESTADO.md`; const state = metadata(root, stateFile);
   const safeDocument = value => typeof value === 'string' && !path.isAbsolute(value) && !value.includes('\\') && !value.split('/').some(part => !part || ['.', '..', '.git'].includes(part));
   const planning = {};
   for (const name of ['prd', 'ux_ui', 'design']) {
@@ -211,7 +212,7 @@ export function inspectDocumentation(root, limits = {}) {
       else if (found.kind === 'symbolic-link') add(found.boundary, found, role);
     }
   }
-  const declared = metadata(root, '.pbai4devs/estado/configuracao/ESTADO.md').documents;
+  const declared = metadata(root, `${stateDirectory(root)}/configuracao/ESTADO.md`).documents;
   for (const [role, file] of Object.entries(declared)) {
     if (!documentRoles.has(role)) continue;
     if (!safeDocument(file)) { if (file !== null) warn(null, 'invalid-configured-path'); continue; }

package/.pbai4devs/scripts/inspecionar-projeto/tests/TEST.mjs

@@ -111,7 +111,7 @@ test('rejeita origens fora das fixtures e opções desconhecidas', () => {
 
 test('classifica sinais de maturidade sem confundir planejamento com produto funcionando', t => {
   const { directory, file, run } = fixture(t);
-  const state = stage => file('.pbai4devs/estado/configuracao/ESTADO.md', `---\npreparacao: concluido\nconfiguracao_tecnica: ${stage}\ndocumentos:\n  prd: docs/PRD.md\n  ux_ui: docs/UX.md\n  design: docs/DESIGN.md\n  releases: docs/releases\n---\n# Estado\n`);
+  const state = stage => file('.pbai4devs/state/configuracao/ESTADO.md', `---\npreparacao: concluido\nconfiguracao_tecnica: ${stage}\ndocumentos:\n  prd: docs/PRD.md\n  ux_ui: docs/UX.md\n  design: docs/DESIGN.md\n  releases: docs/releases\n---\n# Estado\n`);
   assert.equal(run().report.maturity.level, 'preparacao');
   state('pendente'); file('docs/PRD.md', '---\nstatus: rascunho\n---\n# PRD\n');
   assert.equal(run().report.maturity.level, 'descoberta');
@@ -131,6 +131,20 @@ test('classifica sinais de maturidade sem confundir planejamento com produto fun
   assert.match(result.report.maturity.limits[0], /nao substitui/);
 });
 
+test('inspeção lê decisões legadas e informa conflito entre pastas de estado', t => {
+  const { file, run } = fixture(t);
+  const decisions = '---\npreparacao: concluido\nconfiguracao_tecnica: pendente\n---\n# Estado\n';
+  file('.pbai4devs/estado/configuracao/ESTADO.md', decisions);
+  const legacy = run();
+  assert.equal(legacy.status, 0, legacy.stderr);
+  assert.equal(legacy.report.maturity.configuration.present, true);
+  assert.equal(legacy.report.maturity.configuration.preparacao, 'concluido');
+  file('.pbai4devs/state/configuracao/ESTADO.md', decisions);
+  const conflict = run();
+  assert.equal(conflict.status, 2);
+  assert.match(JSON.parse(conflict.stderr).error, /coexistem/);
+});
+
 test('exemplos e caches Playwright não viram aplicação do projeto real', t => {
   const { file, run } = fixture(t);
   for (const folder of ['examples/generated/a', 'examples/fixture', 'tmp/examples/a', 'TEMP/project', '.PLAYWRIGHT-MCP', 'playwright-results']) {
@@ -154,7 +168,7 @@ test('aceita inspecionar cenário em examples/generated sem liberar outras pasta
 
 test('status arbitrários e referências fora da raiz não expõem dados da configuração', t => {
   const { file, run } = fixture(t); const secret = 'PRIVATE_STATUS_192819';
-  file('.pbai4devs/estado/configuracao/ESTADO.md', `---\npreparacao: ${secret}\nconfiguracao_tecnica: ${secret}\ndocumentos:\n  prd: ../outside.md\n  design: docs/DESIGN.md\n---\n# Estado\n`);
+  file('.pbai4devs/state/configuracao/ESTADO.md', `---\npreparacao: ${secret}\nconfiguracao_tecnica: ${secret}\ndocumentos:\n  prd: ../outside.md\n  design: docs/DESIGN.md\n---\n# Estado\n`);
   file('docs/DESIGN.md', `---\nstatus: ${secret}\n---\n# Design\n`);
   const result = run(); assert.equal(result.status, 0);
   assert.equal(result.report.maturity.planning.prd.path, null);
@@ -199,7 +213,7 @@ test('descobre documentação real sem impor caixa, pasta docs ou frontmatter',
 
 test('caminhos cadastrados têm proveniência sem assumir status ou ler arquivos de configuração', t => {
   const { file, run } = fixture(t);
-  file('.pbai4devs/estado/configuracao/ESTADO.md', '---\ndocumentos:\n  design: architecture/current.md\n  specs: specifications\n  prd: planning/absent.md\n  readme: ../private-secret.md\n  seguranca: .env\n---\n# Estado\n');
+  file('.pbai4devs/state/configuracao/ESTADO.md', '---\ndocumentos:\n  design: architecture/current.md\n  specs: specifications\n  prd: planning/absent.md\n  readme: ../private-secret.md\n  seguranca: .env\n---\n# Estado\n');
   file('architecture/current.md', '# Existing architecture\n');
   file('specifications/current.mdx', '# Increment\n');
   file('.env', 'DO_NOT_EMIT_OR_HASH_THIS_SECRET');
@@ -231,7 +245,7 @@ test('documentos simbólicos permanecem opacos sem ler destinos internos, extern
     if (process.platform !== 'win32' || !['EPERM', 'EACCES'].includes(error.code)) throw error;
     t.skip('Links simbólicos indisponíveis sem permissão do Windows.'); return;
   }
-  file('.pbai4devs/estado/configuracao/ESTADO.md', '---\ndocumentos:\n  design: external/private.md\n---\n# State\n');
+  file('.pbai4devs/state/configuracao/ESTADO.md', '---\ndocumentos:\n  design: external/private.md\n---\n# State\n');
   const result = run();
   assert.equal(result.status, 0, result.stderr);
   const docs = result.report.documentation;

package/.pbai4devs/scripts/lib/README.md

@@ -14,3 +14,6 @@ Texto externo, nomes existentes e metadados humanos permanecem preservados.
 
 `gitignore.mjs` planeja exclusões locais e detecta regras conflitantes. Ele não
 altera o `.gitignore` da raiz; conflitos são informados para revisão humana.
+
+`state-path.mjs` identifica o estado atual ou legado sem dividir dados; duas
+pastas simultâneas ou links simbólicos exigem resolver o conflito antes do uso.

package/.pbai4devs/scripts/lib/state-path.mjs

@@ -0,0 +1,20 @@
+import { lstatSync } from 'node:fs';
+import { join } from 'node:path';
+
+// Preserve legacy installations until the CLI migrates them. Do not silently
+// choose between two independently populated state trees.
+export function stateDirectory(root) {
+  const inspect = relative => {
+    let item;
+    try { item = lstatSync(join(root, relative)); }
+    catch (error) { if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return null; throw error; }
+    if (item.isSymbolicLink()) throw new Error(`Link simbolico: ${relative}`);
+    if (!item.isDirectory()) throw new Error(`Pasta de estado inválida: ${relative}`);
+    return item;
+  };
+  if (!inspect('.pbai4devs')) return '.pbai4devs/state';
+  const current = inspect('.pbai4devs/state');
+  const legacy = inspect('.pbai4devs/estado');
+  if (current && legacy) throw new Error('Pastas .pbai4devs/state e .pbai4devs/estado coexistem; preserve os dados e resolva o conflito antes de continuar.');
+  return legacy ? '.pbai4devs/estado' : '.pbai4devs/state';
+}

package/.pbai4devs/scripts/sincronizar-agentes/README.md

@@ -41,6 +41,6 @@ sem Git, informa que a proteção fica pendente até `git init` e sincronizaçã
 Somente arquivos integralmente gerados são excluídos; pastas de clientes podem
 conter arquivos humanos versionados. Conteúdo próprio não é desindexado pela
 presença de um bloco gerenciado.
-Entradas novas usam os templates; hashes em `estado/derived.json` permitem
+Entradas novas usam os templates; hashes em `state/derived.json` permitem
 atualizar arquivos gerados e blocos separadamente, preservando alterações humanas.
 `--check` também acusa derivados ainda rastreados; não altera o índice.

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

@@ -11,11 +11,12 @@ import { nativePathBoundary } from '../lib/native-paths.mjs';
 import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, mergeManagedContent, stripManagedContent } from '../lib/managed-content.mjs';
 import { mergeTomlContent, stripTomlContent } from '../lib/managed-toml.mjs';
 import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
+import { stateDirectory } from '../lib/state-path.mjs';
 
 const marker = '<!-- gerado: sincronizar-agentes -->';
 const tomlMarker = '# gerado: sincronizar-agentes';
 const principals = { skills: 'SKILL.md', agents: 'AGENT.md', commands: 'COMMAND.md', rules: 'RULE.md' };
-const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'estado', 'tests', 'docs', 'adapters'];
+const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'state', 'estado', 'tests', 'docs', 'adapters'];
 const reserved = new Set(['.git', '.pbai4devs', '.agent-tests']);
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const sorted = values => [...new Set(values)].sort(compare);
@@ -140,11 +141,12 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const config = '.pbai4devs/espelhos.conf';
   const configExists = stat(safe(config));
   captureInput(config, configExists ? readFileSync(absolute(config)) : null);
-  const stateFile = '.pbai4devs/estado/agentdevkit.json';
+  const stateRoot = stateDirectory(root);
+  const stateFile = `${stateRoot}/agentdevkit.json`;
   const installed = stat(safe(stateFile)) ? JSON.parse(read(safe(stateFile))) : null;
   const configText = configExists ? read(safe(config)) : adapterManifest(root, { clients: installed?.clients });
   const rows = configText.split('\n');
-  const entryRegistry = '.pbai4devs/estado/derived.json';
+  const entryRegistry = `${stateRoot}/derived.json`;
   const registryBytes = stat(safe(entryRegistry)) ? readFileSync(absolute(entryRegistry)) : null;
   captureInput(entryRegistry, registryBytes);
   const previousEntries = registryBytes ? JSON.parse(registryBytes.toString('utf8')) : { schemaVersion: 1, entries: {} };

package/.pbai4devs/scripts/sincronizar-agentes/tests/COEXISTENCE.mjs

@@ -95,8 +95,8 @@ test('link em caminho registrado continua sendo erro antes de qualquer escrita',
   for (const source of ['files', 'blocks', 'derived', 'outputs']) {
     const root = fixture(t), path = source === 'derived' ? 'CLAUDE.md' : source === 'outputs' ? '.agents/skills.json' : '.claude/skills/demo/SKILL.md';
     if (!link(t, root, 'missing', path)) return;
-    if (source === 'derived' || source === 'outputs') put(root, '.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: source === 'derived' ? { [path]: 'a'.repeat(64) } : {}, ...(source === 'outputs' ? { outputs: { [path]: 'a'.repeat(64) } } : {}) }));
-    else put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: source === 'files' ? { [path]: 'a'.repeat(64) } : {}, blocks: source === 'blocks' ? { [path]: 'a'.repeat(64) } : {} }));
+    if (source === 'derived' || source === 'outputs') put(root, '.pbai4devs/state/derived.json', JSON.stringify({ schemaVersion: 1, entries: source === 'derived' ? { [path]: 'a'.repeat(64) } : {}, ...(source === 'outputs' ? { outputs: { [path]: 'a'.repeat(64) } } : {}) }));
+    else put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: source === 'files' ? { [path]: 'a'.repeat(64) } : {}, blocks: source === 'blocks' ? { [path]: 'a'.repeat(64) } : {} }));
     const before = snapshot(root);
     assert.throws(() => run(root, { force: true }), /Link simbolico em caminho gerenciado/);
     assert.deepEqual(snapshot(root), before);
@@ -106,7 +106,7 @@ test('link em caminho registrado continua sendo erro antes de qualquer escrita',
 test('manifesto standalone editado pelo usuário passa a ser preservado', t => {
   const root = fixture(t); run(root);
   const path = '.agents/skills.json', original = fs.readFileSync(join(root, path), 'utf8');
-  const derived = JSON.parse(fs.readFileSync(join(root, '.pbai4devs/estado/derived.json')));
+  const derived = JSON.parse(fs.readFileSync(join(root, '.pbai4devs/state/derived.json')));
   assert.equal(derived.outputs[path], hash(original));
   put(root, path, '{"entries":[{"path":".agents/skills/custom"}]}\n');
   const result = run(root, { force: true });
@@ -151,7 +151,7 @@ test('tipo alterado em caminho nativo registrado continua recusado antes de grav
   ]) {
     const root = fixture(t);
     if (path === '.codex') put(root, path, 'Human root\n'); else put(root, `${path}/keep.txt`, 'Human directory\n');
-    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
+    put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
     const before = snapshot(root);
     assert.throws(() => run(root, { force: true }), /caminho gerenciado/);
     assert.deepEqual(snapshot(root), before);
@@ -191,7 +191,7 @@ test('variante única de entrada registrada conserva conteúdo como arquivo mist
   for (const owned of ['AGENTS.md', 'agents.md']) {
     const root = fixture(t); put(root, 'agents.md', '# Renamed human entry\n');
     assert.throws(() => nativePathBoundary(root, 'AGENTS.md', [owned], { preserveRootAliases: true }), /maiusculas\/minusculas/);
-    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
+    put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [owned]: 'a'.repeat(64) }, blocks: {} }));
     run(root, { force: true });
     assert.ok(fs.readFileSync(join(root, 'agents.md'), 'utf8').startsWith('# Renamed human entry\n'));
     assert.ok(!fs.readdirSync(root).includes('AGENTS.md'));

package/.pbai4devs/scripts/sincronizar-agentes/tests/HUMAN_OWNERSHIP.mjs

@@ -64,7 +64,7 @@ test('texto humano com formato de referência nunca comprova propriedade', t =>
 test('hash registrado comprova referência legada sem marcador e diretório vazio humano permanece', t => {
   const root = fixture(t), stale = '.claude/skills/legacy.md';
   write(root, stale, human);
-  write(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: { [stale]: hash(human) }, blocks: {} }));
+  write(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: { [stale]: hash(human) }, blocks: {} }));
   fs.mkdirSync(join(root, '.claude/skills/user-empty'), { recursive: true });
   run(root);
   assert.equal(fs.existsSync(join(root, stale)), false);

package/.pbai4devs/scripts/sincronizar-agentes/tests/MANAGED_CONTENT.mjs

@@ -38,7 +38,7 @@ test('sync complementa Markdown humano, preserva CRLF/metadados e acompanha só
   assert.equal(fs.statSync(join(root, path)).mode & 0o777, mode);
   assert.equal(result.managedBlocks[path], managedBlockDigest(actual));
   assert.ok(!result.ownedOutputs.includes(path));
-  const state = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  const state = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
   assert.equal(state.blocks[path], managedBlockDigest(actual));
   assert.equal(state.files[path], undefined);
   assert.equal(run(root, { check: true }).exitCode, 0);
@@ -84,7 +84,7 @@ test('remover recurso ou cliente retira somente bloco próprio de Markdown misto
     run(root);
     assert.equal(read(root, path), outside);
     assert.ok(read(root, path).startsWith(human));
-    assert.equal(JSON.parse(read(root, '.pbai4devs/estado/derived.json')).blocks?.[path], undefined);
+    assert.equal(JSON.parse(read(root, '.pbai4devs/state/derived.json')).blocks?.[path], undefined);
     assert.equal(run(root, { check: true }).exitCode, 0);
   }
 });
@@ -130,10 +130,10 @@ test('retirada standalone registra tombstone para bloco do estado instalado', t
   const root = fixture(t), path = '.claude/skills/demo/SKILL.md';
   put(root, path, '# Human\n'); run(root);
   const block = managedBlockDigest(read(root, path));
-  put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { [path]: block } }));
+  put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { [path]: block } }));
   fs.rmSync(join(root, '.pbai4devs/skills/old/demo'), { recursive: true });
   run(root);
-  const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  const derived = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
   assert.ok(derived.removedBlocks.includes(path));
   assert.equal(extractManagedBlock(read(root, path)), null);
   assert.equal(run(root, { check: true }).exitCode, 0);
@@ -143,7 +143,7 @@ test('stage pode gerar referências sem gravar estado derivado', t => {
   const root = fixture(t);
   run(root, { generateEntrypoints: false, recordDerivedState: false });
   assert.ok(fs.existsSync(join(root, '.claude/skills/demo/SKILL.md')));
-  assert.ok(!fs.existsSync(join(root, '.pbai4devs/estado/derived.json')));
+  assert.ok(!fs.existsSync(join(root, '.pbai4devs/state/derived.json')));
 });
 
 test('regra Cursor mantém globs e modo humanos ao receber referência', t => {
@@ -292,10 +292,10 @@ test('arquivo misto removido é recriado sem conservar propriedade do bloco ause
     const root = fixture(t);
     put(root, path, '# Humano\n'); run(root);
     const hash = managedBlockDigest(read(root, path));
-    put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: {}, blocks: { [path]: hash } }));
+    put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: {}, blocks: { [path]: hash } }));
     fs.rmSync(join(root, path));
     run(root);
-    const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+    const derived = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
     assert.ok(derived.removedBlocks.includes(path));
     assert.ok(derived.files?.[path] || derived.entries?.[path]);
     assert.equal(extractManagedBlock(read(root, path)), null);
@@ -307,10 +307,10 @@ test('renomear caixa de entrada mista transfere só a propriedade do bloco', t =
   const root = fixture(t), before = '# Humano\n';
   put(root, 'AGENTS.md', before); run(root);
   const hash = managedBlockDigest(read(root, 'AGENTS.md'));
-  put(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { 'AGENTS.md': hash } }));
+  put(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: {}, blocks: { 'AGENTS.md': hash } }));
   fs.renameSync(join(root, 'AGENTS.md'), join(root, 'agents.md'));
   const result = run(root);
-  const derived = JSON.parse(read(root, '.pbai4devs/estado/derived.json'));
+  const derived = JSON.parse(read(root, '.pbai4devs/state/derived.json'));
   assert.ok(read(root, 'agents.md').startsWith(before));
   assert.ok(derived.removedBlocks.includes('AGENTS.md'));
   assert.equal(derived.blocks['agents.md'], result.managedBlocks['agents.md']);

package/.pbai4devs/scripts/sincronizar-agentes/tests/TEST.mjs

@@ -14,6 +14,7 @@ import './HUMAN_OWNERSHIP.mjs';
 import './COEXISTENCE.mjs';
 import './MANAGED_CONTENT.mjs';
 import { validateCatalog as validateExternalCatalog } from '../../gerenciar-skills-externas/SCRIPT.mjs';
+import { stateDirectory } from '../../lib/state-path.mjs';
 
 const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
 const cli = resolve(dirname(fileURLToPath(import.meta.url)), '../SCRIPT.mjs');
@@ -24,7 +25,7 @@ const read = (root, path) => readFileSync(join(root, path), 'utf8');
 const write = (root, path, content) => { mkdirSync(dirname(join(root, path)), { recursive: true }); writeFileSync(join(root, path), content); };
 const pointer = (origin = 'origem.md', title = 'Referencia') => `---\ndescription: Referencia.\n---\n\n# ${title}\n\n${marker}\nLeia e siga [origem](${origin}).\n`;
 const recordOwned = (root, paths) => {
-  const statePath = '.pbai4devs/estado/agentdevkit.json';
+  const statePath = '.pbai4devs/state/agentdevkit.json';
   const previous = existsSync(join(root, statePath)) ? JSON.parse(read(root, statePath)) : {};
   write(root, statePath, JSON.stringify({ schemaVersion: 1, files: { ...previous.files, ...Object.fromEntries(paths.map(path => [path, createHash('sha256').update(readFileSync(join(root, path))).digest('hex')])) }, blocks: previous.blocks ?? {} }));
 };
@@ -75,7 +76,7 @@ function fixture(t, minimal = false) {
   write(root, '.github/prompts/custom.prompt.md', '# Prompt proprio\n');
   write(root, '.claude/notas.md', '# Nota propria\n');
   write(root, 'README.md', 'README raiz preservado\n');
-  for (const kind of ['templates', 'scripts', 'tools', 'external-skills', 'estado', 'tests', 'docs', 'adapters', 'extra']) {
+  for (const kind of ['templates', 'scripts', 'tools', 'external-skills', 'state', 'tests', 'docs', 'adapters', 'extra']) {
     write(root, `.pbai4devs/${kind}/demo/REFERENCE.md`, '---\ndescription: Exclusivo.\n---\n\n# Exclusivo\n');
     if (kind !== 'extra') {
       const target = `.claude/${kind}/demo/REFERENCE.md`;
@@ -92,6 +93,30 @@ function fixture(t, minimal = false) {
   recordOwned(root, ownedLegacy);
   return root;
 }
+
+test('sincronização direta conserva estado legado e recusa duas pastas de estado', t => {
+  const root = fixture(t, true);
+  write(root, source, skill);
+  write(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({
+    schemaVersion: 1, clients: ['codex'], files: {}, blocks: {},
+  }));
+  assert.equal(run(root).exitCode, 0);
+  assert.equal(existsSync(join(root, '.pbai4devs/estado/derived.json')), true);
+  assert.equal(existsSync(join(root, '.pbai4devs/state')), false);
+  write(root, '.pbai4devs/state/configuracao/ESTADO.md', '# Decisões próprias\n');
+  const before = snapshot(root);
+  assert.throws(() => run(root), /coexistem/);
+  assert.deepEqual(snapshot(root), before);
+});
+
+test('detecção de estado recusa link simbólico sem abrir o destino', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t, true);
+  const external = join(root, 'externo');
+  mkdirSync(external);
+  symlinkSync(external, join(root, '.pbai4devs/estado'), 'dir');
+  assert.throws(() => stateDirectory(root), /Link simbolico/);
+  assert.equal(existsSync(join(root, '.pbai4devs/state')), false);
+});
 function rejected(root, options = {}, pattern) {
   const before = snapshot(root);
   assert.throws(() => run(root, options), pattern);
@@ -115,7 +140,7 @@ test('sincroniza somente principais, preserva metadados e usa referências UTF-8
   assert.match(read(root, '.kimi-code/agents/revisor.md'), /tools: \[Read, Grep, Glob\]/);
   assert.ok(existsSync(join(root, '.claude/skills/projeto/demo/SKILL.md')));
   for (const client of ['.claude', '.opencode', '.github', '.codex', '.cursor', '.kimi-code', '.vscode', '.agents', '.agent', '.gemini']) {
-    for (const kind of ['templates', 'scripts', 'tools', 'external-skills', 'estado', 'tests', 'docs', 'adapters', 'extra', 'README.md', 'INSTRUCTIONS.md']) assert.equal(existsSync(join(root, client, kind)), false, `${client}/${kind}`);
+  for (const kind of ['templates', 'scripts', 'tools', 'external-skills', 'state', 'estado', 'tests', 'docs', 'adapters', 'extra', 'README.md', 'INSTRUCTIONS.md']) assert.equal(existsSync(join(root, client, kind)), false, `${client}/${kind}`);
   }
   assert.deepEqual(JSON.parse(read(root, '.pbai4devs/agents.json')).entries, [{ path: '.pbai4devs/agents/revisor/AGENT.md' }]);
   assert.ok(JSON.parse(read(root, '.pbai4devs/skills.json')).entries.some(entry => entry.path === '.pbai4devs/skills/grupo com espaço/outro'));
@@ -589,12 +614,12 @@ test('entradas da CLI mantêm ownership integral e recursos têm proveniência d
   write(root, source, skill);
   write(root, '.pbai4devs/templates/entrypoints/AGENTS.md', template);
   write(root, 'AGENTS.md', entry);
-  write(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ clients: ['codex'], files: { 'AGENTS.md': createHash('sha256').update(entry).digest('hex') } }));
+  write(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ clients: ['codex'], files: { 'AGENTS.md': createHash('sha256').update(entry).digest('hex') } }));
   const result = run(root, { generateEntrypoints: true });
   assert.ok(result.ownedOutputs.includes('AGENTS.md'));
   assert.equal(read(root, 'AGENTS.md'), entry);
-  assert.equal(JSON.parse(read(root, '.pbai4devs/estado/derived.json')).entries['AGENTS.md'], undefined);
-  assert.ok(JSON.parse(read(root, '.pbai4devs/estado/derived.json')).files['.codex/skills/demo/SKILL.md']);
+  assert.equal(JSON.parse(read(root, '.pbai4devs/state/derived.json')).entries['AGENTS.md'], undefined);
+  assert.ok(JSON.parse(read(root, '.pbai4devs/state/derived.json')).files['.codex/skills/demo/SKILL.md']);
   assertCheckReadonly(root, { generateEntrypoints: true }, 0);
 });
 

package/.pbai4devs/scripts/testar-maturidade/SCRIPT.mjs

@@ -8,6 +8,7 @@ import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
 import { isGeneratedOutput } from '../lib/gitignore.mjs';
 import { resourcePath, synchronize } from '../sincronizar-agentes/SCRIPT.mjs';
 import { adapterManifest } from '../lib/adapters.mjs';
+import { stateDirectory } from '../lib/state-path.mjs';
 
 const assets = join(dirname(fileURLToPath(import.meta.url)), 'assets');
 const owner = 'testar-maturidade';
@@ -47,9 +48,9 @@ export const SCENARIOS = [
 ];
 
 function manifest(root) {
+  const state = join(root, stateDirectory(root), 'agentdevkit.json');
   const file = join(root, '.pbai4devs/espelhos.conf');
   if (existsSync(file)) return readFileSync(file, 'utf8');
-  const state = join(root, '.pbai4devs/estado/agentdevkit.json');
   return adapterManifest(root, { clients: existsSync(state) ? json(state).clients : undefined });
 }
 
@@ -94,7 +95,7 @@ function copyAllowed(relativePath, directory = false) {
 
 export function copyAgentStructure(sourceRoot, destination) {
   const roots = ['.pbai4devs', ...registeredRoots(sourceRoot)];
-  const stateFile = join(sourceRoot, '.pbai4devs/estado/agentdevkit.json');
+  const stateFile = join(sourceRoot, stateDirectory(sourceRoot), 'agentdevkit.json');
   const stateInfo = stat(stateFile);
   if (stateInfo && (!stateInfo.isFile() || stateInfo.isSymbolicLink())) fail('Estado da instalação deve ser arquivo regular.');
   const installation = stateInfo ? json(stateFile) : null;
@@ -162,10 +163,11 @@ function ensureOutput(output) {
 }
 
 function planning(root, scenario) {
-  const state = '.pbai4devs/estado/configuracao/ESTADO.md';
+  const stateRoot = stateDirectory(root);
+  const state = `${stateRoot}/configuracao/ESTADO.md`;
   rmSync(join(root, state), { force: true });
   if (scenario.planning === 'none' && !scenario.app) return;
-  write(root, '.pbai4devs/estado/README.md', document('Estado dos exemplos', 'Dados sintéticos deste cenário, sem aprovação real de produto.'));
+  write(root, `${stateRoot}/README.md`, document('Estado dos exemplos', 'Dados sintéticos deste cenário, sem aprovação real de produto.'));
   let paths = { prd: null, ux_ui: null, design: null, releases: null, specs: null };
   if (scenario.planning !== 'none') {
     for (const folder of ['docs', 'docs/produto', 'docs/design']) write(root, `${folder}/README.md`, document('Documentos do cenário', 'Entradas sintéticas para testar a classificação de maturidade.'));

package/.pbai4devs/scripts/testar-maturidade/tests/TEST.mjs

@@ -27,6 +27,7 @@ function fixture(t) {
   put('.gitignore', readFileSync(join(projectRoot, '.gitignore')));
   put('.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs', readFileSync(join(projectRoot, '.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs')));
   put('.pbai4devs/scripts/lib/runtime.mjs', readFileSync(join(projectRoot, '.pbai4devs/scripts/lib/runtime.mjs')));
+  put('.pbai4devs/scripts/lib/state-path.mjs', readFileSync(join(projectRoot, '.pbai4devs/scripts/lib/state-path.mjs')));
   return { root, put, outputRoot: join(root, 'examples/generated') };
 }
 
@@ -112,7 +113,7 @@ test('preparação interrompida não conserva resultado anterior nem declara suc
   const index = join(outputRoot, 'README.md');
   writeFileSync(report, JSON.stringify({ owner: 'testar-maturidade', status: 'passed', results: [{}] }));
   writeFileSync(index, readFileSync(index, 'utf8').replaceAll('prepared', 'passed'));
-  put('.pbai4devs/estado/agentdevkit.json', JSON.stringify({ blocks: null }));
+  put('.pbai4devs/state/agentdevkit.json', JSON.stringify({ blocks: null }));
   assert.throws(() => prepareExamples(options), /Estado da instalação/);
   assert.equal(existsSync(report), false);
   assert.match(readFileSync(index, 'utf8'), /status: preparing/);
@@ -181,7 +182,7 @@ test('instalação parcial preserva entradas próprias e blocos editados', t =>
   const { root, put } = fixture(t);
   put('.pbai4devs/espelhos.conf', 'agente|.codex|agrupado\nagente|.agents|agrupado\n');
   const block = '<!-- BEGIN AGENTDEVKIT -->\nEntrada gerenciada.\n<!-- END AGENTDEVKIT -->';
-  put('.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, version: '1.0.0', language: 'pt', clients: ['codex'], files: {}, blocks: { 'AGENTS.md': createHash('sha256').update(block).digest('hex') } }));
+  put('.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, version: '1.0.0', language: 'pt', clients: ['codex'], files: {}, blocks: { 'AGENTS.md': createHash('sha256').update(block).digest('hex') } }));
   put('AGENTS.md', `# Agentes\n\n${block}\n`);
   const human = '# Claude pessoal\r\n\r\nPreservar byte a byte: ação.\r\n';
   put('CLAUDE.md', human);
@@ -222,7 +223,7 @@ test('checkout de fontes sem manifesto deriva clientes em memória', t => {
   assert.ok(registeredRoots(root).includes('.claude'));
   const source = '.pbai4devs/skills/projeto/demo/SKILL.md';
   assert.ok(resourceTargets(root, source).includes('.claude/skills/demo/SKILL.md'));
-  put('.pbai4devs/estado/agentdevkit.json', JSON.stringify({ clients: ['claude'] }));
+  put('.pbai4devs/state/agentdevkit.json', JSON.stringify({ clients: ['claude'] }));
   assert.deepEqual(registeredRoots(root), ['.claude']);
   assert.deepEqual(resourceTargets(root, source), ['.claude/skills/demo/SKILL.md']);
   assert.equal(existsSync(manifest), false);

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

@@ -8,12 +8,13 @@ import { buildCatalog } from '../lib/catalog.mjs';
 import { isGeneratedOutput } from '../lib/gitignore.mjs';
 import { canonicalEntrypoint, extractManagedBlock, managedBlockDigest } from '../lib/managed-content.mjs';
 import { extractTomlManagedBlock, tomlManagedBlockDigest } from '../lib/managed-toml.mjs';
+import { stateDirectory } from '../lib/state-path.mjs';
 
 const fail = message => { throw new Error(message); };
 const normalize = value => value.split(sep).join('/');
 const excluded = new Set(['node_modules', '.git', 'opencode-loop', '.agent-tests']);
 const toolState = new Set(['bin', '.cache', 'npm-cache']);
-const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'adapters', 'estado', 'tests', 'docs'];
+const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'adapters', 'state', 'estado', 'tests', 'docs'];
 
 function checkedStat(root, location) {
   let item;
@@ -31,8 +32,9 @@ function checkedPath(root, path) {
 }
 
 function ownership(root) {
-  const file = checkedPath(root, '.pbai4devs/estado/agentdevkit.json');
-  const derivedFile = checkedPath(root, '.pbai4devs/estado/derived.json');
+  const stateRoot = stateDirectory(root);
+  const file = checkedPath(root, `${stateRoot}/agentdevkit.json`);
+  const derivedFile = checkedPath(root, `${stateRoot}/derived.json`);
   if (!checkedStat(root, file) && !checkedStat(root, derivedFile)) return null;
   const readState = location => {
     try { return JSON.parse(readFileSync(location, 'utf8')); }

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

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, readdirSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, readdirSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, relative } from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -43,14 +43,22 @@ const verify = root => verifyResources({ root, synchronize() {}, catalogCheck()
 
 function installedFixture(t) {
   const context = resourceFixture(t);
-  context.file('.pbai4devs/estado/README.md');
+  context.file('.pbai4devs/state/README.md');
   const generated = '.agents/skills/managed/SKILL.md';
   context.file(generated, document('# Gerado\n'));
   const files = { [generated]: createHash('sha256').update(readFileSync(join(context.root, generated))).digest('hex') };
-  context.file('.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, version: '0.0.9', language: 'pt', files, blocks: {} }));
+  context.file('.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, version: '0.0.9', language: 'pt', files, blocks: {} }));
   return { ...context, generated };
 }
 
+test('verificação consulta propriedade legada e recusa estado ambíguo', t => {
+  const { root } = installedFixture(t);
+  renameSync(join(root, '.pbai4devs/state'), join(root, '.pbai4devs/estado'));
+  assert.doesNotThrow(() => collectMarkdown(root));
+  mkdirSync(join(root, '.pbai4devs/state'));
+  assert.throws(() => collectMarkdown(root), /coexistem/);
+});
+
 function writeCatalog(root) {
   for (const [path, content] of buildCatalog(root).outputs) { mkdirSync(join(root, path, '..'), { recursive: true }); writeFileSync(join(root, path), content); }
 }
@@ -161,10 +169,10 @@ test('instalação confere entradas derivadas sem aplicar lint a blocos humanos'
   const { root, file } = installedFixture(t);
   const contents = document('# Entrada gerada\n');
   file('GEMINI.md', contents);
-  file('.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: { 'GEMINI.md': createHash('sha256').update(contents).digest('hex') } }));
+  file('.pbai4devs/state/derived.json', JSON.stringify({ schemaVersion: 1, entries: { 'GEMINI.md': createHash('sha256').update(contents).digest('hex') } }));
   const block = '<!-- BEGIN AGENTDEVKIT -->\nLeia as fontes.\n<!-- END AGENTDEVKIT -->';
   file('AGENTS.md', `# Instruções humanas sem frontmatter\n\n${block}\n`);
-  const statePath = join(root, '.pbai4devs/estado/agentdevkit.json');
+  const statePath = join(root, '.pbai4devs/state/agentdevkit.json');
   const state = JSON.parse(readFileSync(statePath, 'utf8'));
   state.blocks['AGENTS.md'] = createHash('sha256').update(block).digest('hex');
   state.files['.pbai4devs/skills/exemplo/SKILL.md'] = createHash('sha256').update('fonte anterior').digest('hex');
@@ -182,7 +190,7 @@ test('instalação também protege manifestos registrados em derived.outputs', t
   const manifest = '.agents/skills.json';
   const contents = '{"entries":[]}\n';
   file(manifest, contents);
-  file('.pbai4devs/estado/derived.json', JSON.stringify({ schemaVersion: 1, entries: {}, outputs: { [manifest]: createHash('sha256').update(contents).digest('hex') } }));
+  file('.pbai4devs/state/derived.json', JSON.stringify({ schemaVersion: 1, entries: {}, outputs: { [manifest]: createHash('sha256').update(contents).digest('hex') } }));
   assert.ok(!verify(root).files.includes(join(root, manifest)));
   rmSync(join(root, manifest));
   assert.throws(() => verify(root), /Arquivo gerenciado ausente: .agents\/skills.json/);
@@ -372,7 +380,7 @@ test('fontes novas permanecem elegíveis e derivados locais ficam fora do índic
   const outputs = ['.github/skills/generated/SKILL.md', '.vscode/.gitignore', '.github/.gitignore'];
   applyLocalIgnore(planLocalIgnore(root, { outputs }));
   const sources = ['src/new.mjs', 'bin/new.mjs', 'tests/new.test.mjs', 'scripts/release/new.mjs', '.github/workflows/own.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.github/skills/human/SKILL.md', '.vscode/settings.json'];
-  const generated = [...outputs, '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/espelhos.conf', '.pbai4devs/estado/agentdevkit.json'];
+  const generated = [...outputs, '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/espelhos.conf', '.pbai4devs/state/agentdevkit.json'];
   for (const path of [...sources, ...generated]) file(path, 'fixture\n');
   assert.deepEqual(ignoredPaths(root, sources), []);
   assert.deepEqual(new Set(ignoredPaths(root, generated)), new Set(generated));

package/.pbai4devs/skills/produto/criar-design-doc/SKILL.md

@@ -9,7 +9,7 @@ Siga `.pbai4devs/rules/qualidade/RULE.md` ao criar arquivos Markdown.
 Antes de escrever, use `atualizar-documentacao` para ler e reaproveitar documentos
 existentes; aplique o template somente às lacunas.
 
-Consulte `.pbai4devs/estado/configuracao/ESTADO.md` e confira o PRD aprovado
+Consulte `.pbai4devs/state/configuracao/ESTADO.md` e confira o PRD aprovado
 e UX/UI aprovado ou não aplicável com justificativa,
 incluindo a evidência das decisões. Se faltar, estiver pendente ou houver
 conflito, informe o bloqueio e encaminhe à skill correspondente.

package/.pbai4devs/skills/produto/criar-prd/SKILL.md

@@ -9,7 +9,7 @@ Siga `.pbai4devs/rules/qualidade/RULE.md` ao criar arquivos Markdown.
 Antes de escrever, use `atualizar-documentacao` para ler e reaproveitar documentos
 existentes; aplique o template somente às lacunas.
 
-Confira a preparação em `.pbai4devs/estado/configuracao/ESTADO.md`. Se não estiver
+Confira a preparação em `.pbai4devs/state/configuracao/ESTADO.md`. Se não estiver
 concluída e comprovada, encaminhe a `configurar-projeto` para a fase
 inicial antes de criar o PRD.
 

package/.pbai4devs/skills/produto/criar-ux-ui/SKILL.md

@@ -9,7 +9,7 @@ Siga `.pbai4devs/rules/qualidade/RULE.md` ao criar arquivos Markdown.
 Antes de escrever, use `atualizar-documentacao` para ler e reaproveitar documentos
 existentes; aplique o template somente às lacunas.
 
-Consulte `.pbai4devs/estado/configuracao/ESTADO.md` e confira o PRD
+Consulte `.pbai4devs/state/configuracao/ESTADO.md` e confira o PRD
 com `status: aprovado` e a
 aprovação registrada. Se faltar, estiver pendente ou for insuficiente, informe
 o bloqueio e encaminhe a `criar-prd`.

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

@@ -20,7 +20,7 @@ as ferramentas e rode o diagnóstico. Isso não escolhe a stack da aplicação.
 Antes de criar estado ou documentos, faça o inventário de `atualizar-documentacao`.
 Mapeie os documentos já existentes aos seus papéis, sem reiniciar o produto.
 Reúna dúvidas no início e aproveite decisões existentes. Quando o projeto
-começar, crie ou retome `.pbai4devs/estado/configuracao/ESTADO.md` pelo modelo.
+começar, crie ou retome `.pbai4devs/state/configuracao/ESTADO.md` pelo modelo.
 Combine os arquivos `prd`, `ux_ui`, `design`, `roadmap` e diretórios `releases`,
 `specs`, `tarefas` e documentos de apoio aplicáveis. Crie/evolua o README
 da raiz pelos [modelos da fase](../../../templates/README.md), preservando os

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

@@ -6,7 +6,7 @@ description: Identifica o estado atual e orienta a próxima ação útil do proj
 # Próximos passos
 
 Leia o pedido, o estado salvo e os documentos existentes. Use o idioma de
-`.pbai4devs/estado/agentdevkit.json` ou português quando ainda não houver escolha.
+`.pbai4devs/state/agentdevkit.json` ou português quando ainda não houver escolha.
 Se a CLI estiver disponível, consulte `agentdevkit next --target . --json`;
 caso contrário, use os arquivos e a inspeção local do projeto.
 

package/.pbai4devs/skills/projeto/sincronizar-agentes/SKILL.md

@@ -28,7 +28,7 @@ Não apague raízes inteiras: workflows, configurações nativas e a origem fica
 fora da limpeza. `--check` só confere, sem corrigir nem criar backups.
 
 O manifesto `.pbai4devs/espelhos.conf` registra clientes e formatos nativos.
-Respeite a seleção salva em `estado/agentdevkit.json`; não reative clientes para
+Respeite a seleção salva em `state/agentdevkit.json`; não reative clientes para
 reparar apontamentos. Para alterá-la, use `agents` na CLI. Pastas compartilhadas
 continuam quando necessárias; arquivos próprios dos clientes são preservados
 pela CLI, inclusive ao reduzir a seleção.

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,11 @@ 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.

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

@@ -20,6 +20,7 @@ description: Incrementos verificáveis do AgentDevKit.
 - [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/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.16",
+  "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. */ }
     }