wendkeep 0.76.9 → 0.78.0

package/CHANGELOG.md

@@ -4,6 +4,45 @@ 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.78.0] — 2026-08-22
+
+### Added
+
+- **Evidence Envelope v2.** `verify` liga cada prova a projeto, repositório, worktree, work session,
+  branch, base/HEAD, árvore do índice e digest determinístico de staged/unstaged/untracked por
+  SHA-256 canônico; texto normaliza CRLF/CR para LF e binários preservam bytes.
+- **Proveniência por sensor.** Cada resultado registra comando efetivo sanitizado e hash,
+  timestamps, duração, exit code, digest da saída e tail sanitizado limitado; alteração da
+  configuração invalida o binding anterior.
+- **Diagnóstico causal.** `change status`, doctor, handoff e Observer distinguem evidência `bound`,
+  `stale`, `context-mismatch` e `legacy-unbound`; pacote deep e verdict carregam o mesmo
+  `evidenceEnvelopeId` e `evidenceBinding` completo e não podem ser reutilizados entre worktrees.
+
+### Changed
+
+- **Publicação fail-closed.** Mudança de HEAD durante os sensores preserva a evidência anterior e
+  retorna `WENDKEEP_EVIDENCE_HEAD_CHANGED`. Evidência, pacote, verdict trivial e seals são gravados
+  por temporário path-safe no mesmo diretório e rename atômico.
+- **Compatibilidade explícita.** Evidência v1 continua legível para histórico, mas sensores v1 não
+  satisfazem autoridade v2 no archive. README, schema e guias PT-BR/EN documentam formato,
+  normalização, recovery e vínculo do passe independente.
+
+## [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

package/README.en.md

@@ -147,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. |
 
@@ -239,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) |
@@ -531,7 +531,7 @@ explore → propose → apply (TDD) → verify → archive
 
 - **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`; `--simple` skips the design). `--guide` creates the compact GUIDE contract and omits automatic design/spec/ADR when `contract_impact:none`. It becomes the global *current* change. When the change declares `spec_impact: required`, you author the delta yourself at `specs/<capability>/spec.md` — there is no placeholder to delete. Multiple changes may remain open: `change list`/`status` and the hooks show every pending one, while commands without `--change` act on the current one alone. `change use <slug>` changes focus and `change continue <archived> <new>` creates an auditable continuation.
 - **Apply** — implement each `tarefas.md` task. Mark machine proof with one or more `[sensor:<id>]` tags on the same task: every distinct ID enters the gate once, in declaration order. Also mark satisfied requirements with one or more `[req:<ID>]` tags.
-- **Verify** — `wendkeep verify` runs the sensors your tasks declared (from `wendkeep.sensors.json` at the project root) and writes `evidencia.json`. A red `critical` fails the gate; a red `warning` is advisory. Failures retain only a bounded, sanitized diagnostic; green output is not persisted. `verify --deep` builds a self-contained package with complete effective requirements (living contract + this change's delta), so the independent verifier never needs to reconstruct unarchived requirements from `07-Specs`. Every change needs a `verdict.json` to archive; `verify --deep` writes a trivial one automatically when the change declares no `[req:]`.
+- **Verify** — `wendkeep verify` runs declared sensors and writes an **Evidence Envelope v2** to `evidencia.json`, SHA-256-bound to project/repository/worktree/session, HEAD, index tree, normalized worktree digest, tasks, effective spec, and sensor configuration. Each sensor records a sanitized command, execution window, duration, exit code, output digest, and a sanitized tail bounded to 2,000 characters. If HEAD changes during the run, no new envelope is published. `change status` reports `bound`, `stale`, `context-mismatch`, or `legacy-unbound`; v1 evidence remains readable but cannot satisfy v2 authority. The public schema is [`schema/wendkeep.evidence-envelope-v2.schema.json`](schema/wendkeep.evidence-envelope-v2.schema.json). `verify --deep` binds both package and verdict to the current `envelope_id`.
 - **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each applicable spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md` and moves the change to `_arquivo/`. GOVERN/ASSURE mint an ADR in `04-Decisões/`; compact GUIDE with no contract impact does not mint one automatically.
 
 > The gate blocks unless the scaffold is filled, no task is open, evidence is fresh, and every declared requirement is covered. **`--force` waives exactly one of those — the open-task check — and is the human's call, never the agent's.** An unfilled scaffold, a red critical sensor, stale evidence, an orphan requirement or a missing verdict block regardless.

package/README.md

@@ -147,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. |
 
