wendkeep 0.58.1 → 0.58.3

package/docs/pt-BR/commands/maintenance-and-diagnostics.md

@@ -0,0 +1,77 @@
+# Manutenção e diagnóstico
+
+**PT-BR** · [English](../../en/commands/maintenance-and-diagnostics.md)
+
+## Objetivo
+
+Inspecionar a saúde do cofre e manter definições, tema e versão alinhados sem usar comandos de
+change como teste global.
+
+## Quando usar
+
+Use depois de instalar/atualizar, diante de warnings dos hooks ou antes de iniciar uma change.
+
+## Quando não usar
+
+Não use `wendkeep verify` quando nenhuma change estiver ativa. Ele prova tarefas de uma change;
+não substitui o doctor.
+
+## Pré-requisitos
+
+Execute na raiz do projeto ou informe `--project`/`--vault` explicitamente.
+
+## Sintaxe
+
+```bash
+npx wendkeep doctor [--vault <cofre>]
+npx wendkeep sync-defs [--check|--reseed] --vault <cofre> --project <raiz>
+npx wendkeep theme sync --vault <cofre>
+npx wendkeep --version
+npx wendkeep --help
+```
+
+## Opções e códigos de saída
+
+- `doctor` é read-only; exit `0` aceita warnings recuperáveis e exit não zero indica falha.
+- Em v2, `doctor`/`memory status --gate` correlacionam `last_memory_attempt` (mode, disposition,
+  event IDs e checkpoint) com outbox, ledger e SHARED; não inferem saúde só pela revision atual.
+- `revision: 0` após migração válida, sem attempt v2, é saudável. Attempt `degraded` cujos eventos
+  continuam duráveis na outbox/ledger é warning recuperável.
+- Attempt ambíguo, event ID perdido (ausente de ledger e outbox), estado `projected` apenas na
+  outbox ou checkpoint divergente são falhas bloqueantes.
+- `sync-defs --check` detecta drift sem gravar; `--reseed` restaura skills `wk-*` do pacote.
+- `theme sync` reaplica snippet CSS e grupos do grafo sem recriar o cofre.
+- `wendkeep --version` imprime a versão executada; `wendkeep --help` lista a interface pública.
+
+## Exemplos
+
+Checklist pós-atualização:
+
+```bash
+npx wendkeep --version
+npx wendkeep sync-defs --check --vault .MeuApp-vault --project .
+npx wendkeep doctor --vault .MeuApp-vault
+npx wendkeep memory status --gate --vault .MeuApp-vault
+```
+
+## Resultado esperado
+
+O doctor nomeia sessões, registry, links, notas, preços, derivadas e memória como saudáveis ou
+fornece um comando específico de diagnóstico/reparo. Na memória, ele distingue vazio inicial
+válido, replay pendente recuperável e lifecycle perdido/divergente. Nenhum reparo é aplicado
+implicitamente nem o conteúdo privado do erro do projector é reproduzido no relatório.
+
+## Erros comuns e diagnóstico
+
+- `no vault`: execute da raiz vinculada ou passe `--vault`.
+- `defs stale`: confirme a versão e rode `sync-defs --reseed`.
+- Vault legado: é warning não bloqueante; planeje `memory migrate --apply` separadamente.
+- `degraded` + outbox íntegra: warning; preserve a outbox e permita replay idempotente.
+- `ambiguous`, publicação perdida ou checkpoint divergente: bloqueante; preserve registry, ledger,
+  outbox e SHARED para correlacionar `last_memory_attempt` antes de reparar.
+- Bundle corrompido: preserve a evidência e use `memory status --gate` antes de `memory repair`.
+
+## Próximos passos
+
+Veja [instalação e primeiro uso](getting-started.md), [memória](memory.md) e
+[verificação de changes](verify.md).

package/docs/pt-BR/commands/memory-migration.md

