@pathbit/agentdevkit 0.0.15 → 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.