@pathbit/agentdevkit 0.0.20 → 0.0.22

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

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, resolve, sep } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { isMain, projectRoot, requireNode } from '../lib/runtime.mjs';
@@ -9,6 +9,7 @@ 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';
+import { nativePathBoundary } from '../lib/native-paths.mjs';
 
 const assets = join(dirname(fileURLToPath(import.meta.url)), 'assets');
 const owner = 'testar-maturidade';
@@ -36,6 +37,39 @@ function noLinks(root, target) {
   }
 }
 
+// The child binds its cwd to the verified parent directory. A swapped parent
+// changes the inode or real path before the child can create the new directory.
+const createDirectoryScript = `const fs=require('node:fs');
+const [name,expected,dev,ino]=process.argv.slice(1);
+const info=fs.statSync('.');
+if(fs.realpathSync('.')!==expected || String(info.dev)!==dev || String(info.ino)!==ino) process.exit(73);
+try { fs.mkdirSync(name); } catch(error) { if(error.code==='EEXIST') process.exit(17); throw error; }
+`;
+function createChild(root, parent, name, { allowExisting = false } = {}) {
+  if (!name || name === '.' || name === '..' || basename(name) !== name) fail('Nome de diretório inválido.');
+  noLinks(root, parent);
+  const info = stat(parent);
+  if (!info?.isDirectory() || info.isSymbolicLink()) fail('Diretório ancestral inválido.');
+  const canonical = realpathSync(parent), inside = relative(root, canonical);
+  if (isAbsolute(inside) || inside === '..' || inside.startsWith(`..${sep}`)) fail('Diretório ancestral fora do projeto.');
+  const env = { ...process.env }; delete env.NODE_TEST_CONTEXT;
+  const result = spawnSync(process.execPath, ['-e', createDirectoryScript, name, canonical, String(info.dev), String(info.ino)], { cwd: canonical, env, encoding: 'utf8', timeout: 30000, windowsHide: true, shell: false });
+  if (result.error || result.status !== 0 && !(allowExisting && result.status === 17)) fail(`Não foi possível criar diretório exclusivo: ${result.error?.message || result.stderr?.trim() || result.status}`);
+  noLinks(root, join(parent, name));
+  const output = stat(join(parent, name));
+  if (!output?.isDirectory() || output.isSymbolicLink()) fail('Diretório de saída inválido.');
+}
+function ensureDirectories(root, target) {
+  let current = root;
+  for (const part of relative(root, target).split(sep).filter(Boolean)) {
+    const next = join(current, part), info = stat(next);
+    if (!info) createChild(root, current, part, { allowExisting: true });
+    else if (!info.isDirectory() || info.isSymbolicLink()) fail('Diretório ancestral inválido ou link simbólico.');
+    noLinks(root, next);
+    current = next;
+  }
+}
+
 export const SCENARIOS = [
   { id: 'somente-agentes', title: 'Somente agentes', expected: 'preparacao', complete: false, app: false, planning: 'none', note: 'Recursos compartilhados, sem produto ou aplicação.' },
   { id: 'descoberta', title: 'Descoberta de produto', expected: 'descoberta', complete: false, app: false, planning: 'draft', note: 'PRD em rascunho; nenhuma stack é iniciada.' },
@@ -63,11 +97,28 @@ export function registeredRoots(root) {
 
 export function resourceTargets(root, source, kind = 'skills') {
   const rows = manifest(root).split(/\r?\n/).filter(line => line && !line.startsWith('#')).map(line => line.split('|'));
-  const targets = [];
+  const targets = [], suppressed = new Set();
+  for (const [type, fallback, primary, resource] of rows) {
+    if (type !== 'fallback' || resource !== kind) continue;
+    const primaryRow = rows.find(([entry, target]) => entry === 'agente' && target === primary);
+    const fallbackRow = rows.find(([entry, target]) => entry === 'agente' && target === fallback);
+    if (!primaryRow || !fallbackRow) fail(`Fallback sem cliente: ${fallback}`);
+    const primaryFormat = rows.find(([entry, target, scope]) => entry === 'formato' && target === primary && scope === kind)?.[3] || primaryRow[2] || 'agrupado';
+    const primaryTarget = `${primary}/${resourcePath(source, kind, primaryFormat)}`;
+    const boundary = nativePathBoundary(root, primaryTarget, [], { preserveRootAliases: true });
+    const info = boundary ? null : stat(join(root, primaryTarget));
+    if (boundary || (info && !info.isFile())) {
+      suppressed.add(primaryTarget);
+      targets.push(`${fallback}/${resourcePath(source, kind, fallbackRow[2] || 'agrupado')}`);
+    }
+  }
   for (const [type, agent, layout = 'agrupado'] of rows) {
     if (type !== 'agente') continue;
     const override = rows.find(([entry, target, resource]) => entry === 'formato' && target === agent && resource === kind)?.[3];
-    targets.push(`${agent}/${resourcePath(source, kind, override || layout)}`);
+    if (override === 'nenhum') continue;
+    let target = `${agent}/${resourcePath(source, kind, override || layout)}`;
+    if (agent === '.gemini' && kind === 'commands') target = target.replace(/\.md$/, '.toml');
+    if (!suppressed.has(target)) targets.push(target);
   }
   for (const [type, target, origin] of rows) if (type === 'nativo' && origin === source) targets.push(target);
   return [...new Set(targets)];
@@ -139,29 +190,6 @@ export function copyAgentStructure(sourceRoot, destination) {
   return { roots, copiedFiles: files.length, skipped, files, sourceDigest, entrypoints, toolDefinitions: files.filter(file => /^\.pbai4devs\/tools\/[^/]+\/TOOL\.json$/.test(file)).length };
 }
 
-function ownership(root, file, expectedId) {
-  if (stat(root)?.isSymbolicLink()) return false;
-  const path = join(root, file);
-  if (!existsSync(path)) return false;
-  const item = lstatSync(path);
-  if (!item.isFile() || item.isSymbolicLink()) return false;
-  try { const data = json(path); return data.owner === owner && (!expectedId || data.id === expectedId); }
-  catch { return false; }
-}
-
-function ensureOutput(output) {
-  if (existsSync(output) && lstatSync(output).isSymbolicLink()) fail('A pasta de exemplos não pode ser um link.');
-  for (const name of [suiteMarker, 'README.md', 'REPORT.json', '.gitignore']) {
-    const item = stat(join(output, name));
-    if (item && (!item.isFile() || item.isSymbolicLink())) fail(`Arquivo de saída deve ser regular: ${name}`);
-  }
-  if (existsSync(output) && [suiteMarker, 'README.md', 'REPORT.json'].some(name => existsSync(join(output, name)))
-    && !ownership(output, suiteMarker)) fail('Índice de exemplos existente não pertence a este gerador.');
-  if (existsSync(join(output, 'REPORT.json')) && !ownership(output, 'REPORT.json')) fail('Relatório de exemplos existente não pertence a este gerador.');
-  if (existsSync(join(output, '.gitignore')) && readFileSync(join(output, '.gitignore'), 'utf8') !== outputIgnore) fail('Ignore de exemplos existente não pertence a este gerador.');
-  mkdirSync(output, { recursive: true });
-}
-
 function planning(root, scenario) {
   const stateRoot = stateDirectory(root);
   const state = `${stateRoot}/configuracao/ESTADO.md`;
@@ -228,6 +256,13 @@ function application(root, scenario) {
     preserved.push(server, test, 'config/legacy.json', '.github/workflows/legacy.yml', '.vscode/settings.json', 'Makefile', 'package.json');
   }
   if (scenario.configured) {
+    // Published packages and existing projects need not contain these files;
+    // create only the missing synthetic fixtures, never replace copied content.
+    for (const [file, content] of Object.entries({
+      '.gitignore': '# Arquivos temporários do cenário sintético.\nnode_modules/\n.agent-tests/\n',
+      '.gitattributes': '* text=auto\n',
+      '.editorconfig': 'root = true\n\n[*]\ncharset = utf-8\nend_of_line = lf\ninsert_final_newline = true\n',
+    })) if (!stat(join(root, file))) write(root, file, content);
     write(root, '.dockerignore', '.git\n.agent-tests\nnode_modules\n');
     write(root, '.env.example', 'PORT=3000\n');
     write(root, 'Dockerfile', 'FROM node:24-alpine\nWORKDIR /app\nCOPY package.json ./\nCOPY src ./src\nEXPOSE 3000\nCMD ["node", "src/server.mjs"]\n');
@@ -242,31 +277,37 @@ function gitInit(root) {
   if (result.error || result.status !== 0) fail(`Git init: ${result.error?.message || result.stderr}`);
 }
 
-export function prepareExamples({ sourceRoot = projectRoot, outputRoot = defaultOutput(sourceRoot), scenarios = SCENARIOS, initializeGit = true, renderResources = prepareResources } = {}) {
-  requireNode(); sourceRoot = realpathSync(resolve(sourceRoot)); outputRoot = resolve(outputRoot);
-  const outputPath = portable(relative(sourceRoot, outputRoot));
+export function prepareExamples({ sourceRoot = projectRoot, outputRoot, scenarios = SCENARIOS, initializeGit = true, renderResources = prepareResources } = {}) {
+  requireNode(); sourceRoot = realpathSync(resolve(sourceRoot));
+  const base = resolve(outputRoot ?? defaultOutput(sourceRoot));
+  const outputPath = portable(relative(sourceRoot, base));
   if (!(outputPath === 'examples/generated' || outputPath.startsWith('examples/generated/')
     || outputPath === 'tmp/examples' || outputPath.startsWith('tmp/examples/') || outputPath.startsWith('.agent-tests/'))) fail('Saída permitida somente em examples/generated, tmp/examples ou descendente de .agent-tests.');
-  noLinks(sourceRoot, outputRoot);
+  noLinks(sourceRoot, base);
   const ids = new Set();
+  if (!Array.isArray(scenarios) || !scenarios.length) fail('Selecione pelo menos um cenário.');
   for (const scenario of scenarios) {
     if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(scenario.id) || ids.has(scenario.id)) fail('Cenários devem ter IDs únicos e seguros.');
     ids.add(scenario.id);
   }
-  ensureOutput(outputRoot);
-  for (const scenario of scenarios) {
-    const destination = join(outputRoot, scenario.id);
-    noLinks(sourceRoot, destination);
-    if (existsSync(destination) && !ownership(destination, marker, scenario.id)) fail(`Diretório existente não é gerenciado: ${destination}`);
+  if (outputRoot !== undefined && stat(base)) fail(`Pasta de saída já existe; escolha um destino novo: ${base}`);
+  if (outputRoot !== undefined) {
+    for (let parent = dirname(base); parent !== sourceRoot && parent.startsWith(sourceRoot + sep); parent = dirname(parent)) {
+      if (stat(join(parent, suiteMarker)) || stat(join(parent, marker))) fail('Saída não pode ficar dentro de uma execução anterior.');
+    }
   }
+  const parent = outputRoot === undefined ? base : dirname(base);
+  ensureDirectories(sourceRoot, parent);
+  const name = outputRoot === undefined ? `maturity-${randomUUID()}` : basename(base);
+  createChild(sourceRoot, parent, name);
+  outputRoot = join(parent, name);
   write(outputRoot, suiteMarker, JSON.stringify({ owner, version: 1 }, null, 2) + '\n');
   write(outputRoot, '.gitignore', outputIgnore);
-  rmSync(join(outputRoot, 'REPORT.json'), { force: true });
   writeIndex(outputRoot, [], 'preparing');
   const examples = [];
   for (const scenario of scenarios) {
     const destination = join(outputRoot, scenario.id);
-    rmSync(destination, { recursive: true, force: true }); mkdirSync(destination, { recursive: true });
+    mkdirSync(destination);
     write(destination, marker, JSON.stringify({ owner, version: 1, id: scenario.id }, null, 2) + '\n');
     const copied = copyAgentStructure(sourceRoot, destination);
     planning(destination, scenario);
@@ -283,8 +324,8 @@ export function prepareExamples({ sourceRoot = projectRoot, outputRoot = default
 
 function writeIndex(outputRoot, examples, status) {
   const rows = examples.map(item => `| [${item.id}](${item.id}/README.md) | ${item.expected} | ${item.status || 'prepared'} |`).join('\n');
-  const progress = status === 'preparing' ? '\nPreparação em andamento; os resultados anteriores foram invalidados.\n' : '';
-  write(outputRoot, 'README.md', document('Exemplos de maturidade', `Projetos sintéticos com cópias locais da estrutura de agentes.\nNenhum resultado certifica produção, revisão humana ou outros sistemas operacionais.\n${progress}\n| Cenário | Nível esperado | Resultado |\n| --- | --- | --- |${rows ? '\n' + rows : ''}\n\nRelatório: \`REPORT.json\`. Logs e evidências por projeto ficam em \`.agent-tests/\`.\nPastas sem marcador deste gerador são preservadas.\n`, `status: ${status}\n`));
+  const progress = status === 'preparing' ? '\nPreparação em andamento nesta execução.\n' : '';
+  write(outputRoot, 'README.md', document('Exemplos de maturidade', `Projetos sintéticos com cópias locais da estrutura de agentes.\nNenhum resultado certifica produção, revisão humana ou outros sistemas operacionais.\n${progress}\n| Cenário | Nível esperado | Resultado |\n| --- | --- | --- |${rows ? '\n' + rows : ''}\n\nRelatório: \`REPORT.json\`. Logs e evidências por projeto ficam em \`.agent-tests/\`.\nCada execução usa uma pasta nova e preserva as anteriores.\n`, `status: ${status}\n`));
 }
 
 function hashes(root, files) { return Object.fromEntries(files.map(file => [file, digest(readFileSync(join(root, file)))])); }
@@ -453,7 +494,7 @@ export function testExample(example) {
 export function runExamples(options = {}) {
   const examples = prepareExamples(options);
   const results = examples.map(example => { const result = testExample(example); console.log(`${example.id}=${result.status}${result.error ? ': ' + result.error : ''}`); return result; });
-  const outputRoot = resolve(options.outputRoot || defaultOutput(options.sourceRoot || projectRoot));
+  const outputRoot = dirname(examples[0].root);
   const report = { owner, version: 1, status: results.every(item => item.status === 'passed') ? 'passed' : 'failed', platform: process.platform, arch: process.arch, node: process.version, results, limits: ['Provas reais somente das operações descritas e APIs locais.', 'Pareceres do gate são simulações explícitas, sem revisão humana.', 'Não certifica produção nem sistemas operacionais não executados.'] };
   write(outputRoot, 'REPORT.json', JSON.stringify(report, null, 2) + '\n');
   writeIndex(outputRoot, examples.map(example => ({ ...example, status: results.find(result => result.id === example.id).status })), report.status);
@@ -462,15 +503,16 @@ export function runExamples(options = {}) {
 
 export function main(args = process.argv.slice(2)) {
   requireNode(); const [mode = 'help', ...rest] = args;
-  if (['help', '--help', '-h'].includes(mode)) { console.log('Uso: testar-maturidade prepare|run [--case <id>]. Exemplos gerados em examples/generated; apenas pastas marcadas são substituídas.'); return 0; }
+  if (['help', '--help', '-h'].includes(mode)) { console.log('Uso: testar-maturidade prepare|run [--case <id>]. Cada execução cria uma nova pasta em examples/generated.'); return 0; }
   if (!['prepare', 'run'].includes(mode)) fail('Use prepare ou run.');
   let scenarios = SCENARIOS;
   if (rest.length) {
     if (rest.length !== 2 || rest[0] !== '--case') fail('Use --case <id>.');
     scenarios = SCENARIOS.filter(item => item.id === rest[1]); if (!scenarios.length) fail('Cenário desconhecido.');
   }
-  if (mode === 'prepare') { const examples = prepareExamples({ scenarios }); console.log(`prepared=${examples.length}`); return 0; }
-  return runExamples({ scenarios }).report.status === 'passed' ? 0 : 1;
+  if (mode === 'prepare') { const examples = prepareExamples({ scenarios }); console.log(`prepared=${examples.length}\noutput=${dirname(examples[0].root)}`); return 0; }
+  const result = runExamples({ scenarios }); console.log(`output=${result.outputRoot}`);
+  return result.report.status === 'passed' ? 0 : 1;
 }
 
 if (isMain(import.meta.url)) {

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

@@ -1,7 +1,8 @@
 import assert from 'node:assert/strict';
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { spawnSync } from 'node:child_process';
+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';
@@ -55,21 +56,61 @@ test('copia recursos e configurações, excluindo payloads, caches e segredos',
   assert.deepEqual(result.roots, ['.pbai4devs', '.codex', '.github', '.agents', '.agent', '.gemini', '.vscode']);
 });
 
-test('regeneração preserva pastas alheias e recusa sobrescrevê-las', t => {
+test('destino explícito existente é recusado sem alterar projetos humanos ou gerados', t => {
   const { root, put, outputRoot } = fixture(t);
   put('examples/generated/anotacoes/keep.txt', 'preservado');
   put('examples/README.md', 'Guia humano.');
   const options = { sourceRoot: root, outputRoot, scenarios: [SCENARIOS[0]], initializeGit: false };
-  prepareExamples(options); prepareExamples(options);
+  assert.throws(() => prepareExamples(options), /saída já existe/);
   assert.equal(readFileSync(join(outputRoot, 'anotacoes/keep.txt'), 'utf8'), 'preservado');
   assert.equal(readFileSync(join(root, 'examples/README.md'), 'utf8'), 'Guia humano.');
-  put('examples/generated/descoberta/keep.txt', 'humano');
-  assert.throws(() => prepareExamples({ ...options, scenarios: [SCENARIOS[1]] }), /não é gerenciado/);
-  assert.equal(readFileSync(join(outputRoot, 'descoberta/keep.txt'), 'utf8'), 'humano');
-  assert.throws(() => prepareExamples({ ...options, scenarios: [{ ...SCENARIOS[0], id: '../outside' }] }), /IDs únicos e seguros/);
+  const output = join(outputRoot, 'nova-execucao');
+  const [example] = prepareExamples({ ...options, outputRoot: output });
+  writeFileSync(join(example.root, 'anotacao-humana.txt'), 'não apagar');
+  const report = readFileSync(join(output, 'REPORT.json'));
+  assert.throws(() => prepareExamples({ ...options, outputRoot: output, scenarios: [SCENARIOS[1]] }), /saída já existe/);
+  assert.throws(() => prepareExamples({ ...options, outputRoot: join(example.root, 'nova'), scenarios: [SCENARIOS[1]] }), /execução anterior/);
+  assert.deepEqual(readFileSync(join(output, 'REPORT.json')), report);
+  assert.equal(readFileSync(join(example.root, 'anotacao-humana.txt'), 'utf8'), 'não apagar');
+  assert.throws(() => prepareExamples({ ...options, outputRoot: join(outputRoot, 'invalid'), scenarios: [{ ...SCENARIOS[0], id: '../outside' }] }), /IDs únicos e seguros/);
+  assert.equal(existsSync(join(outputRoot, 'invalid')), false);
 });
 
-test('destino padrão redefine apenas relatório próprio e mantém resultados fora do Git', t => {
+test('troca de ancestral por symlink antes da criação não escreve no destino externo', t => {
+  const { root, outputRoot } = fixture(t);
+  const outside = mkdtempSync(join(dirname(root), 'maturity-outside-'));
+  t.after(() => rmSync(outside, { recursive: true, force: true }));
+  mkdirSync(outputRoot, { recursive: true });
+  const externalSentinel = join(outside, 'sentinel.txt');
+  writeFileSync(externalSentinel, 'externo preservado\n');
+  const linkProbe = join(root, 'probe-link');
+  try { symlinkSync(outside, linkProbe, process.platform === 'win32' ? 'junction' : 'dir'); }
+  catch (error) { if (['EPERM', 'EACCES'].includes(error.code)) { t.skip('Sem permissão para links simbólicos.'); return; } throw error; }
+  unlinkSync(linkProbe);
+  const canonical = realpathSync(outputRoot);
+  const original = childProcess.spawnSync;
+  let injected = false;
+  childProcess.spawnSync = function (file, args, options) {
+    if (!injected && file === process.execPath && args?.[0] === '-e' && options?.cwd === canonical) {
+      injected = true;
+      renameSync(outputRoot, `${outputRoot}-original`);
+      symlinkSync(outside, outputRoot, process.platform === 'win32' ? 'junction' : 'dir');
+    }
+    return original.call(this, file, args, options);
+  };
+  syncBuiltinESMExports();
+  try {
+    assert.throws(() => prepareExamples({ sourceRoot: root, outputRoot: join(outputRoot, 'nova'), scenarios: [SCENARIOS[0]], initializeGit: false }), /diretório exclusivo|ancestral|link simbólico/i);
+    assert.equal(injected, true);
+    assert.deepEqual(readdirSync(outside), ['sentinel.txt']);
+    assert.equal(readFileSync(externalSentinel, 'utf8'), 'externo preservado\n');
+  } finally {
+    childProcess.spawnSync = original;
+    syncBuiltinESMExports();
+  }
+});
+
+test('cada destino padrão é exclusivo, preserva provas anteriores e permanece ignorado', t => {
   const { root, outputRoot } = fixture(t);
   const git = (...args) => {
     const result = spawnSync('git', ['-C', root, ...args], { encoding: 'utf8', shell: false });
@@ -77,48 +118,58 @@ test('destino padrão redefine apenas relatório próprio e mantém resultados f
   };
   git('init', '--template=', '--quiet');
   const options = { sourceRoot: root, scenarios: [SCENARIOS[0]], initializeGit: false };
-  const examples = prepareExamples(options);
-  assert.equal(examples[0].root, join(outputRoot, SCENARIOS[0].id));
-  const reportFile = join(outputRoot, 'REPORT.json');
-  writeFileSync(reportFile, JSON.stringify({ owner: 'testar-maturidade', status: 'passed', results: [{ stale: true }] }));
-  prepareExamples(options);
-  assert.deepEqual(JSON.parse(readFileSync(reportFile)), { owner: 'testar-maturidade', version: 1,
-    status: 'prepared', scenarios: [SCENARIOS[0].id], results: [] });
-  assert.match(git('check-ignore', '--verbose', 'examples/generated/REPORT.json'), /examples\/generated\/\.gitignore:2:\*/);
-  assert.match(git('check-ignore', '--verbose', 'examples/generated/somente-agentes/README.md'), /examples\/generated\/\.gitignore:2:\*/);
-  const human = JSON.stringify({ owner: 'human', notes: 'preservar' });
-  writeFileSync(reportFile, human);
-  assert.throws(() => prepareExamples(options), /Relatório.*não pertence/);
-  assert.equal(readFileSync(reportFile, 'utf8'), human);
+  const [first] = prepareExamples(options);
+  const firstOutput = dirname(first.root);
+  assert.equal(dirname(firstOutput), outputRoot);
+  const human = 'Prova humana que não pode ser apagada.\n';
+  writeFileSync(join(first.root, 'human.txt'), human);
+  const reportFile = join(firstOutput, 'REPORT.json');
+  const oldReport = readFileSync(reportFile);
+  const [second] = prepareExamples(options);
+  assert.notEqual(dirname(second.root), firstOutput);
+  assert.equal(readFileSync(join(first.root, 'human.txt'), 'utf8'), human);
+  assert.deepEqual(readFileSync(reportFile), oldReport);
+  for (const file of [join(firstOutput, 'REPORT.json'), join(first.root, 'README.md'), join(second.root, 'README.md')]) {
+    git('check-ignore', '--quiet', '--', file);
+  }
 });
 
-test('preserva ignore humano e continua aceitando destinos legados', t => {
+test('preserva ignore humano em pastas ancestrais e aceita destinos novos permitidos', t => {
   const { root, put } = fixture(t);
   const options = { sourceRoot: root, scenarios: [SCENARIOS[0]], initializeGit: false };
   put('examples/generated/.gitignore', '!README.md\n');
-  assert.throws(() => prepareExamples(options), /Ignore.*não pertence/);
+  put('examples/generated/.maturity-suite.json', '{"owner":"testar-maturidade"}\n');
+  put('examples/generated/somente-agentes/.maturity-case.json', '{"owner":"testar-maturidade","id":"somente-agentes"}\n');
+  put('examples/generated/somente-agentes/anotacao.txt', 'Conteúdo humano anterior.\n');
+  put('examples/generated/REPORT.json', '{"resultado":"anterior"}\n');
+  const [generated] = prepareExamples(options);
+  assert.equal(dirname(dirname(generated.root)), join(root, 'examples/generated'));
   assert.equal(readFileSync(join(root, 'examples/generated/.gitignore'), 'utf8'), '!README.md\n');
-  for (const target of ['tmp/examples', '.agent-tests/cases']) {
+  assert.equal(readFileSync(join(root, 'examples/generated/somente-agentes/anotacao.txt'), 'utf8'), 'Conteúdo humano anterior.\n');
+  assert.equal(readFileSync(join(root, 'examples/generated/REPORT.json'), 'utf8'), '{"resultado":"anterior"}\n');
+  for (const target of ['tmp/examples/caso-novo', '.agent-tests/cases']) {
     const outputRoot = join(root, target);
     const [example] = prepareExamples({ ...options, outputRoot });
     assert.equal(example.root, join(outputRoot, SCENARIOS[0].id));
   }
 });
 
-test('preparação interrompida não conserva resultado anterior nem declara sucesso', t => {
+test('preparação interrompida não altera resultado anterior nem declara sucesso', t => {
   const { root, put, outputRoot } = fixture(t);
   const options = { sourceRoot: root, scenarios: [SCENARIOS[0]], initializeGit: false };
-  prepareExamples(options);
-  const report = join(outputRoot, 'REPORT.json');
-  const index = join(outputRoot, 'README.md');
-  writeFileSync(report, JSON.stringify({ owner: 'testar-maturidade', status: 'passed', results: [{}] }));
-  writeFileSync(index, readFileSync(index, 'utf8').replaceAll('prepared', 'passed'));
+  const [first] = prepareExamples(options);
+  const firstOutput = dirname(first.root);
+  const report = join(firstOutput, 'REPORT.json');
+  const previous = readFileSync(report);
   put('.pbai4devs/state/agentdevkit.json', JSON.stringify({ blocks: null }));
   assert.throws(() => prepareExamples(options), /Estado da instalação/);
-  assert.equal(existsSync(report), false);
+  assert.deepEqual(readFileSync(report), previous);
+  const failed = readdirSync(outputRoot).filter(name => join(outputRoot, name) !== firstOutput);
+  assert.equal(failed.length, 1);
+  const index = join(outputRoot, failed[0], 'README.md');
   assert.match(readFileSync(index, 'utf8'), /status: preparing/);
+  assert.equal(existsSync(join(outputRoot, failed[0], 'REPORT.json')), false);
   assert.doesNotMatch(readFileSync(index, 'utf8'), /status: passed|\| passed \|/);
-  assert.doesNotMatch(readFileSync(index, 'utf8'), /\n{3,}/);
 });
 
 test('usa entradas distribuídas do hub e mantém fallback legado', t => {
@@ -216,6 +267,38 @@ test('localiza apontamentos pelo formato de cada tipo e por overrides nativos',
   ]);
 });
 
+test('respeita tipo sem espelho e o formato TOML nativo dos comandos Gemini', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', [
+    'agente|.agents|agrupado',
+    'agente|.codex|agrupado', 'formato|.codex|skills|nenhum',
+    'agente|.gemini|agrupado', 'formato|.gemini|commands|arquivo',
+  ].join('\n') + '\n');
+  const skill = resourceTargets(root, '.pbai4devs/skills/projeto/demo/SKILL.md');
+  assert.deepEqual(skill, ['.agents/skills/projeto/demo/SKILL.md', '.gemini/skills/projeto/demo/SKILL.md']);
+  assert.ok(!skill.some(target => target.startsWith('.codex/')));
+  const command = resourceTargets(root, '.pbai4devs/commands/projeto/demo/COMMAND.md', 'commands');
+  assert.ok(command.includes('.codex/commands/projeto/demo/COMMAND.md'));
+  assert.ok(command.includes('.gemini/commands/projeto/demo.toml'));
+  assert.ok(!command.includes('.gemini/commands/projeto/demo.md'));
+});
+
+test('identifica o fallback Codex apenas para a skill cuja rota primária está obstruída', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', [
+    'agente|.agents|agrupado', 'agente|.codex|agrupado',
+    'formato|.codex|skills|nenhum', 'fallback|.codex|.agents|skills',
+  ].join('\n') + '\n');
+  const blocked = '.pbai4devs/skills/projeto/demo/SKILL.md';
+  const available = '.pbai4devs/skills/projeto/outra/SKILL.md';
+  const target = join(root, '.agents/skills/projeto/demo/SKILL.md');
+  mkdirSync(target, { recursive: true });
+  assert.deepEqual(resourceTargets(root, blocked), ['.codex/skills/projeto/demo/SKILL.md']);
+  assert.deepEqual(resourceTargets(root, available), ['.agents/skills/projeto/outra/SKILL.md']);
+  rmSync(target, { recursive: true });
+  assert.deepEqual(resourceTargets(root, blocked), ['.agents/skills/projeto/demo/SKILL.md']);
+});
+
 test('checkout de fontes sem manifesto deriva clientes em memória', t => {
   const { root, put } = fixture(t);
   const manifest = join(root, '.pbai4devs/espelhos.conf');
@@ -277,6 +360,47 @@ test('oito cópias exercitam os seis níveis e preservam layouts legado/monorepo
   assert.equal(existsSync(join(monorepo.root, 'src')), false);
 });
 
+test('cenários configurados completam fixtures ausentes sem alterar a origem ou arquivos copiados', t => {
+  const { root, put, outputRoot } = fixture(t);
+  const files = ['.gitignore', '.gitattributes', '.editorconfig'];
+  const source = Object.fromEntries(files.map(file => [file, `# configuração própria de ${file}\n`]));
+  // As duas fontes ausentes reproduzem uma instalação distribuída; o arquivo
+  // existente prova que a preparação não substitui configurações copiadas.
+  rmSync(join(root, '.gitattributes'));
+  rmSync(join(root, '.editorconfig'));
+  put('.gitignore', source['.gitignore']);
+  const scenarios = SCENARIOS.filter(example => ['app-configurada', 'manutencao', 'app-inicial'].includes(example.id));
+  const examples = prepareExamples({ sourceRoot: root, outputRoot: join(outputRoot, 'parcial'), scenarios, initializeGit: false });
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), source['.gitignore']);
+  for (const file of ['.gitattributes', '.editorconfig']) assert.equal(existsSync(join(root, file)), false, file);
+  for (const example of examples) {
+    assert.equal(readFileSync(join(example.root, '.gitignore'), 'utf8'), source['.gitignore']);
+    if (!example.configured) {
+      for (const file of ['.gitattributes', '.editorconfig']) assert.equal(existsSync(join(example.root, file)), false, file);
+      continue;
+    }
+    for (const file of ['.gitattributes', '.editorconfig']) assert.ok(readFileSync(join(example.root, file), 'utf8').trim(), file);
+    const inspected = spawnSync(process.execPath, ['.pbai4devs/scripts/inspecionar-projeto/SCRIPT.mjs', '--check'], { cwd: example.root, encoding: 'utf8' });
+    assert.ifError(inspected.error);
+    assert.equal(inspected.status, 0, inspected.stderr || inspected.stdout);
+    assert.equal(JSON.parse(inspected.stdout).contract.complete, true, example.id);
+  }
+  // Retest with every file absent, as in the released npm tarball.
+  rmSync(join(root, '.gitignore'));
+  const configured = scenarios.find(example => example.id === 'app-configurada');
+  const missing = prepareExamples({ sourceRoot: root, outputRoot: join(outputRoot, 'ausentes'), scenarios: [configured], initializeGit: false })[0];
+  for (const file of files) {
+    assert.equal(existsSync(join(root, file)), false, file);
+    assert.ok(readFileSync(join(missing.root, file), 'utf8').trim(), file);
+  }
+  for (const file of files) put(file, source[file]);
+  const preserved = prepareExamples({ sourceRoot: root, outputRoot: join(outputRoot, 'presentes'), scenarios: [configured], initializeGit: false })[0];
+  for (const file of files) {
+    assert.equal(readFileSync(join(root, file), 'utf8'), source[file]);
+    assert.equal(readFileSync(join(preserved.root, file), 'utf8'), source[file]);
+  }
+});
+
 test('fixtures padrão, legado e monorepo executam HTTP real e encerram', t => {
   const { root, outputRoot } = fixture(t);
   const scenarios = SCENARIOS.filter(example => ['app-inicial', 'legado', 'monorepo'].includes(example.id));

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

@@ -49,9 +49,20 @@ function ownership(root) {
   if (checkedStat(root, derivedFile)) {
     const derived = readState(derivedFile);
     if (derived?.schemaVersion !== 1 || !validMap(derived.entries) || Object.keys(derived.entries).some(path => !canonicalEntrypoint(path))
-      || !validMap(derived.files ?? {}) || !validMap(derived.blocks ?? {})
+      || !validMap(derived.files ?? {}) || !validMap(derived.blocks ?? {}) || !validMap(derived.removedFiles ?? {})
       || !Array.isArray(derived.removedBlocks ?? []) || (derived.removedBlocks ?? []).some(path => typeof path !== 'string')
       || !validMap(derived.outputs ?? {}) || Object.keys(derived.outputs ?? {}).some(path => !/^\.[a-z0-9][a-z0-9-]*\/(?:skills|rules|agents)\.json$/.test(path))) fail('Estado de entradas derivadas invalido.');
+    for (const [path, hash] of Object.entries(derived.removedFiles ?? {})) {
+      const [nativeRoot, scope] = path.split('/');
+      if (!/^\.[A-Za-z0-9][A-Za-z0-9._-]*$/.test(nativeRoot) || ['.git', '.pbai4devs', '.agent-tests'].includes(nativeRoot.toLowerCase())
+        || !scope || [...auxiliary, 'workflows'].includes(scope.toLowerCase()) || ['readme.md', 'instructions.md'].includes(basename(path).toLowerCase())
+        || !(/\.(?:md|mdc)$/i.test(path) || path.startsWith('.gemini/commands/') && path.endsWith('.toml'))) fail('Registro de arquivos removidos invalido.');
+      const location = checkedPath(root, path);
+      if (state.files[path] && state.files[path] !== hash) fail(`Registro de arquivos removidos divergente: ${path}`);
+      if (state.files[path] !== hash || derived.files?.[path] || derived.blocks?.[path] || derived.entries?.[path]) continue;
+      if (checkedStat(root, location)) fail(`Arquivo removido foi recriado; revise o conteúdo: ${path}`);
+      delete files[path];
+    }
     Object.assign(files, derived.entries, derived.outputs, derived.files);
     for (const [path, hash] of Object.entries({ ...derived.entries, ...derived.files })) {
       const location = checkedPath(root, path);

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

@@ -196,6 +196,28 @@ test('instalação também protege manifestos registrados em derived.outputs', t
   assert.throws(() => verify(root), /Arquivo gerenciado ausente: .agents\/skills.json/);
 });
 
+test('remoções derivadas exigem hash compatível e não ocultam arquivo humano recriado', t => {
+  const { root, file, generated } = installedFixture(t);
+  const statePath = join(root, '.pbai4devs/state/agentdevkit.json');
+  const state = JSON.parse(readFileSync(statePath, 'utf8'));
+  const hash = state.files[generated], derivedPath = '.pbai4devs/state/derived.json';
+  rmSync(join(root, generated));
+  const record = removedFiles => file(derivedPath, JSON.stringify({ schemaVersion: 1, entries: {}, removedFiles }));
+  record({ [generated]: hash });
+  assert.doesNotThrow(() => verify(root));
+  file(generated, document('# Conteúdo recriado pelo usuário\n'));
+  const recreated = readFileSync(join(root, generated));
+  assert.throws(() => verify(root), /Arquivo removido foi recriado/);
+  assert.deepEqual(readFileSync(join(root, generated)), recreated);
+  rmSync(join(root, generated));
+  record({ [generated]: 'f'.repeat(64) });
+  assert.throws(() => verify(root), /Registro de arquivos removidos divergente/);
+  record({ [generated]: 'invalido' });
+  assert.throws(() => verify(root), /Estado de entradas derivadas invalido/);
+  record({ '.pbai4devs/skills/exemplo/SKILL.md': hash });
+  assert.throws(() => verify(root), /Registro de arquivos removidos invalido/);
+});
+
 test('catalogo derivado cobre recursos e detecta JSON editado sem reescrever', t => {
   const { root, file } = resourceFixture(t);
   file('.pbai4devs/commands/inspecionar/COMMAND.md', document('# Inspecionar\n\n[Script](../../scripts/inspecionar/SCRIPT.mjs).\n'));

package/.pbai4devs/templates/clients/ADAPTERS.json

@@ -79,9 +79,10 @@
       "name": "Codex",
       "root": ".codex",
       "formats": {
-        "skills": "agrupado"
+        "skills": "nenhum"
       },
-      "reason": "Skills agrupadas; a entrada nativa de projeto é .agents/skills. Outros recursos em .codex são referências, não registros de agentes.",
+      "skillFallback": ".agents",
+      "reason": "Skills usam apenas .agents/skills para evitar descoberta duplicada; os demais recursos em .codex são referências.",
       "sources": [
         "https://learn.chatgpt.com/docs/build-skills",
         "https://github.com/openai/codex/blob/392ced7d3a9160fd35d40c606359869215f50522/codex-rs/ext/skills/src/loader/host.rs"

package/CHANGELOG.md

@@ -4,6 +4,21 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.22 — 2026-11-13
+
+- Descoberta de skills do Codex sem duplicação, com alternativa segura quando a
+  rota principal está obstruída.
+- Sincronização e atualização reconciliam o estado sem substituir recursos ou
+  metadados humanos.
+- Scripts reconhecem caminhos por aliases e exemplos de maturidade usam saídas isoladas.
+- Testes ampliados para combinações de clientes, projetos existentes e
+  preservação do Git.
+
+## 0.0.21 — 2026-11-13
+
+- Criação automática da tag da versão após aprovação da matriz de CI.
+- Publicação acionada pela automação com proteção contra colisões de tags.
+
 ## 0.0.20 — 2026-11-13
 
 - Atualização da ferramenta agent-browser compatível com sua distribuição atual.

package/docs/maintainers/maintenance.md

@@ -75,8 +75,15 @@ nada. Nunca versione o tarball ou seus relatórios.
 
 1. Atualize versão e lockfile, changelog, exemplos e escopo da entrega.
 2. Conclua testes, documentação e revisão independente.
-3. Envie o commit à branch principal e aguarde o CI aprovado.
-4. Crie e envie a tag `v<versão>` para esse mesmo commit.
+3. Envie o commit à branch principal e acompanhe o CI e a release.
+
+Após toda a matriz de CI passar, a automação cria a tag `v<versão>` no
+commit verificado e inicia o workflow de release. Um push sem mudança de versão
+publicada não gera outra release. Uma tag existente não é movida: se a versão
+mudou e a tag aponta para outro commit, a automação falha para revisão.
+Versões inferiores às já registradas também não são publicadas automaticamente.
+Se um push cancelar o CI anterior e a versão ainda não tiver tag, o próximo
+CI aprovado da branch principal poderá publicar a versão no seu próprio commit.
 
 O [workflow de release][release] localiza o CI aprovado de um push na branch
 principal, confere o commit e baixa seu artifact por ID. Verifica procedência,
@@ -85,9 +92,10 @@ Também envia o mesmo pacote ao [npm público e GitHub Packages](packages.md),
 confere a integridade nos dois destinos e testa versão, instalação, diagnóstico
 e sincronização. O consumo pelo npm é anônimo; pelo GitHub, autenticado.
 
-A tag é a origem da publicação: `v0.0.19`, a release `v0.0.19` e os pacotes
-`0.0.19` apontam para a mesma entrega. A execução manual também exige a tag;
-não crie outra tag para uma versão nem mova uma tag já publicada.
+A tag é a origem da publicação: `v0.0.21`, a release `v0.0.21` e os pacotes
+`0.0.21` apontam para a mesma entrega. A execução manual também exige a tag;
+não crie outra tag para uma versão nem mova uma tag já publicada. Publicações
+feitas fora desse fluxo não criam tags automaticamente.
 
 Para consultar o código de uma versão sem trocar os arquivos atuais:
 
@@ -124,6 +132,9 @@ Se a release ainda não existe, use **Re-run failed jobs** ou
 `gh workflow run release.yml --ref vX.Y.Z` com a tag real. A publicação prioriza
 o secret `NPMJS_TOKEN` do repositório; sem ele, usa OIDC, conforme
 [publicação](packages.md).
+Se a criação da tag ou o acionamento falhar, consulte a execução **Automatic
+release tag**. Uma tag no commit correto pode ser retomada sem movê-la; se ela
+apontar para outro commit, investigue antes de qualquer publicação.
 
 Se a release já existe e falta somente o pacote em um registro, use o modo
 `package_only` descrito em [pacote npm](packages.md#publicar-pelo-actions).

package/docs/specs/README.md

@@ -27,6 +27,9 @@ description: Incrementos verificáveis do AgentDevKit.
 - [Ignore do projeto](project-ignore/SPEC.md): preservar o arquivo da raiz.
 - [Ignore de clientes](client-ignore/SPEC.md): padrão local e exceções do projeto.
 - [Ferramenta e versões](tool-release/SPEC.md): atualização segura e tags de release.
+- [Tags automáticas](automatic-release-tags/SPEC.md): publicação após CI aprovada.
+- [Descoberta e preservação](discovery-preservation/SPEC.md): rotas de skills,
+  sincronização segura e validação em projetos reais.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.