@pathbit/agentdevkit 0.0.16 → 0.0.18

package/.pbai4devs/skills/projeto/sincronizar-agentes/SKILL.md

@@ -28,7 +28,7 @@ Não apague raízes inteiras: workflows, configurações nativas e a origem fica
 fora da limpeza. `--check` só confere, sem corrigir nem criar backups.
 
 O manifesto `.pbai4devs/espelhos.conf` registra clientes e formatos nativos.
-Respeite a seleção salva em `estado/agentdevkit.json`; não reative clientes para
+Respeite a seleção salva em `state/agentdevkit.json`; não reative clientes para
 reparar apontamentos. Para alterá-la, use `agents` na CLI. Pastas compartilhadas
 continuam quando necessárias; arquivos próprios dos clientes são preservados
 pela CLI, inclusive ao reduzir a seleção.

package/.pbai4devs/skills/specs/criar-spec/SKILL.md

@@ -6,7 +6,7 @@ description: Cria uma spec de incremento, esclarecendo requisitos e dúvidas com
 # Criar spec
 
 Antes de escrever, aplique o inventário e plano de `atualizar-documentacao`.
-Leia os caminhos em `.pbai4devs/estado/configuracao/ESTADO.md`. Exija PRD/design
+Leia os caminhos em `.pbai4devs/state/configuracao/ESTADO.md`. Exija PRD/design
 aprovados e UX/UI aprovado ou não aplicável com justificativa aprovada.
 Confira evidências, atualidade e decisões essenciais ao incremento; se faltar
 algo, encaminhe à etapa correspondente antes de escrever a spec.

package/.pbai4devs/skills/specs/implementar-spec/SKILL.md

@@ -5,7 +5,7 @@ description: Planeja e implementa uma spec aprovada, acompanhando tarefas e crit
 
 # Implementar spec
 
-Leia `.pbai4devs/estado/configuracao/ESTADO.md`. Exija spec, PRD e design aprovados;
+Leia `.pbai4devs/state/configuracao/ESTADO.md`. Exija spec, PRD e design aprovados;
 UX/UI aprovado ou não aplicável com justificativa aprovada. Confira evidências,
 atualidade, decisões essenciais e vínculos com o roadmap; resolva pendências
 antes de implementar.

package/.pbai4devs/templates/entrypoints/AGENTS.md

@@ -15,5 +15,5 @@ cliente em `.pbai4devs/COMPATIBILIDADE.md`.
 
 Use o `README.md` do projeto para seu contexto. Os clientes escolhidos têm
 apontamentos; scripts, ferramentas e modelos permanecem na origem compartilhada.
-Respeite a seleção em `.pbai4devs/estado/agentdevkit.json`. Para alterá-la, use
+Respeite a seleção em `.pbai4devs/state/agentdevkit.json`. Para alterá-la, use
 `agents` na CLI; não deduza o agente ativo pelo aplicativo ou pelas pastas.

package/.pbai4devs/templates/gitignore/local.ignore

@@ -6,5 +6,7 @@
 /.pbai4devs/espelhos.conf
 /.pbai4devs/estado/agentdevkit.json
 /.pbai4devs/estado/derived.json
+/.pbai4devs/state/agentdevkit.json
+/.pbai4devs/state/derived.json
 {{ROOTS}}
 {{OUTPUTS}}

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

@@ -6,6 +6,8 @@
 /espelhos.conf
 /estado/agentdevkit.json
 /estado/derived.json
+/state/agentdevkit.json
+/state/derived.json
 
 # Downloads e launchers de ferramentas
 /tools/bin/

package/CHANGELOG.md

@@ -4,6 +4,17 @@ description: Alterações verificáveis por versão do AgentDevKit.
 
 # Changelog
 
+## 0.0.18 — 2026-11-13
+
+- Sincronização preserva recursos próprios, colisões e alterações humanas.
+- Limpeza de recursos obsoletos exige comprovação de propriedade.
+- Comandos e efeitos sobre arquivos, índice e backups documentados.
+
+## 0.0.17 — 2026-11-13
+
+- A pasta compartilhada de estado passa a se chamar `.pbai4devs/state`.
+- Instalações existentes migram os dados sem alterar o índice ou o ignore.
+
 ## 0.0.16 — 2026-11-13
 
 - Testes portáteis distribuídos entre jobs para Windows e macOS.

package/docs/guides/cli.md

