wendkeep 0.58.1 → 0.59.0

package/CHANGELOG.md

@@ -4,6 +4,126 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.59.0] — 2026-07-27
+
+### Added
+
+- **Perfis de Operação separam memória persistente de governança:** `OFF`, `FLOW`, `GUIDE`,
+  `GOVERN` e `ASSURE`, com resolução explícita por sessão ou projeto e fallback conservador para
+  `GOVERN`. O novo `wendkeep profile status|use` torna a escolha e sua origem auditáveis.
+- **FLOW executa ajustes pequenos por um microcontrato E → V:** `flow start/status/show/finish`
+  exige allowlist e sensores, registra baseline Git e tentativas no Vault e produz um recibo
+  terminal imutável sem criar change, ADR ou veredicto independente. `flow promote` preserva a
+  evidência ao converter o trabalho em uma change normal, sem `--force`.
+
+### Changed
+
+- **Keep Core agora é explicitamente inegociável e sempre ativo.** Vault, identidade, sessões,
+  CORE, SHARED_MEMORY, lessons e persistência continuam funcionando em todos os perfis; apenas o
+  Wend Runtime de governança é desligado em `OFF`. Hooks, skills, `init` e `sync` respeitam a mesma
+  fronteira, e instalações novas começam em `GOVERN`.
+- **Artefatos de runtime FLOW vivem em `.brain/runtime/flows/`.** A fronteira arquitetural impede
+  dependências do Vault para o harness/perfil e mantém aberta uma modularização física posterior
+  em `cli`, `harness`, `vault`, `mcp`, `integration` e `pi`.
+
+### Fixed
+
+- **Retries concorrentes do mesmo evento de memória convergem durante a publicação.** O perdedor
+  do `open(..., 'wx')` tolera por uma janela limitada apenas o JSON ainda parcial do produtor
+  vencedor, revalidando a fronteira física do Vault a cada leitura; payload diferente, arquivo
+  permanentemente ilegível e aliases inseguros continuam falhando fechado. Fixtures de CLI também
+  isolam `WENDKEEP_SENSOR_VAULT`, permitindo que a suíte rode dentro do próprio `verify --vault`.
+- **Handoffs sequenciais da mesma ativação respeitam causalidade.** Um turno mais novo da mesma
+  sessão/ativação substitui o anterior em vez de abrir conflito; ativações realmente distintas
+  continuam exigindo resolução humana.
+- **Todas as tags de sensor de uma tarefa entram no gate.** `verify` não descarta mais tags
+  `[sensor:]` adicionais na mesma linha: IDs distintos executam uma vez, na ordem declarada, e o
+  primeiro continua disponível como alias legado para consumidores antigos.
+- **Reconciliação de memória separa reparo estrutural de decisão semântica.** O novo `memory
+  reconcile` é dry-run por padrão, reprojeta o ledger sem consumir outbox, distingue cursor físico
+  de ordem causal e usa os mesmos invariantes do CORE no projector e no health check. `verify` e
+  `flow finish` agora executam sensores contra o Vault efetivamente selecionado. `memory repair`
+  reconhece e migra por CAS checkpoints causais válidos pré-0.59, com backup/auditoria, enquanto
+  locks owner-aware por PID/token impedem reap de processos vivos e remoção ABA.
+- **Iterações truncadas preservam Markdown válido.** Backticks inline ou fences cortados pelo
+  limite de tamanho são escapados antes da escrita e não engolem mais a linha seguinte.
+- **`sync` preserva seu estágio de reparo sem reabrir fallback global.** A CLI não tenta resolver
+  o Vault antes do `init`; binding inválido falha fechado nessa primeira etapa, e apenas o vínculo
+  validado é repassado a `sync-defs` e `doctor`.
+
+### Security
+
+- **FLOW falha fechado fora do contrato.** Escapes da allowlist, superfícies protegidas, mudança
+  de configuração de sensores, metadata/flags ocultas do Git, sensores críticos vermelhos ou
+  mutantes, symlink/junction/reparse/hardlink, submodules e superfícies ignoradas bloqueiam o
+  recibo. ProjectRoot/sensor cwd ficam congelados e um snapshot terminal fecha a janela após os
+  sensores. Raízes adicionais podem ser declaradas por `harness.flow.protectedRoots`; uma política
+  canônica gera classifier, discovery e topologia. Escritas/locks do Vault falham antes de escapar,
+  usando owner+lease sem reap de processo vivo ou liberação ABA. Uma descoberta no-follow limitada
+  inclui aliases protegidos vazios/ignorados sem entrar no Vault, `.git` ou caches. Promoção
+  cross-process elege um dono, vincula semanticamente contrato/reserva/recibo/origem, preflighta
+  destinos multi-spec e permite ao perdedor repetir com `--change-slug`. IDs não atravessam o
+  runtime root, artefatos corrompidos nunca reabrem o FLOW, não existe `--force`, e promoção nunca
+  toma outra change ou repositório. Ledger, outbox, CORE/SHARED, registry, notas, sidecars,
+  temporários e backups também falham fechados em aliases físicos ou hardlinks externos.
+- **Supersession ambígua exige autorização auditável e CAS exato.** A aplicação nomeia a sessão
+  sucessora e o motivo, prova que cada evento pertence à identidade causal nomeada, rejeita flags
+  ambíguas antes de I/O, limita a mutação às duas sessões, preserva o attempt original e cria backup
+  exato do registry antes da troca.
+- **Binding ilegível não desliga governança silenciosamente.** Hooks mutantes falham fechados;
+  quando um Vault explícito ou legado é inequívoco, Keep Core continua injetado sob fallback
+  `GOVERN` junto do diagnóstico de corrupção. Config legada mais próxima inválida, shape tipado
+  incorreto, marcador ausente ou identidade divergente não herdam Vault pai/global; `profile`
+  expõe `binding_error` e rejeita flags duplicadas/ambíguas antes de I/O. O guard cobre caixa,
+  shims locais, entrypoint Node e paths/call operator de Git nos gates force/no-verify.
+
+## [0.58.3] — 2026-07-26
+
+### Fixed
+
+- **O primeiro `SessionStop` elegível após a migração legacy → v2 volta a publicar o handoff.**
+  A activation passa a representar um epoch com múltiplos Stops, e `UserPromptSubmit` recupera
+  uma única activation ausente sob lock. Identidade nativa de sessão/turno e a ordem física do
+  transcript impedem que Stops duplicados, atrasados ou de uma activation anterior publiquem de
+  novo ou sobrescrevam checkpoints mais recentes.
+- **A publicação de memória ficou durável e observável de ponta a ponta.** O evento é enfileirado
+  antes de registrar `enqueued`, a projeção ocorre fora do lock e retries reutilizam a tentativa
+  congelada. Falhas preservam a outbox como `degraded`, enquanto retornos ambíguos deixam evidência
+  diagnóstica em vez de encerrar silenciosamente.
+- **`wendkeep doctor` agora detecta memória v2 realmente estagnada sem acusar uma migração nova.**
+  O diagnóstico correlaciona tentativa, ledger, outbox, revisão e checkpoint; revision 0 logo após
+  uma migração válida continua saudável, mas perda causal, ambiguidade e divergência bloqueiam.
+
+### Changed
+
+- **Os guias bilíngues de memória, sessões, migração e diagnóstico descrevem o lifecycle real.**
+  A documentação cobre epochs multi-Stop, recuperação única, retries idempotentes, estados
+  `enqueued|projected|degraded|ambiguous` e como interpretar revision 0.
+
+### Security
+
+- **Fixtures persistíveis de lifecycle são integralmente sintéticas.** Um gate de privacidade
+  verifica arquivos rastreados e novos e reporta somente arquivo, linha e categoria, evitando que
+  caminhos ou identificadores locais entrem em testes, commits e artefatos.
+
+## [0.58.2] — 2026-07-26
+
+### Added
+
+- **Referência completa dos comandos agora é bilíngue e orientada por tarefa.** Sete guias por
+  domínio e três guias profundos cobrem instalação, changes, verificação, memória, sessões,
+  importação, notas, custos e manutenção em PT-BR e inglês, com sintaxe, exits, exemplos,
+  resultados esperados e diagnóstico.
+- **Paridade documental virou gate automatizado.** O novo sensor `docs-bilingual` bloqueia pares
+  ausentes, comandos públicos sem cobertura, links quebrados, estrutura divergente, drift da regra
+  local e guias ausentes no tarball.
+
+### Changed
+
+- **Os READMEs agora apresentam as funcionalidades por grupos.** A referência extensa deu lugar a
+  um mapa navegável que leva ao guia correto no GitHub e no npm. O fluxo de `verify` deixa explícito
+  que exit 2 por ausência de change é contexto ocioso, não falha de saúde do projeto.
+
 ## [0.58.1] — 2026-07-26
 
 ### Fixed

