wendkeep 0.75.3 → 0.76.0

package/CHANGELOG.md

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

@@ -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,7 @@ 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) |
 | **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

@@ -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,7 @@ 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) |
 | **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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.75.3",
+  "version": "0.76.0",
   "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,6 +41,7 @@
     "node": ">=18"
   },
   "scripts": {
+    "precheck": "node --check src/worktree.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

@@ -1,5 +1,5 @@
 // wendkeep CLI — canonical private runtime.
-//   wendkeep init [--vault <path>] [--project <path>] [--no-mcp] [--yes] [--force]
+//   wendkeep init [--vault <path>] [--project <path>] [--no-mcp] [--yes] [--force] [--vscode-worktree-tasks]
 //   wendkeep hook <name>      (invoked by the agent's settings.json; pipes stdin/stdout)
 //   wendkeep doctor [--vault <path>]
 //   wendkeep --version | --help
@@ -33,6 +33,7 @@ Usage:
                            (default: none — opt in explicitly). dotcontext is legacy — the native a2 loop replaces it.
     --no-companions        Skip companion plugins/MCP entirely.
     --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
+    --vscode-worktree-tasks Create local, Git-excluded VS Code tasks for managed worktrees.
     --dotcontext-mcp <v>   dotcontext MCP placement: auto (default; skip project entry
                            if already global), project, or none.
     --dotcontext-hooks <v> dotcontext hooks: full (default), light (no PostToolUse), none.
@@ -46,10 +47,16 @@ Usage:
                            command — the three steps that repeat identically after every
                            package update. Stops at the first failing step. Install the
                            package first (npm i -D wendkeep@latest); a running process
-                           cannot replace itself. · --vault P · --profile <name> · --yes.
+                           cannot replace itself. · --vault P · --profile <name> · --yes
+                           · --vscode-worktree-tasks.
 
   wendkeep doctor [--vault P]  Health check. --scope core|runtime · --strict for CI/release.
   wendkeep observer <sub>     Local multi-project Observer: serve | register | publish | reconcile | status.
+  wendkeep worktree create <slug> [--base ref] [--branch name] [--open vscode|none] [--json]
+  wendkeep worktree list [--json]
+  wendkeep worktree status [slug] [--json]
+  wendkeep worktree open <slug> [--editor vscode] [--json]
+                           Managed linked worktrees under .worktrees (branch default wk/<slug>).
   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.
@@ -206,7 +213,7 @@ async function main(argv) {
     // `sync` starts with `init` and resolves the freshly bound Vault itself. Pre-resolving
     // here would prevent that repair step from reporting a corrupt binding as its own
     // first-stage failure (and could never make it as far as the guarded init).
-    && !['init', 'sync', 'hook', 'observer', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
+    && !['init', 'sync', 'worktree', 'hook', 'observer', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
     await preferProjectVault(rest);
   }
   switch (cmd) {
@@ -229,6 +236,11 @@ async function main(argv) {
       if (rest[0] !== 'serve') process.exit(observerExitCode);
       break;
     }
+    case 'worktree': {
+      const { runWorktree } = await import('../../../src/worktree.mjs');
+      process.exit(runWorktree(rest));
+      break;
+    }
     case 'sync': {
       const { runSync } = await import('../../../src/sync.mjs');
       process.exit(await runSync(rest));

package/packages/vault/src/index.mjs

@@ -1,4 +1,5 @@
 export * from './project-vault.mjs';
+export * from './worktree-metadata.mjs';
 export * from './vault-path-safety.mjs';
 export * from './locale.mjs';
 export * from './memory-schema.mjs';

package/packages/vault/src/project-vault.mjs

@@ -9,6 +9,7 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { basename, dirname, isAbsolute, join, parse, relative, resolve } from 'node:path';
+import { resolveWorktreeVaultBinding } from './worktree-metadata.mjs';
 
 export const PROJECT_CONFIG_FILE = '.wendkeep.json';
 export const PROJECT_MARKER_REL = '.brain/PROJECT.json';
@@ -203,7 +204,7 @@ export function resolveProjectVault({
     bindingFailure = error;
   }
   if (binding) {
-    const result = {
+    let result = {
       base: binding.base,
       source: 'project-config',
       projectRoot: binding.projectRoot,
@@ -211,7 +212,29 @@ export function resolveProjectVault({
       configPath: binding.configPath,
       config: binding.config,
     };
-    if (validateIdentity) validateMarker(result);
+    if (validateIdentity) {
+      try {
+        validateMarker(result);
+      } catch (error) {
+        const canUsePrivateBinding = error?.code === 'WENDKEEP_VAULT_MARKER_MISSING'
+          && !isAbsolute(binding.config.vault);
+        if (!canUsePrivateBinding) throw error;
+        const privateBinding = resolveWorktreeVaultBinding({
+          startDir: start,
+          projectId: binding.config.projectId,
+        });
+        if (!privateBinding) throw error;
+        result = {
+          ...result,
+          base: privateBinding.base,
+          source: 'worktree-registry',
+          projectRoot: privateBinding.projectRoot,
+          repositoryId: privateBinding.repositoryId,
+          registryPath: privateBinding.registryPath,
+        };
+        validateMarker(result);
+      }
+    }
     return result;
   }