@@ -22,17 +22,17 @@ atendido; lá os comandos de manutenção usam o pacote por `npx`.
 
 | Comando | Resultado |
 | --- | --- |
-| `init [pasta]` | Instala ou reaplica os recursos. |
-| `update` | Usa os recursos da versão do pacote executado. |
-| `sync` | Reconstrói as derivações da fonte do projeto. |
-| `sync --check` | Confere as derivações sem escrever. |
-| `doctor` | Diagnostica a instalação. |
-| `next` | Orienta a próxima etapa do projeto. |
+| `init [pasta]` | Instala o kit no projeto ou reaplica a instalação. |
+| `update` | Atualiza a fonte usando a versão do pacote executado. |
+| `sync` | Atualiza catálogos e apontamentos a partir da fonte local. |
+| `sync --check` | Confere sincronização sem alterar o projeto. |
+| `doctor` | Diagnostica o kit e indica divergências. |
+| `next` | Mostra a próxima etapa, sem iniciá-la. |
 | `lang [idioma]` | Consulta ou altera o idioma: pt, en ou es. |
-| `agents` | Consulta clientes disponíveis e seleção local. |
-| `agents codex,claude` | Altera a seleção local. |
-| `agents all` | Habilita todos os clientes. |
-| `tools <ação>` | Executa o gerenciador de ferramentas. |
+| `agents` | Mostra os clientes disponíveis e a seleção salva. |
+| `agents codex,claude` | Altera a seleção e os apontamentos necessários. |
+| `agents all` | Seleciona todos os clientes compatíveis. |
+| `tools <ação>` | Consulta, instala, atualiza ou executa ferramentas. |
 | `--help`, `--version` | Ajuda ou versão do pacote. |
 
 Sem comando, a CLI executa `init`, que pode criar arquivos. `language` é alias
@@ -48,16 +48,47 @@ de `lang`; `clients`, de `agents`. O idioma não traduz documentos existentes.
 | `--clients <lista>` | Alias de `--agents`. |
 | `--yes`, `-y` | Evita perguntas iniciais; não força conflitos. |
 | `--dry-run` | Exibe o plano sem aplicar alterações. |
-| `--force` | Substitui conflitos gerenciados, com backup. |
+| `--force` | Solicita reparos gerenciados permitidos, com backup. |
 | `--json` | Produz uma resposta JSON para automação. |
 
 O primeiro uso interativo reúne idioma e clientes. Sem interação, valem as
 opções explícitas, a escolha local salva e, por último, `all`. Confira os
 [IDs e dependências](../../.pbai4devs/COMPATIBILIDADE.md).
 
-`update` não procura automaticamente a próxima versão: execute o pacote
-da versão desejada. `sync` não atualiza a fonte distribuída.
-A seleção e os derivados são locais; o source compartilhado permanece no Git.
+`update` usa a versão executada; para escolher outra, fixe-a no nome do
+pacote. `sync` usa o que já está em `.pbai4devs`: ele não baixa outra versão.
+Ambos conciliam recursos e removem apontamentos obsoletos quando a propriedade
+do kit é comprovada. Recursos e configurações próprios permanecem no projeto.
+Diretórios antigos sem comprovação de propriedade podem permanecer vazios.
+Ao mudar a seleção, pastas compartilhadas continuam quando outro cliente
+precisa delas; arquivos adicionais da equipe devem ser preservados.
+
+Antes de aplicar em projeto existente, confira o plano e depois o diagnóstico:
+
+```console
+npx @pathbit/agentdevkit update --dry-run --json
+npx @pathbit/agentdevkit update
+npx @pathbit/agentdevkit doctor
+npx @pathbit/agentdevkit sync --check
+```
+
+Use `init --dry-run --json`, `sync --dry-run --json` ou
+`agents codex,claude --dry-run --json` para as outras operações. Examine
+`plan`, `conflicts`, `preserved`, `untrackedPaths` e `localIgnore` antes de
+aplicar. Conflitos sem solução interrompem a operação; não presuma que uma
+colisão de nomes torna um arquivo propriedade do kit.
+
+O sincronizador independente também pode ser executado pelo
+[script local](../../.pbai4devs/scripts/sincronizar-agentes/README.md). Seu
+`--check` apenas confere e `--force` é explícito na linha de comando. O
+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.
 
 ## Ferramentas
 
