@pathbit/agentdevkit 0.0.23 → 0.0.25

package/.pbai4devs/scripts/testar-maturidade/tests/TEST.mjs

@@ -1,11 +1,13 @@
 import assert from 'node:assert/strict';
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
+import fs from 'node:fs';
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import childProcess, { spawnSync } from 'node:child_process';
 import { syncBuiltinESMExports } from 'node:module';
 import { createHash } from 'node:crypto';
 import test from 'node:test';
 import { projectRoot, requireNode } from '../../lib/runtime.mjs';
+import { adapterManifest } from '../../lib/adapters.mjs';
 import { copyAgentStructure, prepareExamples as prepare, registeredRoots, resourceTargets, SCENARIOS } from '../SCRIPT.mjs';
 
 // As fixtures pequenas isolam a cópia; o caso source-only usa o renderizador real.
@@ -32,6 +34,23 @@ function fixture(t) {
   return { root, put, outputRoot: join(root, 'examples/generated') };
 }
 
+function controlledSource(root) {
+  const source = join(root, 'controlled-source');
+  // Only four explicit resources; exclude local state and additional skills.
+  for (const path of ['.pbai4devs/skills/projeto/criar-skill/SKILL.md', '.pbai4devs/templates/gitignore/clients.json', '.pbai4devs/templates/gitignore/agents.ignore', '.pbai4devs/templates/gitignore/shared.ignore']) {
+    let current = projectRoot;
+    for (const part of path.split('/')) {
+      current = join(current, part);
+      assert.equal(lstatSync(current).isSymbolicLink(), false, `Fonte não pode ser link: ${path}`);
+    }
+    const destination = join(source, path);
+    mkdirSync(dirname(destination), { recursive: true });
+    copyFileSync(join(projectRoot, path), destination);
+  }
+  writeFileSync(join(source, '.gitignore'), 'node_modules/\n');
+  return source;
+}
+
 test('copia recursos e configurações, excluindo payloads, caches e segredos', t => {
   const { root, put } = fixture(t);
   put('.pbai4devs/tools/demo/TOOL.json', '{}'); put('.pbai4devs/tools/demo/SCRIPT.mjs', 'export {};'); put('.pbai4devs/tools/demo/README.md', '# Tool');
@@ -110,6 +129,34 @@ test('troca de ancestral por symlink antes da criação não escreve no destino
   }
 });
 
