wendkeep 0.17.0 → 0.20.0

package/CHANGELOG.md

@@ -4,6 +4,68 @@ 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.20.0] — 2026-07-06
+
+Richer skills: bundled templates (multi-file).
+
+### Added
+- The process skills now ship **bundled templates** next to their `SKILL.md`, delivered together
+  by `sync-defs` (the whole skill folder is copied) and auto-delivered by `init`. The model reads
+  them on demand — depth without bloating `SKILL.md`:
+  - **wk-verify** → `spec-reviewer-prompt.md` (the prompt to hand a fresh read-only verifier
+    sub-agent) + `verdict-template.json` (the exact `verdict.json` shape).
+  - **wk-planning** → `plan-template.md` (file map + bite-sized TDD task structure).
+  - **wk-brainstorming** → `design-template.md` (context, approaches, signed-off assumptions,
+    out-of-scope table, acceptance).
+  - pt-BR and en variants; the prose templates follow the vault locale, the JSON is shared.
+
+### Notes
+- Subagents stay the **native harness's** job. wendkeep ships the verifier **prompt** (the agent
+  spawns a read-only sub-agent via its own Task/Agent tool) and captures subagent telemetry — it
+  does not orchestrate spawning. So the reviewer is a template, not a Claude-only
+  `.claude/agents/*.md`, which keeps it agent-agnostic.
+
+### Upgrade
+- `npm update wendkeep`, then `wendkeep init` (or `wendkeep sync-defs`) to get the templates
+  alongside your existing skills. Non-destructive — existing `SKILL.md` files are never overwritten.
+
+## [0.19.0] — 2026-07-06
+
+Fix: memory + active-change injection wired by default.
+
+### Fixed
+- `wendkeep init` now wires the **`brain-inject`** hook into SessionStart (ordered *before*
+  `session-start`), so every session gets `<brain_memory>` injected: CORE + DIGEST + the
+  **active change** (proposal + open tasks) + project lessons. Previously the default hook set was
+  only `session-start` / `session-stop` / `session-ensure` — the memory/change injector existed
+  (`wendkeep hook brain-inject`) but wasn't wired, so the "the change is injected at the next
+  SessionStart" promise (the `wk-workflow` skill and the README) didn't actually hold on a fresh
+  install. matcher `startup|clear|compact` re-injects after a compaction or clear, not only on a
+  cold startup.
+
+### Upgrade
+- Existing installs pick it up by re-running `wendkeep init --force` (idempotent — it only adds the
+  missing hook), or by adding `npx wendkeep hook brain-inject` to the SessionStart hooks manually.
+
+## [0.18.0] — 2026-07-06
+
+Session identity in the note.
+
+### Added
+- Session notes now carry **`session_id`** in their frontmatter — both live capture and import,
+  Claude and Codex. Pairs with the existing `provider:` field so every note self-identifies
+  (which conversation, which agent) without consulting the registry.
+- **`wendkeep import --stamp-ids`** — backfill `session_id` into existing notes from the
+  `SESSION_REGISTRY` (for notes captured or imported before the field existed). Idempotent;
+  only touches notes missing the field.
+- Import dedup now also scans existing notes' `session_id` (`capturedSessionIds` = registry ∪
+  note frontmatter), so a session that already has a note on disk is never re-imported even if
+  the registry was reset or lost.
+
+### Changed
+- `buildSessionContent` accepts a `sessionId`; the SessionStart hook (all three create/recreate
+  paths) and `importSession` thread the id through, so a note records its identity at creation.
+
 ## [0.17.0] — 2026-07-06
 
 Retroactive memory, now agent-agnostic (Codex).

package/README.md

@@ -113,7 +113,8 @@ wendkeep import --vault .myproject-vault --source codex   # just Codex
 ```
 
 - **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`.
-- **Deduped** by `session_id` against the vault's `SESSION_REGISTRY` — only sessions not already present are imported, and it never overwrites an existing note. Re-running is a no-op.
+- 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).
+- **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.
 - **`--from <dir>`** / **`--codex-from <dir>`** point at the transcript folders explicitly (use if the auto-derived path misses). Also: `--since <date>`, `--limit <n>`, `--json`.
 - Once imported, `wendkeep cost` aggregates your entire history — retroactively, across both agents.
 

package/hooks/import-sessions.mjs