package/README.en.md

@@ -13,7 +13,7 @@
 
 **In the graph:** 🔵 session · 🟣 decision · 🔴 bug · 🟢 learning · 🟡 change — every note, backlinked.
 
-**A persistent‑memory harness for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn‑by‑turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. On top of that memory core sits a native, zero‑dependency **change lifecycle** (spec → change → TDD → sensor‑gated archive) that keeps intent, work and proof wikilinked in one graph. 100% local, open‑core.
+**Persistent memory for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn by turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking and automatically extracted decisions, bugs, and learnings. That always-on plane is **Keep Core**. On top of it, **Wend Runtime** provides a native, zero-dependency lifecycle (spec → change → TDD → sensor-gated archive), selected through the `OFF`, `FLOW`, `GUIDE`, `GOVERN`, and `ASSURE` Operating Profiles. 100% local, open-core.
 
 ```bash
 npm i -D wendkeep && npx wendkeep init      # captures from the next session on
@@ -120,6 +120,9 @@ one command:
 npm install --save-dev wendkeep@latest && npx --no-install wendkeep sync --project . --yes
 ```
 
+`sync` lets its own `init` stage validate or rebuild the binding before resolving the Vault for
+later stages. An invalid `.wendkeep.json` stops at `init` without falling back to an inherited global Vault.
+
 The install stays outside `sync` on purpose: a running process cannot replace itself and
 keep going — the code in memory would still be the old one.
 
