wendkeep 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -4,6 +4,34 @@ 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.23.0] — 2026-07-08
+
+Vault structure — generated views + housekeeping (audit wave 2).
+
+### Added
+- **Generated Bases + Dashboard MOC**: `wendkeep init` now writes one folder-filtered `.base`
+  per taxonomy area (sessions/decisions/bugs/learnings/specs/changes) and a `00-Dashboard.md`
+  that embeds them — the vault's structural index. Filters are **by folder**
+  (`file.inFolder("05-Bugs")`), fixing the tag-filter that hid ~1/3 of bugs. New
+  `wendkeep dashboard [--force]` (re)generates them; non-destructive (never clobbers your own
+  bases). Locale-aware. `src/vault-views.mjs`.
+
+### Changed
+- **Archive ADRs land in the dated month folder** (`04-Decisões/<year>/<MM-MMM>/`) alongside
+  session-derived decisions, instead of the year root. `hooks/change-core.mjs`.
+- **`SESSION_REGISTRY` is pruned** on the idle sweep: `done` entries older than 90 days, then a
+  cap of 200 most-recent — active entries are never touched. Bounds the per-hook read/serialize
+  cost that had grown to 330 entries / ~170 KB in production. `hooks/obsidian-common.mjs`.
+- **Generated note names truncate on a word boundary** instead of mid-word (`slugify` gained a
+  boundary-aware `maxLen`). `hooks/obsidian-common.mjs`, `hooks/linked-notes.mjs`.
+- **Learnings dedup vault-wide**: a learning already recorded anywhere in `06-Aprendizados`
+  (by `content_key`) is not re-emitted on a later day/session. `hooks/linked-notes.mjs`.
+
+### Deferred
+- Unifying the two `buildSessionContent` skeletons (session-start / session-ensure) stays as
+  tracked tech-debt — pure refactor, high regression risk in the capture layer, and the
+  user-facing drift (`session_id`) was already closed in 0.18/0.21.
+
 ## [0.22.0] — 2026-07-08
 
 Hardening — 10 audit-confirmed bugs fixed (each survived an adversarial refuter).

package/bin/wendkeep.mjs

@@ -56,6 +56,7 @@ Usage:
                            --dry-run · --json.
   wendkeep verify [--deep] [--change s]  Run a change's task sensors + record evidence (the gate);
                            --deep assembles the verification package for the wk-verify pass.
+  wendkeep dashboard [--force]  (Re)generate the vault's folder-filtered Bases + 00-Dashboard MOC.
   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
@@ -148,6 +149,11 @@ async function main() {
       runImportCli(rest);
       break;
     }
