@pathbit/agentdevkit 0.0.16 → 0.0.18

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

@@ -0,0 +1,306 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { synchronize } from '../SCRIPT.mjs';
+import { indexContentMatches } from '../../lib/gitignore.mjs';
+
+const repository = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const original = '.pbai4devs/skills/projeto/criar-skill/SKILL.md';
+const pointer = '.claude/skills/criar-skill/SKILL.md';
+const file = (root, relative) => join(root, relative);
+const put = (root, relative, content) => { mkdirSync(dirname(file(root, relative)), { recursive: true }); writeFileSync(file(root, relative), content); };
+function git(root, ...args) {
+  const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8' });
+  assert.equal(result.status, 0, `${args.join(' ')}: ${result.stderr}`);
+  return result.stdout;
+}
+function fixture(t, withGit = true) {
+  mkdirSync(join(repository, '.agent-tests'), { recursive: true });
+  const root = mkdtempSync(join(withGit ? join(repository, '.agent-tests') : tmpdir(), 'sync-preservation-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  if (withGit) git(root, 'init', '--quiet');
+  populate(root);
+  return root;
+}
+function populate(root) {
+  put(root, '.gitignore', '# Human ignore\nnode_modules/\n');
+  put(root, '.pbai4devs/templates/gitignore/agents.ignore', '# Cache\n/*\n!/.gitignore\n{{ALLOWLIST}}\n/cache/\n*.log\n');
+  put(root, '.pbai4devs/templates/gitignore/clients.json', '{}\n');
+  put(root, '.pbai4devs/templates/gitignore/shared.ignore', '# Shared\n/tools/*/.local/\n');
+  put(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\n');
+  put(root, original, '---\nname: criar-skill\ndescription: Criar recurso.\n---\n\n# Criar skill\n');
+  assert.equal(run(root).exitCode, 0);
+  assert.ok(existsSync(file(root, pointer)));
+}
+function run(root, options = {}) {
+  return synchronize({ root, localIgnores: false, generateEntrypoints: false, output() {}, ...options });
+}
+function withoutGit(t, callback) {
+  const emptyPath = mkdtempSync(join(tmpdir(), 'sync-empty-path-'));
+  t.after(() => rmSync(emptyPath, { recursive: true, force: true }));
+  const keys = Object.keys(process.env).filter(key => key.toLowerCase() === 'path');
+  const previous = new Map(keys.map(key => [key, process.env[key]]));
+  if (!keys.length) keys.push('PATH');
+  try {
+    for (const key of keys) process.env[key] = emptyPath;
+    return callback();
+  } finally {
+    for (const key of keys) {
+      if (previous.has(key)) process.env[key] = previous.get(key);
+      else delete process.env[key];
+    }
+  }
+}
+
+for (const [withGit, force] of [[true, false], [true, true], [false, false], [false, true]]) {
+  test(`remoção obsoleta preserva pasta vazia humana (git=${withGit}, force=${force})`, t => {
+    const root = fixture(t, withGit), human = '.claude/skills/criar-skill/Equipe-Vazia';
+    mkdirSync(file(root, human));
+    const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+    const index = withGit ? git(root, 'ls-files', '--stage', '-z') : null;
+    const ignore = readFileSync(file(root, '.gitignore'));
+    rmSync(dirname(file(root, original)), { recursive: true });
+    const check = run(root, { check: true, force });
+    assert.notEqual(check.exitCode, 0);
+    assert.ok(existsSync(file(root, pointer)));
+    assert.ok(existsSync(file(root, human)));
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    run(root, { force });
+    assert.equal(existsSync(file(root, pointer)), false, 'apontamento obsoleto comprovado é removido');
+    assert.ok(existsSync(file(root, human)), 'pasta vazia própria permanece');
+    assert.deepEqual(readFileSync(file(root, '.gitignore')), ignore);
+    if (withGit) assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+for (const force of [false, true]) {
+  test(`índice com conteúdo humano divergente bloqueia remoção (force=${force})`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, pointer));
+    put(root, pointer, Buffer.concat([generated, Buffer.from('\nConteúdo humano staged.\n')]));
+    git(root, 'add', '-f', '--', pointer);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    put(root, pointer, generated);
+    rmSync(dirname(file(root, original)), { recursive: true });
+    const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+    const check = run(root, { check: true, force });
+    assert.notEqual(check.exitCode, 0);
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    assert.throws(() => run(root, { force }), /conflitos|indice|índice/i);
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+for (const force of [false, true]) {
+  test(`índice divergente impede atualização de apontamento ativo (force=${force})`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, pointer));
+    put(root, pointer, Buffer.concat([generated, Buffer.from('\nAlteração humana staged.\n')]));
+    git(root, 'add', '-f', '--', pointer);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    put(root, pointer, generated);
+    put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+    const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+    assert.notEqual(run(root, { check: true, force }).exitCode, 0);
+    assert.throws(() => run(root, { force }), /indice/i);
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+for (const flag of ['--assume-unchanged', '--skip-worktree']) {
+  test(`índice divergente continua protegido com ${flag}`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, pointer));
+    put(root, pointer, Buffer.concat([generated, Buffer.from('\nAlteração humana staged.\n')]));
+    git(root, 'add', '-f', '--', pointer);
+    put(root, pointer, generated);
+    git(root, 'update-index', flag, '--', pointer);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    const flags = git(root, 'ls-files', '-v', '--', pointer);
+    put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+    assert.notEqual(run(root, { check: true, force: true }).exitCode, 0);
+    assert.throws(() => run(root, { force: true }), /indice/i);
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+    assert.equal(git(root, 'ls-files', '-v', '--', pointer), flags);
+  });
+}
+
+test('índice com alias de caixa bloqueia alteração conservadoramente em qualquer sistema', t => {
+  const root = fixture(t), generated = readFileSync(file(root, pointer));
+  const alias = pointer.replace('/skills/', '/SKILLS/');
+  put(root, alias, Buffer.concat([generated, Buffer.from('\nAlteração humana staged.\n')]));
+  git(root, 'add', '-f', '--', alias);
+  const index = git(root, 'ls-files', '--stage', '-z');
+  put(root, pointer, generated);
+  put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+  const aliasBytes = readFileSync(file(root, alias));
+  const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+  const ignore = readFileSync(file(root, '.gitignore'));
+  const preserved = () => {
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.deepEqual(readFileSync(file(root, alias)), aliasBytes);
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    assert.deepEqual(readFileSync(file(root, '.gitignore')), ignore);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  };
+  let check, error;
+  try { check = run(root, { check: true, force: true }); } catch (failure) { error = failure; }
+  if (error) assert.match(error.message, /maiusculas\/minusculas/i);
+  else assert.notEqual(check.exitCode, 0);
+  preserved();
+  assert.throws(() => run(root, { force: true }), /indice|maiusculas\/minusculas/i);
+  preserved();
+});
+
+test('comparação de índice entende CRLF autorizado e recusa filtros, binários e divergência', t => {
+  const root = fixture(t), path = 'arquivo.txt';
+  const crlf = Buffer.from('texto\r\noutra linha\r\n'), lf = Buffer.from('texto\noutra linha\n');
+  git(root, 'config', 'core.autocrlf', 'false');
+  git(root, 'config', 'core.attributesfile', file(root, 'atributos-ausentes'));
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  git(root, 'config', 'core.autocrlf', 'true');
+  assert.equal(indexContentMatches(root, path, crlf, lf), true);
+  assert.equal(indexContentMatches(root, path, crlf, Buffer.from('texto humano\noutra linha\n')), false);
+  assert.equal(indexContentMatches(root, path, Buffer.from([0, 13, 10]), Buffer.from([0, 10])), false);
+  assert.equal(indexContentMatches(root, path, Buffer.from('um\r\ndois\r'), Buffer.from('um\ndois\r')), false);
+  assert.equal(indexContentMatches(root, path, Buffer.from('\ufefftexto\r\n'), Buffer.from('texto\n')), false);
+  assert.equal(indexContentMatches(root, path, Buffer.from('\ufefftexto\r\n'), Buffer.from('\ufefftexto\n')), true);
+  put(root, '.gitattributes', '*.txt -text\n');
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  put(root, '.gitattributes', '*.txt text filter=nao-executar\n');
+  git(root, 'config', 'filter.nao-executar.clean', 'exit 1');
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  put(root, '.gitattributes', '*.txt text working-tree-encoding=UTF-16\n');
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  put(root, '.gitattributes', '*.txt text ident\n');
+  assert.equal(indexContentMatches(root, path, crlf, lf), false);
+  put(root, '.gitattributes', '*.txt text eol=crlf\n');
+  git(root, 'config', 'core.autocrlf', 'false');
+  assert.equal(indexContentMatches(root, path, crlf, lf), true);
+});
+
+test('sync atualiza apontamento staged equivalente em repositório com autocrlf', t => {
+  const root = fixture(t), generated = readFileSync(file(root, pointer), 'utf8').replaceAll('\n', '\r\n');
+  git(root, 'config', 'core.autocrlf', 'true');
+  put(root, pointer, generated);
+  git(root, 'add', '-f', '--', pointer);
+  const index = git(root, 'ls-files', '--stage', '-z');
+  put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+  assert.equal(run(root, { force: true }).exitCode, 0);
+  assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+});
+
+for (const target of ['.pbai4devs/state/derived.json', '.claude/.gitignore']) {
+  test(`índice divergente impede atualização de ${target}`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, target));
+    put(root, target, Buffer.concat([generated, Buffer.from('\nAlteração humana staged.\n')]));
+    git(root, 'add', '-f', '--', target);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    put(root, target, generated);
+    if (target.endsWith('derived.json')) {
+      put(root, original, '---\nname: criar-skill\ndescription: Mudança real.\n---\n\n# Criar skill\n');
+    } else {
+      put(root, '.pbai4devs/templates/gitignore/agents.ignore', '# Cache atualizado\n/*\n!/.gitignore\n{{ALLOWLIST}}\n/cache/\n*.log\n');
+    }
+    assert.notEqual(run(root, { check: true, force: true }).exitCode, 0);
+    assert.throws(() => run(root, { force: true }), /indice/i);
+    assert.deepEqual(readFileSync(file(root, target)), generated);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+for (const options of [{ check: true }, { force: true }]) {
+  test(`Git indisponível bloqueia limpeza em repositório (check=${Boolean(options.check)}, force=${Boolean(options.force)})`, t => {
+    const root = fixture(t), generated = readFileSync(file(root, pointer));
+    put(root, pointer, Buffer.concat([generated, Buffer.from('\nConteúdo humano staged.\n')]));
+    git(root, 'add', '-f', '--', pointer);
+    const index = git(root, 'ls-files', '--stage', '-z');
+    put(root, pointer, generated);
+    rmSync(dirname(file(root, original)), { recursive: true });
+    const state = readFileSync(file(root, '.pbai4devs/state/derived.json'));
+    withoutGit(t, () => assert.throws(() => run(root, options), /consultar o Git.*preservar/i));
+    assert.deepEqual(readFileSync(file(root, pointer)), generated);
+    assert.deepEqual(readFileSync(file(root, '.pbai4devs/state/derived.json')), state);
+    assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+  });
+}
+
+test('projeto realmente sem Git pode limpar apontamento próprio sem executável Git', t => {
+  const root = fixture(t, false), human = '.claude/skills/criar-skill/equipe-vazia';
+  mkdirSync(file(root, human));
+  rmSync(dirname(file(root, original)), { recursive: true });
+  withoutGit(t, () => assert.equal(run(root, { force: true }).exitCode, 0));
+  assert.equal(existsSync(file(root, pointer)), false);
+  assert.ok(existsSync(file(root, human)));
+});
+
+test('preserva diretório preexistente sem prova de propriedade após remover único apontamento', t => {
+  const root = fixture(t), directory = dirname(file(root, pointer));
+  rmSync(dirname(file(root, original)), { recursive: true });
+  assert.equal(run(root, { force: true }).exitCode, 0);
+  assert.equal(existsSync(file(root, pointer)), false);
+  assert.ok(existsSync(directory));
+});
+
+test('alteração concorrente no índice bloqueia limpeza antes de qualquer exclusão', t => {
+  const root = fixture(t), generated = readFileSync(file(root, pointer));
+  rmSync(dirname(file(root, original)), { recursive: true });
+  let staged;
+  assert.throws(() => synchronize({ root, localIgnores: false, generateEntrypoints: false, force: true,
+    output() {
+      if (staged !== undefined) return;
+      put(root, pointer, Buffer.concat([generated, Buffer.from('\nStaged pela equipe.\n')]));
+      git(root, 'add', '-f', '--', pointer);
+      staged = git(root, 'ls-files', '--stage', '-z');
+      put(root, pointer, generated);
+    },
+  }), /indice git mudou/i);
+  assert.notEqual(staged, undefined);
+  assert.deepEqual(readFileSync(file(root, pointer)), generated);
+  assert.equal(git(root, 'ls-files', '--stage', '-z'), staged);
+});
+
+test('índice divergente é protegido quando o projeto fica em subpasta do repositório Git', t => {
+  const outer = mkdtempSync(join(tmpdir(), 'sync-parent-git-'));
+  t.after(() => rmSync(outer, { recursive: true, force: true }));
+  git(outer, 'init', '--quiet');
+  const root = join(outer, 'projeto'); mkdirSync(root);
+  populate(root);
+  const generated = readFileSync(file(root, pointer));
+  put(root, pointer, Buffer.concat([generated, Buffer.from('\nStaged pela equipe.\n')]));
+  git(root, 'add', '-f', '--', pointer);
+  const index = git(outer, 'ls-files', '--stage', '-z');
+  put(root, pointer, generated);
+  rmSync(dirname(file(root, original)), { recursive: true });
+  assert.throws(() => run(root, { force: true }), /indice/i);
+  assert.deepEqual(readFileSync(file(root, pointer)), generated);
+  assert.equal(git(outer, 'ls-files', '--stage', '-z'), index);
+});
+
+test('conteúdo humano na pasta e apontamento gerenciado editado sobrevivem à limpeza forçada', t => {
+  const root = fixture(t), human = '.claude/skills/criar-skill/notas-da-equipe.md';
+  const notes = '# Referência própria\n', edited = Buffer.concat([readFileSync(file(root, pointer)), Buffer.from('\nNota própria.\n')]);
+  put(root, human, notes);
+  put(root, pointer, edited);
+  rmSync(dirname(file(root, original)), { recursive: true });
+  run(root, { force: true });
+  assert.equal(readFileSync(file(root, human), 'utf8'), notes);
+  assert.deepEqual(readFileSync(file(root, pointer)), edited);
+});
+
+test('colisão com arquivo humano ancestral não é removida por --force', t => {
+  const root = fixture(t), ancestor = '.claude/skills/equipe-custom';
+  const human = 'Arquivo da equipe; não substituir.\n';
+  put(root, ancestor, human);
+  put(root, '.pbai4devs/skills/projeto/equipe-custom/SKILL.md', '---\nname: equipe-custom\ndescription: Exemplo.\n---\n\n# Equipe\n');
+  const index = git(root, 'ls-files', '--stage', '-z');
+  try { run(root, { force: true }); } catch (error) { assert.match(error.message, /conflito|gerenciado|arquivo|diretor/i); }
+  assert.equal(readFileSync(file(root, ancestor), 'utf8'), human);
+  assert.equal(git(root, 'ls-files', '--stage', '-z'), index);
+});

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

@@ -13,7 +13,9 @@ import './LOCAL_IGNORE.mjs';
 import './HUMAN_OWNERSHIP.mjs';
 import './COEXISTENCE.mjs';
 import './MANAGED_CONTENT.mjs';
+import './PRESERVATION.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 +26,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 +77,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 +94,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 +141,12 @@ 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']) {
+      if (client === '.claude' && ['templates', 'scripts', 'tools', 'external-skills', 'state', 'tests', 'docs', 'adapters'].includes(kind)) {
+        assert.equal(existsSync(join(root, client, kind, 'demo/REFERENCE.md')), false);
+        assert.ok(existsSync(join(root, client, kind)), 'diretório sem prova de propriedade permanece');
+      } else 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'));
@@ -416,7 +447,8 @@ test('atualiza fontes, adiciona clientes, remove recursos e migra agrupado para
   rmSync(join(root, '.pbai4devs/rules/example/RULE.md'));
   write(root, '.pbai4devs/espelhos.conf', read(root, '.pbai4devs/espelhos.conf').replace('agente|.claude\n', 'agente|.claude|plano\n'));
   run(root);
-  assert.equal(existsSync(join(root, '.claude/skills/projeto')), false);
+  assert.equal(existsSync(join(root, '.claude/skills/projeto/demo/SKILL.md')), false);
+  assert.ok(existsSync(join(root, '.claude/skills/projeto')));
   assert.ok(existsSync(join(root, '.claude/skills/demo/SKILL.md')));
   assert.equal(existsSync(join(root, '.codex/rules/example.md')), false);
   assert.deepEqual(JSON.parse(read(root, '.pbai4devs/rules.json')).entries, []);
@@ -589,12 +621,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);
 });
 
@@ -857,7 +889,8 @@ test('manifestos Antigravity acompanham skills, regras e agentes agrupados', t =
   rmSync(join(root, '.pbai4devs/skills/projeto/demo'), { recursive: true });
   run(root, { generateEntrypoints: true });
   assert.deepEqual(JSON.parse(read(root, '.agents/skills.json')).entries, [{ path: '.agents/skills/projeto/new-skill' }]);
-  assert.equal(existsSync(join(root, '.agents/skills/projeto/demo')), false);
+  assert.equal(existsSync(join(root, '.agents/skills/projeto/demo/SKILL.md')), false);
+  assert.ok(existsSync(join(root, '.agents/skills/projeto/demo')));
   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.