wendkeep 0.87.0 → 0.89.0

package/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.89.0] — 2026-08-30
+
+### Added
+
+- **Bridges opcionais oficiais para Spec Kit e Superpowers.** Projeções read-only preservam IDs,
+  hashes e ownership canônico do WendKeep; adapters são habilitados separadamente, validam
+  versões compatíveis e degradam com diagnósticos tipados sem afetar o Core nativo.
+- **Prova externa vinculada ao Git e ao CI.** Dispatch deriva somente de contratos canônicos e
+  artifacts externos permanecem `reported` até que manifest, blob, task, sensor e Evidence
+  Envelope coincidam com o checkout versionado.
+
+### Security
+
+- **Autoridade única e drift fail-closed.** Ownership concorrente, projeção stale, hashes/paths
+  divergentes, claims fabricados e promoção autoafirmada para `verified` bloqueiam import,
+  dispatch e verify antes de qualquer execução externa.
+
+## [0.88.0] — 2026-08-29
+
+### Added
+
+- **Políticas oficiais e RBAC do Observer por projeto.** Captura de transcripts, uso, memória e
+  sync passa por policy única, redaction por classe/campo e matriz explícita de papéis e scopes;
+  tokens são armazenados somente por hash, escopados, expirados, revogáveis e rotacionáveis.
+- **Ciclo de vida auditável.** Retenção e purge idempotentes ficam disponíveis por CLI e endpoint,
+  com receipts retriáveis, tratamento de chegadas tardias e reconciliação segura do índice FTS.
+
+### Security
+
+- **Criptografia fail-closed no Observer.** Quando exigida, ingestão, outbox e publicação recusam
+  plaintext; o backfill protege dados legados antes de leituras, e backups de migração v5 usam
+  AES-256-GCM, manifest de integridade, permissões restritas e restore autenticado.
+- **Bootstrap remoto sem credencial irrestrita.** Server, MCP, CLI e Compose usam o registry
+  hash-only com projeto, papel, scopes e expiração explícitos, incluindo revogação e rotação.
+
 ## [0.87.0] — 2026-08-29
 
 ### Added

package/README.en.md

@@ -253,6 +253,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Native MCP** | semantic tools, effects/capabilities, stdio, schemas, pagination, budgets, audit, and client configuration | [Native MCP](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/mcp.md) |
 | **Evidence recall and embeddings** | cursor/byte budgets, bounded lexical/FTS sidecars, and an optional local plugin contract that is off by default | [Optional embedding plugin](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/evidence-embeddings.md) |
 | **Host capabilities** | versioned lifecycle/effect matrix, degraded mode, human waivers, and evidence/Observer coverage | [Host capabilities](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/capabilities.md) |
+| **Ecosystem bridges** | optional Spec Kit/Superpowers adapters, canonical baseline, single ownership, drift, and Git/CI/Envelope proof with an index/worktree-identical manifest | [Ecosystem bridges](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/ecosystem-bridges.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, Task Contracts, 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) |
@@ -261,7 +262,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
 | **Evidence-based commits** | `wendkeep commit`, tasks derived from contracts, tests only from canonical execution bound to the exact SHA, opt-in Git hooks, privacy, and remote range gate | [Commits](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/commit.md) |
