@pathbit/agentdevkit 0.0.18 → 0.0.19

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

@@ -332,26 +332,6 @@ function ambiguousExceptions(root, location, clientRoots, artifacts) {
   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;
@@ -370,6 +350,21 @@ function ignoreMatches(location, probes) {
   return { paths, matches };
 }
 
+// A nested .gitignore cannot reopen a project hidden by an ignored ancestor.
+// Detect this before claiming that its client exceptions are effective.
+function ignoredProjectAncestors(location) {
+  if (!location.prefix) return [];
+  const segments = location.prefix.split('/');
+  const paths = segments.map((_part, index) => segments.slice(0, index + 1).join('/'));
+  const result = gitCommand(location.top, ['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 ancestrais Git.');
+  const values = result.stdout.split('\0'), ignored = [];
+  for (let index = 0; index + 3 < values.length; index += 4) {
+    if (!values[index + 2].startsWith('!')) ignored.push(`Ancestral Git ignorado: ${values[index + 3]}/; reabra-o no .gitignore do repositorio pai`);
+  }
+  return ignored;
+}
+
 function localRoot(value) {
   const missing = []; let parent = resolve(value);
   while (!localStat(parent)) { missing.unshift(parent.slice(dirname(parent).length + 1)); parent = dirname(parent); }
@@ -387,15 +382,17 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   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}}.');
-  // A client directory can also contain human instructions and settings. Only
-  // whole files owned by the kit belong in the local output exclusion list.
-  const roots = [];
+  // Client roots are ignored locally. Projects can explicitly opt in to a
+  // complete client with a literal negation in their own root .gitignore.
   const localPolicy = join(templateRoot || root, '.pbai4devs/templates/clients/ADAPTERS.json');
   const policy = JSON.parse(readFileSync(checkedLocalPath(localStat(localPolicy) ? localPolicy : fileURLToPath(new URL('../../templates/clients/ADAPTERS.json', import.meta.url))), 'utf8'));
   const clientRoots = [...new Set(policy.adapters.flatMap(adapter => [adapter.root, ...(adapter.extraRoots || [])]))];
   if (clientRoots.some(path => typeof path !== 'string' || !/^\.[a-z0-9][a-z0-9-]*$/.test(path) || ['.git', '.pbai4devs', '.agent-tests'].includes(path))) throw new Error('Raiz de cliente invalida para exclusao.');
+  const roots = [...clientRoots];
   const privateClients = privateClientPolicy(templateFile, clientRoots);
-  const paths = [...new Set([...outputs.map(checkedOutput), ...template.split(/\r?\n/).filter(line => line.startsWith('/')).map(line => checkedOutput(line.slice(1)))])].sort();
+  const outputPaths = [...new Set(outputs.map(checkedOutput))];
+  const paths = [...new Set([...outputPaths, ...template.split(/\r?\n/).filter(line => line.startsWith('/')).map(line => checkedOutput(line.slice(1)))])]
+    .filter(path => !roots.some(client => path === client || path.startsWith(`${client}/`))).sort();
   const info = gitCommand(resolved.parent, ['rev-parse', '--show-toplevel', '--git-path', 'info/exclude']);
   let location = null;
   if (info.status === 0) {
@@ -412,6 +409,19 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
     throw new Error(`Nao foi possivel localizar Git: ${info.error?.message || info.stderr}`);
   }
   const id = createHash('sha256').update(root).digest('hex').slice(0, 16);
+  const projectIgnore = join(root, '.gitignore'), projectIgnoreStat = localStat(projectIgnore);
+  const literalExceptions = projectIgnoreStat?.isFile() && !projectIgnoreStat.isSymbolicLink()
+    ? new Set(readFileSync(projectIgnore, 'utf8').replace(/^\uFEFF/, '').split(/\r?\n/)) : new Set();
+  const requestedRoots = location ? roots.filter(client => literalExceptions.has(`!/${client}/`) || literalExceptions.has(`!${client}/`)) : [];
+  const optCandidates = requestedRoots.filter(client => safeIgnoreProbe(root, `${client}/.agentdevkit-opt-in-probe`));
+  // A later rule or an ancestor can override a literal negation. Consult Git
+  // before accepting it, including when the client folder does not yet exist.
+  const optProbes = optCandidates.map(client => `${client}/.agentdevkit-opt-in-probe`);
+  const optMatches = location && optProbes.length ? ignoreMatches(location, optProbes) : { paths: [], matches: new Map() };
+  const optedRoots = optCandidates.filter((_client, index) => {
+    const match = optMatches.matches.get(optMatches.paths[index]);
+    return !match || match.pattern.startsWith('!');
+  });
   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'))
     + '\n# Estado privado dos clientes\n' + privateClients.rules.join('\n') + '\n'
@@ -424,10 +434,9 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   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 probes = [...paths, ...rootProbes(root, roots.filter(client => !optedRoots.includes(client)))];
   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)) {
     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;
@@ -436,14 +445,16 @@ export function planLocalIgnore(root, { outputs = [], templateRoot } = {}) {
   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);
+    // Git ignore never untracks existing files. Report private data and test
+    // artifacts, but don't flag legitimate already-tracked project content.
+    return 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 };
+  return { root, status: location ? 'git' : 'no-git', location, paths, outputPaths, roots, requestedRoots, optedRoots, 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));
+  if (plan.location) missing.push(...((plan.requestedRoots || []).length ? ignoredProjectAncestors(plan.location) : []), ...ambiguousExceptions(plan.root, plan.location, plan.clientRoots || [], plan.artifactPatterns || []));
   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.');
