@pathbit/agentdevkit 0.0.6 → 0.0.7

package/.pbai4devs/scripts/lib/gitignore.mjs

@@ -114,6 +114,52 @@ function rootProbes(root, roots) {
   return roots.filter(path => { const item = localStat(join(root, path)); return !item || item.isDirectory(); }).map(path => `${path}/.agentdevkit-ignore-probe`);
 }
 
+function artifactPolicy(templateFile) {
+  const adjacent = join(dirname(templateFile), 'agents.ignore');
+  const source = checkedLocalPath(localStat(adjacent) ? adjacent : fileURLToPath(new URL('../../templates/gitignore/agents.ignore', import.meta.url)));
+  const content = readFileSync(source, 'utf8');
+  const section = content.split(/^## Resultados e arquivos temporarios\r?$/m)[1]?.split(/^## /m)[0];
+  const patterns = section?.split(/\r?\n/).map(line => line.trim()).filter(line => line && !line.startsWith('#'));
+  if (!patterns?.length || patterns.some(pattern => !pattern.startsWith('**/') || /[!\\\x00-\x1f]/.test(pattern) || pattern.split('/').includes('..'))) throw new Error('Secao de artefatos invalida em agents.ignore.');
+  return patterns;
+}
+
+function artifactProbes(root, patterns) {
+  const probes = new Set();
+  for (const pattern of patterns) {
+    const stem = pattern.slice(3).replace(/\/$/, '').replace(/\[([^\]]+)\]/g, (_match, letters) => letters[0]).replace(/\?/g, 'x');
+    const names = stem.includes('*') ? ['', '-mcp', '-report', '-cache', '-agentdevkit'].map(suffix => stem.replace(/\*/g, suffix)) : [stem];
+    for (const name of names) for (const variant of new Set([name, name.toLowerCase()])) {
+      const leaves = stem.includes('*') ? ['.agentdevkit-artifact-probe', '.cache/.agentdevkit-artifact-probe'] : ['.agentdevkit-artifact-probe'];
+      for (const leaf of leaves) for (const path of [`${variant}/${leaf}`, `.agentdevkit-ignore-probes/${variant}/${leaf}`]) {
+        let parent = root, safe = true;
+        for (const part of path.split('/').slice(0, -1)) {
+          parent = join(parent, part); const item = localStat(parent);
+          if (item && !item.isDirectory()) { safe = false; break; }
+        }
+        if (safe) probes.add(path);
+      }
+    }
+  }
+  return [...probes];
+}
+
+function localIgnoreSource(location, source) {
+  const path = resolve(location.top, source);
+  if (path === location.exclude) return true;
+  const inside = relative(location.top, path);
+  return basename(path) === '.gitignore' && !isAbsolute(inside) && inside !== '..' && !inside.startsWith(`..${sep}`);
+}
+
+function ignoreMatches(location, probes) {
+  const paths = probes.map(path => location.prefix ? `${location.prefix}/${path}` : path);
+  const result = gitCommand(location.top, ['-c', 'core.excludesFile=', 'check-ignore', '--verbose', '--no-index', '--stdin', '-z'], paths.join('\0') + '\0');
+  if (result.error || ![0, 1].includes(result.status)) throw new Error(result.error?.message || result.stderr || 'Falha ao conferir exclusoes Git.');
+  const values = result.stdout.split('\0'), matches = new Map();
+  for (let index = 0; index + 3 < values.length; index += 4) matches.set(values[index + 3], { source: values[index], line: Number(values[index + 1]), pattern: values[index + 2] });
+  return { paths, matches };
+}
+
 function localRoot(value) {
   const missing = []; let parent = resolve(value);
   while (!localStat(parent)) { missing.unshift(parent.slice(dirname(parent).length + 1)); parent = dirname(parent); }
@@ -128,6 +174,7 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   const localTemplate = join(root, '.pbai4devs/templates/gitignore/local.ignore');
   const templateFile = checkedLocalPath(templateRoot ? join(templateRoot, '.pbai4devs/templates/gitignore/local.ignore') : localStat(localTemplate) ? localTemplate : fileURLToPath(new URL('../../templates/gitignore/local.ignore', import.meta.url)));
   const template = readFileSync(templateFile, 'utf8');
+  const artifacts = artifactPolicy(templateFile);
   if (template.split('{{OUTPUTS}}').length !== 2) throw new Error('local.ignore exige um unico {{OUTPUTS}}.');
   if (template.split('{{ROOTS}}').length > 2) throw new Error('local.ignore permite um unico {{ROOTS}}.');
   const localPolicy = join(templateRoot || root, '.pbai4devs/templates/clients/ADAPTERS.json');
@@ -152,16 +199,18 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   }
   const id = createHash('sha256').update(root).digest('hex').slice(0, 16);
   const first = `# BEGIN AGENTDEVKIT LOCAL ${id}`, last = `# END AGENTDEVKIT LOCAL ${id}`;
