wendkeep 0.58.0 → 0.58.3

package/docs/en/commands/memory-migration.md

@@ -0,0 +1,73 @@
+# Legacy-to-v2 memory migration
+
+**English** · [Português](../../pt-BR/commands/memory-migration.md)
+
+## Purpose
+
+Convert a legacy `SHARED_MEMORY.md` into an auditable v2 bundle without overwriting CORE or
+silently promoting old reports.
+
+## When to use
+
+Use when `memory status` reports `legacy` and the team is ready to curate converted content.
+
+## When not to use
+
+Do not migrate automatically during `init`, `sync`, SessionStop, or merely to silence a warning.
+Do not apply until the backup and expected state are understood.
+
+## Prerequisites
+
+- Valid CORE and preserved legacy bytes.
+- No partially corrupt v2 bundle.
+- Human review of the candidates that will be created.
+
+## Syntax
+
+```bash
+npx wendkeep memory status --gate --vault <vault>
+npx wendkeep memory migrate --vault <vault>
+npx wendkeep memory migrate --apply --vault <vault>
+```
+
+## Options and exit codes
+
+- Without `--apply`, `wendkeep memory migrate` is a zero-write dry run.
+- `--apply` creates a backup, converts legacy content into candidates, and publishes valid v2.
+- A newly migrated bundle may start healthy at `revision: 0`: no v2 attempt or eligible event has
+  happened yet, so zero does not mean the lifecycle is stalled.
+- Exit `0` means a consistent preview/application; non-zero preserves original state and reports
+  the failure.
+
+## Examples
+
+```bash
+npx wendkeep memory migrate --vault .MyApp-vault
+# review the preview
+npx wendkeep memory migrate --apply --vault .MyApp-vault
+npx wendkeep memory status --gate --vault .MyApp-vault
+```
+
+## Expected result
+
+The vault receives a coherent v2 ledger/projection, a backup of legacy SHARED, and candidates for
+unsupported facts. CORE is untouched and unverified content is not activated automatically.
+After migration, the next `UserPromptSubmit` opens exactly one recovery activation when the
+legacy registry was closed; the first transcript-proven `Stop` publishes once and advances SHARED
+to revision 1. Replaying that prompt or Stop does not duplicate the event/revision.
+
+## Common errors and diagnosis
+
+- Dry run says already v2: do not apply again.
+- `revision: 0` immediately after a valid apply: this is healthy; wait for an eligible prompt and
+  Stop instead of repairing or repeating migration.
+- Partial/corrupt v2 bundle: use status and repair; migration is not a corruption tool.
+- First post-migration Stop is `ambiguous`: verify that its `turn_id` belongs to the transcript and
+  that `UserPromptSubmit` opened/advanced the recovery activation.
+- Many candidates: curate gradually with `memory promote`/`memory reject`.
+- Legacy warning remains after apply: verify the selected vault and project binding.
+
+## Next steps
+
+Return to [memory and curation](memory.md) and run
+[maintenance and diagnostics](maintenance-and-diagnostics.md).

package/docs/en/commands/memory.md