@@ -80,7 +111,7 @@ do separador. `--help` e `--version` do kit não exigem um projeto instalado.
 As respostas incluem `ok`, `command`, `version`, `language`, `target` e
 `next`. Conforme a operação, há seleção, plano, conflitos, backup e erros.
 Leia os campos estruturados, não dependa da tradução da mensagem.
-`preserved` lista caminhos nativos humanos mantidos pelo projeto, com o motivo.
+`preserved` lista caminhos mantidos pelo projeto e o motivo.
 Um complemento pode ser gerenciado por bloco sem tornar o arquivo propriedade
 do kit. Conteúdo humano não é substituído por `--force`.
 

package/docs/guides/installation.md

@@ -111,7 +111,7 @@ usar `git add`. No GitHub Packages, use o prefixo de registry da instalação.
 
 O bloco local também protege `.agent-tests`, `tmp`, `temp`, `.playwright*`
 e relatórios de testes, inclusive com letras maiúsculas e em subpastas.
-O conteúdo do `.gitignore` existente e os arquivos rastreados são preservados.
+O conteúdo do `.gitignore` existente na raiz é preservado.
 Uma exceção que reabra arquivo privado ou artefato é informada como conflito;
 o projeto decide como ajustar suas próprias regras.
 Negativas com curingas também podem ser recusadas preventivamente, mesmo antes
@@ -121,6 +121,9 @@ 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
@@ -133,13 +136,20 @@ continua válida; `agents` consulta e `agents codex,claude` altera a seleção.
 `agents all` habilita todos. As pastas compartilhadas permanecem quando
 necessárias para outro cliente, como `.agents` para Codex e Antigravity.
 
-Confira a simulação antes de atualizar um projeto existente. Arquivos
-gerenciados alterados geram conflito; use `--force` somente após revisar o
-backup e o conteúdo que será substituído. Preserve os dados locais, as
-configurações próprias e os commits do projeto.
+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.
 
-Entradas como `AGENTS.md`, `claude.md` e `GEMINI.md`, além de skills, agentes,
-comandos e regras existentes, recebem apenas um complemento do kit:
+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
+devem ser descartados para reconstruir apontamentos. Remoções automáticas
+ficam restritas a arquivos obsoletos cuja propriedade possa ser comprovada.
+`--force` não autoriza substituir conteúdo próprio; backups ficam em
+`.agent-tests/` e devem ser revisados quando houver reparo gerenciado.
+
+Em entradas como `AGENTS.md`, `claude.md` e `GEMINI.md`, e em recursos nativos
+compatíveis, o kit pode acrescentar apenas uma referência delimitada:
 
 ```markdown
 <!-- BEGIN AGENTDEVKIT -->
@@ -148,7 +158,9 @@ Leia e siga [origem](caminho/para/.pbai4devs/recurso.md).
 ```
 
 O texto e o frontmatter humanos permanecem; a referência usa o caminho real
-do recurso. Repetir a operação não duplica o bloco. Edite suas instruções fora
+do recurso. Um arquivo que não possa receber o bloco é preservado e informado,
+sem prometer a adição do apontamento. Repetir a operação não duplica o bloco.
+Edite suas instruções fora
 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.

package/docs/guides/troubleshooting.md

@@ -73,11 +73,19 @@ Os backups são locais e ignorados; não substituem o controle de versão.
 
 ## Estado ou apontamentos inconsistentes
 
+Se a instalação ainda usa `.pbai4devs/estado`, execute `agentdevkit update`
+para migrar os dados e atualizar os scripts juntos. Se `estado` e `state`
+coexistirem, compare e preserve as duas pastas antes de resolver o conflito;
+o kit não escolhe nem sobrescreve uma delas automaticamente.
+Se a configuração apontar para caminhos dentro da pasta antiga, atualize
+esses caminhos para `.pbai4devs/state` antes de tentar novamente. O kit não
+reescreve as decisões do projeto.
+
 `missing`, `modified` e `outdated` em `issues` indicam arquivo ausente,
 conteúdo alterado ou derivação pendente. Use `sync --check` para inspecionar;
 se as alterações da origem forem intencionais, execute `sync` e confira de novo.
 
-Se `.pbai4devs/estado/agentdevkit.json` estiver inválido, recupere um backup
+Se `.pbai4devs/state/agentdevkit.json` estiver inválido, recupere um backup
 local coerente com os arquivos correspondentes. O estado pessoal não é
 versionado. Não invente hashes nem apague o estado para ocultar conflitos;
 peça ao agente para comparar as fontes e planejar o reparo com `init`/`sync`.