-| **Local Observer** | `observer serve`, registration, incremental publication, `reconcile`, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
+| **Local Observer** | `observer serve`, scoped/expiring hash-only bootstrap, incremental publishing with canonical timestamps, `reconcile`, policy, stable structural identities, content-bound hashes, deletion-safe capture, required encryption, retention, purge, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) · [Security](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer-security.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
 [causal TDD attestation](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/tdd.md),
@@ -570,7 +571,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. For causal TDD, add `[tdd]` and record `wendkeep tdd red|green`; the [TDD attestation guide](docs/en/commands/tdd.md) covers profiles, waivers, and exit codes.
-- **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, TDD attestations, 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 the package, attestations, and verdict to the current `envelope_id`.
+- **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, TDD attestations, 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; `artifact_results` binds explicit digests for versioned files without using stdout as proof. 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 the package, attestations, 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

@@ -253,6 +253,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Native MCP** | semantic tools, effects/capabilities, stdio, schemas, pagination, budgets, audit, and client configuration | [Native MCP](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/mcp.md) |
 | **Evidence recall and embeddings** | cursor/byte budgets, bounded lexical/FTS sidecars, and an optional local plugin contract that is off by default | [Optional embedding plugin](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/evidence-embeddings.md) |
 | **Host capabilities** | versioned lifecycle/effect matrix, degraded mode, human waivers, and evidence/Observer coverage | [Host capabilities](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/capabilities.md) |
+| **Ecosystem bridges** | optional Spec Kit/Superpowers adapters, canonical baseline, single ownership, drift, and Git/CI/Envelope proof with an index/worktree-identical manifest | [Ecosystem bridges](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/ecosystem-bridges.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, Task Contracts, 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) |
@@ -261,7 +262,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Costs and observability** | safe dry-run, tri-state, aggregation, trends, and historical rebuild | [Costs and observability](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/costs-and-observability.md) |
 | **Maintenance and diagnostics** | doctor, frontier/manifest freshness, drift, version, and help | [Maintenance and diagnostics](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/maintenance-and-diagnostics.md) |
 | **Evidence-based commits** | `wendkeep commit`, tasks derived from contracts, tests only from canonical execution bound to the exact SHA, opt-in Git hooks, privacy, and remote range gate | [Commits](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/commit.md) |
-| **Local Observer** | `observer serve`, registration, incremental publication, `reconcile`, outbox, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) |
+| **Local Observer** | `observer serve`, scoped/expiring hash-only bootstrap, incremental publishing with canonical timestamps, `reconcile`, policy, stable structural identities, content-bound hashes, deletion-safe capture, required encryption, retention, purge, and multi-project index | [Local Observer](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer.md) · [Security](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/observer-security.md) |
 
 Operations that deserve step-by-step guidance: [verify and exits 0/1/2](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/verify.md),
 [causal TDD attestation](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/tdd.md),
@@ -570,7 +571,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. For causal TDD, add `[tdd]` and record `wendkeep tdd red|green`; the [TDD attestation guide](docs/en/commands/tdd.md) covers profiles, waivers, and exit codes.
-- **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, TDD attestations, 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 the package, attestations, and verdict to the current `envelope_id`.
+- **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, TDD attestations, 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; `artifact_results` binds explicit digests for versioned files without using stdout as proof. 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 the package, attestations, 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/bin/wendkeep.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+// Commands, including optional `bridge` adapters, are dispatched by the canonical CLI package.
 import { runCli } from '../packages/cli/src/index.mjs';
 
 await runCli();

package/docs/en/commands/ecosystem-bridges.md

