@pathbit/agentdevkit 0.0.12 → 0.0.14

package/.pbai4devs/INSTRUCTIONS.md

@@ -79,7 +79,9 @@ permanecem exclusivamente em `.pbai4devs`.
 O sincronizador mantém a proteção Git das saídas locais e de `.pbai4devs`.
 Use os [modelos de ignore](templates/gitignore/TEMPLATE.md) para alterar a lista
 de fontes e derivados; em Git, os apontamentos usam exclusões locais.
-Sem repositório, o `.gitignore` da raiz protege os derivados até o Git existir.
+O `.gitignore` da raiz pertence ao projeto e não é alterado pelo kit.
+Sem Git, a proteção local fica pendente; após `git init`, sincronize antes
+de adicionar arquivos ao índice.
 Documentos de produto também ficam fora dos espelhos. O comando `sincronizar`
 reconstrói apontamentos com `--force`; `--check` verifica sem alterações.
 

package/.pbai4devs/rules/qualidade/RULE.md

@@ -20,12 +20,11 @@ H1; preserve os metadados exigidos pela ferramenta. Em documentos humanos
 existentes, mantenha o formato e o conteúdo: não os reformate apenas para
 impor esse padrão.
 
-Ao criar ou atualizar `.gitignore`, mantenha o bloco do
-[modelo de gitignore](../../templates/gitignore/TEMPLATE.md)
-como última seção CUSTOM IGNORE e acrescente os padrões específicos ali.
-As políticas vêm desse modelo. `.pbai4devs/.gitignore` controla o hub; o gerador
-protege os derivados externos no Git local. Sem Git, uma proteção temporária
-na raiz evita versioná-los ao iniciar o repositório.
+O `.gitignore` da raiz pertence ao projeto e não é alterado pelo kit. O
+[modelo de gitignore](../../templates/gitignore/TEMPLATE.md) é opcional para
+regras do projeto. `.pbai4devs/.gitignore` controla o hub; o gerador protege
+os derivados externos no Git local. Sem Git, essa proteção fica pendente até
+`git init` e sincronização, antes de adicionar arquivos ao índice.
 Confira com Git tanto os arquivos permitidos quanto os artefatos ignorados.
 Scripts compartilhados devem ser versionados; resultados locais, ignorados.
 Ignore o conteúdo baixado de tools, preservando `TOOL.json`, scripts próprios

package/.pbai4devs/scripts/lib/README.md

@@ -11,3 +11,6 @@ Também procura executáveis opcionais no PATH sem iniciar um shell.
 `managed-content.mjs` limita a propriedade do kit aos seus blocos Markdown;
 `managed-toml.mjs` aplica o mesmo contrato ao `prompt` de comandos Gemini.
 Texto externo, nomes existentes e metadados humanos permanecem preservados.
