wendkeep 0.57.2 → 0.58.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.58.0] — 2026-07-26
+
+### Added
+
+- **Shared Project Memory v2 torna o handoff entre agentes causal, auditável e diretamente
+  injetável.** O `SessionStop` publica eventos locais imutáveis numa outbox, o projector
+  serializa o ledger `MEMORY_EVENTS.jsonl` e gera `SHARED_MEMORY.md`; o próximo
+  `startup|clear|compact` recebe CORE + SHARED completos antes do contexto da change. Epochs
+  de activation impedem um Stop atrasado de fechar ou promover sobre uma sessão mais nova.
+- **Curadoria operacional ganhou comandos e gate próprios.** `wendkeep memory` oferece
+  `status`, migração dry-run/apply com backup, `repair` e decisões append-only de
+  `promote|reject`; `memory-health` bloqueia verify/archive em corrupção, lag ou conflito
+  ativo e mantém outbox/candidates comuns como avisos recuperáveis.
+
+### Security
+
+- **Memória v2 permanece local-only e sanitizada em duas fronteiras.** Secrets, tokens, PII,
+  paths de transcript e payloads do harness são removidos antes da persistência e novamente
+  antes da injeção; eventos são isolados por `project_id`, CORE/SHARED nunca são truncados
+  silenciosamente e o envelope total possui budget rígido de 24 KiB.
+
 ## [0.57.2] — 2026-07-25
 
 ### Fixed

package/README.en.md

@@ -38,7 +38,7 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 |---|---|
 | **Capture** — every turn, on disk | `SessionStart` / `Stop` hooks write each session to a dated Markdown note: prompts, iterations, files touched, wikilinks. |
 | **Derive** — decisions, bugs, learnings | Pulled from the transcript into their own notes, backlinked to the session. Your history becomes navigable, not archival. |
-| **Recall** — injected back | A budget‑capped `CORE` + `DIGEST` and every open change are fed to the agent at the next `SessionStart`. It resumes where it left off. |
+| **Recall** — injected back | Canonical `CORE` + operational `SHARED_MEMORY`, with explicit budgets, are injected on `startup`, `/clear`, and `/compact`; `DIGEST` remains a deep-recall index and legacy fallback. |
 | **Cost** — what it all cost | Per‑model, cache‑aware token pricing per session — plus `cost --trend` with a run‑rate projection across the whole vault. |
 | **Multi‑agent** — one vault, both agents | `init` wires the session hooks into `.claude/settings.json` *and* `.codex/hooks.json`, and every note is tagged with the agent that wrote it: Claude Code is detected from its environment, anything else is recorded as Codex. One shared graph, whichever agent you are in. |
 | **Local‑first** — no cloud, no account | Everything is plain Markdown on your disk. An optional MCP server (`@bitbonsai/mcpvault`) lets the agent read/write the vault. |
