wendkeep 0.45.0 → 0.46.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +104 -0
- package/README.md +44 -40
- package/README.pt-BR.md +110 -33
- package/package.json +2 -2
- package/src/init.mjs +82 -16
- package/src/taxonomy.mjs +34 -8
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,110 @@ All notable changes to **wendkeep** are documented here. Format based on
|
|
|
4
4
|
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
|
|
5
5
|
[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
6
6
|
|
|
7
|
+
## [0.46.0] — 2026-07-18
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
|
|
11
|
+
- `wendkeep init` agora escreve também `<projeto>/.codex/hooks.json`, e não só
|
|
12
|
+
`.claude/settings.json`. Fechava aqui o buraco mais confuso do onboarding com Codex: o
|
|
13
|
+
`.mcp.json` gerado deixava o vault **alcançável**, então tudo parecia certo — mas sem hooks
|
|
14
|
+
não havia sessão, `CURRENT_SESSION.md` nunca aparecia e o `registrySessions` ficava em 0. As
|
|
15
|
+
saídas eram escrever o `.codex/hooks.json` à mão ou rodar `wendkeep import --source codex`
|
|
16
|
+
depois do fato, ambas descobertas tarde demais. Um projeto novo com Codex nasce com sessão.
|
|
17
|
+
- Sete hooks wirados, marcados `codex: true` em `src/taxonomy.mjs`: `brain-inject`
|
|
18
|
+
(SessionStart, matcher `startup|clear|compact`), `session-start` (SessionStart, `startup`),
|
|
19
|
+
`session-ensure` e `change-context` (UserPromptSubmit, sem matcher), `session-stop` e
|
|
20
|
+
`change-nag` (Stop, sem matcher) e `subagent-stop` (SubagentStop).
|
|
21
|
+
- Cinco hooks ficaram **deliberadamente de fora**, cada um com um comentário `// codex:` no
|
|
22
|
+
`src/taxonomy.mjs` explicando o porquê — projetar um hook que não funciona é pior que não
|
|
23
|
+
projetá-lo. `change-guard` lê `tool_input.command`, mas a superfície de shell do Codex é
|
|
24
|
+
`exec` (`custom_tool_call`, com `tool_input` string crua) ou `exec_command`/`shell_command`:
|
|
25
|
+
o guard falharia **aberto**, dando uma sensação de proteção que não existe. `change-warn` lê
|
|
26
|
+
`tool_input.file_path`, e o `apply_patch` do Codex manda um envelope de patch sem esse campo.
|
|
27
|
+
`plan-capture` não tem equivalente — `update_plan` é a lista de TODO corrente e dispara no
|
|
28
|
+
meio do turno, não no fim do plano. `decision-capture` depende de `AskUserQuestion`, uma
|
|
29
|
+
ferramenta exclusiva do Claude. E `task-log` depende de `TaskCompleted`, que não existe no
|
|
30
|
+
enum de eventos de hook do Codex.
|
|
31
|
+
- A projeção Codex tem três diferenças em relação ao formato do `settings.json`, todas
|
|
32
|
+
**silenciosas quando erradas** — daí valerem registro. (1) A chave de timeout é `timeoutSec`,
|
|
33
|
+
não `timeout`. (2) O comando é sempre `npx wendkeep hook <nome>`, nunca a forma node-direta:
|
|
34
|
+
aquela emite `${CLAUDE_PROJECT_DIR}`, que não existe no Codex, então a flag `preferLocal` é
|
|
35
|
+
ignorada de propósito na projeção. (3) As chaves de evento são PascalCase — o snake_case que
|
|
36
|
+
se vê em `[hooks.state]` no `~/.codex/config.toml` é o rótulo interno do evento, não a chave
|
|
37
|
+
do JSON.
|
|
38
|
+
- Merge não-destrutivo, mesma disciplina do `mergeSettings`: reconhece um grupo já wirado e
|
|
39
|
+
nunca duplica em re-`init`, preserva hooks de terceiros e hooks irmãos agrupados junto,
|
|
40
|
+
`--force` atualiza `timeoutSec`/`statusMessage` no lugar, e um `.bak` é salvo. Arquivo
|
|
41
|
+
existente ilegível não é tocado — a proposta vai para `.codex/hooks.json.new`.
|
|
42
|
+
- Testes: `tests/init-codex-hooks.test.mjs` (12 unitários sobre `mergeCodexHooks`) e um e2e em
|
|
43
|
+
`tests/init-vault.test.mjs`. Suíte completa: 397 passando.
|
|
44
|
+
|
|
45
|
+
### Fixed
|
|
46
|
+
|
|
47
|
+
- Hooks Codex do wendkeep rodavam com o timeout **default de 600s**, não com o configurado. A
|
|
48
|
+
chave correta é `timeoutSec`; `timeout` não é campo, não é rejeitado e simplesmente não é
|
|
49
|
+
lido, então o valor caía no default sem um único aviso. Todo `.codex/hooks.json` escrito à
|
|
50
|
+
mão antes disso (o do NutriGym, entre outros) carrega o erro. `mergeCodexHooks` migra a
|
|
51
|
+
chave legada in place, **mesmo sem `--force`** — é correção de bug, não refresh opcional.
|
|
52
|
+
- `src/taxonomy.mjs` carregava um NUL (`0x00`) e um `0x1f` **literais** dentro da classe de
|
|
53
|
+
caracteres do `deriveVaultDirName`. Por causa do NUL o `file` classificava o fonte como
|
|
54
|
+
binário, e o ripgrep pula binário por default — um Grep por qualquer termo no arquivo
|
|
55
|
+
voltava vazio, em silêncio. Não era erro, era ausência de resultado, e justo no arquivo onde
|
|
56
|
+
vivem os specs de hook e as constantes de companion. Os dois bytes viraram as sequências de
|
|
57
|
+
escape `\x00` e `\x1f`; o regex é byte-idêntico em comportamento (#7).
|
|
58
|
+
|
|
59
|
+
### Changed
|
|
60
|
+
|
|
61
|
+
- A numeração dos passos do `init` foi de `[n/4]` para `[n/5]`. O novo passo 3 é o
|
|
62
|
+
`.codex/hooks.json`, então `.mcp.json` passou a ser `[4/5]` e as cores `[5/5]`.
|
|
63
|
+
|
|
64
|
+
### Migration
|
|
65
|
+
|
|
66
|
+
- **Quem já tem hooks Codex do wendkeep vai ver um prompt "Hooks need review" a mais neste
|
|
67
|
+
upgrade.** Isso é esperado, não regressão: a identidade do hook é hasheada, e corrigir
|
|
68
|
+
`timeout` → `timeoutSec` muda o conteúdo, logo muda o hash, logo o Codex pede re-aprovação.
|
|
69
|
+
Uma vez só.
|
|
70
|
+
- Independente disso, todo hook nasce Untrusted: o Codex enumera mas **não executa** até o
|
|
71
|
+
usuário aprovar no prompt de startup. O `init` não tem como pré-aprovar —
|
|
72
|
+
`--dangerously-bypass-hook-trust` é por invocação e não persiste `trusted_hash` — então
|
|
73
|
+
passou a imprimir um aviso explicando o prompt em vez de deixar o usuário achar que o wiring
|
|
74
|
+
falhou.
|
|
75
|
+
- O `init` **não** escreve `[features] hooks = true` no `.codex/config.toml`, de propósito. O
|
|
76
|
+
Codex declara essa feature como `Stage::Stable` com `default_enabled: true`, então a linha
|
|
77
|
+
seria no-op — e a camada de config do projeto é trust-gated como um todo de qualquer forma.
|
|
78
|
+
|
|
79
|
+
## [0.45.1] — 2026-07-18
|
|
80
|
+
|
|
81
|
+
### Fixed
|
|
82
|
+
|
|
83
|
+
- Documentação: 31 inconsistências entre os READMEs e o comportamento real do pacote,
|
|
84
|
+
encontradas auditando o texto contra o tarball publicado da 0.45.0. Nenhuma mudança de
|
|
85
|
+
código — `src/`, `hooks/`, `bin/` e `schema/` são idênticos aos da 0.45.0. Este release
|
|
86
|
+
existe porque o README viaja dentro do tarball: a correção só chega à página do npm e a
|
|
87
|
+
quem instala o pacote com uma nova publicação.
|
|
88
|
+
- Duas afirmações levavam o usuário a um resultado diferente do prometido: o README dizia
|
|
89
|
+
que `context-mode` vinha pré-marcado no picker de companions e que `init --yes` o
|
|
90
|
+
instalava (todo companion é `default: false` desde a 0.24.0, e `--yes` instala zero), e
|
|
91
|
+
as seções de requisitos/init sugeriam captura de sessões Codex automática após o `init`,
|
|
92
|
+
contradizendo o próprio Notes & roadmap (o `init` só wira `.claude/settings.json`).
|
|
93
|
+
- Tabela de Comandos reescrita a partir do `--help` do binário: faltavam `stats` (usado na
|
|
94
|
+
própria introdução do README), `dashboard`, `change use|continue|abandon|relink`,
|
|
95
|
+
`cost --top|--trend|--write`, `import --stamp-ids|--rescan-decisions`, `verify --change`,
|
|
96
|
+
`spec rebase --accept-current`, `sensors add --name|--description` e `sync-defs --reseed`.
|
|
97
|
+
Três linhas da tabela em inglês tinham ficado em português.
|
|
98
|
+
- Correções factuais: `--force` dispensa só a checagem de tarefa aberta (G1), não o gate
|
|
99
|
+
inteiro; `verdict.json` é exigido sempre desde a 0.31.0 (uma change sem `[req:]` destrava
|
|
100
|
+
com o verdict trivial do `verify --deep`, não pulando a etapa); `change new` não scaffolda
|
|
101
|
+
mais `specs/` e `--simple` pula o `design.md`; os sensores semeados são uma allow-list
|
|
102
|
+
fixa mais `memory-validation`; `detectProvider()` não conhece Copilot; `context-mode` é
|
|
103
|
+
plugin do Claude Code, sem entrada em `.mcp.json`; `brain-inject` roda em
|
|
104
|
+
`startup|clear|compact`; as skills vão para `.claude/skills` e `.agents/skills`;
|
|
105
|
+
`dotcontext` é `hidden`; `docs/` não vai no tarball; e uma tarefa carrega um só
|
|
106
|
+
`[sensor:]` (`[req:]` é que aceita vários).
|
|
107
|
+
- `README.pt-BR.md`: a tabela de comandos estava partida ao meio por um parágrafo, fazendo
|
|
108
|
+
oito linhas renderizarem como texto cru no npm e no GitHub. Reparada e sincronizada com o
|
|
109
|
+
inglês — os dois arquivos fecham com os mesmos 20 comandos e 42 flags.
|
|
110
|
+
|
|
7
111
|
## [0.45.0] — 2026-07-18
|
|
8
112
|
|
|
9
113
|
### Fixed
|
package/README.md
CHANGED
|
@@ -13,14 +13,14 @@
|
|
|
13
13
|
|
|
14
14
|
**In the graph:** 🔵 session · 🟣 decision · 🔴 bug · 🟢 learning · 🟡 change — every note, backlinked.
|
|
15
15
|
|
|
16
|
-
**A persistent‑memory harness for AI coding agents, built on your Obsidian vault.** Every Claude Code
|
|
16
|
+
**A persistent‑memory harness for AI coding agents, built on your Obsidian vault.** Every Claude Code **and Codex** session is captured turn‑by‑turn into local Markdown — `init` wires both (Codex asks you to approve its hooks once; `import` backfills past sessions either way) — with token/cost tracking, auto‑extracted decisions, bugs and learnings, and a curated memory layer injected back at the start of the next session. On top of that memory core sits a native, zero‑dependency **change lifecycle** (spec → change → TDD → sensor‑gated archive) that keeps intent, work and proof wikilinked in one graph. 100% local, open‑core.
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
19
|
npm i -D wendkeep && npx wendkeep init # captures from the next session on
|
|
20
20
|
npx wendkeep import # backfill past Claude + Codex sessions
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
**▶ Interactive demo:** [`docs/index.html`](docs/index.html) — a self-contained page with the live knowledge‑graph hero.
|
|
23
|
+
**▶ Interactive demo:** [`docs/index.html`](docs/index.html) — a self-contained page with the live knowledge‑graph hero. It lives in the [GitHub repo](https://github.com/rogersialves/wendkeep/tree/main/docs) (the npm tarball ships only the runtime), so clone or download `docs/` to open it locally or serve it on any static host. The image above is a static render of it.
|
|
24
24
|
|
|
25
25
|
> **From one real production vault** (`npx wendkeep stats`): **308** sessions · **1,696** prompts · **$4,836** captured across **46 active days** (Jan–Jul 2026) · **15** models — every one a note in the graph.
|
|
26
26
|
|
|
@@ -38,15 +38,15 @@ Decisions, dead ends, the reason you chose X over Y — gone next session. The p
|
|
|
38
38
|
|---|---|
|
|
39
39
|
| **Capture** — every turn, on disk | `SessionStart` / `Stop` hooks write each session to a dated Markdown note: prompts, iterations, files touched, wikilinks. |
|
|
40
40
|
| **Derive** — decisions, bugs, learnings | Pulled from the transcript into their own notes, backlinked to the session. Your history becomes navigable, not archival. |
|
|
41
|
-
| **Recall** — injected back | A budget‑capped `CORE` + `DIGEST` and
|
|
41
|
+
| **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. |
|
|
42
42
|
| **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. |
|
|
43
|
-
| **Multi‑agent** — one
|
|
43
|
+
| **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. |
|
|
44
44
|
| **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. |
|
|
45
45
|
|
|
46
46
|
## Requirements
|
|
47
47
|
|
|
48
48
|
- Node.js ≥ 18
|
|
49
|
-
- An AI coding agent with hooks
|
|
49
|
+
- An AI coding agent with hooks. `init` wires **Claude Code** and **Codex** automatically — Codex gets the seven hooks its event model supports and enumerates them untrusted, so approve its “Hooks need review” prompt once at startup (see [Notes & roadmap](#notes--roadmap))
|
|
50
50
|
- Obsidian (to view the graph) — optional but the point
|
|
51
51
|
|
|
52
52
|
## Install & set up
|
|
@@ -60,22 +60,23 @@ npx wendkeep init
|
|
|
60
60
|
`wendkeep init` is interactive and **idempotent**. It will:
|
|
61
61
|
|
|
62
62
|
1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
|
|
63
|
-
2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault.
|
|
64
|
-
3.
|
|
65
|
-
4.
|
|
66
|
-
|
|
63
|
+
2. Write a provider-neutral **`.wendkeep.json`** binding at the project root and a matching `.brain/PROJECT.json` marker in the vault, then merge the session hooks into **`.claude/settings.json`**. The binding is provider-neutral by design: any agent resolves the same vault from its session `cwd`, with no machine-global environment variable. Older registrations already in `.claude/settings.json` are adopted automatically.
|
|
64
|
+
3. Wire the Codex session hooks in **`.codex/hooks.json`** — seven of the twelve: `brain-inject` + `session-start` on `SessionStart`, `session-ensure` + `change-context` on `UserPromptSubmit`, `session-stop` + `change-nag` on `Stop`, `subagent-stop` on `SubagentStop`, always in the `npx wendkeep hook <name>` form. The other five are left out because Codex offers no equivalent payload, tool *or* event: `change-guard` (a `PreToolUse` gate reading `tool_input.command`, but Codex's `exec` carries `tool_input` as a raw string rather than an object, so the gate would fail *open*), `change-warn` (a `PostToolUse` nudge resolving `tool_input.file_path`, a field `apply_patch`'s envelope does not carry — nothing to resolve, and nothing to gate), `plan-capture` (there is no `ExitPlanMode`; `update_plan` is a running TODO list, not an approval), `decision-capture` (`AskUserQuestion` is a Claude-only tool) and `task-log` (`TaskCompleted` is not in Codex's event enum). See [Notes & roadmap](#notes--roadmap) for the per-hook detail. The merge is non-destructive, on the same discipline as `settings.json`: it recognizes an already-wired group and never duplicates on re-init, preserves third-party hooks, saves a `.bak`, and `--force` updates `timeoutSec`/`statusMessage` in place; an unparseable `.codex/hooks.json` is left untouched with the merge written to `.codex/hooks.json.new`. **Codex enumerates every hook as untrusted and runs none of them until you approve the “Hooks need review” prompt at startup — `init` cannot pre-approve them**, and it prints a warning saying so. Anyone who already had hand-written wendkeep hooks in Codex gets one re-review prompt: `init` migrates the legacy `timeout` key (which Codex neither rejects nor reads, falling through to a 600s default) to `timeoutSec`, and that changes the hook's hashed identity.
|
|
65
|
+
4. Add the **`wendkeep-vault`** MCP server to `.mcp.json` so the agent can read/write the vault. Skip with `--no-mcp` — e.g. when the agent already has a vault MCP. (`--no-mcp` skips *only wendkeep's own* MCP; companion MCPs still follow `--companions`.)
|
|
66
|
+
5. Offer to pin **companion** plugins/MCP (multi-choice; **none** pre-checked — wendkeep is a neutral harness and presumes no third-party plugin). Each is wired the most agent-agnostic way it supports:
|
|
67
|
+
- **`context-mode`** — context optimizer + FTS5 memory, wired as a Claude Code plugin. It ships its own MCP server, so wendkeep deliberately adds no `.mcp.json` entry (registering both cold-started two servers at once). On non-Claude agents, add the MCP by hand: `npx -y context-mode`.
|
|
67
68
|
- **`understand-anything`** — project domain graph, via a `understand-inject` SessionStart hook that injects the graph when generated.
|
|
68
69
|
- **`caveman`** — token-compression mode; runs its own cross-agent installer on non-Claude agents.
|
|
69
|
-
- **`dotcontext`** — *legacy, not recommended.* wendkeep's native a2 loop (`change` / `verify` / gate) already does its job, so installing it **duplicates the harness**.
|
|
70
|
+
- **`dotcontext`** — *legacy, not recommended, and hidden from the picker.* wendkeep's native a2 loop (`change` / `verify` / gate) already does its job, so installing it **duplicates the harness**. Reachable only via an explicit `--companions dotcontext` for anyone already invested (tune with `--dotcontext-mcp` / `--dotcontext-hooks`).
|
|
70
71
|
|
|
71
72
|
Control with `--companions <csv>` or `--no-companions`. The Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) is wired as a bonus where the companion has one.
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
73
|
+
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`.
|
|
74
|
+
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).
|
|
75
|
+
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`).
|
|
76
|
+
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.
|
|
76
77
|
|
|
77
78
|
```bash
|
|
78
|
-
npx wendkeep init --vault "~/vaults/work" --project . --yes # non-interactive (
|
|
79
|
+
npx wendkeep init --vault "~/vaults/work" --project . --yes # non-interactive (no companions unless you ask)
|
|
79
80
|
npx wendkeep init --companions "context-mode,understand-anything" --yes
|
|
80
81
|
npx wendkeep init --no-companions --no-mcp --yes # zero companions, no wendkeep MCP
|
|
81
82
|
```
|
|
@@ -129,21 +130,22 @@ Restart Codex and Claude Code after reseeding their generated skills.
|
|
|
129
130
|
|---|---|
|
|
130
131
|
| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP + skills). |
|
|
131
132
|
| `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
|
|
132
|
-
| `wendkeep change <sub>` | Change lifecycle: `new [--simple]` / `list` (global backlog) / `show
|
|
133
|
-
| `wendkeep verify [--deep]` | Run the change's task sensors; `--deep` assembles the independent-verification package. |
|
|
134
|
-
| `wendkeep spec <sub>` | `list` / `show
|
|
135
|
-
| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
|
|
136
|
-
| `wendkeep cost [
|
|
137
|
-
| `wendkeep
|
|
138
|
-
| `wendkeep
|
|
139
|
-
| `wendkeep
|
|
140
|
-
| `wendkeep
|
|
133
|
+
| `wendkeep change <sub>` | Change lifecycle: `new <slug> [--simple]` / `use <slug>` (switch focus) / `continue <archived> <new>` / `bind <slug> --session <id>` / `list` (global backlog) / `show <slug>` / `status [slug]` / `done <id> [--change slug]` / `undone <id> [--change slug]` / `relink [--apply] [--json]` (repair change wikilinks; preview by default) / `diff [slug]` / `archive [slug] [--force]` / `abandon [slug]` (drop it, no ADR). `diff`, `archive` and `abandon` fall back to the active change when you omit the slug; bare `status` lists every open one. |
|
|
134
|
+
| `wendkeep verify [--deep] [--change s]` | Run the change's task sensors; `--deep` assembles the independent-verification package. `--change` targets a change other than the active one. |
|
|
135
|
+
| `wendkeep spec <sub>` | `list` / `show <capability>` generated contracts; `effective [--change <slug>] [--json]` (living contract + delta; defaults to the active change); `migrate`; `rebase [--accept-current]` (stops on conflicts unless you accept the living spec's side). |
|
|
136
|
+
| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` with `--severity` / `--type` / `--report` / `--name` / `--description` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
|
|
137
|
+
| `wendkeep cost [opts]` | Aggregate AI-coding spend across the vault's sessions — total, by model, by day. `--since <date>` / `--top [N]` (priciest) / `--trend [day\|week\|month]` (+ run-rate projection) / `--write` (generate `00-Custo.md`) / `--json`. |
|
|
138
|
+
| `wendkeep cost rebuild [opts]` | Recalculate historical parent + subagent costs from `SESSION_REGISTRY`. Dry-run by default; `--apply` updates the notes and writes `.brain/COST_REBUILD.json`. Also `--session <id\|file>` / `--limit n` / `--json`. |
|
|
139
|
+
| `wendkeep stats [--vault P]` | One shareable line: sessions · prompts · spend · span · models (`--json`). |
|
|
140
|
+
| `wendkeep import [opts]` | **Retroactive memory** — backfill past **Claude + Codex** sessions into the vault (deduped by `session_id`). `--source all\|claude\|codex` / `--stamp-ids` / `--rescan-decisions` / `--from <dir>` / `--codex-from <dir>` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
|
|
141
|
+
| `wendkeep session list\|show\|use` | List the multi-session registry, show one conversation, or move only the human focus in `CURRENT_SESSION.md`. |
|
|
142
|
+
| `wendkeep dashboard [--force]` | (Re)generate the vault's folder-filtered Bases + the `00-Dashboard` MOC. |
|
|
141
143
|
| `wendkeep note new --type bug\|learning "<title>"` | Create a **numbered** derived note (`BUG-`/`APR-NNNN`) in the month folder and print its vault path. `--date YYYY-MM-DD`. |
|
|
142
144
|
| `wendkeep renumber-decisions` | Renumber `04-Decisões` to `ADR-NNNN-<slug>` chronologically, move notes out of legacy `DIA N` subfolders into the month folder, and rewrite wikilinks. Preview by default; `--apply` / `--json`. |
|
|
143
145
|
| `wendkeep renumber-bugs` | Same for `05-Bugs` → `BUG-NNNN-<slug>`. |
|
|
144
146
|
| `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
|
|
145
147
|
| `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). |
|
|
146
|
-
| `wendkeep sync-defs` | Copy `.brain/agents\|skills` into `.codex/agents`, `.claude/skills`, `.agents/skills`; `--check` detects drift. |
|
|
148
|
+
| `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. |
|
|
147
149
|
| `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
|
|
148
150
|
| `wendkeep doctor [--vault P]` | Run a vault health check (integrity of sessions, registry, links). |
|
|
149
151
|
| `wendkeep --version` / `--help` | Version / usage. |
|
|
@@ -163,7 +165,7 @@ wendkeep import --vault .myproject-vault --source codex # just Codex
|
|
|
163
165
|
- **Both agents by default** (`--source all`). Claude sessions come from `~/.claude/projects/<slug>/`; Codex rollouts from `~/.codex/sessions/**`, scoped to this project by the `cwd` recorded in each session (case- and separator-insensitive, subdirs included). Narrow with `--source claude` / `--source codex`.
|
|
164
166
|
- Every note records its **`session_id`** and **`provider`** in frontmatter (live capture and import alike). Backfill older notes with `wendkeep import --stamp-ids` (fills the id from the registry; idempotent).
|
|
165
167
|
- **Deduped** by `session_id` against the vault's `SESSION_REGISTRY` **and** existing notes' frontmatter — only sessions not already present are imported, and it never overwrites an existing note. Re-running is a no-op.
|
|
166
|
-
- **`--from <dir>`** / **`--codex-from <dir>`** point at the transcript folders explicitly (use if the auto-derived path misses). Also: `--since <date>`, `--limit <n>`, `--json`.
|
|
168
|
+
- **`--from <dir>`** / **`--codex-from <dir>`** point at the transcript folders explicitly (use if the auto-derived path misses). Also: `--since <date>`, `--limit <n>`, `--rescan-decisions`, `--json`.
|
|
167
169
|
- Once imported, `wendkeep cost` aggregates your entire history — retroactively, across both agents.
|
|
168
170
|
|
|
169
171
|
## Derived notes — numbered like ADRs (`note new`, `renumber-*`)
|
|
@@ -174,10 +176,10 @@ Decisions, bugs and learnings are **derived notes**: they live in the month fold
|
|
|
174
176
|
|
|
175
177
|
```bash
|
|
176
178
|
wendkeep note new --type bug "login 500s when the token expires mid-refresh"
|
|
177
|
-
# → 05-Bugs/2026/07-JUL/BUG-0007-login-500s-when-the-token-expires.md
|
|
179
|
+
# → 05-Bugs/2026/07-JUL/BUG-0007-login-500s-when-the-token-expires-mid-refresh.md
|
|
178
180
|
|
|
179
181
|
wendkeep note new --type learning "a regex without /g only ever returns the first match"
|
|
180
|
-
# → 06-Aprendizados/2026/07-JUL/APR-0003-a-regex-without-g-only-ever-returns.md
|
|
182
|
+
# → 06-Aprendizados/2026/07-JUL/APR-0003-a-regex-without-g-only-ever-returns-the-first-match.md
|
|
181
183
|
```
|
|
182
184
|
|
|
183
185
|
It prints the created path, numbers from the current max (recursive scan), files it in the month folder for today (`--date YYYY-MM-DD` to override), and links the active session in `source:` so the graph stays connected. Agents get this rule injected at SessionStart — they call the command instead of guessing a filename.
|
|
@@ -211,14 +213,14 @@ Beyond capturing sessions, wendkeep is a **harness**: a native, zero‑dependenc
|
|
|
211
213
|
explore → propose → apply (TDD) → verify → archive
|
|
212
214
|
```
|
|
213
215
|
|
|
214
|
-
- **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md
|
|
215
|
-
- **Apply** — implement each `tarefas.md` task. Tag a task that needs machine proof with `[sensor:<id>]
|
|
216
|
-
- **Verify** — `wendkeep verify`
|
|
216
|
+
- **Propose** — `wendkeep change new <slug>` scaffolds `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`; `--simple` skips the design). 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.
|
|
217
|
+
- **Apply** — implement each `tarefas.md` task. Tag a task that needs machine proof with `[sensor:<id>]` — one sensor per task (a task carries a single sensor; split it in two if you need two) — and the requirement it satisfies with `[req:<ID>]`, of which a task may declare several.
|
|
218
|
+
- **Verify** — `wendkeep verify` runs the sensors your tasks declared (from `wendkeep.sensors.json` at the project root) and writes `evidencia.json`. A red `critical` fails the gate; a red `warning` is advisory. `verify --deep` builds a self-contained package with complete effective requirements (living contract + this change's delta), so the independent verifier never needs to reconstruct unarchived requirements from `07-Specs`. Every change needs a `verdict.json` to archive; `verify --deep` writes a trivial one automatically when the change declares no `[req:]`.
|
|
217
219
|
- **Archive** — `wendkeep change archive <slug>` **gates** on the evidence (blocks unless every declared critical sensor is green), promotes each capability's spec delta (`ADDED`/`MODIFIED`/`REMOVED`) into the living `07-Specs/<capability>.md`, moves the change to `_arquivo/`, and mints an ADR in `04-Decisões/`.
|
|
218
220
|
|
|
219
|
-
> The gate blocks unless the scaffold is filled, no task is open, evidence is fresh, and every declared requirement is covered. **`--force` is the human's call
|
|
221
|
+
> 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.
|
|
220
222
|
|
|
221
|
-
`wendkeep init` seeds process skills into `.brain/skills` and delivers identical copies to
|
|
223
|
+
`wendkeep init` seeds process skills into the vault's `.brain/skills` and delivers identical copies to `.claude/skills/` and `.agents/skills/`; Codex gets the agent definitions (`.brain/agents/*.toml` → `.codex/agents/`) plus a managed section in `AGENTS.md` that indexes the skills. Every skill carries source hash/version metadata; `doctor` warns when reseed + agent restart is required.
|
|
222
224
|
|
|
223
225
|
### The loop in five minutes
|
|
224
226
|
|
|
@@ -237,9 +239,9 @@ Declare the capability in `proposta.md` (`specs: [ui]`) and author its delta onl
|
|
|
237
239
|
`08-Mudanças/<slug>/specs/ui/spec.md`. `07-Specs` is generated/read-only. Then:
|
|
238
240
|
|
|
239
241
|
```bash
|
|
240
|
-
npx wendkeep change status #
|
|
241
|
-
npx wendkeep change list #
|
|
242
|
-
npx wendkeep change status dark-mode # one change
|
|
242
|
+
npx wendkeep change status # every open change + its pending tasks
|
|
243
|
+
npx wendkeep change list # same backlog, plus the archived ones
|
|
244
|
+
npx wendkeep change status dark-mode # one screen for one change: specs / tasks / sensors / verdict
|
|
243
245
|
npx wendkeep spec effective --change dark-mode # living contract + this change's delta
|
|
244
246
|
npx wendkeep change done 1.1 # tick a task from the CLI
|
|
245
247
|
npx wendkeep verify # run the declared sensors -> evidencia.json
|
|
@@ -251,7 +253,8 @@ npx wendkeep change archive dark-mode # gate: sensors + verdict + no op
|
|
|
251
253
|
|
|
252
254
|
The archive promotes the delta into generated `07-Specs/ui.md`, mints an ADR, and the
|
|
253
255
|
Obsidian graph now links *session ↔ change ↔ requirement ↔ decision*. A change that names
|
|
254
|
-
no `[req:]`
|
|
256
|
+
no `[req:]` still runs `verify --deep`, but skips the `wk-verify` reading pass: the
|
|
257
|
+
command writes a trivial verdict on its own and the sensor gate is the real proof.
|
|
255
258
|
|
|
256
259
|
## How it works
|
|
257
260
|
|
|
@@ -260,16 +263,17 @@ agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──
|
|
|
260
263
|
(Claude/Codex) (Node) (02-Sessões/…) (CORE+DIGEST, backlinks)
|
|
261
264
|
```
|
|
262
265
|
|
|
263
|
-
The agent's settings.json points each hook at `npx wendkeep hook
|
|
266
|
+
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.
|
|
264
267
|
|
|
265
|
-
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
|
|
268
|
+
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.
|
|
266
269
|
|
|
267
270
|
## Notes & roadmap
|
|
268
271
|
|
|
269
272
|
- **Vault folder names default to Portuguese** (`02-Sessões`, `04-Decisões`, …). Pass `wendkeep init --locale en` for an English vault (`02-Sessions`, `04-Decisions`, English scaffold/skills). The locale is a vault property, locked at init; parsers are bilingual so mixed content never breaks.
|
|
270
273
|
- **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
|
|
271
274
|
- **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
|
|
272
|
-
- Installer wires **
|
|
275
|
+
- Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Five hooks stay Claude‑only** because Codex has no equivalent payload, tool or event: `change-guard` (a `PreToolUse` gate that reads `tool_input.command`, but Codex's `exec` carries `tool_input` as a raw string rather than an object — the gate would fail *open*), `change-warn` (a `PostToolUse` nudge that resolves `tool_input.file_path`, which `apply_patch`'s envelope simply does not carry — nothing to resolve, and nothing to gate), `plan-capture` (no `ExitPlanMode` — `update_plan` is a running TODO list, not an approval), `decision-capture` (`AskUserQuestion` is Claude‑only) and `task-log` (`TaskCompleted` is not in Codex's event enum).
|
|
276
|
+
- **Codex hooks start untrusted.** They are enumerated but not executed until you approve the “Hooks need review” prompt; `init` cannot pre‑approve them (`--dangerously-bypass-hook-trust` is per‑invocation and stores no trusted hash). Trust is keyed to the hook's identity, so hand‑written wendkeep Codex hooks predating `0.46.0` — which ran at the 600s default because they used `timeout` instead of `timeoutSec` — cost one re‑review after `init` corrects the key. Expected, not a regression. `import --source codex` still backfills past Codex sessions either way.
|
|
273
277
|
|
|
274
278
|
---
|
|
275
279
|
|
package/README.pt-BR.md
CHANGED
|
@@ -13,14 +13,14 @@
|
|
|
13
13
|
|
|
14
14
|
**No grafo:** 🔵 sessão · 🟣 decisão · 🔴 bug · 🟢 aprendizado · 🟡 mudança — cada nota, com backlink.
|
|
15
15
|
|
|
16
|
-
**Um harness de memória persistente para agentes de código, construído sobre o seu cofre Obsidian.** Cada sessão do Claude Code
|
|
16
|
+
**Um harness de memória persistente para agentes de código, construído sobre o seu cofre Obsidian.** Cada sessão do Claude Code e do Codex é capturada turno a turno em Markdown local — o `init` wira os hooks dos dois agentes (no Codex, valendo depois que você aprovar o prompt de confiança dele); o `import` importa as sessões passadas de qualquer um dos dois — com rastreio de tokens/custo, decisões, bugs e aprendizados extraídos automaticamente, e uma camada de memória curada injetada de volta no início da próxima sessão. Sobre esse núcleo de memória fica um **ciclo de mudança** nativo e sem dependências (spec → change → TDD → archive com gate por sensor) que mantém intenção, trabalho e prova wikilinkados num só grafo. 100% local, open‑core.
|
|
17
17
|
|
|
18
18
|
```bash
|
|
19
19
|
npm i -D wendkeep && npx wendkeep init # captura a partir da próxima sessão
|
|
20
20
|
npx wendkeep import # importa sessões passadas do Claude + Codex
|
|
21
21
|
```
|
|
22
22
|
|
|
23
|
-
**▶ Demo interativo:** [`docs/index.pt.html`](docs/index.pt.html) — uma página autocontida com o herói de grafo vivo.
|
|
23
|
+
**▶ Demo interativo:** [`docs/index.pt.html`](docs/index.pt.html) — uma página autocontida com o herói de grafo vivo. Ele vive no [repositório GitHub](https://github.com/rogersialves/wendkeep/tree/main/docs) (o tarball do npm leva só o runtime), então clone ou baixe o `docs/` pra abrir local ou servir em qualquer host estático. A imagem acima é um render estático dele.
|
|
24
24
|
|
|
25
25
|
> **De um cofre de produção real** (`npx wendkeep stats`): **308** sessões · **1.696** prompts · **US$ 4.836** capturados em **46 dias ativos** (jan–jul 2026) · **15** modelos — cada uma delas uma nota no grafo.
|
|
26
26
|
|
|
@@ -36,15 +36,15 @@ Decisões, becos sem saída, o motivo de você ter escolhido X em vez de Y — s
|
|
|
36
36
|
|---|---|
|
|
37
37
|
| **Captura** — cada turno, no disco | Os hooks `SessionStart` / `Stop` escrevem cada sessão numa nota Markdown datada: prompts, iterações, arquivos tocados, wikilinks. |
|
|
38
38
|
| **Deriva** — decisões, bugs, aprendizados | Puxados do transcript pra notas próprias, com backlink pra sessão. Seu histórico fica navegável, não arquivístico. |
|
|
39
|
-
| **Recall** — injetado de volta | Um `CORE` + `DIGEST` com budget capado e
|
|
39
|
+
| **Recall** — injetado de volta | Um `CORE` + `DIGEST` com budget capado e todas as changes abertas são injetados no agente no próximo `SessionStart`. Ele retoma de onde parou. |
|
|
40
40
|
| **Custo** — quanto tudo custou | Preço por modelo, ciente de cache, por sessão — mais `cost --trend` com projeção run‑rate no cofre inteiro. |
|
|
41
|
-
| **Multi‑agente** —
|
|
41
|
+
| **Multi‑agente** — um cofre, os dois agentes | O `init` wira os hooks de sessão no `.claude/settings.json` *e* no `.codex/hooks.json`, e cada nota é marcada com o agente que a escreveu: o Claude Code é detectado pelo ambiente dele, qualquer outro é registrado como Codex. Um grafo só, esteja você em qual agente estiver. |
|
|
42
42
|
| **Local‑first** — sem nuvem, sem conta | Tudo é Markdown puro no seu disco. Um MCP opcional (`@bitbonsai/mcpvault`) deixa o agente ler/escrever o cofre. |
|
|
43
43
|
|
|
44
44
|
## Requisitos
|
|
45
45
|
|
|
46
46
|
- Node.js ≥ 18
|
|
47
|
-
- Um agente de código com hooks
|
|
47
|
+
- Um agente de código com hooks. O `init` wira o **Claude Code** e o **Codex** automaticamente — no Codex ele wira os sete hooks que o modelo de eventos de lá suporta, e eles nascem *Untrusted*, então aprove o "Hooks need review" no primeiro startup (veja [Notas & roadmap](#notas--roadmap))
|
|
48
48
|
- Obsidian (pra ver o grafo) — opcional, mas é o ponto
|
|
49
49
|
|
|
50
50
|
## Instalar & configurar
|
|
@@ -58,19 +58,20 @@ npx wendkeep init
|
|
|
58
58
|
O `wendkeep init` é interativo e **idempotente**. Ele:
|
|
59
59
|
|
|
60
60
|
1. Cria a taxonomia de pastas do cofre e um `README.md` templado (cofre padrão: `<projeto>/.<nome-do-projeto>-vault`, ex.: `.MeuApp-vault`; sobrescreva com `--vault`).
|
|
61
|
-
2. Grava um vínculo provider-neutral **`.wendkeep.json`** na raiz do projeto e o marcador correspondente `.brain/PROJECT.json` no cofre.
|
|
62
|
-
3.
|
|
63
|
-
4.
|
|
64
|
-
|
|
61
|
+
2. Grava um vínculo provider-neutral **`.wendkeep.json`** na raiz do projeto e o marcador correspondente `.brain/PROJECT.json` no cofre, e faz merge dos hooks de sessão no **`.claude/settings.json`**. O vínculo é provider-neutral de propósito: qualquer agente resolve o mesmo cofre pelo `cwd` da sessão, sem variável global da máquina. Registros antigos em `.claude/settings.json` são adotados automaticamente.
|
|
62
|
+
3. Wira os hooks de sessão do Codex em **`.codex/hooks.json`** — sete dos doze: `brain-inject` + `session-start` no `SessionStart`, `session-ensure` + `change-context` no `UserPromptSubmit`, `session-stop` + `change-nag` no `Stop`, `subagent-stop` no `SubagentStop`, sempre na forma `npx wendkeep hook <name>`. Os outros cinco ficam de fora por falta de payload, ferramenta ou evento equivalente no Codex: `change-guard` (gate `PreToolUse` que lê `tool_input.command`; no `exec` do Codex o `tool_input` existe, mas como string crua em vez de objeto — o gate degradaria para liberar tudo, falhando *aberto*), `change-warn` (*nudge* `PostToolUse` que resolve `tool_input.file_path`, campo que o envelope do `apply_patch` não carrega — não há o que resolver nem o que barrar), `plan-capture` (não existe `ExitPlanMode`; o `update_plan` é a lista de TODO em andamento, não uma aprovação), `decision-capture` (`AskUserQuestion` é ferramenta só do Claude) e `task-log` (`TaskCompleted` não está no enum de eventos do Codex). O merge é não‑destrutivo, na mesma disciplina do `settings.json`: reconhece o grupo já wirado e não duplica em re‑init, preserva hooks de terceiros, salva um `.bak`, e o `--force` atualiza `timeoutSec`/`statusMessage` no lugar; um `.codex/hooks.json` ilegível não é tocado e o merge vai pro `.codex/hooks.json.new`. **O Codex enumera todo hook como Untrusted e só executa depois que você aprovar o "Hooks need review" no startup — o `init` não consegue pré-aprovar**, e ele imprime um aviso sobre isso. Quem já tinha hooks wendkeep no Codex escritos à mão leva um prompt de re-revisão: o `init` migra a chave legada `timeout` (que o Codex não rejeita nem lê, caindo no default de 600s) pra `timeoutSec`, e isso muda a identidade com hash do hook.
|
|
63
|
+
4. Adiciona o servidor MCP **`wendkeep-vault`** ao `.mcp.json` pro agente ler/escrever o cofre. Pule com `--no-mcp` — ex.: quando o agente já tem um MCP de cofre. (`--no-mcp` pula *só o MCP do próprio wendkeep*; os MCPs de companion seguem `--companions`.)
|
|
64
|
+
5. Oferece fixar plugins/MCP **companion** (múltipla escolha; **nenhum** pré-marcado — o wendkeep é um harness neutro e não presume plugin de terceiro). Cada um é wirado do jeito mais agnóstico que suporta:
|
|
65
|
+
- **`context-mode`** — otimizador de contexto + memória FTS5, wirado como plugin do Claude Code. Ele traz o próprio servidor MCP, então o wendkeep de propósito não adiciona entrada no `.mcp.json` (registrar os dois subia dois servidores ao mesmo tempo). Em agentes não‑Claude, adicione o MCP à mão: `npx -y context-mode`.
|
|
65
66
|
- **`understand-anything`** — grafo de domínio do projeto, via um hook `understand-inject` no SessionStart que injeta o grafo quando gerado.
|
|
66
67
|
- **`caveman`** — modo de compressão de tokens; roda seu próprio instalador cross‑agent em agentes não‑Claude.
|
|
67
|
-
- **`dotcontext`** — *legado, não recomendado.* O loop a2 nativo do wendkeep (`change` / `verify` / gate) já faz o trabalho dele, então instalar **duplica o harness**.
|
|
68
|
+
- **`dotcontext`** — *legado, não recomendado, e oculto do seletor.* O loop a2 nativo do wendkeep (`change` / `verify` / gate) já faz o trabalho dele, então instalar **duplica o harness**. Alcançável só via um `--companions dotcontext` explícito, pra quem já usa (ajuste com `--dotcontext-mcp` / `--dotcontext-hooks`).
|
|
68
69
|
|
|
69
70
|
Controle com `--companions <csv>` ou `--no-companions`. A camada de plugin do Claude Code (`extraKnownMarketplaces` + `enabledPlugins`) é wirada como bônus onde o companion tiver uma.
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
71
|
+
6. Instala um **sistema de cores** no `.obsidian/` do cofre: um snippet CSS que colore notas por tipo (sessão/decisão/bug/aprendizado, via as `cssclasses` que os hooks emitem) mais grupos de cor do grafo por pasta. Merge não‑destrutivo em `appearance.json`/`graph.json`; pule com `--no-colors`.
|
|
72
|
+
7. Semeia a **camada de memória curada**: `.brain/CORE.md` (a camada quente curada à mão, com as 3 seções obrigatórias) e `.brain/COMPACTION_PROTOCOL.md` (o guia do protocolo). As camadas automáticas (`DIGEST.md`, `index.jsonl`) são geradas pelos hooks. Valide a camada curada com `wendkeep validate-memory` (cap 25 linhas, 3 seções, sem segredos/PII).
|
|
73
|
+
8. Semeia a **camada de definições + skills**: `.brain/agents/` + `.brain/skills/` (fonte da verdade versionada), incluindo as skills de processo nativas `wk-workflow` / `wk-tdd` / `wk-debugging` / `wk-brainstorming` / `wk-planning` / `wk-verify` (algumas trazem templates, ex.: o `verdict-template.json` + prompt de revisor da `wk-verify`). O `init` roda o `wendkeep sync-defs` pra você, entregando as skills em `.claude/skills/` e `.agents/skills/`, e as definições de agent (`.brain/agents/*.toml`) em `.codex/agents/`, mais uma seção gerenciada no `AGENTS.md` que indexa as skills pro Codex; o `sync-defs --check` detecta cópias defasadas (rode `sync-defs` de novo após editar o `.brain`).
|
|
74
|
+
9. Semeia o **ciclo change/spec**: as pastas `07-Specs/` + `08-Mudanças/` e um `wendkeep.sensors.json` nativo — um sensor crítico `memory-validation` (`npx wendkeep validate-memory`) mais um para cada `typecheck` / `test` / `lint` / `build` encontrado no seu `package.json`. Adicione os seus com `wendkeep sensors add`. É o que alimenta o `wendkeep change` / `wendkeep verify` — veja **Ciclo de mudança** abaixo.
|
|
74
75
|
|
|
75
76
|
```bash
|
|
76
77
|
npx wendkeep init --vault "~/vaults/work" --project . --yes # não-interativo
|
|
@@ -126,25 +127,28 @@ Reinicie Codex e Claude Code depois de resemear as skills geradas.
|
|
|
126
127
|
|---|---|
|
|
127
128
|
| `wendkeep init` | Configura o wendkeep num projeto (taxonomia do cofre + settings + MCP + skills). |
|
|
128
129
|
| `wendkeep hook <name>` | Roda um hook de sessão; invocado pelo `settings.json` (lê o JSON do agente no stdin). |
|
|
129
|
-
| `wendkeep change <sub>` | Ciclo de mudança: `new [--simple]` / `list` (backlog global) / `show
|
|
130
|
-
| `wendkeep verify [--deep]` | Roda os sensores das tarefas da change; `--deep` monta o pacote de verificação independente. |
|
|
131
|
-
| `wendkeep spec <sub>` | Specs vivos: `list` / `show <capability
|
|
132
|
-
| `wendkeep sensors <sub>` | `list` / `add <id> "<comando>"` — vê/edita `wendkeep.sensors.json` (JSON Schema incluso). |
|
|
133
|
-
| `wendkeep cost [opts]` | Agrega o gasto de IA nas sessões do cofre — total, por modelo, por dia · `--top [N]` · `--trend [day\|week\|month]` (+ projeção) · `--write` (gera `00-Custo.md`) · `--json`. |
|
|
134
|
-
| `wendkeep cost rebuild [opts]` | Reconstrói custos históricos do transcript principal e subagents via `SESSION_REGISTRY`. Dry-run por padrão; `--apply` grava notas e `.brain/COST_REBUILD.json`. |
|
|
130
|
+
| `wendkeep change <sub>` | Ciclo de mudança: `new <slug> [--simple]` / `use <slug>` (troca o foco) / `continue <arquivada> <nova>` / `bind <slug> --session <id>` / `list` (backlog global) / `show <slug>` / `status [slug]` / `done <id> [--change slug]` / `undone <id> [--change slug]` / `relink [--apply] [--json]` (conserta os wikilinks das changes; prévia por padrão) / `diff [slug]` / `archive [slug] [--force]` / `abandon [slug]` (descarta sem ADR). `diff`, `archive` e `abandon` caem na change ativa quando você omite o slug; o `status` pelado lista todas as abertas. |
|
|
131
|
+
| `wendkeep verify [--deep] [--change s]` | Roda os sensores das tarefas da change; `--deep` monta o pacote de verificação independente. `--change` mira uma change que não é a ativa. |
|
|
132
|
+
| `wendkeep spec <sub>` | Specs vivos: `list` / `show <capability>` / `effective [--change <slug>] [--json]` (contrato vivo + delta; usa a change ativa por padrão) / `migrate` / `rebase [--accept-current]` (para em conflito, a não ser que você aceite o lado do spec vivo). |
|
|
133
|
+
| `wendkeep sensors <sub>` | `list` / `add <id> "<comando>"` com `--severity` / `--type` / `--report` / `--name` / `--description` — vê/edita `wendkeep.sensors.json` (JSON Schema incluso). |
|
|
134
|
+
| `wendkeep cost [opts]` | Agrega o gasto de IA nas sessões do cofre — total, por modelo, por dia · `--since <data>` · `--top [N]` · `--trend [day\|week\|month]` (+ projeção) · `--write` (gera `00-Custo.md`) · `--json`. |
|
|
135
|
+
| `wendkeep cost rebuild [opts]` | Reconstrói custos históricos do transcript principal e subagents via `SESSION_REGISTRY`. Dry-run por padrão; `--apply` grava notas e `.brain/COST_REBUILD.json`. Também `--session <id\|arquivo>` / `--limit n` / `--json`. |
|
|
135
136
|
| `wendkeep session list\|show\|use` | Lista o registry multi-sessão, mostra uma conversa ou muda somente o foco humano de `CURRENT_SESSION.md`. |
|
|
136
|
-
| `wendkeep change bind <slug> --session <id>` | Vincula ou transfere uma change para uma conversa canônica sem esconder as demais pendências. |
|
|
137
|
-
|
|
138
|
-
As notas de sessão usam um único snapshot vivo `## Agentes, tokens e custos`. Os hooks do agente principal e dos subagents recompõem o bloco atomicamente, incluindo custo, dimensões de tokens, reasoning e effort por modelo/origem.
|
|
139
137
|
| `wendkeep stats [--vault P]` | Uma linha compartilhável: sessões · prompts · gasto · período · modelos (`--json`). |
|
|
140
|
-
| `wendkeep import [opts]` | **Memória retroativa** — importa sessões passadas de **Claude + Codex** pro cofre (dedup por `session_id`). `--source all\|claude\|codex` / `--from <dir>` / `--codex-from <dir>` / `--
|
|
138
|
+
| `wendkeep import [opts]` | **Memória retroativa** — importa sessões passadas de **Claude + Codex** pro cofre (dedup por `session_id`). `--source all\|claude\|codex` / `--stamp-ids` / `--rescan-decisions` / `--from <dir>` / `--codex-from <dir>` / `--since d` / `--limit n` / `--dry-run` / `--json`. |
|
|
141
139
|
| `wendkeep dashboard [--force]` | (Re)gera os Bases filtrados por pasta + o MOC `00-Dashboard`. |
|
|
140
|
+
| `wendkeep note new --type bug\|learning "<título>"` | Cria uma nota derivada **numerada** (`BUG-`/`APR-NNNN`) na pasta do mês e imprime o caminho no cofre. `--date YYYY-MM-DD`. |
|
|
141
|
+
| `wendkeep renumber-decisions` | Renumera `04-Decisões` pra `ADR-NNNN-<slug>` em ordem cronológica, tira as notas de subpastas legadas `DIA N` pra pasta do mês e reescreve os wikilinks. Prévia por padrão; `--apply` / `--json`. |
|
|
142
|
+
| `wendkeep renumber-bugs` | Idem pra `05-Bugs` → `BUG-NNNN-<slug>`. |
|
|
143
|
+
| `wendkeep renumber-learnings` | Idem pra `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
|
|
142
144
|
| `wendkeep lesson add "t" "l"` | Registra uma lição local do projeto (injetada no próximo SessionStart). |
|
|
143
|
-
| `wendkeep sync-defs` | Copia `.brain/agents\|skills` pro projeto (`.codex/agents`, `.claude/skills`). |
|
|
145
|
+
| `wendkeep sync-defs` | Copia `.brain/agents\|skills` pro projeto (`.codex/agents`, `.claude/skills`, `.agents/skills`); `--check` detecta drift, `--reseed` ressemeia as skills `wk-*` com os seeds da versão instalada. |
|
|
144
146
|
| `wendkeep validate-memory [path]` | Valida `.brain/CORE.md` (cap 25, 3 seções, sem segredos/PII). |
|
|
145
147
|
| `wendkeep doctor [--vault P]` | Roda um check de saúde do cofre (integridade de sessões, registry, links). |
|
|
146
148
|
| `wendkeep --version` / `--help` | Versão / uso. |
|
|
147
149
|
|
|
150
|
+
As notas de sessão usam um único snapshot vivo `## Agentes, tokens e custos`. Os hooks do agente principal e dos subagents recompõem o bloco atomicamente, incluindo custo, dimensões de tokens, reasoning e effort por modelo/origem.
|
|
151
|
+
|
|
148
152
|
## Memória retroativa (`import`) — instale hoje, lembre de ontem
|
|
149
153
|
|
|
150
154
|
Instale o wendkeep num projeto existente e ele só lembra sessões **a partir de agora**. O `wendkeep import` conserta isso: um comando importa as sessões passadas de **Claude & Codex** do projeto pro cofre — dedup, datadas, com custo — então o grafo começa cheio, não vazio. Reconstrói cada transcript como uma nota de sessão completa na pasta datada **real** — frontmatter (taggeado com o provedor real), um bloco de iteração por turno, custo + telemetria de subagents, notas derivadas de decisão/bug/aprendizado, encerramento finalizado. Um replay offline do fluxo de captura vivo, então uma nota importada é indistinguível de uma capturada.
|
|
@@ -158,8 +162,46 @@ wendkeep import --vault .meuprojeto-vault --source codex # só Codex
|
|
|
158
162
|
- **Os dois agentes por padrão** (`--source all`). As sessões do Claude vêm de `~/.claude/projects/<slug>/`; os rollouts do Codex de `~/.codex/sessions/**`, escopados pro projeto pelo `cwd` gravado em cada sessão (insensível a case e separador, subpastas inclusas). Estreite com `--source claude` / `--source codex`.
|
|
159
163
|
- Toda nota grava o **`session_id`** e o **`provider`** no frontmatter (captura live e import iguais). Carimbe notas antigas com `wendkeep import --stamp-ids` (preenche o id a partir do registry; idempotente).
|
|
160
164
|
- **Dedup** por `session_id` contra o `SESSION_REGISTRY` do cofre **e** o frontmatter das notas existentes — só importa sessões ausentes e nunca sobrescreve. Rodar de novo é no‑op.
|
|
165
|
+
- **`--from <dir>`** / **`--codex-from <dir>`** apontam as pastas de transcript explicitamente (use se o caminho auto‑derivado errar). Também: `--since <data>`, `--limit <n>`, `--rescan-decisions`, `--json`.
|
|
161
166
|
- Depois de importar, o `wendkeep cost` agrega seu histórico inteiro — retroativamente, nos dois agentes.
|
|
162
167
|
|
|
168
|
+
## Notas derivadas — numeradas como ADRs (`note new`, `renumber-*`)
|
|
169
|
+
|
|
170
|
+
Decisões, bugs e aprendizados são **notas derivadas**: vivem na pasta do mês da sua árvore (`<pasta>/<ano>/<MM-MMM>/`) e carregam um id sequencial — `ADR-0001`, `BUG-0001`, `APR-0001`. Uma olhada já diz o que a nota é e onde ela cai na história do projeto. Sem subpasta por dia: uma pasta `DIA N` com uma nota só é ruído, e esconde a nota da busca por pasta.
|
|
171
|
+
|
|
172
|
+
**Criando uma** (nunca escreva o arquivo à mão — o comando é dono do número, da pasta e do frontmatter):
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
wendkeep note new --type bug "login dá 500 quando o token expira no meio do refresh"
|
|
176
|
+
# → 05-Bugs/2026/07-JUL/BUG-0007-login-da-500-quando-o-token-expira-no-meio-do-refresh.md
|
|
177
|
+
|
|
178
|
+
wendkeep note new --type learning "regex sem /g só retorna o primeiro match"
|
|
179
|
+
# → 06-Aprendizados/2026/07-JUL/APR-0003-regex-sem-g-so-retorna-o-primeiro-match.md
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
Ele imprime o caminho criado, numera a partir do máximo atual (varredura recursiva), arquiva na pasta do mês de hoje (`--date YYYY-MM-DD` pra sobrescrever) e linka a sessão ativa em `source:` pro grafo seguir conectado. Os agentes recebem essa regra injetada no SessionStart — chamam o comando em vez de chutar um nome de arquivo.
|
|
183
|
+
|
|
184
|
+
**Migrando um cofre existente.** Notas criadas antes da `0.41.0` têm nome com prefixo de data (`2026-07-16-bug-<slug>.md`) e podem estar em subpastas legadas `DIA N`. Um comando por árvore renumera cronologicamente, sobe as notas pra pasta do mês e reescreve todos os wikilinks do cofre:
|
|
185
|
+
|
|
186
|
+
```bash
|
|
187
|
+
# Bugs — 05-Bugs → BUG-NNNN
|
|
188
|
+
wendkeep renumber-bugs # prévia: imprime cada de → para, não escreve nada
|
|
189
|
+
wendkeep renumber-bugs --apply # migra
|
|
190
|
+
|
|
191
|
+
# Aprendizados — 06-Aprendizados → APR-NNNN
|
|
192
|
+
wendkeep renumber-learnings # prévia
|
|
193
|
+
wendkeep renumber-learnings --apply # migra
|
|
194
|
+
|
|
195
|
+
# Decisões — 04-Decisões → ADR-NNNN (desde a 0.30.0)
|
|
196
|
+
wendkeep renumber-decisions # prévia
|
|
197
|
+
wendkeep renumber-decisions --apply # migra
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
- **Prévia é o padrão.** Nada é escrito até o `--apply` — leia a lista `de → para` primeiro; é ali que um slug estropiado aparece, antes de tocar seus arquivos.
|
|
201
|
+
- **Uma árvore por vez, de propósito.** Não existe `renumber-all`: cada pasta é migrada e revisada por conta própria.
|
|
202
|
+
- **A ordem é cronológica**, derivada da data da nota (frontmatter → prefixo do nome → pasta), então `BUG-0001` é de fato o bug mais antigo — não o primeiro que o scanner leu.
|
|
203
|
+
- **Wikilinks são reescritos no cofre inteiro** (forma com path completo e por basename, aliases preservados), o `type`/`bug:`/`apr:`/H1 do corpo são normalizados e pastas `DIA` esvaziadas são removidas. **Idempotente**: um segundo `--apply` não renomeia nada. Feche o Obsidian durante a migração, e commite o cofre antes se ele estiver sob git.
|
|
204
|
+
|
|
163
205
|
## Ciclo de mudança — o loop a2 (spec‑driven, nativo)
|
|
164
206
|
|
|
165
207
|
Além de capturar sessões, o wendkeep é um **harness**: um loop nativo e sem dependências que mantém *intenção* (specs), *trabalho* (changes) e *prova* (sensores) juntos no cofre, wikilinkados no grafo Obsidian.
|
|
@@ -168,14 +210,48 @@ Além de capturar sessões, o wendkeep é um **harness**: um loop nativo e sem d
|
|
|
168
210
|
explore → propose → apply (TDD) → verify → archive
|
|
169
211
|
```
|
|
170
212
|
|
|
171
|
-
- **Propose** — `wendkeep change new <slug>` faz o scaffold de `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`
|
|
172
|
-
- **Apply** — implemente cada tarefa de `tarefas.md`. Taggeie a tarefa que precisa de prova de máquina com `[sensor:<id>]
|
|
173
|
-
- **Verify** — `wendkeep verify` roda os sensores que suas tarefas declararam (do `wendkeep.sensors.json` na raiz do projeto) e grava `evidencia.json`. Um vermelho crítico falha o gate; um vermelho `warning` é aviso.
|
|
213
|
+
- **Propose** — `wendkeep change new <slug>` faz o scaffold de `08-Mudanças/<slug>/` (`proposta.md`, `design.md`, `tarefas.md`; o `--simple` pula o design). A change vira a *atual* global; `change use <slug>` troca o foco e `change continue <arquivada> <nova>` cria uma continuação auditável. Várias changes podem ficar abertas: hooks e `change list/status` mostram todas as pendências, enquanto comandos sem `--change` usam somente a atual. Quando a change declara `spec_impact: required`, você mesmo escreve o delta em `specs/<capability>/spec.md` — não há placeholder pra apagar.
|
|
214
|
+
- **Apply** — implemente cada tarefa de `tarefas.md`. Taggeie a tarefa que precisa de prova de máquina com `[sensor:<id>]` — um sensor por tarefa (a tarefa carrega um só; quebre em duas se precisar de dois) — e o requisito que ela satisfaz com `[req:<ID>]`, dos quais a tarefa pode declarar vários.
|
|
215
|
+
- **Verify** — `wendkeep verify` roda os sensores que suas tarefas declararam (do `wendkeep.sensors.json` na raiz do projeto) e grava `evidencia.json`. Um vermelho crítico falha o gate; um vermelho `warning` é aviso. O `verify --deep` monta o pacote autocontido de verificação (contrato vivo + delta desta change). Toda change precisa de um `verdict.json` pra arquivar; quando ela não declara `[req:]`, o próprio `verify --deep` grava um verdict trivial.
|
|
174
216
|
- **Archive** — `wendkeep change archive <slug>` faz **gate** na evidência (bloqueia a não ser que todo sensor crítico declarado esteja verde), promove o delta de cada capability (`ADDED`/`MODIFIED`/`REMOVED`) pro `07-Specs/<capability>.md` vivo, move a change pro `_arquivo/` e cunha um ADR em `04-Decisões/`.
|
|
175
217
|
|
|
176
|
-
> O gate bloqueia a não ser que o scaffold esteja preenchido, nenhuma tarefa aberta, evidência fresca e todo requisito declarado coberto.
|
|
218
|
+
> O gate bloqueia a não ser que o scaffold esteja preenchido, nenhuma tarefa aberta, evidência fresca e todo requisito declarado coberto. **O `--force` dispensa exatamente uma dessas — a checagem de tarefa aberta — e é decisão do humano, nunca do agente.** Scaffold não preenchido, sensor crítico vermelho, evidência stale, requisito órfão ou verdict ausente bloqueiam de qualquer jeito.
|
|
219
|
+
|
|
220
|
+
O `wendkeep init` também semeia **skills de processo nativas** (`wk-workflow`, `wk-tdd`, `wk-debugging`, `wk-brainstorming`, `wk-planning`, `wk-verify`) no `.brain/skills` do cofre e as entrega em `.claude/skills/` e `.agents/skills/` — a camada do *como*, zero‑dep. O Codex recebe as definições de agent (`.brain/agents/*.toml` → `.codex/agents/`) mais uma seção gerenciada no `AGENTS.md` que indexa as skills. Cada skill carrega metadados de hash/versão da fonte; o `doctor` avisa quando é preciso ressemear e reiniciar o agente. Companions opcionais (`context-mode`, `dotcontext`, `understand-anything`, `caveman`) ficam como camada extra opt‑in.
|
|
221
|
+
|
|
222
|
+
### O loop em cinco minutos
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
npx wendkeep init --yes # cofre + hooks + sensores + skills
|
|
226
|
+
npx wendkeep change new dark-mode # proposta/design/tarefas — a change fica ativa
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
Edite o `tarefas.md` — marque a prova e o requisito por tarefa:
|
|
230
|
+
|
|
231
|
+
```markdown
|
|
232
|
+
- [ ] 1.1 o toggle persiste entre sessões [req:UI-1] [sensor:tests]
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Declare a capability na `proposta.md` (`specs: [ui]`) e escreva o delta dela só em
|
|
236
|
+
`08-Mudanças/<slug>/specs/ui/spec.md`. O `07-Specs` é gerado/read-only. Então:
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
npx wendkeep change status # todas as changes abertas + tarefas pendentes
|
|
240
|
+
npx wendkeep change list # o mesmo backlog, mais as arquivadas
|
|
241
|
+
npx wendkeep change status dark-mode # uma tela pra uma change: specs / tarefas / sensores / veredito
|
|
242
|
+
npx wendkeep spec effective --change dark-mode # contrato vivo + delta desta change
|
|
243
|
+
npx wendkeep change done 1.1 # marca uma tarefa pela CLI
|
|
244
|
+
npx wendkeep verify # roda os sensores declarados -> evidencia.json
|
|
245
|
+
npx wendkeep verify --deep # monta o pacote de verificação
|
|
246
|
+
# a skill wk-verify (passe fresco, read-only) grava o verdict.json
|
|
247
|
+
npx wendkeep change diff # prévia do que vai cair no 07-Specs
|
|
248
|
+
npx wendkeep change archive dark-mode # gate: sensores + verdict + nenhuma tarefa aberta
|
|
249
|
+
```
|
|
177
250
|
|
|
178
|
-
O
|
|
251
|
+
O archive promove o delta pro `07-Specs/ui.md` gerado, cunha um ADR, e o grafo do Obsidian
|
|
252
|
+
agora liga *sessão ↔ change ↔ requisito ↔ decisão*. Uma change que não nomeia nenhum
|
|
253
|
+
`[req:]` ainda roda o `verify --deep`, mas pula o passe de leitura do `wk-verify`: o próprio
|
|
254
|
+
comando grava um verdict trivial e o gate de sensores é a prova real.
|
|
179
255
|
|
|
180
256
|
## Como funciona
|
|
181
257
|
|
|
@@ -184,16 +260,17 @@ sessão do agente ──hooks──▶ wendkeep ──▶ Markdown no cofre ─
|
|
|
184
260
|
(Claude/Codex) (Node) (02-Sessões/…) (CORE+DIGEST, backlinks)
|
|
185
261
|
```
|
|
186
262
|
|
|
187
|
-
O settings.json do agente aponta cada hook pra `npx wendkeep hook
|
|
263
|
+
O settings.json do agente aponta cada hook pra `npx wendkeep hook …`; no Claude Code, os hooks do ciclo de mudança rodam o script instalado direto (`node` em `${CLAUDE_PROJECT_DIR}/node_modules/wendkeep/hooks/<name>.mjs`) quando o pacote está presente local, pulando uma resolução do npx a cada evento. O `.codex/hooks.json` usa sempre a forma `npx` — o `${CLAUDE_PROJECT_DIR}` não existe no Codex — com chaves de evento em PascalCase e o timeout em `timeoutSec`. No `Stop`, o wendkeep parseia o transcript, anexa o turno, atualiza a tabela de tokens/custo e (idempotentemente) emite qualquer nota de decisão/bug/aprendizado. No `SessionStart` — startup, `/clear` e `/compact` — o `brain-inject` injeta a memória curada (CORE + DIGEST), todas as changes abertas com suas pendências, o marcador global da change atual, as lições do projeto e o roteador `<wk_process>`. Claude, Codex ou outro agente podem assim retomar trabalho iniciado em outro lugar sem ocultar o restante do backlog.
|
|
188
264
|
|
|
189
|
-
O **gate** do archive bloqueia a não ser que: o scaffold da change esteja preenchido (G0), nenhuma tarefa esteja aberta (G1), todo sensor crítico declarado esteja verde (com evidência fresca) e
|
|
265
|
+
O **gate** do archive bloqueia a não ser que: o scaffold da change esteja preenchido (G0), nenhuma tarefa esteja aberta (G1), todo sensor crítico declarado esteja verde (com evidência fresca) e exista um `verdict.json` presente e atual. O `--force` dispensa só o G1 — o G0 é inescapável por design (uma change placeholder forçada uma vez cunhou um ADR falso), e nenhuma flag torna verde um sensor vermelho ou um verdict ausente. O agente é instruído a nunca usar por conta própria.
|
|
190
266
|
|
|
191
267
|
## Notas & roadmap
|
|
192
268
|
|
|
193
269
|
- **Nomes das pastas do cofre são em Português por padrão** (`02-Sessões`, `04-Decisões`, …). Passe `wendkeep init --locale en` pra um cofre em inglês (`02-Sessions`, `04-Decisions`, scaffold/skills em inglês). O locale é uma propriedade do cofre, travada no init; os parsers são bilíngues, então conteúdo misto nunca quebra.
|
|
194
270
|
- **Busca é scoring por keyword/frontmatter**, não embeddings on‑device (isso está no roadmap).
|
|
195
271
|
- **Formatos de transcript são internos ao agente** e podem mudar entre versões; o parsing é isolado mas pode precisar de atualizações.
|
|
196
|
-
- O instalador wira settings do **Claude Code** + `.mcp.json`.
|
|
272
|
+
- O instalador wira settings do **Claude Code** + **`.codex/hooks.json`** + `.mcp.json`. **No Codex vão sete dos doze hooks** — os outros cinco não têm payload, ferramenta ou evento equivalente: `change-guard` (gate `PreToolUse` que lê `tool_input.command`, mas o `exec` do Codex carrega `tool_input` como string crua, não objeto — o gate falharia *aberto*), `change-warn` (*nudge* `PostToolUse` que resolve `tool_input.file_path`, campo ausente do envelope do `apply_patch` — não há o que resolver nem o que barrar), `plan-capture` (não existe `ExitPlanMode`; o `update_plan` é lista de TODO em andamento, não aprovação), `decision-capture` (`AskUserQuestion` é ferramenta só do Claude) e `task-log` (`TaskCompleted` não está no enum de eventos do Codex). Ou seja: captura de sessão, custo e memória funciona igual, mas os avisos de mudança ligados a ferramenta e a captura de plano/decisão/tarefa são só do Claude. Os hooks também só rodam depois que você aprovar o "Hooks need review" — o `init` não consegue pré-aprovar. Pra sessões Codex anteriores ao wiring, use `import --source codex`.
|
|
273
|
+
- **Os hooks do Codex nascem Untrusted.** Eles são enumerados, mas não executados, até você aprovar o "Hooks need review"; o `init` não consegue pré‑aprovar (o `--dangerously-bypass-hook-trust` vale só por invocação e não grava nenhum trusted hash). A confiança é atrelada à identidade do hook, então quem tinha hooks wendkeep do Codex escritos à mão antes da `0.46.0` — que rodavam no default de 600s por usarem `timeout` em vez de `timeoutSec` — paga uma re‑revisão única depois que o `init` corrige a chave. Isso é esperado, não é regressão.
|
|
197
274
|
|
|
198
275
|
---
|
|
199
276
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "wendkeep",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.46.0",
|
|
4
4
|
"description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -46,6 +46,6 @@
|
|
|
46
46
|
"url": "https://github.com/rogersialves/wendkeep/issues"
|
|
47
47
|
},
|
|
48
48
|
"devDependencies": {
|
|
49
|
-
"wendkeep": "^0.
|
|
49
|
+
"wendkeep": "^0.45.0"
|
|
50
50
|
}
|
|
51
51
|
}
|
package/src/init.mjs
CHANGED
|
@@ -16,6 +16,9 @@ import {
|
|
|
16
16
|
hookCommand,
|
|
17
17
|
hookCommandLocal,
|
|
18
18
|
hookCommandLocalLegacy,
|
|
19
|
+
codexHookSpecs,
|
|
20
|
+
codexHookEntry,
|
|
21
|
+
CODEX_MATCHER_EVENTS,
|
|
19
22
|
deriveVaultDirName,
|
|
20
23
|
selectableCompanions,
|
|
21
24
|
resolveCompanions,
|
|
@@ -192,6 +195,47 @@ export function mergeSettings(existing, { vaultPath, withMcp, force, companions
|
|
|
192
195
|
return { settings: s, added };
|
|
193
196
|
}
|
|
194
197
|
|
|
198
|
+
// Codex counterpart of mergeSettings: projects the SAME hook specs into the shape Codex
|
|
199
|
+
// reads from <project>/.codex/hooks.json. Deliberately simpler than mergeSettings — there
|
|
200
|
+
// is only one command form (npx), so there is no dual-recognition to do. The one migration
|
|
201
|
+
// it does handle is the legacy `timeout` key, which Codex silently ignores in favour of a
|
|
202
|
+
// 600s default; rewriting it to `timeoutSec` invalidates the stored trusted_hash and costs
|
|
203
|
+
// the user one "Hooks need review" prompt. That is the point.
|
|
204
|
+
export function mergeCodexHooks(existing, { force = false } = {}) {
|
|
205
|
+
const file = existing && typeof existing === 'object' ? { ...existing } : {};
|
|
206
|
+
file.hooks = { ...(file.hooks || {}) };
|
|
207
|
+
const specs = codexHookSpecs([...SESSION_HOOKS, ...CHANGE_NUDGE_HOOKS, ...CHANGE_GATE_HOOKS])
|
|
208
|
+
.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
|
|
209
|
+
for (const h of specs) {
|
|
210
|
+
const entry = codexHookEntry(h);
|
|
211
|
+
const owns = (x) => x.command === entry.command;
|
|
212
|
+
const groups = Array.isArray(file.hooks[h.event]) ? [...file.hooks[h.event]] : [];
|
|
213
|
+
const owning = groups.find((g) => (g.hooks || []).some(owns));
|
|
214
|
+
if (owning) {
|
|
215
|
+
const hk = owning.hooks.find(owns);
|
|
216
|
+
// `timeout` is the pre-0.46 key: Codex never read it. Migrate it even without --force,
|
|
217
|
+
// otherwise the hook keeps running at the 600s default forever.
|
|
218
|
+
const legacyTimeout = 'timeout' in hk;
|
|
219
|
+
if (force || legacyTimeout) {
|
|
220
|
+
if (legacyTimeout) {
|
|
221
|
+
if (hk.timeoutSec === undefined) hk.timeoutSec = hk.timeout;
|
|
222
|
+
delete hk.timeout;
|
|
223
|
+
}
|
|
224
|
+
if (force) {
|
|
225
|
+
hk.timeoutSec = entry.timeoutSec;
|
|
226
|
+
if (entry.statusMessage) hk.statusMessage = entry.statusMessage;
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
file.hooks[h.event] = groups;
|
|
230
|
+
continue;
|
|
231
|
+
}
|
|
232
|
+
const matcher = CODEX_MATCHER_EVENTS.has(h.event) ? h.matcher : null;
|
|
233
|
+
groups.push(matcher ? { matcher, hooks: [entry] } : { hooks: [entry] });
|
|
234
|
+
file.hooks[h.event] = groups;
|
|
235
|
+
}
|
|
236
|
+
return file;
|
|
237
|
+
}
|
|
238
|
+
|
|
195
239
|
export function mergeMcp(existing, { vaultPath, withVault = true, companions = [], skipMcp = [] }) {
|
|
196
240
|
const m = existing && typeof existing === 'object' ? { ...existing } : {};
|
|
197
241
|
m.mcpServers = { ...(m.mcpServers || {}) };
|
|
@@ -278,16 +322,19 @@ const MESSAGES = {
|
|
|
278
322
|
lCompanions: ' companions ', lColors: ' cores ',
|
|
279
323
|
skipped: 'ignorado', none: 'nenhum',
|
|
280
324
|
colorsOn: 'wendkeep-colors (snippet + grupos do grafo)',
|
|
281
|
-
taxonomy: (n, c, loc, readme, views) => ` [1/
|
|
325
|
+
taxonomy: (n, c, loc, readme, views) => ` [1/5] taxonomia do vault: ${n} pastas (${c} criadas, locale ${loc})${readme}, .brain + change/spec + sensores semeados${views}`,
|
|
282
326
|
readmeCreated: ', README.md criado', viewsNote: (n) => `, ${n} view(s) + dashboard`,
|
|
283
327
|
defs: (s, a) => ` defs entregues: ${s} skill(s) -> .claude/skills + .agents/skills, ${a} agent(s) -> .codex/agents`,
|
|
284
|
-
settingsBadJson: (p) => ` [2/
|
|
285
|
-
settings: (verb, added, bak) => ` [2/
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
328
|
+
settingsBadJson: (p) => ` [2/5] settings.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
|
|
329
|
+
settings: (verb, added, bak) => ` [2/5] settings.json ${verb} (${added} hook(s) wirados; .wendkeep.json é o vínculo compartilhado${bak})`,
|
|
330
|
+
codexBadJson: (p) => ` [3/5] .codex/hooks.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
|
|
331
|
+
codexHooks: (verb, bak) => ` [3/5] .codex/hooks.json ${verb} (hooks de sessão do Codex${bak})`,
|
|
332
|
+
codexTrust: ' [!] o Codex só executa esses hooks depois que você aprovar "Hooks need review" no startup — o init não consegue pré-aprovar.',
|
|
333
|
+
mcpBadJson: (p) => ` [4/5] .mcp.json existe mas não é JSON válido -> escrevi ${p}.new (mescle à mão)`,
|
|
334
|
+
mcp: (verb, names, bak) => ` [4/5] .mcp.json ${verb} (${names}${bak})`,
|
|
335
|
+
mcpSkipped: ' [4/5] .mcp.json ignorado (--no-mcp, sem companions MCP)',
|
|
336
|
+
colorsSkipped: ' [5/5] cores ignoradas (--no-colors)',
|
|
337
|
+
colors: (r) => ` [5/5] cores: ${r}`,
|
|
291
338
|
merged: 'mesclado', created: 'criado', bakSaved: ', .bak salvo',
|
|
292
339
|
nextSteps: '\nPróximos passos:',
|
|
293
340
|
step1: (v) => ` 1. Abra o vault no Obsidian: "Abrir pasta como cofre" -> ${v}`,
|
|
@@ -303,16 +350,19 @@ const MESSAGES = {
|
|
|
303
350
|
lCompanions: ' companions ', lColors: ' colors ',
|
|
304
351
|
skipped: 'skipped', none: 'none',
|
|
305
352
|
colorsOn: 'wendkeep-colors (snippet + graph groups)',
|
|
306
|
-
taxonomy: (n, c, loc, readme, views) => ` [1/
|
|
353
|
+
taxonomy: (n, c, loc, readme, views) => ` [1/5] vault taxonomy: ${n} folders (${c} created, locale ${loc})${readme}, .brain + change/spec + sensors seeded${views}`,
|
|
307
354
|
readmeCreated: ', README.md created', viewsNote: (n) => `, ${n} view(s) + dashboard`,
|
|
308
355
|
defs: (s, a) => ` defs delivered: ${s} skill(s) -> .claude/skills + .agents/skills, ${a} agent(s) -> .codex/agents`,
|
|
309
|
-
settingsBadJson: (p) => ` [2/
|
|
310
|
-
settings: (verb, added, bak) => ` [2/
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
356
|
+
settingsBadJson: (p) => ` [2/5] settings.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
|
|
357
|
+
settings: (verb, added, bak) => ` [2/5] settings.json ${verb} (${added} hook(s) wired; .wendkeep.json is the shared binding${bak})`,
|
|
358
|
+
codexBadJson: (p) => ` [3/5] .codex/hooks.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
|
|
359
|
+
codexHooks: (verb, bak) => ` [3/5] .codex/hooks.json ${verb} (Codex session hooks${bak})`,
|
|
360
|
+
codexTrust: ' [!] Codex only runs these hooks after you approve "Hooks need review" at startup — init cannot pre-approve them.',
|
|
361
|
+
mcpBadJson: (p) => ` [4/5] .mcp.json exists but is not valid JSON -> wrote ${p}.new (merge by hand)`,
|
|
362
|
+
mcp: (verb, names, bak) => ` [4/5] .mcp.json ${verb} (${names}${bak})`,
|
|
363
|
+
mcpSkipped: ' [4/5] .mcp.json skipped (--no-mcp, no MCP companions)',
|
|
364
|
+
colorsSkipped: ' [5/5] colors skipped (--no-colors)',
|
|
365
|
+
colors: (r) => ` [5/5] colors: ${r}`,
|
|
316
366
|
merged: 'merged', created: 'created', bakSaved: ', .bak saved',
|
|
317
367
|
nextSteps: '\nNext steps:',
|
|
318
368
|
step1: (v) => ` 1. Open the vault in Obsidian: "Open folder as vault" -> ${v}`,
|
|
@@ -538,6 +588,22 @@ export async function runInit(argv) {
|
|
|
538
588
|
log(M.settings(hadFile ? M.merged : M.created, added, hadFile ? M.bakSaved : ''));
|
|
539
589
|
}
|
|
540
590
|
|
|
591
|
+
// 2b. .codex/hooks.json -----------------------------------------------------
|
|
592
|
+
// Without this, Codex opens with the vault reachable (via .mcp.json) but no session:
|
|
593
|
+
// CURRENT_SESSION.md never gets written and registrySessions stays 0.
|
|
594
|
+
const codexPath = join(projectPath, '.codex', 'hooks.json');
|
|
595
|
+
const codexRead = readJsonSafe(codexPath);
|
|
596
|
+
if (!codexRead.ok) {
|
|
597
|
+
writeJson(`${codexPath}.new`, mergeCodexHooks(null, { force: true }));
|
|
598
|
+
log(M.codexBadJson(codexPath));
|
|
599
|
+
} else {
|
|
600
|
+
const hadFile = codexRead.data !== null;
|
|
601
|
+
if (hadFile) backup(codexPath);
|
|
602
|
+
writeJson(codexPath, mergeCodexHooks(codexRead.data, { force: args.force }));
|
|
603
|
+
log(M.codexHooks(hadFile ? M.merged : M.created, hadFile ? M.bakSaved : ''));
|
|
604
|
+
}
|
|
605
|
+
log(M.codexTrust);
|
|
606
|
+
|
|
541
607
|
// 3. .mcp.json --------------------------------------------------------------
|
|
542
608
|
// Written when mcpvault is wanted OR a selected companion ships an MCP server.
|
|
543
609
|
const companionMcp = companionMcpPatch(companions, skipMcp);
|
package/src/taxonomy.mjs
CHANGED
|
@@ -102,15 +102,17 @@ export const SESSION_HOOKS = [
|
|
|
102
102
|
// timeout 45 (was 15): measured ~4s warm via npx, but Windows startup contention (several npx
|
|
103
103
|
// cold-starts at once — a sibling MCP took 26s in a real log) blew 15s and silently dropped the
|
|
104
104
|
// memory injection for the whole session.
|
|
105
|
-
{ event: 'SessionStart', matcher: 'startup|clear|compact', name: 'brain-inject', timeout: 45, order: -10, statusMessage: 'wendkeep: injecting memory + active change' },
|
|
106
|
-
{ event: 'SessionStart', matcher: 'startup', name: 'session-start', timeout: 30, statusMessage: 'wendkeep: opening Obsidian session' },
|
|
107
|
-
{ event: 'Stop', matcher: null, name: 'session-stop', timeout: 60, statusMessage: 'wendkeep: writing session checkpoint' },
|
|
108
|
-
{ event: 'UserPromptSubmit', matcher: null, name: 'session-ensure', timeout: 30, statusMessage: 'wendkeep: ensuring active session' },
|
|
105
|
+
{ event: 'SessionStart', matcher: 'startup|clear|compact', name: 'brain-inject', timeout: 45, order: -10, codex: true, statusMessage: 'wendkeep: injecting memory + active change' },
|
|
106
|
+
{ event: 'SessionStart', matcher: 'startup', name: 'session-start', timeout: 30, codex: true, statusMessage: 'wendkeep: opening Obsidian session' },
|
|
107
|
+
{ event: 'Stop', matcher: null, name: 'session-stop', timeout: 60, codex: true, statusMessage: 'wendkeep: writing session checkpoint' },
|
|
108
|
+
{ event: 'UserPromptSubmit', matcher: null, name: 'session-ensure', timeout: 30, codex: true, statusMessage: 'wendkeep: ensuring active session' },
|
|
109
109
|
// Capture an interactive decision (AskUserQuestion) — options + the user's choice — into 04-Decisões.
|
|
110
|
+
// codex: AskUserQuestion is a Claude-only tool; there is nothing to match on.
|
|
110
111
|
{ event: 'PostToolUse', matcher: 'AskUserQuestion', name: 'decision-capture', timeout: 15, statusMessage: 'wendkeep: recording decision' },
|
|
111
112
|
// Refresh subagent/workflow telemetry as each subagent finishes (resilient to a missed Stop).
|
|
112
|
-
{ event: 'SubagentStop', matcher: null, name: 'subagent-stop', timeout: 20, statusMessage: 'wendkeep: subagent telemetry' },
|
|
113
|
+
{ event: 'SubagentStop', matcher: null, name: 'subagent-stop', timeout: 20, codex: true, statusMessage: 'wendkeep: subagent telemetry' },
|
|
113
114
|
// Log plan/task progress into the active session note when a task is marked complete.
|
|
115
|
+
// codex: TaskCompleted is not in Codex's hook event enum.
|
|
114
116
|
{ event: 'TaskCompleted', matcher: null, name: 'task-log', timeout: 10, statusMessage: 'wendkeep: plan progress' },
|
|
115
117
|
];
|
|
116
118
|
|
|
@@ -134,15 +136,39 @@ export function hookCommandLocalLegacy(name) {
|
|
|
134
136
|
// preservar a opção futura de gates opt-in; hoje o init wira TODOS por default.
|
|
135
137
|
// preferLocal: alta frequência → invocação node-direta quando houver instalação local.
|
|
136
138
|
export const CHANGE_NUDGE_HOOKS = [
|
|
137
|
-
{ event: 'UserPromptSubmit', matcher: null, name: 'change-context', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: change ping' },
|
|
139
|
+
{ event: 'UserPromptSubmit', matcher: null, name: 'change-context', timeout: 15, order: 10, preferLocal: true, codex: true, statusMessage: 'wendkeep: change ping' },
|
|
140
|
+
// codex: reads tool_input.file_path, which Codex's apply_patch envelope does not carry.
|
|
138
141
|
{ event: 'PostToolUse', matcher: 'Edit|Write|MultiEdit', name: 'change-warn', timeout: 10, order: 10, preferLocal: true, statusMessage: 'wendkeep: change warn' },
|
|
142
|
+
// codex: no ExitPlanMode equivalent — update_plan is the running TODO list, not an approval.
|
|
139
143
|
{ event: 'PostToolUse', matcher: 'ExitPlanMode', name: 'plan-capture', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: capturing approved plan' },
|
|
140
|
-
{ event: 'Stop', matcher: null, name: 'change-nag', timeout: 15, order: 10, preferLocal: true, statusMessage: 'wendkeep: open tasks check' },
|
|
144
|
+
{ event: 'Stop', matcher: null, name: 'change-nag', timeout: 15, order: 10, preferLocal: true, codex: true, statusMessage: 'wendkeep: open tasks check' },
|
|
141
145
|
];
|
|
142
146
|
export const CHANGE_GATE_HOOKS = [
|
|
147
|
+
// codex: reads tool_input.command; Codex's exec sends a raw string and exec_command an argv,
|
|
148
|
+
// so the guard would silently fail OPEN — worse than absent, since the docs would promise it.
|
|
143
149
|
{ event: 'PreToolUse', matcher: 'Bash', name: 'change-guard', timeout: 10, order: 10, preferLocal: true, statusMessage: 'wendkeep: change gate' },
|
|
144
150
|
];
|
|
145
151
|
|
|
152
|
+
// --- Codex projection ---------------------------------------------------------
|
|
153
|
+
// Codex reads <project>/.codex/hooks.json (PascalCase event keys, same group shape as
|
|
154
|
+
// Claude's settings.json). Only specs that opt in with `codex: true` are projected — the
|
|
155
|
+
// rest carry a `// codex:` comment above them saying why. Three deltas from Claude, each
|
|
156
|
+
// verified against codex-rs and each silent when wrong: the timeout key is `timeoutSec`
|
|
157
|
+
// (`timeout` is not a field and falls through to a 600s default), there is no
|
|
158
|
+
// ${CLAUDE_PROJECT_DIR} so `preferLocal` never applies, and matcher is only honoured on
|
|
159
|
+
// SessionStart (UserPromptSubmit/Stop null it at discovery).
|
|
160
|
+
export const CODEX_MATCHER_EVENTS = new Set(['SessionStart']);
|
|
161
|
+
|
|
162
|
+
export function codexHookSpecs(specs) {
|
|
163
|
+
return specs.filter((h) => h.codex === true && !h.command);
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
export function codexHookEntry(spec) {
|
|
167
|
+
const entry = { type: 'command', command: hookCommand(spec.name), timeoutSec: spec.timeout };
|
|
168
|
+
if (spec.statusMessage) entry.statusMessage = spec.statusMessage;
|
|
169
|
+
return entry;
|
|
170
|
+
}
|
|
171
|
+
|
|
146
172
|
// --- companion plugins / MCP --------------------------------------------------
|
|
147
173
|
// Optional tools wendkeep init can pin alongside the vault. Each is wired through
|
|
148
174
|
// the MOST agent-agnostic mechanism it supports; the Claude Code plugin entry
|
|
@@ -330,7 +356,7 @@ export function deriveVaultDirName(projectPath) {
|
|
|
330
356
|
.pop() || '';
|
|
331
357
|
const clean = base
|
|
332
358
|
.replace(/^[.\s]+/, '') // drop leading dots/space so we never get `..name`
|
|
333
|
-
.replace(/[<>:"
|
|
359
|
+
.replace(/[<>:"/\\|?*\x00-\x1f]/g, '-') // FS-unsafe chars -> dash
|
|
334
360
|
.replace(/\s+/g, '-') // whitespace -> dash
|
|
335
361
|
.replace(/-+/g, '-') // collapse dash runs
|
|
336
362
|
.replace(/^-+|-+$/g, '') // trim edge dashes
|