@@ -0,0 +1,84 @@
+# Shared memory and curation
+
+**English** · [Português](../../pt-BR/commands/memory.md)
+
+## Purpose
+
+Inspect and curate CORE, SHARED, ledger, outbox, attempts, and candidates without confusing
+canonical authorship with generated operational state.
+
+## When to use
+
+Use in CI, before verify/archive, after doctor warnings, or when deciding candidates.
+
+## When not to use
+
+Do not hand-edit `SHARED_MEMORY.md` or `MEMORY_EVENTS.jsonl`. Do not repair a healthy legacy vault
+that merely awaits migration.
+
+## Prerequisites
+
+Pass the vault explicitly in automation. Preserve backups and evidence before repair.
+
+## Syntax
+
+```bash
+npx wendkeep memory status [--gate] --vault <vault>
+npx wendkeep memory repair --vault <vault>
+npx wendkeep memory promote <candidate> --vault <vault>
+npx wendkeep memory reject <candidate> --vault <vault>
+npx wendkeep validate-memory [CORE-path]
+npx wendkeep validate-memory --vault <v2-vault>
+```
+
+## Options and exit codes
+
+- `memory status` is read-only; `--gate` exits `1` only for blocking state.
+- `Stop` writes events to the outbox before acknowledging `last_memory_attempt: enqueued`, then the
+  projector runs outside the registry lock. Retrying the same attempt reuses its frozen event IDs
+  and can project them at most once.
+- A busy/failed projector persists `degraded`, preserves the outbox, and reports replay. A later
+  Stop/retry reuses that attempt instead of rebuilding its handoff from new transient data.
+- The outcome updates `memory_status`/checkpoint only while activation, epoch, turn, and attempt
+  still match exactly. A stale/superseded result cannot clear or overwrite a newer checkpoint.
+- A valid legacy vault warns and exits `0`. For v2, status correlates `last_memory_attempt`,
+  disposition, outbox, ledger, SHARED, and checkpoint: an ambiguous attempt, lost publication, or
+  mismatched checkpoint blocks; `degraded` with an intact outbox is a warning.
+- `memory repair` locks, writes a `.bak`, retains valid events, and reprojects state.
+- `promote`/`reject` append auditable decisions and never rewrite the ledger in place.
+- `validate-memory <CORE.md>` checks the 25-line cap, required sections, and secrets.
+- `validate-memory --vault` requires a complete v2 bundle and is not the legacy-vault gate.
+
+## Examples
+
+```bash
+npx wendkeep memory status --gate --vault .MyApp-vault
+npx wendkeep validate-memory .MyApp-vault/.brain/CORE.md
+npx wendkeep memory promote candidate-123 --vault .MyApp-vault
+```
+
+## Expected result
+
+Status prints schema, revision, cursor, hash, events, outbox, candidates, conflicts, and the causal
+state of the last attempt. CORE stays hand-curated and canonical; SHARED stays a verifiable
+operational projection. After successful projection, an attempt checkpoint may be a valid prefix
+of a global projection that has already advanced with concurrent events.
+
+## Common errors and diagnosis
+
+- `legacy`: follow the migration guide; this is not corruption.
+- `revision: 0` immediately after a valid migration, with no v2 attempt, is healthy; do not run
+  repair merely to manufacture the first event.
+- `degraded` with every event ID present in either the ledger or an intact outbox is recoverable;
+  let idempotent replay finish. An event ID absent from both locations means lost publication.
+- An `ambiguous` attempt, an `applied` attempt without event IDs, a `projected` event found only in
+  the outbox, or a mismatched checkpoint is blocking: preserve the artifacts and investigate
+  before repair.
+- Ordinary pending candidate: recoverable warning, requiring human choice when appropriate.
+- Missing `event_cursor` or mismatched v2 hash: preserve the bundle and assess `memory repair`.
+- `validate-memory --vault` fails on legacy: validate CORE only or migrate first.
+
+## Next steps
+
+Read [memory migration](memory-migration.md), [maintenance](maintenance-and-diagnostics.md), and
+[verify](verify.md).

package/docs/en/commands/notes-and-knowledge.md

@@ -0,0 +1,70 @@
+# Derived notes and knowledge graph
+
+**English** · [Português](../../pt-BR/commands/notes-and-knowledge.md)
+
+## Purpose
+
+Create, repair, number, and navigate decisions, bugs, and learnings while preserving provenance
+and wikilinks.
+
+## When to use
+
+Use to record durable knowledge or repair historical notes diagnosed by doctor.
+
+## When not to use
+
+Do not hand-edit numbering or wikilinks in bulk. Do not use `--apply` before reviewing the preview.
+
+## Prerequisites
+
+A bound vault, identifiable source session, and backup before broad renumbering.
+
+## Syntax
+
+```bash
+npx wendkeep dashboard [--force]
+npx wendkeep note new --type bug|learning "<title>"
+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 "<title>" "<lesson>"
+```
+
+## Options and exit codes
+
+- `note new` creates a monthly `BUG-NNNN` or `APR-NNNN` and accepts `--date`.
+- `note relink`, `repair-frontmatter`, `repair-sections`, and `renumber-*` default to dry-run;
+  `--apply` writes and `--json` supports audit.
+- `dashboard --force` regenerates Bases/MOC when required.
+- `lesson add` accepts `--change <slug>` and `--vault` to bind local learning.
+- Exit `0` means a consistent preview/application; non-zero makes incomplete repair explicit.
+
+## Examples
+
+```bash
+npx wendkeep note new --type bug "refresh expires during upload"
+npx wendkeep note relink --json
+npx wendkeep renumber-decisions --json
+# review before repeating with --apply
+npx wendkeep dashboard --force
+```
+
+## Expected result
+
+Derived notes live in the month folder, use global per-type numbering, and link back to the source
+session. Repairs preserve valid frontmatter and rewrite wikilinks when files move.
+
+## Common errors and diagnosis
+
+- Orphan note without a modal source: `note relink` reports it and does not invent provenance.
+- Stacked frontmatter: repair under the same lock used by hooks.
+- Grey links after renumber/archive: preview relink and inspect ambiguities.
+- Sensitive title: remove secrets/PII before persistence.
+
+## Next steps
+
+See [sessions and import](sessions-and-import.md), [costs and observability](costs-and-observability.md),
+and [maintenance](maintenance-and-diagnostics.md).