@@ -0,0 +1,73 @@
+# Migração de memória legada para v2
+
+**PT-BR** · [English](../../en/commands/memory-migration.md)
+
+## Objetivo
+
+Converter um `SHARED_MEMORY.md` legado em bundle v2 auditável sem sobrescrever CORE nem promover
+relatos antigos silenciosamente.
+
+## Quando usar
+
+Use quando `memory status` retorna `legacy` e a equipe está pronta para curar o conteúdo convertido.
+
+## Quando não usar
+
+Não migre automaticamente durante `init`, `sync`, SessionStop ou como tentativa de silenciar um
+warning. Não aplique enquanto um backup/estado esperado não estiver claro.
+
+## Pré-requisitos
+
+- CORE válido e bytes legados preservados.
+- Vault sem corrupção v2 parcial.
+- Revisão humana dos candidates que serão criados.
+
+## Sintaxe
+
+```bash
+npx wendkeep memory status --gate --vault <cofre>
+npx wendkeep memory migrate --vault <cofre>
+npx wendkeep memory migrate --apply --vault <cofre>
+```
+
+## Opções e códigos de saída
+
+- Sem `--apply`, `wendkeep memory migrate` é dry-run e não grava.
+- `--apply` cria backup, converte conteúdo legado em candidates e publica bundle v2 válido.
+- Um bundle recém-migrado pode começar saudável em `revision: 0`: ainda não houve attempt v2 nem
+  evento elegível, portanto zero não significa estagnação.
+- Exit `0` indica prévia/aplicação consistente; exit diferente de zero preserva o estado original
+  e informa a falha.
+
+## Exemplos
+
+```bash
+npx wendkeep memory migrate --vault .MeuApp-vault
+# revise a prévia
+npx wendkeep memory migrate --apply --vault .MeuApp-vault
+npx wendkeep memory status --gate --vault .MeuApp-vault
+```
+
+## Resultado esperado
+
+O vault recebe ledger/projeção v2 coerentes, backup do SHARED legado e candidates para fatos sem
+evidência. CORE não é editado e conteúdo não verificado não vira estado ativo automaticamente.
+Após a migração, o próximo `UserPromptSubmit` recupera uma única activation se o registry legado
+estava fechado; o primeiro `Stop` cujo turno for comprovado publica uma vez e avança SHARED para
+revision 1. Repetir esse prompt ou Stop não duplica evento/revision.
+
+## Erros comuns e diagnóstico
+
+- Dry-run mostra vault já v2: não aplique novamente.
+- `revision: 0` imediatamente após apply válido: estado saudável; aguarde um prompt e Stop
+  elegíveis, não rode repair nem repita a migração.
+- Bundle v2 parcial/corrompido: use status e repair; migração não é ferramenta de corrupção.
+- Primeiro Stop pós-migração fica `ambiguous`: confirme que o `turn_id` pertence ao transcript e
+  que `UserPromptSubmit` abriu/avançou a activation de recuperação.
+- Candidates numerosos: curate gradualmente com `memory promote`/`memory reject`.
+- Warning legado após apply: confirme o vault efetivamente selecionado e o vínculo do projeto.
+
+## Próximos passos
+
+Volte para [memória e curadoria](memory.md) e execute
+[manutenção e diagnóstico](maintenance-and-diagnostics.md).

package/docs/pt-BR/commands/memory.md

