wendkeep 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.14.0] — 2026-07-06
+
+### Changed
+- **dotcontext is no longer a default companion.** wendkeep's native a2 loop (`change` /
+  `verify` / gate) recreates dotcontext's execution/gate role, so pinning it duplicates the
+  harness. The interactive / `--yes` default is now **`context-mode` only**; dotcontext stays
+  selectable via `--companions dotcontext` for anyone already invested.
+- **README:** rewrote "Install & set up" with a clear **`init` options table** and a
+  per-companion breakdown; clarified that `--no-mcp` skips **only wendkeep's own** vault MCP
+  (companion MCPs still follow `--companions`).
+
+## [0.13.0] — 2026-07-06
+
+Cost intelligence: waste + average.
+
+### Added
+- **Wasted-spend tracking:** a killed/failed workflow run's subagent cost is now recorded per
+  session (`subagents_wasted_usd` + a line in the note's `## Subagents & Workflows`) and rolled
+  up by `wendkeep cost` (`desperdiçado (runs killed/failed): $X`). Money burned on aborted runs
+  was invisible before.
+- **`wendkeep cost` per-session average** (`$/sessão`) alongside the vault total.
+
 ## [0.12.0] — 2026-07-06
 
 Deeper subagent/workflow telemetry.
@@ -261,6 +283,8 @@ Initial release — the capture engine, extracted from a system in daily product
 - `wendkeep init` (cross-platform installer) + optional `@bitbonsai/mcpvault` MCP server.
 
 <!-- Only v0.4.0+ is tagged in git (history starts here); older versions link to npm. -->
+[0.14.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.14.0
+[0.13.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.13.0
 [0.12.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.12.0
 [0.11.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.11.0
 [0.10.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.10.0

package/README.md

@@ -39,20 +39,40 @@ npx wendkeep init
 
 1. Create the vault folder taxonomy and a templated `README.md` (default vault: `<project>/.<project-name>-vault`, e.g. `.MyApp-vault`; override with `--vault`).
 2. **Merge** the three session hooks and `OBSIDIAN_VAULT_PATH` into `.claude/settings.json` — without clobbering your existing settings (a `.bak` is saved; an unparseable file is left untouched and a `.new` is written for you to merge).
-3. Add the `wendkeep-vault` MCP server to `.mcp.json` (skip with `--no-mcp`).
-4. Offer to pin **companion** plugins/MCP (multi-choice; `context-mode` + `dotcontext` pre-checked). Each is wired through the most agent-agnostic path it supports — `context-mode` and `dotcontext` as `.mcp.json` MCP servers (any agent), `understand-anything` via a `understand-inject` SessionStart hook that injects its domain graph when generated, and the Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) as a bonus. **`dotcontext`** (execution/PREVC harness) also gets its lifecycle hooks wired (SessionStart-last + Stop + PostToolUse, pinned CLI) and a starter `.context/config/sensors.json` seeded with a `wendkeep validate-memory` sensor plus one per detected `package.json` script (test/typecheck/lint/build) — add the `.context/runtime|cache|logs|plans|agents|skills/` paths to `.gitignore` (wendkeep doesn't touch git). If dotcontext is already configured globally (`~/.claude.json`), the project MCP entry is **skipped automatically** to avoid a duplicate; tune with `--dotcontext-mcp <auto|project|none>` and `--dotcontext-hooks <full|light|none>` (light drops PostToolUse). Control selection with `--companions <csv>` or `--no-companions`. (`caveman` additionally runs its own cross-agent installer on non-Claude agents.)
+3. 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`.)
+4. Offer to pin **companion** plugins/MCP (multi-choice; only `context-mode` pre-checked). Each is wired the most agent-agnostic way it supports:
+   - **`context-mode`** — context optimizer + FTS5 memory, as a `.mcp.json` MCP server (any agent). The recommended default.
+   - **`understand-anything`** — project domain graph, via a `understand-inject` SessionStart hook that injects the graph when generated.
+   - **`caveman`** — token-compression mode; runs its own cross-agent installer on non-Claude agents.
+   - **`dotcontext`** — *legacy, not recommended.* wendkeep's native a2 loop (`change` / `verify` / gate) already does its job, so installing it **duplicates the harness**. Still selectable via `--companions dotcontext` for anyone already invested (tune with `--dotcontext-mcp` / `--dotcontext-hooks`), but off by default.
+
+   Control with `--companions <csv>` or `--no-companions`. The Claude Code plugin layer (`extraKnownMarketplaces` + `enabledPlugins`) is wired as a bonus where the companion has one.
 5. 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`.
 6. Seed the **curated memory layer**: `.brain/CORE.md` (the hand-curated hot layer, with the 3 required sections) and `.brain/COMPACTION_PROTOCOL.md` (the protocol guide). The auto layers (`DIGEST.md`, `index.jsonl`) are generated by the hooks. Validate the curated layer with `wendkeep validate-memory` (cap 25 lines, 3 sections, no secrets/PII).
 7. Seed 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`. `init` runs `wendkeep sync-defs` for you, delivering them to `.codex/agents/` + `.claude/skills/` (re‑run `sync-defs` after editing `.brain`).
 8. Seed the **change/spec lifecycle**: the `07-Specs/` + `08-Mudanças/` folders and a native `wendkeep.sensors.json` (a `validate-memory` sensor plus one per detected `package.json` script). Drives `wendkeep change` / `wendkeep verify` — see **Change lifecycle** below.
 
 ```bash
-npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (companions: context-mode,dotcontext)
-npx wendkeep init --companions "context-mode,caveman" --yes
-npx wendkeep init --no-companions --yes
+npx wendkeep init --vault "~/vaults/work" --project . --yes   # non-interactive (default companion: context-mode)
+npx wendkeep init --companions "context-mode,understand-anything" --yes
+npx wendkeep init --no-companions --no-mcp --yes              # zero companions, no wendkeep MCP
 ```
 
-Then open the vault in Obsidian, send a test prompt in your agent, and confirm a note appears under `02-Sessões/…`.
+### `init` options
+
+| Flag | What it does |
+|---|---|
+| `--vault <path>` | Vault folder. Default `<project>/.<project-name>-vault`; interactive init asks. Point it at an existing vault to install into it. |
+| `--project <path>` | Project root to wire (default: current directory). |
+| `--locale <pt-BR\|en>` | Vault language — folder names, scaffold, skills. Interactive init asks; locked at init. |
+| `--companions <csv>` | Companions to pin: `context-mode,caveman,understand-anything` (default: `context-mode`; `dotcontext` is legacy). |
+| `--no-companions` | Pin no companions. |
+| `--no-mcp` | Skip **wendkeep's own** vault MCP (`wendkeep-vault`). Companion MCPs still follow `--companions`. |
+| `--no-colors` | Skip the Obsidian color system (`.obsidian` snippet + graph groups). |
+| `--yes`, `-y` | Non-interactive; accept defaults (skips the language / vault / companion prompts). |
+| `--force` | Overwrite existing wendkeep config blocks. |
+
+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).
 
 ## Updating
 

package/bin/wendkeep.mjs

@@ -29,8 +29,8 @@ Usage:
     --vault <path>         Obsidian vault folder (default: <project>/.<project-name>-vault).
     --project <path>       Project root to wire (default: current directory).
     --no-mcp               Do not add the mcpvault MCP server to .mcp.json.
-    --companions <csv>     Companion plugins/MCP to pin: context-mode,dotcontext,caveman,understand-anything
-                           (default when interactive/--yes: context-mode,dotcontext).
+    --companions <csv>     Companion plugins/MCP to pin: context-mode,caveman,understand-anything
+                           (default: context-mode). dotcontext is legacy — the native a2 loop replaces it.
     --no-companions        Skip companion plugins/MCP entirely.
     --no-colors            Skip the Obsidian color system (.obsidian snippet + graph groups).
     --dotcontext-mcp <v>   dotcontext MCP placement: auto (default; skip project entry

package/hooks/subagent-usage.mjs

@@ -143,10 +143,15 @@ export function collectSubagentUsage(sessionDir) {
     };
   });
 
+  // Wasted spend: cost of workflow runs that did not complete (killed/failed/…). The
+  // subagents that ran before the kill still cost money — this makes that visible.
+  const WASTE = /^(killed|failed|error|aborted|cancel(l)?ed)$/i;
+  const wasted = round4(workflows.filter((w) => WASTE.test(w.status)).reduce((s, w) => s + w.cost, 0));
+
   return {
     subagents,
     workflows,
-    aggregate: { count, calls, tokens: tokensTotal(usageAgg), cost: round4(cost), usage: usageAgg, tools: [...allTools] },
+    aggregate: { count, calls, tokens: tokensTotal(usageAgg), cost: round4(cost), wasted, usage: usageAgg, tools: [...allTools] },
   };
 }
 
@@ -167,13 +172,14 @@ export function renderSubagentSection(c) {
   const rows = c.subagents
     .map((s) => `| ${s.id} | ${s.agentType || '-'} | ${s.workflow || '-'} | ${s.model} | ${s.tools} | ${fmt(s.tokens)} | ${usd(s.cost)} |`)
     .join('\n');
+  const wasteLine = a.wasted ? `\n- **Desperdiçado (runs killed/failed):** ${usd(a.wasted)}` : '';
   return `## Subagents & Workflows
 
 > Custo de subagents/workflows desta sessão — NÃO incluído no total principal acima.
 
 - **Subagents:** ${a.count} · ${a.calls} chamadas · ${fmt(a.tokens)} tokens · ${usd(a.cost)}
 - **Workflows:** ${wf}
-- **Tools (subagents):** ${tools}
+- **Tools (subagents):** ${tools}${wasteLine}
 
 <details><summary>Por subagent (${a.count})</summary>
 
@@ -220,6 +226,7 @@ export function upsertSubagentUsage(sessionPath, transcriptPath) {
   content = setFrontmatterField(content, 'subagents_tokens_total', a.tokens);
   content = setFrontmatterField(content, 'subagents_custo_usd', a.cost);
   content = setFrontmatterField(content, 'subagents_tools', `"${(a.tools || []).join(', ')}"`);
+  content = setFrontmatterField(content, 'subagents_wasted_usd', a.wasted || 0);
   content = setFrontmatterField(content, 'tokens_total_incl_subagents', frontmatterNumber(content, 'tokens_total') + a.tokens);
   content = upsertSection(content, '## Subagents & Workflows', renderSubagentSection(collected));
   writeFileSync(sessionPath, content, 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "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…).",
   "type": "module",
   "bin": {

package/src/cost.mjs

@@ -21,6 +21,7 @@ export function parseSessionCost(content) {
     model: fmValue(content, 'custo_modelo_label') || fmValue(content, 'modelo') || '?',
     mainCost: Number(fmValue(content, 'custo_modelo_usd')) || 0,
     subCost: Number(fmValue(content, 'subagents_custo_usd')) || 0,
+    wasted: Number(fmValue(content, 'subagents_wasted_usd')) || 0,
     tokens: Number(fmValue(content, 'tokens_total')) || 0,
     subTokens: Number(fmValue(content, 'subagents_tokens_total')) || 0,
   };
@@ -31,19 +32,22 @@ export function aggregateCosts(entries) {
   const byModel = {};
   let main = 0;
   let sub = 0;
+  let wasted = 0;
   let tokens = 0;
   let subTokens = 0;
   for (const e of entries) {
-    main += e.mainCost; sub += e.subCost; tokens += e.tokens; subTokens += e.subTokens;
+    main += e.mainCost; sub += e.subCost; wasted += e.wasted || 0; tokens += e.tokens; subTokens += e.subTokens;
     const d = e.date || '?';
     (byDay[d] = byDay[d] || { cost: 0, count: 0 }).cost += e.mainCost + e.subCost;
     byDay[d].count += 1;
     (byModel[e.model] = byModel[e.model] || { cost: 0, count: 0 }).cost += e.mainCost + e.subCost;
     byModel[e.model].count += 1;
   }
+  const total = main + sub;
   return {
     count: entries.length,
-    main: round4(main), sub: round4(sub), total: round4(main + sub),
+    main: round4(main), sub: round4(sub), total: round4(total), wasted: round4(wasted),
+    avg: round4(entries.length ? total / entries.length : 0),
     tokens, subTokens,
     byDay: Object.entries(byDay).sort().map(([date, v]) => ({ date, cost: round4(v.cost), count: v.count })),
     byModel: Object.entries(byModel).sort((a, b) => b[1].cost - a[1].cost).map(([model, v]) => ({ model, cost: round4(v.cost), count: v.count })),
@@ -93,8 +97,9 @@ export function runCost(argv) {
 
   if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(agg, null, 2)}\n`); process.exit(0); }
 
-  process.stdout.write(`Custo total (vault): ${usd(agg.total)} — ${agg.count} sessão(ões)\n`);
+  process.stdout.write(`Custo total (vault): ${usd(agg.total)} — ${agg.count} sessão(ões) · ${usd(agg.avg)}/sessão\n`);
   process.stdout.write(`  main: ${usd(agg.main)} · subagents: ${usd(agg.sub)}\n`);
+  if (agg.wasted) process.stdout.write(`  desperdiçado (runs killed/failed): ${usd(agg.wasted)}\n`);
   if (agg.byModel.length) {
     process.stdout.write('\nPor modelo:\n');
     for (const m of agg.byModel) process.stdout.write(`  ${m.model.padEnd(20)} ${usd(m.cost)}  (${m.count})\n`);

package/src/taxonomy.mjs

@@ -124,8 +124,11 @@ export const COMPANIONS = [
   },
   {
     id: 'dotcontext',
-    label: 'dotcontext — orquestração de execução (PREVC + sensores + gate E→V)',
-    default: true,
+    // Legacy: wendkeep's native a2 loop (change/verify/gate) recreates dotcontext's role,
+    // so it is no longer recommended — installing it would duplicate the native harness.
+    // Kept selectable for anyone already invested in it; not a default.
+    label: 'dotcontext — legado (o loop a2 nativo do wendkeep substitui; não recomendado)',
+    default: false,
     // MCP-only (no Claude Code plugin). Agent-agnostic server, @latest surface.
     mcp: { key: 'dotcontext', entry: { type: 'stdio', command: 'npx', args: ['-y', '@dotcontext/mcp@latest'], env: {} } },
     // Lifecycle hooks via the pinned CLI; wired by wendkeep (single writer).