+
+`gitignore.mjs` planeja exclusões locais e detecta regras conflitantes. Ele não
+altera o `.gitignore` da raiz; conflitos são informados para revisão humana.

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

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from 'node:crypto';
-import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, closeSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
@@ -112,7 +112,7 @@ function checkedOutput(path) {
 function escapePattern(path) { return path.replace(/[\\!#*?\[\] ]/g, '\\$&'); }
 
 function rootProbes(root, roots) {
-  return roots.filter(path => { const item = localStat(join(root, path)); return !item || item.isDirectory(); }).map(path => `${path}/.agentdevkit-ignore-probe`);
+  return roots.filter(path => { const item = localStat(join(root, path)); return !item || item.isDirectory() && !item.isSymbolicLink(); }).map(path => `${path}/.agentdevkit-ignore-probe`);
 }
 
 function artifactPolicy(templateFile) {
@@ -136,9 +136,11 @@ function privateClientPolicy(templateFile, roots) {
     const negative = pattern.startsWith('!'), rule = pattern.replace(/^!/, '').replace(/^\//, '');
     rules.push(`${negative ? '!' : ''}/${escapePattern(root)}/${rule}`);
     if (negative) continue;
-    const stem = rule.replace(/^\*\*\//, '').replace(/\[([^\]]+)\]/g, (_match, letters) => letters[0]).replace(/\*/g, 'agentdevkit-private-probe').replace(/\?/g, 'x');
-    probes.push(`${root}/${stem}${stem.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
-    if (rule.startsWith('**/')) probes.push(`${root}/.agentdevkit-ignore-probes/${stem}${stem.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+    const witness = lower => rule.replace(/^\*\*\//, '').replace(/\[([^\]]+)\]/g, (_match, letters) => lower ? letters[0].toLowerCase() : letters[0]).replace(/\*/g, 'agentdevkit-private-probe').replace(/\?/g, 'x');
+    for (const variant of new Set([witness(false), witness(true)])) {
+      probes.push(`${root}/${variant}${variant.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+      if (rule.startsWith('**/')) probes.push(`${root}/.agentdevkit-ignore-probes/${variant}${variant.endsWith('/') ? '.agentdevkit-ignore-probe' : ''}`);
+    }
   }
   return { rules, probes };
 }
@@ -148,7 +150,7 @@ function safeIgnoreProbe(root, path) {
   for (const part of path.split('/').slice(0, -1)) {
     parent = join(parent, part);
     const item = localStat(parent);
-    if (item && !item.isDirectory()) return false;
+    if (item && (!item.isDirectory() || item.isSymbolicLink())) return false;
   }
   return true;
 }
@@ -164,7 +166,7 @@ function artifactProbes(root, patterns) {
         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 (item && (!item.isDirectory() || item.isSymbolicLink())) { safe = false; break; }
         }
         if (safe) probes.add(path);
       }
@@ -202,8 +204,8 @@ function visibleArtifactProbes(root, location, patterns) {
   const listed = gitCommand(location.top, ['--literal-pathspecs', '-c', 'core.excludesFile=', 'ls-files', '--cached', '--others', '--exclude-standard', '-z', '--', location.prefix ? `${location.prefix}/` : '.']);
   if (listed.error || listed.status !== 0) throw new Error(listed.error?.message || listed.stderr || 'Falha ao conferir artefatos existentes.');
   const paths = listed.stdout.split('\0').filter(Boolean), prefix = location.prefix ? `${location.prefix}/` : '';
-  const probes = new Set(paths.filter(path => path.startsWith(prefix)).map(path => path.slice(prefix.length)).filter(path => artifactPath(path, patterns)));
-  const ignores = new Set(paths.filter(path => path.startsWith(prefix) && (path === '.gitignore' || path.endsWith('/.gitignore'))));
+  const probes = new Set(paths.filter(path => path.startsWith(prefix)).map(path => path.slice(prefix.length)).filter(path => artifactPath(path, patterns) && safeIgnoreProbe(root, path)));
+  const ignores = new Set(paths.filter(path => path.startsWith(prefix) && (path === '.gitignore' || path.endsWith('/.gitignore')) && safeIgnoreProbe(root, path.slice(prefix.length))));
   let ancestor = root;
   while (true) {
     ignores.add(portable(relative(location.top, join(ancestor, '.gitignore'))));
@@ -222,12 +224,111 @@ function visibleArtifactProbes(root, location, patterns) {
       const ruleBase = !rule.startsWith('/') && !literal.includes('/') && relative(dirname(file), root).split(sep)[0] !== '..' ? root : dirname(file);
       const candidate = portable(relative(root, resolve(ruleBase, literal.replace(/\\(.)/g, '$1'))));
       if (!candidate || candidate === '..' || candidate.startsWith('../') || !artifactPath(candidate, patterns, directory)) continue;
-      probes.add(checkedOutput(directory ? `${candidate}/.agentdevkit-artifact-probe` : candidate));
+      const probe = checkedOutput(directory ? `${candidate}/.agentdevkit-artifact-probe` : candidate);
+      if (safeIgnoreProbe(root, probe)) probes.add(probe);
+    }
+  }
+  return [...probes];
+}
+
+// Existing unignored private files and literal/mixed-case root exceptions must
+// not slip through merely because a synthetic wildcard used another spelling.
+function visiblePrivateProbes(root, location, clientRoots) {
+  const listed = gitCommand(location.top, ['--literal-pathspecs', '-c', 'core.excludesFile=', 'ls-files', '--others', '--exclude-standard', '-z', '--', location.prefix ? `${location.prefix}/` : '.']);
+  if (listed.error || listed.status !== 0) throw new Error(listed.error?.message || listed.stderr || 'Falha ao conferir arquivos privados.');
+  const prefix = location.prefix ? `${location.prefix}/` : '', roots = new Set(clientRoots);
+  const probes = new Set(listed.stdout.split('\0').filter(path => path.startsWith(prefix)).map(path => path.slice(prefix.length))
+    .filter(path => roots.has(path.split('/')[0]) && isGeneratedOutput(path) && safeIgnoreProbe(root, path)));
+  const ignore = join(root, '.gitignore'), item = localStat(ignore);
+  if (item?.isFile() && !item.isSymbolicLink()) for (const line of readFileSync(ignore, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/)) {
+    if (!line.startsWith('!') || line.length === 1) continue;
+    const rule = line.slice(1), directory = rule.endsWith('/');
+    const witness = rule.replace(/^\//, '').replace(/\*\*\//g, '').replace(/\[([^\]]+)\]/g, (_m, letters) => letters[0]).replace(/\*/g, '').replace(/\?/g, 'x').replace(/\/$/, '');
+    if (!witness || /[\\\x00-\x1f]/.test(witness)) continue;
+    const candidates = roots.has(witness.split('/')[0]) ? [witness] : [...roots].map(client => `${client}/${witness}`);
+    for (const path of candidates) {
+      const probe = checkedOutput(directory ? `${path}/.agentdevkit-ignore-probe` : path);
+      if (isGeneratedOutput(path, directory) && safeIgnoreProbe(root, probe)) probes.add(probe);
     }
   }
   return [...probes];
 }
 
+// Wildcard negations may expose files that do not exist yet. Inspect client
+// ignores directly, even when an old rule currently hides the entire client.
+function ambiguousExceptions(root, location, clientRoots, artifacts) {
+  const files = [];
+  const visit = directory => {
+    const item = localStat(directory);
+    if (!item?.isDirectory() || item.isSymbolicLink()) return;
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      if (entry.isSymbolicLink()) continue;
+      if (entry.isFile() && entry.name === '.gitignore') files.push(path);
+      else if (entry.isDirectory()) {
+        const local = portable(relative(root, path)), client = clientRoots.includes(local.split('/')[0]);
+        const downloaded = entry.name === 'node_modules' || /^\.pbai4devs\/(?:tools\/(?:npm-cache|bin)|external-skills\/[^/]+)$/.test(local);
+        const gitPath = location.prefix ? `${location.prefix}/${local}/` : `${local}/`;
+        const ignoredDownload = downloaded && gitCommand(location.top, ['-c', 'core.excludesFile=', 'check-ignore', '--no-index', '-q', '--', gitPath]).status === 0;
+        const protectedDir = entry.name === '.git' || artifactPath(local, artifacts, true)
+          || ignoredDownload || (client || local.startsWith('.pbai4devs/')) && isGeneratedOutput(local, true);
+        if (!protectedDir) visit(path);
+      }
+    }
+  };
+  visit(root);
+  let ancestor = dirname(root);
+  while (root !== location.top && (ancestor === location.top || !relative(location.top, ancestor).startsWith(`..${sep}`))) {
+    files.push(join(ancestor, '.gitignore'));
+    if (ancestor === location.top) break;
+    ancestor = dirname(ancestor);
+  }
+  const rootIgnore = join(root, '.gitignore');
+  const conflicts = [];
+  for (const file of files) {
+    const item = localStat(file);
+    if (!item?.isFile() || item.isSymbolicLink()) continue;
+    const lines = readFileSync(file, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/);
+    for (const line of lines) {
+      if (!line.startsWith('!')) continue;
+      const rule = line.slice(1).replace(/^\/?(?:\*\*\/)?/, '');
+      if (/^\.env\.(?:example|sample|template|\*\.example)$/.test(rule)) continue;
+      const wildcard = /(^|[^\\])[*?\[]/.test(line);
+      const scope = portable(relative(dirname(file), root));
+      if (scope && !scope.startsWith('..') && !/^!\/?\*\*\//.test(line) && rule.includes('/')) {
+        const parts = rule.split('/'), project = scope.split('/');
+        if (project.some((part, index) => parts[index] && !/[*?\[]/.test(parts[index]) && parts[index] !== part && parts.slice(0, index).every(value => value && !/[*?\[]/.test(value)))) continue;
+      }
+      if (!wildcard) {
+        if (file !== rootIgnore && isGeneratedOutput(portable(relative(root, join(dirname(file), rule))), rule.endsWith('/'))) conflicts.push(portable(relative(root, file)) + ': ' + line);
+        continue;
+      }
+      conflicts.push(portable(relative(root, file)) + ': ' + line);
+    }
+  }
+  return conflicts;
+}
+
+function foreignHiddenClients(plan) {
+  if (!plan.location) return [];
+  const content = localRead(plan.location.exclude) || '', ranges = [];
+  let start = null;
+  content.split(/\r?\n/).forEach((line, index) => {
+    const begin = line.match(/^# BEGIN AGENTDEVKIT LOCAL ([a-f0-9]{16})$/);
+    const end = line.match(/^# END AGENTDEVKIT LOCAL ([a-f0-9]{16})$/);
+    if (begin) start = { id: begin[1], line: index + 1 };
+    else if (end && start?.id === end[1]) { ranges.push({ ...start, end: index + 1 }); start = null; }
+  });
+  const probes = plan.clientRoots.filter(path => { const item = localStat(join(plan.root, path)); return !item || item.isDirectory() && !item.isSymbolicLink(); }).map(path => `${path}/.agentdevkit-human-probe.md`);
+  if (!probes.length) return [];
+  const { paths, matches } = ignoreMatches(plan.location, probes);
+  return paths.flatMap((path, index) => {
+    const match = matches.get(path);
+    if (!match || match.pattern.startsWith('!') || resolve(plan.location.top, match.source) !== plan.location.exclude) return [];
+    return ranges.some(range => `# BEGIN AGENTDEVKIT LOCAL ${range.id}` !== plan.first && match.line >= range.line && match.line <= range.end) ? [probes[index]] : [];
+  });
+}
+
 function localIgnoreSource(location, source) {
   const path = resolve(location.top, source);
   if (path === location.exclude) return true;
@@ -236,6 +337,8 @@ function localIgnoreSource(location, source) {
 }
 
 function ignoreMatches(location, probes) {
+  const root = join(location.top, location.prefix);
+  if (probes.some(path => !safeIgnoreProbe(root, path))) throw new Error('Probe atravessa caminho simbolico.');
   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.');
@@ -295,27 +398,29 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
     if (line.startsWith('!/')) return `!/${escapePattern(location.prefix)}${line.slice(1)}`;
     return 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 target = location?.exclude;
+  const before = target ? localRead(target) : null, after = target ? localBlock(before, first, last, body) : null;
   const edits = before === after ? [] : [{ path: target, before, after, beforeMode: localMode(target) }];
   const probes = [...paths, ...rootProbes(root, roots)];
-  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...privateClients.probes.filter(path => safeIgnoreProbe(root, path)), ...(location ? visibleArtifactProbes(root, location, artifacts) : [])])];
+  const existingPrivate = privateClients.probes.filter(path => localStat(join(root, path.split('/')[0]))?.isDirectory() && safeIgnoreProbe(root, path));
+  const artifactPaths = [...new Set([...artifactProbes(root, artifacts), ...existingPrivate, ...(location ? [...visibleArtifactProbes(root, location, artifacts), ...visiblePrivateProbes(root, location, clientRoots)] : [])])];
   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 = ignoreMatches(location, [...probes, ...artifactPaths]);
+  if (location && !before?.includes(first)) {
+    const ignored = ignoreMatches(location, [...probes, ...artifactPaths].filter(path => safeIgnoreProbe(root, path)));
     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'));
-    const old = localRead(fallback), next = localBlock(old, first, last, null);
-    if (old !== null && old !== next) edits.push({ path: fallback, before: old, after: next, beforeMode: localMode(fallback) });
-  }
-  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, artifactPatterns: artifacts, artifactProbes: artifactPaths, edits, trackedOutputs: tracked, first, last };
+  const prefix = location?.prefix ? `${location.prefix}/` : '';
+  const tracked = location ? gitCommand(location.top, ['ls-files', '-z']).stdout.split('\0').filter(path => {
+    if (!path.startsWith(prefix)) return false;
+    const local = path.slice(prefix.length);
+    return wanted.has(path) || artifactPath(local, artifacts) || clientRoots.includes(local.split('/')[0]) && isGeneratedOutput(local);
+  }).map(path => path.slice(prefix.length)) : [];
+  return { root, status: location ? 'git' : 'no-git', location, paths, roots, clientRoots, artifactPatterns: artifacts, artifactProbes: artifactPaths, privateProbes: privateClients.probes, edits, trackedOutputs: tracked, first, last };
 }
 
 export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
   const missing = [];
+  if (plan.location) missing.push(...ambiguousExceptions(plan.root, plan.location, plan.clientRoots || [], plan.artifactPatterns || []), ...foreignHiddenClients(plan));
   const replacements = replacedBlocks.map(item => {
     const path = canonicalExisting(checkedLocalPath(resolve(item.path))), inside = relative(localRoot(plan.root).root, path);
     if (isAbsolute(inside) || inside === '..' || inside.startsWith(`..${sep}`) || !Number.isInteger(item.firstLine) || !Number.isInteger(item.lastLine) || item.firstLine < 1 || item.lastLine < item.firstLine || !/^[a-f0-9]{64}$/.test(item.sha256)) throw new Error('Faixa de ignore gerenciado invalida.');
@@ -328,8 +433,11 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
     return { ...item, path };
   });
   if (plan.location && (plan.paths.length || plan.artifactProbes?.length)) {
-    const probes = [...new Set([...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || []),
-      ...(plan.artifactPatterns ? visibleArtifactProbes(plan.root, plan.location, plan.artifactPatterns) : [])])];
+    missing.push(...plan.paths.filter(path => !safeIgnoreProbe(plan.root, path)));
+    const privateProbes = (plan.privateProbes || []).filter(path => localStat(join(plan.root, path.split('/')[0]))?.isDirectory() && safeIgnoreProbe(plan.root, path));
+    const probes = [...new Set([...plan.paths, ...rootProbes(plan.root, plan.roots || []), ...(plan.artifactProbes || []), ...privateProbes,
+      ...(plan.artifactPatterns ? visibleArtifactProbes(plan.root, plan.location, plan.artifactPatterns) : []),
+      ...visiblePrivateProbes(plan.root, plan.location, plan.clientRoots || [])])].filter(path => safeIgnoreProbe(plan.root, path));
     const { paths: relativePaths, matches } = ignoreMatches(plan.location, probes);
     for (let index = 0; index < relativePaths.length; index++) {
       const match = matches.get(relativePaths[index]);
@@ -340,7 +448,7 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
       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 };
+  return { ok: plan.status === 'git' && plan.edits.length === 0 && missing.length === 0 && plan.trackedOutputs.length === 0, status: plan.status, missing, trackedOutputs: plan.trackedOutputs, changed: plan.edits.length };
 }
 
 export function assertLocalIgnoreUnchanged(plan) {

package/.pbai4devs/scripts/sincronizar-agentes/README.md

@@ -37,7 +37,7 @@ a seleção, use `agentdevkit agents <lista>`; não edite o manifesto gerado.
 
 Os derivados ficam locais: catálogos, manifesto, estado e apontamentos são
 excluídos pelo Git. O bloco em `.git/info/exclude` preserva regras próprias;
-sem Git, usa um bloco na raiz que migra ao executar depois de `git init`.
+sem Git, informa que a proteção fica pendente até `git init` e sincronização.
 Somente arquivos integralmente gerados são excluídos; pastas de clientes podem
 conter arquivos humanos versionados. Conteúdo próprio não é desindexado pela
 presença de um bloco gerenciado.

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

@@ -577,9 +577,10 @@ export function synchronize({ root = projectRoot, check = false, force = false,
   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 summary = { changed: changed.length + rootEntryChanges.length, stale: removals.length, conflicts: conflicts.size, missing: missing.length, legacy: legacy.length, registries: registries.size, gitignores: ignoreFiles.size, manifests: configExists ? 0 : 1, localIgnores: localStatus.changed + localStatus.missing.length + localStatus.trackedOutputs.length + (localStatus.status === 'no-git' ? 1 : 0) };
   const dirty = Object.values(summary).some(Boolean);
   output(`${summary.changed} desatualizadas; ${summary.stale} obsoletas; ${summary.conflicts} conflitos; ${summary.missing} origens nativas ausentes; ${summary.legacy} documentos antigos; ${summary.registries} indices derivados; ${summary.gitignores} gitignores; ${summary.localIgnores} exclusoes locais.`);
+  if (localStatus.status === 'no-git') output('Git ausente: apos git init, execute a sincronizacao para proteger os arquivos locais.');
   const preservedPaths = sorted(preserved.keys()).map(path => preserved.get(path));
   if (check) return { ...summary, ownedOutputs, managedBlocks, preserved: preservedPaths, exitCode: dirty ? 1 : 0 };
   if (conflicts.size) fail(`Use --force para reconstruir somente os caminhos gerenciados: ${sorted(conflicts).join(', ')}`);

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

@@ -23,14 +23,14 @@ function git(root, args, input) {
   assert.ifError(result.error); assert.equal(result.status, 0, result.stderr); return result.stdout;
 }
 
-test('fallback protege outputs antes de git init e migra para exclude preservando regras', t => {
+test('sem Git preserva ignore e informa pendência; após git init protege outputs', t => {
   const root = fixture(t), outputs = ['.github/skills/generated/SKILL.md', '.vscode/.gitignore', 'AGENTS.md'];
   put(root, '.gitignore', '# Regras humanas\n*.own-cache\n');
   const plan = planLocalIgnore(root, { outputs });
-  assert.equal(plan.status, 'fallback'); assert.equal(checkLocalIgnore(plan).ok, false);
+  assert.equal(plan.status, 'no-git'); assert.equal(checkLocalIgnore(plan).ok, false);
   applyLocalIgnore(plan);
-  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs })).ok, true);
-  assert.match(readFileSync(join(root, '.gitignore'), 'utf8'), /^# Regras humanas\n\*\.own-cache\n/);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs })).ok, false);
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), '# Regras humanas\n*.own-cache\n');
   git(root, ['init', '-q']);
   put(root, '.git/info/exclude', '# Exclusoes humanas\n*.local-backup\n');
   applyLocalIgnore(planLocalIgnore(root, { outputs }));
@@ -68,12 +68,86 @@ test('check identifica negação humana e outputs rastreados sem alterar o índi
   assert.equal(git(root, ['ls-files', 'generated.md']).trim(), 'generated.md');
 });
 
-test('planejamento é somente leitura e aplicação detecta mudança concorrente', t => {
+test('exceções de templates preservam o ignore raiz e protegem dados privados', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  git(root, ['config', 'core.ignorecase', 'false']);
+  const original = '# Regras do projeto\n.env.*\n!.env.example\n!.env.*.example\n';
+  put(root, '.gitignore', original); git(root, ['add', '.gitignore']);
+  const index = git(root, ['ls-files', '--stage', '-z']);
+  const plan = planLocalIgnore(root);
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), original);
+  assert.equal(existsSync(join(root, '.cursor')), false);
+  applyLocalIgnore(plan);
+  const updated = readFileSync(join(root, '.gitignore'), 'utf8');
+  assert.equal(updated, original);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+  assert.equal(existsSync(join(root, '.cursor')), false);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+  put(root, '.cursor/.CACHE/private.json', 'local');
+  put(root, '.cursor/.cache/private.json', 'local');
+  put(root, '.cursor/human.md', 'human');
+  assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.CACHE/private.json']).includes('.cursor/.CACHE/private.json'));
+  assert.ok(git(root, ['check-ignore', '--no-index', '.cursor/.cache/private.json']).includes('.cursor/.cache/private.json'));
+  const visible = spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', '.cursor/human.md']);
+  assert.equal(visible.status, 1);
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), updated);
+  put(root, '.gitignore', updated + '# edição humana posterior\n');
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+});
+
+test('bloco legado na raiz pertence ao projeto e permanece intacto', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const original = '# BEGIN AGENTDEVKIT PRIVATE legado\n# edição humana\n# END AGENTDEVKIT PRIVATE legado\n';
+  put(root, '.gitignore', original);
+  applyLocalIgnore(planLocalIgnore(root));
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), original);
+});
+
+test('negação com caixa mista não expõe cache em Git sensível a maiúsculas', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  git(root, ['config', 'core.ignorecase', 'false']);
+  put(root, '.gitignore', '!*.CaChE/\n');
+  put(root, '.cursor/.CaChE/private.json', 'local');
+  assert.throws(() => applyLocalIgnore(planLocalIgnore(root)), /Regras humanas/);
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), '!*.CaChE/\n');
+});
+
+test('negações literais e com caixa mista não expõem estado privado', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  git(root, ['config', 'core.ignorecase', 'false']);
+  put(root, '.gitignore', '!*.LoCaL/\n!/.cursor/.env.production\n');
+  for (const path of ['.cursor/.LoCaL/private.json', '.cursor/.env.production']) put(root, path, 'privado');
+  assert.throws(() => applyLocalIgnore(planLocalIgnore(root)), /Regras humanas/);
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), '!*.LoCaL/\n!/.cursor/.env.production\n');
+});
+
+test('negação na primeira linha com BOM preserva bytes e protege segredos', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const original = '\uFEFF!/.cursor/.env.production\r\n';
+  put(root, '.gitignore', original); put(root, '.cursor/.env.production', 'privado');
+  assert.throws(() => applyLocalIgnore(planLocalIgnore(root)), /Regras humanas/);
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), original);
+});
+
+test('negação humana posterior é informada sem reescrever a raiz', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '# humano\n'); applyLocalIgnore(planLocalIgnore(root));
+  const path = join(root, '.gitignore');
+  writeFileSync(path, readFileSync(path, 'utf8') + '!/.cursor/.env.production\n');
+  put(root, '.cursor/.env.production', 'privado');
+  const plan = planLocalIgnore(root);
+  assert.ok(checkLocalIgnore(plan).missing.includes('.cursor/.env.production'));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.equal(readFileSync(path, 'utf8'), '# humano\n!/.cursor/.env.production\n');
+});
+
+test('planejamento sem Git não modifica ignore nem edição humana posterior', t => {
   const root = fixture(t); put(root, '.gitignore', 'antes\r\n');
   const plan = planLocalIgnore(root, { outputs: ['generated.md'] });
   assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), 'antes\r\n');
   put(root, '.gitignore', 'depois\r\n');