package/docs/guides/workflow.md

@@ -56,7 +56,7 @@ Neste momento quero apenas preparar os agentes; não crie produto ou aplicação
 
 Quando o produto começar, combine os caminhos dos documentos no estado de
 configuração. Não presuma que todo projeto usa as mesmas pastas de documentos.
-O registro é `.pbai4devs/estado/configuracao/ESTADO.md`.
+O registro é `.pbai4devs/state/configuracao/ESTADO.md`.
 
 ## 3. Definir produto e experiência
 

package/docs/specs/README.md

@@ -20,6 +20,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [Ecossistema de desenvolvimento](development-ecosystem/SPEC.md):
   especialistas, colaboração e provas.
 - [Confiabilidade da pipeline](ci-resilience/SPEC.md): testes e releases.
+- [Pasta de estado](state-directory/SPEC.md): migração segura para `state`.
+- [Sincronização segura](safe-synchronization/SPEC.md): preservar recursos próprios.
 - [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.

package/docs/specs/safe-synchronization/SPEC.md

@@ -0,0 +1,21 @@
+---
+description: Sincronização segura com recursos e alterações próprios do projeto.
+---
+
+# Sincronização segura
+
+Projetos podem ter arquivos próprios e recursos adicionais aos do pacote.
+Os comandos devem preservar esse conteúdo ao instalar, atualizar e sincronizar.
+
+## Critérios de aceite
+
+- AC-001: Recursos humanos ou modificados no hub e nos clientes são
+  preservados, inclusive em colisões e com `--force`.
+- AC-002: A limpeza remove somente saídas obsoletas com propriedade comprovada;
+  pastas e arquivos adicionais da equipe não são removidos.
+- AC-003: Um conteúdo divergente preparado no índice não é descartado pela
+  sincronização; `.gitignore` da raiz e dados humanos são preservados.
+- AC-004: `init`, `update`, `sync`, consultas e opções estão documentados com
+  seus efeitos sobre arquivos, backups, seleção de clientes e Git.
+- AC-005: Testes exercitam instalações existentes, obsolescência, colisões,
+  execução repetida, Git e falhas; a CI contempla Linux, Windows e macOS.

package/docs/specs/state-directory/SPEC.md

@@ -0,0 +1,22 @@
+---
+description: Nome em inglês para a pasta de estado compartilhado.
+---
+
+# Pasta de estado
+
+A pasta de primeiro nível passa de `.pbai4devs/estado` para
+`.pbai4devs/state`. Ela contém estado de instalação e configuração, não
+memória de conversas. Os nomes internos permanecem iguais.
+
+## Critérios de aceite
+
+- AC-001: Instalações novas usam `state` e recursos, documentação, exclusões
+  e pacote apontam para ela, sem expor estado local no pacote ou no Git.
+- AC-002: A atualização de instalações antigas preserva seleção, idioma,
+  decisões, conteúdo humano e permissões; conflitos e links inseguros não
+  causam perda ou sobrescrita silenciosa.
+- AC-003: Simulação, repetição, falhas e recuperação preservam arquivos,
+  índice Git e `.gitignore` do projeto. Scripts independentes identificam
+  instalações antigas e novas de forma coerente.
+- AC-004: Testes locais, CI em Linux, Windows e macOS e revisão independente
+  verificam o comportamento e os limites da migração.

package/package.json

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

package/src/cli.mjs

@@ -2,7 +2,7 @@ import { existsSync } from 'node:fs';
 import { resolve, join } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
-import { packageInfo } from './config.mjs';
+import { packageInfo, statePath, legacyStatePath } from './config.mjs';
 import { text, normalizeLanguage, explainError } from './i18n.mjs';
 import { resolveTarget, loadState, planInstallation, applyPlan, inspect } from './install.mjs';
 import { getNextSteps } from './next.mjs';
@@ -169,7 +169,7 @@ export async function main(argv = process.argv.slice(2), context = {}) {
     }
     print(result, options, output); return exitCode;
   } catch (error) {
-    const result = { ok: false, command: options.command || 'help', version: packageInfo.version, language, clients, target, message: explainError(language, error.code), error: { code: error.code || 'E_OPERATION', detail: error.message }, next: getNextSteps({ command: 'error', language, target, installed: existsSync(join(target, '.pbai4devs/estado/agentdevkit.json')) }) };
+    const result = { ok: false, command: options.command || 'help', version: packageInfo.version, language, clients, target, message: explainError(language, error.code), error: { code: error.code || 'E_OPERATION', detail: error.message }, next: getNextSteps({ command: 'error', language, target, installed: existsSync(join(target, statePath)) || existsSync(join(target, legacyStatePath)) }) };
     if (!options.json) result.message += ` (${error.code || 'E_OPERATION'})`;
     print(result, options, output); return error.exitCode || 1;
   }