@@ -0,0 +1,83 @@
+# Memória compartilhada e curadoria
+
+**PT-BR** · [English](../../en/commands/memory.md)
+
+## Objetivo
+
+Inspecionar e curar CORE, SHARED, ledger, outbox, attempts e candidates sem confundir autoria
+canônica com estado operacional gerado.
+
+## Quando usar
+
+Use no CI, antes de verify/archive, diante de avisos do doctor ou para decidir candidates.
+
+## Quando não usar
+
+Não edite `SHARED_MEMORY.md` ou `MEMORY_EVENTS.jsonl` à mão. Não use repair em vault legado que
+apenas aguarda migração.
+
+## Pré-requisitos
+
+Informe o vault explicitamente em automações. Preserve backups e evidências antes de reparar.
+
+## Sintaxe
+
+```bash
+npx wendkeep memory status [--gate] --vault <cofre>
+npx wendkeep memory repair --vault <cofre>
+npx wendkeep memory promote <candidate> --vault <cofre>
+npx wendkeep memory reject <candidate> --vault <cofre>
+npx wendkeep validate-memory [caminho-do-CORE]
+npx wendkeep validate-memory --vault <cofre-v2>
+```
+
+## Opções e códigos de saída
+
+- `memory status` é read-only; `--gate` retorna exit `1` apenas para estado bloqueante.
+- O `Stop` grava os eventos na outbox antes de reconhecer `last_memory_attempt: enqueued`; depois o
+  projector roda fora do lock do registry. Retry do mesmo attempt reutiliza os event IDs congelados
+  e pode projetá-los no máximo uma vez.
+- Projector busy/falho persiste `degraded`, preserva a outbox e avisa que há replay. Um Stop/retry
+  seguinte reaproveita essa tentativa; não reconstrói o handoff com dados transitórios novos.
+- O outcome só atualiza `memory_status`/checkpoint se activation, epoch, turno e attempt ainda forem
+  exatamente os mesmos. Resultado stale/superseded não apaga nem sobrescreve checkpoint mais novo.
+- Vault legado válido gera warning e exit `0`. Em v2, o status correlaciona
+  `last_memory_attempt`, disposition, outbox, ledger, SHARED e checkpoint: attempt ambíguo,
+  publicação perdida ou checkpoint divergente bloqueiam; `degraded` com outbox íntegra é warning.
+- `memory repair` trabalha sob lock, salva `.bak`, retém eventos válidos e reprojeta.
+- `promote`/`reject` acrescentam decisão auditável; nunca reescrevem o ledger no lugar.
+- `validate-memory <CORE.md>` valida cap de 25 linhas, seções e segredos.
+- `validate-memory --vault` exige bundle v2 completo; não é o gate correto para vault legado.
+
+## Exemplos
+
+```bash
+npx wendkeep memory status --gate --vault .MeuApp-vault
+npx wendkeep validate-memory .MeuApp-vault/.brain/CORE.md
+npx wendkeep memory promote candidate-123 --vault .MeuApp-vault
+```
+
+## Resultado esperado
+
+O status imprime schema, revision, cursor, hash, eventos, outbox, candidates, conflitos e o estado
+causal do último attempt. CORE permanece canônico e curado à mão; SHARED permanece projeção
+operacional verificável. Depois de uma projeção bem-sucedida, o checkpoint do attempt pode ser um
+prefixo válido de uma projeção global que já avançou com eventos concorrentes.
+
+## Erros comuns e diagnóstico
+
+- `legacy`: siga o guia de migração; não é corrupção.
+- `revision: 0` logo após migração válida, sem attempt v2, é saudável; não rode repair só para
+  fabricar o primeiro evento.
+- `degraded` com todos os event IDs presentes no ledger ou na outbox íntegra é recuperável; deixe o
+  replay idempotente concluir. Event ID ausente nos dois lugares indica publicação perdida.
+- Attempt `ambiguous`, attempt `applied` sem event IDs, evento `projected` apenas na outbox ou
+  checkpoint divergente são bloqueantes: preserve os artefatos e investigue antes de repair.
+- Candidate pendente comum: warning recuperável, exige decisão humana quando apropriado.
+- `event_cursor` ausente ou hash divergente em v2: preserve o bundle e avalie `memory repair`.
+- `validate-memory --vault` falha no legado: valide apenas CORE ou migre primeiro.
+
+## Próximos passos
+
+Leia [migração de memória](memory-migration.md), [manutenção](maintenance-and-diagnostics.md) e
+[verify](verify.md).

package/docs/pt-BR/commands/notes-and-knowledge.md

