@pathbit/agentdevkit 0.0.24 → 0.0.25

package/.pbai4devs/commands/revisar-entrega/COMMAND.md

@@ -24,6 +24,12 @@ urgente, defina critérios próprios AC-001 e registre o motivo.
    revisão e `revisar-entrega check <relatorio>` pelo mesmo seletor. Falha,
    critério sem prova ou revisão pendente bloqueiam o commit/merge.
 
+Antes de um merge fast-forward, na origem, execute `revisar-entrega check-merge
+--destino refs/heads/<destino> <relatorio> [outros-relatorios...]`. A verificação
+exige cobertura do diff e correspondência com o commit revisado. Ela bloqueia
+históricos divergentes, links, submódulos, arquivos executáveis e operações Git
+acima de 64 MiB. Confirme os hashes retornados antes de integrar.
+
 Saída: resultado por critério, pendências e caminho do único `revisao.json` em
 `.agent-tests/<referencia>/<execucao>/`. Esta etapa é obrigatória após qualquer
 implementação; a ausência de spec não elimina a revisão.

package/.pbai4devs/scripts/revisar-entrega/SCRIPT.mjs

@@ -26,7 +26,7 @@ function pathInRoot(root, input) {
 }
 
 function git(root, args, allowFailure = false) {
-  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 15000, windowsHide: true });
+  const result = spawnSync('git', args, { cwd: root, encoding: 'utf8', timeout: 15000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' } });
   if ((result.error || result.status !== 0) && !allowFailure) fail(`Git: ${result.error?.message || result.stderr?.trim() || 'operacao falhou'}`);
   return result;
 }
@@ -53,7 +53,7 @@ function tracked(root, file) {
 
 function ignoredPaths(root, files) {
   if (!files.length) return new Set();
-  const result = spawnSync('git', ['check-ignore', '--no-index', '--stdin', '-z'], { cwd: root, input: files.join('\0') + '\0', encoding: 'utf8', timeout: 15000, windowsHide: true });
+  const result = spawnSync('git', ['check-ignore', '--no-index', '--stdin', '-z'], { cwd: root, input: files.join('\0') + '\0', encoding: 'utf8', timeout: 15000, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' } });
   if (result.error || ![0, 1].includes(result.status)) fail(`Git: ${result.error?.message || result.stderr?.trim() || 'falha ao conferir ignores'}`);
   return new Set(result.stdout.split('\0').filter(Boolean));
 }
@@ -211,11 +211,79 @@ function validateReview(file, { root = projectRoot, requireSeal = true } = {}) {
     const recorded = JSON.parse(readFileSync(join(root, sealPath), 'utf8'));
     if (JSON.stringify(recorded) !== JSON.stringify(seal)) fail('Relatorio, baseline ou evidencia alterados apos selar a revisao.');
   }
-  return { root, prefix, seal, result: { status: 'passed', report: reportPath, criteria: ids.size, documents: docs.size } };
+  return { root, prefix, seal, snapshot: state, result: { status: 'passed', report: reportPath, criteria: ids.size, documents: docs.size } };
 }
 
 export function checkReview(file, { root = projectRoot } = {}) { return validateReview(file, { root, requireSeal: true }).result; }
 
+// This deliberately permits only a fast-forward and regular non-executable
+// files. Existing review snapshots do not record modes or merge results.
+export function checkMerge(reports, destination, { root = projectRoot } = {}) {
+  requireNode(); root = repository(root);
+  if (!Array.isArray(reports) || !reports.length) fail('Informe um ou mais relatorios selados, sem repeticao.');
+  reports = reports.map(file => pathInRoot(root, file));
+  if (new Set(reports).size !== reports.length) fail('Informe relatorios selados sem repeticao.');
+  if (typeof destination !== 'string' || !destination.startsWith('refs/heads/') || git(root, ['check-ref-format', destination], true).status !== 0) fail('Destino deve ser uma branch local completa: refs/heads/<nome>.');
+  const currentBranch = git(root, ['symbolic-ref', '--quiet', 'HEAD'], true);
+  if (currentBranch.status !== 0) fail('Confira a branch de origem; HEAD destacado nao e aceito.');
+  const sourceRef = currentBranch.stdout.trim();
+  if (!sourceRef.startsWith('refs/heads/') || git(root, ['check-ref-format', sourceRef], true).status !== 0) fail('A origem deve ser uma branch local valida.');
+  if (sourceRef === destination) fail('Origem e destino devem ser branches distintas.');
+  for (const ref of [sourceRef, destination]) if (git(root, ['symbolic-ref', '--quiet', ref], true).status === 0) fail(`Branch simbolica nao e aceita: ${ref}`);
+  const resolveCommit = ref => {
+    const out = git(root, ['rev-parse', '--verify', `${ref}^{commit}`], true);
+    const value = out.stdout?.trim();
+    if (out.status !== 0 || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value || '')) fail(`Branch ou commit invalido: ${ref}`);
+    return value;
+  };
+  const source = resolveCommit(sourceRef), target = resolveCommit(destination);
+  if (head(root) !== source) fail('HEAD diverge da branch de origem.');
+  if (git(root, ['merge-base', '--is-ancestor', target, source], true).status !== 0) fail('Apenas fast-forward comprovado e suportado; revise o resultado integrado para historico divergente.');
+  const bytes = args => {
+    const result = spawnSync('git', args, { cwd: root, timeout: 15000, windowsHide: true, maxBuffer: 64 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', GIT_NO_REPLACE_OBJECTS: '1' } });
+    if (result.error || result.status !== 0) fail(`Git: ${result.error?.message || result.stderr?.toString().trim() || 'operacao falhou'}`);
+    return result.stdout;
+  };
+  const decode = data => { try { return new TextDecoder('utf-8', { fatal: true }).decode(data); } catch { fail('Caminho Git nao e UTF-8 valido.'); } };
+  const raw = bytes(['diff', '--raw', '-z', '--no-abbrev', '--no-renames', '--no-ext-diff', '--no-textconv', '--ignore-submodules=none', target, source, '--']);
+  const parts = decode(raw).split('\0');
+  if (parts.pop() !== '' || parts.length % 2) fail('Diff Git incompleto ou ambiguo.');
+  const changes = new Map();
+  for (let i = 0; i < parts.length; i += 2) {
+    const match = /^:(\d{6}) (\d{6}) ([a-f0-9]+) ([a-f0-9]+) ([AMD])$/.exec(parts[i]);
+    if (!match) fail('Tipo de alteracao Git nao suportado.');
+    const [, beforeMode, afterMode, , , action] = match, path = pathInRoot(root, parts[i + 1]);
+    if (changes.has(path) || !['000000', '100644'].includes(beforeMode) || !['000000', '100644'].includes(afterMode)) fail(`Tipo ou modo nao comprovado: ${path}`);
+    changes.set(path, action);
+  }
+  if (!changes.size) fail('Nao ha alteracoes para integrar.');
+  const reviewed = new Set();
+  const verified = reports.map(file => validateReview(file, { root, requireSeal: true }));
+  for (const review of verified) {
+    if (review.snapshot.head !== source) fail('Relatorio nao corresponde ao commit de origem.');
+    for (const item of review.snapshot.files) {
+      const path = pathInRoot(root, item.path);
+      if (item.indexAction !== undefined) fail(`Acao de indice nao pode comprovar merge: ${path}`);
+      const tree = decode(bytes(['--literal-pathspecs', 'ls-tree', '-z', '--full-tree', source, '--', path]));
+      if (!tree) {
+        if (item.sha256 !== null) fail(`Conteudo revisado nao esta no commit de origem: ${path}`);
+      } else {
+        const m = /^(\d{6}) blob ([a-f0-9]+)\t([^\0]+)\0$/.exec(tree);
+        if (!m || m[1] !== '100644' || m[3] !== path) fail(`Arquivo, link ou modo nao comprovado no commit: ${path}`);
+        if (item.sha256 !== createHash('sha256').update(bytes(['cat-file', 'blob', m[2]])).digest('hex')) fail(`Conteudo revisado difere do commit de origem: ${path}`);
+      }
+      if (changes.has(path)) reviewed.add(path);
+    }
+  }
+  const missing = [...changes.keys()].filter(path => !reviewed.has(path));
+  if (missing.length) fail(`Alteracoes sem revisao selada: ${missing.join(', ')}`);
+  // Detect moved refs or changed worktree/reports during the validation.
+  if (git(root, ['symbolic-ref', '--quiet', 'HEAD']).stdout.trim() !== sourceRef || resolveCommit(sourceRef) !== source || resolveCommit(destination) !== target || head(root) !== source) fail('Origem ou destino mudou durante a verificacao.');
+  for (const file of reports) validateReview(file, { root, requireSeal: true });
+  if (git(root, ['symbolic-ref', '--quiet', 'HEAD']).stdout.trim() !== sourceRef || resolveCommit(sourceRef) !== source || resolveCommit(destination) !== target || head(root) !== source) fail('Origem ou destino mudou durante a verificacao.');
+  return { status: 'passed', sourceRef, source, destination, target, changes: changes.size, reports: reports.length, mode: 'fast-forward' };
+}
+
 export function sealReview(file, options) {
   const checked = validateReview(file, { ...options, requireSeal: false });
   const path = artifact(checked.root, `${checked.prefix}/seal.json`, checked.prefix, false);
@@ -224,12 +292,13 @@ export function sealReview(file, options) {
   return checkReview(file, options);
 }
 
-const usage = 'Uso: revisar-entrega prepare --id <slug> [--execution <slug>] [--spec <arquivo>] [--scope <arquivo>] [--document <arquivo>] [--output <artefato>]; seal|check <revisao.json>';
+const usage = 'Uso: revisar-entrega prepare --id <slug> [--execution <slug>] [--spec <arquivo>] [--scope <arquivo>] [--document <arquivo>] [--output <artefato>]; seal|check <revisao.json>; check-merge --destino refs/heads/<branch> <revisao.json> [...]';
 export function main(args = process.argv.slice(2)) {
   requireNode(); const [mode, ...rest] = args;
   if (!mode || ['--help', '-h'].includes(mode)) { console.log(usage); return 0; }
   if (mode === 'check' && rest.length === 1) { console.log(JSON.stringify(checkReview(rest[0]))); return 0; }
   if (mode === 'seal' && rest.length === 1) { console.log(JSON.stringify(sealReview(rest[0]))); return 0; }
+  if (mode === 'check-merge' && rest.length >= 3 && rest[0] === '--destino') { console.log(JSON.stringify(checkMerge(rest.slice(2), rest[1]))); return 0; }
   if (mode !== 'prepare') fail(usage);
   const options = { scope: [], documents: [] };
   const fields = { '--id': 'id', '--execution': 'execution', '--spec': 'spec', '--output': 'output' };

package/.pbai4devs/scripts/revisar-entrega/tests/TEST.mjs

@@ -1,9 +1,9 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { checkReview, prepareReview, sealReview, specCriteria } from '../SCRIPT.mjs';
+import { checkMerge, checkReview, prepareReview, sealReview, specCriteria } from '../SCRIPT.mjs';
 import { projectRoot } from '../../lib/runtime.mjs';
 
 function fixture(t) {
@@ -247,3 +247,113 @@ test('documentos rastreados permanecem obrigatórios mesmo com regra de ignore',
   assert.ok(f.report.documentation.some(item => item.path === 'spec.md'));
   assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
 });
+
+function mergeFixture(t, { scope = ['src/main.mjs', 'src/old.txt', 'src/new.txt'], dirty = false, seal = true, ignoredSubmodule = false } = {}) {
+  const f = fixture(t);
+  const commit = message => f.git('-c', 'user.name=Test User', '-c', 'user.email=test@example.invalid', '-c', 'commit.gpgsign=false', '-c', 'core.hooksPath=disabled-hooks', 'commit', '-q', '-m', message);
+  f.put('src/old.txt', 'original\n'); f.git('add', '.'); commit('test: base');
+  f.git('branch', '-M', 'main'); f.git('checkout', '-q', '-b', 'feature');
+  f.put('src/main.mjs', 'export const value=2;\n');
+  f.git('mv', 'src/old.txt', 'src/new.txt'); f.git('add', 'src/main.mjs'); commit('test: source');
+  if (ignoredSubmodule) {
+    const object = f.git('rev-parse', 'HEAD').trim();
+    f.git('update-index', '--add', '--cacheinfo', `160000,${object},vendor`);
+    commit('test: submodule');
+    f.git('config', 'diff.ignoreSubmodules', 'all');
+  }
+  if (dirty) f.put('src/main.mjs', 'export const value=3; // not committed\n');
+  const made = prepareReview({ root: f.root, id: 'merge', execution: 'review', scope });
+  for (const item of made.report.documentation) Object.assign(item, { decision: 'no-impact', reason: 'Documento examinado na fixture.' });
+  const proof = '.agent-tests/merge/review/proof.txt'; f.put(proof, 'Prova sintetica para testar validacao.\n');
+  for (const item of made.report.validation) Object.assign(item, { method: 'fixture', prerequisite: 'fixture local', assertion: 'snapshot comparado', evidence: [proof], status: 'passed' });
+  made.report.review = { status: 'approved', reviewer: 'simulacao de teste', findings: [] };
+  f.put(made.file, JSON.stringify(made.report));
+  if (seal) sealReview(made.file, { root: f.root });
+  return { ...f, ...made, commit };
+}
+
+test('check-merge prova fast-forward completo sem alterar indice ou arquivos humanos', t => {
+  const f = mergeFixture(t);
+  f.put('human.txt', 'staged humano\n'); f.git('add', 'human.txt'); f.put('human.txt', 'alteracao humana\n');
+  const index = readFileSync(join(f.root, '.git/index')), human = readFileSync(join(f.root, 'human.txt'));
+  const result = checkMerge([f.file], 'refs/heads/main', { root: f.root });
+  assert.equal(result.status, 'passed'); assert.equal(result.mode, 'fast-forward'); assert.equal(result.changes, 3);
+  assert.equal(result.source, f.git('rev-parse', 'HEAD').trim()); assert.equal(result.target, f.git('rev-parse', 'main').trim());
+  assert.deepEqual(readFileSync(join(f.root, '.git/index')), index); assert.deepEqual(readFileSync(join(f.root, 'human.txt')), human);
+});
+
+test('check-merge funciona na CLI e rejeita relatorio duplicado por alias', t => {
+  const f = mergeFixture(t);
+  const script = '.pbai4devs/scripts/revisar-entrega/SCRIPT.mjs', runtime = '.pbai4devs/scripts/lib/runtime.mjs';
+  for (const file of [script, runtime]) { mkdirSync(dirname(join(f.root, file)), { recursive: true }); cpSync(join(projectRoot, file), join(f.root, file)); }
+  const args = [join(f.root, script), 'check-merge', '--destino', 'refs/heads/main', f.file];
+  const run = spawnSync(process.execPath, args, { cwd: f.root, encoding: 'utf8' });
+  assert.equal(run.status, 0, run.stderr); assert.equal(JSON.parse(run.stdout).status, 'passed');
+  assert.throws(() => checkMerge([f.file, `./${f.file}`], 'refs/heads/main', { root: f.root }), /sem repeticao/);
+});
+
+test('check-merge bloqueia conteudo nao commitado e escopo parcial', async t => {
+  await t.test('working tree diferente do commit', t => {
+    const f = mergeFixture(t, { dirty: true });
+    assert.equal(checkReview(f.file, { root: f.root }).status, 'passed');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /difere do commit/);
+  });
+  await t.test('omissao de arquivo removido', t => {
+    const f = mergeFixture(t, { scope: ['src/main.mjs', 'src/new.txt'] });
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /sem revisao selada: src\/old.txt/);
+  });
+  await t.test('relatorio sem selo', t => {
+    const f = mergeFixture(t, { seal: false });
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /nao selada/);
+  });
+});
+
+test('check-merge aceita cobertura distribuida por relatorios selados', t => {
+  const f = mergeFixture(t, { scope: ['src/main.mjs', 'src/new.txt'] });
+  const made = prepareReview({ root: f.root, id: 'merge-extra', execution: 'review', scope: ['src/old.txt'] });
+  for (const item of made.report.documentation) Object.assign(item, { decision: 'no-impact', reason: 'Documento examinado na fixture.' });
+  const proof = '.agent-tests/merge-extra/review/proof.txt'; f.put(proof, 'Prova sintetica complementar.\n');
+  for (const item of made.report.validation) Object.assign(item, { method: 'fixture', prerequisite: 'fixture local', assertion: 'delecao revisada', evidence: [proof], status: 'passed' });
+  made.report.review = { status: 'approved', reviewer: 'simulacao de teste', findings: [] };
+  f.put(made.file, JSON.stringify(made.report)); sealReview(made.file, { root: f.root });
+  const result = checkMerge([f.file, made.file], 'refs/heads/main', { root: f.root });
+  assert.equal(result.status, 'passed'); assert.equal(result.reports, 2); assert.equal(result.changes, 3);
+});
+
+test('check-merge recusa origem e destino invalidos, divergencia e tipos nao comprovados', async t => {
+  await t.test('branch invalida ou identica', t => {
+    const f = mergeFixture(t);
+    for (const name of ['main', 'refs/heads/missing', 'refs/heads/feature', '--help']) assert.throws(() => checkMerge([f.file], name, { root: f.root }));
+  });
+  await t.test('historico divergente', t => {
+    const f = mergeFixture(t); f.git('checkout', '-q', 'main'); f.put('different.txt', 'destino\n'); f.git('add', 'different.txt'); f.commit('test: target'); f.git('checkout', '-q', 'feature');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /fast-forward/);
+  });
+  await t.test('HEAD destacado', t => {
+    const f = mergeFixture(t); f.git('checkout', '-q', '--detach');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /HEAD destacado/);
+  });
+  await t.test('origem fora das branches locais', t => {
+    const f = mergeFixture(t); f.git('symbolic-ref', 'HEAD', 'refs/remotes/origin/feature');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /origem deve ser uma branch local/);
+  });
+  await t.test('submodulo ignorado pela configuracao Git', t => {
+    const f = mergeFixture(t, { ignoredSubmodule: true });
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /modo nao comprovado: vendor/);
+    const script = '.pbai4devs/scripts/revisar-entrega/SCRIPT.mjs', runtime = '.pbai4devs/scripts/lib/runtime.mjs';
+    for (const file of [script, runtime]) { mkdirSync(dirname(join(f.root, file)), { recursive: true }); cpSync(join(projectRoot, file), join(f.root, file)); }
+    const run = spawnSync(process.execPath, [join(f.root, script), 'check-merge', '--destino', 'refs/heads/main', f.file], { cwd: f.root, encoding: 'utf8' });
+    assert.equal(run.status, 1); assert.match(run.stderr, /modo nao comprovado: vendor/);
+  });
+  await t.test('link simbolico', t => {
+    const f = mergeFixture(t);
+    try { symlinkSync('main.mjs', join(f.root, 'src/link')); }
+    catch (error) { if (['EPERM', 'EACCES', 'ENOSYS'].includes(error.code)) return t.skip('Sem permissao de symlink.'); throw error; }
+    f.git('add', 'src/link'); f.commit('test: link');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /simbolico|modo nao comprovado/);
+  });
+  await t.test('arquivo executavel', t => {
+    const f = mergeFixture(t); f.git('update-index', '--chmod=+x', 'src/main.mjs'); f.commit('test: mode');
+    assert.throws(() => checkMerge([f.file], 'refs/heads/main', { root: f.root }), /modo nao comprovado/);
+  });
+});

