wendkeep 0.58.0 → 0.58.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@ 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.58.1] — 2026-07-26
+
+### Fixed
+
+- **Vaults com `SHARED_MEMORY.md` legado voltam a atualizar sem bloquear o doctor.** `init` e
+  `sync` ainda preservam todos os bytes existentes e podem criar os sidecars v2 ausentes,
+  mas sidecars vazios não ativam a memória v2. `memory status --gate` reporta o estado
+  `legacy` como aviso não bloqueante e `brain-inject` mantém CORE+DIGEST durante a janela de
+  compatibilidade.
+- **`SessionStop` não migra memória implicitamente.** Enquanto o vault permanecer legado, o
+  Stop não grava outbox, ledger, candidates nem reescreve SHARED. A transição acontece somente
+  com `wendkeep memory migrate --apply`; conteúdo com assinatura/evidência v2 corrompida continua
+  visível e bloqueante, sem fallback silencioso.
+
 ## [0.58.0] — 2026-07-26
 
 ### Added

package/hooks/brain-inject.mjs

@@ -12,6 +12,7 @@ import { buildLessonsInjection } from './lessons-core.mjs';
 import { getLocale } from './locale.mjs';
 import { resolveSessionEntry } from './session-identity.mjs';
 import { sanitizeMemoryText, validateSharedMemory } from './memory-schema.mjs';
+import { detectMemoryMode } from './memory-mode.mjs';
 import { validateCore } from '../src/validate-core.mjs';
 
 // The process ROUTER — the enforcement layer. The wk-* skills are passive files; without a
