wendkeep 0.76.8 → 0.77.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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.77.0] — 2026-08-22
+
+### Added
+
+- **Fechamento comprovado de worktrees.** `worktree finish <slug> --pr <ref>` valida no GitHub que o
+  PR foi merged, cruza branch e merge commit com a base local, executa preflight de checkout,
+  sessões, delivery, outbox e handoff, e fecha somente o active context da worktree alvo.
+- **Cleanup auditável e retomável.** Reservas sob lock, remoção do ref local por CAS e receipts JSONL
+  append-only tornam o fechamento idempotente e retomável depois de crash; `doctor` diagnostica
+  estado interrompido, failed ou receipt inconsistente com recovery objetivo.
+- **Comandos destrutivos explícitos.** `worktree cleanup --merged` e `worktree prune` são dry-run por
+  padrão e exigem `--apply`; `worktree remove --reason` preserva branch não merged. Exclusão remota
+  continua proibida sem `--delete-remote` e falha fechado quando a branch diverge.
+- **Paridade operacional.** README e guia de worktrees PT-BR/EN documentam flags, blockers,
+  PowerShell/POSIX e recovery; a task local do VS Code oferece `WendKeep: Finish merged worktree`.
+
+## [0.76.9] — 2026-08-22
+
+### Fixed
+
+- **Injeção de change causal.** `brain-inject` e `change-context` usam o active context da sessão
+  para marcar `ATUAL`, calcular o hash da sentinela e preservar o mesmo foco em todos os degraus do
+  budget; o backlog continua global sem promover a change irmã pelo pointer legado.
+- **Store vazio fail-closed.** A presença de `active_contexts`, schema ou revision — inclusive
+  `active_contexts: {}` — impede fallback a `CURRENT_CHANGE.md` quando o contexto causal está ausente
+  ou ambíguo; compatibilidade legada permanece somente antes da inicialização contextual.
+- **Criação contextual preservada.** Operações mutáveis como `delivery start` continuam recebendo a
+  identidade causal antes de existir um context record, enquanto hooks read-only exigem o registro
+  existente e nunca publicam foco de sibling.
+
 ## [0.76.8] — 2026-08-22
 
 ### Added

package/README.en.md

@@ -116,6 +116,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. 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. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. `doctor` diagnoses orphaned active contexts, removed worktrees, and expired `request-stop` leases without writing; `context repair --key <key> --revision <n> --reason <text> --session <id>` revalidates under lock, closes only the ownerless/removed context or expires only its lease, while preserving the record and all historical memory. The change lifecycle uses `active_contexts`, identified by `repository_id` + `worktree_id` + `work_session_id`; two matching sessions fail with ambiguity instead of selecting silently, `CURRENT_CHANGE.md` is only a derived projection for one unambiguous context, and migration never invents a worktree or session identity. 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**.
+   Once `active_contexts` is initialized, `brain-inject` and `change-context` mark only the causal context's change as current; the backlog remains global, and an empty or ambiguous store never revives `CURRENT_CHANGE.md`.
 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,7 +147,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`. |
+| `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening/finishing 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. |
 
@@ -238,7 +239,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) |
+| **Managed worktrees** | `worktree create/list/status/open/finish/cleanup/remove/prune`, merge proof, preflight, and receipts | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
 | **Active context** | `active_contexts` by `repository_id`/`worktree_id`/`work_session_id`, causal transition, quarantine, and explicit recovery | [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) |
