wendkeep 0.67.2 → 0.67.3

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.67.3] — 2026-08-02
+
+### Fixed
+
+- **Conflitos semânticos agora levam a uma curadoria humana executável.** O doctor diferencia
+  candidates em conflito de corrupção estrutural, explica que `memory repair` não escolhe um
+  vencedor e mostra `memory candidates --active --vault <vault>` com o Vault resolvido, seguido
+  pelos modelos explícitos para promover ou rejeitar a decisão.
+- **A inspeção de candidates deixa de exigir leitura direta do sidecar.** O novo comando read-only
+  `memory candidates [--active]` devolve somente `candidate_id`, `reason`, `status`, `memory_key` e
+  `event_ids`, sem valores ou conteúdo, em ordem determinística e sem alterar o bundle de memória.
+
 ## [0.67.2] — 2026-08-02
 
 ### Fixed

package/README.en.md

@@ -369,8 +369,10 @@ backup/audit; divergent mirrors fail closed. A demonstrably superseded
 ambiguity uses `memory reconcile <session> --by-session <successor>
 --reason <reason>` as a dry run and requires `--apply`; the decision is backed up and audited
 without rewriting ledger, CORE, or notes. Run `status --gate` again afterwards. Conflicts require
-explicit, durable curation: `memory promote <id> --event <event-id>` selects one event from the
-candidate, while `memory reject <id>` keeps the current value. The decision is idempotent, and a
+explicit, durable curation: `memory candidates --active --vault <vault>` lists only safe IDs and
+metadata in read-only mode — it does not expose memory values or content. After human review,
+`memory promote <id> --event <event-id>` selects one event from the candidate, while
+`memory reject <id>` keeps the current value. `memory repair` does not choose a winner. The decision is idempotent, and a
 new promotion accepts a later Stop from the same session/activation without recreating a conflict.
 A promotion written by 0.66.1 remains historical: if the next Stop forms a new candidate, update
 to 0.66.3 and run `memory repair`. During replay, a transient candidate is re-evaluated against the

package/README.md

@@ -369,8 +369,10 @@ backup/audit; divergent mirrors fail closed. A demonstrably superseded
 ambiguity uses `memory reconcile <session> --by-session <successor>
 --reason <reason>` as a dry run and requires `--apply`; the decision is backed up and audited
 without rewriting ledger, CORE, or notes. Run `status --gate` again afterwards. Conflicts require
-explicit, durable curation: `memory promote <id> --event <event-id>` selects one event from the
-candidate, while `memory reject <id>` keeps the current value. The decision is idempotent, and a
+explicit, durable curation: `memory candidates --active --vault <vault>` lists only safe IDs and
+metadata in read-only mode — it does not expose memory values or content. After human review,
+`memory promote <id> --event <event-id>` selects one event from the candidate, while
+`memory reject <id>` keeps the current value. `memory repair` does not choose a winner. The decision is idempotent, and a
 new promotion accepts a later Stop from the same session/activation without recreating a conflict.
 A promotion written by 0.66.1 remains historical: if the next Stop forms a new candidate, update
 to 0.66.3 and run `memory repair`. During replay, a transient candidate is re-evaluated against the

package/docs/en/commands/maintenance-and-diagnostics.md

@@ -57,6 +57,7 @@ npx --no-install wendkeep --version
 npx --no-install wendkeep sync-defs --check --vault .MyApp-vault --project .
 npx --no-install wendkeep doctor --vault .MyApp-vault
 npx --no-install wendkeep memory status --gate --vault .MyApp-vault