-  assert.throws(() => applyLocalIgnore(plan), /alterada apos planejar/);
+  applyLocalIgnore(plan);
   assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), 'depois\r\n');
   for (const path of ['../outside', '/absolute', 'line\nname', 'a\\b']) assert.throws(() => planLocalIgnore(root, { outputs: [path] }), /invalida/);
 });
@@ -99,7 +173,7 @@ test('plano de instalação em alvo inexistente não cria arquivos', t => {
   const root = fixture(t);
   const target = join(root, 'new project', 'nested');
   const fallback = planLocalIgnore(target, { outputs: ['AGENTS.md'] });
-  assert.equal(fallback.status, 'fallback'); assert.equal(existsSync(target), false);
+  assert.equal(fallback.status, 'no-git'); assert.equal(existsSync(target), false);
   git(root, ['init', '-q']);
   const plan = planLocalIgnore(target, { outputs: ['AGENTS.md'] });
   assert.equal(plan.status, 'git'); assert.equal(existsSync(target), false);
@@ -131,21 +205,21 @@ test('configurações humanas dos clientes continuam versionáveis', t => {
   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 => {
+test('artefatos vêm da política compartilhada e rastreados são informados', 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'));
+  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);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs: ['AGENTS.md'] })).ok, false);
 });
 
 test('regras de artefatos são limitadas ao projeto dentro do monorepo', t => {
@@ -250,7 +324,7 @@ test('negação humana é detectada antes de aplicar novas exclusões e permanec
   put(root, '.gitignore', '!/AGENTS.md\n');
   const before = readFileSync(join(root, '.git/info/exclude'), 'utf8');
   const plan = planLocalIgnore(root, { outputs: ['AGENTS.md'] });
-  assert.equal(plan.edits.length, 1);
+  assert.ok(plan.edits.some(edit => edit.path === join(root, '.git/info/exclude')));
   assert.deepEqual(checkLocalIgnore(plan).missing, ['AGENTS.md']);
   assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
   assert.equal(readFileSync(join(root, '.git/info/exclude'), 'utf8'), before);
@@ -381,6 +455,63 @@ test('arquivo real reaberto por glob é detectado também se surgir após o plan
   assert.equal(readFileSync(join(root, path), 'utf8'), 'artefato local\n');
 });
 
+test('negações globais e aninhadas não expõem futuros arquivos privados', t => {
+  for (const [file, rule] of [['.gitignore', '!/.claude/s*.json'], ['.claude/.gitignore', '!s*.json'], ['.claude/.gitignore', '!/settings.local.json'], ['.pbai4devs/.gitignore', '!.playwright-*/'], ['.pbai4devs/module/.gitignore', '!.playwright-*/'], ['logs/.gitignore', '!.playwright-*/'], ['.gitignore', '!**/foo/s*.json'], ['.gitignore', '!**/foo/.playwright-*.png'], ['.gitignore', '!/docs/.playwright-*.png'], ['docs/.gitignore', '!.playwright-*/'], ['.gitignore', '!*.CaChE/'], ['.gitignore', '!/.playwright-*.png']]) {
+    const root = fixture(t); git(root, ['init', '-q']);
+    put(root, file, `\uFEFF${rule}\n`);
+    const before = readFileSync(join(root, '.git/info/exclude'));
+    const index = git(root, ['ls-files', '--stage', '-z']);
+    const plan = planLocalIgnore(root);
+    assert.ok(checkLocalIgnore(plan).missing.some(value => value.includes(rule)), rule);
+    assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+    assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), before);
+    assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+    assert.equal(readFileSync(join(root, file), 'utf8'), `\uFEFF${rule}\n`);
+  }
+});
+
+test('glob ancestral do subprojeto é detectado antes de alterar o exclude', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const child = join(root, 'packages/app'); mkdirSync(child, { recursive: true });
+  put(root, '.gitignore', '!/packages/app/.claude/s*.json\n');
+  const before = readFileSync(join(root, '.git/info/exclude'));
+  const plan = planLocalIgnore(child);
+  assert.ok(checkLocalIgnore(plan).missing.some(value => value.includes('s*.json')));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), before);
+});
+
+test('dependências já ignoradas não causam conflito, mas ignores visíveis são verificados', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', 'node_modules/\n');
+  put(root, 'node_modules/pacote/.gitignore', '!.playwright-*/\n');
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).missing.length, 0);
+  put(root, '.gitignore', '# dependências visíveis\n');
+  assert.ok(checkLocalIgnore(planLocalIgnore(root)).missing.some(value => value.includes('!.playwright-*/')));
+});
+
+test('bloco antigo de outro caminho não oculta arquivos humanos silenciosamente', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const old = '# BEGIN AGENTDEVKIT LOCAL 0123456789abcdef\n/.claude/\n# END AGENTDEVKIT LOCAL 0123456789abcdef\n';
+  put(root, '.git/info/exclude', old);
+  const plan = planLocalIgnore(root);
+  assert.ok(checkLocalIgnore(plan).missing.includes('.claude/.agentdevkit-human-probe.md'));
+  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.equal(readFileSync(join(root, '.git/info/exclude'), 'utf8'), old);
+});
+
+test('artefatos já versionados são informados sem alterar o índice', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const artifacts = ['.playwright-mcp/trace.zip', 'playwright-report/index.html', 'test-results/result.txt', '.agent-tests/log.txt', '.claude/settings.local.json', '.codex/.env'];
+  for (const path of artifacts) put(root, path, 'trace');
+  git(root, ['add', '-f', ...artifacts]);
+  const before = git(root, ['ls-files', '--stage', '-z']);
+  const plan = planLocalIgnore(root);
+  assert.deepEqual([...plan.trackedOutputs].sort(), artifacts.sort());
+  assert.equal(checkLocalIgnore(plan).ok, false);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), before);
+});
+
 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');
