wendkeep 0.41.0 → 0.44.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.44.0] — 2026-07-17
+
+### Changed
+
+- `wendkeep change new` não cria mais o placeholder `specs/exemplo/spec.md` (nem a pasta
+  `specs/`). Era ruído — sempre deletado à mão, e `discoverSpecDeltas` já o filtrava. Quando
+  a change resolve `spec_impact: required`, o autor escreve `specs/<capability>/spec.md`
+  direto; o formato do delta vive na skill wk-workflow. O filtro de `exemplo` fica (compat
+  com changes antigas em voo).
+- README gerado do `07-Specs` reescrito para explicar o ponto mais confundido: specs são
+  **por capability, não por mudança** (N changes promovem no mesmo arquivo; o histórico
+  por-change vive em `_arquivo`). `promoteSpecs` passa a garantir/atualizar esse README a
+  cada archive (`ensureSpecsReadme`), então vaults existentes recebem o texto novo no
+  próximo archive — não só os criados via `init`.
+
+## [0.43.0] — 2026-07-17
+
+### Fixed
+
+- Dedup de nota derivada era assimétrico: aprendizado deduplicava recursivamente (vault
+  inteiro), mas **bug e decisão só olhavam a pasta do mês** (`existingKeysForSession`, scan
+  não-recursivo). Uma nota da sessão numa subpasta `DIA` legada não era vista, então um
+  re-import/re-captura da mesma sessão criava uma duplicata de bug/decisão. Agora
+  `existingKeysForSession` varre a pasta derivada recursivamente (como o de aprendizado),
+  mantendo a semântica per-sessão (só notas que referenciam a sessão contam).
+
+## [0.42.0] — 2026-07-17
+
+### Changed
+
+- `wendkeep renumber-decisions --apply` agora **move** as notas de subpastas `DIA N` para a
+  pasta do mês da sua data (achatando o legado), consistente com `renumber-bugs`/
+  `renumber-learnings` do 0.41.0. Antes só renomeava in-place para `ADR-NNNN-<slug>` e
+  deixava as pastas de dia intactas. Os wikilinks já eram reescritos vault-wide; agora
+  acompanham o novo caminho de mês, e as pastas `DIA` que ficam vazias são removidas.
+  Notas sem data resolvível preservam a pasta atual (nunca são perdidas). Idempotente.
+
 ## [0.41.0] — 2026-07-16
 
 ### Added

package/README.md

@@ -138,14 +138,18 @@ Restart Codex and Claude Code after reseeding their generated skills.
 | `wendkeep cost rebuild [opts]` | Recalcula custos históricos do transcript principal e subagents usando `SESSION_REGISTRY`. Dry-run por padrão; `--apply` atualiza notas e grava `.brain/COST_REBUILD.json`. Aceita `--session`, `--limit` e `--json`. |
 | `wendkeep session list\|show\|use` | Lista o registry multi-sessão, mostra uma conversa ou muda somente o foco humano de `CURRENT_SESSION.md`. |
 | `wendkeep change bind <slug> --session <id>` | Vincula ou transfere uma change para uma conversa canônica sem esconder as demais pendências. |
-
-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.
+| `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`. |
+| `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`. |
+| `wendkeep renumber-bugs` | Same for `05-Bugs` → `BUG-NNNN-<slug>`. |
+| `wendkeep renumber-learnings` | Same for `06-Aprendizados`/`06-Learnings` → `APR-NNNN-<slug>`. |
 | `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). |
 | `wendkeep sync-defs` | Copy `.brain/agents\|skills` into `.codex/agents`, `.claude/skills`, `.agents/skills`; `--check` detects drift. |
 | `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |
 | `wendkeep doctor [--vault P]` | Run a vault health check (integrity of sessions, registry, links). |
 | `wendkeep --version` / `--help` | Version / usage. |
 
+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.
+
 ## Retroactive memory (`import`) — install today, remember yesterday
 
 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.