@@ -582,7 +583,7 @@ agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──
    (Claude/Codex)        (Node)      (02-Sessões/…)        (CORE+SHARED, ledger, backlinks)
 ```
 
-The agent's settings.json points each hook at `npx wendkeep hook …`; **in Claude Code** the change-lifecycle hooks instead run the installed script directly (`node` on `${CLAUDE_PROJECT_DIR}/node_modules/wendkeep/hooks/<name>.mjs`) when the package is present locally, skipping an npx resolve on every event. `.codex/hooks.json` mirrors the same groups with PascalCase event keys, but always uses the `npx` form (`${CLAUDE_PROJECT_DIR}` does not exist in Codex) and spells its timeout `timeoutSec` — a plain `timeout` is neither a field nor an error there, it silently falls through to a 600s default, so `init` migrates that legacy key in place. On `Stop`, wendkeep parses the session transcript, appends the turn, updates token/cost data, emits derived notes, and publishes the sanitized handoff to the memory outbox. On `SessionStart` — startup, `/clear`, and `/compact` — `brain-inject` injects CORE + SHARED, every open change with its pending tasks, the global current-change marker, project lessons, and a `<wk_process>` router. Claude, Codex, or another agent can therefore resume work started elsewhere without hiding the rest of the backlog.
+The agent's settings.json points each hook at `npx wendkeep hook …`; **in Claude Code** the change-lifecycle hooks instead run the installed script directly (`node` on `${CLAUDE_PROJECT_DIR}/node_modules/wendkeep/hooks/<name>.mjs`) when the package is present locally, skipping an npx resolve on every event. `.codex/hooks.json` mirrors the same groups with PascalCase event keys, but always uses the `npx` form (`${CLAUDE_PROJECT_DIR}` does not exist in Codex) and spells its timeout `timeoutSec` — a plain `timeout` is neither a field nor an error there, it silently falls through to a 600s default, so `init` migrates that legacy key in place. On `Stop`, wendkeep parses the session transcript, appends the turn, updates token/cost data, emits derived notes, and publishes the sanitized handoff to the memory outbox. On `SessionStart` — startup, `/clear`, and `/compact` — `brain-inject` injects CORE + SHARED, every open change with its pending tasks, the causal current-change marker, project lessons, and a `<wk_process>` router. The inventory remains global, but `CURRENT` and the sentinel hash come from the session's active context; `active_contexts: {}` fails closed instead of reviving `CURRENT_CHANGE.md`. Claude, Codex, or another agent can therefore resume work started elsewhere without hiding the rest of the backlog.
 
 The archive **gate** blocks unless: the change scaffold is filled (G0), no task is open (G1), every declared critical sensor is green (with fresh evidence), and a `verdict.json` is present and current. `--force` waives G1 only — G0 is inescapable by design (a placeholder change forced through once minted a fake ADR), and no flag turns a red sensor or a missing verdict green. The agent is instructed never to use it on its own.
 

package/README.md

@@ -116,6 +116,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. 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. If a divergence is already quarantined, `context status --session <id>` inventories sanitized `reserved`/`observed` candidates; `context recover --session <id> --select <reserved|observed> --revision <n> --reason <text>` requires an explicit choice, CAS, and current-checkout proof, failing closed before clearing the conflict if revalidation changes. `doctor` diagnoses orphaned active contexts, removed worktrees, and expired `request-stop` leases without writing; `context repair --key <key> --revision <n> --reason <text> --session <id>` revalidates under lock, closes only the ownerless/removed context or expires only its lease, while preserving the record and all historical memory. The change lifecycle uses `active_contexts`, identified by `repository_id` + `worktree_id` + `work_session_id`; two matching sessions fail with ambiguity instead of selecting silently, `CURRENT_CHANGE.md` is only a derived projection for one unambiguous context, and migration never invents a worktree or session identity. 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**.
+   Once `active_contexts` is initialized, `brain-inject` and `change-context` mark only the causal context's change as current; the backlog remains global, and an empty or ambiguous store never revives `CURRENT_CHANGE.md`.
 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,7 +147,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`. |
+| `--vscode-worktree-tasks` | Create a local, Git-excluded `.vscode/tasks.json` for creating/listing/opening/finishing 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. |
 
@@ -238,7 +239,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) |
+| **Managed worktrees** | `worktree create/list/status/open/finish/cleanup/remove/prune`, merge proof, preflight, and receipts | [Managed worktrees](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/worktrees.md) |
 | **Active context** | `active_contexts` by `repository_id`/`worktree_id`/`work_session_id`, causal transition, quarantine, and explicit recovery | [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) |