package/.pbai4devs/skills/git/git-merge/SKILL.md

@@ -8,6 +8,29 @@ description: Integra branches com trabalho concluído e verificado.
 Confira origem, destino, histórico, identidades, mensagens, alterações locais e
 verificações; integre somente tarefas completas conforme AGENTS.md. Se os
 commits a integrar identificarem agentes como autores ou coautores, informe e
-não os integre. Se gerar commit de merge, confira as identidades efetivas e siga
+não os integre.
+
+Quando houver implementação ou gate exigido, na origem execute isoladamente:
+
+```sh
+node .pbai4devs/scripts/revisar-entrega/SCRIPT.mjs check-merge \
+  --destino refs/heads/<branch> <revisao.json> [outros...]
+```
+
+O check exige fast-forward, cobertura de todo o diff e snapshots correspondentes
+ao commit de origem; qualquer falha bloqueia a integração. Registre os hashes
+de origem e destino retornados e confirme ambos imediatamente antes do merge,
+com comandos que interrompam a execução em qualquer falha; não mascare o status.
+Confirme também que `git symbolic-ref HEAD` é a ref de destino e que o HEAD
+corresponde ao hash de destino validado. Se alguma conferência falhar,
+interrompa; se os hashes mudarem, refaça a revisão e o check. Integre com
+`git merge --ff-only <hash-da-origem-validada>`. Essas verificações não são
+atômicas. O check recusa links, submódulos, arquivos executáveis e saídas Git
+maiores que 64 MiB; informe bloqueios sem contorná-los. Preserve trabalho fora
+do escopo.
+Se o resultado integrado divergir do conteúdo revisado, faça nova revisão e
+verificações antes de concluir. Sem implementação, siga os critérios aplicáveis.
+
+Se gerar commit de merge, confira as identidades efetivas e siga
 `.pbai4devs/rules/git/RULE.md` para identidade, mensagem e assinatura. Preserve
 alterações, resolva conflitos no escopo autorizado e respeite proteções da branch.