+test('troca de saída durante escrita é detectada, sem alegar atomicidade', t => {
+  const { root, outputRoot } = fixture(t);
+  const target = join(outputRoot, 'race-output'), outside = mkdtempSync(join(root, 'race-outside-'));
+  const sentinel = join(outside, 'sentinel'); writeFileSync(sentinel, 'Não alterar.\n');
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir';
+  const probe = join(root, 'race-link-probe');
+  try { symlinkSync(outside, probe, linkType); }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) { t.skip('Links simbólicos indisponíveis.'); return; } throw error; }
+  unlinkSync(probe);
+  const original = fs.writeFileSync; let injected = false;
+  try {
+    fs.writeFileSync = (file, ...args) => {
+      if (!injected && String(file) === join(target, '.maturity-suite.json')) {
+        renameSync(target, `${target}-moved`); symlinkSync(outside, target, linkType); injected = true;
+      }
+      return original.call(fs, file, ...args);
+    };
+    syncBuiltinESMExports();
+    assert.throws(() => prepareExamples({ sourceRoot: root, outputRoot: target, scenarios: [SCENARIOS[0]], initializeGit: false }), /link|alterado/i);
+  } finally { fs.writeFileSync = original; syncBuiltinESMExports(); }
+  assert.equal(injected, true);
+  assert.equal(readFileSync(sentinel, 'utf8'), 'Não alterar.\n');
+  // O write já em curso pode ter criado o marcador no destino externo: a
+  // verificação detecta a troca, mas não é uma operação atômica de diretório.
+  assert.equal(existsSync(join(outside, '.maturity-suite.json')), true);
+  assert.equal(existsSync(join(outside, 'REPORT.json')), false);
+});
+
 test('cada destino padrão é exclusivo, preserva provas anteriores e permanece ignorado', t => {
   const { root, outputRoot } = fixture(t);
   const git = (...args) => {
@@ -172,16 +219,16 @@ test('preparação interrompida não altera resultado anterior nem declara suces
   assert.doesNotMatch(readFileSync(index, 'utf8'), /status: passed|\| passed \|/);
 });
 
-test('usa entradas distribuídas do hub e mantém fallback legado', t => {
+test('sem estado comprovado conserva entradas humanas mesmo com template', t => {
   const { root, put } = fixture(t);
   const template = '---\ndescription: Entrada genérica.\n---\n\n# Agentes do projeto\n';
   put('AGENTS.md', '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
   put('.pbai4devs/templates/entrypoints/AGENTS.md', template);
   const destination = join(root, 'copy');
   const copied = copyAgentStructure(root, destination);
-  assert.equal(readFileSync(join(destination, 'AGENTS.md'), 'utf8'), template);
+  assert.equal(readFileSync(join(destination, 'AGENTS.md'), 'utf8'), '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
   assert.equal(readFileSync(join(destination, 'CLAUDE.md'), 'utf8'), 'fixture\n');
-  assert.equal(copied.entrypoints['AGENTS.md'], '.pbai4devs/templates/entrypoints/AGENTS.md');
+  assert.equal(copied.entrypoints['AGENTS.md'], 'AGENTS.md');
   assert.equal(copied.entrypoints['CLAUDE.md'], 'CLAUDE.md');
   assert.equal(readFileSync(join(root, 'AGENTS.md'), 'utf8'), '# Produto do distribuidor\n\n[PRD](docs/prd.md)\n');
 });
@@ -315,7 +362,9 @@ test('checkout de fontes sem manifesto deriva clientes em memória', t => {
 test('prepare gera apontamentos reais mesmo sem pastas de clientes na origem', t => {
   const { root } = fixture(t);
   const sourceRoot = join(root, 'source-only');
-  copyAgentStructure(projectRoot, sourceRoot);
+  copyAgentStructure(controlledSource(root), sourceRoot);
+  // Model a clean source checkout regardless of ignored local developer data.
+  for (const path of ['.pbai4devs/espelhos.conf', '.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json', '.pbai4devs/state/agentdevkit.json', '.pbai4devs/state/derived.json', '.pbai4devs/estado/agentdevkit.json', '.pbai4devs/estado/derived.json']) rmSync(join(sourceRoot, path), { force: true });
   const roots = registeredRoots(sourceRoot);
   for (const client of roots) rmSync(join(sourceRoot, client), { recursive: true, force: true });
   const [example] = prepare({ sourceRoot, scenarios: [SCENARIOS[0]], initializeGit: false });
@@ -325,6 +374,102 @@ test('prepare gera apontamentos reais mesmo sem pastas de clientes na origem', t
   for (const file of ['src/cli.mjs', 'bin/agentdevkit.mjs', 'scripts/release/pipeline.mjs', 'tests/cli.test.mjs']) assert.equal(existsSync(join(example.root, file)), false, file);
 });
 
+for (const withState of [false, true]) test(`prepare preserva catálogos humanos na cópia e na origem (estado=${withState})`, t => {
+  const { root } = fixture(t), sourceRoot = join(root, `source-catalog-${withState}`);
+  copyAgentStructure(controlledSource(root), sourceRoot);
+  // Source checkouts do not include generated manifests; provide this fixture
+  // explicitly instead of depending on ignored files in the developer's tree.
+  writeFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf'), adapterManifest(sourceRoot, { clients: ['codex'] }));
+  const state = join(sourceRoot, '.pbai4devs/state/agentdevkit.json');
+  const derived = join(sourceRoot, '.pbai4devs/state/derived.json');
+  rmSync(state, { force: true }); rmSync(derived, { force: true }); // Só cópias criadas nesta fixture.
+  if (withState) {
+    mkdirSync(dirname(state), { recursive: true });
+    writeFileSync(state, JSON.stringify({ schemaVersion: 1, version: '0.0.24', language: 'pt', clients: ['codex'], files: {}, blocks: {} }) + '\n');
+  }
+  const originals = {};
+  for (const name of ['catalog.json', 'skills.json', 'agents.json', 'rules.json']) {
+    const file = join(sourceRoot, '.pbai4devs', name), content = `{ "arquivo humano": ${JSON.stringify(name)} }\n`;
+    writeFileSync(file, content); originals[name] = content;
+  }
+  for (const path of ['.pbai4devs/.gitignore', '.codex/.gitignore']) {
+    const file = join(sourceRoot, path);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, '# BEGIN AGENT IGNORE\n# Alteração humana dentro do bloco\n!/nao-apagar/\n# END AGENT IGNORE\n');
+  }
+  const skill = '.pbai4devs/skills/projeto/equipe-local/SKILL.md';
+  const skillFile = join(sourceRoot, skill);
+  mkdirSync(dirname(skillFile), { recursive: true });
+  writeFileSync(skillFile, '---\nname: equipe-local\ndescription: Conteúdo próprio.\n---\n\n# Equipe local\n');
+  const sourceIgnore = readFileSync(join(sourceRoot, '.gitignore'));
+  const sourceConfig = readFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf'));
+  const [example] = prepare({ sourceRoot, scenarios: [SCENARIOS[0]], initializeGit: false });
+  assert.equal(example.copied.catalogSnapshots.length, 4);
+  for (const [name, content] of Object.entries(originals)) {
+    assert.equal(readFileSync(join(sourceRoot, '.pbai4devs', name), 'utf8'), content);
+    assert.equal(readFileSync(join(example.root, '.agent-tests/testar-maturidade/original-catalogs', name), 'utf8'), content);
+    assert.doesNotMatch(readFileSync(join(example.root, '.pbai4devs', name), 'utf8'), /arquivo humano/);
+  }
+  for (const path of ['.pbai4devs/.gitignore', '.codex/.gitignore']) {
+    const original = readFileSync(join(sourceRoot, path));
+    const saved = example.copied.overriddenSnapshots.find(item => item.source === path);
+    assert.ok(saved, path);
+    assert.deepEqual(readFileSync(join(example.root, saved.snapshot)), original);
+    assert.match(original.toString('utf8'), /Alteração humana/);
+    assert.doesNotMatch(readFileSync(join(example.root, path), 'utf8'), /Alteração humana/);
+  }
+  assert.equal(readFileSync(join(example.root, skill), 'utf8'), readFileSync(skillFile, 'utf8'));
+  assert.deepEqual(readFileSync(join(sourceRoot, '.gitignore')), sourceIgnore);
+  assert.deepEqual(readFileSync(join(sourceRoot, '.pbai4devs/espelhos.conf')), sourceConfig);
+  const report = JSON.parse(readFileSync(join(dirname(example.root), 'REPORT.json'), 'utf8'));
+  assert.deepEqual(report.copies[0].catalogSnapshots, example.copied.catalogSnapshots);
+  assert.match(readFileSync(join(example.root, 'README.md'), 'utf8'), /não um teste no projeto original/);
+  assert.equal(existsSync(state), withState);
+});
+
+test('arquiva arquivos substituídos mesmo quando o cliente não está selecionado', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|plano\n');
+  const files = ['.vscode/settings.json', '.github/workflows/legacy.yml'];
+  for (const path of files) put(path, `Conteúdo de equipe: ${path}\r\n`);
+  const [example] = prepareExamples({ sourceRoot: root, scenarios: [SCENARIOS.find(item => item.id === 'legado')], initializeGit: false });
+  for (const path of files) {
+    const saved = example.copied.overriddenSnapshots.filter(item => item.source === path);
+    assert.equal(saved.length, 1, path);
+    assert.deepEqual(readFileSync(join(example.root, saved[0].snapshot)), readFileSync(join(root, path)));
+  }
+});
+
+test('arquivo de cliente não selecionado com ancestral simbólico é recusado', t => {
+  const { root, put } = fixture(t);
+  put('.pbai4devs/espelhos.conf', 'agente|.codex|plano\n');
+  const outside = mkdtempSync(join(root, 'outside-'));
+  writeFileSync(join(outside, 'settings.json'), 'Conteúdo externo.\n');
+  rmSync(join(root, '.vscode'), { recursive: true });
+  try { symlinkSync(outside, join(root, '.vscode'), 'dir'); }
+  catch (error) { if (['EPERM', 'EACCES', 'ENOTSUP'].includes(error.code)) { t.skip('Links simbólicos indisponíveis.'); return; } throw error; }
+  assert.throws(() => prepareExamples({ sourceRoot: root, scenarios: [SCENARIOS.find(item => item.id === 'legado')], initializeGit: false }), /link/i);
+  assert.equal(readFileSync(join(outside, 'settings.json'), 'utf8'), 'Conteúdo externo.\n');
+});
+
+test('arquivos da fonte substituídos por fixtures têm cópias byte a byte', t => {
+  const { root, put } = fixture(t);
+  const files = ['README.md', 'Makefile', '.dockerignore', '.env.example', '.pbai4devs/state/README.md', '.pbai4devs/state/configuracao/ESTADO.md', '.vscode/settings.json', '.github/workflows/legacy.yml'];
+  const contents = Object.fromEntries(files.map(file => [file, `Conteúdo humano sintético: ${file}\r\n`]));
+  for (const [file, content] of Object.entries(contents)) put(file, content);
+  const cases = [SCENARIOS.find(item => item.id === 'app-configurada'), SCENARIOS.find(item => item.id === 'legado')];
+  const examples = prepareExamples({ sourceRoot: root, scenarios: cases, initializeGit: false });
+  for (const example of examples) {
+    for (const { source, snapshot } of example.copied.overriddenSnapshots) {
+      assert.equal(readFileSync(join(example.root, snapshot), 'utf8'), contents[source], source);
+      assert.equal(readFileSync(join(root, source), 'utf8'), contents[source], source);
+    }
+    for (const path of ['README.md', 'Makefile', '.pbai4devs/state/README.md', '.pbai4devs/state/configuracao/ESTADO.md']) assert.ok(example.copied.overriddenSnapshots.some(item => item.source === path), path);
+    const expected = example.id === 'legado' ? ['.vscode/settings.json', '.github/workflows/legacy.yml'] : ['.dockerignore', '.env.example'];
+    for (const path of expected) assert.ok(example.copied.overriddenSnapshots.some(item => item.source === path), path);
+  }
+});
+
 test('saída não pode sobrepor recursos de origem nem escapar das áreas de teste', t => {
   const { root } = fixture(t);
   const original = readFileSync(join(root, '.pbai4devs/espelhos.conf'), 'utf8');

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,21 @@ 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
+  propriedade, inclusive ao usar `--force` ou sincronização direta.
+- Mantém o estado coerente quando a sincronização atualiza saídas gerenciadas.
+- Acrescenta testes de colisão, arquivos idênticos e preservação do índice Git.
+
 ## 0.0.23 — 2026-11-13
 
 - Corrige a resolução de destinos inexistentes diretamente sob a raiz.

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/docs/guides/troubleshooting.md

@@ -56,9 +56,10 @@ Compare cada `conflicts` com o que deseja manter. Edite a origem em
 recurso. Use `sync` para atualizar suas derivações. `update` reaplica os
 recursos do pacote invocado e pode conflitar com essa personalização.
 
-Quando a substituição for intencional, repita com `--force`. Arquivos
-existentes afetados recebem backup antes da escrita, inclusive em operações
-normais. O campo `backup` informa uma pasta relativa ao projeto:
+`--force` não substitui arquivos próprios nem blocos alterados. Resolva o
+conflito preservando o conteúdo que deseja manter e confira novamente o plano.
+Arquivos gerenciados afetados recebem backup antes da escrita, inclusive em
+operações normais. O campo `backup` informa uma pasta relativa ao projeto:
 
 ```text
 .agent-tests/agentdevkit/backups/<identificador>/
@@ -105,9 +106,10 @@ ou caminhos já gerenciados em links.
 Destinos dentro de `.git`, `node_modules` ou `.pbai4devs` são recusados,
 inclusive com variações de maiúsculas/minúsculas.
 
-Na CLI e no script `sincronizar-agentes`, `--force` repara conflitos gerenciados
-com backup. Recursos nativos humanos e links preservados continuam intactos.
-Para manter a instalação e sua seleção de clientes, prefira a CLI.
+No script `sincronizar-agentes`, `--force` repara conflitos gerenciados com
+backup. A CLI bloqueia conflitos de propriedade mesmo com `--force`. Recursos
+nativos humanos e links preservados continuam intactos. Para manter a instalação
+e sua seleção de clientes, prefira a CLI.
 
 ## Download, plataforma ou ferramenta falhando
 

package/package.json

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

package/src/i18n.mjs

@@ -12,7 +12,7 @@ const messages = {
     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.',
-    next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano; --force salva backup antes de substituir.',
+    next: 'Próximo passo', init: 'Estrutura instalada.', update: 'Estrutura atualizada.', sync: 'Apontamentos sincronizados.', lang: 'Idioma configurado.', unchanged: 'Estrutura já atualizada.', plan: 'Plano calculado; nenhum arquivo alterado.', conflict: 'Há arquivos próprios ou alterados em conflito. Revise o plano e resolva os conflitos; --force não substitui conteúdo próprio.',
     healthy: 'Estrutura verificada.', unhealthy: 'A estrutura precisa de ajustes.', missing: 'AgentDevKit ainda não foi inicializado neste diretório.', error: 'Não foi possível concluir a operação.', invalid: 'Argumentos inválidos.', language: 'Idioma atual', version: 'Versão', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Projeto', readme: 'AgentDevKit instalado. Leia AGENTS.md e siga as etapas de produto, design e implementação.', state: 'Estado local do AgentDevKit e configuração compartilhada do projeto.',
     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',
@@ -23,7 +23,7 @@ const messages = {
     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.',
-    next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review it; --force backs them up before replacement.',
+    next: 'Next step', init: 'Structure installed.', update: 'Structure updated.', sync: 'Pointers synchronized.', lang: 'Language configured.', unchanged: 'Structure is already current.', plan: 'Plan calculated; no files changed.', conflict: 'User files or edits conflict with this plan. Review and resolve the conflicts; --force does not replace user content.',
     healthy: 'Structure verified.', unhealthy: 'The structure needs attention.', missing: 'AgentDevKit has not been initialized in this directory.', error: 'The operation could not be completed.', invalid: 'Invalid arguments.', language: 'Current language', version: 'Version', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Project', readme: 'AgentDevKit installed. Read AGENTS.md and follow the product, design and implementation stages.', state: 'AgentDevKit state and shared project configuration.',
     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',
@@ -34,7 +34,7 @@ const messages = {
     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.',
-    next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise el plan; --force guarda una copia antes de reemplazarlos.',
+    next: 'Próximo paso', init: 'Estructura instalada.', update: 'Estructura actualizada.', sync: 'Referencias sincronizadas.', lang: 'Idioma configurado.', unchanged: 'La estructura ya está actualizada.', plan: 'Plan calculado; ningún archivo modificado.', conflict: 'Hay archivos propios o cambios en conflicto. Revise y resuelva los conflictos; --force no reemplaza contenido propio.',
     healthy: 'Estructura verificada.', unhealthy: 'La estructura necesita ajustes.', missing: 'AgentDevKit no se ha inicializado en este directorio.', error: 'No se pudo completar la operación.', invalid: 'Argumentos inválidos.', language: 'Idioma actual', version: 'Versión', select: 'Idioma / Language / Idioma [pt/en/es] (pt): ',
     project: 'Proyecto', readme: 'AgentDevKit instalado. Lea AGENTS.md y siga las etapas de producto, diseño e implementación.', state: 'Estado de AgentDevKit y configuración compartida del proyecto.',
     agentLanguage: 'Responde en español salvo que el usuario solicite otro idioma.', inspect: 'Compruebe la instalación', workflow: 'Consulte la siguiente etapa', install: 'Inicialice este proyecto', repair: 'Compruebe la sincronización', review: 'Revise los archivos en conflicto', tools: 'Resultado de la herramienta',

package/src/install.mjs

@@ -457,7 +457,14 @@ function replaceJsonMember(bytes, member, value) {
     fail('E_STATE', 'Invalid JSON member separator.');
   }
   const matches = properties.filter(item => item.key === member);
-  if (matches.length !== 1) fail('E_STATE', 'Ambiguous derived state member.');
+  if (matches.length > 1) fail('E_STATE', 'Ambiguous state member.');
+  if (!matches.length) {
+    if (value === undefined) return bytes;
+    const insertion = `${properties.length ? ',' : ''}\n  ${JSON.stringify(member)}: ${JSON.stringify(value, null, 2)}\n`;
+    const next = text.slice(0, i) + insertion + text.slice(i);
+    try { JSON.parse(next); } catch { fail('E_STATE', 'Unable to preserve state safely.'); }
+    return Buffer.from(next);
+  }
   const current = matches[0], index = properties.indexOf(current);
   let next;
   if (value !== undefined) next = text.slice(0, current.valueStart) + JSON.stringify(value, null, 2) + text.slice(current.end);
@@ -468,29 +475,44 @@ function replaceJsonMember(bytes, member, value) {
   return Buffer.from(next);
 }
 
+function reconcileStateBytes(original, previous, next) {
+  if (!original) return Buffer.from(`${JSON.stringify(next, null, 2)}\n`);
+  const canonical = value => value && typeof value === 'object' && !Array.isArray(value)
+    ? Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]))
+    : Array.isArray(value) ? value.map(canonical) : value;
+  let result = original;
+  for (const key of ['schemaVersion', 'version', 'language', 'clients', 'files', 'blocks']) {
+    if (JSON.stringify(canonical(previous?.[key])) !== JSON.stringify(canonical(next[key]))) result = replaceJsonMember(result, key, next[key]);
+  }
+  return result;
+}
+
 function readDerivedState(target) {
-  let entries = {}, outputs = {}, blocks = {}, files = {}, removedBlocks = [], removedFiles = {};
+  let entries = {}, outputs = {}, blocks = {}, files = {}, catalogs = {}, config = null, removedBlocks = [], removedFiles = {};
   const derived = read(target, actualStatePath(target).replace(/agentdevkit\.json$/, 'derived.json'));
   if (derived) {
     try {
       const value = JSON.parse(derived);
       if (value.schemaVersion !== 1 || !value.entries || typeof value.entries !== 'object' || Array.isArray(value.entries)
-        || ['outputs', 'blocks', 'files', 'removedFiles'].some(key => value[key] !== undefined && (!value[key] || typeof value[key] !== 'object' || Array.isArray(value[key])))) fail('E_STATE', 'Invalid derived entrypoint state.');
-      entries = value.entries; outputs = value.outputs ?? {}; blocks = value.blocks ?? {}; files = value.files ?? {}; removedFiles = value.removedFiles ?? {};
+        || ['outputs', 'blocks', 'files', 'catalogs', 'removedFiles'].some(key => value[key] !== undefined && (!value[key] || typeof value[key] !== 'object' || Array.isArray(value[key])))) fail('E_STATE', 'Invalid derived entrypoint state.');
+      entries = value.entries; outputs = value.outputs ?? {}; blocks = value.blocks ?? {}; files = value.files ?? {}; catalogs = value.catalogs ?? {}; removedFiles = value.removedFiles ?? {};
+      if (value.config !== undefined && (typeof value.config !== 'string' || !/^[a-f0-9]{64}$/.test(value.config))) fail('E_STATE', 'Invalid derived configuration state.');
+      config = value.config ?? null;
       removedBlocks = value.removedBlocks ?? [];
       if (!Array.isArray(removedBlocks) || removedBlocks.some(path => typeof path !== 'string' || !nativeManagedText(path))) fail('E_STATE', 'Invalid removed block state.');
       for (const [path, digest] of Object.entries(entries)) if (!canonicalEntrypoint(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived entrypoint state.');
       for (const [path, digest] of Object.entries(outputs)) if (!allowedManaged(path) || !/^\.[^/]+\/(?:skills|agents|rules)\.json$/.test(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived output state.');
-      for (const [path, digest] of Object.entries(blocks)) if (!(nativeManagedText(path) || adapterRoots.some(root => path === `${root}/.gitignore`)) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived block state.');
+      for (const [path, digest] of Object.entries(blocks)) if (!(nativeManagedText(path) || path === '.pbai4devs/.gitignore' || adapterRoots.some(root => path === `${root}/.gitignore`)) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived block state.');
       for (const [path, digest] of Object.entries(files)) if (!allowedManaged(path) || !/\.(?:md|mdc|toml)$/.test(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived file state.');
+      for (const [path, digest] of Object.entries(catalogs)) if (!/^\.pbai4devs\/(?:catalog|skills|agents|rules)\.json$/.test(path) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid derived catalogue state.');
       for (const [path, digest] of Object.entries(removedFiles)) if (canonicalEntrypoint(path) || !(nativeMarkdown(path) || nativeToml(path)) || !/^[a-f0-9]{64}$/.test(digest)) fail('E_STATE', 'Invalid removed file state.');
       const installed = loadState(target);
       if (Object.entries(removedFiles).some(([path, digest]) => installed?.files?.[path] && installed.files[path] !== digest)) fail('E_STATE', 'Removed file state differs from installation.');
     }
     catch { fail('E_STATE', 'Invalid derived entrypoint state.'); }
-    for (const path of [...Object.keys(entries), ...Object.keys(outputs), ...Object.keys(blocks), ...Object.keys(files), ...Object.keys(removedFiles), ...removedBlocks]) safePath(target, path);
+    for (const path of [...Object.keys(entries), ...Object.keys(outputs), ...Object.keys(blocks), ...Object.keys(files), ...Object.keys(catalogs), ...Object.keys(removedFiles), ...removedBlocks]) safePath(target, path);
   }
-  return { entries, outputs, blocks, files, removedBlocks, removedFiles };
+  return { entries, outputs, blocks, files, catalogs, config, removedBlocks, removedFiles };
 }
 
 export function planInstallation({ target, language = 'pt', mode = 'init', force = false, clients }) {
@@ -511,11 +533,12 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
       if (original === null ? content !== null : !content?.equals(original)) fail('E_CHANGED', `File changed while planning: ${path}`);
     } else nativeInputs.set(path, content);
   };
-  const { entries: derivedEntries, outputs: derivedOutputs, blocks: derivedBlocks, files: derivedFiles, removedBlocks, removedFiles } = readDerivedState(target);
+  const { entries: derivedEntries, outputs: derivedOutputs, blocks: derivedBlocks, files: derivedFiles, catalogs: derivedCatalogs, config: derivedConfig, removedBlocks, removedFiles } = readDerivedState(target);
+  const derivedConfigFiles = derivedConfig ? { '.pbai4devs/espelhos.conf': derivedConfig } : {};
   if (previous) previous = { ...previous, files: Object.fromEntries(Object.entries(previous.files).filter(([path, digest]) => removedFiles[path] !== digest)) };
   const previousBlocks = Object.fromEntries(Object.entries(previous?.blocks || {}).filter(([path]) => !removedBlocks.includes(path)));
   const knownBlocks = { ...previousBlocks, ...derivedBlocks };
-  const ownedPaths = [...Object.keys(previous?.files || {}), ...Object.keys(previousBlocks), ...Object.keys(derivedEntries), ...Object.keys(derivedOutputs), ...Object.keys(derivedBlocks), ...Object.keys(derivedFiles)];
+  const ownedPaths = [...Object.keys(previous?.files || {}), ...Object.keys(previousBlocks), ...Object.keys(derivedEntries), ...Object.keys(derivedOutputs), ...Object.keys(derivedBlocks), ...Object.keys(derivedFiles), ...Object.keys(derivedCatalogs), ...Object.keys(derivedConfigFiles)];
   const entryPaths = new Map(entryNames.map(name => [name, resolveEntrypoint(target, name)]));
   const blockHash = path => knownBlocks[path]
     ?? (canonicalEntrypoint(path) ? Object.entries(knownBlocks).find(([candidate]) => canonicalEntrypoint(candidate) === canonicalEntrypoint(path))?.[1] : undefined);
@@ -597,7 +620,17 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const ownIgnore = read(target, '.pbai4devs/.gitignore');
     if (ownIgnore) write(stage, '.pbai4devs/.gitignore', ownIgnore);
     writeAdapterManifest(stage, { clients: selected });
-    const synchronized = synchronize({ root: stage, force: true, localIgnores: false, generateEntrypoints: false, recordDerivedState: false, outputBlocked, output() {} });
+    // Supply the already-validated ownership records to the private stage so
+    // the synchronizer can distinguish an owned ignore block from a user's.
+    // These temporary records never replace or bypass checks on the target.
+    const stagingState = '.pbai4devs/state/agentdevkit.json', stagingDerived = '.pbai4devs/state/derived.json';
+    if (previous) write(stage, stagingState, JSON.stringify(previous));
+    if (Object.keys(derivedEntries).length || Object.keys(derivedOutputs).length || Object.keys(derivedBlocks).length || Object.keys(derivedFiles).length || Object.keys(derivedCatalogs).length || derivedConfig || removedBlocks.length || Object.keys(removedFiles).length) {
+      write(stage, stagingDerived, JSON.stringify({ schemaVersion: 1, entries: derivedEntries, outputs: derivedOutputs, blocks: derivedBlocks, files: derivedFiles, catalogs: derivedCatalogs, ...(derivedConfig ? { config: derivedConfig } : {}), removedBlocks, removedFiles }));
+    }
+    let synchronized;
+    try { synchronized = synchronize({ root: stage, force: true, localIgnores: false, generateEntrypoints: false, recordDerivedState: false, outputBlocked, output() {} }); }
+    finally { rmSync(join(stage, stagingState), { force: true }); rmSync(join(stage, stagingDerived), { force: true }); }
     for (const canonical of active.entrypoints) {
       const name = entryPaths.get(canonical);
       if (preserveNative(name)) continue;
@@ -673,14 +706,14 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     // A standalone sync records its proven outputs separately. During a later
     // check/sync, compare that overlay before declaring the installation state
     // stale; update still consolidates it into the main state transactionally.
-    let stateContent = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+    let stateContent = reconcileStateBytes(installedState ? read(target, actualStatePath(target)) : null, installedState, manifest);
     if (mode === 'sync' && installedState && !changingClients) {
       const files = { ...installedState.files }, blocks = { ...installedState.blocks };
       for (const [path, digest] of Object.entries(removedFiles)) {
         if (files[path] === digest && !stat(safePath(target, path))) delete files[path];
       }
       for (const path of removedBlocks) delete blocks[path];
-      for (const [path, digest] of Object.entries({ ...derivedFiles, ...derivedOutputs, ...derivedEntries })) { files[path] = digest; delete blocks[path]; }
+      for (const [path, digest] of Object.entries({ ...derivedFiles, ...derivedOutputs, ...derivedEntries, ...derivedCatalogs, ...derivedConfigFiles })) { files[path] = digest; delete blocks[path]; }
       for (const [path, digest] of Object.entries(derivedBlocks)) { blocks[path] = digest; delete files[path]; }
       const same = (a, b) => {
         const keys = Object.keys(a).sort();
@@ -692,23 +725,70 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     desired.set(statePath, stateContent);
     const derivedPath = actualStatePath(target).replace(/agentdevkit\.json$/, 'derived.json');
     const derivedBytes = !migration ? read(target, derivedPath) : null;
-    if (derivedBytes && Object.keys(removedFiles).length) {
+    let nextDerivedBytes = derivedBytes;
+    if (nextDerivedBytes && Object.keys(removedFiles).length) {
       const finalState = JSON.parse(stateContent);
       const remaining = Object.fromEntries(Object.entries(removedFiles).filter(([path, digest]) =>
         finalState.files[path] === digest && !stat(safePath(target, path))));
       if (Object.keys(remaining).length !== Object.keys(removedFiles).length) {
         observeNative(derivedPath, derivedBytes);
-        desired.set(derivedPath, replaceJsonMember(derivedBytes, 'removedFiles', Object.keys(remaining).length ? remaining : undefined));
+        nextDerivedBytes = replaceJsonMember(nextDerivedBytes, 'removedFiles', Object.keys(remaining).length ? remaining : undefined);
       }
     }
+    if (nextDerivedBytes && Object.keys(derivedCatalogs).length) {
+      const finalState = JSON.parse(stateContent);
+      const remaining = Object.fromEntries(Object.entries(derivedCatalogs).filter(([path]) => {
+        const content = desired.get(path);
+        return !content || finalState.files[path] !== hash(content);
+      }));
+      if (Object.keys(remaining).length !== Object.keys(derivedCatalogs).length) {
+        observeNative(derivedPath, derivedBytes);
+        nextDerivedBytes = replaceJsonMember(nextDerivedBytes, 'catalogs', Object.keys(remaining).length ? remaining : undefined);
+      }
+    }
+    if (nextDerivedBytes && Object.keys(derivedBlocks).length) {
+      const finalState = JSON.parse(stateContent);
+      const remaining = Object.fromEntries(Object.entries(derivedBlocks).filter(([path, digest]) => {
+        const content = desired.get(path);
+        // A deselected generated block is removed later in this transaction.
+        // Drop its overlay only if its current bytes are still proven; edited
+        // blocks remain conflicts and no metadata is committed on failure.
+        if (!content && !canonicalEntrypoint(path) && !finalState.blocks[path] && !finalState.files[path]) {
+          const current = read(target, path);
+          return Boolean(current && blockDigest(path, current) !== digest);
+        }
+        return !content || finalState.blocks[path] !== blockDigest(path, content);
+      }));
+      if (Object.keys(remaining).length !== Object.keys(derivedBlocks).length) {
+        observeNative(derivedPath, derivedBytes);
+        nextDerivedBytes = replaceJsonMember(nextDerivedBytes, 'blocks', Object.keys(remaining).length ? remaining : undefined);
+      }
+    }
+    if (nextDerivedBytes && derivedConfig) {
+      const finalState = JSON.parse(stateContent), path = '.pbai4devs/espelhos.conf', content = desired.get(path);
+      if (content && finalState.files[path] === hash(content)) {
+        observeNative(derivedPath, derivedBytes);
+        nextDerivedBytes = replaceJsonMember(nextDerivedBytes, 'config', undefined);
+      }
+    }
+    if (nextDerivedBytes && !nextDerivedBytes.equals(derivedBytes)) desired.set(derivedPath, nextDerivedBytes);
     const changes = [], conflicts = [];
     const aliasedEntrypoint = path => canonicalEntrypoint(path) && entryPaths.get(canonicalEntrypoint(path)) !== path;
+    const generatedInternal = new Set(['.pbai4devs/catalog.json', '.pbai4devs/skills.json', '.pbai4devs/agents.json', '.pbai4devs/rules.json', '.pbai4devs/espelhos.conf']);
     for (const [path, content] of desired) {
       const current = read(target, path);
       if (nativeInputs.has(path) && (nativeInputs.get(path) === null ? current !== null : !current?.equals(nativeInputs.get(path)))) fail('E_CHANGED', `File changed while planning: ${path}`);
-      if (current?.equals(content)) continue;
+      const wholeFileOwned = current && [previous?.files[path], derivedOutputs[path], derivedEntries[path], derivedFiles[path], derivedCatalogs[path], derivedConfigFiles[path]].some(digest => digest && digest === hash(current));
+      const existingBlock = current && (nativeManagedText(path) || canonicalEntrypoint(path) || path.endsWith('/.gitignore')) ? blockDigest(path, current) : null;
+      if (existingBlock && !wholeFileOwned && knownBlocks[path] !== existingBlock) conflicts.push(path);
+      if (current?.equals(content)) {
+        // Identical bytes do not prove ownership of a pre-existing catalogue.
+        // Refuse adoption: a later sync could otherwise overwrite user data.
+        if (!wholeFileOwned && (generatedInternal.has(path) || native(path) && !existingBlock && !mixedPaths.has(path) && !preserved.has(path))) conflicts.push(path);
+        continue;
+      }
       const managed = path === derivedPath && derivedBytes && current?.equals(derivedBytes)
-        || [previous?.files[path], derivedOutputs[path], derivedEntries[path], derivedFiles[path]].some(digest => digest && hash(current || '') === digest)
+        || [previous?.files[path], derivedOutputs[path], derivedEntries[path], derivedFiles[path], derivedCatalogs[path], derivedConfigFiles[path]].some(digest => digest && hash(current || '') === digest)
         || knownBlocks[path] && blockDigest(path, current || Buffer.alloc(0)) === knownBlocks[path];
       const appendBlock = mixedPaths.has(path) || canonicalEntrypoint(path) || path === '.gitignore' || path.endsWith('/.gitignore');
       const conflict = current && path !== statePath && !managed && !appendBlock;
@@ -828,7 +908,9 @@ export function planInstallation({ target, language = 'pt', mode = 'init', force
     const localIgnore = planLocalIgnore(target, { outputs: ownedOutputs, templateRoot: stage });
     const localIgnoreCheck = checkLocalIgnore(localIgnore, { replacedBlocks: replacedIgnoreBlocks(target, changes, previous) });
     conflicts.push(...(untrack?.conflicts || []), ...localIgnoreCheck.missing);
-    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: (!conflicts.length || force) && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck, migration, fallbackChecks: [...fallbackChecks], fallbackOwnedPaths: ownedPaths, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
+    // A conflict means ownership or the managed bytes could not be proven.
+    // Backups do not authorize replacing user content, even with --force.
+    return { target, language, mode, changes, conflicts: [...new Set(conflicts)].sort(), canApply: !conflicts.length && !untrack?.conflicts?.length && !localIgnoreCheck.missing.length, manifest, retiredRoots, ownedOutputs, untrack, localIgnore, localIgnoreCheck, migration, fallbackChecks: [...fallbackChecks], fallbackOwnedPaths: ownedPaths, preserved: [...preserved.values()].sort((a, b) => a.path.localeCompare(b.path)) };
   } finally { rmSync(stage, { recursive: true, force: true }); }
 }
 
@@ -1019,7 +1101,7 @@ export function inspect(target) {
       if (content) issues.push({ code: 'modified', path });
       continue;
     }
-    if (!content || hash(content) !== digest && hash(content) !== derived.outputs[path] && hash(content) !== derived.files[path] && hash(content) !== derived.entries[path]) issues.push({ code: content ? 'modified' : 'missing', path });
+    if (!content || hash(content) !== digest && hash(content) !== derived.outputs[path] && hash(content) !== derived.files[path] && hash(content) !== derived.entries[path] && hash(content) !== derived.catalogs[path] && !(path === '.pbai4devs/espelhos.conf' && hash(content) === derived.config)) issues.push({ code: content ? 'modified' : 'missing', path });
   }
   for (const [path, digest] of Object.entries({ ...state.blocks, ...derived.blocks })) {
     if (derived.removedBlocks.includes(path) && !Object.hasOwn(derived.blocks, path)) continue;