package/docs/en/commands/retroactive-import.md

@@ -0,0 +1,67 @@
+# Safe retroactive import
+
+**English** · [Português](../../pt-BR/commands/retroactive-import.md)
+
+## Purpose
+
+Import historical Claude and Codex sessions with bounded scope, stable identity, and review before
+writes.
+
+## When to use
+
+Use when installing WendKeep in an existing project, recovering a date range, or rescanning
+decisions without importing every transcript on the machine.
+
+## When not to use
+
+Do not use `--source all` without dry-run on machines with many projects, forks, or subagent
+rollouts. Do not treat imported conversation history as current implementation evidence.
+
+## Prerequisites
+
+Confirm project, vault, provider, source directory, and date window. Back up the registry if it
+already contains manual repairs.
+
+## Syntax
+
+```bash
+npx wendkeep import --dry-run --json
+npx wendkeep import --source claude|codex|all [--since <date>] [--limit <n>]
+npx wendkeep import --from <claude-dir> --codex-from <codex-dir>
+npx wendkeep import --stamp-ids | --rescan-decisions
+```
+
+## Options and exit codes
+
+- `--source` bounds provider; `--since` and `--limit` bound volume.
+- `--from`/`--codex-from` override discovered directories.
+- `--dry-run` performs zero writes; `--json` emits an auditable report.
+- `--stamp-ids` fills IDs in existing notes; `--rescan-decisions` reruns prose extraction.
+- Exit `0` means a consistent scan/import; non-zero requires fixing source, parsing, or identity
+  before retrying.
+
+## Examples
+
+```bash
+npx wendkeep import --source codex --since 2026-07-20 --limit 20 --dry-run --json
+# inspect accepted/skipped/forks
+npx wendkeep import --source codex --since 2026-07-20 --limit 20
+```
+
+## Expected result
+
+Accepted sessions enter once per `session_id` with matching provider/transcript. Canonical
+duplicates are skipped; forks/subagents retain origin relationships instead of copying inherited
+history into another full independent conversation.
+
+## Common errors and diagnosis
+
+- Cross-project contamination: stop and verify cwd, binding, and filters before cleaning notes.
+- Ordinary fork imported as full session: inspect `forked_from_id` and source payload.
+- Note without `session_id`: use `--stamp-ids` only after dry-run.
+- Missing decisions in an imported note: prefer `--rescan-decisions` over duplicating the session.
+
+## Next steps
+
+Return to [sessions and hooks](sessions-and-import.md), generate [costs](costs-and-observability.md),
+and review [derived notes](notes-and-knowledge.md).

package/docs/en/commands/sessions-and-import.md