@@ -156,41 +159,52 @@ stop reporting `defs stale` without a single skill having been updated. If you h
 `wk-*`, that edit is overwritten; your own customisation belongs in a skill of your own,
 which the reseed never touches.
 
-## Commands
-
-| Command | What it does |
-|---|---|
-| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP + skills). |
-| `wendkeep sync [--project P]` | **One-command update**: runs `init` → `sync-defs` → `doctor` on the current project, stopping at the first failing step. Install the package first (a running process cannot replace itself). `--vault P` · `--yes` to skip the companions picker. |
-| `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
-| `wendkeep change <sub>` | Change lifecycle: `new <slug> [--simple]` / `use <slug>` (switch focus) / `continue <archived> <new> [--simple]` / `bind <slug> --session <id>` / `list` (global backlog) / `show <slug>` / `status [slug]` / `done <id> [--change slug]` / `undone <id> [--change slug]` / `relink [--apply] [--json]` (repair change wikilinks; preview by default) / `diff [slug]` / `archive [slug] [--force]` / `abandon [slug]` (drop it, no ADR) / `backlink [--apply]` (inject the proposal backlink into orphan design/tasks/spec files). `diff`, `archive` and `abandon` fall back to the active change when you omit the slug; bare `status` lists every open one. |
-| `wendkeep verify [--deep] [--change s]` | Run the change's task sensors; `--deep` assembles the independent-verification package. `--change` targets a change other than the active one; `--project <root>` runs it from outside the root. |
-| `wendkeep spec <sub>` | `list` / `show <capability>` generated contracts; `effective [--change <slug>] [--json]` (living contract + delta; defaults to the active change); `migrate`; `rebase [--accept-current]` (stops on conflicts unless you accept the living spec's side). |
-| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` with `--severity` / `--type` / `--report` / `--name` / `--description` / `--project` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
-| `wendkeep cost [opts]` | Aggregate AI-coding spend across the vault's sessions — total, by model, by day. `--since <date>` / `--top [N]` (priciest) / `--trend [day\|week\|month]` (+ run-rate projection) / `--write` (generate `00-Custo.md`) / `--json`. |
-| `wendkeep cost rebuild [opts]` | Recalculate historical parent + subagent costs from `SESSION_REGISTRY`. Dry-run by default; `--apply` updates the notes and writes `.brain/COST_REBUILD.json`. Also `--session <id\|file>` / `--limit n` / `--json`. |
-| `wendkeep stats [--vault P]` | One shareable line: sessions · prompts · spend · span · models (`--json`). |
-| `wendkeep import [opts]` | **Retroactive memory** — backfill past **Claude + Codex** sessions into the vault (deduped by `session_id`). `--source all\|claude\|codex` / `--stamp-ids` / `--rescan-decisions` / `--from <dir>` / `--codex-from <dir>` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
-| `wendkeep session list\|show\|use` | List the multi-session registry, show one conversation, or move only the human focus in `CURRENT_SESSION.md`. |
-| `wendkeep dashboard [--force]` | (Re)generate the vault's folder-filtered Bases + the `00-Dashboard` MOC. |
-| `wendkeep note new --type bug\|learning "<title>"` | Create a **numbered** derived note (`BUG-`/`APR-NNNN`) in the month folder and print its vault path. `--date YYYY-MM-DD`. |
-| `wendkeep note relink [--apply]` | Backfill provenance on orphan derived notes (BUG/APR with no source session), inheriting the modal session of their type/month cohort. Preview by default. |
-| `wendkeep note repair-frontmatter [--apply]` | Merge stacked frontmatter blocks in a session note — damage from the concurrent writes of pre-0.50 versions. Base keys from the original block, values from the newest; preview by default · `--json`. |
-| `wendkeep note repair-sections [--apply]` | Rebuild the `## Decisions/Bugs/Learnings generated in this session` sections from the linked derived notes — the body used to lag behind the closing block. Preview by default · `--json`. |
-| `wendkeep renumber-decisions` | Renumber `04-Decisões` to `ADR-NNNN-<slug>` chronologically, move notes out of legacy `DIA N` subfolders into the month folder, and rewrite wikilinks. Preview by default; `--apply` / `--json`. |
-| `wendkeep renumber-bugs` | Same for `05-Bugs` → `BUG-NNNN-<slug>`. |
-| `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
-| `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). `--change <slug>` ties the lesson to a change; `--vault P`. |
-| `wendkeep sync-defs` | Copy `.brain/agents\|skills` into `.codex/agents`, `.claude/skills`, `.agents/skills`; `--check` detects drift, `--reseed` refreshes the `wk-*` skills from the installed version's seeds. |
-| `wendkeep memory status [--gate] --vault P` | Inspect the v2 bundle without mutating it. `--gate` exits 1 only for a blocking state; warnings keep exit code 0. |
-| `wendkeep memory migrate [--apply] --vault P` | Convert a legacy `SHARED_MEMORY.md`. Dry-run by default; `--apply` creates a backup, turns legacy content into candidates, and publishes a valid v2 projection without editing CORE. |
-| `wendkeep memory repair --vault P` | Repair a partial/corrupt ledger under lock, preserving the original bytes in a `.bak`, retaining valid events, and re-projecting state. |
-| `wendkeep memory promote <candidate> --vault P` | Promote a candidate by ID by appending an auditable event; never edits the ledger in place. |
-| `wendkeep memory reject <candidate> --vault P` | Reject a candidate by ID by appending the decision to the audit history. |
-| `wendkeep validate-memory [path]` | Compatibility mode: validate `.brain/CORE.md` only (cap 25, 3 sections, no secrets/PII). Use `--vault <path>` to validate CORE + ledger + SHARED as a v2 bundle. |
-| `wendkeep theme sync [--vault P]` | Re-apply the colour system (CSS snippet + graph groups) to an existing vault — recovers a grey graph without re-running `init`. |
-| `wendkeep doctor [--vault P]` | Read-only vault health check. Beyond sessions/registry, links, notes, prices, and derived sections, it checks the v2 bundle and points to `memory status --gate` or `memory repair`; doctor never projects or repairs by itself. |
-| `wendkeep --version` / `--help` | Version / usage. |
+## Features by group
+
+The README is the map; the guides provide syntax, options, exit codes, examples, and diagnosis.
+
+| Group | Use it for | Detailed guide |
+|---|---|---|
+| **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
+| **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
+| **Changes and verification** | `change`, specs, sensors, TDD, evidence, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
+| **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |
+| **Sessions and import** | hooks, registry, session focus, and Claude/Codex backfill | [Sessions and import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sessions-and-import.md) |
+| **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
+| **Costs and observability** | stats, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
+| **Maintenance and diagnostics** | doctor, definition drift, theme, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+
+Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
+[legacy-memory migration](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory-migration.md), and
+[safe retroactive import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/retroactive-import.md).
+
+## Operating Profiles — Keep Core is always active
+
+**Keep Core is always active**: the Vault, sessions, identity, CORE/SHARED, lessons, costs,
+and persistence do not turn off with the harness. **Wend Runtime** controls only the governance
+layer:
+
+| Profile | Route | Use |
+|---|---|---|
+| `OFF` | LLM-native harness | No Wend router, skill gate, or gates; explicit selection only. |
+| `FLOW` | E → V | Microcontract with Git baseline, allowlist, sensor, and receipt, without a change. |
+| `GUIDE` | P → E → V | Compact guided change. |
+| `GOVERN` | P → R → E → V | Current a2 loop and compatible fallback. |
+| `ASSURE` | P → R → E → V → C | Governance with confirmation and handoff. |
+
+A corrupt binding never selects `OFF`: with one unambiguous explicit or legacy Vault, Keep Core
+remains active under `GOVERN`, the error stays visible, and mutation guards fail closed. Additional
+roots that FLOW must protect can be declared as project-relative paths under
+`harness.flow.protectedRoots` in `.wendkeep.json`; any change below them requires promotion.
+Invalid local config, marker, or identity never silently falls back to a parent/global Vault.
+
+`wendkeep profile status/use` makes the choice observable; `wendkeep flow
+start/finish/promote` handles local adjustments without manufacturing an ADR and fails closed on
+physical escapes, Git metadata/hidden flags, mutating sensors, protected surfaces, or incomplete
+session projection. Bounded no-follow discovery sees empty/ignored protected aliases; Vault writes
+and owner+lease locks validate physical topology. Concurrent promotion elects one owner and supports
+retry through `--change-slug`. Read the complete
+[Operating profiles guide](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md).
 
 ## Shared Project Memory v2
 