@@ -582,7 +583,7 @@ agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──
    (Claude/Codex)        (Node)      (02-Sessões/…)        (CORE+SHARED, ledger, backlinks)
 ```
 
-The agent's settings.json points each hook at `npx wendkeep hook …`; **in Claude Code** the change-lifecycle hooks instead run the installed script directly (`node` on `${CLAUDE_PROJECT_DIR}/node_modules/wendkeep/hooks/<name>.mjs`) when the package is present locally, skipping an npx resolve on every event. `.codex/hooks.json` mirrors the same groups with PascalCase event keys, but always uses the `npx` form (`${CLAUDE_PROJECT_DIR}` does not exist in Codex) and spells its timeout `timeoutSec` — a plain `timeout` is neither a field nor an error there, it silently falls through to a 600s default, so `init` migrates that legacy key in place. On `Stop`, wendkeep parses the session transcript, appends the turn, updates token/cost data, emits derived notes, and publishes the sanitized handoff to the memory outbox. On `SessionStart` — startup, `/clear`, and `/compact` — `brain-inject` injects CORE + SHARED, every open change with its pending tasks, the global current-change marker, project lessons, and a `<wk_process>` router. Claude, Codex, or another agent can therefore resume work started elsewhere without hiding the rest of the backlog.
+The agent's settings.json points each hook at `npx wendkeep hook …`; **in Claude Code** the change-lifecycle hooks instead run the installed script directly (`node` on `${CLAUDE_PROJECT_DIR}/node_modules/wendkeep/hooks/<name>.mjs`) when the package is present locally, skipping an npx resolve on every event. `.codex/hooks.json` mirrors the same groups with PascalCase event keys, but always uses the `npx` form (`${CLAUDE_PROJECT_DIR}` does not exist in Codex) and spells its timeout `timeoutSec` — a plain `timeout` is neither a field nor an error there, it silently falls through to a 600s default, so `init` migrates that legacy key in place. On `Stop`, wendkeep parses the session transcript, appends the turn, updates token/cost data, emits derived notes, and publishes the sanitized handoff to the memory outbox. On `SessionStart` — startup, `/clear`, and `/compact` — `brain-inject` injects CORE + SHARED, every open change with its pending tasks, the causal current-change marker, project lessons, and a `<wk_process>` router. The inventory remains global, but `CURRENT` and the sentinel hash come from the session's active context; `active_contexts: {}` fails closed instead of reviving `CURRENT_CHANGE.md`. Claude, Codex, or another agent can therefore resume work started elsewhere without hiding the rest of the backlog.
 
 The archive **gate** blocks unless: the change scaffold is filled (G0), no task is open (G1), every declared critical sensor is green (with fresh evidence), and a `verdict.json` is present and current. `--force` waives G1 only — G0 is inescapable by design (a placeholder change forced through once minted a fake ADR), and no flag turns a red sensor or a missing verdict green. The agent is instructed never to use it on its own.
 

package/docs/en/commands/context.md

@@ -117,6 +117,14 @@ unambiguous active context. With zero or multiple contexts it stays empty. Migra
 and never invents a worktree or session identity. The legacy pointer becomes a context only
 when one active session, a complete scope, and worktree metadata prove one identity.
 
+The `brain-inject` (`SessionStart`) and `change-context` (`UserPromptSubmit`) hooks resolve the same
+causal identity before marking a change as `CURRENT` or computing the sentinel hash. The backlog
+remains global and lists every other change as `OPEN`, but a divergent `CURRENT_CHANGE.md` never
+turns a sibling change into the session focus. The presence of `active_contexts`, its schema, or its
+revision — including `active_contexts: {}` — disables legacy fallback: a missing or ambiguous
+context fails closed without reviving the pointer. Fallback exists only before contextual-store
+initialization.
+
 ## Common errors and diagnosis
 
 - `WENDKEEP_CONTEXT_AMBIGUOUS`: pass `--session <id>`; no candidate is selected silently.

package/docs/en/commands/worktrees.md

@@ -4,23 +4,24 @@
 
 ## Purpose
 
-Create isolated linked worktrees that remain bound to the same project and canonical Vault,
-without copying private state into versioned files.
+Create and finish isolated linked worktrees that remain bound to the same project and canonical
+Vault, without copying private state into versioned files or discarding local work.
 
 ## 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.
+Use it to start isolated implementation work, list managed checkouts, diagnose a partial operation,
+open a worktree in VS Code, or clean it up after a provably merged PR.
 
 ## When not to use
 
-Do not use it to remove, merge, or self-merge worktrees. Those operations remain outside this
-capability.
+Do not use it to merge the PR, discard a dirty/untracked checkout, or delete a remote branch without
+explicit authorization. `finish` consumes an existing merge; it does not self-merge.
 
 ## 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.
+- Git on `PATH`; `finish` also requires authenticated `gh` access to query GitHub.
+- Opening also requires the VS Code `code` command.
 
 ## Syntax
 
@@ -29,48 +30,88 @@ npx --no-install wendkeep worktree create <slug> [--base <ref>] [--branch <name>
 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]
+npx --no-install wendkeep worktree finish <slug> [--pr <number|url>] [--delete-remote] [--open-main] [--json]
+npx --no-install wendkeep worktree cleanup --merged [--dry-run|--apply] [--json]
+npx --no-install wendkeep worktree remove <slug> --reason <text> [--json]
+npx --no-install wendkeep worktree prune [--dry-run|--apply] [--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.
+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.
+
+## Safe finish
+
+When `origin` exists, `finish` runs `git fetch --prune`, queries the PR through the GitHub adapter,
+and requires `MERGED`, a matching branch, and a merge commit reachable from the local base. The
+number/URL is associated with the registry. Before removal, preflight fails closed on dirty or
+untracked files, an active session, active delivery, memory outbox, or pending handoff.
+
+After reserving under lock, the command removes the linked worktree, closes only its active
+contexts, prunes, deletes the local ref with CAS, and appends a JSONL receipt in the Git common-dir.
+This accepts merge commits, squash, and rebase without `git branch -D`. Re-running the same proof is
+idempotent; when the directory vanished between steps, the interrupted reservation resumes.
+`doctor` reports interrupted/failed cleanup with an objective recovery command.
+
+`--delete-remote` is the only authorization to delete the remote branch. The branch must remain at
+the proven head; divergence or an unavailable network blocks the operation. An already-absent branch
+is idempotent success. `--open-main` opens the main worktree only after completion.
+
+## Cleanup, remove, and prune
+
+`cleanup --merged` and `prune` are dry-run by default. `--dry-run` makes that intent explicit; only
+`--apply` permits mutation. Plans are slug-sorted and do not change Git, registry, contexts, or
+receipts. `cleanup --merged` acts only on entries with an associated PR whose merge is revalidated.
+`remove --reason` is the auditable escape hatch for explicit abandonment: it waives merge proof but
+keeps every preflight and preserves both local and remote branches.
 
 ## 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.
+multi-process lock. It stores repository/worktree identity, canonical binding, PR, and transient
+cleanup state; `.wendkeep.json` stays unchanged. Receipts live at
+`wendkeep/worktree-cleanup-receipts-v1.jsonl`. `.worktrees/` is added to both the versioned ignore
+and the repository-private exclude. JSON `list`/`status` output exposes neither Vault paths nor
+contents.
 
 `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.