@@ -0,0 +1,69 @@
+# Notas derivadas e grafo de conhecimento
+
+**PT-BR** · [English](../../en/commands/notes-and-knowledge.md)
+
+## Objetivo
+
+Criar, reparar, numerar e navegar decisões, bugs e aprendizados mantendo proveniência e wikilinks.
+
+## Quando usar
+
+Use para registrar conhecimento durável ou reparar notas históricas diagnosticadas pelo doctor.
+
+## Quando não usar
+
+Não edite numeração e wikilinks em massa à mão. Não use `--apply` sem conferir a prévia.
+
+## Pré-requisitos
+
+Vault vinculado, sessão de origem identificável e backup antes de renumerações amplas.
+
+## Sintaxe
+
+```bash
+npx wendkeep dashboard [--force]
+npx wendkeep note new --type bug|learning "<título>"
+npx wendkeep note relink [--apply]
+npx wendkeep note repair-frontmatter [--apply]
+npx wendkeep note repair-sections [--apply]
+npx wendkeep renumber-decisions [--apply]
+npx wendkeep renumber-bugs [--apply]
+npx wendkeep renumber-learnings [--apply]
+npx wendkeep lesson add "<título>" "<lição>"
+```
+
+## Opções e códigos de saída
+
+- `note new` cria `BUG-NNNN` ou `APR-NNNN` no mês e aceita `--date`.
+- `note relink`, `repair-frontmatter`, `repair-sections` e `renumber-*` são dry-run por padrão;
+  `--apply` grava e `--json` facilita auditoria.
+- `dashboard --force` regenera Bases/MOC quando necessário.
+- `lesson add` aceita `--change <slug>` e `--vault` para ligar aprendizado local.
+- Exit `0` indica prévia/aplicação consistente; não zero deixa o reparo incompleto explícito.
+
+## Exemplos
+
+```bash
+npx wendkeep note new --type bug "refresh expira durante upload"
+npx wendkeep note relink --json
+npx wendkeep renumber-decisions --json
+# revise antes de repetir com --apply
+npx wendkeep dashboard --force
+```
+
+## Resultado esperado
+
+Notas derivadas vivem na pasta do mês, têm numeração global do tipo e backlink para a sessão. Os
+reparos preservam frontmatter válido e reescrevem wikilinks quando arquivos mudam.
+
+## Erros comuns e diagnóstico
+
+- Nota órfã sem fonte modal: `note relink` informa que não consegue inferir e não inventa vínculo.
+- Frontmatter empilhado: use repair sob o mesmo lock dos hooks.
+- Links cinza após renumber/archive: rode prévia de relink e confirme ambiguidades.
+- Título sensível: remova secrets/PII antes de persistir.
+
+## Próximos passos
+
+Veja [sessões e importação](sessions-and-import.md),
+[custos e observabilidade](costs-and-observability.md) e [manutenção](maintenance-and-diagnostics.md).

package/docs/pt-BR/commands/retroactive-import.md

@@ -0,0 +1,67 @@
+# Importação retroativa segura
+
+**PT-BR** · [English](../../en/commands/retroactive-import.md)
+
+## Objetivo
+
+Importar sessões históricas de Claude e Codex com escopo controlado, identidade estável e revisão
+antes da escrita.
+
+## Quando usar
+
+Use ao instalar o WendKeep num projeto existente, recuperar uma faixa de datas ou reprocessar
+decisões sem importar o mundo inteiro.
+
+## Quando não usar
+
+Não use `--source all` sem dry-run em máquinas com muitos projetos, forks ou rollouts de subagents.
+Não trate transcript importado como evidência de implementação atual.
+
+## Pré-requisitos
+
+Confirme projeto, vault, provider, diretório fonte e janela temporal. Faça backup se o registry já
+contiver reparos manuais.
+
+## Sintaxe
+
+```bash
+npx wendkeep import --dry-run --json
+npx wendkeep import --source claude|codex|all [--since <data>] [--limit <n>]
+npx wendkeep import --from <claude-dir> --codex-from <codex-dir>
+npx wendkeep import --stamp-ids | --rescan-decisions
+```
+
+## Opções e códigos de saída
+
+- `--source` limita provider; `--since` e `--limit` limitam volume.
+- `--from`/`--codex-from` substituem diretórios descobertos.
+- `--dry-run` não grava e `--json` produz relatório auditável.
+- `--stamp-ids` preenche IDs em notas existentes; `--rescan-decisions` reaplica extração de prosa.
+- Exit `0` indica varredura/importação consistente; exit diferente de zero exige resolver fonte,
+  parsing ou identidade antes de repetir.
+
+## Exemplos
+
+```bash
+npx wendkeep import --source codex --since 2026-07-20 --limit 20 --dry-run --json
+# confira accepted/skipped/forks
+npx wendkeep import --source codex --since 2026-07-20 --limit 20
+```
+
+## Resultado esperado
+
+Sessões aceitas entram uma vez por `session_id`, com provider e transcript corretos. Duplicatas
+canônicas são ignoradas; forks/subagents preservam relação de origem em vez de copiar toda a
+história herdada como uma nova conversa independente.
+
+## Erros comuns e diagnóstico
+
+- Contaminação entre projetos: pare e confira cwd, binding e filtros antes de limpar qualquer nota.
+- Fork comum importado como sessão cheia: inspecione `forked_from_id` e payload de origem.
+- Nota sem `session_id`: use `--stamp-ids` somente após dry-run.
+- Decisões faltantes em nota já importada: prefira `--rescan-decisions` a duplicar a sessão.
+
+## Próximos passos
+
+Volte para [sessões e hooks](sessions-and-import.md), gere [custos](costs-and-observability.md) e
+revise [notas derivadas](notes-and-knowledge.md).

