wendkeep 0.76.0 → 0.76.1

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.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) |

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) |

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.76.0",
+  "version": "0.76.1",
   "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/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;
+  }
+}