@@ -456,9 +467,9 @@ export function checkLocalIgnore(plan, { replacedBlocks = [] } = {}) {
     return { ...item, path };
   });
   if (plan.location && (plan.paths.length || plan.artifactProbes?.length)) {
-    missing.push(...plan.paths.filter(path => !safeIgnoreProbe(plan.root, path)));
+    missing.push(...new Set([...plan.paths, ...(plan.outputPaths || [])].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,
+    const probes = [...new Set([...plan.paths, ...rootProbes(plan.root, (plan.roots || []).filter(client => !(plan.optedRoots || []).includes(client))), ...(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);
@@ -481,12 +492,13 @@ export function assertLocalIgnoreUnchanged(plan) {
   }
 }
 
-function atomicLocalWrite(path, content, mode, published) {
+function atomicLocalWrite(path, content, mode, published, beforePublish) {
   const temporary = `${path}.agentdevkit-${randomUUID()}`;
   try {
     writeFileSync(temporary, content, { flag: 'wx' });
     if (mode !== null && mode !== undefined) chmodSync(temporary, mode);
     const writtenMode = localMode(temporary);
+    beforePublish?.();
     renameSync(temporary, path);
     published?.(writtenMode);
   } finally { rmSync(temporary, { force: true }); }
@@ -500,7 +512,10 @@ export function applyLocalIgnore(plan) {
   try {
     for (const edit of plan.edits) {
       mkdirSync(dirname(edit.path), { recursive: true });
-      atomicLocalWrite(edit.path, edit.after, edit.beforeMode, mode => written.push({ edit, mode }));
+      atomicLocalWrite(edit.path, edit.after, edit.beforeMode, mode => written.push({ edit, mode }), () => {
+        checkedLocalPath(edit.path);
+        if (localRead(edit.path) !== edit.before || localMode(edit.path) !== edit.beforeMode) throw new Error(`Exclusao alterada antes de publicar; conteudo preservado: ${edit.path}`);
+      });
     }
     const verified = checkLocalIgnore({ ...plan, edits: [], trackedOutputs: [] });
     if (verified.missing.length) throw new Error(`Regras humanas reabrem derivados locais: ${verified.missing.join(', ')}`);
@@ -509,7 +524,12 @@ export function applyLocalIgnore(plan) {
     for (const { edit, mode } of written.reverse()) {
       try {
         if (localRead(edit.path) !== edit.after || localMode(edit.path) !== mode) continue;
-        if (edit.before === null) rmSync(edit.path, { force: true }); else atomicLocalWrite(edit.path, edit.before, edit.beforeMode);
+        const checkPublished = () => {
+          checkedLocalPath(edit.path);
+          if (localRead(edit.path) !== edit.after || localMode(edit.path) !== mode) throw new Error(`Exclusao alterada durante rollback; conteudo preservado: ${edit.path}`);
+        };
+        if (edit.before === null) { checkPublished(); rmSync(edit.path, { force: true }); }
+        else atomicLocalWrite(edit.path, edit.before, edit.beforeMode, undefined, checkPublished);
       } catch (failure) { rollbackErrors.push(failure); }
     }
     if (rollbackErrors.length) throw new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error });

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

@@ -38,16 +38,14 @@ Após a instalação, depende somente de Node e do hub local, sem o pacote npm.
 Ele respeita os clientes escolhidos, sem recriar os desmarcados. Para trocar
 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, 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.
+O bloco local em `.git/info/exclude` ignora as pastas de clientes por padrão;
+sem Git, a proteção fica pendente até `git init` e sincronização. Para incluir
+uma pasta, use uma exceção literal no `.gitignore` da raiz, como `!/.claude/`.
+Isso também vale para `.github` e `.vscode`, que podem conter arquivos humanos.
+Arquivos já rastreados e o índice não são alterados automaticamente.
 Entradas novas usam os templates; hashes em `state/derived.json` permitem
 atualizar arquivos gerados e blocos separadamente, preservando alterações humanas.
-`--check` também acusa derivados ainda rastreados; não altera o índice.
+`--check` somente verifica; não altera o índice.
 Apontamentos obsoletos podem ser removidos quando a propriedade é comprovada;
 arquivos e pastas próprios, inclusive os adicionais dentro do mesmo recurso,
-devem permanecer. Na CLI, confira `untrackedPaths` antes de aplicar: saídas
-geradas comprovadas podem deixar de ser rastreadas, sem excluir seus bytes.
+devem permanecer.

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

@@ -42,7 +42,7 @@ test('sem Git preserva ignore e informa pendência; após git init protege outpu
   git(root, ['add', '--all']);
   const tracked = git(root, ['ls-files', '-z']).split('\0').filter(Boolean);
   for (const path of outputs) assert.equal(tracked.includes(path), false, path);
-  for (const path of ['.github/workflows/ci.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.vscode/settings.json', '.github/skills/human/SKILL.md']) assert.ok(tracked.includes(path), path);
+  for (const path of ['.github/workflows/ci.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.vscode/settings.json', '.github/skills/human/SKILL.md']) assert.equal(tracked.includes(path), false, path);
 });
 
 test('prefixos e projetos distintos preservam blocos locais independentes', t => {
@@ -58,13 +58,49 @@ test('prefixos e projetos distintos preservam blocos locais independentes', t =>
   assert.match(content, /first\\ space/); assert.match(content, /second/);
 });
 
-test('check identifica negação humana e outputs rastreados sem alterar o índice', t => {
+test('projeto aninhado sob ancestral ignorado falha antes de alterar índices ou excludes', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '/.github/\n');
+  const child = join(root, '.github/project');
+  put(child, '.gitignore', '!/.claude/\n');
+  put(child, '.claude/custom.md', 'instruções próprias\n');
+  const exclude = readFileSync(join(root, '.git/info/exclude'));
+  const index = git(root, ['ls-files', '--stage', '-z']);
+  const plan = planLocalIgnore(child, { outputs: ['.claude/custom.md'] });
+  assert.ok(checkLocalIgnore(plan).missing.some(value => value.includes('Ancestral Git ignorado: .github/')));
+  assert.throws(() => applyLocalIgnore(plan), /Ancestral Git ignorado/);
+  assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), exclude);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+  assert.equal(readFileSync(join(child, '.claude/custom.md'), 'utf8'), 'instruções próprias\n');
+  put(root, '.gitignore', '/.github/\n!/.github/\n');
+  const opened = planLocalIgnore(child, { outputs: ['.claude/custom.md'] });
+  applyLocalIgnore(opened);
+  assert.equal(checkLocalIgnore(planLocalIgnore(child, { outputs: ['.claude/custom.md'] })).ok, true);
+  assert.equal(spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', '.github/project/.claude/custom.md']).status, 1);
+});
+
+test('opt-in aninhado respeita também excludesFile configurado pelo usuário', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, 'global-ignore', '/.private/\n');
+  git(root, ['config', '--local', 'core.excludesFile', join(root, 'global-ignore')]);
+  const child = join(root, '.private/project');
+  put(child, '.gitignore', '!/.claude/\n');
+  put(child, '.claude/custom.md', 'instruções próprias\n');
+  const before = readFileSync(join(root, '.git/info/exclude'));
+  const plan = planLocalIgnore(child);
+  assert.ok(checkLocalIgnore(plan).missing.some(value => value.includes('Ancestral Git ignorado: .private/')));
+  assert.throws(() => applyLocalIgnore(plan), /Ancestral Git ignorado/);
+  assert.deepEqual(readFileSync(join(root, '.git/info/exclude')), before);
+  assert.equal(readFileSync(join(child, '.claude/custom.md'), 'utf8'), 'instruções próprias\n');
+});
+
+test('check identifica negação humana sem alterar nem diagnosticar conteúdo rastreado legítimo', t => {
   const root = fixture(t), outputs = ['generated.md']; git(root, ['init', '-q']);
   put(root, 'generated.md', 'gerado'); git(root, ['add', 'generated.md']);
   applyLocalIgnore(planLocalIgnore(root, { outputs }));
   put(root, '.gitignore', '!/generated.md\n');
   const result = checkLocalIgnore(planLocalIgnore(root, { outputs }));
-  assert.equal(result.ok, false); assert.deepEqual(result.missing, outputs); assert.deepEqual(result.trackedOutputs, outputs);
+  assert.equal(result.ok, false); assert.deepEqual(result.missing, outputs); assert.deepEqual(result.trackedOutputs, []);
   assert.equal(git(root, ['ls-files', 'generated.md']).trim(), 'generated.md');
 });
 
@@ -89,7 +125,7 @@ test('exceções de templates preservam o ignore raiz e protegem dados privados'
   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);
+  assert.equal(visible.status, 0);
   applyLocalIgnore(planLocalIgnore(root));
   assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), updated);
   put(root, '.gitignore', updated + '# edição humana posterior\n');
@@ -134,12 +170,12 @@ 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');
+  writeFileSync(path, readFileSync(path, 'utf8') + '!/.cursor/\n!/.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');
+  assert.equal(readFileSync(path, 'utf8'), '# humano\n!/.cursor/\n!/.cursor/.env.production\n');
 });
 
 test('planejamento sem Git não modifica ignore nem edição humana posterior', t => {
@@ -193,11 +229,13 @@ test('desindexação não descarta edição humana staged com workingtree restau
   assert.equal(readFileSync(join(root, 'generated.md'), 'utf8'), 'gerado\n');
 });
 
-test('configurações humanas dos clientes continuam versionáveis', t => {
+test('configurações humanas podem ser versionadas após exceção explícita', t => {
   const root = fixture(t); git(root, ['init', '-q']);
   applyLocalIgnore(planLocalIgnore(root));
   put(root, '.codex/config.toml', 'local'); put(root, '.claude/settings.json', 'local');
   put(root, '.github/settings.json', 'fonte'); put(root, '.vscode/settings.json', 'fonte');
+  put(root, '.gitignore', '!/.codex/\n!/.claude/\n!/.github/\n!/.vscode/\n');
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
   git(root, ['add', '--all']);
   const tracked = git(root, ['ls-files', '-z']).split('\0');
   assert.equal(tracked.includes('.codex/config.toml'), true);
@@ -205,6 +243,53 @@ 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('exceções de raiz usam precedência real e mantêm credenciais ignoradas', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.gitignore', '!/.claude/\n!/.github/\n');
+  put(root, '.claude/skills/team/SKILL.md', 'skill humana\n');
+  put(root, '.claude/auth.json', 'segredo');
+  put(root, '.github/workflows/ci.yml', 'workflow humano\n');
+  put(root, '.vscode/settings.json', 'configuração humana\n');
+  const original = readFileSync(join(root, '.gitignore'));
+  const plan = planLocalIgnore(root, { outputs: ['.claude/skills/team/SKILL.md', '.github/workflows/ci.yml'] });
+  assert.ok(plan.optedRoots.includes('.claude'));
+  assert.ok(plan.optedRoots.includes('.github'));
+  applyLocalIgnore(plan);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root)).ok, true);
+  for (const path of ['.claude/skills/team/SKILL.md', '.github/workflows/ci.yml']) {
+    assert.equal(spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', path]).status, 1, path);
+  }
+  for (const path of ['.claude/auth.json', '.vscode/settings.json']) {
+    assert.equal(spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', path]).status, 0, path);
+  }
+  assert.deepEqual(readFileSync(join(root, '.gitignore')), original);
+  put(root, '.gitignore', '!/.claude/\n/.claude/\n');
+  const overridden = planLocalIgnore(root);
+  assert.equal(overridden.optedRoots.includes('.claude'), false);
+  assert.equal(spawnSync('git', ['-C', root, 'check-ignore', '--no-index', '-q', '.claude/skills/team/SKILL.md']).status, 0);
+  put(root, '.gitignore', '!/.claude/\n!/.claude/**\n');
+  assert.throws(() => applyLocalIgnore(planLocalIgnore(root)), /Regras humanas/);
+});
+
+test('derivados e entradas legítimas já rastreados permanecem no índice com ou sem opt-in', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  put(root, '.claude/skills/team/SKILL.md', 'skill rastreada\n');
+  put(root, '.github/workflows/ci.yml', 'workflow rastreado\n');
+  put(root, 'AGENTS.md', 'instruções rastreadas\n');
+  git(root, ['add', '--all']);
+  const before = git(root, ['ls-files', '--stage', '-z']);
+  const outputs = ['.claude/skills/team/SKILL.md', '.github/workflows/ci.yml', 'AGENTS.md'];
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
+  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs })).ok, true);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), before);
+  put(root, '.gitignore', '!/.claude/\n');
+  const opted = planLocalIgnore(root, { outputs });
+  assert.ok(opted.optedRoots.includes('.claude'));
+  applyLocalIgnore(opted);
+  assert.equal(checkLocalIgnore(planLocalIgnore(root, { outputs })).ok, true);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), before);
+});
+
 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']);