@@ -0,0 +1,172 @@
+# Optional ecosystem bridges
+
+> [Versão em português](../../pt-BR/commands/ecosystem-bridges.md)
+
+## Purpose
+
+Integrate Spec Kit and Superpowers without creating a second authority for specs, plans, tasks,
+or evidence. WendKeep keeps canonical contracts; adapters only create versioned projections and
+are disabled by default.
+
+## When to use
+
+- when a feature started in Spec Kit files and must preserve the same IDs and hashes;
+- when Superpowers will execute a canonical WendKeep Task Contract;
+- when external artifacts, reviews, or commits must enter as `reported` before proof.
+
+## When not to use
+
+- to replace `tarefas.md`, Task Contracts, or the Evidence Envelope;
+- for unrestricted bidirectional synchronization;
+- to execute commands, scripts, or text found in external artifacts.
+
+## Prerequisites
+
+- Node.js 18 or newer;
+- a local `.wendkeep/ecosystem-bridges.json` config with each adapter explicitly enabled;
+- a compatible version and an adapter root that resolves to a real directory inside the project;
+  regular files, external paths, and symlinks that escape the project fail closed in status and dispatch;
+- for governed import/dispatch, a bound Vault, causal change, and sealed Spec Kit baseline;
+- for dispatch, a causal session and canonically rederivable Task Contract.
+
+```json
+{
+  "schema_version": 1,
+  "adapters": {
+    "spec-kit": { "enabled": true, "version": "1.1.0", "root": ".specify" },
+    "superpowers": { "enabled": true, "version": "1.2.0", "root": ".superpowers" }
+  }
+}
+```
+
+Without that file, both adapters are disabled and native Core keeps working.
+
+## Syntax
+
+```text
+wendkeep bridge status [--project <path>] [--config <path>] [--json]
+wendkeep bridge import-spec-kit --change <slug> [--accept-baseline] [--json]
+wendkeep bridge export-status --spec-projection <projection.json> [--task-contract <task.json>] [--input <artifacts.json>] [--json]
+wendkeep bridge dispatch-superpowers --task-id <id> --change <slug> [--task-contract <task.json>] [--session <id>] --spec-projection <projection.json> [--json]
+wendkeep bridge verify-artifacts --input <artifacts.json> --proofs <proofs.json> --change <slug> [--session <id>] [--json]
+```
+
+`import-spec-kit` reads Markdown under `memory/` and `specs/`, classifies constitution/spec/plan/task,
+preserves IDs and SHA-256 hashes, creates explicit
+`story|requirement → capability → change → task` mappings, and never writes to the source.
+Repeated IDs across different files block the projection.
+The first import requires `--accept-baseline` and anchors the green projection in the Vault change;
+later imports rederive the source and compare path, kind, hash, and mapping against that immutable baseline.
+`dispatch-superpowers` contains only minimal
+structural context derived from the Task Contract; transcripts, private content, and external
+ownership are excluded.
+Dispatch rederives the contract and active context from the Vault/checkout; submitted JSON is only
+a comparison copy and never validates its own `binding`.
+With Spec Kit active, the baseline and `--spec-projection` are mandatory and the source is
+reimported before dispatch.
+The `spec-projection` contract belongs exclusively to the `spec-kit` adapter: an incompatible
+version, out-of-schema kind, or projection resealed by another adapter is rejected before producing `spec_refs`.
+An `ok: false` decision requires at least one blocking diagnostic, while `ok: true` cannot coexist
+with a blocking diagnostic; any inconsistency blocks dispatch without exposing references.
+`export-status` recomputes and validates `projection_id`, returns a `reported` projection only, and
+does not write to Spec Kit files.
+
+## Options and exit codes
+
+| Option | Effect |
+|---|---|
+| `--project <path>` | Selects the consumer root. |
+| `--config <path>` | Overrides `.wendkeep/ecosystem-bridges.json`. |
+| `--change <slug>` | Selects the change holding canonical baseline and Evidence Envelope. |
+| `--accept-baseline` | Anchors only the first green Spec Kit baseline; never overwrites drift. |
+| `--task-id <id>` | Selects the causal task and rederives its canonical contract. |
+| `--task-contract <path>` | Optional copy that must match the rederived contract. |
+| `--spec-projection <path>` | Links Spec Kit refs to dispatch without copying content. |
+| `--input` / `--proofs` | Classifies external artifacts and their Git/CI/Envelope proofs. |
+| `--json` | Emits the typed contract as one JSON line. |
+
+- `0`: valid operation; optional disabled adapters are healthy too;
+- `1`: enabled adapter blocked, drift, incompatibility, or missing proof;
+- `2`: invalid argument, configuration, or input file.
+
+## Examples
+
+Small flow without adapters:
+
+```powershell
+node ./bin/wendkeep.mjs bridge status --json
+```
+
+Medium read-only Spec Kit flow:
+
+```powershell
+node ./bin/wendkeep.mjs bridge import-spec-kit --change ecosystem-bridges --accept-baseline --json > spec-projection.json
+node ./bin/wendkeep.mjs bridge dispatch-superpowers --task-id 3.1 --change ecosystem-bridges --session "$env:CODEX_THREAD_ID" --spec-projection spec-projection.json --json
+node ./bin/wendkeep.mjs bridge export-status --spec-projection spec-projection.json --task-contract task-contract.json --json
+```
+
+Large flow with external report and proof ingestion:
+
+```powershell
+node ./bin/wendkeep.mjs verify --change ecosystem-bridges
+node ./bin/wendkeep.mjs bridge verify-artifacts --input artifacts.json --proofs ci-proofs.json --change ecosystem-bridges --json
+```
+
+Before `verify`, commit the artifact and `.wendkeep/bridge-artifacts.json` to the Git index. The v1
+manifest binds each item to `source`, `external_id`, `kind`, `path`, `sensor_id`, and `task_id`. The
+matching sensor in `wendkeep.sensors.json` declares v1 `artifact_results` with `external_id`, `path`,
+and `algorithm: sha256`; the runner computes the byte digest, including binary files, only after a
+green run. This explicit result contains no artifact content, transcript, or artifact output tail.
+The collector checks the index first and then requires the identical copy to exist in the worktree;
+deleting or changing only the working copy fails closed, while absence from both index and worktree
+still means that the optional bridge declared no artifacts.
+
+Each `ci-proofs.json` reference contains only
+`{"type":"evidence-envelope","external_id":"review-1"}`. Path, task, sensor, digests, and Git
+blobs are rederived from the canonical manifest and Envelope; self-declared state, SHA, or authority
+are ignored for promotion. `artifacts.json` remains only the external report to compare.
+
+An artifact starts as `reported`. External JSON that merely declares `state: verified` remains
+`reported`. Promotion to `verified` jointly requires a project-contained file equal to its Git
+index blob, a green CI sensor with an explicit `artifact_results.digest`, a canonical Evidence
+Envelope v2 bound to the checkout, and a matching Envelope `external_artifacts` entry.
+`output_sha256` does not prove artifacts. The result
+exposes a sealed proof bound to `evidence_envelope_id` without copying transcript or Vault content.
+
+## Expected result
+
+- Spec Kit remains a read-only external source;
+- canonical plan, task, and evidence remain owned by WendKeep;
+- Superpowers receives minimal dispatch without permission to rewrite scope;
+- worktree creation/reuse and finishing remain delegated to the `wendkeep worktree` argv derived in dispatch;
+- post-merge cleanup uses `wendkeep worktree finish <slug> --pr <number-or-url>`;
+- drift and competing ownership block before execution;
+- removing or disabling an adapter does not degrade Core.
+
+## Common errors and diagnosis
+
+| Code | Diagnosis |
+|---|---|
+| `BRIDGE_ADAPTER_DISABLED` | Normal optional state; enable explicitly when needed. |
+| `BRIDGE_ADAPTER_MISSING` | Adapter is enabled, but its root is absent. |
+| `BRIDGE_VERSION_INCOMPATIBLE` | Version falls outside the published compatibility range. |
+| `BRIDGE_OWNERSHIP_CONFLICT` | External tool tried to own plan/task/evidence. |
+| `BRIDGE_SOURCE_DRIFT` | Hash changed, a plan became stale, or a reference appeared/disappeared. |
+| `BRIDGE_SOURCE_ID_DUPLICATE` | The same story/requirement ID appears in different files. |
+| `BRIDGE_BASELINE_MISSING` | Spec Kit is active without canonical baseline or required projection. |
+| `BRIDGE_BASELINE_STALE` | Source/projection diverged from the sealed Vault baseline. |
+| `BRIDGE_PROJECTION_INVALID` | Content and `projection_id` differ or schema fields are incomplete. |
+| `BRIDGE_SCHEMA_INVALID` | Runtime envelope does not satisfy the published contract. |
+| `BRIDGE_ARTIFACT_MANIFEST_UNTRACKED` | Bridge manifest exists on only one side or differs between index and worktree. |
+| `BRIDGE_ARTIFACT_FORGED` | Artifact path/bytes do not match the versioned file. |
+| `BRIDGE_ARTIFACT_RESULT_MISSING` | A green sensor did not produce the explicit digest bound by the manifest. |
+| `BRIDGE_PROOF_MISSING` | External report has no bound independent proof yet. |
+| `BRIDGE_PROOF_UNVERIFIED` | Self-declared proof was retained as `reported`. |
+
+`wendkeep doctor` renders a `[bridges]` section without importing, dispatching, or writing.
+
+## Next steps
+
+Review the projection before dispatch, keep generated files outside canonical control, and verify
+artifacts through CI or an Evidence Envelope. See [Changes and verification](changes-and-verification.md)
+and [Managed worktrees](worktrees.md) as well.

