@pathbit/agentdevkit 0.0.21 → 0.0.23

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

@@ -21,7 +21,7 @@ const auxiliary = ['templates', 'scripts', 'tools', 'external-skills', 'state',
 const reserved = new Set(['.git', '.pbai4devs', '.agent-tests']);
 const compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 const sorted = values => [...new Set(values)].sort(compare);
-const layouts = new Set(['agrupado', 'plano', 'arquivo', 'mdc', 'instrucoes', 'prompt', 'agente']);
+const layouts = new Set(['agrupado', 'plano', 'arquivo', 'mdc', 'instrucoes', 'prompt', 'agente', 'nenhum']);
 const fail = message => { throw new Error(message); };
 const normalize = text => text.replace(/\r\n?/g, '\n');
 const read = file => normalize(readFileSync(file, 'utf8'));
@@ -30,6 +30,77 @@ const stat = file => {
   catch (error) { if (['ENOENT', 'ENOTDIR'].includes(error.code)) return null; throw error; }
 };
 
+function replaceJsonMember(bytes, member, value) {
+  const text = bytes.toString('utf8');
+  if (!Buffer.from(text, 'utf8').equals(bytes)) fail('Invalid UTF-8 in derived state.');
+  let i = 0;
+  const space = () => { while (/\s/.test(text[i] || '') && i < text.length) i++; };
+  const stringEnd = () => {
+    if (text[i++] !== '"') fail('Invalid JSON member.');
+    while (i < text.length) {
+      const char = text[i++];
+      if (char === '\\') { i++; continue; }
+      if (char === '"') return;
+    }
+    fail('Unterminated JSON string.');
+  };
+  space(); if (text[i++] !== '{') fail('Invalid derived state.');
+  const properties = [];
+  while (true) {
+    space(); if (text[i] === '}') break;
+    const start = i; stringEnd(); const key = JSON.parse(text.slice(start, i));
+    space(); if (text[i++] !== ':') fail('Invalid JSON member.');
+    space(); const valueStart = i;
+    if (text[i] === '"') stringEnd();
+    else if (text[i] === '{' || text[i] === '[') {
+      const stack = [];
+      do {
+        const char = text[i];
+        if (char === '"') { stringEnd(); continue; }
+        i++;
+        if (char === '{' || char === '[') stack.push(char);
+        else if (char === '}' || char === ']') stack.pop();
+      } while (stack.length && i < text.length);
+      if (stack.length) fail('Invalid derived state.');
+    } else { while (i < text.length && text[i] !== ',' && text[i] !== '}') i++; while (i > valueStart && /\s/.test(text[i - 1])) i--; }
+    const end = i; properties.push({ key, start, valueStart, end });
+    space(); if (text[i] === ',') { i++; continue; } if (text[i] === '}') break;
+    fail('Invalid JSON member separator.');
+  }
+  const matches = properties.filter(item => item.key === member);
+  if (matches.length > 1) fail('Ambiguous derived state member.');
+  if (!matches.length) {
+    if (value === undefined) return bytes;
+    const insertion = `${properties.length ? ',' : ''}\n  ${JSON.stringify(member)}: ${JSON.stringify(value, null, 2)}\n`;
+    const next = text.slice(0, i) + insertion + text.slice(i);
+    try { JSON.parse(next); } catch { fail('Unable to preserve derived state safely.'); }
+    return Buffer.from(next);
+  }
+  const current = matches[0], index = properties.indexOf(current);
+  let next;
+  if (value !== undefined) next = text.slice(0, current.valueStart) + JSON.stringify(value, null, 2) + text.slice(current.end);
+  else if (index > 0) next = text.slice(0, properties[index - 1].end) + text.slice(current.end);
+  else if (properties.length > 1) next = text.slice(0, current.start) + text.slice(properties[1].start);
+  else next = text.slice(0, current.start) + text.slice(current.end);
+  try { JSON.parse(next); } catch { fail('Unable to preserve derived state safely.'); }
+  return Buffer.from(next);
+}
+
+
+// Compare owned fields structurally, preserving all other JSON bytes.
+function derivedContent(original, previous, next) {
+  if (!original) return JSON.stringify(next, null, 2) + '\n';
+  const keys = ['schemaVersion', 'entries', 'outputs', 'files', 'blocks', 'removedBlocks', 'removedFiles'];
+  const canonical = value => value && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.keys(value).sort(compare).map(key => [key, canonical(value[key])]))
+    : Array.isArray(value) ? value.map(canonical) : value;
+  let result = original;
+  for (const key of keys) {
+    if (JSON.stringify(canonical(previous[key])) !== JSON.stringify(canonical(next[key]))) result = replaceJsonMember(result, key, next[key]);
+  }
+  return result.toString('utf8');
+}
+
 export function header(text) {
   const lines = normalize(text).split('\n');
   if (lines[0] !== '---') fail('Frontmatter YAML ausente.');
@@ -76,7 +147,7 @@ function link(target, source) {
 
 export { resourcePath } from '../lib/resource-path.mjs';
 
-export function synchronize({ root = projectRoot, check = false, force = false, localIgnores = true, generateEntrypoints = true, recordDerivedState = true, output = console.log } = {}) {
+export function synchronize({ root = projectRoot, check = false, force = false, localIgnores = true, generateEntrypoints = true, recordDerivedState = true, outputBlocked, output = console.log } = {}) {
   requireNode();
   root = realpathSync(resolve(root));
   const absolute = value => join(root, ...value.split('/'));
@@ -156,6 +227,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const protectedPath = value => /^(workflows(?:\/|$)|settings\.json$|extensions\.json$)/.test(value.slice(value.indexOf('/') + 1).toLowerCase());
   const agents = new Map();
   const formats = new Map();
+  const fallbacks = new Map();
   const discoveries = new Set();
   const ignoreRoots = new Set();
   const natives = [];
@@ -182,14 +254,20 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       && !['readme.md', 'instructions.md'].includes(posix.basename(path).toLowerCase())
       && (/\.(md|mdc)$/i.test(path) || path.startsWith('.gemini/commands/') && path.endsWith('.toml'));
   };
+  const validIgnoreBlock = path => typeof path === 'string' && /^\.[A-Za-z0-9][A-Za-z0-9._-]*\/\.gitignore$/.test(path) && !reserved.has(path.split('/')[0].toLowerCase());
   for (const [name, values] of [['files', previousEntries.files ?? {}], ['blocks', previousEntries.blocks ?? {}]]) {
-    if (!values || typeof values !== 'object' || Array.isArray(values) || Object.entries(values).some(([path, hash]) => !(validResourcePath(path) || name === 'blocks' && canonicalEntrypoint(path)) || !/^[a-f0-9]{64}$/.test(hash))) fail(`Registro de ${name} derivados invalido.`);
+    if (!values || typeof values !== 'object' || Array.isArray(values) || Object.entries(values).some(([path, hash]) => !(validResourcePath(path) || name === 'blocks' && (canonicalEntrypoint(path) || validIgnoreBlock(path))) || !/^[a-f0-9]{64}$/.test(hash))) fail(`Registro de ${name} derivados invalido.`);
     for (const path of Object.keys(values)) safe(canonicalEntrypoint(path) ? resolveEntrypoint(root, canonicalEntrypoint(path)) : path);
   }
   const removedBlocks = new Set(previousEntries.removedBlocks ?? []);
   if (!Array.isArray(previousEntries.removedBlocks ?? []) || [...removedBlocks].some(path => typeof path !== 'string' || !(validResourcePath(path) || canonicalEntrypoint(path)))) fail('Registro de blocos removidos invalido.');
   for (const path of removedBlocks) safe(canonicalEntrypoint(path) ? resolveEntrypoint(root, canonicalEntrypoint(path)) : path);
-  const priorFiles = { ...installed?.files, ...previousEntries.files };
+  const removedFiles = previousEntries.removedFiles ?? {};
+  if (!removedFiles || typeof removedFiles !== 'object' || Array.isArray(removedFiles) || Object.entries(removedFiles).some(([path, hash]) => !validResourcePath(path) || !/^[a-f0-9]{64}$/.test(hash))) fail('Registro de arquivos removidos invalido.');
+  if (Object.entries(removedFiles).some(([path, hash]) => installed?.files?.[path] && installed.files[path] !== hash)) fail('Registro de arquivos removidos diverge do estado instalado.');
+  for (const path of Object.keys(removedFiles)) safe(path);
+  const effectiveRemovedFiles = Object.fromEntries(Object.entries(removedFiles).filter(([path, hash]) => installed?.files?.[path] === hash));
+  const priorFiles = { ...Object.fromEntries(Object.entries(installed?.files ?? {}).filter(([path, hash]) => effectiveRemovedFiles[path] !== hash)), ...previousEntries.files };
   const priorBlocks = { ...Object.fromEntries(Object.entries(installed?.blocks ?? {}).filter(([path]) => !removedBlocks.has(path))), ...previousEntries.blocks };
   const ownedPaths = new Set([...Object.keys(priorFiles), ...Object.keys(priorBlocks), ...Object.keys(previousEntries.entries), ...Object.keys(previousOutputs)]);
   const nativeRoots = new Set(rows.map(row => row.split('|')).filter(([type]) => ['agente', 'gitignore'].includes(type)).map(([, target]) => target));
@@ -200,6 +278,28 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     const boundary = nativePathBoundary(root, value, ownedPaths, { preserveRootAliases: true });
     return boundary ? remember(boundary.path, boundary.reason) : false;
   }
+  const fallbackChecks = new Map();
+  function blockedOutput(path) {
+    if (outputBlocked) return outputBlocked(path);
+    let boundary = nativePathBoundary(root, path, ownedPaths, { preserveRootAliases: true });
+    if (!boundary) {
+      const info = stat(safe(path));
+      if (info && !info.isFile()) boundary = { path, reason: 'non-file' };
+    }
+    if (!boundary) return { blocked: false };
+    remember(boundary.path, boundary.reason);
+    const info = lstatSync(absolute(boundary.path));
+    return { blocked: true, ...boundary, identity: [info.dev, info.ino, info.mode, info.size, info.mtimeMs, info.ctimeMs] };
+  }
+  function unavailable(path) {
+    const status = blockedOutput(path);
+    if (fallbackChecks.has(path) && JSON.stringify(fallbackChecks.get(path)) !== JSON.stringify(status)) fail(`Caminho de skill mudou durante o planejamento: ${path}`);
+    fallbackChecks.set(path, status);
+    return status.blocked;
+  }
+  function assertFallbackChecks() {
+    for (const [path, status] of fallbackChecks) if (JSON.stringify(blockedOutput(path)) !== JSON.stringify(status)) fail(`Caminho de skill mudou apos o planejamento: ${path}`);
+  }
   function claimed(value) {
     if (ownedPaths.has(value)) return true;
     const info = stat(safe(value));
@@ -241,7 +341,8 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       agents.set(target, mode);
     } else if (type === 'formato') {
       if (fields.length !== 4 || !Object.hasOwn(principals, source) || !layouts.has(metadata)) fail(`Formato invalido: ${row}`);
-      if (source === 'skills' && !['agrupado', 'plano'].includes(metadata)) fail(`Skills exigem formato agrupado ou plano: ${row}`);
+      if (source === 'skills' && !['agrupado', 'plano', 'nenhum'].includes(metadata)) fail(`Skills exigem formato agrupado, plano ou nenhum: ${row}`);
+      if (metadata === 'nenhum' && source !== 'skills') fail(`Formato incompativel com recurso: ${row}`);
       if ((metadata === 'mdc' || metadata === 'instrucoes') && source !== 'rules' || metadata === 'prompt' && source !== 'commands' || metadata === 'agente' && source !== 'agents') fail(`Formato incompativel com recurso: ${row}`);
       const key = `${target}/${source}`;
       if (formats.has(key)) fail(`Formato duplicado: ${key}`);
@@ -249,6 +350,9 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     } else if (type === 'descoberta') {
       if (fields.length !== 3 || target !== '.agents' || source !== 'antigravity' || discoveries.has(target)) fail(`Descoberta invalida: ${row}`);
       discoveries.add(target);
+    } else if (type === 'fallback') {
+      if (fields.length !== 4 || metadata !== 'skills' || target === source || fallbacks.has(target)) fail(`Fallback invalido: ${row}`);
+      fallbacks.set(target, source);
     } else if (type === 'gitignore') {
       if (fields.length !== 2) fail('gitignore aceita somente a pasta de destino.');
       ignoreRoot(target);
@@ -269,6 +373,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   if (!agents.size) fail('Nenhum agente cadastrado.');
   for (const key of formats.keys()) if (!agents.has(key.split('/')[0])) fail(`Formato fora dos agentes: ${key}`);
+  for (const [target, source] of fallbacks) if (!agents.has(target) || !agents.has(source) || formats.get(`${target}/skills`) !== 'nenhum' || formats.get(`${source}/skills`) === 'nenhum') fail(`Fallback fora dos agentes: ${target}`);
   for (const root of discoveries) if (!agents.has(root)) fail(`Descoberta fora dos agentes: ${root}`);
   const managed = value => [...agents.keys()].some(agent => value.startsWith(agent + '/'));
   const built = buildCatalog(root);
@@ -287,7 +392,19 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   for (const [source, kind] of sources) {
     for (const [agent, mode] of agents) {
-      let path = resourcePath(source, kind, formats.get(`${agent}/${kind}`) || mode);
+      const format = formats.get(`${agent}/${kind}`) || mode;
+      if (format === 'nenhum') {
+        const primary = kind === 'skills' && fallbacks.get(agent);
+        if (!primary) continue;
+        const primaryFormat = formats.get(`${primary}/${kind}`) || agents.get(primary);
+        const primaryTarget = `${primary}/${resourcePath(source, kind, primaryFormat)}`;
+        if (!unavailable(primaryTarget)) continue;
+        const target = `${agent}/${resourcePath(source, kind, mode)}`;
+        if (unavailable(target)) fail(`Skill indisponivel: ${source}; caminhos ${primaryTarget} e ${target} obstruidos.`);
+        add(target, source);
+        continue;
+      }
+      let path = resourcePath(source, kind, format);
       if (agent === '.gemini' && kind === 'commands') path = path.replace(/\.md$/, '.toml');
       add(`${agent}/${path}`, source);
     }
@@ -385,7 +502,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       const unchanged = current === null || priorHashes.includes(createHash('sha256').update(current).digest('hex'));
       if (!unchanged) { remember(manifest, 'edited-generated-file'); continue; }
       const nextHash = createHash('sha256').update(content).digest('hex');
-      if (installed?.files?.[manifest] !== nextHash) discoveryOutputs[manifest] = nextHash;
+      if (installed?.files?.[manifest] !== nextHash || Object.hasOwn(previousOutputs, manifest)) discoveryOutputs[manifest] = nextHash;
       if (!info || readFileSync(absolute(manifest), 'utf8') !== content) {
         if (info && force) backup.add(manifest);
         registries.set(manifest, content);
@@ -416,6 +533,10 @@ export function synchronize({ root = projectRoot, check = false, force = false,
       merged = mergeGitignore(current, patterns);
     }
     catch (error) { fail(`${target}: ${error.message}`); }
+    if (target !== '.pbai4devs/.gitignore') {
+      const start = merged.text.indexOf(ignoreBegin), finish = merged.text.indexOf(ignoreEnd);
+      if (start >= 0 && finish > start) managedBlocks[target] = createHash('sha256').update(merged.text.slice(start, finish + ignoreEnd.length)).digest('hex');
+    }
     if (merged.text !== current) {
       ignoreFiles.set(target, merged.text);
       if (force && info && merged.hasBlock) backup.add(target);
@@ -568,8 +689,11 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   if (Object.keys(derivedBlocks).length) next.blocks = derivedBlocks;
   for (const path of Object.keys(managedBlocks)) removedBlocks.delete(path);
   if (removedBlocks.size) next.removedBlocks = sorted(removedBlocks);
-  const registryContent = JSON.stringify(next, null, 2) + '\n';
-  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
+  for (const path of expected.keys()) delete effectiveRemovedFiles[path];
+  for (const path of remove) if (validResourcePath(path) && installed?.files?.[path] && !expected.has(path)) effectiveRemovedFiles[path] = installed.files[path];
+  if (Object.keys(effectiveRemovedFiles).length) next.removedFiles = Object.fromEntries(Object.entries(effectiveRemovedFiles).sort(([a], [b]) => compare(a, b)));
+  const registryContent = derivedContent(registryBytes, previousEntries, next);
+  if (recordDerivedState && (Object.keys(nextEntries).length || Object.keys(discoveryOutputs).length || Object.keys(generatedFiles).length || Object.keys(derivedBlocks).length || removedBlocks.size || Object.keys(effectiveRemovedFiles).length || stat(safe(entryRegistry))) && (!stat(safe(entryRegistry)) || readFileSync(absolute(entryRegistry), 'utf8') !== registryContent)) registries.set(entryRegistry, registryContent);
   const ownedOutputs = sorted([...targets, ...built.outputs.keys(), '.pbai4devs/espelhos.conf', ...rootEntries.keys(), ...(recordDerivedState && (stat(safe(entryRegistry)) || registries.has(entryRegistry)) ? [entryRegistry] : []),
     ...[...discoveries].flatMap(agent => ['skills', 'rules', 'agents'].map(kind => `${agent}/${kind}.json`)),
     ...[...ignoreTemplates.keys()].filter(target => {
@@ -633,6 +757,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const summary = { changed: changed.length + rootEntryChanges.length, stale: removals.length, conflicts: conflicts.size, missing: missing.length, legacy: legacy.length, registries: registries.size, gitignores: ignoreFiles.size, manifests: configExists ? 0 : 1, localIgnores: localStatus.changed + localStatus.missing.length + localStatus.trackedOutputs.length + (localStatus.status === 'no-git' ? 1 : 0) };
   const dirty = Object.values(summary).some(Boolean);
   output(`${summary.changed} desatualizadas; ${summary.stale} obsoletas; ${summary.conflicts} conflitos; ${summary.missing} origens nativas ausentes; ${summary.legacy} documentos antigos; ${summary.registries} indices derivados; ${summary.gitignores} gitignores; ${summary.localIgnores} exclusoes locais.`);
+  assertFallbackChecks();
   if (localStatus.status === 'no-git') output('Git ausente: apos git init, execute a sincronizacao para proteger os arquivos locais.');
   const preservedPaths = sorted(preserved.keys()).map(path => preserved.get(path));
   if (check) return { ...summary, ownedOutputs, managedBlocks, preserved: preservedPaths, exitCode: dirty ? 1 : 0 };
@@ -700,6 +825,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     chmodSync(safe(value), content.mode);
   }
   try {
+    assertFallbackChecks();
     if (localPlan) assertLocalIgnoreUnchanged(localPlan);
     if (Object.keys(affectedHashes).length) {
       if (!assertGitReadableForChanges() && hadGit) fail('Git deixou de estar disponivel antes da sincronizacao; arquivos preservados.');
@@ -712,6 +838,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     for (const [value, text] of ignoreFiles) mutate(value, () => atomic(value, text), text);
     for (const [value, text] of rootEntryChanges) mutate(value, () => atomic(value, text), text);
     if (configChanged) mutate(config, () => atomic(config, finalConfig), finalConfig);
+    assertFallbackChecks();
     // Directory ownership is not recorded: keep even empty parent directories.
     if (localPlan) applyLocalIgnore(localPlan);
   } catch (error) {

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

@@ -122,6 +122,36 @@ test('conteúdo humano concorrente não é apagado durante rollback', t => {
   assert.equal(fs.readFileSync(join(root, generated), 'utf8'), human);
 });
 
+test('falha ao registrar remoção derivada restaura fallback e preserva índice', t => {
+  const root = fixture(t), fallback = '.codex/skills/demo/SKILL.md';
+  write(root, '.pbai4devs/espelhos.conf', [
+    'agente|.agents|agrupado', 'agente|.codex|plano',
+    'formato|.codex|skills|nenhum', 'fallback|.codex|.agents|skills',
+  ].join('\n') + '\n');
+  write(root, '.agents/skills', 'obstrução humana');
+  write(root, '.gitignore', '# ignore humano\n');
+  assert.equal(spawnSync('git', ['-C', root, 'add', '.gitignore']).status, 0);
+  run(root);
+  const initial = fs.readFileSync(join(root, fallback));
+  write(root, '.pbai4devs/state/agentdevkit.json', JSON.stringify({ schemaVersion: 1, files: { [fallback]: hash(initial) }, blocks: {} }));
+  fs.rmSync(join(root, '.pbai4devs/state/derived.json'), { force: true });
+  fs.rmSync(join(root, '.agents/skills')); // A obstrução pertence à fixture.
+  const before = snapshot(root), index = fs.readFileSync(join(root, '.git/index'));
+  const originalRename = fs.renameSync;
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    if (!injected && to === join(root, '.pbai4devs/state/derived.json')) { injected = true; throw new Error('falha injetada no registro derivado'); }
+    return originalRename(from, to);
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root), /falha injetada no registro derivado/);
+  assert.equal(injected, true);
+  assert.deepEqual(snapshot(root), before);
+  assert.deepEqual(fs.readFileSync(join(root, '.git/index')), index);
+  assert.deepEqual(fs.readFileSync(join(root, fallback)), initial);
+});
+
 test('conteúdo humano é preservado quando a escrita lança erro após promover o arquivo', t => {
   const root = fixture(t), rename = fs.renameSync;
   const failure = new Error('falha depois de promover');

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

@@ -913,6 +913,9 @@ test('formatos desconhecidos ou fora do cliente falham antes de mutar', t => {
   for (const row of [
     'formato|.missing|skills|agrupado', 'formato|.codex|unknown|agrupado',
     'formato|.codex|skills|mdc', 'formato|.codex|rules|prompt',
+    'formato|.codex|agents|nenhum', 'formato|.codex|commands|nenhum',
+    'fallback|.codex|.missing|skills', 'fallback|.codex|.codex|skills',
+    'fallback|.codex|.agents|rules',
     'formato|.codex|skills|plano\nformato|.codex|skills|agrupado',
     'descoberta|.codex|antigravity', 'descoberta|.agents|antigravity',
   ]) {
@@ -922,3 +925,22 @@ test('formatos desconhecidos ou fora do cliente falham antes de mutar', t => {
   assert.equal(resourcePath('.pbai4devs/commands/team/check/COMMAND.md', 'commands', 'arquivo'), 'commands/team/check.md');
   assert.throws(() => resourcePath(source, 'skills', 'arquivo'), /Skills/);
 });
+
+test('sincronização direta recusa troca concorrente da obstrução de fallback', t => {
+  const root = fixture(t, true);
+  write(root, source, skill);
+  write(root, '.pbai4devs/espelhos.conf', [
+    'agente|.agents|agrupado', 'agente|.codex|agrupado',
+    'formato|.codex|skills|nenhum', 'fallback|.codex|.agents|skills',
+  ].join('\n') + '\n');
+  write(root, '.agents/skills/projeto', 'Obstrução humana.');
+  let called = false;
+  assert.throws(() => synchronize({ root, localIgnores: false, generateEntrypoints: false, output() {
+    if (called) return;
+    called = true;
+    rmSync(join(root, '.agents/skills/projeto')); // Simula mudança humana após o planejamento.
+  } }), /mudou apos o planejamento/);
+  assert.equal(called, true);
+  assert.equal(existsSync(join(root, '.codex')), false);
+  assert.equal(existsSync(join(root, '.agents/skills/projeto/demo/SKILL.md')), false);
+});

package/.pbai4devs/scripts/testar-maturidade/README.md

@@ -14,19 +14,21 @@ node .pbai4devs/scripts/testar-maturidade/SCRIPT.mjs run --case legado
 node --test .pbai4devs/scripts/testar-maturidade/tests/TEST.mjs
 ```
 
-`prepare` só gera as cópias; `run` gera e executa. Os oito cenários ficam em
-`examples/generated/`: agentes, descoberta, planejamento, aplicação inicial,
-configurada, manutenção, legado e monorepo com caminhos em português.
+`prepare` só gera as cópias; `run` gera e executa. Cada execução cria uma nova
+pasta `examples/generated/maturity-*` e informa seu caminho no console. Por
+padrão são oito cenários: agentes, descoberta, planejamento, aplicação inicial,
+configurada, manutenção, legado e monorepo com caminhos em português. Use
+`--case` para executar apenas um.
 
 O harness copia recursos e configurações reais; exclui pacotes, caches, logs,
 resultados de testes, Playwright e pastas temporárias em qualquer caixa,
 `.git` e nomes conhecidos de credenciais/overrides locais. Não faz varredura
 semântica de segredos. A API também aceita `tmp/examples/` para compatibilidade
-e descendentes de `.agent-tests/`. Regenera apenas pastas identificadas como
-suas. Cada exemplo recebe Git local, sem commits nem identidade alterada.
-O diretório gerado contém um ignore próprio, inclusive em projetos consumidores.
-`prepare` redefine o relatório como `prepared`, sem conservar provas antigas.
-Se a preparação falhar, o índice fica em `preparing` e o relatório antigo sai.
+e descendentes de `.agent-tests/`. Um destino explícito deve ser inexistente;
+execuções e projetos anteriores não são substituídos nem removidos. Cada
+exemplo recebe Git local, sem commits nem identidade alterada. O diretório
+gerado contém um ignore próprio, inclusive em projetos consumidores. Se a
+preparação falhar, o índice da nova execução permanece em `preparing`.
 O hub `.pbai4devs` e os clientes registrados são copiados, incluindo comandos
 nativos em TOML. Sem manifesto local, os templates definem os clientes em
 memória, respeitando a seleção salva. `.vscode` exige registro. Apenas as entradas
@@ -50,5 +52,5 @@ O gate positivo simula o parecer para testar seu contrato; não representa
 revisão humana. Estados de aprovação são dados sintéticos. Nenhum teste
 certifica produção, Docker, interface visual ou outro sistema operacional.
 
-Índice e relatório: `examples/generated/README.md` e `REPORT.json`. Logs e provas
-individuais ficam em `.agent-tests/` dentro de cada exemplo, todos ignorados.
+Índice e relatório ficam em `README.md` e `REPORT.json` na pasta informada.
+Logs e provas ficam em `.agent-tests/` dentro de cada exemplo, todos ignorados.

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)) {