@pathbit/agentdevkit 0.0.6 → 0.0.8

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

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 // Planeja em memória; somente os caminhos gerenciados pelo manifesto são alterados.
-import { cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { chmodSync, cpSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, posix, resolve } from 'node:path';
 import { randomUUID, createHash } from 'node:crypto';
 import { requireNode, projectRoot, isMain } from '../lib/runtime.mjs';
 import { buildCatalog } from '../lib/catalog.mjs';
 import { resourcePath } from '../lib/resource-path.mjs';
 import { adapterManifest, resolveAdapters } from '../lib/adapters.mjs';
-import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
+import { mergeGitignore, validateIgnoreClients, renderClientIgnore, isGeneratedOutput, planLocalIgnore, applyLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, ignoreBegin, ignoreEnd } from '../lib/gitignore.mjs';
 
 const marker = '<!-- gerado: sincronizar-agentes -->';
 const tomlMarker = '# gerado: sincronizar-agentes';
@@ -113,9 +113,13 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   const referenceFile = value => {
     const info = stat(safe(value));
-    return Boolean(info?.isFile() && info.size <= 1024 * 1024 && isReference(read(absolute(value))));
+    if (!info?.isFile() || info.size > 1024 * 1024) return false;
+    const bytes = readFileSync(absolute(value)), text = normalize(bytes.toString('utf8'));
+    const recorded = installed?.files?.[value] === createHash('sha256').update(bytes).digest('hex');
+    const marked = text.split('\n').includes(marker) || text.startsWith(tomlMarker + '\n');
+    return isReference(text) && (marked || recorded);
   };
-  const onlyReferences = value => scan(value).every(file => /\.(md|mdc|toml)$/.test(file) && referenceFile(file));
+  const onlyReferences = value => { const files = scan(value); return files.length > 0 && files.every(file => /\.(md|mdc|toml)$/.test(file) && referenceFile(file)); };
   const protectedPath = value => /^(workflows(?:\/|$)|settings\.json$|extensions\.json$)/.test(value.slice(value.indexOf('/') + 1).toLowerCase());
   const agents = new Map();
   const formats = new Map();
@@ -237,6 +241,7 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   }
   function cleanScope(value) {
     if (!stat(safe(value))) return;
+    if (stat(safe(value)).isDirectory() && !scan(value).length) return;
     if (force && value.split('/')[1] === 'external-skills') planRemove(value, true);
     else if (onlyReferences(value)) planRemove(value);
     else if (force) planRemove(value, true);
@@ -410,16 +415,72 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   const removals = topPaths(remove);
   const backups = topPaths(backup);
   const rootEntryChanges = [...rootEntries].filter(([name, content]) => !stat(absolute(name)) || readFileSync(absolute(name), 'utf8') !== content);
+  const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
+  const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
+  const configChanged = !configExists || configText !== finalConfig;
+  function capture(value) {
+    const file = safe(value), info = stat(file);
+    if (!info) return null;
+    if (info.isFile()) return { mode: info.mode & 0o777, data: readFileSync(file) };
+    if (!info.isDirectory()) fail(`Tipo de arquivo nao suportado: ${value}`);
+    return { mode: info.mode & 0o777, children: Object.fromEntries(readdirSync(file).sort(compare).map(name => [name, capture(`${value}/${name}`)])) };
+  }
+  function fingerprint(value) {
+    return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+  }
+  const transactionRoots = topPaths([...removals, ...changed, ...registries.keys(), ...ignoreFiles.keys(), ...rootEntryChanges.map(([name]) => name), ...(configChanged ? [config] : [])]);
+  const originals = new Map(transactionRoots.map(value => [value, capture(value)]));
+  const currentHashes = new Map([...originals].map(([value, content]) => [value, fingerprint(content)]));
+  const originalDirectories = new Set();
+  for (const value of transactionRoots) {
+    let parent = posix.dirname(value);
+    while (parent !== '.') { if (stat(safe(parent))?.isDirectory()) originalDirectories.add(parent); parent = posix.dirname(parent); }
+  }
+  const touched = new Set(), createdDirectories = new Set(), restoredDirectories = new Set();
+  const prunedDirectories = new Map();
+  let restoring = 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 };
   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.`);
   if (check) return { ...summary, ownedOutputs, exitCode: dirty ? 1 : 0 };
   if (conflicts.size) fail(`Use --force para reconstruir somente os caminhos gerenciados: ${sorted(conflicts).join(', ')}`);
+  if (localStatus.missing.length) fail(`Regras humanas reabrem derivados locais: ${localStatus.missing.join(', ')}`);
+  if (localPlan) assertLocalIgnoreUnchanged(localPlan);
+  function ensureDirectory(value) {
+    let parent = posix.dirname(value);
+    const missing = [];
+    while (parent !== '.' && !stat(safe(parent))) { missing.push(parent); parent = posix.dirname(parent); }
+    for (const directory of missing.reverse()) {
+      mkdirSync(safe(directory)); createdDirectories.add(directory);
+      if (restoring) restoredDirectories.add(directory);
+    }
+  }
+  function mutate(value, action, text) {
+    const boundary = transactionRoots.find(root => value === root || value.startsWith(root + '/'));
+    if (!boundary || fingerprint(capture(boundary)) !== currentHashes.get(boundary)) fail(`Arquivo mudou apos planejar: ${value}`);
+    const beforeHash = currentHashes.get(boundary);
+    touched.add(boundary);
+    let failure;
+    try { action(); } catch (error) { failure = error; }
+    let afterHash;
+    try { afterHash = fingerprint(capture(boundary)); }
+    catch (error) { currentHashes.set(boundary, 'conteudo-concorrente'); throw failure || error; }
+    const matches = text === undefined || (text === null ? !stat(safe(value)) : stat(safe(value))?.isFile() && readFileSync(absolute(value)).equals(Buffer.from(text)));
+    if (!matches && afterHash !== beforeHash) {
+      currentHashes.set(boundary, 'conteudo-concorrente');
+      if (failure) throw failure;
+      fail(`Mudanca concorrente preservada: ${value}`);
+    }
+    currentHashes.set(boundary, afterHash);
+    if (failure) throw failure;
+    if (!matches) fail(`Arquivo nao corresponde a gravacao planejada: ${value}`);
+  }
   function atomic(value, text) {
     const target = safe(value);
-    mkdirSync(dirname(target), { recursive: true });
+    const mode = stat(target)?.isFile() ? stat(target).mode & 0o777 : undefined;
+    ensureDirectory(value);
     const temporary = `${target}.sync.${randomUUID()}`;
-    try { writeFileSync(temporary, text, { flag: 'wx' }); renameSync(temporary, target); }
+    try { writeFileSync(temporary, text, { flag: 'wx' }); if (mode !== undefined) chmodSync(temporary, mode); renameSync(temporary, target); }
     finally { rmSync(temporary, { force: true }); }
   }
   let backupRoot;
@@ -433,21 +494,60 @@ export function synchronize({ root = projectRoot, check = false, force = false,
     }
     output(`Backup local: ${posix.join('.agent-tests', backupRoot.slice(backupRoot.lastIndexOf('/') + 1).split('\\').at(-1))}`);
   }
-  for (const value of removals) rmSync(safe(value), { recursive: true, force: true });
-  for (const value of changed) atomic(value, expected.get(value));
-  for (const [value, text] of registries) atomic(value, text);
-  for (const [value, text] of ignoreFiles) atomic(value, text);
-  for (const [value, text] of rootEntryChanges) atomic(value, text);
-  if (localPlan) applyLocalIgnore(localPlan);
-  function pruneEmpty(value) {
-    if (!stat(safe(value))?.isDirectory()) return;
-    for (const name of readdirSync(absolute(value))) if (stat(safe(`${value}/${name}`))?.isDirectory()) pruneEmpty(`${value}/${name}`);
-    if (!readdirSync(absolute(value)).length) rmdirSync(absolute(value));
+  function restore(value, content) {
+    rmSync(safe(value), { recursive: true, force: true });
+    if (!content) return;
+    ensureDirectory(value);
+    if (content.data) writeFileSync(safe(value), content.data);
+    else {
+      mkdirSync(safe(value));
+      for (const [name, child] of Object.entries(content.children)) restore(`${value}/${name}`, child);
+    }
+    chmodSync(safe(value), content.mode);
+  }
+  try {
+    if (localPlan) assertLocalIgnoreUnchanged(localPlan);
+    for (const value of removals) mutate(value, () => rmSync(safe(value), { recursive: true, force: true }), null);
+    for (const value of changed) mutate(value, () => atomic(value, expected.get(value)), expected.get(value));
+    for (const [value, text] of registries) mutate(value, () => atomic(value, text), text);
+    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);
+    // Só os ancestrais de remoções conhecidas são candidatos à limpeza.
+    for (const value of removals) {
+      let parent = posix.dirname(value);
+      const boundary = value.split('/').slice(0, 2).join('/');
+      while (parent.startsWith(boundary + '/') || parent === boundary) {
+        const info = stat(safe(parent));
+        if (!info?.isDirectory() || readdirSync(absolute(parent)).length) break;
+        rmdirSync(safe(parent)); prunedDirectories.set(parent, info.mode & 0o777); parent = posix.dirname(parent);
+      }
+    }
+    if (localPlan) applyLocalIgnore(localPlan);
+  } catch (error) {
+    const failures = [];
+    restoring = true;
+    for (const value of [...touched].reverse()) {
+      try {
+        if (fingerprint(capture(value)) !== currentHashes.get(value)) fail(`Mudanca concorrente preservada: ${value}`);
+        restore(value, originals.get(value));
+      } catch (failure) { failures.push(failure); }
+    }
+    for (const [directory, mode] of [...prunedDirectories].sort(([left], [right]) => right.length - left.length)) {
+      try {
+        if (!stat(safe(directory))) ensureDirectory(`${directory}/.restore-probe`);
+        const info = stat(safe(directory));
+        if (!info?.isDirectory() || !restoredDirectories.has(directory) && (info.mode & 0o777) !== mode) fail(`Diretorio concorrente preservado: ${directory}`);
+        chmodSync(safe(directory), mode);
+      } catch (failure) { failures.push(failure); }
+    }
+    for (const directory of sorted(createdDirectories).sort((a, b) => b.length - a.length)) {
+      try { if (!originalDirectories.has(directory) && stat(safe(directory))?.isDirectory() && !readdirSync(absolute(directory)).length) rmdirSync(safe(directory)); }
+      catch (failure) { failures.push(failure); }
+    }
+    if (failures.length) throw new AggregateError([error, ...failures], `${error.message}; rollback incompleto: ${failures.map(failure => failure.message).join('; ')}`);
+    throw error;
   }
-  for (const agent of agents.keys()) for (const kind of [...Object.keys(principals), 'instructions', 'prompts']) pruneEmpty(`${agent}/${kind}`);
-  const omittedRows = new Set([...legacy, ...missing.map(native => native.index)]);
-  const finalConfig = rows.filter((row, index) => !omittedRows.has(index)).join('\n').replace(/\n*$/, '\n');
-  if (!configExists || configText !== finalConfig) atomic(config, finalConfig);
   return { ...summary, ownedOutputs, exitCode: 0, ...(backupRoot ? { backupRoot } : {}) };
 }
 

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

@@ -0,0 +1,145 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { syncBuiltinESMExports } from 'node:module';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { projectRoot } from '../../lib/runtime.mjs';
+import { isReference, synchronize } from '../SCRIPT.mjs';
+
+const hash = value => createHash('sha256').update(value).digest('hex');
+const source = '.pbai4devs/skills/demo/SKILL.md';
+const generated = '.claude/skills/demo/SKILL.md';
+const human = '# Título\n\nLeia [manual](https://example.com/manual).\n';
+function write(root, path, data) { fs.mkdirSync(dirname(join(root, path)), { recursive: true }); fs.writeFileSync(join(root, path), data); }
+function fixture(t) {
+  const root = fs.realpathSync(fs.mkdtempSync(join(tmpdir(), 'agentdevkit-ownership-')));
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+  write(root, '.pbai4devs/espelhos.conf', 'agente|.claude|plano\n');
+  write(root, source, '---\nname: demo\ndescription: Exemplo.\n---\n\n# Demo\n');
+  for (const name of ['agents.ignore', 'shared.ignore', 'local.ignore', 'clients.json']) write(root, `.pbai4devs/templates/gitignore/${name}`, fs.readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore', name)));
+  const initialized = spawnSync('git', ['-C', root, 'init', '-q'], { encoding: 'utf8' });
+  assert.equal(initialized.status, 0, initialized.stderr);
+  return root;
+}
+const run = (root, options = {}) => synchronize({ root, generateEntrypoints: false, localIgnores: false, output() {}, ...options });
+function snapshot(root) {
+  const files = {};
+  function visit(path, prefix = '') {
+    for (const entry of fs.readdirSync(path, { withFileTypes: true })) {
+      if (entry.name === '.git') continue;
+      const next = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) { files[next] = 'directory'; visit(join(path, entry.name), next); }
+      else files[next] = hash(fs.readFileSync(join(path, entry.name)));
+    }
+  }
+  visit(root); return files;
+}
+
+test('texto humano com formato de referência nunca comprova propriedade', t => {
+  for (const path of [generated, '.claude/skills/human.md']) {
+    const root = fixture(t); write(root, path, human);
+    const before = snapshot(root);
+    assert.equal(isReference(human), true, 'O parser de formato continua independente da propriedade.');
+    assert.equal(run(root, { check: true }).exitCode, 1);
+    assert.throws(() => run(root), /--force/);
+    assert.deepEqual(snapshot(root), before);
+    assert.equal(fs.readFileSync(join(root, path), 'utf8'), human);
+  }
+});
+
+test('hash registrado comprova referência legada sem marcador e diretório vazio humano permanece', t => {
+  const root = fixture(t), stale = '.claude/skills/legacy.md';
+  write(root, stale, human);
+  write(root, '.pbai4devs/estado/agentdevkit.json', JSON.stringify({ schemaVersion: 1, clients: ['claude'], files: { [stale]: hash(human) }, blocks: {} }));
+  fs.mkdirSync(join(root, '.claude/skills/user-empty'), { recursive: true });
+  run(root);
+  assert.equal(fs.existsSync(join(root, stale)), false);
+  assert.equal(fs.existsSync(join(root, '.claude/skills/user-empty')), true);
+  assert.equal(run(root, { check: true }).exitCode, 0);
+});
+
+test('conflito de ignore é recusado antes de criar recursos ou catálogos', t => {
+  const root = fixture(t); write(root, '.gitignore', '!/.agent-tests/\n!/.agent-tests/**\n');
+  const before = snapshot(root), exclude = fs.readFileSync(join(root, '.git/info/exclude'));
+  assert.throws(() => run(root, { localIgnores: true, force: true }), /Regras humanas/);
+  assert.deepEqual(snapshot(root), before);
+  assert.deepEqual(fs.readFileSync(join(root, '.git/info/exclude')), exclude);
+  assert.equal(fs.existsSync(join(root, generated)), false);
+  assert.equal(fs.existsSync(join(root, '.pbai4devs/catalog.json')), false);
+});
+
+test('atualização de referência própria conserva permissões', t => {
+  const root = fixture(t); run(root);
+  fs.chmodSync(join(root, generated), 0o600);
+  const mode = fs.statSync(join(root, generated)).mode & 0o777;
+  write(root, source, '---\nname: demo\ndescription: Atualizado.\n---\n\n# Demo\n');
+  run(root);
+  assert.equal(fs.statSync(join(root, generated)).mode & 0o777, mode);
+});
+
+test('mudança concorrente de ignore após gravação reverte recursos e preserva a regra humana', t => {
+  const root = fixture(t); run(root);
+  write(root, source, '---\nname: demo\ndescription: Atualizado.\n---\n\n# Demo\n');
+  const before = snapshot(root), rename = fs.renameSync;
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    rename(from, to);
+    if (!injected && to === join(root, generated)) { injected = true; write(root, '.git/info/exclude', '# concurrent human change\n'); }
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root, { localIgnores: true }), /Exclusao alterada apos planejar/);
+  assert.equal(injected, true);
+  assert.deepEqual(snapshot(root), before);
+  assert.equal(fs.readFileSync(join(root, '.git/info/exclude'), 'utf8'), '# concurrent human change\n');
+});
+
+test('conteúdo humano concorrente não é apagado durante rollback', t => {
+  const root = fixture(t), rename = fs.renameSync;
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    rename(from, to);
+    if (!injected && to === join(root, generated)) { injected = true; write(root, generated, human); }
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root), /Mudanca concorrente preservada/);
+  assert.equal(injected, true);
+  assert.equal(fs.readFileSync(join(root, generated), 'utf8'), human);
+});
+
+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');
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    rename(from, to);
+    if (!injected && to === join(root, generated)) { injected = true; write(root, generated, human); throw failure; }
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root), error => error instanceof AggregateError && error.errors.includes(failure));
+  assert.equal(injected, true);
+  assert.equal(fs.readFileSync(join(root, generated), 'utf8'), human);
+});
+
+test('rollback recria ancestral podado com suas permissões originais', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t); run(root);
+  const parent = join(root, '.claude/skills'); fs.chmodSync(parent, 0o700);
+  fs.rmSync(join(root, '.pbai4devs/skills/demo'), { recursive: true });
+  const before = snapshot(root), rename = fs.renameSync;
+  let injected = false;
+  t.mock.method(fs, 'renameSync', (from, to) => {
+    rename(from, to);
+    if (!injected && to === join(root, '.pbai4devs/catalog.json')) { injected = true; write(root, '.git/info/exclude', '# concurrent human change\n'); }
+  });
+  syncBuiltinESMExports();
+  t.after(() => { t.mock.restoreAll(); syncBuiltinESMExports(); });
+  assert.throws(() => run(root, { localIgnores: true }), /Exclusao alterada apos planejar/);
+  assert.equal(injected, true);
+  assert.deepEqual(snapshot(root), before);
+  assert.equal(fs.statSync(parent).mode & 0o777, 0o700);
+});

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

@@ -1,10 +1,12 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import { syncBuiltinESMExports } from 'node:module';
 import { projectRoot } from '../../lib/runtime.mjs';
 import { planLocalIgnore, applyLocalIgnore, checkLocalIgnore, planUntrack, applyUntrack, restoreUntrack, assertLocalIgnoreUnchanged } from '../../lib/gitignore.mjs';
 
@@ -129,6 +131,72 @@ test('raízes dedicadas são locais, enquanto configurações de GitHub e VS Cod
   assert.ok(tracked.includes('.github/settings.json')); assert.ok(tracked.includes('.vscode/settings.json'));
 });
 
+test('artefatos vêm da política compartilhada e não entram na lista de outputs', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.agent-tests/human.txt', 'evidência humana'); git(root, ['add', '-f', '.agent-tests/human.txt']);
+  const plan = planLocalIgnore(root, { outputs: ['AGENTS.md'] });
+  assert.ok(plan.artifactProbes.some(path => path.startsWith('.agent-tests/')));
+  assert.ok(plan.artifactProbes.some(path => path.startsWith('.agentdevkit-ignore-probes/')));
+  assert.ok(plan.paths.every(path => !plan.artifactProbes.includes(path)));
+  assert.ok(!plan.trackedOutputs.includes('.agent-tests/human.txt'));
+  applyLocalIgnore(plan);
+  for (const path of ['.agent-tests/x', 'TMP/x', 'nested/TeMp/x', '.PlAyWrIgHt-McP/x', 'nested/playwright-report/x', 'TEST-RESULTS/x', 'nested/TestResults/x', 'BLOB-REPORT/x']) {
+    assert.equal(git(root, ['check-ignore', '--no-index', path]).trim(), path);
+  }
+  assert.equal(git(root, ['ls-files', '.agent-tests/human.txt']).trim(), '.agent-tests/human.txt');
+  assert.equal(readFileSync(join(root, '.agent-tests/human.txt'), 'utf8'), 'evidência humana');
+  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs: ['AGENTS.md'] })).ok, true);
+});
+
+test('regras de artefatos são limitadas ao projeto dentro do monorepo', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const child = join(root, 'apps', 'my project'); mkdirSync(child, { recursive: true });
+  applyLocalIgnore(planLocalIgnore(child, { outputs: ['AGENTS.md'] }));
+  for (const path of ['apps/my project/.agent-tests/x', 'apps/my project/nested/.Playwright-MCP/x', 'apps/my project/sub/test-results/x']) {
+    assert.equal(git(root, ['check-ignore', '--no-index', path]).trim(), path);
+  }
+  for (const path of ['apps/other/.agent-tests/x', 'apps/other/tmp/x', '.agent-tests/x']) {
+    const result = spawnSync('git', ['-C', root, 'check-ignore', '--no-index', path], { encoding: 'utf8' });
+    assert.equal(result.status, 1, path + result.stderr);
+  }
+});
+
+test('ignore global não mascara a ausência das regras locais de artefatos', t => {
+  const root = fixture(t), outside = fixture(t); git(root, ['init', '-q']);
+  put(outside, 'global.ignore', '*\n');
+  git(root, ['config', 'core.excludesFile', join(outside, 'global.ignore')]);
+  const plan = planLocalIgnore(root, { outputs: ['AGENTS.md'] });
+  assert.equal(plan.edits.length, 1);
+  const missing = checkLocalIgnore({ ...plan, edits: [] });
+  assert.ok(missing.missing.some(path => path.startsWith('.agent-tests/')));
+  applyLocalIgnore(plan);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs: ['AGENTS.md'] })).ok, true);
+});
+
+test('negação humana de artefatos bloqueia aplicação sem modificar regras ou índice', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const human = '!/.agent-tests/**\n'; put(root, '.gitignore', human);
+  const exclude = readFileSync(join(root, '.git/info/exclude'));
+  const plan = planLocalIgnore(root, { outputs: ['AGENTS.md'] });
+  assert.ok(checkLocalIgnore(plan).missing.some(path => path.startsWith('.agent-tests/')));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), exclude);
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), human);
+});
+
+test('probes reconhecem exceções humanas para nomes reais de Playwright', async t => {
+  for (const path of ['.playwright-mcp', 'playwright-report', 'playwright/.cache']) await t.test(path, subtest => {
+    const root = fixture(subtest); git(root, ['init', '-q']);
+    const prefixes = path.split('/').map((_part, index, parts) => '!/' + parts.slice(0, index + 1).join('/') + '/');
+    const human = [...prefixes, `!/${path}/**`, ''].join('\n'); put(root, '.gitignore', human);
+    const before = readFileSync(join(root, '.git/info/exclude'));
+    const plan = planLocalIgnore(root, { outputs: ['AGENTS.md'] });
+    assert.ok(checkLocalIgnore(plan).missing.some(probe => probe.startsWith(path + '/')));
+    assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+    assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), before);
+  });
+});
+
 test('milhares de caminhos usam stdin e não ampliam metadata de área já ignorada', t => {
   const root = fixture(t); git(root, ['init', '-q']); put(root, '.gitignore', '/ignored/\n');
   const before = readFileSync(join(root, '.git/info/exclude'), 'utf8');
@@ -288,3 +356,145 @@ test('worktree usa a raiz nativa, exclude comum e seu próprio índice', t => {
   assert.equal(git(linked, ['show', ':generated.md']), 'gerado\n');
   assert.equal(git(root, ['ls-files', 'generated.md']), '');
 });
+
+test('exceções com nomes arbitrários de artefatos não passam por amostragem', t => {
+  for (const [name, directory] of [['.playwright-custom', true], ['.playwright-report.json', false], ['playwright-e2e', true]]) {
+    const root = fixture(t); git(root, ['init', '-q']);
+    const human = `!/${name}${directory ? '/' : ''}\n${directory ? `!/${name}/**\n` : ''}`;
+    put(root, '.gitignore', human);
+    const before = readFileSync(join(root, '.git/info/exclude'));
+    const plan = planLocalIgnore(root);
+    assert.ok(checkLocalIgnore(plan).missing.some(path => path.startsWith(name)), name);
+    assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+    assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), human);
+    assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), before);
+  }
+});
+
+test('arquivo real reaberto por glob é detectado também se surgir após o plano', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '!/.playwright-report-*.json\n');
+  const plan = planLocalIgnore(root), path = '.playwright-report-real.json';
+  put(root, path, 'artefato local\n');
+  assert.ok(checkLocalIgnore(plan).missing.includes(path));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.equal(readFileSync(join(root, path), 'utf8'), 'artefato local\n');
+});
+
+test('regras customizadas aninhadas continuam válidas e incluem pais ocultos', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const policy = readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore/agents.ignore'), 'utf8');
+  put(root, '.pbai4devs/templates/gitignore/agents.ignore', `${policy}\n**/reports/cache*/\n`);
+  const path = '.hidden/reports/cache-custom/out.json';
+  put(root, path, 'local\n');
+  put(root, '.gitignore', '!/.hidden/reports/cache-custom/\n!/.hidden/reports/cache-custom/**\n');
+  const plan = planLocalIgnore(root);
+  assert.ok(checkLocalIgnore(plan).missing.includes(path));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.equal(readFileSync(join(root, path), 'utf8'), 'local\n');
+});
+
+test('chaves literais em padrões Git não viram expansão de glob', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const policy = readFileSync(join(projectRoot, '.pbai4devs/templates/gitignore/agents.ignore'), 'utf8');
+  put(root, '.pbai4devs/templates/gitignore/agents.ignore', `${policy}\n**/cache{keep,archive}/\n`);
+  put(root, 'cachekeep/source.txt', 'código humano\n');
+  put(root, '.gitignore', '!cachekeep/**\n');
+  assert.doesNotThrow(() => applyLocalIgnore(planLocalIgnore(root)));
+  assert.equal(readFileSync(join(root, 'cachekeep/source.txt'), 'utf8'), 'código humano\n');
+});
+
+test('exceção nominal de um ignore ancestral é conferida no subprojeto', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '!/modules/app/.playwright-personal/\n!/modules/app/.playwright-personal/**\n');
+  const child = join(root, 'modules/app'); mkdirSync(child, { recursive: true });
+  const plan = planLocalIgnore(child);
+  assert.ok(checkLocalIgnore(plan).missing.some(path => path.startsWith('.playwright-personal/')));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+});
+
+test('escrita de exclusões preserva permissões e detecta alteração concorrente', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const exclude = join(root, '.git/info/exclude'); chmodSync(exclude, 0o600);
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.equal(statSync(exclude).mode & 0o777, 0o600);
+  const changed = planLocalIgnore(root, { outputs: ['new-generated.md'] });
+  chmodSync(exclude, 0o640);
+  assert.throws(() => applyLocalIgnore(changed), /alterada apos planejar/);
+  assert.equal(statSync(exclude).mode & 0o777, 0o640);
+});
+
+test('fallback e rollback de exclusões mantêm o modo original', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t), ignore = join(root, '.gitignore');
+  put(root, '.gitignore', '# humano\n'); chmodSync(ignore, 0o600);
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.equal(statSync(ignore).mode & 0o777, 0o600);
+  const original = readFileSync(ignore); git(root, ['init', '-q']);
+  const exclude = join(root, '.git/info/exclude'), before = readFileSync(exclude);
+  chmodSync(exclude, 0o600);
+  const plan = planLocalIgnore(root); assert.equal(plan.edits.length, 2);
+  Object.defineProperty(plan.edits[1], 'after', { get() { throw new Error('injected rollback failure'); } });
+  assert.throws(() => applyLocalIgnore(plan), /injected rollback failure/);
+  assert.deepEqual(readFileSync(exclude), before); assert.equal(statSync(exclude).mode & 0o777, 0o600);
+  assert.deepEqual(readFileSync(ignore), original); assert.equal(statSync(ignore).mode & 0o777, 0o600);
+});
+
+test('rollback restaura exclusão somente leitura com escrita atômica', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t), ignore = join(root, '.gitignore');
+  put(root, '.gitignore', '# humano\n'); chmodSync(ignore, 0o444);
+  applyLocalIgnore(planLocalIgnore(root));
+  const original = readFileSync(ignore); git(root, ['init', '-q']);
+  const exclude = join(root, '.git/info/exclude'), before = readFileSync(exclude);
+  chmodSync(exclude, 0o444);
+  const plan = planLocalIgnore(root);
+  Object.defineProperty(plan.edits[1], 'after', { get() { throw new Error('readonly rollback probe'); } });
+  assert.throws(() => applyLocalIgnore(plan), /readonly rollback probe/);
+  assert.deepEqual(readFileSync(exclude), before); assert.equal(statSync(exclude).mode & 0o777, 0o444);
+  assert.deepEqual(readFileSync(ignore), original); assert.equal(statSync(ignore).mode & 0o777, 0o444);
+});
+
+test('projeto aninhado não lê gitignore inacessível do projeto irmão', { skip: process.platform === 'win32' }, t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const other = join(root, 'other/.gitignore'); put(root, 'other/.gitignore', 'tmp/\n');
+  git(root, ['add', 'other/.gitignore']); chmodSync(other, 0o000);
+  t.after(() => { try { chmodSync(other, 0o600); } catch {} });
+  const child = join(root, 'app'); mkdirSync(child);
+  const plan = planLocalIgnore(child);
+  applyLocalIgnore(plan);
+  assert.equal(checkLocalIgnore(planLocalIgnore(child)).ok, true);
+});
+
+test('falha no cleanup após promoção ainda reverte a exclusão publicada', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const file = join(root, '.git/info/exclude'), original = readFileSync(file);
+  const plan = planLocalIgnore(root), remove = fs.rmSync;
+  const injected = new Error('published cleanup failure'); let failed = false;
+  try {
+    fs.rmSync = (path, options) => {
+      if (!failed && String(path).startsWith(`${file}.agentdevkit-`) && !existsSync(path)) { failed = true; throw injected; }
+      return remove(path, options);
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => applyLocalIgnore(plan), error => error === injected);
+  } finally { fs.rmSync = remove; syncBuiltinESMExports(); }
+  assert.equal(failed, true);
+  assert.deepEqual(readFileSync(file), original);
+});
+
+test('falha irrecuperável de rollback informa também o erro original', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const file = join(root, '.git/info/exclude'), plan = planLocalIgnore(root);
+  const remove = fs.rmSync, rename = fs.renameSync;
+  const original = new Error('original cleanup failure'), rollback = new Error('restore unavailable');
+  let failed = false;
+  try {
+    fs.rmSync = (path, options) => {
+      if (!failed && String(path).startsWith(`${file}.agentdevkit-`) && !existsSync(path)) { failed = true; throw original; }
+      return remove(path, options);
+    };
+    fs.renameSync = (from, to) => { if (failed && to === file) throw rollback; return rename(from, to); };
+    syncBuiltinESMExports();
+    assert.throws(() => applyLocalIgnore(plan), error => error instanceof AggregateError
+      && error.cause === original && error.errors.includes(rollback));
+  } finally { fs.rmSync = remove; fs.renameSync = rename; syncBuiltinESMExports(); }
+});

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

@@ -10,6 +10,7 @@ import { buildCatalog } from '../../lib/catalog.mjs';
 import { toolWrapper } from '../../preparar-ferramentas/SCRIPT.mjs';
 import { mergeGitignore, ignoreBegin, ignoreEnd, validateIgnoreClients } from '../../lib/gitignore.mjs';
 import './LOCAL_IGNORE.mjs';
+import './HUMAN_OWNERSHIP.mjs';
 import { validateCatalog as validateExternalCatalog } from '../../gerenciar-skills-externas/SCRIPT.mjs';
 
 const project = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
@@ -58,7 +59,7 @@ function fixture(t, minimal = false) {
   write(root, '.pbai4devs/agents/revisor/kimi-code.yaml', '---\nname: revisor\ntools: [Read, Grep, Glob]\n---\n');
   write(root, '.pbai4devs/agents/revisor/opencode.yaml', '---\nmode: subagent\npermission:\n  edit: deny\n---\n');
   write(root, '.pbai4devs/adapters/antigravity/agents/revisor.md', pointer('../../../agents/revisor/AGENT.md', 'Revisor'));
-  write(root, '.opencode/agents/revisor/AGENT.md', '---\nmode: subagent\npermission:\n  edit: deny\n---\n\n# Revisor\n\nLeia e siga [origem](../../../.pbai4devs/agents/revisor/AGENT.md).\n');
+  write(root, '.opencode/agents/revisor/AGENT.md', `---\nmode: subagent\npermission:\n  edit: deny\n---\n\n# Revisor\n\n${marker}\nLeia e siga [origem](../../../.pbai4devs/agents/revisor/AGENT.md).\n`);
   write(root, '.github/workflows/ci.yml', 'workflow-preservado\n');
   write(root, '.vscode/settings.json', '{"fixture":"config-preservada"}\n');
   write(root, '.vscode/extensions.json', '{"recommendations":[]}\n');