package/docs/pt-BR/commands/sessions-and-import.md

@@ -0,0 +1,85 @@
+# Sessões, hooks e importação
+
+**PT-BR** · [English](../../en/commands/sessions-and-import.md)
+
+## Objetivo
+
+Entender como os hooks capturam sessões ao vivo, como activation/turno preservam causalidade no
+registry e quando usar a importação retroativa.
+
+## Quando usar
+
+Use `session` para inspecionar/focar uma conversa e `import` para recuperar sessões anteriores à
+instalação ou fora do registry atual.
+
+## Quando não usar
+
+Não invoque hooks manualmente sem o envelope JSON esperado. Não use import amplo antes de uma
+prévia quando existirem forks/subagents possivelmente duplicados.
+
+## Pré-requisitos
+
+Hooks instalados para captura ao vivo; para import, acesso local aos diretórios de transcripts do
+Claude/Codex e um vault vinculado ao projeto correto.
+
+## Sintaxe
+
+```bash
+npx wendkeep hook <nome>
+npx wendkeep session list
+npx wendkeep session show <id>
+npx wendkeep session use <id>
+npx wendkeep import [opções]
+```
+
+## Opções e códigos de saída
+
+- `wendkeep hook <name>` lê o payload do agente em stdin; nomes válidos aparecem em `--help`.
+- `SessionStart` abre uma activation, isto é, um epoch que continua ativo por vários `Stop`; só um
+  novo `SessionStart` torna o epoch anterior superseded.
+- `UserPromptSubmit` avança o turno nativo da activation ativa. Se encontrar um registry legado
+  com o epoch fechado, abre exatamente uma activation de recuperação; repetir o mesmo prompt não
+  abre outra.
+- No Codex, `session_id`, o `turn_id` nativo e a ordem observada no transcript bastam para resolver
+  o turno. O payload do hook não precisa inventar `activation_id` nem `turn_sequence`.
+- `Stop` aceita somente o turno comprovado pelo transcript e pela activation ativa compatível.
+  Duplicatas são no-op; Stops stale/superseded não publicam memória nem sobrescrevem o checkpoint
+  de um epoch mais novo.
+- `session list` lê `SESSION_REGISTRY`; `show` exibe uma sessão e `use` muda apenas o foco humano
+  em `CURRENT_SESSION.md`.
+- `import --source all|claude|codex`, `--since`, `--limit`, `--from` e `--codex-from` limitam escopo.
+- `--dry-run`/`--json` permitem auditar antes de gravar; `--stamp-ids` e `--rescan-decisions`
+  corrigem históricos específicos.
+- Exit `0` indica processamento consistente; exit não zero indica configuração, fonte ou escrita
+  inválida sem transformar isso em sucesso parcial silencioso.
+
+## Exemplos
+
+```bash
+npx wendkeep session list
+npx wendkeep session show 019abc-session-id
+npx wendkeep import --source codex --since 2026-07-01 --dry-run --json
+```
+
+## Resultado esperado
+
+Cada sessão canônica aponta para provider, transcript, arquivo de nota e custos correspondentes.
+O registry mantém um epoch de `SessionStart` por activation e o turno nativo mais recente; vários
+`Stop` podem confirmar turnos do mesmo epoch sem fechá-lo. Importações repetidas do mesmo
+`session_id` são deduplicadas; o foco humano não encerra nem altera a identidade dos hooks.
+
+## Erros comuns e diagnóstico
+
+- Sessão ausente: confira provider, path do transcript e registry antes de importar novamente.
+- `Stop ambiguous`: o `turn_id` não foi comprovado pelo transcript ou nenhuma activation ativa
+  compatível foi encontrada; o attempt fica observável, mas não publica memória.
+- Stop atrasado aparece como `stale_turn`/`superseded`: o epoch mais novo e seu checkpoint são
+  preservados; não force a reaplicação do payload antigo.
+- Duplicatas de forks: limite por fonte/data e revise `forked_from_id`/`source.subagent`.
+- Codex não captura: aprove os hooks e reinicie a sessão após `sync`.
+- Custo contaminado: valide `session_id → session_file → transcript_path → provider`.
+
+## Próximos passos
+
+Leia [importação retroativa](retroactive-import.md),
+[custos e observabilidade](costs-and-observability.md) e [notas](notes-and-knowledge.md).

