wendkeep 0.76.0 → 0.76.2

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.76.2] — 2026-08-21
+
+### Fixed
+
+- **Projeção SHARED bounded na origem.** O projector agora admite eventos completos de forma
+  determinística e priorizada, nunca publica `SHARED_MEMORY.md` acima de 48 linhas/6144 bytes e
+  declara as contagens projetada/omitida sem perder a autoridade integral do ledger.
+- **Omissão bounded verificável.** O gate semântico rederiva a seleção esperada; apenas o recorte
+  exato é aceito como aviso operacional, enquanto IDs ou contagens divergentes continuam bloqueando.
+- **Recuperação antes de rescope.** Com memória estruturalmente bloqueada, o doctor orienta
+  `memory repair` e novo `memory status --gate` antes de voltar ao dry-run, sem recomendar
+  `memory rescope --apply` sobre uma projeção inválida.
+
+## [0.76.1] — 2026-08-21
+
+### Added
+
+- **Transição causal de branch.** `context switch <branch> [--create] [--session <id>]` move
+  Git e a scope da mesma sessão juntos na worktree atual, preserva change/lease/autorizações,
+  incrementa revisão e registra evidência `from/to` sob o lock do registry.
+
+### Fixed
+
+- **Guard não deixa mais a sessão inutilizável após checkout.** `git checkout/switch` cru que
+  mudaria branch é negado antecipadamente com orientação acionável; falha durante a transição
+  segura executa rollback da branch/HEAD e não publica scope parcial. Contextos incompletos de
+  outra worktree comprovada também deixam de causar falso conflito na worktree atual.
+
 ## [0.76.0] — 2026-08-21
 
 ### Added

package/README.en.md

@@ -115,7 +115,7 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
-3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
 4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
@@ -239,6 +239,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 |---|---|---|
 | **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) |
 | **Managed worktrees** | `worktree create/list/status/open`, Vault binding, and recovery | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
+| **Active context** | `context switch`, causal branch transition, and rollback | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.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) |
@@ -372,7 +373,7 @@ an installation failure.
 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.
+- **`SHARED_MEMORY.md` is bounded 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. Admission prioritizes critical operational state and never publishes beyond 48 lines/6 KiB; omitted events remain in the append-only authority and surface only as verifiable counts. 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.** `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; promotion preserves the selected event's JSON type, session, activation/epoch, and source turn.
 - **Registers are scoped.** `git.local-head`, handoffs, verdicts, and change status carry project, work-session, change, branch, or worktree scope. Two branches do not create a global conflict; only events in the same scope and causal lineage may advance automatically.
@@ -388,9 +389,9 @@ Codex uses `session_id`/`turn_id` plus transcript order, with no artificial caus
 
 ### Injection and budgets
 
-`CORE.md` is the only manual layer: it accepts up to 40 lines, warns from 35, keeps a 4 KiB ceiling, and caps each line at 320 characters. `SHARED_MEMORY.md` is generated exclusively by the projector and ledger; never edit it to repair state. `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; SHARED reserves up to 6 KiB. 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>`.
+`CORE.md` is the only manual layer: it accepts up to 40 lines, warns from 35, keeps a 4 KiB ceiling, and caps each line at 320 characters. `SHARED_MEMORY.md` is generated exclusively by the projector and ledger; never edit it to repair state. `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; SHARED reserves up to 48 lines/6 KiB. Under pressure, lessons are removed first, then non-current changes. CORE is never sliced and SHARED admits deterministic whole events rather than prefix-slicing; a missing, invalid, or over-budget layer becomes a visible, repairable `<wk_memory_error>`.
 
-`memory status --gate` and `validate-memory --vault` also check semantic coverage: they report a code, counts, and active/projected/missing keys. An empty v2 bundle is neutral; a missing projectable event, placeholders as the only content, or an unresolved decision link becomes an explicit degraded/blocking diagnosis without printing memory values.
+`memory status --gate` and `validate-memory --vault` also check semantic coverage: they report a code, counts, and active/projected/missing keys. An empty v2 bundle is neutral; a bounded omission that exactly reproduces ledger selection is an operational warning. An arbitrarily missing event, false count, placeholders as the only content, or an unresolved decision link remains explicitly degraded/blocking without printing memory values.
 
 `DIGEST.md` is no longer the operational handoff: it remains the `/brain-recall` bridge and legacy-vault fallback. A vault without SHARED receives CORE+DIGEST with a deprecation warning; migrate during the compatibility window:
 

package/README.md

@@ -115,7 +115,7 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
-3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
+3. Wire the Codex hooks in **`.codex/hooks.json`** — twelve compatible entries: `brain-inject` + `session-start` + `observer-publish` on `SessionStart`, `session-ensure` + `evidence-context` + `change-context` on `UserPromptSubmit`, `session-stop` + `observer-publish` + `change-nag` on `Stop`, `subagent-stop` + `observer-publish` on `SubagentStop`, and `change-guard` on `PreToolUse` for `Bash`, `exec_command`, `apply_patch`, and mutable MCP tools, always in the `npx wendkeep hook <name>` form. For the Observer, `SessionStart` only drains the outbox, `Stop` enqueues the changed session, and `SubagentStop` enqueues only the affected transcript; full scanning is explicit through `observer reconcile`. The guard accepts object, raw-string, and argv Codex payloads; before a mutation it compares the session with the project, Git root, remote, branch, and worktree, denying missing or divergent targets. A raw `git checkout/switch` branch transition is denied before it can strand the session; use `wendkeep context switch <branch> [--create]`, which moves Git and the causal scope together in the same worktree with an audited revision and rollback. The other four stay out because Codex offers no equivalent payload, tool, or event: `change-warn` (no reliable `tool_input.file_path`), `plan-capture` (no `ExitPlanMode`), `decision-capture` (`AskUserQuestion` is Claude-only), and `task-log` (`TaskCompleted` is not in Codex's event enum). Codex scope blocks use `permissionDecision: "deny"`; `ask` is never emitted in `PreToolUse`. The merge remains non-destructive, preserves third-party hooks, and migrates legacy `timeout` to `timeoutSec`. **Codex enumerates every hook as untrusted and runs none until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**.
 4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
 5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
    - **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
@@ -239,6 +239,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 |---|---|---|
 | **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) |
 | **Managed worktrees** | `worktree create/list/status/open`, Vault binding, and recovery | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
+| **Active context** | `context switch`, causal branch transition, and rollback | [Active context](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/context.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) |
@@ -372,7 +373,7 @@ an installation failure.
 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.
+- **`SHARED_MEMORY.md` is bounded 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. Admission prioritizes critical operational state and never publishes beyond 48 lines/6 KiB; omitted events remain in the append-only authority and surface only as verifiable counts. 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.** `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; promotion preserves the selected event's JSON type, session, activation/epoch, and source turn.
 - **Registers are scoped.** `git.local-head`, handoffs, verdicts, and change status carry project, work-session, change, branch, or worktree scope. Two branches do not create a global conflict; only events in the same scope and causal lineage may advance automatically.
@@ -388,9 +389,9 @@ Codex uses `session_id`/`turn_id` plus transcript order, with no artificial caus
 
 ### Injection and budgets
 
-`CORE.md` is the only manual layer: it accepts up to 40 lines, warns from 35, keeps a 4 KiB ceiling, and caps each line at 320 characters. `SHARED_MEMORY.md` is generated exclusively by the projector and ledger; never edit it to repair state. `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; SHARED reserves up to 6 KiB. 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>`.
+`CORE.md` is the only manual layer: it accepts up to 40 lines, warns from 35, keeps a 4 KiB ceiling, and caps each line at 320 characters. `SHARED_MEMORY.md` is generated exclusively by the projector and ledger; never edit it to repair state. `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; SHARED reserves up to 48 lines/6 KiB. Under pressure, lessons are removed first, then non-current changes. CORE is never sliced and SHARED admits deterministic whole events rather than prefix-slicing; a missing, invalid, or over-budget layer becomes a visible, repairable `<wk_memory_error>`.
 