-  const fixed = template.replace('{{ROOTS}}', roots.map(path => `/${path}/`).join('\n')).replace('{{OUTPUTS}}', paths.filter(path => !roots.some(root => path === root || path.startsWith(root + '/'))).map(path => `/${escapePattern(path)}`).join('\n'));
+  const fixed = template.replace('{{ROOTS}}', roots.map(path => `/${path}/`).join('\n')).replace('{{OUTPUTS}}', paths.filter(path => !roots.some(root => path === root || path.startsWith(root + '/'))).map(path => `/${escapePattern(path)}`).join('\n'))
+    + '\n# Resultados e arquivos temporarios\n' + artifacts.map(pattern => `/${pattern}`).join('\n') + '\n';
   const body = fixed.split(/\r?\n/).map(line => location?.prefix && line.startsWith('/') ? `/${escapePattern(location.prefix)}${line}` : line).join('\n');
   const target = location?.exclude ?? checkedLocalPath(join(root, '.gitignore'));
   const before = localRead(target), after = localBlock(before, first, last, body);
   const edits = before === after ? [] : [{ path: target, before, after }];
   const probes = [...paths, ...rootProbes(root, roots)];
+  const artifactPaths = artifactProbes(root, artifacts);
   const wanted = new Set(probes.map(path => location?.prefix ? `${location.prefix}/${path}` : path));
   if (location && !before?.includes(first) && !localRead(join(root, '.gitignore'))?.includes(first)) {
-    const ignored = gitCommand(location.top, ['check-ignore', '--no-index', '--stdin', '-z'], [...wanted].join('\0') + '\0');
-    if (!ignored.error && [0, 1].includes(ignored.status) && ignored.stdout.split('\0').filter(Boolean).length === wanted.size) edits.length = 0;
+    const ignored = ignoreMatches(location, [...probes, ...artifactPaths]);
+    if (ignored.paths.every(path => { const match = ignored.matches.get(path); return match && !match.pattern.startsWith('!') && localIgnoreSource(location, match.source); })) edits.length = 0;
   }
   if (location) {
     const fallback = checkedLocalPath(join(root, '.gitignore'));
@@ -169,7 +218,7 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
     if (old !== null && old !== next) edits.push({ path: fallback, before: old, after: next });
   }
   const tracked = location ? gitCommand(location.top, ['ls-files', '-z']).stdout.split('\0').filter(path => wanted.has(path)).map(path => location.prefix ? path.slice(location.prefix.length + 1) : path) : [];
-  return { root, status: location ? 'git' : 'fallback', location, paths, roots, edits, trackedOutputs: tracked, first, last };
+  return { root, status: location ? 'git' : 'fallback', location, paths, roots, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last };
 }
 
 export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
@@ -185,19 +234,16 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
     if (createHash('sha256').update(block).digest('hex') !== item.sha256) throw new Error('Bloco de ignore mudou antes da verificacao.');
     return { ...item, path };
   });