+after reservation remain `failed`; run `worktree status <slug>` and follow `recovery`. `doctor`
+also reports create or cleanup debt under `[worktrees]` without repairing it.
 
-## VS Code and exit codes
+## VS Code
 
-`--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.
+`--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, including
+**WendKeep: Finish merged worktree**; 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.
+Exit `0` means success. Usage, binding, safety, proof, Git, or editor failures return `2` with a
+stable `WENDKEEP_WORKTREE_*` code. No command merges or uses force to discard a checkout.
 
 ## Examples
 
-```bash
+PowerShell:
+
+```powershell
 npx --no-install wendkeep worktree create auth --open vscode
-npx --no-install wendkeep worktree status auth --json
-npx --no-install wendkeep worktree list
+npx --no-install wendkeep worktree finish auth --pr 72 --open-main
+npx --no-install wendkeep worktree cleanup --merged --dry-run --json
+```
+
+POSIX:
+
+```bash
+npx --no-install wendkeep worktree cleanup --merged --apply
+npx --no-install wendkeep worktree remove spike --reason "PR cancelled"
+npx --no-install wendkeep worktree prune --dry-run
 ```
 
 ## 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.
+`create auth` produces `.worktrees/auth` on branch `wk/auth`. After a proven merge, `finish` removes
+the checkout and local ref, closes only its active context, and preserves the Vault, sessions,
+evidence, and receipt.
 
 ## Common errors and diagnosis
 
@@ -79,13 +120,20 @@ the same `projectId` and Vault, while the main checkout remains clean.
 - `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_PR_INVALID`, `WENDKEEP_WORKTREE_PR_NOT_MERGED`,
+  `WENDKEEP_WORKTREE_PR_MISMATCH`, or `WENDKEEP_WORKTREE_PR_MERGE_UNREACHABLE`: correct/associate
+  the PR, update the local base, and retry without manually removing the worktree.
+- `WENDKEEP_WORKTREE_DIRTY`, `WENDKEEP_WORKTREE_ACTIVE_SESSION`,
+  `WENDKEEP_WORKTREE_ACTIVE_DELIVERY`, `WENDKEEP_WORKTREE_OUTBOX_PENDING`, or
+  `WENDKEEP_WORKTREE_HANDOFF_PENDING`: complete the recovery named by the blocker.
+- `WENDKEEP_WORKTREE_CLEANUP_BUSY`: another operation owns the reservation; if the directory is
+  already gone, retry the same command/proof to resume. Use `doctor` for failed/incomplete state.
+- `WENDKEEP_WORKTREE_REMOTE_UNAVAILABLE` or `WENDKEEP_WORKTREE_REMOTE_DIVERGED`: the local branch is
+  preserved; recover the network or review the divergence before authorizing again.
 - `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
 

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

