wendkeep 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -4,6 +4,64 @@ 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
+
+- `parseTasks` captura **todos** os `[req:]` de uma tarefa em `reqs: string[]` (`req` permanece
+  como alias do primeiro, retrocompatível). Antes, só o primeiro entrava no pacote de
+  verificação e os demais sumiam sem aviso.
+- Heading de requisito aceita ID puro (`### Requisito: GATE-1`) como identidade, além do
+  formato preferido `### Requisito: <ID> — <nome>`. Diagnóstico de requisito órfão agora
+  ensina o formato esperado com exemplo concreto.
+- `findProjectRoot`: `wendkeep verify` executado de um subdiretório sobe a árvore até achar
+  `wendkeep.sensors.json`/`.wendkeep.json` (à la `.git`); `--project` continua autoritativo.
+- `--help`/`-h` universal: qualquer subcomando com `--help` imprime a ajuda e sai com 0,
+  interceptado antes da resolução de vault — nunca executa o comando.
+
+### Fixed
+
+- Regex de ID de requisito unificada entre tarefa e spec (`REQ_ID_RE_SRC`): IDs
+  multi-segmento (`API-AUTH-2`) agora são reconhecidos também nas tarefas.
+- `wendkeep verify` distingue `wendkeep.sensors.json` ausente (aviso com path + dica
+  `--project`) de JSON inválido (erro alto com a mensagem do parse). Antes, ambos viravam
+  "sensor não definido" para todos os sensores.
+- `wendkeep import` com flag desconhecida agora falha com exit 2 citando a flag, em vez de
+  cair no default destrutivo `--source all` (que chegou a importar 78 sessões sem querer).
+- Templates seed (skills de workflow pt/en) documentam o formato de heading de requisito e o
+  suporte a múltiplos `[req:]` por tarefa.
+
 ## [0.39.0] — 2026-07-13
 
 ### 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