-  if (plan.location && plan.paths.length) {
-    const probes = [...plan.paths, ...rootProbes(plan.root, plan.roots || [])];
-    const relativePaths = probes.map(path => plan.location.prefix ? `${plan.location.prefix}/${path}` : path);
-    const result = gitCommand(plan.location.top, ['check-ignore', '--verbose', '--no-index', '--stdin', '-z'], relativePaths.join('\0') + '\0');
-    if (result.error || ![0, 1].includes(result.status)) throw new Error(result.error?.message || result.stderr || 'Falha ao conferir exclusoes Git.');
-    const values = result.stdout.split('\0'), matches = new Map();
-    for (let index = 0; index + 3 < values.length; index += 4) matches.set(values[index + 3], { source: values[index], line: Number(values[index + 1]), pattern: values[index + 2] });
+  if (plan.location && (plan.paths.length || plan.artifactProbes?.length)) {
+    const probes = [...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || [])];
+    const { paths: relativePaths, matches } = ignoreMatches(plan.location, probes);
     for (let index = 0; index < relativePaths.length; index++) {
       const match = matches.get(relativePaths[index]);
       const negative = match?.pattern.startsWith('!');
-      const humanOverride = negative && /(?:^|[\\/])\.gitignore$/.test(match.source);
+      const local = match && localIgnoreSource(plan.location, match.source);
+      const humanOverride = negative && local && /(?:^|[\\/])\.gitignore$/.test(match.source);
       const replaced = negative && replacements.some(item => item.path === canonicalExisting(resolve(plan.location.top, match.source)) && match.line >= item.firstLine && match.line <= item.lastLine);
-      if (!replaced && ((!plan.edits.length && (!match || negative)) || humanOverride)) missing.push(probes[index]);
+      if (!replaced && ((!plan.edits.length && (!match || negative || !local)) || humanOverride)) missing.push(probes[index]);
     }
   }
   return { ok: plan.edits.length === 0 && missing.length === 0 && plan.trackedOutputs.length === 0, status: plan.status, missing, trackedOutputs: plan.trackedOutputs, changed: plan.edits.length };
