@pathbit/agentdevkit 0.0.22 → 0.0.24

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

@@ -1,11 +1,13 @@
 import assert from 'node:assert/strict';
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import fs from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import childProcess, { spawnSync } from 'node:child_process';
 import { syncBuiltinESMExports } from 'node:module';
 import { createHash } from 'node:crypto';
 import test from 'node:test';
 import { projectRoot, requireNode } from '../../lib/runtime.mjs';
+import { adapterManifest } from '../../lib/adapters.mjs';
 import { copyAgentStructure, prepareExamples as prepare, registeredRoots, resourceTargets, SCENARIOS } from '../SCRIPT.mjs';
 
 // As fixtures pequenas isolam a cópia; o caso source-only usa o renderizador real.
@@ -32,6 +34,23 @@ function fixture(t) {
   return { root, put, outputRoot: join(root, 'examples/generated') };
 }
 
+function controlledSource(root) {
+  const source = join(root, 'controlled-source');
+  // Only four explicit resources; exclude local state and additional skills.
+  for (const path of ['.pbai4devs/skills/projeto/criar-skill/SKILL.md', '.pbai4devs/templates/gitignore/clients.json', '.pbai4devs/templates/gitignore/agents.ignore', '.pbai4devs/templates/gitignore/shared.ignore']) {
+    let current = projectRoot;
+    for (const part of path.split('/')) {
+      current = join(current, part);
+      assert.equal(lstatSync(current).isSymbolicLink(), false, `Fonte não pode ser link: ${path}`);
+    }
+    const destination = join(source, path);
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(join(projectRoot, path), destination);
+  }
+  writeFileSync(join(source, '.gitignore'), 'node_modules/\n');
+  return source;
+}
+
 test('copia recursos e configurações, excluindo payloads, caches e segredos', t => {
   const { root, put } = fixture(t);
   put('.pbai4devs/tools/demo/TOOL.json', '{}'); put('.pbai4devs/tools/demo/SCRIPT.mjs', 'export {};'); put('.pbai4devs/tools/demo/README.md', '# Tool');
@@ -110,6 +129,34 @@ test('troca de ancestral por symlink antes da criação não escreve no destino
   }
 });
 