+npx --no-install wendkeep memory candidates --active --vault .MyApp-vault
 npx --no-install wendkeep cost rebuild --session <id> --json --vault .MyApp-vault
 npx --no-install wendkeep cost rebuild --session <id> --json --vault .MyApp-vault --apply
 ```
@@ -74,11 +75,17 @@ dry-run path before any write.
 
 - `no vault`: run from the bound root or pass `--vault`.
 - `defs stale`: confirm the version and run `sync-defs --reseed`.
-- Legacy vault: this is a non-blocking warning; plan `memory migrate --apply` separately.
+- Legacy vault: this is a non-blocking warning; doctor shows
+  `npx --no-install wendkeep memory migrate --apply --vault <vault>` with the resolved Vault, but
+  migration remains opt-in and must be planned separately.
 - `degraded` plus an intact outbox: warning; preserve the outbox and allow idempotent replay.
 - `ambiguous`, lost publication, or a mismatched checkpoint: blocking; preserve registry, ledger,
   outbox, and SHARED so `last_memory_attempt` can be correlated before repair.
 - Corrupt bundle: preserve evidence and run `memory status --gate` before `memory repair`.
+- An active semantic conflict requires a human decision: `memory repair` does not choose a winner.
+  List safe IDs with `memory candidates --active --vault <vault>`, review the evidence, and then use
+  `memory promote <candidate-id> --event <event-id> --vault <vault>` to select an event or
+  `memory reject <candidate-id> --vault <vault>` to keep the current operational value.
 - `legacy`/`degraded`/`stale`/`manifest-unproven` observability: run
   `npx --no-install wendkeep cost rebuild --session <id> --json --vault <vault>`, review diagnostics,
   and only then authorize the second variant with `--apply`.

package/docs/en/commands/memory.md

@@ -24,6 +24,7 @@ Pass the vault explicitly in automation. Preserve backups and evidence before re
 
 ```bash
 npx wendkeep memory status [--gate] --vault <vault>
+npx wendkeep memory candidates [--active] --vault <vault>
 npx wendkeep memory repair --vault <vault>
 npx wendkeep memory recover-attempt <session> [--apply] --vault <vault>
 npx wendkeep memory reconcile <ambiguous-session> --by-session <successor-session> --reason <reason> [--apply] --vault <vault>
@@ -36,6 +37,13 @@ npx wendkeep validate-memory --vault <v2-vault>
 ## Options and exit codes
 
 - `memory status` is read-only; `--gate` exits `1` only for blocking state.
+- `memory candidates` is read-only and prints deterministic JSON containing only `candidate_id`,
+  `reason`, `status`, `memory_key`, and `event_ids`; it does not expose memory values or content and
+  does not create a lock or mutate the bundle. `--active` omits terminal candidates (`resolved`,
+  `rejected`, and `superseded`). A missing status is normalized to `active`.
+- For `memory candidates`, exit `0` means a valid inventory (including empty or conflicted), exit
+  `1` means an invalid sidecar/unsafe topology, and exit `2` means a missing `--vault`, unknown or
+  duplicate option, extra argument, or an invalid value passed to `--active`.
 - `Stop` writes events to the outbox before acknowledging `last_memory_attempt: enqueued`, then the
   projector runs outside the registry lock. Retrying the same attempt reuses its frozen event IDs
   and can project them at most once.
@@ -105,6 +113,7 @@ npx wendkeep validate-memory --vault <v2-vault>
 
 ```bash
 npx wendkeep memory status --gate --vault .MyApp-vault
+npx wendkeep memory candidates --active --vault .MyApp-vault
 npx wendkeep memory recover-attempt session-123 --vault .MyApp-vault
 npx wendkeep memory recover-attempt session-123 --apply --vault .MyApp-vault
 npx wendkeep memory reconcile old --by-session current --reason "delivery continued" --vault .MyApp-vault
@@ -121,6 +130,9 @@ state of the last attempt. CORE stays hand-curated and canonical; SHARED stays a
 operational projection. After successful projection, an attempt checkpoint may be a valid prefix
 of a global projection that has already advanced with concurrent events.
 
+`memory candidates` returns `status: "ok"` and the sanitized candidate list in stable order; with
+`--active`, the list contains only decisions still open for human curation.
+
 ## Common errors and diagnosis
 
 - `legacy`: follow the migration guide; this is not corruption.

package/docs/pt-BR/commands/maintenance-and-diagnostics.md

@@ -57,6 +57,7 @@ npx --no-install wendkeep --version
 npx --no-install wendkeep sync-defs --check --vault .MeuApp-vault --project .
 npx --no-install wendkeep doctor --vault .MeuApp-vault
 npx --no-install wendkeep memory status --gate --vault .MeuApp-vault
+npx --no-install wendkeep memory candidates --active --vault .MeuApp-vault
 npx --no-install wendkeep cost rebuild --session <id> --json --vault .MeuApp-vault
 npx --no-install wendkeep cost rebuild --session <id> --json --vault .MeuApp-vault --apply
 ```
