@pathbit/agentdevkit 0.0.7 → 0.0.8

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';
 
@@ -354,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,15 @@ 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.

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.7 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.7
+[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

package/README.es.md

@@ -35,7 +35,7 @@ Después, abre el proyecto en tu agente y pide:
 La [guía de instalación](docs/guides/installation.md) incluye Windows, Node ausente,
 simulación y actualización. Instala y actualiza mediante el
 [paquete npm público][packages];
-la [release v0.0.7][release] conserva artefactos y checksums para verificarlos.
+la [release v0.0.8][release] conserva artefactos y checksums para verificarlos.
 No requiere instalación global.
 La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 
@@ -80,7 +80,7 @@ formularios. Consulta [cómo participar](docs/maintainers/community.md).
 al agente que lea `AGENTS.md`.
 
 [clients]: .pbai4devs/COMPATIBILIDADE.md
-[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.7
+[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

package/README.md

@@ -32,7 +32,7 @@ Depois, abra o projeto no seu agente e peça:
 
 Windows, instalação sem Node, simulação e atualização estão no
 [guia de instalação](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/installation.md). A distribuição usa a
-versão publicada no [npm público][packages] e na [release v0.0.7][release],
+versão publicada no [npm público][packages] e na [release v0.0.8][release],
 sem instalação global. Instalação e atualização usam o pacote do registro;
 os arquivos da release servem para conferir os artefatos publicados.
 O idioma da CLI pode ser `pt`, `en` ou `es`.
@@ -89,7 +89,7 @@ ao seu agente para ler `AGENTS.md`.
 [help]: https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/troubleshooting.md
 [issues]: https://github.com/pathbit/AgentDevKit/issues/new/choose
 [packages]: https://github.com/pathbit/AgentDevKit/blob/master/docs/maintainers/packages.md
-[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.7
+[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

package/docs/guides/cli.md

@@ -63,6 +63,15 @@ e `unlock`. Consultar ou executar não instala silenciosamente.
 `setup` prepara as ferramentas compatíveis; outros comandos podem receber
 um nome ou grupo. Consulte [ferramentas e testes](tools-and-testing.md).
 
+Em `tools`, use `--` antes dos argumentos que pertencem à ferramenta:
+
+```console
+npx @pathbit/agentdevkit tools run agent-browser -- --json --help
+```
+
+Nesse exemplo, `--json` pertence ao agent-browser. Opções do kit ficam antes
+do separador. `--help` e `--version` do kit não exigem um projeto instalado.
+
 ## JSON e retorno
 
 As respostas incluem `ok`, `command`, `version`, `language`, `target` e

package/docs/guides/installation.md

@@ -64,6 +64,8 @@ O bloco local também protege `.agent-tests`, `tmp`, `temp`, `.playwright*`
 e relatórios de testes, inclusive com letras maiúsculas e em subpastas.
 O `.gitignore` existente e seus arquivos rastreados são preservados;
 uma exceção humana que conflite com essa proteção é informada como conflito.
+Nomes próprios de artefatos e arquivos existentes também são conferidos;
+a validação fica restrita ao projeto e aos ignores de seus ancestrais.
 
 Arquivos já rastreados exigem migração do índice: apenas saídas identificadas
 do kit podem deixar de ser rastreadas, preservando seus bytes no disco.
@@ -86,10 +88,14 @@ Links simbólicos em caminhos usados pela instalação podem bloquear a operaç
 O kit informa o caminho e não converte nem remove o link automaticamente.
 Use a simulação para identificar esse caso antes de aplicar.
 
+Arquivos humanos não se tornam gerenciados apenas por conterem um link.
+As alterações de arquivos existentes preservam permissões, inclusive em backup
+e restauração após falha.
+
 O [fluxo de trabalho](workflow.md) orienta a próxima etapa do projeto.
 Se houver erro, consulte [solução de problemas](troubleshooting.md).
 
-[Wiki](../README.md) · [Spec v0.0.7][spec]
+[Wiki](../README.md) · [Spec v0.0.8][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.7/SPEC.md
+[spec]: ../specs/v0.0.8/SPEC.md

package/docs/guides/tools-and-testing.md

@@ -32,6 +32,8 @@ node .pbai4devs/scripts/preparar-ferramentas/SCRIPT.mjs setup
 `setup` reutiliza instalações saudáveis e verifica as compatíveis. Um nome
 ou grupo limita a seleção. `check`, `info` e `run` não trocam uma consulta
 por instalação. Downloads, caches e recibos permanecem locais e ignorados.
+O gerenciador recusa links simbólicos nos caminhos que escreve ou usa como
+estado local; a atualização não segue esses links para fora da instalação.
 
 ## Escolher a prova
 

package/docs/maintainers/packages.md

@@ -64,7 +64,7 @@ existir; a primeira publicação pode usar o secret `NPMJS_TOKEN`.
 Para publicar somente o pacote de uma tag que já tem artefato aprovado:
 
 ```console
-gh workflow run release.yml --ref master -f tag=v0.0.7 -F package_only=true
+gh workflow run release.yml --ref master -f tag=v0.0.8 -F package_only=true
 ```
 
 Se o artefato expirou, reexecute o CI original da tag antes da publicação.

package/docs/product/roadmap.md

@@ -18,6 +18,7 @@ status: vigente
 | Instalação pelo registro v0.0.5 | Pacote publicado | [Spec][registry]. |
 | Apresentação e licença v0.0.6 | Distribuição e atualização | [Spec][public]. |
 | Compatibilidade real v0.0.7 | Testes em clones existentes | [Spec][oss]. |
+| Preservação v0.0.8 | Auditoria e regressões | [Spec][robustness]. |
 
 A primeira entrega segue a [spec v0.0.1](../specs/v0.0.1/SPEC.md), disponível
 na [release v0.0.1][release]. Os detalhes de mudanças estão no
@@ -38,3 +39,4 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [registry]: ../specs/v0.0.5/SPEC.md
 [public]: ../specs/v0.0.6/SPEC.md
 [oss]: ../specs/v0.0.7/SPEC.md
+[robustness]: ../specs/v0.0.8/SPEC.md

package/docs/specs/README.md

@@ -12,6 +12,7 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.5](v0.0.5/SPEC.md): instalação pelo registro em todos os fluxos.
 - [v0.0.6](v0.0.6/SPEC.md): apresentação pública, licença e atualização segura.
 - [v0.0.7](v0.0.7/SPEC.md): projetos reais e proteção local de artefatos.
+- [v0.0.8](v0.0.8/SPEC.md): preservação, transações e validação aprofundada.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

package/docs/specs/v0.0.8/README.md

@@ -0,0 +1,10 @@
+---
+description: Validação aprofundada e preservação de dados do AgentDevKit.
+---
+
+# Versão 0.0.8
+
+A [spec](SPEC.md) reúne correções da auditoria do instalador, sincronizador,
+gerenciador de ferramentas, CLI e regras de ignore.
+
+[Specs](../README.md)

package/docs/specs/v0.0.8/SPEC.md

@@ -0,0 +1,62 @@
+---
+description: Correções verificadas de preservação, transações e interface CLI.
+status: aprovado
+version: 0.0.8
+---
+
+# Preservação e validação aprofundada
+
+## Objetivo e autorização
+
+Atender ao pedido de revisão profunda, corrigindo falhas comprovadas e
+publicando uma nova versão estável após validação. Esta etapa continua o
+[PRD](../../product/prd.md), o [design](../../product/design.md) e os
+[testes em projetos reais](../v0.0.7/SPEC.md).
+
+## Contrato
+
+- Não apagar ou sobrescrever arquivos humanos pela aparência de seu Markdown.
+  Exigir propriedade comprovada para limpeza automática de apontamentos.
+- Recusar conflitos conhecidos antes de escrever. Em falhas posteriores,
+  restaurar as alterações próprias sem substituir edições humanas concorrentes.
+- Preservar permissões em atualização, backup e rollback, inclusive em
+  arquivos somente para leitura quando a operação for permitida pelo sistema.
+- Recusar componentes simbólicos nos caminhos locais de ferramentas, inclusive
+  após operações externas, antes de escrever ou confirmar uma instalação.
+- Preservar integralmente argumentos após `tools ... --`; ajuda e versão
+  não exigem diretório de projeto válido.
+- Conferir artefatos existentes e exceções literais além dos nomes de amostra,
+  sem ler ignores de projetos irmãos ou desindexar arquivos humanos.
+- Manter a recusa de links simbólicos incompatíveis do Zod; não converter
+  esse bloqueio documentado em uma instalação bem-sucedida.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Markdown humano é preservado; limpeza usa propriedade comprovada. |
+| AC-002 | Falhas não deixam gravações próprias parciais nem mudam permissões. |
+| AC-003 | Gerenciador não escreve fora da instalação por links simbólicos. |
+| AC-004 | CLI repassa argumentos; ajuda funciona sem projeto. |
+| AC-005 | Ignore protege artefatos sem invadir projetos irmãos. |
+| AC-006 | Regressões, pacote público e atualização do router são verificados. |
+
+## Verificação
+
+Para AC-001 a AC-005, conservar reproduções anteriores e testes de regressão
+que falham antes da correção, com assertivas de conteúdo, modo, estado e Git.
+Executar os testes relevantes em Node 24/26 e revisar os diffs de forma
+independente. Limitações de plataforma devem ficar explícitas.
+
+Para AC-006, executar pipeline completo, cenários de maturidade e matriz OSS
+do pacote gerado. Confirmar no CI Linux, macOS e Windows; publicar o mesmo TGZ,
+comparar checksum e repetir o consumo público. Atualizar o router com preview,
+backup, diagnóstico e comparação da baseline, preservando o índice existente.
+
+Testes e fixtures são versionados. Clones e provas ficam em `tmp/` e o registro
+de revisão em `.agent-tests/`. Não prometer ausência universal de bugs.
+
+## Documentação afetada
+
+Atualizar referência da CLI, instalação, ferramentas, changelog, README,
+roadmap e índices. Não criar documentos de produto nos projetos consumidores.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",

package/src/cli.mjs

@@ -18,7 +18,10 @@ export function parseArgs(argv) {
   const options = { command: null, positionals: [], toolArgs: [], target: null, language: null, clients: undefined, yes: false, json: false, dryRun: false, force: false, check: false };
   for (let index = 0; index < argv.length; index++) {
     const arg = argv[index];
-    if (['--target', '--lang', '--agents', '--clients'].includes(arg)) {
+    if (arg === '--' && options.command === 'tools') {
+      options.toolArgs.push(...argv.slice(index));
+      break;
+    } else if (['--target', '--lang', '--agents', '--clients'].includes(arg)) {
       const value = argv[++index]; if (!value || value.startsWith('-')) usage(`Missing value: ${arg}`);
       if (arg === '--target') options.target = value;
       else if (arg === '--lang') { options.language = normalizeLanguage(value); if (!options.language) usage('Use --lang pt, en or es.'); }
@@ -86,11 +89,14 @@ function print(result, options, output) {
 
 export async function main(argv = process.argv.slice(2), context = {}) {
   const output = context.stdout || process.stdout, input = context.stdin || process.stdin, errorOutput = context.stderr || process.stderr;
-  let options = { json: argv.includes('--json') }, language = normalizeLanguage(argv[argv.indexOf('--lang') + 1]) || 'pt', target = resolve(context.cwd || process.cwd()), clients = ['all'];
+  const separator = argv.indexOf('--'), globalArgs = separator < 0 ? argv : argv.slice(0, separator);
+  let options = { json: globalArgs.includes('--json') }, language = normalizeLanguage(globalArgs[globalArgs.indexOf('--lang') + 1]) || 'pt', target = resolve(context.cwd || process.cwd()), clients = ['all'];
   try {
     options = parseArgs(argv);
-    target = resolveTarget(options.target || (options.command === 'init' ? options.positionals[0] : '.'), context.cwd || process.cwd());
-    const previous = ['help', 'version'].includes(options.command) ? null : loadState(target);
+    const informational = ['help', 'version'].includes(options.command);
+    target = informational ? resolve(context.cwd || process.cwd(), options.target || '.')
+      : resolveTarget(options.target || (options.command === 'init' ? options.positionals[0] : '.'), context.cwd || process.cwd());
+    const previous = informational ? null : loadState(target);
     language = options.language || previous?.language || 'pt';
     clients = options.clients ?? previous?.clients ?? ['all'];
     if (options.command === 'init' && !previous && !options.yes && !options.json && !options.dryRun && input.isTTY && output.isTTY && (!options.language || options.clients === undefined)) {