@@ -198,11 +212,17 @@ Hot memory now separates human authorship, operational state, and evidence:
 
 - **`CORE.md` is canonical.** It is the short, hand-curated nucleus for durable preferences, active patterns, and open issues; no projector may infer or overwrite it.
 - **`SHARED_MEMORY.md` is generated operational state.** The `Stop` hook turns the session handoff into sanitized events; the projector deterministically reduces the ledger and publishes a verifiable revision, cursor, and hash. Facts are `verified` only with local evidence; unsupported reports remain `reported`, and disagreements become candidates for human judgment.
-- **`MEMORY_EVENTS.jsonl` is the append-only authority.** Producers publish to the outbox with exclusive creation, then the projector serializes append + projection under a lock. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
+- **`MEMORY_EVENTS.jsonl` is the append-only authority.** `Stop` makes events durable in the outbox before acknowledging the attempt; the projector runs outside the registry lock and retries reuse the same IDs. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
 - **`MEMORY_CANDIDATES.jsonl` is the curation queue.** Conflicts and legacy content are never silently promoted. `promote` and `reject` record the decision as a new event.
 
 Artifacts stay under `.brain/` only. Sanitization strips secrets, tokens, local paths, transcripts, and harness payloads both before persistence and before injection. Events carry a `project_id`, and one vault never accepts another project's events.
 