@@ -239,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) |
@@ -531,7 +531,7 @@ explore → propose → apply (TDD) → verify → archive
 
 - **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`; `--simple` skips the design). `--guide` creates the compact GUIDE contract and omits automatic design/spec/ADR when `contract_impact:none`. It becomes the global *current* change. When the change declares `spec_impact: required`, you author the delta yourself at `specs/<capability>/spec.md` — there is no placeholder to delete. Multiple changes may remain open: `change list`/`status` and the hooks show every pending one, while commands without `--change` act on the current one alone. `change use <slug>` changes focus and `change continue <archived> <new>` creates an auditable continuation.
 - **Apply** — implement each `tarefas.md` task. Mark machine proof with one or more `[sensor:<id>]` tags on the same task: every distinct ID enters the gate once, in declaration order. Also mark satisfied requirements with one or more `[req:<ID>]` tags.
-- **Verify** — `wendkeep verify` runs the sensors your tasks declared (from `wendkeep.sensors.json` at the project root) and writes `evidencia.json`. A red `critical` fails the gate; a red `warning` is advisory. Failures retain only a bounded, sanitized diagnostic; green output is not persisted. `verify --deep` builds a self-contained package with complete effective requirements (living contract + this change's delta), so the independent verifier never needs to reconstruct unarchived requirements from `07-Specs`. Every change needs a `verdict.json` to archive; `verify --deep` writes a trivial one automatically when the change declares no `[req:]`.
+- **Verify** — `wendkeep verify` runs declared sensors and writes an **Evidence Envelope v2** to `evidencia.json`, SHA-256-bound to project/repository/worktree/session, HEAD, index tree, normalized worktree digest, tasks, effective spec, and sensor configuration. Each sensor records a sanitized command, execution window, duration, exit code, output digest, and a sanitized tail bounded to 2,000 characters. If HEAD changes during the run, no new envelope is published. `change status` reports `bound`, `stale`, `context-mismatch`, or `legacy-unbound`; v1 evidence remains readable but cannot satisfy v2 authority. The public schema is [`schema/wendkeep.evidence-envelope-v2.schema.json`](schema/wendkeep.evidence-envelope-v2.schema.json). `verify --deep` binds both package and verdict to the current `envelope_id`.
 - **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each applicable spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md` and moves the change to `_arquivo/`. GOVERN/ASSURE mint an ADR in `04-Decisões/`; compact GUIDE with no contract impact does not mint one automatically.
 
 > The gate blocks unless the scaffold is filled, no task is open, evidence is fresh, and every declared requirement is covered. **`--force` waives exactly one of those — the open-task check — and is the human's call, never the agent's.** An unfilled scaffold, a red critical sensor, stale evidence, an orphan requirement or a missing verdict block regardless.

package/docs/en/commands/changes-and-verification.md

@@ -76,7 +76,12 @@ npx wendkeep sensors add api-contracts "npm run test:contracts" --severity criti
 An archived change promotes its delta into the living spec when applicable and preserves proposal,
 tasks/proof, and design when present. GOVERN/ASSURE mint an ADR; compact GUIDE with no contract
 impact does not mint one automatically. Archive passes only with closed tasks, green required
-sensors, and a fresh verdict.
+sensors, and a fresh verdict bound to the same Evidence Envelope v2. V1 evidence is reported as
+`legacy-unbound`; `change status <slug>` also diagnoses `bound`, `stale`, and `context-mismatch`.
+Archive compares the package/verdict `evidenceEnvelopeId` and complete `evidenceBinding` with the
+proven checkout. On a mismatch, return to the correct worktree/session and rerun `verify`,
+`verify --deep`, and `wk-verify`. Fields, text/binary normalization, error codes, and recovery are
+detailed in the [verify guide](verify.md).
 
 ## Tool-scope fence
 
@@ -105,6 +110,8 @@ selection/lease; never carry authorization from another conversation.
 - Sensor not executed: keep one or more `[sensor:id]` tags on the same checkbox line. Every
   distinct ID on that line is required and runs once, in declaration order.
 - Stale evidence: rerun `verify` and `verify --deep` after task/spec edits.
+- Evidence from another worktree/session: return to the correct causal context; it cannot satisfy
+  the current archive even when every sensor is green.
 - Rebase conflict: resolve the delta or use `--accept-current` only when that is the decision.
 
 ## Next steps

package/docs/en/commands/verify.md

@@ -42,7 +42,8 @@ npx wendkeep change use <slug>
 - **Exit 0:** all required sensors passed and evidence was written.
 - **Exit 1:** the gate ran, but at least one critical sensor was red or a mutant survived.
 - **Exit 2:** invalid usage/context, including `no change (--change or active)`, missing vault,