+    case 'dashboard': {
+      const { runDashboard } = await import('../src/vault-views.mjs');
+      runDashboard(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

package/hooks/change-core.mjs

@@ -3,7 +3,7 @@
 // the `wendkeep change` CLI (src/change.mjs) and the brain-inject hook. No external deps.
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
-import { ensureDir, wikilinkFromRel } from './obsidian-common.mjs';
+import { ensureDir, wikilinkFromRel, monthFolderRelFromDateStr } from './obsidian-common.mjs';
 import { parseSpecsList, promoteSpecs } from './spec-core.mjs';
 import { getLocale } from './locale.mjs';
 
@@ -261,8 +261,9 @@ export function archiveChange(vaultBase, slug, { gate = gateGreen, dateStr, adrN
     writeFileSync(pp, c, 'utf8');
   } catch { /* proposta ilegível — segue */ }
 
-  const [year] = String(dateStr).split('-');
-  const adrDirRel = join(loc.folders.decisions, year);
+  // ADR goes in the same dated month folder as session-derived decisions (04-Decisões/ano/MM-MMM/)
+  // — not the year root — so all ADRs sit together in the vault's convention.
+  const adrDirRel = monthFolderRelFromDateStr(loc.folders.decisions, dateStr, vaultBase);
   ensureDir(join(vaultBase, adrDirRel));
   const num = String(adrNum).padStart(3, '0');
   const adrRel = join(adrDirRel, `ADR-${num}-${slug}.md`);

package/hooks/linked-notes.mjs

@@ -477,6 +477,30 @@ function listMd(dir) {
 }
 
 // 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/
+// session was duplicated. This dedups a learning against everything already learned in the vault.
+function collectLearningKeys(vaultBase) {
+  const keys = new Set();
+  const root = join(vaultBase, getLocale(vaultBase).folders.learnings);
+  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);
+      else if (e.name.endsWith('.md')) {
+        try {
+          const m = readFileSync(p, 'utf-8').match(/^content_key:\s*"?(.*?)"?\s*$/m);
+          if (m && m[1]) keys.add(m[1]);
+        } catch { /* nota ilegível */ }
+      }
+    }
+  };
+  walk(root);
+  return keys;
+}
+
 function existingKeysForSession(vaultBase, sessionRel, dateStr) {
   const wikilink = wikilinkFromRel(sessionRel);
   const out = { bugs: [], decisions: [], learnings: [] };
@@ -518,7 +542,7 @@ export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options =
     const issueRef = issueRefs[0] || '';
     const bugKey = derivedContentKey(bugDetails.rootCause);
     if (!alreadyHasKey(existingKeys.bugs, bugKey)) {
-      const causeSlug = slugify(bugDetails.rootCause.slice(0, 40), 'bug');
+      const causeSlug = slugify(bugDetails.rootCause, 'bug', 40);
       const fileName = issueRef ? `${issueRef}-${causeSlug}.md` : `${dateStr}-bug-${causeSlug}.md`;
       const filePath = join(bugsDir, fileName);
       if (!existsSync(filePath)) writeFileSync(filePath, buildBugNoteContent(bugDetails, issueRef, dateStr, sessionRel, provider, bugKey, loc.id), 'utf-8');
@@ -531,7 +555,7 @@ export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options =
   if (decisionDetails) {
     const decisionKey = derivedContentKey(decisionDetails.title);
     if (!alreadyHasKey(existingKeys.decisions, decisionKey)) {
-      const titleSlug = slugify(decisionDetails.title.slice(0, 40), 'decisao');
+      const titleSlug = slugify(decisionDetails.title, 'decisao', 40);
       const existing = adrFileExistsBySlug(decisionsDir, titleSlug);
       const fileName = existing || `ADR-${String(getNextAdrNumber(vaultBase)).padStart(3, '0')}-${titleSlug}.md`;
       const filePath = join(decisionsDir, fileName);
@@ -546,10 +570,12 @@ export function createLinkedNotes(vaultBase, dateStr, sessionRel, tx, options =
 
   const learnings = extractLearningDetails(tx, bugDetails);
   if (learnings) {
+    const vaultLearningKeys = collectLearningKeys(vaultBase); // vault-wide dedup
     for (const learning of learnings) {
       const learningKey = derivedContentKey(learning.title);
       if (alreadyHasKey(existingKeys.learnings, learningKey)) continue;
-      const learningSlug = slugify(learning.title.slice(0, 40), 'aprendizado');
+      if (vaultLearningKeys.has(learningKey)) continue; // already learned elsewhere in the vault
+      const learningSlug = slugify(learning.title, 'aprendizado', 40);
       const fileName = `${dateStr}-${learningSlug}.md`;
       const filePath = join(learningsDir, fileName);
       if (!existsSync(filePath)) writeFileSync(filePath, buildLearningNoteContent(learning, dateStr, sessionRel, provider, learningKey, loc.id), 'utf-8');

package/hooks/obsidian-common.mjs

@@ -289,12 +289,38 @@ export function sweepStaleSessions(registry, nowMs, maxIdleMs, excludeTranscript
   return closed;
 }
 
-// Wrapper de IO: varre as ociosas, grava o registry e fecha a NOTA `.md` de cada
+// Registry retention. The registry is read/serialized in full on every hook and scanned O(N)
+// for routing — it only needs active + recent sessions (historical audit lives in the notes).
+// Left unbounded it grew to 330 entries / ~170 KB in production.
+export const REGISTRY_KEEP_DONE = 200;
+export const REGISTRY_DONE_MAX_AGE_MS = 90 * 24 * 60 * 60 * 1000;
+
+// Pure: drop 'done' entries older than maxAgeMs, then cap the remaining 'done' at keepDone
+// (newest by ended_at/updated_at/started_at kept). Never touches active entries. Mutates the
+// registry and returns how many were pruned.
+export function pruneRegistry(registry, nowMs, { keepDone = REGISTRY_KEEP_DONE, maxAgeMs = REGISTRY_DONE_MAX_AGE_MS } = {}) {
+  const sessions = registry?.sessions || {};
+  const stamp = (v) => Date.parse((v && (v.ended_at || v.updated_at || v.started_at)) || '') || 0;
+  let pruned = 0;
+  for (const [id, v] of Object.entries(sessions)) {
+    if (!v || v.status !== 'done') continue;
+    const t = stamp(v);
+    if (t && nowMs - t > maxAgeMs) { delete sessions[id]; pruned += 1; }
+  }
+  const done = Object.entries(sessions)
+    .filter(([, v]) => v && v.status === 'done')
+    .sort((a, b) => stamp(b[1]) - stamp(a[1]));
+  for (const [id] of done.slice(keepDone)) { delete sessions[id]; pruned += 1; }
+  return pruned;
+}
+
+// Wrapper de IO: varre as ociosas, poda o registry, grava e fecha a NOTA `.md` de cada
 // sessão encerrada (mantém vault e registry alinhados). Devolve quantas fechou.
 export function sweepStaleSessionsFile(vaultBase, now = new Date(), maxIdleMs = SESSION_IDLE_CLOSE_MS, excludeTranscriptPath = '') {
   const registry = readSessionRegistry(vaultBase);
   const closed = sweepStaleSessions(registry, now.getTime(), maxIdleMs, excludeTranscriptPath);
-  if (closed.length) writeSessionRegistry(vaultBase, registry);
+  const pruned = pruneRegistry(registry, now.getTime());
+  if (closed.length || pruned) writeSessionRegistry(vaultBase, registry);
   for (const { session_file, ended_at } of closed) {
     try { closeSessionNoteFile(vaultBase, session_file, ended_at); } catch { /* nunca derruba o sweep */ }
   }
@@ -335,15 +361,20 @@ export function closeSessionNote(content, endedAt) {
   return next;
 }
 
-export function slugify(text, fallback = 'nota') {
-  const slug = String(text || '')
+export function slugify(text, fallback = 'nota', maxLen = 60) {
+  let slug = String(text || '')
     .normalize('NFD')
     .replace(/[\u0300-\u036f]/g, '')
     .toLowerCase()
     .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '')
-    .slice(0, 70)
-    .replace(/-+$/g, '');
+    .replace(/^-+|-+$/g, '');
+  if (slug.length > maxLen) {
+    // Truncate on a word boundary (last '-' before maxLen) when a reasonable one exists,
+    // instead of cutting mid-word \u2014 keeps generated note names readable.
+    const cut = slug.slice(0, maxLen);
+    const lastDash = cut.lastIndexOf('-');
+    slug = (lastDash > maxLen * 0.5 ? cut.slice(0, lastDash) : cut).replace(/-+$/g, '');
+  }
   return slug || fallback;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.22.0",
+  "version": "0.23.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

@@ -22,6 +22,7 @@ import {
   DOTCONTEXT_GITIGNORE,
 } from './taxonomy.mjs';
 import { renderVaultReadme } from './vault-readme.mjs';
+import { seedVaultViews } from './vault-views.mjs';
 import { canInteractiveSelect, selectCompanionsInteractive } from './companion-select.mjs';
 import {
   SNIPPET_NAME,
@@ -364,7 +365,13 @@ export async function runInit(argv) {
     try { scripts = JSON.parse(readFileSync(join(projectPath, 'package.json'), 'utf8')).scripts || {}; } catch { /* no package.json */ }
     writeFileSync(sensorsFile, renderSensorsJson(scripts), 'utf8');
   }
-  log(`  [1/4] vault taxonomy: ${folders.length} folders (${created} created, locale ${loc.id})${readmeNote}, .brain + change/spec + sensors seeded`);
+  // Generated Bases + Dashboard MOC (folder-filtered views over the taxonomy) — non-destructive.
+  let viewsNote = '';
+  try {
+    const views = seedVaultViews(vaultPath);
+    if (views.length) viewsNote = `, ${views.length} view(s) + dashboard`;
+  } catch { /* views são bônus — nunca derrubam o init */ }
+  log(`  [1/4] vault taxonomy: ${folders.length} folders (${created} created, locale ${loc.id})${readmeNote}, .brain + change/spec + sensors seeded${viewsNote}`);
   // Deliver the seeded defs (agents + wk process skills) to the project so they're
   // usable immediately — no separate `wendkeep sync-defs` step needed.
   const synced = syncDefs(vaultPath, projectPath);

package/src/vault-views.mjs

@@ -0,0 +1,99 @@
+// Generated Obsidian Bases + a Dashboard MOC — the vault's structural index (0.23.0).
+// Each taxonomy folder gets a folder-filtered `.base` (NOT tag-filtered: a tag filter hid ~1/3
+// of the corpus in production) and 00-Dashboard.md embeds them. Locale-aware; non-destructive
+// (never overwrites a user's own base) unless force is passed. Zero runtime deps.
+import { existsSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { getLocale } from '../hooks/locale.mjs';
+
+// Per-area view: which folder, which frontmatter columns, and their display labels.
+function areaSpecs(loc) {
+  const f = loc.folders;
+  const en = loc.id === 'en';
+  const date = en ? 'Date' : 'Data';
+  return [
+    { key: 'sessoes', folder: f.sessions, title: en ? 'Sessions' : 'Sessões',
+      cols: ['date', 'provider', 'custo_modelo_usd', 'prompts', 'tool_calls'],
+      labels: { date, provider: en ? 'Agent' : 'Agente', custo_modelo_usd: 'US$', prompts: 'Prompts', tool_calls: 'Tools' } },
+    { key: 'decisoes', folder: f.decisions, title: en ? 'Decisions' : 'Decisões',
+      cols: ['date', 'status'], labels: { date, status: 'Status' } },
+    { key: 'bugs', folder: f.bugs, title: 'Bugs',
+      cols: ['date', 'status', 'severity'], labels: { date, status: 'Status', severity: en ? 'Severity' : 'Severidade' } },
+    { key: 'aprendizados', folder: f.learnings, title: en ? 'Learnings' : 'Aprendizados',
+      cols: ['date'], labels: { date } },
+    { key: 'specs', folder: f.specs, title: 'Specs', cols: ['date'], labels: { date } },
+    { key: 'mudancas', folder: f.changes, title: en ? 'Changes' : 'Mudanças',
+      cols: ['date', 'status'], labels: { date, status: 'Status' } },
+  ];
+}
+
+// A minimal, valid Base: folder filter + one table view. No formulas (that's where Base syntax
+// errors hide) — the folder filter is the whole fix.
+export function renderBase(spec) {
+  const props = spec.cols.map((c) => `  ${c}:\n    displayName: ${spec.labels[c] || c}`).join('\n');
+  const order = ['file.name', ...spec.cols].map((c) => `      - ${c}`).join('\n');
+  return `filters:
+  and:
+    - file.inFolder("${spec.folder}")
+    - file.ext == "md"
+properties:
+${props}
+views:
+  - type: table
+    name: ${spec.title}
+    order:
+${order}
+`;
+}
+
+export function renderDashboard(specs, en) {
+  const blocks = specs.map((s) => `## ${s.title}\n\n![[${s.key}.base]]`).join('\n\n---\n\n');
+  return `---
+tags:
+  - dashboard
+cssclasses:
+  - topic-dashboard
+---
+
+# ${en ? 'Vault — Overview' : 'Vault — Visão Geral'}
+
+> ${en ? 'Generated by wendkeep. Each section embeds a folder-filtered Base view (needs the Obsidian Bases core plugin).' : 'Gerado pelo wendkeep. Cada seção embeda uma view Base filtrada por pasta (requer o core plugin Bases do Obsidian).'}
+
+---
+
+${blocks}
+`;
+}
+
+// Write one `<key>.base` per area + 00-Dashboard.md. Non-destructive unless force. Returns the
+// list of files written.
+export function seedVaultViews(vaultBase, { force = false } = {}) {
+  const loc = getLocale(vaultBase);
+  const specs = areaSpecs(loc);
+  const written = [];
+  for (const s of specs) {
+    const p = join(vaultBase, `${s.key}.base`);
+    if (force || !existsSync(p)) { writeFileSync(p, renderBase(s), 'utf8'); written.push(`${s.key}.base`); }
+  }
+  const dash = join(vaultBase, '00-Dashboard.md');
+  if (force || !existsSync(dash)) { writeFileSync(dash, renderDashboard(specs, loc.id === 'en'), 'utf8'); written.push('00-Dashboard.md'); }
+  return written;
+}
+
+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;
+}
+
+// `wendkeep dashboard [--vault P] [--force]` — (re)generate the Bases + Dashboard.
+export function runDashboard(argv) {
+  const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep dashboard: 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 dashboard: vault not found: ${vaultBase}\n`); process.exit(2); }
+  const written = seedVaultViews(vaultBase, { force: argv.includes('--force') });
+  process.stdout.write(written.length ? `dashboard: ${written.length} arquivo(s) — ${written.join(', ')}\n` : 'dashboard: nada a fazer (use --force para regenerar)\n');
+  process.exit(0);
+}