wendkeep 0.55.0 → 0.57.2
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 +76 -0
- package/README.en.md +333 -0
- package/README.md +50 -13
- package/package.json +6 -3
- package/src/sync.mjs +8 -1
- package/README.pt-BR.md +0 -287
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,82 @@ 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.57.2] — 2026-07-25
|
|
8
|
+
|
|
9
|
+
### Fixed
|
|
10
|
+
|
|
11
|
+
- **O README deixa de recomendar um `pnpm add` que não atualiza.** A seção "Atualizar"
|
|
12
|
+
mandava rodar `pnpm add -D -w wendkeep@latest`. Medido num projeto pnpm limpo, sem
|
|
13
|
+
configuração alguma: o comando devolveu `+ wendkeep 0.49.0 (0.57.1 is available)` e saiu 0.
|
|
14
|
+
O `minimumReleaseAge` de 24h é **default do pnpm 11**, não config do projeto, e ele não
|
|
15
|
+
recusa o pacote recente — instala o anterior em silêncio, com o `(X.Y.Z is available)` como
|
|
16
|
+
única pista. Quem seguia o README ficava na versão velha achando que tinha atualizado. O
|
|
17
|
+
bloco pnpm passa a mostrar a versão exata com `--config.minimumReleaseAge=0`, e o `@latest`
|
|
18
|
+
aparece como armadilha nomeada. A nota também corrige quem escreve a exceção: o
|
|
19
|
+
`minimumReleaseAgeExclude` do `pnpm-workspace.yaml` é **manual** — o pnpm não escreve essa
|
|
20
|
+
linha, e sem ela o `pnpm install` do CI falha com
|
|
21
|
+
`ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` até a versão completar 24h. Vale nos dois idiomas.
|
|
22
|
+
|
|
23
|
+
## [0.57.1] — 2026-07-25
|
|
24
|
+
|
|
25
|
+
### Fixed
|
|
26
|
+
|
|
27
|
+
- **A troca de README no empacotamento resiste a falha transitória de arquivo.** O CI ficou
|
|
28
|
+
vermelho em **windows-latest + node 22** (só nessa matriz — Windows 18/20 e as três de
|
|
29
|
+
Ubuntu passaram): o `postpack` não restaurou e o repositório ficou com o inglês em
|
|
30
|
+
`README.md`. É uma operação de arquivo falhando enquanto outro processo segura o handle,
|
|
31
|
+
a mesma classe do `rmSync` já conhecida neste projeto. A restauração passa a tentar
|
|
32
|
+
`rename` e, falhando, `copyFile` + `unlink`, com algumas tentativas curtas; esgotadas,
|
|
33
|
+
**falha ruidosamente** com `git checkout README.md` em vez de deixar a árvore trocada em
|
|
34
|
+
silêncio — o estado ruim aqui é o repositório de quem publica, e ele só descobriria
|
|
35
|
+
estranhando um `git status`. O teste de empacotamento passa a restaurar a árvore no
|
|
36
|
+
`finally`: continua detectando a falha pela asserção, mas deixa de ser ele próprio a causa
|
|
37
|
+
de um repositório sujo.
|
|
38
|
+
|
|
39
|
+
## [0.57.0] — 2026-07-25
|
|
40
|
+
|
|
41
|
+
### Fixed
|
|
42
|
+
|
|
43
|
+
- **`wendkeep sync` deixa de mascarar o `defs stale`.** O comando chamava `sync-defs` **sem**
|
|
44
|
+
`--reseed`: copiava o conteúdo da versão anterior de `.brain/skills` para os destinos **e**
|
|
45
|
+
carimbava a versão nova no `.wendkeep-meta.json`. Como o `checkSyncDefs` compara
|
|
46
|
+
destino × `.brain` e `meta.wendkeepVersion` × versão instalada, os dois passavam a bater e
|
|
47
|
+
o `doctor` parava de acusar `defs stale` **sem que uma única skill fosse atualizada** —
|
|
48
|
+
pior que não fazer nada, porque o aviso que apontava o problema real desaparecia. O `sync`
|
|
49
|
+
agora ressemeia: as `wk-*` são artefato do pacote, e trazer os seeds da versão instalada é
|
|
50
|
+
o trabalho dele. Se você editou uma `wk-*` à mão, a edição é sobrescrita — customização
|
|
51
|
+
própria pertence a uma skill sua, que o reseed não toca. Capability `cli-safety`
|
|
52
|
+
(CLI-SYNC-1).
|
|
53
|
+
- **O comando de atualização documentado abria um seletor interativo.** `wendkeep sync
|
|
54
|
+
--project` sem `--yes` cai no picker de companions a cada atualização; e `--project` sem
|
|
55
|
+
valor funcionava por acaso, contradizendo a assinatura `[--project P]` da própria tabela.
|
|
56
|
+
Os dois READMEs passam a mostrar `--project . --yes`.
|
|
57
|
+
|
|
58
|
+
## [0.56.0] — 2026-07-25
|
|
59
|
+
|
|
60
|
+
### Changed
|
|
61
|
+
|
|
62
|
+
- **O README do GitHub passa a ser o português.** `README.md` é o português (o que a página
|
|
63
|
+
do projeto exibe) e `README.en.md` o inglês, cada um linkando o outro. O
|
|
64
|
+
`README.pt-BR.md` deixa de existir — manter os dois nomes seria convidá-los a divergir.
|
|
65
|
+
- **O npm continua em inglês.** A página do pacote sempre renderiza o `README.md` do
|
|
66
|
+
tarball, e não há campo em `package.json` que aponte para outro arquivo; sem tratamento,
|
|
67
|
+
inverter no repositório mudaria também a vitrine para o público global. Hooks
|
|
68
|
+
`prepack`/`postpack` trocam os dois no empacotamento, cobrindo `npm publish` e `npm pack`
|
|
69
|
+
— o teste confere o **conteúdo do tarball**, não os arquivos do repositório, que é
|
|
70
|
+
justamente onde os dois divergem de propósito. Capability `cli-safety` (CLI-PKG-1).
|
|
71
|
+
|
|
72
|
+
### Fixed
|
|
73
|
+
|
|
74
|
+
- **Os dois READMEs estavam atrás do código.** Nenhum documentava `wendkeep sync`,
|
|
75
|
+
`note repair-frontmatter`, `note repair-sections` nem as quatro seções de diagnóstico do
|
|
76
|
+
`doctor`; o português também não tinha `theme sync` nem `note relink`, e `change backlink`
|
|
77
|
+
faltava nos dois. Uma auditoria contra o CLI achou ainda quatro flags que existem no
|
|
78
|
+
código e não estavam documentadas: `verify --project`, `sensors --project`,
|
|
79
|
+
`lesson --change/--vault` e `continue --simple`. A seção de atualização prescrevia a
|
|
80
|
+
receita manual de quatro comandos que o `sync` substitui, e agora cobre npm **e** pnpm —
|
|
81
|
+
inclusive o cooldown que faz o comando de npm falhar num monorepo pnpm.
|
|
82
|
+
|
|
7
83
|
## [0.55.0] — 2026-07-25
|
|
8
84
|
|
|
9
85
|
### Fixed
|
package/README.en.md
ADDED
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
# wendkeep
|
|
2
|
+
|
|
3
|
+
[Português](README.md) · **English**
|
|
4
|
+
|
|
5
|
+
> **Your AI coding agent forgets every session. wendkeep makes it remember — in the Obsidian vault you already use.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/wendkeep)
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
[](docs/index.html)
|
|
13
|
+
|
|
14
|
+
**In the graph:** 🔵 session · 🟣 decision · 🔴 bug · 🟢 learning · 🟡 change — every note, backlinked.
|
|
15
|
+
|
|
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
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm i -D wendkeep && npx wendkeep init # captures from the next session on
|
|
20
|
+
npx wendkeep import # backfill past Claude + Codex sessions
|
|
21
|
+
```
|
|
22
|
+
|
|
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
|
+
|
|
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
|
+
|
|
27
|
+
<!-- Optional: drop a real Obsidian graph screenshot at docs/assets/graph.png and add it here (see docs/21-graph-screenshot.md). -->
|
|
28
|
+
|
|
29
|
+
> Extracted from a system in daily production use: the capture engine, cost tracking and graph wiring are battle‑tested; the cross‑platform installer (`wendkeep init`) and the native change loop are the newer parts. See [`docs/`](https://github.com/rogersialves/wendkeep/tree/main/docs) for the project's strategy and decision log.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## The problem: the context dies when the window closes
|
|
34
|
+
|
|
35
|
+
Decisions, dead ends, the reason you chose X over Y — gone next session. The pieces to fix that exist but are scattered (qmd‑sessions, memsearch, Nexus, hand‑written hooks). wendkeep ships them as one turnkey package that writes into a knowledge graph **inside the Obsidian vault you already use** — no manual setup, no snapshot to keep in sync.
|
|
36
|
+
|
|
37
|
+
| | |
|
|
38
|
+
|---|---|
|
|
39
|
+
| **Capture** — every turn, on disk | `SessionStart` / `Stop` hooks write each session to a dated Markdown note: prompts, iterations, files touched, wikilinks. |
|
|
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 every open change are fed to the agent at the next `SessionStart`. It resumes where it left off. |
|
|
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 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
|
+
| **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
|
+
|
|
46
|
+
## Requirements
|
|
47
|
+
|
|
48
|
+
- Node.js ≥ 18
|
|
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
|
+
- Obsidian (to view the graph) — optional but the point
|
|
51
|
+
|
|
52
|
+
## Install & set up
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
# in your project
|
|
56
|
+
npm install --save-dev wendkeep # or: npm install -g wendkeep
|
|
57
|
+
npx wendkeep init
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
`wendkeep init` is interactive and **idempotent**. It will:
|
|
61
|
+
|
|
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, 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`.
|
|
68
|
+
- **`understand-anything`** — project domain graph, via a `understand-inject` SessionStart hook that injects the graph when generated.
|
|
69
|
+
- **`caveman`** — token-compression mode; runs its own cross-agent installer on non-Claude agents.
|
|
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`).
|
|
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.
|
|
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`. 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`.
|
|
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.
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
npx wendkeep init --vault "~/vaults/work" --project . --yes # non-interactive (no companions unless you ask)
|
|
80
|
+
npx wendkeep init --companions "context-mode,understand-anything" --yes
|
|
81
|
+
npx wendkeep init --no-companions --no-mcp --yes # zero companions, no wendkeep MCP
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
### `init` options
|
|
85
|
+
|
|
86
|
+
| Flag | What it does |
|
|
87
|
+
|---|---|
|
|
88
|
+
| `--vault <path>` | Vault folder. Default `<project>/.<project-name>-vault`; interactive init asks. Point it at an existing vault to install into it. |
|
|
89
|
+
| `--project <path>` | Project root to wire (default: current directory). |
|
|
90
|
+
| `--locale <pt-BR\|en>` | Vault language — folder names, scaffold, skills. Interactive init asks; locked at init. |
|
|
91
|
+
| `--companions <csv>` | Companions to pin: `context-mode,caveman,understand-anything` (default: **none** — opt in explicitly; `dotcontext` is legacy). |
|
|
92
|
+
| `--no-companions` | Pin no companions. |
|
|
93
|
+
| `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
|
|
94
|
+
| `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
|
|
95
|
+
| `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
|
|
96
|
+
| `--force` | Overwrite existing wendkeep config blocks. |
|
|
97
|
+
|
|
98
|
+
Then open the vault in Obsidian, send a test prompt in your agent, and confirm a note appears under `02-Sessões/…` (or `02-Sessions/…` for an `en` vault).
|
|
99
|
+
|
|
100
|
+
### Project isolation
|
|
101
|
+
|
|
102
|
+
Each project owns a `.wendkeep.json` containing a stable `projectId` and its vault path.
|
|
103
|
+
Relative paths (for example `.NutriGymBrain`) are resolved from the project root; absolute
|
|
104
|
+
paths are also supported. Hooks search upward from the agent's `cwd`, so nested packages use
|
|
105
|
+
the nearest binding. The vault carries the same identity in `.brain/PROJECT.json`; a mismatch
|
|
106
|
+
is rejected before any session is written. If no binding exists, hooks fail closed and never
|
|
107
|
+
create the historical `~/wendkeep-vault` fallback.
|
|
108
|
+
|
|
109
|
+
`OBSIDIAN_VAULT_PATH` remains only as legacy/manual CLI compatibility. It is not used to
|
|
110
|
+
route automatic Codex or Claude hooks and a project-local binding overrides an inherited
|
|
111
|
+
machine value.
|
|
112
|
+
|
|
113
|
+
## Updating
|
|
114
|
+
|
|
115
|
+
The hooks live inside the installed package, so upgrading means installing the new version
|
|
116
|
+
and re-wiring the project. `sync` does the three steps (`init` → `sync-defs` → `doctor`) in
|
|
117
|
+
one command:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
npm install --save-dev wendkeep@latest && npx --no-install wendkeep sync --project . --yes
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The install stays outside `sync` on purpose: a running process cannot replace itself and
|
|
124
|
+
keep going — the code in memory would still be the old one.
|
|
125
|
+
|
|
126
|
+
In a **pnpm** monorepo the install command differs (`npm` in a pnpm repo fails with
|
|
127
|
+
`Cannot read properties of null (reading 'matches')`) and the version must be **exact**:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
pnpm add -D -w wendkeep@X.Y.Z --config.minimumReleaseAge=0 && npx --no-install wendkeep sync --project . --yes
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
> **Do not ask pnpm for `wendkeep@latest`.** pnpm 11 ignores packages published in the last
|
|
134
|
+
> 24h by default (`minimumReleaseAge`, a supply-chain guard) — and it does not complain: it
|
|
135
|
+
> installs the previous version, exits 0, and the only hint is a quiet `(X.Y.Z is available)`
|
|
136
|
+
> in the output. You end up on the old version thinking you upgraded. Check with
|
|
137
|
+
> `npx wendkeep --version`.
|
|
138
|
+
>
|
|
139
|
+
> After installing, record the exception in `pnpm-workspace.yaml` — **pnpm does not write
|
|
140
|
+
> that line for you**:
|
|
141
|
+
>
|
|
142
|
+
> ```yaml
|
|
143
|
+
> minimumReleaseAgeExclude:
|
|
144
|
+
> - wendkeep@X.Y.Z
|
|
145
|
+
> ```
|
|
146
|
+
>
|
|
147
|
+
> Without it, CI's `pnpm install` fails with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` until
|
|
148
|
+
> the version turns 24h old.
|
|
149
|
+
|
|
150
|
+
Restart Codex and Claude Code afterwards — the generated skills are read at startup.
|
|
151
|
+
|
|
152
|
+
`sync` **reseeds** the `wk-*` skills from the installed version's seeds. That is not an
|
|
153
|
+
extra: they are package artifacts, and merely copying `.brain/skills` would propagate the
|
|
154
|
+
previous version's content while stamping the new version into the metadata — `doctor` would
|
|
155
|
+
stop reporting `defs stale` without a single skill having been updated. If you hand-edited a
|
|
156
|
+
`wk-*`, that edit is overwritten; your own customisation belongs in a skill of your own,
|
|
157
|
+
which the reseed never touches.
|
|
158
|
+
|
|
159
|
+
## Commands
|
|
160
|
+
|
|
161
|
+
| Command | What it does |
|
|
162
|
+
|---|---|
|
|
163
|
+
| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP + skills). |
|
|
164
|
+
| `wendkeep sync [--project P]` | **One-command update**: runs `init` → `sync-defs` → `doctor` on the current project, stopping at the first failing step. Install the package first (a running process cannot replace itself). `--vault P` · `--yes` to skip the companions picker. |
|
|
165
|
+
| `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
|
|
166
|
+
| `wendkeep change <sub>` | Change lifecycle: `new <slug> [--simple]` / `use <slug>` (switch focus) / `continue <archived> <new> [--simple]` / `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) / `backlink [--apply]` (inject the proposal backlink into orphan design/tasks/spec files). `diff`, `archive` and `abandon` fall back to the active change when you omit the slug; bare `status` lists every open one. |
|
|
167
|
+
| `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; `--project <root>` runs it from outside the root. |
|
|
168
|
+
| `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). |
|
|
169
|
+
| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` with `--severity` / `--type` / `--report` / `--name` / `--description` / `--project` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
|
|
170
|
+
| `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`. |
|
|
171
|
+
| `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`. |
|
|
172
|
+
| `wendkeep stats [--vault P]` | One shareable line: sessions · prompts · spend · span · models (`--json`). |
|
|
173
|
+
| `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`. |
|
|
174
|
+
| `wendkeep session list\|show\|use` | List the multi-session registry, show one conversation, or move only the human focus in `CURRENT_SESSION.md`. |
|
|
175
|
+
| `wendkeep dashboard [--force]` | (Re)generate the vault's folder-filtered Bases + the `00-Dashboard` MOC. |
|
|
176
|
+
| `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`. |
|
|
177
|
+
| `wendkeep note relink [--apply]` | Backfill provenance on orphan derived notes (BUG/APR with no source session), inheriting the modal session of their type/month cohort. Preview by default. |
|
|
178
|
+
| `wendkeep note repair-frontmatter [--apply]` | Merge stacked frontmatter blocks in a session note — damage from the concurrent writes of pre-0.50 versions. Base keys from the original block, values from the newest; preview by default · `--json`. |
|
|
179
|
+
| `wendkeep note repair-sections [--apply]` | Rebuild the `## Decisions/Bugs/Learnings generated in this session` sections from the linked derived notes — the body used to lag behind the closing block. Preview by default · `--json`. |
|
|
180
|
+
| `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`. |
|
|
181
|
+
| `wendkeep renumber-bugs` | Same for `05-Bugs` → `BUG-NNNN-<slug>`. |
|
|
182
|
+
| `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
|
|
183
|
+
| `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`. |
|
|
184
|
+
| `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. |
|
|
185
|
+
| `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
|
|
186
|
+
| `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`. |
|
|
187
|
+
| `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. |
|
|
188
|
+
| `wendkeep --version` / `--help` | Version / usage. |
|
|
189
|
+
|
|
190
|
+
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.
|
|
191
|
+
|
|
192
|
+
## Retroactive memory (`import`) — install today, remember yesterday
|
|
193
|
+
|
|
194
|
+
Install wendkeep into an existing project and it only remembers sessions **from now on**. `wendkeep import` fixes that: one command backfills your project's past **Claude & Codex** sessions into the vault — deduped, dated, with cost — so the graph starts full, not empty. It rebuilds each transcript as a full session note in its **real** date folder — frontmatter (tagged with the transcript's real provider), one iteration block per turn, cost + subagent telemetry, derived decision/bug/learning notes, finalized closing. An offline replay of the live capture flow, so an imported note is indistinguishable from a captured one.
|
|
195
|
+
|
|
196
|
+
```bash
|
|
197
|
+
wendkeep import --vault .myproject-vault --dry-run # preview what would be imported (both agents)
|
|
198
|
+
wendkeep import --vault .myproject-vault # write the notes
|
|
199
|
+
wendkeep import --vault .myproject-vault --source codex # just Codex
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
- **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`.
|
|
203
|
+
- 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).
|
|
204
|
+
- **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.
|
|
205
|
+
- **`--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`.
|
|
206
|
+
- Once imported, `wendkeep cost` aggregates your entire history — retroactively, across both agents.
|
|
207
|
+
|
|
208
|
+
## Derived notes — numbered like ADRs (`note new`, `renumber-*`)
|
|
209
|
+
|
|
210
|
+
Decisions, bugs and learnings are **derived notes**: they live in the month folder of their tree (`<folder>/<year>/<MM-MON>/`) and carry a sequential id — `ADR-0001`, `BUG-0001`, `APR-0001`. One glance tells you what a note is and where it sits in the project's history. No day-level subfolders: a `DIA N` folder holding one note is noise, and it hides the note from folder-wide search.
|
|
211
|
+
|
|
212
|
+
**Creating one** (never write the file by hand — the command owns the number, the folder and the frontmatter):
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
wendkeep note new --type bug "login 500s when the token expires mid-refresh"
|
|
216
|
+
# → 05-Bugs/2026/07-JUL/BUG-0007-login-500s-when-the-token-expires-mid-refresh.md
|
|
217
|
+
|
|
218
|
+
wendkeep note new --type learning "a regex without /g only ever returns the first match"
|
|
219
|
+
# → 06-Aprendizados/2026/07-JUL/APR-0003-a-regex-without-g-only-ever-returns-the-first-match.md
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
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.
|
|
223
|
+
|
|
224
|
+
**Reconnecting legacy notes.** Derived notes created by older versions carry no `source:` session and sit as islands in the graph. `wendkeep note relink` backfills them: each orphan inherits the modal source session of its type/month cohort (the session its non-orphan siblings already point to). Dry-run by default; `--apply` writes; notes with no sibling to infer from are skipped and reported.
|
|
225
|
+
|
|
226
|
+
**Migrating an existing vault.** Notes created before `0.41.0` have date-prefixed names (`2026-07-16-bug-<slug>.md`) and may sit in legacy `DIA N` subfolders. One command per tree renumbers them chronologically, moves them up into the month folder, and rewrites every wikilink across the vault:
|
|
227
|
+
|
|
228
|
+
```bash
|
|
229
|
+
# Bugs — 05-Bugs → BUG-NNNN
|
|
230
|
+
wendkeep renumber-bugs # preview: prints every from → to, writes nothing
|
|
231
|
+
wendkeep renumber-bugs --apply # migrate
|
|
232
|
+
|
|
233
|
+
# Learnings — 06-Aprendizados → APR-NNNN
|
|
234
|
+
wendkeep renumber-learnings # preview
|
|
235
|
+
wendkeep renumber-learnings --apply # migrate
|
|
236
|
+
|
|
237
|
+
# Decisions — 04-Decisões → ADR-NNNN (since 0.30.0)
|
|
238
|
+
wendkeep renumber-decisions # preview
|
|
239
|
+
wendkeep renumber-decisions --apply # migrate
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
- **Preview is the default.** Nothing is written until `--apply` — read the `from → to` list first; that is where a mangled slug shows up, before it touches your files.
|
|
243
|
+
- **One tree at a time, on purpose.** There is no `renumber-all`: each folder is migrated and reviewed on its own.
|
|
244
|
+
- **Order is chronological**, derived from the note's date (frontmatter → filename prefix → folder), so `BUG-0001` is genuinely the oldest bug — not the first one the scanner happened to read.
|
|
245
|
+
- **Wikilinks are rewritten vault-wide** (full-path and basename forms, aliases preserved), the body's `type`/`bug:`/`apr:`/H1 are normalized, and emptied `DIA` folders are removed. **Idempotent**: a second `--apply` renames nothing. Close Obsidian while migrating, and commit the vault first if it is under git.
|
|
246
|
+
|
|
247
|
+
## Change lifecycle — the a2 loop (spec‑driven, native)
|
|
248
|
+
|
|
249
|
+
Beyond capturing sessions, wendkeep is a **harness**: a native, zero‑dependency loop that keeps *intent* (specs), *work* (changes) and *proof* (sensors) together in the vault, wikilinked into the Obsidian graph.
|
|
250
|
+
|
|
251
|
+
```
|
|
252
|
+
explore → propose → apply (TDD) → verify → archive
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
- **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.
|
|
256
|
+
- **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.
|
|
257
|
+
- **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:]`.
|
|
258
|
+
- **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/`.
|
|
259
|
+
|
|
260
|
+
> 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.
|
|
261
|
+
|
|
262
|
+
`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.
|
|
263
|
+
|
|
264
|
+
### The loop in five minutes
|
|
265
|
+
|
|
266
|
+
```bash
|
|
267
|
+
npx wendkeep init --yes # vault + hooks + sensors + skills
|
|
268
|
+
npx wendkeep change new dark-mode # proposta/design/tarefas — change is now active
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Edit `tarefas.md` — tag proof and requirement per task:
|
|
272
|
+
|
|
273
|
+
```markdown
|
|
274
|
+
- [ ] 1.1 toggle persists across sessions [req:UI-1] [sensor:tests]
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Declare the capability in `proposta.md` (`specs: [ui]`) and author its delta only in
|
|
278
|
+
`08-Mudanças/<slug>/specs/ui/spec.md`. `07-Specs` is generated/read-only. Then:
|
|
279
|
+
|
|
280
|
+
```bash
|
|
281
|
+
npx wendkeep change status # every open change + its pending tasks
|
|
282
|
+
npx wendkeep change list # same backlog, plus the archived ones
|
|
283
|
+
npx wendkeep change status dark-mode # one screen for one change: specs / tasks / sensors / verdict
|
|
284
|
+
npx wendkeep spec effective --change dark-mode # living contract + this change's delta
|
|
285
|
+
npx wendkeep change done 1.1 # tick a task from the CLI
|
|
286
|
+
npx wendkeep verify # run the declared sensors -> evidencia.json
|
|
287
|
+
npx wendkeep verify --deep # assemble the verification package
|
|
288
|
+
# the wk-verify skill (fresh, read-only pass) writes verdict.json
|
|
289
|
+
npx wendkeep change diff # preview what will land in 07-Specs
|
|
290
|
+
npx wendkeep change archive dark-mode # gate: sensors + verdict + no open tasks
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
The archive promotes the delta into generated `07-Specs/ui.md`, mints an ADR, and the
|
|
294
|
+
Obsidian graph now links *session ↔ change ↔ requirement ↔ decision*. Every generated
|
|
295
|
+
artifact (`design`/`tarefas`) is born linking its change's `proposta` hub, and hand-authored
|
|
296
|
+
`spec.md` deltas are auto-linked on `verify`/`archive` — no change artifact is a graph island.
|
|
297
|
+
To backfill older changes that predate this, run `wendkeep change backlink --apply` (dry-run
|
|
298
|
+
without `--apply`). A change that names no `[req:]` still runs `verify --deep`, but skips the
|
|
299
|
+
`wk-verify` reading pass: the command writes a trivial verdict on its own and the sensor gate
|
|
300
|
+
is the real proof.
|
|
301
|
+
|
|
302
|
+
## How it works
|
|
303
|
+
|
|
304
|
+
```
|
|
305
|
+
agent session ──hooks──▶ wendkeep ──▶ Markdown in vault ──▶ .brain index + Obsidian graph
|
|
306
|
+
(Claude/Codex) (Node) (02-Sessões/…) (CORE+DIGEST, backlinks)
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
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.
|
|
310
|
+
|
|
311
|
+
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.
|
|
312
|
+
|
|
313
|
+
## Notes & roadmap
|
|
314
|
+
|
|
315
|
+
- **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.
|
|
316
|
+
- **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
|
|
317
|
+
- **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
|
|
318
|
+
- 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).
|
|
319
|
+
- **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.
|
|
320
|
+
|
|
321
|
+
---
|
|
322
|
+
|
|
323
|
+
## Stop re‑explaining your codebase every morning
|
|
324
|
+
|
|
325
|
+
```bash
|
|
326
|
+
npm i -D wendkeep && npx wendkeep init
|
|
327
|
+
```
|
|
328
|
+
|
|
329
|
+
**[Install from npm](https://www.npmjs.com/package/wendkeep)** · **[Star on GitHub](https://github.com/rogersialves/wendkeep)** — MIT · open‑core · your data never leaves your disk.
|
|
330
|
+
|
|
331
|
+
## License
|
|
332
|
+
|
|
333
|
+
MIT
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# wendkeep
|
|
2
2
|
|
|
3
|
-
[Português](README.
|
|
3
|
+
[Português](README.md) · **English**
|
|
4
4
|
|
|
5
5
|
> **Your AI coding agent forgets every session. wendkeep makes it remember — in the Obsidian vault you already use.**
|
|
6
6
|
|
|
@@ -112,28 +112,61 @@ machine value.
|
|
|
112
112
|
|
|
113
113
|
## Updating
|
|
114
114
|
|
|
115
|
-
|
|
116
|
-
|
|
115
|
+
The hooks live inside the installed package, so upgrading means installing the new version
|
|
116
|
+
and re-wiring the project. `sync` does the three steps (`init` → `sync-defs` → `doctor`) in
|
|
117
|
+
one command:
|
|
117
118
|
|
|
118
119
|
```bash
|
|
119
|
-
npm install --save-dev wendkeep@latest
|
|
120
|
-
npx --no-install wendkeep init --project . --vault <your-vault> --yes
|
|
121
|
-
npx --no-install wendkeep sync-defs --project . --reseed
|
|
122
|
-
npx --no-install wendkeep doctor --project .
|
|
120
|
+
npm install --save-dev wendkeep@latest && npx --no-install wendkeep sync --project . --yes
|
|
123
121
|
```
|
|
124
122
|
|
|
125
|
-
|
|
123
|
+
The install stays outside `sync` on purpose: a running process cannot replace itself and
|
|
124
|
+
keep going — the code in memory would still be the old one.
|
|
125
|
+
|
|
126
|
+
In a **pnpm** monorepo the install command differs (`npm` in a pnpm repo fails with
|
|
127
|
+
`Cannot read properties of null (reading 'matches')`) and the version must be **exact**:
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
pnpm add -D -w wendkeep@X.Y.Z --config.minimumReleaseAge=0 && npx --no-install wendkeep sync --project . --yes
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
> **Do not ask pnpm for `wendkeep@latest`.** pnpm 11 ignores packages published in the last
|
|
134
|
+
> 24h by default (`minimumReleaseAge`, a supply-chain guard) — and it does not complain: it
|
|
135
|
+
> installs the previous version, exits 0, and the only hint is a quiet `(X.Y.Z is available)`
|
|
136
|
+
> in the output. You end up on the old version thinking you upgraded. Check with
|
|
137
|
+
> `npx wendkeep --version`.
|
|
138
|
+
>
|
|
139
|
+
> After installing, record the exception in `pnpm-workspace.yaml` — **pnpm does not write
|
|
140
|
+
> that line for you**:
|
|
141
|
+
>
|
|
142
|
+
> ```yaml
|
|
143
|
+
> minimumReleaseAgeExclude:
|
|
144
|
+
> - wendkeep@X.Y.Z
|
|
145
|
+
> ```
|
|
146
|
+
>
|
|
147
|
+
> Without it, CI's `pnpm install` fails with `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION` until
|
|
148
|
+
> the version turns 24h old.
|
|
149
|
+
|
|
150
|
+
Restart Codex and Claude Code afterwards — the generated skills are read at startup.
|
|
151
|
+
|
|
152
|
+
`sync` **reseeds** the `wk-*` skills from the installed version's seeds. That is not an
|
|
153
|
+
extra: they are package artifacts, and merely copying `.brain/skills` would propagate the
|
|
154
|
+
previous version's content while stamping the new version into the metadata — `doctor` would
|
|
155
|
+
stop reporting `defs stale` without a single skill having been updated. If you hand-edited a
|
|
156
|
+
`wk-*`, that edit is overwritten; your own customisation belongs in a skill of your own,
|
|
157
|
+
which the reseed never touches.
|
|
126
158
|
|
|
127
159
|
## Commands
|
|
128
160
|
|
|
129
161
|
| Command | What it does |
|
|
130
162
|
|---|---|
|
|
131
163
|
| `wendkeep init` | Set up wendkeep in a project (vault taxonomy + settings + MCP + skills). |
|
|
164
|
+
| `wendkeep sync [--project P]` | **One-command update**: runs `init` → `sync-defs` → `doctor` on the current project, stopping at the first failing step. Install the package first (a running process cannot replace itself). `--vault P` · `--yes` to skip the companions picker. |
|
|
132
165
|
| `wendkeep hook <name>` | Run a session hook; invoked by `settings.json` (reads agent JSON on stdin). |
|
|
133
|
-
| `wendkeep change <sub>` | Change lifecycle: `new <slug> [--simple]` / `use <slug>` (switch focus) / `continue <archived> <new
|
|
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. |
|
|
166
|
+
| `wendkeep change <sub>` | Change lifecycle: `new <slug> [--simple]` / `use <slug>` (switch focus) / `continue <archived> <new> [--simple]` / `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) / `backlink [--apply]` (inject the proposal backlink into orphan design/tasks/spec files). `diff`, `archive` and `abandon` fall back to the active change when you omit the slug; bare `status` lists every open one. |
|
|
167
|
+
| `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; `--project <root>` runs it from outside the root. |
|
|
135
168
|
| `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). |
|
|
169
|
+
| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` with `--severity` / `--type` / `--report` / `--name` / `--description` / `--project` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
|
|
137
170
|
| `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
171
|
| `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
172
|
| `wendkeep stats [--vault P]` | One shareable line: sessions · prompts · spend · span · models (`--json`). |
|
|
@@ -141,13 +174,17 @@ Restart Codex and Claude Code after reseeding their generated skills.
|
|
|
141
174
|
| `wendkeep session list\|show\|use` | List the multi-session registry, show one conversation, or move only the human focus in `CURRENT_SESSION.md`. |
|
|
142
175
|
| `wendkeep dashboard [--force]` | (Re)generate the vault's folder-filtered Bases + the `00-Dashboard` MOC. |
|
|
143
176
|
| `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`. |
|
|
177
|
+
| `wendkeep note relink [--apply]` | Backfill provenance on orphan derived notes (BUG/APR with no source session), inheriting the modal session of their type/month cohort. Preview by default. |
|
|
178
|
+
| `wendkeep note repair-frontmatter [--apply]` | Merge stacked frontmatter blocks in a session note — damage from the concurrent writes of pre-0.50 versions. Base keys from the original block, values from the newest; preview by default · `--json`. |
|
|
179
|
+
| `wendkeep note repair-sections [--apply]` | Rebuild the `## Decisions/Bugs/Learnings generated in this session` sections from the linked derived notes — the body used to lag behind the closing block. Preview by default · `--json`. |
|
|
144
180
|
| `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`. |
|
|
145
181
|
| `wendkeep renumber-bugs` | Same for `05-Bugs` → `BUG-NNNN-<slug>`. |
|
|
146
182
|
| `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
|
|
147
|
-
| `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). |
|
|
183
|
+
| `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`. |
|
|
148
184
|
| `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. |
|
|
149
185
|
| `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
|
|
150
|
-
| `wendkeep
|
|
186
|
+
| `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`. |
|
|
187
|
+
| `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. |
|
|
151
188
|
| `wendkeep --version` / `--help` | Version / usage. |
|
|
152
189
|
|
|
153
190
|
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.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "wendkeep",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.57.2",
|
|
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": {
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
"hooks",
|
|
14
14
|
"schema",
|
|
15
15
|
"README.md",
|
|
16
|
+
"README.en.md",
|
|
16
17
|
"CHANGELOG.md"
|
|
17
18
|
],
|
|
18
19
|
"engines": {
|
|
@@ -22,7 +23,9 @@
|
|
|
22
23
|
"check": "node --check bin/wendkeep.mjs && node --check src/init.mjs && node --check src/doctor.mjs && node --check src/project-vault.mjs",
|
|
23
24
|
"test": "node --test",
|
|
24
25
|
"release": "node scripts/release.mjs",
|
|
25
|
-
"release:dry": "node scripts/release.mjs --dry-run"
|
|
26
|
+
"release:dry": "node scripts/release.mjs --dry-run",
|
|
27
|
+
"prepack": "node scripts/readme-pack.mjs pre",
|
|
28
|
+
"postpack": "node scripts/readme-pack.mjs post"
|
|
26
29
|
},
|
|
27
30
|
"keywords": [
|
|
28
31
|
"claude-code",
|
|
@@ -46,6 +49,6 @@
|
|
|
46
49
|
"url": "https://github.com/rogersialves/wendkeep/issues"
|
|
47
50
|
},
|
|
48
51
|
"devDependencies": {
|
|
49
|
-
"wendkeep": "^0.
|
|
52
|
+
"wendkeep": "^0.57.1"
|
|
50
53
|
}
|
|
51
54
|
}
|
package/src/sync.mjs
CHANGED
|
@@ -52,9 +52,16 @@ export async function runSync(argv) {
|
|
|
52
52
|
}
|
|
53
53
|
|
|
54
54
|
// 2. sync-defs — propaga as skills/agents da versão instalada para o projeto.
|
|
55
|
+
//
|
|
56
|
+
// COM --reseed, e isso é o ponto: as `wk-*` são artefato do pacote, e o sync existe para
|
|
57
|
+
// rodar depois de instalar uma versão nova. Sem ressemear, o passo copia o conteúdo antigo
|
|
58
|
+
// de `.brain/skills` para os destinos E carimba a versão nova no .wendkeep-meta.json — o
|
|
59
|
+
// checkSyncDefs compara destino×.brain e meta×versão, os dois passam a bater, e o doctor
|
|
60
|
+
// para de acusar `defs stale` sem nenhuma skill ter sido atualizada. Silenciar o aviso sem
|
|
61
|
+
// resolver o problema é pior que não fazer nada.
|
|
55
62
|
step(2, 'sync-defs');
|
|
56
63
|
const { runSyncDefs } = await import('./sync-defs.mjs');
|
|
57
|
-
const defsCode = runSyncDefs(['--vault', vaultBase, '--project', projectPath]);
|
|
64
|
+
const defsCode = runSyncDefs(['--vault', vaultBase, '--project', projectPath, '--reseed']);
|
|
58
65
|
if (defsCode) {
|
|
59
66
|
// Seguir para o doctor aqui seria enganoso: ele acusaria um `defs stale` que este
|
|
60
67
|
// passo deveria ter resolvido.
|
package/README.pt-BR.md
DELETED
|
@@ -1,287 +0,0 @@
|
|
|
1
|
-
# wendkeep
|
|
2
|
-
|
|
3
|
-
**Português** · [English](README.md)
|
|
4
|
-
|
|
5
|
-
> **Seu agente de código esquece cada sessão. O wendkeep faz ele lembrar — no cofre Obsidian que você já usa.**
|
|
6
|
-
|
|
7
|
-
[](https://www.npmjs.com/package/wendkeep)
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
[](docs/index.pt.html)
|
|
13
|
-
|
|
14
|
-
**No grafo:** 🔵 sessão · 🟣 decisão · 🔴 bug · 🟢 aprendizado · 🟡 mudança — cada nota, com backlink.
|
|
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 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
|
-
|
|
18
|
-
```bash
|
|
19
|
-
npm i -D wendkeep && npx wendkeep init # captura a partir da próxima sessão
|
|
20
|
-
npx wendkeep import # importa sessões passadas do Claude + Codex
|
|
21
|
-
```
|
|
22
|
-
|
|
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
|
-
|
|
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
|
-
|
|
27
|
-
> Extraído de um sistema em uso diário de produção: o motor de captura, o rastreio de custo e a fiação do grafo são testados em batalha; o instalador multiplataforma (`wendkeep init`) e o ciclo de mudança nativo são as partes mais novas. Veja [`docs/`](https://github.com/rogersialves/wendkeep/tree/main/docs) para a estratégia e o log de decisões do projeto.
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## O problema: o contexto morre quando a janela fecha
|
|
32
|
-
|
|
33
|
-
Decisões, becos sem saída, o motivo de você ter escolhido X em vez de Y — some na próxima sessão. As peças pra resolver existem, mas espalhadas (qmd‑sessions, memsearch, Nexus, hooks feitos à mão). O wendkeep entrega tudo num pacote turnkey que escreve num grafo de conhecimento **dentro do cofre Obsidian que você já usa** — sem setup manual, sem snapshot pra manter sincronizado.
|
|
34
|
-
|
|
35
|
-
| | |
|
|
36
|
-
|---|---|
|
|
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
|
-
| **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 todas as changes abertas são injetados no agente no próximo `SessionStart`. Ele retoma de onde parou. |
|
|
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** — 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
|
-
| **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
|
-
|
|
44
|
-
## Requisitos
|
|
45
|
-
|
|
46
|
-
- Node.js ≥ 18
|
|
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
|
-
- Obsidian (pra ver o grafo) — opcional, mas é o ponto
|
|
49
|
-
|
|
50
|
-
## Instalar & configurar
|
|
51
|
-
|
|
52
|
-
```bash
|
|
53
|
-
# no seu projeto
|
|
54
|
-
npm install --save-dev wendkeep # ou: npm install -g wendkeep
|
|
55
|
-
npx wendkeep init
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
O `wendkeep init` é interativo e **idempotente**. Ele:
|
|
59
|
-
|
|
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, 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`.
|
|
66
|
-
- **`understand-anything`** — grafo de domínio do projeto, via um hook `understand-inject` no SessionStart que injeta o grafo quando gerado.
|
|
67
|
-
- **`caveman`** — modo de compressão de tokens; roda seu próprio instalador cross‑agent em agentes não‑Claude.
|
|
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`).
|
|
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.
|
|
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.
|
|
75
|
-
|
|
76
|
-
```bash
|
|
77
|
-
npx wendkeep init --vault "~/vaults/work" --project . --yes # não-interativo
|
|
78
|
-
npx wendkeep init --companions "context-mode,understand-anything" --yes
|
|
79
|
-
npx wendkeep init --no-companions --no-mcp --yes # zero companions, sem MCP do wendkeep
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
### Opções do `init`
|
|
83
|
-
|
|
84
|
-
| Flag | O que faz |
|
|
85
|
-
|---|---|
|
|
86
|
-
| `--vault <path>` | Pasta do cofre. Padrão `<projeto>/.<nome-do-projeto>-vault`; o init interativo pergunta. Aponte pra um cofre existente pra instalar nele. |
|
|
87
|
-
| `--project <path>` | Raiz do projeto a wirar (padrão: diretório atual). |
|
|
88
|
-
| `--locale <pt-BR\|en>` | Idioma do cofre — nomes das pastas, scaffold, skills. O init interativo pergunta; travado no init. |
|
|
89
|
-
| `--companions <csv>` | Companions a fixar: `context-mode,caveman,understand-anything` (padrão: **nenhum** — opte explicitamente; `dotcontext` é legado). |
|
|
90
|
-
| `--no-companions` | Não fixa nenhum companion. |
|
|
91
|
-
| `--no-mcp` | Pula o MCP de cofre **do próprio wendkeep** (`wendkeep-vault`). Os MCPs de companion seguem `--companions`. |
|
|
92
|
-
| `--no-colors` | Pula o sistema de cores do Obsidian (snippet `.obsidian` + grupos do grafo). |
|
|
93
|
-
| `--yes`, `-y` | Não-interativo; aceita os padrões (pula os prompts de idioma / cofre / companion). |
|
|
94
|
-
| `--force` | Sobrescreve os blocos de config do wendkeep existentes. |
|
|
95
|
-
|
|
96
|
-
Depois abra o cofre no Obsidian, mande um prompt de teste no seu agente e confirme que uma nota aparece em `02-Sessões/…` (ou `02-Sessions/…` num cofre `en`).
|
|
97
|
-
|
|
98
|
-
### Isolamento por projeto
|
|
99
|
-
|
|
100
|
-
Cada projeto possui um `.wendkeep.json` com `projectId` estável e caminho do vault. Caminhos
|
|
101
|
-
relativos, como `.NutriGymBrain`, partem da raiz do projeto; caminhos absolutos também são
|
|
102
|
-
aceitos. Os hooks procuram o vínculo mais próximo subindo a partir do `cwd`. O vault guarda a
|
|
103
|
-
mesma identidade em `.brain/PROJECT.json`, e uma divergência bloqueia a escrita. Sem vínculo,
|
|
104
|
-
os hooks falham de modo seguro e nunca criam o antigo fallback `~/wendkeep-vault`.
|
|
105
|
-
|
|
106
|
-
`OBSIDIAN_VAULT_PATH` permanece somente como compatibilidade legada para comandos manuais.
|
|
107
|
-
Ele não roteia hooks automáticos do Codex ou Claude, e o vínculo local prevalece sobre uma
|
|
108
|
-
variável herdada da máquina.
|
|
109
|
-
|
|
110
|
-
## Atualizar
|
|
111
|
-
|
|
112
|
-
Como os hooks vivem dentro do pacote instalado, atualize e rode novamente o `init`
|
|
113
|
-
idempotente. Essa etapa cria ou migra o vínculo provider-neutral:
|
|
114
|
-
|
|
115
|
-
```bash
|
|
116
|
-
npm install --save-dev wendkeep@latest
|
|
117
|
-
npx --no-install wendkeep init --project . --vault <seu-vault> --yes
|
|
118
|
-
npx --no-install wendkeep sync-defs --project . --reseed
|
|
119
|
-
npx --no-install wendkeep doctor --project .
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
Reinicie Codex e Claude Code depois de resemear as skills geradas.
|
|
123
|
-
|
|
124
|
-
## Comandos
|
|
125
|
-
|
|
126
|
-
| Comando | O que faz |
|
|
127
|
-
|---|---|
|
|
128
|
-
| `wendkeep init` | Configura o wendkeep num projeto (taxonomia do cofre + settings + MCP + skills). |
|
|
129
|
-
| `wendkeep hook <name>` | Roda um hook de sessão; invocado pelo `settings.json` (lê o JSON do agente no stdin). |
|
|
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`. |
|
|
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`. |
|
|
137
|
-
| `wendkeep stats [--vault P]` | Uma linha compartilhável: sessões · prompts · gasto · período · modelos (`--json`). |
|
|
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`. |
|
|
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>`. |
|
|
144
|
-
| `wendkeep lesson add "t" "l"` | Registra uma lição local do projeto (injetada no próximo SessionStart). |
|
|
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. |
|
|
146
|
-
| `wendkeep validate-memory [path]` | Valida `.brain/CORE.md` (cap 25, 3 seções, sem segredos/PII). |
|
|
147
|
-
| `wendkeep doctor [--vault P]` | Roda um check de saúde do cofre (integridade de sessões, registry, links). |
|
|
148
|
-
| `wendkeep --version` / `--help` | Versão / uso. |
|
|
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
|
-
|
|
152
|
-
## Memória retroativa (`import`) — instale hoje, lembre de ontem
|
|
153
|
-
|
|
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.
|
|
155
|
-
|
|
156
|
-
```bash
|
|
157
|
-
wendkeep import --vault .meuprojeto-vault --dry-run # prévia do que seria importado (os dois agentes)
|
|
158
|
-
wendkeep import --vault .meuprojeto-vault # escreve as notas
|
|
159
|
-
wendkeep import --vault .meuprojeto-vault --source codex # só Codex
|
|
160
|
-
```
|
|
161
|
-
|
|
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`.
|
|
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).
|
|
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`.
|
|
166
|
-
- Depois de importar, o `wendkeep cost` agrega seu histórico inteiro — retroativamente, nos dois agentes.
|
|
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
|
-
|
|
205
|
-
## Ciclo de mudança — o loop a2 (spec‑driven, nativo)
|
|
206
|
-
|
|
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.
|
|
208
|
-
|
|
209
|
-
```
|
|
210
|
-
explore → propose → apply (TDD) → verify → archive
|
|
211
|
-
```
|
|
212
|
-
|
|
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.
|
|
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/`.
|
|
217
|
-
|
|
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
|
-
```
|
|
250
|
-
|
|
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.
|
|
255
|
-
|
|
256
|
-
## Como funciona
|
|
257
|
-
|
|
258
|
-
```
|
|
259
|
-
sessão do agente ──hooks──▶ wendkeep ──▶ Markdown no cofre ──▶ índice .brain + grafo Obsidian
|
|
260
|
-
(Claude/Codex) (Node) (02-Sessões/…) (CORE+DIGEST, backlinks)
|
|
261
|
-
```
|
|
262
|
-
|
|
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.
|
|
264
|
-
|
|
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.
|
|
266
|
-
|
|
267
|
-
## Notas & roadmap
|
|
268
|
-
|
|
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.
|
|
270
|
-
- **Busca é scoring por keyword/frontmatter**, não embeddings on‑device (isso está no roadmap).
|
|
271
|
-
- **Formatos de transcript são internos ao agente** e podem mudar entre versões; o parsing é isolado mas pode precisar de atualizações.
|
|
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.
|
|
274
|
-
|
|
275
|
-
---
|
|
276
|
-
|
|
277
|
-
## Pare de reexplicar seu código toda manhã
|
|
278
|
-
|
|
279
|
-
```bash
|
|
280
|
-
npm i -D wendkeep && npx wendkeep init
|
|
281
|
-
```
|
|
282
|
-
|
|
283
|
-
**[Instalar do npm](https://www.npmjs.com/package/wendkeep)** · **[Deixar uma star no GitHub](https://github.com/rogersialves/wendkeep)** — MIT · open‑core · seus dados nunca saem do seu disco.
|
|
284
|
-
|
|
285
|
-
## Licença
|
|
286
|
-
|
|
287
|
-
MIT
|