package/src/config.mjs

@@ -5,7 +5,8 @@ import { fileURLToPath } from 'node:url';
 export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 export const frameworkRoot = resolve(packageRoot, '.pbai4devs');
 export const packageInfo = JSON.parse(readFileSync(resolve(packageRoot, 'package.json'), 'utf8'));
-export const statePath = '.pbai4devs/estado/agentdevkit.json';
+export const statePath = '.pbai4devs/state/agentdevkit.json';
+export const legacyStatePath = '.pbai4devs/estado/agentdevkit.json';
 export const entryNames = ['AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
 export const begin = '<!-- BEGIN AGENTDEVKIT -->';
 export const end = '<!-- END AGENTDEVKIT -->';

package/src/i18n.mjs

@@ -42,6 +42,31 @@ const messages = {
 };
 export const text = (language, key) => messages[language || 'pt'][key] || key;
 export function explainError(language, code) {
+  if (code === 'E_STAGED') return {
+    pt: 'Há alterações preparadas diferentes dos arquivos locais; revise-as antes de atualizar.',
+    en: 'Staged changes differ from the working files; review them before updating.',
+    es: 'Hay cambios preparados distintos de los archivos locales; revíselos antes de actualizar.',
+  }[language || 'pt'];
+  if (code === 'E_GIT') return {
+    pt: 'Não foi possível verificar o índice Git com segurança; nenhum arquivo foi alterado.',
+    en: 'The Git index could not be checked safely; no files were changed.',
+    es: 'No se pudo verificar el índice Git de forma segura; no se modificaron archivos.',
+  }[language || 'pt'];
+  if (code === 'E_CONFIG_PARSE') return {
+    pt: 'Não foi possível analisar a configuração legada com segurança; revise o frontmatter e as aspas antes de executar update.',
+    en: 'The legacy configuration could not be safely parsed; review its frontmatter and quoted values before running update.',
+    es: 'No se pudo analizar la configuración anterior de forma segura; revise el frontmatter y las comillas antes de ejecutar update.',
+  }[language || 'pt'];
+  if (code === 'E_LEGACY_PATH') return {
+    pt: 'Ajuste os caminhos .pbai4devs/estado para .pbai4devs/state na configuração antes de executar update.',
+    en: 'Change .pbai4devs/estado paths to .pbai4devs/state in the configuration before running update.',
+    es: 'Cambie las rutas .pbai4devs/estado por .pbai4devs/state en la configuración antes de ejecutar update.',
+  }[language || 'pt'];
+  if (code === 'E_UPGRADE') return {
+    pt: 'Execute agentdevkit update antes de sincronizar ou alterar a configuração legada.',
+    en: 'Run agentdevkit update before syncing or changing the legacy configuration.',
+    es: 'Ejecute agentdevkit update antes de sincronizar o cambiar la configuración anterior.',
+  }[language || 'pt'];
   const value = {
     pt: { E_ARGS: 'Argumentos inválidos; consulte --help.', E_STATE: 'O estado do AgentDevKit está inválido.', E_SYMLINK: 'Um link simbólico impede a operação segura.', E_TARGET: 'Escolha uma pasta real e segura como destino.', E_PATH: 'Um caminho gerenciado é inválido.', E_BLOCK: 'Os marcadores do bloco gerenciado estão inválidos.', E_CHANGED: 'Um arquivo mudou depois do planejamento; execute novamente.', E_TEMPLATE: 'Um template necessário está inválido.' },
     en: { E_ARGS: 'Invalid arguments; see --help.', E_STATE: 'AgentDevKit state is invalid.', E_SYMLINK: 'A symbolic link prevents this operation.', E_TARGET: 'Choose a real, safe target directory.', E_PATH: 'A managed path is invalid.', E_BLOCK: 'Managed block markers are invalid.', E_CHANGED: 'A file changed after planning; try again.', E_TEMPLATE: 'A required template is invalid.' },