package/CHANGELOG.md

@@ -4,6 +4,22 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.8 — 2026-11-11
+
+- Preservação de arquivos humanos que parecem apontamentos gerados.
+- Conflitos de ignore recusados antes das gravações e rollback revisado.
+- Permissões mantidas em atualização, backup e restauração de arquivos.
+- Caminhos simbólicos de ferramentas bloqueados antes de escrita externa.
+- Argumentos de ferramentas preservados após `--`; ajuda sem projeto válido.
+- Verificação de artefatos com nomes próprios, arquivos e regras aninhadas.
+
+## 0.0.7 — 2026-11-11
+
+- Artefatos de testes e pastas temporárias protegidos em projetos existentes.
+- Regras locais respeitam o escopo do projeto e as exceções do usuário.
+- Teste opt-in em clones reais, com commits fixos e comparação de arquivos.
+- Relato explícito de bloqueios por links simbólicos preexistentes.
+
 ## 0.0.6 — 2026-11-11
 
 - Metadados npm com autoria PathBit, palavras-chave e licença MIT.

package/README.en.md

@@ -34,7 +34,7 @@ Then open the project in your coding agent and ask:
 
 See [installation](docs/guides/installation.md) for Windows, missing Node, previews
 and updates. Install and update through the [public npm package][packages]; the
-[v0.0.6 release][release] retains artifacts and checksums for verification.
+[v0.0.8 release][release] retains artifacts and checksums for verification.
 No global installation is required.
 The CLI supports `pt`, `en` and `es`; it saves your selection per project.
 
@@ -78,7 +78,7 @@ forms. See [how to participate](docs/maintainers/community.md).
 agent to read `AGENTS.md`.
 
 [clients]: .pbai4devs/COMPATIBILIDADE.md
-[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.6
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.8
 [npm-package]: https://www.npmjs.com/package/@pathbit/agentdevkit
 [npm-badge]: https://img.shields.io/npm/v/%40pathbit%2Fagentdevkit
 [license-badge]: https://img.shields.io/badge/license-MIT-blue