wendkeep 0.75.3 → 0.76.1

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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
+
+- **Worktrees gerenciadas e seguras.** `worktree create/list/status/open` cria linked worktrees
+  idempotentes sob `.worktrees`, com branch `wk/<slug>`, validação de path/ref e abertura opcional
+  em nova janela do VS Code. O registry privado no Git common-dir compartilha identidade e Vault
+  canônico sem alterar `.wendkeep.json`, usa lock multiprocesso e registra falhas recuperáveis.
+- **Integração operacional.** `doctor` reconcilia registry/Git, `init` e `sync` aceitam
+  `--vscode-worktree-tasks` sem sobrescrever preferências locais, e ignores/walkers excluem a raiz
+  gerenciada. Saídas humanas são bilíngues e `--json` preserva o boundary do Vault.
+
+### Fixed
+
+- **Gate staged sem falsos positivos.** O scanner reconhece códigos públicos `WENDKEEP_*`, limita
+  a allowlist de diagnósticos às superfícies de observabilidade e mantém bloqueio de identificadores
+  opacos; fixtures do worktree manager usam exclusivamente o namespace sintético `wk-fixture-*`.
+
 ## [0.75.3] — 2026-08-20
 
 ### Fixed

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`.
@@ -146,6 +146,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--no-companions` | Pin no companions. |
 | `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
 | `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
+| `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening worktrees; never overwrites an existing file. Also accepted by `sync`. |
 | `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
 | `--force` | Overwrite existing wendkeep config blocks. |
 
@@ -237,6 +238,8 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | Group | Use it for | Detailed guide |
 |---|---|---|
 | **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
+| **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`.
@@ -146,6 +146,7 @@ npx wendkeep init --no-companions --no-mcp --yes              # zero companions,
 | `--no-companions` | Pin no companions. |
 | `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
 | `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
+| `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening worktrees; never overwrites an existing file. Also accepted by `sync`. |
 | `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
 | `--force` | Overwrite existing wendkeep config blocks. |
 
@@ -237,6 +238,8 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | Group | Use it for | Detailed guide |
 |---|---|---|
 | **Installation and updates** | `init`, `sync`, companions, and the first project↔vault binding | [Installation and first use](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/getting-started.md) |
+| **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/en/commands/getting-started.md

@@ -27,7 +27,7 @@ Do not run `init --force` as a generic repair for memory or unreadable configura
 ```bash
 npm install --save-dev wendkeep
 npx wendkeep init [options]