-  unknown change, or invalid `wendkeep.sensors.json`.
+  unknown change, a project outside a Git repository, invalid `wendkeep.sensors.json`, or
+  `WENDKEEP_EVIDENCE_HEAD_CHANGED`.
 
 `verify --deep` writes `verificacao.json`; it does not replace the reviewer. The `wk-verify` skill
 must be run by a different author and writes `verdict.json`.
@@ -72,10 +73,22 @@ npx wendkeep memory status --gate --vault .MyApp-vault
 
 ## Expected result
 
-`evidencia.json` contains sensor results and a seal binds proof to the current `tarefas.md` hash.
-When a sensor is red, its entry receives only a local, sanitized diagnostic bounded to 2,000
-characters; stdout/stderr from green sensors is not persisted. Deep mode packages requirements,
-tasks, and evidence for read-only review; the verdict covers every `[req:]` before archive.
+`evidencia.json` follows the [public v2 schema](../../../schema/wendkeep.evidence-envelope-v2.schema.json).
+The envelope binds `project_id`, `repository_id`, `worktree_id`, `work_session_id`, change, and
+branch to `base_sha`, `head_sha`, `index_tree_sha`, `worktree_digest`, tasks, effective spec, and
+sensor configuration with complete SHA-256 digests. The worktree digest covers staged, unstaged,
+untracked, rename, and delete state; paths use `/`, text normalizes CRLF/CR to LF, and binaries keep
+their bytes. Binary classification honors Git `binary`/`-text` attributes and known binary
+extensions (including `.bin`); ignored files are excluded.
+
+Each sensor records its sanitized command and hash, start/end, duration, exit code, output digest,
+and a sanitized tail bounded to 2,000 characters. Authority artifacts publish through a path-safe
+temporary in the same directory and an atomic rename. In deep mode, `verificacao.json` and
+`verdict.json` carry the same `evidenceEnvelopeId` and complete `evidenceBinding`; the independent
+reviewer must preserve both.
+
+V1 evidence remains readable as `legacy-unbound`, never as equivalent authority. Run
+`wendkeep change status <slug>` to inspect `bound`, `stale`, or `context-mismatch`.
 
 ## Common errors and diagnosis
 
@@ -85,6 +98,10 @@ tasks, and evidence for read-only review; the verdict covers every `[req:]` befo
 - Red gate: inspect the bounded `note` field on the `evidencia.json` entry, fix the cause, and
   rerun; never choose `archive --force` on your own.
 - Missing/stale verdict: regenerate `--deep` and request a fresh independent pass.
+- `WENDKEEP_EVIDENCE_HEAD_CHANGED`: HEAD moved while sensors ran; stabilize the checkout and rerun.
+  The previous evidence was not replaced.
+- `legacy-unbound`, `stale`, or `context-mismatch`: return to the correct worktree/session, recover
+  the context when needed, and rerun `verify` plus `verify --deep`.
 - Surviving mutants: strengthen the discriminating test; after three rounds, review manually.
 
 ## Next steps

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/changes-and-verification.md

@@ -76,7 +76,12 @@ npx wendkeep sensors add api-contracts "npm run test:contracts" --severity criti
 A change arquivada move seu delta para o spec vivo quando aplicável e preserva proposta,
 tarefas/evidência e design quando existente. GOVERN/ASSURE geram ADR; GUIDE compacta sem impacto
 de contrato não gera ADR automático. O archive só passa com tarefas fechadas, sensores exigidos
-verdes e verdict atual.
+verdes e verdict atual ligado ao mesmo Evidence Envelope v2. Evidência v1 é mostrada como
+`legacy-unbound`; `change status <slug>` também diagnostica `bound`, `stale` e `context-mismatch`.
+O archive compara `evidenceEnvelopeId` e o `evidenceBinding` completo de package/verdict com o
+checkout provado. Se houver divergência, volte à worktree/sessão correta e rode `verify`,
+`verify --deep` e `wk-verify` novamente. Campos, normalização textual/binária, códigos e recovery
+estão detalhados no [guia de verify](verify.md).
 
 ## Cerca de escopo para ferramentas
 
@@ -105,6 +110,8 @@ exige uma nova seleção/lease; não use autorização de outra conversa.
 - Sensor não executado: mantenha uma ou mais tags `[sensor:id]` na mesma linha do checkbox. Todos
   os IDs distintos dessa linha são exigidos e executados uma vez, na ordem declarada.
 - Evidência stale: rode novamente `verify` e `verify --deep` depois de alterar tarefas/spec.
+- Evidência de outra worktree/sessão: retorne ao contexto causal correto; ela não satisfaz o
+  archive atual mesmo que todos os sensores estejam verdes.
 - Rebase em conflito: resolva o delta ou use `--accept-current` apenas quando isso for a decisão.
 
 ## Próximos passos

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