@@ -212,6 +258,8 @@ export function assertLocalIgnoreUnchanged(plan) {
 
 export function applyLocalIgnore(plan) {
   assertLocalIgnoreUnchanged(plan);
+  const before = checkLocalIgnore(plan);
+  if (before.missing.length) throw new Error(`Regras humanas reabrem derivados locais: ${before.missing.join(', ')}`);
   const written = [];
   try {
     for (const edit of plan.edits) {

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

@@ -129,6 +129,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');

package/CHANGELOG.md

@@ -4,6 +4,13 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 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.7 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.7
 [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.6][release] conserva artefactos y checksums para verificarlos.
+la [release v0.0.7][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.6
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.7
 [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.6][release],
+versão publicada no [npm público][packages] e na [release v0.0.7][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.6
+[release]: https://github.com/pathbit/AgentDevKit/releases/tag/v0.0.7
 [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/installation.md

@@ -60,6 +60,11 @@ workflows, formulários de issues ou configurações humanas em `.github`.
 Sem Git, uma proteção no `.gitignore` da raiz evita incluir os derivados
 quando o repositório for iniciado.
 
+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.
+
 Arquivos já rastreados exigem migração do índice: apenas saídas identificadas
 do kit podem deixar de ser rastreadas, preservando seus bytes no disco.
 Revise o plano e os conflitos em um projeto existente; use `--dry-run` antes
@@ -77,10 +82,14 @@ gerenciados alterados geram conflito; use `--force` somente após revisar o
 backup e o conteúdo que será substituído. Preserve os dados locais, as
 configurações próprias e os commits do projeto.
 
+Links simbólicos em caminhos usados pela instalação podem bloquear a operação.
+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.
+
 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.6][spec]
+[Wiki](../README.md) · [Spec v0.0.7][spec]
 
 [bootstrap]: ../../.pbai4devs/scripts/preparar-ferramentas/BOOTSTRAP.md
-[spec]: ../specs/v0.0.6/SPEC.md
+[spec]: ../specs/v0.0.7/SPEC.md

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.6 -F package_only=true
+gh workflow run release.yml --ref master -f tag=v0.0.7 -F package_only=true
 ```
 
 Se o artefato expirou, reexecute o CI original da tag antes da publicação.

package/docs/product/roadmap.md

@@ -17,6 +17,7 @@ status: vigente
 | Estrutura e exemplos v0.0.4 | CLI, distribuição e gerador | [Spec][layout]. |
 | 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]. |
 
 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
@@ -36,3 +37,4 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [layout]: ../specs/v0.0.4/SPEC.md
 [registry]: ../specs/v0.0.5/SPEC.md
 [public]: ../specs/v0.0.6/SPEC.md
+[oss]: ../specs/v0.0.7/SPEC.md

package/docs/specs/README.md

@@ -11,6 +11,7 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.4](v0.0.4/SPEC.md): estrutura padrão e exemplos na raiz.
 - [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.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

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

@@ -0,0 +1,10 @@
+---
+description: Compatibilidade do pacote com projetos open source existentes.
+---
+
+# Versão 0.0.7
+
+A [spec](SPEC.md) define testes em clones reais e a correção das exclusões
+locais de artefatos, preservando os arquivos e as decisões dos projetos.
+
+[Specs](../README.md)

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

@@ -0,0 +1,59 @@
+---
+description: Testes em projetos reais e proteção de artefatos locais.
+status: aprovado
+version: 0.0.7
+---
+
+# Compatibilidade com projetos existentes
+
+## Objetivo e autorização
+
+Atender ao pedido de testar o pacote publicado em projetos open source com
+conteúdo real, usando clones em `tmp/` ignorado. Corrigir a falta de proteção
+de artefatos revelada em projetos que não tinham as regras do AgentDevKit.
+
+O trabalho usa o [PRD](../../product/prd.md),
+o [design](../../product/design.md) e a
+[distribuição pública](../v0.0.6/SPEC.md). Não altera as aplicações clonadas.
+
+## Contrato
+
+- Clonar commits fixos de Express, Zod e Chi; preservar os projetos originais.
+- Comparar bytes, tipos, permissões, links, HEAD e alterações staged.
+- Verificar instalação, atualização, repetição, skill própria e conflitos.
+- Proteger artefatos no ignore local sem reescrever o `.gitignore` do usuário
+  nem desindexar arquivos humanos. Respeitar projetos irmãos e exceções.
+- Manter as recusas de links simbólicos. Um bloqueio seguro não comprova
+  instalação bem-sucedida; relatá-lo e verificar ausência de alterações.
+- Versionar o teste; guardar clones, logs e resultados somente em `tmp/`.
+- Publicar correções como nova versão estável; repetir a prova pública.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Matriz real registra resultado e preservação por projeto. |
+| AC-002 | Artefatos são ignorados sem alterar fontes ou projetos irmãos. |
+| AC-003 | Regressões e revisão independente aprovam a correção. |
+| AC-004 | Pacote estável publicado repete os resultados e atualiza o router. |
+
+## Verificação
+
+- **AC-001:** executar o runner contra o npm, incluindo caso staged e bloqueios;
+  registrar commits, versão e hashes. Não confundir com testes das aplicações.
+- **AC-002:** testar Git, instalação sem Git, projeto aninhado, caixa mista,
+  exceções humanas e artefatos já rastreados. Não forçar sobrescritas.
+- **AC-003:** executar testes do pacote, infraestrutura, lint e distribuição.
+  Comparar testes nativos do Express antes e depois, sem modificar suas fontes.
+- **AC-004:** conferir release, `latest`, checksum e instalação anônima; repetir
+  matriz com o pacote publicado e atualizar o router com backup e diagnóstico.
+
+Evidências dos clones ficam em `tmp/oss-compatibility/`; o relatório de revisão
+em `.agent-tests/oss-compatibility/` referencia cópias dessas provas.
+Zod e Chi não terão testes nativos sem os runtimes/gerenciadores exigidos.
+Não concluir compatibilidade universal a partir desta matriz.
+
+## Documentação afetada
+
+Atualizar instalação, testes, changelog, índices e roadmap. Documentar a
+proteção de artefatos locais e os limites de configurações preexistentes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",
@@ -50,7 +50,8 @@
     "pack:release": "node scripts/release/assets.mjs",
     "ci:full": "node scripts/release/pipeline.mjs full",
     "ci:portable": "node scripts/release/pipeline.mjs portable",
-    "ci:smoke": "node scripts/release/pipeline.mjs smoke"
+    "ci:smoke": "node scripts/release/pipeline.mjs smoke",
+    "test:oss": "node tests/oss-compatibility.mjs"
   },
   "author": {
     "name": "PathBit",