+Lifecycle in brief: each `SessionStart` opens an epoch that spans multiple `Stop` events;
+`UserPromptSubmit` advances the native turn and recovers exactly one closed legacy activation.
+Codex uses `session_id`/`turn_id` plus transcript order, with no artificial causal fields. See
+[sessions and hooks](docs/en/commands/sessions-and-import.md) and
+[memory](docs/en/commands/memory.md).
+
 ### Injection and budgets
 
 `brain-inject` delivers the same revision/hash on `startup`, `/clear`, and `/compact` `SessionStart` events, always placing CORE and SHARED before change context. The full envelope is capped at 24 KiB; CORE reserves up to 4 KiB, SHARED up to 6 KiB, and each line is capped at 320 characters. Under pressure, lessons are removed first, then non-current changes. CORE and SHARED are never prefix-sliced: a missing, invalid, or over-budget layer becomes a visible, repairable `<wk_memory_error>`.
@@ -217,9 +237,19 @@ wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2
 
 ### Health and recovery
 
-Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. The critical `memory-health` sensor blocks ledger/outbox/bundle corruption, revision/cursor/hash lag, and active conflicts. A valid pending outbox or ordinary candidate is recoverable and remains a warning rather than blocking.
+Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. Revision 0
+immediately after valid migration is healthy. The gate correlates `last_memory_attempt`, outbox,
+ledger, SHARED, and checkpoint: `degraded` with a durable outbox is a warning; an ambiguous attempt,
+lost publication, or mismatched checkpoint blocks. See [migration](docs/en/commands/memory-migration.md)
+and [diagnostics](docs/en/commands/maintenance-and-diagnostics.md).
 
-If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to save a backup of the corrupt ledger, retain valid lines, and re-project. Then run `status --gate` again. Conflicts require explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.
+If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to back up
+the corrupt ledger, retain valid lines, and re-project. Repair never reclassifies attempts. A
+valid pre-0.59 causal checkpoint is CAS-migrated to the physical boundary with backup/audit. A
+demonstrably superseded ambiguity uses `memory reconcile <session> --by-session <successor>
+--reason <reason>` as a dry run and requires `--apply`; the decision is backed up and audited
+without rewriting ledger, CORE, or notes. Run `status --gate` again afterwards. Conflicts require
+explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.
 
 Session notes use one live `## Agentes, tokens e custos` snapshot. Main-agent and subagent hooks recompose it atomically, with costs, token dimensions, reasoning tokens and effort per model/source. Every hook that rewrites a session note takes a per-file lock and writes through a temp file + rename, so the `SubagentStop` fan-out (one hook run per subagent) can never leave a note half-written; a note whose frontmatter reads back damaged is left untouched rather than patched.
 
@@ -287,7 +317,7 @@ explore → propose → apply (TDD) → verify → archive
 ```
 
 - **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`; `--simple` skips the design). It becomes the global *current* change. When the change declares `spec_impact: required`, you author the delta yourself at `specs/<capability>/spec.md` — there is no placeholder to delete. Multiple changes may remain open: `change list`/`status` and the hooks show every pending one, while commands without `--change` act on the current one alone. `change use <slug>` changes focus and `change continue <archived> <new>` creates an auditable continuation.