@@ -0,0 +1,85 @@
+# Sessions, hooks, and import
+
+**English** · [Português](../../pt-BR/commands/sessions-and-import.md)
+
+## Purpose
+
+Understand how hooks capture live sessions, how activation/turn state preserves causality in the
+registry, and when to use retroactive import.
+
+## When to use
+
+Use `session` to inspect/focus a conversation and `import` to recover sessions from before setup or
+outside the current registry.
+
+## When not to use
+
+Do not invoke hooks manually without their expected JSON envelope. Do not run broad imports before
+a preview when forks/subagents may duplicate history.
+
+## Prerequisites
+
+Installed hooks for live capture; for imports, local access to Claude/Codex transcript directories
+and a vault bound to the correct project.
+
+## Syntax
+
+```bash
+npx wendkeep hook <name>
+npx wendkeep session list
+npx wendkeep session show <id>
+npx wendkeep session use <id>
+npx wendkeep import [options]
+```
+
+## Options and exit codes
+
+- `wendkeep hook <name>` reads the agent payload from stdin; valid names are listed by `--help`.
+- `SessionStart` opens an activation: an epoch that remains active across multiple `Stop` events;
+  only a new `SessionStart` supersedes the previous epoch.
+- `UserPromptSubmit` advances the active activation's native turn. If it finds a legacy registry
+  with a closed epoch, it opens exactly one recovery activation; replaying the same prompt does
+  not open another one.
+- On Codex, `session_id`, the native `turn_id`, and observed transcript order are enough to resolve
+  the turn. Hook payloads do not need invented `activation_id` or `turn_sequence` fields.
+- `Stop` accepts only a transcript-proven turn from the compatible active activation. Duplicates
+  are no-ops; stale/superseded Stops neither publish memory nor overwrite a newer epoch's
+  checkpoint.
+- `session list` reads `SESSION_REGISTRY`; `show` displays one session and `use` only changes human
+  focus in `CURRENT_SESSION.md`.
+- `import --source all|claude|codex`, `--since`, `--limit`, `--from`, and `--codex-from` bound scope.
+- `--dry-run`/`--json` support audit before writes; `--stamp-ids` and `--rescan-decisions` address
+  specific historical gaps.
+- Exit `0` means consistent processing; non-zero reports invalid source/config/write instead of
+  presenting silent partial success.
+
+## Examples
+
+```bash
+npx wendkeep session list
+npx wendkeep session show 019abc-session-id
+npx wendkeep import --source codex --since 2026-07-01 --dry-run --json
+```
+
+## Expected result
+
+Each canonical session points to the matching provider, transcript, note file, and costs. The
+registry keeps one `SessionStart` epoch per activation plus the latest native turn; multiple
+`Stop` events may acknowledge turns in that epoch without closing it. Repeated imports of the
+same `session_id` deduplicate; human focus does not close or re-identify live hooks.
+
+## Common errors and diagnosis
+
+- Missing session: verify provider, transcript path, and registry before importing again.
+- `Stop ambiguous`: the transcript did not prove the `turn_id`, or no compatible active activation
+  was found; the attempt remains observable but does not publish memory.
+- A late Stop reports `stale_turn`/`superseded`: the newer epoch and checkpoint are preserved; do
+  not force the old payload to apply.
+- Fork duplicates: bound source/date and inspect `forked_from_id`/`source.subagent`.
+- Codex does not capture: approve hooks and start a new session after `sync`.
+- Contaminated cost: validate `session_id → session_file → transcript_path → provider`.
+
+## Next steps
+
+Read [retroactive import](retroactive-import.md), [costs and observability](costs-and-observability.md),
+and [notes](notes-and-knowledge.md).

package/docs/en/commands/verify.md