-`memory status --gate` and `validate-memory --vault` also check semantic coverage: they report a code, counts, and active/projected/missing keys. An empty v2 bundle is neutral; a missing projectable event, placeholders as the only content, or an unresolved decision link becomes an explicit degraded/blocking diagnosis without printing memory values.
+`memory status --gate` and `validate-memory --vault` also check semantic coverage: they report a code, counts, and active/projected/missing keys. An empty v2 bundle is neutral; a bounded omission that exactly reproduces ledger selection is an operational warning. An arbitrarily missing event, false count, placeholders as the only content, or an unresolved decision link remains explicitly degraded/blocking without printing memory values.
 
 `DIGEST.md` is no longer the operational handoff: it remains the `/brain-recall` bridge and legacy-vault fallback. A vault without SHARED receives CORE+DIGEST with a deprecation warning; migrate during the compatibility window:
 

package/docs/en/commands/context.md

@@ -0,0 +1,88 @@
+# Active context
+
+**English** · [Português](../../pt-BR/commands/context.md)
+
+## Purpose
+
+Switch the Git branch and the same session's causal scope together inside the current worktree,
+without opening a new session or weakening the guard.
+
+## When to use
+
+Use `context switch` when an active session must create or select another branch in the same
+worktree and continue mutating the repository after the transition.
+
+## When not to use
+
+Do not use it to move to another worktree, adopt an already-divergent scope, repair the registry,
+or replace `worktree create`. Those cases require a separate physical context or explicit diagnosis.
+
+## Prerequisites
+
+- A Git project bound to a Vault through `.wendkeep.json`.
+- An active session with a complete `project_scope` matching the current worktree.
+- Git on `PATH` and a branch accepted by `git check-ref-format --branch`.
+
+## Syntax
+
+```bash
+npx --no-install wendkeep context switch <branch> [--create] [--session <id>] [--project <root>] [--vault <vault>] [--json]
+```
+
+Without `--session`, exactly one active session must fully match the current scope. `--create`
+uses `git switch -c`; without it, the command follows `git switch` semantics.
+
+## Options and exit codes
+
+- `--create`: create the branch from the current HEAD.
+- `--session <id>`: select the causal session explicitly; recommended whenever selection is unclear.
+- `--project <root>` and `--vault <vault>`: select the binding and paths for manual use.
+- `--json`: emit status, session id, branch, HEAD, revision, and event without exposing the Vault.
+
+Exit `0` means the transition completed or the target was already active. Invalid usage,
+ambiguity, scope mismatch, conflict, Git failure, or rollback returns `2` with a
+`WENDKEEP_CONTEXT_*` code.
+
+## Examples
+
+```bash
+npx --no-install wendkeep context switch wk/auth --create
+npx --no-install wendkeep context switch main --session 019abc-session-id
+npx --no-install wendkeep context switch wk/auth --session 019abc-session-id --json
+```
+
+Do not replace it with the raw command below while the harness is active:
+
+```bash
+git switch -c wk/auth
+```
+
+The guard returns `WENDKEEP_CONTEXT_SWITCH_REQUIRED` before Git runs, preventing the next mutation
+from failing with a scope mismatch.
+
+## Expected result
+
+The command validates the initial scope under lock, switches branch, proves project, repository,
+remote, worktree, provider, and session id stayed unchanged, increments `context_revision`, and
+appends a `from/to` event to `context_transitions`. The active change, task lease, and existing
+authorizations are preserved.
+
+If validation or persistence fails after the switch, rollback restores the previous branch or
+detached HEAD; a branch created by the failed attempt is removed as well.
+
+## Common errors and diagnosis
+
+- `WENDKEEP_CONTEXT_AMBIGUOUS`: pass `--session <id>`; no candidate is selected silently.
+- `WENDKEEP_CONTEXT_SCOPE_MISMATCH` or `WENDKEEP_CONTEXT_SCOPE_CONFLICT`: return to the reserved
+  checkout or diagnose the session; the command never adopts a post-hoc divergence.
+- `WENDKEEP_CONTEXT_CONFLICT`: another active context occupies the target; use another
+  branch/worktree or close the competing context correctly.
+- `WENDKEEP_CONTEXT_GIT`: fix the branch, conflicting dirty state, or Git error and retry.
+- `WENDKEEP_CONTEXT_ROLLBACK_FAILED`: preserve Git and registry state and diagnose manually before
+  any new mutation.
+- `WENDKEEP_CONTEXT_SWITCH_REQUIRED`: replace the raw Git command with `wendkeep context switch`.
+
+## Next steps
+
+See [managed worktrees](worktrees.md) to create isolated checkouts and
+[changes and verification](changes-and-verification.md) to continue the lifecycle on the new branch.

package/docs/en/commands/memory.md

@@ -98,12 +98,19 @@ npx wendkeep validate-memory --vault <v2-vault>
   and its successor. Replay is CORE-aware, checkpoints use the physical ledger cursor, and the
   command neither rewrites ledger/CORE/notes nor consumes the outbox. Retrying the same applied
   decision is idempotent.
+- The projector deterministically admits whole events, prioritizing critical operational state up
+  to 48 lines/6144 bytes. `projection_mode`, `projected_events`, and `omitted_events` make the
+  selection verifiable; revision, cursor, and `state_hash` still cover the complete ledger. The
+  gate accepts only omissions that re-derive exactly from the same policy.
 - `memory rescope` is a dry run by default and lists only planned IDs, keys, and scopes. With
   `--apply`, it appends explicit project, work-session, change, branch, or worktree events while
   preserving historic bytes as the ledger prefix. Legacy `handoff.latest` events inside candidates
   are also rescoped individually when they carry proven session identity, separating independent
   workflows without selecting a winner. Ambiguities that remain inside one scope stay under human
   curation; retry returns `unchanged`.
+  If doctor reports structurally blocked memory, run `memory repair` first, confirm a green
+  `memory status --gate`, and only then return to the dry run; never apply rescope over an invalid
+  projection.
 - Registers such as `git.local-head`, `handoff.latest`, `quality.latest-*`, and
   `change.<slug>.status` compete only inside the same scope. Automatic resolution still requires
   the same project and causal lineage; incompatible decisions, constraints, and blockers remain

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

