wendkeep 0.40.0 → 0.41.0

package/CHANGELOG.md

@@ -4,6 +4,37 @@ 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.41.0] — 2026-07-16
+
+### Added
+
+- Notas derivadas numeradas: bug e aprendizado gerados automaticamente nascem como
+  `BUG-NNNN-<slug>.md` / `APR-NNNN-<slug>.md` na pasta do mês (nunca subpasta `DIA N`),
+  com frontmatter `bug:`/`apr:` e H1 `# BUG-0001 — <título>` — paridade com o ADR de
+  04-Decisões. Numeração via `getNextDerivedNumber` (scan recursivo, max+1; `getNextAdrNumber`
+  virou wrapper).
+- `wendkeep note new --type bug|learning "<título>"`: cria a nota manual já numerada no
+  path certo (respeitando locale), com backlink da sessão ativa, e imprime o path — o
+  agente nunca calcula número nem pasta à mão. `--date YYYY-MM-DD` opcional.
+- `wendkeep renumber-bugs` e `wendkeep renumber-learnings`: migração retroativa — preview
+  por default, `--apply` renomeia em ordem cronológica, MOVE notas de subpastas `DIA N` e
+  da raiz para a pasta do mês, normaliza frontmatter/H1, reescreve wikilinks vault-wide
+  (full-path e basename) e remove pastas `DIA` vazias. Idempotente.
+- Convenção injetada (VAULT_COMPLEMENT_RULES) e seeds wk-debugging (pt/en) ensinam a
+  numeração, a regra sem-DIA e o uso de `wendkeep note new`.
+
+### Fixed
+
+- `findLinkedDerivedNotes` (Stop hook) agora varre as pastas derivadas recursivamente —
+  antes só enxergava notas na raiz de 04-Decisões/05-Bugs/06-Aprendizados, então notas nas
+  subpastas de mês nunca entravam no merge de wikilinks da sessão.
+
+### Migration
+
+- Para migrar vaults existentes: `wendkeep renumber-bugs` (revisar preview) →
+  `wendkeep renumber-bugs --apply`; idem `renumber-learnings`. Depois
+  `wendkeep sync-defs --project . --reseed` para atualizar as skills wk-*.
+
 ## [0.40.0] — 2026-07-16
 
 ### Added

package/bin/wendkeep.mjs

@@ -68,6 +68,12 @@ Usage:
   wendkeep renumber-decisions   Renumber 04-Decisões to ADR-<NNNN>-<slug> in chronological order,
                            renaming files + rewriting every wikilink. Preview by default; --apply to
                            write. --vault P · --json.
+  wendkeep renumber-bugs        Renumber 05-Bugs to BUG-<NNNN>-<slug> chronologically, moving notes
+                           out of legacy "DIA N" subfolders into the month folder and rewriting
+                           wikilinks. Preview by default; --apply · --vault P · --json.
+  wendkeep renumber-learnings   Same for 06-Aprendizados/06-Learnings with APR-<NNNN>-<slug>.
+  wendkeep note new --type bug|learning "<título>"  Create a numbered derived note (BUG-/APR-NNNN)
+                           in the month folder and print its vault path. --date YYYY-MM-DD · --vault P.
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
                            protocol (cap 25, 3 sections, no secrets/PII). Uses
@@ -214,6 +220,21 @@ async function main() {
       runRenumberDecisions(rest);
       break;
     }