-- **Apply** — implement each `tarefas.md` task. Tag a task that needs machine proof with `[sensor:<id>]` — one sensor per task (a task carries a single sensor; split it in two if you need two) — and the requirement it satisfies with `[req:<ID>]`, of which a task may declare several.
+- **Apply** — implement each `tarefas.md` task. Mark machine proof with one or more `[sensor:<id>]` tags on the same task: every distinct ID enters the gate once, in declaration order. Also mark satisfied requirements with one or more `[req:<ID>]` tags.
 - **Verify** — `wendkeep verify` runs the sensors your tasks declared (from `wendkeep.sensors.json` at the project root) and writes `evidencia.json`. A red `critical` fails the gate; a red `warning` is advisory. `verify --deep` builds a self-contained package with complete effective requirements (living contract + this change's delta), so the independent verifier never needs to reconstruct unarchived requirements from `07-Specs`. Every change needs a `verdict.json` to archive; `verify --deep` writes a trivial one automatically when the change declares no `[req:]`.
 - **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each capability's spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md`, moves the change to `_arquivo/`, and mints an ADR in `04-Decisões/`.
 

package/README.md

@@ -13,7 +13,7 @@
 
 **In the graph:** 🔵 session · 🟣 decision · 🔴 bug · 🟢 learning · 🟡 change — every note, backlinked.
 
-**A persistent‑memory harness for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn‑by‑turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. On top of that memory core sits a native, zero‑dependency **change lifecycle** (spec → change → TDD → sensor‑gated archive) that keeps intent, work and proof wikilinked in one graph. 100% local, open‑core.
+**Persistent memory for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn by turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking and automatically extracted decisions, bugs, and learnings. That always-on plane is **Keep Core**. On top of it, **Wend Runtime** provides a native, zero-dependency lifecycle (spec → change → TDD → sensor-gated archive), selected through the `OFF`, `FLOW`, `GUIDE`, `GOVERN`, and `ASSURE` Operating Profiles. 100% local, open-core.
 
 ```bash
 npm i -D wendkeep && npx wendkeep init      # captures from the next session on
@@ -120,6 +120,9 @@ one command:
 npm install --save-dev wendkeep@latest && npx --no-install wendkeep sync --project . --yes
 ```
 
+`sync` lets its own `init` stage validate or rebuild the binding before resolving the Vault for
+later stages. An invalid `.wendkeep.json` stops at `init` without falling back to an inherited global Vault.
+
 The install stays outside `sync` on purpose: a running process cannot replace itself and
 keep going — the code in memory would still be the old one.
 
@@ -156,41 +159,52 @@ stop reporting `defs stale` without a single skill having been updated. If you h
 `wk-*`, that edit is overwritten; your own customisation belongs in a skill of your own,
 which the reseed never touches.
 
-## Commands
-
-| Command | What it does |
-|---|---|
-| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP + skills). |
-| `wendkeep sync [--project P]` | **One-command update**: runs `init` → `sync-defs` → `doctor` on the current project, stopping at the first failing step. Install the package first (a running process cannot replace itself). `--vault P` · `--yes` to skip the companions picker. |
-| `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
-| `wendkeep change <sub>` | Change lifecycle: `new <slug> [--simple]` / `use <slug>` (switch focus) / `continue <archived> <new> [--simple]` / `bind <slug> --session <id>` / `list` (global backlog) / `show <slug>` / `status [slug]` / `done <id> [--change slug]` / `undone <id> [--change slug]` / `relink [--apply] [--json]` (repair change wikilinks; preview by default) / `diff [slug]` / `archive [slug] [--force]` / `abandon [slug]` (drop it, no ADR) / `backlink [--apply]` (inject the proposal backlink into orphan design/tasks/spec files). `diff`, `archive` and `abandon` fall back to the active change when you omit the slug; bare `status` lists every open one. |
-| `wendkeep verify [--deep] [--change s]` | Run the change's task sensors; `--deep` assembles the independent-verification package. `--change` targets a change other than the active one; `--project <root>` runs it from outside the root. |
-| `wendkeep spec <sub>` | `list` / `show <capability>` generated contracts; `effective [--change <slug>] [--json]` (living contract + delta; defaults to the active change); `migrate`; `rebase [--accept-current]` (stops on conflicts unless you accept the living spec's side). |
-| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` with `--severity` / `--type` / `--report` / `--name` / `--description` / `--project` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
-| `wendkeep cost [opts]` | Aggregate AI-coding spend across the vault's sessions — total, by model, by day. `--since <date>` / `--top [N]` (priciest) / `--trend [day\|week\|month]` (+ run-rate projection) / `--write` (generate `00-Custo.md`) / `--json`. |
-| `wendkeep cost rebuild [opts]` | Recalculate historical parent + subagent costs from `SESSION_REGISTRY`. Dry-run by default; `--apply` updates the notes and writes `.brain/COST_REBUILD.json`. Also `--session <id\|file>` / `--limit n` / `--json`. |
-| `wendkeep stats [--vault P]` | One shareable line: sessions · prompts · spend · span · models (`--json`). |
-| `wendkeep import [opts]` | **Retroactive memory** — backfill past **Claude + Codex** sessions into the vault (deduped by `session_id`). `--source all\|claude\|codex` / `--stamp-ids` / `--rescan-decisions` / `--from <dir>` / `--codex-from <dir>` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
-| `wendkeep session list\|show\|use` | List the multi-session registry, show one conversation, or move only the human focus in `CURRENT_SESSION.md`. |
-| `wendkeep dashboard [--force]` | (Re)generate the vault's folder-filtered Bases + the `00-Dashboard` MOC. |
-| `wendkeep note new --type bug\|learning "<title>"` | Create a **numbered** derived note (`BUG-`/`APR-NNNN`) in the month folder and print its vault path. `--date YYYY-MM-DD`. |
-| `wendkeep note relink [--apply]` | Backfill provenance on orphan derived notes (BUG/APR with no source session), inheriting the modal session of their type/month cohort. Preview by default. |
-| `wendkeep note repair-frontmatter [--apply]` | Merge stacked frontmatter blocks in a session note — damage from the concurrent writes of pre-0.50 versions. Base keys from the original block, values from the newest; preview by default · `--json`. |
-| `wendkeep note repair-sections [--apply]` | Rebuild the `## Decisions/Bugs/Learnings generated in this session` sections from the linked derived notes — the body used to lag behind the closing block. Preview by default · `--json`. |
-| `wendkeep renumber-decisions` | Renumber `04-Decisões` to `ADR-NNNN-<slug>` chronologically, move notes out of legacy `DIA N` subfolders into the month folder, and rewrite wikilinks. Preview by default; `--apply` / `--json`. |
-| `wendkeep renumber-bugs` | Same for `05-Bugs` → `BUG-NNNN-<slug>`. |
-| `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
-| `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). `--change <slug>` ties the lesson to a change; `--vault P`. |
-| `wendkeep sync-defs` | Copy `.brain/agents\|skills` into `.codex/agents`, `.claude/skills`, `.agents/skills`; `--check` detects drift, `--reseed` refreshes the `wk-*` skills from the installed version's seeds. |
-| `wendkeep memory status [--gate] --vault P` | Inspect the v2 bundle without mutating it. `--gate` exits 1 only for a blocking state; warnings keep exit code 0. |
-| `wendkeep memory migrate [--apply] --vault P` | Convert a legacy `SHARED_MEMORY.md`. Dry-run by default; `--apply` creates a backup, turns legacy content into candidates, and publishes a valid v2 projection without editing CORE. |
-| `wendkeep memory repair --vault P` | Repair a partial/corrupt ledger under lock, preserving the original bytes in a `.bak`, retaining valid events, and re-projecting state. |
-| `wendkeep memory promote <candidate> --vault P` | Promote a candidate by ID by appending an auditable event; never edits the ledger in place. |
-| `wendkeep memory reject <candidate> --vault P` | Reject a candidate by ID by appending the decision to the audit history. |
-| `wendkeep validate-memory [path]` | Compatibility mode: validate `.brain/CORE.md` only (cap 25, 3 sections, no secrets/PII). Use `--vault <path>` to validate CORE + ledger + SHARED as a v2 bundle. |
-| `wendkeep theme sync [--vault P]` | Re-apply the colour system (CSS snippet + graph groups) to an existing vault — recovers a grey graph without re-running `init`. |
-| `wendkeep doctor [--vault P]` | Read-only vault health check. Beyond sessions/registry, links, notes, prices, and derived sections, it checks the v2 bundle and points to `memory status --gate` or `memory repair`; doctor never projects or repairs by itself. |
-| `wendkeep --version` / `--help` | Version / usage. |
+## Features by group
+
+The README is the map; the guides provide syntax, options, exit codes, examples, and diagnosis.
+
+| Group | Use it for | Detailed guide |
+|---|---|---|
+| **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
+| **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
+| **Changes and verification** | `change`, specs, sensors, TDD, evidence, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
+| **Shared memory** | CORE, SHARED, status, validation, repair, and curation | [Memory](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory.md) |
+| **Sessions and import** | hooks, registry, session focus, and Claude/Codex backfill | [Sessions and import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sessions-and-import.md) |
+| **Notes and knowledge** | BUG/APR/ADR, repairs, renumbering, lessons, and dashboard | [Notes and knowledge](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/notes-and-knowledge.md) |
+| **Costs and observability** | stats, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
+| **Maintenance and diagnostics** | doctor, definition drift, theme, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
+
+Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
+[legacy-memory migration](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/memory-migration.md), and
+[safe retroactive import](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/retroactive-import.md).
+
+## Operating Profiles — Keep Core is always active
+
+**Keep Core is always active**: the Vault, sessions, identity, CORE/SHARED, lessons, costs,
+and persistence do not turn off with the harness. **Wend Runtime** controls only the governance
+layer:
+
+| Profile | Route | Use |
+|---|---|---|
+| `OFF` | LLM-native harness | No Wend router, skill gate, or gates; explicit selection only. |
+| `FLOW` | E → V | Microcontract with Git baseline, allowlist, sensor, and receipt, without a change. |
+| `GUIDE` | P → E → V | Compact guided change. |
+| `GOVERN` | P → R → E → V | Current a2 loop and compatible fallback. |
+| `ASSURE` | P → R → E → V → C | Governance with confirmation and handoff. |
+
+A corrupt binding never selects `OFF`: with one unambiguous explicit or legacy Vault, Keep Core
+remains active under `GOVERN`, the error stays visible, and mutation guards fail closed. Additional
+roots that FLOW must protect can be declared as project-relative paths under
+`harness.flow.protectedRoots` in `.wendkeep.json`; any change below them requires promotion.
+Invalid local config, marker, or identity never silently falls back to a parent/global Vault.
+
+`wendkeep profile status/use` makes the choice observable; `wendkeep flow
+start/finish/promote` handles local adjustments without manufacturing an ADR and fails closed on
+physical escapes, Git metadata/hidden flags, mutating sensors, protected surfaces, or incomplete
+session projection. Bounded no-follow discovery sees empty/ignored protected aliases; Vault writes
+and owner+lease locks validate physical topology. Concurrent promotion elects one owner and supports
+retry through `--change-slug`. Read the complete
+[Operating profiles guide](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md).
 
 ## Shared Project Memory v2
 