@@ -4,7 +4,7 @@
 // dated folder, deduped by session_id against the vault's SESSION_REGISTRY. This is an offline
 // replay of the live capture flow — same skeleton, same iteration blocks, same cost/subagent
 // telemetry, same finalize — so an imported note is indistinguishable from a captured one.
-import { existsSync, readdirSync, writeFileSync, openSync, readSync, closeSync } from 'fs';
+import { existsSync, readdirSync, writeFileSync, readFileSync, openSync, readSync, closeSync } from 'fs';
 import { basename, join } from 'path';
 import {
   parseTranscript,
@@ -19,6 +19,7 @@ import { createLinkedNotes } from './linked-notes.mjs';
 import { updateSessionUsage } from './token-usage.mjs';
 import { upsertSubagentUsage } from './subagent-usage.mjs';
 import { readSessionRegistry, upsertSessionRegistry, formatLocalIso, formatDate } from './obsidian-common.mjs';
+import { getLocale } from './locale.mjs';
 
 // Claude encodes a project's absolute path as its `.claude/projects` dir name by replacing each
 // path separator and the drive colon with '-'. `C:\GitHub\WendKeep` -> `C--GitHub-WendKeep`.
@@ -69,45 +70,71 @@ function cwdMatchesProject(cwd, projectPath) {
   return c === proj || c.startsWith(`${proj}/`);
 }
 
-// Recursively collect *.jsonl paths (manual walk: readdir recursive lands in Node 20; floor is 18).
-function walkJsonl(dir, out = []) {
+// Recursively collect paths matching `re` (manual walk: readdir recursive lands in Node 20; floor is 18).
+function walkFiles(dir, re, out = []) {
   let entries;
   try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
   for (const e of entries) {
     const p = join(dir, e.name);
-    if (e.isDirectory()) walkJsonl(p, out);
-    else if (/\.jsonl$/i.test(e.name)) out.push(p);
+    if (e.isDirectory()) walkFiles(p, re, out);
+    else if (re.test(e.name)) out.push(p);
   }
   return out;
 }
 
-// Read only the leading bytes to pull the session_meta payload (id + cwd); session_meta is the
-// first line of a rollout, so a bounded prefix read avoids parsing multi-MB transcripts twice.
-function readSessionMeta(path) {
+// Read only the leading bytes of a file (avoids slurping multi-MB transcripts / notes).
+function readPrefix(path, bytes = 4096) {
   let fd;
   try {
     fd = openSync(path, 'r');
-    const buf = Buffer.alloc(16384);
-    const n = readSync(fd, buf, 0, buf.length, 0);
-    for (const line of buf.slice(0, n).toString('utf-8').split('\n')) {
-      if (!line.trim()) continue;
-      let e;
-      try { e = JSON.parse(line); } catch { return null; } // partial/oversized first line -> skip
-      return e.type === 'session_meta' ? (e.payload || {}) : null; // meta is always line 1
-    }
+    const buf = Buffer.alloc(bytes);
+    const n = readSync(fd, buf, 0, bytes, 0);
+    return buf.slice(0, n).toString('utf-8');
   } catch {
-    return null;
+    return '';
   } finally {
     if (fd !== undefined) { try { closeSync(fd); } catch { /* already closed */ } }
   }
+}
+
+// Pull the session_meta payload (id + cwd). session_meta is line 1 of a rollout.
+function readSessionMeta(path) {
+  for (const line of readPrefix(path, 16384).split('\n')) {
+    if (!line.trim()) continue;
+    let e;
+    try { e = JSON.parse(line); } catch { return null; } // partial/oversized first line -> skip
+    return e.type === 'session_meta' ? (e.payload || {}) : null;
+  }
   return null;
 }
 
+// The `session_id` recorded in a note's frontmatter (empty when absent).
+function noteSessionId(path) {
+  const m = readPrefix(path, 2048).match(/^session_id:\s*["']?([^"'\r\n]+)["']?\s*$/m);
+  return m ? m[1].trim() : '';
+}
+
+// Every session_id the vault already has a record of: the SESSION_REGISTRY plus every session
+// note's frontmatter id. The registry is authoritative for wendkeep-native vaults, but scanning
+// notes too keeps import safe even if the registry was reset/lost — a session with a note on
+// disk is never re-imported.
+export function capturedSessionIds(vaultBase) {
+  const ids = new Set(Object.keys(readSessionRegistry(vaultBase).sessions || {}));
+  try {
+    const sessionsDir = join(vaultBase, getLocale(vaultBase).folders.sessions);
+    for (const path of walkFiles(sessionsDir, /\.md$/i)) {
+      const id = noteSessionId(path);
+      if (id) ids.add(id);
+    }
+  } catch { /* registry alone is enough */ }
+  return ids;
+}
+
 export function discoverCodexTranscripts(projectPath, fromDir) {
   const dir = fromDir || defaultCodexSessionsDir();
   if (!dir || !existsSync(dir)) return { dir, transcripts: [] };
   const transcripts = [];
-  for (const path of walkJsonl(dir)) {
+  for (const path of walkFiles(dir, /\.jsonl$/i)) {
     const meta = readSessionMeta(path);
     if (!meta || !meta.id) continue;
     if (projectPath && !cwdMatchesProject(meta.cwd, projectPath)) continue;
@@ -147,9 +174,9 @@ export function importSession(vaultBase, txPath, opts = {}) {
   const endDate = toDate(turns.at(-1).timestamp, startDate);
   const summary = deriveSummary(tx);
 
-  // Skeleton in the real dated folder, tagged with the transcript's own provider.
+  // Skeleton in the real dated folder, tagged with the transcript's own provider + session id.
   const { absPath, relPath } = allocateSessionPath(vaultBase, startDate, summary);
-  writeFileSync(absPath, buildSessionContent({ relPath, now: startDate, summary, provider: tx.provider }), 'utf-8');
+  writeFileSync(absPath, buildSessionContent({ relPath, now: startDate, summary, provider: tx.provider, sessionId }), 'utf-8');
 
   // One iteration block per turn (insertIteration dedups by turn marker -> re-import safe).
   for (const turn of turns) {
@@ -186,6 +213,34 @@ export function importSession(vaultBase, txPath, opts = {}) {
   return { sessionId, relPath, turns: turns.length };
 }
 
+// Stamp a missing/empty `session_id` into a note's frontmatter (only within the frontmatter
+// block, right after `provider:`). Leaves a note that already has a non-empty id untouched.
+function injectSessionIdFrontmatter(content, sessionId) {
+  const q = `"${String(sessionId).replace(/"/g, '\\"')}"`;
+  if (/^session_id:\s*$/m.test(content)) return content.replace(/^session_id:\s*$/m, `session_id: ${q}`);
+  if (/^session_id:\s*\S/m.test(content)) return content; // already has a value
+  if (/^provider:.*$/m.test(content)) return content.replace(/^(provider:.*)$/m, `$1\nsession_id: ${q}`);
+  return content.replace(/^---\s*$/m, `---\nsession_id: ${q}`);
+}
+
+// Backfill `session_id` into existing session notes from the SESSION_REGISTRY (session_file -> id).
+// For notes captured/imported before the field existed. Idempotent; only touches notes missing it.
+export function stampSessionIds(vaultBase) {
+  const reg = readSessionRegistry(vaultBase).sessions || {};
+  const report = { total: Object.keys(reg).length, stamped: 0, alreadyOk: 0, missingFile: 0 };
+  for (const [sessionId, entry] of Object.entries(reg)) {
+    if (!entry?.session_file) continue;
+    const abs = join(vaultBase, entry.session_file);
+    if (!existsSync(abs)) { report.missingFile++; continue; }
+    let content;
+    try { content = readFileSync(abs, 'utf-8'); } catch { report.missingFile++; continue; }
+    const next = injectSessionIdFrontmatter(content, sessionId);
+    if (next !== content) { writeFileSync(abs, next, 'utf-8'); report.stamped++; }
+    else { report.alreadyOk++; }
+  }
+  return report;
+}
+
 // Import every not-yet-captured transcript from the requested source(s). Deduped by session_id
 // against the registry. Options: { projectPath, source ('all'|'claude'|'codex'), from, codexFrom,
 // since (ISO/date), limit, dryRun }. importSession is provider-agnostic, so both sources share
@@ -206,7 +261,7 @@ export function runImport(vaultBase, opts = {}) {
     codexDir = d.dir;
     transcripts.push(...d.transcripts);
   }
-  const captured = new Set(Object.keys(readSessionRegistry(vaultBase).sessions || {}));
+  const captured = capturedSessionIds(vaultBase);
   const sinceMs = since ? Date.parse(since) : 0;
   const report = { source: src, claudeDir, codexDir, scanned: transcripts.length, imported: 0, skipped: 0, errors: [], sessions: [] };
 

package/hooks/session-start.mjs

@@ -31,7 +31,7 @@ import {
   yamlQuote,
 } from './obsidian-common.mjs';
 
-export function buildSessionContent({ relPath, now, summary = 'session', provider: providerId }) {
+export function buildSessionContent({ relPath, now, summary = 'session', provider: providerId, sessionId = '' }) {
   const date = formatDate(now);
   const startedAt = formatLocalIso(now);
   const titleTime = formatTime(now).slice(0, 5);
@@ -46,6 +46,7 @@ date: ${date}
 started_at: ${startedAt}
 ended_at:
 provider: ${provider.id}
+session_id: ${sessionId ? yamlQuote(sessionId) : ''}
 status: active
 summary: ${yamlQuote(summary)}
 cssclasses:
@@ -202,7 +203,7 @@ function main() {
       const knownAbs = join(vaultBase, known.session_file);
       if (!existsSync(knownAbs)) {
         ensureDir(join(vaultBase, known.session_file.split('/').slice(0, -1).join('/')));
-        writeFileSync(knownAbs, buildSessionContent({ relPath: known.session_file, now, summary: sessionSummaryFromInput(input) }), 'utf-8');
+        writeFileSync(knownAbs, buildSessionContent({ relPath: known.session_file, now, summary: sessionSummaryFromInput(input), sessionId }), 'utf-8');
       }
       const startedAt = known.started_at || control.started_at || formatLocalIso(now);
       writeControl(vaultBase, {
@@ -244,7 +245,7 @@ function main() {
       const matchAbs = join(vaultBase, match.session_file);
       if (!existsSync(matchAbs)) {
         ensureDir(join(vaultBase, match.session_file.split('/').slice(0, -1).join('/')));
-        writeFileSync(matchAbs, buildSessionContent({ relPath: match.session_file, now, summary: sessionSummaryFromInput(input) }), 'utf-8');
+        writeFileSync(matchAbs, buildSessionContent({ relPath: match.session_file, now, summary: sessionSummaryFromInput(input), sessionId: sessionId || match.sessionId }), 'utf-8');
       }
       const startedAt = match.started_at || control.started_at || formatLocalIso(now);
       writeControl(vaultBase, {
@@ -276,7 +277,7 @@ function main() {
   const summary = sessionSummaryFromInput(input);
   const { absPath, relPath } = allocateSessionPath(vaultBase, now, summary);
   const startedAt = formatLocalIso(now);
-  writeFileSync(absPath, buildSessionContent({ relPath, now, summary }), 'utf-8');
+  writeFileSync(absPath, buildSessionContent({ relPath, now, summary, sessionId }), 'utf-8');
   writeControl(vaultBase, {
     status: 'active',
     session_file: relPath,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.17.0",
+  "version": "0.20.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/import.mjs

@@ -3,7 +3,7 @@
 // by session_id). One command backfills your whole history: cost, subagents, iterations.
 import { existsSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
-import { runImport } from '../hooks/import-sessions.mjs';
+import { runImport, stampSessionIds } from '../hooks/import-sessions.mjs';
 
 function opt(argv, name) {
   const i = argv.indexOf(name);
@@ -18,6 +18,14 @@ export function runImportCli(argv) {
   const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
   if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep import: vault not found: ${vaultBase}\n`); process.exit(2); }
 
+  // Repair mode: backfill session_id into existing notes from the registry, then stop.
+  if (argv.includes('--stamp-ids')) {
+    const r = stampSessionIds(vaultBase);
+    if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(r, null, 2)}\n`); process.exit(0); }
+    process.stdout.write(`session_id carimbado em ${r.stamped} nota(s) · ${r.alreadyOk} já ok · ${r.missingFile} sem arquivo (de ${r.total} no registry)\n`);
+    process.exit(0);
+  }
+
   const projectRaw = opt(argv, '--project') || process.cwd();
   const projectPath = isAbsolute(projectRaw) ? projectRaw : resolve(process.cwd(), projectRaw);
   const source = (opt(argv, '--source') || 'all').toLowerCase();

package/src/skills-seed.mjs

@@ -4,8 +4,11 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 
-function skill(name, description, body) {
-  return { name, description, body: `---\nname: ${name}\ndescription: ${description}\n---\n${body}` };
+// A skill is a SKILL.md plus optional bundled files (templates/prompts) that ship in the same
+// folder and are delivered together by `wendkeep sync-defs` (cpSync of the whole dir). The
+// SKILL.md references them; the model reads them on demand — depth without bloating SKILL.md.
+function skill(name, description, body, files = []) {
+  return { name, description, body: `---\nname: ${name}\ndescription: ${description}\n---\n${body}`, files };
 }
 
 const WORKFLOW = `# Loop a2 — o ciclo de trabalho do wendkeep
@@ -144,6 +147,10 @@ precisar de design" é onde suposições não-checadas mais custam. O design pod
 mas tem que existir e ser aprovado.
 
 Ao aprovar, o próximo passo é **wk-planning** (design → plano). Não pule pra implementação.
+
+## Template
+Use o \`design-template.md\` (nesta pasta da skill) pra estruturar o design (contexto, abordagens,
+decisões assinadas, tabela out-of-scope, aceite).
 `;
 
 const PLANNING = `# Planejamento — design vira plano de tarefas
@@ -174,6 +181,9 @@ de 2–5 min:
   "tratar erros apropriadamente", "similar à Task N".
 - DRY, YAGNI. Corte features que o design não pediu.
 - Nomes/assinaturas consistentes entre tarefas (uma função é \`x()\` em toda parte).
+
+## Template
+Comece do \`plan-template.md\` (nesta pasta da skill) — a estrutura de arquivos + tarefas TDD.
 `;
 
 const VERIFY = `# Verificação independente — o passe fresco
@@ -201,6 +211,10 @@ nunca tivesse visto a implementação. Contexto fresco, read-only.
 - \`ok: false\` se algum requisito não tem cobertura que discrimina. Gap não é "quase lá" — é vermelho.
 - Não conserte aqui. Gap vira tarefa de correção na change; re-verifica depois.
 - O gate do \`archive\` **exige** \`verdict.json\` com \`ok\` cobrindo todo \`[req:]\`. Sem isso, não arquiva.
+
+## Templates (nesta pasta)
+- \`spec-reviewer-prompt.md\` — cole ao spawnar o subagente verificador (read-only, autor≠verificador).
+- \`verdict-template.json\` — o formato exato do \`verdict.json\` a gravar.
 `;
 
 const WORKFLOW_EN = `# The a2 loop — wendkeep's work cycle
@@ -291,6 +305,10 @@ List explicitly what the change does **not** do. Undeclared scope becomes creep.
 ## Hard gate
 No code / scaffold / implementation action until a design is presented and approved. Then go to
 **wk-planning**.
+
+## Template
+Use \`design-template.md\` (in this skill folder) to structure the design (context, approaches,
+signed-off decisions, out-of-scope table, acceptance).
 `;
 
 const PLANNING_EN = `# Planning — design into a task plan
@@ -309,6 +327,9 @@ implementation (show code) → run and see it pass → checkpoint: suite green.
 ## Rules
 - Exact file paths, always. Real code in each step — no "TODO", "handle errors appropriately",
   "similar to Task N". DRY, YAGNI. Consistent names/signatures across tasks.
+
+## Template
+Start from \`plan-template.md\` (in this skill folder) — the file map + TDD task structure.
 `;
 
 const VERIFY_EN = `# Independent verification — the fresh pass
@@ -329,24 +350,190 @@ the author — even if you wrote the code, enter as if you'd never seen it. Fres
 - \`ok: false\` if any requirement lacks discriminating coverage. A gap is red, not "almost".
 - Don't fix here — a gap becomes a fix task; re-verify after.
 - The archive gate **requires** a fresh \`verdict.json\` (matching \`tasksHash\`) covering every \`[req:]\`.
+
+## Templates (in this folder)
+- \`spec-reviewer-prompt.md\` — hand it to the verifier sub-agent you spawn (read-only, author≠verifier).
+- \`verdict-template.json\` — the exact shape of the \`verdict.json\` to write.
+`;
+
+// --- bundled templates (shipped alongside the relevant SKILL.md) -------------
+
+// Shared, language-neutral verdict skeleton for the independent verify pass.
+const VERDICT_TEMPLATE = `{
+  "slug": "<change-slug>",
+  "ok": true,
+  "coverage": [
+    { "req": "GATE-1", "covered": true, "evidence": "tests/foo.test.mjs:42" }
+  ],
+  "tasksHash": "<copie de verificacao.json — selo de frescor / copy from verificacao.json — freshness seal>",
+  "notes": []
+}
+`;
+
+const REVIEWER_PROMPT_PT = `# Prompt — passe de verificação independente (read-only)
+
+Entregue este prompt ao spawnar o subagente verificador (via o harness nativo — Task/Agent no
+Claude). Ele NÃO é o autor: entra fresco, read-only, não edita nada.
+
+---
+Você é o verificador independente de uma mudança do wendkeep. Não escreveu este código —
+entre como se nunca o tivesse visto. Read-only.
+
+Leia o pacote \`08-Mudanças/<slug>/verificacao.json\` (requisitos, tarefas, evidência) e os
+specs vivos em \`07-Specs/<capability>.md\`.
+
+Para cada \`[req:ID]\` da mudança:
+1. Leia o **critério de aceite do requisito** no spec — NÃO leia a implementação primeiro.
+2. Ache o teste que cobre esse comportamento. Ele **discrimina**? (falharia sob uma
+   implementação errada; afirma valor/estado persistido, não "o mock foi chamado").
+3. Evidência \`arquivo:linha\`. Sem teste que discrimina = \`covered: false\` (é vermelho, não "quase").
+4. Cheque o resultado observável contra o critério — não contra o código.
+
+Grave \`08-Mudanças/<slug>/verdict.json\` no formato de \`verdict-template.json\`. \`ok: false\` se
+qualquer \`[req:]\` não tem cobertura que discrimina. Não conserte aqui — gap vira tarefa de
+correção. O \`tasksHash\` vem do pacote (selo de frescor; alterou tarefa depois, o gate rejeita).
+---
+`;
+
+const REVIEWER_PROMPT_EN = `# Prompt — independent verification pass (read-only)
+
+Hand this to the verifier sub-agent you spawn (via the native harness — Task/Agent on Claude).
+It is NOT the author: fresh context, read-only, edits nothing.
+
+---
+You are the independent verifier of a wendkeep change. You did not write this code — enter as if
+you'd never seen it. Read-only.
+
+Read the package \`08-Changes/<slug>/verificacao.json\` (requirements, tasks, evidence) and the
+living specs in \`07-Specs/<capability>.md\`.
+
+For each \`[req:ID]\`:
+1. Read the requirement's **acceptance criterion** in the spec — do NOT read the implementation first.
+2. Find the test covering that behaviour. Does it **discriminate**? (would fail under a wrong
+   implementation; asserts a persisted value/state, not "the mock was called").
+3. \`file:line\` evidence. No discriminating test = \`covered: false\` (red, not "almost").
+4. Check the observable result against the criterion — not the code.
+
+Write \`08-Changes/<slug>/verdict.json\` in the shape of \`verdict-template.json\`. \`ok: false\` if any
+\`[req:]\` lacks discriminating coverage. Don't fix here — a gap becomes a fix task. \`tasksHash\`
+comes from the package (freshness seal; edit a task later and the gate rejects it as stale).
+---
+`;
+
+const PLAN_TEMPLATE_PT = `# Template — plano de tarefas (TDD, bite-sized)
+
+## Arquivos
+- Criar: \`caminho/exato.mjs\`
+- Modificar: \`caminho/existente.mjs:120-140\`
+- Teste: \`tests/exato.test.mjs\`
+
+## Tarefa N — <nome>
+- **Consome:** <o que usa de tarefas anteriores — assinaturas exatas>
+- **Produz:** <o que tarefas seguintes usam — nomes/tipos exatos>
+
+- [ ] N.1 escreva o teste que falha (mostre o código do teste)  \`[req:<ID>]\`
+- [ ] N.2 rode e veja falhar — pelo motivo certo (comando exato + saída esperada)
+- [ ] N.3 implementação mínima (mostre o código)  \`[sensor:<id>]\` se precisa de prova
+- [ ] N.4 rode e veja passar
+- [ ] N.5 checkpoint: suíte verde · commit
+
+## Regras
+Caminhos exatos sempre. Código real em cada passo — nada de "TODO" / "tratar erros
+apropriadamente" / "similar à Tarefa N". DRY, YAGNI. Nomes e assinaturas consistentes entre
+tarefas (uma função é \`x()\` em toda parte). Cada tarefa termina num entregável testável sozinho.
+`;
+
+const PLAN_TEMPLATE_EN = `# Template — task plan (TDD, bite-sized)
+
+## Files
+- Create: \`exact/path.mjs\`
+- Modify: \`exact/existing.mjs:120-140\`
+- Test: \`tests/exact.test.mjs\`
+
+## Task N — <name>
+- **Consumes:** <what it uses from earlier tasks — exact signatures>
+- **Produces:** <what later tasks rely on — exact names/types>
+
+- [ ] N.1 write the failing test (show the test code)  \`[req:<ID>]\`
+- [ ] N.2 run and see it fail — for the right reason (exact command + expected output)
+- [ ] N.3 minimal implementation (show the code)  \`[sensor:<id>]\` if it needs proof
+- [ ] N.4 run and see it pass
+- [ ] N.5 checkpoint: suite green · commit
+
+## Rules
+Exact paths always. Real code in every step — no "TODO" / "handle errors appropriately" /
+"similar to Task N". DRY, YAGNI. Consistent names/signatures across tasks. Each task ends in an
+independently testable deliverable.
+`;
+
+const DESIGN_TEMPLATE_PT = `# Template — documento de design
+
+## Contexto
+<o problema, o estado atual, por que agora>
+
+## Abordagens consideradas
+1. **<A>** — <trade-off>.
+2. **<B>** — <trade-off>.
+Recomendada: **<qual>** — <por quê>.
+
+## Design
+<arquitetura, componentes, fluxo de dados, tratamento de erro, estratégia de teste — em seções
+escaladas ao tamanho do problema>
+
+## Decisões e assumptions assinadas
+- Assumo **X** porque **Y** — corrija se errado.
+
+## Out-of-scope (o contrato do que NÃO muda)
+| Item | Por que fora |
+|---|---|
+| <x> | <razão> |
+
+## Aceite
+<critérios verificáveis: para cada requisito, o teste que falha → passa>
+`;
+
+const DESIGN_TEMPLATE_EN = `# Template — design document
+
+## Context
+<the problem, the current state, why now>
+
+## Approaches considered
+1. **<A>** — <trade-off>.
+2. **<B>** — <trade-off>.
+Recommended: **<which>** — <why>.
+
+## Design
+<architecture, components, data flow, error handling, test strategy — sections scaled to the
+size of the problem>
+
+## Decisions and signed-off assumptions
+- Assuming **X** because **Y** — correct me if wrong.
+
+## Out-of-scope (the contract of what does NOT change)
+| Item | Why out |
+|---|---|
+| <x> | <reason> |
+
+## Acceptance
+<verifiable criteria: for each requirement, the test that fails → passes>
 `;
 
 const WK_SKILLS_PT = [
   skill('wk-workflow', 'Use ao começar qualquer mudança não-trivial — orquestra o loop a2 (explore, propose, apply, verify, archive) nos comandos wendkeep.', WORKFLOW),
   skill('wk-tdd', 'Use ao implementar qualquer comportamento — Red/Green/Refactor com testes que discriminam (derivados do spec, litmus não-raso, adequação).', TDD),
   skill('wk-debugging', 'Use quando algo falha ou quebra — depuração sistemática por hipótese antes de corrigir.', DEBUGGING),
-  skill('wk-brainstorming', 'Use quando a ideia ainda é vaga — vira design aprovado, com closure gate e tabela out-of-scope, antes de código.', BRAINSTORMING),
-  skill('wk-planning', 'Use após um design aprovado — decompõe em plano de tarefas TDD bite-sized.', PLANNING),
-  skill('wk-verify', 'Use no verify deep — passe independente read-only (autor≠verificador) que re-deriva a cobertura do spec e grava verdict.json.', VERIFY),
+  skill('wk-brainstorming', 'Use quando a ideia ainda é vaga — vira design aprovado, com closure gate e tabela out-of-scope, antes de código.', BRAINSTORMING, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_PT }]),
+  skill('wk-planning', 'Use após um design aprovado — decompõe em plano de tarefas TDD bite-sized.', PLANNING, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_PT }]),
+  skill('wk-verify', 'Use no verify deep — passe independente read-only (autor≠verificador) que re-deriva a cobertura do spec e grava verdict.json.', VERIFY, [{ name: 'spec-reviewer-prompt.md', content: REVIEWER_PROMPT_PT }, { name: 'verdict-template.json', content: VERDICT_TEMPLATE }]),
 ];
 
 const WK_SKILLS_EN = [
   skill('wk-workflow', 'Use when starting any non-trivial change — orchestrates the a2 loop (explore, propose, apply, verify, archive) over the wendkeep commands.', WORKFLOW_EN),
   skill('wk-tdd', 'Use when implementing any behaviour — Red/Green/Refactor with tests that discriminate (spec-derived, non-shallow litmus, adequacy).', TDD_EN),
   skill('wk-debugging', 'Use when something fails or breaks — systematic hypothesis-driven debugging before fixing.', DEBUGGING_EN),
-  skill('wk-brainstorming', 'Use when the idea is still vague — turns it into an approved design, with a closure gate and out-of-scope table, before code.', BRAINSTORMING_EN),
-  skill('wk-planning', 'Use after an approved design — decomposes it into a bite-sized TDD task plan.', PLANNING_EN),
-  skill('wk-verify', 'Use in verify deep — an independent read-only pass (author≠verifier) that re-derives spec coverage and writes verdict.json.', VERIFY_EN),
+  skill('wk-brainstorming', 'Use when the idea is still vague — turns it into an approved design, with a closure gate and out-of-scope table, before code.', BRAINSTORMING_EN, [{ name: 'design-template.md', content: DESIGN_TEMPLATE_EN }]),
+  skill('wk-planning', 'Use after an approved design — decomposes it into a bite-sized TDD task plan.', PLANNING_EN, [{ name: 'plan-template.md', content: PLAN_TEMPLATE_EN }]),
+  skill('wk-verify', 'Use in verify deep — an independent read-only pass (author≠verifier) that re-derives spec coverage and writes verdict.json.', VERIFY_EN, [{ name: 'spec-reviewer-prompt.md', content: REVIEWER_PROMPT_EN }, { name: 'verdict-template.json', content: VERDICT_TEMPLATE }]),
 ];
 
 // Skill set for a locale. WK_SKILLS stays the pt-BR set for back-compat.
@@ -355,17 +542,23 @@ export function wkSkills(localeId = 'pt-BR') {
 }
 export const WK_SKILLS = WK_SKILLS_PT;
 
-// Seed each skill into <brainDir>/skills/<name>/SKILL.md if absent (non-destructive).
+// Seed each skill into <brainDir>/skills/<name>/ if absent (non-destructive): SKILL.md plus any
+// bundled template/prompt files. Existing files are never overwritten, so re-seeding an older
+// install just fills in the new template files alongside its SKILL.md.
 export function seedWkSkills(brainDir, localeId = 'pt-BR') {
   const created = [];
   for (const s of wkSkills(localeId)) {
     const dir = join(brainDir, 'skills', s.name);
     mkdirSync(dir, { recursive: true });
-    const f = join(dir, 'SKILL.md');
-    if (!existsSync(f)) {
-      writeFileSync(f, s.body, 'utf8');
-      created.push(f);
-    }
+    const writeIfAbsent = (name, content) => {
+      const f = join(dir, name);
+      if (!existsSync(f)) {
+        writeFileSync(f, content, 'utf8');
+        created.push(f);
+      }
+    };
+    writeIfAbsent('SKILL.md', s.body);
+    for (const file of s.files || []) writeIfAbsent(file.name, file.content);
   }
   return created;
 }

package/src/taxonomy.mjs

@@ -78,6 +78,10 @@ export const MCP_SERVER_KEY = 'wendkeep-vault';
 // installed package is the single source of truth (update with `npm update wendkeep`,
 // no re-copying). Returned as a spec the merge logic folds into settings.json.
 export const SESSION_HOOKS = [
+  // Memory + active-change injection. Runs FIRST on SessionStart (order -10, folds before
+  // session-start) so the agent gets CORE + DIGEST + the active change + lessons as context.
+  // matcher 'startup|clear|compact' re-injects after a compaction/clear, not only cold startup.
+  { event: 'SessionStart', matcher: 'startup|clear|compact', name: 'brain-inject', timeout: 15, order: -10, statusMessage: 'wendkeep: injecting memory + active change' },
   { event: 'SessionStart', matcher: 'startup', name: 'session-start', timeout: 30, statusMessage: 'wendkeep: opening Obsidian session' },
   { event: 'Stop', matcher: null, name: 'session-stop', timeout: 60, statusMessage: 'wendkeep: writing session checkpoint' },
   { event: 'UserPromptSubmit', matcher: null, name: 'session-ensure', timeout: 30, statusMessage: 'wendkeep: ensuring active session' },