package/docs/en/commands/observer-security.md

@@ -0,0 +1,154 @@
+# Observer security
+
+**English** · [Português](../../pt-BR/commands/observer-security.md)
+
+## Purpose
+
+The Observer is a local/team read model, never a new authority over the Vault, specs, memory, or
+sync. Its threat model assumes a compromised remote host, stolen token, curious operator, copied
+database/outbox, adversarial payload, and interrupted purge. Host/Origin validation remains active;
+mutations and sensitive reads fail closed, including on loopback.
+
+| Class | Default | Primary risk |
+|---|---|---|
+| document | `metadata` | full memory/decisions |
+| transcript | `metadata` | conversation and tools |
+| prompt/response | `redacted` | PII and secrets |
+| usage | `aggregate` | cost and operational identity |
+| audit/receipt | minimal metadata | deleting the proof itself |
+
+Policy v1 restricts by class, `project_id`, path glob, and `entity_type`. Later rules win only in
+the matching project. Redaction covers Bearer values, URL/connection-string credentials, access
+keys, email, phone, and safe configurable regular expressions. Its schema is
+`schema/observer-policy-v1.schema.json`.
+With `transcript_capture: messages`, arrays, JSONL, and the canonical `{messages:[...]}` envelope
+retain only `user|assistant|system` messages with string `role`/`content` after redaction; extra
+fields, tool records, and malformed entries are dropped or fail closed.
+Explicit policy is the publisher's sole capture authority; `WENDKEEP_OBSERVER_CAPTURE_LEVEL` is
+only translated into policy for legacy callers that supplied no policy file, and can never elevate
+or suppress explicit `none|metadata|messages|full` or `selected` documents.
+For document/transcript upserts, `content_hash` always binds the final content after capture and
+redaction; metadata/selected capture uses the SHA-256 of empty content. Document deletions remain
+effective even when content capture is `none`, preserve their path/revision/operation metadata,
+and never carry stale content or content hashes.
+Redaction never rewrites validated structural identity fields such as project/event/entity IDs,
+logical paths, revisions, or operations. Path privacy is enforced fail-closed by project/path
+capture rules; it is not implemented by renaming a storage key through a content-redaction rule.
+The per-event structural contract also preserves accepted snake/camel aliases, document/session/
+agent/call/transcript/rollup keys, timestamps, roles, status, coverage, model/pricing dimensions,
+workflow, and source provenance. `title`, `summary`, `agent_name`, content, prompt/response, and
+metadata remain redactable display/content fields.
+During incremental publishing, missing or blank turn timestamps inherit the batch's canonical
+instant, numeric epoch milliseconds are normalized to ISO 8601, and invalid non-empty values fail
+closed before policy/store; the event and payload use the same instant.
+
+## When to use
+
+Use it before enabling Observer for real data, registering or revoking credentials, restricting
+capture, protecting SQLite/outbox, defining retention, or deleting data with verifiable proof.
+
+## When not to use
+
+Do not use it as a corporate KMS/secret manager, to publish Vault/runtime data, to replace local
+authority, or to delete tables and indexes manually. `full` capture remains opt-in and subject to
+policy/redaction.
+
+## Prerequisites
+
+Use Node.js 22.13+, keep the bind on loopback, and inject tokens/keys only through environment
+variables. The bootstrap token is registered hash-only with explicit projects and a finite expiry;
+it is not a registry-bypassing wildcard admin. For Docker, also set
+`WENDKEEP_OBSERVER_BOOTSTRAP_PROJECTS`, `WENDKEEP_OBSERVER_BOOTSTRAP_EXPIRES_AT`, and a 32-byte
+hex/base64 `WENDKEEP_OBSERVER_ENCRYPTION_KEY`. The operator owns the key and external receipts.
+
+## Syntax
+
+```bash
+npx wendkeep observer serve --token <token> --bootstrap-projects <p1,p2> --bootstrap-expires-at <ISO> [--bootstrap-token-id <id>] [--require-loopback-auth] [--require-encryption]
+npx wendkeep observer security token create --project-id <project> --role <role> --scopes <scopes> --token-env <env> --expires-at <ISO>
+npx wendkeep observer security token rotate --project-id <project> --token-id <id> --token-env <env> --expires-at <ISO> [--new-token-id <id>]
+npx wendkeep observer security token revoke --project-id <project> --token-id <id>
+npx wendkeep observer security policy set --project-id <project> --file <policy.json>
+npx wendkeep observer security policy show --project-id <project>
+npx wendkeep observer security purge --project-id <project> --before <ISO> --classes <classes> [--dry-run]
+npx wendkeep observer security retention run --project-id <project> [--dry-run] [--operation-id <id>]
+```
+
+## Options and exit codes
+
+- `viewer` reads metadata/aggregates; `auditor` may receive sensitive scopes; `publisher` ingests;
+  `admin` manages policy, purge, and recovery. Role, scope, and project must authorize together.
+- Tokens persist only as SHA-256; expiry, rotation, and revocation take effect without restart.
+- After rotating bootstrap credentials, update both token and token ID in the environment; restart
+  never reactivates an expired or revoked predecessor.
+- `--token-env` names the variable holding the secret; the command never prints its value.
+- `--require-loopback-auth` protects the whole API; sensitive reads require a token without it too.
+- `--require-encryption` fails when external key material is missing or invalid.
+- `WENDKEEP_OBSERVER_REQUIRE_ENCRYPTION=1` applies the same fail-closed behavior to `status`,
+  `security`, `register`, `publish`, and `reconcile`; with a configured key, every first v5 upgrade
+  creates only `.bak.enc` plus its manifest before any read/backfill.
+- Exit `0` means the operation completed; exit `1` means invalid configuration, authorization,
+  policy, key, or operation. The hook retains fail-open exit `0` for the local workflow, but aborts
+  before persisting unsafe content.
+
+Audit stores capability, outcome, route, and time, never a Bearer value, prompt, response, or payload.
+
+## Examples
+
+Explicit audited offline recovery:
+
+```powershell
+$env:OBSERVER_RECOVERY_TOKEN = '<strong-temporary-secret>'
+npx wendkeep observer security token create --data-dir C:\WendKeepObserver `
+  --project-id project-a --role admin --scopes '*' --token-env OBSERVER_RECOVERY_TOKEN `
+  --expires-at 2026-09-29T12:00:00Z --reason 'offline recovery' --json
+npx wendkeep observer security token revoke --data-dir C:\WendKeepObserver `
+  --project-id project-a --token-id <id> --reason 'recovery complete' --json
+```
+
+Always dry-run purge first. The retention runner is explicit and idempotent (CLI or
+`POST /v1/projects/:id/security/retention`), with no hidden timer:
+
+```powershell
+npx wendkeep observer security purge --data-dir C:\WendKeepObserver `
+  --project-id project-a --before 2026-08-01T00:00:00Z `
+  --classes documents,calls,transcripts --dry-run --json
+```
+
+```powershell
+npx wendkeep observer security retention run --data-dir C:\WendKeepObserver `
+  --project-id project-a --operation-id scheduled-2026-08-29 --dry-run --json
+```
+
+## Expected result
+
+TTL is independent for documents, calls, and transcripts. Counts, projection/FTS removal, events,
+and receipt share one transaction; retry is idempotent and late old data creates new proof.
+
+AES-256-GCM uses project/class/record/field AAD and an external `keyProvider`. The v6 backfill
+removes plaintext and derived indexes before reads; a wrong key fails without disclosing content.
+Structural migration `006-observer-security.sql` creates a backup, checks checksum, rolls back, and
+supports retry. In required at-rest mode the backup is `.bak.enc`, carries a manifest/key ID and
+restrictive permissions, fails restore with a wrong key, and leaves no plaintext `.bak` behind.
+
+The hook applies metadata/redacted policy by default; `WENDKEEP_OBSERVER_POLICY_FILE` selects an
+explicit policy. `WENDKEEP_OBSERVER_OUTBOX_KEY_ENV` names the outbox key variable and
+`WENDKEEP_OBSERVER_OUTBOX_KEY_ID` identifies the key. Compose requires authentication and
+encryption. The dashboard keeps Bearer only in memory, exports a sanitized copy, and exposes
+Security. MCP requires scopes for calls/full search. Sync carries only `policy_ref`, without
+duplicating tokens or authority.
+
+## Common errors and diagnosis
+
+- `observer_token_missing|expired|revoked`: create/rotate a scoped token or use offline recovery.
+- `observer_project_forbidden|role_forbidden|scope_forbidden`: check project/role/scope intersection.
+- `observer_encryption_key_unavailable|observer_decryption_failed`: check key ID/material; never
+  weaken required mode.
+- `observer_policy_invalid`: validate fields/captures and remove invalid or explosive regexes.
+- v6 migration failure: preserve `.pre-006-*.bak.enc` and its manifest, correct the cause, and retry.
+
+## Next steps
+
+Read [Local Observer](observer.md), dry-run retention, validate revoked/expired tokens, and keep the
+receipt outside the database when external proof is required. Never publish the database, backup,
+outbox, key, token, or `/data`.