@@ -114,6 +114,13 @@ contexto ativo inequívoco. Com zero ou múltiplos contextos, fica vazio. A migr
 não inventa uma identidade de worktree ou sessão. O ponteiro legado só vira contexto quando uma sessão
 ativa, scope completa e metadados da worktree provam uma única identidade.
 
+Os hooks `brain-inject` (`SessionStart`) e `change-context` (`UserPromptSubmit`) resolvem a mesma
+identidade causal antes de marcar uma change como `ATUAL` ou calcular o hash da sentinela. O backlog
+continua global e lista as demais changes como `ABERTA`, mas um `CURRENT_CHANGE.md` divergente nunca
+transforma a change irmã em foco da sessão. A presença de `active_contexts`, schema ou revision —
+inclusive `active_contexts: {}` — desativa o fallback legado: contexto ausente ou ambíguo falha
+fechado sem reativar o ponteiro. O fallback só existe antes da inicialização do store contextual.
+
 ## Erros comuns e diagnóstico
 
 - `WENDKEEP_CONTEXT_AMBIGUOUS`: informe `--session <id>`; nenhuma candidata é escolhida em silêncio.

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

@@ -4,23 +4,24 @@
 
 ## Objetivo
 
-Criar linked worktrees isoladas que continuam vinculadas ao mesmo projeto e Vault canônico,
-sem copiar estado privado para arquivos versionados.
+Criar e encerrar linked worktrees isoladas que continuam vinculadas ao mesmo projeto e Vault
+canônico, sem copiar estado privado para arquivos versionados nem descartar trabalho local.
 
 ## 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.
+Use ao iniciar uma implementação isolada, listar checkouts gerenciados, diagnosticar uma operação
+parcial, abrir uma worktree no VS Code ou limpá-la depois de um PR comprovadamente merged.
 
 ## Quando não usar
 
-Não use para remover, mesclar ou fazer self-merge de worktrees. Essas operações permanecem fora
-desta capability.
+Não use para fazer merge do PR, descartar checkout dirty/untracked nem remover branch remota sem
+autorização explícita. `finish` consome um merge já concluído; não faz self-merge.
 
 ## 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.
+- Git disponível no `PATH`; `finish` também requer `gh` autenticado para consultar o GitHub.
+- Para abertura, o comando `code` do VS Code deve existir.
 
 ## Sintaxe
 