@@ -74,11 +75,17 @@ ou sem manifest comprovado e oferece um caminho dry-run antes de qualquer escrit
 
 - `no vault`: execute da raiz vinculada ou passe `--vault`.
 - `defs stale`: confirme a versão e rode `sync-defs --reseed`.
-- Vault legado: é warning não bloqueante; planeje `memory migrate --apply` separadamente.
+- Vault legado: é warning não bloqueante; o doctor mostra
+  `npx --no-install wendkeep memory migrate --apply --vault <cofre>` com o Vault resolvido, mas a
+  migração continua sendo opt-in e deve ser planejada separadamente.
 - `degraded` + outbox íntegra: warning; preserve a outbox e permita replay idempotente.
 - `ambiguous`, publicação perdida ou checkpoint divergente: bloqueante; preserve registry, ledger,
   outbox e SHARED para correlacionar `last_memory_attempt` antes de reparar.
 - Bundle corrompido: preserve a evidência e use `memory status --gate` antes de `memory repair`.
+- Conflito semântico ativo exige decisão humana: `memory repair` não escolhe vencedor. Liste os IDs
+  seguros com `memory candidates --active --vault <cofre>`, revise a evidência e então use
+  `memory promote <candidate-id> --event <event-id> --vault <cofre>` para selecionar um evento ou
+  `memory reject <candidate-id> --vault <cofre>` para manter o valor operacional atual.
 - Observabilidade `legacy`/`degraded`/`stale`/`manifest-unproven`: rode
   `npx --no-install wendkeep cost rebuild --session <id> --json --vault <cofre>`, revise diagnostics
   e só então autorize a segunda variante com `--apply`.

package/docs/pt-BR/commands/memory.md

@@ -24,6 +24,7 @@ Informe o vault explicitamente em automações. Preserve backups e evidências a
 
 ```bash
 npx wendkeep memory status [--gate] --vault <cofre>
+npx wendkeep memory candidates [--active] --vault <cofre>
 npx wendkeep memory repair --vault <cofre>
 npx wendkeep memory recover-attempt <sessão> [--apply] --vault <cofre>
 npx wendkeep memory reconcile <sessão-ambígua> --by-session <sessão-sucessora> --reason <motivo> [--apply] --vault <cofre>
@@ -36,6 +37,13 @@ npx wendkeep validate-memory --vault <cofre-v2>
 ## Opções e códigos de saída
 
 - `memory status` é read-only; `--gate` retorna exit `1` apenas para estado bloqueante.
+- `memory candidates` é read-only e imprime JSON determinístico com somente `candidate_id`,
+  `reason`, `status`, `memory_key` e `event_ids`; não expõe valores nem conteúdo da memória e não
+  cria lock nem altera o bundle. `--active` omite candidates terminais (`resolved`, `rejected` e
+  `superseded`). Status ausente é normalizado para `active`.
+- Em `memory candidates`, exit `0` indica inventário válido (inclusive vazio ou com conflitos),
+  exit `1` indica sidecar inválido/topologia insegura e exit `2` indica `--vault` ausente, opção
+  desconhecida/duplicada, argumento extra ou valor indevido em `--active`.
 - O `Stop` grava os eventos na outbox antes de reconhecer `last_memory_attempt: enqueued`; depois o
   projector roda fora do lock do registry. Retry do mesmo attempt reutiliza os event IDs congelados
   e pode projetá-los no máximo uma vez.
@@ -103,6 +111,7 @@ npx wendkeep validate-memory --vault <cofre-v2>
 
 ```bash
 npx wendkeep memory status --gate --vault .MeuApp-vault