@@ -162,6 +166,43 @@ wendkeep import --vault .myproject-vault --source codex   # just Codex
 - **`--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.
 
+## Derived notes — numbered like ADRs (`note new`, `renumber-*`)
+
+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.
+
+**Creating one** (never write the file by hand — the command owns the number, the folder and the frontmatter):
+
+```bash
+wendkeep note new --type bug "login 500s when the token expires mid-refresh"
+# → 05-Bugs/2026/07-JUL/BUG-0007-login-500s-when-the-token-expires.md
+
+wendkeep note new --type learning "a regex without /g only ever returns the first match"
+# → 06-Aprendizados/2026/07-JUL/APR-0003-a-regex-without-g-only-ever-returns.md
+```
+
+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.
+
+**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:
+
+```bash
+# Bugs — 05-Bugs → BUG-NNNN
+wendkeep renumber-bugs                  # preview: prints every from → to, writes nothing
+wendkeep renumber-bugs --apply          # migrate
+
+# Learnings — 06-Aprendizados → APR-NNNN
+wendkeep renumber-learnings             # preview
+wendkeep renumber-learnings --apply     # migrate
+
+# Decisions — 04-Decisões → ADR-NNNN (since 0.30.0)
+wendkeep renumber-decisions             # preview
+wendkeep renumber-decisions --apply     # migrate
+```
+
+- **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.
+- **One tree at a time, on purpose.** There is no `renumber-all`: each folder is migrated and reviewed on its own.
+- **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.
+- **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.
+
 ## Change lifecycle — the a2 loop (spec‑driven, native)
 
 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.

package/hooks/change-core.mjs

@@ -110,14 +110,12 @@ export function newChange(vaultBase, slug, { sessionRel = '', dateStr, simple =
   write('proposta.md', files.proposta);
   write('tarefas.md', files.tarefas);
   if (!existed) write('.spec-impact-v1', '1\n');
-  // Auto-sizing (Wave B): a --simple change skips the design + spec-delta scaffold.
+  // Auto-sizing (Wave B): a --simple change skips the design scaffold.
+  // No `specs/exemplo` placeholder: it was pure noise (always hand-deleted). When a change
+  // resolves `spec_impact: required`, the author writes `specs/<capability>/spec.md` directly
+  // — the delta format lives in the wk-workflow skill (and `renderChangeScaffold().specDelta`).
   if (!simple) {
     write('design.md', files.design);
-    const exampleDelta = join(dir, 'specs', 'exemplo', 'spec.md');
-    if (!existsSync(exampleDelta)) {
-      mkdirSync(join(dir, 'specs', 'exemplo'), { recursive: true });
-      writeFileSync(exampleDelta, files.specDelta, 'utf8');
-    }
   }
   if (!existed) captureSpecBaseline(vaultBase, dir);
   setActiveChange(vaultBase, slug);

package/hooks/linked-notes.mjs

@@ -553,10 +553,6 @@ ${L.learn.futureHint}
 
 const derivedFoldersFor = (vaultBase) => { const f = getLocale(vaultBase).folders; return { bugs: f.bugs, decisions: f.decisions, learnings: f.learnings }; };
 
-function listMd(dir) {
-  try { return readdirSync(dir).filter((f) => f.endsWith('.md')); } catch { return []; }
-}
-
 // Chaves content_key das derivadas já existentes que linkam esta sessão.
 // Vault-wide learning content_keys (recursive over the learnings folder). existingKeysForSession
 // only looks at the current session + month, so the same lesson re-extracted on a later day/
@@ -582,19 +578,31 @@ function collectLearningKeys(vaultBase) {
   return keys;
 }
 
-function existingKeysForSession(vaultBase, sessionRel, dateStr) {
+// dateStr kept for call compatibility; no longer used to narrow the scan — a session's note may
+// sit in a legacy `DIA` subfolder, not just the month folder, so we walk the whole derived tree
+// (like collectLearningKeys). The per-session semantics stay: only notes referencing THIS session
+// count, so bugs/decisions from other sessions never leak in.
+export function existingKeysForSession(vaultBase, sessionRel, dateStr) { // eslint-disable-line no-unused-vars
   const wikilink = wikilinkFromRel(sessionRel);
   const out = { bugs: [], decisions: [], learnings: [] };
   for (const [type, folder] of Object.entries(derivedFoldersFor(vaultBase))) {
-    const dir = join(vaultBase, monthFolderRelFromDateStr(folder, dateStr, vaultBase));
-    for (const fileName of listMd(dir)) {
-      try {
-        const c = readFileSync(join(dir, fileName), 'utf-8');
-        if (!c.includes(sessionRel) && !c.includes(wikilink)) continue;
-        const m = c.match(/^content_key:\s*"?(.*?)"?\s*$/m);
-        if (m && m[1]) out[type].push(m[1]);
-      } catch { /* ignora nota ilegível */ }
-    }
+    const root = join(vaultBase, folder);
+    const walk = (d) => {
+      let entries;
+      try { entries = readdirSync(d, { withFileTypes: true }); } catch { return; }
+      for (const e of entries) {
+        const p = join(d, e.name);
+        if (e.isDirectory()) { walk(p); continue; }
+        if (!e.name.endsWith('.md')) continue;
+        try {
+          const c = readFileSync(p, 'utf-8');
+          if (!c.includes(sessionRel) && !c.includes(wikilink)) continue;
+          const m = c.match(/^content_key:\s*"?(.*?)"?\s*$/m);
+          if (m && m[1]) out[type].push(m[1]);
+        } catch { /* ignora nota ilegível */ }
+      }
+    };
+    walk(root);
   }
   return out;
 }

package/hooks/renumber-decisions.mjs

@@ -5,9 +5,10 @@
 // chronological order (the order decisions were made), renames the files in place, updates every
 // wikilink to them across the whole vault, and normalizes each note's `type`/`adr`/H1. Idempotent:
 // running it again on an already-canonical vault is a no-op (same order, same names).
-import { readdirSync, readFileSync, renameSync, writeFileSync, existsSync } from 'node:fs';
+import { readdirSync, readFileSync, renameSync, rmdirSync, writeFileSync, existsSync } from 'node:fs';
 import { join, dirname, relative } from 'node:path';
 import { getLocale } from './locale.mjs';
+import { ensureDir, monthFolderRelFromDateStr } from './obsidian-common.mjs';
 
 export const padAdr = (n) => String(n).padStart(4, '0');
 
@@ -29,17 +30,25 @@ function walkDecisions(vaultBase, decisionsDir) {
   return out;
 }
 
+// Resolve a decision's date: frontmatter `date:` > filename `YYYY-MM-DD` prefix > dated folder
+// (`.../YYYY/MM-.../DIA N/`). Returns '' when nothing is derivable. Used by both the sort key
+// and the destination-folder computation (so a note is filed under the month of its real date).
+export function decisionDate({ abs, base, content }) {
+  const c = content ?? (existsSync(abs) ? safeRead(abs) : '');
+  const fmDate = c.match(/^date:\s*(\d{4}-\d{2}-\d{2})/m);
+  if (fmDate) return fmDate[1];
+  const fnDate = base.match(/^(\d{4}-\d{2}-\d{2})/);
+  if (fnDate) return fnDate[1];
+  const folderDate = String(abs).replaceAll('\\', '/').match(/\/(\d{4})\/(\d{2})-[^/]+\/DIA\s+(\d{1,2})\//i);
+  if (folderDate) return `${folderDate[1]}-${folderDate[2]}-${String(folderDate[3]).padStart(2, '0')}`;
+  return '';
+}
+
 // Chronological sort key: date, then time, then existing ADR number, then filename — all derived
 // from (in priority) frontmatter, filename prefix, and the dated folder path.
 export function decisionSortKey({ abs, base, content }) {
   const c = content ?? (existsSync(abs) ? safeRead(abs) : '');
-  const fmDate = c.match(/^date:\s*(\d{4}-\d{2}-\d{2})/m);
-  const fnDate = base.match(/^(\d{4}-\d{2}-\d{2})/);
-  const folderDate = abs.replaceAll('\\', '/').match(/\/(\d{4})\/(\d{2})-[^/]+\/DIA\s+(\d{1,2})\//i);
-  let date = '9999-12-31';
-  if (fmDate) date = fmDate[1];
-  else if (fnDate) date = fnDate[1];
-  else if (folderDate) date = `${folderDate[1]}-${folderDate[2]}-${String(folderDate[3]).padStart(2, '0')}`;
+  const date = decisionDate({ abs, base, content: c }) || '9999-12-31';
 
   const fmTime = c.match(/^started_at:\s*\S*T(\d{2}:\d{2}:\d{2})/m);
   const srcTime = c.match(/\[\[[^\]]*\/(\d{2})-(\d{2})-[^\]]*\]\]/); // session wikilink HH-MM prefix
@@ -131,13 +140,16 @@ export function planRenumber(vaultBase) {
     const num = i + 1;
     const slug = slugFromDecisionName(n.base);
     const newBase = `ADR-${padAdr(num)}-${slug}.md`;
-    const folderRel = dirname(n.rel);
-    const newRel = folderRel === '.' ? newBase : `${folderRel}/${newBase}`;
+    // Destination = the month folder of the note's date (like renumber-derived): flatten legacy
+    // `DIA N` subfolders. No derivable date -> keep the current dirname (never lose the note).
+    const date = decisionDate(n);
+    const destDirRel = date ? monthFolderRelFromDateStr(decisionsDir, date, vaultBase) : dirname(n.rel);
+    const newRel = `${destDirRel.replaceAll('\\', '/')}/${newBase}`;
     const oldAdr = n.base.match(/^ADR-(\d+)/i);
     renames.push({
       num, slug,
       oldAbs: n.abs,
-      newAbs: join(dirname(n.abs), newBase),
+      newAbs: join(vaultBase, destDirRel, newBase),
       oldRelNoExt: n.rel.replace(/\.md$/i, ''),
       newRelNoExt: newRel.replace(/\.md$/i, ''),
       oldBaseNoExt: n.base.replace(/\.md$/i, ''),
@@ -173,11 +185,12 @@ export function renumberDecisions(vaultBase, { apply = false } = {}) {
     temps.set(r, tmp);
   });
 
-  // Phase B — normalize each note's body, then land it at its final path. For a renamed note we
-  // write the normalized content back over its temp and renameSync temp -> final (no delete: the
-  // temp file becomes the final file). For an unchanged name we just rewrite in place.
+  // Phase B — normalize each note's body, then land it at its final path (possibly a different
+  // month directory). For a renamed note we write the normalized content over its temp and
+  // renameSync temp -> final; for an unchanged name we rewrite in place.
   for (const r of renames) {
     const tmp = temps.get(r);
+    ensureDir(dirname(r.newAbs));
     if (tmp) {
       writeFileSync(tmp, normalizeDecisionContent(safeRead(tmp), r.num), 'utf8');
       renameSync(tmp, r.newAbs);
@@ -194,5 +207,25 @@ export function renumberDecisions(vaultBase, { apply = false } = {}) {
     const after = rewriteLinks(before, linkRenames);
     if (after !== before) { writeFileSync(abs, after, 'utf8'); report.filesTouched += 1; report.linksUpdated += 1; }
   }
+
+  // Phase D — drop legacy `DIA *` folders left empty by the move to the month folder.
+  pruneEmptyDayFolders(vaultBase, getLocale(vaultBase).folders.decisions);
   return report;
 }
+
+// Remove now-empty `DIA *` folders under the decisions root (best-effort, fail-quiet).
+function pruneEmptyDayFolders(vaultBase, folderRel) {
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory()) continue;
+      const abs = join(dir, e.name);
+      walk(abs);
+      if (/^DIA\s/i.test(e.name)) {
+        try { rmdirSync(abs); } catch { /* não-vazio — fica */ }
+      }
+    }
+  };
+  walk(join(vaultBase, folderRel));
+}

package/hooks/spec-core.mjs

@@ -317,6 +317,47 @@ export function discoverSpecDeltas(changeDir) {
   return caps;
 }
 
+// The 07-Specs README, explaining the most-confused point: specs are per-CAPABILITY, not
+// per-change (many changes promote into the same file; the per-change record lives in
+// _arquivo). Generated + read-only. Written on init and refreshed on every archive so
+// existing vaults self-heal. Bilingual by vault locale.
+export function ensureSpecsReadme(vaultBase) {
+  const loc = getLocale(vaultBase);
+  const en = loc.id === 'en';
+  const dir = join(vaultBase, loc.folders.specs);
+  ensureDir(dir);
+  const body = en
+    ? `# Specs — generated living contract
+
+**One file per _capability_, not per change.** Each file is the current, cumulative contract
+of a capability — the sum of every change's spec delta that was promoted here. Many changes
+touch the same capability, so N changes collapse into far fewer spec files.
+
+Think of it like source code vs commits: this folder is the *current code* of each capability;
+the *commits* that built it are the archived changes in \`${loc.folders.changes}/_arquivo/\`.
+
+- **Generated + read-only.** Never author here. Write deltas only in
+  \`${loc.folders.changes}/<slug>/specs/<capability>/spec.md\` (ADDED/MODIFIED/REMOVED);
+  \`wendkeep change archive\` promotes them into this folder.
+- Per-change history → \`${loc.folders.changes}/_arquivo/\`. Current contract → here.
+`
+    : `# Specs — contrato consolidado gerado
+
+**Um arquivo por _capability_, não por mudança.** Cada arquivo é o contrato atual e acumulado
+de uma capability — a soma de todos os deltas de spec promovidos aqui. Várias mudanças tocam a
+mesma capability, então N mudanças colapsam em bem menos specs.
+
+Pense como código-fonte vs commits: esta pasta é o *código atual* de cada capability; os
+*commits* que a construíram são as mudanças arquivadas em \`${loc.folders.changes}/_arquivo/\`.
+
+- **Gerado + somente leitura.** Nunca edite aqui. Escreva deltas apenas em
+  \`${loc.folders.changes}/<slug>/specs/<capability>/spec.md\` (ADDED/MODIFIED/REMOVED); o
+  \`wendkeep change archive\` promove para esta pasta.
+- Histórico por mudança → \`${loc.folders.changes}/_arquivo/\`. Contrato atual → aqui.
+`;
+  writeFileSync(join(dir, 'README.md'), body, 'utf8');
+}
+
 // Merge each capability's delta (in the change) into the living spec in 07-Specs.
 export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, dateStr } = {}) {
   const loc = getLocale(vaultBase);
@@ -347,6 +388,7 @@ export function promoteSpecs(vaultBase, changeDir, specs, { changeWikilink, date
     promoted.push(cap);
   }
   recordPromotedSpecs(vaultBase, promoted);
+  ensureSpecsReadme(vaultBase); // self-heal the explainer so existing vaults get it on archive
   return { promoted, warnings };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.41.0",
+  "version": "0.44.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/init.mjs

@@ -40,7 +40,7 @@ import { seedDefinitions, syncDefs } from './sync-defs.mjs';
 import { seedWkSkills } from './skills-seed.mjs';
 import { LOCALES, DEFAULT_LOCALE, getLocale, clearLocaleCache, vaultFolders } from '../hooks/locale.mjs';
 import { seedDotcontext, globalHasDotcontext, resolveDotcontextSkipMcp, renderSensorsJson } from './dotcontext-seed.mjs';
-import { adoptSpecsState, SPECS_STATE_FILE } from '../hooks/spec-core.mjs';
+import { adoptSpecsState, ensureSpecsReadme, SPECS_STATE_FILE } from '../hooks/spec-core.mjs';
 import { bindProjectVault, readProjectBinding } from './project-vault.mjs';
 
 function parseArgs(argv) {
@@ -490,12 +490,7 @@ export async function runInit(argv) {
   seedWkSkills(brainDir, loc.id); // Pilar A: native process skills, in the vault locale.
   // Seed the change/spec layer starters (Pilar B) — non-destructive.
   const en = loc.id === 'en';
-  const specsReadme = join(vaultPath, loc.folders.specs, 'README.md');
-  if (!existsSync(specsReadme)) {
-    writeFileSync(specsReadme, en
-      ? `# Specs — generated living contract\n\nRead-only: do not author here. Write deltas only in \`${loc.folders.changes}/<slug>/specs/\`; archive promotes them here.\n`
-      : `# Specs — contrato consolidado gerado\n\nSomente leitura: não edite aqui. Escreva deltas apenas em \`${loc.folders.changes}/<slug>/specs/\`; o archive promove para cá.\n`, 'utf8');
-  }
+  ensureSpecsReadme(vaultPath); // same explainer promoteSpecs refreshes (per-capability, read-only)
   if (!existsSync(join(vaultPath, SPECS_STATE_FILE))) {
     const livingSpecs = readdirSync(join(vaultPath, loc.folders.specs)).filter((name) => name.endsWith('.md') && name !== 'README.md');
     if (!livingSpecs.length) adoptSpecsState(vaultPath);