-npx wendkeep sync [--project <root>] [--vault <vault>] [--profile <profile>] [--yes]
+npx wendkeep sync [--project <root>] [--vault <vault>] [--profile <profile>] [--yes] [--vscode-worktree-tasks]
 ```
 
 ## Options and exit codes
@@ -37,6 +37,8 @@ npx wendkeep sync [--project <root>] [--vault <vault>] [--profile <profile>] [--
 - `--profile <OFF|FLOW|GUIDE|GOVERN|ASSURE>` selects the Operating Profile; new installs use
   `GOVERN`, re-init/sync without the flag preserves the existing choice, and `OFF` is never inferred.
 - `--no-mcp`, `--no-colors`, and `--no-companions` disable optional integrations.
+- `--vscode-worktree-tasks` creates local VS Code tasks without overwriting `tasks.json`; `sync`
+  forwards the same flag to its `init` stage.
 - `--companions <csv>` explicitly enables companion integrations.
 - `--yes` accepts non-interactive defaults; `--force` refreshes managed blocks only.
 - Exit `0` means setup/sync completed. Any other exit identifies the failed stage. `sync` stops at

package/docs/en/commands/maintenance-and-diagnostics.md

@@ -37,6 +37,9 @@ npx --no-install wendkeep --help
   also fails on workflow attention, repairable debt, semantic degradation, and warnings.
 - `--scope core` checks the installation, binding, ledger, and Keep Core only. `--scope runtime`
   checks changes, sensors, and governance only. The default `all` reports both surfaces.
+- The `[worktrees]` section reconciles the private registry with Git and reports slugs in
+  `failed`, `missing`, or invalid-binding states. Under `--strict` this debt also fails; doctor
+  never performs the repair.
 - `doctor` uses human-readable output with `[integrity]` and `[memory]` sections, friendly
   categories, and a copyable next action. The `vault-health.mjs` hook remains the JSON surface for
   automation; neither surface applies curation.

package/docs/en/commands/worktrees.md

@@ -0,0 +1,93 @@
+# Managed worktrees
+
+**English** · [Português](../../pt-BR/commands/worktrees.md)
+
+## Purpose
+
+Create isolated linked worktrees that remain bound to the same project and canonical Vault,
+without copying private state into versioned files.
+
+## When to use
+
+Use it to start isolated implementation work, list managed checkouts, diagnose a partial create,
+or open an already-ready worktree in VS Code.
+
+## When not to use
+
+Do not use it to remove, merge, or self-merge worktrees. Those operations remain outside this
+capability.
+
+## Prerequisites
+
+- A Git repository whose project is already bound to its Vault through `.wendkeep.json`.
+- Git on `PATH`; opening also requires the VS Code `code` command.
+
+## Syntax
+
+```bash
+npx --no-install wendkeep worktree create <slug> [--base <ref>] [--branch <name>] [--open vscode|none] [--json]
+npx --no-install wendkeep worktree list [--json]
+npx --no-install wendkeep worktree status [<slug>] [--json]
+npx --no-install wendkeep worktree open <slug> [--editor vscode] [--json]
+```
+
+All commands accept `--project <root>`. By default, create uses `.worktrees/<slug>`, the detected
+base, and branch `wk/<slug>`. When configured, `worktrees.root` must be a
+non-empty relative path. Git validates slugs and branches; paths escaping the root or crossing a
+symlink/junction are rejected before mutation.
+
+## Options and exit codes
+
+The registry lives in the Git common-dir at `wendkeep/worktrees-v1.json`, protected by a
+multi-process lock. It stores repository/worktree identity and the canonical binding;
+`.wendkeep.json` stays unchanged. `.worktrees/` is added to both the versioned ignore and the
+repository-private exclude. JSON `list`/`status` output exposes neither Vault paths nor contents.
+For each worktree, human output shows its slug, identity, checkout path, branch, HEAD, state, and
+binding health.
+
+`create` is idempotent when slug, path, and branch already match. Collisions fail closed. Failures
+after reservation remain `failed`; run `worktree status <slug>` and follow the `recovery` field.
+`doctor` also reports this debt under `[worktrees]` without repairing it.
+
+## VS Code and exit codes
+
+`--open vscode` and `worktree open` validate `code --version`, then open a new window with
+`code -n`. Use `init --vscode-worktree-tasks` or `sync --vscode-worktree-tasks` to create local
+tasks; an existing or tracked `.vscode/tasks.json`, even when deleted in the checkout, is never
+overwritten.
+
+Exit `0` means success. Usage, binding, safety, Git, or editor failures return `2` with a stable
+`WENDKEEP_WORKTREE_*` code. The command never removes or merges a worktree.
+
+## Examples
+
+```bash
+npx --no-install wendkeep worktree create auth --open vscode
+npx --no-install wendkeep worktree status auth --json
+npx --no-install wendkeep worktree list
+```
+
+## Expected result
+
+`create auth` produces `.worktrees/auth` on branch `wk/auth`; the main and linked worktrees resolve
+the same `projectId` and Vault, while the main checkout remains clean.
+
+## Common errors and diagnosis
+
+- `WENDKEEP_WORKTREE_SLUG_INVALID`, `WENDKEEP_WORKTREE_BRANCH_INVALID`, or
+  `WENDKEEP_WORKTREE_ROOT_INVALID`: correct the input before retrying; no reservation is created.
+- `WENDKEEP_WORKTREE_PATH_OUTSIDE_ROOT` or `WENDKEEP_WORKTREE_PATH_SYMLINK_ESCAPE`: use a relative
+  root contained in the main worktree, without an intermediate symlink/junction.
+- `WENDKEEP_WORKTREE_COLLISION`: the slug, path, or branch represents different state; run `status`.
+- `WENDKEEP_WORKTREE_GIT_FAILED` or `WENDKEEP_WORKTREE_BASE_UNRESOLVED`: repair the Git state and
+  retry the command shown in `recovery`.
+- `WENDKEEP_WORKTREE_REGISTRY_*`, `WENDKEEP_WORKTREE_*_MISMATCH`, or `WENDKEEP_VAULT_*` errors:
+  preserve the artifacts and use `doctor` to diagnose the registry/binding.
+- `WENDKEEP_WORKTREE_EDITOR_NOT_FOUND` or `WENDKEEP_WORKTREE_EDITOR_OPEN_FAILED`: make `code`
+  available on PATH or use `--open none`.
+- `failed`/`missing` state: read `recovery` from `status --json` and doctor's `[worktrees]` section.
+
+## Next steps
+
+See [installation and first use](getting-started.md) for local VS Code tasks and
+[maintenance and diagnostics](maintenance-and-diagnostics.md) for doctor.

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/getting-started.md

@@ -27,7 +27,7 @@ Não rode `init --force` para tentar reparar memória ou uma configuração ileg
 ```bash
 npm install --save-dev wendkeep
 npx wendkeep init [opções]