@@ -0,0 +1,86 @@
+# Verify and independent verification
+
+**English** · [Português](../../pt-BR/commands/verify.md)
+
+## Purpose
+
+Run the sensors required by a change's tasks, persist fresh evidence, and assemble the
+self-contained package consumed by the independent `wk-verify` pass.
+
+## When to use
+
+Run after implementing tasks and again whenever tasks, specs, or tests change.
+
+## When not to use
+
+Do not use it as a post-install health check or when no change exists. Run `wendkeep doctor` and
+`wendkeep memory status --gate` instead.
+
+## Prerequisites
+
+- An open change selected through `CURRENT_CHANGE.md` or `--change <slug>`.
+- A placeholder-free `tarefas.md` with `[req:]` and `[sensor:]` tags on checkbox lines.
+- Sensors declared in `wendkeep.sensors.json`.
+
+## Syntax
+
+```bash
+npx wendkeep verify [--change <slug>] [--project <root>] [--vault <vault>]
+npx wendkeep verify --deep [--change <slug>]
+npx wendkeep change use <slug>
+```
+
+## Options and exit codes
+
+- `--change <slug>` targets a change without changing the active pointer.
+- `change use <slug>` persists focus for following commands.
+- `--project <root>` selects the sensor cwd; `--vault` selects where proof is stored.
+- **Exit 0:** all required sensors passed and evidence was written.
+- **Exit 1:** the gate ran, but at least one critical sensor was red or a mutant survived.
+- **Exit 2:** invalid usage/context, including `no change (--change or active)`, missing vault,
+  unknown change, or invalid `wendkeep.sensors.json`.
+
+`verify --deep` writes `verificacao.json`; it does not replace the reviewer. The `wk-verify` skill
+must be run by a different author and writes `verdict.json`.
+
+## Examples
+
+Active change:
+
+```bash
+npx wendkeep verify
+npx wendkeep verify --deep
+```
+
+Explicit change:
+
+```bash
+npx wendkeep verify --change tenant-login
+npx wendkeep verify --deep --change tenant-login
+```
+
+Project with no open change:
+
+```bash
+npx wendkeep doctor --vault .MyApp-vault
+npx wendkeep memory status --gate --vault .MyApp-vault
+```
+
+## Expected result
+
+`evidencia.json` contains sensor results and a seal binds proof to the current `tarefas.md` hash.
+Deep mode packages requirements, tasks, and evidence for read-only review; the verdict covers every
+`[req:]` before archive.
+
+## Common errors and diagnosis
+
+- `no change`: this is exit 2 and a valid idle state; create/use a change or skip verify.
+- Zero sensors: inspect same-line tags and `sensors list`.
+- Red gate: fix the cause and rerun; never choose `archive --force` on your own.
+- Missing/stale verdict: regenerate `--deep` and request a fresh independent pass.
+- Surviving mutants: strengthen the discriminating test; after three rounds, review manually.
+
+## Next steps
+
+Return to the [change lifecycle](changes-and-verification.md) for archive, or use
+[maintenance](maintenance-and-diagnostics.md) when no change exists.

package/docs/pt-BR/commands/changes-and-verification.md

@@ -0,0 +1,80 @@
+# Changes, specs, sensores e archive
+
+**PT-BR** · [English](../../en/commands/changes-and-verification.md)
+
+## Objetivo
+
+Conduzir uma mudança desde a intenção registrada até uma decisão arquivada, ligando requisitos,
+tarefas, sensores, evidência e verdict no grafo do cofre.
+
+## Quando usar
+
+Use para qualquer implementação não trivial ou correção que precise deixar prova auditável.
+
+## Quando não usar
+
+Não crie uma change para consultar saúde, importar sessões ou executar manutenção read-only.
+
+## Pré-requisitos
+
+Tenha o projeto inicializado, um vault saudável e `wendkeep.sensors.json` válido na raiz.
+
+## Sintaxe
+
+```bash
+npx wendkeep change new <slug>
+npx wendkeep change status [slug]
+npx wendkeep spec effective --change <slug>
+npx wendkeep sensors list
+npx wendkeep verify [--deep] [--change <slug>]
+npx wendkeep change archive <slug>
+```
+
+## Opções e códigos de saída
+
+- `wendkeep change new <slug> [--simple]` cria proposta, design, tarefas e ponteiro ativo.
+- `change use`, `list`, `show`, `status`, `diff`, `done` e `undone` inspecionam ou atualizam o
+  trabalho sem arquivar.
+- `change continue <arquivada> <nova>` abre continuação sem herdar evidência antiga.
+- `change bind <slug> --session <id>` liga uma sessão existente.
+- `change relink [--apply]` e `change backlink [--apply]` reparam o grafo; dry-run é o padrão.
+- `change abandon <slug>` descarta sem ADR; `archive --force` exige decisão humana explícita.
+- `wendkeep spec list|show|effective|migrate|rebase` administra contratos vivos e deltas.
+- `wendkeep sensors list|add` administra provas executáveis.
+- Exit `0` indica comando concluído; os gates usam exit `1` para prova vermelha e exit `2` para
+  contexto/uso inválido.
+
+## Exemplos
+
+```bash
+npx wendkeep change new login-tenant
+npx wendkeep spec effective --change login-tenant
+npx wendkeep change done 1.1 --change login-tenant
+npx wendkeep verify --change login-tenant
+npx wendkeep verify --deep --change login-tenant
+npx wendkeep change archive login-tenant
+```
+
+Para adicionar um sensor:
+
+```bash
+npx wendkeep sensors add api-contracts "npm run test:contracts" --severity critical
+```
+
+## Resultado esperado
+
+A change arquivada move seu delta para o spec vivo, preserva proposta/design/tarefas/evidência e
+gera um ADR. O archive só passa com tarefas fechadas, sensores exigidos verdes e verdict atual.
+
+## Erros comuns e diagnóstico
+
+- `no change`: selecione com `change use <slug>` ou informe `--change`.
+- `spec_impact: pending`: defina `required` com delta ou `none` com justificativa real.
+- Sensor não executado: mantenha `[sensor:id]` na mesma linha do checkbox da tarefa.
+- Evidência stale: rode novamente `verify` e `verify --deep` depois de alterar tarefas/spec.
+- Rebase em conflito: resolva o delta ou use `--accept-current` apenas quando isso for a decisão.
+
+## Próximos passos
+
+Leia o guia profundo de [verify](verify.md) e a referência de
+[manutenção e diagnóstico](maintenance-and-diagnostics.md).

