wendkeep 0.42.0 → 0.45.0

package/CHANGELOG.md

@@ -4,6 +4,44 @@ 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.45.0] — 2026-07-18
+
+### Fixed
+
+- Observabilidade: o note de sessão deixa de ser reescrito com timestamp novo a cada Stop
+  quando o uso não muda. A preservação de `atualizado_em` (`token-usage.mjs`) comparava
+  `previous` (parseado do note) com `current` (recém-computado) via `JSON.stringify` —
+  sensível à ordem das chaves, que difere entre parse e build, então a comparação **sempre**
+  falhava e o timestamp era re-stampado toda vez. Novo `sameUsageData(a, b)` compara os campos
+  de uso de forma ordem-insensível (ignorando `atualizado_em`). Corrige o churn de reescrita e
+  o teste flaky "same sources produce byte-identical markdown".
+
+## [0.44.0] — 2026-07-17
+
+### Changed
+
+- `wendkeep change new` não cria mais o placeholder `specs/exemplo/spec.md` (nem a pasta
+  `specs/`). Era ruído — sempre deletado à mão, e `discoverSpecDeltas` já o filtrava. Quando
+  a change resolve `spec_impact: required`, o autor escreve `specs/<capability>/spec.md`
+  direto; o formato do delta vive na skill wk-workflow. O filtro de `exemplo` fica (compat
+  com changes antigas em voo).
+- README gerado do `07-Specs` reescrito para explicar o ponto mais confundido: specs são
+  **por capability, não por mudança** (N changes promovem no mesmo arquivo; o histórico
+  por-change vive em `_arquivo`). `promoteSpecs` passa a garantir/atualizar esse README a
+  cada archive (`ensureSpecsReadme`), então vaults existentes recebem o texto novo no
+  próximo archive — não só os criados via `init`.
+
+## [0.43.0] — 2026-07-17
+
+### Fixed
+
+- Dedup de nota derivada era assimétrico: aprendizado deduplicava recursivamente (vault
+  inteiro), mas **bug e decisão só olhavam a pasta do mês** (`existingKeysForSession`, scan
+  não-recursivo). Uma nota da sessão numa subpasta `DIA` legada não era vista, então um
+  re-import/re-captura da mesma sessão criava uma duplicata de bug/decisão. Agora
+  `existingKeysForSession` varre a pasta derivada recursivamente (como o de aprendizado),
+  mantendo a semântica per-sessão (só notas que referenciam a sessão contam).
+
 ## [0.42.0] — 2026-07-17
 
 ### Changed

package/hooks/change-core.mjs

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

package/hooks/linked-notes.mjs

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

package/hooks/spec-core.mjs

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

package/hooks/token-usage.mjs

@@ -604,6 +604,19 @@ function transcriptIdFromPath(transcriptPath) {
   return basename(String(transcriptPath || '')).replace(/\.jsonl?$/i, '') || 'desconhecido';
 }
 
+// The usage fields that define whether a transcript's entry "changed" — everything except the
+// key (transcript_id) and the timestamp (atualizado_em). Order-insensitive by design: a new
+// field here is the single place to keep preservation correct.
+const USAGE_FIELDS = ['provider', 'pensamento', 'input', 'cache_write', 'cache_read',
+  'output', 'reasoning', 'total', 'custo_usd', 'prompts', 'tool_calls', 'chamadas_llm'];
+
+export function sameUsageData(a, b) {
+  if (!a || !b) return false;
+  const listEqual = (x, y) => (x || []).join('') === (y || []).join('');
+  return USAGE_FIELDS.every((f) => (a[f] ?? null) === (b[f] ?? null))
+    && listEqual(a.modelos, b.modelos) && listEqual(a.tools, b.tools);
+}
+
 function entryFromSummary(summary, transcriptId) {
   return {
     transcript_id: transcriptId,
@@ -931,10 +944,11 @@ export function collectSessionUsage({ sessionContent, transcriptPath }) {
   const transcriptId = transcriptIdFromPath(transcriptPath);
   const previous = existingEntries.find((entry) => entry.transcript_id === transcriptId);
   const current = entryFromSummary(summary, transcriptId);
-  if (previous) {
-    const comparable = (entry) => JSON.stringify({ ...entry, atualizado_em: undefined });
-    if (comparable(previous) === comparable(current)) current.atualizado_em = previous.atualizado_em;
-  }
+  // Preserve the old timestamp when the usage data is unchanged, so an unchanged session note
+  // stays byte-identical (no needless rewrite on every Stop). Compared semantically, NOT via
+  // JSON.stringify: the parsed-from-note entry and the freshly-built one have different key
+  // orders, which made the old stringify compare always mismatch — preservation never fired.
+  if (previous && sameUsageData(previous, current)) current.atualizado_em = previous.atualizado_em;
   let entries = existingEntries.filter((e) => e.transcript_id !== transcriptId);
 
   if (!existingEntries.length) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.42.0",
+  "version": "0.45.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.39.0"
+    "wendkeep": "^0.44.0"
   }
 }

package/src/init.mjs

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