-npx wendkeep sync [--project <raiz>] [--vault <cofre>] [--profile <perfil>] [--yes]
+npx wendkeep sync [--project <raiz>] [--vault <cofre>] [--profile <perfil>] [--yes] [--vscode-worktree-tasks]
 ```
 
 ## Opções e códigos de saída
@@ -37,6 +37,8 @@ npx wendkeep sync [--project <raiz>] [--vault <cofre>] [--profile <perfil>] [--y
 - `--profile <OFF|FLOW|GUIDE|GOVERN|ASSURE>` seleciona o Perfil de Operação; instalação nova usa
   `GOVERN`, re-init/sync sem a flag preserva a escolha existente e `OFF` nunca é inferido.
 - `--no-mcp`, `--no-colors` e `--no-companions` desativam integrações opcionais.
+- `--vscode-worktree-tasks` cria tarefas locais do VS Code sem sobrescrever `tasks.json`; `sync`
+  repassa a mesma flag ao seu estágio `init`.
 - `--companions <csv>` habilita companions explicitamente.
 - `--yes` aceita defaults não interativos; `--force` atualiza apenas blocos gerenciados.
 - Exit `0` indica instalação/sincronização concluída; exit diferente de zero identifica a etapa

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

@@ -37,6 +37,8 @@ npx --no-install wendkeep --help
   atenção de workflow, dívida reparável e memória degradada apropriadas para gate de CI/release.
 - `--scope core` verifica somente instalação, identidade, sessão e memória; `sync` usa esse escopo
   e não falha por change ainda em andamento. `--scope runtime` isola harness/governança.
+- O bloco `[worktrees]` reconcilia o registry privado com o Git e aponta slugs em `failed`,
+  `missing` ou com binding inválido. Em `--strict`, essa dívida também falha; o doctor não repara.
 - O `doctor` usa saída em formato humano, com blocos `[integridade]` e `[memória]`, categorias
   amigáveis e uma próxima ação copiável. O hook `vault-health.mjs` continua sendo a superfície JSON
   para automações; nenhum dos dois aplica curadoria.

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

@@ -0,0 +1,91 @@
+# Worktrees gerenciadas
+
+**PT-BR** · [English](../../en/commands/worktrees.md)
+
+## Objetivo
+
+Criar linked worktrees isoladas que continuam vinculadas ao mesmo projeto e Vault canônico,
+sem copiar estado privado para arquivos versionados.
+
+## Quando usar
+
+Use ao iniciar uma implementação isolada, listar checkouts gerenciados, diagnosticar uma criação
+parcial ou abrir uma worktree já pronta no VS Code.
+
+## Quando não usar
+
+Não use para remover, mesclar ou fazer self-merge de worktrees. Essas operações permanecem fora
+desta capability.
+
+## Pré-requisitos
+
+- Repositório Git com o projeto já vinculado ao Vault por `.wendkeep.json`.
+- Git disponível no `PATH`; para abertura, o comando `code` do VS Code também deve existir.
+
+## Sintaxe
+
+```bash
+npx --no-install wendkeep worktree create <slug> [--base <ref>] [--branch <nome>] [--open vscode|none] [--json]
+npx --no-install wendkeep worktree list [--json]
+npx --no-install wendkeep worktree status [<slug>] [--json]
+npx --no-install wendkeep worktree open <slug> [--editor vscode] [--json]
+```
+
+Todas aceitam `--project <raiz>`. O padrão cria `.worktrees/<slug>` a partir da base detectada e
+usa a branch `wk/<slug>`. `worktrees.root`, quando configurado, deve ser um
+path relativo não vazio. Slug e branch são validados pelo Git; paths que escapam da raiz ou
+atravessam symlink/junction são rejeitados antes da mutação.
+
+## Opções e códigos de saída
+
+O registry fica no Git common-dir, em `wendkeep/worktrees-v1.json`, sob lock multiprocesso. Ele
+guarda identidade do repositório/worktree e o binding canônico; `.wendkeep.json` permanece
+inalterado. `.worktrees/` entra no ignore versionado e no exclude privado do repositório. A saída
+JSON de `list`/`status` não expõe path nem conteúdo do Vault. A saída humana apresenta, por
+worktree, slug, identidade, path do checkout, branch, HEAD, estado e saúde do binding.
+
+`create` é idempotente quando slug, path e branch já correspondem. Colisões falham fechadas.
+Falhas depois da reserva ficam como `failed`; rode `worktree status <slug>` e siga o campo
+`recovery`. `doctor` também lista dívida em `[worktrees]` sem repará-la.
+
+## VS Code e códigos de saída
+
+`--open vscode` e `worktree open` validam `code --version` e abrem uma janela nova com `code -n`.
+Use `init --vscode-worktree-tasks` ou `sync --vscode-worktree-tasks` para criar tarefas locais;
+um `.vscode/tasks.json` existente ou rastreado, mesmo removido no checkout, nunca é sobrescrito.
+
+Exit `0` indica sucesso. Erro de uso, binding, segurança, Git ou editor retorna `2` com código
+estável `WENDKEEP_WORKTREE_*`. O comando nunca remove ou mescla uma worktree.
+
+## Exemplos
+
+```bash
+npx --no-install wendkeep worktree create auth --open vscode
+npx --no-install wendkeep worktree status auth --json
+npx --no-install wendkeep worktree list
+```
+
+## Resultado esperado
+
+`create auth` produz `.worktrees/auth` na branch `wk/auth`; main e linked worktree resolvem o
+mesmo `projectId` e Vault, e o checkout principal permanece limpo.
+
+## Erros comuns e diagnóstico
+
+- `WENDKEEP_WORKTREE_SLUG_INVALID`, `WENDKEEP_WORKTREE_BRANCH_INVALID` ou
+  `WENDKEEP_WORKTREE_ROOT_INVALID`: corrija a entrada antes de repetir; nenhuma reserva é criada.
+- `WENDKEEP_WORKTREE_PATH_OUTSIDE_ROOT` ou `WENDKEEP_WORKTREE_PATH_SYMLINK_ESCAPE`: use uma raiz
+  relativa contida no main worktree, sem symlink/junction intermediário.
+- `WENDKEEP_WORKTREE_COLLISION`: slug, path ou branch já representa outro estado; rode `status`.
+- `WENDKEEP_WORKTREE_GIT_FAILED` ou `WENDKEEP_WORKTREE_BASE_UNRESOLVED`: corrija o estado Git e
+  repita o comando indicado em `recovery`.
+- Erros `WENDKEEP_WORKTREE_REGISTRY_*`, `WENDKEEP_WORKTREE_*_MISMATCH` ou
+  `WENDKEEP_VAULT_*`: preserve os artefatos e use `doctor` para diagnosticar registry/binding.
+- `WENDKEEP_WORKTREE_EDITOR_NOT_FOUND` ou `WENDKEEP_WORKTREE_EDITOR_OPEN_FAILED`: disponibilize
+  `code` no PATH ou use `--open none`.
+- Estado `failed`/`missing`: leia `recovery` em `status --json` e o bloco `[worktrees]` do `doctor`.
+
+## Próximos passos
+
+Veja [instalação e primeiro uso](getting-started.md) para tarefas locais do VS Code e
+[manutenção e diagnóstico](maintenance-and-diagnostics.md) para o doctor.

package/hooks/flow-protected-policy.mjs

@@ -27,7 +27,7 @@ export const FLOW_PROTECTED_SCAN_POLICY = Object.freeze({
   maxDepth: 64,
   maxEntries: 100_000,
   excludedDirectoryNames: Object.freeze([
-    '.git', 'node_modules', '.pnpm-store', '.yarn', '.venv', 'venv',
+    '.git', '.worktrees', 'node_modules', '.pnpm-store', '.yarn', '.venv', 'venv',
     '__pycache__', '.pytest_cache', '.mypy_cache', '.ruff_cache', '.tox', '.nox',
   ]),
 });

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;