package/docs/pt-BR/commands/costs-and-observability.md

@@ -0,0 +1,65 @@
+# Custos e observabilidade
+
+**PT-BR** · [English](../../en/commands/costs-and-observability.md)
+
+## Objetivo
+
+Medir sessões, prompts, modelos e custo de IA, além de reconstruir históricos a partir dos
+transcripts canônicos quando necessário.
+
+## Quando usar
+
+Use `stats` para visão rápida, `cost` para análise e `cost rebuild` quando notas antigas não têm
+custos confiáveis.
+
+## Quando não usar
+
+Não aplique rebuild antes de validar provider e transcript de cada sessão. Não compare custos de
+projetos com registries misturados.
+
+## Pré-requisitos
+
+Registry consistente, tabela de preços completa e acesso aos transcripts das sessões reconstruídas.
+
+## Sintaxe
+
+```bash
+npx wendkeep stats [--vault <cofre>] [--json]
+npx wendkeep cost [--since <data>] [--top [N]] [--trend day|week|month] [--write] [--json]
+npx wendkeep cost rebuild [--session <id|arquivo>] [--limit N] [--apply] [--json]
+```
+
+## Opções e códigos de saída
+
+- `wendkeep stats` gera uma linha compartilhável ou JSON.
+- `wendkeep cost` agrega total/modelo/dia; `--trend` inclui projeção e `--write` atualiza
+  `00-Custo.md`.
+- `wendkeep cost rebuild` é dry-run por padrão; `--apply` grava notas e
+  `.brain/COST_REBUILD.json`.
+- Exit `0` indica cálculo consistente; não zero indica registry, preço, transcript ou parsing
+  insuficiente.
+
+## Exemplos
+
+```bash
+npx wendkeep stats --vault .MeuApp-vault
+npx wendkeep cost --since 2026-07-01 --top 10 --trend week
+npx wendkeep cost rebuild --session 019abc --json
+```
+
+## Resultado esperado
+
+Totais preservam dimensões de input/output/cache/reasoning por modelo e período. Rebuild mostra a
+prévia antes de alterar notas e deixa um relatório reproduzível quando aplicado.
+
+## Erros comuns e diagnóstico
+
+- Modelo sem preço: atualize a tabela antes de aceitar o total.
+- Custos de provider errado: valide a cadeia de identidade da sessão.
+- Transcript ausente: não estime silenciosamente; mantenha a lacuna visível.
+- Total duplicado por subagent/fork: confirme relação pai/subagent e deduplicação do registry.
+
+## Próximos passos
+
+Veja [sessões e importação](sessions-and-import.md), [importação retroativa](retroactive-import.md)
+e [manutenção](maintenance-and-diagnostics.md).