@@ -271,12 +356,13 @@ test('probes reconhecem exceções humanas para nomes reais de Playwright', asyn
   });
 });
 
-test('milhares de caminhos usam stdin e não ampliam metadata de área já ignorada', t => {
+test('milhares de caminhos usam stdin sem ampliar 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');
   const target = join(root, 'ignored'); mkdirSync(target);
-  const outputs = Array.from({ length: 1500 }, (_, index) => `.github/skills/generated-${index}-${'x'.repeat(45)}/SKILL.md`);
+  const outputs = Array.from({ length: 1500 }, (_, index) => `generated-${index}-${'x'.repeat(45)}.md`);
   const plan = planLocalIgnore(target, { outputs });
+  assert.ok(plan.paths.length >= 1500);
   assert.deepEqual(plan.edits, []); assert.equal(checkLocalIgnore(plan).ok, true);
   applyLocalIgnore(plan); assert.equal(readFileSync(join(root, '.git/info/exclude'), 'utf8'), before);
   assert.deepEqual(planUntrack(target, Object.fromEntries(outputs.map(path => [path, 'a'.repeat(64)]))).paths, []);
@@ -341,16 +427,17 @@ test('cliente não selecionado com symlink próprio não é atravessado pelo pro
   assert.deepEqual(readdirSync(outside), before);
 });
 
-test('preflight dispensa somente regras de bloco substituído com hash válido', t => {
+test('preflight valida hash do bloco substituído sem impor exclusão sobre cliente optado', t => {
   const root = fixture(t); git(root, ['init', '-q']);
   const block = '# BEGIN AGENT IGNORE\r\n!/generated.md\r\n# END AGENT IGNORE';
+  put(root, '.gitignore', '!/.github/\n');
   put(root, '.github/.gitignore', `# Humano\r\n${block}\r\n!/human.md\r\n`);
   const plan = planLocalIgnore(root, { outputs: ['.github/generated.md', '.github/human.md'] });
   const replacement = { path: join(root, '.github/.gitignore'), firstLine: 2, lastLine: 4, sha256: createHash('sha256').update(block).digest('hex') };
-  assert.deepEqual(checkLocalIgnore(plan).missing, ['.github/generated.md', '.github/human.md']);
-  assert.deepEqual(checkLocalIgnore(plan, { replacedBlocks: [replacement] }).missing, ['.github/human.md']);
+  assert.deepEqual(checkLocalIgnore(plan).missing, []);
+  assert.deepEqual(checkLocalIgnore(plan, { replacedBlocks: [replacement] }).missing, []);
   assert.throws(() => checkLocalIgnore(plan, { replacedBlocks: [{ ...replacement, sha256: '0'.repeat(64) }] }), /Bloco de ignore mudou/);
-  assert.throws(() => applyLocalIgnore(plan), /Regras humanas/);
+  assert.doesNotThrow(() => applyLocalIgnore(plan));
   assert.equal(readFileSync(join(root, '.github/.gitignore'), 'utf8'), `# Humano\r\n${block}\r\n!/human.md\r\n`);
 });
 
@@ -490,14 +577,14 @@ test('dependências já ignoradas não causam conflito, mas ignores visíveis s
   assert.ok(checkLocalIgnore(planLocalIgnore(root)).missing.some(value => value.includes('!.playwright-*/')));
 });
 
-test('bloco antigo de outro caminho não oculta arquivos humanos silenciosamente', t => {
+test('bloco de outra worktree não bloqueia a política local de clientes', 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);
+  assert.equal(checkLocalIgnore(plan).missing.length, 0);
+  assert.doesNotThrow(() => applyLocalIgnore(plan));
+  assert.ok(readFileSync(join(root, '.git/info/exclude'), 'utf8').startsWith(old));
 });
 
 test('artefatos já versionados são informados sem alterar o índice', t => {
@@ -555,6 +642,57 @@ test('escrita de exclusões preserva permissões e detecta alteração concorren
   assert.equal(statSync(exclude).mode & 0o777, 0o640);
 });
 
+test('alteração no exclude durante escrita temporária é preservada antes da promoção', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const file = join(root, '.git/info/exclude'), before = readFileSync(file, 'utf8');
+  const plan = planLocalIgnore(root), index = git(root, ['ls-files', '--stage', '-z']);
+  const write = fs.writeFileSync; let injected = false;
+  try {
+    fs.writeFileSync = (path, content, options) => {
+      const value = write(path, content, options);
+      if (!injected && String(path).startsWith(`${file}.agentdevkit-`)) {
+        injected = true;
+        write(file, `${before}\n# regra humana concorrente\n`);
+      }
+      return value;
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => applyLocalIgnore(plan), /Exclusao alterada antes de publicar/);
+  } finally { fs.writeFileSync = write; syncBuiltinESMExports(); }
+  assert.equal(injected, true);
+  assert.equal(readFileSync(file, 'utf8'), `${before}\n# regra humana concorrente\n`);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+});
+
+test('alteração no exclude durante rollback não é substituída', t => {
+  const root = fixture(t); git(root, ['init', '-q']);
+  const file = join(root, '.git/info/exclude'), plan = planLocalIgnore(root);
+  const index = git(root, ['ls-files', '--stage', '-z']);
+  const write = fs.writeFileSync, remove = fs.rmSync;
+  let failed = false, injected = false;
+  try {
+    fs.rmSync = (path, options) => {
+      if (!failed && String(path).startsWith(`${file}.agentdevkit-`) && !existsSync(path)) {
+        failed = true; throw new Error('falha após promoção');
+      }
+      return remove(path, options);
+    };
+    fs.writeFileSync = (path, content, options) => {
+      const value = write(path, content, options);
+      if (failed && !injected && String(path).startsWith(`${file}.agentdevkit-`)) {
+        injected = true;
+        write(file, `${readFileSync(file, 'utf8')}\n# regra humana no rollback\n`);
+      }
+      return value;
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => applyLocalIgnore(plan), /rollback incompleto.*conteudo preservado/s);
+  } finally { fs.rmSync = remove; fs.writeFileSync = write; syncBuiltinESMExports(); }
+  assert.equal(injected, true);
+  assert.match(readFileSync(file, 'utf8'), /# regra humana no rollback/);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']), index);
+});
+
 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);

package/.pbai4devs/scripts/verificar-recursos/tests/TEST.mjs

@@ -375,19 +375,36 @@ function ignoreFixture(t) {
   return context;
 }
 
-test('fontes novas permanecem elegíveis e derivados locais ficam fora do índice', t => {
+test('fontes permanecem elegíveis e pastas de clientes aceitam opt-in explícito', t => {
   const { root, file } = ignoreFixture(t);
   const outputs = ['.github/skills/generated/SKILL.md', '.vscode/.gitignore', '.github/.gitignore'];
-  applyLocalIgnore(planLocalIgnore(root, { outputs }));
-  const sources = ['src/new.mjs', 'bin/new.mjs', 'tests/new.test.mjs', 'scripts/release/new.mjs', '.github/workflows/own.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.github/skills/human/SKILL.md', '.vscode/settings.json'];
+  const sources = ['src/new.mjs', 'bin/new.mjs', 'tests/new.test.mjs', 'scripts/release/new.mjs'];
+  const clients = ['.github/workflows/own.yml', '.github/ISSUE_TEMPLATE/bug.yml', '.github/skills/human/SKILL.md', '.vscode/settings.json'];
   const generated = [...outputs, '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/espelhos.conf', '.pbai4devs/state/agentdevkit.json'];
-  for (const path of [...sources, ...generated]) file(path, 'fixture\n');
+  for (const path of [...sources, ...clients, ...generated.filter(path => !path.endsWith('/.gitignore'))]) file(path, 'fixture\n');
+  file('.github/auth.json', 'credencial local\n');
+  file('.vscode/logs/session.log', 'artefato local\n');
+  assert.equal(git(root, ['add', '--', clients[0], sources[0]]).status, 0);
+  const index = git(root, ['ls-files', '--stage', '-z']).stdout;
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
   assert.deepEqual(ignoredPaths(root, sources), []);
+  assert.deepEqual(new Set(ignoredPaths(root, clients)), new Set(clients));
   assert.deepEqual(new Set(ignoredPaths(root, generated)), new Set(generated));
+  assert.equal(git(root, ['ls-files', '--stage', '-z']).stdout, index);
+  for (const path of clients) assert.equal(readFileSync(join(root, path), 'utf8'), 'fixture\n', path);
+
+  const exceptions = '!/.github/\n!/.vscode/\n';
+  file('.gitignore', exceptions);
+  applyLocalIgnore(planLocalIgnore(root, { outputs }));
+  assert.equal(readFileSync(join(root, '.gitignore'), 'utf8'), exceptions);
+  assert.equal(git(root, ['ls-files', '--stage', '-z']).stdout, index);
+  assert.deepEqual(ignoredPaths(root, clients), []);
+  const privateFiles = ['.github/auth.json', '.vscode/logs/session.log'];
+  assert.deepEqual(new Set(ignoredPaths(root, privateFiles)), new Set(privateFiles));
   assert.equal(git(root, ['add', '--all']).status, 0);
   const tracked = git(root, ['ls-files', '-z']).stdout.split('\0');
-  for (const path of sources) assert.ok(tracked.includes(path), path);
-  for (const path of generated) assert.equal(tracked.includes(path), false, path);
+  for (const path of [...sources, ...clients, ...outputs]) assert.ok(tracked.includes(path), path);
+  for (const path of [...generated.filter(path => !outputs.includes(path)), ...privateFiles]) assert.equal(tracked.includes(path), false, path);
 });
 
 test('ignores locais cobrem resultados em qualquer caixa sem bloquear fixtures', t => {

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

@@ -7,14 +7,21 @@ description: Exemplo opcional de regras de ignore para o projeto.
 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, essa proteção
-fica pendente até `git init` e sincronização, antes de adicionar arquivos.
+[agents.ignore](agents.ignore). As pastas dos clientes usam
+[local.ignore](local.ignore) em `.git/info/exclude`; o `.gitignore` deste hub
+não alcança pastas irmãs com `../`. As regras locais não são copiadas pelo Git:
+execute `init` ou `sync` em cada clone com Git inicializado, antes de adicionar
+arquivos. Worktrees do mesmo repositório podem compartilhar as exclusões;
+sem Git, essa proteção fica pendente.
 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
-dos clientes são locais. Em `.github` e `.vscode`, arquivos próprios continuam
-elegíveis; somente os derivados são excluídos.
+regras próprias ficam fora dele, com exceções depois do bloco. Arquivos já
+rastreados permanecem no índice; o kit não os desindexa automaticamente.
+Pastas dos clientes também podem conter arquivos humanos ainda não rastreados.
+Em especial, `.github` pode conter workflows e formulários do projeto.
+Para permitir o versionamento, acrescente uma exceção literal ao `.gitignore`
+da raiz, como `!/.claude/` ou `!/.github/`. Regras mais profundas continuam
+válidas. Evite exceções amplas como `!/.claude/**`, que podem expor arquivos
+privados e artefatos; `doctor` informa regras conflitantes.
 Ignore binários baixados por local, não por extensão: `.bat`, `.exe` e outros
 arquivos podem ser scripts ou fixtures necessários. Não use regras genéricas
 como `Release/`, `Scripts/` ou `Lib/` que escondam fontes e modelos.

package/.pbai4devs/templates/gitignore/shared.ignore

@@ -1,3 +1,4 @@
+# Pastas irmas: templates/gitignore/local.ignore e .git/info/exclude.
 # Derivados locais
 /catalog.json
 /skills.json

package/CHANGELOG.md

@@ -4,6 +4,11 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.19 — 2026-11-13
+
+- Pastas dos clientes são ignoradas localmente por padrão, com exceções do projeto.
+- O índice Git e os arquivos já rastreados permanecem intactos.
+
 ## 0.0.18 — 2026-11-13
 
 - Sincronização preserva recursos próprios, colisões e alterações humanas.

package/README.en.md

@@ -13,7 +13,7 @@ Organize work with coding agents, from planning to verification. Keep skills,
 rules, commands and agent profiles in `.pbai4devs`; the kit generates the
 references each client can discover. Code lives in `src/`, product tests in
 `tests/`, and shared agent resources in `.pbai4devs/`. Generated client
-folders, entrypoints and preferences stay local and untracked.
+folders are ignored locally by default; projects can opt in to tracking them.
 See the [supported clients][clients].
 
 ## Start in your project

package/README.es.md

@@ -13,8 +13,8 @@ Organiza el trabajo con agentes de código, desde la planificación hasta la
 verificación. Mantén skills, reglas, comandos y perfiles en `.pbai4devs`;
 el kit genera las referencias de cada [cliente compatible][clients].
 El código vive en `src/`, las pruebas del producto en `tests/` y los recursos
-compartidos en `.pbai4devs/`. Las carpetas, entradas y preferencias generadas
-son locales y no se versionan.
+compartidos en `.pbai4devs/`. Las carpetas de clientes se ignoran localmente
+por defecto; cada proyecto puede elegir versionarlas.
 
 ## Empezar en tu proyecto
 

package/docs/guides/cli.md

@@ -85,10 +85,12 @@ comando agêntico [sincronizar](../../.pbai4devs/commands/sincronizar/COMMAND.md
 orienta executar o script com `--force`; ele não é o mesmo que `sync` da CLI.
 
 No Git, o kit preserva o `.gitignore` da raiz e pode atualizar
-`.git/info/exclude`. Se o plano indicar `untrackedPaths`, a operação pode
-retirar do índice saídas comprovadamente geradas, mantendo seus arquivos no
-disco. Confira a lista: `--dry-run` e `sync --check` não alteram o índice.
-Backups locais ficam em `.agent-tests/` e não substituem o histórico Git.
+`.git/info/exclude` para ocultar por padrão as pastas dos clientes. O projeto
+pode reabri-las no `.gitignore` da raiz, como em `!/.claude/`; consulte as
+[exceções e seus efeitos](installation.md#git-e-migração). Os comandos não
+retiram arquivos já rastreados do índice, e `untrackedPaths` permanece vazio
+por compatibilidade. Backups locais ficam em `.agent-tests/` e não substituem
+o histórico Git.
 
 ## Ferramentas
 

package/docs/guides/installation.md

@@ -87,7 +87,7 @@ O próximo passo é [preparar as ferramentas](prerequisites.md#depois-de-instala
 | Conteúdo | Tratamento |
 | --- | --- |
 | `.pbai4devs` com recursos e templates | Fonte compartilhada versionável. |
-| Skills, regras e comandos nos clientes | Apontamentos locais gerados. |
+| Recursos nos clientes | Apontamentos locais; pastas ignoradas por padrão. |
 | Entradas da raiz criadas pelo kit | Arquivos locais gerados. |
 | Índices, manifesto e seleção pessoal | Derivados locais ignorados. |
 | Código, documentos e configurações humanas | Preservados. |
@@ -102,12 +102,31 @@ identifica a licença dos recursos do AgentDevKit, sem redefinir a do projeto.
 
 ## Git e migração
 
-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`.
-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.
+Um `.gitignore` dentro de `.pbai4devs` só controla essa árvore: `../` não
+alcança pastas irmãs. O kit gera regras em `.git/info/exclude` para ignorar
+por padrão as pastas dos clientes, sem alterar o `.gitignore` da raiz.
+Essas regras são locais, não acompanham o clone; execute `init` ou `sync`
+em cada clone com Git inicializado, antes de usar `git add`. Sem Git, a
+exclusão fica pendente até `git init` e sincronização.
+Worktrees do mesmo repositório podem compartilhar esse arquivo de exclusões.
+
+Para versionar uma pasta de cliente, o projeto pode acrescentar uma exceção
+literal ao seu próprio `.gitignore` da raiz, por exemplo:
+
+```gitignore
+!/.claude/
+!/.github/
+```
+
+A exceção da raiz tem precedência sobre `.git/info/exclude`; regras de um
+`.gitignore` mais profundo continuam valendo. Não use `!/.claude/**`: um
+curinga amplo pode reabrir credenciais e artefatos que devem ficar locais.
+O diagnóstico informa exceções que exponham esses arquivos.
+
+O padrão também oculta arquivos humanos ainda não rastreados nas pastas dos
+clientes. Em especial, `.github` pode conter workflows, formulários de issues
+e outras configurações do projeto; use `!/.github/` se precisar versioná-los.
+O mesmo cuidado vale para `.vscode` e configurações próprias de outros agentes.
 
 O bloco local também protege `.agent-tests`, `tmp`, `temp`, `.playwright*`
 e relatórios de testes, inclusive com letras maiúsculas e em subpastas.
@@ -119,15 +138,10 @@ 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.
-O plano informa esses caminhos em `untrackedPaths` antes de aplicar; examine-os
-e preserve alterações preparadas da equipe. `--dry-run` e `sync --check` não
-alteram o índice.
-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.
+Ignorar uma pasta não retira arquivos já rastreados do índice. O kit preserva
+o índice, inclusive alterações preparadas; para mudar o rastreamento, o projeto
+decide a ação Git. `--dry-run` e `sync --check` também não alteram o índice.
+Revise o plano e os conflitos antes de aplicar em um projeto existente.
 
 ## Atualizar e escolher agentes
 
@@ -137,9 +151,9 @@ continua válida; `agents` consulta e `agents codex,claude` altera a seleção.
 necessárias para outro cliente, como `.agents` para Codex e Antigravity.
 
 Confira `update --dry-run --json` antes de atualizar um projeto existente.
-Revise arquivos criados, atualizados e removidos, conflitos, `preserved` e
-eventuais alterações do índice. `sync` usa as fontes já instaladas e não baixa
-uma nova versão. Consulte a [referência da CLI](cli.md) para todos os comandos.
+Revise arquivos criados, atualizados e removidos, conflitos e `preserved`.
+`sync` usa as fontes já instaladas e não baixa uma nova versão. Consulte a
+[referência da CLI](cli.md) para todos os comandos.
 
 Skills e outros recursos próprios podem coexistir com os do kit. Um nome
 igual não comprova propriedade: conteúdo humano e arquivos adicionais não
@@ -165,8 +179,8 @@ dele: atualizações alteram somente a contribuição do kit. Nomes de entradas
 com caixa diferente são reaproveitados quando há uma única opção.
 Comandos Gemini mantêm a referência dentro do valor `prompt` em TOML válido.
 Configurações que não são instruções não recebem uma mesclagem arbitrária.
-Arquivos mistos permanecem sob controle do Git do projeto; somente derivados
-integralmente gerados pelo kit recebem exclusão local.
+Arquivos mistos não passam a pertencer ao kit. Sua visibilidade para o Git
+também depende da regra aplicada à pasta do cliente.
 
 Links simbólicos preexistentes são preservados sem atravessá-los. O campo
 `preserved` informa rotas que continuam sob controle do projeto. Um formato

package/docs/guides/troubleshooting.md

@@ -164,8 +164,9 @@ não devem ser versionados. Verifique com `git status` e `git check-ignore -v
 retira automaticamente do Git; revise a remoção do índice sem apagar dados.
 
 O `.gitignore` do hub não controla pastas irmãs. Confira a proteção local
-gerada pelo kit, incluindo `info/exclude` nos repositórios Git. Preserve
-configurações humanas em `.github` e `.vscode` ao migrar arquivos antigos.
+gerada pelo kit em `info/exclude`. Para versionar configurações humanas novas
+em `.github` ou `.vscode`, reabra a pasta com `!/.github/` ou `!/.vscode/`
+no `.gitignore` da raiz. Confira as regras com `git check-ignore -v`.
 
 Para pedir ajuda, inclua SO/arquitetura, versões de Node/npm/AgentDevKit,
 comando executado, código de saída e trecho relevante do JSON, sem segredos.

package/docs/product/design.md

@@ -60,13 +60,13 @@ bloco exigem revisão e não autorizam sobrescrever o arquivo com `--force`.
 Arquivos novos e integralmente gerados continuam com propriedade integral.
 Comandos TOML recebem a referência no valor de `prompt`, preservando as demais
 chaves. Configurações nativas fora desse escopo permanecem sob controle humano.
-Nunca é possível ignorar somente um trecho de arquivo no Git: arquivos mistos
-não entram nas exclusões do kit. Veja a [spec de integração][additive].
+Nunca é possível ignorar somente um trecho de arquivo no Git. Veja a
+[spec de integração][additive].
 
-Saídas identificadas são excluídas localmente do versionamento. O Git local
-usa `info/exclude`; fora de um repositório, a proteção fica no `.gitignore`
-da raiz. A política vem dos templates, não de listas copiadas por cliente.
-Os arquivos humanos de `.github` e `.vscode` continuam versionáveis.
+O Git usa `info/exclude` para ignorar localmente pastas de clientes, inclusive
+seus arquivos humanos ainda não rastreados. Exceções literais no `.gitignore`
+da raiz permitem versioná-las. Arquivos já rastreados e o índice permanecem;
+sem Git, a proteção fica pendente. A política vem dos templates.
 
 O estado registra versão, escolha e propriedade local. Índices e manifesto
 podem ser reconstruídos. Downloads, credenciais e relatórios ficam fora do

package/docs/specs/README.md

@@ -25,6 +25,7 @@ description: Incrementos verificáveis do AgentDevKit.
 - [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.
+- [Ignore de clientes](client-ignore/SPEC.md): padrão local e exceções do projeto.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 

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

@@ -0,0 +1,21 @@
+---
+description: Exclusão local de clientes com escolha explícita do projeto.
+---
+
+# Ignore de clientes
+
+O Git não aplica `../` no `.gitignore` do hub às pastas irmãs. O kit usa
+exclusões locais do Git e o projeto escolhe exceções no seu `.gitignore`.
+
+## Critérios de aceite
+
+- AC-001: Pastas de clientes são ignoradas por padrão em repositórios Git,
+  sem modificar o `.gitignore` da raiz.
+- AC-002: Uma exceção literal da raiz, como `!/.claude/`, permite versionar
+  o cliente e continua válida após instalação, atualização e sincronização.
+- AC-003: Credenciais e artefatos continuam protegidos; exceções inseguras
+  são informadas antes de qualquer mudança.
+- AC-004: Arquivos humanos e o índice Git, incluindo alterações preparadas,
+  são preservados. Arquivos já rastreados continuam rastreados.
+- AC-005: Documentação e testes explicam e verificam precedência, limites,
+  clones, clientes compartilhados, cenários sem Git e sistemas suportados.

package/package.json

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

package/src/install.mjs

@@ -4,7 +4,7 @@ import { chmodSync, closeSync, existsSync, fstatSync, lstatSync, openSync, readF
 import { tmpdir } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { synchronize, isReference } from '../.pbai4devs/scripts/sincronizar-agentes/SCRIPT.mjs';
-import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, planUntrack, applyUntrack, restoreUntrack, indexContentMatches } from '../.pbai4devs/scripts/lib/gitignore.mjs';
+import { isGeneratedOutput, planLocalIgnore, checkLocalIgnore, assertLocalIgnoreUnchanged, applyLocalIgnore, indexContentMatches } from '../.pbai4devs/scripts/lib/gitignore.mjs';
 import { nativePathBoundary } from '../.pbai4devs/scripts/lib/native-paths.mjs';
 import { canonicalEntrypoint, resolveEntrypoint, entrypointReference, renderEntrypointImports, extractManagedBlock, managedBlockDigest, mergeManagedContent, stripManagedContent } from '../.pbai4devs/scripts/lib/managed-content.mjs';
 import { extractTomlManagedBlock, tomlManagedBlockDigest, mergeTomlContent, stripTomlContent } from '../.pbai4devs/scripts/lib/managed-toml.mjs';
@@ -698,16 +698,9 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     if (stagedChanges.length) fail('E_STAGED', `Staged content differs from the working tree for planned changes: ${stagedChanges.map(change => `${change.action} ${change.path}`).join(', ')}. Preserve and review these paths before updating.`);
     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 (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);
-      if (current) { const source = current.toString('utf8'), block = extractBlock(source, '# BEGIN AGENT IGNORE', '# END AGENT IGNORE'); if (block && source.trim() === block.trim() && hash(block) === previous.blocks[path]) hashes[path] = hash(current); }
-    }
-    if (previous && !migration) hashes[statePath] = hash(read(target, statePath));
-    const untrack = existsSync(target) ? planUntrack(target, hashes) : null;
-    if (migration && untrack?.paths.length) fail('E_STATE', 'State migration would change the Git index; preserve and resolve tracked outputs first.');
+    // Ignore rules affect only untracked files. Never remove existing index
+    // entries on behalf of the project; staged bytes are checked separately.
+    const untrack = { root: target, paths: [], hashes: {}, index: '', conflicts: [] };
     const localIgnore = planLocalIgnore(target, { outputs: ownedOutputs, templateRoot: stage });
     const localIgnoreCheck = checkLocalIgnore(localIgnore, { replacedBlocks: replacedIgnoreBlocks(target, changes, previous) });
     conflicts.push(...(untrack?.conflicts || []), ...localIgnoreCheck.missing);
@@ -759,14 +752,12 @@ export function applyPlan(plan) {
   for (const change of plan.changes) if ((before.get(change.path) ? hash(before.get(change.path)) : null) !== change.beforeHash) fail('E_CHANGED', `File changed after planning: ${change.path}`);
   for (const [path, content] of before) if (content) write(target, `${backup}/${path}`, content, beforeModes.get(path));
   const applied = [], removedDirectories = [];
-  let untracked = false;
   const assertOriginal = path => {
     const file = safePath(target, path), info = stat(file), bytes = before.get(path);
     if (bytes === null ? info !== null : !info?.isFile() || !readFileSync(file).equals(bytes) || (info.mode & 0o777) !== beforeModes.get(path)) fail('E_CHANGED', `File changed before writing: ${path}`);
   };
   try {
     for (const change of plan.changes) assertOriginal(change.path);
-    if (plan.untrack?.paths.length) { applyUntrack(plan.untrack); untracked = true; }
     for (const change of plan.changes) {
       assertOriginal(change.path);
       const file = safePath(target, change.path);
@@ -806,7 +797,7 @@ export function applyPlan(plan) {
     const changesFallback = plan.changes.some(change => change.path === '.gitignore');
     // Metadata is committed last; its writer rolls back partial writes itself.
     const ignored = applyLocalIgnore(changesFallback ? planLocalIgnore(target, { outputs: plan.ownedOutputs }) : plan.localIgnore);
-    return { changed: Boolean(plan.changes.length || ignored.changed || untracked), backup: [...before.values()].some(Boolean) ? backup : null };
+    return { changed: Boolean(plan.changes.length || ignored.changed), backup: [...before.values()].some(Boolean) ? backup : null };
   } catch (error) {
     const rollbackErrors = [], preserved = [];
     for (const removed of [...removedDirectories].sort((a, b) => a.path.length - b.path.length)) {
@@ -847,7 +838,6 @@ export function applyPlan(plan) {
     if (preserved.length) {
       try { error.rollbackPreservedPaths = preserved; } catch { /* Preserve a exceção original. */ }
     }
-    if (untracked) try { restoreUntrack(plan.untrack); } catch (failure) { rollbackErrors.push(failure); }
     if (rollbackErrors.length) throw Object.assign(new AggregateError([error, ...rollbackErrors], `${error.message}; rollback incompleto: ${rollbackErrors.map(failure => failure.message).join('; ')}`, { cause: error }), { code: error.code || 'E_OPERATION' });
     throw error;
   }