+    case 'renumber-bugs': {
+      const { runRenumberBugs } = await import('../src/renumber.mjs');
+      runRenumberBugs(rest);
+      break;
+    }
+    case 'renumber-learnings': {
+      const { runRenumberLearnings } = await import('../src/renumber.mjs');
+      runRenumberLearnings(rest);
+      break;
+    }
+    case 'note': {
+      const { runNote } = await import('../src/note.mjs');
+      runNote(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

package/hooks/linked-notes.mjs

@@ -6,6 +6,7 @@ import {
   derivedContentKey,
   ensureDir,
   getNextAdrNumber,
+  getNextDerivedNumber,
   keysBate,
   providerMeta,
   slugify,
@@ -183,11 +184,13 @@ const NOTE_LABELS = {
 };
 function noteLabels(localeId) { return NOTE_LABELS[localeId] || NOTE_LABELS['pt-BR']; }
 
-export function buildBugNoteContent(bug, issueRef, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(bug.rootCause), localeId = 'pt-BR') {
+export function buildBugNoteContent(bug, issueRef, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(bug.rootCause), localeId = 'pt-BR', bugNum = 0) {
   const L = noteLabels(localeId);
   const title = issueRef
     ? `${issueRef} - ${normalizeInline(bug.rootCause, 80)}`
     : normalizeInline(bug.rootCause, 80);
+  // bugNum = 0 keeps the legacy unnumbered shape (existing call sites/tests unaffected).
+  const heading = bugNum ? `# BUG-${String(bugNum).padStart(4, '0')} — ${title}` : `# Bug - ${title}`;
 
   return `---
 type: bug
@@ -195,7 +198,7 @@ date: ${dateStr}
 status: fixed
 provider: ${provider.id}
 content_key: "${contentKey}"
-${sessionYamlLinks(sessionRel)}
+${bugNum ? `bug: ${bugNum}\n` : ''}${sessionYamlLinks(sessionRel)}
 cssclasses:
   - topic-bug
 tags:
@@ -204,7 +207,7 @@ severity: ${yamlQuote(bug.severity)}
 issue: ${yamlQuote(issueRef || '')}
 ---
 
-# Bug - ${title}
+${heading}
 
 > [!note] ${L.autoTag}
 > ${L.autoLine(provider.label)}
@@ -436,22 +439,24 @@ export function extractLearningDetails(tx, bugDetails) {
   return learnings.length ? learnings.slice(0, 5) : null;
 }
 
-export function buildLearningNoteContent(learning, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(learning.title), localeId = 'pt-BR') {
+export function buildLearningNoteContent(learning, dateStr, sessionRel, provider = providerMeta(), contentKey = derivedContentKey(learning.title), localeId = 'pt-BR', aprNum = 0) {
   const L = noteLabels(localeId);
+  // aprNum = 0 keeps the legacy unnumbered shape (existing call sites/tests unaffected).
+  const heading = aprNum ? `# APR-${String(aprNum).padStart(4, '0')} — ${learning.title}` : `# ${L.learn.title} - ${learning.title}`;
   return `---
 type: learning
 date: ${dateStr}
 status: active
 provider: ${provider.id}
 content_key: "${contentKey}"
-${sessionYamlLinks(sessionRel)}
+${aprNum ? `apr: ${aprNum}\n` : ''}${sessionYamlLinks(sessionRel)}
 cssclasses:
   - topic-learning
 tags:
 ${yamlTags(learning.tags.map((tag) => (tag === 'codex' ? provider.tag : tag)))}
 ---
 
-# ${L.learn.title} - ${learning.title}
+${heading}
 
 > [!note] ${L.autoTag}
 > ${L.autoLine(provider.label)}
@@ -471,6 +476,81 @@ ${L.learn.futureHint}
 `;
 }
 
+// Manual derived notes (`wendkeep note new`): same sections as the auto-generated shape,
+// but with placeholders — the agent/human fills them in. status differs: a manual bug is
+// OPEN (the auto one is extracted from an applied fix, hence fixed).
+export function buildManualBugNote(title, { num, dateStr, sessionRel = '', localeId = 'pt-BR' }) {
+  const L = noteLabels(localeId);
+  const src = sessionRel ? `${sessionYamlLinks(sessionRel)}\n` : '';
+  return `---
+type: bug
+date: ${dateStr}
+status: open
+content_key: "${derivedContentKey(title)}"
+bug: ${num}
+${src}cssclasses:
+  - topic-bug
+tags:
+  - bug
+severity: ""
+issue: ""
+---
+
+# BUG-${String(num).padStart(4, '0')} — ${title}
+
+## ${L.bug.symptom}
+
+${L.verify}
+
+## ${L.bug.rootCause}
+
+${L.verify}
+
+## ${L.bug.fix}
+
+${L.bug.noFix}
+
+## ${L.bug.evidence}
+
+${L.bug.addEvidence}
+
+## ${L.bug.lessons}
+
+${L.complete}
+`;
+}
+
+export function buildManualLearningNote(title, { num, dateStr, sessionRel = '', localeId = 'pt-BR' }) {
+  const L = noteLabels(localeId);
+  const src = sessionRel ? `${sessionYamlLinks(sessionRel)}\n` : '';
+  return `---
+type: learning
+date: ${dateStr}
+status: active
+content_key: "${derivedContentKey(title)}"
+apr: ${num}
+${src}cssclasses:
+  - topic-learning
+tags:
+  - aprendizado
+---
+
+# APR-${String(num).padStart(4, '0')} — ${title}
+
+## ${L.learn.context}
+
+${L.complete}
+
+## ${L.learn.learned}
+
+${L.complete}
+
+## ${L.learn.future}
+
+${L.learn.futureHint}
+`;
+}
+
 const derivedFoldersFor = (vaultBase) => { const f = getLocale(vaultBase).folders; return { bugs: f.bugs, decisions: f.decisions, learnings: f.learnings }; };
 
 function listMd(dir) {
@@ -544,9 +624,14 @@ export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options =
     const bugKey = derivedContentKey(bugDetails.rootCause);
     if (!alreadyHasKey(existingKeys.bugs, bugKey)) {
       const causeSlug = slugify(bugDetails.rootCause, 'bug', 40);
-      const fileName = issueRef ? `${issueRef}-${causeSlug}.md` : `${dateStr}-bug-${causeSlug}.md`;
+      // Numbered AFTER the dedup guard so a deduplicated note never burns a number.
+      const bugNum = getNextDerivedNumber(vaultBase, 'bugs', 'BUG');
+      // Keep the tracker ref in the name, but only once — root causes often repeat it.
+      const refSlug = issueRef ? slugify(issueRef, '', 20) : '';
+      const refPrefix = refSlug && !causeSlug.includes(refSlug) ? `${refSlug}-` : '';
+      const fileName = `BUG-${String(bugNum).padStart(4, '0')}-${refPrefix}${causeSlug}.md`;
       const filePath = join(bugsDir, fileName);
-      if (!existsSync(filePath)) writeFileSync(filePath, buildBugNoteContent(bugDetails, issueRef, dateStr, sessionRel, provider, bugKey, loc.id), 'utf-8');
+      if (!existsSync(filePath)) writeFileSync(filePath, buildBugNoteContent(bugDetails, issueRef, dateStr, sessionRel, provider, bugKey, loc.id, bugNum), 'utf-8');
       linked.bugs.push(toVaultRelative(vaultBase, filePath));
       existingKeys.bugs.push(bugKey);
     }
@@ -585,9 +670,11 @@ export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options =
       if (alreadyHasKey(existingKeys.learnings, learningKey)) continue;
       if (vaultLearningKeys.has(learningKey)) continue; // already learned elsewhere in the vault
       const learningSlug = slugify(learning.title, 'aprendizado', 40);
-      const fileName = `${dateStr}-${learningSlug}.md`;
+      // Minted inside the loop: each learning consumes its own sequential number.
+      const aprNum = getNextDerivedNumber(vaultBase, 'learnings', 'APR');
+      const fileName = `APR-${String(aprNum).padStart(4, '0')}-${learningSlug}.md`;
       const filePath = join(learningsDir, fileName);
-      if (!existsSync(filePath)) writeFileSync(filePath, buildLearningNoteContent(learning, dateStr, sessionRel, provider, learningKey, loc.id), 'utf-8');
+      if (!existsSync(filePath)) writeFileSync(filePath, buildLearningNoteContent(learning, dateStr, sessionRel, provider, learningKey, loc.id, aprNum), 'utf-8');
       linked.learnings.push(toVaultRelative(vaultBase, filePath));
       existingKeys.learnings.push(learningKey);
     }

package/hooks/obsidian-common.mjs

@@ -19,6 +19,7 @@ export const VAULT_COMPLEMENT_RULES = [
   'Regra prática do Vault: os hooks garantem o histórico automático por turno; o agente só complementa manualmente quando houver valor durável de memória, decisão, bug, aprendizado ou auditoria/validação.',
   'Evite duplicar o que o hook já registra. Use escrita manual para síntese curada baseada em evidências, não para histórico bruto nem raciocínio interno.',
   'Quando complementar, registre a síntese na sessão ativa dentro de `## Iterações` antes de `## Decisões geradas nesta sessão`, ou crie nota derivada em `04-Decisões/`, `05-Bugs/` ou `06-Aprendizados/` com backlink para a sessão.',
+  'Notas derivadas vivem na pasta do MÊS (`<pasta>/<ano>/<MM-MMM>/`), nunca em subpasta `DIA N`, com nome numerado `ADR-`/`BUG-`/`APR-NNNN-<slug>`. Para criar bug ou aprendizado manual, use `wendkeep note new --type bug|learning "título"` — o comando cria a nota já numerada no lugar certo e imprime o path; nunca escreva o arquivo à mão.',
   'Atualize `SHARED_MEMORY.md` somente quando a síntese mudar estado ativo que outro agente precise saber.',
 ];
 
@@ -661,10 +662,12 @@ export function listMarkdownFiles(dir) {
   }
 }
 
-export function getNextAdrNumber(vaultBase) {
-  const decisionsDir = join(vaultBase, getLocale(vaultBase).folders.decisions);
+// Sequential numbering shared by every derived-note family (ADR-, BUG-, APR-):
+// recursive walk because notes live in dated subfolders (AAAA/MM-MMM and legacy DIA DD).
+export function getNextDerivedNumber(vaultBase, folderKey, prefix) {
+  const baseDir = join(vaultBase, getLocale(vaultBase).folders[folderKey]);
+  const re = new RegExp(`^${prefix}-(\\d+)`, 'i');
   let max = 0;
-  // Varre recursivamente: os ADRs agora vivem em subpastas datadas (AAAA/MM-MMM/DIA DD).
   const walk = (dir) => {
     let entries;
     try {
@@ -676,15 +679,19 @@ export function getNextAdrNumber(vaultBase) {
       if (entry.isDirectory()) {
         walk(join(dir, entry.name));
       } else {
-        const match = entry.name.match(/^ADR-(\d+)/i);
+        const match = entry.name.match(re);
         if (match) max = Math.max(max, Number(match[1]));
       }
     }
   };
-  walk(decisionsDir);
+  walk(baseDir);
   return max + 1;
 }
 
+export function getNextAdrNumber(vaultBase) {
+  return getNextDerivedNumber(vaultBase, 'decisions', 'ADR');
+}
+
 export function statExists(path) {
   try {
     return statSync(path);

package/hooks/renumber-decisions.mjs

@@ -102,7 +102,7 @@ export function rewriteLinks(content, renames) {
   return c;
 }
 
-function allVaultMarkdown(vaultBase) {
+export function allVaultMarkdown(vaultBase) {
   const out = [];
   const skip = new Set(['.git', '.obsidian', 'node_modules', '_arquivo']);
   const walk = (dir) => {

package/hooks/renumber-derived.mjs

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+// Retroactive renumbering for the OTHER derived-note families (0.41.0): 05-Bugs -> BUG-NNNN,
+// 06-Aprendizados/06-Learnings -> APR-NNNN. Mirrors renumber-decisions with one deliberate
+// difference: the destination is always the MONTH folder of the note's resolved date — legacy
+// `DIA N` subfolders and dated root notes are moved up/in, then empty `DIA *` dirs are removed.
+// (Decisions renumber preserves dirname; the semantics differ, so the modules stay separate.)
+// Known edge: an issueRef that itself starts with `BUG-\d+` would be eaten by the slug strip.
+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';
+import { padAdr, rewriteLinks, allVaultMarkdown } from './renumber-decisions.mjs';
+
+export const DERIVED_KINDS = {
+  bugs: { folderKey: 'bugs', prefix: 'BUG', numField: 'bug', type: 'bug', fallbackSlug: 'bug' },
+  learnings: { folderKey: 'learnings', prefix: 'APR', numField: 'apr', type: 'learning', fallbackSlug: 'aprendizado' },
+};
+
+function safeRead(abs) {
+  try { return readFileSync(abs, 'utf8'); } catch { return ''; }
+}
+
+function walkNotes(vaultBase, folderRel) {
+  const out = [];
+  const walk = (dir) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) walk(abs);
+      else if (e.name.endsWith('.md')) {
+        out.push({ abs, rel: relative(vaultBase, abs).replaceAll('\\', '/'), base: e.name });
+      }
+    }
+  };
+  walk(join(vaultBase, folderRel));
+  return out;
+}
+
+// Resolve the note's date (frontmatter > filename prefix > `DIA N` folder > month folder).
+// Returns 'YYYY-MM-DD' or '' when nothing is derivable.
+export function derivedNoteDate({ abs, base, content }) {
+  const c = content ?? 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 posix = abs.replaceAll('\\', '/');
+  const dayFolder = posix.match(/\/(\d{4})\/(\d{2})-[^/]+\/DIA\s+(\d{1,2})\//i);
+  if (dayFolder) return `${dayFolder[1]}-${dayFolder[2]}-${String(dayFolder[3]).padStart(2, '0')}`;
+  const monthFolder = posix.match(/\/(\d{4})\/(\d{2})-[^/]+\//);
+  if (monthFolder) return `${monthFolder[1]}-${monthFolder[2]}-01`;
+  return '';
+}
+
+function derivedSortKey(note, prefix) {
+  const date = derivedNoteDate(note) || '9999-12-31';
+  const numMatch = note.base.match(new RegExp(`^${prefix}-(\\d+)`, 'i'));
+  const num = numMatch ? Number(numMatch[1]) : 999999;
+  return `${date}#${String(num).padStart(6, '0')}#${note.base}`;
+}
+
+// Descriptive slug from any era's filename: PREFIX-NNNN-, date prefix and legacy `bug-` marker out.
+export function slugFromDerivedName(base, kind) {
+  let s = base.replace(/\.md$/i, '');
+  s = s.replace(new RegExp(`^${kind.prefix}-\\d+-`, 'i'), '');
+  s = s.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+  if (kind.folderKey === 'bugs') s = s.replace(/^bug-/i, '');
+  return s || kind.fallbackSlug;
+}
+
+// Normalize body: type, numeric field (bug:/apr:) and the canonical `PREFIX-NNNN — ` H1.
+export function normalizeDerivedContent(content, num, kind) {
+  let c = String(content || '');
+  const label = `${kind.prefix}-${padAdr(num)}`;
+
+  if (/^type:\s*.*$/m.test(c)) c = c.replace(/^type:\s*.*$/m, `type: ${kind.type}`);
+  else c = c.replace(/^---\n/, `---\ntype: ${kind.type}\n`);
+
+  const fieldRe = new RegExp(`^${kind.numField}:\\s*.*$`, 'm');
+  if (fieldRe.test(c)) c = c.replace(fieldRe, `${kind.numField}: ${num}`);
+  else c = c.replace(new RegExp(`^type: ${kind.type}$`, 'm'), `type: ${kind.type}\n${kind.numField}: ${num}`);
+
+  c = c.replace(/^#\s+(.*)$/m, (_, title) => {
+    let bare = title.replace(new RegExp(`^${kind.prefix}-\\d+\\s*[—–-]\\s*`, 'i'), '');
+    bare = bare.replace(/^(?:Bug|Aprendizado|Learning)\s*[-—–]\s*/i, '').trim();
+    return `# ${label} — ${bare}`;
+  });
+  return c;
+}
+
+// Pure plan: chronological numbering, destination = month folder of the resolved date
+// (fallback: keep the current dirname when no date is derivable).
+export function planRenumberDerived(vaultBase, kindId) {
+  const kind = DERIVED_KINDS[kindId];
+  if (!kind) throw new Error(`renumber-derived: unknown kind "${kindId}"`);
+  const folderRel = getLocale(vaultBase).folders[kind.folderKey];
+  const notes = walkNotes(vaultBase, folderRel)
+    .map((n) => ({ ...n, content: safeRead(n.abs) }))
+    .sort((a, b) => derivedSortKey(a, kind.prefix).localeCompare(derivedSortKey(b, kind.prefix)));
+
+  const renames = [];
+  notes.forEach((n, i) => {
+    const num = i + 1;
+    const slug = slugFromDerivedName(n.base, kind);
+    const newBase = `${kind.prefix}-${padAdr(num)}-${slug}.md`;
+    const date = derivedNoteDate(n);
+    const destDirRel = date ? monthFolderRelFromDateStr(folderRel, date, vaultBase) : dirname(n.rel);
+    const newRel = `${destDirRel.replaceAll('\\', '/')}/${newBase}`;
+    renames.push({
+      num, slug,
+      oldAbs: n.abs,
+      newAbs: join(vaultBase, destDirRel, newBase),
+      oldRelNoExt: n.rel.replace(/\.md$/i, ''),
+      newRelNoExt: newRel.replace(/\.md$/i, ''),
+      oldBaseNoExt: n.base.replace(/\.md$/i, ''),
+      newBaseNoExt: newBase.replace(/\.md$/i, ''),
+      renamed: n.rel !== newRel,
+    });
+  });
+  return renames;
+}
+
+// Remove now-empty `DIA *` folders under the derived 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));
+}
+
+export function renumberDerived(vaultBase, kindId, { apply = false } = {}) {
+  const kind = DERIVED_KINDS[kindId];
+  const renames = planRenumberDerived(vaultBase, kindId);
+  const changed = renames.filter((r) => r.renamed);
+  const report = {
+    total: renames.length,
+    renamed: changed.length,
+    normalized: 0,
+    linksUpdated: 0,
+    filesTouched: 0,
+    plan: renames.map((r) => ({ num: r.num, from: r.oldRelNoExt, to: r.newRelNoExt, renamed: r.renamed })),
+    applied: apply,
+  };
+  if (!apply) return report;
+
+  // Phase A — park renamed sources under temp names (no target clobbers an unmoved source).
+  const temps = new Map();
+  changed.forEach((r, i) => {
+    const tmp = join(dirname(r.oldAbs), `.wk-renum-${i}.tmp`);
+    renameSync(r.oldAbs, tmp);
+    temps.set(r, tmp);
+  });
+
+  // Phase B — normalize body and land at the final path (possibly a different directory).
+  for (const r of renames) {
+    const tmp = temps.get(r);
+    ensureDir(dirname(r.newAbs));
+    if (tmp) {
+      writeFileSync(tmp, normalizeDerivedContent(safeRead(tmp), r.num, kind), 'utf8');
+      renameSync(tmp, r.newAbs);
+    } else {
+      writeFileSync(r.newAbs, normalizeDerivedContent(safeRead(r.oldAbs), r.num, kind), 'utf8');
+    }
+    report.normalized += 1;
+  }
+
+  // Phase C — rewrite wikilinks vault-wide (full-path and basename forms).
+  for (const abs of allVaultMarkdown(vaultBase)) {
+    const before = safeRead(abs);
+    const after = rewriteLinks(before, changed);
+    if (after !== before) { writeFileSync(abs, after, 'utf8'); report.filesTouched += 1; report.linksUpdated += 1; }
+  }
+
+  // Phase D — drop empty legacy `DIA *` folders.
+  pruneEmptyDayFolders(vaultBase, getLocale(vaultBase).folders[kind.folderKey]);
+  return report;
+}

package/hooks/session-stop.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 import { request } from 'http';
 import { pathToFileURL } from 'url';
@@ -803,10 +803,15 @@ export function findLinkedDerivedNotes(vaultBase, sessionRel) {
     learnings: locF.learnings,
   };
 
-  for (const [key, folder] of Object.entries(folders)) {
-    const dir = join(vaultBase, folder);
-    for (const fileName of listMarkdownFiles(dir)) {
-      const absPath = join(dir, fileName);
+  // Recursive: derived notes live in month subfolders (04-Decisões/2026/07-JUL/ADR-...,
+  // 05-Bugs/.../BUG-...) — a root-only scan missed every one of them.
+  const walk = (dir, key) => {
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      const absPath = join(dir, entry.name);
+      if (entry.isDirectory()) { walk(absPath, key); continue; }
+      if (!entry.name.endsWith('.md')) continue;
       try {
         const content = readFileSync(absPath, 'utf-8');
         if (noteReferencesSession(content, sessionRel)) {
@@ -816,7 +821,8 @@ export function findLinkedDerivedNotes(vaultBase, sessionRel) {
         // Ignore unreadable notes; the hook must not block session shutdown.
       }
     }
-  }
+  };
+  for (const [key, folder] of Object.entries(folders)) walk(join(vaultBase, folder), key);
 
   return linked;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.40.0",
+  "version": "0.41.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/note.mjs

@@ -0,0 +1,80 @@
+// `wendkeep note new` — manual derived notes without guesswork. The agent (or a human)
+// asks for a bug/learning note and gets it already numbered (BUG-/APR-NNNN), in the month
+// folder of the right derived tree, with the correct frontmatter — and the created vault
+// path on stdout. Nobody computes the next number by hand, nobody recreates `DIA N` folders.
+import { existsSync, writeFileSync } from 'node:fs';
+import { isAbsolute, resolve, join, dirname } from 'node:path';
+import {
+  ensureDir,
+  getNextDerivedNumber,
+  monthFolderRelFromDateStr,
+  readControl,
+  slugify,
+  uniquePath,
+  toVaultRelative,
+} from '../hooks/obsidian-common.mjs';
+import { getLocale } from '../hooks/locale.mjs';
+import { buildManualBugNote, buildManualLearningNote } from '../hooks/linked-notes.mjs';
+
+const TYPES = {
+  bug: { folderKey: 'bugs', prefix: 'BUG', build: buildManualBugNote },
+  learning: { folderKey: 'learnings', prefix: 'APR', build: buildManualLearningNote },
+};
+
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
+export function runNote(argv) {
+  const [sub, ...rest] = argv;
+  if (sub !== 'new') {
+    process.stderr.write('wendkeep note: subcomando desconhecido (use `note new --type bug|learning "<título>"`).\n');
+    process.exit(2);
+  }
+
+  const type = (opt(rest, '--type') || '').toLowerCase();
+  const kind = TYPES[type];
+  if (!kind) {
+    process.stderr.write('wendkeep note new: --type deve ser bug ou learning.\n');
+    process.exit(2);
+  }
+
+  // Título = primeiro argumento posicional (não-flag, não-valor de flag).
+  const flagValues = new Set([opt(rest, '--type'), opt(rest, '--vault'), opt(rest, '--date')].filter(Boolean));
+  const title = rest.find((a) => !a.startsWith('--') && !flagValues.has(a));
+  if (!title || !title.trim()) {
+    process.stderr.write('wendkeep note new: falta o título — `note new --type bug "resumo do bug"`.\n');
+    process.exit(2);
+  }
+
+  const dateStr = opt(rest, '--date') || new Date().toISOString().slice(0, 10);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(dateStr)) {
+    process.stderr.write(`wendkeep note new: --date inválida "${dateStr}" (use YYYY-MM-DD).\n`);
+    process.exit(2);
+  }
+
+  const vaultRaw = opt(rest, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep note new: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep note new: vault not found: ${vaultBase}\n`); process.exit(2); }
+
+  const loc = getLocale(vaultBase);
+  const num = getNextDerivedNumber(vaultBase, kind.folderKey, kind.prefix);
+  const dirRel = monthFolderRelFromDateStr(loc.folders[kind.folderKey], dateStr, vaultBase);
+  const fileName = `${kind.prefix}-${String(num).padStart(4, '0')}-${slugify(title, type, 60)}.md`;
+  const filePath = uniquePath(join(vaultBase, dirRel, fileName));
+  ensureDir(dirname(filePath));
+
+  let sessionRel = '';
+  try {
+    const control = readControl(vaultBase);
+    if (control?.status === 'active' && control.session_file) sessionRel = control.session_file;
+  } catch { /* sem sessão ativa — nota nasce sem backlink */ }
+
+  writeFileSync(filePath, kind.build(title.trim(), { num, dateStr, sessionRel, localeId: loc.id }), 'utf8');
+  process.stdout.write(`${toVaultRelative(vaultBase, filePath)}\n`);
+  process.exit(0);
+}

package/src/renumber.mjs

@@ -1,9 +1,11 @@
-// `wendkeep renumber-decisions` — retroactive ADR fix. Renumbers every note in 04-Decisões to
-// `ADR-<NNNN>-<slug>` in chronological order, renames the files, and rewrites every wikilink to
-// them across the vault. Preview by default; pass --apply to write. Idempotent.
+// `wendkeep renumber-decisions|-bugs|-learnings` — retroactive renumbering. Renumbers every note
+// in the derived folder (`ADR-`/`BUG-`/`APR-<NNNN>-<slug>`) in chronological order, renames the
+// files (bugs/learnings also move out of legacy `DIA N` folders into the month folder), and
+// rewrites every wikilink to them across the vault. Preview by default; --apply writes. Idempotent.
 import { existsSync } from 'node:fs';
 import { isAbsolute, resolve } from 'node:path';
 import { renumberDecisions } from '../hooks/renumber-decisions.mjs';
+import { renumberDerived, DERIVED_KINDS } from '../hooks/renumber-derived.mjs';
 
 function opt(argv, name) {
   const i = argv.indexOf(name);
@@ -12,21 +14,33 @@ function opt(argv, name) {
   return eq ? eq.slice(name.length + 1) : undefined;
 }
 
-export function runRenumberDecisions(argv) {
+function runRenumberCli(argv, cmdName, unitLabel, prefix, run) {
   const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
-  if (!vaultRaw) { process.stderr.write('wendkeep renumber-decisions: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  if (!vaultRaw) { process.stderr.write(`wendkeep ${cmdName}: no vault (--vault or OBSIDIAN_VAULT_PATH).\n`); process.exit(2); }
   const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
-  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep renumber-decisions: vault not found: ${vaultBase}\n`); process.exit(2); }
+  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep ${cmdName}: vault not found: ${vaultBase}\n`); process.exit(2); }
 
   const apply = argv.includes('--apply');
-  const report = renumberDecisions(vaultBase, { apply });
+  const report = run(vaultBase, { apply });
 
   if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(report, null, 2)}\n`); process.exit(0); }
 
-  process.stdout.write(`${report.total} decisão(ões) · ${report.renamed} a renomear${apply ? ` · ${report.filesTouched} arquivo(s) com links atualizados` : ''}\n`);
+  process.stdout.write(`${report.total} ${unitLabel} · ${report.renamed} a renomear${apply ? ` · ${report.filesTouched} arquivo(s) com links atualizados` : ''}\n`);
   for (const p of report.plan.filter((x) => x.renamed)) {
-    process.stdout.write(`  ADR-${String(p.num).padStart(4, '0')}  ${p.from}\n              → ${p.to}\n`);
+    process.stdout.write(`  ${prefix}-${String(p.num).padStart(4, '0')}  ${p.from}\n              → ${p.to}\n`);
   }
   if (!apply) process.stdout.write('\nNada foi escrito (preview). Rode com --apply para renomear e atualizar os wikilinks.\n');
   process.exit(0);
 }
+
+export function runRenumberDecisions(argv) {
+  runRenumberCli(argv, 'renumber-decisions', 'decisão(ões)', 'ADR', (vault, o) => renumberDecisions(vault, o));
+}
+
+export function runRenumberBugs(argv) {
+  runRenumberCli(argv, 'renumber-bugs', 'bug(s)', DERIVED_KINDS.bugs.prefix, (vault, o) => renumberDerived(vault, 'bugs', o));
+}
+
+export function runRenumberLearnings(argv) {
+  runRenumberCli(argv, 'renumber-learnings', 'aprendizado(s)', DERIVED_KINDS.learnings.prefix, (vault, o) => renumberDerived(vault, 'learnings', o));
+}

package/src/skills-seed.mjs

@@ -65,6 +65,9 @@ vault cego. Exceção única: mudança trivial (typo, 1 linha).
   o que você declarou. Sem \`[sensor:]\`, o archive não trava.
 - A proposta linka a sessão de origem; a sessão linka a mudança ativa. É de propósito:
   o grafo do Obsidian mostra plano↔sessão↔decisão.
+- Notas derivadas (bug/aprendizado) são numeradas (\`BUG-NNNN-\`/\`APR-NNNN-\`) e vivem na
+  pasta do mês — nunca em subpasta \`DIA N\`. Crie via \`wendkeep note new --type
+  bug|learning "título"\` (imprime o path), não à mão.
 `;
 
 const TDD = `# TDD — Red, Green, Refactor (testes que discriminam)
@@ -132,6 +135,13 @@ mudando coisas no escuro.
   isole uma variável por vez.
 - Leia a mensagem de erro inteira e a stack — a linha decisiva costuma estar ali.
 - "Não faz sentido" = uma suposição sua está errada. Cheque as suposições, não o improvável.
+
+## Registro no vault
+
+Bug com valor durável vira nota numerada: \`wendkeep note new --type bug "resumo"\` —
+cria \`BUG-NNNN-<slug>.md\` na pasta do mês de \`05-Bugs\` (nunca subpasta \`DIA N\`) e
+imprime o path pra você preencher sintoma/causa raiz/correção. Aprendizado extraído do
+debug: \`wendkeep note new --type learning "lição"\` (vira \`APR-NNNN-\` em \`06-Aprendizados\`).
 `;
 
 const BRAINSTORMING = `# Brainstorming — ideia vira design
@@ -281,6 +291,9 @@ leaves the vault blind. Single exception: a trivial change (typo, one line).
   \`wendkeep change use <slug>\` or \`--change <slug>\` where available.
 - No \`[sensor:]\` on a task = no automated gate for it. No \`[req:]\` = no independent verdict.
 - The graph links session ↔ change ↔ requirement ↔ decision. That is the point.
+- Derived notes (bug/learning) are numbered (\`BUG-NNNN-\`/\`APR-NNNN-\`) and live in the
+  month folder — never in a \`DIA N\` subfolder. Create them via \`wendkeep note new --type
+  bug|learning "title"\` (prints the path), never by hand.
 `;
 
 const TDD_EN = `# TDD — Red, Green, Refactor (tests that discriminate)
@@ -324,6 +337,13 @@ Use it when something fails or behaves wrong. One hypothesis at a time — no sh
 
 Changed several things and it "worked"? You don't know what fixed it — revert, isolate one
 variable. Read the whole error + stack — the decisive line is usually there.
+
+## Vault record
+
+A durable bug becomes a numbered note: \`wendkeep note new --type bug "summary"\` — creates
+\`BUG-NNNN-<slug>.md\` in the month folder of \`05-Bugs\` (never a \`DIA N\` subfolder) and
+prints the path for you to fill in. A learning from the debug: \`wendkeep note new --type
+learning "lesson"\` (becomes \`APR-NNNN-\` in the learnings folder).
 `;
 
 const BRAINSTORMING_EN = `# Brainstorming — idea into design

package/src/taxonomy.mjs

@@ -46,6 +46,7 @@ export const HOOK_FILES = [
   'import-sessions.mjs',
   'decision-capture.mjs',
   'renumber-decisions.mjs',
+  'renumber-derived.mjs',
   'subagent-stop.mjs',
   'task-log.mjs',
   'vault-health.mjs',