@@ -43,7 +43,8 @@ npx wendkeep change use <slug>
 - **Exit 1:** o gate executou, mas ao menos um sensor crítico ficou vermelho ou um mutante
   sobreviveu.
 - **Exit 2:** uso/contexto inválido, como `no change (--change or active)`, vault ausente,
-  change inexistente ou `wendkeep.sensors.json` inválido.
+  change inexistente, projeto fora de um repositório Git, `wendkeep.sensors.json` inválido ou
+  `WENDKEEP_EVIDENCE_HEAD_CHANGED`.
 
 `verify --deep` gera `verificacao.json`; ele não substitui o verificador. A skill `wk-verify`
 precisa ser executada por autor diferente e grava `verdict.json`.
@@ -73,11 +74,22 @@ npx wendkeep memory status --gate --vault .MeuApp-vault
 
 ## Resultado esperado
 
-`evidencia.json` contém resultados dos sensores e um selo liga a prova ao hash atual de
-`tarefas.md`. Quando um sensor fica vermelho, sua entrada recebe somente um diagnóstico local
-sanitizado e limitado a 2.000 caracteres; stdout/stderr de sensores verdes não é persistido. No
-deep, o pacote contém requisitos, tarefas e evidência suficientes para revisão read-only; o
-verdict cobre cada `[req:]` antes do archive.
+`evidencia.json` segue o [schema público v2](../../../schema/wendkeep.evidence-envelope-v2.schema.json).
+O envelope liga `project_id`, `repository_id`, `worktree_id`, `work_session_id`, change e branch a
+`base_sha`, `head_sha`, `index_tree_sha`, `worktree_digest`, tarefas, spec e configuração dos
+sensores por SHA-256 completo. O digest cobre staged, unstaged, untracked, rename e delete; paths
+usam `/`, texto normaliza CRLF/CR para LF e binários preservam bytes. A classificação binária
+respeita atributos Git `binary`/`-text` e extensões binárias conhecidas (incluindo `.bin`); arquivos
+ignorados não entram.
+
+Cada sensor registra comando sanitizado e seu hash, início/fim, duração, exit code, digest da saída
+e tail sanitizado de até 2.000 caracteres. Os artefatos são publicados por temporário path-safe no
+mesmo diretório e rename atômico. No deep, `verificacao.json` e `verdict.json` carregam o mesmo
+`evidenceEnvelopeId` e `evidenceBinding` completo; o verificador independente deve preservar ambos
+no verdict.
+
+Evidência v1 continua legível como `legacy-unbound`, nunca como autoridade equivalente. Rode
+`wendkeep change status <slug>` para ver `bound`, `stale` ou `context-mismatch`.
 
 ## Erros comuns e diagnóstico
 
@@ -87,6 +99,10 @@ verdict cobre cada `[req:]` antes do archive.
 - Gate vermelho: consulte o campo `note` limitado da entrada em `evidencia.json`, corrija a causa
   e repita; não use `archive --force` por conta própria.
 - Verdict stale/ausente: regenere `--deep` e peça novo passe independente.
+- `WENDKEEP_EVIDENCE_HEAD_CHANGED`: o HEAD mudou enquanto os sensores rodavam; estabilize o
+  checkout e repita. A evidência anterior não foi substituída.
+- `legacy-unbound`, `stale` ou `context-mismatch`: volte à worktree/sessão correta, recupere o
+  contexto se necessário e rode `verify` + `verify --deep` novamente.
 - Mutantes sobreviventes: fortaleça o teste discriminante; após três rodadas, revise manualmente.
 
 ## Próximos passos

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/change-core.mjs

@@ -15,6 +15,7 @@ import {
   resolveActiveContext,
   setActiveContextChange,
 } from './active-context-store.mjs';
+import { evidenceSensors } from '../packages/vault/src/evidence-envelope.mjs';
 
 export const ARCHIVE_DIR = '_arquivo';
 const POINTER = '.brain/CURRENT_CHANGE.md';
@@ -442,7 +443,7 @@ export function quickGateState(vaultBase, { context } = {}) {
   let redCritical = false;
   try {
     const ev = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8'));
-    redCritical = (Array.isArray(ev) ? ev : []).some((e) => e.status !== 'green' && (e.severity || 'critical') !== 'warning');
+    redCritical = evidenceSensors(ev).some((e) => e.status !== 'green' && (e.severity || 'critical') !== 'warning');
   } catch { /* sem/ilegível = não conta contra o nudge */ }
   let evidenceStale = false;
   try {