+npx wendkeep memory candidates --active --vault .MeuApp-vault
 npx wendkeep memory recover-attempt sessao-123 --vault .MeuApp-vault
 npx wendkeep memory recover-attempt sessao-123 --apply --vault .MeuApp-vault
 npx wendkeep memory reconcile antiga --by-session atual --reason "entrega continuada" --vault .MeuApp-vault
@@ -119,6 +128,9 @@ causal do último attempt. CORE permanece canônico e curado à mão; SHARED per
 operacional verificável. Depois de uma projeção bem-sucedida, o checkpoint do attempt pode ser um
 prefixo válido de uma projeção global que já avançou com eventos concorrentes.
 
+`memory candidates` retorna `status: "ok"` e a lista sanitizada de candidates em ordem estável;
+com `--active`, a lista contém somente decisões ainda abertas para curadoria humana.
+
 ## Erros comuns e diagnóstico
 
 - `legacy`: siga o guia de migração; não é corrupção.

package/hooks/vault-health.mjs

@@ -106,6 +106,18 @@ const memoryStatusCommand = (vaultBase) => (
 const memoryRepairCommand = (vaultBase) => (
   `${WENDKEEP_COMMAND} memory repair --vault ${quoteCommandArgument(vaultBase)}`
 );
+const memoryMigrateCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory migrate --apply --vault ${quoteCommandArgument(vaultBase)}`
+);
+const memoryCandidatesCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory candidates --active --vault ${quoteCommandArgument(vaultBase)}`
+);
+const memoryPromoteCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory promote <candidate-id> --event <event-id> --vault ${quoteCommandArgument(vaultBase)}`
+);
+const memoryRejectCommand = (vaultBase) => (
+  `${WENDKEEP_COMMAND} memory reject <candidate-id> --vault ${quoteCommandArgument(vaultBase)}`
+);
 
 function readJsonLines(vaultBase, path, label) {
   let checked;
@@ -397,7 +409,7 @@ export function checkMemoryBundle(vaultBase, { registry } = {}) {
       ok: true,
       status: 'legacy',
       failures: [],
-      warnings: [LEGACY_MEMORY_WARNING],
+      warnings: [`${LEGACY_MEMORY_WARNING} Comando com Vault resolvido: ${memoryMigrateCommand(vaultBase)}.`],
       metrics: memoryMetrics(),
     };
   }
@@ -466,7 +478,12 @@ export function checkMemoryBundle(vaultBase, { registry } = {}) {
   const activeConflicts = unresolved.filter((item) => item?.reason === 'conflict');
   const ordinaryCandidates = unresolved.filter((item) => item?.reason !== 'conflict');
   if (activeConflicts.length) {
-    failures.push(`${activeConflicts.length} conflito ativo em chave operacional (${activeConflicts.map((item) => item.memory_key || item.candidate_id).join(', ')}). Inspecione com: ${memoryStatusCommand(vaultBase)}.`);
+    const keys = [...new Set(activeConflicts.map((item) => item.memory_key || item.candidate_id))]
+      .sort((left, right) => String(left).localeCompare(String(right)));
+    const label = activeConflicts.length === 1
+      ? '1 conflito ativo'
+      : `${activeConflicts.length} conflitos ativos`;
+    failures.push(`${label} em chave operacional (${keys.join(', ')}). Conflito semântico exige curadoria humana; memory repair não escolhe vencedor. Liste IDs seguros com: ${memoryCandidatesCommand(vaultBase)}. Depois da revisão, use ${memoryPromoteCommand(vaultBase)} ou ${memoryRejectCommand(vaultBase)}.`);
   }
   if (outbox.count) warnings.push(`${outbox.count} evento(s) pendente(s) na outbox; execute o projector quando seguro.`);
   if (ordinaryCandidates.length) warnings.push(`${ordinaryCandidates.length} candidate(s) aguardando curadoria humana.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.67.2",