@@ -198,11 +212,17 @@ Hot memory now separates human authorship, operational state, and evidence:
 
 - **`CORE.md` is canonical.** It is the short, hand-curated nucleus for durable preferences, active patterns, and open issues; no projector may infer or overwrite it.
 - **`SHARED_MEMORY.md` is generated operational state.** The `Stop` hook turns the session handoff into sanitized events; the projector deterministically reduces the ledger and publishes a verifiable revision, cursor, and hash. Facts are `verified` only with local evidence; unsupported reports remain `reported`, and disagreements become candidates for human judgment.
-- **`MEMORY_EVENTS.jsonl` is the append-only authority.** Producers publish to the outbox with exclusive creation, then the projector serializes append + projection under a lock. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
+- **`MEMORY_EVENTS.jsonl` is the append-only authority.** `Stop` makes events durable in the outbox before acknowledging the attempt; the projector runs outside the registry lock and retries reuse the same IDs. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
 - **`MEMORY_CANDIDATES.jsonl` is the curation queue.** Conflicts and legacy content are never silently promoted. `promote` and `reject` record the decision as a new event.
 
 Artifacts stay under `.brain/` only. Sanitization strips secrets, tokens, local paths, transcripts, and harness payloads both before persistence and before injection. Events carry a `project_id`, and one vault never accepts another project's events.
 