@@ -125,6 +131,13 @@ async function preferProjectVault(argv) {
 
 async function main() {
   const [cmd, ...rest] = process.argv.slice(2);
+  // Universal --help: any subcommand with --help/-h prints usage and never executes.
+  // Intercepted BEFORE vault resolution so it works anywhere — help must never depend
+  // on project state, and no command may treat --help as a runnable default.
+  if (cmd && (rest.includes('--help') || rest.includes('-h'))) {
+    process.stdout.write(HELP);
+    process.exit(0);
+  }
   if (cmd && !['init', 'hook', '--version', '-v', '--help', '-h', 'help'].includes(cmd)) {
     await preferProjectVault(rest);
   }
@@ -207,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/change-core.mjs

@@ -4,7 +4,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { ensureDir, wikilinkFromRel, monthFolderRelFromDateStr } from './obsidian-common.mjs';
-import { parseSpecsList, promoteSpecs, discoverSpecDeltas, tasksHashOf, captureSpecBaseline } from './spec-core.mjs';
+import { parseSpecsList, promoteSpecs, discoverSpecDeltas, tasksHashOf, captureSpecBaseline, REQ_ID_RE_SRC } from './spec-core.mjs';
 import { getLocale } from './locale.mjs';
 
 export const ARCHIVE_DIR = '_arquivo';
@@ -161,18 +161,18 @@ export function parseTasks(md) {
   const tasks = [];
   const re = /^-\s+\[( |x)\]\s+(\S+)\s+(.*)$/gm;
   const sensorRe = /\[sensor:\s*([\w.-]+)\]/;
-  const reqRe = /\[req:\s*([A-Z][A-Z0-9]*-\d+)\]/;
+  const reqReG = new RegExp(`\\[req:\\s*(${REQ_ID_RE_SRC})\\]`, 'g');
   let m;
   while ((m = re.exec(String(md))) !== null) {
     let text = m[3].trim();
     const sm = text.match(sensorRe);
-    const rm = text.match(reqRe);
+    const reqs = [...text.matchAll(reqReG)].map((r) => r[1]);
     const sensor = sm ? sm[1] : undefined;
-    const req = rm ? rm[1] : undefined;
     if (sm) text = text.replace(sensorRe, '');
-    if (rm) text = text.replace(reqRe, '');
+    if (reqs.length) text = text.replace(reqReG, '');
     text = text.replace(/\s+/g, ' ').trim();
-    tasks.push({ id: m[2], text, done: m[1] === 'x', ...(sensor ? { sensor } : {}), ...(req ? { req } : {}) });
+    // `req` stays as alias of the first id — older consumers keep working.
+    tasks.push({ id: m[2], text, done: m[1] === 'x', ...(sensor ? { sensor } : {}), ...(reqs.length ? { req: reqs[0], reqs } : {}) });
   }
   return tasks;
 }
@@ -419,7 +419,7 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
   }
 
   let reqIds = [];
-  try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).map((t) => t.req).filter(Boolean))]; } catch { /* sem tarefas */ }
+  try { reqIds = [...new Set(parseTasks(readFileSync(join(src, 'tarefas.md'), 'utf8')).flatMap((t) => t.reqs ?? []))]; } catch { /* sem tarefas */ }
 
   ensureDir(join(vaultBase, chDir, ARCHIVE_DIR));
   try {

package/hooks/harness-doctor.mjs

@@ -41,7 +41,7 @@ export function checkHarness(vaultBase, projectRoot) {
     let tasks = [];
     let tarefasMd = '';
     try { tarefasMd = readFileSync(join(dir, 'tarefas.md'), 'utf8'); tasks = parseTasks(tarefasMd); } catch { /* sem tarefas */ }
-    const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+    const reqIds = [...new Set(tasks.flatMap((t) => t.reqs ?? []))];
     const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
     errors.push(...effective.errors.map((e) => `${name}: spec efetiva inválida: ${e}`));
     if (effective.missing.length) errors.push(`req órfão em ${name}: ${effective.missing.map((id) => `[req:${id}]`).join(', ')} não existe na spec efetiva`);

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/sensors-core.mjs

@@ -2,15 +2,37 @@
 // Pure-ish: `spawn` is injectable so runs are testable without a shell. Config lives
 // at the PROJECT ROOT (wendkeep.sensors.json); evidence lives per-change in the vault.
 import { spawnSync } from 'node:child_process';
-import { readFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 
 export function loadSensors(projectRoot, file = 'wendkeep.sensors.json') {
+  return loadSensorsDetailed(projectRoot, file).sensors;
+}
+
+// Missing config and broken config are different failures: absent file usually means
+// wrong cwd (subdirectory), broken JSON means the config itself needs fixing. Collapsing
+// both into [] made every sensor report "sensor não definido" — a misleading diagnosis.
+export function loadSensorsDetailed(projectRoot, file = 'wendkeep.sensors.json') {
+  const path = join(projectRoot, file);
+  if (!existsSync(path)) return { sensors: [], missing: true, error: null, path };
   try {
-    const data = JSON.parse(readFileSync(join(projectRoot, file), 'utf8'));
-    return Array.isArray(data.sensors) ? data.sensors : [];
-  } catch {
-    return [];
+    const data = JSON.parse(readFileSync(path, 'utf8'));
+    return { sensors: Array.isArray(data.sensors) ? data.sensors : [], missing: false, error: null, path };
+  } catch (e) {
+    return { sensors: [], missing: false, error: e.message, path };
+  }
+}
+
+// Climb the directory tree looking for a project marker (wendkeep.sensors.json or
+// .wendkeep.json), like git does with .git — shells in agent harnesses keep their cwd
+// across commands, so verify is often run from a subdirectory.
+export function findProjectRoot(startDir) {
+  let dir = resolve(startDir);
+  for (;;) {
+    if (existsSync(join(dir, 'wendkeep.sensors.json')) || existsSync(join(dir, '.wendkeep.json'))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
   }
 }
 

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/hooks/spec-core.mjs

@@ -22,15 +22,29 @@ export const MANAGED_SPEC_MARKER = '<!-- wendkeep:managed-spec — generated fro
 // Parse is BILINGUAL always (mixed vaults never break); rendering follows the vault locale.
 const REQ_RE = /^### (?:Requisito|Requirement):\s*(.+)$/gm;
 
+// Single source of truth for requirement-id shape — task tags ([req:ID]) and spec
+// headings MUST agree, or coverage silently misses (multi-segment ids like API-AUTH-2).
+export const REQ_ID_RE_SRC = '[A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\\d+';
+
+// Orphan diagnostics must teach the fix, not just name the ids — the heading format
+// is the most common cause and lives only here.
+export function formatOrphanReqs(ids) {
+  const list = ids.join(', ');
+  const ex = ids[0] || 'GATE-1';
+  return `requisito(s) órfão(s) na spec efetiva: ${list} — heading esperado no spec.md da change: "### Requisito: ${ex} — <nome>" (ou só "### Requisito: ${ex}")`;
+}
+
 export function parseRequirements(md) {
   const text = String(md);
   const matches = [...text.matchAll(REQ_RE)];
   const reqs = [];
   for (let i = 0; i < matches.length; i += 1) {
     const raw = matches[i][1].trim();
-    // Identity is the ID (e.g. GATE-1) when the heading is "<ID> — <nome>"; else the whole text.
-    const idM = raw.match(/^([A-Z][A-Z0-9]*(?:-[A-Z0-9]+)*-\d+)\s*—\s*(.+)$/);
-    const id = idM ? idM[1] : null;
+    // Identity is the ID (e.g. GATE-1) when the heading is "<ID> — <nome>" or a bare
+    // "<ID>"; else the whole text. Bare ids keep specs writable without the em-dash.
+    const idM = raw.match(new RegExp(`^(${REQ_ID_RE_SRC})\\s*—\\s*(.+)$`));
+    const bare = idM ? null : raw.match(new RegExp(`^(${REQ_ID_RE_SRC})$`));
+    const id = idM ? idM[1] : bare ? bare[1] : null;
     const name = idM ? idM[2].trim() : raw;
     const start = matches[i].index + matches[i][0].length;
     const end = i + 1 < matches.length ? matches[i + 1].index : text.length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.39.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": {
@@ -46,6 +46,6 @@
     "url": "https://github.com/rogersialves/wendkeep/issues"
   },
   "devDependencies": {
-    "wendkeep": "^0.38.3"
+    "wendkeep": "^0.39.0"
   }
 }

package/src/change.mjs

@@ -17,7 +17,7 @@ import {
   scaffoldPlaceholders,
 } from '../hooks/change-core.mjs';
 import { evaluateGate, requiredSensors } from '../hooks/sensors-core.mjs';
-import { buildEffectiveRequirementPackage, evaluateVerdict, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta, validateSpecImpact } from '../hooks/spec-core.mjs';
+import { buildEffectiveRequirementPackage, evaluateVerdict, formatOrphanReqs, tasksHashOf, parseSpecsList, parseDelta, parseRequirements, applyDelta, validateSpecImpact } from '../hooks/spec-core.mjs';
 import { getNextAdrNumber, readControl, readSessionRegistry, upsertSessionRegistry } from '../hooks/obsidian-common.mjs';
 import { getLocale } from '../hooks/locale.mjs';
 
@@ -147,13 +147,13 @@ export function runChange(argv) {
     process.stdout.write(`specs: ${specs.join(', ') || '(nenhuma)'}\n`);
     process.stdout.write(`tarefas: ${done} done / ${tasks.length - done} open\n`);
     for (const t of tasks) {
-      process.stdout.write(`  [${t.done ? 'x' : ' '}] ${t.id} ${t.text}${t.req ? ` [req:${t.req}]` : ''}${t.sensor ? ` [sensor:${t.sensor}]` : ''}\n`);
+      process.stdout.write(`  [${t.done ? 'x' : ' '}] ${t.id} ${t.text}${(t.reqs ?? []).map((r) => ` [req:${r}]`).join('')}${t.sensor ? ` [sensor:${t.sensor}]` : ''}\n`);
     }
     let evidence = null;
     try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* sem evidência */ }
     if (evidence) for (const e of evidence) process.stdout.write(`  ${e.status === 'green' ? '✓' : '✗'} ${e.id} (${e.severity || 'critical'})\n`);
     else process.stdout.write('evidencia: ausente\n');
-    const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+    const reqIds = [...new Set(tasks.flatMap((t) => t.reqs ?? []))];
     const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
     if (effective.errors.length || effective.missing.length) {
       process.stdout.write(`spec efetiva: inválida (${[...effective.errors, ...effective.missing.map((id) => `req órfão ${id}`)].join('; ')})\n`);
@@ -239,10 +239,10 @@ export function runChange(argv) {
           return { ok: false, failing: ['evidência stale (tarefas.md mudou desde o último verify) — rode `wendkeep verify` de novo'] };
         }
       }
-      const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+      const reqIds = [...new Set(tasks.flatMap((t) => t.reqs ?? []))];
       const effective = buildEffectiveRequirementPackage(vaultBase, dir, reqIds);
       if (effective.errors.length) return { ok: false, failing: [`spec efetiva inválida: ${effective.errors.join('; ')}`] };
-      if (effective.missing.length) return { ok: false, failing: [`requisito(s) órfão(s) na spec efetiva: ${effective.missing.join(', ')}`] };
+      if (effective.missing.length) return { ok: false, failing: [formatOrphanReqs(effective.missing)] };
       let evidence = [];
       try { evidence = JSON.parse(readFileSync(join(dir, 'evidencia.json'), 'utf8')); } catch { /* no evidence */ }
       const s = evaluateGate(evidence, required);

package/src/import.mjs

@@ -12,7 +12,22 @@ function opt(argv, name) {
   return eq ? eq.slice(name.length + 1) : undefined;
 }
 
+const KNOWN_FLAGS = new Set([
+  '--vault', '--project', '--source', '--from', '--codex-from', '--since', '--limit',
+  '--dry-run', '--json', '--rescan-decisions', '--stamp-ids', '--help', '-h',
+]);
+
 export function runImportCli(argv) {
+  // Import writes to the vault; an unrecognized flag must never fall through to the
+  // destructive default (--source all). Fail fast, point at --help.
+  for (const a of argv) {
+    if (!a.startsWith('-')) continue;
+    const name = a.includes('=') ? a.slice(0, a.indexOf('=')) : a;
+    if (!KNOWN_FLAGS.has(name)) {
+      process.stderr.write(`wendkeep import: flag desconhecida "${name}" (use --help)\n`);
+      process.exit(2);
+    }
+  }
   const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
   if (!vaultRaw) { process.stderr.write('wendkeep import: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
   const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);

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

@@ -35,15 +35,18 @@ vault cego. Exceção única: mudança trivial (typo, 1 linha).
    Antes de implementar, resolva \`spec_impact\` na proposta:
    - \`required\`: liste a capability em \`specs:\` e preencha
      \`specs/<capability>/spec.md\` com ADDED/MODIFIED/REMOVED; ligue tarefas com \`[req:ID]\`.
+     Heading de requisito: \`### Requisito: <ID> — <nome>\` (ou só \`### Requisito: <ID>\`);
+     o ID é a identidade (ex.: \`GATE-1\`, \`API-AUTH-2\`).
    - \`none\`: registre uma justificativa real em \`spec_impact_reason\`.
    \`pending\` nunca é estado pronto para implementação ou archive.
 3. **Apply** — implemente cada tarefa de \`tarefas.md\` com disciplina **wk-tdd**
    (teste vermelho antes do código). Marque \`- [x]\` ao concluir. Declare nas tarefas:
    - \`[sensor:<id>]\` — a prova automatizada (roda no verify).
    - \`[req:<ID>]\` — o requisito do spec que a tarefa satisfaz (ex.: \`[req:GATE-1]\`),
-      quando a change mexe numa capability. Toda autoria de spec ocorre somente em
+      quando a change mexe numa capability. Uma tarefa pode declarar vários
+      \`[req:]\` — todos contam na cobertura. Toda autoria de spec ocorre somente em
       \`08-Mudanças/<slug>/specs/<capability>/spec.md\`; \`07-Specs\` é gerado/read-only.
-   Ex.: \`- [ ] 2.1 valida CORE [req:MEM-1] [sensor:memory-validation]\`.
+   Ex.: \`- [ ] 2.1 valida CORE [req:MEM-1] [req:MEM-2] [sensor:memory-validation]\`.
 4. **Verify** — \`wendkeep verify\` roda os sensores → \`evidencia.json\`. Depois
    \`wendkeep verify --deep\` monta o *pacote de verificação* pro passe independente.
 5. **Verify deep** — a skill **wk-verify** (passe fresco, autor≠verificador) lê o pacote,
@@ -62,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)
@@ -129,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
@@ -259,8 +272,11 @@ leaves the vault blind. Single exception: a trivial change (typo, one line).
    Before implementation, resolve \`spec_impact\`: \`required\` needs the capability listed in
    \`specs:\` plus a real \`specs/<capability>/spec.md\` delta and \`[req:ID]\` links; \`none\`
    needs a real \`spec_impact_reason\`. \`pending\` is never ready for implementation/archive.
+   Requirement heading: \`### Requirement: <ID> — <name>\` (or bare \`### Requirement: <ID>\`);
+   the ID is the identity (e.g. \`GATE-1\`, \`API-AUTH-2\`).
 3. **Apply** — implement each task in tarefas.md with **wk-tdd** (red test first). Tag tasks:
-   \`[sensor:<id>]\` (automated proof) and \`[req:<ID>]\` (the spec requirement it satisfies).
+   \`[sensor:<id>]\` (automated proof) and \`[req:<ID>]\` (the spec requirement it satisfies;
+   a task may declare several \`[req:]\` tags — all of them count toward coverage).
    Author specs only in \`08-Changes/<slug>/specs/\`; \`07-Specs\` is generated/read-only.
 4. **Verify** — \`wendkeep verify\` runs the sensors; then \`wendkeep verify --deep\` builds
    the verification package.
@@ -275,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)
@@ -318,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/spec.mjs

@@ -49,7 +49,7 @@ export function runSpec(argv) {
       tasks = parseTasks(readFileSync(join(changeDir, 'tarefas.md'), 'utf8'));
     }
     catch { process.stderr.write(`wendkeep spec effective: change not found: ${slug}\n`); process.exit(2); }
-    const reqIds = [...new Set(tasks.map((task) => task.req).filter(Boolean))];
+    const reqIds = [...new Set(tasks.flatMap((task) => task.reqs ?? []))];
     const effective = buildEffectiveRequirementPackage(vaultBase, changeDir, reqIds);
     if (effective.errors.length) {
       process.stderr.write(`wendkeep spec effective: invalid delta: ${effective.errors.join('; ')}\n`);

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',

package/src/verify.mjs

@@ -4,10 +4,11 @@
 import { readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { isAbsolute, join, resolve } from 'node:path';
 import { parseTasks, activeChange, appendFixTasks } from '../hooks/change-core.mjs';
-import { loadSensors, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.mjs';
+import { loadSensorsDetailed, findProjectRoot, requiredSensors, runSensors, evaluateGate } from '../hooks/sensors-core.mjs';
 import {
   buildEffectiveRequirementPackage,
   captureSpecBaseline,
+  formatOrphanReqs,
   tasksHashOf,
 } from '../hooks/spec-core.mjs';
 import { addLesson } from '../hooks/lessons-core.mjs';
@@ -29,7 +30,9 @@ export function runVerify(argv) {
   const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
   if (!vaultRaw) { process.stderr.write('wendkeep verify: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
   const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
-  const projectRoot = resolve(opt(argv, '--project') || process.cwd());
+  // --project wins; otherwise climb from cwd to the nearest project marker (agent shells
+  // keep their cwd across commands, so verify from a subdirectory is a recurring miss).
+  const projectRoot = resolve(opt(argv, '--project') || findProjectRoot(process.cwd()) || process.cwd());
   const slug = opt(argv, '--change') || activeChange(vaultBase);
   if (!slug) { process.stderr.write('wendkeep verify: no change (--change or active).\n'); process.exit(2); }
 
@@ -39,7 +42,15 @@ export function runVerify(argv) {
   catch { process.stderr.write(`wendkeep verify: change not found: ${slug}\n`); process.exit(2); }
 
   const ids = requiredSensors(parseTasks(tarefas));
-  const sensors = loadSensors(projectRoot);
+  const loaded = loadSensorsDetailed(projectRoot);
+  if (loaded.error) {
+    process.stderr.write(`wendkeep verify: wendkeep.sensors.json inválido em ${loaded.path}: ${loaded.error}\n`);
+    process.exit(2);
+  }
+  if (loaded.missing && ids.length) {
+    process.stderr.write(`wendkeep verify: wendkeep.sensors.json não encontrado em ${loaded.path} — rode da raiz do projeto ou use --project <raiz>\n`);
+  }
+  const sensors = loaded.sensors;
   const evidence = runSensors(sensors, ids, { cwd: projectRoot });
   writeFileSync(join(changeDir, 'evidencia.json'), `${JSON.stringify(evidence, null, 2)}\n`, 'utf8');
   // Freshness seal: bind this evidence to the tarefas.md it was produced against, so the archive
@@ -90,7 +101,7 @@ export function runVerify(argv) {
   // change (no [req:] tasks, sensors green) gets an auto verdict — no agent pass needed.
   if (argv.includes('--deep')) {
     const tasks = parseTasks(tarefas);
-    const reqIds = [...new Set(tasks.map((t) => t.req).filter(Boolean))];
+    const reqIds = [...new Set(tasks.flatMap((t) => t.reqs ?? []))];
     const tasksHash = tasksHashOf(tarefas);
     captureSpecBaseline(vaultBase, changeDir);
     const effective = buildEffectiveRequirementPackage(vaultBase, changeDir, reqIds);
@@ -99,7 +110,7 @@ export function runVerify(argv) {
       process.exit(1);
     }
     if (effective.missing.length) {
-      process.stderr.write(`verify --deep: requisito(s) órfão(s) na spec efetiva: ${effective.missing.join(', ')}\n`);
+      process.stderr.write(`verify --deep: ${formatOrphanReqs(effective.missing)}\n`);
       process.exit(1);
     }
     const pkg = {
@@ -116,7 +127,7 @@ export function runVerify(argv) {
           body: req.body,
         };
       }),
-      tasks: tasks.map((t) => ({ id: t.id, text: t.text, req: t.req || null, done: t.done })),
+      tasks: tasks.map((t) => ({ id: t.id, text: t.text, req: t.req || null, reqs: t.reqs || [], done: t.done })),
       sensors: evidence,
     };
     writeFileSync(join(changeDir, 'verificacao.json'), `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');