package/CHANGELOG.md

@@ -4,6 +4,14 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.25 — 2026-11-14
+
+- Verifica a cobertura e o conteúdo revisado antes de um merge fast-forward;
+  bloqueia situações que o gate não consegue comprovar.
+- Esclarece a validação na origem e a interrupção do merge quando o gate falha.
+- Amplia as provas de preservação em projetos existentes e explica os limites
+  do campo `preserved`. Os projetos de exemplo gerados continuam locais.
+
 ## 0.0.24 — 2026-11-14
 
 - Preserva catálogos, configuração e blocos existentes sem comprovação de

package/docs/guides/installation.md

@@ -183,9 +183,11 @@ 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
-não suportado ou um bloco alterado é informado; `--force` não permite apagar
-instruções humanas para reconstruir um apontamento.
+`preserved` lista caminhos próprios encontrados no planejamento ou em colisões,
+sem inventariar rotas não examinadas. A ausência de um caminho não prova que ele
+foi verificado ou preservado. Um formato não suportado ou um bloco alterado é
+informado; `--force` não permite apagar instruções humanas para reconstruir um
+apontamento.
 
 Essa preservação não autoriza trocar arquivos gerenciados por links. Links
 em caminhos já pertencentes ao kit, no hub, no estado ou em ferramentas

package/docs/guides/resources.md

@@ -158,7 +158,10 @@ Não apague pastas inteiras para contornar um conflito.
 
 Recursos nativos humanos são preservados, inclusive com `--force` e nomes
 iguais aos do kit. Links humanos são tratados como caminhos opacos; o gerador
-não os atravessa. A CLI informa essas rotas em `preserved` no JSON.
+não os atravessa. No JSON, `preserved` lista caminhos humanos encontrados no
+planejamento ou em colisões; não inventaria rotas não examinadas, como um
+fallback não utilizado. A ausência de um caminho não prova que ele foi
+verificado ou preservado.
 
 Não edite ou versione `catalog.json`, `skills.json`, `rules.json` ou
 `agents.json`: são derivados locais. Configurações nativas e documentos

package/package.json

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