@@ -29,46 +30,87 @@ npx --no-install wendkeep worktree create <slug> [--base <ref>] [--branch <nome>
 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]
+npx --no-install wendkeep worktree finish <slug> [--pr <número|url>] [--delete-remote] [--open-main] [--json]
+npx --no-install wendkeep worktree cleanup --merged [--dry-run|--apply] [--json]
+npx --no-install wendkeep worktree remove <slug> --reason <texto> [--json]
+npx --no-install wendkeep worktree prune [--dry-run|--apply] [--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.
+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.
+
+## Fechamento seguro
+
+`finish` executa `git fetch --prune` quando existe `origin`, consulta o PR por adapter GitHub e
+exige estado `MERGED`, branch coerente e merge commit alcançável pela base local. O número/URL fica
+associado ao registry. Antes da remoção, o preflight falha fechado diante de checkout dirty ou
+untracked, sessão ativa, delivery ativa, memory outbox ou handoff pendente.
+
+Depois da reserva sob lock, o comando remove a linked worktree, fecha somente seus active contexts,
+faz prune, apaga o ref local por CAS e grava receipt JSONL append-only no Git common-dir. Isso aceita
+merge commit, squash e rebase sem usar `git branch -D`. Reexecução com a mesma prova é idempotente;
+se a pasta sumiu entre etapas, a reserva interrompida é retomada. `doctor` mostra cleanup
+interrompido/failed e uma recuperação objetiva.
+
+`--delete-remote` é a única autorização para excluir a branch remota. A branch deve continuar no
+head comprovado; divergência ou rede indisponível bloqueia. Branch já ausente é sucesso idempotente.
+`--open-main` abre a worktree principal somente depois da conclusão.
+
+## Cleanup, remove e prune
+
+`cleanup --merged` e `prune` são dry-run por padrão. `--dry-run` apenas torna essa intenção
+explícita; somente `--apply` permite mutação. O plano é ordenado por slug e não altera Git,
+registry, contexts ou receipts. `cleanup --merged` atua apenas em entries com PR associado e merge
+revalidado. `remove --reason` é a saída auditável para abandono explícito: dispensa prova de merge,
+mas mantém todo o preflight e preserva as branches local e remota.
 
 ## 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.
+guarda identidade do repositório/worktree, binding canônico, PR e estado transitório de cleanup;
+`.wendkeep.json` permanece inalterado. Receipts ficam em
+`wendkeep/worktree-cleanup-receipts-v1.jsonl`. `.worktrees/` entra no ignore versionado e no exclude
+privado. A saída JSON de `list`/`status` não expõe path nem conteúdo do Vault.
 
 `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.
+Falhas depois da reserva ficam como `failed`; rode `worktree status <slug>` e siga `recovery`.
+`doctor` também lista dívida de criação ou cleanup em `[worktrees]` sem repará-la.
 
-## VS Code e códigos de saída
+## VS Code
 
 `--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.
+Use `init --vscode-worktree-tasks` ou `sync --vscode-worktree-tasks` para criar tarefas locais,
+incluindo **WendKeep: Finish merged worktree**; 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.
+Exit `0` indica sucesso. Erro de uso, binding, segurança, prova, Git ou editor retorna `2` com código
+estável `WENDKEEP_WORKTREE_*`. Nenhum comando faz merge ou usa force para descartar checkout.
 
 ## Exemplos
 
-```bash
+PowerShell:
+
+```powershell
 npx --no-install wendkeep worktree create auth --open vscode
-npx --no-install wendkeep worktree status auth --json
-npx --no-install wendkeep worktree list
+npx --no-install wendkeep worktree finish auth --pr 72 --open-main
+npx --no-install wendkeep worktree cleanup --merged --dry-run --json
+```
+
+POSIX:
+
+```bash
+npx --no-install wendkeep worktree cleanup --merged --apply
+npx --no-install wendkeep worktree remove spike --reason "PR cancelado"
+npx --no-install wendkeep worktree prune --dry-run
 ```
 
 ## 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.
+`create auth` produz `.worktrees/auth` na branch `wk/auth`. Depois do merge comprovado, `finish`
+remove o checkout e o ref local, fecha apenas seu active context e preserva Vault, sessões,
+evidências e receipt.
 
 ## Erros comuns e diagnóstico
 
@@ -77,13 +119,20 @@ mesmo `projectId` e Vault, e o checkout principal permanece limpo.
 - `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_PR_INVALID`, `WENDKEEP_WORKTREE_PR_NOT_MERGED`,
+  `WENDKEEP_WORKTREE_PR_MISMATCH` ou `WENDKEEP_WORKTREE_PR_MERGE_UNREACHABLE`: corrija/associe o PR,
+  atualize a base local e repita sem remover a worktree manualmente.
+- `WENDKEEP_WORKTREE_DIRTY`, `WENDKEEP_WORKTREE_ACTIVE_SESSION`,
+  `WENDKEEP_WORKTREE_ACTIVE_DELIVERY`, `WENDKEEP_WORKTREE_OUTBOX_PENDING` ou
+  `WENDKEEP_WORKTREE_HANDOFF_PENDING`: conclua a recuperação indicada pelo blocker.
+- `WENDKEEP_WORKTREE_CLEANUP_BUSY`: outra operação ainda possui a reserva; se a pasta já sumiu,
+  repita o mesmo comando/prova para retomar. Use `doctor` para reservations failed/incompletas.
+- `WENDKEEP_WORKTREE_REMOTE_UNAVAILABLE` ou `WENDKEEP_WORKTREE_REMOTE_DIVERGED`: a branch local é
+  preservada; recupere rede ou revise a divergência antes de autorizar novamente.
+- 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
 

package/hooks/active-context-handoff-evidence.mjs

@@ -1,7 +1,12 @@
 import { readSessionRegistry } from './obsidian-common.mjs';
-import { resolveActiveContext } from './active-context-store.mjs';
+import {
+  activeContextRegistryInitialized,
+  resolveActiveContext,
+} from './active-context-store.mjs';
 import { resolveRuntimeActiveContext } from '../src/active-context-runtime.mjs';
 
+export { activeContextRegistryInitialized } from './active-context-store.mjs';
+
 const IDENTITY_FIELDS = Object.freeze([
   ['work_session_id', 'workSessionId'],
   ['repository_id', 'repositoryId'],
@@ -26,12 +31,6 @@ function contextsOf(registry) {
     ? registry.active_contexts : {};
 }
 
-export function activeContextRegistryInitialized(registry = {}) {
-  return Object.hasOwn(registry, 'active_contexts')
-    || Object.hasOwn(registry, 'active_contexts_schema')
-    || Object.hasOwn(registry, 'active_contexts_revision');
-}
-
 function assertAuthority(identity, context) {
   if (!identity || !context || context.state !== 'active') {
     throw contextError(

package/hooks/active-context-store.mjs

@@ -11,6 +11,12 @@ const ID_PATTERN = /^[A-Za-z0-9._-]{1,160}$/;
 const SLUG_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,159}$/;
 const DELIVERY_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{1,100}$/;
 
+export function activeContextRegistryInitialized(registry = {}) {
+  return Object.hasOwn(registry, 'active_contexts')
+    || Object.hasOwn(registry, 'active_contexts_schema')
+    || Object.hasOwn(registry, 'active_contexts_revision');
+}
+
 function contextError(code, message) {
   const error = new Error(message);
   error.code = code;
@@ -254,7 +260,7 @@ export function migrateLegacyActiveContext(vaultBase, {
   const slug = legacyPointer(vaultBase);
   if (!slug) return { migrated: false, reason: 'no-pointer' };
   const registry = readSessionRegistry(vaultBase);
-  if (Object.keys(contextsOf(registry)).length) return { migrated: false, reason: 'already-initialized' };
+  if (activeContextRegistryInitialized(registry)) return { migrated: false, reason: 'already-initialized' };
   if (typeof identityForSession !== 'function') return { migrated: false, reason: 'identity-unavailable' };
 
   const candidates = [];