@@ -0,0 +1,86 @@
+# Contexto ativo
+
+**PT-BR** · [English](../../en/commands/context.md)
+
+## Objetivo
+
+Trocar a branch Git e a scope causal da mesma sessão juntas, dentro da worktree atual, sem abrir
+uma nova sessão e sem relaxar o guard.
+
+## Quando usar
+
+Use `context switch` quando uma sessão ativa precisa criar ou selecionar outra branch na mesma
+worktree e deve continuar mutando o repositório depois da troca.
+
+## Quando não usar
+
+Não use para mudar de worktree, adotar uma scope já divergente, reparar o registry ou substituir
+`worktree create`. Esses casos exigem outro contexto físico ou diagnóstico explícito.
+
+## Pré-requisitos
+
+- Projeto Git vinculado a um Vault por `.wendkeep.json`.
+- Sessão ativa com `project_scope` completa e correspondente à worktree atual.
+- Git disponível no `PATH` e branch válida segundo `git check-ref-format --branch`.
+
+## Sintaxe
+
+```bash
+npx --no-install wendkeep context switch <branch> [--create] [--session <id>] [--project <raiz>] [--vault <cofre>] [--json]
+```
+
+Sem `--session`, exatamente uma sessão ativa deve corresponder integralmente à scope atual. Use
+`--create` para executar `git switch -c`; sem a flag, a semântica é `git switch`.
+
+## Opções e códigos de saída
+
+- `--create`: cria a branch a partir do HEAD atual.
+- `--session <id>`: seleciona explicitamente a sessão causal; recomendado quando houver dúvida.
+- `--project <raiz>` e `--vault <cofre>`: selecionam binding e paths para uso manual.
+- `--json`: emite status, session id, branch, HEAD, revisão e evento sem expor o Vault.
+
+Exit `0` significa transição concluída ou destino já ativo. Uso inválido, ambiguidade,
+scope divergente, conflito, falha Git ou rollback retorna `2` com um código `WENDKEEP_CONTEXT_*`.
+
+## Exemplos
+
+```bash
+npx --no-install wendkeep context switch wk/auth --create
+npx --no-install wendkeep context switch main --session 019abc-session-id
+npx --no-install wendkeep context switch wk/auth --session 019abc-session-id --json
+```
+
+Não substitua pelo comando cru abaixo quando o harness estiver ativo:
+
+```bash
+git switch -c wk/auth
+```
+
+O guard responde `WENDKEEP_CONTEXT_SWITCH_REQUIRED` antes do Git, evitando que a próxima mutação
+falhe por mismatch.
+
+## Resultado esperado
+
+O comando valida a scope inicial sob lock, troca a branch, prova que projeto, repositório, remoto,
+worktree, provider e session id não mudaram, incrementa `context_revision` e anexa um evento
+`from/to` em `context_transitions`. Change ativa, task lease e autorizações são preservadas.
+
+Se qualquer validação ou persistência falhar depois do switch, o rollback restaura a branch ou
+detached HEAD anterior; uma branch criada pela tentativa também é removida.
+
+## Erros comuns e diagnóstico
+
+- `WENDKEEP_CONTEXT_AMBIGUOUS`: informe `--session <id>`; nenhuma candidata é escolhida em silêncio.
+- `WENDKEEP_CONTEXT_SCOPE_MISMATCH` ou `WENDKEEP_CONTEXT_SCOPE_CONFLICT`: volte ao checkout
+  reservado ou diagnostique a sessão; o comando não adota uma divergência posterior.
+- `WENDKEEP_CONTEXT_CONFLICT`: outro contexto ativo ocupa o destino; use outra branch/worktree ou
+  encerre corretamente o contexto concorrente.
+- `WENDKEEP_CONTEXT_GIT`: corrija a branch, dirty state conflitante ou erro do Git e repita.
+- `WENDKEEP_CONTEXT_ROLLBACK_FAILED`: preserve Git e registry e faça diagnóstico manual antes de
+  qualquer nova mutação.
+- `WENDKEEP_CONTEXT_SWITCH_REQUIRED`: troque o comando Git cru por `wendkeep context switch`.
+
+## Próximos passos
+
+Veja [worktrees gerenciadas](worktrees.md) para criar checkouts isolados e
+[changes e verificação](changes-and-verification.md) para continuar o lifecycle na nova branch.

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

@@ -98,12 +98,19 @@ npx wendkeep validate-memory --vault <cofre-v2>
   do attempt exato, salva backup do registry e limita a mutação ao attempt ambíguo e à sucessora.
   O replay é CORE-aware, usa cursor físico do ledger no checkpoint e não reescreve ledger, CORE ou
   notas, nem consome a outbox. Repetir a mesma decisão aplicada é idempotente.
+- O projector admite eventos completos de forma determinística e prioriza estado operacional
+  crítico até o limite de 48 linhas/6144 bytes. `projection_mode`, `projected_events` e
+  `omitted_events` tornam o recorte verificável; revision, cursor e `state_hash` continuam cobrindo
+  o ledger integral. O gate aceita somente a omissão que rederiva exatamente da mesma política.
 - `memory rescope` é dry-run por padrão e lista somente IDs, chaves e escopos planejados. Com
   `--apply`, anexa eventos explícitos de projeto, work session, change, branch ou worktree e mantém
   os bytes históricos como prefixo do ledger. Eventos legados de `handoff.latest` que participam
   de candidates também são reescopados individualmente quando possuem identidade de sessão
   comprovável: isso separa workflows independentes sem selecionar vencedor. Ambiguidades que
   permanecem no mesmo escopo continuam sob curadoria; uma repetição retorna `unchanged`.
+  Se o doctor indicar memória estruturalmente bloqueada, execute primeiro `memory repair`, confirme
+  `memory status --gate` verde e só então volte ao dry-run; não aplique rescope sobre uma projeção
+  inválida.
 - Registradores como `git.local-head`, `handoff.latest`, `quality.latest-*` e
   `change.<slug>.status` só competem dentro do mesmo escopo. Resolução automática ainda exige o
   mesmo projeto e linhagem causal; decisões, constraints e blockers incompatíveis permanecem sob

package/hooks/project-scope.mjs