+  "version": "0.67.3",
   "description": "Vault-first persistent memory for AI coding agents, with an optional profile-aware governance runtime: OFF, FLOW, GUIDE, GOVERN, or ASSURE. Local-first and agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "workspaces": [
@@ -70,6 +70,6 @@
   },
   "devDependencies": {
     "acorn": "^8.18.0",
-    "wendkeep": "^0.67.1"
+    "wendkeep": "^0.67.2"
   }
 }

package/packages/cli/src/index.mjs

@@ -99,7 +99,7 @@ Usage:
                            in session notes from the linked derived notes — the body used to lag
                            behind the closing block. Dry-run by default · --apply · --json.
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
-  wendkeep memory <sub>          Shared memory v2: status | migrate [--apply] | repair |
+  wendkeep memory <sub>          Shared memory v2: status | candidates [--active] | migrate [--apply] | repair |
                            recover-attempt <session> [--apply] |
                            reconcile <session> --by-session <session> --reason <text> [--apply] |
                            promote <candidate> [--event <event-id>] | reject <candidate>. --vault P.

package/src/memory.mjs

@@ -237,6 +237,48 @@ function readCandidates(vault) {
     .split('\n').filter(Boolean).map((line) => JSON.parse(line));
 }
 
+const TERMINAL_CANDIDATE_STATUSES = new Set(['resolved', 'rejected', 'superseded']);
+
+function lexicalCompare(left, right) {
+  if (left < right) return -1;
+  if (left > right) return 1;
+  return 0;
+}
+
+function sanitizedCandidate(candidate, index) {
+  if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+    throw new Error(`MEMORY_CANDIDATES.jsonl: candidate ${index + 1} inválido.`);
+  }
+  const required = ['candidate_id', 'reason', 'memory_key'];
+  const missing = required.filter((field) => typeof candidate[field] !== 'string' || !candidate[field]);
+  if (missing.length) {
+    throw new Error(`MEMORY_CANDIDATES.jsonl: candidate ${index + 1} sem ${missing.join(', ')}.`);
+  }
+  if (candidate.status !== undefined && (typeof candidate.status !== 'string' || !candidate.status)) {
+    throw new Error(`MEMORY_CANDIDATES.jsonl: candidate ${index + 1} possui status inválido.`);
+  }
+  const eventIds = candidate.event_ids ?? [];
+  if (!Array.isArray(eventIds) || eventIds.some((eventId) => typeof eventId !== 'string' || !eventId)) {
+    throw new Error(`MEMORY_CANDIDATES.jsonl: candidate ${index + 1} possui event_ids inválidos.`);
+  }
+  return {
+    candidate_id: candidate.candidate_id,
+    reason: candidate.reason,
+    status: candidate.status || 'active',
+    memory_key: candidate.memory_key,
+    event_ids: [...eventIds].sort(lexicalCompare),
+  };
+}
+
+export function listMemoryCandidates(vault, { activeOnly = false } = {}) {
+  const candidates = readCandidates(vault)
+    .map(sanitizedCandidate)
+    .filter((candidate) => !activeOnly || !TERMINAL_CANDIDATE_STATUSES.has(candidate.status))
+    .sort((left, right) => lexicalCompare(left.memory_key, right.memory_key)
+      || lexicalCompare(left.candidate_id, right.candidate_id));
+  return { status: 'ok', candidates };
+}
+
 function priorCandidateDecision(vault, candidateId) {
   return readMemoryLedger(vault).events.find(
     (event) => event.candidate_decision?.candidate_id === candidateId,
@@ -1897,10 +1939,49 @@ function parseRecoverAttemptArgs(argv) {
   };
 }
 
+function parseCandidatesArgs(argv) {
+  const seen = new Set();
+  let activeOnly = false;
+  let vault = '';
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      throw memoryUsageError(`memory candidates recebeu argumento posicional extra: ${token}.`);
+    }
+
+    const equalAt = token.indexOf('=');
+    const name = equalAt >= 0 ? token.slice(0, equalAt) : token;
+    if (name !== '--active' && name !== '--vault') {
+      throw memoryUsageError(`memory candidates recebeu opção desconhecida: ${name}.`);
+    }
+    if (seen.has(name)) {
+      throw memoryUsageError(`memory candidates recebeu opção duplicada: ${name}.`);
+    }
+    seen.add(name);
+
+    if (name === '--active') {
+      if (equalAt >= 0) throw memoryUsageError('--active não aceita valor.');
+      activeOnly = true;
+      continue;
+    }
+
+    const value = equalAt >= 0 ? token.slice(equalAt + 1) : argv[index + 1];
+    if (!value || !value.trim() || value.startsWith('--')) {
+      throw memoryUsageError('--vault requer valor não vazio que não comece com --.');
+    }
+    vault = value;
+    if (equalAt < 0) index += 1;
+  }
+
+  return { activeOnly, vault };
+}
+
 export function runMemory(argv) {
   const [sub, positional] = argv;
   let reconcileArgs = null;
   let recoverAttemptArgs = null;
+  let candidatesArgs = null;
   if (sub === 'reconcile') {
     try {
       reconcileArgs = parseReconcileArgs(argv);
@@ -1919,14 +2000,26 @@ export function runMemory(argv) {
       return;
     }
   }
+  if (sub === 'candidates') {
+    try {
+      candidatesArgs = parseCandidatesArgs(argv);
+    } catch (error) {
+      process.stderr.write(`wendkeep memory: ${error.message}\n`);
+      process.exitCode = error.code === 'WENDKEEP_MEMORY_USAGE' ? 2 : 1;
+      return;
+    }
+  }
   const vault = (
-    recoverAttemptArgs?.vault || reconcileArgs?.vault || option(argv, '--vault')
+    recoverAttemptArgs?.vault || reconcileArgs?.vault || candidatesArgs?.vault || option(argv, '--vault')
   ) || process.env.OBSIDIAN_VAULT_PATH;
   if (!vault) { process.stderr.write('wendkeep memory: passe --vault <path>.\n'); process.exitCode = 2; return; }
   if (!existsSync(vault)) { process.stderr.write(`wendkeep memory: not found: ${vault}\n`); process.exitCode = 2; return; }
   try {
     let result;
     if (sub === 'status') result = memoryStatus(vault);
+    else if (sub === 'candidates') {
+      result = listMemoryCandidates(vault, { activeOnly: candidatesArgs.activeOnly });
+    }
     else if (sub === 'migrate') result = migrateMemory(vault, { apply: argv.includes('--apply') });
     else if (sub === 'repair') result = repairMemory(vault);
     else if (sub === 'reconcile') {
@@ -1950,7 +2043,7 @@ export function runMemory(argv) {
         action: sub, candidateId: positional, ...(eventId ? { eventId } : {}),
       });
     }
-    else { process.stderr.write('wendkeep memory: use status | migrate [--apply] | repair | recover-attempt <session> [--apply] | reconcile <session> --by-session <session> --reason <text> [--apply] | promote <candidate> [--event <event-id>] | reject <candidate>.\n'); process.exitCode = 2; return; }
+    else { process.stderr.write('wendkeep memory: use status | candidates [--active] | migrate [--apply] | repair | recover-attempt <session> [--apply] | reconcile <session> --by-session <session> --reason <text> [--apply] | promote <candidate> [--event <event-id>] | reject <candidate>.\n'); process.exitCode = 2; return; }
     process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
     if (sub === 'status' && argv.includes('--gate')) process.exitCode = result.status === 'blocked' ? 1 : 0;
     else if (sub === 'reconcile' && reconcileArgs.apply) process.exitCode = result.health?.status === 'blocked' ? 1 : 0;