+Lifecycle in brief: each `SessionStart` opens an epoch that spans multiple `Stop` events;
+`UserPromptSubmit` advances the native turn and recovers exactly one closed legacy activation.
+Codex uses `session_id`/`turn_id` plus transcript order, with no artificial causal fields. See
+[sessions and hooks](docs/en/commands/sessions-and-import.md) and
+[memory](docs/en/commands/memory.md).
+
 ### Injection and budgets
 
 `brain-inject` delivers the same revision/hash on `startup`, `/clear`, and `/compact` `SessionStart` events, always placing CORE and SHARED before change context. The full envelope is capped at 24 KiB; CORE reserves up to 4 KiB, SHARED up to 6 KiB, and each line is capped at 320 characters. Under pressure, lessons are removed first, then non-current changes. CORE and SHARED are never prefix-sliced: a missing, invalid, or over-budget layer becomes a visible, repairable `<wk_memory_error>`.
@@ -217,9 +237,19 @@ wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2
 
 ### Health and recovery
 
-Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. The critical `memory-health` sensor blocks ledger/outbox/bundle corruption, revision/cursor/hash lag, and active conflicts. A valid pending outbox or ordinary candidate is recoverable and remains a warning rather than blocking.
+Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. Revision 0
+immediately after valid migration is healthy. The gate correlates `last_memory_attempt`, outbox,
+ledger, SHARED, and checkpoint: `degraded` with a durable outbox is a warning; an ambiguous attempt,
+lost publication, or mismatched checkpoint blocks. See [migration](docs/en/commands/memory-migration.md)
+and [diagnostics](docs/en/commands/maintenance-and-diagnostics.md).
 
-If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to save a backup of the corrupt ledger, retain valid lines, and re-project. Then run `status --gate` again. Conflicts require explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.
+If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to back up
+the corrupt ledger, retain valid lines, and re-project. Repair never reclassifies attempts. A
+valid pre-0.59 causal checkpoint is CAS-migrated to the physical boundary with backup/audit. A
+demonstrably superseded ambiguity uses `memory reconcile <session> --by-session <successor>
+--reason <reason>` as a dry run and requires `--apply`; the decision is backed up and audited
+without rewriting ledger, CORE, or notes. Run `status --gate` again afterwards. Conflicts require
+explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.
 
 Session notes use one live `## Agentes, tokens e custos` snapshot. Main-agent and subagent hooks recompose it atomically, with costs, token dimensions, reasoning tokens and effort per model/source. Every hook that rewrites a session note takes a per-file lock and writes through a temp file + rename, so the `SubagentStop` fan-out (one hook run per subagent) can never leave a note half-written; a note whose frontmatter reads back damaged is left untouched rather than patched.
 
@@ -287,7 +317,7 @@ explore → propose → apply (TDD) → verify → archive
 ```
 
 - **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`; `--simple` skips the design). It becomes the global *current* change. When the change declares `spec_impact: required`, you author the delta yourself at `specs/<capability>/spec.md` — there is no placeholder to delete. Multiple changes may remain open: `change list`/`status` and the hooks show every pending one, while commands without `--change` act on the current one alone. `change use <slug>` changes focus and `change continue <archived> <new>` creates an auditable continuation.
-- **Apply** — implement each `tarefas.md` task. Tag a task that needs machine proof with `[sensor:<id>]` — one sensor per task (a task carries a single sensor; split it in two if you need two) — and the requirement it satisfies with `[req:<ID>]`, of which a task may declare several.
+- **Apply** — implement each `tarefas.md` task. Mark machine proof with one or more `[sensor:<id>]` tags on the same task: every distinct ID enters the gate once, in declaration order. Also mark satisfied requirements with one or more `[req:<ID>]` tags.
 - **Verify** — `wendkeep verify` runs the sensors your tasks declared (from `wendkeep.sensors.json` at the project root) and writes `evidencia.json`. A red `critical` fails the gate; a red `warning` is advisory. `verify --deep` builds a self-contained package with complete effective requirements (living contract + this change's delta), so the independent verifier never needs to reconstruct unarchived requirements from `07-Specs`. Every change needs a `verdict.json` to archive; `verify --deep` writes a trivial one automatically when the change declares no `[req:]`.
 - **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each capability's spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md`, moves the change to `_arquivo/`, and mints an ADR in `04-Decisões/`.