package/docs/en/commands/observer.md

@@ -26,7 +26,9 @@ WendKeep hooks.
 
 Use Node.js 22.13 or newer for the SQL Observer. Keep Core and the remaining commands continue to
 support Node.js 18 or newer. Explicitly register each project and set `WENDKEEP_OBSERVER_TOKEN`;
-loopback reads remain open, while every mutation requires a Bearer token.
+every mutation and every sensitive-content read requires a Bearer token, including on loopback.
+Metadata and aggregates may remain locally open when `--require-loopback-auth` is omitted. See
+[Observer security](observer-security.md).
 
 ## Syntax
 
@@ -36,7 +38,7 @@ npx wendkeep observer register --project <project> --vault <vault> --data-dir <d
 npx wendkeep observer publish --project <project> --vault <vault> --data-dir <directory>
 npx wendkeep observer reconcile --project <project> --vault <vault> --data-dir <directory> [--url http://127.0.0.1:8787]
 npx wendkeep observer memory import --project <project> --vault <vault> --url http://127.0.0.1:8787 --token <token> --json
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory> --token <token>
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory> --token <token> --bootstrap-projects <p1,p2> --bootstrap-expires-at <ISO> [--require-loopback-auth] [--require-encryption]
 ```
 
 ## Options and exit codes
@@ -46,7 +48,13 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory>
 - `--project` and `--vault` identify a project for `register`, `publish`, `reconcile`, and `memory import`.
 - `--host` accepts only `127.0.0.1`, `localhost`, or `::1`; other hosts are rejected before
   listening.
-- `--token` or `WENDKEEP_OBSERVER_TOKEN` authenticates mutations; `--allow-non-loopback` fails without one.
+- `--token` or `WENDKEEP_OBSERVER_TOKEN` supplies hash-only bootstrap material; explicit projects
+  and finite expiry are required, and all mutations/sensitive reads go through the registry;
+  `--allow-non-loopback` fails without one.
+- `--require-loopback-auth` also requires Bearer for local metadata and aggregates and enables the
+  project's secure ingestion policy.
+- `--require-encryption` requires a 32-byte hex/base64 `WENDKEEP_OBSERVER_ENCRYPTION_KEY`; use
+  `WENDKEEP_OBSERVER_ENCRYPTION_KEY_ID` to identify the external key.
 - `WENDKEEP_OBSERVER_CAPTURE_LEVEL` accepts `metadata` (default, no messages), `messages`, or
   `full-transcript`. Absolute local paths are never published.
 - Exit `0` means success; exit `1` means configuration or operation failure; the publisher hook
@@ -57,7 +65,10 @@ npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir <directory>
 ```powershell
 npx wendkeep observer register --project C:\GitHub\WendKeep --vault C:\GitHub\WendKeep\.WendKeep-vault --data-dir C:\WendKeepObserver
 $env:WENDKEEP_OBSERVER_TOKEN = '<strong-local-token>'
-npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver --token $env:WENDKEEP_OBSERVER_TOKEN
+$env:WENDKEEP_OBSERVER_BOOTSTRAP_PROJECTS = 'project-a'
+$env:WENDKEEP_OBSERVER_BOOTSTRAP_EXPIRES_AT = '2026-09-29T12:00:00Z'
+$env:WENDKEEP_OBSERVER_ENCRYPTION_KEY = '<32-bytes-in-hex-or-base64>'
+npx wendkeep observer serve --host 127.0.0.1 --port 8787 --data-dir C:\WendKeepObserver --token $env:WENDKEEP_OBSERVER_TOKEN --require-loopback-auth
 $env:WENDKEEP_OBSERVER_URL = 'http://127.0.0.1:8787'
 ```
 
@@ -67,15 +78,19 @@ For local Docker:
 docker compose -f docker/wendkeep-observer/compose.yaml up -d --build
 ```
 
+Compose requires token, bootstrap allowlist/expiry, and key material; it starts with full
+authentication and required encryption. An `encryption_required` policy refuses plaintext ingest/outbox.
+
 ## Local web dashboard
 
 With the server running, open [http://127.0.0.1:8787/](http://127.0.0.1:8787/) in a browser. The
-dashboard is served by the same process and opens directly for reads, without a form or token. Keep the port
-bound to the computer loopback; do not expose this address on a network interface.
+dashboard is served by the same process. Enter the token in the local form: it remains only in page
+memory, is sent as Bearer for queries, and is discarded on reload. Keep the port bound to the
+computer loopback; do not expose this address on a network interface.
 
 The dashboard shows the multi-project list, version, health, latest session, active change, change
 count, and last capture time. Opening a project exposes Overview, Consumption, Sessions, Memory,
-Changes, and Sync screens. Consumption shows total cost, token categories, primary agents,
+Changes, Sync, and Security screens. Consumption shows total cost, token categories, primary agents,
 subagents, providers, models, daily trend, historical coverage, and calls with prompt, response,
 and transcript content according to the selected capture level. Loading, empty, unavailable-server, conflict, no-pricing, and stale-data
 states are visible, with manual refresh and an automatic 15-second refresh.
@@ -160,18 +175,21 @@ complete, archive, repair, or promote state.
 - `POST /v1/projects/:project_id/ingest` — idempotent batches of documents, sessions, agents,
   rollups, calls, and transcripts.
 - `GET /v1/projects/:project_id/memory/tree` — document tree and metadata.
-- `GET /v1/projects/:project_id/memory/document?path=...` — complete Markdown content.
+- `GET /v1/projects/:project_id/memory/document?path=...` — complete Markdown content; requires Bearer.
 - `GET /v1/projects/:project_id/memory/search?q=...` — ranked chunk search with matching passage
-  and provenance; uses a lexical fallback when FTS5 is unavailable.
+  and provenance; uses a lexical fallback when FTS5 is unavailable and requires Bearer.
 - `GET /v1/projects/:project_id/sync` — mode, counts, conflicts, and latest event.
 - `PUT /v1/projects/:project_id/sync` — compatibility configuration; SQL remains authoritative.
-- `GET /v1/projects/:project_id/memory/export` — read-only export with complete content.
+- `GET /v1/projects/:project_id/memory/export` — read-only export sanitized by default; requires Bearer.
 - `POST /v1/projects/:project_id/memory/events` — idempotent batch ingestion.
 - `GET /v1/projects/:project_id/usage/summary` — filterable totals by period, change, session,
   agent, provider, model, and role.
 - `GET /v1/projects/:project_id/usage/breakdown` — agent, subagent, and model hierarchy.
-- `GET /v1/projects/:project_id/usage/calls` — individual calls with prompt and response.
-- `GET /v1/projects/:project_id/transcripts/:transcript_id` — compressed transcript validated by hash.
+- `GET /v1/projects/:project_id/usage/calls` — individual calls with prompt and response; requires Bearer.
+- `GET /v1/projects/:project_id/transcripts/:transcript_id` — compressed transcript validated by hash; requires Bearer.
+- `GET /v1/projects/:project_id/security` — policy, token counts, and sanitized audit; requires admin.
+- `PUT /v1/projects/:project_id/security/policy` — updates the effective policy without restart; requires admin.
+- `POST /v1/projects/:project_id/security/purge` — transactional dry-run/purge with receipt; requires admin.
 
 The `/v1` routes reject transported or expanded bodies above their limits and validate project,
 path, revision, hash, idempotency, and isolation before writing to SQLite. Use `memory/export` for

package/docs/en/commands/verify.md

@@ -87,6 +87,12 @@ temporary in the same directory and an atomic rename. In deep mode, `verificacao
 `verdict.json` carry the same `evidenceEnvelopeId` and complete `evidenceBinding`; the independent
 reviewer must preserve both.
 
+For bridge artifacts, `.wendkeep/bridge-artifacts.json` and every referenced file must be committed
+and equal to the Git index. The sensor bound to the same task declares v1 `artifact_results` in
+`wendkeep.sensors.json`; after GREEN, the runner computes SHA-256 directly from the bytes and records
+the structured result on that sensor. `verify` crosses manifest, task, sensor, digest, and Git blobs
+before populating `external_artifacts`; stdout, transcripts, and `output_tail` never prove the file.
+
 The envelope carries `tdd_attestations`, and `verificacao.json` carries `tddAttestations`. Under GOVERN, a task marked
 `[tdd]` requires a current GREEN or explicit waiver; under ASSURE this applies to testable
 behavior. A later refactor/commit or a surviving mutant invalidates GREEN in the Task Contract.