@@ -115,11 +115,15 @@ function invocationOf(segment) {
   if (executable === 'git' || executable === 'git.exe' || executable === 'git.cmd') {
     return { kind: 'git', args: segment.slice(index + 1).map(unquote) };
   }
+  const args = segment.slice(index + 1).map(unquote);
+  if (isWendKeepContextSwitch(executable, args)) {
+    return { kind: 'context-switch', args };
+  }
   if (['rm', 'rm.exe', 'del', 'erase', 'remove-item', 'move-item', 'set-content', 'out-file', 'copy-item', 'new-item'].includes(executable)) {
-    return { kind: 'filesystem', args: segment.slice(index + 1).map(unquote) };
+    return { kind: 'filesystem', args };
   }
-  if (isPublicationInvocation(executable, segment.slice(index + 1).map(unquote))) {
-    return { kind: 'publication', args: segment.slice(index + 1).map(unquote) };
+  if (isPublicationInvocation(executable, args)) {
+    return { kind: 'publication', args };
   }
   return null;
 }
@@ -133,6 +137,24 @@ function isWendKeepPublication(args) {
   return command === 'publish' || command === 'release';
 }
 
+function isWendKeepContextSwitch(executable, args) {
+  let commandArgs = args;
+  if (['node', 'node.exe'].includes(executable)) {
+    const entrypoint = args.findIndex((arg) => executableName(arg) === 'wendkeep.mjs');
+    if (entrypoint < 0) return false;
+    commandArgs = args.slice(entrypoint + 1);
+  } else if (['npx', 'npx.cmd'].includes(executable)) {
+    const packageIndex = args.findIndex((arg) => ['wendkeep', 'wk'].includes(executableName(arg)));
+    if (packageIndex < 0) return false;
+    commandArgs = args.slice(packageIndex + 1);
+  } else if (!['wendkeep', 'wendkeep.cmd', 'wk', 'wk.cmd'].includes(executable)) {
+    return false;
+  }
+  const command = firstNonOption(commandArgs);
+  const commandIndex = commandArgs.findIndex((arg) => String(arg).toLowerCase() === command);
+  return command === 'context' && String(commandArgs[commandIndex + 1] || '').toLowerCase() === 'switch';
+}
+
 function isPublicationInvocation(executable, args) {
   if (['npm', 'npm.cmd', 'pnpm', 'pnpm.cmd', 'yarn', 'yarn.cmd', 'bun', 'bun.exe'].includes(executable)) {
     const command = firstNonOption(args);
@@ -214,12 +236,27 @@ export function scopeActionsForCommand(command) {
   const actions = [];
   for (const invocation of commandInvocations(command)) {
     if (invocation.kind === 'git') actions.push(gitAction(invocation.args));
+    if (invocation.kind === 'context-switch') actions.push('git:destructive');
     if (invocation.kind === 'filesystem') actions.push('filesystem:mutation');
     if (invocation.kind === 'publication') actions.push('publish');
   }
   return [...new Set(actions.filter(Boolean))];
 }
 
+export function commandChangesGitBranch(command) {
+  return commandInvocations(command).some((invocation) => {
+    if (invocation.kind !== 'git') return false;
+    const subcommand = firstGitSubcommand(invocation.args);
+    if (subcommand === 'switch') return true;
+    if (subcommand !== 'checkout') return false;
+    const subcommandIndex = invocation.args.findIndex((arg) => String(arg).toLowerCase() === 'checkout');
+    const checkoutArgs = invocation.args.slice(subcommandIndex + 1);
+    if (!checkoutArgs.length || checkoutArgs.includes('--')) return false;
+    if (checkoutArgs.includes('-p') || checkoutArgs.includes('--patch') || checkoutArgs.includes('--help')) return false;
+    return true;
+  });
+}
+
 export function commandChangesDirectory(command) {
   return shellSegments(command).some((segment) => {
     const executable = executableName(segment[0]);
@@ -333,7 +370,14 @@ export function concurrentScopeConflicts(expectedScope, activeSessions = [], cur
     if (!entry || String(sessionId) === String(current) || String(entry.sessionId || '') === String(current)) continue;
     if (entry.status && entry.status !== 'active') continue;
     const other = entry.project_scope || entry.projectScope || (entry.complete !== undefined ? entry : null);
-    if (!other || other.complete !== true) {
+    if (!other) {
+      conflicts.push({ sessionId: String(sessionId), reason: 'scope-unavailable' });
+      continue;
+    }
+    const leftWorktree = comparableScopeValue(expectedScope, 'worktree');
+    const rightWorktree = comparableScopeValue(other, 'worktree');
+    if (leftWorktree && rightWorktree && leftWorktree !== rightWorktree) continue;
+    if (other.complete !== true) {
       conflicts.push({ sessionId: String(sessionId), reason: 'scope-unavailable' });
       continue;
     }
@@ -343,8 +387,6 @@ export function concurrentScopeConflicts(expectedScope, activeSessions = [], cur
       return Boolean(left && right && left === right);
     });
     if (!sameRepositoryBranch) continue;
-    const leftWorktree = comparableScopeValue(expectedScope, 'worktree');
-    const rightWorktree = comparableScopeValue(other, 'worktree');
     if (!leftWorktree || !rightWorktree || leftWorktree === rightWorktree) {
       conflicts.push({ sessionId: String(sessionId), reason: 'same-repository-branch' });
     }
@@ -388,6 +430,9 @@ export function scopeDecision({
   if (concurrent.length) {
     return decision(host, `WENDKEEP_SCOPE_CONFLICT: há ${concurrent.length} sessão(ões) ativa(s) com a mesma raiz Git/branch ou escopo não comprovado; use um worktree distinto ou selecione explicitamente o projeto para criar uma nova lease.`);
   }
+  if (commandChangesGitBranch(command)) {
+    return decision(host, 'WENDKEEP_CONTEXT_SWITCH_REQUIRED: troca de branch Git crua deixaria a sessão fora da scope reservada; use `wendkeep context switch <branch> [--create] [--session <id>]`.');
+  }
   const authorized = Array.isArray(expectedScope.authorizedActions)
     ? expectedScope.authorizedActions
     : null;

package/hooks/vault-health.mjs

@@ -523,12 +523,21 @@ export function checkMemoryBundle(vaultBase, { registry } = {}) {
     const label = historicalHandoffs.length === 1
       ? '1 handoff histórico reparável'
       : `${historicalHandoffs.length} handoffs históricos reparáveis`;
-    warnings.push(
-      `${label}; sessões de origem estão encerradas e nenhuma versão precisa virar estado atual. `
-      + `Execute primeiro o dry-run: ${memoryRescopeCommand(vaultBase)}. `
-      + `Se a prévia estiver correta: ${memoryRescopeCommand(vaultBase, { apply: true })}. `
-      + `Dívida restante: ${memoryCurateAllCommand(vaultBase)}.`,
-    );
+    if (!bundle.ok) {
+      warnings.push(
+        `${label}; a memória está bloqueada e rescope não deve ampliar uma projeção inválida. `
+        + `Repare primeiro: ${memoryRepairCommand(vaultBase)}. `
+        + `Confirme a recuperação: ${memoryStatusCommand(vaultBase)}. `
+        + 'Somente depois de um gate verde reexecute o doctor para revisar o dry-run de rescope.',
+      );
+    } else {
+      warnings.push(
+        `${label}; sessões de origem estão encerradas e nenhuma versão precisa virar estado atual. `
+        + `Execute primeiro o dry-run: ${memoryRescopeCommand(vaultBase)}. `
+        + `Se a prévia estiver correta: ${memoryRescopeCommand(vaultBase, { apply: true })}. `
+        + `Dívida restante: ${memoryCurateAllCommand(vaultBase)}.`,
+      );
+    }
   }
   if (outbox.count) warnings.push(`${outbox.count} evento(s) pendente(s) na outbox; execute o projector quando seguro.`);
   if (ordinaryCandidates.length) warnings.push(`${ordinaryCandidates.length} candidate(s) aguardando curadoria humana.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.76.0",
+  "version": "0.76.2",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -41,7 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "precheck": "node --check src/worktree.mjs && node --check packages/vault/src/worktree-metadata.mjs",
+    "precheck": "node --check src/worktree.mjs && node --check src/context.mjs && node --check packages/vault/src/worktree-metadata.mjs",
     "check": "node --check scripts/release.mjs && node --check scripts/release-plan.mjs && node --check scripts/release-provenance.mjs && node --check scripts/run-scope.mjs && node --check src/release-provenance.mjs && node --check bin/wendkeep.mjs && node --check packages/cli/src/index.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/project-vault.mjs && node --check src/observer-auth.mjs && node --check src/observer-privacy.mjs && node --check src/observer-snapshot.mjs && node --check src/observer-store.mjs && node --check src/observer-memory.mjs && node --check src/observer-memory-publish.mjs && node --check src/observer-sql-store.mjs && node --check src/observer-sql-migrate.mjs && node --check src/observer-sql-publish.mjs && node --check src/observer-transcript-store.mjs && node --check src/observer-server.mjs && node --check src/observer.mjs && node --check src/observer-publish.mjs && node --check src/operating-profile.mjs && node --check src/profile.mjs && node --check src/flow.mjs && node --check src/work-kind.mjs && node --check src/delivery.mjs && node --check web/observer/app.mjs && node --check hooks/observer-publish.mjs && node --check hooks/evidence-context.mjs && node --check hooks/evidence-recall.mjs && node --check hooks/memory-scope.mjs && node --check hooks/operating-profile-runtime.mjs && node --check hooks/operating-profile-task-store.mjs && node --check hooks/flow-core.mjs && node --check hooks/flow-protected-policy.mjs && node --check hooks/git-snapshot.mjs && node --check hooks/vault-path-safety.mjs && node --check hooks/vault-runtime-store.mjs && node --check packages/harness/src/index.mjs && node --check packages/harness/src/flow-store.mjs && node --check packages/harness/src/operating-profile.mjs && node --check packages/harness/src/sensors-core.mjs && node --check packages/integrations/src/host-hooks.mjs && node --check packages/integrations/src/hook-envelope.mjs && node --check packages/integrations/src/prompt-content.mjs && node --check packages/integrations/src/transcript-usage.mjs && node --check packages/integrations/src/transcripts.mjs && node --check packages/integrations/src/session-identity.mjs && node --check packages/integrations/src/index.mjs && node --check packages/mcp/src/config.mjs && node --check packages/mcp/src/index.mjs && node --check packages/vault/src/index.mjs && node --check packages/vault/src/project-vault.mjs && node --check packages/vault/src/vault-path-safety.mjs && node --check packages/vault/src/locale.mjs && node --check packages/vault/src/memory-schema.mjs && node --check packages/vault/src/memory-mode.mjs && node --check packages/vault/src/memory-scope.mjs && node --check packages/vault/src/memory-candidate-policy.mjs && node --check packages/vault/src/evidence-recall.mjs && node --check packages/vault/src/memory-handoff.mjs && node --check packages/vault/src/memory-store.mjs && node --check packages/vault/src/validate-core.mjs && node --check packages/vault/src/validate-memory.mjs",
     "test": "node --test --test-concurrency=2",
     "test:core": "node scripts/run-scope.mjs core",

package/packages/cli/src/index.mjs

@@ -57,6 +57,8 @@ Usage:
   wendkeep worktree status [slug] [--json]
   wendkeep worktree open <slug> [--editor vscode] [--json]
                            Managed linked worktrees under .worktrees (branch default wk/<slug>).
+  wendkeep context switch <branch> [--create] [--session <id>] [--json]
+                           Switch Git branch and the causal session scope in the same worktree.
   wendkeep change <sub>        Change lifecycle: new [--simple|--guide] | use | bind <slug> --session <id> | continue | list | show |
                            status | done <id> | undone <id> | diff | archive [--force] | abandon | relink | backlink.
                            archive exige verdict (rode verify --deep); abandon descarta sem ADR.
@@ -200,6 +202,9 @@ async function main(argv) {
     } else if (cmd === 'profile') {
       const { PROFILE_HELP } = await import('../../../src/profile.mjs');
       process.stdout.write(PROFILE_HELP);
+    } else if (cmd === 'context') {
+      const { CONTEXT_HELP } = await import('../../../src/context.mjs');
+      process.stdout.write(CONTEXT_HELP);
     } else {
       process.stdout.write(HELP);
     }
@@ -241,6 +246,11 @@ async function main(argv) {
       process.exit(runWorktree(rest));
       break;
     }
+    case 'context': {
+      const { runContext } = await import('../../../src/context.mjs');
+      process.exit(runContext(rest));
+      break;
+    }
     case 'sync': {
       const { runSync } = await import('../../../src/sync.mjs');
       process.exit(await runSync(rest));

package/packages/vault/src/memory-schema.mjs

@@ -14,6 +14,17 @@ export const SHARED_SECTIONS = Object.freeze([
   'Último Handoff',
 ]);
 
+const SHARED_ADMISSION_SECTIONS = Object.freeze([
+  'Bloqueios',
+  'Objetivo Atual',
+  'Restrições Ativas',
+  'Decisões em Vigor',
+  'Próximas Ações',
+  'Riscos Conhecidos',
+  'Último Handoff',
+  'Estado Entregue',
+]);
+
 const AUTHORITIES = new Set(['verified', 'reported', 'candidate']);
 const OPERATIONS = new Set(['assert', 'replace', 'add', 'remove']);
 const ISO_INSTANT = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,3})?Z$/;
@@ -197,29 +208,63 @@ function defaultInstant(events) {
   return instants.at(-1) || new Date(0).toISOString();
 }
 
-/** Render the generated operational projection. Inputs are sanitized a second time. */
-export function renderSharedMemory({
-  revision = 0,
-  eventCursor = 'none',
-  events = [],
+function authorityPriority(authority) {
+  if (authority === 'verified') return 0;
+  if (authority === 'reported') return 1;
+  return 2;
+}
+
+function compareProjectionEvents(left, right) {
+  return authorityPriority(left?.authority) - authorityPriority(right?.authority)
+    || String(right?.observed_at || '').localeCompare(String(left?.observed_at || ''))
+    || String(left?.projection_key || left?.memory_key || '').localeCompare(
+      String(right?.projection_key || right?.memory_key || ''),
+    )
+    || String(left?.event_id || '').localeCompare(String(right?.event_id || ''));
+}
+
+function admissionOrder(events) {
+  const grouped = new Map(SHARED_ADMISSION_SECTIONS.map((section) => [section, []]));
+  for (const event of events) grouped.get(sectionFor(event?.memory_key)).push(event);
+  for (const bucket of grouped.values()) bucket.sort(compareProjectionEvents);
+
+  const ordered = [];
+  for (let round = 0; ; round += 1) {
+    let admitted = false;
+    for (const section of SHARED_ADMISSION_SECTIONS) {
+      const event = grouped.get(section)[round];
+      if (!event) continue;
+      ordered.push(event);
+      admitted = true;
+    }
+    if (!admitted) return ordered;
+  }
+}
+
+function renderSharedMemoryContent({
+  revision,
+  eventCursor,
+  allEvents,
+  projectedEvents,
   stateHash,
-  updatedAt,
-  reviewAfter,
-} = {}) {
-  const safeEvents = Array.isArray(events) ? events : [];
-  const updated = updatedAt || defaultInstant(safeEvents);
-  const review = reviewAfter || new Date(Date.parse(updated) + (7 * 24 * 60 * 60 * 1000)).toISOString();
+  updated,
+  review,
+}) {
   const grouped = new Map(SHARED_SECTIONS.map((section) => [section, []]));
-  for (const event of safeEvents) grouped.get(sectionFor(event.memory_key)).push(eventLine(event));
+  for (const event of projectedEvents) grouped.get(sectionFor(event.memory_key)).push(eventLine(event));
+  const omittedEvents = allEvents.length - projectedEvents.length;
 
   const lines = [
     '---',
     'schema_version: 2',
     `revision: ${Number.isInteger(revision) ? revision : 0}`,
     `event_cursor: ${sanitizeMemoryText(eventCursor || 'none')}`,
-    `state_hash: ${sanitizeMemoryText(stateHash || hashProjection(safeEvents))}`,
+    `state_hash: ${sanitizeMemoryText(stateHash || hashProjection(allEvents))}`,
     `updated_at: ${sanitizeMemoryText(updated)}`,
     `review_after: ${sanitizeMemoryText(review)}`,
+    `projection_mode: ${omittedEvents ? 'bounded' : 'complete'}`,
+    `projected_events: ${projectedEvents.length}`,
+    `omitted_events: ${omittedEvents}`,
     '---',
     '',
     '# SHARED_MEMORY — projeção operacional gerada',
@@ -231,6 +276,45 @@ export function renderSharedMemory({
   return `${lines.join('\n').trimEnd()}\n`;
 }
 
+function actualLineCount(text) {
+  const lines = text.split('\n');
+  return text.endsWith('\n') ? lines.length - 1 : lines.length;
+}
+
+function sharedFits(content) {
+  return actualLineCount(content) <= SHARED_LIMITS.lines
+    && Buffer.byteLength(content, 'utf8') <= SHARED_LIMITS.bytes;
+}
+
+/** Render the generated operational projection. Inputs are sanitized a second time. */
+export function renderSharedMemory({
+  revision = 0,
+  eventCursor = 'none',
+  events = [],
+  stateHash,
+  updatedAt,
+  reviewAfter,
+} = {}) {
+  const safeEvents = Array.isArray(events) ? events : [];
+  const updated = updatedAt || defaultInstant(safeEvents);
+  const review = reviewAfter || new Date(Date.parse(updated) + (7 * 24 * 60 * 60 * 1000)).toISOString();
+  const render = (projectedEvents) => renderSharedMemoryContent({
+    revision,
+    eventCursor,
+    allEvents: safeEvents,
+    projectedEvents,
+    stateHash,
+    updated,
+    review,
+  });
+  const projectedEvents = [];
+  for (const event of admissionOrder(safeEvents)) {
+    const trial = [...projectedEvents, event];
+    if (sharedFits(render(trial))) projectedEvents.push(event);
+  }
+  return render(projectedEvents);
+}
+
 function parseScalar(value) {
   if (/^-?\d+$/.test(value)) return Number(value);
   return value;
@@ -278,11 +362,6 @@ export function parseSharedMemory(content) {
   return { ok: errors.length === 0, errors, metadata, sections };
 }
 
-function actualLineCount(text) {
-  const lines = text.split('\n');
-  return text.endsWith('\n') ? lines.length - 1 : lines.length;
-}
-
 export function validateSharedMemory(content, { eventIds } = {}) {
   const text = String(content ?? '').replace(/\r\n/g, '\n');
   const parsed = parseSharedMemory(text);
@@ -306,6 +385,31 @@ export function validateSharedMemory(content, { eventIds } = {}) {
   for (const key of ['event_cursor', 'state_hash', 'updated_at', 'review_after']) {
     if (typeof metadata[key] !== 'string' || !metadata[key]) errors.push(`${key} é obrigatório.`);
   }
+  const projectionFields = ['projection_mode', 'projected_events', 'omitted_events'];
+  const projectionFieldCount = projectionFields.filter((key) => metadata[key] !== undefined).length;
+  if (projectionFieldCount && projectionFieldCount !== projectionFields.length) {
+    errors.push('Metadados bounded incompletos: projection_mode, projected_events e omitted_events são inseparáveis.');
+  } else if (projectionFieldCount === projectionFields.length) {
+    const projectedEventLines = [...parsed.sections.values()].flat()
+      .filter((line) => /^\s*-\s+\[[^\]]+\]/.test(line)).length;
+    if (!['complete', 'bounded'].includes(metadata.projection_mode)) {
+      errors.push('projection_mode deve ser complete ou bounded.');
+    }
+    if (!Number.isInteger(metadata.projected_events) || metadata.projected_events < 0) {
+      errors.push('projected_events deve ser inteiro não negativo.');
+    } else if (metadata.projected_events !== projectedEventLines) {
+      errors.push(`projected_events declara ${metadata.projected_events}, mas SHARED contém ${projectedEventLines} evento(s).`);
+    }
+    if (!Number.isInteger(metadata.omitted_events) || metadata.omitted_events < 0) {
+      errors.push('omitted_events deve ser inteiro não negativo.');
+    }
+    if (metadata.projection_mode === 'complete' && metadata.omitted_events !== 0) {
+      errors.push('projection_mode complete exige omitted_events igual a 0.');
+    }
+    if (metadata.projection_mode === 'bounded' && !(metadata.omitted_events > 0)) {
+      errors.push('projection_mode bounded exige omitted_events maior que 0.');
+    }
+  }
   for (const key of ['updated_at', 'review_after']) {
     if (typeof metadata[key] === 'string'
         && (!ISO_INSTANT.test(metadata[key]) || Number.isNaN(Date.parse(metadata[key])))) {

package/packages/vault/src/memory-store.mjs

@@ -10,6 +10,7 @@ import {
 } from 'node:fs';
 import { join } from 'node:path';
 import {
+  parseSharedMemory,
   renderSharedMemory,
   sanitizeMemoryText,
   validateMemoryEvent,
@@ -1007,6 +1008,7 @@ export function prepareMemoryProjection(vaultBase, allEvents) {
     stateHash: reduced.stateHash,
     updatedAt,
   });
+  const sharedMetadata = parseSharedMemory(shared).metadata;
   const candidates = reduced.candidates.map((item) => canonicalMemoryJson(item)).join('\n')
     + (reduced.candidates.length ? '\n' : '');
   return {
@@ -1018,6 +1020,8 @@ export function prepareMemoryProjection(vaultBase, allEvents) {
     stateHash: reduced.stateHash,
     checkpoint: reduced.checkpoint,
     candidates: reduced.candidates.length,
+    projectedEvents: sharedMetadata.projected_events ?? reduced.activeEvents.length,
+    omittedEvents: sharedMetadata.omitted_events ?? 0,
   };
 }
 

package/packages/vault/src/validate-memory.mjs

@@ -1,6 +1,8 @@
 import { readdirSync, readFileSync } from 'node:fs';
 import { basename, join, relative } from 'node:path';
-import { sanitizeMemoryText, validateMemoryEvent, validateSharedMemory } from './memory-schema.mjs';
+import {
+  parseSharedMemory, renderSharedMemory, sanitizeMemoryText, validateMemoryEvent, validateSharedMemory,
+} from './memory-schema.mjs';
 import { deriveMemoryProjection } from './memory-store.mjs';
 import { assertVaultPathSafe } from './vault-path-safety.mjs';
 import { validateCore } from './validate-core.mjs';
@@ -161,6 +163,10 @@ function sharedEventIds(content) {
   return ids;
 }
 
+function sameStringSet(left, right) {
+  return left.size === right.size && [...left].every((value) => right.has(value));
+}
+
 function walkDecisionFiles(root, vaultBase, output = []) {
   let entries;
   try { entries = readdirSync(root, { withFileTypes: true }); } catch { return output; }
@@ -255,13 +261,41 @@ function semanticMemoryHealth(vaultBase, { ledger, shared, candidates }) {
   const errors = [];
   const warnings = [];
   const codes = [];
+  const metadata = shared.metadata || {};
+  const boundedDeclared = metadata.projection_mode === 'bounded';
+  let boundedProjection = false;
+  if (boundedDeclared) {
+    const expectedContent = renderSharedMemory({
+      revision: metadata.revision,
+      eventCursor: metadata.event_cursor,
+      stateHash: metadata.state_hash,
+      updatedAt: metadata.updated_at,
+      reviewAfter: metadata.review_after,
+      events: replay.activeEvents,
+    });
+    const expectedIds = sharedEventIds(expectedContent);
+    const expectedMetadata = parseSharedMemory(expectedContent).metadata;
+    boundedProjection = sameStringSet(projectedIds, expectedIds)
+      && metadata.projected_events === expectedMetadata.projected_events
+      && metadata.omitted_events === expectedMetadata.omitted_events;
+    if (!boundedProjection) {
+      codes.push('MEMORY_SEMANTIC_COVERAGE_MISSING');
+      errors.push('[MEMORY_SEMANTIC_COVERAGE_MISSING] SHARED declara bounded, mas IDs ou contagens não reproduzem a seleção do ledger.');
+    }
+  }
 
   if (missingKeys.length && placeholderOnly) {
     codes.push('MEMORY_SEMANTIC_PLACEHOLDER_ONLY');
     errors.push(`[MEMORY_SEMANTIC_PLACEHOLDER_ONLY] SHARED contém somente placeholders para ${activeKeys.length} chave(s) ativa(s); candidates=${candidateCount}.`);
   } else if (missingKeys.length) {
-    codes.push('MEMORY_SEMANTIC_COVERAGE_MISSING');
-    errors.push(`[MEMORY_SEMANTIC_COVERAGE_MISSING] SHARED não cobre ${missingKeys.length} chave(s) ativa(s): ${missingKeys.join(', ')}.`);
+    if (boundedProjection) {
+      warnings.push(`[MEMORY_SEMANTIC_BOUNDED_PROJECTION] SHARED omite deterministicamente ${metadata.omitted_events} evento(s) do ledger dentro do budget.`);
+    } else if (!boundedDeclared) {
+      codes.push('MEMORY_SEMANTIC_COVERAGE_MISSING');
+      errors.push(`[MEMORY_SEMANTIC_COVERAGE_MISSING] SHARED não cobre ${missingKeys.length} chave(s) ativa(s): ${missingKeys.join(', ')}.`);
+    }
+  } else if (boundedProjection) {
+    warnings.push(`[MEMORY_SEMANTIC_BOUNDED_PROJECTION] SHARED omite deterministicamente ${metadata.omitted_events} evento(s) do ledger dentro do budget.`);
   }
   if (unresolvedLinks.length) {
     codes.push('MEMORY_SEMANTIC_DECISION_LINK_UNRESOLVED');
@@ -280,6 +314,9 @@ function semanticMemoryHealth(vaultBase, { ledger, shared, candidates }) {
   } else if (codes.length) {
     status = 'degraded';
     code = codes[0];
+  } else if (boundedProjection) {
+    status = 'bounded';
+    code = 'MEMORY_SEMANTIC_BOUNDED_PROJECTION';
   }
 
   return {

package/src/context.mjs

@@ -0,0 +1,297 @@
+import { spawnSync } from 'node:child_process';
+import { isAbsolute, resolve } from 'node:path';
+import {
+  mutateSessionRegistry,
+  readSessionRegistry,
+} from '../hooks/obsidian-common.mjs';
+import {
+  captureProjectScope,
+  compareProjectScopes,
+  concurrentScopeConflicts,
+  scopeForRegistry,
+} from '../hooks/project-scope.mjs';
+
+export const CONTEXT_HELP = `wendkeep context <subcommand>
+
+  switch <branch> [--create] [--session <id>] [--project <path>] [--vault <path>] [--json]
+
+Switches Git branch and the causal session scope together inside the same worktree.
+Without --session, exactly one active session must match the current scope.
+`;
+
+const VALUE_OPTIONS = new Set(['--project', '--vault', '--session']);
+const FLAG_OPTIONS = new Set(['--create', '--json']);
+
+function contextError(code, message) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function optionValue(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+function positionals(argv) {
+  const result = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (VALUE_OPTIONS.has(value)) { index += 1; continue; }
+    if ([...VALUE_OPTIONS].some((name) => value.startsWith(`${name}=`))) continue;
+    if (FLAG_OPTIONS.has(value)) continue;
+    if (value.startsWith('--')) throw contextError('WENDKEEP_CONTEXT_ARGS', `opção desconhecida: ${value}`);
+    result.push(value);
+  }
+  return result;
+}
+
+function validateArgv(argv) {
+  const seen = new Set();
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (FLAG_OPTIONS.has(value)) {
+      if (seen.has(value)) throw contextError('WENDKEEP_CONTEXT_ARGS', `opção duplicada: ${value}`);
+      seen.add(value);
+      continue;
+    }
+    if (VALUE_OPTIONS.has(value)) {
+      if (seen.has(value)) throw contextError('WENDKEEP_CONTEXT_ARGS', `opção duplicada: ${value}`);
+      seen.add(value);
+      const next = argv[index + 1];
+      if (!next || next.startsWith('--')) throw contextError('WENDKEEP_CONTEXT_ARGS', `${value} requer um valor`);
+      index += 1;
+      continue;
+    }
+    if (value.startsWith('--')) {
+      const name = value.split('=', 1)[0];
+      if (!VALUE_OPTIONS.has(name)) throw contextError('WENDKEEP_CONTEXT_ARGS', `opção desconhecida: ${name}`);
+      if (seen.has(name)) throw contextError('WENDKEEP_CONTEXT_ARGS', `opção duplicada: ${name}`);
+      seen.add(name);
+      if (!value.slice(name.length + 1)) throw contextError('WENDKEEP_CONTEXT_ARGS', `${name} requer um valor`);
+    }
+  }
+}
+
+function vaultOf(argv) {
+  const raw = optionValue(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!raw) throw contextError('WENDKEEP_CONTEXT_VAULT', 'binding de Vault ausente; use --vault <path>');
+  return isAbsolute(raw) ? raw : resolve(process.cwd(), raw);
+}
+
+function projectOf(argv) {
+  const raw = optionValue(argv, '--project') || process.cwd();
+  return isAbsolute(raw) ? raw : resolve(process.cwd(), raw);
+}
+
+function git(projectRoot, args, spawn = spawnSync) {
+  const result = spawn('git', args, { cwd: projectRoot, encoding: 'utf8', windowsHide: true });
+  if (result.error || result.status !== 0) {
+    const detail = String(result.stderr || result.error?.message || 'falhou').trim();
+    throw contextError('WENDKEEP_CONTEXT_GIT', `git ${args.join(' ')}: ${detail}`);
+  }
+  return String(result.stdout || '').trim();
+}
+
+function actualScope(projectRoot, expected, sessionId, spawn) {
+  return captureProjectScope({
+    input: { cwd: projectRoot },
+    projectRoot: expected?.projectRoot || projectRoot,
+    projectId: expected?.projectId || '',
+    provider: expected?.provider || '',
+    sessionId,
+    targetCwd: projectRoot,
+    spawn,
+  });
+}
+
+function matchingSessionIds(registry, projectRoot, spawn) {
+  const matches = [];
+  for (const [sessionId, entry] of Object.entries(registry.sessions || {})) {
+    if (entry?.status !== 'active' || entry.project_scope_conflict === true || !entry?.project_scope) continue;
+    const actual = actualScope(projectRoot, entry.project_scope, sessionId, spawn);
+    if (compareProjectScopes(entry.project_scope, actual).ok) matches.push(sessionId);
+  }
+  return matches;
+}
+
+function contextRevision(entry) {
+  return Number.isSafeInteger(entry?.context_revision) && entry.context_revision >= 0
+    ? entry.context_revision : 0;
+}
+
+function resolveSessionId(vaultBase, projectRoot, requested, spawn) {
+  const registry = readSessionRegistry(vaultBase);
+  if (requested) {
+    const entry = registry.sessions?.[requested];
+    if (!entry || entry.status !== 'active') {
+      throw contextError('WENDKEEP_CONTEXT_SESSION', `sessão ativa não encontrada: ${requested}`);
+    }
+    return { sessionId: requested, revision: contextRevision(entry) };
+  }
+  const matches = matchingSessionIds(registry, projectRoot, spawn);
+  if (matches.length !== 1) {
+    throw contextError(
+      'WENDKEEP_CONTEXT_AMBIGUOUS',
+      `${matches.length} sessões ativas correspondem à scope atual; informe --session <id>.`,
+    );
+  }
+  return {
+    sessionId: matches[0],
+    revision: contextRevision(registry.sessions[matches[0]]),
+  };
+}
+
+function rollbackGit(projectRoot, previous, createdBranch, spawn) {
+  const args = previous.branch.startsWith('detached:')
+    ? ['switch', '--detach', previous.head]
+    : ['switch', previous.branch];
+  git(projectRoot, args, spawn);
+  if (createdBranch) git(projectRoot, ['branch', '-D', createdBranch], spawn);
+}
+
+export function switchSessionContext({
+  vaultBase,
+  projectRoot = process.cwd(),
+  branch,
+  create = false,
+  sessionId = '',
+  spawn = spawnSync,
+  mutateRegistry = mutateSessionRegistry,
+  now = () => new Date(),
+} = {}) {
+  const target = String(branch || '').trim();
+  if (!target) throw contextError('WENDKEEP_CONTEXT_ARGS', 'switch requer <branch>');
+  git(projectRoot, ['check-ref-format', '--branch', target], spawn);
+  const selected = resolveSessionId(vaultBase, projectRoot, sessionId, spawn);
+  const selectedSessionId = selected.sessionId;
+  let switched = false;
+  let previous = null;
+
+  try {
+    return mutateRegistry(vaultBase, (registry) => {
+      const entry = registry.sessions?.[selectedSessionId];
+      if (!entry || entry.status !== 'active') {
+        throw contextError('WENDKEEP_CONTEXT_SESSION', `sessão ativa não encontrada: ${selectedSessionId}`);
+      }
+      if (entry.project_scope_conflict === true || !entry.project_scope) {
+        throw contextError('WENDKEEP_CONTEXT_SCOPE_CONFLICT', 'a sessão possui scope ausente ou conflitante');
+      }
+      const currentRevision = contextRevision(entry);
+      if (currentRevision !== selected.revision) {
+        throw contextError(
+          'WENDKEEP_CONTEXT_CAS_MISMATCH',
+          `context_revision mudou de ${selected.revision} para ${currentRevision}; repita com estado fresco`,
+        );
+      }
+      const expected = entry.project_scope;
+      const actual = actualScope(projectRoot, expected, selectedSessionId, spawn);
+      const comparison = compareProjectScopes(expected, actual);
+      if (!comparison.ok) {
+        throw contextError(
+          'WENDKEEP_CONTEXT_SCOPE_MISMATCH',
+          `scope atual diverge da reserva (${comparison.mismatches.join(', ')})`,
+        );
+      }
+      if (actual.branch === target && !create) {
+        return {
+          status: 'unchanged', session_id: selectedSessionId, branch: target,
+          head: actual.head, revision: currentRevision,
+        };
+      }
+
+      previous = { branch: actual.branch, head: actual.head };
+      git(projectRoot, create ? ['switch', '-c', target] : ['switch', target], spawn);
+      switched = true;
+      const next = actualScope(projectRoot, expected, selectedSessionId, spawn);
+      const identity = compareProjectScopes({ ...expected, branch: next.branch }, next);
+      if (!identity.ok || next.branch !== target || next.worktree !== actual.worktree) {
+        const mismatches = [...identity.mismatches, ...(next.branch === target ? [] : ['scope.branch'])];
+        throw contextError(
+          'WENDKEEP_CONTEXT_IDENTITY_CHANGED',
+          `a transição saiu da identidade reservada (${[...new Set(mismatches)].join(', ')})`,
+        );
+      }
+      const conflicts = concurrentScopeConflicts(
+        next,
+        Object.entries(registry.sessions || {}).filter(([, candidate]) => candidate?.status === 'active'),
+        selectedSessionId,
+      );
+      if (conflicts.length) {
+        throw contextError(
+          'WENDKEEP_CONTEXT_CONFLICT',
+          `o destino conflita com ${conflicts.length} contexto(s) ativo(s): ${conflicts.map((item) => item.sessionId).join(', ')}`,
+        );
+      }
+
+      const revision = currentRevision + 1;
+      const at = now().toISOString();
+      const transition = {
+        revision,
+        operation: create ? 'create' : 'switch',
+        from: { branch: actual.branch, head: actual.head },
+        to: { branch: next.branch, head: next.head },
+        worktree: next.worktree,
+        at,
+      };
+      const {
+        project_scope_conflict: _conflict,
+        project_scope_conflict_fields: _conflictFields,
+        project_scope_observed: _observed,
+        ...preserved
+      } = entry;
+      registry.sessions[selectedSessionId] = {
+        ...preserved,
+        project_scope: scopeForRegistry(next, { authorizedActions: expected.authorizedActions }),
+        context_revision: revision,
+        context_transitions: [...(Array.isArray(entry.context_transitions) ? entry.context_transitions : []), transition],
+        last_seen: at,
+        updated_at: at,
+      };
+      return {
+        status: 'switched', session_id: selectedSessionId, branch: next.branch,
+        head: next.head, revision, transition,
+      };
+    });
+  } catch (error) {
+    if (switched && previous) {
+      try {
+        rollbackGit(projectRoot, previous, create ? target : '', spawn);
+      } catch (rollbackError) {
+        throw contextError(
+          'WENDKEEP_CONTEXT_ROLLBACK_FAILED',
+          `${error.code || 'WENDKEEP_CONTEXT_FAILED'}: ${error.message}; rollback: ${rollbackError.message}`,
+        );
+      }
+    }
+    throw error;
+  }
+}
+
+function output(result, json) {
+  if (json) process.stdout.write(`${JSON.stringify(result)}\n`);
+  else process.stdout.write(`context ${result.status}: ${result.branch} (session ${result.session_id}; revision ${result.revision})\n`);
+}
+
+export function runContext(argv = []) {
+  try {
+    validateArgv(argv);
+    const [sub, branch, ...extra] = positionals(argv);
+    if (sub !== 'switch' || !branch || extra.length) {
+      throw contextError('WENDKEEP_CONTEXT_ARGS', 'use: wendkeep context switch <branch> [--create] [--session <id>]');
+    }
+    const result = switchSessionContext({
+      vaultBase: vaultOf(argv),
+      projectRoot: projectOf(argv),
+      branch,
+      create: argv.includes('--create'),
+      sessionId: optionValue(argv, '--session'),
+    });
+    output(result, argv.includes('--json'));
+    return 0;
+  } catch (error) {
+    process.stderr.write(`wendkeep context: ${error.code || 'WENDKEEP_CONTEXT_FAILED'}: ${error.message}\n`);
+    return 2;
+  }
+}