@@ -399,7 +530,7 @@ test('chaves literais em padrões Git não viram expansão de glob', t => {
   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');
+  put(root, '.gitignore', '!cachekeep/source.txt\n');
   assert.doesNotThrow(() => applyLocalIgnore(planLocalIgnore(root)));
   assert.equal(readFileSync(join(root, 'cachekeep/source.txt'), 'utf8'), 'código humano\n');
 });
@@ -424,32 +555,28 @@ test('escrita de exclusões preserva permissões e detecta alteração concorren
   assert.equal(statSync(exclude).mode & 0o777, 0o640);
 });
 
-test('fallback e rollback de exclusões mantêm o modo original', { skip: process.platform === 'win32' }, t => {
+test('ignore raiz mantém modo e bytes antes e depois de git init', { 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);
+  const exclude = join(root, '.git/info/exclude'); chmodSync(exclude, 0o600);
+  applyLocalIgnore(planLocalIgnore(root));
+  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 => {
+test('ignore raiz somente leitura não impede exclusão local no Git', { 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);
+  const exclude = join(root, '.git/info/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);
+  applyLocalIgnore(plan);
+  assert.equal(statSync(exclude).mode & 0o777, 0o444);
   assert.deepEqual(readFileSync(ignore), original); assert.equal(statSync(ignore).mode & 0o777, 0o444);
 });
 

package/.pbai4devs/templates/gitignore/TEMPLATE.md

@@ -1,15 +1,15 @@
 ---
-description: Bloco customizado obrigatório ao final do gitignore.
+description: Exemplo opcional de regras de ignore para o projeto.
 ---
 
 # Custom ignore
 
-Ao criar ou atualizar `.gitignore`, mantenha este bloco no final. Preserve
-exceções existentes e acrescente os ignorados específicos da tecnologia aqui.
+O `.gitignore` da raiz pertence ao projeto; o kit não o cria nem o altera.
+O projeto pode adotar este exemplo e seus próprios padrões se desejar.
 Regras de artefatos locais vêm de [shared.ignore](shared.ignore) e
 [agents.ignore](agents.ignore). As saídas calculadas usam
-[local.ignore](local.ignore) em `.git/info/exclude`; sem Git, um bloco gerado
-na raiz protege os arquivos e migra para `exclude` após `git init` e `sync`.
+[local.ignore](local.ignore) em `.git/info/exclude`; sem Git, essa proteção
+fica pendente até `git init` e sincronização, antes de adicionar arquivos.
 O sincronizador mantém o bloco `BEGIN AGENT IGNORE` / `END AGENT IGNORE`;
 regras próprias ficam fora dele, com exceções depois do bloco. Para permitir
 novos arquivos compartilhados, ajuste as fontes e sincronize. Raízes dedicadas

package/CHANGELOG.md

@@ -4,6 +4,19 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.14 — 2026-11-12
+
+- O `.gitignore` da raiz pertence ao projeto e não é alterado pelo kit.
+- Exclusões locais ficam no Git e conflitos são informados antes da instalação.
+- Projetos sem Git recebem orientação para ativar a proteção após `git init`.
+- Negação ambígua, blocos antigos e artefatos rastreados recebem diagnóstico.
+
+## 0.0.13 — 2026-11-12
+
+- Proteção de caches de agentes mesmo com negações genéricas no `.gitignore`.
+- Matriz de compatibilidade ampliada para os sete projetos públicos solicitados.
+- Dois exemplos reproduzíveis com produto, design e três specs testadas.
+
 ## 0.0.12 — 2026-11-12
 
 - Entradas e recursos existentes recebem referências em blocos próprios do kit.

package/README.en.md

@@ -43,7 +43,7 @@ Then open the project in your coding agent and ask:
 
 See [installation](docs/guides/installation.md) for runtime preparation, previews
 and updates. Both [package registries][packages] provide the same version;
-the [v0.0.12 release][release] retains artifacts and checksums for verification.
+the [latest 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.
 
@@ -90,7 +90,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.12
+[release]: https://github.com/pathbit/AgentDevKit/releases/latest
 [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

@@ -44,7 +44,7 @@ Después, abre el proyecto en tu agente y pide:
 La [guía de instalación](docs/guides/installation.md) incluye preparación del
 runtime, simulación y actualización. Los dos [registros][packages] ofrecen
 la misma versión;
-la [release v0.0.12][release] conserva artefactos y checksums para verificarlos.
+la [última release][release] conserva artefactos y checksums para verificarlos.
 No requiere instalación global.
 La CLI guarda el idioma `pt`, `en` o `es` por proyecto.
 
@@ -92,7 +92,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.12
+[release]: https://github.com/pathbit/AgentDevKit/releases/latest
 [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

@@ -46,7 +46,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 e GitHub Packages][packages] e na [release v0.0.12][release],
+versão publicada no [npm e GitHub Packages][packages] e na [release][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`.
@@ -60,6 +60,7 @@ O idioma da CLI pode ser `pt`, `en` ou `es`.
 | Planejar ou retomar um projeto | [Fluxo de trabalho](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/workflow.md) |
 | Evoluir documentos existentes | [Inventário e complementos](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/documentation.md) |
 | Criar uma skill ou comando | [Recursos](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/resources.md) |
+| Entender agentes, skills e comandos | [Recursos na prática](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/recursos-na-pratica.md) |
 | Instalar ferramentas e comprovar uma entrega | [Ferramentas e testes][tests] |
 | Revisar segurança sem serviços externos | [Segurança local](https://github.com/pathbit/AgentDevKit/blob/master/docs/guides/security.md) |
 | Consultar opções ou resolver um erro | [CLI][cli] · [Soluções][help] |
@@ -106,7 +107,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.12
+[release]: https://github.com/pathbit/AgentDevKit/releases/latest
 [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/README.md

@@ -27,6 +27,7 @@ pode trocar de agente sem manter várias cópias das mesmas instruções.
 | Projeto em andamento | [Instalar com simulação][install] → [retomar][flow] |
 | Evoluir documentação existente | [Inventariar e complementar](guides/documentation.md) |
 | Personalizar agentes | [Recursos][resources] → [compatibilidade][clients] |
+| Entender cada peça com um exemplo | [Recursos na prática](guides/recursos-na-pratica.md) |
 | Revisar segurança | [Scanners locais e controles](guides/security.md) |
 | Executar ou verificar algo | [CLI](guides/cli.md) → [ferramentas e testes][tests] |
 | Corrigir uma dificuldade | [Soluções e recuperação](guides/troubleshooting.md) |

package/docs/guides/README.md

@@ -10,6 +10,7 @@ description: Guias de instalação, uso e verificação do AgentDevKit.
 - [Fluxo de trabalho](workflow.md)
 - [Evoluir documentação existente](documentation.md)
 - [Recursos dos agentes](resources.md)
+- [Recursos na prática: do pedido à entrega](recursos-na-pratica.md)
 - [Segurança local](security.md)
 - [Ferramentas e testes](tools-and-testing.md)
 - [Solução de problemas](troubleshooting.md)

package/docs/guides/installation.md

@@ -105,18 +105,24 @@ identifica a licença dos recursos do AgentDevKit, sem redefinir a do projeto.
 Um `.gitignore` dentro de `.pbai4devs` só controla essa árvore. Para os
 apontamentos externos, o kit gera exclusões locais do Git, sem ignorar
 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 kit não cria nem altera o `.gitignore` da raiz. Sem Git, a exclusão local
+fica pendente; execute `git init` e `npx @pathbit/agentdevkit sync` antes de
+usar `git add`. No GitHub Packages, use o prefixo de registry da instalação.
 
 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.
+O conteúdo do `.gitignore` existente e os arquivos rastreados são preservados.
+Uma exceção que reabra arquivo privado ou artefato é informada como conflito;
+o projeto decide como ajustar suas próprias regras.
+Negativas com curingas também podem ser recusadas preventivamente, mesmo antes
+de existir um arquivo correspondente. Examine a regra indicada no diagnóstico.
 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.
+Artefatos já rastreados são informados por `doctor` e `sync --check` para
+revisão; não são removidos automaticamente do índice.
 Revise o plano e os conflitos em um projeto existente; use `--dry-run` antes
 de aplicar. Conteúdo humano não deve ser classificado como saída do gerador.
 

package/docs/guides/recursos-na-pratica.md

@@ -0,0 +1,91 @@
+---
+description: Como usar os recursos do AgentDevKit no desenvolvimento de software.
+language: pt
+---
+
+# Recursos na prática
+
+O AgentDevKit organiza o trabalho de desenvolvimento de software com agentes
+que você escolhe. O kit reúne instruções e ferramentas; decisões de produto,
+revisão humana e testes continuam necessários no projeto atendido.
+
+## Qual recurso usar?
+
+| Recurso | Para que serve | Exemplo concreto |
+| --- | --- | --- |
+| [Skill][skills] | Orienta decisões e passos de uma tarefa recorrente. | [Criar uma spec][spec] com dúvidas e critérios. |
+| [Comando][commands] | Dá entrada a um caso de uso e encaminha o trabalho. | [Validar entrega][validar] com provas. |
+| [Agente][agents] | Define responsabilidades e limites de um papel. | [Revisor][reviewer] examina a mudança em leitura. |
+| [Regra][rules] | Registra uma convenção aplicável a um contexto. | [Qualidade][quality] orienta os cuidados da entrega. |
+| [Template][templates] | Oferece uma estrutura para registrar decisões. | Preencher a [spec][spec-template] de um incremento. |
+| [Script][scripts] | Executa uma automação reutilizável. | [Sincronizar][sync] os apontamentos. |
+| [Ferramenta][tools] | Fornece uma capacidade técnica verificável. | [agent-browser][browser] exercita uma interface web. |
+| [Testes e evidências][tests] | Comprovam comportamento e registram resultados. | Versionar o teste e manter relatório local. |
+
+Os links levam às fontes e aos catálogos. Uma instrução em Markdown não inicia
+um processo sozinha; o cliente de IA decide como descobrir e executar recursos
+conforme suas capacidades e permissões. Consulte a
+[compatibilidade por cliente][compat] antes de depender de um atalho.
+
+## Exemplo: entregar uma funcionalidade
+
+1. Peça ao agente para ler `AGENTS.md` e usar
+   [proximos-passos][next]. Ele identifica a fase e as pendências do projeto.
+2. Defina produto, experiência quando aplicável e design técnico com o usuário.
+   Os [templates][templates] são pontos de partida, não decisões prontas.
+3. Use [criar-spec][spec] para esclarecer dúvidas, limitar o incremento e
+   registrar critérios verificáveis. Planeje e obtenha a aprovação necessária.
+4. Use [implementar-entrega][implement] com a spec e o plano. O perfil
+   [implementador][developer] segue a skill e respeita o escopo aprovado.
+5. Execute as verificações adequadas: testes automatizados, navegador para um
+   fluxo web ou desktop para uma aplicação desktop, quando aplicáveis. Registre
+   o resultado de cada critério, incluindo o que não pôde ser executado.
+6. Atualize a documentação afetada e encaminhe a mudança à
+   [revisão independente][review]. A equipe decide quando integrar a entrega.
+
+Para um projeto existente, comece pelo inventário e preserve suas decisões;
+consulte o [fluxo de trabalho][workflow] e a
+[instalação em projetos existentes][install].
+
+## Onde ficam os arquivos?
+
+`.pbai4devs/` contém as fontes compartilhadas. Pastas como `.claude/` ou
+`.codex/` recebem apenas os recursos de integração dos clientes selecionados;
+os arquivos humanos existentes continuam pertencendo ao projeto. A seleção pode
+ser consultada ou alterada pela [CLI][cli].
+
+O código dos testes e as fixtures necessárias são versionáveis. Relatórios,
+capturas, downloads e resultados locais ficam fora do versionamento. O
+`.gitignore` da raiz pertence ao projeto; com Git inicializado, o kit mantém
+suas exclusões locais em `.git/info/exclude` e informa conflitos. Sem Git,
+execute a sincronização após `git init`, antes de adicionar arquivos ao índice.
+Veja [instalação][install] e [ferramentas e testes][tests].
+
+Para criar ou mudar um recurso, use o [guia de recursos][resources] e depois
+sincronize e verifique os apontamentos. Para dúvidas de operação, consulte
+[solução de problemas](troubleshooting.md).
+
+[skills]: ../../.pbai4devs/skills/README.md
+[commands]: ../../.pbai4devs/commands/README.md
+[agents]: ../../.pbai4devs/agents/README.md
+[rules]: ../../.pbai4devs/rules/README.md
+[templates]: ../../.pbai4devs/templates/README.md
+[scripts]: ../../.pbai4devs/scripts/README.md
+[tools]: ../../.pbai4devs/tools/README.md
+[spec]: ../../.pbai4devs/skills/specs/criar-spec/SKILL.md
+[spec-template]: ../../.pbai4devs/templates/spec/TEMPLATE.md
+[validar]: ../../.pbai4devs/commands/validar-entrega/COMMAND.md
+[reviewer]: ../../.pbai4devs/agents/revisor/AGENT.md
+[developer]: ../../.pbai4devs/agents/implementador/AGENT.md
+[quality]: ../../.pbai4devs/rules/qualidade/RULE.md
+[sync]: ../../.pbai4devs/scripts/sincronizar-agentes/README.md
+[browser]: ../../.pbai4devs/tools/agent-browser/README.md
+[tests]: tools-and-testing.md
+[compat]: ../../.pbai4devs/COMPATIBILIDADE.md
+[next]: ../../.pbai4devs/skills/projeto/proximos-passos/SKILL.md
+[implement]: ../../.pbai4devs/commands/implementar-entrega/COMMAND.md
+[review]: ../../.pbai4devs/commands/revisar-entrega/COMMAND.md
+[workflow]: workflow.md
+[install]: installation.md
+[cli]: cli.md
+[resources]: resources.md

package/docs/guides/resources.md

@@ -14,6 +14,9 @@ O hub permanece completo mesmo com poucos clientes selecionados. Apenas os
 apontamentos necessários são gerados; consulte ou altere a seleção com `agents`
 na [CLI](cli.md). Pastas compartilhadas podem atender mais de um cliente.
 
+Para um exemplo de cada tipo aplicado ao desenvolvimento de software, veja
+[recursos na prática](recursos-na-pratica.md).
+
 ## Escolher o tipo certo
 
 Os caminhos abaixo são relativos a `.pbai4devs/`.

package/docs/maintainers/maintenance.md

@@ -91,7 +91,7 @@ existente, mesmo em rascunho. Remova somente o rascunho incompleto dessa
 tentativa após conferir a origem; nunca apague uma release publicada para
 repetir o fluxo.
 
-Para reiniciar uma publicação que falhou, use **Re-run failed jobs** ou
+Se a release ainda não existe, use **Re-run failed jobs** ou
 `gh workflow run release.yml --ref vX.Y.Z` com a tag real. A publicação prioriza
 o secret `NPMJS_TOKEN` do repositório; sem ele, usa OIDC, conforme
 [publicação](packages.md).

package/docs/maintainers/packages.md

@@ -103,7 +103,8 @@ publicados. Assim, a verificação comprova o acesso de um usuário comum.
 Confirme também que `latest` aponta para a versão estável e que o tarball é
 baixável; metadados visíveis sozinhos não comprovam uma instalação funcional.
 Se o registro ainda não disponibilizar o pacote, aguarde a verificação sem
-republicar automaticamente a mesma versão.
+republicar automaticamente a mesma versão. Durante a propagação, `E404` e
+`ETARGET` do download do tarball são repetidos dentro da mesma janela limitada.
 
 O GitHub Packages verifica os mesmos comandos com autenticação. Metadados
 devem indicar visibilidade pública e associação ao repositório correto.

package/docs/specs/README.md

@@ -18,6 +18,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.10](v0.0.10/SPEC.md): release com instalação pelos dois registries e pré-requisitos.
 - [Ecossistema de segurança](security-ecosystem/SPEC.md): fluxos e scanners locais.
 - [Integração sem substituição][additive]: acréscimos em arquivos existentes.
+- [Compatibilidade com projetos reais][oss]: projetos públicos e exemplos reproduzíveis.
+- [Ignore do projeto](project-ignore/SPEC.md): preservar o arquivo da raiz.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 
@@ -28,3 +30,4 @@ projeto, siga o [fluxo](../guides/workflow.md) e use os
 [Wiki](../README.md) · [Roadmap](../product/roadmap.md)
 
 [additive]: additive-integration/SPEC.md
+[oss]: real-projects/SPEC.md

package/docs/specs/project-ignore/SPEC.md

@@ -0,0 +1,26 @@
+---
+description: Preservar o ignore do projeto ao instalar o AgentDevKit.
+---
+
+# Ignore do projeto
+
+O arquivo `.gitignore` da raiz pertence ao projeto. Instalação, atualização e
+sincronização preservam seus bytes, permissões e estado no índice Git, inclusive
+quando um estado antigo do kit registra esse arquivo.
+
+## Critérios de aceite
+
+- AC-001: O kit não cria, altera, remove ou desindexa o `.gitignore` da raiz.
+- AC-002: Derivados e artefatos locais são protegidos via `.git/info/exclude`.
+- AC-003: Conflitos com regras humanas são informados antes das alterações; exceções
+  ambíguas não são consideradas seguras apenas por ausência do arquivo.
+- AC-004: Sem Git, a instalação informa a pendência e orienta a executar a
+  sincronização depois de `git init` e antes de `git add`.
+- AC-005: Arquivos humanos e configurações existentes são preservados.
+- AC-006: Instalação e atualização são verificadas em projetos pelo pacote.
+
+## Verificação
+
+Os testes de exclusão local cobrem negações, migração, arquivos rastreados,
+permissões e worktrees. Os testes de instalação e compatibilidade conferem a
+preservação do projeto e o comportamento com e sem Git.

package/docs/specs/real-projects/SPEC.md

@@ -0,0 +1,26 @@
+---
+description: Compatibilidade com repositórios públicos e exemplos incrementais.
+status: aprovado
+version: 0.0.13
+---
+
+# Projetos reais e exemplos incrementais
+
+Validar a instalação e manutenção do pacote em commits fixos de projetos reais,
+preservando suas configurações e seu índice Git. Demonstrar o fluxo de produto,
+design e três specs em dois projetos novos, com resultados locais ignorados.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Testar os sete repositórios, com commits registrados. |
+| AC-002 | Testar init repetido, update, sync e preservação nos clones. |
+| AC-003 | Proteger caches ante exceções Git, preservando texto e índice. |
+| AC-004 | Produto e design antes das três specs de cada projeto novo. |
+| AC-005 | Documentar reprodução, limites e saídas ignoradas. |
+| AC-006 | Testes de regressão, pacote e revisão independente passam. |
+
+Os testes de compatibilidade não executam nem compilam as aplicações externas.
+Aprovações de produto e revisão nos exemplos são simuladas. Código de teste é
+versionado; clones, projetos gerados e evidências permanecem fora do Git.

package/package.json

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

package/src/cli.mjs

@@ -59,6 +59,7 @@ export function parseArgs(argv) {
 function print(result, options, output) {
   if (options.json) { output.write(`${JSON.stringify(result)}\n`); return; }
   output.write(`${result.message}\n`);
+  if (result.warnings?.length) for (const warning of result.warnings) output.write(`${warning}\n`);
   if (result.clients) output.write(`${text(result.language, 'clientsCurrent')}: ${result.clients.join(', ')}\n`);
   if (result.availableClients) output.write(`${text(result.language, 'clientsAvailable')}: ${result.availableClients.map(client => client.id).join(', ')}\n`);
   if (result.toolOutput) output.write(`${result.toolOutput.trimEnd()}\n`);
@@ -125,9 +126,11 @@ export async function main(argv = process.argv.slice(2), context = {}) {
       if (found.installed && !found.issues.length) {
         const plan = planInstallation({ target, language, mode: 'sync' });
         result.preserved = plan.preserved;
+        if (plan.localIgnore.status === 'no-git') { found.issues.push({ code: 'git-pending', path: '.git/info/exclude' }); result.warnings = [text(language, 'gitPending')]; }
         found.issues.push(...plan.changes.map(change => ({ code: 'outdated', path: change.path })));
         found.issues.push(...plan.localIgnoreCheck.missing.map(path => ({ code: 'unignored', path })));
-        if (plan.localIgnore.edits.length || plan.untrack?.paths.length) found.issues.push({ code: 'local-ignore', path: '.gitignore / Git info/exclude' });
+        found.issues.push(...plan.localIgnoreCheck.trackedOutputs.map(path => ({ code: 'tracked-local-output', path })));
+        if (plan.localIgnore.edits.length || plan.untrack?.paths.length) found.issues.push({ code: 'local-ignore', path: 'Git info/exclude' });
       }
       result.issues = found.issues; result.ok = found.installed && found.issues.length === 0;
       result.message = text(language, result.ok ? 'healthy' : found.installed ? 'unhealthy' : 'missing'); exitCode = result.ok ? 0 : 1;
@@ -149,13 +152,15 @@ export async function main(argv = process.argv.slice(2), context = {}) {
       result.preserved = plan.preserved;
       result.plan = plan.changes.map(({ path, action }) => ({ path, action, conflict: plan.conflicts.includes(path) }));
       result.untrackedPaths = [...(plan.untrack?.paths || [])];
-      result.localIgnore = { status: plan.localIgnore.status, edits: plan.localIgnore.edits.map(({ path, before }) => ({ path, action: before === null ? 'create' : 'update' })), missing: plan.localIgnoreCheck.missing };
-      if (plan.localIgnore.edits.length) result.plan.push({ path: '.gitignore / Git info/exclude', action: 'update', conflict: false });
+      result.localIgnore = { status: plan.localIgnore.status, edits: plan.localIgnore.edits.map(({ path, before }) => ({ path, action: before === null ? 'create' : 'update' })), missing: plan.localIgnoreCheck.missing, trackedOutputs: plan.localIgnoreCheck.trackedOutputs };
+      if (plan.localIgnore.status === 'no-git') result.warnings = [text(language, 'gitPending')];
+      if (plan.localIgnoreCheck.trackedOutputs.length) (result.warnings ||= []).push(`${text(language, 'trackedLocal')} ${plan.localIgnoreCheck.trackedOutputs.join(', ')}`);
+      if (plan.localIgnore.edits.length) result.plan.push({ path: 'Git info/exclude', action: 'update', conflict: false });
       if (plan.untrack?.paths.length) result.plan.push({ path: 'Git index (generated files)', action: 'update', conflict: false });
       result.conflicts = plan.conflicts;
       const preview = options.dryRun || (options.command === 'sync' && options.check);
       if (!plan.canApply || preview) {
-        result.ok = plan.canApply && (!options.check || result.plan.length === 0);
+        result.ok = plan.canApply && (!options.check || result.plan.length === 0 && plan.localIgnore.status !== 'no-git' && !plan.localIgnoreCheck.trackedOutputs.length);
         result.message = text(language, plan.canApply ? 'plan' : 'conflict'); exitCode = result.ok ? 0 : 1;
       } else {
         Object.assign(result, applyPlan(plan)); result.message = text(language, result.changed ? options.command : 'unchanged');

package/src/i18n.mjs

@@ -7,6 +7,8 @@ export function normalizeLanguage(value) {
 
 const messages = {
   pt: {
+    gitPending: 'Git não foi inicializado; após git init, execute sync para proteger os arquivos locais.',
+    trackedLocal: 'Artefatos locais já estão versionados; revise o índice sem excluir conteúdo automaticamente.',
     preserved: 'Caminhos existentes preservados', preservedDetails: 'Use --json para consultar os caminhos e motivos.',
     help: 'AgentDevKit: init [diretório], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <ação>.\nOpções: --target <diretório>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAliases: --clients e clients.',
     clientsCurrent: 'Agentes selecionados', clientsAvailable: 'Agentes disponíveis', clientsSelect: 'Agentes (IDs separados por vírgula ou all) [all]: ', agents: 'Seleção de agentes atualizada.',
@@ -16,6 +18,8 @@ const messages = {
     agentLanguage: 'Responda em português, salvo quando o usuário solicitar outro idioma.', inspect: 'Verifique a instalação', workflow: 'Consulte a próxima etapa', install: 'Inicialize este projeto', repair: 'Confira a sincronização', review: 'Revise os arquivos em conflito', tools: 'Resultado da ferramenta',
   },
   en: {
+    gitPending: 'Git is not initialized; after git init, run sync to protect local files.',
+    trackedLocal: 'Local artifacts are already tracked; review the index without automatically deleting content.',
     preserved: 'Existing paths preserved', preservedDetails: 'Use --json to inspect paths and reasons.',
     help: 'AgentDevKit: init [directory], update, doctor, sync [--check], lang [pt|en|es], agents [list], next, tools <action>.\nOptions: --target <directory>, --lang <language>, --agents <list>, --yes, --dry-run, --force, --json.\nAliases: --clients and clients.',
     clientsCurrent: 'Selected agents', clientsAvailable: 'Available agents', clientsSelect: 'Agents (comma-separated IDs or all) [all]: ', agents: 'Agent selection updated.',
@@ -25,6 +29,8 @@ const messages = {
     agentLanguage: 'Respond in English unless the user requests another language.', inspect: 'Check the installation', workflow: 'Review the next stage', install: 'Initialize this project', repair: 'Check synchronization', review: 'Review conflicting files', tools: 'Tool result',
   },
   es: {
+    gitPending: 'Git no está inicializado; tras git init, ejecute sync para proteger los archivos locales.',
+    trackedLocal: 'Hay artefactos locales versionados; revise el índice sin eliminar contenido automáticamente.',
     preserved: 'Rutas existentes preservadas', preservedDetails: 'Use --json para consultar las rutas y los motivos.',
     help: 'AgentDevKit: init [directorio], update, doctor, sync [--check], lang [pt|en|es], agents [lista], next, tools <acción>.\nOpciones: --target <directorio>, --lang <idioma>, --agents <lista>, --yes, --dry-run, --force, --json.\nAlias: --clients y clients.',
     clientsCurrent: 'Agentes seleccionados', clientsAvailable: 'Agentes disponibles', clientsSelect: 'Agentes (IDs separados por coma o all) [all]: ', agents: 'Selección de agentes actualizada.',

package/src/install.mjs

@@ -352,6 +352,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     }
     const wholeRecords = [previous?.files || {}, derivedEntries, derivedFiles];
     for (const path of new Set(wholeRecords.flatMap(record => Object.keys(record)))) if (!desired.has(path)) {
+      if (path === '.gitignore') { recordPreserved(path, 'project-owned'); continue; }
       if (aliasedEntrypoint(path)) continue;
       const current = read(target, path); if (!current) continue;
       const known = wholeRecords.some(record => record[path] === hash(current));
@@ -412,7 +413,7 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const retiredRoots = adapterRoots.filter(root => !active.roots.includes(root) && changes.some(change => change.action === 'remove' && change.path.startsWith(`${root}/`) && (previous?.files[change.path] || previous?.blocks[change.path])));
     const ownedOutputs = [...new Set([...synchronized.ownedOutputs, ...ownedEntrypoints, statePath])].filter(path => !mixedPaths.has(path) && !overlapsPreserved(path));
     const hashes = {};
-    for (const [path, digest] of Object.entries(previous?.files || {})) if ((ownedOutputs.includes(path) || !path.startsWith('.pbai4devs/')) && !mixedPaths.has(path) && !overlapsPreserved(path) && !aliasedEntrypoint(path)) hashes[path] = digest;
+    for (const [path, digest] of Object.entries(previous?.files || {})) if (path !== '.gitignore' && (ownedOutputs.includes(path) || !path.startsWith('.pbai4devs/')) && !mixedPaths.has(path) && !overlapsPreserved(path) && !aliasedEntrypoint(path)) hashes[path] = digest;
     for (const path of ownedEntrypoints) { const current = read(target, path); if (current && (previous?.blocks[path] || derivedEntries[path] === hash(current))) hashes[path] = hash(current); }
     for (const path of Object.keys(previous?.blocks || {})) if (path.endsWith('/.gitignore') && adapterRoots.some(root => path === `${root}/.gitignore`)) {
       const current = read(target, path);