+test('troca de saída durante escrita é detectada, sem alegar atomicidade', t => {
+  const { root, outputRoot } = fixture(t);
+  const target = join(outputRoot, 'race-output'), outside = mkdtempSync(join(root, 'race-outside-'));
+  const sentinel = join(outside, 'sentinel'); writeFileSync(sentinel, 'Não alterar.\n');
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+  const probe = join(root, 'race-link-probe');
+  try { symlinkSync(outside, probe, linkType); }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) { t.skip('Links simbólicos indisponíveis.'); return; } throw error; }
+  unlinkSync(probe);
+  const original = fs.writeFileSync; let injected = false;
+  try {
+    fs.writeFileSync = (file, ...args) => {
+      if (!injected && String(file) === join(target, '.maturity-suite.json')) {
+        renameSync(target, `${target}-moved`); symlinkSync(outside, target, linkType); injected = true;
+      }
+      return original.call(fs, file, ...args);
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => prepareExamples({ sourceRoot: root, outputRoot: target, scenarios: [SCENARIOS[0]], initializeGit: false }), /link|alterado/i);
+  } finally { fs.writeFileSync = original; syncBuiltinESMExports(); }
+  assert.equal(injected, true);
+  assert.equal(readFileSync(sentinel, 'utf8'), 'Não alterar.\n');
+  // O write já em curso pode ter criado o marcador no destino externo: a
+  // verificação detecta a troca, mas não é uma operação atômica de diretório.
+  assert.equal(existsSync(join(outside, '.maturity-suite.json')), true);
+  assert.equal(existsSync(join(outside, 'REPORT.json')), false);
+});
+
 test('cada destino padrão é exclusivo, preserva provas anteriores e permanece ignorado', t => {
   const { root, outputRoot } = fixture(t);
   const git = (...args) => {
@@ -172,16 +219,16 @@ test('preparação interrompida não altera resultado anterior nem declara suces
   assert.doesNotMatch(readFileSync(index, 'utf8'), /status: passed|\| passed \|/);
 });
 
-test('usa entradas distribuídas do hub e mantém fallback legado', t => {
+test('sem estado comprovado conserva entradas humanas mesmo com template', t => {
   const { root, put } = fixture(t);
   const template = '---\ndescription: Entrada genérica.\n---\n\n# Agentes do projeto\n';
   put('AGENTS.md', '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
   put('.pbai4devs/templates/entrypoints/AGENTS.md', template);
   const destination = join(root, 'copy');
   const copied = copyAgentStructure(root, destination);
-  assert.equal(readFileSync(join(destination, 'AGENTS.md'), 'utf8'), template);
+  assert.equal(readFileSync(join(destination, 'AGENTS.md'), 'utf8'), '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
   assert.equal(readFileSync(join(destination, 'CLAUDE.md'), 'utf8'), 'fixture\n');
-  assert.equal(copied.entrypoints['AGENTS.md'], '.pbai4devs/templates/entrypoints/AGENTS.md');
+  assert.equal(copied.entrypoints['AGENTS.md'], 'AGENTS.md');
   assert.equal(copied.entrypoints['CLAUDE.md'], 'CLAUDE.md');
   assert.equal(readFileSync(join(root, 'AGENTS.md'), 'utf8'), '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
 });
@@ -315,7 +362,9 @@ test('checkout de fontes sem manifesto deriva clientes em memória', t => {
 test('prepare gera apontamentos reais mesmo sem pastas de clientes na origem', t => {
   const { root } = fixture(t);
   const sourceRoot = join(root, 'source-only');
-  copyAgentStructure(projectRoot, sourceRoot);
+  copyAgentStructure(controlledSource(root), sourceRoot);
+  // Model a clean source checkout regardless of ignored local developer data.
+  for (const path of ['.pbai4devs/espelhos.conf', '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json', '.pbai4devs/state/agentdevkit.json', '.pbai4devs/state/derived.json', '.pbai4devs/estado/agentdevkit.json', '.pbai4devs/estado/derived.json']) rmSync(join(sourceRoot, path), { force: true });
   const roots = registeredRoots(sourceRoot);
   for (const client of roots) rmSync(join(sourceRoot, client), { recursive: true, force: true });
   const [example] = prepare({ sourceRoot, scenarios: [SCENARIOS[0]], initializeGit: false });
@@ -325,6 +374,102 @@ test('prepare gera apontamentos reais mesmo sem pastas de clientes na origem', t
   for (const file of ['src/cli.mjs', 'bin/agentdevkit.mjs', 'scripts/release/pipeline.mjs', 'tests/cli.test.mjs']) assert.equal(existsSync(join(example.root, file)), false, file);
 });
 
+for (const withState of [false, true]) test(`prepare preserva catálogos humanos na cópia e na origem (estado=${withState})`, t => {
+  const { root } = fixture(t), sourceRoot = join(root, `source-catalog-${withState}`);
+  copyAgentStructure(controlledSource(root), sourceRoot);
+  // Source checkouts do not include generated manifests; provide this fixture
+  // explicitly instead of depending on ignored files in the developer's tree.
+  writeFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf'), adapterManifest(sourceRoot, { clients: ['codex'] }));
+  const state = join(sourceRoot, '.pbai4devs/state/agentdevkit.json');
+  const derived = join(sourceRoot, '.pbai4devs/state/derived.json');
+  rmSync(state, { force: true }); rmSync(derived, { force: true }); // Só cópias criadas nesta fixture.
+  if (withState) {
+    mkdirSync(dirname(state), { recursive: true });
+    writeFileSync(state, JSON.stringify({ schemaVersion: 1, version: '0.0.24', language: 'pt', clients: ['codex'], files: {}, blocks: {} }) + '\n');
+  }
+  const originals = {};
+  for (const name of ['catalog.json', 'skills.json', 'agents.json', 'rules.json']) {
+    const file = join(sourceRoot, '.pbai4devs', name), content = `{ "arquivo humano": ${JSON.stringify(name)} }\n`;
+    writeFileSync(file, content); originals[name] = content;
+  }
+  for (const path of ['.pbai4devs/.gitignore', '.codex/.gitignore']) {
+    const file = join(sourceRoot, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, '# BEGIN AGENT IGNORE\n# Alteração humana dentro do bloco\n!/nao-apagar/\n# END AGENT IGNORE\n');
+  }
+  const skill = '.pbai4devs/skills/projeto/equipe-local/SKILL.md';
+  const skillFile = join(sourceRoot, skill);
+  mkdirSync(dirname(skillFile), { recursive: true });
+  writeFileSync(skillFile, '---\nname: equipe-local\ndescription: Conteúdo próprio.\n---\n\n# Equipe local\n');
+  const sourceIgnore = readFileSync(join(sourceRoot, '.gitignore'));
+  const sourceConfig = readFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf'));
+  const [example] = prepare({ sourceRoot, scenarios: [SCENARIOS[0]], initializeGit: false });
+  assert.equal(example.copied.catalogSnapshots.length, 4);
+  for (const [name, content] of Object.entries(originals)) {
+    assert.equal(readFileSync(join(sourceRoot, '.pbai4devs', name), 'utf8'), content);
+    assert.equal(readFileSync(join(example.root, '.agent-tests/testar-maturidade/original-catalogs', name), 'utf8'), content);
+    assert.doesNotMatch(readFileSync(join(example.root, '.pbai4devs', name), 'utf8'), /arquivo humano/);
+  }
+  for (const path of ['.pbai4devs/.gitignore', '.codex/.gitignore']) {
+    const original = readFileSync(join(sourceRoot, path));
+    const saved = example.copied.overriddenSnapshots.find(item => item.source === path);
+    assert.ok(saved, path);
+    assert.deepEqual(readFileSync(join(example.root, saved.snapshot)), original);
+    assert.match(original.toString('utf8'), /Alteração humana/);
+    assert.doesNotMatch(readFileSync(join(example.root, path), 'utf8'), /Alteração humana/);
+  }
+  assert.equal(readFileSync(join(example.root, skill), 'utf8'), readFileSync(skillFile, 'utf8'));
+  assert.deepEqual(readFileSync(join(sourceRoot, '.gitignore')), sourceIgnore);
+  assert.deepEqual(readFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf')), sourceConfig);
+  const report = JSON.parse(readFileSync(join(dirname(example.root), 'REPORT.json'), 'utf8'));
+  assert.deepEqual(report.copies[0].catalogSnapshots, example.copied.catalogSnapshots);
+  assert.match(readFileSync(join(example.root, 'README.md'), 'utf8'), /não um teste no projeto original/);
+  assert.equal(existsSync(state), withState);
+});
+
+test('arquiva arquivos substituídos mesmo quando o cliente não está selecionado', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|plano\n');
+  const files = ['.vscode/settings.json', '.github/workflows/legacy.yml'];
+  for (const path of files) put(path, `Conteúdo de equipe: ${path}\r\n`);
+  const [example] = prepareExamples({ sourceRoot: root, scenarios: [SCENARIOS.find(item => item.id === 'legado')], initializeGit: false });
+  for (const path of files) {
+    const saved = example.copied.overriddenSnapshots.filter(item => item.source === path);
+    assert.equal(saved.length, 1, path);
+    assert.deepEqual(readFileSync(join(example.root, saved[0].snapshot)), readFileSync(join(root, path)));
+  }
+});
+
+test('arquivo de cliente não selecionado com ancestral simbólico é recusado', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|plano\n');
+  const outside = mkdtempSync(join(root, 'outside-'));
+  writeFileSync(join(outside, 'settings.json'), 'Conteúdo externo.\n');
+  rmSync(join(root, '.vscode'), { recursive: true });
+  try { symlinkSync(outside, join(root, '.vscode'), 'dir'); }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) { t.skip('Links simbólicos indisponíveis.'); return; } throw error; }
+  assert.throws(() => prepareExamples({ sourceRoot: root, scenarios: [SCENARIOS.find(item => item.id === 'legado')], initializeGit: false }), /link/i);
+  assert.equal(readFileSync(join(outside, 'settings.json'), 'utf8'), 'Conteúdo externo.\n');
+});
+
+test('arquivos da fonte substituídos por fixtures têm cópias byte a byte', t => {
+  const { root, put } = fixture(t);
+  const files = ['README.md', 'Makefile', '.dockerignore', '.env.example', '.pbai4devs/state/README.md', '.pbai4devs/state/configuracao/ESTADO.md', '.vscode/settings.json', '.github/workflows/legacy.yml'];
+  const contents = Object.fromEntries(files.map(file => [file, `Conteúdo humano sintético: ${file}\r\n`]));
+  for (const [file, content] of Object.entries(contents)) put(file, content);
+  const cases = [SCENARIOS.find(item => item.id === 'app-configurada'), SCENARIOS.find(item => item.id === 'legado')];
+  const examples = prepareExamples({ sourceRoot: root, scenarios: cases, initializeGit: false });
+  for (const example of examples) {
+    for (const { source, snapshot } of example.copied.overriddenSnapshots) {
+      assert.equal(readFileSync(join(example.root, snapshot), 'utf8'), contents[source], source);
+      assert.equal(readFileSync(join(root, source), 'utf8'), contents[source], source);
+    }
+    for (const path of ['README.md', 'Makefile', '.pbai4devs/state/README.md', '.pbai4devs/state/configuracao/ESTADO.md']) assert.ok(example.copied.overriddenSnapshots.some(item => item.source === path), path);
+    const expected = example.id === 'legado' ? ['.vscode/settings.json', '.github/workflows/legacy.yml'] : ['.dockerignore', '.env.example'];
+    for (const path of expected) assert.ok(example.copied.overriddenSnapshots.some(item => item.source === path), path);
+  }
+});
+
 test('saída não pode sobrepor recursos de origem nem escapar das áreas de teste', t => {
   const { root } = fixture(t);
   const original = readFileSync(join(root, '.pbai4devs/espelhos.conf'), 'utf8');

package/.pbai4devs/scripts/verificar-configuracao/README.md

@@ -0,0 +1,22 @@
+---
+description: Confere os indicadores registrados antes da implementação.
+---
+
+# Verificar configuração
+
+```sh
+node .pbai4devs/scripts/executar-script/SCRIPT.mjs verificar-configuracao
+```
+
+Somente leitura: retorna `1` se o estado estiver ausente, inacessível,
+ambíguo ou com preparação ou configuração pendente. Retorna `0` e
+`verificar-evidencias` quando ambos os indicadores registram `concluido`.
+Para evitar ambiguidades, recusa chaves complexas e tags, âncoras, aliases ou
+mesclagens no topo do cabeçalho. Links simbólicos detectados são recusados;
+a leitura não é uma trava
+atômica contra mudanças simultâneas de caminhos.
+Não valida o YAML inteiro, a infraestrutura ou as provas; confira-os antes de
+escrever código. O comando não bloqueia alterações de quem ignore seu resultado.
+
+O estado legado é reconhecido sem migração; estados em conflito são recusados.
+Erros de uso retornam `2`.

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

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
+import { stateDirectory } from '../lib/state-path.mjs';
+
+const limit = 'O estado não comprova evidências nem impede um agente de escrever.';
+const blocked = motivo => ({ status: 'bloqueado', motivo, limite: limit });
+
+// Read only the two indicators; never print arbitrary state content.
+export function verifyConfiguration(root = projectRoot) {
+  requireNode();
+  try {
+    root = realpathSync(resolve(root));
+    const parts = `${stateDirectory(root)}/configuracao/ESTADO.md`.split('/');
+    let current = root; let info;
+    for (let index = 0; index < parts.length; index++) {
+      current = join(current, parts[index]);
+      info = lstatSync(current);
+      if (info.isSymbolicLink() || (index < parts.length - 1 && !info.isDirectory())) return blocked('estado-inseguro');
+    }
+    if (!info.isFile() || info.size > 1024 * 1024) return blocked('estado-invalido');
+    const text = readFileSync(current, 'utf8').replaceAll('\r\n', '\n');
+    const header = text.match(/^---\n([\s\S]*?)\n---(?:\n|$)/)?.[1];
+    if (header === undefined) return blocked('estado-invalido');
+    const values = {};
+    for (const line of header.split('\n')) {
+      if (!line.trim() || line.trimStart().startsWith('#') || /^[ \t]/.test(line)) continue;
+      // Explicit mapping keys and merge keys may hide duplicate indicators.
+      if (/^(?:\?|<<\s*:)/.test(line)) return blocked('estado-invalido');
+      const match = line.match(/^("(?:[^"\\]|\\.)*"|'(?:[^']|'')*'|[a-zA-Z_][a-zA-Z0-9_.-]*)[ \t]*:(.*)$/);
+      if (!match) return blocked('estado-invalido');
+      if (/^[!&*]/.test(match[2].trim())) return blocked('estado-invalido');
+      let key = match[1];
+      if (key.startsWith('"')) {
+        try { key = JSON.parse(key); } catch { return blocked('estado-invalido'); }
+      } else if (key.startsWith("'")) key = key.slice(1, -1).replaceAll("''", "'");
+      if (!['preparacao', 'configuracao_tecnica'].includes(key)) continue;
+      if (Object.hasOwn(values, key)) return blocked('estado-invalido');
+      const value = match[2].trim().match(/^(?:concluido|pendente|'(?:concluido|pendente)'|"(?:concluido|pendente)")(?:[ \t]+#.*)?$/)?.[0];
+      if (!value) return blocked('estado-invalido');
+      values[key] = value.replace(/[ \t]+#.*$/, '').replace(/^['"]|['"]$/g, '');
+    }
+    if (!Object.hasOwn(values, 'preparacao') || !Object.hasOwn(values, 'configuracao_tecnica')) return blocked('estado-invalido');
+    if (values.preparacao !== 'concluido' || values.configuracao_tecnica !== 'concluido') return blocked('configuracao-pendente');
+    return { status: 'verificar-evidencias', estado: values, limite: limit };
+  } catch (error) {
+    if (error.code === 'ENOENT' || error.code === 'ENOTDIR') return blocked('estado-ausente');
+    return blocked('estado-inacessivel-ou-inseguro');
+  }
+}
+
+export function main(args = process.argv.slice(2)) {
+  if (args.length) throw new Error('Uso: verificar-configuracao sem argumentos.');
+  const report = verifyConfiguration();
+  console.log(JSON.stringify(report));
+  return report.status === 'bloqueado' ? 1 : 0;
+}
+
+if (isMain(import.meta.url)) {
+  try { process.exitCode = main(); }
+  catch (error) { console.error(error.message); process.exitCode = 2; }
+}

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

@@ -0,0 +1,145 @@
+import assert from 'node:assert/strict';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import test from 'node:test';
+import { projectRoot } from '../../lib/runtime.mjs';
+import { verifyConfiguration } from '../SCRIPT.mjs';
+
+function fixture(t) {
+  const base = join(projectRoot, '.agent-tests'); mkdirSync(base, { recursive: true });
+  const root = mkdtempSync(join(base, 'config-gate-'));
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const write = (file, content) => {
+    const destination = join(root, file); mkdirSync(dirname(destination), { recursive: true });
+    writeFileSync(destination, content);
+  };
+  for (const file of ['lib/runtime.mjs', 'lib/state-path.mjs', 'lib/script-config.mjs', 'executar-script/SCRIPT.mjs', 'verificar-configuracao/SCRIPT.mjs']) {
+    const destination = join(root, '.pbai4devs/scripts', file);
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(join(projectRoot, '.pbai4devs/scripts', file), destination);
+  }
+  const state = (body, folder = 'state') => write(`.pbai4devs/${folder}/configuracao/ESTADO.md`, body);
+  const run = (...args) => {
+    const file = join(root, '.pbai4devs/scripts/verificar-configuracao/SCRIPT.mjs');
+    const result = spawnSync(process.execPath, [file, ...args], { encoding: 'utf8' });
+    assert.ifError(result.error);
+    return { ...result, report: result.stdout ? JSON.parse(result.stdout) : null };
+  };
+  return { root, state, write, run };
+}
+
+const document = (preparation, configuration) => `---\npreparacao: ${preparation}\nconfiguracao_tecnica: ${configuration}\ndocumentos:\n  prd: docs/PRD.md\n---\n\n# Estado\n`;
+
+test('bloqueia antes do código quando o estado está ausente ou pendente', t => {
+  const { root, state, run } = fixture(t);
+  assert.deepEqual(run().report.motivo, 'estado-ausente');
+  assert.equal(run().status, 1);
+  for (const [preparation, configuration] of [['pendente', 'pendente'], ['concluido', 'pendente'], ['pendente', 'concluido']]) {
+    state(document(preparation, configuration));
+    const result = run(); assert.equal(result.status, 1);
+    assert.equal(result.report.motivo, 'configuracao-pendente');
+    assert.equal(existsSync(join(root, 'src')), false);
+  }
+});
+
+test('aceita o modelo real e mantém provas da aplicação como verificação separada', t => {
+  const { root, state, run } = fixture(t);
+  const template = readFileSync(join(projectRoot, '.pbai4devs/templates/configuracao/TEMPLATE.md'), 'utf8');
+  state(template); assert.equal(run().report.motivo, 'configuracao-pendente');
+  state(template.replace('preparacao: pendente', 'preparacao: concluido')
+    .replace('configuracao_tecnica: pendente', 'configuracao_tecnica: concluido'));
+  assert.equal(run().report.status, 'verificar-evidencias');
+  assert.equal(existsSync(join(root, 'src')), false);
+});
+
+test('indicadores concluídos exigem revisão adicional de evidências e não alteram Git', t => {
+  const { root, state, write, run } = fixture(t);
+  state(document('"concluido" # aprovado', "'concluido'"));
+  write('.gitignore', 'node_modules/\n'); write('AGENTS.md', '# Instruções humanas\n');
+  assert.equal(spawnSync('git', ['init', '--quiet', root]).status, 0);
+  assert.equal(spawnSync('git', ['-C', root, 'add', '.gitignore', 'AGENTS.md']).status, 0);
+  const index = readFileSync(join(root, '.git/index'));
+  const statePath = join(root, '.pbai4devs/state/configuracao/ESTADO.md');
+  const original = readFileSync(statePath), ignore = readFileSync(join(root, '.gitignore'));
+  const result = run(); assert.equal(result.status, 0);
+  assert.equal(result.report.status, 'verificar-evidencias');
+  assert.match(result.report.limite, /não comprova evidências/);
+  assert.deepEqual(readFileSync(statePath), original);
+  assert.deepEqual(readFileSync(join(root, '.git/index')), index);
+  assert.deepEqual(readFileSync(join(root, '.gitignore')), ignore);
+  assert.equal(existsSync(join(root, 'src')), false);
+});
+
+test('recusa indicadores ausentes, desconhecidos, duplicados e não expõe valores', t => {
+  const { state, run } = fixture(t);
+  const secret = 'SENSITIVE_VALUE_47849';
+  for (const value of [
+    'preparacao: concluido',
+    'preparacao: concluido\nconfiguracao_tecnica: ausente',
+    'preparacao: concluido\npreparacao: pendente\nconfiguracao_tecnica: concluido',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\n"configuracao_tecnica": pendente',
+    "'preparacao': concluido\npreparacao: pendente\nconfiguracao_tecnica: concluido",
+    'preparacao: concluido\n"prepara\\u0063ao": pendente\nconfiguracao_tecnica: concluido',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\n!!str configuracao_tecnica: pendente',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\npadrao: &base { configuracao_tecnica: pendente }',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\npadrao: *base',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\npadrao: !!str valor',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\n<<: *base',
+    'preparacao: concluido\nconfiguracao_tecnica: concluido\n? configuracao_tecnica\n: pendente',
+    `preparacao: concluido\nconfiguracao_tecnica: ${secret}`,
+    'preparacao: concluido\nconfiguracao_tecnica: true',
+  ]) {
+    state(`---\n${value}\n---\n# Estado\n`);
+    const result = run(); assert.equal(result.status, 1);
+    assert.equal(result.report.motivo, 'estado-invalido');
+    assert.ok(!result.stdout.includes(secret)); assert.ok(!result.stderr.includes(secret));
+  }
+  state('preparacao: concluido\nconfiguracao_tecnica: concluido\n');
+  assert.equal(run().report.motivo, 'estado-invalido');
+  state('---\n"preparacao": concluido\n\'configuracao_tecnica\': concluido\n---\n# Estado\n');
+  assert.equal(run().report.status, 'verificar-evidencias');
+});
+
+test('aceita estado legado e recusa coexistência de árvores de estado', t => {
+  const { state, run } = fixture(t);
+  state(document('concluido', 'concluido'), 'estado');
+  assert.equal(run().report.status, 'verificar-evidencias');
+  state(document('concluido', 'concluido'));
+  const result = run(); assert.equal(result.status, 1);
+  assert.equal(result.report.motivo, 'estado-inacessivel-ou-inseguro');
+});
+
+test('não segue link humano em arquivo ou pasta de estado', t => {
+  const { root, state, run } = fixture(t);
+  const outside = join(root, 'fora'); mkdirSync(outside);
+  const target = join(outside, 'ESTADO.md'); writeFileSync(target, document('concluido', 'concluido'));
+  const directory = join(root, '.pbai4devs/state/configuracao'); mkdirSync(directory, { recursive: true });
+  try { symlinkSync(target, join(directory, 'ESTADO.md')); }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOSYS'].includes(error.code)) { t.skip('Sem permissão para links.'); return; } throw error; }
+  assert.equal(run().report.motivo, 'estado-inseguro');
+  assert.equal(readFileSync(target, 'utf8'), document('concluido', 'concluido'));
+  unlinkSync(join(directory, 'ESTADO.md')); rmdirSync(directory);
+  symlinkSync(outside, directory, process.platform === 'win32' ? 'junction' : 'dir');
+  assert.equal(run().report.motivo, 'estado-inseguro');
+  assert.equal(readFileSync(target, 'utf8'), document('concluido', 'concluido'));
+});
+
+test('exige Node e rejeita argumentos extras sem ler outro projeto', t => {
+  const { root, run } = fixture(t);
+  const result = run('--root', root); assert.equal(result.status, 2);
+  assert.match(result.stderr, /sem argumentos/);
+  assert.equal(verifyConfiguration(root).status, 'bloqueado');
+});
+
+test('seletor de scripts propaga bloqueio e exige revisão de evidências', t => {
+  const { root, state } = fixture(t);
+  const selector = join(root, '.pbai4devs/scripts/executar-script/SCRIPT.mjs');
+  const execute = () => spawnSync(process.execPath, [selector, 'verificar-configuracao'], { cwd: root, encoding: 'utf8' });
+  state(document('concluido', 'pendente'));
+  const pending = execute(); assert.ifError(pending.error); assert.equal(pending.status, 1);
+  assert.match(pending.stdout, /"motivo":"configuracao-pendente"/);
+  state(document('concluido', 'concluido'));
+  const recorded = execute(); assert.ifError(recorded.error); assert.equal(recorded.status, 0);
+  assert.match(recorded.stdout, /"status":"verificar-evidencias"/);
+});

package/.pbai4devs/skills/desenvolvimento/implementar-backend/SKILL.md

@@ -5,9 +5,21 @@ description: Implementa mudanças de backend com contratos, dados e provas de co
 
 # Implementar backend
 
-Siga a spec e o plano aprovados, os contratos e a stack existentes. Esclareça
-dúvidas sobre entradas, saídas, persistência,
-compatibilidade e falhas antes de decidir. Altere somente o escopo atribuído.
+Siga o escopo aprovado, os contratos e a stack existentes. Ao implementar uma
+spec, confirme spec e plano aprovados e, antes de alterar código, execute
+`node .pbai4devs/scripts/executar-script/SCRIPT.mjs verificar-configuracao`.
+Se o estado estiver ausente, inválido ou pendente, ou faltar prova obrigatória,
+pare e informe o responsável. Saída zero ainda exige conferir as evidências.
+Siga a ordem e as pré-condições já acordadas em
+[implementar-spec](../../specs/implementar-spec/SKILL.md), sem reiniciar o fluxo
+nem pedir novamente aprovações já dadas.
+
+Em correção avulsa autorizada de projeto existente, preserve suas decisões e
+use `preparar-dev` quando necessário, sem inventar spec ou estado. Uma tarefa
+que cite uma spec ou esteja coberta por seu escopo é tarefa de spec, mesmo
+sendo correção pontual; não a trate como avulsa. Esclareça dúvidas sobre
+entradas, saídas, persistência, compatibilidade e falhas antes de decidir.
+Altere somente o escopo atribuído.
 
 Verifique validação de entrada, autorização por recurso e isolamento de dados.
 Considere limites, concorrência, repetição, timeout, migração e recuperação

package/.pbai4devs/skills/desenvolvimento/implementar-frontend/SKILL.md

@@ -5,9 +5,21 @@ description: Implementa interfaces web conforme a spec, o design e as provas de
 
 # Implementar frontend
 
-Siga a spec e o plano aprovados, o design e os componentes existentes.
-Esclareça comportamento, conteúdo e acessibilidade
-quando faltarem decisões; não escolha framework nem crie telas fora do escopo.
+Siga o escopo aprovado, o design e os componentes existentes. Ao implementar
+uma spec, confirme spec e plano aprovados e, antes de alterar código, execute
+`node .pbai4devs/scripts/executar-script/SCRIPT.mjs verificar-configuracao`.
+Se o estado estiver ausente, inválido ou pendente, ou faltar prova obrigatória,
+pare e informe o responsável. Saída zero ainda exige conferir as evidências.
+Siga a ordem e as pré-condições já acordadas em
+[implementar-spec](../../specs/implementar-spec/SKILL.md), sem reiniciar o fluxo
+nem pedir novamente aprovações já dadas.
+
+Em correção avulsa autorizada de projeto existente, preserve suas decisões e
+use `preparar-dev` quando necessário, sem inventar spec ou estado. Uma tarefa
+que cite uma spec ou esteja coberta por seu escopo é tarefa de spec, mesmo
+sendo correção pontual; não a trate como avulsa. Esclareça comportamento,
+conteúdo e acessibilidade quando faltarem decisões; não escolha framework nem
+crie telas fora do escopo.
 
 Considere estados de carregamento, vazio, erro e sucesso; navegação por teclado,
 semântica acessível e diferentes tamanhos de tela. Preserve contratos com o

package/.pbai4devs/skills/git/git-diff/SKILL.md

@@ -6,4 +6,6 @@ description: Examina e resume alterações Git.
 # git-diff
 
 Examine os diffs preparados e não preparados conforme o pedido, incluindo
-arquivos não rastreados quando relevantes. Não altere arquivos.
+arquivos não rastreados quando relevantes. Execute consultas com
+`GIT_OPTIONAL_LOCKS=0` no ambiente do subprocesso para evitar atualizar o índice;
+não altere arquivos.

package/.pbai4devs/skills/git/git-status/SKILL.md

@@ -6,4 +6,5 @@ description: Inspeciona o estado do repositório e das branches locais e remotas
 # git-status
 
 Mostre branch, alterações preparadas e não preparadas, arquivos não rastreados e
-divergência do upstream. Não altere arquivos.
+divergência do upstream. Execute a consulta com `GIT_OPTIONAL_LOCKS=0` no
+ambiente do subprocesso para evitar atualizar o índice; não altere arquivos.

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

@@ -42,20 +42,25 @@ aprovações já dadas.
 2. Prepare as ferramentas definidas em `.pbai4devs/tools/<nome>/TOOL.json` com
    `preparar-ferramentas`; confira versões e compatibilidade com SO/arquitetura.
    Reutilize instalações e lockfiles; não repita init nem troque a stack.
-3. Aplique a [estrutura e o ambiente obrigatórios][estrutura],
-   preenchendo os modelos de Makefile, Compose e dockerignore. Configure os
-   serviços reais, healthchecks, portas, volumes e comandos da tecnologia.
+3. Aplique a [estrutura e o ambiente obrigatórios][estrutura], preenchendo os
+   modelos de Makefile, Compose e dockerignore. Configure os serviços de
+   infraestrutura necessários, healthchecks, portas, volumes e comandos.
+   Antes de concluir a configuração, não implemente código da aplicação;
+   `src/` e `tests/` podem existir vazios ou conter apenas configuração.
 4. Configure VS Code e recomende EditorConfig, sem regras conflitantes.
    Termine `.gitignore` com o modelo CUSTOM IGNORE e os padrões da tecnologia;
    confirme que templates, scripts, testes e fixtures continuam versionáveis.
 5. Documente versões, estrutura, setup, comandos, origem do template/init e
    decisões no README/estado. Use `atualizar-documentacao` para contribuição,
    configuração e ADRs aplicáveis. Preserve arquivos e convenções existentes.
-6. Use `verificar-trabalho`: valide Compose, build, saúde dos serviços e testes
-   acordados; confira a estrutura com `inspecionar-projeto --check`.
-   Com aplicação, prove o fluxo real no navegador/desktop conforme
-   seu tipo; sem aplicação, registre a prova funcional pendente. Marque
-   `configuracao_tecnica: concluido` somente com evidência da configuração.
+6. Use `verificar-trabalho`: valide runtime, configuração Compose e saúde dos
+   serviços de infraestrutura necessários; confira a estrutura com
+   `inspecionar-projeto --check`. Se Docker ou outra dependência obrigatória
+   estiver inacessível, mantenha a configuração pendente e informe a prova
+   faltante. Sem aplicação, registre build, saúde e fluxo dela como pendentes;
+   não os reporte como aprovados. Com aplicação existente, prove o fluxo real
+   conforme seu tipo. Marque `configuracao_tecnica: concluido` somente com
+   evidência da configuração prévia e dos serviços aplicáveis.
 
 Após alterações técnicas, conclua `revisar-entrega`. Sincronize apontamentos
 somente quando recursos dos agentes forem alterados.

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

@@ -17,7 +17,9 @@ Faça apenas as perguntas que impedem avançar.
 Continue o trabalho já autorizado; não reinicie fases concluídas nem apresente
 suposições como aprovações.
 
-Projeto novo segue preparação → PRD → UX/design → configuração → specs →
-implementação → revisão. Projeto existente parte de suas evidências atuais;
+Projeto novo segue preparação → PRD → UX → design (arquitetura e tecnologia) →
+roadmap → spec aprovada → plano aprovado → configuração técnica → implementação
+→ revisão. UX pode ser não aplicável com justificativa aprovada.
+Projeto existente parte de suas evidências atuais;
 instalar o kit não autoriza recriar documentos ou substituir decisões.
 Se não houver pendências no escopo, diga isso claramente.

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

@@ -18,8 +18,20 @@ antes de implementar.
    seus IDs/revisões. Não invente uma solução já atendida por elas.
 3. Depois da aprovação, crie ou retome `feature/<slug-da-spec>` de `develop`.
    Se faltar `develop`, use `main` quando seguro; sem base/remoto, combine como
-   proceder. Preserve alterações. Registre a aprovação no roadmap e confira a
-   configuração real; complete-a com `configurar-projeto` antes de codificar.
+   proceder. Preserve alterações. Registre a aprovação no roadmap e complete a
+   configuração real com `configurar-projeto` antes de codificar.
+   Antes de qualquer patch de código da spec, execute:
+
+   ```sh
+   node .pbai4devs/scripts/executar-script/SCRIPT.mjs verificar-configuracao
+   ```
+
+   Releia o estado e confira as evidências da infraestrutura obrigatória. Se o
+   estado estiver ausente, inválido ou pendente, ou uma prova falhar, pare sem
+   escrever código; retome quando o impedimento for resolvido. Código zero do
+   script só confirma o estado registrado, não comprova as evidências nem impede
+   escrita por um agente que ignore o resultado. Não peça novamente aprovações
+   já concedidas.
 4. Use o modelo de tarefas em `<documentos.tarefas>/<slug-da-spec>/TASKS.md`.
    Vincule spec/release e registre tarefas, dependências, critérios e evidências.
    Atualize `[ ]`, `[-]` e `[x]` ao avançar; conclusão exige prova. Ao retomar,

package/CHANGELOG.md

@@ -4,6 +4,23 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.24 — 2026-11-14
+
+- Preserva catálogos, configuração e blocos existentes sem comprovação de
+  propriedade, inclusive ao usar `--force` ou sincronização direta.
+- Mantém o estado coerente quando a sincronização atualiza saídas gerenciadas.
+- Acrescenta testes de colisão, arquivos idênticos e preservação do índice Git.
+
+## 0.0.23 — 2026-11-13
+
+- Corrige a resolução de destinos inexistentes diretamente sob a raiz.
+- Aceita aliases temporários confiáveis do macOS e recusa destinos que
+  atravessam links humanos, inclusive os indicados por variáveis de ambiente.
+- Orienta roadmap e spec antes da configuração técnica e acrescenta uma
+  verificação do estado antes da implementação.
+- Aplica a verificação também aos especialistas e orienta consultas Git que
+  preservam os bytes do índice.
+
 ## 0.0.22 — 2026-11-13
 
 - Descoberta de skills do Codex sem duplicação, com alternativa segura quando a

package/docs/guides/cli.md

@@ -125,5 +125,14 @@ do kit. Conteúdo humano não é substituído por `--force`.
 
 `doctor` verifica o kit, não o produto inteiro. `next` pode terminar com
 sucesso enquanto orienta uma etapa ainda pendente.
+Após produto e design, ele usa os caminhos de roadmap e specs registrados no
+estado. Para orientar uma spec existente, exige uma única referência aberta
+`[ ]` ou em andamento `[-]` no roadmap. Com mais de uma spec, entrega encerrada,
+vínculo ausente ou leitura ambígua, orienta a revisão do roadmap. Um status
+declarado não comprova aprovação: a skill confere decisões e evidências. Com uma
+spec aberta e declarada aprovada, `implementar-spec` verifica o plano antes de
+encaminhar a configuração técnica; `next` não presume aprovação do plano.
+Se o inventário for truncado, `next` orienta inspeção manual, sem escolher uma
+fase ou presumir que um projeto existente está vazio.
 
 [Wiki](../README.md) · [Solução de problemas](troubleshooting.md)