@@ -186,7 +187,7 @@ function budgetNotice(priority, layer, message) {
 
 export function buildInjection(vaultBase, input = {}) {
   const dir = brainDir(vaultBase);
-  const brain = existsSync(join(dir, 'SHARED_MEMORY.md')) ? buildV2Memory(dir) : buildLegacyMemory(dir);
+  const brain = detectMemoryMode(vaultBase).mode === 'v2' ? buildV2Memory(dir) : buildLegacyMemory(dir);
   const router = processRouter(getLocale(vaultBase).id);
   const { identity, entry } = resolveSessionEntry(vaultBase, input);
   const focus = identity.state === 'resolved' && entry?.change_slug

package/hooks/memory-mode.mjs

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { classifySharedMemory } from './memory-schema.mjs';
+
+export const LEGACY_MEMORY_WARNING = 'Vault legado: CORE+DIGEST permanece ativo; execute `wendkeep memory migrate --apply` quando a curadoria estiver pronta.';
+
+function readText(path) {
+  if (!existsSync(path)) return { exists: false, content: '', error: null };
+  try { return { exists: true, content: readFileSync(path, 'utf8'), error: null }; }
+  catch (error) { return { exists: true, content: '', error }; }
+}
+
+function hasOutboxEvidence(path) {
+  if (!existsSync(path)) return false;
+  try { return readdirSync(path, { withFileTypes: true }).some((entry) => entry.isFile()); }
+  catch { return true; }
+}
+
+/** A single, read-only mode decision shared by injection, health and SessionStop. */
+export function detectMemoryMode(vaultBase) {
+  const brain = join(vaultBase, '.brain');
+  const shared = readText(join(brain, 'SHARED_MEMORY.md'));
+  if (shared.error) return { mode: 'v2', reason: 'shared-unreadable' };
+  const classified = classifySharedMemory(shared.content);
+  if (classified.mode === 'v2') return classified;
+
+  const ledger = readText(join(brain, 'MEMORY_EVENTS.jsonl'));
+  if (ledger.error) return { mode: 'v2', reason: 'ledger-unreadable' };
+  const candidates = readText(join(brain, 'MEMORY_CANDIDATES.jsonl'));
+  if (candidates.error) return { mode: 'v2', reason: 'candidates-unreadable' };
+  const ledgerHasEvents = ledger.content.trim().length > 0;
+  const candidatesHaveEntries = candidates.content.trim().length > 0;
+  const outboxHasEvents = hasOutboxEvidence(join(brain, 'memory-outbox'));
+  if (ledgerHasEvents || candidatesHaveEntries || outboxHasEvents) {
+    return { mode: 'v2', reason: 'operational-evidence' };
+  }
+  return classified;
+}

package/hooks/memory-schema.mjs

@@ -293,3 +293,18 @@ export function validateSharedMemory(content, { eventIds } = {}) {
     sections: parsed.sections,
   };
 }
+
+/**
+ * Classify SHARED from its own bytes without accepting malformed v2 as legacy.
+ * Empty v2 sidecar files are intentionally not part of this pure classification;
+ * vault-level operational evidence is handled by memory-mode.mjs.
+ */
+export function classifySharedMemory(content) {
+  const text = String(content ?? '').replace(/\r\n/g, '\n');
+  if (validateSharedMemory(text).ok) return { mode: 'v2', reason: 'valid-v2' };
+  const hasV2Signature = /^(?:schema_version|event_cursor|state_hash)\s*:/m.test(text)
+    || /^# SHARED_MEMORY\s+[—-]\s+proje[cç][aã]o operacional gerada\s*$/mi.test(text);
+  return hasV2Signature
+    ? { mode: 'v2', reason: 'v2-signature' }
+    : { mode: 'legacy', reason: text.trim() ? 'legacy-shared' : 'shared-absent' };
+}

package/hooks/session-stop.mjs

@@ -14,6 +14,7 @@ import { mutateSessionNote } from './session-note-io.mjs';
 import { applyDerivedSections, provenanceSessions } from './derived-sections.mjs';
 import { buildSessionMemoryEvents, collectLifecycleEvidence } from './memory-handoff.mjs';
 import { enqueueMemoryEvent, projectMemoryOutbox } from './memory-store.mjs';
+import { detectMemoryMode } from './memory-mode.mjs';
 import { sanitizeMemoryText } from './memory-schema.mjs';
 import {
   ensureDir,
@@ -799,6 +800,9 @@ function shouldFinalizeSession() {
 }
 
 export function commitSessionMemory(vaultBase, handoff, { projectOptions = {} } = {}) {
+  if (detectMemoryMode(vaultBase).mode === 'legacy') {
+    return { status: 'legacy', eventCount: 0, eventIds: [], checkpoint: null };
+  }
   const events = buildSessionMemoryEvents(handoff);
   const eventIds = events.map((event) => event.event_id);
   try {

package/hooks/vault-health.mjs

@@ -12,6 +12,7 @@ import {
 } from './obsidian-common.mjs';
 import { getLocale } from './locale.mjs';
 import { parseSharedMemory, validateMemoryEvent } from './memory-schema.mjs';
+import { detectMemoryMode, LEGACY_MEMORY_WARNING } from './memory-mode.mjs';
 import { reduceMemoryEvents } from './memory-store.mjs';
 import { validateMemoryBundle } from '../src/validate-memory.mjs';
 
@@ -101,7 +102,9 @@ const MEMORY_REPAIR_COMMAND = 'wendkeep memory repair --vault <vault>';
 
 function readJsonLines(path, label) {
   if (!existsSync(path)) return { items: [], errors: [] };
-  const raw = readFileSync(path, 'utf8').replace(/\r\n/g, '\n');
+  let raw;
+  try { raw = readFileSync(path, 'utf8').replace(/\r\n/g, '\n'); }
+  catch (error) { return { items: [], errors: [`${label} ilegível: ${error?.message || error}`] }; }
   const lines = raw.endsWith('\n') ? raw.split('\n').slice(0, -1) : raw.split('\n');
   const items = [];
   const errors = [];
@@ -140,6 +143,25 @@ function inspectOutbox(vaultBase, projectId) {
  */
 export function checkMemoryBundle(vaultBase) {
   const brain = join(vaultBase, '.brain');
+  const mode = detectMemoryMode(vaultBase);
+  if (mode.mode === 'legacy') {
+    return {
+      ok: true,
+      status: 'legacy',
+      failures: [],
+      warnings: [LEGACY_MEMORY_WARNING],
+      metrics: {
+        schemaVersion: null,
+        revision: null,
+        eventCursor: null,
+        stateHash: null,
+        ledgerEvents: 0,
+        pendingOutbox: 0,
+        candidates: 0,
+        activeConflicts: 0,
+      },
+    };
+  }
   const bundle = validateMemoryBundle(vaultBase);
   const failures = [];
   const warnings = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.58.0",
+  "version": "0.58.1",
   "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/memory.mjs

@@ -1,8 +1,8 @@
 import { createHash } from 'node:crypto';
 import {
-  copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync,
+  copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync,
 } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { sanitizeMemoryText, renderSharedMemory, validateSharedMemory } from '../hooks/memory-schema.mjs';
 import {
   enqueueMemoryEvent, projectMemoryOutbox, repairMemoryLedger,
@@ -75,7 +75,11 @@ export function memoryStatus(vault) {
   return checkMemoryBundle(vault);
 }
 
-export function migrateMemory(vault, { apply = false, validateBundle = validateMemoryBundle } = {}) {
+export function migrateMemory(vault, {
+  apply = false,
+  validateBundle = validateMemoryBundle,
+  publishArtifact = writeFileAtomic,
+} = {}) {
   projectId(vault);
   const sharedPath = brainPath(vault, SHARED);
   const hadShared = existsSync(sharedPath);
@@ -95,16 +99,37 @@ export function migrateMemory(vault, { apply = false, validateBundle = validateM
   const sharedValidation = validateSharedMemory(emptyShared, { eventIds: new Set() });
   if (!sharedValidation.ok) throw new Error(`Migração inválida: ${sharedValidation.errors.join(' ')}`);
   if (backupPath && !existsSync(backupPath)) copyFileSync(sharedPath, backupPath);
+
+  // Build and validate a complete candidate vault away from the live paths. This makes
+  // the validation callback incapable of observing a half-published live bundle.
+  const stagingVault = mkdtempSync(join(dirname(vault), '.wendkeep-memory-stage-'));
+  const stagingBrain = join(stagingVault, BRAIN);
+  let stagedValidation;
+  try {
+    mkdirSync(stagingBrain, { recursive: true });
+    copyFileSync(brainPath(vault, 'CORE.md'), join(stagingBrain, 'CORE.md'));
+    copyFileSync(brainPath(vault, 'PROJECT.json'), join(stagingBrain, 'PROJECT.json'));
+    writeFileSync(join(stagingBrain, LEDGER), '', 'utf8');
+    writeFileSync(join(stagingBrain, SHARED), emptyShared, 'utf8');
+    writeFileSync(join(stagingBrain, CANDIDATES), candidateText(candidates), 'utf8');
+    stagedValidation = validateBundle(stagingVault);
+    if (!stagedValidation.ok) {
+      throw new Error(`Bundle migrado inválido: ${(stagedValidation.errors || []).join(' ')}`);
+    }
+  } finally {
+    rmSync(stagingVault, { recursive: true, force: true });
+  }
+
   const targets = [LEDGER, SHARED, CANDIDATES].map((name) => brainPath(vault, name));
   const before = new Map(targets.map((path) => [path, {
     existed: existsSync(path),
     content: existsSync(path) ? readFileSync(path, 'utf8') : '',
   }]));
   try {
-    if (!existsSync(brainPath(vault, LEDGER))) writeFileAtomic(brainPath(vault, LEDGER), '');
-    writeFileAtomic(sharedPath, emptyShared);
-    writeFileAtomic(brainPath(vault, CANDIDATES), candidateText(candidates));
-    const validation = validateBundle(vault);
+    if (!existsSync(brainPath(vault, LEDGER))) publishArtifact(brainPath(vault, LEDGER), '');
+    publishArtifact(sharedPath, emptyShared);
+    publishArtifact(brainPath(vault, CANDIDATES), candidateText(candidates));
+    const validation = validateMemoryBundle(vault);
     if (!validation.ok) throw new Error(`Bundle migrado inválido: ${validation.errors.join(' ')}`);
     return { status: 'migrated', alreadyV2: false, candidates: candidates.length, backupPath, validation };
   } catch (error) {