@@ -71,9 +71,9 @@ npx wendkeep init
 
    Control with `--companions <csv>` or `--no-companions`. The Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) is wired as a bonus where the companion has one.
 6. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`. Re-apply it any time on an existing vault with `wendkeep theme sync` — Obsidian owns `graph.json` and can drop the color groups (a grey graph); the re-sync restores them without a full re-`init`.
-7. Seed the **curated memory layer**: `.brain/CORE.md` (the hand-curated hot layer, with the 3 required sections) and `.brain/COMPACTION_PROTOCOL.md` (the protocol guide). The auto layers (`DIGEST.md`, `index.jsonl`) are generated by the hooks. Validate the curated layer with `wendkeep validate-memory` (cap 25 lines, 3 sections, no secrets/PII).
+7. Seed **Shared Project Memory v2** without overwriting existing artifacts: `.brain/CORE.md` (hand-curated canonical truth), `.brain/SHARED_MEMORY.md` (generated operational state), `.brain/MEMORY_EVENTS.jsonl` (append-only ledger), `.brain/MEMORY_CANDIDATES.jsonl` (curation queue), and `.brain/COMPACTION_PROTOCOL.md`. The durable outbox appears under `.brain/memory-outbox/` when events exist; `DIGEST.md` and `index.jsonl` remain deep recall. Everything stays local to the vault.
 8. Seed the **definitions + skills layer**: `.brain/agents/` + `.brain/skills/` (versioned source of truth), including the native process skills `wk-workflow` / `wk-tdd` / `wk-debugging` / `wk-brainstorming` / `wk-planning` / `wk-verify` (some ship templates — e.g. `wk-verify`'s `verdict-template.json` + reviewer prompt). `init` runs `wendkeep sync-defs` for you, delivering the skills to `.claude/skills/` and `.agents/skills/`, and the agent definitions (`.brain/agents/*.toml`) to `.codex/agents/`, plus a managed section in `AGENTS.md` that indexes the skills for Codex; `sync-defs --check` detects stale copies (re-run `sync-defs` after editing `.brain`).
-9. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` — a critical `memory-validation` sensor (`npx wendkeep validate-memory`) plus one for each of `typecheck` / `test` / `lint` / `build` found in your `package.json`. Add your own with `wendkeep sensors add`. Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
+9. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` — critical memory validation/health sensors plus one for each of `typecheck` / `test` / `lint` / `build` found in your `package.json`. `memory-health` blocks delivery on corruption, projection divergence, or an active conflict; pending outbox events and ordinary candidates are warnings. Add sensors with `wendkeep sensors add`. Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
 
 ```bash
 npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (no companions unless you ask)
@@ -182,11 +182,45 @@ which the reseed never touches.
 | `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
 | `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). `--change <slug>` ties the lesson to a change; `--vault P`. |
 | `wendkeep sync-defs` | Copy `.brain/agents\|skills` into `.codex/agents`, `.claude/skills`, `.agents/skills`; `--check` detects drift, `--reseed` refreshes the `wk-*` skills from the installed version's seeds. |
-| `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
+| `wendkeep memory status [--gate] --vault P` | Inspect the v2 bundle without mutating it. `--gate` exits 1 only for a blocking state; warnings keep exit code 0. |
+| `wendkeep memory migrate [--apply] --vault P` | Convert a legacy `SHARED_MEMORY.md`. Dry-run by default; `--apply` creates a backup, turns legacy content into candidates, and publishes a valid v2 projection without editing CORE. |
+| `wendkeep memory repair --vault P` | Repair a partial/corrupt ledger under lock, preserving the original bytes in a `.bak`, retaining valid events, and re-projecting state. |
+| `wendkeep memory promote <candidate> --vault P` | Promote a candidate by ID by appending an auditable event; never edits the ledger in place. |
+| `wendkeep memory reject <candidate> --vault P` | Reject a candidate by ID by appending the decision to the audit history. |
+| `wendkeep validate-memory [path]` | Compatibility mode: validate `.brain/CORE.md` only (cap 25, 3 sections, no secrets/PII). Use `--vault <path>` to validate CORE + ledger + SHARED as a v2 bundle. |
 | `wendkeep theme sync [--vault P]` | Re-apply the colour system (CSS snippet + graph groups) to an existing vault — recovers a grey graph without re-running `init`. |
-| `wendkeep doctor [--vault P]` | Vault health check. Beyond session and registry integrity, it reports in sections: `[links]` (graph orphans), `[notas]` (stacked frontmatter), `[preços]` (a model missing from the price table, which would close the session at zero cost) and `[derivadas]` (stale body sections) — each with its repair command alongside. |
+| `wendkeep doctor [--vault P]` | Read-only vault health check. Beyond sessions/registry, links, notes, prices, and derived sections, it checks the v2 bundle and points to `memory status --gate` or `memory repair`; doctor never projects or repairs by itself. |
 | `wendkeep --version` / `--help` | Version / usage. |
 
+## Shared Project Memory v2
+
+Hot memory now separates human authorship, operational state, and evidence:
+
+- **`CORE.md` is canonical.** It is the short, hand-curated nucleus for durable preferences, active patterns, and open issues; no projector may infer or overwrite it.
+- **`SHARED_MEMORY.md` is generated operational state.** The `Stop` hook turns the session handoff into sanitized events; the projector deterministically reduces the ledger and publishes a verifiable revision, cursor, and hash. Facts are `verified` only with local evidence; unsupported reports remain `reported`, and disagreements become candidates for human judgment.
+- **`MEMORY_EVENTS.jsonl` is the append-only authority.** Producers publish to the outbox with exclusive creation, then the projector serializes append + projection under a lock. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
+- **`MEMORY_CANDIDATES.jsonl` is the curation queue.** Conflicts and legacy content are never silently promoted. `promote` and `reject` record the decision as a new event.
+
+Artifacts stay under `.brain/` only. Sanitization strips secrets, tokens, local paths, transcripts, and harness payloads both before persistence and before injection. Events carry a `project_id`, and one vault never accepts another project's events.
+
+### Injection and budgets
+
+`brain-inject` delivers the same revision/hash on `startup`, `/clear`, and `/compact` `SessionStart` events, always placing CORE and SHARED before change context. The full envelope is capped at 24 KiB; CORE reserves up to 4 KiB, SHARED up to 6 KiB, and each line is capped at 320 characters. Under pressure, lessons are removed first, then non-current changes. CORE and SHARED are never prefix-sliced: a missing, invalid, or over-budget layer becomes a visible, repairable `<wk_memory_error>`.
+
+`DIGEST.md` is no longer the operational handoff: it remains the `/brain-recall` bridge and legacy-vault fallback. A vault without SHARED receives CORE+DIGEST with a deprecation warning; migrate during the compatibility window:
+
+```bash
+wendkeep memory status --gate --vault .MyApp-vault
+wendkeep memory migrate --vault .MyApp-vault          # preview, zero writes
+wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2 bundle
+```
+
+### Health and recovery
+
+Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. The critical `memory-health` sensor blocks ledger/outbox/bundle corruption, revision/cursor/hash lag, and active conflicts. A valid pending outbox or ordinary candidate is recoverable and remains a warning rather than blocking.
+
+If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to save a backup of the corrupt ledger, retain valid lines, and re-project. Then run `status --gate` again. Conflicts require explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.
+
 Session notes use one live `## Agentes, tokens e custos` snapshot. Main-agent and subagent hooks recompose it atomically, with costs, token dimensions, reasoning tokens and effort per model/source. Every hook that rewrites a session note takes a per-file lock and writes through a temp file + rename, so the `SubagentStop` fan-out (one hook run per subagent) can never leave a note half-written; a note whose frontmatter reads back damaged is left untouched rather than patched.
 
 ## Retroactive memory (`import`) — install today, remember yesterday
@@ -302,11 +336,11 @@ is the real proof.
 ## How it works
 
 ```
-agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──▶ .brain index + Obsidian graph
-   (Claude/Codex)        (Node)      (02-Sessões/…)        (CORE+DIGEST, backlinks)
+agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──▶ .brain memory + Obsidian graph
+   (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 the token/cost table, and (idempotently) emits any decision/bug/learning notes. On `SessionStart` — startup, `/clear` and `/compact` — `brain-inject` injects back curated memory (CORE + DIGEST), 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 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 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

@@ -38,7 +38,7 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
 |---|---|
 | **Capture** — every turn, on disk | `SessionStart` / `Stop` hooks write each session to a dated Markdown note: prompts, iterations, files touched, wikilinks. |
 | **Derive** — decisions, bugs, learnings | Pulled from the transcript into their own notes, backlinked to the session. Your history becomes navigable, not archival. |
-| **Recall** — injected back | A budget‑capped `CORE` + `DIGEST` and every open change are fed to the agent at the next `SessionStart`. It resumes where it left off. |
+| **Recall** — injected back | Canonical `CORE` + operational `SHARED_MEMORY`, with explicit budgets, are injected on `startup`, `/clear`, and `/compact`; `DIGEST` remains a deep-recall index and legacy fallback. |
 | **Cost** — what it all cost | Per‑model, cache‑aware token pricing per session — plus `cost --trend` with a run‑rate projection across the whole vault. |
 | **Multi‑agent** — one vault, both agents | `init` wires the session hooks into `.claude/settings.json` *and* `.codex/hooks.json`, and every note is tagged with the agent that wrote it: Claude Code is detected from its environment, anything else is recorded as Codex. One shared graph, whichever agent you are in. |
 | **Local‑first** — no cloud, no account | Everything is plain Markdown on your disk. An optional MCP server (`@bitbonsai/mcpvault`) lets the agent read/write the vault. |
@@ -71,9 +71,9 @@ npx wendkeep init
 
    Control with `--companions <csv>` or `--no-companions`. The Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) is wired as a bonus where the companion has one.
 6. Install a **color system** into the vault's `.obsidian/`: a CSS snippet that accents notes by type (session/decision/bug/learning, via the `cssclasses` the hooks emit) plus graph color groups by folder. Non-destructive merge into `appearance.json`/`graph.json`; skip with `--no-colors`. Re-apply it any time on an existing vault with `wendkeep theme sync` — Obsidian owns `graph.json` and can drop the color groups (a grey graph); the re-sync restores them without a full re-`init`.
-7. Seed the **curated memory layer**: `.brain/CORE.md` (the hand-curated hot layer, with the 3 required sections) and `.brain/COMPACTION_PROTOCOL.md` (the protocol guide). The auto layers (`DIGEST.md`, `index.jsonl`) are generated by the hooks. Validate the curated layer with `wendkeep validate-memory` (cap 25 lines, 3 sections, no secrets/PII).
+7. Seed **Shared Project Memory v2** without overwriting existing artifacts: `.brain/CORE.md` (hand-curated canonical truth), `.brain/SHARED_MEMORY.md` (generated operational state), `.brain/MEMORY_EVENTS.jsonl` (append-only ledger), `.brain/MEMORY_CANDIDATES.jsonl` (curation queue), and `.brain/COMPACTION_PROTOCOL.md`. The durable outbox appears under `.brain/memory-outbox/` when events exist; `DIGEST.md` and `index.jsonl` remain deep recall. Everything stays local to the vault.
 8. Seed the **definitions + skills layer**: `.brain/agents/` + `.brain/skills/` (versioned source of truth), including the native process skills `wk-workflow` / `wk-tdd` / `wk-debugging` / `wk-brainstorming` / `wk-planning` / `wk-verify` (some ship templates — e.g. `wk-verify`'s `verdict-template.json` + reviewer prompt). `init` runs `wendkeep sync-defs` for you, delivering the skills to `.claude/skills/` and `.agents/skills/`, and the agent definitions (`.brain/agents/*.toml`) to `.codex/agents/`, plus a managed section in `AGENTS.md` that indexes the skills for Codex; `sync-defs --check` detects stale copies (re-run `sync-defs` after editing `.brain`).
-9. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` — a critical `memory-validation` sensor (`npx wendkeep validate-memory`) plus one for each of `typecheck` / `test` / `lint` / `build` found in your `package.json`. Add your own with `wendkeep sensors add`. Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
+9. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` — critical memory validation/health sensors plus one for each of `typecheck` / `test` / `lint` / `build` found in your `package.json`. `memory-health` blocks delivery on corruption, projection divergence, or an active conflict; pending outbox events and ordinary candidates are warnings. Add sensors with `wendkeep sensors add`. Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
 
 ```bash
 npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (no companions unless you ask)
@@ -182,11 +182,45 @@ which the reseed never touches.
 | `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
 | `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). `--change <slug>` ties the lesson to a change; `--vault P`. |
 | `wendkeep sync-defs` | Copy `.brain/agents\|skills` into `.codex/agents`, `.claude/skills`, `.agents/skills`; `--check` detects drift, `--reseed` refreshes the `wk-*` skills from the installed version's seeds. |
-| `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
+| `wendkeep memory status [--gate] --vault P` | Inspect the v2 bundle without mutating it. `--gate` exits 1 only for a blocking state; warnings keep exit code 0. |
+| `wendkeep memory migrate [--apply] --vault P` | Convert a legacy `SHARED_MEMORY.md`. Dry-run by default; `--apply` creates a backup, turns legacy content into candidates, and publishes a valid v2 projection without editing CORE. |
+| `wendkeep memory repair --vault P` | Repair a partial/corrupt ledger under lock, preserving the original bytes in a `.bak`, retaining valid events, and re-projecting state. |
+| `wendkeep memory promote <candidate> --vault P` | Promote a candidate by ID by appending an auditable event; never edits the ledger in place. |
+| `wendkeep memory reject <candidate> --vault P` | Reject a candidate by ID by appending the decision to the audit history. |
+| `wendkeep validate-memory [path]` | Compatibility mode: validate `.brain/CORE.md` only (cap 25, 3 sections, no secrets/PII). Use `--vault <path>` to validate CORE + ledger + SHARED as a v2 bundle. |
 | `wendkeep theme sync [--vault P]` | Re-apply the colour system (CSS snippet + graph groups) to an existing vault — recovers a grey graph without re-running `init`. |
-| `wendkeep doctor [--vault P]` | Vault health check. Beyond session and registry integrity, it reports in sections: `[links]` (graph orphans), `[notas]` (stacked frontmatter), `[preços]` (a model missing from the price table, which would close the session at zero cost) and `[derivadas]` (stale body sections) — each with its repair command alongside. |
+| `wendkeep doctor [--vault P]` | Read-only vault health check. Beyond sessions/registry, links, notes, prices, and derived sections, it checks the v2 bundle and points to `memory status --gate` or `memory repair`; doctor never projects or repairs by itself. |
 | `wendkeep --version` / `--help` | Version / usage. |
 
+## Shared Project Memory v2
+
+Hot memory now separates human authorship, operational state, and evidence:
+
+- **`CORE.md` is canonical.** It is the short, hand-curated nucleus for durable preferences, active patterns, and open issues; no projector may infer or overwrite it.
+- **`SHARED_MEMORY.md` is generated operational state.** The `Stop` hook turns the session handoff into sanitized events; the projector deterministically reduces the ledger and publishes a verifiable revision, cursor, and hash. Facts are `verified` only with local evidence; unsupported reports remain `reported`, and disagreements become candidates for human judgment.
+- **`MEMORY_EVENTS.jsonl` is the append-only authority.** Producers publish to the outbox with exclusive creation, then the projector serializes append + projection under a lock. Repeating an identical `event_id`/payload is a no-op; reusing the ID with different bytes is observable corruption.
+- **`MEMORY_CANDIDATES.jsonl` is the curation queue.** Conflicts and legacy content are never silently promoted. `promote` and `reject` record the decision as a new event.
+
+Artifacts stay under `.brain/` only. Sanitization strips secrets, tokens, local paths, transcripts, and harness payloads both before persistence and before injection. Events carry a `project_id`, and one vault never accepts another project's events.
+
+### Injection and budgets
+
+`brain-inject` delivers the same revision/hash on `startup`, `/clear`, and `/compact` `SessionStart` events, always placing CORE and SHARED before change context. The full envelope is capped at 24 KiB; CORE reserves up to 4 KiB, SHARED up to 6 KiB, and each line is capped at 320 characters. Under pressure, lessons are removed first, then non-current changes. CORE and SHARED are never prefix-sliced: a missing, invalid, or over-budget layer becomes a visible, repairable `<wk_memory_error>`.
+
+`DIGEST.md` is no longer the operational handoff: it remains the `/brain-recall` bridge and legacy-vault fallback. A vault without SHARED receives CORE+DIGEST with a deprecation warning; migrate during the compatibility window:
+
+```bash
+wendkeep memory status --gate --vault .MyApp-vault
+wendkeep memory migrate --vault .MyApp-vault          # preview, zero writes
+wendkeep memory migrate --apply --vault .MyApp-vault  # backup + candidates + v2 bundle
+```
+
+### Health and recovery
+
+Use `wendkeep memory status --gate --vault <vault>` in CI and before `verify`/`archive`. The critical `memory-health` sensor blocks ledger/outbox/bundle corruption, revision/cursor/hash lag, and active conflicts. A valid pending outbox or ordinary candidate is recoverable and remains a warning rather than blocking.
+
+If status blocks, preserve the evidence and run `wendkeep memory repair --vault <vault>` to save a backup of the corrupt ledger, retain valid lines, and re-project. Then run `status --gate` again. Conflicts require explicit curation with `memory promote <id>` or `memory reject <id>`; doctor only diagnoses.
+
 Session notes use one live `## Agentes, tokens e custos` snapshot. Main-agent and subagent hooks recompose it atomically, with costs, token dimensions, reasoning tokens and effort per model/source. Every hook that rewrites a session note takes a per-file lock and writes through a temp file + rename, so the `SubagentStop` fan-out (one hook run per subagent) can never leave a note half-written; a note whose frontmatter reads back damaged is left untouched rather than patched.
 
 ## Retroactive memory (`import`) — install today, remember yesterday
@@ -302,11 +336,11 @@ is the real proof.
 ## How it works
 
 ```
-agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──▶ .brain index + Obsidian graph
-   (Claude/Codex)        (Node)      (02-Sessões/…)        (CORE+DIGEST, backlinks)
+agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──▶ .brain memory + Obsidian graph
+   (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 the token/cost table, and (idempotently) emits any decision/bug/learning notes. On `SessionStart` — startup, `/clear` and `/compact` — `brain-inject` injects back curated memory (CORE + DIGEST), 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 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 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/bin/wendkeep.mjs

@@ -94,9 +94,11 @@ Usage:
                            in session notes from the linked derived notes — the body used to lag
                            behind the closing block. Dry-run by default · --apply · --json.
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
+  wendkeep memory <sub>          Shared memory v2: status | migrate [--apply] | repair |
+                           promote <candidate> | reject <candidate>. --vault P.
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
-                           protocol (cap 25, 3 sections, no secrets/PII). Uses
-                           --vault <path> or OBSIDIAN_VAULT_PATH if no path given.
+                           protocol (cap 25, 3 sections, no secrets/PII).
+                           --vault <path> validates the complete v2 bundle.
   wendkeep sync-defs [opts]    Copy versioned defs from the vault's .brain into the
                            project: .brain/agents/*.toml -> .codex/agents,
                            .brain/skills/<name> -> .claude/skills + .agents/skills. --vault P --project P.
@@ -180,8 +182,18 @@ async function main() {
       break;
     }
     case 'validate-memory': {
-      const { runValidateMemory } = await import('../src/validate-core.mjs');
-      runValidateMemory(rest);
+      if (rest.includes('--vault') || rest.some((item) => item.startsWith('--vault='))) {
+        const { runValidateMemoryBundle } = await import('../src/memory.mjs');
+        runValidateMemoryBundle(rest);
+      } else {
+        const { runValidateMemory } = await import('../src/validate-core.mjs');
+        runValidateMemory(rest);
+      }
+      break;
+    }
+    case 'memory': {
+      const { runMemory } = await import('../src/memory.mjs');
+      runMemory(rest);
       break;
     }
     case 'sync-defs': {

package/hooks/brain-inject.mjs

@@ -1,8 +1,8 @@
 // .agent/hooks/brain-inject.mjs
 // Injeção da camada quente no SessionStart (Claude/Codex/Copilot): CORE curado +
-// DIGEST auto + 1-linha pointer do recall + backlog completo de changes. Nunca derruba o hook.
+// SHARED operacional no v2; DIGEST fica só no fallback legado/recall. Nunca derruba o hook.
 // Uso (hook): node .agent/hooks/brain-inject.mjs   (input JSON via stdin)
-import { readFileSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { getVaultBase, readHookInput, writeHookOutput } from './obsidian-common.mjs';
@@ -11,6 +11,8 @@ import { buildActiveChangeInjection, changeCtxState, writeSentinel } from './cha
 import { buildLessonsInjection } from './lessons-core.mjs';
 import { getLocale } from './locale.mjs';
 import { resolveSessionEntry } from './session-identity.mjs';
+import { sanitizeMemoryText, validateSharedMemory } from './memory-schema.mjs';
+import { validateCore } from '../src/validate-core.mjs';
 
 // The process ROUTER — the enforcement layer. The wk-* skills are passive files; without a
 // standing instruction the model plans in chat, leaves the change scaffold raw and forces the
@@ -41,30 +43,194 @@ function processRouter(localeId) {
   ].join('\n');
 }
 
-const MAX_LINES = 45; // CORE ≤25 + DIGEST ≤15 + folga; salvaguarda se o CORE crescer à mão
+const INJECTION_LIMITS = Object.freeze({
+  totalBytes: 24 * 1024,
+  lineChars: 320,
+  coreBytes: 4 * 1024,
+  sharedBytes: 6 * 1024,
+  attentionBytes: 1024,
+  recallBytes: 512,
+});
+
+function readMemoryFile(dir, name) {
+  try { return readFileSync(join(dir, name), 'utf8').replace(/\r\n/g, '\n').trim(); }
+  catch { return ''; }
+}
+
+function byteLength(value) {
+  return Buffer.byteLength(String(value || ''), 'utf8');
+}
+
+function xmlAttr(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('"', '"')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;');
+}
+
+function safeError(layer, reasons) {
+  const detail = sanitizeMemoryText((reasons || []).join('; ') || 'arquivo ausente ou inválido')
+    .replace(/\s+/g, ' ');
+  const max = 260;
+  const visible = detail.length <= max ? detail : `${detail.slice(0, max - 20)} … [erro resumido]`;
+  return `<wk_memory_error layer="${layer}" repair="wendkeep memory status --gate">${visible}</wk_memory_error>`;
+}
+
+function validateCoreLayer(raw) {
+  if (!raw) return { ok: false, rendered: safeError('core', ['CORE.md ausente']) };
+  const sanitized = sanitizeMemoryText(raw);
+  const validation = validateCore(raw);
+  const errors = [...validation.errors];
+  if (sanitized !== raw) errors.push('CORE exige sanitização de segredo, PII, path local ou payload de harness');
+  if (byteLength(sanitized) > INJECTION_LIMITS.coreBytes) {
+    errors.push(`CORE excede ${INJECTION_LIMITS.coreBytes} bytes`);
+  }
+  sanitized.split('\n').forEach((line, index) => {
+    if (line.length > INJECTION_LIMITS.lineChars) errors.push(`CORE linha ${index + 1} excede ${INJECTION_LIMITS.lineChars} caracteres`);
+  });
+  return errors.length
+    ? { ok: false, rendered: safeError('core', errors) }
+    : { ok: true, rendered: sanitized };
+}
+
+function validateSharedLayer(raw) {
+  if (!raw) return { ok: false, rendered: safeError('shared', ['SHARED_MEMORY.md ausente']) };
+  // Boundary sanitization is deliberately repeated even though the projector already sanitizes.
+  const sanitized = sanitizeMemoryText(raw);
+  const validation = validateSharedMemory(raw);
+  return validation.ok
+    ? { ok: true, rendered: sanitized, metadata: validation.metadata }
+    : { ok: false, rendered: safeError('shared', validation.errors), metadata: validation.metadata };
+}
+
+function buildV2Memory(dir) {
+  const core = validateCoreLayer(readMemoryFile(dir, 'CORE.md'));
+  const shared = validateSharedLayer(readMemoryFile(dir, 'SHARED_MEMORY.md'));
+  const revision = shared.metadata?.revision ?? 'unknown';
+  const stateHash = shared.metadata?.state_hash ?? 'unknown';
+  const attention = [core, shared].every((layer) => layer.ok)
+    ? 'none'
+    : 'Memória degradada: repare os erros bloqueantes acima antes de confiar no estado operacional.';
+  const pointer = 'Memória profunda sob demanda: /brain-recall <tópico> (índice .brain/index.jsonl; DIGEST é apenas recall).';
+  const block = [
+    `<brain_memory version="2" revision="${xmlAttr(revision)}" state_hash="${xmlAttr(stateHash)}">`,
+    '<wk_memory_contract>',
+    'CORE é canônico e SHARED é operacional; nenhum deles pode ser inferido de wikilinks ou truncado.',
+    '</wk_memory_contract>',
+    '<wk_core authority="canonical">',
+    core.rendered,
+    '</wk_core>',
+    '<wk_shared_state authority="operational">',
+    shared.rendered,
+    '</wk_shared_state>',
+    '<wk_memory_attention>',
+    attention,
+    '</wk_memory_attention>',
+    '<wk_recall>',
+    pointer,
+    '</wk_recall>',
+    '</brain_memory>',
+  ].join('\n');
+  // Layer validation above makes this defensive guard observable without ever prefix-slicing.
+  if (byteLength(block) > (INJECTION_LIMITS.coreBytes + INJECTION_LIMITS.sharedBytes
+      + INJECTION_LIMITS.attentionBytes + INJECTION_LIMITS.recallBytes + 2048)) {
+    return [
+      `<brain_memory version="2" revision="${xmlAttr(revision)}" state_hash="${xmlAttr(stateHash)}">`,
+      safeError('envelope', ['envelope de memória excedeu o budget reservado']),
+      '</brain_memory>',
+    ].join('\n');
+  }
+  return block;
+}
+
+function validateLegacyLayer(raw, layer, { maxLines, maxBytes }) {
+  if (!raw) return '';
+  const sanitized = sanitizeMemoryText(raw);
+  const lines = sanitized.split('\n');
+  const errors = [];
+  if (lines.length > maxLines) errors.push(`${layer} excede ${maxLines} linhas`);
+  if (byteLength(sanitized) > maxBytes) errors.push(`${layer} excede ${maxBytes} bytes`);
+  if (lines.some((line) => line.length > INJECTION_LIMITS.lineChars)) errors.push(`${layer} contém linha acima de ${INJECTION_LIMITS.lineChars} caracteres`);
+  return errors.length ? safeError(layer.toLowerCase(), errors) : sanitized;
+}
+
+function buildLegacyMemory(dir) {
+  const coreRaw = readMemoryFile(dir, 'CORE.md');
+  const coreValidation = coreRaw ? validateCoreLayer(coreRaw) : { ok: true, rendered: '' };
+  const digest = validateLegacyLayer(readMemoryFile(dir, 'DIGEST.md'), 'DIGEST', { maxLines: 15, maxBytes: 4096 });
+  const pointer = 'Memória profunda sob demanda: /brain-recall <tópico> (índice .brain/index.jsonl).';
+  return [
+    '<brain_memory>',
+    '<wk_memory_legacy_warning>Vault legado: CORE+DIGEST será removido após uma release; migre para SHARED_MEMORY v2.</wk_memory_legacy_warning>',
+    coreValidation.rendered,
+    digest,
+    pointer,
+    '</brain_memory>',
+  ].filter(Boolean).join('\n');
+}
+
+function joinInjection(parts) {
+  return sanitizeMemoryText(parts.filter(Boolean).join('\n'));
+}
+
+function boundAncillaryText(text, reservedChars = 0) {
+  if (text.length + reservedChars <= INJECTION_LIMITS.lineChars) return text;
+  const marker = ' … [linha resumida pelo budget]';
+  return `${text.slice(0, INJECTION_LIMITS.lineChars - reservedChars - marker.length)}${marker}`;
+}
+
+function budgetNotice(priority, layer, message) {
+  return `<wk_budget_notice priority="${priority}" layer="${layer}">${message}</wk_budget_notice>`;
+}
 
 export function buildInjection(vaultBase, input = {}) {
   const dir = brainDir(vaultBase);
-  const read = (name) => {
-    try { return readFileSync(join(dir, name), 'utf8').trim(); } catch { return ''; }
-  };
-  const pointer = 'Memória profunda sob demanda: /brain-recall <tópico> (índice .brain/index.jsonl).';
-  // Quando CORE e DIGEST não existem, ''.split('\n') vira [''] — o filter derruba essa
-  // linha vazia para o caso "só pointer" ficar com exatamente 3 linhas.
-  let lines = [read('CORE.md'), read('DIGEST.md')].filter(Boolean).join('\n\n').split('\n').filter((l, i, a) => a.length > 1 || l);
-  if (lines.length > MAX_LINES) {
-    lines = lines.slice(0, MAX_LINES);
-    lines.push('*…truncado pelo budget — fonte completa: .brain/CORE.md + .brain/DIGEST.md*');
-  }
-  const brain = ['<brain_memory>', ...lines, pointer, '</brain_memory>'].join('\n');
+  const brain = existsSync(join(dir, 'SHARED_MEMORY.md')) ? buildV2Memory(dir) : buildLegacyMemory(dir);
   const router = processRouter(getLocale(vaultBase).id);
-  const change = buildActiveChangeInjection(vaultBase);
-  const lessons = buildLessonsInjection(vaultBase);
   const { identity, entry } = resolveSessionEntry(vaultBase, input);
   const focus = identity.state === 'resolved' && entry?.change_slug
-    ? `<session_change>Change vinculada a esta sessão: ${entry.change_slug}. Este vínculo prevalece para writes automáticos; todas as pendências continuam visíveis acima.</session_change>`
+    ? `<session_change>${boundAncillaryText(`Change vinculada a esta sessão: ${entry.change_slug}. Este vínculo prevalece para writes automáticos; todas as pendências continuam visíveis acima.`, '<session_change></session_change>'.length)}</session_change>`
     : '';
-  return [brain, router, focus, change, lessons].filter(Boolean).join('\n');
+  const allChanges = buildActiveChangeInjection(vaultBase, { maxLineChars: INJECTION_LIMITS.lineChars });
+  const lessons = buildLessonsInjection(vaultBase, { maxLineChars: INJECTION_LIMITS.lineChars });
+
+  // Global priority is deterministic: memory/router/focus, then changes, then lessons.
+  let output = joinInjection([brain, router, focus, allChanges, lessons]);
+  if (byteLength(output) <= INJECTION_LIMITS.totalBytes) return output;
+
+  // First pressure step: lessons are fully removable and remain available in the vault.
+  const lessonsEvicted = budgetNotice(1, 'lessons', 'Lessons omitidas primeiro pelo budget global.');
+  output = joinInjection([brain, router, focus, allChanges, lessonsEvicted]);
+  if (byteLength(output) <= INJECTION_LIMITS.totalBytes) return output;
+
+  // Second pressure step: non-current changes leave the hot context before the current one.
+  const nonCurrentEvicted = budgetNotice(2, 'non-current-changes', 'Changes não atuais omitidas depois das lessons.');
+  const currentChange = buildActiveChangeInjection(vaultBase, {
+    currentOnly: true,
+    maxLineChars: INJECTION_LIMITS.lineChars,
+  });
+  output = joinInjection([brain, router, focus, currentChange, lessonsEvicted, nonCurrentEvicted]);
+  if (byteLength(output) <= INJECTION_LIMITS.totalBytes) return output;
+
+  // Last step caps only the current change block, with an explicit marker and closed wrapper.
+  const currentSummarized = budgetNotice(3, 'current-change', 'Change atual resumida por último; blocker e início da fila foram preservados.');
+  const fixed = joinInjection([brain, router, focus, lessonsEvicted, nonCurrentEvicted, currentSummarized]);
+  const remaining = Math.max(512, INJECTION_LIMITS.totalBytes - byteLength(fixed) - 1);
+  const boundedCurrent = buildActiveChangeInjection(vaultBase, {
+    currentOnly: true,
+    maxBytes: remaining,
+    maxLineChars: INJECTION_LIMITS.lineChars,
+  });
+  return joinInjection([
+    brain,
+    router,
+    focus,
+    lessonsEvicted,
+    nonCurrentEvicted,
+    boundedCurrent,
+    currentSummarized,
+  ]);
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/hooks/change-core.mjs

@@ -245,30 +245,67 @@ export function allChangesState(vaultBase) {
   return { current, changes, pointerWarning, hash: tasksHashOf(fingerprint.join('\n')) };
 }
 
-export function renderOpenChanges(state, { tag = 'open_changes' } = {}) {
+function boundInjectionLine(line, maxLineChars) {
+  if (!Number.isFinite(maxLineChars) || line.length <= maxLineChars) return line;
+  const marker = ' … [linha resumida pelo budget]';
+  return `${line.slice(0, Math.max(0, maxLineChars - marker.length))}${marker}`;
+}
+
+function capInjectionBlock(lines, { tag, maxBytes, maxLineChars }) {
+  const bounded = lines.map((line) => boundInjectionLine(line, maxLineChars));
+  if (!Number.isFinite(maxBytes) || Buffer.byteLength(bounded.join('\n'), 'utf8') <= maxBytes) {
+    return bounded.join('\n');
+  }
+  const closing = tag ? `</${tag}>` : '';
+  const marker = '- … conteúdo restante omitido pelo budget de injeção.';
+  const body = tag ? bounded.slice(0, -1) : bounded;
+  const out = [];
+  for (const line of body) {
+    const candidate = [...out, line, marker, closing].filter(Boolean).join('\n');
+    if (Buffer.byteLength(candidate, 'utf8') > maxBytes) break;
+    out.push(line);
+  }
+  // The tag itself and an explicit marker are the minimum valid degraded block.
+  if (!out.length && tag) out.push(`<${tag}>`);
+  out.push(marker);
+  if (closing) out.push(closing);
+  return out.join('\n');
+}
+
+export function renderOpenChanges(state, {
+  tag = 'open_changes',
+  currentOnly = false,
+  maxBytes = Number.POSITIVE_INFINITY,
+  maxLineChars = 320,
+} = {}) {
   if (!state?.changes?.length && !state?.pointerWarning) return '';
   const lines = [];
   if (tag) lines.push(`<${tag}>`);
   if (state.current) lines.push(`Change atual (comandos sem --change): ${state.current}.`);
   else lines.push('Nenhuma change atual selecionada; comandos sem --change continuam recusados.');
   if (state.pointerWarning) lines.push(`Aviso: ${state.pointerWarning}.`);
-  for (const change of state.changes || []) {
+  const visibleChanges = currentOnly
+    ? (state.changes || []).filter((change) => change.current)
+    : (state.changes || []);
+  for (const change of visibleChanges) {
     const label = change.current ? 'ATUAL' : 'ABERTA';
     lines.push(`### ${label} — ${change.slug} (${change.openCount} aberta(s), ${change.doneCount} concluída(s))`);
     if (change.warning) lines.push(`- Aviso: ${change.warning}.`);
     else if (!change.openTasks.length) lines.push('- Nenhuma tarefa aberta.');
     else for (const task of change.openTasks) lines.push(`- [ ] ${task.id} ${task.text}`);
   }
+  const omittedChanges = (state.changes || []).length - visibleChanges.length;
+  if (omittedChanges > 0) lines.push(`- ${omittedChanges} change(s) não atual(is) omitida(s) pelo budget global.`);
   if (state.current) lines.push('Para change atual: `wendkeep change done <id>`; antes de archive: `wendkeep verify`.');
   lines.push('Qualquer agente pode assumir uma change: selecione-a com `wendkeep change use <slug>` ou use `--change <slug>` quando disponível.');
   if (tag) lines.push(`</${tag}>`);
-  return lines.join('\n');
+  return capInjectionBlock(lines, { tag, maxBytes, maxLineChars });
 }
 
 // Mantém o nome exportado para consumidores internos existentes, mas agora injeta o backlog
 // completo em vez de ocultar changes não selecionadas.
-export function buildActiveChangeInjection(vaultBase) {
-  return renderOpenChanges(allChangesState(vaultBase));
+export function buildActiveChangeInjection(vaultBase, options = {}) {
+  return renderOpenChanges(allChangesState(vaultBase), options);
 }
 
 export function activeChangeLink(vaultBase) {

package/hooks/lessons-core.mjs

@@ -36,7 +36,7 @@ export function addLesson(vaultBase, { trigger, lesson, sourceChange = '', dateS
 
 // Compact <lessons> block of the most recent lessons (filename-sorted desc; a date prefix
 // makes that chronological). Budget-capped by `max`. '' when there are none.
-export function buildLessonsInjection(vaultBase, { max = 5 } = {}) {
+export function buildLessonsInjection(vaultBase, { max = 5, maxLineChars = 320 } = {}) {
   const dir = join(vaultBase, '.brain', 'lessons');
   let files;
   try { files = readdirSync(dir).filter((f) => f.endsWith('.md')).sort().reverse().slice(0, max); }
@@ -45,7 +45,13 @@ export function buildLessonsInjection(vaultBase, { max = 5 } = {}) {
   for (const f of files) {
     try {
       const body = readFileSync(join(dir, f), 'utf8').replace(/^---[\s\S]*?---\n/, '').trim().split('\n')[0];
-      if (body) lines.push(`- ${body}`);
+      if (body) {
+        const line = `- ${body}`;
+        const marker = ' … [linha resumida pelo budget]';
+        lines.push(line.length <= maxLineChars
+          ? line
+          : `${line.slice(0, Math.max(0, maxLineChars - marker.length))}${marker}`);
+      }
     } catch { /* skip */ }
   }
   return lines.length ? `<lessons>\nLições do projeto (de falhas anteriores):\n${lines.join('\n')}\n</lessons>` : '';