package/docs/pt-BR/commands/verify.md

@@ -0,0 +1,87 @@
+# Verify e verificação independente
+
+**PT-BR** · [English](../../en/commands/verify.md)
+
+## Objetivo
+
+Executar os sensores exigidos pelas tarefas de uma change, persistir evidência fresca e montar o
+pacote autocontido usado pelo passe independente `wk-verify`.
+
+## Quando usar
+
+Use depois de implementar as tarefas e novamente sempre que tarefas, specs ou testes mudarem.
+
+## Quando não usar
+
+Não use como health check pós-instalação ou quando não existe change. Nesse caso, rode
+`wendkeep doctor` e `wendkeep memory status --gate`.
+
+## Pré-requisitos
+
+- Change aberta selecionada por `CURRENT_CHANGE.md` ou `--change <slug>`.
+- `tarefas.md` sem placeholders, com tags `[req:]` e `[sensor:]` na linha do checkbox.
+- Sensores declarados em `wendkeep.sensors.json`.
+
+## Sintaxe
+
+```bash
+npx wendkeep verify [--change <slug>] [--project <raiz>] [--vault <cofre>]
+npx wendkeep verify --deep [--change <slug>]
+npx wendkeep change use <slug>
+```
+
+## Opções e códigos de saída
+
+- `--change <slug>` mira uma change sem alterar o ponteiro ativo.
+- `change use <slug>` troca o foco persistido para comandos seguintes.
+- `--project <raiz>` define onde os sensores executam; `--vault` define onde a prova é gravada.
+- **Exit 0:** todos os sensores exigidos passaram e a evidência foi gravada.
+- **Exit 1:** o gate executou, mas ao menos um sensor crítico ficou vermelho ou um mutante
+  sobreviveu.
+- **Exit 2:** uso/contexto inválido, como `no change (--change or active)`, vault ausente,
+  change inexistente ou `wendkeep.sensors.json` inválido.
+
+`verify --deep` gera `verificacao.json`; ele não substitui o verificador. A skill `wk-verify`
+precisa ser executada por autor diferente e grava `verdict.json`.
+
+## Exemplos
+
+Change ativa:
+
+```bash
+npx wendkeep verify
+npx wendkeep verify --deep
+```
+
+Change explícita:
+
+```bash
+npx wendkeep verify --change tenant-login
+npx wendkeep verify --deep --change tenant-login
+```
+
+Projeto sem change aberta:
+
+```bash
+npx wendkeep doctor --vault .MeuApp-vault
+npx wendkeep memory status --gate --vault .MeuApp-vault
+```
+
+## Resultado esperado
+
+`evidencia.json` contém resultados dos sensores e um selo liga a prova ao hash atual de
+`tarefas.md`. No deep, o pacote contém requisitos, tarefas e evidência suficientes para revisão
+read-only; o verdict cobre cada `[req:]` antes do archive.
+
+## Erros comuns e diagnóstico
+
+- `no change`: isso é exit 2 e estado ocioso válido; crie/use uma change ou não rode verify.
+- Zero sensores: confira tags na mesma linha e `sensors list`.
+- Gate vermelho: corrija a causa e repita; não use `archive --force` por conta própria.
+- Verdict stale/ausente: regenere `--deep` e peça novo passe independente.
+- Mutantes sobreviventes: fortaleça o teste discriminante; após três rodadas, revise manualmente.
+
+## Próximos passos
+
+Volte ao [ciclo de changes](changes-and-verification.md) para archive ou consulte
+[manutenção](maintenance-and-diagnostics.md) quando não houver change.